diagram-generator

图表生成器

必须执行的操作（读完后立刻执行）

1. NOW：确认当前任务是否命中本 skill 的适用范围
2. NOW：读取 ../tool-index.md，校验工具可用性和实际路径
3. NEXT：缺工具时调用 bootstrap，不要猜路径
4. ACT：进入"工作流"第一步并执行，不要停在确认状态

用途

从杂乱或结构化的输入中创建清晰、可编辑的图表。优先使用基于文本的图表源，以便结果可以被审阅、版本化和改进。只有当用户要求图片/PDF，或可下载的产物确实有显著帮助时，才渲染为文件。

默认工作流

1. 确定用户的意图、受众和源材料。
2. 使用下方的决策表选择图表家族和语言。
3. 在编写图表代码之前，先规范化实体、关系、标签、状态、分支以及时间/顺序信息。
4. 生成简洁、可读的图表源。
5. 在脑中校验语法，创建文件时运行 scripts/render_diagram.py。
6. 返回图表源，并附上关于假设的简短说明。生成文件时，包含输出文件的链接。

不要过度请求澄清。如果请求不够明确，做出合理的假设并简要标注它们。

图表语言决策表

除非另一种语言明显更好，否则使用 Mermaid。

用户想要	优先选择	原因
流程图、决策树、简单泳道图	Mermaid flowchart	可读性强，易于粘贴到 Markdown
系统/用户交互序列	Mermaid sequenceDiagram 或 PlantUML sequence	文档用 Mermaid；UML 正式性用 PlantUML
生命周期、状态机、状态转换	Mermaid stateDiagram-v2 或 PlantUML state	紧凑的转换语法
数据库模式、实体、关系	Mermaid erDiagram	可移植的 ER 表示法
类/接口/对象模型	Mermaid classDiagram 或 PlantUML class	文档用 Mermaid；详细 UML 用 PlantUML
项目进度	Mermaid gantt	简洁的时间线语法
层级、想法、笔记	Mermaid mindmap	想法图的良好默认选择
客户/产品旅程	Mermaid journey	内置的旅程表示法
git 历史	Mermaid gitGraph	内置的 git 表示法
依赖图、包图、大型网络	Graphviz DOT	对密集图有更好的布局引擎
带层级、集群、边界的架构	带 subgraphs 的 Mermaid flowchart、Graphviz clusters 或 PlantUML C4 风格	根据所要求的保真度选择
加权流/桑基式关系	支持时用 Mermaid sankey-beta，否则用 SVG 或 Graphviz	Mermaid 支持可能因渲染器而异
源语言难以适配的自定义可视化	SVG	对布局和样式有精确控制

输出策略

• 始终提供可编辑的源，除非用户明确只要求图片。
• 默认输出一个最佳图表。只有在确实有用时才提供备选方案。
• 优先使用稳定、简单的语法，而不是在旧版 Mermaid/PlantUML 中可能无法渲染的花哨特性。
• 使用简短标签。必要时将长文本拆分到图表外的注释中。
• 避免有歧义的节点 ID。使用 ASCII ID 和人类可读的标签。
• 保留用户术语，但在单个图表内统一大小写。
• 对于技术图表，当隐含存在时，包含诸如 client、service、database、queue、external API 和 operator/user 等边界。
• 对于业务流程图，当存在时，区分 happy path、决策点、失败、重试和手动步骤。
• 对于从不确定文本创建的图表，在代码后包含一个 Assumptions 部分。

Mermaid 生成规则

查阅 references/diagram-patterns.md 获取紧凑模板。

Mermaid 通用规则：

• 以正确的图表指令开头，例如 flowchart TD、sequenceDiagram、erDiagram、gantt、mindmap 或 journey。
• 对于流程图，除非用户要求从左到右，否则使用 flowchart TD；对于架构和流水线，使用 flowchart LR。
• 使用子图表示泳道或架构分层。用可读的标签命名子图。
• 保持节点 ID 稳定且仅使用 ASCII，例如 ingest_service[Ingest Service]。
• 为包含可能混淆解析器的标点的标签加引号。
• 使用菱形表示分支判断：decision{Condition?}。
• 使用一致的边标签：-- yes -->、-- no -->、-. async .-> 或 == critical ==>，仅在有意义时使用。
• 在时序图中，先声明参与者再写消息。用 actor 表示人类，用 participant 表示系统。
• 使用 alt/else/end、opt/end、loop/end 和 par/and/end 块表示条件、可选、重复和并行流程。

