Architecture Diagram

Architecture Diagram Generator — 架构图生成器

> 基于 Cocoon AI 的 MIT 开源项目深度优化版。 > 核心改进：Quick Mode / Deep Mode 自适应分支 + 多轮结构化发现协议，轻量场景秒出图，复杂系统深度理解。

工作流程总览

用户请求
    │
    ▼
┌─────────────────────────────┐
│ Step 0: Mode Detection      │
│ 判断走 Quick 还是 Deep       │
└──────────┬──────────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
┌────────┐   ┌────────────────────┐
│ Quick   │   │ Deep               │
│ 0-1轮确认│   │ 5轮渐进发现         │
│ 直接生成 │   │ R1→R2→R3→R4→R5     │
└───┬────┘   └─────────┬──────────┘
    │                  │
    └──────┬───────────┘
           ▼
    Phase 1: Layout  →  Phase 2: Generate  →  Phase 3: Verify

---

Step 0: Mode Detection — 自动判断走 Quick 还是 Deep

> 核心原则：不是所有图都需要大费周章。根据用户请求的特征，自动选择最合适的路径。

判断标准

在收到用户请求后，先用以下规则判断模式：

| 信号 | → Quick Mode | → Deep Mode | |------|-------------|-------------| | 组件数量 | ≤ 5 个明确组件 | > 5 个，或数量不明 | | 描述完整度 | 用户说清楚了组件+关系 | 描述模糊（"我们有个微服务系统"） | | 场景类型 | 局部流程、单链路、概念草图 | 全栈系统、多子系统、企业架构 | | 用户意图 | "快速画一下" "示意一下" "简单画个" | "完整架构图" "梳理一下" "帮我理清" | | 领域知识 | 典型/通用架构（AI已有足够知识） | 用户自己的定制系统 |

Quick Mode 触发示例

> 以下类型请求 → 直接走 Quick Mode，不要追问：

| 用户说什么 | 为什么 Quick | |-----------|-------------| | "画一个 React + Node + PostgreSQL 的三层架构" | 经典三层，AI 完全理解 | | "画一下 OAuth 2.0 授权码流程" | 标准协议流程 | | "画出用户登录的时序图，从浏览器到数据库" | 单链路，组件明确 | | "给我一个典型的 AWS serverless 架构" | 通用参考架构 | | "CDN → ALB → ECS → RDS，画出来" | 用户已经列清楚了 | | "画个简单的微服务示意图，API Gateway + 3个服务 + Kafka" | 组件数量少且明确 | | "把这个数据流画一下：Kafka → Flink → ClickHouse → Grafana" | 线性管道，组件明确 | | "示意一下前端调用后端的认证流程" | 示意级别，不需要精确 |

Deep Mode 触发示例

> 以下类型请求 → 走 Deep Mode 5轮发现：

| 用户说什么 | 为什么 Deep | |-----------|------------| | "帮我梳理我们电商系统的完整架构" | 大型系统，需要理解业务 | | "画一下我们公司的技术架构图" | 需要大量追问才能搞清楚 | | "我想重构现有系统，先画个现状图" | 需要深入理解现有系统 | | "画一个包含安全边界的生产环境部署架构" | 多维度（部署+安全+网络） | | "我们用了 K8s + Istio + 20个微服务，画个图" | 组件多，需要组织 |

灰色地带处理

当不确定时：

1. 先用 1 轮轻量确认（类似 Quick Mode 的确认方式）
2. 如果用户回复暴露出更多复杂性，自动升级到 Deep Mode
3. 如果用户回复简洁明确，继续 Quick Mode 直接生成

一句话原则：用户说得越清楚，你问得越少；用户说得越模糊，你问得越多。

---

Quick Mode — 轻量快速出图

> 适用场景：组件 ≤ 5 个、用户描述清晰、典型通用架构、局部流程/单链路、概念草图。

Quick Mode 流程

用户请求 → [可选：1轮确认] → 直接生成 → 让用户看图迭代

什么时候跳过确认直接生成

直接生成（0 轮确认），当：

• 组件完全明确（用户列出了每个组件名和技术栈）
• 是标准/经典架构（三层架构、OAuth 流程、典型 AWS 架构等）
• 用户说了"简单画个""示意一下""quick"

1 轮确认，当：

• 组件明确但关系/方向不清晰
• 有 2-3 种合理的画法（比如数据流方向不确定）
• 用户给了组件但没给连接关系

Quick Mode 确认模板（1轮即可）

当需要确认时，用极简格式，不要抛出 5 轮问题：

