为什么要用架构图 Skill
- 目标：把分散在文档、代码与基础设施描述中的关系提取成可讨论的视图，便于评审与协作。
- 核心决策：先弄清“读者是谁”（管理层/开发/运维）、“要回答的问题是什么”（边界/调用链/部署）以及“可编辑交付物格式”（Mermaid 文本便于版本化，draw.io 便于交互式编辑，SVG/PNG 用于静态展示）。
常见任务与合适输出（简要指南）
- 梳理服务与依赖（代码库优先）：选择能读取源码或服务声明并输出 C4/组件视图的 Skill，输出格式建议 Mermaid 或 draw.io 源文件以便后续维护。
- 说明请求链路或业务流程：选择支持时序图、流程图或数据流图的 Skill，推荐输出为 Mermaid（文本化）或 SVG（可嵌入文档）。
- 审核云资源与网络边界：选择能解析云资源或 IaC 的 Skill，输出应清楚展示子网、资源组、网络安全组与信任边界；交付物建议包含可导出的可编辑源（Mermaid / draw.io）并去敏感化。
新的示例：电商下单（小型系统）
場景要点：我们要为开发团队绘制两张图：一张关注“下单请求链路”（面向开发），一张关注“部署与网络边界”（面向运维/安全）。 系统组件示例（简化）:
- API Gateway
- Order Service
- Payment Service (第三方支付依赖)
- Inventory Service
- MySQL（订单数据库）
- Redis（会话/缓存）
- Azure 子网：AppSubnet、DBSubnet
工作目标：输出一张 Mermaid 时序图描述下单请求流程；输出一张 draw.io 可编辑部署拓扑图展示网络分区与子网内资源。
步骤（概念级、适用于大多数架构图 Skill）： 1) 定义输入材料 - README 或接口文档：列出各服务职责与外部依赖 - 代码仓库的服务清单（package.json、Dockerfile、compose 或 k8s manifest） - IaC（若有）或手工列出的云资源清单 2) 确定读者和问题（已在场景中定义） 3) 为每个视图选择 Skill 输出格式 - 请求链路：Mermaid 時序圖（文本），便于版本管理与快速迭代 - 部署拓扑：draw.io 可编辑文件，以便运维拖拽调整 4) 运行 Skill（抽象流程，因环境不同请按所用 Skill 文档执行） - 将输入材料（接口列表、服务映射）整理成 Skill 要求的输入格式 - 指定输出格式：Mermaid / draw.io - 请先在小范围（例如只绘制 Order⇄Payment⇄DB）进行试跑 5) 审核生成图 - 让服务负责人核对：组件是否齐全、调用方向是否正确、缺失的外部服务是否标注 - 对部署图进行安全审查：去除或屏蔽真实密钥、私有 IP、账号标识 6) 导出并保留源文件 - 保存 Mermaid 文本或 draw.io 源以纳入版本库
示例输出（示意）
- Mermaid 时序图（简化版文本）：
- 用户 -> API Gateway -> Order Service -> Inventory Service - Order Service -> Payment Service (外部) - Order Service -> MySQL 写入订单 - Inventory Service -> MySQL 更新库存
- 部署拓扑（说明要点）：
- AppSubnet：API Gateway、Order、Inventory、Redis - DBSubnet：MySQL（受限访问，仅开放给 Order/Inventory 节点） - 网络安全组规则：AppSubnet -> DBSubnet (TCP 3306 仅限 Order/Inventory)
验收检查清单（生成后必须人工完成）
- 内容一致性
- 节点职责是否用简短文本描述（不是仅写名称）？ - 调用箭头是否标注方向与协议（HTTP/gRPC/消息队列）？
- 完整性
- 是否列出所有运行时依赖（第三方 API、手工流程、外部队列）？ - 是否与代码和 IaC 对照（例如：服务数量、端口、环境差异）？
- 安全与隐私
- 输出文件中是否含有密钥、账户、内部地址？若有，已删除或模糊化？
- 可维护性
- 是否保存了可编辑源（Mermaid/draw.io）并纳入版本控制？
- 可读性
- 节点数量是否适中？复杂系统是否拆成多张图？
常见限制与注意事项
- 静态分析的局限：从代码或 IaC 自动推断运行时行为、外部服务、人工操作和故障模式往往不完整，需要系统负责人人工补全。
- 过度汇总风险：把所有层级的节点放在一张图会降低可读性，应按上下文/容器/组件/部署分层制图。
- 输出格式约束：并非所有 Skill 都能输出所有目标格式（例如某些 Skill 仅输出 Mermaid 或 SVG）；请先确认支持的导出格式。
- 敏感信息：云架构图在分享前必须检查并移除密钥、账号标识和内部地址。
建议的最佳实践
- 先小范围试跑并让负责人逐项核对，再扩大范围或授予 Skill 读取更多资源的权限。
- 为不同受众维护不同视图：管理层看高层上下文图，开发看容器/组件图，运维看部署/网络图。
- 保持可编辑的源文件在版本控制中，并把图更新过程纳入设计更改流程。
总结
用 Skill 生成架构图可以大幅节省从零画图的时间，但输出只是“草案”与沟通基础：务必界定读者与问题、保存可编辑源并进行人工核验。正确的流程是“生成 → 校对 → 修订 → 纳入版本库”，这样图才能随系统演进保持可用性。