architecture-diagram

architecture-diagram 技能概览

architecture-diagram 技能可以把一段粗略的系统描述，整理成一张精致的深色架构图，并以带内联 SVG 的独立 HTML 文件输出。它特别适合用来表达服务边界、数据流、云组件、安全层或网络拓扑，而不是做一页泛泛的演示幻灯片。

对于工程师、产品团队和技术文档作者来说，architecture-diagram 技能的价值在于：它能快速生成一张可读性高、风格统一、无需额外构建步骤就能直接分享的图。核心优势是速度加结构：它提供了视觉体系、配色语言，以及可直接在浏览器中打开的输出格式。

architecture-diagram 技能适合做什么

当你的输出需要传达组件之间的关系，而不只是罗列组件时，就应该用 architecture-diagram。它尤其适合：

• 微服务和 API 布局
• 云架构或 AWS 风格的架构视图
• 安全与信任边界图
• 数据管道和消息总线流转
• 内部平台总览

它的不同之处

这个 repo 对呈现方式有明确偏好：深色主题、JetBrains Mono、按组件类型区分的语义化颜色，以及在 HTML 中以 SVG 为核心进行渲染。也就是说，architecture-diagram 技能更强调产出一致、技术感强、接近生产可用的架构图，而不是自由发挥式的插画。

architecture-diagram 技能什么时候可能不合适

如果你需要的是像 Lucidchart 这类工具里的可编辑图，或者需要大量图标库支持的图，这个技能可能并不是最佳选择。它更适合浏览器渲染的交付物：在这里，清晰度、可移植性和技术审美比拖拽式编辑更重要。

如何使用 architecture-diagram 技能

安装并正确加载 architecture-diagram

进行 architecture-diagram 安装时，先添加技能，然后在开始写提示词前先阅读技能说明：

npx skills add Cocoon-AI/architecture-diagram-generator --skill architecture-diagram

安装完成后，先打开 SKILL.md 和 assets/template.html。这两个文件会展示核心布局规则，以及技能期望的输出结构。

提供完整的系统说明

architecture-diagram 的使用效果最好时，你的输入会明确写出系统名称、主要组件，以及它们之间的关系。一个高质量的提示词通常应包含：

• 业务或系统名称
• 前端、后端、数据库和云服务
• 信任边界或安全区域
• 主要请求 / 数据流
• 必须展示的技术栈或标签

提示词示例：

Create an architecture diagram for a SaaS app with React frontend, Node API, Postgres, Redis cache, AWS ECS, S3, and Stripe. Show login, API calls, async jobs, and security boundaries.

按正确顺序阅读 repo 文件

如果你想让 architecture-diagram 真的提升输出质量，就不要只看标题。建议按下面顺序开始：

1. SKILL.md：查看约定和组件映射
2. assets/template.html：查看视觉骨架和 class 名称
3. 技能正文中的任何内联示例：查看布局或标签密度的示范

这个顺序很重要，因为这个技能的价值在于把呈现选择编码进去，而不是在于庞大的文件树。

优化工作流，让图的质量更稳定

更实用的工作流是：先定义范围，再列出组件，再映射数据流，最后生成。如果原始材料很乱，先把它重写成一份简单清单。和含糊的架构堆砌相比，architecture-diagram 技能更擅长处理结构清晰的输入。给它明确优先级，比如“展示外部边界”“强调事件总线”“尽量减少数据库内部细节”，这样图就不容易变得拥挤。

architecture-diagram 技能常见问题

architecture-diagram 只适合云架构图吗？

不是。architecture-diagram 技能的适用范围比云架构更广。只要输出的是组件关系图，它也可以用于应用技术栈、内部平台、安全视图和网络图。

我需要先懂图形语法吗？

不需要。这个技能的价值之一，就是把自然语言的系统描述转成结构化视觉图。你需要提供足够准确的细节，但不必手写图形代码。

它和普通提示词相比有什么优势？

普通提示词可能只会生成一次性的图形想法。architecture-diagram 技能则增加了可复用的设计系统、输出格式纪律，以及更清晰的浏览器可交付路径。这让你更容易在不同项目之间产出一致的架构图。

什么情况下不该用它？

如果你的主要需求是协作编辑、带大量正文的架构决策记录，或者高度定制的矢量插画，就不要选 architecture-diagram。它适合的是干净的技术架构图，而不是完整的文档套件。

如何改进 architecture-diagram 技能

先明确你希望这张图支持什么决策

最好的结果来自这样的提示：先说明这张图要帮助读者理解什么。比如，你可以要求它展示“请求路径和失败点”“安全区域与数据暴露”“入职流程中的服务依赖”。这样 architecture-diagram 技能得到的是有层级的目标，而不是一份扁平清单。

提供约束，而不只是列组件

用户最在意的是清晰度，而杂乱是最常见的失败模式。要告诉技能哪些内容该省略、压缩或分组。好的约束包括：

• “把内部 worker 合并成一个框”
• “不要使用厂商 logo”
• “限制在 6 个核心框以内”
• “只展示面向用户的流程，不要把每个后台任务都画出来”

这通常是最快提升 architecture-diagram 使用效果的方法之一。

从布局问题入手迭代，而不是笼统地说不满意

如果第一次输出效果一般，要精准定位问题。可以要求缩小范围、优化标签，或者换一种分组策略。例如：

• 太拥挤：减少标签，合并低价值服务
• 流向不清：给步骤编号并加箭头
• 重点不突出：用更强的对比突出一条路径
• 上下文不足：补上边界标签和外部依赖

用模板保持输出一致

当你需要可重复的品牌样式，或者希望多个系统共享同一种图表风格时，assets/template.html 会特别有用。复用这套结构，可以让 architecture-diagram 技能在保持视觉一致性的同时，仍然支持不同的组件映射和标签内容。