## 🏗️ 确认一下（1 分钟）

**我理解的架构**：
  [组件A] ──HTTP──▶ [组件B] ──SQL──▶ [组件C]

**布局方向**: 左→右 / 上→下
**需要标注的协议/端口**: HTTP :443, PostgreSQL :5432

这样画可以吗？还是有什么要调整的？

确认后直接进入 Phase 2（跳过 Phase 1 的复杂布局规划，用默认布局）。

Quick Mode 默认布局规则

不经过 Phase 1 规划时，使用以下默认值：

| 参数 | 默认值 | |------|--------| | 布局方向 | 左→右（从左到右数据流） | | 画布 | viewBox="0 0 1000 680" | | 组件尺寸 | 标准 110×60px | | 水平间距 | 100px | | 垂直对齐 | 所有组件垂直居中（y 相同） | | Header | 从用户请求中提取关键词作为标题 | | 摘要卡片 | 全部省略（Quick Mode 不生成摘要卡片，保持简洁） |

---

Deep Mode — 多轮结构化提问

> 适用场景：组件 > 5 个、大型系统、描述模糊、需要梳理、多子系统、企业级架构。

> 关键原则：在生成任何 SVG 代码之前，必须通过多轮对话精确理解系统架构。 > 根据用户初始描述的详细程度，自动判断需要深入哪些轮次。 > 如果用户已经提供了非常详细的描述，可以跳过部分轮次并直接确认。

Round 1: 系统类型识别 & 范围界定

目标：确定架构的顶层模式和边界。

向用户提问（根据已有信息选择性提问，不要全部抛出）：

1. 系统类型：这是什么类型的系统？

• Web 应用（前后端分离 / SSR / SPA）
• 微服务系统（服务数量、服务间通信方式）
• 数据管道 / ETL（数据源→处理→存储链路）
• 云基础设施（AWS / Azure / GCP / 混合云）
• 移动端后端 (BFF + Microservices)
• Serverless 架构
• 事件驱动架构
• AI/ML 推理平台
• 其他：________

1. 规模感：系统的规模大约多大？

• 小型（3-7 个核心组件）
• 中型（8-15 个组件，多个子系统）
• 大型（15+ 组件，多层嵌套，多区域）

1. 目标受众：这张图给谁看？

• 技术团队内部（可以偏技术细节）
• 跨团队沟通（需要适度简化）
• 高管/客户（需要高度抽象）
• 文档/PPT（需要正式美观）

1. 侧重点：用户最关心哪个维度？

• 数据流（请求/响应路径）
• 部署拓扑（物理/虚拟节点）
• 安全边界（信任域、网络隔离）
• 高可用/容灾（多区域、故障转移）
• 全部展示

输出：1-2 句话的系统概要 + 架构模式标签。

---

Round 2: 组件清单盘点

目标：穷举所有组件，不遗漏。

根据 Round 1 的系统类型，引导用户分层列出组件：

📋 组件清单模板：

[客户端层]
  - 组件名 | 技术栈 | 关键信息（URL/端口/协议）

[接入层]
  - CDN / WAF / API Gateway / Load Balancer | 技术选型 | 配置要点

[应用层]
  - 每个服务/模块 | 语言/框架 | 端口/协议 | 扩缩容策略

[数据层]
  - 数据库类型 | 具体产品 | 用途 | 高可用方案
  - 缓存 | 消息队列 | 对象存储

[基础设施层]
  - 云平台/自建 | 区域 | 编排工具 | 监控告警

[外部依赖]
  - 第三方 API | 身份提供商 | 支付网关 | 邮件服务

交互策略：

• 如果用户描述模糊（如 "用了一个数据库"），追问具体产品（PostgreSQL? MongoDB?）
• 如果用户遗漏了常见配套组件（如说了 API 但没说 API Gateway），主动提醒
• 如果组件过多（>20），建议拆分多张图或用分组折叠

输出：完整的组件表格，每个组件标注：名称、类型、技术栈、备注。

---

Round 3: 关系与数据流映射

目标：精确理解组件间的连接关系。

对 Round 2 的每个组件，逐一确认：

1. 它调用谁？ → 出方向箭头
2. 谁调用它？ → 入方向箭头
3. 通信协议？ → HTTP/REST, gRPC, WebSocket, GraphQL, TCP, UDP, 消息队列
4. 认证方式？ → JWT, OAuth2, mTLS, API Key, 无
5. 数据方向？ → 单向读取 / 双向读写 / 异步推送
6. 是否有特殊流程？ → 启动流程、故障转移路径、定时任务链路

