Back to Details

graph-easy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Graph-Easy Diagram Skill

Graph-Easy 图表技能

Create ASCII architecture diagrams for any GitHub Flavored Markdown file using graph-easy. Pure text output with automatic layout - no image rendering required.
使用graph-easy为任何GitHub Flavored Markdown（GFM）文件创建ASCII架构图。纯文本输出，自动布局 - 无需图像渲染。

When to Use This Skill

何时使用该技能

  • Adding diagrams to README files
  • Design specification documentation
  • Any GFM markdown file needing architecture visualization
  • Creating flowcharts, pipelines, or system diagrams
  • User mentions "diagram", "ASCII diagram", "graph-easy", or "architecture chart"
NOT for ADRs - Use 
adr-graph-easy-architect
for Architecture Decision Records (includes ADR-specific patterns like 2-diagram requirement and before/after templates).
  • 为README文件添加图表
  • 设计规范文档
  • 任何需要架构可视化的GFM Markdown文件
  • 创建流程图、流水线或系统图
  • 用户提及“图表”、“ASCII图表”、“graph-easy”或“架构图”时
不适用于ADR - 如需架构决策记录（ADR），请使用
adr-graph-easy-architect
（包含ADR特定模式，如双图表要求、前后模板等）。

Preflight Check

预检查

Run these checks in order. Each layer depends on the previous.
按顺序运行以下检查，每一层依赖于前一层。

Layer 1: Package Manager

第一层：包管理器

bash
/usr/bin/env bash << 'SETUP_EOF'
bash
/usr/bin/env bash << 'SETUP_EOF'

Detect OS and set package manager

检测操作系统并设置包管理器

case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: Unsupported OS (require macOS or Linux)"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: $PM not installed"; exit 1; } echo "✓ Package manager: $PM" SETUP_EOF
undefined
case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: 不支持的操作系统（需macOS或Linux）"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: 未安装$PM"; exit 1; } echo "✓ 包管理器: $PM" SETUP_EOF
undefined

Layer 2: Perl + cpanminus (mise-first approach)

第二层：Perl + cpanminus（优先使用mise）

bash
undefined
bash
undefined

Prefer mise for unified tool management

优先使用mise进行统一工具管理

if command -v mise &>/dev/null; then

Install Perl via mise

mise which perl &>/dev/null || mise install perl

Install cpanminus under mise perl

mise exec perl -- cpanm --version &>/dev/null 2>&1 || { echo "Installing cpanminus under mise perl..." mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus } echo "✓ cpanminus installed (via mise perl)" else

Fallback: Install cpanminus via system package manager

command -v cpanm &>/dev/null || { echo "Installing cpanminus via $PM..." case "$PM" in brew) brew install cpanminus ;; apt) sudo apt install -y cpanminus ;; esac } echo "✓ cpanminus installed" fi
undefined
if command -v mise &>/dev/null; then

通过mise安装Perl

mise which perl &>/dev/null || mise install perl

在mise管理的Perl环境下安装cpanminus

mise exec perl -- cpanm --version &>/dev/null 2>&1 || { echo "在mise Perl环境下安装cpanminus..." mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus } echo "✓ cpanminus已安装（通过mise Perl）" else

备选方案：通过系统包管理器安装cpanminus

command -v cpanm &>/dev/null || { echo "通过$PM安装cpanminus..." case "$PM" in brew) brew install cpanminus ;; apt) sudo apt install -y cpanminus ;; esac } echo "✓ cpanminus已安装" fi
undefined

Layer 3: Graph::Easy Perl module

第三层：Graph::Easy Perl模块

bash
undefined
bash
undefined

Check if Graph::Easy is installed (mise-first)

检查是否已安装Graph::Easy（优先使用mise）

if command -v mise &>/dev/null; then mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || { echo "Installing Graph::Easy via mise perl cpanm..." mise exec perl -- cpanm Graph::Easy } echo "✓ Graph::Easy installed (via mise perl)" else perl -MGraph::Easy -e1 2>/dev/null || { echo "Installing Graph::Easy via cpanm..." cpanm Graph::Easy } echo "✓ Graph::Easy installed" fi
undefined
if command -v mise &>/dev/null; then mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || { echo "通过mise Perl的cpanm安装Graph::Easy..." mise exec perl -- cpanm Graph::Easy } echo "✓ Graph::Easy已安装（通过mise Perl）" else perl -MGraph::Easy -e1 2>/dev/null || { echo "通过cpanm安装Graph::Easy..." cpanm Graph::Easy } echo "✓ Graph::Easy已安装" fi
undefined

