dev-docs/软件设计开发需求流程.md

软件设计开发需求流程

版本: v4.2 | 日期: 2026-07-24 | 适用范围: 通用软件项目 | 核心方法论: 文件驱动设计（DDD）+ AI 全链路

---

目录

1. 0. 简介
2. 0.1 文档清单与文件对应关系
3. 0.2 流程全景图
4. 1. 项目启动与需求收集
5. 1.1 可行性分析
6. 1.2 PoC 执行计划
7. 2. 需求分析
8. 2.1 需求变更管理
9. 3. 系统架构设计
10. 3.1 API 版本管理
11. 4. 数据模型设计
12. 4.1 数据迁移与回滚
13. 5. 开发计划
14. 6. 编码规范
15. 6.1 国际化规范
16. 7. 构建与环境
17. 7.1 多环境管理
18. 8. 测试策略
19. 9. 开发工作流
20. 10. 部署运维
21. 10.1 事故响应
22. 10.2 功能开关与灰度发布
23. 11. 反馈迭代
24. 12. 技术债务管理
25. 13. 知识管理
26. 13.1 开发者使用助手生成规范
27. 14. 文件驱动设计生产（DDD）
28. 附录A: 安全开发生命周期
29. 附录B: 合规性管理
30. 附录C: 供应链安全
31. 附录D: 无障碍访问规范
32. 附录E: 依赖升级管理
33. 附录F: 团队沟通与知识传递
34. 附录G: AI Agent 自主开发操作规范（PA 章）
35. PA.0 核心概念与能力模型
36. PA.0.3 环境自检
37. PA.0.4 文档读取策略
38. PA.1 项目状态文件
39. PA.2 上下文窗口管理
40. PA.3 AI 执行权限
41. PA.4 每阶段 AI 执行标准 SOP
42. PA.5 AI 版编码规范
43. PA.6 AI 质量自检门禁
44. PA.7 失败恢复与阻塞处理
45. PA.8 人类反馈级联传播
46. PA.9 多 Agent 协作
47. PA.10 提示词工程规范
48. PA.11 项目初始化 AI 流程
49. PA.12 人类通信格式
50. PA.13 中断处理协议
51. PA.14 异常场景处理
52. PA.15 端到端走查示例
53. PA.16 持续改进机制
54. 附录H: AI 辅助设计开发规范

---

0. 简介

本指南是一份通用的、可复用的软件设计开发流程方法论，覆盖从项目启动到部署运维的完整生命周期。适用于任何新项目——直接复制本文档，按 {占位符} 填入项目信息即可使用。

适用场景：Web 应用、移动 App、桌面软件、后端服务、嵌入式系统、平台型产品等各类软件项目。

核心理念：

• 文件驱动设计（DDD）：以规范文件作为"单一事实来源"，驱动设计、编码、测试、部署全流程
• 微内核 + 插件化：最小内核 + 功能通过插件扩展，实现松耦合、热插拔
• 渐进式交付：分阶段路线图，每阶段有明确里程碑与验收标准
• AI 嵌入全链路：需求 → 设计 → 编码 → 测试 → 运维，AI 作为基础设施嵌入每个环节

每个阶段均包含：目标、输入物、产出物、关键步骤和检查清单。所有模板使用 {占位符} 标记，按项目特点替换即可。

---

0.1 文档清单与文件对应关系

本节作用：当 AI 接收本文档时，首先阅读本节以了解所有已有文档的位置、格式、内容概要和读写优先级，避免遗漏关键上下文。

项目文档结构模板

使用方式：新建项目时，按此模板在 docs/design/ 和 docs/plan/ 下创建对应的 Markdown 文件。文件编号为推荐顺序，文件名可按项目特点调整。

docs/
├── design/
│   ├── 00-项目概述与愿景.md          # 项目定位、目标用户、核心价值主张
│   ├── 01-功能需求文档.md            # 全模块功能需求、优先级、非功能需求
│   ├── 02-系统架构与技术选型.md       # 分层架构、技术栈选型、项目目录结构
│   ├── 03-开发计划与里程碑.md         # Phase 划分、路线图、任务分解
│   ├── 04-数据模型设计.md            # 核心数据结构、持久化格式、数据流
│   ├── 05-UI设计方案.md              # 界面架构、扩展点、主题、交互规范
│   ├── 06-插件SDK与开发规范.md       # 插件接口、manifest 规范、API 参考
│   ├── 07-竞争对标分析.md            # 竞品功能矩阵、差异化策略
│   ├── 08-商业化与许可证方案.md       # 版本分级、定价、License 技术方案
│   ├── 09-API与通信协议设计.md       # 内部 API、外部 API、事件总线、IPC
│   ├── 10-安全架构设计.md            # 威胁模型、认证授权、加密、安全层
│   ├── 11-部署与运维方案.md          # 打包分发、CI/CD、监控、备份恢复
│   ├── 12-测试策略.md               # 测试金字塔、工具链、覆盖率目标
│   ├── 13-性能与扩展性设计.md        # 性能目标、优化策略、扩展性方案
│   ├── 14-平台适配方案.md            # 跨平台策略、特定平台适配方案
│   ├── 15-能力缺口分析.md            # 与行业标杆的差距、填补计划
│   ├── 16-编码规范与代码风格指南.md   # 命名、格式、注释、错误处理规范
│   ├── 17-开源治理与许可证方案.md     # 开源策略、贡献协议、社区治理
│   ├── 18-品牌与商标策略.md          # 品牌资产、商标注册、使用规范
│   ├── 19-供应链安全方案.md          # SBOM、依赖扫描、构建签名
│   ├── 20-市场定价与本地化策略.md     # 多区域定价、支付渠道、税务合规
│   ├── 21-多语言国际化方案.md        # 语言优先级、翻译工作流、RTL 支持
│   ├── 22-用户文档与帮助系统.md      # 文档体系、帮助系统、教程
│   ├── 23-版权与专利风险评估.md      # 专利风险、合规审查、IP 保护
│   ├── 24-开发者社区治理方案.md      # 治理模型、RFC 流程、贡献激励
│   ├── 25-用户反馈与迭代闭环.md      # 反馈渠道、分类处理、迭代节奏
│   ├── 26-教育与培训体系.md          # 课程体系、认证、合作伙伴
│   ├── 27-数据迁移方案.md            # 迁移向导、数据映射、质量验证
│   ├── 28-无障碍可访问性设计.md      # WCAG 合规、键盘导航、屏幕阅读器
│   ├── 29-核心架构模式设计.md        # 架构模式选择与组合策略
│   ├── 30-补充设计要点.md            # 日志、错误处理、配置管理、备份
│   └── 31-开发进度跟踪.md            # 项目仪表盘、Phase 进度、任务状态
│
├── api/                             # 使用助手（AI 自动生成）
│   ├── README.md                    # 模块总览 + 目录索引
│   ├── {module}.md                  # 每个模块的 API 手册
│   ├── examples.md                  # 常见用法速查
│   └── call-graph.md               # 调用关系图
│
└── plan/
    ├── README.md                     # 计划方法论、进度约定
    └── {Phase名}-执行计划.md          # 具体 Phase 的任务分解、依赖图、里程碑

裁剪原则：

• 小型项目可合并相关文档（如 04+05 合并、17+18 合并）
• 大型项目可拆分文档（如 02 拆分为架构概要 + 各子系统详细设计）
• 不需要的文档可跳过，但建议保留文件占位并标注"暂不适用"
• 文档编号连续有助于 AI 按顺序读取

AI 文档读取策略

AI 接收本文档后，按以下顺序读取：

第一步（必读）：
  1. 读取本文档（本流程文档）全文 — 理解完整流程框架
  2. 读取 docs/design/01-功能需求文档.md — 了解软件要做什么
  3. 读取 docs/design/02-系统架构与技术选型.md — 了解怎么做
  4. 读取 docs/design/31-开发进度跟踪.md — 了解做到哪了（如有）

第二步（按需读取，根据当前阶段）：
  - 立项阶段 → 00-项目概述、07-竞争对标、15-能力缺口
  - 需求阶段 → 01-功能需求、29-架构模式
  - 设计阶段 → 02-系统架构、04-数据模型、05-UI设计、09-API设计、10-安全架构、13-性能
  - 编码阶段 → 06-插件SDK、16-编码规范、docs/plan/{Phase}-执行计划.md
  - 测试阶段 → 12-测试策略、13-性能与扩展性
  - 部署阶段 → 11-部署运维、19-供应链安全
  - 运营阶段 → 08-商业化、20-定价策略、24-社区治理、25-用户反馈
  - 平台适配 → 14-平台适配、21-国际化、28-无障碍
  - 法务合规 → 17-开源治理、18-品牌商标、23-版权专利
  - 补充设计 → 30-补充设计要点、22-用户文档、27-数据迁移

---

流程全景图

┌──────────────────────────────────────────────────────────────────────────┐
│  软件设计开发需求流程 — 全面生命周期                                      │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  P0: 项目启动 → P1: 需求分析 → P2: 架构设计 → P3: 数据模型                 │
│       ↓               ↓               ↓               ↓                  │
│  P4: 开发计划 → P5: 编码规范 → P6: 构建系统 → P7: 测试策略                 │
│       ↓               ↓               ↓               ↓                  │
│  P8: 开发协作 → P9: 部署运维 → P10: 用户反馈 → P11: 风险管理               │
│       ↓               ↓               ↓               ↓                  │
│                        P12: 项目记忆（贯穿始终）                            │
│                                                                          │
│  ═══════════════════════════════════════════════════════════════════      │
│  核心理念:                                                               │
│  - 文件驱动设计: AI先产出规范文件，以文件为"单一事实来源"驱动全流程（见PM章）│
│  - 微内核+插件化: 最小内核 + 功能通过插件扩展，实现松耦合、热插拔             │
│  - 渐进式交付: 4-Phase 路线图，每阶段有明确里程碑与验收标准                   │
│  - AI 嵌入全链路: 需求→设计→编码→测试→运维，AI 作为第一公民                 │
│  - 开发者体验优先: 脚手架工具、标准化 SDK、完整文档、清晰入职路径            │
└──────────────────────────────────────────────────────────────────────────┘

---

1. 项目启动与需求收集

关联文档: docs/design/00-项目概述与愿景.md | docs/design/07-竞争对标分析.md | docs/design/15-能力缺口分析.md | docs/design/18-品牌与商标策略.md

目标

明确项目愿景、核心价值主张、目标用户画像，初步收敛功能范围，建立项目基础设施骨架。

输入物

输入	来源	说明
市场调研报告	市场/产品团队	竞品分析、市场缺口、目标用户痛点
技术可行性预研	技术团队	核心技术难点初步 PoC 验证
初始愿景陈述	创始人/产品负责人	一句话产品定位、核心差异化策略
竞品对标分析	产品团队	Top 3-5 竞品功能矩阵对比

产出物

产出	格式	说明	对应文件
项目章程	Markdown	愿景、目标、范围边界、不做什么	更新本流程文档立项章节
竞品分析	Markdown	与竞品的核心差异矩阵	docs/design/07-竞争对标分析.md
AI 总体方案	Markdown	AI 架构、插件、路线图	docs/design/00-项目概述与愿景.md
能力缺口分析	Markdown	与行业标杆的差距分析	docs/design/15-能力缺口分析.md
品牌策略	Markdown	品牌资产、商标注册	docs/design/18-品牌与商标策略.md
微内核设计文档	Markdown	Shell 最小内核定义	docs/design/02-系统架构与技术选型.md
Phase 0 执行计划	Markdown	3 个月路线图，含任务分解	docs/plan/{Phase名}-执行计划.md
进度跟踪	Markdown	项目仪表盘	docs/design/31-开发进度跟踪.md

关键步骤

1. 竞品功能矩阵对比: 读取 docs/design/07-竞争对标分析.md 已有数据，补充 Top N 竞品最新信息
2. 定义核心差异化: 确定项目在哪些维度上建立壁垒（如开源免费 + 本地 AI + 全插件化 + 跨平台）
3. 确定架构顶层设计: 选定微内核 + 插件化架构，定义 Shell 最少必须提供的基础服务集
4. 最小可行内核 (MVP Kernel): 定义 Phase 0 用户不可见但必须跑通的基础能力——插件发现/加载/卸载、事件总线、命令注册、许可证管理
5. 建立项目仓库骨架: 初始化单体仓库 (单体仓库) 结构、构建系统骨架 ({构建工具} + {包管理器})、CI/CD 三平台构建流水线

检查清单

• 项目愿景能用一句话说清楚
• 竞品分析覆盖至少 3 个直接竞品
• 差异化策略有明确的壁垒维度（不依赖单点功能）
• Shell 最少服务集已定义（不超过 12 个核心服务）
• {插件接口} 接口生命周期清晰（uid/name/version/initialize/shutdown）
• 构建系统能三平台编译通过（Windows / Linux / macOS）
• 许可证管理方案已纳入 Phase 0 设计（{签名算法} 验证 / 硬件指纹 / FeatureFlag 门控）
• 单体仓库目录结构已确定

---

---

---

1.1 可行性分析

目标

在项目正式启动前，从技术、市场、商业、法律和时间五个维度系统性评估项目可行性，输出 Go/No-Go 决策依据和风险缓释方案。

可行性分析框架

                  ┌──────────────────┐
                  │   可行性分析      │
                  └────────┬─────────┘
           ┌───────────────┼───────────────┐
     ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐
     │ 技术可行性  │  │ 市场可行性  │  │ 商业可行性  │
     └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
     ┌─────┴─────┐  ┌─────┴─────┐
     │ 法律/合规   │  │ 时间可行性  │
     └───────────┘  └───────────┘

---

一、技术可行性

1.1 核心技术挑战识别

挑战类别	评估问题	风险等级判定
算法可行性	核心算法是否有理论证明/论文/开源实现？	有已知实现→低；纯研发→高
性能边界	性能目标是否在已知技术能力范围内？	有 Benchmark→低；无先例→高
集成复杂度	依赖的第三方库/服务是否成熟稳定？	成熟生态→低；自研为主→高
平台兼容	目标平台是否有已知限制？	全平台成熟→低；新平台→中
数据可用性	训练/测试数据是否可获取？质量和数量？	丰富→低；稀缺→高

1.2 技术可行性评分卡

维度	权重	评分(1-5)	加权	说明
核心算法成熟度	25%	X	X	有开源参考，需适配优化
依赖生态成熟度	15%	X	X	包管理器覆盖情况
团队技术储备	20%	X	X	核心技术栈匹配度
性能目标可实现性	20%	X	X	与已知 Benchmark 对比
平台兼容风险	10%	X	X	三平台方案成熟度
技术债务预估	10%	X	X	早期架构债评估
总分	100%	-	X.X/5	>=3.0 可行，>=4.0 强推荐

结论: 🟢 可行 / 🟡 有条件可行 / 🔴 不可行

1.3 PoC（概念验证）策略

当技术可行性评分 <3.5 或有关键技术不确定性时，必须先执行 PoC。

## 1.2 PoC 执行计划

### PoC 目标（限 2 周）
验证: {最不确定的技术点}

### 最小验证范围
- [ ] 验证项 1: {描述} — 成功标准: {量化指标}
- [ ] 验证项 2: {描述} — 成功标准: {量化指标}

### 时间与资源
- 周期: 2 周
- 人员: 1-2 名核心开发者
- 预算: {人天成本 + 硬件/云服务费用}

### Go/No-Go 判定
- Go: 所有验证项达标
- Conditional Go: 关键项达标，次要项有 workaround
- No-Go: 关键项不达标 -> 调整方案或放弃

---

二、市场可行性

2.1 竞品功能矩阵对比

功能维度	本项目	竞品A	竞品B	竞品C	差异化程度
核心功能1	✅	✅	✅	✅	无差异
核心功能2	✅	❌	⚠️	❌	强差异
价格策略	开源免费	¥X/年	¥Y/年	免费(受限)	强差异
AI 能力	✅ 本地	❌	⚠️ 云端	❌	强差异
插件生态	✅ 开放	❌	⚠️ 受限	❌	强差异

差异化持续性评估:

• 单点功能差异化 → 竞品 3-6 个月可复制（弱壁垒）
• 架构级差异化 → 竞品 12-24 个月可追赶（中壁垒）
• 生态/社区差异化 → 竞品 24+ 个月难以复制（强壁垒）

2.2 市场风险评估

风险	概率	影响	缓解措施
竞品快速跟进差异化	高	中	持续迭代，保持 6 个月技术领先
付费意愿低于预期	中	高	开源社区运营+企业增值服务双轨
市场窗口被巨头关闭	低	高	差异化壁垒（本地 AI + 全插件化）

---

三、商业可行性

3.1 成本估算

成本类别	Phase 0-1 (1-2年)	Phase 2-3 (2-4年)	说明
人力成本	N人 x 平均薪资 x 24月	N人 x 平均薪资 x 24月	含五险一金
基础设施	云服务器/域名/SaaS	{容器编排}/{内容分发网络}/监控	随用户量增长
第三方服务	IDE/工具授权	代码签名 + 翻译平台	-
法务/合规	商标注册 + 隐私合规	等保测评 + 专利	-
营销	社区运营	展会 + 内容营销	-
总计	¥X M	¥Y M	-

3.2 盈亏平衡分析

指标	Year 1	Year 2	Year 3	Year 4
活跃用户	1K	10K	50K	150K
付费转化率	0%	2%	5%	8%
年收入	¥0	¥200K	¥2.5M	¥12M
年成本	¥1.5M	¥3M	¥5M	¥7M
盈亏	-¥1.5M	-¥2.8M	-¥2.5M	+¥5M

3.3 商业模式画布

组件	内容
价值主张	{一句话核心价值}
客户细分	个人开发者 / 中小企业 / 大型企业 / 教育机构
渠道	官网 / 应用商店 / 开源社区 / 企业直销
收入来源	开源免费(社区版) + 企业订阅(Pro) + 云服务 + 插件市场抽成
成本结构	人力(70%) + 基础设施(15%) + 营销(10%) + 其他(5%)

---

四、法律与合规可行性

检查项	状态	风险评估
开源许可证选择	⚠️ 待定	{许可证A} vs {许可证B}，需法务评估
第三方依赖许可证审计	⚠️ 待执行	{许可证E} 传染性风险隔离方案确认
商标注册	❌ 未开始	项目名/Logo 商标检索和注册
软件著作权	❌ 未开始	核心模块著作权登记
专利 Freedom to Operate	⚠️ 待执行	核心算法专利检索
隐私合规 (PIPL/GDPR)	❌ 未开始	数据收集/存储/传输合规评估
出口管制	⚠️ 待评估	加密算法/AI 模型的出口限制
等保/安全合规	❌ 未开始	如涉政务/央企场景需等保测评

---

五、时间可行性

5.1 市场窗口分析

因素	评估
竞品时间线	竞品A 已上市 v3.0；竞品B 传闻 Q3 发布 AI 功能
我们的窗口	需在竞品 AI 能力成熟前建立本地 AI 壁垒
窗口长度	预估 18-24 个月

5.2 内部时间风险

风险	影响阶段	延后预估	缓解措施
核心团队招聘延迟	P1-P2	+3-6月	远程优先，扩大候选人池
核心技术攻关超预期	P1	+2-4月	PoC 先行，备选技术方案
关键依赖库不成熟/变更	P2-P3	+1-2月	封装抽象层，隔离外部变化
合规审批延误	P3-P4	+1-3月	提前启动合规流程，并行推进

---

六、Go/No-Go 决策矩阵

维度	最低通过标准	当前评分/状态	决策
技术可行性	>=3.0/5	X.X
市场可行性	至少 2 个强差异化维度	X 个
商业可行性	3 年内可见盈亏平衡路径	是/否
法律可行性	无阻断性合规风险	是/否
时间可行性	市场窗口 >=18 个月	X 月

最终决策:

• GO — 启动 P0 项目启动与需求收集
• CONDITIONAL GO — 条件（___）满足后启动
• NO-GO — 项目暂停/调整方向
• REPLAN — 调整范围或目标后重新评估

---

可行性分析驱动 AI 执行

当 AI Agent 执行可行性分析时：

1. 自动收集信息：搜索竞品信息、查阅技术文档、分析依赖生态
2. 生成评分卡：按上述维度逐项评分，标注不确定性来源
3. 识别关键未知：列出必须人类确认的事项（如融资计划、法律意见）
4. 输出建议：附带置信度的 Go/No-Go 建议
5. 人类决策：AI 提供分析依据，人类做最终判断

检查清单

• 五维可行性分析全部完成（技术/市场/商业/法律/时间）
• 技术可行性评分 >=3.0/5，或 PoC 计划已启动并获得资源
• 至少识别 2 个可持续的差异化维度（非单点功能，有壁垒）
• 成本估算覆盖前 3 年，盈亏平衡路径清晰
• 专利 Freedom to Operate 检索完成或确认为低风险
• 第三方依赖许可证审计完成（无阻断性 {许可证E} 传染风险）
• Go/No-Go 决策已作出并记录，所有利益相关方已确认
• 如果是 Conditional Go，前提条件清单、验证方法、到期时间已明确

---

2. 需求分析

关联文档: docs/design/01-功能需求文档.md | docs/design/29-核心架构模式设计.md | docs/design/15-能力缺口分析.md

目标

将用户需求转化为完整的、结构化的功能需求文档，明确模块划分、功能边界、优先级排序，形成可被开发团队直接理解的规格说明。

输入物

输入	来源	说明
项目章程	P0 产出	愿景、范围边界
竞品功能矩阵	P0 产出	对标功能清单
用户调研报告	产品团队	用户工作流、痛点、期望
技术预研结论	技术团队	技术可行性边界

产出物

产出	格式	说明	对应文件
功能需求文档 (FRD)	Markdown	全模块功能规格说明	docs/design/01-功能需求文档.md
模块清单与优先级	Markdown 表格	按 P0/P1/P2 分级的完整模块列表	docs/design/01-功能需求文档.md
非功能性需求	Markdown 章节	性能指标、兼容性矩阵、安全要求	docs/design/01-功能需求文档.md
核心架构模式	Markdown	架构模式选择与理由	docs/design/29-核心架构模式设计.md
能力缺口分析	Markdown	与高端 CAD 的差距	docs/design/15-能力缺口分析.md

功能需求文档结构模板

# {项目名} 功能需求文档

## 1. Shell 微内核（必做）
### 1.1 插件管理器
- 功能描述：发现 plugins/ 目录下的合法插件、解析 manifest.json、依赖排序、加载/卸载 DLL/SO/DYLIB
- 输入：插件搜索路径列表
- 输出：已加载插件列表、加载失败原因
- 交互流程：启动→扫描→解析 manifest→依赖拓扑排序→逐插件 load→调用 initialize()
- 异常处理：manifest 无效 → 跳过并日志；缺少依赖 → 跳过；初始化失败 → 标记 LoadFailed

### 1.2 事件总线
- 功能描述：线程安全的发布/订阅事件系统，插件间解耦通信
- 事件类型：文档打开/关闭、选择变更、实体重建、业务对象模式进入/退出等
- 订阅方式：template<T> subscribe(handler) 返回 SubscriptionId
- 线程安全：publish 内部加锁，回调在发布线程执行

### 1.3 命令服务
- 功能描述：统一命令注册、查找、执行入口，支持命令灰显/可用性检查
- 命令命名规范：cmd.{模块}.{操作}（如 cmd.{模块}.{操作}）
- Undo/Redo：每个命令返回 {撤销数据}，命令服务管理 Undo 栈

## 2. 核心业务逻辑 (P0)
## 3. 高级业务逻辑 (P1)
## 4. 数据分析 (P1-P2)
## 5. 业务扩展 (P2)
## ...

非功能性需求模板

