graph-easy

Graph-Easy 图表技能

使用 graph-easy 为任意 GitHub Flavored Markdown 文件创建 ASCII 架构图。纯文本输出，自动布局，无需渲染图像。

自我演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

• 在 README 文件中添加图表
• 设计规范文档
• 任何需要架构可视化的 GFM Markdown 文件
• 创建流程图、管道图或系统图
• 用户提到“图表”“ASCII 图表”“graph-easy”或“架构图”

不适用于 ADR——架构决策记录请使用 adr-graph-easy-architect（包含 ADR 专用模式，例如必须提供 2 张图和前后对比模板）。

预检

渲染前，请确保已安装 graph-easy 且能够正常运行。完整的分层安装指南（优先使用 mise，适用于 macOS + Linux）请参阅预检。

快速验证：

echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy ready"

---

DSL 快速参考

完整语法参考：DSL 语法

基本内容

[Node] -> [Node]              # Basic edge
[A] -- label --> [B]          # Labeled edge
[A] <-> [B]                   # Bidirectional
( Group: [Node A] [Node B] )  # Container
[n] { label: "Display Name"; }  # Custom label

必需的图表属性

graph { label: "Title"; flow: south; }   # Top-to-bottom
graph { label: "Title"; flow: east; }    # Left-to-right

• 每张图表都必须包含带有语义表情符号和标题的 label:
• 每张图表都必须明确指定 flow: 方向

字符安全性

位置	图形表情符号	Unicode 符号	ASCII 标记
节点内部	绝不可用	可以使用	始终安全
图表标签	安全	可以使用	可以使用

ASCII 标记：[x] [+] [!] [OK] [>] [*] [~] [?] [=]

节点和边样式

样式	语法	用途
圆角	{ shape: rounded; }	起始/结束节点
双边框	{ border: double; }	关键内容/强调
粗边框	{ border: bold; }	重要节点
点线边框	{ border: dotted; }	可选（GH 注意事项）
实线箭头	-> / <->	常规/顺利路径
点线箭头	..>	条件/备用路径
粗箭头	==>	关键路径

---

常见模式

完整示例（管道、多组件、决策、分组、双向、分层架构）请参阅图表模式。

快速模板：

# Pipeline (left-to-right)
graph { label: "Pipeline"; flow: east; }
[Input] -> [Process] -> [Output]

# Multi-component (top-down)
graph { label: "System"; flow: south; }
[Gateway] -> [Service A]
[Gateway] -> [Service B]
[Service A] -> [Database]
[Service B] -> [Database]

---

渲染

命令（适用于不同平台）

# For GitHub markdown (RECOMMENDED) - renders as solid lines
graph-easy --as=ascii << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

# For terminal/local viewing - prettier Unicode lines
graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

输出模式

模式	命令	使用场景
ascii	--as=ascii	GitHub Markdown——+--+ 在任何地方都会渲染为实线
boxart	--as=boxart	仅限终端——┌──┐ 在本地显示效果不错，但在 GitHub 上会显示为点线

为什么 GitHub 上要使用 ASCII？ GitHub 会将 Unicode 框线字符（┌─┐│└─┘）渲染为点线。纯 ASCII（+---+、|）在任何地方都能正确显示。

生成后的对齐验证（推荐）

嵌入后，使用 Skill(doc-tools:ascii-diagram-validator) 进行验证：

• 检测复制粘贴造成的对齐偏差和字体渲染问题
• 如果图表刚生成且尚未手动编辑，可跳过

---

在 Markdown 中嵌入

包含 GFM 可折叠区段语法的完整指南：嵌入指南

重要：每张图表都必须包含 <details> 源代码块。 此要求不可协商。

## Architecture

```
+----------+     +----------+     +----------+
|  Input   | --> | Process  | --> |  Output  |
+----------+     +----------+     +----------+
```

<details>
<summary>graph-easy source</summary>

