# Arch Diagram

> 使用 PlantUML 绘制清晰美观的架构图，支持分层架构、流程图、C4容器图、新旧对比图。 优先使用 PlantUML package 风格，适配飞书文档画板渲染。 触发词：画架构图、架构图、architecture diagram、画分层图、画流程图、 系统架构、技术架构图、画图、绘制架构。 输出：PlantUML 代码块（可直接嵌入飞书文档或 Markdown）。

- Skill: `josephcooperhc/arch-diagram` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add josephcooperhc/arch-diagram`
- Raw SKILL.md: https://api.skillmd.com/api/skills/josephcooperhc/arch-diagram/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: JosephCooperHC (https://skillmd.com/u/josephcooperhc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/josephcooperhc/arch-diagram

---


# 架构图绘制

使用 PlantUML `package` 风格绘制分层清晰、配色统一的架构图。

## 绘图规则

1. **必须用 PlantUML**，不用 Mermaid（飞书渲染 PlantUML 更稳定）
2. **必须加骨架头**：
   ```
   skinparam backgroundColor white
   skinparam shadowing false
   skinparam defaultFontSize 12
   skinparam rectangle { roundCorner 10 }
   ```
3. **分组用 `package`**，单模块用 `rectangle`，数据库用 `database`，队列用 `queue`
4. **实线 `-->` 表调用**，**虚线 `..>` 表可选/反馈**
5. **每层一个颜色**，统一配色方案：

| 层级 | 色值 | 用途 |
|------|------|------|
| 顶层/用户 | `#E3F2FD` | 浅蓝 |
| 核心/业务 | `#E8F5E9` | 浅绿 |
| 服务/中间 | `#FFF3E0` | 浅橙 |
| 数据/底层 | `#FCE4EC` | 浅粉 |
| 外部/中性 | `#F5F5F5` | 浅灰 |

## 图型选择

| 场景 | 图型 | 关键语法 |
|------|------|---------|
| 系统分层架构 | 分层图 | `package` 嵌套 `rectangle` |
| 请求处理/工作流 | 流程图 | `rectangle` 链式 `-->` |
| 微服务/系统边界 | C4容器图 | `package` + `database` + `queue` |
| 方案对比 | 双栏图 | 两个 `package` + `..>` 演进线 |

## 输出目标适配

- **飞书文档**：用 ` ```plantuml ``` ` 代码块，飞书自动渲染为画板
- **Markdown/终端**：输出代码块，用户自行渲染
- **create-doc/update-doc**：直接嵌入 markdown 参数中

## 模板库

详细模板和完整示例见 [templates.md](references/templates.md)，按需 Read 对应模板复制修改。

## 避坑指南（血泪实战经验）

### 语法类
- `skinparam` 中不要用分号连接多属性（如 `#E3F2FD;line:#42A5F5`），会语法错误
- 每个元素必须有唯一 `as` 别名
- `package` 内 `rectangle` 的颜色写在别名后：`as X #E3F2FD`
- package 标题中不要用括号 `()`，用中文或空格代替

### 布局类（最容易翻车）
- **禁止 package 嵌套超过 2 层**：嵌套 package 在飞书渲染大概率空白或排版混乱
- **禁止回路箭头**（如 `AR --> PSE` 指回上层）：会把上层元素拉到底部，整个图翻转
- **禁止 `together {}`**：飞书渲染不稳定
- **禁止 `-[hidden]->`**：飞书中无效
- **箭头只向下**：所有 `-->` 必须从上层指向下层，不要向上或横向跨层
- **每层连线数控制在 8 条以内**：超过 8 条箭头从同一节点出发，布局会歪

### 结构类
- **扁平优先**：能用 1 层 package 解决的不要嵌套 2 层
- **一个 package 内元素不超过 7 个**：超过则拆成多个 package
- **A2A 协议层用单个 rectangle 而非拆成 3 个子模块**：拆开后 PlantUML 会把它们竖排，占据过多空间
- **连线顺序决定布局**：PlantUML 按代码中连线出现的顺序排布，先写的连线对应的元素排在左边