类别	指标	目标值	测量方式
渲染性能	100 万面场景帧率	>30fps	Benchmark CI
业务对象求解	100+ 业务计算	<100ms	Benchmark CI
文件导入	500MB 大文件导入	<30s	Benchmark CI
冷启动	5 插件加载	<5s	启动计时
兼容性	操作系统	{桌面OS A}, {桌面OS B}, {桌面OS C}	CI 多平台矩阵
安全性	文件解析	模糊测试通过、无 CVE	{模糊测试A} + {安全扫描A}
国际化	语言支持	至少中英双语	i18n 框架

检查清单

• 每个功能模块均有：功能描述、输入/输出、交互流程、异常处理定义
• 模块按 P0/P1/P2/P3 分了优先级
• 模块间依赖关系已标注（A 依赖 B/C）
• 非功能需求有具体可量化的指标
• 插件的 manifest 字段定义完整（uid/name/version/dependencies/entry/minShellVersion）
• 与竞品的功能覆盖率对比已完成

---

---

2.1 需求变更管理

目标

建立正式的变更控制流程，确保需求变更经过充分评估和审批，避免范围蔓延和非受控变更导致的项目风险。

为什么需要独立管理

需求变更不是代码变更（后者在 P8 管理），也不仅是文档修订（后者在 PM 章管理）。需求变更直接影响商业价值、交付时间和资源分配，需要独立的决策机制。

变更控制委员会 (CCB)

组成：产品负责人 + 技术负责人 + 至少 1 名核心开发者（根据变更影响的领域轮换）

决策规则：

变更等级	审批人	最大响应时间
P0 - 紧急（阻塞发布/安全）	技术负责人直批，事后通知 CCB	4h
P1 - 重大（影响里程碑或架构）	CCB 全体同意	3 个工作日
P2 - 中等（影响单个模块工期）	产品负责人 + 技术负责人	5 个工作日
P3 - 轻微（不改变工期和架构）	产品负责人直批	不设限制

变更影响评估模板

# CR-{编号}: {变更简述}

## 变更来源
- 提出人: @username
- 来源: Bug / {业务单元} Request / 用户反馈 / 管理层决策
- 关联 FRD 条目: D-100 § {章节号}

## 变更内容
- 当前定义: {现状描述}
- 期望定义: {变更后描述}

## 四维影响评估

| 维度 | 影响程度 | 说明 |
|------|---------|------|
| 技术 | 高/中/低/无 | {是否需要架构调整、接口变更、数据迁移} |
| 进度 | ±N 人天 | {对当前 Sprint 和里程碑的影响} |
| 成本 | ¥/人天 | {额外资源需求} |
| 风险 | 高/中/低 | {引入的新风险或技术债务} |

## 下游影响清单
- [ ] D-XXX FRD §X.X（源文件更新）
- [ ] D-XXX MIDL（接口变更）
- [ ] D-XXX DM（数据模型变更）
- [ ] D-XXX TCS（测试用例更新）
- [ ] 受影响插件: xxx, yyy
- [ ] 受影响 milestone: M-N

## 决策
- [ ] 接受（排入当前 Sprint）
- [ ] 推迟（排入下一 Sprint / 下一 Phase）
- [ ] 拒绝（原因: ___）
- 审批人签名: ___
- 日期: ___

变更流程

变更提出 → 自动分类(按影响范围) → CCB 评审（按等级路由）
           ├─ P0: 技术负责人直批 → 执行 → 事后补评估
           ├─ P1: CCB 全体评审 → 通过 → 更新 FRD → 级联更新下游 → 排入 Sprint
           ├─ P2: 产品+技术评审 → 通过 → 更新 FRD → 通知下游
           └─ P3: 产品直批 → 更新 FRD → 记录变更

需求冻结窗口

时间节点	冻结级别	允许的变更类型
Sprint 开始后	{业务单元} Freeze	仅 P0/P1 Bug 修复
发布前 1 周	Code Freeze	仅 P0 Bug 修复
正式发布后	全冻结	仅 Hotfix

变更追踪文件

# 变更记录文件: docs/specs/CHANGE_LOG.md

| CR编号 | 日期 | 提出人 | FRD章节 | 变更类型 | 影响等级 | 决策 | 状态 |
|--------|------|--------|---------|---------|---------|------|------|
| CR-001 | 2026-01-20 | @zhangsan | §2.3 | 功能新增 | P2 | 接受 | ✅ 已实现 |
| CR-002 | 2026-02-01 | @lisi | §3.1 | 接口变更 | P1 | 推迟 | 🟡 排入 v0.3 |

检查清单

• CCB 成员已确定，决策规则已公示
• 变更影响评估模板覆盖技术/进度/成本/风险四维
• 下游影响清单自动关联 FRD→MIDL→DM→TCS 依赖链
• 需求冻结窗口已定义并与 P8 发布流程对齐
• 变更记录文件已建立，所有变更可追溯
• P0 紧急变更通道已建立（事后补流程，不阻塞响应）

---

---

3. 系统架构设计

关联文档: docs/design/02-系统架构与技术选型.md | docs/design/05-UI设计方案.md | docs/design/09-API与通信协议设计.md | docs/design/10-安全架构设计.md | docs/design/13-性能与扩展性设计.md | docs/design/29-核心架构模式设计.md

目标

确定系统整体架构、技术栈选型、关键技术决策，输出可供开发团队并行工作的架构蓝图。

输入物

输入	来源	说明
功能需求文档 (FRD)	P1 产出	全模块功能清单与优先级
竞品技术架构分析	技术团队	竞品的技术栈与架构模式
技术预研 PoC	技术团队	核心引擎可行性验证

产出物

产出	格式	说明	对应文件
系统架构文档	Markdown + 架构图	总体分层架构、组件关系、数据流	docs/design/02-系统架构与技术选型.md
UI 设计方案	Markdown	界面架构、扩展点、菜单/工具栏/面板注册 API	docs/design/05-UI设计方案.md
API 与通信协议	Markdown	Shell 内部 API、REST API、EventBus	docs/design/09-API与通信协议设计.md
安全架构	Markdown	威胁模型、5 层安全架构	docs/design/10-安全架构设计.md
性能与扩展性	Markdown	性能目标、渲染管线、多线程	docs/design/13-性能与扩展性设计.md
数据模型设计	Markdown + UML	实体定义、层级关系、原生文件格式	docs/design/04-数据模型设计.md
插件 SDK 规范	Markdown	manifest.json、核心 API	docs/design/06-插件SDK与开发规范.md
核心架构模式	Markdown	Command/FeatureDependency/TopologicalNaming	docs/design/29-核心架构模式设计.md
补充设计要点	Markdown	日志/错误处理/配置管理/备份	docs/design/30-补充设计要点.md
项目目录结构	Markdown	Shell / SDK / Plugins / Tests / Docs 布局	docs/design/02-系统架构与技术选型.md
开发计划	Markdown	Phase 0-4 路线图、196 任务分解	docs/design/03-开发计划与里程碑.md

架构分层模板

┌──────────────────────────────────────────────────────────────┐
│                    {项目名} Shell (微内核宿主)                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │ {插件管理器} │ {事件总线} │ Command/Undo │ {扩展注册表}│
│  └────────────────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────────────────┤
│                      N 个独立功能插件                          │
│  ┌─────────┐┌─────────┐┌─────────┐┌─────────┐              │
│  │ P0 核心  ││ P1 高级  ││ P2 扩展  ││ P3 生态  │              │
│  └─────────┘└─────────┘└─────────┘└─────────┘              │
├──────────────────────────────────────────────────────────────┤
│                        内核引擎层                              │
│  ┌──────────┐┌──────────┐┌──────────┐┌──────────┐          │
│  │ 核心引擎1 ││ 核心引擎2 ││ 渲染后端  ││ 数据交换  │          │
│  └──────────┘└──────────┘└──────────┘└──────────┘          │
└──────────────────────────────────────────────────────────────┘

技术选型决策表模板

决策点	选择	理由	备选	风险
编程语言	C++20 + Python 3.11	性能关键路径 C++，脚本/工具链 Python	Rust	C++ 人才稀缺
构建系统	{构建工具} 3.28+ + {构建后端} + {包管理器}	跨平台、声明式依赖、可重现构建	Bazel	学习曲线
UI 框架	{UI框架} 6.8	跨平台原生 UI，工业级成熟度	Electron	包体积大
渲染引擎	{渲染引擎}	跨平台（D3D11/Metal/Vulkan），轻量	OpenGL 直接	抽象层额外开销
依赖管理	{包管理器} + manifest 模式	声明式、可锁定版本、CI 友好	Conan	包生态
AI 模型	{AI模型A} / {AI模型B} 本地+云端混合	开源自部署、离线可用	{AI模型厂商} API only	本地推理硬件要求
许可证策略	{许可证A}（开源）+ 企业订阅	防止云厂商白嫖，企业付费	MIT	企业接受度

技术选型决策记录 (ADR) 模板

# ADR-001: 选择 {核心引擎库} 作为核心引擎

## 状态
已通过

## 背景
需要 核心数据结构 核心引擎支持结构化业务逻辑、核心运算、标准格式导入导出

## 选项
1. {核心引擎库名} ({核心引擎库}) - {许可证D} 2.1，开源，完整 核心数据结构 内核
2. {商业引擎库} - 商业授权，{商业产品A}/{商业产品B} 内核
3. 自研 - 完全自主可控

## 决策
选择 {核心引擎库}

## 理由
- 开源许可无前期成本
- 完整 核心数据结构 + {标准格式A}/{标准格式B} 支持
- 活跃社区与商业支持 ({核心引擎厂商})
- 选择 2 成本不可接受，选择 3 时间不可接受

## 后果
- 需要处理 {核心引擎库} 边界条件下的核心运算失败
- 需要实现自有实体命名机制
- 需要建立回归测试数据集

检查清单

• 架构分层清晰（宿主壳 → 插件层 → 内核引擎层）
• 每个重大技术决策都有 ADR 记录（理由 + 后果）
• 插件间通信机制已定义（事件总线、命令服务、文档服务）
• 扩展点注册机制覆盖：菜单/工具栏/面板/命令/文件格式/属性页/快捷键
• {许可证E} 依赖已确认隔离策略（独立进程 CLI 调用）
• 跨平台矩阵已定义（OS / 编译器 / 渲染后端）
• 目录结构遵循单体仓库最佳实践（cmake/, sdk/, src/, plugins/, tests/, docs/, tools/）
• 线程安全模型已定义（主线程 UI / Worker Pool 业务数据 / 事件总线线程安全）

---

---

3.1 API 版本管理

目标

定义接口（API/MIDL/公共头文件）的版本演进规则、Breaking Change 判定标准和废弃（Deprecation）流程，确保接口变更的可预期性和向后兼容。

核心原则

1. 接口版本与产品版本解耦：接口版本独立演进，不受营销版本号约束
2. 向后兼容优先：新版本接口应兼容旧版本调用方
3. 有计划的废弃：任何接口移除必须经过"标注→警告→移除"三步流程

API 版本号规范

格式: API v{MAJOR}.{MINOR}

MAJOR: 不兼容的 Breaking Change（如参数类型变更、返回值结构变更）
MINOR: 向后兼容的新增（如新增可选参数、新增命令、新增事件）

示例:
  API v1.0 → v1.1: 新增 cmd.module.newOp 命令（兼容）
  API v1.1 → v2.0: 修改 cmd.module.op 返回值类型（不兼容）

Breaking Change 判定标准

以下变更视为 Breaking Change（需增加 MAJOR 版本）：

• 删除或重命名公共 API（函数/类/方法/命令/事件）
• 修改函数签名（参数类型、参数顺序、返回值类型）
• 修改数据模型字段类型
• 修改枚举值（删除/重命名/重编号）
• 收紧约束条件（原来可空变不可空、原来可选变必填）
• 修改错误码含义
• 改变默认行为

以下变更不视为 Breaking Change：

• 新增函数/类/命令/事件
• 新增可选参数（提供默认值）
• 新增枚举值（不改变已有值）
• 放宽约束条件（必填变可选、新增合法输入值）
• 修正 Bug（即使改变了行为，只要原行为是错误）
• 性能优化（不改变语义）

Deprecation 流程

Step 1: 标注废弃（版本 vN）
  - 在文档中添加 @deprecated 注释
  - 在代码中标记 [[deprecated]] 属性
  - 编译时产生警告（不阻断编译）
  - 更新 MIDL 文件，标注废弃原因和替代方案

Step 2: 警告期（至少 2 个 Minor 版本或 6 个月）
  - 发送废弃通知给所有已知下游消费者
  - 提供迁移指南和自动化迁移工具（如可能）
  - 在 CHANGELOG 中高亮标注

Step 3: 移除（版本 vN+2 或 6 个月后）
  - 从 MIDL 中删除接口定义
  - 从代码中删除实现
  - 大版本升级时彻底清理

Deprecation 标注模板

# MIDL 中的废弃标注
commands:
  - name: "cmd.module.oldOp"
    description: "DEPRECATED since v1.5 - Use cmd.module.newOp instead"
    deprecated: true
    deprecated_since: "1.5.0"
    removal_version: "2.0.0"
    migration_guide: "docs/migration/oldOp-to-newOp.md"
    parameters:
      - name: "param_a"
        type: "string"

// C++ 代码中的废弃标注
[[deprecated("Since v1.5. Use Module::NewOp() instead. Will be removed in v2.0.")]]
{命令结果} OldOp(const std::string& param_a);

向后兼容承诺矩阵

承诺项	承诺范围	例外
源码兼容 (Source)	MINOR 版本内兼容	无
二进制兼容 (ABI)	PATCH 版本内兼容	安全修复
插件兼容	MAJOR 版本内兼容	安全/合规
文件格式兼容	永久兼容（新版本可读旧文件）	无

检查清单

• API 版本号独立于产品版本号管理
• Breaking Change 判定标准已公示并写入编码规范
• 所有公共 API 在 MIDL 中有对应声明
• CI 中运行 API 兼容性检查（对比当前版本 vs 上一版本 MIDL）
• 废弃接口有明确的替代方案和迁移指南
• CHANGELOG 区分 API Breaking Changes 和普通功能变更

---

---

4. 数据模型设计

关联文档: docs/design/04-数据模型设计.md | docs/design/02-系统架构与技术选型.md（项目目录结构）

目标

定义系统的核心数据结构、层级关系、持久化格式、跨模块数据流，确保所有插件对数据有一致理解。

输入物

输入	来源	说明
功能需求文档	P1 产出	功能所需的数据实体
系统架构文档	P2 产出	数据流向与组件关系
领域模型分析	领域专家	行业标准数据规范

产出物

产出	格式	说明	对应文件
核心数据模型	Markdown + UML	实体定义、层级关系、字段说明	docs/design/04-数据模型设计.md
原生文件格式	Markdown	项目原生文件格式的二进制/JSON 结构	docs/design/04-数据模型设计.md
数据库 Schema	SQL / Markdown	云服务数据表设计	docs/design/04-数据模型设计.md
数据流场景	Markdown	典型业务流程的数据流转	docs/design/04-数据模型设计.md

核心数据模型层级模板

Application
 └── Document[]
      ├── uid: UUID
      ├── name: string
      ├── filePath: string
      ├── units: UnitSystem (mm/inch/m)
      ├── layers: Layer[]
      ├── metadatas: Metadata[]
      ├── parts: Part[]
      ├── aggregates: {聚合实体}[]
      └── {输出模块}s: {输出模块}[]

Part
├── uid: UUID
├── name: string
├── children: {子实体}[]
├── sub_entities: {子实体类型B}[]
├── referenceGeometry: {引用几何}[]
├── metadata: Metadata (ref)
└── customProperties: Map<string, Variant>

{子实体}（子实体）
├── uid: UUID
├── name: string
├── features: Feature[]              # 操作历史列表（有序，设计意图链）
├── shape: {核心形状}              # 最终业务数据形状（派生，由 {业务单元} DAG 计算）
└── tip: {业务单元}                     # 当前末端特征

Feature（业务单元 - 设计历史节点，抽象基类）
├── uid: UUID
├── name: string
├── type: {业务单元}类型 (enum)
├── status: {业务单元}状态 (Valid/Invalid/Warning)
├── previousShape: Shape
├── resultingShape: Shape
└── parameters: {业务单元}参数
    ├── 基础类型: {类型A}/{类型B}/{类型C}/{类型D}
    ├── 业务对象驱动: {操作A}/{操作B}/{操作C}/{操作D}/{操作E}
    ├── 修饰类型: {修饰A}/{修饰B}/{修饰C}/{修饰D}/{修饰E}
    ├── 变换类型: {变换A}/{变换B}/{变换C}
    └── 组合类型: {组合A}/{组合B}/{组合C}

数据流关键场景

场景1: 用户操作 → 数据变更 → 视图更新
  用户操作 → Command 对象 → 修改 Document 数据模型
      ├→ Entity Graph 增量重算 → 更新 Data
      └→ {事件总线} 发布事件
          ├→ UI插件: 更新显示
          ├→ 详情面板: 更新属性
          ├→ 导航树: 更新结构
          └→ AI 插件: 感知上下文变化

场景2: 文件保存/加载 (往返测试)
  内存模型 → serialize → 原生格式 (.{原生格式}) → deserialize → 内存模型
  验证: 核心属性值前后一致

命名与标识规范

元素	格式	示例
实体 UID	UUID v4	550e8400-e29b-41d4-a716-446655440000
命令名	cmd.{模块}.{操作}	cmd.{模块}.{操作}
事件名	PascalCase + Event 后缀	SelectionChangedEvent
约束名	字母+数字	D1, R5, H10

检查清单

• 核心实体层级清晰（Document → Part → {子实体} → Feature）
• 每个实体定义了 uid/name/type/status 核心字段
• 实体采用 DAG 而非简单列表（允许多父特征聚合）
• 原生文件格式支持完整语义保存（操作树 + 规则 + 元数据 + 自定义属性）
• 文件 I/O 往返测试已列入计划（保存→重载→业务数据属性对比）
• 实体间引用采用 UID 而非裸指针（支持持久化）
• 数据模型预留了扩展字段（customProperties: Map<string, Variant>）

---

---

4.1 数据迁移与回滚

目标

建立数据模型变更时的迁移（Migration）机制，确保数据库/文件格式/持久化数据的结构变更可追溯、可逆、可自动执行。

核心原则

1. 一切 Migration 必须可逆：每个 Migration 必须有对应的 Down 脚本（回滚）
2. Migration 必须幂等：多次执行同一 Migration 不会产生错误或重复效果
3. Migration 先于代码部署：数据库/存储结构变更必须在应用代码变更之前完成
4. 禁止手动修改生产数据库结构：所有 DDL 变更必须通过 Migration 系统执行

Migration 脚本规范

-- Migration: V{序号}__{描述}.sql
-- 示例: V003__add_column_status_to_orders.sql

-- ======== UP ========
-- 此脚本在生产环境执行前，必须在 Staging 环境验证通过
ALTER TABLE orders ADD COLUMN status VARCHAR(32) NOT NULL DEFAULT 'pending';
CREATE INDEX idx_orders_status ON orders(status);

-- ======== DOWN ========
-- 紧急回滚时执行此段
-- DROP INDEX idx_orders_status;
-- ALTER TABLE orders DROP COLUMN status;

命名规范：V{YYYYMMDDHHmm}_{描述}.sql 或 V{序号}__{描述}.sql

回滚策略分类

回滚类型	适用场景	实施方式	RTO
向前回滚 (Roll-forward)	数据不兼容，无法简单回退	编写新 Migration 修正错误	30min
向后回滚 (Roll-back)	数据兼容，可恢复到上一版本	执行 Down 脚本	10min
数据快照回滚	数据已损坏，Migration 不可逆	从备份恢复 + 重放部分 Migration	2h
全量恢复	灾难性故障	从最新备份恢复	4h（按 RTO 目标）

大表在线迁移方案

对于生产环境中包含海量数据的表结构变更（如亿级别行），不允许锁表操作：

方案	工具	适用数据库
Online DDL	pt-online-schema-change	MySQL/Percona
渐进式 Migration	gh-ost	MySQL
零停机迁移	pg_repack	{数据库A}
逻辑复制切换	双写 + 数据回填	任何数据库

大表迁移检查清单：

• 迁移脚本已在等比例数据量的 Staging 环境测试
• 预估执行时间 < 维护窗口
• Lock timeout 已设置合理值
• 监控告警已配置（长事务检测）
• 回滚方案已就绪

文件格式迁移

对于自定义文件格式的版本升级：

策略: 读取时自动检测版本 → 优先使用新版 Parser → 降级到旧版 Parser → 提示用户升级

实现:
  FileVersion readVersion = DetectVersion(fileHeader);
  if (readVersion == kLatest) {
    return ParseV2(file);
  } else if (readVersion == kV1) {
    auto data = ParseV1(file);
    return MigrateV1toV2(data);  // 内存中转换
  } else {
    return Error("Unsupported file version");
  }

Migration 执行流程

开发环境: 开发者本地执行 → CI 自动验证 UP/DOWN
         ↓
Staging: 自动执行（部署流水线） → 验证数据完整性
         ↓
生产环境: 人工审批 → 维护窗口内执行 → 监控 → 确认 → 关闭窗口
         ↓  (如失败)
         自动执行 Down 脚本 → 告警 → 复盘

检查清单

• 所有 Migration 有对应的 Down 脚本（可回滚）
• Migration 在 CI 中自动执行 UP + DOWN 往返测试
• 大表变更使用在线迁移工具（不锁表）
• 生产 Migration 执行前有备份（数据库 / 文件存储）
• 文件格式支持自动版本检测和兼容读取
• Migration 失败自动告警并回滚，不在无人值守时阻塞
• 迁移脚本和回滚脚本在 Staging 环境预演通过

---

---

5. 开发计划

关联文档: docs/design/03-开发计划与里程碑.md | docs/plan/{Phase名}-执行计划.md | docs/design/31-开发进度跟踪.md

目标

将项目分解为多个 Phase，每个 Phase 有明确的里程碑 (Milestone)、团队规模、任务分解和验收标准，形成可执行的路线图。

输入物

输入	来源	说明
功能需求文档 (FRD)	P1 产出	模块清单与优先级
系统架构文档	P2 产出	技术依赖与构建顺序
团队资源评估	管理层	可用人力和时间约束

产出物

产出	格式	说明	对应文件
长期路线图	Markdown	Phase 0-4 宏观里程碑	docs/design/03-开发计划与里程碑.md
Phase 1 执行计划	Markdown	11 阶段 × 196 任务、依赖图	docs/plan/{Phase名}-执行计划.md
进度跟踪看板	Markdown	项目仪表盘、Phase 进度	docs/design/31-开发进度跟踪.md
计划方法论	Markdown	DDD 驱动的计划方法	docs/plan/README.md

Phase 路线图模板

Year 1              Year 2              Year 3              Year 4+
├──────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┤
│Phase0│Phase1 │ Phase2             │ Phase3              │ Phase4│
│ 基础  │核心能力│ 高级功能+扩展       │ 全面落地+AI         │ 云+生态│
│ M0   │M1:v0.1│ M2:v0.5 Alpha      │ M3:v1.0 Beta       │M4:v2.0│

Phase 定义

Phase	名称	周期	团队	目标	里程碑
0	微内核 + 插件框架	2-3 个月	2-3 人	空白宿主壳，插件加载能力，2 个验证插件	可启动空壳
1	核心功能	4-6 个月	4-7 人	核心功能可用，覆盖 P0 插件	v0.1 MVP
2	高级功能	6-8 个月	6-10 人	高级功能 + 扩展模块	v0.5 Alpha
3	全面落地	8-10 个月	10-13 人	制造 + 行业 + AI 全面落地	v1.0 Beta
4	云生态 + 持续迭代	持续	6-11 人	云协同 + 移动端 + 完整生态	v2.0 GA

当前进度快照（通用模板）

使用方式：AI 执行时读取 docs/design/31-开发进度跟踪.md 获取最新进度。以下为模板格式，新建项目时填入实际数据。

Phase	状态	完成率	已完成/总任务	下一步行动
Phase 0	✅ 已完成	100%	{n}/{n}	—
Phase 1	🔵 进行中	{x}%	{m}/{n}	{具体行动}
Phase 2	⚪ 待启动	0%	—	等待 Phase 1 完成
...	...	...	...	...

