JosephCooperHC 架构图绘制
使用 PlantUML package 风格绘制分层清晰、配色统一的架构图。
绘图规则
- 必须用 PlantUML，不用 Mermaid（飞书渲染 PlantUML 更稳定）
- 必须加骨架头：
skinparam backgroundColor white skinparam shadowing false skinparam defaultFontSize 12 skinparam rectangle { roundCorner 10 } - 分组用
package，单模块用rectangle，数据库用database，队列用queue - 实线
-->表调用，虚线..>表可选/反馈 - 每层一个颜色，统一配色方案：
| 层级 | 色值 | 用途 |
|---|---|---|
| 顶层/用户 | #E3F2FD |
浅蓝 |
| 核心/业务 | #E8F5E9 |
浅绿 |
| 服务/中间 | #FFF3E0 |
浅橙 |
| 数据/底层 | #FCE4EC |
浅粉 |
| 外部/中性 | #F5F5F5 |
浅灰 |
图型选择
| 场景 | 图型 | 关键语法 |
|---|---|---|
| 系统分层架构 | 分层图 | package 嵌套 rectangle |
| 请求处理/工作流 | 流程图 | rectangle 链式 --> |
| 微服务/系统边界 | C4容器图 | package + database + queue |
| 方案对比 | 双栏图 | 两个 package + ..> 演进线 |
输出目标适配
- 飞书文档：用
```plantuml ```代码块，飞书自动渲染为画板 - Markdown/终端：输出代码块，用户自行渲染
- create-doc/update-doc：直接嵌入 markdown 参数中
模板库
详细模板和完整示例见 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 按代码中连线出现的顺序排布，先写的连线对应的元素排在左边