图表即代码
指导 Agent 用声明式语法维护架构图、序列图与部署拓扑，使图表与代码一同走 PR 与历史追溯。
本页为 Agent 提供图表即代码的完整实践：Mermaid 5 种图类型示例、Markdown 嵌入与 CI 渲染配置、PlantUML vs Mermaid 的选择标准，以及版本控制友好的图表更新工作流。
在 SKILL 中约定首选 DSL（如 Mermaid 流程图/时序图、C4-PlantUML）及存放路径（docs/diagrams/）；大型图拆分为子图或分层（C4 上下文→容器→组件）；图表走 PR diff，不提交生成的二进制 PNG。
- 语法校验：CI 调用
mmdc --input file.mmd，失败时输出错误行号。 - 版本锁定：
package.json中锁定@mermaid-js/mermaid-cli版本。 - 与 README/ADR 交叉引用：图源文件路径与嵌入方式写清楚。
Mermaid 5 种图类型示例
适合放在 Markdown/GitHub/GitLab 预览中的轻量图。SKILL 规定 ```mermaid 围栏内节点 ID 使用英文，禁止外链图片。
1. flowchart（流程图）
```mermaid
flowchart TD
A([用户请求]) --> B{认证?}
B -- 通过 --> C[业务处理]
B -- 失败 --> D([返回 401])
C --> E[(数据库)]
E --> F([返回响应])
```2. sequenceDiagram（时序图）
```mermaid
sequenceDiagram
actor User
participant API
participant Auth
participant DB
User->>API: POST /login {email, password}
API->>Auth: verifyCredentials()
Auth->>DB: SELECT user WHERE email=?
DB-->>Auth: User row
Auth-->>API: JWT token
API-->>User: 200 {token}
```3. classDiagram（类图）
```mermaid
classDiagram
class Order {
+String id
+OrderStatus status
+List~Item~ items
+calculateTotal() float
}
class Item {
+String sku
+int quantity
+float price
}
class OrderStatus {
<<enumeration>>
PENDING
PAID
SHIPPED
}
Order "1" --> "*" Item : contains
Order --> OrderStatus : has
```4. gitGraph（Git 分支图）
```mermaid
gitGraph
commit id: "init"
branch feature/login
checkout feature/login
commit id: "add login form"
commit id: "add auth service"
checkout main
merge feature/login id: "merge login"
branch hotfix/token
checkout hotfix/token
commit id: "fix token expiry"
checkout main
merge hotfix/token id: "hotfix merged"
```5. erDiagram（实体关系图）
```mermaid
erDiagram
USER {
uuid id PK
string email UK
string name
timestamp created_at
}
ORDER {
uuid id PK
uuid user_id FK
decimal total
string status
}
ORDER_ITEM {
uuid id PK
uuid order_id FK
string sku
int quantity
decimal price
}
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
```下方为页内实时渲染示例（仅本页加载 Mermaid；站点其余页面不依赖该脚本）。
PlantUML vs Mermaid 选择标准
适合 C4、复杂时序与部署图；通常经 Jar、Docker 或 Kroki 渲染。SKILL 写明是否允许 !include 与远程主题文件路径。
Mermaid 优先场景 PlantUML 优先场景 ───────────────── ──────────────────────── GitHub/GitLab 原生渲染 C4 架构图（C4-PlantUML 库） Markdown 内嵌（README/ADR） 复杂部署/网络拓扑图 简单流程图/时序图/类图 需要 !include 复用片段 前端团队维护 需要精细样式与主题控制 快速迭代，diff 优先 架构委员会评审，精确度优先 无服务器依赖 已有 Kroki/PlantUML 服务
@startuml C4-Container
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
Person(user, "用户", "使用 Web 浏览器")
System_Boundary(sys, "电商系统") {
Container(web, "Web 应用", "React", "提供购物界面")
Container(api, "API 服务", "Node.js/Express", "处理业务逻辑")
ContainerDb(db, "数据库", "PostgreSQL", "存储订单与用户数据")
}
Rel(user, web, "使用", "HTTPS")
Rel(web, api, "调用", "REST/JSON")
Rel(api, db, "读写", "SQL")
@enduml
Mermaid CI 渲染配置（GitHub Actions）：
# .github/workflows/diagrams.yml
name: Render Diagrams
on:
pull_request:
paths: ['docs/diagrams/**/*.mmd', 'docs/**/*.md']
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm i -g @mermaid-js/mermaid-cli@10
- name: Validate all .mmd files
run: |
find docs/diagrams -name '*.mmd' | while read f; do
mmdc --input "$f" --output /tmp/out.svg || exit 1
donePR 与渲染流程
从改图到合入的常见路径；Agent 步骤里可对应「改源 → 本地校验 → 提交 → CI」。
[ 编辑 .mmd / PlantUML / DOT ]
│
▼
[ 本地：mmdc / plantuml / dot ]
│
┌────────┴────────┐
▼ ▼
[ 语法通过 ] [ 报错：定位行号 ]
│ │
│ └──► [ 修源再跑 ]
▼
[ git diff 可读 ]
│
▼
[ 开 PR：附图或链接 docs/diagrams/ ]
│
▼
[ CI 同版本渲染器 / 可选产出 SVG ]
│
├────► [ 通过 → merge ]
└────► [ 失败 → 不提交二进制，只修文本 ]
页内工具：围栏 DSL 扫描
以下脚本仅在本页运行：粘贴 README 或设计文档草稿，列出闭合围栏中出现的 mermaid、plantuml/puml、dot/graphviz 块及起止行号，便于核对 SKILL 与 CI 是否覆盖。
SKILL 大纲
可直接复制为技能正文骨架，再替换为仓库真实路径与渲染命令。
---
name: diagram-as-code
description: 用 Mermaid/PlantUML 等维护可版本化的架构与流程图
---
# 规则
- 图表源文件存放在 docs/diagrams/，按类型子目录（flow/sequence/c4）
- Mermaid 优先用于 README/ADR 内嵌；C4/复杂部署图用 PlantUML
- 节点 ID 用英文；禁止外链图片；不提交生成的 PNG/SVG 二进制
- PR 必须同时改图表源文件，CI 验证语法（mmdc --input 或 plantuml -syntax）
- 版本锁定：package.json devDependencies 中注明 mermaid-cli 版本
# 步骤
1. 确认 SKILL 中的 DSL 选择（Mermaid vs PlantUML）与目录约定
2. 按场景选图类型：
- 流程图 → flowchart TD/LR
- API 交互 → sequenceDiagram
- 数据模型 → erDiagram / classDiagram
- Git 分支 → gitGraph
- 架构分层 → C4-PlantUML（Context/Container/Component）
3. 大型图拆子图（subgraph）或分层文件，保持单文件可 diff
4. 本地验证：mmdc --input diagram.mmd --output /tmp/out.svg
5. CI 配置：在 PR checks 中加 validate-diagrams job
6. README 中用相对路径嵌入：