Graphviz DOT 生成规则

对于大型、密集或对布局敏感的关系图，使用 Graphviz。

• 对于有向关系优先使用 digraph G，对于无向网络使用 graph G。
• 在顶部设置有利于布局的图属性：rankdir=LR、nodesep、ranksep，在有帮助时使用 splines=true。
• 使用 subgraph cluster_name 表示边界和子系统。
• 使用简洁的标签和克制的样式。
• 仅在边标签能增加含义时使用。
• 对于大量节点，按领域用簇分组，避免交叉过多的全连接边。

PlantUML 生成规则

当用户要求 UML 或需要正式的 UML 记法时，使用 PlantUML。

• 用 @startuml 和 @enduml 包裹图表。
• 在有帮助时使用 actor、participant、database、queue、collections 或 component 构造型。
• 使用 package、rectangle 或 node 表示架构边界。
• 对于类图，除非用户要求穷尽细节，否则只包含重要的字段/方法。
• 对于活动图，使用清晰的开始/结束标记和明确的分支标签。

SVG 生成规则

仅当文本图表语言无法可靠表达所请求的视觉效果时，才使用 SVG。

• 保持 SVG 简单、可访问且可编辑。
• 包含 <title> 和有意义的文本标签。
• 优先使用矩形、线条、箭头和分组，而非复杂路径。
• 不要嵌入外部字体或远程图片。

渲染文件

当用户要求 PNG/SVG/PDF 时，创建一个源文件并运行：

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> 是本包 skills/ 目录的实际路径，AI 应自动检测。

渲染器有意容忍依赖缺失。它会尝试常见的本地工具，并在渲染器不可用时报告可操作的安装提示。除非脚本成功完成且输出文件存在，否则不要声称已渲染图像。

验证清单

在最终确定之前：

• 图表类型与用户的任务匹配。
• 源码对所选择的语言在语法上合理。
• 标签足够短以适合显示。
• 边和消息顺序准确反映输入。
• 当输入不完整时，明确指出假设。
• 对于生成的文件，输出存在并且可以打开或大小非零。

常见响应模板

对大多数图表回答使用此结构：

下面是可编辑的 [language] 版本：

```[language]
[source]

假设：

• [仅在需要时]

渲染文件：[link] [仅在已生成时]

For English user requests, respond in English. For Chinese user requests, respond in Chinese unless they ask otherwise.

---

## 按需自举（On-Demand Bootstrap）

### 自动化能力边界

| 工具 | 可自动安装 | 安装方式 | 说明 |
|------|-----------|---------|------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | 渲染 Mermaid 为 PNG/SVG |
| Graphviz (dot) | ✗ | 手动安装 | https://graphviz.org/download/ |
| PlantUML | ✗ | 需要 Java + plantuml.jar | https://plantuml.com/download |
| Python (render script) | ✓ | 已在 bootstrap 中 | `scripts/render_diagram.py` 依赖 |

### 说明

本 skill 主要输出文本格式的图表源码（Mermaid/DOT/PlantUML），不一定需要本地渲染工具。只有当用户明确要求生成 PNG/SVG/PDF 文件时才需要对应的渲染器。

如果渲染器不可用，`scripts/render_diagram.py` 会输出安装提示而不是报错。

---

## 路由上下文

**上游入口**: `skills/SKILL.md`（总控）、`routing.md`
**触发条件**: 用户说"画图"、"流程图"、"架构图"、"攻击路径图"、"时序图"、"Mermaid"、"Graphviz"、"PlantUML"
**下游出口**:
- 生成的图表可嵌入 `docs-generator/` 的报告中
- 攻击路径图可配合 `pentest-tools/` 的渗透报告

**同级关联模块**: `docs-generator/`（报告中嵌入图表）


## 任务完成自检（声称完成前 MUST 通过）

- [ ] 我是否执行了工作流中的每一步（而不是只阅读）？
- [ ] 我是否基于 `tool-index` 使用了真实工具路径？
- [ ] 我是否产出了可复现证据（命令/脚本/截图/报告）？
- [ ] 我是否完成并回写了 RULES 要求的 Checklist 项？