Layer 4: Verify graph-easy is in PATH

第四层：验证graph-easy是否在PATH中

bash
undefined
bash
undefined

Verify graph-easy is accessible and functional

验证graph-easy是否可访问且功能正常

command -v graph-easy &>/dev/null || { echo "ERROR: graph-easy not found in PATH" exit 1 }
command -v graph-easy &>/dev/null || { echo "ERROR: graph-easy未在PATH中找到" exit 1 }

Test actual functionality (--version hangs waiting for stdin AND exits with code 2)

测试实际功能（--version会等待标准输入且退出码为2，因此改用管道测试）

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

All-in-One Preflight Script

一站式预检查脚本

bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
bash
/usr/bin/env bash << 'PREFLIGHT_EOF'

Copy-paste this entire block to ensure graph-easy is ready (macOS + Linux)

复制粘贴整个代码块，确保graph-easy就绪（支持macOS + Linux）

Prefers mise for unified cross-platform tool management

优先使用mise进行跨平台统一工具管理

Check for mise first (recommended)

首先检查是否安装mise（推荐）

if command -v mise &>/dev/null; then echo "Using mise for Perl management..." mise which perl &>/dev/null || mise install perl mise exec perl -- cpanm --version &>/dev/null 2>&1 ||
mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || mise exec perl -- cpanm Graph::Easy else

Fallback: system package manager

echo "💡 Tip: Install mise for unified tool management: curl https://mise.run | sh" case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: Unsupported OS"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: $PM not installed"; exit 1; } command -v cpanm &>/dev/null || { [ "$PM" = "apt" ] && sudo apt install -y cpanminus || brew install cpanminus; } perl -MGraph::Easy -e1 2>/dev/null || cpanm Graph::Easy fi
if command -v mise &>/dev/null; then echo "使用mise管理Perl..." mise which perl &>/dev/null || mise install perl mise exec perl -- cpanm --version &>/dev/null 2>&1 ||
mise exec perl -- curl -L https://cpanmin.us | mise exec perl -- perl - App::cpanminus mise exec perl -- perl -MGraph::Easy -e1 2>/dev/null || mise exec perl -- cpanm Graph::Easy else

备选方案：使用系统包管理器

echo "💡 提示：安装mise以实现统一工具管理：curl https://mise.run | sh" case "$(uname -s)" in Darwin) PM="brew" ;; Linux) PM="apt" ;; *) echo "ERROR: 不支持的操作系统"; exit 1 ;; esac command -v $PM &>/dev/null || { echo "ERROR: 未安装$PM"; exit 1; } command -v cpanm &>/dev/null || { [ "$PM" = "apt" ] && sudo apt install -y cpanminus || brew install cpanminus; } perl -MGraph::Easy -e1 2>/dev/null || cpanm Graph::Easy fi

Verify graph-easy is in PATH and functional

验证graph-easy是否在PATH中且功能正常

command -v graph-easy &>/dev/null || { echo "ERROR: graph-easy not in PATH after installation" exit 1 }
command -v graph-easy &>/dev/null || { echo "ERROR: 安装后graph-easy仍未在PATH中" exit 1 }

Test actual functionality (--version hangs waiting for stdin AND exits with code 2)

测试实际功能（--version会等待标准输入且退出码为2，因此改用管道测试）

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

---
echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy已就绪" PREFLIGHT_EOF

---

Part 1: DSL Syntax

第一部分：DSL语法

Basic Elements

基础元素

undefined
undefined

Nodes (square brackets)

节点（方括号）

[Node Name]
[节点名称]

Edges (arrows)

边（箭头）

[A] -> [B]
[A] -> [B]

Labeled edges

带标签的边

[A] -- label --> [B]
[A] -- 标签 --> [B]

Bidirectional

双向边

[A] <-> [B]
[A] <-> [B]

Chain

链式结构

[A] -> [B] -> [C]
undefined
[A] -> [B] -> [C]
undefined

Groups (Containers)

分组（容器）

undefined
undefined

Named group with dashed border

带虚线边框的命名分组

( Group Name: [Node A] [Node B] )
( 分组名称: [节点A] [节点B] )

Nested connections

嵌套连接

( Frontend: [React App] [API Client] ) ( Backend: [API Server] [Database] ) [API Client] -> [API Server]
undefined
( 前端: [React App] [API客户端] ) ( 后端: [API服务器] [数据库] ) [API客户端] -> [API服务器]
undefined

Node Labels

节点标签

undefined
undefined

