FlowForge

FlowForge — Draw.io 图表技能

生成专业的 draw.io XML 图表文件。支持 13 种图表类型：流程图、对比图、层级堆叠图、循环图、树形图、中心辐射图、列图、矩阵图、漏斗图、时间线、时序图和泳道图。

用法

/FlowForge "OAuth 2.0 authorization code flow"
/FlowForge path/to/design-doc.md
/FlowForge "CI/CD pipeline" --type loop
/FlowForge "Monolith vs Microservices" --type compare --theme morandi
/FlowForge "System Architecture" --lang en

---

工作流

步骤 1：理解并提出方案（确认一次，而非三次）

如果提供了文档： 通读全文，找出 1–3 个适合用图表呈现的位置，并为每个位置注明插入位置、主题（一句话）和推荐类型（参见“图表类型参考”）。

如果直接提供了概念： 确定核心信息，并通过“选择指南”选择类型。

然后提出一份合并后的方案，并且只请求确认一次。方案包含：

• 图表类型和主题（默认：tech-blue；其他选项：morandi、mint、terracotta、indigo）
• ASCII 草图：所有节点及其标签、箭头方向和标签、分组、颜色角色标签、布局方向

草图示例：

Direction: left-to-right | Nodes: 4 | Type: flow | Theme: tech-blue

[primary] Code Commit  →  [process] Build  →  [process] Test  →  [accent] Deploy
                                                    ↓ (fail)
                                              [error] Alert

当请求已经明确指定所有内容（用户提供了 --type/--theme 或描述清晰无歧义），或者没有人可以回复（子 Agent、批处理、CI）时，完全跳过确认。此时使用默认值继续，并在最终报告中说明所采用的假设。

步骤 2：生成 draw.io XML

1. 阅读 references/layouts.md——所选类型的布局算法——并根据公式计算所有坐标
2. 应用 themes.md 中的主题颜色
3. 使用 xml-reference.md 中的元素模板
4. 对于不熟悉的类型，阅读 examples.md 中列出的对应示例文件

步骤 3：验证（必须执行）

python3 {skill_dir}/scripts/validate.py <file.drawio> --theme <theme>

此步骤会确定性地检查：XML 格式是否正确、ID 是否唯一、箭头引用是否悬空、边线样式是否为正交、画布边界、节点重叠、z 顺序（容器位于子项之前）、字体大小、文本适配估算以及主题颜色合规性。修复所有 ERROR 并重新运行，直到检查通过。 WARN 是启发式提示——逐项判断并修复确实存在的问题。

步骤 4：视觉自检（draw.io CLI 可用时）

bash {skill_dir}/scripts/render.sh <file.drawio>   # writes a .png next to the file

如果脚本报告未安装 draw.io，则跳过此步骤（用户可以通过 brew install --cask drawio 一次性启用）。否则，阅读 PNG 并以全新的视角检查：文本是否溢出节点、区域是否拥挤、箭头是否与节点碰撞、颜色节奏以及整体平衡。修复并重新渲染，直到效果理想——这一步能发现规则无法捕捉的问题。

步骤 5：保存并交付

将 .drawio 文件保存到输出目录（参见“配置”）。保存后，报告：

• 文件路径（如果执行了步骤 4，还要报告渲染后的 PNG 路径）
• 打开方式：draw.io 桌面应用或 https://app.diagrams.net

迭代

用户查看后若要求修改：

1. 读取当前 .drawio 文件
2. 根据反馈修改 XML
3. 另存为 {name}_v2.drawio（保留之前的版本），然后重新执行步骤 3–4

---

配置

可选的项目配置文件 ./.flowforge.json（位于工作目录中，绝不能放在技能目录内——技能目录可能是只读的，也可能由多个项目共享）：

{
  "defaultTheme": "tech-blue",
  "outputDir": "./diagrams",
  "language": "auto"
}

如果文件不存在，严格使用以下默认值——无需询问用户。"language": "auto" 表示使用与用户相同的语言；技术缩写（API、LLM、CI/CD）始终保留英文。每次调用时传入的标志（--theme、--lang）优先于配置。

---

图表类型参考

核心类型

类型	代码	适用场景	示例
线性流程	flow	A→B→C 的顺序步骤	API 调用流程、数据管道
垂直流程	flow-vertical	自上而下的流程	决策流程、审批链
对比	compare	并列比较 A 和 B	传统方法与 AI 方法
分层结构	layers	技术栈、层级	系统架构层
循环	loop	迭代流程	ML 训练循环、CI/CD
树形结构	tree	层级结构、分类体系	组织结构图、决策树
中心辐射	hub	核心概念及其分支	产品功能图

扩展类型

类型	代码	适用场景
并行列	columns	3 个或更多并行概念
矩阵	matrix	多维比较
漏斗	funnel	筛选、转化
时间线	timeline	版本演进、历史
序列	sequence	组件交互
泳道图	swimlane	跨角色流程（谁负责什么）

选择指南

内容模式	推荐类型
顺序步骤	flow 或 flow-vertical
比较两件事	compare
3 个或更多并行概念	columns 或 hub
分层系统	layers
迭代／循环流程	loop
一个核心，多个分支（包括思维导图风格）	hub 或 tree
组件之间的通信	sequence
随时间变化	timeline
多标准评估	matrix
渐进式筛选	funnel
由不同角色／系统负责的步骤	swimlane

---

颜色使用原则

这是影响视觉质量的最重要部分。

4+6 规则