交互策略：

• 引导用户按 "请求进来 → 经过 → 到达 → 返回" 的路径描述
• 对微服务系统，额外确认服务发现、配置中心、分布式追踪的位置
• 对事件驱动系统，确认生产者→Topic→消费者的完整链路

输出：连接关系列表，每条标注：from → to | 协议 | 认证 | 备注。

---

Round 4: 基础设施与部署上下文

目标：理解运行环境的物理/虚拟拓扑。

仅在 Round 1 确认需要展示部署拓扑时深入：

1. 云平台：AWS / Azure / GCP / 阿里云 / 腾讯云 / 自建机房？
2. 区域部署：单区域？多区域？具体 region 名称？
3. 容器化：Kubernetes? Docker Compose? 无容器？
4. 网络拓扑：VPC / 子网划分？公网/私网暴露面？
5. CI/CD 链路：是否需要展示构建→测试→部署流程？
6. 监控告警：Prometheus + Grafana? Datadog? CloudWatch?

输出：基础设施上下文摘要。

---

Round 5: 安全边界确认

目标：明确信任域和隔离边界。

1. 安全组/防火墙规则：哪些端口对谁开放？
2. 网络隔离：公网子网 / 私有子网 / 数据库子网？
3. 认证流程：用户登录的完整路径（前端→Auth Provider→Token 签发→验证）
4. 敏感数据处理：PII 数据在哪里？加密方式？
5. 合规要求：SOC2 / HIPAA / PCI-DSS？

输出：安全边界列表 + 安全组标记位置。

---

Discovery 完成确认

在进入 Phase 1 之前，向用户输出一份 架构理解摘要：

## 🏗️ 架构理解确认

**系统类型**: [识别的模式]
**规模**: [小型/中型/大型]
**组件总数**: [N] 个

**组件清单**:
  [Frontend] React SPA → CloudFront CDN
  [Backend]  Node.js/Express API (:3000)
  [Database] PostgreSQL (RDS, Multi-AZ)
  ...

**关键数据流**:
  用户 → CloudFront → ALB → API → RDS
  认证流: 用户 → Cognito → JWT → API 验证
  ...

**部署**: AWS us-east-1, EKS 集群, 2个AZ

以上理解是否正确？确认后我开始画图。

只有在用户确认后，才进入 Phase 1。

---

Phase 1: Layout Planning — 布局规划（Deep Mode）

> 基于 Phase 0 的发现结果，在生成代码前先规划布局。 > Quick Mode 跳过此阶段，使用默认布局参数（左→右，组件垂直居中）。

1.1 布局模式选择

根据系统类型自动选择最佳布局：

| 系统类型 | 推荐布局 | 说明 | |---------|---------|------| | Web 应用（前后端） | 左→右 | 客户端在左，逐步向右到数据层 | | 微服务系统 | 左→右 + 分层 | 入口层→业务服务层→数据层 | | 数据管道/ETL | 左→右 | Source→Transform→Sink 线性流 | | 云基础设施 | 自由分组 | 按 VPC/子网/区域分组 | | 事件驱动 | 上→下 | Producer→Bus→Consumer 流 | | 安全架构 | 洋葱模型 | 外层→内层信任域递增 |

1.2 画布尺寸计算

画布宽度 = max(1000, 组件列数 × 180 + 边距 × 2)
画布高度 = max(680, 组件行数 × 100 + 边界框高度 + 图例高度 + 边距)

1.3 组件分组与 z-order 规划

• Region boundaries (最底层)
• Security groups (第二层)
• Connection arrows (第三层，在组件后面)
• Component boxes (第四层，半透明背景 + 不透明底层遮挡箭头)
• Labels & annotations (最顶层)

1.4 配色分配

按组件类型自动分配（参见 Design System 章节的颜色表）：

• Frontend → Cyan
• Backend → Emerald
• Database / AI/ML → Violet
• Cloud / AWS / Infrastructure → Amber
• Security / Auth → Rose
• Message Bus / Event → Orange
• External / Third-party → Slate

---

Phase 2: Code Generation — 代码生成

2.1 使用模板

从 resources/template.html 获取基础模板，然后：

1. 更新 `` 和 Header 文字
2. 调整 SVG viewBox 尺寸（根据 Phase 1 计算）
3. 按 Phase 1 布局逐一定位每个组件（参考 Design System 的 Component Box Pattern）
4. 绘制所有连接箭头（在组件之前，参见 z-order 规则）
5. 添加安全组虚线框、区域边界框
6. 填充 3 张摘要卡片（关键指标、技术栈、安全要点）
7. 添加图例（放在所有边界框之外）
8. 更新 Footer 元数据

