# agent-word-diagram

**Repository Path**: PC888/agent-word-diagram

## Basic Information

- **Project Name**: agent-word-diagram
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# Agent Word Diagram 🎨

**输入 SQL / JSON / 文本 DSL，一键生成符合学术规范的图表**

*Text-to-diagram engine that turns SQL, JSON and simple DSL into standards-compliant diagrams.*

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.128-009688.svg)](https://fastapi.tiangolo.com)
[![Tests](https://img.shields.io/badge/tests-149%20passed-brightgreen.svg)](tests/)

**ER 图 · UML 类图 · 流程图 · 时序图 · 架构图 · 用例图 · 功能模块树**

</div>

---

## 🖼️ 效果展示（全部由本引擎实际生成）

| 流程图（判定分支 + 循环回边） | UML 类图（继承 / 组合 / 聚合） |
|:---:|:---:|
| ![流程图](docs/images/flowchart.png) | ![UML 类图](docs/images/uml.png) |
| *Yes/No 按目标方位出线，回边自动绕行* | *空心三角=继承，实心菱形=组合，空心菱形=聚合* |

| ER 图（Chen 记法） | 时序图（学术黑白 PNG） |
|:---:|:---:|
| ![ER 图](docs/images/er.png) | ![时序图](docs/images/sequence.png) |
| *主键下划线，外键关系菱形 + 1:N 基数* | *实线=同步调用，虚线=返回* |

| 架构图（拓扑分层） | 用例图（系统边界） | 功能模块树 |
|:---:|:---:|:---:|
| ![架构图](docs/images/architecture.png) | ![用例图](docs/images/usecase.png) | ![功能模块树](docs/images/tree.png) |
| *按调用关系自动分四层* | *«include» 虚线箭头 + 边界框* | *缩进文本 → 层级树* |

> 🎁 **在线体验**：克隆后双击 `diagram_test.html`，本地即可交互式生成以上全部图型（无需外网）。

---

## ✨ 特性

- **7 种图表，开箱即用** —— 覆盖论文、系统设计、需求分析最常见的图型
- **严格符合规范** —— UML 2.5（关系装饰、include 方向、系统边界）、Chen 记法 ER（PK 下划线、基数标注）、ISO 5807 流程图符号
- **双格式输出** —— 所有图型输出 **Draw.io 兼容 XML**（可继续在线/桌面编辑）；时序图额外输出 **PNG**
- **学术黑白模式** —— `academic_bw` 为论文打印优化（默认），`default` 为彩色
- **智能布局** —— 流程图分层 + 回边处理、架构图拓扑分层、决策分支防交叉、时序图间距自适应
- **质量有保障** —— 149 个测试：单元 + 几何审计 + 规范审计 + 随机模糊测试，全部校验**最终交付物**（XML）而非中间结构
- **零外部依赖服务** —— 解析、布局、渲染全本地完成，不需要 LLM、不需要联网

---

## 🚀 快速开始

### 1. 安装

```bash
git clone https://github.com/<你的用户名>/agent-word-diagram.git
cd agent-word-diagram

python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# Linux / macOS
.venv/bin/pip install -r requirements.txt
```

> 需要 Python 3.10+。若安装较慢可先执行 `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`

### 2. 启动服务

```bash
python run.py
# 或等价命令
python -m uvicorn api.main:app --host 0.0.0.0 --port 8000
```

| 入口 | 地址 |
|------|------|
| Swagger 交互文档 | http://localhost:8000/docs |
| 健康检查 | http://localhost:8000/health |
| 可视化测试页 | 双击项目根目录 `diagram_test.html` |

### 3. 第一个请求

```bash
curl -X POST http://localhost:8000/api/diagram/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(50), dept_id INT, FOREIGN KEY (dept_id) REFERENCES dept(id));",
    "diagram_type": "er",
    "style_mode": "academic_bw"
  }'
```

返回：

```json
{
    "xml_data": "7VlNb9MwEP9rpH/g...(Draw.io 压缩 XML, Base64)",
    "image_data": null,
    "status": "success",
    "diagram_type": "er",
    "style_mode": "academic_bw",
    "node_count": 7,
    "edge_count": 6
}
```

**如何查看生成的图**（三选一）：

1. 打开 [diagram_test.html](diagram_test.html) 粘贴输入，页面内直接渲染
2. 把 `xml_data` 拼到 `https://app.diagrams.net/#R{xml_data}` 在 Draw.io 在线打开
3. 测试页的"下载 .drawio 文件"按钮保存后，用 [Draw.io 桌面版](https://github.com/jgraph/drawio-desktop) 编辑

---

## 📖 使用规范

### 接口定义

**唯一绘图端点**（另有一个 Java 集成变体 `/generate-java`，见 [docs/API_DIAGRAM_JAVA.md](docs/API_DIAGRAM_JAVA.md)）：

```
POST /api/diagram/generate
Content-Type: application/json
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| `content` | string | ✅ | 图表内容（格式见下表） |
| `diagram_type` | string | ✅ | `er` / `uml` / `flowchart` / `sequence` / `architecture` / `usecase` / `tree` |
| `style_mode` | string | — | `academic_bw`（默认，学术黑白）/ `default`（彩色） |

**响应字段**：

| 字段 | 说明 |
|------|------|
| `xml_data` | Draw.io 兼容压缩 XML（Base64），所有图型都返回 |
| `image_data` | PNG 图片（Base64），**仅时序图**返回 |
| `node_count` / `edge_count` | 节点数 / 连线数 |
| `status` | `success`；失败时返回 400/500 + `detail` 错误信息 |

### 七种图型的输入格式

#### ① ER 图（`er`）—— SQL DDL

自动识别 `PRIMARY KEY`（下划线标注）与 `FOREIGN KEY`（生成关系菱形 + 1:N 基数）。

```sql
CREATE TABLE student (
    id INT PRIMARY KEY,
    name VARCHAR(50),
    class_id INT,
    FOREIGN KEY (class_id) REFERENCES class(id)
);
CREATE TABLE class (id INT PRIMARY KEY, title VARCHAR(50));
```

#### ② UML 类图（`uml`）—— JSON

```json
{
    "classes": [
        {"name": "Animal", "attributes": ["# name: String"], "methods": ["+ eat()"]},
        {"name": "Bird", "attributes": ["+ canFly: boolean"], "methods": ["+ fly()"]}
    ],
    "relationships": [
        {"from": "Bird", "to": "Animal", "type": "inheritance"}
    ]
}
```

`relationships.type` 与渲染装饰的对应（UML 2.5）：

| type | 线型 |
|------|------|
| `inheritance` | 空心三角箭头，指向父类 |
| `composition` | 实心菱形在整体端（`from` 端） |
| `aggregation` | 空心菱形在整体端 |
| `dependency` | 虚线 + 开口箭头 |
| `association` | 普通实线 |

#### ③ 流程图（`flowchart`）—— JSON

```json
{
    "nodes": [
        {"id": "s", "label": "开始", "type": "start"},
        {"id": "d", "label": "密码正确?", "type": "decision"},
        {"id": "m", "label": "进入系统", "type": "process"},
        {"id": "i", "label": "输入密码", "type": "io"},
        {"id": "e", "label": "结束", "type": "end"}
    ],
    "edges": [
        {"from": "s", "to": "i"},
        {"from": "i", "to": "d"},
        {"from": "d", "to": "m", "label": "Yes"},
        {"from": "d", "to": "e", "label": "No"}
    ]
}
```

`nodes.type`：`start` / `end`（椭圆）、`process`（矩形）、`decision`（菱形）、`io`（平行四边形）。未填 type 时按标签自动识别（含"开始/结束/?"等关键词）。

#### ④ 时序图（`sequence`）—— 文本 DSL

```
用户 -> 登录页: 输入账号密码
登录页 -> 认证服务: 提交登录请求
认证服务 --> 登录页: 认证通过+token
```

`->` 实线同步调用；`-->` 虚线返回。参与者按首次出现顺序排列。

#### ⑤ 架构图（`architecture`）—— JSON（两种等价格式）

```json
{
    "nodes": [
        {"id": "gw", "label": "API 网关", "type": "container"},
        {"id": "user", "label": "用户服务", "type": "container"},
        {"id": "mysql", "label": "MySQL 数据库", "type": "database"},
        {"id": "mq", "label": "消息队列", "type": "queue"}
    ],
    "edges": [
        {"from": "gw", "to": "user"},
        {"from": "user", "to": "mysql"},
        {"from": "user", "to": "mq"}
    ]
}
```

- 也可用 `containers` / `relations` 作为键名（与 `nodes` / `edges` 完全等价）
- `type`：`container`（矩形）/ `database`（圆柱体）/ `queue`（文档形）
- 布局按调用关系自动分层（客户端 → 网关 → 服务 → 存储）

#### ⑥ 用例图（`usecase`）—— JSON 层级

```json
{
    "actor": "买家",
    "hierarchy": [
        {"main": "搜索商品", "subs": ["关键词搜索", "分类浏览"]},
        {"main": "下单购买", "subs": ["加入购物车", "在线支付"]}
    ]
}
```

自动生成：系统边界框、主/子用例尺寸区分、主→子 «include» 虚线箭头。

#### ⑦ 功能模块树（`tree`）—— 缩进文本

```
教务管理系统
- 学生管理
  - 学籍登记
  - 信息修改
- 课程管理
  - 排课调度
```

也支持 JSON 树：`{"root": "系统", "children": [{"label": "模块", "children": []}]}`

### 多语言调用示例

**Python：**

```python
import json, urllib.request

def generate(content, dtype, style="academic_bw"):
    body = json.dumps({"content": content, "diagram_type": dtype,
                       "style_mode": style}).encode()
    req = urllib.request.Request(
        "http://localhost:8000/api/diagram/generate",
        data=body, headers={"Content-Type": "application/json"})
    return json.loads(urllib.request.urlopen(req).read())

result = generate("用户 -> 服务器: 请求\n服务器 --> 用户: 响应", "sequence")
with open("sequence.png", "wb") as f:
    f.write(__import__("base64").b64decode(result["image_data"]))
```

**Java（Spring / RestTemplate）** 完整示例见 [docs/API_DIAGRAM_JAVA.md](docs/API_DIAGRAM_JAVA.md)。

> 📋 **13 个实测可用的完整测试用例**见 [测试示例.md](测试示例.md)，可直接复制粘贴。

### 错误处理

| HTTP 状态 | 场景 | 响应 |
|-----------|------|------|
| 400 | `content` 无法解析（JSON 语法错误 / 空图 / 不支持的类型） | `{"detail": "Parsing failed: ..."}` |
| 422 | 请求体缺少必填字段 | FastAPI 标准校验错误 |
| 500 | 引擎内部异常（含堆栈信息，见服务日志 `logs/error.log`） | `{"detail": "Internal error: ..."}` |

---

## 🧱 架构与项目结构

```
输入(SQL/JSON/DSL) → ParserEngine 解析 → DiagramGraph 图模型
    → LayoutEngine 布局(分层/拓扑/树) → DrawIOEncoder 编码 → Draw.io XML
                                              → MatplotlibRenderer → PNG(时序图)
```

```
├── api/                              # FastAPI 应用层
│   ├── main.py                       # 入口（日志 / CORS / 生命周期）
│   ├── routes/diagram.py             # 绘图接口
│   └── models/schemas.py             # 请求/响应模型
├── tools/diagram_engine/             # 🔧 核心引擎
│   ├── parsers.py                    # SQL / JSON / DSL → 图模型
│   ├── layout.py                     # 布局（分层/拓扑/树/网格）
│   ├── flow_layout.py                # 流程图专用布局（回边/分支方位）
│   ├── renderer.py                   # Draw.io XML 编码器（样式/端口/标签）
│   ├── matplotlib_renderer.py        # 时序图 PNG 渲染（黑白/彩色）
│   ├── audit.py                      # 几何审计（重叠/穿越/标签遮挡）
│   ├── audit_semantics.py            # 规范审计（ISO 5807 / UML 2.5 / Chen）
│   └── domain.py                     # 领域模型
├── usecase_diagram/  cloud_diagram/  # 独立画图模块（示例/扩展）
├── tests/                            # 149 个测试 + 质量回归用例 + 模糊测试
├── diagram_test.html                 # 可视化测试页（双击即用）
├── make_showcase.py                  # README 展示图一键重生成
└── run.py                            # 启动入口
```

## ✅ 测试与质量

```bash
python -m pytest tests/ -v
```

质量体系分四层，全部针对**最终交付物**（draw.io XML）：

1. **单元测试** —— 解析器 / 布局 / 编码器行为
2. **几何审计** —— 节点重叠、连线穿越节点、标签遮挡、端点吸附
3. **规范审计** —— 按图型校验行业规范（UML 2.5 装饰方向、ISO 5807 符号、Chen 记法结构）
4. **模糊测试** —— 随机生成图结构，统计审计错误类型防回归

一键重新生成 README 展示图：`python make_showcase.py`

## 🤝 贡献

欢迎 Issue 和 PR！流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。提交前请跑通 `pytest`。

## 📄 许可证

[MIT](LICENSE)