SuperAPI AI 工具集

01-high-level-design

编程与开发

查看项目

更新于 10-16 07:08

技能介绍

用途

该技能是设计文档阶段(Phase 03)的第一个技能,用于在需求足够稳定、可以选择系统边界、职责划分和跨组件流程时,将经过验证的 SRS 需求转化为系统级架构文档。文档定义组件边界、部署拓扑、数据流路径和技术决策。不用于发明缺失需求,也不用于规定类、方法和算法等实现细节。

使用时机与前提

在 Phase 02 完成、SRS_Draft.md 已存在于 projects/<ProjectName>/<phase>/<document>/ 且包含第 1.0 至 3.5 节或更新版本后使用。需要 projects/<ProjectName>/_context/ 中存在 tech_stack.md。可选读取 PRD.md 以补充产品上下文,敏捷项目还可参考 user_stories.md。若 SRS_Draft.md 或 tech_stack.md 缺失,则停止执行并报告缺口。

输入与输出

必需输入:SRS_Draft.md(功能需求、接口、约束、用户类别)和 tech_stack.md(技术选型、框架版本、基础设施目标)。可选输入:PRD.md。输出为 projects/<ProjectName>/<phase>/<document>/HLD.md,含架构图、技术决策和追溯性,遵循 IEEE 1016-2009 Sec 5。

核心步骤

按顺序执行十一步:1)读取上下文文件并记录绝对路径;2)确定架构风格(单体、微服务、无服务器、分层或事件驱动),并引用具体 SRS 约束给出理由;3)生成 Mermaid C4Context 系统上下文图,覆盖外部参与者和外部系统及数据交换;4)生成组件架构图,按表示层、业务逻辑层、数据访问层、基础设施层分解,为每个组件记录名称、职责与暴露接口;5)生成部署拓扑图,映射组件到服务器、容器或云服务,包含端口、协议和 TLS 配置;6)评估可扩展性需求(可选,适用于高可用 >99.9%、并发 >1000 用户或 >100 请求/秒的系统);7)生成数据流图;8)生成技术决策表(决策、考虑选项、选择、理由);9)记录集成点(系统名称与用途、协议、认证方式、数据格式、错误处理策略);10)记录横切关注点(认证授权、日志监控、错误处理、缓存);11)生成追溯表,将每个 HLD 组件关联到来源 SRS 章节和需求 ID。

输出结构

HLD.md 依次包含:文档头(项目名、日期、版本、标准)、1. 架构风格、2. 系统上下文图、3. 组件架构、4. 部署拓扑、5. 数据流图、6. 技术决策、7. 集成点、8. 横切关注点(8.1 认证/授权、8.2 日志、8.3 错误处理、8.4 缓存)、9. 追溯矩阵、附录 A 术语表。

适用场景与限制

适用于瀑布和敏捷项目。能力边界方面:分析和规划默认为只读,需要授权项目制品的读写与搜索权限;编辑仅限明确要求的交付物;未经明确授权不得发布、消费、更改生产环境、批准策略或声称认证。若所需能力不可用,返回最窄范围内的经限定草稿和缺口登记表,绝不把未评估的检查转为通过。

质量标准与反模式

保留仓库术语并将每个重要选择追溯到项目上下文;用确定性验收条件替代模糊质量声明;覆盖错误、空、边界、恢复和运行场景。反模式包括:画没有职责的组件、先选技术再定约束、只画正常路径流程、在 HLD 中嵌入类细节、无负载指标却声称可扩展性。

参考与集成

参考资源包括逻辑提示、实践架构知识、SaaS HLD 模式及 README。上游消费 Phase 02 的 SRS_Draft.md;下游供 02-low-level-design、03-api-specification、04-database-design 使用。遵循 IEEE 1016-2009 Sec 5 和 ISO/IEC 25010。生成 HLD 时应同时触发测试策略文档(若尚未开始)。官方文本中未提供具体的收费、价格或平台信息。