2.2 关键约束

• 必须保留模板中的 2 个 CDN script（html2canvas + jsPDF，含 SRI hash）
• 必须保留 id="report-container" 在外层容器
• 必须保留 .toolbar 和相关 JS 导出函数
• 禁止引入新的外部依赖（除 Google Fonts 外）

---

Phase 3: Quality Verification — 质量验证

生成 HTML 后，逐项检查。Quick Mode 只需检查标有 ⚡ 的项目（核心项），Deep Mode 需全部检查。

自检清单

• [ ] ⚡ 间距：所有组件间垂直间距 ≥ 40px，水平间距 ≥ 30px
• [ ] ⚡ 无重叠：组件不重叠，箭头不穿过文字
• [ ] 图例位置：图例在所有边界框下方 ≥ 20px（Quick Mode 如无图例可跳过）
• [ ] ⚡ 箭头遮蔽：每个组件有 fill="#0f172a" 底层 rect 遮蔽穿透的箭头
• [ ] ⚡ 箭头方向：所有箭头终点指向正确方向
• [ ] ⚡ 完整性：用户提到的所有组件都在图中
• [ ] ⚡ 颜色一致：同类组件使用相同的配色方案
• [ ] ⚡ 文字可读：字号 ≥ 7px，标签不溢出组件边界
• [ ] ⚡ 导出功能：工具栏 HTML + JS 完整，html2canvas/jsPDF CDN 标签完整
• [ ] ⚡ 移动端：容器有 overflow-x: auto，小屏可横向滚动
• [ ] 摘要卡片：3 张卡片内容准确（Deep Mode only — Quick Mode 不生成摘要卡片）

修复优先级

1. 功能性问题（箭头指向错误、组件缺失）→ 立即修复
2. 视觉问题（重叠、溢出）→ 调整坐标
3. 增强性改进（更好的标注、更美观的布局）→ 可选修复

---

Design System

> 以下设计规范继承自上游 Cocoon AI v1.1，保持不变。

Color Palette

| Component Type | Fill (rgba) | Stroke | |---------------|-------------|--------| | Frontend | rgba(8, 51, 68, 0.4) | #22d3ee (cyan-400) | | Backend | rgba(6, 78, 59, 0.4) | #34d399 (emerald-400) | | Database | rgba(76, 29, 149, 0.4) | #a78bfa (violet-400) | | AWS/Cloud | rgba(120, 53, 15, 0.3) | #fbbf24 (amber-400) | | Security | rgba(136, 19, 55, 0.4) | #fb7185 (rose-400) | | Message Bus | rgba(251, 146, 60, 0.3) | #fb923c (orange-400) | | External/Generic | rgba(30, 41, 59, 0.5) | #94a3b8 (slate-400) |

Typography

• Font: JetBrains Mono (Google Fonts)
• Sizes: 12px (组件名), 9px (副标签), 8px (注释), 7px (微型标签)
• Weights: 400 (正文), 500 (强调), 600-700 (标题)

Visual Elements

• Background: #020617 (slate-950) + 40px 网格
• Component boxes: rx="6", 1.5px stroke, 半透明 fill
• Security groups: stroke-dasharray="4,4", 透明 fill, rose 色
• Region boundaries: stroke-dasharray="8,4", amber 色, rx="12"
• Arrows: SVG ` 箭头, #64748b` 颜色
• Auth flows: 虚线 stroke-dasharray="5,5", rose 色

Arrow Masking

箭头在 SVG 中先绘制，组件半透明 fill 会让箭头透出。解决方案：

Spacing Rules

• 标准组件高度: 60px (服务), 80-120px (大型组件)
• 垂直间距: ≥ 40px
• 消息总线: 放在间隙中间，不重叠相邻组件
• 图例: 在所有边界框下方 ≥ 20px

---

Iteration Protocol — 修改迭代协议

用户提出修改需求时，按以下优先级处理：

| 修改类型 | 示例 | 处理方式 | |---------|------|---------| | 增删组件 | "加一个 Redis 缓存" | 重新计算受影响区域的坐标 | | 修改连接 | "API 不直连 DB，走 DAO 层" | 调整箭头路径 | | 样式调整 | "把 Frontend 改成蓝色" | 修改颜色常量 | | 布局调整 | "数据库放到底部" | 局部重新布局 | | 标注修正 | "端口号不对，应该是 8080" | 修改文本内容 |