每个主题都有 4 种基础颜色（primary、process、accent、neutral）和 6 种扩展颜色（success、warning、error、secondary、storage、group）。主色系应始终占主导；非主色系点缀的数量应随图表大小调整。

按图表大小分配颜色

节点数	目标颜色数	指南
3-5 个节点	2-3 种颜色	主色系占主导。点缀节点最多 1 个。
6-8 个节点	3-4 种颜色	主色约占 60%。在语义转折点添加 1-2 种非主色。
9 个或更多节点	4-5 种颜色	主色约占 50%。分配 2-3 种非主色，以形成视觉节奏。

无论图表大小如何，使用 6 种以上的颜色几乎总是不好看。

颜色分配策略

1. 主色占主导 — primary 和 process 覆盖最大的视觉区域，并用于最大的节点。
2. 点缀色是手术刀，不是油漆刷 — 关键强调最多 1-2 处，绝不要用于最大的节点。
3. 随长度调整 — 4 个节点的流程使用 2 种颜色显得简洁；9 个节点的流程使用 2 种颜色则会显得单调。沿自然的语义边界添加非主色，以形成节奏。
4. 连续 3 个的指导原则 — 如果发现 4 个或更多相邻节点颜色相同，就选出语义特征最明显的节点并为其更换颜色。
5. 分散布局 — 非主色节点应分散在图表中，而不是聚集在同一区域。

语义颜色选择启发式

节点类型	推荐颜色
用户输入／起点	primary
标准处理步骤	process
决策／分支点	warning 或 accent
特定领域／翻译步骤	secondary
关键转换／强调	accent
数据源／外部系统	neutral
错误路径／回退	accent 或 error
成功输出／终点	success 或 primary
数据库／存储	storage

themes.md 底部提供了颜色节奏的正反示例。

---

设计原则

1. 叙述式标题——使用“OAuth 2.0 如何授权用户”，而不是“OAuth 2.0 图示”。
2. 双语标签——使用用户的语言。技术缩写（API、LLM、CI/CD）始终保留英文。
3. 正交流程箭头——节点之间的每个箭头都包含 edgeStyle=orthogonalEdgeStyle;，确保只沿水平或垂直方向绘制。例外：带有 endArrow=none 的装饰性连接线（辐射线、时间线轴线/刻度）可以直线绘制。

---

注意事项——常见问题

验证器（第 3 步）会在事后捕获大多数几何/引用错误，但了解以下问题可以避免返工：

1. 富文本节点标题重复——标题位于单独的文本单元格中；背景矩形的 value="" 必须保留为空，否则标题会渲染两次。
2. 箭头忽略退出/进入点——始终指定 exitX/exitY/entryX/entryY；否则 draw.io 会自动布线路径，通常效果很差。
3. value 属性中的 HTML 实体——value 是 XML 属性中的 HTML：< > &，项目符号使用 •。漏掉一个转义字符就会破坏整个文件（验证器：解析错误）。
4. 在子元素之后绘制的填充框会遮住它们——泳道背景和所有填充容器都要在其中的节点之前定义（验证器：z 序检查）。
5. 画布过小——根据布局公式计算 pageWidth/pageHeight：max(x + w) + CANVAS_PAD（验证器：边界检查）。
6. 忘记 parent="1"——每个内容元素都需要它，除非该元素是有意分组的（验证器：父级检查）。
7. 菱形文本溢出——菱形的可用宽度约为 60%；标签应限制为 2-3 个简短的词，字体大小为 11。
8. 蛇形布局的换行箭头——回转箭头应从一行最后一个节点的底部出发，并进入下一行第一个节点的顶部，而不是从侧面进入。
9. 循环返回箭头——在 loop 图中，最后一个节点指向第一个节点的箭头应绕矩形外侧布线，绝不要穿过中心。
10. 宽度计算的差一错误——n 个节点有 n-1 个间隙：画布宽度 = PAD×2 + n×NODE_W + (n-1)×GAP_H（验证器：边界/重叠检查）。
11. 分支/合并箭头变为对角线——退出点/进入点未对齐时，只有 edgeStyle=orthogonalEdgeStyle; 能确保箭头正交；每个流程箭头都要包含它（验证器：样式检查）。

---

支持文件

按照工作流步骤的要求阅读文件——不要一开始就全部加载。

文件	阅读时机
references/layouts.md	第 2 步，计算坐标前——全局常量 + 全部 13 种布局算法
themes.md	第 2 步，应用颜色时——5 种主题 × 10 种语义颜色 + 7 种文本颜色、色彩节奏示例
xml-reference.md	第 2 步，编写 XML 时——画布样板、元素模板、箭头方向表
examples.md	第 2 步——坐标计算演练 + 示例文件索引
scripts/validate.py	第 3 步——对每个生成的文件运行（不要阅读，只需运行）
scripts/render.sh	第 4 步——导出 PNG，用于视觉自检

示例 .drawio 文件（位于 examples/ 中）

可正常工作的实际文件，生成类似类型的图时可参照阅读：

• examples/flow-cicd.drawio——线性流程，4 个节点，tech-blue
• examples/compare-monolith-vs-micro.drawio——对比，2 列 × 3 行，morandi
• examples/loop-ml-training.drawio——循环，4 个节点，顺时针，mint
• examples/tree-storage-decision.drawio——包含菱形节点的决策树，mint
• examples/hub-agent-capabilities.drawio——中心辐射图，6 条辐射线，indigo
• examples/timeline-llm-history.drawio——包含轴线和刻度的时间线，terracotta