Custom label (different from ID)

自定义标签（与ID不同）

[db] { label: "PostgreSQL Database"; }
[db] { label: "PostgreSQL数据库"; }

ASCII markers for visual distinction INSIDE boxes

用于视觉区分的ASCII标记（放在节点内部）

(emojis break box alignment - use ASCII markers instead)

（表情符号会破坏框对齐 - 改用ASCII标记）

[deleted] { label: "[x] Old Component"; } [added] { label: "[+] New Component"; } [warning] { label: "[!] Deprecated"; } [success] { label: "[OK] Passed"; }

**Character rules for nodes:**

- Graphical emojis (rocket, bulb, checkmark) - NEVER (double-width breaks box alignment)
- Unicode symbols (check, cross, arrow) - OK (single-width, safe)
- ASCII markers ([x] [+] [!] :) ) - ALWAYS safe (monospace)

Use `graph { label: "..."; }` for graphical emojis in title/legend.

**Example: Emoji breaks alignment (DON'T DO THIS)**
[已删除] { label: "[x] 旧组件"; } [新增] { label: "[+] 新组件"; } [警告] { label: "[!] 已弃用"; } [成功] { label: "[OK] 通过"; }

**节点字符规则：**

- 图形表情符号（火箭、灯泡、对勾）- 绝对禁止（双宽度会破坏框对齐）
- Unicode符号（对勾、叉号、箭头）- 允许（单宽度，安全）
- ASCII标记（[x] [+] [!] :) ）- 始终安全（等宽字体）

如需在标题/图例中使用图形表情符号，请使用`graph { label: "..."; }`。

**示例：表情符号破坏对齐（禁止操作）**

BAD - emoji inside node

错误 - 节点内使用表情符号

[rocket] { label: "Launch"; }

Renders broken:
+----------------+ | Launch | <-- box edge misaligned due to double-width emoji +----------------+

**Example: ASCII marker preserves alignment (DO THIS)**
[rocket] { label: "启动"; }

渲染结果会错位：
+----------------+ | 启动 | <-- 由于双宽度表情符号，框边缘错位 +----------------+

**示例：ASCII标记保持对齐（正确操作）**

GOOD - ASCII marker inside node

正确 - 节点内使用ASCII标记

[rocket] { label: "[>] Launch"; }

Renders correctly:
+--------------+ | [>] Launch | +--------------+
undefined
[rocket] { label: "[>] 启动"; }

渲染结果正确：
+--------------+ | [>] 启动 | +--------------+
undefined

Flow Direction (MANDATORY: Always specify)

流向（必填：必须明确指定）

undefined
undefined

MANDATORY: Always specify flow direction explicitly

必填：必须明确指定流向

graph { flow: south; } # Top-to-bottom (architecture, decisions) graph { flow: east; } # Left-to-right (pipelines, sequences)

Never rely on default flow - explicit is clearer.
graph { flow: south; } # 从上到下（架构、决策类图表） graph { flow: east; } # 从左到右（流水线、序列类图表）

永远不要依赖默认流向 - 明确指定更清晰。

Graph Title and Legend (Outside Boxes - Emojis Safe Here)

图表标题和图例（框外 - 可安全使用表情符号）

Emojis break alignment INSIDE boxes but are SAFE in graph titles/legends.
Emoji Selection Guide - Choose emoji that matches diagram purpose:
Diagram TypeEmojiExample Title
Migration/Changeswap
"Database Migration"
Deployment/Releaserocket
"Deployment Pipeline"
Data Flowchart
"Data Ingestion Flow"
Security/Authlock
"Authentication Flow"
Error/Failurewarn
"Error Handling"
Decision/Branchsplit
"Routing Decision"
Architecturebuild
"System Architecture"
Network/APIglobe
"API Integration"
Storage/Databasedisk
"Storage Layer"
Monitoring/Observabilitysignal
"Monitoring Stack"
undefined
表情符号在节点内部会破坏对齐，但在图表标题/图例中是安全的。
表情符号选择指南 - 选择与图表用途匹配的表情符号：
图表类型表情符号示例标题
迁移/变更🔄
"数据库迁移"
部署/发布🚀
"部署流水线"
数据流📊
"数据采集流程"
安全/认证🔒
"认证流程"
错误/故障⚠️
"错误处理"
决策/分支🔀
"路由决策"
架构🏗️
"系统架构"
网络/API🌐
"API集成"
存储/数据库💾
"存储层"
监控/可观测性📶
"监控栈"
undefined

Title with semantic emoji

带语义表情符号的标题

