# Graph-简易图表技巧使用 graph-easy 为任何 GitHub Flavored Markdown 文件创建 ASCII 架构图。具有自动布局的纯文本输出 - 无需图像渲染。 ## 何时使用此技能 * 将图表添加到自述文件中 * 设计规范文档 * 任何需要架构可视化的 GFM Markdown 文件 * 创建流程图、管道或系统图 * 用户提及“图表”、“ASCII 图”、“graph-easy”或“架构图” **不适用于 ADR** \- 使用 `adr-graph-easy-architect` 进行架构决策记录（包括 ADR 特定模式，如 2 图表要求和之前/之后模板）。 ## 飞行前检查在渲染之前确保 graph-easy 已安装并正常运行。请参阅 [预检检查]() 了解完整的分层安装指南（mise-first 方法，macOS + Linux）。 **快速验证：** echo "[测试] -> [确定]" | graph-easy &>/dev/null && echo "✓ graph-easy 就绪" ** ** ## DSL 快速参考完整语法参考：[DSL 语法]() ### 要点 [Node] -> [Node] # 基本边 [A] -- 标签 --> [B] # 标记边缘 [A] <-> [B] # 双向 ( 组: [节点 A] [节点 B] ) # 容器 [n] { 标签：“显示名称”; } # 自定义标签 ### 强制图表属性图 { 标签：“标题”;流向：南； } # 从上到下图 { 标签：“标题”;流向：东； } # 从左到右 * **每个图表必须有** `label:` 以及语义表情符号 + 标题 * **每个图表必须有**明确的“流程：”方向 ### 角色安全地点 |图形表情符号 | Unicode 符号 | ASCII 标记 ---|---|---|--- 内部节点 |从来没有 |好的 |始终安全图表标签|安全|好的 |好的 ASCII 标记： `[x]` `[+]` `[!]` `[OK]` `[>]` `[*]` `[~]` `[?]` `[=]` ### 节点和边缘样式风格|语法 |用于 ---|---|--- 圆形| `{ 形状：圆形； }` |起始/结束节点双边框| `{ 边框：双； }` |批判/强调粗体边框| `{边框：粗体； }` |重要节点虚线边框| `{ 边框：点线； }` |可选（GH警告）实心箭头| `->` / `<->` |正常/幸福之路虚线箭头| `..>` |有条件/替代粗体箭头| `==>` |关键路径 ** ** ## 常见模式有关完整示例（管道、多组件、决策、分组、双向、分层架构），请参阅图表模式。 **快速模板：** # 管道（从左到右）图{标签：“管道”;流向：东； } [输入] -> [处理] -> [输出] # 多组件（自上而下）图{标签：“系统”;流向：南； } [网关] -> [服务A] [网关] -> [服务B] [服务A] -> [数据库] [服务B] -> [数据库] ** ** ## 渲染 ### 命令（平台感知） # 对于 GitHub markdown（推荐）- 呈现为实线 graph-easy --as=ascii << 'EOF' 图{流向：南； } [A] -> [B] -> [C] EOF # 用于终端/本地查看 - 更漂亮的 Unicode 行 graph-easy --as=boxart << 'EOF' 图{流向：南； } [A] -> [B] -> [C] EOF ### 输出模式模式|命令 |何时使用 ---|---|--- `ascii` | `--as=ascii` | **GitHub markdown** \- `+--+` 在任何地方都呈现为实线 '盒子艺术' | `--as=boxart` | **仅限终端** \- `┌──┐` 在本地看起来不错，在 GitHub 上有点缀 **为什么 GitHub 使用 ASCII？** GitHub 将 Unicode 方框图字符 (`┌─┐│└─┘`) 呈现为虚线。纯 ASCII（`+---+`、`|`）在任何地方都能正确呈现。 ### 生成后对齐验证（推荐）嵌入后，使用“Skill(doc-tools:ascii-diagram-validator)”进行验证 * 捕获复制粘贴对齐漂移和字体渲染问题 * 如果图表刚刚生成且未手动编辑，则跳过 ** ** ## 嵌入 Markdown 包含 GFM 可折叠部分语法的完整指南：[嵌入指南]() **关键：每个图表必须包含一个`