```
graph { flow: east; }
[Input] -> [Process] -> [Output]
```

</details>

---

等宽字体安全符号

完整参考：等宽字体符号

常用标记：[+] 已添加 | [x] 已移除 | [*] 已更改 | [!] 警告 | [>] 进行中

---

图表标签（强制要求：每个图表都必须包含表情符号 + 标题）

警告：这是最常被忘记的要求。没有标签的图表无效。

正确示例

graph { label: "Deployment Pipeline"; flow: east; }
[Build] -> [Test] -> [Deploy]

反面示例（无效 - 切勿这样做）

graph { flow: east; }
[Build] -> [Test] -> [Deploy]

错误原因：缺少带表情符号的 label:。每个图表都需要让人一眼就能了解其上下文。

---

强制检查清单（渲染前）

图表级别（必须满足）

• graph { label: "Title"; } - 语义表情符号 + 标题（最常被忘记 - 请先检查！）
• graph { flow: south; } 或 graph { flow: east; } - 明确指定方向
• GitHub Markdown 使用 --as=ascii，仅用于终端时使用 --as=boxart

嵌入（必须满足 - 不容妥协）

• 包含源代码的 <details> 块 - 每个图表都必须有可折叠的源代码块
• 切勿提交没有可复现源代码的图表

嵌入后验证（建议）

• 嵌入图表后，对文件运行 ascii-diagram-validator
• 如果图表在生成后经过手动编辑，这一步尤其重要

节点和边的样式

• 起点/终点：{ shape: rounded; } | 关键项：{ border: double; } | 可选项：{ border: dotted; }
• 主路径：-> | 条件路径：..> | 关键路径：==> | 标签：1-3 个词
• 节点内不得使用图形表情符号；表情符号只能放在 graph { label: "..."; } 中

结构

• 对 4 个或更多相关节点使用分组 ( Name: ... )
• 节点 ID 简短，标签清晰：[db] { label: "PostgreSQL"; }
• 每个图表最多包含 7-10 个节点（更多时拆分）

成功标准

正确性

1. 解析无错误 - graph-easy 能够接受该 DSL
2. 渲染整洁 - 没有错位的框或断开的线
3. 内容匹配 - 描述中的所有关键元素都得到体现
4. 保留源代码（强制要求） - 每个图表都必须有包含 graph-easy DSL 源代码的 <details> 块

美观性

1. 输出适合目标平台 - GitHub 使用 --as=ascii，终端使用 --as=boxart
2. 标签清晰易读 - 使用 \n 换行，不要截断
3. 流程清晰 - 方向符合自然阅读顺序（自上而下或从左到右）
4. 样式一致 - 相同的边框样式始终表示相同的语义

完整性

1. 边的语义 - 实线 = 普通，点线 = 条件，粗线 = 关键
2. 逻辑分组 - 使用 ( Group: ... ) 容器对相关节点进行分组

故障排除

问题	原因	解决方案
command not found	未安装 graph-easy	运行预检
GH 上显示点线	使用了 --as=boxart	GitHub Markdown 请使用 --as=ascii
框线断裂	节点中使用了图形表情符号	移除表情符号，使用 ASCII 标记 [x][+]
节点重叠	图表过于复杂	拆分成多个图表（每个最多 7-10 个节点）
边标签被截断	标签过长	缩短至 1-3 个词
未显示标题	语法错误	使用 graph { label: "Title"; flow: south; }
布局异常	未指定流程方向	添加 graph { flow: south; } 或 flow: east
解析错误	节点中包含特殊字符	转义或简化节点名称

资源

• CPAN 上的 Graph::Easy
• Graph::Easy 手册
• Graph::Easy GitHub 页面

执行后反思

此技能执行完毕后，关闭前请检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生偏移，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要变通方案？ — 如果你不得不临时调整（更换标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需采用相同的变通方案。

只有问题确实存在且可复现时才进行更新，不要基于猜测更新。