graph { label: "Deployment Pipeline"; flow: east; }
graph { label: "🚀 部署流水线"; flow: east; }

Title with legend (multiline using \n)

带图例的标题（使用\n换行）

graph { label: "Hook Flow\n----------\nAllow Deny Warn"; flow: south; }
undefined
graph { label: "钩子流程\n----------\n允许 拒绝 警告"; flow: south; }
undefined

Node Styling (Best Practices)

节点样式（最佳实践）

undefined
undefined

Rounded corners for start/end nodes

开始/结束节点使用圆角

[ Start ] { shape: rounded; } [ End ] { shape: rounded; }
[ 开始 ] { shape: rounded; } [ 结束 ] { shape: rounded; }

Double border for emphasis

双边框用于强调

[ Critical Step ] { border: double; }
[ 关键步骤 ] { border: double; }

Bold border for important nodes

粗边框用于重要节点

[ Key Decision ] { border: bold; }
[ 核心决策 ] { border: bold; }

Dotted border for optional/skippable

虚线边框用于可选/可跳过节点

[ Optional ] { border: dotted; }
[ 可选 ] { border: dotted; }

Multiline labels with \n

使用\n实现多行标签

[ Hook Input\n(stdin JSON) ]

**Rendered examples:**
+----------+ +---------+ | Rounded | | Default | +----------+ +---------+
+==========+ +=========+ | Double | | Bold | +==========+ +=========+

> **Note:** Dotted borders (`{ border: dotted; }`) use special characters that render inconsistently on GitHub. Use sparingly.
[ 钩子输入\n(标准输入JSON) ]

**渲染示例：**
+----------+ +---------+ | 圆角节点 | | 默认节点 | +----------+ +---------+
+==========+ +=========+ | 双边框节点 | | 粗边框节点 | +==========+ +=========+

> **注意：** 虚线边框（`{ border: dotted; }`）使用的特殊字符在GitHub上渲染不一致，请谨慎使用。

Edge Styles

边样式

[ A ] -> [ B ]      # Solid arrow (default)
[ A ] ..> [ B ]     # Dotted arrow
[ A ] ==> [ B ]     # Bold/double arrow
[ A ] - -> [ B ]    # Dashed arrow
[ A ] -- label --> [ B ]  # Labeled edge
[ A ] -> [ B ]      # 实线箭头（默认）
[ A ] ..> [ B ]     # 虚线箭头
[ A ] ==> [ B ]     # 粗/双箭头
[ A ] - -> [ B ]    # 破折号箭头
[ A ] -- 标签 --> [ B ]  # 带标签的边

Part 2: Common Diagram Patterns

第二部分：常见图表模式

Pipeline (Left-to-Right)

流水线（从左到右）

graph { flow: east; }
[Input] -> [Process] -> [Output]
graph { flow: east; }
[输入] -> [处理] -> [输出]

Multi-Component System

多组件系统

graph { flow: south; }
[API Gateway] -> [Service A]
[API Gateway] -> [Service B]
[Service A] -> [Database]
[Service B] -> [Database]
graph { flow: south; }
[API网关] -> [服务A]
[API网关] -> [服务B]
[服务A] -> [数据库]
[服务B] -> [数据库]

Decision with Options

带选项的决策

graph { flow: south; }
[Decision] -> [Option A]
[Decision] -> [Option B]
[Decision] -> [Option C]
graph { flow: south; }
[决策点] -> [选项A]
[决策点] -> [选项B]
[决策点] -> [选项C]

Grouped Components

分组组件

( Frontend:
  [React App]
  [Vue App]
)
( Backend:
  [API Server]
  [Worker]
)
[React App] -> [API Server]
[Vue App] -> [API Server]
[API Server] -> [Worker]
( 前端:
  [React App]
  [Vue App]
)
( 后端:
  [API服务器]
  [工作进程]
)
[React App] -> [API服务器]
[Vue App] -> [API服务器]
[API服务器] -> [工作进程]

Bidirectional Flow

双向流

[Client] <-> [Server]
[Server] -> [Database]
[客户端] <-> [服务器]
[服务器] -> [数据库]

Layered Architecture

分层架构

graph { flow: south; }
( Presentation:
  [UI Components]
)
( Business:
  [Services]
)
( Data:
  [Repository]
  [Database]
)
[UI Components] -> [Services]
[Services] -> [Repository]
[Repository] -> [Database]
graph { flow: south; }
( 表现层:
  [UI组件]
)
( 业务层:
  [服务]
)
( 数据层:
  [仓库]
  [数据库]
)
[UI组件] -> [服务]
[服务] -> [仓库]
[仓库] -> [数据库]

