Diagram Generator
ACTION REQUIRED（读完后立刻执行）
NOW：确认当前任务是否命中本 skill 的适用范围NOW：读取../tool-index.md，校验工具可用性和实际路径NEXT：缺工具时调用 bootstrap，不要猜路径ACT：进入"工作流"第一步并执行，不要停在确认状态
目的
从混乱或结构化的输入中创建清晰、可编辑的图表。优先使用基于文本的图表源码，以便后续审查、版本控制和优化。仅在用户要求生成图片/PDF 或者可下载的产物能够显著提升效果时，才渲染为文件。
默认工作流
- 识别用户的意图、受众和原始材料。
- 根据下面的决策表选择合适的图表类型和语言。
- 在编写图表代码之前，规范实体、关系、标签、状态、分支以及时间/顺序信息。
- 生成简洁、可读的图表源码。
- 语法上验证合理性，并在创建文件时运行
scripts/render_diagram.py。 - 返回图表源码以及关于假设的简短说明。如果生成了文件，请包含输出文件的链接。
不要过度请求澄清。如果请求不够明确，请做出合理的假设并简要标注。
图表语言决策表
除非其他语言明显更好，否则使用 Mermaid。
| 用户想要 | 优先使用 | 原因 |
|---|---|---|
| 流程、决策树、简单泳道 | Mermaid flowchart | 可读性强，易于嵌入 Markdown |
| 系统/用户交互序列 | Mermaid sequenceDiagram 或 PlantUML sequence | Mermaid 用于文档；PlantUML 用于 UML 的正式性 |
| 生命周期、状态机、转换 | Mermaid stateDiagram-v2 或 PlantUML state | 紧凑的转换语法 |
| 数据库模式、实体、关系 | Mermaid erDiagram | 可移植的 ER 表示法 |
| 类/接口/对象模型 | Mermaid classDiagram 或 PlantUML class | Mermaid 用于文档；PlantUML 用于详细的 UML |
| 项目进度 | Mermaid gantt | 简洁的时间线语法 |
| 层次结构、想法、笔记 | Mermaid mindmap | 概念图的良好默认选择 |
| 客户/产品旅程 | Mermaid journey | 内置的旅程表示法 |
| Git 历史 | Mermaid gitGraph | 内置的 Git 表示法 |
| 依赖图、包图、大型网络 | Graphviz DOT | 适合密集图形的更好布局引擎 |
| 包含层、集群、边界的架构 | Mermaid flowchart 结合子图、Graphviz 集群或 PlantUML C4 风格 | 根据请求的精度选择 |
| 带权重的流程/桑基图关系 | Mermaid sankey-beta（如果支持），否则 SVG 或 Graphviz | Mermaid 的支持可能因渲染器而异 |
| 源语言不适合的自定义视觉 | SVG | 对布局和样式进行精确控制 |
输出策略
- 始终提供可编辑的源码，除非用户明确只要求图片。
- 默认生成一个最佳图表。只有在确实有用时才提供备选方案。
- 优先选择稳定、简单的语法，避免使用可能在较旧版本的 Mermaid/PlantUML 中无法渲染的高级特性。
- 使用简短的标签。需要时将长文本拆分为图表外的注释。
- 避免模糊的节点 ID。使用 ASCII ID 和可读的标签。
- 保留用户术语，但在图表中统一大小写。
- 对于技术图表，在暗示的情况下包含边界，例如客户端、服务、数据库、队列、外部 API 和操作员/用户。
- 对于业务流程图表，在存在时区分快乐路径、决策点、失败、重试和手动步骤。
- 对于基于不确定文本创建的图表，在代码之后包含一个
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]
Assumptions:
- [仅当需要时]
Rendered file: [link] [仅当生成了文件]
对于英文用户的请求，用英文回答。对于中文用户的请求，用中文回答，除非他们要求其他语言。
---
## 按需自举（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 项？