`源代码块。**这是不容协商的。 ## 架构 ```` +----------+ +----------+ +----------+ | 输入 | --> |流程| --> | 输出| +----------+ +----------+ +----------+ ```` <详情>

图表简单来源

```` 图{流：东； } [输入] -> [处理] -> [输出] ```` ** ** ## 等宽安全符号完整参考：[等宽符号]() 关键标记：`[+]` 添加 | `[x]` 已删除 | `[*]` 已更改 | `[!]` 警告 | `[>]` 活动 ** ** ## 图表标签（强制：每个图表都必须有表情符号+标题） **警告**：这是最常被遗忘的要求。没有标签的图表无效。 ### 正确示例 graph { label: "部署管道";流向：东； } [构建] -> [测试] -> [部署] ### 反模式（无效 - 不要这样做）图{流：东； } [构建] -> [测试] -> [部署] **为什么这是错误的**：缺少带有表情符号的“标签：”。每个图表都需要一目了然的上下文。 ** ** ## 强制清单（渲染前） ### 图级（必须有） * **`graph { 标签：“标题”; }`** \- 语义表情符号 + 标题（最容易被遗忘 - 首先检查！） * `graph { 流向：南； }` 或 `graph { flow: east; }` \- 明确的方向 * 命令使用 `--as=ascii` 进行 GitHub markdown（或仅使用 `--as=boxart` 进行终端） ### 嵌入（必须有 - 不可协商） * **`

` 带有源代码块** \- 每个图表都必须有可折叠的源代码块 * 切勿提交没有可复制源的图表 ### 嵌入后验证（推荐） * 嵌入图表后在文件上运行“ascii-diagram-validator” * 如果图表在生成后手动编辑，则尤为重要 ### 节点和边缘样式 * 开始/结束：`{ 形状：圆形； }` |关键：`{边框：双； }` |可选：`{边框：点线； }` * 主路径：`->` |条件：`..>` |关键：`==>` |标签：1-3个字 * 节点内没有图形表情符号；表情符号仅出现在 `graph { label: "..."; }` ### 结构 * 为 4 个以上相关节点分组 `( Name: ... )` * 节点 ID 短，标签描述性： `[db] { label: "PostgreSQL"; }` * 每个图最多 7-10 个节点（如果较大则拆分） ## 成功标准 ### 正确性 1. **解析无错误** \- graph-easy 接受 DSL 2. **渲染干净** \- 没有未对齐的框或断线 3. **匹配内容** \- 所代表的描述中的所有关键元素 4. **保留源代码（强制）** \- 每个图表都必须具有包含图形简易 DSL 源代码的 `

` 块 ### 美学 1. **适合平台的输出** \- `--as=ascii` 用于 GitHub，`--as=boxart` 用于终端 2. **可读标签** \- 带 `\n` 的多行，不截断 3. **清晰的流程** \-方向符合自然阅读（从上到下或从左到右） 4. **一致的样式** \- 相同的边框样式 = 始终相同的语义 ### 综合性 1. **边缘语义** \-solid=正常，dotted=条件，bold=关键 2. **逻辑分组** \- `( Group: ... )` 容器中的相关节点 ## 故障排除问题 |原因 |解决方案 ---|---|--- `未找到命令` | graph-easy 未安装 |运行[预检检查]() GH 上的虚线 |使用 `--as=boxart` |使用 `--as=ascii` 进行 GitHub markdown 盒子边框破损 |节点中的图形表情符号 |删除表情符号，使用 ASCII 标记 [x][+] 节点重叠 |太复杂|分成多个图（最多 7-10 个节点）边缘标签被切断|标签太长 |缩短至1-3个字没有显示标题 |语法错误 |使用 `graph { label: "标题";流向：南； }` 奇怪的布局|无流向 |添加 `graph { flow: 南; }` 或 `流：东` 解析错误 |节点 | 中的特殊字符转义或简化节点名称 ## 资源 * [Graph::Easy on CPAN]() * [图::简易手册]() * [图::Easy GitHub]()

图表简单

包含技能