Part 3: Rendering

第三部分：渲染

Command (Platform-Aware)

命令（适配平台）

bash
undefined
bash
undefined

For GitHub markdown (RECOMMENDED) - renders as solid lines

GitHub Markdown推荐使用 - 渲染为实线

graph-easy --as=ascii << 'EOF' graph { flow: south; } [A] -> [B] -> [C] EOF
graph-easy --as=ascii << 'EOF' graph { flow: south; } [A] -> [B] -> [C] EOF

For terminal/local viewing - prettier Unicode lines

终端/本地查看使用 - 更美观的Unicode线条

graph-easy --as=boxart << 'EOF' graph { flow: south; } [A] -> [B] -> [C] EOF
undefined
graph-easy --as=boxart << 'EOF' graph { flow: south; } [A] -> [B] -> [C] EOF
undefined

Output Modes

输出模式

ModeCommandWhen to Use
ascii
--as=ascii
GitHub markdown - 
+--+
renders as solid lines everywhere
boxart
--as=boxart
Terminal only - 
┌──┐
looks nice locally, dotted on GitHub
Why ASCII for GitHub? GitHub's markdown preview renders Unicode box-drawing characters (
┌─┐│└─┘
) as dotted lines, breaking the visual appearance. Pure ASCII (
+---+
, 
|
) renders correctly as solid lines on all platforms.
模式命令使用场景
ascii
--as=ascii
GitHub Markdown - 
+--+
在所有平台渲染为实线
boxart
--as=boxart
仅终端使用 - 
┌──┐
在本地显示美观，但在GitHub上会显示为虚线
为什么GitHub要使用ASCII？ GitHub的Markdown预览会将Unicode框绘制字符（
┌─┐│└─┘
）渲染为虚线，破坏视觉效果。纯ASCII（
+---+
, 
|
）在所有平台都能正确渲染为实线。

Validation Workflow

验证流程

bash
undefined
bash
undefined

1. Write DSL to heredoc

1. 将DSL写入here文档

2. Render with ascii (for GitHub) or boxart (for terminal)

2. 使用ascii（GitHub）或boxart（终端）渲染

graph-easy --as=ascii << 'EOF' [Your] -> [Diagram] -> [Here] EOF
graph-easy --as=ascii << 'EOF' [你的] -> [图表] -> [内容] EOF

3. Review output

3. 查看输出

4. Iterate if needed

4. 如有需要进行迭代调整

5. Copy final output to markdown

5. 将最终输出复制到Markdown

6. Validate alignment (RECOMMENDED)

6. 验证对齐（推荐）

undefined
undefined

Post-Generation Alignment Validation (Recommended)

生成后对齐验证（推荐）

After embedding diagram in markdown, validate alignment to catch rendering issues.
Use the doc-tools plugin skill:
Skill: doc-tools:ascii-diagram-validator
Or invoke directly: 
Skill(doc-tools:ascii-diagram-validator)
with the target file path.
Why validate?
  • Catches copy-paste alignment drift
  • Detects font rendering issues
  • Ensures vertical columns align properly
  • Graph-easy output is machine-aligned, but manual edits can break it
When to skip: If diagram was just generated by graph-easy and not manually edited, validation is optional (output is inherently aligned).
将图表嵌入Markdown后，验证对齐情况以发现渲染问题。
使用doc-tools插件技能：
Skill: doc-tools:ascii-diagram-validator
或直接调用：
Skill(doc-tools:ascii-diagram-validator)
并传入目标文件路径。
为什么要验证？
  • 捕获复制粘贴导致的对齐偏移
  • 检测字体渲染问题
  • 确保垂直列正确对齐
  • Graph-easy输出是机器对齐的，但手动编辑可能会破坏对齐
何时可以跳过： 如果图表刚由graph-easy生成且未手动编辑，验证是可选的（输出本身已对齐）。

Part 4: Embedding in Markdown

第四部分：嵌入Markdown

Markdown Format (MANDATORY: Always Include Source)

Markdown格式（必填：必须包含源代码）

CRITICAL: Every rendered diagram MUST be followed by a collapsible 
<details>
block containing the graph-easy source code. This is non-negotiable for:
  • Reproducibility: Future maintainers can regenerate the diagram
  • Editability: Source can be modified and re-rendered
  • Auditability: Changes to diagrams are trackable in git diffs