状态图例：✅ 已完成 | 🔵 进行中 | ⚪ 待启动 | 🔴 阻塞 | ⚪ 跳过

Phase 执行计划模板

每个 Phase 的详细执行计划应包含：

# Phase N 执行计划

## 1. 并行开发组划分
A组 - 领域A: 插件1, 插件2, ...
B组 - 领域B: 插件3, 插件4, ...
...

## 2. 阶段分解 (Stage 1-N)
每个 Stage 包含:
- 任务 ID + 名称
- 人天估算
- 前置依赖 (Stage/任务)
- 核心交付物
- 验收标准

## 3. 依赖图
Stage 1 → Stage 2 → Stage 3
              ↘ Stage 4 (可与 3 并行)

## 4. 里程碑检查点
M-N: {名称}
- [ ] 验收项1
- [ ] 验收项2

## 5. 总计
总人天: XXX | 并行小组: N 个 | 预计周期: X 个月

里程碑准出条件模板

检查项	标准	验证方式
功能完成度	本阶段计划插件 100% 通过验收	端到端设计工作流测试
测试覆盖率	核心业务逻辑 >80% 行覆盖率	{覆盖率工具A}/{覆盖率工具B} 报告
性能指标	所有基准测试不低于目标值	Benchmark CI
跨平台构建	三平台 (Win/Mac/Linux) 编译零警告零错误	CI 矩阵
Bug 清零	无 P0/P1 级未解决 Issue	Issue Tracker
文档就绪	API 文档 + 用户手册更新	文档审查

检查清单

• 路线图覆盖至少 3-4 年，每个 Phase 有明确的里程碑
• 各 Phase 的任务分解粒度合理（每任务 1-15 人天）
• 并行小组划分避免了资源冲突
• 依赖图标注了 Stage 间的串行/并行关系
• 每个里程碑有可量化、可验证的准出条件
• 团队规划与实际资源匹配（未过度承诺）

---

---

6. 编码规范

关联文档: docs/design/16-编码规范与代码风格指南.md | docs/design/06-插件SDK与开发规范.md

目标

建立统一的编码规范、代码风格、错误处理范式、内存管理策略，确保多人协作时代码质量一致、可维护。

输入物

输入	来源	说明
技术选型	P2 产出	编程语言、编译器版本
团队经验	团队	现有代码风格与偏好

产出物

产出	格式	说明	对应文件
编码规范文档	Markdown	命名/格式/注释/头文件/类/错误处理/内存管理	docs/design/16-编码规范与代码风格指南.md
插件 SDK 规范	Markdown	manifest.json、核心 API、开发模板	docs/design/06-插件SDK与开发规范.md
测试策略	Markdown	测试金字塔、CAD 领域测试、性能基准	docs/design/12-测试策略.md
国际化方案	Markdown	语言优先级、Qt TS 翻译、RTL 支持	docs/design/21-多语言国际化方案.md
无障碍设计	Markdown	WCAG 2.1 AA、键盘导航	docs/design/28-无障碍可访问性设计.md

编码规范核心内容

命名规范

元素	风格	示例
命名空间	snake_case	project::core, project::module
类/结构体	PascalCase	{插件管理器}, DocumentService
接口 (I 前缀)	IPascalCase	{插件接口}, IDocumentService
枚举类型	PascalCase	{业务单元}类型, ErrorCode
枚举值	kPascalCase	k{操作A}, k{操作B}
函数/方法	PascalCase	LoadPlugin(), GetDocument()
变量 (局部/成员)	snake_case	plugin_count, is_loaded
私有成员变量	snake_case_（尾下划线）	plugin_map_, is_running_
常量/constexpr	kPascalCase	kMaxPlugins, kDefaultTimeout
宏	UPPER_SNAKE_CASE	{项目前缀}_ASSERT, {项目前缀}_VERSION_MAJOR
文件名	snake_case	plugin_manager.cpp

注释规范

// 文件头注释（必须）
//===--------------------------------------------------------------===//
//  {项目名} - 一句话描述
//
//  File:        plugin_manager.h
//  Description: 核心插件生命周期管理器
//  Author:      {name} <{email}>
//  Created:     YYYY-MM-DD
//  License:     {license}
//===--------------------------------------------------------------===//

// 公共 API 必须注释（做什么、参数、返回值、异常）
/// Manages the lifecycle of all plugins.
///
/// @param search_paths  Directories to scan for plugins
/// @return  List of valid plugin manifests found
/// @throws  std::filesystem_error  if a path is invalid
std::vector<{插件清单}> DiscoverPlugins(
    const std::vector<std::filesystem::path>& search_paths);

// TODO/FIXME/HACK 必须带负责人
// TODO(zhangsan): Replace linear search with hash map when plugin count > 100
// FIXME(lisi): Memory leak when unloading plugin with active subscriptions

错误处理策略

场景	方式	说明
编程错误（断言失败）	assert / {项目前缀}_ASSERT	立即崩溃，CI 中暴露
可恢复错误	std::expected<T, E> (C++23) 或自定义 Result<T, E>	调用方必须处理
不可恢复错误	抛异常	核心引擎异常等
构造函数失败	工厂方法 + optional 或抛异常	构造函数本身不应失败

内存管理铁律

禁止	替代方案
裸 new / delete	std::make_unique / std::make_shared
NULL / 0 表示空指针	nullptr
C 风格类型转换 (int)x	static_cast / dynamic_cast
using namespace std; (头文件)	显式 std:: 前缀
全局变量	封装在类/命名空间中
C 风格数组 int arr[10]	std::array<int, 10>
魔法数字	命名常量或 constexpr
goto	结构化控制流

Python 编码规范（如项目含 Python）

• 遵循 PEP 8，用 Black 自动格式化（line-length=100）
• isort 排序 import，mypy 类型检查（严格模式）
• 命名: 类 PascalCase，函数/变量 snake_case，常量 UPPER_SNAKE
• 私有成员前缀 _，类型注解强制

工具链配置

# C++ 格式化（CI 阻断）
{格式化工具} --style=file --dry-run -Werror

# 静态分析（CI 阻断）
{静态分析工具} --checks='bugprone-*,modernize-*,performance-*,readability-*,cppcoreguidelines-*'

# Python 格式化（CI 阻断）
black --check --line-length 100 .
isort --check-only .

# 编译器警告（CI 阻断）
# MSVC: /W4 /WX
# GCC/Clang: -Wall -Wextra -Wpedantic -Werror

检查清单

• 命名规范覆盖所有语言元素（命名空间/类/函数/变量/常量/枚举/宏/文件）
• 代码格式有自动化工具保障（{格式化工具} / black）
• 静态分析已集成到 CI 门禁（{静态分析工具} / mypy）
• 注释规范区分了强制/推荐/建议三级
• 错误处理策略覆盖了断言/Result/异常三种场景
• 禁止事项清单明确（裸 new/delete、C 风格转换、魔法数字、goto 等）
• 编译器警告视为错误 (-Werror)
• 有快速检查清单供开发者在提交前自查

---

---

6.1 国际化规范

目标

建立从代码编写到翻译交付的完整国际化工作流，确保产品可以低摩擦地支持多语言。

核心原则

1. 代码中禁止硬编码用户可见字符串：所有面向用户的文本必须通过 i18n 框架获取
2. 开发和UI语言分离：开发使用英文 Key，翻译文件提供各语言文本
3. 翻译先于发布：Translation Freeze 早于 Code Freeze（给翻译团队留出时间）
4. 上下文即注释：每个翻译 Key 必须附带上下文说明（在哪里显示、什么用途）

字符串外置规范

// ❌ 禁止: 硬编码字符串
label->setText("打开文件");
errorMessage("文件格式不支持");

// ✅ 正确: 使用 i18n Key
label->setText(tr("menu.file.open"));  // {UI框架} 方式
errorMessage(i18n::Get("error.io.format_unsupported"));

翻译 Key 命名规范：{域}.{组件}.{含义}

域	说明	示例 Key
menu.	菜单项	menu.file.open
dialog.	对话框标题和内容	dialog.export.format_select
error.	错误消息	error.io.file_not_found
status.	状态栏	status.solver.running
tooltip.	工具提示	tooltip.cmd.extrude.distance
unit.	单位	unit.mm, unit.inch

翻译文件格式

// en.json — 源语言（始终完整，由开发者维护）
{
  "menu.file.open": "Open File...",
  "menu.file.save": "Save",
  "error.io.file_not_found": "File not found: {path}",
  "error.io.format_unsupported": "Unsupported file format: {format}",
  "dialog.about.version": "Version {version}",
  "unit.mm": "mm",
  "unit.inch": "in"
}

// zh-CN.json — 翻译（由翻译团队/翻译平台维护）
{
  "menu.file.open": "打开文件...",
  "menu.file.save": "保存",
  "error.io.file_not_found": "找不到文件: {path}",
  "error.io.format_unsupported": "不支持的文件格式: {format}",
  "dialog.about.version": "版本 {version}",
  "unit.mm": "毫米",
  "unit.inch": "英寸"
}

特殊处理规则

场景	处理方式
带参数的字符串	使用命名占位符 {name}，禁止 %s %d
复数形式	使用 ICU MessageFormat: {count, plural, one {...} other {...}}
日期/时间	使用系统 Locale 格式化，不可硬编码格式
货币/数字	使用系统 Locale，不可假设小数点/千位分隔符
快捷键	平台相关（Ctrl vs Cmd），不可硬编码
缩写/专有名词	在翻译 Key 注释中标注不可翻译

翻译工作流

开发阶段:
 开发者修改代码 → 添加新的 tr() 调用 → 更新 en.json（源语言文件）

翻译阶段 (每个 Sprint 的翻译窗口):
 CI 检查 en.json 变更 → 自动提取新增 Key → 推送到翻译平台
 翻译团队/平台完成翻译 → CI 拉回各语言 json → PR Review

构建阶段:
 {构建工具} 中将 .json 编译为 .qm 或其他二进制格式
 打包时包含所有语言文件

翻译覆盖率检查

# CI 脚本: 对比各语言文件与 en.json 的 Key 涵盖率
python tools/check_i18n_coverage.py

# 输出示例:
# zh-CN: 245/250 keys (98.0%) — ⚠️ 5 keys missing
# ja:    230/250 keys (92.0%) — 🔴 20 keys missing, below threshold

CI 门禁：翻译覆盖率低于 95% 的语言 → 构建告警（不阻断），低于 90% → 阻断发布。

测试要求

• i18n 单元测试：验证所有 Key 在所有语言文件中存在
• 占位符一致性测试：验证 {name} 在翻译中未被删除或修改
• UI 截断测试：德语/俄语等长文本语言下的 UI 布局截图对比
• RTL 语言测试：如计划支持阿拉伯语/希伯来语，需 UI 镜像测试

检查清单

• 代码中无硬编码用户可见字符串（lint 规则检查）
• 翻译 Key 命名遵循 {域}.{组件}.{含义} 规范
• 所有 Key 在 en.json 中有上下文注释
• 带参数字符串使用命名占位符 {name}
• CI 检查翻译覆盖率，低于阈值阻断发布
• 翻译平台双向同步脚本就绪
• Translation Freeze 时间窗口早于 Code Freeze

---

---

7. 构建与环境

目标

建立可重现、跨平台、声明式的构建系统，降低新开发者入职门槛，确保 CI/CD 流水线一致性。

输入物

输入	来源	说明
技术选型	P2 产出	编译语言、目标平台、依赖库清单
第三方依赖清单	P2 产出	所有直接和间接依赖的版本与 License

产出物

产出	格式	说明	对应文件
构建系统架构	Markdown	CMake 结构、Target 依赖图	docs/design/02-系统架构与技术选型.md
供应链安全	Markdown	SBOM、依赖扫描、构建签名	docs/design/19-供应链安全方案.md
部署方案	Markdown	跨平台打包、CI/CD	docs/design/11-部署与运维方案.md

构建系统设计原则

1. 单体仓库 (单体仓库)：Shell + 所有官方插件在同一仓库
2. 声明式依赖：通过 {包管理器}.json 明确声明所有依赖及版本
3. 可重现构建：lockfile + 固定依赖版本
4. 增量编译：模块化 {构建工具} target，最小化重编译
5. 统一配置：所有插件共享编译选项、警告级别、静态分析规则

{构建工具} 项目结构

{项目名}/
├── {构建工具}Lists.txt                  # 根配置：全局选项、子目录索引
├── cmake/
│   ├── CompilerWarnings.cmake      # 警告级别配置
│   ├── StaticAnalyzers.cmake       # {静态分析工具}/cppcheck 集成
│   ├── InstallRules.cmake          # 安装规则
│   └── Packaging.cmake             # CPack 打包配置
├── {包管理器}.json                      # 根 manifest（公共依赖）
├── src/
│   └── shell/                      # Shell 入口 + 核心服务库
├── plugins/                        # 插件（每个独立 {构建工具} target）
│   ├── {项目前缀}-{示例插件}/
│   │   ├── {构建工具}Lists.txt
│   │   ├── {包管理器}.json              # 插件专属依赖(可选)
│   │   ├── src/
│   │   └── tests/
├── sdk/                            # 插件 SDK (header-only + 薄库)
├── tests/                          # 集成测试
├── tools/                          # 构建/发布脚本
└── docs/                           # 文档

Target 依赖图

{项目前缀}_shell (exe)
  ├── {项目前缀}_core (static lib)       ← 核心服务({插件管理器}/{事件总线}/{命令服务}...)
  │   ├── {UI框架}6::Core, {UI框架}6::Widgets
  │   └── {日志库}::{日志库}
  └── {项目前缀}_sdk (header-only)

{项目前缀}_plugin_xxx (shared plugin)
  ├── {项目前缀}_sdk                     ← 插件 SDK 接口
  ├── 领域引擎依赖
  └── 其他库...

第三方依赖清单模板

库	版本	用途	License	风险等级	隔离方式
核心库1	1.0+	核心功能	{许可证D}	低	动态链接
{许可证E}库	2.0+	辅助功能	{许可证E} 2	高	独立进程 CLI 调用
工具库	1.5+	工具	MIT	低	动态链接

{许可证E} 依赖隔离策略

● {许可证D} 依赖 ── 允许动态链接，无需开源
● {许可证E} 依赖  ── 独立进程，通过 CLI/文件通信 → 不触发 {许可证E} 传染

开发者入职路线

第 1 天:
  □ 完成环境搭建，成功编译运行
  □ 阅读功能需求文档 + 系统架构文档

第 2 天:
  □ 阅读编码规范 + 开发工作流文档
  □ 找一个 Good First Issue
  □ 提交第一个 PR

第 3-5 天:
  □ 熟悉当前 Phase 代码
  □ 认领一个功能模块

检查清单

• 构建系统支持三平台（Windows / Linux / macOS）
• {构建工具} Presets 覆盖开发/Debug/Release/CI 多种场景
• 所有第三方依赖在 {包管理器}.json 中声明，含版本约束
• {许可证E} 依赖有明确的隔离策略
• 编译器缓存已配置（ccache/sccache）
• 预编译头 (PCH) 已配置（加速编译）
• 开发者入职指南覆盖环境搭建/IDE 配置/首次构建/常见问题
• 有脚本化的一键构建与发布流程

---

---

7.1 多环境管理

目标

建立开发、测试、预发布和生产环境的标准管理体系，确保环境间配置隔离、数据安全，并实现环境的快速创建和销毁。

环境层级定义

环境	缩写	用途	数据来源	部署方式	谁可访问
Local	LCL	开发者本机开发调试	Mock / 本地数据库	手动	仅本人
Development	DEV	联调、功能验证	匿名化测试数据	自动 (每次合并到 develop)	开发团队
Test	TST	QA 测试、集成测试	匿名化测试数据	自动 (每次 release 分支)	QA + 开发
Staging	STG	预发布验证、性能测试	脱敏生产数据	手动触发	核心团队
Production	PRD	线上服务	真实数据	严格审批后手动	运维 + On-Call

核心铁律

❌ 禁止生产数据出现在非生产环境（未经脱敏）
❌ 禁止非生产环境访问生产服务（数据库/API/存储）
❌ 禁止跨环境配置混用
❌ 禁止在生产环境手动执行命令（通过 CI/CD 流水线）
✅ 所有环境通过代码（IaC）定义，{版本控制} 仓库中可审计
✅ 环境销毁后 24h 内可重建

配置管理策略

# 配置分层模型
配置来源（优先级从高到低）:
  1. 环境变量（敏感信息：密钥/密码/Token）
  2. 配置文件（环境特定参数：数据库地址/日志级别）
  3. 配置中心（动态配置：功能开关/限流阈值）
  4. 代码默认值（开发友好默认值）

配置文件的存放：

config/
├── defaults.yaml          # 所有环境的公共默认值
├── env/
│   ├── dev.yaml           # DEV 环境覆盖值
│   ├── tst.yaml           # TST 环境覆盖值
│   ├── stg.yaml           # STG 环境覆盖值
│   └── prd.yaml           # PRD 环境覆盖值（不含密钥）
└── secrets/               # .gitignore，密钥文件不入库
    ├── dev.env.example    # 示例文件（可入库，值为空）
    └── prd.env            # 生产密钥（仅运维可见）

环境同步策略

同步方向	频率	方式
DEV → TST	每次 release 分支合并	CI 自动部署
PRD → STG	每周一次	数据脱敏后导入
STG → TST	按需（大版本测试前）	手动触发

生产数据脱敏规则（用于导入 STG/TST）：

• 用户 PII（姓名/邮箱/手机）→ 替换为假数据或哈希
• 密码 → 替换为已知测试密码
• API Key/Token → 替换为无效值
• 业务数据 → 保留（用于真实测试），但金额等敏感字段需模糊化

环境创建与销毁

新环境创建模板：

# 一键创建新环境（通过 IaC）
make env-create NAME=perf-test ENV=stg TEMPLATE=stg

# 环境包含:
# - 计算资源（容器/VM）
# - 数据库（含初始 Schema + Migration）
# - 消息队列/缓存
# - DNS/负载均衡配置
# - 监控告警规则
# - 测试账号

环境自动回收：

• STG/TST 环境超过 7 天无活动 → 自动通知
• {业务单元} 分支环境在分支合并后 24h 自动销毁
• 长期保留的环境需标记 persistent: true

环境间隔离验证

# CI 自动检查: 验证环境隔离
tools/check_env_isolation.sh

# 检查项:
# 1. STG 是否能访问 PRD 数据库 → 必须拒绝
# 2. DEV 是否使用了 PRD API Key → 必须拒绝
# 3. 各环境日志是否混入生产数据 → 必须拒绝

检查清单

• 五层环境体系已建立（LCL → DEV → TST → STG → PRD）
• 所有环境通过 IaC 定义，{版本控制} 仓库可审计
• 敏感配置通过环境变量注入，不入库
• 生产数据脱敏脚本就绪（PRD → STG）
• 环境间网络隔离已验证（DEV 不能访问 PRD）
• 环境自动回收策略已生效
• 新成员入职 1 小时内可构建完整 DEV 环境

---

---

8. 测试策略

关联文档: docs/design/12-测试策略.md | docs/design/13-性能与扩展性设计.md（性能基准） | docs/design/19-供应链安全方案.md（安全测试）

目标

建立分层测试体系，确保代码质量和功能正确性，将测试融入开发流程和 CI/CD 流水线。

输入物

输入	来源	说明
功能需求文档	P1 产出	需验证的功能点
系统架构文档	P2 产出	测试隔离策略
编码规范	P5 产出	Mock 策略

产出物

产出	格式	说明	对应文件
测试策略	Markdown	测试金字塔、测试类型、工具链	docs/design/12-测试策略.md
性能基准	Markdown	性能目标、优化策略	docs/design/13-性能与扩展性设计.md
安全测试	Markdown	模糊测试、SAST/DAST	docs/design/19-供应链安全方案.md

测试金字塔

            ╱───────╲
           ╱   E2E   ╲          端到端测试: 全流程手动+自动 (10%)
          ╱─────────────╲
         ╱   Integration  ╲      集成测试: 多插件协作场景 (30%)
        ╱───────────────────╲
       ╱     Unit Tests       ╲   单元测试: 每插件独立 (60%)
      ╱─────────────────────────╲

单元测试规范

每个插件必须覆盖：

• 核心业务逻辑: 80% 行覆盖率
• 命令执行: 所有命令至少 1 个正向 + 1 个异常用例
• 数据序列化: 往返测试（serialize → deserialize → equals）
• 边界条件: 空输入、极值、null

框架与工具：

语言	框架	覆盖率工具
C++	{测试框架A} + {模拟框架}	{覆盖率工具A} / {覆盖率工具B}
Python	{测试框架B}	coverage.py
Qt/UI	{UI框架} Test	-

Mock 策略

// 插件单元测试使用 Mock 核心服务，无需启动 Shell
class PluginTest : public ::testing::Test {
protected:
    void SetUp() override {
        mockContext = std::make_unique<MockPluginContext>();
        mockDocService = std::make_unique<MockDocumentService>();

        ON_CALL(*mockContext, documentService())
            .WillByDefault(Return(mockDocService.get()));
    }
};

领域专项测试（按项目领域定制）

领域示例：

• 核心逻辑正确性验证：核心数据结构 拓扑一致性（isValid/isClosed/isSolid）、核心运算体积期望
• 算法正确性验证：确定性验证（相同输入 → 相同输出）、回归测试集（100+ 算法场景）
• 文件 I/O 往返测试：导出 → 重导入 → 比较业务数据属性（体积/面数/边界盒）
• 回归测试数据集：标准业务对象 JSON、标准特征参数、标准聚合实体、标准导入文件

性能基准测试

场景	目标	CI 门禁
场景A	<X ms	不比上次 commit 慢 >10%
场景B	>Y fps	不低于目标值
场景C	<Z s	不超过目标值 2x

跨平台测试矩阵

平台	OS	编译器	渲染后端
Windows	{桌面OS A}	{编译器A} 2022	D3D11/12
macOS	14+	{编译器C} 16	Metal
Linux	{桌面OS C}	{编译器B} 13	Vulkan/GL

安全测试

测试类型	工具
模糊测试（文件解析）	{模糊测试A} / {模糊测试B}
静态分析	{安全扫描A}, {静态分析工具}, {代码质量平台}
漏洞扫描	{漏洞扫描A}, {依赖监控}（依赖库 CVE）
渗透测试	每大版本手工渗透测试

CI/CD 测试流水线

PR 提交:
  ├─ 快速检查 (必须通过): lint, unit tests, affected plugin tests
  └─ 完整检查 (合并前): integration, performance benchmark, fuzz (nightly)

合并到 develop:
  └─ 全平台构建 + 全量测试 + 安全扫描 + 性能对比

发布前:
  └─ 手工 QA checklist + 跨平台冒烟测试

检查清单

• 测试金字塔比例合理（60% 单元 / 30% 集成 / 10% E2E）
• 每个插件有独立测试目录 + Mock 依赖
• 核心业务逻辑覆盖率目标 >80%
• 文件 I/O 往返测试覆盖所有支持格式
• 性能基准测试已集成 CI，不允许回退 >10%
• 跨平台测试矩阵覆盖所有目标平台
• 安全测试（模糊测试/静态分析/漏洞扫描）已纳入流水线
• CI 门禁分层：快速检查（PR）→ 完整检查（合并前）→ 发布前检查

---

---

9. 开发工作流

目标

定义团队协作的 {版本控制} 工作流、代码审查标准、发布管理流程，确保多人协作高效有序。

输入物

输入	来源	说明
团队规模与结构	管理层	并行小组数、成员角色
发布节奏要求	产品团队	迭代周期、用户期望

产出物

产出	格式	说明
开发工作流规范文档	Markdown	{版本控制} 分支策略、Commit 规范、PR 流程、Code Review 标准
PR 模板	Markdown	{代码托管平台} PR 描述模板
Issue 模板	Markdown	Bug / {业务单元} / Question 模板
发布管理流程	文档	版本号规范、发布检查清单、Changelog 规范
CI/CD 门禁规则	配置文件	各阶段自动检查规则

