architecture-diagram 是 Cocoon AI 发布的一款面向 AI 助手的架构图生成 Skill。它把"理解自然语言中的系统结构"与"生成可直接交付的前端文件"组合在一起：用户只需描述系统组件、连接关系、技术栈、协议、端口或部署边界，AI 就会生成一个独立的 HTML 文件，其中以内联 SVG 绘制专业的系统架构图。项目主页将它定位为 Claude AI Skill，但其核心产物是标准 HTML、CSS 与 SVG，因此生成结果不依赖专用看图软件，可直接在现代浏览器中打开、分享或托管。GitHub 仓库
它解决什么问题
传统架构图通常需要在 Draw.io、Figma、Visio 等工具中手工放置节点、拉线、调整层级和统一配色。这个 Skill 将工作方式改成"用文字定义架构，由 AI 完成视觉实现"。用户可以输入已有系统的说明，也可以让 AI 先分析 README、技术方案或代码库，再把识别出的客户端、网关、服务、数据库、缓存、消息系统、云资源和外部集成组织为图。
它尤其适合：技术方案评审、系统概览、团队入职材料、售前方案、云部署说明、微服务拓扑和文档中的架构插图。生成后仍可通过对话继续迭代，例如要求增加 Redis、把认证服务移到安全边界内、标出 HTTPS/gRPC、改变布局或修正连线。
核心能力
- 自然语言生成：输入组件列表及关系即可，不要求用户掌握 SVG 或制图软件。
- 独立 HTML 交付：CSS、页面结构和 SVG 图形整合在一个文件中，便于邮件发送、文档归档和静态站点托管。
- 深色技术视觉风格：默认使用 Slate-950 风格背景、细网格和 JetBrains Mono 字体，整体接近现代开发者工具界面。
- 语义化配色：前端/客户端使用青色，后端/服务使用翠绿色，数据库与 AI/ML 使用紫色，云基础设施使用琥珀色，安全组件使用玫红色，外部系统使用灰色。颜色不仅装饰画面，也帮助读者快速辨认组件职责。
- 架构关系表达：可表现请求流、数据流、服务依赖、协议和端口，以及安全组、云区域、边界上下文等分组。
- 内置导出：生成页面带 Copy、PNG 和 PDF 操作；可复制高分辨率 PNG、下载 PNG，或保留深色主题导出 PDF。
- 响应式 SVG ：典型
viewBox宽度约为 1000--1100 像素，浏览器可按容器大小缩放。 - 连线层级处理：连线优先绘制在组件下方，并通过不透明底层遮挡穿过节点的部分，使复杂关系图更整洁。
Skill 的组成与运行机制
原仓库中的安装包结构很精简：
text
architecture-diagram/
├── SKILL.md
└── resources/
└── template.htmlSKILL.md 是给 AI 助手读取的操作规范，负责规定触发场景、设计语言、节点与连线的表达方法、布局要求以及生成流程；resources/template.html 是基础页面模板，提供统一的 CSS、SVG 容器、页头、摘要卡片、页脚和导出逻辑。AI 并不是调用一个远程"绘图服务"，而是根据 Skill 规则理解输入，再在模板基础上直接编写 HTML/SVG。
典型处理链路如下：
text
自然语言或代码库说明
↓
提取组件、技术栈、边界与连接关系
↓
选择层次、分组、颜色与 SVG 坐标
↓
生成自包含 HTML + 内联 SVG
↓
浏览器查看、复制或导出 PNG/PDF生成页面一般包含四部分：项目标题与状态提示、架构图主体、三张关键信息摘要卡片，以及项目元数据页脚。图本身会根据实际系统调整布局、节点标签、协议标注与安全或部署边界，而不是机械填充固定示例。
安装与使用
在 Claude.ai 中，先启用 Code Execution，然后下载仓库提供的 architecture-diagram.zip，进入 Customize → Skills ，选择创建并上传 Skill，最后开启它。团队或企业环境可能需要管理员在组织设置中允许 Skills。Claude Code 用户也可以把压缩包解压到全局 ~/.claude/skills/ 或项目级 ./.claude/skills/。仓库 README 提供了完整的安装与快速开始说明。
一个有效的输入示例是：
text
请使用 architecture diagram skill 绘制一个 SaaS 系统：
- React Web 与 iOS/Android 客户端
- CloudFront 和 API Gateway
- Node.js 用户服务、Go 订单服务
- PostgreSQL、Redis 和 Kafka
- 使用 Cognito 认证
- 标出 HTTPS、异步事件流和 AWS 边界信息越具体，结果越可靠。建议至少提供：组件名称、职责、上游和下游关系、同步或异步方式、协议/端口、数据存储，以及部署区域或信任边界。若信息缺失，AI 可以给出"典型架构"作为起点，但那是推断方案，不应被当作现有系统事实。
典型输出的技术特征
输出是标准 HTML 文档，主体大致由页头、SVG 容器、摘要卡片和页脚组成。背景基色为 #020617，通常叠加 40px 网格；组件框使用半透明填充和语义色描边；SVG 连线、箭头标记和标签全部内联。字体可从 Google Fonts 加载 JetBrains Mono，因此在严格离线环境中可能回退到本机字体；如果要求完全隔离网络，应将字体一并内嵌或改用系统字体。
这种实现方式的优势是可移植、无需构建步骤，并且容易嵌入 Wiki 或静态站点。代价是图的编辑方式更偏"修改代码或继续与 AI 对话"，不具备 Draw.io 那样的原生拖拽工程文件；页面中的导出功能也依赖浏览器能力。对于非常庞大、需要自动布局或持续同步实时拓扑的系统，最好先拆成上下文图、容器图和关键链路图，而不是把所有节点塞进一张图。
优势与局限
| 维度 | 表现 |
|---|---|
| 上手成本 | 很低，系统说明即可成为输入 |
| 交付便利性 | 很高，单 HTML 文件可直接打开和分享 |
| 视觉一致性 | 默认设计系统统一，适合技术展示 |
| 迭代方式 | 对话修改迅速，适合方案讨论 |
| 精细手工编辑 | 弱于专业矢量或拖拽制图工具 |
| 超大规模拓扑 | 容易产生拥挤和交叉线，需要拆图 |
| 架构正确性 | 取决于输入完整度和人工复核，不能替代架构评审 |
| 动态数据 | 生成的是静态说明性页面，不是监控面板 |
特别需要强调的是：视觉上"漂亮"不等于架构事实正确。对生产系统使用时，应人工核对组件遗漏、箭头方向、同步/异步语义、网络边界、敏感数据路径和高可用关系。导出前还应检查标签遮挡、连线穿过节点和不同分辨率下的可读性。
与附件 fireworks-tech-graph 的关系
本次附件 {7acef5f8-c022-4593-b797-8198cbc84ea4}.zip 并不是目标仓库原始的极简 architecture-diagram 安装包，而是一个名为 fireworks-tech-graph 的扩展型技术制图 Skill。附件包含 SKILL.md、多套模板与风格参考、JSON Schema、Python/JavaScript/Shell 工具、测试夹具、示例图片及验证流程，其能力范围明显更广。
根据附件内容，它支持架构图、数据流、流程图、序列图、C4 评审、云部署、事件流、可观测性调查、Agent/Memory 系统、UML、ER、网络拓扑和时间线；输出可覆盖 SVG、PNG、语义动效 GIF 与离线交互 HTML。它还加入了几何检查、组合质量约束、语义契约、统一 CLI、正交路由、PNG 导出、视觉复核以及多风格系统。
因此，两者可这样理解：
| 项目 | Cocoon-AI 原始 Skill | 附件 fireworks-tech-graph |
|---|---|---|
| 核心目标 | 快速生成深色自包含 HTML/SVG 架构图 | 构建可验证、多类型、多格式的技术制图工具链 |
| 结构 | SKILL.md + HTML 模板 |
Skill、参考规范、模板、Schema、脚本、测试和样例 |
| 图类型 | 主要面向系统架构图 | 架构、流程、序列、UML、ER、网络等多类图 |
| 输出 | HTML，页面内导出 PNG/PDF | SVG、PNG、GIF、离线交互 HTML 等 |
| 质量控制 | 依赖规则与人工检查 | 提供 XML、几何、语义和渲染验证流程 |
| 使用复杂度 | 低，适合快速出图 | 较高，适合工程化、可复现的制图需求 |
附件可以视为同类思路的工程化扩展，但不应将其 12 种风格、GIF 动效、Schema 或验证脚本归因于 Cocoon-AI 原仓库。介绍目标项目时，应以原仓库 README 和实际目录为准；评估如何升级或二次开发时，附件则提供了很有价值的实现参考。
总体评价
architecture-diagram 的价值不在于创造新的图形格式，而在于把架构师的文字表达快速转换成一致、可展示、可分享的网页图。它以很小的 Skill 包实现了较完整的交付体验：自然语言输入、统一视觉模板、浏览器直接查看和内置导出，特别适合中小规模系统的方案沟通与文档配图。
若需求是"几分钟内生成一张效果专业的系统架构图"，原始 Skill 简洁而实用；若需求进一步包含多种工程图、严格几何验证、批量生成、动效或 CI 质量门禁，则附件中的 fireworks-tech-graph 路线更合适。无论使用哪一种，都应把 AI 生成物视为架构表达草稿，并由了解真实系统的人完成最终技术审阅。