markdown
undefined
关键要求： 每个渲染后的图表必须紧跟一个可折叠的
<details>
块，包含graph-easy源代码。这是不可协商的，因为：
  • 可重现性：未来维护者可以重新生成图表
  • 可编辑性：源代码可修改并重新渲染
  • 可审计性：图表的变更可在git diff中追踪
markdown
undefined

Architecture

架构

+----------+     +----------+     +----------+
|  Input   | --> | Process  | --> |  Output  |
+----------+     +----------+     +----------+
<details> <summary>graph-easy source</summary> 
graph { flow: east; }
[Input] -> [Process] -> [Output]
</details> ````
The 
<details>
block is MANDATORY - never embed a diagram without its source.
+----------+     +----------+     +----------+
|  输入   | --> |  处理  | --> |  输出  |
+----------+     +----------+     +----------+
<details> <summary>graph-easy源代码</summary> 
graph { flow: east; }
[Input] -> [Process] -> [Output]
</details> ```` 
<details>
块是必填项 - 永远不要嵌入没有可重现源代码的图表。

GFM Collapsible Section Syntax

GFM可折叠区域语法

GitHub Flavored Markdown supports HTML 
<details>
and 
<summary>
tags for collapsible sections. Key syntax rules:
Structure:
html
<details>
  <summary>Click to expand</summary>

  <!-- BLANK LINE REQUIRED HERE -->
  Content goes here (Markdown supported)
  <!-- BLANK LINE REQUIRED HERE -->
</details>
Critical rules:
  1. Blank lines required - Must have empty line after 
    <summary>
    and before 
    </details>
    for Markdown to render
  2. No indentation - 
    <details>
    and 
    <summary>
    must be at column 0 (no leading spaces)
  3. Summary is clickable label - Text in 
    <summary>
    appears as the collapsed header
  4. Markdown inside works - Code blocks, headers, lists all render correctly inside
Optional: Default expanded:
html
<details open>
  <summary>Expanded by default</summary>

  Content visible on page load