重要: 修改后必须重新执行 Phase 3 的间距和重叠检查。

---

安装方式

Claude Code CLI（本项目）

cp -r architecture-diagram/ ~/.claude/skills/architecture-diagram/

Claude.ai

下载 architecture-diagram.zip 并通过 Skills 面板上传。

---

触发示例

Quick Mode（快速出图）：

• "画一个 React + Node.js + PostgreSQL 的三层架构"
• "画一下 OAuth 2.0 授权码流程"
• "简单画个 CDN → ALB → ECS → RDS 的图"
• "给我一个典型的 AWS serverless 架构"
• "示意一下前端调后端的认证流程"
• "画个 Kafka → Flink → ClickHouse 数据管道"

Deep Mode（深度梳理）：

• "帮我梳理一下我们电商系统的完整架构"
• "画一个包含安全边界的生产环境部署架构"
• "我们用了 K8s + Istio + 20 个微服务，画个图"
• "我想重构现有系统，先画个现状架构图"

---

输出示例

参考 examples/ 目录下的示例 HTML 文件：

• web-app.html — Web 应用三层架构
• aws-serverless.html — AWS Serverless 架构
• microservices.html — 微服务 + Kubernetes 架构

---

上游致谢

本 skill 基于 Cocoon AI 的 architecture-diagram-generator (MIT License) 深度优化。

v2.1 核心改进：

• ✅ Quick Mode / Deep Mode 自适应分支：轻量场景秒出图（0-1轮确认），复杂系统深度发现（5轮）
• ✅ Step 0: Mode Detection：自动判断走哪个模式，不是所有图都要大费周章
• ✅ Quick Mode 省略摘要卡片和复杂布局规划，保持输出简洁
• ✅ 增加 Phase 1: Layout Planning 布局规划（模式选择 + 画布计算）
• ✅ 增加 Phase 3: Quality Verification 质量验证清单（区分 Quick/Deep）
• ✅ 增加 Iteration Protocol 迭代修改协议
• ✅ 增加中文触发关键词和双语支持
• ✅ 保留上游 v1.1 的完整设计系统、模板和导出功能

---

中文介绍

> 以下内容整理自卡兹克的介绍文章：《又一个神级画图 Skill 开源，再见 draw.io！》

这是什么？

Cocoon AI 开源的 Claude Skill，说人话就能画架构图。跟 Claude 描述系统架构，它直接生成一张深色主题的 HTML 架构图，浏览器打开就能看，还能导出 PNG 和 PDF。不用碰 Draw.io，颜色、箭头、对齐 Claude 全包了。

开源地址：https://github.com/Cocoon-AI/architecture-diagram-generator

功能亮点

说人话就能画。 不需要写代码、不用学标记语法。把架构描述丢给 Claude，它自己决定组件怎么摆、箭头往哪指、用什么颜色。

颜色自动分类。 深色主题 + JetBrains Mono 字体，颜色语义固定：青色给前端，翠绿给后端，紫色给数据库，琥珀色给 AWS 等云服务，玫瑰色给认证和安全模块，一眼就能分辨模块类型。

一键导出。 生成的 HTML 右上角三个按钮：Copy PNG 到剪贴板、Download PNG、Download PDF。零命令行，零额外依赖。

安装方式

Claude Code：把 zip 解压到 ~/.claude/skills/ 或项目本地 .claude/skills/ 目录。

Codex / Cursor / Copilot 等：用 npx skills add 安装，或让 AI 直接重构一个适配版本。

使用方式

三种路子获得架构描述：

1. 让 AI 分析代码库：把代码丢给 Codex/Claude，让它分析结构并输出组件清单
2. 自己手写：直接列出组件和连接关系，比如 "React 前端 talking to Node.js API，PostgreSQL 数据库，Redis 缓存"
3. 让 Claude 给模板：没有具体系统的话，直接问 "画一个典型的 SaaS 应用架构图"

然后把描述贴进对话，加一句"用你的架构图 Skill 生成一张架构图"，Codex/Claude 返回 HTML 文件。想改图直接在聊天里说"把 Redis 挪到消息队列旁边"或"加一层 CDN"就行。

适用与不适用

✅ 擅长：软件架构、云基础设施、微服务拓扑等有明确层次和连接关系的图 ❌ 不适合：物理硬件图、流程图（流程图的姐妹项目 process-flow-diagram-generator 同作者出品）

省下时间干嘛？

写代码、想设计、或者干脆摸鱼，都比调箭头颜色有意义。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ZhouYinLong-lab
• Source: ZhouYinLong-lab/Dog-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.