{版本控制} 分支策略（Trunk-Based Development 变体）

分支	用途	命名	合并到
main	生产稳定版	main	-
develop	开发主线	develop	main
feature/*	功能开发	feature/{核心模块}-line-tool	develop
fix/*	Bug 修复	fix/issue-1234-crash-on-import	develop
release/*	发布准备	release/0.2.0	main + develop
hotfix/*	紧急修复	hotfix/0.1.1-crash-fix	main + develop

Commit Message 规范

<type>(<scope>): <简短描述>

[可选的详细描述]

[Breaking Change 标注]

type: feat / fix / docs / style / refactor / perf / test / chore / ci

scope (项目特有): shell / {核心模块} / {业务模块} / {聚合模块} / {输出模块} / io / sdk / build / docs / tests

示例：

feat({核心模块}): add tangent constraint between arc and line
fix(io): resolve {标准格式} import crash on files with Chinese path (#1234)
refactor({业务模块}): extract {辅助单元}Builder from {业务单元} for reuse

Pull Request 流程

创建 {业务单元} 分支 → 开发 → 提交 Draft PR → CI 自动检查
  ↓
通过检查 → 标记 Ready for Review → 至少 1 人 Code Review
  ↓
Review 通过 → 合并到 develop → 删除 feature 分支

PR 规则：

• PR 大小限制：单 PR 不超过 500 行变更（超过则拆分）
• Draft PR 机制：开发初期创建 Draft PR 获取早期反馈
• PR 模板：描述（做了什么/为什么/怎么测试）、关联 Issue、检查清单

代码审查标准

维度	审查要点
正确性	逻辑是否正确、边界条件是否处理、错误处理是否完善
安全性	是否有注入风险、文件路径是否安全、内存是否正确管理
性能	是否有不必要的拷贝、算法复杂度是否合理
可维护性	命名是否清晰、是否有重复代码、是否符合 SOLID
测试	是否覆盖正向+异常用例、测试是否合理
规范	是否符合编码规范、{格式化工具}/{静态分析工具} 是否通过

评论标签：

• [nit]: 小问题（可修可不修）
• [blocking]: 必须修复才能合并
• [question]: 讨论性问题
• [suggestion]: 改进建议

发布管理流程

版本号: MAJOR.MINOR.PATCH（语义化版本）

• Patch (0.1.1): 每 2 周，Bug 修复 + 小改进
• Minor (0.2.0): 每 3 月，新功能 + API 兼容
• Major (1.0.0): 每 12 月，架构变更 / 里程碑

发布清单：

发布前 2 周:
  □ {业务单元} Freeze（不再接新功能）
  □ 代码冻结（只合 Bug 修复）
  □ 翻译冻结

发布前 1 周:
  □ RC 版本构建
  □ 社区 Beta 测试
  □ 更新 Changelog
  □ 更新文档 + 截图

发布日:
  □ 签名 + 上传 + 发布公告
  □ 社交媒体通知
  □ 邮件通知关键用户

检查清单

• {版本控制} 分支策略明确（分支类型/命名规则/合并目标）
• Commit Message 规范有 type + scope 枚举
• PR 模板覆盖"做了什么/为什么/怎么测试/关联 Issue"
• Code Review 标准覆盖 6 个维度
• CI 门禁自动化（lint → test → build → performance）
• 发布流程有明确的 {业务单元} Freeze / Code Freeze 时间窗口
• Bug/Feature/Question Issue 模板已创建

---

---

10. 部署运维

关联文档: docs/design/11-部署与运维方案.md | docs/design/19-供应链安全方案.md（构建签名） | docs/design/10-安全架构设计.md（运行安全）

目标

建立应用打包、分发、云端部署、监控告警的完整方案，确保产品稳定交付和运行。

输入物

输入	来源	说明
目标平台列表	P2 产出	需要支持的 OS 和分发渠道
云端架构设计	P2 产出	云端服务组件与依赖

产出物

产出	格式	说明	对应文件
部署与运维方案	Markdown	全链路部署运维文档	docs/design/11-部署与运维方案.md
供应链安全	Markdown	SBOM、构建签名、漏洞响应	docs/design/19-供应链安全方案.md
安全架构	Markdown	运行安全层	docs/design/10-安全架构设计.md

应用分发

平台	格式	工具	自动更新
Windows	.msi / .exe	WiX Toolset + {更新工具A}	{更新工具A}
macOS	.dmg（签名+公证）	create-dmg + codesign	{更新工具B}
Linux	.{打包格式A} / .deb / .rpm / {打包格式B}	linuxdeploy + CPack	包管理器 + {打包格式A}Update

安装包目录结构：

{应用名}/
├── bin/
│   ├── {应用名}.exe
│   └── 工具CLI.exe
├── lib/                        # 运行时依赖
├── plugins/                    # 插件目录（用户可自行添加）
├── sdk/                        # 插件 SDK
├── resources/                  # 图标/材质/模板/翻译
│   ├── icons/
│   ├── metadatas/
│   ├── templates/
│   └── translations/
└── docs/

云端服务部署

架构：{内容分发网络}/{Web防火墙} → Load Balancer → API/WS/Web Pods ({容器编排}) → {数据库A}/{缓存系统}/{对象存储}

部署模式：

模式	适用	说明
单机部署	小型团队 <20 人	{容器引擎} Compose
高可用部署	中大型企业	{容器编排} / {容器引擎} Swarm
气隙部署	军工/涉密	离线安装包，无外网连接
混合部署	云端+本地	数据本地、AI 调用云端

监控与可观测性

三支柱: Metrics ({监控系统A}) + Logs ({日志系统}) + Traces ({追踪系统})

关键指标：

• 应用: QPS, P95 延迟, 错误率, 活跃连接数
• 业务: 文档创建数, 功能使用数, AI 请求数
• 系统: CPU, 内存, 磁盘 IO

告警规则：

告警	条件	严重级别
API 错误率 >5%	5 分钟内	P1
P95 延迟 >2s	5 分钟内	P2
核心服务不可达	立即	P1
磁盘使用 >85%	持续 5 分钟	P2

备份与灾难恢复

数据类型	备份策略	RPO	RTO
数据库	每日全量 + WAL 连续归档	5 分钟	1 小时
文件存储	跨区域复制 + 版本历史	15 分钟	30 分钟
缓存	RDB 快照每 6 小时	6 小时	5 分钟

检查清单

• 三平台安装包构建自动化（Win/Mac/Linux）
• 自动更新机制已实现（含增量更新 + 签名校验 + 回滚）
• 云端部署支持 {容器编排} + {容器引擎} Compose 双模式
• 企业 License Server 支持内网私有部署
• 监控覆盖应用/业务/系统三层指标
• 告警规则分 P1/P2/P3 三级，有明确升级路径
• 备份策略定义了 RPO/RTO，有定期恢复演练计划

---

---

10.1 事故响应

目标

建立明确的线上事故分级、响应、升级和复盘机制，确保故障能得到快速有效的处理，并通过事后复盘持续改进系统可靠性。

事故等级定义

等级	定义	判定标准	响应时间	解决时间
🔴 P0 - Critical	全站/核心功能不可用	>50% 用户受影响，核心业务流程中断	5min	1h
🟠 P1 - High	重要功能不可用	10-50% 用户受影响，无 Workaround	15min	4h
🟡 P2 - Medium	部分功能降级	<10% 用户受影响，有 Workaround	30min	24h
🟢 P3 - Low	轻微影响	边缘功能异常，不影响核心流程	2h	下一 Sprint

On-Call 轮值制度

角色	职责	轮值周期
主 On-Call	第一时间响应告警，初步诊断和修复	1 周
副 On-Call	主 On-Call 无法联系时接替	1 周
升级联系人	特定领域专家（数据库/网络/安全）	按需

On-Call 要求：

• 工作时间：15 分钟内响应
• 非工作时间（20:00-09:00）：30 分钟内响应（仅 P0/P1）
• 必须携带手机并开启告警通知
• 如无法值班，需提前 48h 找到替班并通知

事故响应 SOP

01. 告警触发 → On-Call 响应
    ├─ 确认告警真实性（非误报）
    └─ 判定事故等级

02. 创建事故频道（专用沟通渠道）
    ├─ 拉入相关人员
    └─ 机器人自动发布初始信息（告警详情/时间/受影响服务）

03. 止损（第一时间）— 先止血，再找原因
    ├─ P0/P1: 立即回滚最近部署 / 切换到备集群
    ├─ P2: 降级非关键功能 / 限流
    └─ P3: 排入 Sprint Backlog

04. 根因分析（止损后）
    ├─ 检查近期变更（部署/配置/流量变化）
    ├─ 分析日志/监控/Metrics
    └─ 确认根因

05. 修复验证
    ├─ 在 STG 环境复现 → 验证修复
    ├─ 灰度部署到生产
    └─ 监控确认恢复

06. 关闭事故
    ├─ 通知受影响方（对内 + 对外）
    ├─ 安排 Postmortem（P0/P1 必须 48h 内完成）
    └─ 创建 Action Items

Postmortem 模板（事故复盘）

# Postmortem: {事故简述}（{INC-编号}）

## 概况
- 日期: YYYY-MM-DD
- 持续时间: {从 X 到 Y，共 N 分钟}
- 等级: P0/P1/P2
- 影响: {受影响用户数/功能/业务指标}
- On-Call: @username
- 复盘主持人: @username

## 时间线（UTC+8）
| 时间 | 事件 |
|------|------|
| 14:32 | 告警触发：API 错误率升至 15% |
| 14:35 | On-Call 确认非误报，判定 P1 |
| 14:38 | 开始回滚最近部署 |
| 14:45 | 回滚完成，错误率开始下降 |
| 14:50 | 确认恢复，关闭事故 |

## 根因
{用 5 Whys 方法追溯根因，不满足于表面原因}

## 为什么监控没提前发现
{是否有前置指标被忽略} → 新增监控

## 为什么部署流程没阻止
{是否可在 CI/Staging 中提前发现} → 增强部署门禁

## Action Items
| # | 类型 | 描述 | 负责人 | 截止日期 | 状态 |
|---|------|------|--------|---------|------|
| 1 | 预防 | 增加 {指标} 的告警规则 | @zhangsan | 2026-01-25 | ✅ |
| 2 | 检测 | 自动回滚触发器（错误率>10%） | @lisi | 2026-02-01 | 🟡 |

## Lessons Learned
{对外分享的关键经验}

事故演练

演练类型	频率	内容
桌面推演	每月	团队围坐，走查事故场景和响应流程
故障注入	每季度	在 STG 环境注入故障（Chaos Engineering）
全链路演练	每半年	模拟 P0 事故，包括对外沟通和回滚

混沌工程原则：

• 始终在 STG 环境执行（生产环境需 CTO 特批）
• 始终在工作时间执行（确保人员在场）
• 设定明确的"中止条件"和爆炸半径
• 每次只注入一种故障

状态页与对外沟通

P0/P1 事故时维护公共状态页：

• 15min 内更新状态
• 每 30min 发布进展更新
• 恢复后发布 Postmortem 摘要（脱敏版）

检查清单

• 事故等级定义明确，每个等级有响应时间和解决时间 SLA
• On-Call 轮值表已排好下 4 周，交接流程明确
• P0/P1 事故 48h 内完成 Postmortem
• 所有 Action Items 进入 Issue Tracker 追踪
• 每月至少一次桌面推演
• 回滚操作一键化（单命令/单按钮）
• 告警通知通道有冗余（主通道 + 备用通道）

---

---

10.2 功能开关与灰度发布

目标

通过功能开关实现发布与部署的解耦，支持灰度发布、A/B 测试和紧急功能关闭，降低发布风险。

功能开关分类

类型	生命周期	示例	动态更新
Release Flag	短期（1-2 个版本）	隐藏未完成功能，直到开发完毕	✅
Kill Switch	长期（保留）	紧急关闭高负载/有问题的功能	✅
Experiment Flag	中期（A/B 测试周期）	对比新旧 UI/算法效果	✅
Ops Flag	长期（保留）	维护模式、降级开关	✅
Permission Flag	长期（保留）	按用户等级开启功能	✅

功能开关实现规范

// ✅ 推荐：通过配置中心动态控制
if (FeatureFlag::IsEnabled("new_search_engine")) {
    return SearchV2(query);
} else {
    return SearchV1(query);
}

// ❌ 禁止：功能开关中嵌套复杂逻辑
if (flag1 && (flag2 || user.isPremium()) && flag3 && !flag4) { ... }

铁律：

• 开关决策路径必须简单（if/else），禁止嵌套 >2 层
• 新代码和旧代码同时存在于同一版本中
• 每个开关必须有明确的负责人和计划移除日期
• 禁用状态下的代码路径必须有测试覆盖

开关生命周期

创建 → 代码集成 → 关闭状态部署 → 灰度开启 → 全量开启 → 清理开关→ 移除旧代码
  │                                          │
  └─ 附带负责人+计划移除日期                    └─ 超过计划移除日期 → CI 告警

开关清理规则：

• Release Flag 在全量开启后 2 周内删除
• Experiment Flag 在实验结束后 1 周内删除
• CI 自动扫描超期开关 → 阻断构建

灰度发布 (Canary Deployment)

流量切换策略：

阶段 1: 金丝雀 5% 流量，观察 30min
  ├─ 监控指标: 错误率、P95延迟、CPU/内存
  ├─ 异常条件: 错误率 > baseline × 1.5 或 P95延迟 > baseline × 2
  └─ 满足异常条件 → 自动回滚

阶段 2: 扩大到 25% 流量，观察 1h
  └─ 同上

阶段 3: 扩大到 100% 流量，持续监控 24h
  └─ 确认稳定后关闭开关、清理代码

自动回滚条件：

指标	阈值	观察窗口
HTTP 5xx 错误率	>1%	5min
P95 延迟	> baseline × 2	10min
崩溃率	>0.1%	5min
内存使用	>90% 且持续增长	15min

桌面端应用的灰度发布

桌面端无法使用服务端流量切换，可采用：

策略	说明
通道分离	Beta 通道 vs Stable 通道，用户自行选择
分批推送	5% → 25% → 100%，通过自动更新系统控制
用户 opt-in	在设置中提供"尝鲜功能"开关
内部 Dogfooding	团队全员使用 Beta 版本至少 1 周再外发

检查清单

• 每个功能开关关联一个 Issue（负责人 + 计划移除日期）
• CI 自动扫描超期开关，超期 >30 天阻断构建
• 开关关闭状态和开启状态的代码路径都有测试
• 灰度发布有自动回滚条件（错误率/P95延迟阈值）
• 金丝雀部署前在 STG 环境通过全量验证
• 灰度放量过程有监控 Dashboard 实时可见

---

---

11. 反馈迭代

关联文档: docs/design/25-用户反馈与迭代闭环.md | docs/design/30-补充设计要点.md（数据埋点）

目标

建立多渠道用户反馈收集、{业务单元} Request 优先级投票、产品迭代节奏和 NPS 满意度追踪机制。

输入物

输入	来源	说明
产品定位与用户画像	P0 产出	反馈渠道选择依据
发布节奏	P8 产出	迭代周期对齐

产出物

产出	格式	说明	对应文件
用户反馈体系	Markdown	渠道矩阵、分类标准、处理流程	docs/design/25-用户反馈与迭代闭环.md
数据埋点	Markdown	埋点方案、隐私设置	docs/design/30-补充设计要点.md
用户文档体系	Markdown	L1-L5 文档架构	docs/design/22-用户文档与帮助系统.md
商业化方案	Markdown	版本定价、License 技术方案	docs/design/08-商业化与许可证方案.md
多区域定价	Markdown	全球定价、中国市场定价	docs/design/20-市场定价与本地化策略.md

反馈渠道矩阵

渠道	目标用户	反馈类型	工具
应用内反馈	所有用户	Bug / {业务单元} / 满意度	内置表单 + 截图标注
{代码托管平台} Issues	开发者	Bug / {业务单元}	{代码托管平台}
{代码托管平台} Discussions	社区	想法 / 讨论	{代码托管平台}（投票功能）
{社区平台}	活跃社区	实时讨论	{社区平台}
邮件	Enterprise	专属支持	工单系统
NPS 调查	Pro 用户	满意度	邮件 + 应用内
用户访谈	关键用户	深度需求	视频会议

应用内反馈设计要点

• 自动携带：应用版本、OS 版本、活动插件列表、最后 30 秒操作历史
• 分类入口：报告 Bug / 请求新功能 / 一般建议 / 报告崩溃
• 自动附带：截图/录屏（自动截取当前窗口）、日志（自动收集）

反馈分类与 Triage

类型	优先级	首次响应	解决周期
崩溃/数据丢失	P0 - Critical	4h	24h（hotfix）
核心功能 Bug	P1 - High	24h	1 周
非核心 Bug	P2 - Medium	48h	2 周
UI/UX 改进	P3 - Low	1 周	当个 Milestone
{业务单元} Request	按投票数	1 周	Roadmap 排期

Triage 流程：新 Issue → 自动打标签(bot) → 人工分类(维护者轮值，每天 15 分钟) → Bug/Feature/Question 分流

{业务单元} Request 投票系统

规则：

• Pro 用户每月 5 票，Community 用户每月 1 票，Enterprise 用户 10 票/席位
• 票数每月重置（不累计）
• 开发团队保留否决权（技术不可行/与愿景冲突）

生命周期：提交 → 审核 → 进入投票池 → 达到阈值(≥50票) → 考虑中 → 技术评估 → 排入 Roadmap → 开发中 → Beta → 发布

迭代节奏

Patch (0.1.1):  每 2 周    Bug 修复 + 小改进
Minor (0.2.0):  每 3 月    新功能 + API 兼容
Major (1.0.0):  每 12 月   架构变更 / 里程碑

发布窗口: 周二或周三（避开周五/周末）

年度 Roadmap 循环：Q1 社区讨论收集 → Q2 重大技术项目启动 → Q3 持续交付+用户大会 → Q4 年终冲刺+下年规划

NPS 与留存

• NPS 调查：使用 30 天后或订阅续费时触发，目标 >50
• 留存漏斗：下载 → 安装 → 首次使用 → 创建第一个作品 → 第 7 天 → 第 30 天 → 付费
• 流失分析：取消时必填原因（价格/功能/Bug/竞品/不再需要）

检查清单

• 反馈渠道覆盖至少 4 种（应用内 / {代码托管平台} / 社区 / 企业邮件）
• 反馈分类有明确的优先级定义和 SLA（首次响应/解决周期）
• {业务单元} Request 有投票机制，且票数与 Roadmap 排期挂钩
• 发布节奏有明确的版本号策略和发布窗口
• NPS 调查触发时机合理，有流失原因收集机制

---

---

12. 技术债务管理

目标

建立技术债务的识别/记录/偿还机制和项目级风险的识别/评估/缓解体系，防止技术债务失控积累和风险突然爆发。

输入物

输入	来源	说明
所有技术决策	P2 产出	ADR 中的风险记录
当前开发进度	P4 产出	进度偏差
第三方依赖清单	P6 产出	外部依赖风险

产出物

产出	格式	说明	对应文件
技术债务管理策略	Markdown	债务类型/等级/追踪方式	更新本流程文档技术债务章节
风险登记册	Markdown 表格	风险描述/概率/影响/缓解措施	更新本流程文档风险登记册
版权与专利评估	Markdown	专利风险地图、规避策略	docs/design/23-版权与专利风险评估.md

技术债务管理

核心原则：

1. 承认债务存在（快速迭代期可接受有意识的债务）
2. 记录每一笔债务（不自欺，所有债务可追溯）
3. 设定偿还计划（"暂时"不是永远）
4. 新代码不引入已知类型债务（不进则退）

债务分类：

类别	标记	说明
架构债务	TD-ARCH	架构决策在规模扩大后不再适用
代码债务	TD-CODE	重复代码、上帝类、魔法数字
测试债务	TD-TEST	核心路径缺测试、测试不稳定
文档债务	TD-DOC	API 缺文档、过时文档
依赖债务	TD-DEP	过时依赖、未维护的 fork
性能债务	TD-PERF	已知性能瓶颈未优化
安全债务	TD-SEC	已知安全风险未修复（需立即处理）

严重等级：🔴 Critical（阻塞后续）→ 🟠 High（显著影响）→ 🟡 Medium（有 workaround）→ 🟢 Low（改善项）

债务登记模板：

### TD-001: {债务简述}
- **类型**: TD-ARCH
- **等级**: 🟠 High
- **引入 Phase**: P0
- **计划偿还**: P1 开始前
- **描述**: {详细说明}
- **影响**: {对开发/用户的影响}
- **负责人**: @username
- **状态**: 🟡 已登记

偿债时间分配：

Phase	偿债时间占比	说明
P0	10%	基础打牢，少欠债
P1	15%	快速迭代，允许有意识债务
P2	20%	债务积累，需开始偿还
P3+	25-30%	稳定性优先，持续清理

每个 Sprint 预留 15-20% 时间偿债。每月最后一个周五为 "Tech Debt Friday"。

零容忍红线：

❌ 内存泄漏（任何级别）
❌ 数据损坏风险
❌ 线程安全问题（可能导致崩溃）
❌ 安全漏洞（任何级别）
❌ 测试完全缺失的核心模块
❌ 不处理错误返回值的文件 I/O 操作

风险登记册模板

ID	风险描述	类别	概率	影响	等级	缓解措施	触发条件
R-001	核心技术稳定性不足	技术	高	高	🔴	封装+重试+回归测试集+备选方案	复杂场景出现时
R-002	核心技术实现复杂度超预期	技术	高	高	🔴	提前预研+专门测试集+参考开源方案	深度 >10 时
R-003	团队招聘困难（领域人才稀缺）	人员	高	高	🔴	远程优先+内部培养+高校合作+实习生通道	扩张阶段
R-004	性能目标无法达成	技术	中	高	🟠	提前建性能基准+优化从 Day1 开始+渐进式加载	大负载场景
R-005	License 合规风险	合规	低	高	🟡	{许可证E} 隔离(独立进程)+License 审计	法律审查

风险应对流程

识别 → 评估(概率×影响) → 登记 → 制定缓解措施 → 主动监控(每月)/定期审查(每 Phase)

触发条件满足 → 升级为 Issue → 进入问题追踪流程

风险状态：🟢 监控中 / 🟡 预警 / 🔴 已触发（转 Issue）/ ✅ 已消除

检查清单

• 技术债务有分类体系（7 类）和严重等级
• 每笔债务有登记模板（类型/等级/引入Phase/偿还计划/负责人）
• 偿债时间分配随 Phase 递增（10% → 30%）
• 零容忍红线清单明确且可执行
• 风险登记册覆盖技术/人员/进度/外部依赖 4 类
• 每个风险有概率×影响评估和具体缓解措施
• 风险触发条件明确，触发后自动升级为 Issue

---

---

13. 知识管理

关联文档: docs/design/22-用户文档与帮助系统.md | docs/design/26-教育与培训体系.md | docs/design/24-开发者社区治理方案.md

目标

维护一份随仓库分发的"项目记忆"文档，让任何新加入者无需重新探索即可获知全貌。

输入物

输入	来源	说明
所有前述文档	P0-P11	项目全部知识

产出物

产出	格式	说明	对应文件
项目记忆文档	Markdown	项目速览/结构/技术决策/已知陷阱	更新本流程文档知识管理章节
开发者社区治理	Markdown	BDFL+Meritocracy、RFC 流程	docs/design/24-开发者社区治理方案.md
教育培训体系	Markdown	课程体系、认证考试	docs/design/26-教育与培训体系.md
竞品迁移向导	Markdown	迁移设计、数据映射	docs/design/27-数据迁移方案.md
平台适配方案	Markdown	跨平台策略、目标平台适配路径	docs/design/14-平台适配方案.md
开源治理	Markdown	AGPL v3、贡献者协议	docs/design/17-开源治理与许可证方案.md

项目记忆文档模板

# {项目名} 项目记忆

> 此文件随仓库分发，克隆工程后即可获知全貌，无需重新探索。
> 每次重大变更后同步更新。

---

## 一、项目速览

| 项目 | 说明 |
|------|------|
| **产品** | {一句话描述} |
| **阶段** | Phase N ({阶段名称}) |
| **版本** | vX.Y.Z |
| **进度** | {关键进度百分比} |
| **测试** | {测试数量/通过率} |
| **编译** | {编译器/工具链} |

## 二、文件结构速查

{项目完整目录树，标注每个目录的用途}

## 三、核心服务/模块清单

| 服务 | 类/模块名 | 说明 |
|------|-----------|------|

## 四、构建与发布

{一键构建命令 / 发布命令 / 环境要求}

## 五、技术决策

{关键架构决策、编译器选择、依赖策略、命名规范}

## 六、关键规则

{插件系统关键规则 / 生命周期规则 / API 约束}

## 七、已知陷阱

{容易踩的坑、常见编译/运行时问题及解决方案}

## 八、当前状态

{当前 Phase 完成百分比、已完成/推迟任务清单}

## 九、关联文档索引

| 目的 | 文档 |
|------|------|
| 功能全景 | 01-功能需求文档.md |
| 架构全貌 | 02-系统架构与技术选型.md |
| 进度跟踪 | 31-开发进度跟踪.md |
| 问题记录 | 32-开发问题记录表.md |
| 编码规范 | 16-编码规范.md |

更新规则

• 每次重大变更后同步更新（功能完成、架构调整、重大 Bug 修复）
• "已知陷阱"部分看到新人踩坑就追加
• "关联文档索引"保持最新链接

检查清单

• 项目速览表能让人 30 秒了解项目状态
• 文件结构速查标注了关键目录的用途
• 核心服务/模块清单完整且每个有简短说明
• 构建命令经新人验证可用
• 已知陷阱随时追加（每次有人踩坑就记录）
• 关联文档索引指向正确的文件路径
• 文档在每次重大变更后更新

---

13.1 开发者使用助手生成规范

本节作用：要求 AI 在编码阶段同步生成一份可浏览的"使用助手"文档，类似 Qt Assistant，让开发者能快速查阅每个模块、类、函数的用法和示例。

目标

AI 在完成编码后，自动扫描源代码，生成一份结构化的 API 使用手册，包含：

1. 模块总览 — 每个模块的职责、对外接口、依赖关系
2. 类/结构体参考 — 每个公开类的字段、方法、构造方式
3. 函数/方法字典 — 每个公开函数的签名、参数说明、返回值、异常、使用示例
4. 调用关系图 — 模块间的调用链路（文本形式）
5. 常见用法速查 — 按场景组织的代码片段（如"如何创建对象"、"如何查询数据"）

产出物

产出	格式	说明	对应文件
使用助手主文档	Markdown	模块总览 + 目录索引	docs/api/README.md
模块 API 手册	Markdown	每个模块一个文件	docs/api/{module}.md
类参考	Markdown	每个核心类一个章节	内嵌于模块手册
函数字典	Markdown	按模块分组	内嵌于模块手册
使用示例集	Markdown + 代码块	按场景组织	docs/api/examples.md
调用关系图	Markdown + ASCII	模块间依赖	docs/api/call-graph.md

使用助手文档模板

# {项目名} 使用助手

> AI 自动生成，基于源代码扫描。最后更新: {日期}

---

## 快速导航

| 模块 | 说明 | 手册 |
|------|------|------|
| {module-a} | {一句话说明} | [查看](#module-a) |
| {module-b} | {一句话说明} | [查看](#module-b) |

---

## {module-name} 模块

### 职责

{模块做什么、解决什么问题}

### 依赖

{本模块依赖哪些其他模块}

### 公开 API

#### 类: {ClassName}

| 方法 | 签名 | 说明 |
|------|------|------|
| {methodName} | `{returnType} {methodName}({params})` | {一句话说明} |

**{methodName} 详解**

```cpp
// 函数签名
ReturnType ClassName::methodName(ParamType param1, ParamType param2);

// 参数说明
// param1 — {参数含义、取值范围、默认值}
// param2 — {参数含义}

// 返回值
// {返回值含义}

// 异常
// {可能抛出的异常及条件}

// 使用示例
auto result = obj.methodName(value1, value2);

调用示例

// 场景: {描述使用场景}
#include "{module}/{header}.h"

void example() {
    // 1. 创建对象
    ClassName obj;
    
    // 2. 调用方法
    auto result = obj.methodName(value1, value2);
    
    // 3. 处理结果
    if (result.isValid()) {
        // ...
    }
}

---

常见用法速查

场景: {如"创建并初始化"}

// 步骤 1: ...
// 步骤 2: ...

场景: {如"查询数据"}

// 步骤 1: ...
// 步骤 2: ...

---

调用关系图

ModuleA ──调用──► ModuleB ──调用──► ModuleC
   │
   └──调用──► ModuleD

#### AI 生成规则

1. **扫描范围**: 所有 `public` / `export` 的类、函数、枚举、常量
2. **忽略**: `private` / `internal` / `test` 文件、自动生成的代码
3. **参数推断**: 从函数签名和注释中提取参数含义；若无注释，标注 `{待补充}`
4. **示例生成**: 每个公开函数至少一个使用示例；复杂函数至少两个（简单场景 + 高级场景）
5. **类型标注**: 所有参数和返回值必须标注类型
6. **异常标注**: 如果函数可能抛出异常或返回错误码，必须说明

#### 更新时机

- 每次编码阶段完成后，AI 重新扫描并更新使用助手
- 每次 API 变更后，同步更新对应模块的手册
- 每次 Phase 完成后，生成完整版本

#### 检查清单

- [ ] 每个公开模块都有对应的 API 手册文件
- [ ] 每个公开类都有字段和方法说明
- [ ] 每个公开函数都有签名、参数、返回值、示例
- [ ] 常见用法速查覆盖了主要使用场景
- [ ] 调用关系图准确反映模块间依赖
- [ ] 所有代码示例可编译通过
- [ ] 文档在 API 变更后同步更新

---

## 14. 文件驱动设计生产（DDD）

### 概述

**文件驱动设计生产（Document-Driven Development, DDD）** 是贯穿软件设计开发全流程的核心方法论。它的核心思想是：**AI 先生成各类规范文件，再以这些文件作为"单一事实来源（Single Source of Truth）"**，驱动后续的设计、编码、测试、部署各环节。所有后续工作必须以已生成的文件为准，不得偏离。

### 核心原则

原则1: 文件即契约（File as Contract） 每个阶段产出的文件是下一阶段的输入契约。任何实现必须与文件中定义的接口、模型、规范保持一致。 如需修改，必须更新源文件并经评审后方可执行。

原则2: 单一事实来源（Single Source of Truth） 同一信息只在一份文件中定义。禁止在代码中重复定义已在文档中声明的接口/模型/规则。 如果代码需要引用，应通过代码生成从文档自动产生，或建立双向校验机制。

原则3: 先文档后代码（Document-First） 在开始任何编码之前，必须先完成对应阶段的规范文件并评审通过。 没有评审通过的接口定义，不写实现代码。没有评审通过的测试用例，不开始功能开发。

原则4: 文件驱动流水线（Document-Driven Pipeline） 每个阶段产出的文件自动触发下游任务——需求文档变更触发架构评审，接口变更触发代码生成， 数据模型变更触发数据库迁移脚本生成。

---

### 各阶段核心文件清单与依赖链

┌─────────────────────────────────────────────────────────────────────────────┐ │ 文件驱动设计生产 — 文件依赖链 (Document Dependency Chain) │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ [P0] 项目章程 ──────┐ │ │ [P0] 技术预研报告 ──┤ │ │ ▼ │ │ [P1] 功能需求规格书 (FRD) ──────────────────────┐ │ │ [P1] 非功能性需求清单 (NFR) ────────────────────┤ │ │ ▼ │ │ │ [P2] 系统架构设计书 (SAD) ◄── 依赖 FRD + NFR │ │ │ [P2] 技术选型决策记录 (ADR) │ │ │ [P2] 模块接口定义文件 (MIDL) │ │ │ ▼ │ │ │ [P3] 数据模型定义文件 (DM) ◄── 依赖 SAD + FRD │ │ │ [P3] 文件格式规范 (FFS) │ │ │ ▼ │ │ │ [P4] 开发计划与里程碑 (DPM) ◄── 依赖 SAD + FRD │ │ │ ▼ │ │ │ [P5] 编码规范文件 (CSG) │ │ │ [P6] 构建配置清单 (BCM) │ │ │ ▼ │ │ │ [P7] 测试策略文件 (TSP) │ │ │ [P7] 测试用例规格书 (TCS) ◄── 依赖 FRD + SAD │ │ │ ▼ │ │ │ [P_CODE] 源代码 ◄── 依赖 MIDL + DM + CSG │ │ │ ▼ │ │ │ [P9] 部署配置清单 (DCM) │ │ │ [P10] 反馈追踪规范 (FTS) │ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘

### 各阶段产出文件清单

> **AI 执行时**：读取此表确定每个阶段应读取/更新的文件路径。文件编号为 DDD 通用编号，对应文件为本项目实际文件。

| 阶段 | DDD 编号 | 通用文件名 | 文件类型 | 对应实际文件 | 下游消费者 |
|------|----------|-----------|----------|-------------|-----------|
| P0 | D-001 | 项目章程 | `.md` | 更新本流程文档立项章节 | P1, P2 |
| P0 | D-002 | 项目概述与愿景 | `.md` | `docs/design/00-项目概述与愿景.md` | P2 |
| P0 | D-003 | 竞品分析 | `.md` | `docs/design/07-竞争对标分析.md` | P1 |
| P0 | D-004 | 能力缺口分析 | `.md` | `docs/design/15-能力缺口分析.md` | P1 |
| P0 | D-005 | 品牌策略 | `.md` | `docs/design/18-品牌与商标策略.md` | 运营 |
| P1 | D-100 | 功能需求规格书 (FRD) | `.md` | `docs/design/01-功能需求文档.md` | P2, P_CODE |
| P1 | D-101 | 非功能性需求 (NFR) | `.md` | `docs/design/01-功能需求文档.md` | P2, P7 |
| P1 | D-102 | 核心架构模式 | `.md` | `docs/design/29-核心架构模式设计.md` | P2 |
| P2 | D-200 | 系统架构设计书 (SAD) | `.md` | `docs/design/02-系统架构与技术选型.md` | P3, P_CODE |
| P2 | D-201 | 数据模型设计 | `.md` | `docs/design/04-数据模型设计.md` | P_CODE |
| P2 | D-202 | UI 设计方案 | `.md` | `docs/design/05-UI设计方案.md` | P_CODE |
| P2 | D-203 | 插件 SDK 规范 | `.md` | `docs/design/06-插件SDK与开发规范.md` | P_CODE |
| P2 | D-204 | API 与通信协议 | `.md` | `docs/design/09-API与通信协议设计.md` | P_CODE |
| P2 | D-205 | 安全架构设计 | `.md` | `docs/design/10-安全架构设计.md` | P7, P9 |
| P2 | D-206 | 性能与扩展性设计 | `.md` | `docs/design/13-性能与扩展性设计.md` | P7, P_CODE |
| P2 | D-207 | 补充设计要点 | `.md` | `docs/design/30-补充设计要点.md` | P_CODE |
| P3 | D-300 | 开发计划与里程碑 | `.md` | `docs/design/03-开发计划与里程碑.md` | 项目管理 |
| P3 | D-301 | Phase 执行计划 | `.md` | `docs/plan/{Phase名}-执行计划.md` | P_CODE |
| P3 | D-302 | 进度跟踪看板 | `.md` | `docs/design/31-开发进度跟踪.md` | 项目管理 |
| P4 | D-400 | 编码规范 (CSG) | `.md` | `docs/design/16-编码规范与代码风格指南.md` | P_CODE |
| P5 | D-500 | 构建与供应链安全 | `.md` | `docs/design/19-供应链安全方案.md` | CI/CD |
| P6 | D-600 | 部署与运维方案 | `.md` | `docs/design/11-部署与运维方案.md` | 运维 |
| P7 | D-700 | 测试策略 (TSP) | `.md` | `docs/design/12-测试策略.md` | P_CODE |
| P8 | D-800 | 国际化方案 | `.md` | `docs/design/21-多语言国际化方案.md` | P_CODE |
| P8 | D-801 | 无障碍设计 | `.md` | `docs/design/28-无障碍可访问性设计.md` | P_CODE |
| P9 | D-900 | 商业化与定价 | `.md` | `docs/design/08-商业化与许可证.md` + `docs/design/20-市场定价与本地化策略.md` | 运营 |
| P10 | D-1000 | 用户反馈体系 | `.md` | `docs/design/25-用户反馈与迭代闭环.md` | 产品 |
| P11 | D-1100 | 开源治理 | `.md` | `docs/design/17-开源治理与许可证方案.md` | 社区 |
| P11 | D-1101 | 社区治理 | `.md` | `docs/design/24-开发者社区治理方案.md` | 社区 |
| P11 | D-1102 | 版权与专利 | `.md` | `docs/design/23-版权与专利风险评估.md` | 法务 |
| P11 | D-1103 | 平台适配 | `.md` | `docs/design/14-平台适配方案.md` | 平台 |
| P11 | D-1104 | 用户文档体系 | `.md` | `docs/design/22-用户文档与帮助系统.md` | 文档 |
| P11 | D-1105 | 教育培训体系 | `.md` | `docs/design/26-教育与培训体系.md` | 教育 |
| P11 | D-1106 | 数据迁移方案 | `.md` | `docs/design/27-数据迁移方案.md` | 运营 |

---

### "文件即契约"原则实施细则

#### 1. 接口契约

```yaml
# 示例: D-210 模块接口定义文件 (MIDL)
# 文件: docs/specs/interfaces/{项目前缀}-{核心模块}.yaml
plugin:
  uid: "com.{项目名}.{核心模块}"
  version: "0.1.0"

commands:
  - name: "cmd.{模块}.{操作}"
    description: "Create an entity in the active session"
    parameters:
      - name: "param_a"
        type: "{命名空间}::DataType"
        description: "First input parameter"
      - name: "param_b"
        type: "{命名空间}::DataType"
        description: "Second input parameter"
    returns:
      type: "{命名空间}::{命令结果}"
    errors:
      - code: "E_NO_ACTIVE_SESSION"
        description: "No active session is available"
    since: "0.1.0"

events:
  published:
    - name: "{核心实体}AddedEvent"
      payload:
        entity_uid: "UUID"
        child_ids: "UUID[]"
  subscribed:
    - name: "SelectionChangedEvent"
    - name: "DocumentOpenedEvent"

契约执行规则：

• 实现代码的函数签名必须与 MIDL 定义完全一致（参数名、类型、顺序、返回值）
• CI 流水线中运行接口一致性检查：解析 MIDL → 对比头文件/实现 → 不一致则阻断
• 接口变更流程：修改 MIDL → 触发 API Review → 更新实现 → 更新下游调用方 → 更新测试

2. 数据模型契约

// 示例: D-300 数据模型定义文件 (DM)
{
  "entities": {
    "Part": {
      "description": "A single part in the document",
      "fields": {
        "uid": {"type": "UUID", "required": true, "immutable": true},
        "name": {"type": "string", "required": true, "max_length": 256},
        "children": {"type": "{子实体}[]", "default": []},
        "sub_entities": {"type": "{子实体类型B}[]", "default": []},
        "metadata": {"type": "Metadata", "ref": true}
      },
      "invariants": [
        "uid must be unique within Document",
        "name must not be empty"
      ]
    }
  }
}

契约执行规则：

• 数据库/文件序列化代码必须从 DM 文件生成（代码生成器读取 DM → 生成 C++ struct + 序列化/反序列化代码）
• 禁止手动编写序列化/反序列化逻辑
• 模型变更流程：修改 DM → 运行代码生成 → 更新测试

3. 测试用例契约

# 示例: D-710 测试用例规格书 (TCS)
# 文件: docs/specs/tests/{项目前缀}-core-{核心模块}-tests.md

## TCS-{MOD}-001: Entity Creation - Happy Path
- **前置条件**: Active session exists
- **输入**: params valid
- **期望输出**: {命令结果}.success=true, session contains 1 entity
- **验证点**: 
  - Entity type matches
  - Start param matches
  - End param matches

## TCS-{MOD}-002: Entity Creation - No Active Session
- **前置条件**: No active session
- **输入**: params valid
- **期望输出**: {命令结果}.success=false, error=E_NO_ACTIVE_SESSION

契约执行规则：

• 测试用例必须先从 TCS 文件生成测试骨架，再填充具体验证逻辑
• TCS 中的每条用例必须对应至少一个测试函数
• CI 运行"测试覆盖度检查"：TCS 中的用例数 vs 实际测试函数数，不匹配则告警

---

文件命名规范

{阶段前缀}-{序号}-{类别}-{名称}.{扩展名}

阶段前缀:
  P0_  项目启动
  P1_  需求分析
  P2_  架构设计
  P3_  数据模型
  P4_  开发计划
  P5_  编码规范
  P6_  构建系统
  P7_  测试
  P8_  开发流程
  P9_  部署运维
  P10_ 用户反馈
  P11_ 风险债务
  P12_ 项目管理

类别缩写:
  REQ   需求文档 (Requirements)
  ARCH  架构文档 (Architecture)
  ADR   架构决策记录 (Architecture Decision Record)
  API   接口定义 (API Definition)
  DMOD  数据模型 (Data Model)
  SCH   数据库Schema (Schema)
  PLAN  计划文档 (Plan)
  SPEC  规范文件 (Specification)
  CONF  配置文件 (Configuration)
  TEST  测试用例 (Test Cases)
  PROC  流程文档 (Process)
  DEPL  部署配置 (Deployment)
  FEED  反馈文档 (Feedback)
  MEMO  项目记忆 (Project Memory)

示例：

P1_001_REQ_功能需求规格书.md
P2_001_ARCH_系统架构设计书.md
P2_010_API_{核心模块}接口定义.yaml
P3_001_DMOD_核心数据模型.json
P7_001_TEST_{核心模块}测试用例.md

---

版本管理规范

文档版本号规则

文档版本 = 对应的 Phase 版本 + 修订号

格式: v{Phase主版本}.{Phase次版本}-r{修订号}

示例:
  v1.0-r3  表示 Phase 1 首发版，第 3 次修订
  v2.1-r0  表示 Phase 2.1 首发版

变更记录要求

每个规范文件末尾必须包含变更记录表：

---

## 附录A: 安全开发生命周期

### 目标

将安全实践嵌入软件开发生命周期的每个阶段，而非"事后打补丁"。遵循"安全左移（Shift Left）"原则——安全问题发现得越早，修复成本越低。

### 核心原则

1. **安全是每个人的责任**：不只是安全团队的职责，开发/测试/运维均需参与
2. **安全左移**：需求阶段就考虑威胁，设计阶段完成威胁建模
3. **默认安全（Secure by Default）**：不安全的配置不应是默认值
4. **纵深防御**：多层防护，不依赖单一安全措施

### 安全嵌入各阶段

P0 项目启动: 安全需求基线（合规要求/数据分类/认证目标） P1 需求分析: 安全功能需求 + 滥用案例（Abuse Cases） P2 架构设计: 威胁建模 + 安全设计评审 P3 数据模型: 敏感数据识别 + 数据分类分级 + 加密策略 P5 编码规范: 安全编码规范（OWASP Top 10 防御） P6 构建系统: 依赖安全扫描 + SAST 集成 P7 测试策略: DAST + 渗透测试 + Fuzzing P8 开发协作: 安全 Code Review 检查点 P9 部署运维: 安全配置基线 + 密钥管理 + {Web防火墙} P10 用户反馈: 安全漏洞报告通道（Bug Bounty / 安全邮箱） P11 风险管理: 安全风险专项追踪

### 威胁建模（每 Phase 开始时执行）

**方法**: STRIDE（欺骗/篡改/抵赖/信息泄露/拒绝服务/权限提升）

**流程**：
1. 绘制数据流图（DFD）
2. 对每个数据流/数据存储/处理节点应用 STRIDE
3. 识别威胁 → 评估风险 → 设计缓解措施
4. 输出威胁模型文档

**威胁建模模板**：

```markdown
# 威胁模型: {模块/功能名}

## 数据流图
{描述数据如何在系统组件间流动}

## 威胁清单

| ID | STRIDE 类别 | 威胁描述 | 受影响资产 | 风险等级 | 缓解措施 | 状态 |
|----|-----------|---------|-----------|---------|---------|------|
| T-001 | Spoofing | 伪造用户身份访问 API | 用户数据 | 高 | JWT + 签名验证 | ✅ |
| T-002 | Tampering | 插件被篡改后加载 | 系统完整性 | 高 | 插件签名校验 | 🟡 |
| T-003 | Info Disclosure | 日志中打印敏感信息 | 用户隐私 | 中 | 日志脱敏工具 | 🟡 |

安全编码规范（OWASP Top 10 防御）

风险	防御措施	代码检查
注入 (Injection)	参数化查询、输入校验、白名单	SAST 规则
认证失效	MFA、密码强度策略、会话管理	认证流程测试
敏感数据泄露	传输加密({传输加密版本})、存储加密({加密标准})、日志脱敏	敏感信息扫描
XXE	禁用外部实体解析	XML Parser 配置
访问控制失效	最小权限原则、服务端权限校验	权限矩阵测试
安全配置错误	安全基线模板、云安全态势管理	配置合规扫描
XSS	输出编码、CSP 头	XSS 测试用例
不安全反序列化	白名单类名、签名校验	反序列化安全测试
使用含已知漏洞的组件	SBOM + CVE 监控 + 自动升级	依赖扫描
日志和监控不足	审计日志、异常检测、告警	日志完整性检查

安全工具链集成

阶段	工具	触发条件
编码时	IDE 安全插件（SonarLint）	实时
提交时	Pre-commit hooks（密钥扫描: gitleaks/truffleHog）	每次 commit
PR 时	SAST（{安全扫描A}/Semgrep/{代码质量平台}）	每次 PR
构建时	依赖扫描（{漏洞扫描A}/{依赖监控}/Snyk）	每次构建
部署前	容器镜像扫描 + IaC 安全扫描	每次部署
运行时	DAST（OWASP ZAP）+ RASP	定期/持续

密钥管理

❌ 禁止: 密钥硬编码在源码中
❌ 禁止: 密钥通过 {消息平台}/微信/邮件明文传递
❌ 禁止: 生产密钥与开发密钥相同

✅ 使用密钥管理服务（HashiCorp Vault / AWS Secrets Manager）
✅ 密钥定期轮换（90天）
✅ 密钥访问审计日志
✅ 开发环境使用独立密钥

安全事件响应

当安全漏洞被发现时（内部发现或外部报告）：

时间	行动
0-4h	确认漏洞真实性、评估影响范围
4-24h	制定修复方案、准备补丁
24-72h	发布修复、通知受影响用户
72h+	Postmortem + 改进安全流程

检查清单

• 每 Phase 新功能有威胁建模文档
• 安全编码规范已纳入 P5 编码规范
• SAST/DAST/依赖扫描已集成到 CI 流水线
• 密钥管理方案已就绪（不入库、定期轮换）
• 安全漏洞报告通道对外公开（security@域名 / Bug Bounty）
• 第三方依赖 CVE 有自动监控和升级策略
• 定期渗透测试（至少每年一次）

---

---

附录B: 合规性管理

目标

确保软件产品在开发、分发和运营过程中满足适用的法律法规和行业标准要求。

适用范围

根据产品定位和分发区域，确定需遵守的法规框架：

法规	适用范围	核心要求
中国《个人信息保护法》(PIPL)	中国用户数据处理	知情同意、最小必要、数据本地化
中国《数据安全法》	中国境内数据处理	数据分类分级、安全审查
中国《网络安全法》	在中国运营的网络产品	等保测评、实名制
中国等保 2.0 (GB/T 22239)	中国政务/央企/关键基础设施	安全等级测评
GDPR	欧盟用户数据	数据主体权利、DPIA、跨境传输
CCPA/CPRA	加州居民数据	知情权、删除权、不出售权
SOC 2	企业级 SaaS	安全性/可用性/机密性审计
ISO 27001	国际通用	信息安全管理体系
WCAG 2.1 AA	欧美政府/教育客户	无障碍访问标准

合规嵌入各阶段

阶段	合规任务
P0	确定适用法规范围，明确产品合规基线
P1	隐私需求（数据收集清单、Cookie 分类、隐私政策）
P2	数据存储位置策略（数据本地化 / 跨境传输评估）
P3	数据分类分级（公开/内部/机密/绝密）、保留策略
P5	合规编码约束（日志中不记录 PII、数据加密存储）
P7	合规测试用例（数据删除验证、同意管理测试）
P9	加密传输 ({传输加密版本})、加密存储 ({加密标准})、审计日志
P10	用户权利响应（数据下载/删除请求处理 SLA）
P13	安全措施与合规要求的对应关系

数据分类分级

级别	标签	示例	存储要求	传输要求	访问控制
公开	Public	产品文档、开源代码	无需加密	无需加密	所有人
内部	Internal	设计文档、开发日志	加密存储	TLS	团队成员
机密	Confidential	用户 PII、业务数据	加密+{加密标准}	{传输加密版本}	最小权限
绝密	Restricted	密钥、支付信息、健康数据	加密+HSM	{传输加密版本}+	审计+审批

隐私设计检查清单（PbD: Privacy by Design）

• 数据收集: 是否只收集了必要的数据？（数据最小化）
• 数据用途: 用户是否明确知道数据将如何被使用？
• 同意管理: 用户是否可以撤回同意？
• 数据删除: 用户是否可以请求删除其数据？（"被遗忘权"）
• 数据导出: 用户是否可以导出其数据？（数据可移植性）
• 数据留存: 是否定义了数据保留期限？过期数据是否自动删除？
• 第三方共享: 用户数据是否与第三方共享？是否已披露？
• 儿童数据: 是否涉及 14 岁以下儿童数据？（需监护人同意）

合规审计

审计类型	频率	负责方
内部合规自查	每季度	安全/法务团队
第三方渗透测试	每年	外部安全公司
等保测评	每 2 年（三级）	等保测评机构
SOC 2 审计	每年	审计事务所
ISO 27001 审核	每年（监督审核）/ 每 3 年（重认证）	认证机构

检查清单

• 适用法规清单已确定并随产品迭代更新
• 数据分类分级方案已实施
• 隐私政策已发布且保持更新
• 用户数据删除/导出请求处理流程就绪
• 敏感数据加密存储和传输
• 合规审计频率满足行业和法规要求
• 员工数据安全培训完成（每年复训）

---

---

附录C: 供应链安全

目标

管理软件供应链的安全风险，确保所有第三方依赖、构建工具和分发渠道的完整性和安全性，防范供应链攻击。

核心原则

1. 零信任：不信任任何第三方依赖，默认需要验证
2. 可追溯：所有依赖的来源、版本、许可证、CVE 状态可审计
3. 最小依赖：优先使用标准库，减少依赖数量
4. 锁定版本：所有依赖锁定具体版本（含哈希），禁止 latest 标签

SBOM（软件物料清单）

要求：每次发布必须生成 SBOM，格式为 SPDX 或 CycloneDX。

# SBOM 示例 (CycloneDX 格式)
bomFormat: CycloneDX
specVersion: "1.5"
components:
  - name: openssl
    version: "3.2.1"
    purl: pkg:conan/openssl@3.2.1
    licenses:
      - license:
          name: Apache-2.0
    hashes:
      - alg: {哈希算法}
        content: a1b2c3...

  - name: {JSON库}
    version: "3.11.3"
    purl: pkg:github/nlohmann/json@3.11.3
    licenses:
      - license:
          name: MIT

SBOM 用途：

• 许可证合规审计
• CVE 影响范围快速定位（Log4Shell 级别的应急响应）
• 企业客户安全审查

依赖安全策略

策略	规则
来源可信	仅从官方仓库/包管理器拉取，禁止从随机 {代码托管平台} fork 引用
版本锁定	所有依赖锁定到具体版本，通过 lockfile 管理
哈希校验	CI 中校验下载的依赖包哈希是否与 lockfile 一致
CVE 监控	自动扫描依赖的已知漏洞，高危漏洞 7 天内修复
许可证审计	所有依赖的许可证必须通过审核，禁止引入 {许可证E}/A{许可证E} 传染性依赖（或隔离处理）

依赖风险等级

风险	判定标准	处理方式
🔴 阻断	已知 CVE Critical/High + 有公开 Exploit	立即升级或替换
🟠 高风险	已知 CVE Critical/High，无公开 Exploit	1 个 Sprint 内升级
🟡 中风险	已知 CVE Medium/Low	2 个 Sprint 内升级
🟢 低风险	无已知 CVE	定期维护

构建管道安全

构建环境安全要求:
 □ 构建在隔离环境中执行（容器/VM），每次构建后销毁
 □ 构建产物签名（代码签名证书）
 □ SBOM 自动生成并归档
 □ 构建日志保留 90 天
 □ 构建依赖缓存独立，不同项目不共享

签名验证链:
 源代码 → CI 构建 → 产物签名 → 签名验证 → 分发渠道 → 用户端验签

私有包/镜像仓库

国内网络环境下，推荐搭建私有代理仓库：

# Conan 私有源
conan remote add private https://conan.internal.example.com

# {容器引擎} 镜像加速
registry-mirrors: ["https://mirror.internal.example.com"]

# npm 私有源
npm config set registry https://npm.internal.example.com

私有仓库安全要求：

• 访问控制（谁可以发布/拉取）
• 包扫描（上传时自动 CVE 扫描）
• 审计日志（谁在什么时候拉取/发布了什么）

检查清单

• SBOM 在每次发布时自动生成并归档
• 所有依赖锁定具体版本 + 哈希
• CVE 监控自动化，Critical 漏洞 7 天内修复
• 构建在隔离环境中执行
• 构建产物有代码签名
• 第三方依赖来源审核完成（无不可信来源）
• 许可证合规检查已集成（阻断 {许可证E} 传染性依赖）
• 私有包仓库安全策略已就绪

---

---

附录D: 无障碍访问规范

目标

确保软件产品可以被残障用户（视力障碍、听力障碍、运动障碍、认知障碍）正常使用，满足 WCAG 2.1 AA 标准。

为什么需要

• 法律要求：欧美政府采购和政府客户普遍要求 WCAG 2.1 AA 合规
• 扩大用户群：全球约 15% 人口有某种形式的残障
• 更好的用户体验：无障碍设计通常让所有用户受益（如键盘操作、高对比度）

WCAG 2.1 AA 核心要求速查

原则	要求	具体实现
可感知	文本替代	所有非文本内容（图片/图标）有文本描述
可感知	时间媒体	视频有字幕，音频有文字稿
可感知	可适配	内容在不同屏幕方向和缩放比例下可用
可感知	可辨别	颜色不是传达信息的唯一方式，对比度≥4.5:1
可操作	键盘可访问	所有功能可通过键盘完成（Tab/Enter/Esc）
可操作	足够时间	无强制时间限制，或可延长/关闭
可操作	导航	有跳过导航的机制、有意义的页面标题
可理解	可读	语言可编程式检测，缩写有解释
可理解	可预测	组件行为一致，不自动触发上下文变化
可理解	输入辅助	错误提示明确、有纠正建议、有确认机制
健壮	兼容	兼容屏幕阅读器等辅助技术

开发实现规范

1. 键盘导航

// 所有交互元素必须支持键盘操作
// Tab 键在可聚焦元素间移动
// Enter/Space 激活按钮
// Esc 关闭对话框
// 方向键在列表/菜单中导航

// 自定义组件的键盘支持
class AccessibleListWidget : public QListWidget {
protected:
    void keyPressEvent(QKeyEvent* event) override {
        switch (event->key()) {
            case Qt::Key_Up:    MoveSelection(-1); break;
            case Qt::Key_Down:  MoveSelection(+1); break;
            case Qt::Key_Enter: ActivateItem();    break;
            default: QListWidget::keyPressEvent(event);
        }
    }
};

2. 屏幕阅读器支持

// 设置可访问名称和描述
widget->setAccessibleName("文件列表");
widget->setAccessibleDescription("显示当前项目中的所有文件，按名称排序");
button->setAccessibleName("导出");  // 而非 "button_export_01"

// 动态内容变化通知
void OnSearchComplete() {
    statusLabel->setText("找到 15 个结果");
    // 通知屏幕阅读器状态变化
    QAccessibleEvent event(statusLabel, QAccessible::NameChanged);
    QAccessible::updateAccessibility(&event);
}

3. 颜色与对比度

元素	最小对比度
正文文本	4.5:1
大文本（≥18px 或 ≥14px 粗体）	3:1
UI 组件（按钮边框、输入框）	3:1

/* 不要仅用颜色区分状态 */
/* ❌ 错误: */
.error { color: red; }
.success { color: green; }

