arch-diagram-pro — 架构图专业绘制 Skill
概述
本 skill 具备三大核心能力：智能意图挖掘（从自然语言中提取展示意图与风格决策）、多模式渲染（HTML 模板 / 内联 SVG / Mermaid 三选一）、工程化规范（能力边界、渲染自检、异常处理）。零外部依赖，离线可用。
触发关键词：架构图、流程图、系统架构、模块图、画个图、时序图、状态机、ER图、拓扑图、数据流图、draw、diagram、architecture、flowchart。
一、三条不变式（核心心智模型）
所有规则都是以下三条不变式的推论。理解它们即可正确应对任何场景。
不变式 1：解引用一切（Dereference Everything）
Agent 看不见用户脑中的背景知识。绘图前必须把所有"引用"解引用为自包含的语义文本：
| 悬空引用 | 解引用动作 |
|---|---|
| 文件路径（"请参考 /path/to/x"） | 必须先读取文件，将核心逻辑拍平为纯文本 |
| 专有名词/缩写 | 补全最小信息集：角色（对象类型与责任）、层级（所属模块）、动作（关键行为）、上下游关系 |
| 旧图上下文（"基于上一张图修改"） | 读取已保存的 HTML/SVG 文件作为基线，不要求用户重复描述 |
- 未释义的术语不得直接作为节点标签（禁止"仅列词成框"）
- 若输入仅包含术语清单，先补全最小信息集再进入结构决策
不变式 2：论证而非展示
- 图结构必须服务于语义论证：概念层级、因果关系、依赖链路是结构主线
- 每条关系必须可复述为明确语句（如"A 依赖 B""C 触发 D"），禁止用"元素靠得近"替代关系定义
- 同构校验：移除文字标签后，结构本身仍应能传达核心逻辑
不变式 3：一图一主题（先定层级，再定粒度）
- 宏观图展示全局骨架，中观图展示子系统交互，微观图展示执行细节
- 单图装不下时必须拆分（决策见 references/intent-mining-guide.md §3）
- 输出前自检：关键模块是否标注了职责？连线关系是否明确？
二、三模式输出策略
根据图表类型和用途，选择最合适的渲染模式：
模式 A：HTML 模板（推荐用于架构图）
适用场景：系统架构图、微服务架构图、分层架构图——需要精美视觉效果的展示型图表。
操作步骤：
1. 理解架构：模块、层级、数据流向、用户角色
2. 参考 references/html-template-guide.md 的组件清单与扩展规则
3. 基于 assets/architecture-template.html 的 CSS 变量和组件类名生成 HTML
4. 将文件写入用户指定位置（默认当前目录），文件名建议 {project}-architecture.html
优势：视觉精美度有保证（暖色极简风格 + hover/fadeUp 动画 + 响应式），即开即用。
模式 B：内联 SVG（推荐用于流程/时序/状态机等）
适用场景：业务流程图、时序图、状态机、ER图、网络拓扑图——需要精确控制结构的图表。
操作步骤：
1. 先调用 read_me 加载 ["diagram"] 模块（含 HTML 交互控件时追加 "interactive"）
2. 参考 references/diagram-types.md 获取 SVG 骨架模板
3. 遵循 references/svg-standards.md 的渲染规范（marker、防压字、Token 优化、分层布局）
4. 调用 show_widget 传入原始 SVG 片段（viewBox 0 0 680 <h>，禁止 DOCTYPE/html 标签）
优势：精确可控，支持所有结构图类型，Token 效率高。
模式 C：Mermaid 代码块（用于文档嵌入）
适用场景：需要嵌入 Markdown 文档、或用户明确要求 Mermaid 语法时。
操作步骤：参考 references/diagram-types.md 末尾的 Mermaid 语法速查，直接输出代码块。
模式选择决策表
| 用户意图 | 推荐模式 | 参考文件 |
|---|---|---|
| 系统/微服务/分层架构图 | 模式 A HTML 模板 | html-template-guide.md |
| 业务流程 / 泳道图 | 模式 B SVG 或 模式 C Mermaid | diagram-types.md |
| 时序图 | 模式 B SVG 或 模式 C Mermaid | diagram-types.md |
| 状态机 | 模式 B SVG 或 模式 C Mermaid | diagram-types.md |
| ER 图 | 模式 C Mermaid（推荐）或 模式 B SVG | diagram-types.md |
| 网络拓扑图 | 模式 B SVG | diagram-types.md |
| 嵌入 Markdown 文档 | 模式 C Mermaid | diagram-types.md |
| 不在支持范围（饼/柱/思维导/3D/地图） | 先主动告知不支持 + 原因 + 替代方案 | capability-and-exceptions.md |
三、意图挖掘：从自然语言中提取展示意图
用户的展示要求往往藏在自然语言里。你的职责是挖掘并翻译为语义级展示意图。
3.1 挖掘信号清单
- 信息层级信号："了解个大概/整体框架"→ 侧重宏观骨架；"具体怎么做/详细逻辑"→ 侧重微观流转
- 焦点信号："重点是订单链路""突出异步部分"→ 决定哪些内容进主图、哪些淡化
- 复杂度信号：用户一次性给了海量素材 → 主动按一图一主题拆分
3.2 呈现逻辑与构图范式（正交解耦）
两个正交概念决定图表的骨架结构与视觉排版：
呈现逻辑（决定骨架结构）：
- 拓扑：描述组件/系统间的静态关系（如架构图）
- 逻辑：描述步骤/分支/因果的动态过程（如流程图）
- 混合：以流程为骨架，组件为落点
- 思维导图：树形结构，根节点逐层展开
构图范式（决定视觉排版）：
- 包容式：浅色底板分区包裹，强调模块化与边界
- 流转式：以流向和链路为叙事主线，强调数据/控制流
- 陈述式：强调文本排版与留白，适用于文本密集型场景
组合示例：
- 包容式 + 拓扑 = 经典系统分层架构图 → 模式 A
- 流转式 + 逻辑 = 业务流程图 → 模式 B
- 包容式 + 逻辑 = 跨域复杂业务流 → 模式 B
- 陈述式 + 拓扑 = 科研方法论框架图 → 模式 B
3.3 风格决策前置（意图澄清交互）
意图不明确时必须先向用户澄清，不要猜测。最多四个核心问题：
- 图表类型：你要画的是架构图、流程图、时序图、还是其他？（参考模式选择决策表）
- 输出形态：精美 HTML 文件 / 对话内联图 / Mermaid 代码块？
- 配色倾向：科技蓝 / 暖色 / 深色 / 自定义主色？
- 重点强调：是否有需要高亮或突出的模块/链路？
豁免条件：用户请求已明确图类型、输出形态与配色时（如"画一张蓝白配色的分层架构图，输出 HTML 文件"）跳过提问。用户回答"随便/你决定"时，agent 自主选择最匹配的组合并在回复中说明选择依据。
3.4 复杂图多视图拆分
当架构过于复杂，单图无法承载时：
| 用户意图 | 拆分机制 | 操作方式 |
|---|---|---|
| 架构庞大，需拆为多个独立视图 | 多文件拆分 | 每个子模块/层级生成独立 HTML/SVG 文件 |
| 同一架构上高亮不同链路 | 多图聚焦 | 生成多张图，每张高亮一条链路、淡化其余 |
拆分确认门：判定需要拆分时，必须先向用户输出拆分推荐方案（视图名称/聚焦点/抽象层级/拆分理由）并阻塞等待确认，用户未确认前禁止动手。豁免：用户已显式指定拆分方式时跳过。
详细指南见 references/intent-mining-guide.md。
四、快速开始（Happy Path）
模式 A 快速流程（HTML 架构图）
- 解析需求：识别模块、层级、数据流向、用户角色（不变式 1）
- 意图挖掘：确定呈现逻辑与构图范式，意图不明确时先澄清（§3.3）
- 规划结构：分几层、每层几个卡片、箭头方向、分组标签
- 生成 HTML：基于
assets/architecture-template.html的 CSS 变量和组件类名填充内容 - 写入文件：保存为
{project}-architecture.html，用present_files展示给用户
模式 B 快速流程（内联 SVG）
- 解析需求：同上
- 意图挖掘：同上
- 加载模块：调用
read_me(["diagram"]) - 绘制 SVG：参考
references/diagram-types.md骨架 +references/svg-standards.md规范 - 渲染前自检：逐条核对自检清单（§六）
- 展示：调用
show_widget传入 SVG
五、二次修改与迭代
文件迭代法（替代云端 session）
本 skill 采用文件迭代法实现图表的持续修改：
- 首次生成：将图表保存为文件（HTML 或 SVG），告知用户文件路径
- 修改请求：用户说"基于上一张图修改 X"时，读取已保存的文件作为基线
- 增量修改：在基线上修改对应部分，保留未变更内容
- 覆盖保存：修改后覆盖原文件（或另存为新版本），再次用
present_files展示
修改类型速查
| 修改类型 | 操作 |
|---|---|
| 新增模块/节点 | 在对应层级/位置插入新卡片/节点 |
| 删除模块/节点 | 移除对应元素及其连线 |
| 调整关系 | 修改连线方向/标签 |
| 更换配色 | 修改 CSS 变量（模式 A）或 stroke/fill 值（模式 B） |
| 拆分多视图 | 按拆分确认门流程执行 |
六、渲染前自检清单
模式 A（HTML 模板）自检
- [ ] HTML 文件自包含，无外部依赖（仅允许 Google Fonts CDN）
- [ ] CSS 变量使用正确（
--accent-*、--surface-*、--text-*） - [ ] 卡片 theme 类名正确（
card-web/card-api/card-db等） - [ ] 分组区块有
section-N类控制动画延迟 - [ ] 768px 以下响应式正常（
cards-row纵向排列） - [ ] 文件已写入磁盘并用
present_files展示
模式 B（内联 SVG）自检
- [ ] SVG 以
<svg>开头，viewBox 为0 0 680 <height> - [ ] 不含
<!DOCTYPE>、<html>、<head>、<body>标签 - [ ] 样式用
<style>类集中定义，形状用<defs>+<use>复用（Token 优化） - [ ] 箭头 marker 的
markerWidth/markerHeight >= viewBox 宽高，路径朝右（+x） - [ ] 箭头尖端 10px 禁区内无文字；文字与连线 >=6px 净空（必要时白底衬底）
- [ ] 节点间距 >=16px，文字与边框 >=8px
- [ ] 中文标签使用
font-family="sans-serif" - [ ] 单张图节点不超过 20 个，超出已计划拆分
七、能力边界与异常处理
能力边界速查
直接支持：系统/分层/微服务架构图、网络拓扑图、业务流程图/泳道图、数据流图、时序图、状态机图、ER图、类图、甘特图、通用关系图。
不直接支持（不要硬画，主动告知 + 给替代）：
- 饼图/柱状图/折线图等统计图表 → 建议改用 Chart.js（read_me chart 模块）
- 思维导图 → Mermaid mindmap 或拆成层级架构图
- 3D 图/地理地图 → 建议专用工具
- 直接导出 PNG/PDF → 说明可交付 HTML/SVG 源码让用户自行导出
- 反向工程（图→代码） → 仅支持"需求→图"方向
完整矩阵、前置澄清话术与出错标准话术见 references/capability-and-exceptions.md。
异常处理原则
- 能力边界先确认：动手前先对照支持矩阵，落在不支持的区间时第一句说明"不支持 + 原因 + 替代方案"并停下等确认
- 前置澄清：输出形态/图表类型/范围粒度任一不清时，用不超过 3 个选项提问确认
- 渲染前自检：发送前逐条核对自检清单，任一不过先改再发
- 出错主动交代：按"现象 → 原因 → 建议/修复"三段式回复，用户不需要自己排查
八、绘图原则
- 先理解，再绘制：完整理解用户意图后再动手，必要时确认组件和关系
- 边界前置、异常主动：绘制前确认类型在支持范围内；越界或出错时主动、明确告知
- 分层清晰：架构图按"前端 → 后端 → 数据层 → 基础设施"等层次布局，避免交叉
- 信息密度适中：单张图不超过 20 个节点；复杂系统拆成多张图
- 中文友好：节点标签支持中文，保证编码和字体兼容
- Token 意识：SVG 用 CSS 类 +
<defs>/<use>复用，减少重复内联样式 - 复杂图分多视图：一张图一个聚焦视角，多图配合文字解释形成完整叙述
九、反模式清单
| # | 反模式 | 正确做法 |
|---|---|---|
| 1 | 未读取文件就引用文件路径 | 先读取文件，拍平为纯文本 |
| 2 | 术语未释义直接作为节点标签 | 补全角色、层级、动作、上下游 |
| 3 | 用"元素靠得近"表达关系 | 显式连线 + 方向，可复述为"A 依赖 B" |
| 4 | 一张图塞入所有细节 | 按受众定层级，复杂时拆分多视图 |
| 5 | 请求了不支持的图表类型还硬画 | 主动告知不支持 + 原因 + 替代方案 |
| 6 | 格式/范围不清时直接开画 | 先前置澄清三问再画 |
| 7 | SVG 含 DOCTYPE/html 标签或 viewBox 非 680 | 只给裸 SVG 片段，viewBox 固定 680 |
| 8 | 逐元素内联 style 不抽 CSS 类 | 样式集中 <style>，形状用 <defs> 定义 |
| 9 | 箭头尖端 10px 内放文字 | 文字进节点/留白，必要时白底衬底 |
| 10 | 修改已有图时不读取原文件 | 读取已保存文件作为基线再修改 |
| 11 | 意图不明时直接落盘 | 先提问澄清图表类型、输出形态、配色 |
| 12 | 未经用户确认擅自拆分多视图 | 先输出拆分方案并阻塞等待确认 |
附：输出前最终自检
- [ ] 所有文件引用是否已拍平为文本？（不变式 1）
- [ ] 是否存在未释义的专有名词？（不变式 1）
- [ ] 每条关键关系是否可复述为明确语句？（不变式 2）
- [ ] 图的层级与粒度是否匹配信息焦点？是否该拆分？（不变式 3）
- [ ] 涉及多视图拆分时是否已获得用户确认？（§3.4 确认门）
- [ ] 选择的输出模式是否匹配图表类型？（§二 模式选择决策表）
- [ ] 是否完成了对应模式的渲染前自检？（§六）
- [ ] 涉及修改时是否读取了原文件作为基线？（§五）