</details>
Common mistake (Markdown won't render):
html
<details>
  <summary>Broken</summary>
  No blank line - this won't render as Markdown!
</details>
References:
GitHub Flavored Markdown支持HTML 
<details>
和
<summary>
标签来创建可折叠区域。关键语法规则：
结构：
html
<details>
  <summary>点击展开</summary>

  <!-- 此处必须留空行 -->
  内容写在这里（支持Markdown）
  <!-- 此处必须留空行 -->
</details>
关键规则：
  1. 必须留空行 - 
    <summary>
    后和
    </details>
    前必须有空白行，Markdown才能正确渲染
  2. 不要缩进 - 
    <details>
    和
    <summary>
    必须在第0列（无前置空格）
  3. 摘要为可点击标签 - 
    <summary>
    中的文本显示为折叠状态的标题
  4. 内部支持Markdown - 代码块、标题、列表等都能在内部正确渲染
可选：默认展开
html
<details open>
  <summary>默认展开</summary>

  页面加载时内容可见
</details>
常见错误（Markdown无法渲染）：
html
<details>
  <summary>错误示例</summary>
  没有留空行 - 这部分无法渲染为Markdown！
</details>
参考：

Regeneration

重新生成

If the markdown changes, regenerate by running the source through graph-easy again:
bash
undefined
如果Markdown内容变更，可将源代码再次通过graph-easy重新生成：
bash
undefined

Extract source from <details> block, pipe through graph-easy

从<details>块中提取源代码，通过管道传给graph-easy

graph-easy --as=boxart << 'EOF'
graph-easy --as=boxart << 'EOF'

paste source here

粘贴源代码到这里

EOF

---
EOF

---

Reference: Monospace-Safe Symbols

参考：等宽安全符号

Avoid emojis - they have variable width and break box alignment on GitHub.
避免使用表情符号 - 它们宽度可变，会在GitHub上破坏框对齐。

Status Markers

状态标记

MeaningMarker
Added/New
[+]
Removed/Deleted
[x]
Changed/Updated
[*]
Warning/Deprecated
[!]
Deferred/Pending
[~]
Current/Active
[>]
Optional
[?]
Locked/Fixed
[=]
含义标记
新增
[+]
删除
[x]
变更
[*]
警告/已弃用
[!]
推迟/待处理
[~]
当前/活跃
[>]
可选
[?]
锁定/固定
[=]

Box Drawing (U+2500-257F)

框绘制字符（U+2500-257F）

- | + + + + + + + + +   (light)
= | + + + + + + + + +   (double)
- | + + + + + + + + +   (细线条)
= | + + + + + + + + +   (双线条)

Arrows & Pointers

箭头与指针

-> <- up down            (arrows)
v ^                      (logic - graph-easy uses these)
< > ^ v                  (ASCII arrows)
-> <- up down            (箭头)
v ^                      (逻辑符号 - graph-easy使用这些)
< > ^ v                  (ASCII箭头)

Shapes & Bullets

形状与项目符号

* o O                    (bullets)
[ ] #                    (squares)
< > <>                   (diamonds)
* o O                    (项目符号)
[ ] #                    (方块)
< > <>                   (菱形)

Graph Label (MANDATORY: EVERY diagram MUST have emoji + title)

图表标签（必填：每个图表必须包含表情符号+标题）

WARNING: This is the most commonly forgotten requirement. Diagrams without labels are invalid.
警告： 这是最常被忽略的要求。没有标签的图表是无效的。

Correct Example

正确示例

graph { label: "🚀 Deployment Pipeline"; flow: east; }
[Build] -> [Test] -> [Deploy]
graph { label: "🚀 部署流水线"; flow: east; }
[构建] -> [测试] -> [部署]

Anti-Pattern (INVALID - DO NOT DO THIS)

反模式（无效 - 禁止操作）

graph { flow: east; }
[Build] -> [Test] -> [Deploy]
Why this is wrong: Missing 
label:
with emoji. Every diagram needs context at a glance.
graph { flow: east; }
[构建] -> [测试] -> [部署]
错误原因： 缺少带表情符号的
label:
。每个图表都需要一眼就能看懂的上下文。

Mandatory Checklist (Before Rendering)

渲染前必填检查清单

Graph-Level (MUST have)

图表层级（必须包含）

  • graph { label: "🚀 Title"; }
     - semantic emoji + title (MOST FORGOTTEN - check first!)
  • graph { flow: south; }
    or 
    graph { flow: east; }
    - explicit direction
  • Command uses 
    --as=ascii
    for GitHub markdown (or 
    --as=boxart
    for terminal only)
  • graph { label: "🚀 标题"; }
     - 语义表情符号+标题（最常被忽略 - 首先检查！）
  • graph { flow: south; }
    或 
    graph { flow: east; }
    - 明确指定流向
  • 命令使用
    --as=ascii
    用于GitHub Markdown（或
    --as=boxart
    仅用于终端）

Embedding (MUST have - non-negotiable)

嵌入要求（必须包含 - 不可协商）

  • <details>
    block with source     - EVERY diagram MUST have collapsible source code block
  • Format: rendered diagram in code block, followed immediately by 
    <details><summary>graph-easy source</summary>
    with source in code block
  • Never commit a diagram without its reproducible source
  • 包含源代码的
    <details>
    块     - 每个图表必须紧跟包含graph-easy DSL源代码的可折叠块
  • 格式：渲染后的图表在代码块中，紧随其后是
    <details><summary>graph-easy源代码</summary>
    及代码块中的源代码
  • 永远不要提交没有可重现源代码的图表

Post-Embedding Validation (Recommended)

嵌入后验证（推荐）

  • Run 
    ascii-diagram-validator
    on the file after embedding diagram
  • Especially important if diagram was manually edited after generation
  • Catches alignment drift from copy-paste or font rendering issues
  • 在嵌入图表后对文件运行
    ascii-diagram-validator
  • 如果图表生成后经过手动编辑，这一点尤为重要
  • 捕获复制粘贴或字体渲染导致的对齐偏移

Node Styling (Visual hierarchy)

节点样式（视觉层级）

  • Start/end nodes: 
    { shape: rounded; }
    - entry/exit points
  • Critical/important nodes: 
    { border: double; }
    or 
    { border: bold; }
  • Optional/skippable nodes: 
    { border: dotted; }
  • Default nodes: no styling (standard border)
  • Long labels use 
    \n
    for multiline - max ~15 chars per line
  • 开始/结束节点：
    { shape: rounded; }
    - 入口/出口点
  • 关键/重要节点：
    { border: double; }
    或 
    { border: bold; }
  • 可选/可跳过节点：
    { border: dotted; }
  • 默认节点：无样式（标准边框）
  • 长标签使用
    \n
    换行 - 每行最多约15个字符

Edge Styling (Semantic meaning)

边样式（语义含义）

  • Main/happy path: 
    ->
    solid arrow
  • Conditional/alternate: 
    ..>
    dotted arrow
  • Emphasized/critical: 
    ==>
    bold arrow
  • Edge labels are SHORT (1-3 words): 
    -- YES -->
    , 
    -- error -->
  • 主路径/正常流程：
    ->
    实线箭头
  • 条件/备选路径：
    ..>
    虚线箭头
  • 强调/关键路径：
    ==>
    粗箭头
  • 边标签要简短（1-3个词）：
    -- 是 -->
    , 
    -- 错误 -->

Character Safety (Alignment)

字符安全（对齐）

  • NO graphical emojis inside nodes (break alignment)
  • Unicode symbols OK inside nodes (single-width)
  • ASCII markers ALWAYS safe ([x] [+] [!] [OK])
  • Graphical emojis ONLY in 
    graph { label: "..."; }
    title
  • 节点内部禁止使用图形表情符号（破坏对齐）
  • 节点内部可使用Unicode符号（单宽度）
  • ASCII标记始终安全（[x] [+] [!] [OK]）
  • 图形表情符号仅可用于
    graph { label: "..."; }
    标题中

Structure (Organization)

结构（组织性）

  • Groups 
    ( Name: ... )
    used for logical clustering when 4+ related nodes
  • Node IDs short, labels descriptive: 
    [db] { label: "PostgreSQL"; }
  • No more than 7-10 nodes per diagram (split if larger)
  • 当有4个及以上相关节点时，使用
    ( 名称: ... )
    分组进行逻辑聚类
  • 节点ID简短，标签描述性强：
    [db] { label: "PostgreSQL"; }
  • 每个图表最多包含7-10个节点（如果节点过多，拆分图表）

Success Criteria

成功标准

Correctness

正确性

  1. Parses without error - graph-easy accepts the DSL
  2. Renders cleanly - no misaligned boxes or broken lines
  3. Matches content - all key elements from description represented
  4. Source preserved (MANDATORY) - EVERY diagram MUST have 
    <details>
    block with graph-easy DSL source immediately after the rendered output
  1. 无错误解析 - graph-easy可接受该DSL
  2. 渲染清晰 - 无错位的框或断裂的线条
  3. 内容匹配 - 描述中的所有关键元素都已呈现
  4. 源代码已保留（必填） - 每个图表必须在渲染输出后紧跟包含graph-easy DSL源代码的
    <details>
    块

Aesthetics

美观性

  1. Platform-appropriate output - 
    --as=ascii
    for GitHub (solid lines), 
    --as=boxart
    for terminal only
  2. Readable labels - multiline with 
    \n
    , no truncation
  3. Clear flow - direction matches natural reading (top-down or left-right)
  4. Consistent styling - same border style = same semantic meaning throughout
  1. 适配平台的输出 - GitHub使用
    --as=ascii
    （实线），仅终端使用
    --as=boxart
  2. 标签可读 - 使用
    \n
    换行，无截断
  3. 流向清晰 - 流向符合自然阅读习惯（从上到下或从左到右）
  4. 样式一致 - 相同边框样式在整个图表中代表相同语义

Comprehensiveness

完整性

  1. Edge semantics - solid=normal, dotted=conditional, bold=critical
  2. Logical grouping - related nodes in 
    ( Group: ... )
    containers
  1. 边语义明确 - 实线=正常，虚线=条件，粗线=关键
  2. 逻辑分组 - 相关节点放在
    ( 分组: ... )
    容器中

Troubleshooting

故障排除

IssueCauseSolution
command not found
graph-easy not installedRun preflight check
Dotted lines on GHUsed 
--as=boxart
Use 
--as=ascii
for GitHub markdown
Box border brokenGraphical emoji in nodeRemove emojis, use ASCII markers [x][+]
Nodes overlapToo complexSplit into multiple diagrams (max 7-10 nodes)
Edge labels cut offLabel too longShorten to 1-3 words
No title showingWrong syntaxUse 
graph { label: "Title"; flow: south; }
Weird layoutNo flow directionAdd 
graph { flow: south; }
or 
flow: east
Parse errorSpecial chars in nodeEscape or simplify node names
问题原因解决方案
command not found
未安装graph-easy运行预检查脚本
GitHub上显示虚线使用了
--as=boxart
GitHub Markdown使用
--as=ascii
框边框断裂节点内使用了图形表情符号删除表情符号，改用ASCII标记[x][+]
节点重叠图表过于复杂拆分为多个图表（最多7-10个节点）
边标签被截断标签过长缩短为1-3个词
无标题显示语法错误使用
graph { label: "标题"; flow: south; }
布局异常未指定流向添加
graph { flow: south; }
或
flow: east
解析错误节点名称包含特殊字符转义或简化节点名称

Resources

资源