罗斯蒙德可视化图形生成

SKILL.md 节选

# 可视化图形生成

把「一段业务描述」变成**一套可编辑、多格式、风格统一的图**，而不是一张死图。

## 四条硬规则

1. **统一图模型是唯一真相源** —— 所有产物（Mermaid / drawio / Excalidraw / SVG）都由同一份 `graph.json` 生成。**禁止**为不同格式各写一份图，否则改一处、其余全部失真。
2. **可编辑性是交付底线** —— 只给 PNG 而不给可编辑源 = 交付不合格。结构化文本与可编辑文件至少各出一种。
3. **节点必须有语义类型** —— 每个节点标 `type`（service / db / queue / external / actor / decision / entity / state…），由样式系统统一决定配色与形状。**禁止**随手指定颜色，这是"风格不统一"的根因。
4. **图要配说明** —— 图只是半成品。必须输出「图的含义」+「关键节点解释」+「关键连线解释」，否则别人读不懂。

## 三步决策：先分诊，再建模，后产出

### Step 1 · 分诊图类型

从需求描述判断该画什么图（不确定就问，不要瞎猜）：

| 图类型 | 适用场景 | 信号词 |
|--------|----------|--------|
| `architecture` 架构图 | 系统由哪些组件构成、如何协作 | 系统架构、部署、组件、服务划分、技术选型 |
| `flowchart` 流程图 | 业务流程、判断分支、审批流 | 流程、审批、如果…则、环节、步骤 |
| `er` ER 图 | 数据实体与关系 | 表结构、实体、字段、一对多、关联 |
| `sequence` 时序图 | 跨系统/对象的调用时序 | 调用链、请求顺序、接口时序、交互过程 |
| `state` 状态图 | 单个对象的状态流转 | 状态、流转、生命周期、状态机 |
| `c4` C4 容器图 | 分层表达系统上下文与容器 | 系统上下文、容器图、边界、外部依赖 |

复杂需求可拆多张图（如先给架构图、再给核心链路时序图），**每张图单独建一份 graph.json**。

### Step 2 · 建模：填 graph.json

加载 `references/graph-model.md` 取 schema，逐字段填。要点：

- **节点**：`id` 全局唯一、`label` 简洁（≤ 8 字优先）、`type` 必须从类型表选、`desc` 一句话解释
- **边**：`source`/`target` 必须指向已存在的节点 id；`label` 写"传什么/为什么"（如"HTTPS 下单请求"），不是只写"调用"
- **分组**：用 `groups` 表达系统边界（接入层 / 业务层 / 数据层），这是"正确反映系统边界"的落地方式
- **分层**：`layer` 决定纵向排布；不给则由布局引擎自动推断

### Step 3 · 产出：一次建模，四格式输出

按用户需要选择（默认出结构化文本 + 可编辑文件 + SVG）：

```bash
PY="<venv>/Scripts/python.exe"
S="~/.workbuddy/skills/罗斯蒙德可视化图形生成/scripts"

# 0. 校验（必跑，有 ERROR 不许往下走）
"$PY" "$S/check_graph.py" graph.json

# 1. 结构化文本（嵌 Markdown / 进 Git）
"$PY" "$S/gen_mermaid.py" graph.json -o out/diagram.mmd
"$PY" "$S/gen_mermaid.py" graph.json --format plantuml -o out/diagram.puml

# 2. 可编辑文件（图形化工具打开二次修改）
"$PY" "$S/gen_drawio.py" graph.json -o out/diagram.drawio
"$PY" "$S/gen_excalidraw.py" graph.json -o out/diagram.excalidraw

# 3. 静态图
"$PY" "$S/render_svg.py" graph.json -o out/diagram.svg     # 自渲染，零依赖
# PNG：见 references/export-guide.md 的转换命令
```

然后按 `templates/图说明.md` 写图形说明，与图一起交付。

## 脚本清单

| 脚本 | 作用 | 何时用 |
|------|------|--------|
| `scripts/check_graph.py` | 校验图模型：id 唯一、边引用有效、无孤立节点、type 合法、说明齐全 | 建模后、产出前**必跑** |
| `scripts/gen_mermaid.py` | graph.json → Mermaid / PlantUML 文本 | 需要嵌文档或进 Git |
| `scripts/gen_drawio.py` | graph.json → .drawio（mxGraph XML，含自动布局） | 需要图形化二次修改（**首选**） |

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 15 个文件，合计 108.9 KiB