/* ✅ 正确: 颜色 + 图标 + 文本 */
.error::before { content: "❌ "; }
.error { color: #d32f2f; }
.success::before { content: "✅ "; }
.success { color: #2e7d32; }

4. 焦点管理

• 焦点指示器始终可见（不可 outline: none 且不提供替代）
• 模态对话框打开时，焦点自动移到对话框内第一个可聚焦元素
• 对话框关闭时，焦点回到触发它的元素

5. 缩放支持

• 支持 200% 缩放而不丢失内容和功能
• 文本可调整到 200% 而不需要水平滚动
• 布局不依赖固定像素值（使用相对单位）

测试方法

方法	工具	覆盖
自动化检查	axe-core / Accessibility Insights	约 30% 的 WCAG 标准
手动检查	键盘 + 屏幕阅读器	约 70% 的 WCAG 标准
用户测试	残障用户参与测试	真实体验验证

CI 集成：

# 自动化无障碍检查（在 UI 测试中集成）
# 每次 PR 自动运行
npm run test:a11y  # axe-core automated checks

无障碍声明

产品官网应发布无障碍声明（Accessibility Statement），包括：

• 承诺遵守的标准（WCAG 2.1 AA）
• 已知的合规差距和改进计划
• 反馈渠道（无障碍问题专用联系邮箱）

检查清单

• 所有功能可通过键盘完成（Tab/Enter/Esc/方向键）
• 所有非文本内容有文本替代（图片 Alt、图标 Label）
• 颜色不是传达信息的唯一方式
• 文本对比度满足 WCAG AA 标准（4.5:1）
• 支持 200% 缩放不丢失功能
• 动态内容变化通知屏幕阅读器
• 焦点管理在对话框/模态窗口中正确处理
• 自动化无障碍检查集成到 CI
• 无障碍声明在官网发布

---

---

附录E: 依赖升级管理

目标

建立系统化的第三方依赖升级评估和执行流程，在"保持最新"和"维护稳定"之间找到平衡，避免依赖腐烂。

升级策略

类型	频率	触发条件
安全补丁	立即	CVE Critical/High 披露
小版本升级 (Patch)	每月	无 Breaking Change
中版本升级 (Minor)	每季度	无 Breaking Change
大版本升级 (Major)	每年评估	有 Breaking Change

升级评估模板

# 依赖升级评估: {库名} v{当前版本} → v{目标版本}

## 基本信息
- 库: {名称}
- 当前版本: v1.2.3
- 目标版本: v2.0.0
- 升级类型: Major

## 变更分析
- Breaking Changes: {数量}（详见 Changelog）
- 新增功能: {列表}
- 安全修复: {列表}
- 性能改进: {列表}

## 影响评估
| 影响范围 | 说明 |
|---------|------|
| API 变更 | {需要修改的调用点数量} |
| 行为变更 | {是否有默认行为变化} |
| 平台兼容 | {Win/Mac/Linux 是否都支持新版本} |
| 许可证变更 | {许可证是否变化，是否仍合规} |
| 依赖冲突 | {是否引入新的传递依赖或版本冲突} |

## 测试要求
- [ ] 现有单元测试全量通过
- [ ] API 兼容性自动检查（对比旧版本 vs 新版本 MIDL）
- [ ] 性能基准对比（升级前后 Benchmark）
- [ ] 跨平台编译通过

## 决策
- [ ] 批准升级
- [ ] 延期（原因: ___）
- [ ] 拒绝（原因: ___）

自动化依赖监控

# CI 配置: 依赖升级检查（每周自动执行）
dependency-update-check:
  schedule: "0 9 * * 1"  # 每周一 09:00
  steps:
    - name: Check outdated dependencies
      run: |
        {包管理器} outdated
        npm outdated
    - name: Check CVE
      run: trivy fs --severity HIGH,CRITICAL .
    - name: Create upgrade PR (if safe)
      run: tools/auto-upgrade-patch.sh  # 仅自动升级 Patch 版本

依赖腐烂指标

指标	健康值	告警值
超过 1 个大版本的依赖比例	<10%	>25%
有已知 CVE 的依赖数量	0	>0 Critical/High
已 Deprecated 的依赖	0	>0
过去 6 个月未升级的依赖比例	<30%	>50%

升级窗口

常规升级窗口:
  - 每月第 1 个 Sprint 的周三
  - 仅升级 Patch/Minor 版本

Major 版本升级窗口:
  - 每个 Phase 开始前
  - 需要完整的升级评估和测试周期
  - 可能涉及 API 适配和回归测试

检查清单

• 依赖版本锁定机制已启用（lockfile）
• CVE 自动监控已配置（每周扫描）
• Patch 版本自动升级流水线就绪
• Major 版本升级有评估模板
• 依赖腐烂指标在项目仪表盘中可见
• 关键依赖（核心引擎库等）有备选方案

---

---

附录F: 团队沟通与知识传递

目标

建立高效的团队沟通节奏和知识传递机制，确保信息在分布式/远程团队中流畅传递，减少信息孤岛和重复踩坑。

沟通节奏

活动	频率	时长	参与者	目的
每日站会 (Standup)	每日	15min	开发团队	昨日进展/今日计划/阻塞项
Sprint 计划会	每 2 周	2h	全团队	确定 Sprint 目标和任务分解
Sprint 评审会 (Demo)	每 2 周	1h	全团队 + 利益相关方	演示已完成功能
Sprint 复盘会 (Retro)	每 2 周	1h	开发团队	改进流程
技术分享 (Tech Talk)	每 2 周	1h	全团队（自愿）	知识分享和交叉培训
架构评审	按需	1-2h	核心开发者	重大技术决策评审
1-on-1	每 2 周	30min	Manager + 每人	个人发展和反馈
产品路线图评审	每月	1h	全团队	同步路线图进展和调整

异步沟通规范

远程团队应默认异步沟通：

事项	沟通方式	期望响应时间
日常讨论/问题	项目频道 ({企业内部平台}/{消息平台})	工作时间内 4h
设计决策	设计文档 + 异步评论	48h
阻塞项	项目频道 + @相关人员	4h
紧急事项	直接消息/电话	1h
周报/进度更新	项目频道（异步发布）	N/A

异步沟通原则：

• 写清楚上下文，让阅读者不需要追问"背景是什么"
• 区分决策型和讨论型消息（[DECISION], [DISCUSSION], [FYI]）
• 重要决策邮件/文档归档，不要仅存在于聊天记录中

文档评审机制

文档类型	评审人	评审标准
FRD (功能需求)	产品负责人 + 技术负责人	需求完整性、优先级合理性
SAD (架构设计)	技术负责人 + 至少 1 名核心开发者	架构一致性、技术可行性
ADR (技术决策)	技术负责人 + 受影响模块负责人	选项充分、理由充分
MIDL (接口定义)	技术负责人 + 下游消费者代表	接口一致性、向后兼容
TCS (测试用例)	QA + 模块开发者	覆盖完整性

知识传递机制

机制	频率	内容
新人 Onboarding 文档	持续维护	环境搭建、项目架构、编码规范
结对编程 (Pairing)	每周 2-4h	高优先级任务或新人结对
Code Walkthrough	复杂 PR 合并前	作者向 Reviewer 讲解核心逻辑
Architecture Walkthrough	新成员入职 / 架构变更后	系统整体架构讲解
Brown Bag 午餐会	每 2 周	非正式技术分享
外部培训预算	每人每年	会议/课程/书籍

新人入职 (Onboarding)

Week 1:
  Day 1: 环境搭建 + 跑通构建 + 入职文档阅读
  Day 2: 阅读 FRD + SAD + P12 项目记忆
  Day 3: 结对编程影子 (跟随老成员)
  Day 4-5: Good First Issue (已标记的低难度任务)

Week 2:
  认领第一个功能模块
  提交第一个 PR
  参加 Sprint 全流程

Week 3-4:
  独立完成一个功能模块
  Code Review 别人的 PR

入职 Buddy 制度：每位新成员指派一位老成员，负责第一月内的非正式指导和答疑。

远程协作规范

规范	要求
工作时间	核心重叠时间 4h（如 UTC+8 14:00-18:00 全员在线）
状态同步	日历保持更新，签名标注工作时段
会议规范	必须有议程，会后发会议纪要
视频会议	默认开摄像头（鼓励但不强制）
文档优先	能写文档的不要开长会，"写下来比说出来持久"

跨时区协作

当团队跨时区分布时：

策略: 核心重叠窗口 + 异步为主
- UTC+8 (中国) 与 UTC+1 (欧洲): 重叠 ~2h (中国 16:00-18:00)
- UTC+8 (中国) 与 UTC-8 (美西): 几乎不重叠 → 全异步

异步协作要点:
- 每日站会改为异步文字（频道内发送"今日3件事"）
- 设计评审用文档评论替代同步会议
- 录制重要会议供无法参会者回看

检查清单

• 团队沟通节奏已确定（站会/Sprint/评审/复盘频率）
• 异步沟通规范已文档化（响应时间期望 + 标签规范）
• 文档评审矩阵已建立（谁在什么阶段评审哪些文档）
• 新人入职路径已定义（Week 1-4 检查清单 + Buddy 制度）
• 知识传递机制涵盖结对编程/技术分享/文档归档
• 远程协作规范已明确（核心重叠时间 + 会议纪要要求）
• 团队日历和休假制度公开透明

---

---

附录G: AI Agent 自主开发操作规范

概述

本规范是 v3.0 的 AI 执行层扩展。P0-P18 定义了"开发什么"和"按什么标准开发"，PA 章定义的是"AI Agent 如何自主执行这些阶段"。它面向的不是人类开发者，而是被赋予软件设计开发任务的 AI Agent。

本规范假设：AI Agent 已接入代码仓库、构建系统、测试框架，拥有一份完整的需求描述，并遵循"文件驱动设计生产（DDD）"方法论（见 PM 章）。

版本: v1.1 | 依赖: 软件设计开发需求流程 v3.1 | 核心理念: 自主决策边界 · 状态驱动 · 自检闭环 · 人机协作

---

PA.0: 核心概念与能力模型

PA.0.1 AI Agent 能力层级

L0: 代码生成 — 根据规范生成单个文件/函数
L1: 任务执行 — 执行一个完整的任务（如"生成 P2 架构文档"）
L2: 阶段执行 — 自主完成一个完整 Phase（如"执行 P1 需求分析"）
L3: 多阶段执行 — 按依赖链执行多个 Phase
L4: 全流程执行 — 从需求到部署的全自动执行

本规范覆盖 L1-L4。L0 见 PA.5（代码生成规范）。

PA.0.2 AI Agent 行为原则

1. 先读后写：执行任何任务前，必须先读取相关上下文（状态文件、前置规范文件、编码规范）
2. 小步提交：每个文件生成后立即自检，不要攒到一堆再检查
3. 不确定时暂停求助：置信度低于阈值的决策必须升级人类审批，不猜测
4. 产出必有记录：每个操作的结果写入状态文件，确保下次醒来能接上
5. 失败不静默：任何失败（编译/测试/一致性检查）必须记录到状态文件并通知

PA.0.3: 环境自检 — 启动前必执行

在开始任何任务之前，Agent 必须验证自身运行环境完整可用。自检失败 → 记录缺失项 → 求助人类 → 等待解决。

自检清单

# Agent 环境自检 — 每一项必须 PASS 才能开始工作

environment_checklist:
  # ---- 基础工具 ----
  - check: "git --version"
    required: true
    fix_hint: "请安装 git 或确保其在 PATH 中"

  - check: "cmake --version"
    required: true
    fix_hint: "请安装 {构建工具} >= 3.28"

  # ---- 编译器 ----
  - check: "gcc --version || clang --version || cl.exe"
    required: true
    fix_hint: "请安装 C++ 编译器（{编译器B} >= 13 / {编译器C} >= 16 / {编译器A} 2022）"

  # ---- 包管理器 ----
  - check: "{包管理器} version || conan --version"
    required: false
    warn_if_missing: "{包管理器} 或 conan 未安装，依赖管理需手动处理"

  # ---- 代码格式化 ----
  - check: "{格式化工具} --version"
    required: true
    fix_hint: "请安装 {格式化工具}"

  # ---- 静态分析 ----
  - check: "{静态分析工具} --version"
    required: false
    warn_if_missing: "{静态分析工具} 未安装，将跳过静态分析检查"

  # ---- AI专属检查 ----
  - check: "可以读写 PROJECT_STATE.yaml"
    required: true
    fix_hint: "检查 docs/state/ 目录权限"

  - check: "可以读取 docs/specs/ 目录"
    required: true
    fix_hint: "检查规范文件目录是否存在"

自检流程

Agent 启动:
  1. 逐项执行环境检查
  2. required=true 的项失败 → 记录到 PROJECT_STATE.blocked
     → 输出清晰的缺失清单 + 修复指令 → 求助人类 → 等待
  3. required=false 的项缺失 → 记录到 known_issues（降级运行）
  4. 全部 required 通过 → 输出"环境就绪"确认 → 开始执行任务

PA.0.4: 文档读取策略 — AI 启动后必读清单

AI Agent 在完成环境自检后、开始执行任何任务前，必须按以下顺序读取文档，建立完整上下文：

第一步：建立全局认知（必读）

1. 读取 本文档（软件设计开发需求流程.md）
   → 目的：理解完整流程框架、当前所处阶段、产出要求
   → 重点：当前阶段的输入物/产出物/检查清单

2. 读取 docs/design/01-功能需求文档.md
   → 目的：了解软件要做什么、模块划分、功能优先级
   → 重点：P0/P1/P2 模块清单、非功能需求指标

3. 读取 docs/design/02-系统架构与技术选型.md
   → 目的：了解技术栈、架构模式、项目目录结构
   → 重点：微内核+插件架构、技术选型决策

4. 读取 docs/design/31-开发进度跟踪.md
   → 目的：了解项目当前状态、已完成/进行中/待开始的任务
   → 重点：Phase 进度、阻塞项、下一步行动

第二步：按阶段读取（按需）

当前阶段	必读文档	可选参考
立项决策	00-AI辅助设计总体方案、07-竞争对标分析、15-高端能力缺口分析	18-品牌与商标策略、08-商业化与许可证方案
需求分析	01-功能需求文档、29-核心架构模式设计	30-补充设计要点
架构设计	02-系统架构与技术选型、04-数据模型、05-UI设计、09-API设计、10-安全架构、13-性能	29-核心架构模式设计
编码实现	16-编码规范、06-插件SDK、docs/plan/01-phase1-master-plan.md	04-数据模型、09-API设计
测试验证	12-测试策略、13-性能与扩展性	10-安全架构（安全测试）
部署运维	11-部署运维、19-供应链安全	10-安全架构（运行安全）
运营迭代	25-用户反馈、08-商业化、20-定价策略	24-社区治理、26-教育培训
平台适配	14-平台适配、21-国际化、28-无障碍	-
法务合规	17-开源治理、23-版权专利、18-品牌商标	-

第三步：文档读取后的动作

读取完毕后，Agent 必须:
1. 验证文档完整性：文件是否存在、格式是否正确、关键章节是否齐全
2. 提取关键信息：当前阶段的输入物、产出物、验收标准
3. 交叉验证：不同文档间的信息是否一致（如需求文档与架构文档的模块划分）
4. 记录到 PROJECT_STATE.yaml：已读取的文档列表、发现的不一致项
5. 如发现重大不一致 → 暂停执行 → 输出差异报告 → 求助人类决策

自检输出格式

## 环境自检结果

| 检查项 | 状态 | 说明 |
|--------|------|------|
| git | ✅ PASS | git version 2.43.0 |
| cmake | ✅ PASS | cmake version 3.28.1 |
| gcc | ❌ FAIL | 未找到，请安装 {编译器B} >= 13 |
| {格式化工具} | ✅ PASS | {格式化工具} version 18.1.0 |

结果: ❌ 环境未就绪 — 1 项缺失
需要人类协助: 安装 {编译器B} >= 13

---

PA.1: 项目状态文件 (PROJECT_STATE.yaml)

PA.1.1 为什么需要

AI Agent 每次会话醒来没有记忆。状态文件是 AI 的"外部工作记忆"，让 Agent 在任何时候重启都能准确知道：项目在哪个阶段、完成了什么、正在做什么、下一个任务是什么、有什么阻塞或问题。

PA.1.2 状态文件规范

# docs/state/PROJECT_STATE.yaml
# AI Agent 工作状态 — 每次操作后更新

project:
  name: "{项目名}"
  version: "v0.1.0"
  created: "2026-01-15"

pipeline:
  current_phase: "P2"            # 当前所在阶段
  current_task: "D-210_MIDL"     # 当前任务 ID
  phase_status: "in_progress"    # not_started | in_progress | blocked | review | done
  overall_progress: 35           # 百分比估算

completed:
  - task_id: "D-001"             # P0 项目章程
    status: "done"
    file: "docs/specs/P0_initiation/P0_001_REQ_项目章程.md"
    completed_at: "2026-01-16"
    human_approved: true

  - task_id: "D-100"             # P1 FRD
    status: "done"
    file: "docs/specs/P1_requirements/P1_001_REQ_功能需求规格书.md"
    completed_at: "2026-01-22"
    human_approved: true

in_progress:
  - task_id: "D-210_MIDL"
    description: "生成核心模块接口定义文件"
    started_at: "2026-01-23"
    attempts: 1
    last_action: "generated draft, running self_check"
    depends_on: ["D-200"]

blocked:
  - task_id: "D-200"
    description: "系统架构设计书"
    blocked_by: "waiting for human review"
    blocked_since: "2026-01-22"
    resolution_hint: "请评审 docs/specs/P2_architecture/P2_001_ARCH_系统架构设计书.md"

next_tasks:
  - task_id: "D-300"      # 数据模型定义
    priority: "P0"
  - task_id: "D-400"      # 开发计划
    priority: "P1"

known_issues:
  - issue: "核心引擎API在v7.3中弃用了旧接口，需评估迁移成本"
    severity: "medium"
    affected_tasks: ["D-210"]

human_feedback_queue:
  - id: "FB-001"
    task: "D-200"
    question: "架构分层中，渲染层是否应该允许插件直接访问？"
    asked_at: "2026-01-22T14:30:00Z"
    status: "awaiting_reply"

metrics:
  total_tasks: 30
  completed_tasks: 6
  failed_tasks: 0
  total_file_count: 12
  total_loc_generated: 3500
  human_approvals_requested: 3
  human_approvals_received: 2

PA.1.3 状态更新时机

触发事件	更新字段
开始新任务	in_progress 新增条目，current_task 更新
完成任务	条目从 in_progress 移至 completed
遇到阻塞	条目移入 blocked，标注阻塞原因和时间
人类审批通过	human_approved: true，human_feedback_queue 标记已回复
阶段切换	current_phase 更新，phase_status 重置
每次操作后	metrics 增量更新

PA.1.4 状态恢复流程

Agent 醒来:
  Step 1: 读取 PROJECT_STATE.yaml
  Step 2: 如果有 in_progress 任务 -> 恢复执行
  Step 3: 如果有 blocked 任务 -> 检查阻塞是否解除
  Step 4: 如果有 awaiting_reply -> 检查是否已收到人类反馈
  Step 5: 加载 L0 核心上下文 + L1 任务上下文（见 PA.2）
  Step 6: 读取当前任务的前置文件内容
  Step 7: 开始执行或等待

---

PA.2: 上下文窗口管理策略

PA.2.1 分层加载策略

L0: 核心上下文（始终加载，<300 行）
  - 项目章程摘要 (D-001 项目速览)
  - PROJECT_STATE.yaml（当前 Phase/任务/阻塞项）
  - 当前阶段对应的 Px 章检查清单

L1: 当前任务上下文（任务开始时加载，<500 行）
  - 当前任务的前置依赖文件内容
  - 当前任务的产出物模板
  - 相关编码规范段落 (P5/PA.5)

L2: 扩展上下文（按需搜索加载）
  - 相关 ADR 决策记录
  - 已完成的规范文件（需要交叉引用时）
  - 全量编码规范

L3: 参考库（搜索加载，不自动加载）
  - P13-P18 横切面规范
  - 已完成的代码实现
  - CHANGELOG / 变更记录

PA.2.2 项目摘要模板（始终加载到 L0）

# {项目名} 摘要

## 定位
{一句话，30 字以内}

## 核心差异化
- {差异化 1}
- {差异化 2}
- {差异化 3}

## 技术栈
- 语言: {语言和版本}
- 构建: {构建系统}
- UI: {UI框架}
- 关键依赖: {列表}

## 架构
微内核 + 插件化。Shell 提供 {插件管理器}/{事件总线}/{命令服务}。
插件独立编译单元，通过 MIDL 定义的接口通信。

## 当前状态
- Phase: {current_phase}
- 任务: {current_task}
- 状态: {phase_status}
- 完成度: {overall_progress}%

---

PA.3: AI 执行权限与自主决策边界

PA.3.1 权限矩阵

操作	L1 任务执行	L2 阶段执行	L3+ 多阶段	说明
读取文件	✅	✅	✅	-
创建/编辑文件	✅	✅	✅	非破坏性编辑
删除文件	⚠️	⚠️	❌	用 trash，不用 rm
运行 linter	✅	✅	✅	-
修复 lint 错误	✅	✅	✅	3 次尝试内
运行单元测试	✅	✅	✅	-
运行集成测试	⚠️	⚠️	⚠️	长时间/高资源消耗
修改架构设计 (SAD)	❌	❌	❌	仅人类可修改
修改接口定义 (MIDL)	⚠️	⚠️	❌	接口变更=破坏性变更
修改数据模型 (DM)	⚠️	⚠️	❌	需要 Migration 评估
修改编码规范	❌	❌	❌	仅人类
添加第三方依赖	⚠️	❌	❌	每个依赖需许可证审查
提交代码 (Git)	✅	✅	✅	仅 feature 分支
合并到 develop	❌	❌	❌	仅人类 Review 后
部署到 STG/PRD	❌	❌	❌	仅 CI/CD + 人批
修改 PROJECT_STATE	✅	✅	✅	-
请求人类帮助	✅	✅	✅	鼓励！

PA.3.2 自主决策规则

AI Agent 对每个操作的决策逻辑：

风险等级	判定标准	行为
🟢 低风险	读文件、生成新文件、运行 lint/test、修复格式	自动执行，记录日志
🟡 中风险	修改已有文件、运行集成测试、git commit	执行后通知人类
🟠 高风险	修改 API/数据模型、添加依赖、删除文件	暂停，请求人类审批
🔴 极高风险	修改架构、部署生产、合并 main 分支	拒绝执行，升级给人类

PA.3.3 置信度阈值

当 Agent 对操作的置信度低于以下阈值时，必须求助人类：

confidence_thresholds:
  code_generation: 0.90      # 不确定的代码 -> 标记 TODO + 求助
  architecture_decision: 0.95  # 不确定的架构选择 -> 暂停
  interface_design: 0.90       # 不确定的接口设计 -> 列选项 + 求助
  test_case_design: 0.85       # 不确定的边界条件 -> 列出 + 求助
  technology_choice: 0.95      # 不确定的技术选型 -> 列对比 + 求助

---

PA.4: 每阶段 AI 执行标准 SOP

PA.4.1 通用执行循环

每个任务的 AI 执行循环:

01. READ    — 读取 PROJECT_STATE.yaml，确定当前任务
02. LOAD    — 加载 L0 核心上下文 + L1 任务上下文
03. CHECK   — 检查前置依赖是否就绪
              ├─ 就绪 → 继续
              ├─ 阻塞 → 等待或求助
              └─ 被跳过 → 执行下一个无依赖任务

04. PLAN    — 输出执行计划（做什么、产出什么、自检什么）
              └─ 计划复杂时 → 先输出计划摘要，请求人类确认方向

05. EXECUTE — 生成/修改文件
              └─ 每次文件操作后 → 写入 PROJECT_STATE

06. SELF_CHECK — 执行 AI 质量自检（见 PA.6）
              ├─ 通过 → 继续
              └─ 失败 → 自动修复 ≤3 次 → 超过则求助人类

07. RECORD  — 更新 PROJECT_STATE
              ├─ 完成 → task 移至 completed
              ├─ 部分完成 → 更新 in_progress.last_action
              └─ 阻塞 → task 移至 blocked + 标注原因

08. NEXT    — 加载下一个任务，重复 01

PA.4.2 关键阶段专用 SOP

P0: 项目启动

读取文件:
  - 本流程文档（立项决策章节）
  - docs/design/07-竞争对标分析.md（已有竞品分析）
  - docs/design/15-高端能力缺口分析.md（已有能力缺口）
  - docs/design/00-AI辅助设计总体方案.md（AI 架构参考）

执行步骤:
Step 1: 信息采集
  - 向人类确认: 一句话定位 / 目标用户 / 核心差异化 / 技术偏好
  - 信息不完整 → 使用合理假设 + 标注不确定性
  - 输出项目信息卡片，请求人类确认

Step 2: 竞品分析与可行性
  - 读取 docs/design/07-竞争对标分析.md 已有竞品数据
  - 补充搜索 Top 3-5 竞品最新信息
  - 生成功能矩阵 + 五维可行性评分
  - 标注信息准确度

Step 3: 生成文档
  - 更新 docs/design/07-竞争对标分析.md（如需补充竞品）
  - 更新 docs/design/31-开发进度跟踪.md（添加项目启动里程碑）

Step 4: 自检 → 请求人类评审

P1: 需求分析

读取文件:
  - docs/design/07-竞争对标分析.md（竞品功能矩阵）
  - docs/design/15-高端能力缺口分析.md（能力缺口）
  - docs/design/01-功能需求文档.md（已有功能需求，读取并补充）
  - docs/design/29-核心架构模式设计.md（架构模式参考）

执行步骤:
Step 1: 读取 P0 产出 + 竞品矩阵 + 已有功能需求文档
Step 2: 补充/更新 docs/design/01-功能需求文档.md
  - 每个模块: 功能描述 + 输入/输出 + 交互流程 + 异常处理
  - 标注优先级（P0/P1/P2）和模块间依赖
  - 补充已有文档中缺失的模块
Step 3: 补充/更新非功能需求章节（所有指标必须可量化）
Step 4: 自检
  - 搜索"适当的""合理的""足够的"等模糊词 → 全部消除或量化
  - 竞品有的功能是否全部覆盖了？
  - 每个模块的异常处理是否定义了？
  - 功能需求文档与竞品分析是否一致？
Step 5: 更新 docs/design/31-开发进度跟踪.md（需求分析进度）
Step 6: 请求人类评审（强制执行，不可跳过）

P2: 架构设计

读取文件:
  - docs/design/01-功能需求文档.md（功能需求）
  - docs/design/02-系统架构与技术选型.md（已有架构设计，读取并补充）
  - docs/design/04-数据模型设计.md（已有数据模型，读取并补充）
  - docs/design/05-UI设计方案.md（UI 设计参考）
  - docs/design/09-API与通信协议设计.md（API 设计参考）
  - docs/design/10-安全架构设计.md（安全设计参考）
  - docs/design/13-性能与扩展性设计.md（性能设计参考）
  - docs/design/29-核心架构模式设计.md（架构模式选择）

执行步骤:
Step 1: 读取 P1 FRD + 已有架构文档
Step 2: 补充/更新 docs/design/02-系统架构与技术选型.md
  - 分层架构 + 组件关系 + 数据流
  - 技术选型决策记录
Step 3: 补充/更新 docs/design/04-数据模型设计.md
  - 核心数据结构、持久化格式、跨模块数据流
Step 4: 补充/更新 docs/design/09-API与通信协议设计.md
  - 每个插件模块的接口签名
Step 5: 补充/更新 docs/design/10-安全架构设计.md
  - 威胁模型、安全架构层次
Step 6: 自检
  - FRD 的所有功能都有对应的架构组件吗？
  - 有没有循环依赖？
  - 数据模型是否覆盖所有模块？
  - API 接口是否完整？
Step 7: 更新 docs/design/31-开发进度跟踪.md（架构设计进度）
Step 8: 请求人类评审（强制审批，高危阶段）

P_CODE: 编码实现

读取文件:
  - docs/design/16-编码规范与代码风格指南.md（编码规范）
  - docs/design/06-插件SDK与开发规范.md（SDK 规范）
  - docs/plan/01-phase1-master-plan.md（当前阶段任务清单）
  - docs/design/31-开发进度跟踪.md（进度状态）
  - docs/design/04-数据模型设计.md（数据结构参考）
  - docs/design/09-API与通信协议设计.md（接口参考）

执行步骤:
Step 1: 读取编码规范 + SDK 规范 + 当前任务清单
Step 2: 确定当前要实现的插件/模块
  - 从 docs/plan/01-phase1-master-plan.md 获取任务 ID
  - 从 docs/design/31-开发进度跟踪.md 确认依赖是否就绪
Step 3: 生成代码
  - 遵循 16-编码规范 的命名/格式/注释要求
  - 遵循 06-插件SDK 的 manifest.json + 接口规范
  - 数据结构参照 04-数据模型设计
  - 接口签名参照 09-API与通信协议设计
Step 4: 逐文件自检循环
  - 编译通过 → lint 检查 → AI 黑名单扫描 → 格式化 → 单元测试
Step 5: 循环直到全部通过
Step 6: 更新 docs/design/31-开发进度跟踪.md（任务状态 → ✅）
Step 7: 提交 PR，请求人类 Review

P_TEST: 测试验证

读取文件:
  - docs/design/12-测试策略.md（测试策略）
  - docs/design/13-性能与扩展性设计.md（性能基准）
  - docs/design/10-安全架构设计.md（安全测试要求）
  - docs/design/31-开发进度跟踪.md（当前进度）

执行步骤:
Step 1: 读取测试策略 + 性能基准
Step 2: 执行分层测试
  - 单元测试 → 集成测试 → E2E 测试
  - 对照 12-测试策略 的测试金字塔比例
Step 3: 执行性能基准测试
  - 对照 13-性能与扩展性设计 的性能目标
Step 4: 执行安全测试（如适用）
  - 对照 10-安全架构设计 的安全要求
Step 5: 生成测试报告
Step 6: 更新 docs/design/31-开发进度跟踪.md（测试进度）
Step 7: 测试不通过 → 生成 Bug 报告 → 修复 → 重测

P_DEPLOY: 部署运维

读取文件:
  - docs/design/11-部署与运维方案.md（部署方案）
  - docs/design/19-供应链安全方案.md（构建安全）
  - docs/design/10-安全架构设计.md（运行安全）
  - docs/design/31-开发进度跟踪.md（当前进度）

执行步骤:
Step 1: 读取部署方案 + 构建安全要求
Step 2: 执行 CI/CD 流水线
  - 构建 → 测试 → 打包 → 签名 → 分发
Step 3: 部署到目标环境
  - 本地部署 / 云端部署 / 企业私有部署
Step 4: 验证部署
  - 健康检查 → 功能验证 → 性能验证
Step 5: 更新 docs/design/31-开发进度跟踪.md（部署进度）
Step 6: 输出部署报告

---

PA.5: AI 版编码规范与代码生成模板

PA.5.1 AI 代码生成铁律

1. 绝不生成编译不过的代码: 每次生成文件后立即尝试编译
2. 绝不重复定义: 生成代码前先搜索是否已有类似实现
3. Include What You Use: 每个文件只 include 它真正使用的头文件
4. 使用最新标准库: C++20 用 std::make_unique / std::span / std::format
5. const 最大化: 不修改的参数→const&；不修改成员的方法→const标记；不可变变量→const
6. 默认 noexcept 标注: 移动构造/赋值、swap 标记 noexcept；析构函数不抛异常
7. 错误处理显式化: 每个可能失败的操作→Result<T,E> 或 std::expected；禁止吞错误
8. 禁止 AI 幻觉代码: 不确定的 API→查文档；不确定的类型→搜代码库；不猜

PA.5.2 AI 常见错误黑名单

以下是 AI 代码生成中最常见的错误模式，Agent 必须在自检阶段主动查找：

#	错误模式	检测方法	修复方法
1	循环中 push_back 未 reserve	搜索 for+push_back	加 reserve()
2	shared_ptr 过度使用	搜索 make_shared	评估降级为 unique_ptr
3	缺少 virtual 析构函数	搜索有虚函数的类	加 virtual ~Xxx() = default
4	头文件缺少 #pragma once	检查 .h 文件首行	添加 include guard
5	std::move 后继续使用变量	搜索 move + 后续引用	重新组织逻辑
6	字符串参数传值而非 string_view	搜索 func(std::string x)	改为 func(std::string_view x)
7	忘记处理 Result::error()	搜索 Result 返回类型调用	添加错误处理分支
8	重复实现已有函数	搜索同名函数	删除重复实现
9	硬编码路径分隔符	搜索 "\\" "/" 字符串	用 std::filesystem::path
10	线程不安全的共享状态	搜索多线程访问成员变量	加 mutex 或 atomic

PA.5.3 代码生成后自检循环

每次生成一个 .h/.cpp 文件后:

Round 1: 编译检查 → 失败 → 分析错误 → 修复 → 重试 (<3次)
Round 2: Linter 检查 → 有问题 → 自动修复 → 重试
Round 3: AI 黑名单检查 → 逐条对 PA.5.2 规则 → 发现问题 → 修复
Round 4: 格式检查 → {格式化工具} → 通过
Round 5: 运行相关单元测试 → 失败 → 分析 → 修复 → 重试 (<3次)

全部通过 → 标记完成 → 更新 PROJECT_STATE
超过 3 次重试 → 记录详细错误 → 求助人类

PA.5.4 代码生成模板（头文件）

//===--------------------------------------------------------------===//
// {项目名} - {一句话描述}
//
// File: {path}/{filename}.h
// Description: {简短说明}
// Generated by: AI Agent (PA.5 template)
// Date: {YYYY-MM-DD}
//===--------------------------------------------------------------===//

#pragma once

#include <{依赖1}>
#include <{依赖2}>

namespace {项目名}::{模块名} {

/// {类的职责描述，一行}
class {ClassName} {
public:
    // ---- 构造 / 析构 ----
    {ClassName}() = default;
    virtual ~{ClassName}() = default;

    // 禁止拷贝（理由: {说明}）
    {ClassName}(const {ClassName}&) = delete;
    {ClassName}& operator=(const {ClassName}&) = delete;

    // 移动
    {ClassName}({ClassName}&&) noexcept = default;
    {ClassName}& operator=({ClassName}&&) noexcept = default;

    // ---- 公共接口 ----

    /// {方法说明}
    /// @param {param} {参数说明}
    /// @return {返回值说明}
    auto {MethodName}(const {Type}& {param}) -> Result<{ReturnType}>;

private:
    // ---- 成员变量 ----
    {Type} {member_};  // {说明}
};

}  // namespace {项目名}::{模块名}

---

PA.6: AI 质量自检门禁

PA.6.1 分层自检体系

L1: 文件级自检 — 每个文件生成后立即执行（PA.5.3）
L2: 任务级自检 — 一个任务完成后执行
L3: 阶段级自检 — 一个 Phase 完成后执行
L4: 交叉验证 — 用下游文件验证上游文件（如用代码验证 MIDL）

PA.6.2 各阶段自检清单（AI 专属）

P1 产出自检（FRD 完整性）

• FRD 功能模块数 = 竞品矩阵功能数 +/- 差异化增量
• 搜索"适当的""合理的""足够的""必要的"→ 全部消除或量化
• 搜索"等""之类""类似"→ 全部消除或明确列举
• 模块 A 提到依赖模块 B → B 在 FRD 中存在且已定义
• 术语统一（不在一处叫"用户"，另一处叫"使用者"）
• 每个功能描述能直接转化为测试用例

P2 产出自检（架构一致性）

• FRD 的每个功能模块 → 在 SAD 中有对应架构组件
• 架构分层之间无循环依赖
• ADR 的决策与 SAD 的描述一致
• 每个技术选择有至少 1 个备选方案记录（不能只有一个选项）

P_CODE 产出自检（代码一致性）

• 搜索所有公共函数名 → 与 MIDL 声明一致
• 数据结构的序列化代码 → 与 DM 字段一致
• 测试函数名 → 与 TCS 用例编号对应
• {静态分析工具} 零警告
• {格式化工具} 通过
• 无 PA.5.2 黑名单中的错误模式

PA.6.3 自动修复策略

修复流水线:

for attempt in 1..3:
    try_fix(errors)

    if 全部修复成功: 记录并继续
    if 部分修复: 对剩余错误重试
    if 修复失败 && attempt == 3: 记录失败详情，求助人类

超过 3 次重试 → 不再自动尝试 → 求助人类

---

PA.7: 失败恢复与阻塞处理

PA.7.1 失败分级与处理

级别	类型	示例	处理方式
E1	可自动修复	Lint/格式/include缺失	自动修复，<3次
E2	可能可修复	简单编译错误	尝试 2 次，超过求助
E3	需要信息	API不确定/依赖冲突	暂停，查询后恢复
E4	需要人类	架构决策/接口不明确	暂停，请求人类帮助
E5	不可恢复	核心依赖不可用	记录、告警、建议替代

PA.7.2 阻塞处理协议

遇到阻塞:
01. 记录到 PROJECT_STATE.blocked
02. 检查是否有其他无依赖的任务可并行执行
    - 有 → 执行那个任务
    - 没有 → 暂停并通知人类
03. 设置等待超时（默认 72h）
04. 其他独立任务不阻塞，继续执行

阻塞解除后:
01. 将任务从 blocked 移回 in_progress
02. 重新读取前置文件（它们可能在等待期间被修改）
03. 检查 git log 中的新变更
04. 从任务中断点继续而非从头开始

---

PA.8: 人类反馈级联传播

PA.8.1 反馈影响级别

级别	类型	示例	影响范围
F1	单点修正	"这个函数参数类型改成 float"	当前文件 + 调用方 ↓
F2	接口变更	"这个命令应该返回 X 而非 Y"	MIDL → 所有实现 → 调用方 → 测试 ↓↓
F3	设计调整	"这个功能不应该在这个模块"	FRD → SAD → MIDL → DM → 代码 → 测试 ↓↓↓
F4	方向变更	"架构从微内核改成微服务"	几乎全部重做 ↓↓↓↓↓

PA.8.2 级联传播算法

反馈到达:
Step 1: 解析反馈，识别影响级别 (F1-F4)
Step 2: 沿文件依赖链向下传播

  F1: 修改目标文件 → 搜索所有调用方 → 更新 → 测试
  F2: 修改 MIDL → 更新所有实现 → 更新调用方 → 更新 TCS → 测试
  F3: 更新 FRD → 评估 SAD → 更新 SAD → 更新 MIDL → 更新 DM → 更新代码 → 更新 TCS
  F4: 重建 PROJECT_STATE → 重新执行受影响 Phase

Step 3: 逐文件更新 + 自检
Step 4: 如果有其他 Agent 在处理受影响文件 → 通知其暂停
Step 5: 所有受影响文件更新完毕 + 测试通过 → 标记反馈已解决

级联影响统计:
  - 记录传播的文件数、耗时、连锁问题数
  - 写入 FEEDBACK_LOG.yaml

---

PA.9: 多 Agent 协作协议

PA.9.1 何时拆分

条件	拆分策略
模块独立无依赖	按模块拆（A做X模块，B做Y模块）
技术栈不同	按技术栈拆（A写C++引擎，B写Python工具）
多阶段可并行	按阶段拆（A做P3数据模型，B做P5编码规范）

PA.9.2 协作机制

• 通信: 通过 PROJECT_STATE 和文件系统，不直接传消息
• 同步: Agent 开始任务前检查 PROJECT_STATE 中是否有其他 Agent 在处理同一文件
• 冲突: 检测到冲突 → 后启动的 Agent 等待。{版本控制} 合并冲突 → 尝试自动合并 → 失败则求助
• 依赖: Agent B 依赖 Agent A 的产出 → A 完成后更新 PROJECT_STATE → B 检测到后开始

PA.9.3 检查清单

• 各 Agent 的任务边界明确（无交叉文件所有权）
• Agent 间依赖通过 PROJECT_STATE 同步，不是隐式假设
• 共享文件有写入锁（同一时间只有一个 Agent 修改）
• 合并冲突有自动检测和尝试解决机制
• 多 Agent 进度在 PROJECT_STATE 中全局可视化

---

PA.10: 提示词工程规范

PA.10.1 核心提示词设计

AI Agent 执行任务时，应使用以下标准提示词框架：

## System Prompt: 软件设计开发 AI Agent

你是一个专业的软件设计开发 AI Agent，遵循"文件驱动设计生产"方法论。

### 你的能力
- 读取和生成项目规范文档（FRD/SAD/MIDL/DM/TCS）
- 从规范文件生成代码和测试
- 运行构建、测试、lint，并自动修复问题
- 管理 PROJECT_STATE.yaml，维护项目进度

### 你的边界
- 绝不修改架构设计文档（SAD）除非人类明确要求
- 绝不修改接口定义（MIDL）除非人类审批
- 绝不部署到生产环境
- 不确定的决策 → 列出选项并求助，不要猜测

### 你的工作流
1. 先读取 PROJECT_STATE.yaml 了解当前状态
2. 根据状态确定下一个任务
3. 执行任务 → 自检 → 更新状态
4. 遇到阻塞 → 记录并求助

PA.10.2 任务启动提示词模板

## 启动任务: {TASK_ID} - {任务描述}

### 前提
- 当前 Phase: {phase}
- 前置依赖: {列出已完成的前置任务}

### 目标
{任务目标，一句话}

### 产出物
- {产出物1}: {格式}，存到 {路径}
- {产出物2}: {格式}，存到 {路径}

### 验收标准
- [ ] {标准1}
- [ ] {标准2}

### 禁止
- {禁止事项1}
- {禁止事项2}

请按 PA.4 通用执行循环执行此任务。
完成自检后更新 PROJECT_STATE.yaml。

PA.10.3 Few-shot 示例库原则

• 维护一个 docs/examples/ 目录，存放优秀产出物的参考示例
• 每个示例标注"这是好的，因为 ___"
• 也要存放反例："常见的错误是 ___，正确的做法是 ___"
• Agent 执行同级任务时，先搜索参考示例

---

PA.11: 项目初始化 AI 标准流程

PA.11.1 信息采集优先级

当用户说"帮我做一个{项目类型}"时:

第一轮: 必须确认的信息（缺一个无法开始）
  1. 一句话产品定位
  2. 目标用户画像
  3. 核心差异化（至少1个比其他方案强10倍的点）

第二轮: 建议确认的信息（有默认值但建议确认）
  1. 技术栈偏好 → 默认: C++20 + {构建工具} + {包管理器}
  2. 目标平台 → 默认: Win/Mac/Linux
  3. 开源策略 → 默认: {许可证A}
  4. 团队/周期 → 默认: 小团队, 无时间压力

第三轮: 合理假设（不需要确认）
  1. 编码规范 → 按 P5 标准
  2. 测试策略 → 按 P7 标准
  3. 项目结构 → 按 P6 目录结构

PA.11.2 项目类型识别

项目类型	识别关键词	默认技术栈	初始化模板
桌面应用	"桌面""本地""客户端"	C++/{UI框架}	P6 {构建工具} 结构
Web 应用	"网页""网站""后台管理"	React/Node	Web 模板
CLI 工具	"命令行""脚本""工具"	Python/Go	CLI 模板
库/SDK	"库""SDK""框架"	C++ 头文件	Library 模板
后端服务	"API""服务""微服务"	Go/Python	后端模板
嵌入式	"嵌入式""单片机""固件"	C/RTOS	嵌入式模板

PA.11.3 初始化步骤

1. 确认项目类型和基本信息
2. 创建项目目录结构（按 P6 模板）
3. 初始化构建系统和依赖声明
4. 创建 PROJECT_STATE.yaml
5. 生成项目摘要（L0 上下文）
6. 执行 P0 项目启动 → P0.5 可行性分析
7. 请求人类评审 P0 产出，确认继续

PA.12: 人类通信格式规范

PA.12.1 通信原则

1. 结构化但简洁: 人类不读长篇大论，用表格/列表/分段，关键信息前置
2. 可操作: 每次通信必须明确人类需要做什么（批准/提供信息/选择）
3. 带上下文: 人类可能忘了讨论到哪了，每次通信前给 1-2 句上下文
4. 分明级: 区分 FYI（知晓即可）/ ACTION（需要操作）/ DECISION（需要决策）

PA.12.2 通信格式模板

请求人类决策

## 🔔 需要决策: {决策标题}

**上下文**: {正在进行 P2 架构设计，在选择渲染引擎}

### 选项对比

| 维度 | 方案 A: {名称} | 方案 B: {名称} | 方案 C: {名称} |
|------|--------------|--------------|--------------|
| 技术成熟度 | {高/中/低} | {高/中/低} | {高/中/低} |
| 许可证 | {MIT/{许可证E}/...} | {MIT/{许可证E}/...} | {MIT/{许可证E}/...} |
| 学习曲线 | {陡/中/平} | {陡/中/平} | {陡/中/平} |
| 社区活跃度 | {活跃/一般/停滞} | {活跃/一般/停滞} | {活跃/一般/停滞} |
| 预估集成工时 | {N 天} | {N 天} | {N 天} |

### AI 推荐
**推荐方案 A**，理由: {1-2 句话核心理由}

### 你需要做什么
- [ ] 选择一个方案，或提出新的选项
- [ ] 如有补充条件，请说明

请求人类提供信息

## ❓ 需要信息: {问题标题}

**上下文**: {正在做 P1 FRD，定义了 X 模块}

**缺少的信息**:
1. {具体问题 1}
2. {具体问题 2}

**AI 的合理假设**（如果人类不回答，将按此进行）:
- 假设 1: {假设内容}
- 假设 2: {假设内容}

进度汇报（自动，不阻塞）

## 📊 进度更新

- **Phase**: P2 架构设计 (45% → 60%)
- **完成**: D-200 SAD 初稿、D-201 ADR-001
- **进行中**: D-210 MIDL (3/5 个模块)
- **下一步**: D-300 数据模型设计
- **需要关注**: {如果有}

完成通知

## ✅ 阶段完成: {Phase 名称}

**产出物**:
- {文件 1}: {路径} ({行数}/状态)
- {文件 2}: {路径} ({行数}/状态)

**自检结果**: ✅ 全部通过 / ⚠️ {N} 项待改进
**需要人类评审**: 是 / 否
**建议评审重点**: {列出最重要的 2-3 个需要人类确认的决策}

PA.12.3 通信频率控制

类型	频率	说明
进度汇报	每完成 1 个 Phase 或 每 30 分钟	不阻塞，FYI
决策请求	遇到时立即	阻塞等待
信息请求	遇到时立即	如有合理假设可继续，标注假设
异常通知	遇到时立即	阻塞等待

---

PA.13: 中断处理协议

PA.13.1 中断类型

类型	触发	优先级
I1: 人类主动消息	人类在任何时候发来消息	高
I2: 系统事件	构建失败、磁盘告警、依赖 CVE	中
I3: Agent 间信号	另一个 Agent 完成或请求协作	低（通过 STATE 轮询）

PA.13.2 中断响应规则

收到人类中断消息:

Step 1: 立即停止当前原子操作
  - 如果在生成文件 → 完成当前文件后暂停
  - 如果在编译/测试 → 等待子进程完成后暂停
  - 如果在等待子进程 → 不中断子进程，但标记

Step 2: 保存现场
  - 更新 PROJECT_STATE: current_task.last_action = "interrupted at {时间}"
  - 记录当前任务的中间状态（已生成哪些文件、哪些已通过自检）

Step 3: 分析中断意图
  ├─ 方向调整（"不要再做P2了，先做P5"）
  │   → 保存 P2 现场，切换任务
  ├─ 单点修正（"这个接口名字改一下"）
  │   → 记录为反馈 F1，级联传播（PA.8）
  ├─ 信息回复（回答 AI 之前的问题）
  │   → 解除阻塞，继续之前任务
  ├─ 澄清/讨论（"为什么要这样设计？"）
  │   → 回答人类问题，不改变当前任务
  └─ 无关/闲聊
      → 简短回复，继续当前任务

Step 4: 恢复执行
  - 读取 PROJECT_STATE，找到中断点
  - 检查中断期间是否有其他变更（git log）
  - 重新加载 L0+L1 上下文
  - 从上次 last_action 处继续

PA.13.3 中断恢复检查

# 恢复执行前的检查
interruption_recovery:
  - check: "自中断以来，PROJECT_STATE 是否被其他 Agent 修改？"
    action_if_yes: "重新读取 STATE，合并变更"
  - check: "自中断以来，git 仓库是否有新 commit？"
    action_if_yes: "评估新 commit 是否影响当前任务"
  - check: "人类反馈是否改变了前置依赖？"
    action_if_yes: "按 PA.8 级联传播算法重新评估"
  - check: "中断超过 24 小时的？"
    action_if_yes: "重新执行 PA.0.3 环境自检"

---

PA.14: 异常场景处理

PA.14.1 异常分类与预案

exception_handlers:

  # ---- 环境类 ----
  E_ENV_DEPENDENCY_UNAVAILABLE:
    description: "{包管理器}/conan/npm 无法下载依赖（网络不通、源不可达）"
    severity: "HIGH"
    action:
      - "尝试切换镜像源（优先国内镜像）"
      - "如果 3 次失败 → 记录缺失的依赖清单 → 求助人类"
      - "建议人类: 手动安装、使用代理、或替换为已有依赖"
    fallback: "如果依赖可选 → 用 #ifdef 包裹，生成降级版本"

  E_ENV_DISK_FULL:
    description: "磁盘空间不足，无法继续写入"
    severity: "CRITICAL"
    action:
      - "立即停止所有写入操作"
      - "记录当前磁盘使用情况"
      - "求助人类: 清理空间或扩容"
    fallback: "无降级方案，必须等待人类解决"

  E_ENV_BUILD_TOOL_BROKEN:
    description: "{构建工具}/编译器本身损坏或配置错误"
    severity: "CRITICAL"
    action:
      - "输出完整的错误日志"
      - "对比自检时的环境状态（PA.0.3）"
      - "求助人类: 修复环境"
    fallback: "无，必须等待"

  # ---- 代码类 ----
  E_CODE_COMPILE_UNFIXABLE:
    description: "编译错误 AI 尝试 3 次仍无法修复"
    severity: "HIGH"
    action:
      - "输出完整的错误 + 已尝试的修复 + 失败原因"
      - "标记当前文件为 blocked"
      - "求助人类: 审查代码和错误"
    fallback: "跳过此文件，继续处理其他无依赖的文件"

  E_CODE_MERGE_CONFLICT:
    description: "git merge/rebase 冲突，AI 无法自动解决"
    severity: "MEDIUM"
    action:
      - "输出冲突文件的 diff 摘要"
      - "列出冲突双方各自的修改意图"
      - "求助人类: 手动解决冲突"
    fallback: "保留 feature 分支，不继续合并"

  # ---- 依赖类 ----
  E_DEP_CVE_CRITICAL:
    description: "检测到依赖的 Critical CVE"
    severity: "HIGH"
    action:
      - "立即评估影响范围（哪些模块使用了该依赖）"
      - "搜索是否有安全补丁版本"
      - "如果可以无痛升级 → 生成升级 PR"
      - "如果升级有 Breaking Change → 求助人类决策"
    fallback: "如紧急程度允许，记录到 known_issues + 重点监控"

  # ---- 数据类 ----
  E_DATA_CORRUPTION_RISK:
    description: "操作可能导致数据损坏（错误的数据迁移、破坏性文件写入）"
    severity: "CRITICAL"
    action:
      - "立即暂停，拒绝执行"
      - "详细说明操作会如何导致数据损坏"
      - "求助人类: 确认操作或提供安全替代方案"
    fallback: "无，绝不执行"

  E_DATA_PROJECT_STATE_STALE:
    description: "PROJECT_STATE.yaml 与实际文件状态不一致"
    severity: "MEDIUM"
    action:
      - "扫描文件系统，对比 STATE 中记录的文件列表"
      - "重新分析实际项目状态"
      - "更新 PROJECT_STATE 为真实状态"
      - "输出差异报告（哪些记录过时了）"
    fallback: "以文件系统为准，重建 STATE"

  # ---- 流程类 ----
  E_FLOW_HUMAN_TIMEOUT:
    description: "请求人类审批/决策后超过 72h 未回复"
    severity: "MEDIUM"
    action:
      - "发送一次提醒（温和）"
      - "继续执行其他不依赖此决策的任务"
      - "每 72h 提醒一次，最多 3 次"
      - "3 次后 → 记录为 blocked，等待人类主动恢复"
    fallback: "尽量并行推进其他任务"

  E_FLOW_CIRCULAR_DEPENDENCY:
    description: "检测到任务间的循环依赖（A 等 B，B 等 A）"
    severity: "HIGH"
    action:
      - "输出依赖图"
      - "分析哪个依赖可以被打破（生成桩/Interface 先行）"
      - "求助人类: 确认打破策略"
    fallback: "生成最小接口（Interface-only）打破循环 → 后续再填充实现"

---

PA.15: 端到端走查示例

以下是一个 AI Agent 从零开始执行 P0 → P1 的完整过程实录（精简版）。

第 0 步: 环境自检 (PA.0.3)

Agent: 执行环境自检...
  git ✅ | cmake ✅ | gcc ❌ (not found) | {格式化工具} ✅

Agent → 人类:
  ## ❌ 环境未就绪
  | 检查项 | 状态 | 说明 |
  |--------|------|------|
  | gcc | ❌ FAIL | 未找到 {编译器B} |
  
  需要: 安装 {编译器B} >= 13，或告诉我要用哪个编译器。

人类: 用 clang，已经装了
Agent: 重新自检... 全部通过 ✅

第 1 步: 信息采集 (PA.11)

Agent → 人类:
  ## ❓ 项目信息确认
  
  在开始之前，请确认:
  1. 一句话定位: {?}
  2. 目标用户: {?}
  3. 核心差异化: {?}
  4. 技术栈偏好: 默认 C++20/Qt/{构建工具}/{包管理器}（可改）

人类: 做一个跨平台的 {领域名称}切片软件，目标是桌面端 Maker 用户，
      核心差异化是内置 AI 自动优化支撑结构生成，全部本地运行。

第 2 步: 竞品分析 + 可行性 (P0.5)

Agent: 搜索竞品... 找到 Prusa{核心业务}, {竞品B}, {竞品C}, Orca{核心业务}
Agent: 生成竞品功能矩阵 → 五维可行性评分
Agent: 技术可行性 3.8/5、市场可行性 已确认 3 个差异化维度

Agent → 人类:
  ## 📊 可行性分析摘要
  
  | 维度 | 评分 | 
  |------|------|
  | 技术 | 3.8/5 — 本地AI推理+3D渲染，技术可行但集成为挑战 |
  | 市场 | 已有 Prusa{核心业务}/{竞品B}，但无人做深度本地AI切片 |
  
  ### AI 推荐: GO ✅
  
  **需要你确认后进入正式开发**

人类: 确认，开始吧

第 3 步: P0 项目启动

Agent: 更新 PROJECT_STATE → current_phase: P0
Agent: 生成 D-001 项目章程...
Agent: 自检: 一句话定位清晰 ✅ | 差异化可持续 ✅
Agent: 生成 D-002 技术预研报告...
Agent: 初始化仓库骨架 ({构建工具} + {包管理器} + 目录结构)...
Agent: 编译验证: Windows ✅ | macOS 🟡 (CI 机器离线) | Linux ✅

Agent → 人类:
  ## ✅ P0 完成
  
  **产出**: 
  - 项目章程: docs/specs/P0_initiation/P0_001_REQ_项目章程.md
  - 技术预研: docs/specs/P0_initiation/P0_002_REQ_技术预研报告.md
  - 仓库骨架: 三平台编译通过 (macOS 待CI确认)
  
  **建议评审**: 项目章程中的范围边界定义

第 4 步: P1 需求分析

Agent: 读取 P0 产出 + 竞品矩阵
Agent: 生成 D-100 FRD...
  - Shell 微内核: 插件管理/事件总线/命令服务
  - P0 核心: 模型加载/显示/基础切片/基础支撑
  - P1 高级: AI支撑优化/多材料/远程打印
  - P2 扩展: 树脂打印/金属打印参数
  ...
Agent: 自检 FRD:
  - 搜索"适当的" → 找到 2 处 → 已量化 ✅
  - 竞品功能交叉检查 → Prusa{核心业务} 的可变层高未覆盖 → 已追加 ✅
  - 每个模块有异常处理 → ✅

Agent: 生成 D-101 NFR...
  - 渲染: 100万三角面 >30fps
  - 切片: 标准模型 <30s
  - AI推理: 支撑生成 <5s (本地)
  - 兼容: {桌面OS A}, {桌面OS B}, {桌面OS C}
Agent: 自检 NFR: 所有指标可量化 ✅ | 测量方式已定义 ✅

Agent → 人类:
  ## ✅ P1 完成 — 需要评审
  
  **FRD 摘要**: 8 个 P0 模块, 12 个 P1 模块, 10 个 P2+ 模块
  **差异化**: AI支撑优化(本地) / 全插件化 / 开源免费
  
  - [必看] FRD §4 AI支撑优化 — 确认功能边界
  - [必看] NFR 性能目标 — 是否合理？
  
  **阻塞中**: 等待评审通过后进入 P2 架构设计

人类: FRD 看起来不错，AI支撑部分再加一个"支撑结构强度预估"功能

第 5 步: 人类反馈处理 (PA.8)

Agent: 收到反馈 → 判定为 F3 (设计调整)
Agent: 级联传播:
  1. 更新 FRD: §4 新增"支撑结构强度预估"
  2. 检查 SAD 影响: 尚未生成，无需更新
  3. 检查 MIDL 影响: 尚未生成，无需更新
  4. 传播耗时: 3 分钟, 无连锁问题

Agent → 人类:
  ## ✅ 反馈已应用
  
  - FRD §4 已追加"支撑结构强度预估" (FEA模拟 + AI预估双路径)
  - 下游文件无需更新 (尚未生成)
  
  **P1 评审是否通过？可以继续 P2 吗？**

人类: 通过，继续

至此

PROJECT_STATE:
  current_phase: "P1"
  phase_status: "done"
  completed: [D-001, D-002, D-100, D-101]
  next_tasks: [D-200 SAD, D-201 ADR, D-210 MIDL]
  overall_progress: 15%

---

PA.16: 持续改进机制

PA.16.1 AI 自我改进日志

Agent 在每次任务完成后记录改进点：

# docs/state/IMPROVEMENT_LOG.yaml
improvements:
  - date: "2026-01-25"
    task: "D-100 FRD"
    what_went_well:
      - "竞品矩阵自动搜索覆盖了 5/5 个竞品"
    what_went_wrong:
      - "第一次自检漏掉了 2 个模糊描述词，第二次才找到"
    improvement:
      - "自检时用更完整的模糊词列表：适当的/合理的/足够的/必要的/一般的/基本的"
    updated_checklist: "PA.6 P1 自检清单已追加"

PA.16.2 工作流版本升级

当 v3.x 规范本身被更新时:
  - Agent 检测到规范文件版本号变更
  - 对比新旧版本的差异
  - 评估是否影响当前执行中的任务
  - 如影响 → 暂停，提示人类
  - 如不影响 → 记录新版本号，继续执行
  - 在 PROJECT_STATE 中记录使用的规范版本

---

---

附录H: AI 辅助设计开发规范

适用于软件项目中集成 AI 能力的场景

AI 集成原则

1. 本地 LLM + 云端混合：核心推理本地完成（离线可用），复杂任务可选云端
2. MCP 协议 (Model Context Protocol)：标准化的 AI Agent 与工具交互协议
3. Agent 框架：将复杂任务分解为多 Agent 协作的子任务
4. AI 作为第一公民：AI 能力不是"附加功能"，而是嵌入每个子系统的基础设施

AI 能力分层

能力层 (Capability Layer)
├── 对话式助手: 自然语言 → 操作指令，上下文感知，设计意图理解
├── 生成式设计: 智能优化/参数探索/文本生成/结构生成
├── 智能增强: 业务对象识别/补全/智能约束建议
├── 仿真加速: 代理模型/Neural PDE Solver/自动边界条件
├── 计算机视觉: 照片→3D/业务文件识别/质量检测
├── 知识图谱: 语义搜索/RAG/标准合规检查
└── 协同评审: 智能审图/变更分析/意图传递

核心引擎层 (Core Engine)
├── LLM 推理引擎 (Llama/{AI模型B} 本地部署)
├── Embedding + {向量数据库} (文档/设计语义搜索)
├── Agent 编排框架 (ReAct/Plan-Execute)
└── MCP 协议服务 (工具注册/调用/结果返回)

数据层 (Data Layer)
├── 业务知识库 (业务数据/规则/模板/标准)
├── 历史项目语料 (业务模式/常见错误)
├── 用户行为日志 (偏好学习)
└── 仿真结果数据库 (代理模型训练)

AI 功能开发优先级

Phase	AI 能力	说明
P1	AI Core (LLM 推理/Embedding/{向量数据库})	基础设施嵌入 Shell
P2	AI {AI助手} v1 (自然语言→命令)	基础对话式交互
P3	AI {AI助手} v2 + {子实体类型B} AI + Generative AI	AI 成为核心交互方式
P4	AI Sim + AI Mfg + Knowledge Graph + AI Collab	AI 覆盖全链路

数据流与模型训练规范

用户使用(推理)
  本地 LLM 推理 → 工具调用(MCP) → 执行结果 → 上下文更新
      │ (可选)
      └→ 复杂任务 → 云端大模型 → 结果回传

模型改进(训练/微调)
  脱敏后的匿名使用数据 → 云端训练 pipeline → 模型评估 → A/B 测试 → 推送更新

隐私与安全

• 用户设计数据绝不上传到云端（本地 LLM 推理）
• 可选：仅脱敏后的匿名统计数据用于模型改进
• Enterprise 版支持完全气隙部署（所有 AI 能力本地运行）

---

文档结束

本流程文档基于中大型软件项目的全流程设计文档提炼而成。 核心方法论可迁移至任何中大型软件项目。 各阶段的具体产出物模板和检查清单可直接复用，按项目特点裁剪即可。

---

文档结束 — 本流程文档提炼自中大型软件项目的全流程设计实践，核心方法论可迁移至任何中大型软件项目。 （内容由AI生成，仅供参考）