From b915f44060994a563455932d61840d3cfc2ca367 Mon Sep 17 00:00:00 2001 From: hm-thinkbook16p Date: Fri, 24 Jul 2026 11:51:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=B2=BE=E7=AE=80README=E4=B8=BA?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E4=BB=8B=E7=BB=8D=EF=BC=8C=E5=88=A0=E9=99=A4?= =?UTF-8?q?=E9=87=8D=E5=8F=A0=E7=9A=84DDD=E5=85=A8=E6=96=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4831 +---------------------------------------------------- 1 file changed, 26 insertions(+), 4805 deletions(-) diff --git a/README.md b/README.md index 4264b38..bb5ec2c 100644 --- a/README.md +++ b/README.md @@ -1,4825 +1,46 @@ ---- -AIGC: - Label: "1" - ContentProducer: 001191440300708461136T1XGW3 - ProduceID: 3527d3b35d3fcd9fe5a95c4f3fe3651c_7c85a4b2863611f18766525400f8a581 - ReservedCode1: GJelXnb6XIFHzA5B0RhHFEVbxcWMoOagx3xHjbkphs5SovBGfeCprt5uJzJH7cEh9k3mIQc+hXoJaNpqqW4fENKOj+ieqoeypXu6tm00ckf4/g0YRorsGareI2eYzkluxtOZX2Jd1HMaEfdb4I3PLe98uQ4R1mCEOYqTuhj7D99Bb2E1/RGiHfSacVs= - ContentPropagator: 001191440300708461136T1XGW3 - PropagateID: 3527d3b35d3fcd9fe5a95c4f3fe3651c_7c85a4b2863611f18766525400f8a581 - ReservedCode2: GJelXnb6XIFHzA5B0RhHFEVbxcWMoOagx3xHjbkphs5SovBGfeCprt5uJzJH7cEh9k3mIQc+hXoJaNpqqW4fENKOj+ieqoeypXu6tm00ckf4/g0YRorsGareI2eYzkluxtOZX2Jd1HMaEfdb4I3PLe98uQ4R1mCEOYqTuhj7D99Bb2E1/RGiHfSacVs= ---- - ---- -AIGC: - Label: "1" - ContentProducer: 001191440300708461136T1XGW3 - ProduceID: 3527d3b35d3fcd9fe5a95c4f3fe3651c_feb391dc863411f18108525400287e28 - ReservedCode1: WElXjUfmRAFyb0JtMrkHMsRS0BH4hV/6M/LjdBXxmXc6cEbG5JfwrFTU3KN+oDXtgkadlYoYPmhQYiaabtIgx3iruEEHyOiOYW7wCjG4i4LWbjJX1cuIwhG4jFwVvcCC0hPiT9/FHhIeF4CmpneRtA/ZzQ2d7vVOEu1o7d9HhrptcURCMvi7EhpB1lQ= - ContentPropagator: 001191440300708461136T1XGW3 - PropagateID: 3527d3b35d3fcd9fe5a95c4f3fe3651c_feb391dc863411f18108525400287e28 - ReservedCode2: WElXjUfmRAFyb0JtMrkHMsRS0BH4hV/6M/LjdBXxmXc6cEbG5JfwrFTU3KN+oDXtgkadlYoYPmhQYiaabtIgx3iruEEHyOiOYW7wCjG4i4LWbjJX1cuIwhG4jFwVvcCC0hPiT9/FHhIeF4CmpneRtA/ZzQ2d7vVOEu1o7d9HhrptcURCMvi7EhpB1lQ= ---- - - - - - # 软件设计开发需求流程 -## 关于本指南 +> **版本**: v4.1 | **适用范围**: 通用软件项目 | **核心方法论**: 文件驱动设计（DDD）+ AI 全链路 -本指南是一份面向中大型软件项目的**通用设计开发流程方法论**。它定义了从项目启动到部署运维的完整生命周期，覆盖 18 个核心阶段 + P0.5 可行性分析 + PM 章文件驱动方法论 + PA 章 AI Agent 自主开发规范(含环境自检/通信/中断/异常/走查) + 附录，并融入了"文件驱动设计生产（Document-Driven Development）"方法论——让 AI 先生成规范文件，再以文件作为"单一事实来源"驱动后续的设计、编码、测试和部署。 +## 这是什么 -无论你正在构建 Web 应用、移动 App、桌面软件、后端服务、嵌入式系统还是平台型产品，都可以直接使用本指南中的流程模板、检查清单和工作流指令。每个阶段均包含：目标、输入物、产出物、关键步骤和检查清单，所有模板使用 `{占位符}` 标记，按项目特点替换即可。 +一份**通用的软件设计开发流程文档**，定义了从项目启动到部署运维的完整生命周期。核心理念是 **文件驱动设计（DDD）**——AI 先生成规范文件，再以文件作为"单一事实来源"驱动设计、编码、测试、部署全流程。 -> **版本**: v3.1 | **适用范围**: 中大型软件项目 | **核心理念**: 文件驱动设计 · 微内核+插件化 · 渐进式交付 · AI 嵌入全链路 +适用于 Web 应用、移动 App、桌面软件、后端服务、嵌入式系统、平台型产品等任何软件项目。 ---- +## 怎么用 -## 目录 +**方式一：直接给 AI 使用** -1. [流程全景图](#流程全景图) -2. [P0: 项目启动与需求收集](#p0-项目启动与需求收集) -3. [P0.5: 可行性分析](#p05-可行性分析) -4. [P1: 需求分析与功能规格](#p1-需求分析与功能规格) -5. [P1.5: 需求变更管理](#p15-需求变更管理) -6. [P2: 系统架构与技术选型](#p2-系统架构与技术选型) -7. [P2.5: API 版本管理与废弃策略](#p25-api-版本管理与废弃策略) -8. [P3: 数据模型设计](#p3-数据模型设计) -9. [P3.5: 数据迁移与回滚策略](#p35-数据迁移与回滚策略) -10. [P4: 开发计划与里程碑规划](#p4-开发计划与里程碑规划) -11. [P5: 编码规范与开发标准](#p5-编码规范与开发标准) -12. [P5.5: 国际化 (i18n) 与本地化 (L10n) 开发规范](#p55-国际化-i18n-与本地化-l10n-开发规范) -13. [P6: 构建系统与环境搭建](#p6-构建系统与环境搭建) -14. [P6.5: 多环境管理规范](#p65-多环境管理规范) -15. [P7: 测试策略与质量保障](#p7-测试策略与质量保障) -16. [P8: 开发工作流与协作规范](#p8-开发工作流与协作规范) -17. [P9: 部署与运维](#p9-部署与运维) -18. [P9.5: 线上事故响应流程](#p95-线上事故响应流程) -19. [P9.6: 功能开关 (Feature Flag) 与灰度发布](#p96-功能开关-feature-flag-与灰度发布) -20. [P10: 用户反馈与迭代闭环](#p10-用户反馈与迭代闭环) -21. [P11: 技术债务与风险管理](#p11-技术债务与风险管理) -22. [P12: 项目记忆与知识管理](#p12-项目记忆与知识管理) -23. [P13: 安全开发生命周期 (SDL)](#p13-安全开发生命周期) -24. [P14: 合规性管理](#p14-合规性管理) -25. [P15: 供应链安全](#p15-供应链安全) -26. [P16: 无障碍访问 (a11y) 规范](#p16-无障碍访问-a11y-规范) -27. [P17: 依赖升级管理](#p17-依赖升级管理) -28. [P18: 团队沟通与知识传递](#p18-团队沟通与知识传递) -29. [PM: 文件驱动设计生产规范（Document-Driven Development）](#pm-文件驱动设计生产规范document-driven-development) -30. [PA: AI Agent 自主开发操作规范 (含环境自检/通信/中断/异常/走查)](#pa-ai-agent-自主开发操作规范) -31. [附录: AI 辅助设计开发规范](#附录-ai-辅助设计开发规范) +将 `软件设计开发需求流程.md` 提供给 AI，AI 会按照文档中的流程和 PA 章规范，自动完成从需求分析到代码产出的全过程。 ---- +**方式二：人工参考执行** -## 流程全景图 +按文档中 0-14 章的流程顺序，逐步完成各阶段的产出物。所有模板使用 `{占位符}` 标记，替换为你的项目信息即可。 -``` -┌──────────────────────────────────────────────────────────────────────────┐ -│ 软件设计开发需求流程 — 全面生命周期 │ -├──────────────────────────────────────────────────────────────────────────┤ -│ │ -│ P0: 项目启动 → P1: 需求分析 → P2: 架构设计 → P3: 数据模型 │ -│ ↓ ↓ ↓ ↓ │ -│ P4: 开发计划 → P5: 编码规范 → P6: 构建系统 → P7: 测试策略 │ -│ ↓ ↓ ↓ ↓ │ -│ P8: 开发协作 → P9: 部署运维 → P10: 用户反馈 → P11: 风险管理 │ -│ ↓ ↓ ↓ ↓ │ -│ P12: 项目记忆（贯穿始终） │ -│ │ -│ ═══════════════════════════════════════════════════════════════════ │ -│ 核心理念: │ -│ - 文件驱动设计: AI先产出规范文件，以文件为"单一事实来源"驱动全流程（见PM章）│ -│ - 微内核+插件化: 最小内核 + 功能通过插件扩展，实现松耦合、热插拔 │ -│ - 渐进式交付: 4-Phase 路线图，每阶段有明确里程碑与验收标准 │ -│ - AI 嵌入全链路: 需求→设计→编码→测试→运维，AI 作为第一公民 │ -│ - 开发者体验优先: 脚手架工具、标准化 SDK、完整文档、清晰入职路径 │ -└──────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## PM: 文件驱动设计生产规范（Document-Driven Development） - -### 概述 - -**文件驱动设计生产（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) │ │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### 各阶段产出文件清单 - -| 阶段 | 文件编号 | 文件名 | 文件类型 | 作用 | 下游消费者 | -|------|----------|--------|----------|------|-----------| -| P0 | D-001 | 项目章程 | `.md` | 定义项目愿景、范围、边界 | P1 FRD, P2 SAD | -| P0 | D-002 | 技术预研报告 | `.md` | 核心技术可行性结论 | P2 ADR, P2 技术选型 | -| P1 | D-100 | 功能需求规格书 (FRD) | `.md` | 全模块功能描述、优先级 | P2 SAD, P3 DM, P7 TCS | -| P1 | D-101 | 非功能性需求清单 (NFR) | `.md` | 性能/安全/兼容性指标 | P2 SAD, P7 TSP | -| P2 | D-200 | 系统架构设计书 (SAD) | `.md` + 架构图 | 分层架构、组件关系、数据流 | P3 DM, P4 DPM, P_CODE | -| P2 | D-201 | 技术选型决策记录 (ADR) | `.md`（每决策一篇） | 重大技术决策背景与理由 | P6 BCM | -| P2 | D-210 | 模块接口定义文件 (MIDL) | `.json` / `.yaml` | 各模块对外接口签名 | P_CODE, P7 TCS | -| P3 | D-300 | 数据模型定义文件 (DM) | `.json` / `.yaml` | 实体定义、字段、关系 | P_CODE, D-310 | -| P3 | D-310 | 数据库 Schema / 文件格式规范 | `.sql` / `.md` | 持久化结构定义 | P_CODE, P9 DCM | -| P4 | D-400 | 开发计划与里程碑 (DPM) | `.md` | 任务分解、人天、里程碑 | 项目管理 | -| P5 | D-500 | 编码规范文件 (CSG) | `.md` | 命名/格式/错误处理规范 | P_CODE, Code Review | -| P5 | D-501 | 格式化配置文件 | `.clang-format` 等 | 自动化格式规则 | CI/CD | -| P6 | D-600 | 构建配置清单 (BCM) | `CMakeLists.txt` + `vcpkg.json` | 构建规则与依赖声明 | CI/CD | -| P7 | D-700 | 测试策略文件 (TSP) | `.md` | 测试金字塔、工具、覆盖率目标 | P_CODE | -| P7 | D-710 | 测试用例规格书 (TCS) | `.md` 或 `.json` | 每个模块的测试用例定义 | 测试代码 | -| P8 | D-800 | 开发工作流规范 | `.md` | Git 策略、PR 流程、Review 标准 | 团队协作 | -| P9 | D-900 | 部署配置清单 (DCM) | `.yaml` (Docker Compose / K8s) | 部署拓扑、环境变量 | CI/CD, 运维 | -| P10 | D-1000 | 反馈追踪规范 (FTS) | `.md` | 反馈渠道、分类、SLA | 产品/运营 | - ---- - -### "文件即契约"原则实施细则 - -#### 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: "{命名空间}::CommandResult" - 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. 数据模型契约 - -```json -// 示例: 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": "ChildEntity[]", "default": []}, - "sub_entities": {"type": "SubEntity[]", "default": []}, - "metadata": {"type": "Metadata", "ref": true} - }, - "invariants": [ - "uid must be unique within Document", - "name must not be empty" - ] - } - } -} -``` - -**契约执行规则**： -- 数据库/文件序列化代码必须从 DM 文件生成（代码生成器读取 DM → 生成 C++ struct + 序列化/反序列化代码） -- 禁止手动编写序列化/反序列化逻辑 -- 模型变更流程：修改 DM → 运行代码生成 → 更新测试 - -#### 3. 测试用例契约 - -```markdown -# 示例: D-710 测试用例规格书 (TCS) -# 文件: docs/specs/tests/{项目前缀}-core-{核心模块}-tests.md - -## TCS-{MOD}-001: Entity Creation - Happy Path -- **前置条件**: Active session exists -- **输入**: params valid -- **期望输出**: CommandResult.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 -- **期望输出**: CommandResult.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 首发版 -``` - -#### 变更记录要求 - -每个规范文件末尾必须包含变更记录表： - -```markdown -## 变更记录 - -| 版本 | 日期 | 作者 | 变更说明 | 影响范围 | -|------|------|------|----------|----------| -| v1.0-r0 | 2026-01-15 | @zhangsan | 初始版本 | - | -| v1.0-r1 | 2026-02-01 | @lisi | 新增 {业务单元}定义 | {业务模块}, {输出模块} | -| v1.0-r2 | 2026-02-15 | @wangwu | 修正 {业务单元}.{参数名} 类型变更 | {业务模块}, IO | -``` - -#### 版本兼容矩阵 - -| 文档版本 | 最低 Shell 版本 | 最低 SDK 版本 | 破坏性变更 | -|----------|----------------|---------------|-----------| -| v1.0-r0 | 0.1.0 | 1.0.0 | - | -| v1.0-r2 | 0.1.1 | 1.0.0 | 否 | -| v2.0-r0 | 0.2.0 | 2.0.0 | 是 ({参数名} 类型变更) | - ---- - -### AI 执行时的文件驱动工作流指令模板 - -以下是 AI 在执行软件设计开发任务时应当遵循的标准工作流。用户只需描述需求，AI 应按此流程自动生成并维护规范文件。 - -#### 指令模板: 启动新项目 - -```markdown -## 任务: 启动新项目 — 按 DDD 流程生成初始文件 - -### 步骤 1: 信息采集 -- 向用户确认：项目定位、目标用户、核心差异化、技术偏好 -- 输出：项目信息卡片（确认后进入步骤 2） - -### 步骤 2: 生成 P0 文件 -- 生成 D-001 项目章程（{路径}/P0_001_REQ_项目章程.md） -- 生成 D-002 技术预研报告（{路径}/P0_002_REQ_技术预研报告.md） -- 用户评审确认后进入步骤 3 - -### 步骤 3: 生成 P1 文件 -- 读取 P0 文件作为输入 -- 生成 D-100 功能需求规格书 FRD（{路径}/P1_001_REQ_功能需求规格书.md） -- 生成 D-101 非功能性需求清单 NFR（{路径}/P1_002_REQ_非功能性需求清单.md） -- 生成 P1 模块优先级矩阵 -- 用户评审确认后进入步骤 4 - -### 步骤 4: 生成 P2 文件（依赖 P1） -- 读取 P1 FRD + NFR 作为输入 -- 生成 D-200 系统架构设计书 SAD（{路径}/P2_001_ARCH_系统架构设计书.md） -- 对每个重大技术决策生成 ADR（{路径}/P2_002_ADR_{决策名}.md） -- 生成 D-210 模块接口定义文件 MIDL（{路径}/P2_010_API_{模块名}.yaml） -- 用户评审确认后进入步骤 5 - -### 步骤 5→N: 按依赖链依次生成 -- 始终以已生成的文件作为输入，不得偏离 -- 文件依赖关系见本文"文件依赖链"图 -- 每阶段产出完成后，标注版本号并记录变更 - -### 每次变更时的执行规则 -- 如果用户要求修改某功能 → 先找到对应 FRD 条目 → 评估影响范围 → 更新 FRD → 级联更新下游文件 -- 如果用户要求改变架构 → 更新 SAD + ADR → 检查所有 MIDL → 更新受影响的接口定义 → 更新代码 -``` - -#### 指令模板: 修改已有功能 - -```markdown -## 任务: 修改功能 — DDD 变更流程 - -### 步骤 1: 定位源文件 -- 搜索 docs/specs/ 目录，找到相关 FRD 条目 -- 向用户展示当前定义，确认修改范围 - -### 步骤 2: 影响分析 -- 列出所有引用该定义的下游文件（MIDL/ADM/DM/TCS/代码） -- 列出所有受影响的模块 -- 评估是否属于"破坏性变更" - -### 步骤 3: 执行变更 -- 先更新源文件（FRD/SAD/MIDL） -- 再级联更新下游文件 -- 标注变更记录 - -### 步骤 4: 同步代码 -- 根据更新后的 MIDL/DM 修改代码 -- 根据更新后的 TCS 修改测试 -``` - -#### 指令模板: 新功能开发 - -```markdown -## 任务: 新增功能 — DDD 新功能流程 - -### 步骤 1: 需求定义 -- 在 FRD 中新增功能条目 -- 更新模块优先级（如有需要） - -### 步骤 2: 架构评审 -- 评估是否需要更新 SAD（新功能是否影响架构） -- 在 MIDL 中新增接口定义 - -### 步骤 3: 数据模型 -- 在 DM 中新增实体/字段（如有需要） - -### 步骤 4: 测试用例 -- 在 TCS 中新增测试用例（先于编码） - -### 步骤 5: 编码实现 -- 严格按照 MIDL + DM + CSG 实现 -- 严格按 TCS 编写测试 - -### 步骤 6: 文档闭环 -- 更新 CHANGELOG -- 更新项目记忆文档 -``` - ---- - -### 文件存放目录结构规范 - -``` -{项目根目录}/ -├── docs/ -│ └── specs/ # 所有规范文件（单一事实来源） -│ ├── P0_initiation/ # P0 项目启动 -│ │ ├── P0_001_REQ_项目章程.md -│ │ └── P0_002_REQ_技术预研报告.md -│ ├── P1_requirements/ # P1 需求分析 -│ │ ├── P1_001_REQ_功能需求规格书.md -│ │ └── P1_002_REQ_非功能性需求清单.md -│ ├── P2_architecture/ # P2 架构设计 -│ │ ├── P2_001_ARCH_系统架构设计书.md -│ │ ├── P2_002_ADR_核心引擎选型.md -│ │ ├── P2_003_ADR_渲染引擎选型.md -│ │ └── P2_010_API_{核心模块}接口定义.yaml -│ ├── P3_datamodel/ # P3 数据模型 -│ │ └── P3_001_DMOD_核心数据模型.json -│ ├── P4_planning/ # P4 开发计划 -│ ├── P5_standards/ # P5 编码规范 -│ ├── P6_build/ # P6 构建系统 -│ ├── P7_testing/ # P7 测试 -│ │ └── P7_001_TEST_{核心模块}测试用例.md -│ ├── P8_workflow/ # P8 开发流程 -│ ├── P9_deployment/ # P9 部署运维 -│ ├── P10_feedback/ # P10 用户反馈 -│ ├── P11_risk/ # P11 风险债务 -│ └── P12_memory/ # P12 项目记忆 -└── src/ # 源代码（由 specs/ 驱动） -``` - ---- - -### DDD 检查清单 - -- [ ] 每个阶段产出文件已按命名规范创建并存入对应目录 -- [ ] 每份文件的"下游消费者"字段已标注（谁依赖这份文件） -- [ ] 文件间引用关系清晰可追溯（A 文件第 X 节 → B 文件第 Y 节） -- [ ] 接口定义文件 (MIDL) 与实际代码可通过工具自动比对 -- [ ] 数据模型定义文件 (DM) 驱动代码生成，无手工序列化代码 -- [ ] 测试用例文件 (TCS) 中的每条用例对应至少一个测试函数 -- [ ] 每份文件末尾有变更记录表且保持更新 -- [ ] 破坏性变更已标注并通知所有下游消费者 -- [ ] 文件版本号与代码版本号对齐（文档 v2.0 → 代码 v2.0） -- [ ] CI 流水线包含"文档-代码一致性检查"步骤 - ---- - -## P0: 项目启动与需求收集 - -### 目标 - -明确项目愿景、核心价值主张、目标用户画像，初步收敛功能范围，建立项目基础设施骨架。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 市场调研报告 | 市场/产品团队 | 竞品分析、市场缺口、目标用户痛点 | -| 技术可行性预研 | 技术团队 | 核心技术难点初步 PoC 验证 | -| 初始愿景陈述 | 创始人/产品负责人 | 一句话产品定位、核心差异化策略 | -| 竞品对标分析 | 产品团队 | Top 3-5 竞品功能矩阵对比 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 项目章程 | 文档 | 愿景、目标、范围边界、不做什么 | -| 微内核设计文档 | 技术文档 | Shell 最小内核定义：插件管理、事件总线、命令服务、配置服务、日志服务 | -| 插件 SDK 规范 v0 | 技术文档 | IPlugin 生命周期接口、扩展点注册机制初版 | -| 差异化策略分析 | 文档 | 与竞品的核心差异矩阵 | -| Phase 0 执行计划与里程碑 | 计划文档 | 3 个月路线图，含任务分解、验收标准 | - -### 关键步骤 - -1. **竞品功能矩阵对比**: 列举 Top N 竞品，从功能、价格、架构、AI 能力、跨平台、可扩展性等维度逐一对比 -2. **定义核心差异化**: 确定项目在哪些维度上建立壁垒（如开源免费 + 本地 AI + 全插件化 + 跨平台） -3. **确定架构顶层设计**: 选定微内核 + 插件化架构，定义 Shell 最少必须提供的基础服务集 -4. **最小可行内核 (MVP Kernel)**: 定义 Phase 0 用户不可见但必须跑通的基础能力——插件发现/加载/卸载、事件总线、命令注册、许可证管理 -5. **建立项目仓库骨架**: 初始化单体仓库 (Monorepo) 结构、构建系统骨架 (CMake + vcpkg)、CI/CD 三平台构建流水线 - -### 检查清单 - -- [ ] 项目愿景能用一句话说清楚 -- [ ] 竞品分析覆盖至少 3 个直接竞品 -- [ ] 差异化策略有明确的壁垒维度（不依赖单点功能） -- [ ] Shell 最少服务集已定义（不超过 12 个核心服务） -- [ ] IPlugin 接口生命周期清晰（uid/name/version/initialize/shutdown） -- [ ] 构建系统能三平台编译通过（Windows / Linux / macOS） -- [ ] 许可证管理方案已纳入 Phase 0 设计（RSA 验证 / 硬件指纹 / FeatureFlag 门控） -- [ ] 单体仓库目录结构已确定 - ---- - - ---- - -## P0.5: 可行性分析 - -### 目标 - -在项目正式启动前，从技术、市场、商业、法律和时间五个维度系统性评估项目可行性，输出 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。 - -```markdown -## 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 | K8s/CDN/监控 | 随用户量增长 | -| 第三方服务 | 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%) | - ---- - -### 四、法律与合规可行性 - -| 检查项 | 状态 | 风险评估 | -|--------|------|---------| -| 开源许可证选择 | ⚠️ 待定 | AGPL v3 vs Apache 2.0，需法务评估 | -| 第三方依赖许可证审计 | ⚠️ 待执行 | GPL 传染性风险隔离方案确认 | -| 商标注册 | ❌ 未开始 | 项目名/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 检索完成或确认为低风险 -- [ ] 第三方依赖许可证审计完成（无阻断性 GPL 传染风险） -- [ ] Go/No-Go 决策已作出并记录，所有利益相关方已确认 -- [ ] 如果是 Conditional Go，前提条件清单、验证方法、到期时间已明确 -## P1: 需求分析与功能规格 - -### 目标 - -将用户需求转化为完整的、结构化的功能需求文档，明确模块划分、功能边界、优先级排序，形成可被开发团队直接理解的规格说明。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 项目章程 | P0 产出 | 愿景、范围边界 | -| 竞品功能矩阵 | P0 产出 | 对标功能清单 | -| 用户调研报告 | 产品团队 | 用户工作流、痛点、期望 | -| 技术预研结论 | 技术团队 | 技术可行性边界 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 功能需求文档 (FRD) | Markdown 文档 | 全模块功能规格说明，每个模块含：功能描述、输入/输出、交互流程、约束条件 | -| 模块清单与优先级 | 表格 | 按 P0/P1/P2/P3 分级的完整模块列表（60+ 模块级别） | -| 非功能性需求 | 文档章节 | 性能指标、兼容性矩阵、安全要求、可访问性标准 | -| 插件化拆分方案 | 文档 | 每个模块是否独立插件、依赖关系、编译单元划分 | - -### 功能需求文档结构模板 - -```markdown -# {项目名} 功能需求文档 - -## 1. Shell 微内核（必做） -### 1.1 插件管理器 -- 功能描述：发现 plugins/ 目录下的合法插件、解析 manifest.json、依赖排序、加载/卸载 DLL/SO/DYLIB -- 输入：插件搜索路径列表 -- 输出：已加载插件列表、加载失败原因 -- 交互流程：启动→扫描→解析 manifest→依赖拓扑排序→逐插件 load→调用 initialize() -- 异常处理：manifest 无效 → 跳过并日志；缺少依赖 → 跳过；初始化失败 → 标记 LoadFailed - -### 1.2 事件总线 -- 功能描述：线程安全的发布/订阅事件系统，插件间解耦通信 -- 事件类型：文档打开/关闭、选择变更、实体重建、业务对象模式进入/退出等 -- 订阅方式：template subscribe(handler) 返回 SubscriptionId -- 线程安全：publish 内部加锁，回调在发布线程执行 - -### 1.3 命令服务 -- 功能描述：统一命令注册、查找、执行入口，支持命令灰显/可用性检查 -- 命令命名规范：cmd.{模块}.{操作}（如 cmd.{模块}.{操作}） -- Undo/Redo：每个命令返回 UndoData，命令服务管理 Undo 栈 - -## 2. 核心业务逻辑 (P0) -## 3. 高级业务逻辑 (P1) -## 4. 数据分析 (P1-P2) -## 5. 业务扩展 (P2) -## ... -``` - -### 非功能性需求模板 - -| 类别 | 指标 | 目标值 | 测量方式 | -|------|------|--------|----------| -| 渲染性能 | 100 万面场景帧率 | >30fps | Benchmark CI | -| 业务对象求解 | 100+ 业务计算 | <100ms | Benchmark CI | -| 文件导入 | 500MB 大文件导入 | <30s | Benchmark CI | -| 冷启动 | 5 插件加载 | <5s | 启动计时 | -| 兼容性 | 操作系统 | Win10/11, macOS 14+, Ubuntu 22.04 | CI 多平台矩阵 | -| 安全性 | 文件解析 | 模糊测试通过、无 CVE | libFuzzer + CodeQL | -| 国际化 | 语言支持 | 至少中英双语 | i18n 框架 | - -### 检查清单 - -- [ ] 每个功能模块均有：功能描述、输入/输出、交互流程、异常处理定义 -- [ ] 模块按 P0/P1/P2/P3 分了优先级 -- [ ] 模块间依赖关系已标注（A 依赖 B/C） -- [ ] 非功能需求有具体可量化的指标 -- [ ] 插件的 manifest 字段定义完整（uid/name/version/dependencies/entry/minShellVersion） -- [ ] 与竞品的功能覆盖率对比已完成 - - - - ---- - -## P1.5: 需求变更管理 - -### 目标 - -建立正式的变更控制流程，确保需求变更经过充分评估和审批，避免范围蔓延和非受控变更导致的项目风险。 - -### 为什么需要独立管理 - -需求变更不是代码变更（后者在 P8 管理），也不仅是文档修订（后者在 PM 章管理）。需求变更直接影响商业价值、交付时间和资源分配，需要独立的决策机制。 - -### 变更控制委员会 (CCB) - -**组成**：产品负责人 + 技术负责人 + 至少 1 名核心开发者（根据变更影响的领域轮换） - -**决策规则**： -| 变更等级 | 审批人 | 最大响应时间 | -|---------|--------|------------| -| P0 - 紧急（阻塞发布/安全） | 技术负责人直批，事后通知 CCB | 4h | -| P1 - 重大（影响里程碑或架构） | CCB 全体同意 | 3 个工作日 | -| P2 - 中等（影响单个模块工期） | 产品负责人 + 技术负责人 | 5 个工作日 | -| P3 - 轻微（不改变工期和架构） | 产品负责人直批 | 不设限制 | - -### 变更影响评估模板 - -```markdown -# CR-{编号}: {变更简述} - -## 变更来源 -- 提出人: @username -- 来源: Bug / Feature 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 开始后 | Feature Freeze | 仅 P0/P1 Bug 修复 | -| 发布前 1 周 | Code Freeze | 仅 P0 Bug 修复 | -| 正式发布后 | 全冻结 | 仅 Hotfix | - -### 变更追踪文件 - -```markdown -# 变更记录文件: 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 紧急变更通道已建立（事后补流程，不阻塞响应） - ---- - -## P2: 系统架构与技术选型 - -### 目标 - -确定系统整体架构、技术栈选型、关键技术决策，输出可供开发团队并行工作的架构蓝图。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 功能需求文档 (FRD) | P1 产出 | 全模块功能清单与优先级 | -| 竞品技术架构分析 | 技术团队 | 竞品的技术栈与架构模式 | -| 技术预研 PoC | 技术团队 | 核心引擎可行性验证 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 系统架构文档 | Markdown + 架构图 | 总体分层架构、组件关系、数据流 | -| 技术选型决策表 | 表格 | 各技术领域选择、理由、备选方案 | -| 插件完整清单 v2 | 清单 | 扩展后的完整插件清单（含新增插件） | -| 关键技术决策记录 (ADR) | 文档 | 重大技术决策的背景、选项、理由、后果 | -| 项目目录结构定义 | 目录树 | Shell / SDK / Plugins / Tests / Docs 完整布局 | - -### 架构分层模板 - -``` -┌──────────────────────────────────────────────────────────────┐ -│ {项目名} Shell (微内核宿主) │ -│ ┌────────────────────────────────────────────────────────┐ │ -│ │ PluginManager │ EventBus │ Command/Undo │ ExtensionRegistry│ -│ └────────────────────────────────────────────────────────┘ │ -├──────────────────────────────────────────────────────────────┤ -│ N 个独立功能插件 │ -│ ┌─────────┐┌─────────┐┌─────────┐┌─────────┐ │ -│ │ P0 核心 ││ P1 高级 ││ P2 扩展 ││ P3 生态 │ │ -│ └─────────┘└─────────┘└─────────┘└─────────┘ │ -├──────────────────────────────────────────────────────────────┤ -│ 内核引擎层 │ -│ ┌──────────┐┌──────────┐┌──────────┐┌──────────┐ │ -│ │ 核心引擎1 ││ 核心引擎2 ││ 渲染后端 ││ 数据交换 │ │ -│ └──────────┘└──────────┘└──────────┘└──────────┘ │ -└──────────────────────────────────────────────────────────────┘ -``` - -### 技术选型决策表模板 - -| 决策点 | 选择 | 理由 | 备选 | 风险 | -|--------|------|------|------|------| -| 编程语言 | C++20 + Python 3.11 | 性能关键路径 C++，脚本/工具链 Python | Rust | C++ 人才稀缺 | -| 构建系统 | CMake 3.28 + Ninja + vcpkg | 跨平台、声明式依赖、可重现构建 | Bazel | 学习曲线 | -| UI 框架 | Qt 6.8 | 跨平台原生 UI，工业级成熟度 | Electron | 包体积大 | -| 渲染引擎 | bgfx | 跨平台（D3D11/Metal/Vulkan），轻量 | OpenGL 直接 | 抽象层额外开销 | -| 依赖管理 | vcpkg + manifest 模式 | 声明式、可锁定版本、CI 友好 | Conan | 包生态 | -| AI 模型 | Llama 3 / Qwen 本地+云端混合 | 开源自部署、离线可用 | OpenAI API only | 本地推理硬件要求 | -| 许可证策略 | AGPL v3（开源）+ 企业订阅 | 防止云厂商白嫖，企业付费 | MIT | 企业接受度 | - -### 技术选型决策记录 (ADR) 模板 - -```markdown -# ADR-001: 选择 {核心引擎库} 作为核心引擎 - -## 状态 -已通过 - -## 背景 -需要 核心数据结构 核心引擎支持结构化业务逻辑、核心运算、标准格式导入导出 - -## 选项 -1. {核心引擎库名} ({核心引擎库}) - LGPL 2.1，开源，完整 核心数据结构 内核 -2. {商业引擎库} - 商业授权，{商业产品A}/{商业产品B} 内核 -3. 自研 - 完全自主可控 - -## 决策 -选择 {核心引擎库} - -## 理由 -- 开源许可无前期成本 -- 完整 核心数据结构 + {标准格式A}/{标准格式B} 支持 -- 活跃社区与商业支持 ({核心引擎厂商}) -- 选择 2 成本不可接受，选择 3 时间不可接受 - -## 后果 -- 需要处理 {核心引擎库} 边界条件下的核心运算失败 -- 需要实现自有实体命名机制 -- 需要建立回归测试数据集 -``` - -### 检查清单 - -- [ ] 架构分层清晰（宿主壳 → 插件层 → 内核引擎层） -- [ ] 每个重大技术决策都有 ADR 记录（理由 + 后果） -- [ ] 插件间通信机制已定义（事件总线、命令服务、文档服务） -- [ ] 扩展点注册机制覆盖：Ribbon/菜单/面板/命令/文件格式/属性页/快捷键 -- [ ] GPL 依赖已确认隔离策略（独立进程 CLI 调用） -- [ ] 跨平台矩阵已定义（OS / 编译器 / 渲染后端） -- [ ] 目录结构遵循单体仓库最佳实践（cmake/, sdk/, src/, plugins/, tests/, docs/, tools/） -- [ ] 线程安全模型已定义（主线程 UI / Worker Pool 业务数据 / 事件总线线程安全） - - - - ---- - -## P2.5: 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 标注模板 - -```yaml -# 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" -``` - -```cpp -// C++ 代码中的废弃标注 -[[deprecated("Since v1.5. Use Module::NewOp() instead. Will be removed in v2.0.")]] -CommandResult OldOp(const std::string& param_a); -``` - -### 向后兼容承诺矩阵 - -| 承诺项 | 承诺范围 | 例外 | -|--------|---------|------| -| 源码兼容 (Source) | MINOR 版本内兼容 | 无 | -| 二进制兼容 (ABI) | PATCH 版本内兼容 | 安全修复 | -| 插件兼容 | MAJOR 版本内兼容 | 安全/合规 | -| 文件格式兼容 | 永久兼容（新版本可读旧文件） | 无 | - -### 检查清单 - -- [ ] API 版本号独立于产品版本号管理 -- [ ] Breaking Change 判定标准已公示并写入编码规范 -- [ ] 所有公共 API 在 MIDL 中有对应声明 -- [ ] CI 中运行 API 兼容性检查（对比当前版本 vs 上一版本 MIDL） -- [ ] 废弃接口有明确的替代方案和迁移指南 -- [ ] CHANGELOG 区分 API Breaking Changes 和普通功能变更 - ---- - -## P3: 数据模型设计 - -### 目标 - -定义系统的核心数据结构、层级关系、持久化格式、跨模块数据流，确保所有插件对数据有一致理解。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 功能需求文档 | P1 产出 | 功能所需的数据实体 | -| 系统架构文档 | P2 产出 | 数据流向与组件关系 | -| 领域模型分析 | 领域专家 | 行业标准数据规范 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 核心数据模型文档 | Markdown + UML 图 | 实体定义、层级关系、字段说明 | -| 原生文件格式规范 | 文档 | 自定义文件格式的二进制/JSON 结构 | -| 数据库 Schema（如适用） | SQL / ER 图 | 云服务相关数据表设计（后续阶段） | -| 数据流关键场景 | 文档 | 典型业务流程的数据流转路径 | - -### 核心数据模型层级模板 - -``` -Application - └── Document[] - ├── uid: UUID - ├── name: string - ├── filePath: string - ├── units: UnitSystem (mm/inch/m) - ├── layers: Layer[] - ├── metadatas: Metadata[] - ├── parts: Part[] - ├── aggregates: Aggregate[] - └── {输出模块}s: {输出模块}[] - -Part -├── uid: UUID -├── name: string -├── children: ChildEntity[] -├── sub_entities: SubEntity[] -├── referenceGeometry: RefGeometry[] -├── metadata: Metadata (ref) -└── customProperties: Map - -ChildEntity（子实体） -├── uid: UUID -├── name: string -├── features: Feature[] # 操作历史列表（有序，设计意图链） -├── shape: CoreShape # 最终业务数据形状（派生，由 Feature DAG 计算） -└── tip: Feature # 当前末端特征 - -Feature（业务单元 - 设计历史节点，抽象基类） -├── uid: UUID -├── name: string -├── type: FeatureType (enum) -├── status: FeatureStatus (Valid/Invalid/Warning) -├── previousShape: Shape -├── resultingShape: Shape -└── parameters: FeatureParams - ├── 基础类型: {类型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 - └→ EventBus 发布事件 - ├→ UI插件: 更新显示 - ├→ 详情面板: 更新属性 - ├→ 导航树: 更新结构 - └→ AI 插件: 感知上下文变化 - -场景2: 文件保存/加载 (往返测试) - 内存模型 → serialize → 原生格式 (.{原生格式}) → deserialize → 内存模型 - 验证: 核心属性值前后一致 -``` - -### 命名与标识规范 - -| 元素 | 格式 | 示例 | -|------|------|------| -| 实体 UID | UUID v4 | `550e8400-e29b-41d4-a716-446655440000` | -| 命令名 | `cmd.{模块}.{操作}` | `cmd.{模块}.{操作}` | -| 事件名 | PascalCase + Event 后缀 | `SelectionChangedEvent` | -| 约束名 | 字母+数字 | `D1`, `R5`, `H10` | - -### 检查清单 - -- [ ] 核心实体层级清晰（Document → Part → ChildEntity → Feature） -- [ ] 每个实体定义了 uid/name/type/status 核心字段 -- [ ] 实体采用 DAG 而非简单列表（允许多父特征聚合） -- [ ] 原生文件格式支持完整语义保存（操作树 + 规则 + 元数据 + 自定义属性） -- [ ] 文件 I/O 往返测试已列入计划（保存→重载→业务数据属性对比） -- [ ] 实体间引用采用 UID 而非裸指针（支持持久化） -- [ ] 数据模型预留了扩展字段（customProperties: Map） - - - - ---- - -## P3.5: 数据迁移与回滚策略 - -### 目标 - -建立数据模型变更时的迁移（Migration）机制，确保数据库/文件格式/持久化数据的结构变更可追溯、可逆、可自动执行。 - -### 核心原则 - -1. **一切 Migration 必须可逆**：每个 Migration 必须有对应的 Down 脚本（回滚） -2. **Migration 必须幂等**：多次执行同一 Migration 不会产生错误或重复效果 -3. **Migration 先于代码部署**：数据库/存储结构变更必须在应用代码变更之前完成 -4. **禁止手动修改生产数据库结构**：所有 DDL 变更必须通过 Migration 系统执行 - -### Migration 脚本规范 - -```sql --- 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 | PostgreSQL | -| 逻辑复制切换 | 双写 + 数据回填 | 任何数据库 | - -**大表迁移检查清单**： -- [ ] 迁移脚本已在**等比例数据量**的 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 环境预演通过 - ---- - -## P4: 开发计划与里程碑规划 - -### 目标 - -将项目分解为多个 Phase，每个 Phase 有明确的里程碑 (Milestone)、团队规模、任务分解和验收标准，形成可执行的路线图。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 功能需求文档 (FRD) | P1 产出 | 模块清单与优先级 | -| 系统架构文档 | P2 产出 | 技术依赖与构建顺序 | -| 团队资源评估 | 管理层 | 可用人力和时间约束 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 长期路线图 (4-5 年) | 时间线图 | Phase 0-4 宏观里程碑 | -| 各 Phase 执行计划 | Markdown 文档 | 任务分解、人天估算、依赖关系、验收标准 | -| 里程碑检查清单 | 表格 | 每个 Milestone 的准出条件 | -| 团队规划 | 表格 | 各阶段所需角色与人数 | - -### 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 | - -### Phase 执行计划模板 - -每个 Phase 的详细执行计划应包含： - -```markdown -# 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% 行覆盖率 | gcov/lcov 报告 | -| 性能指标 | 所有基准测试不低于目标值 | Benchmark CI | -| 跨平台构建 | 三平台 (Win/Mac/Linux) 编译零警告零错误 | CI 矩阵 | -| Bug 清零 | 无 P0/P1 级未解决 Issue | Issue Tracker | -| 文档就绪 | API 文档 + 用户手册更新 | 文档审查 | - -### 检查清单 - -- [ ] 路线图覆盖至少 3-4 年，每个 Phase 有明确的里程碑 -- [ ] 各 Phase 的任务分解粒度合理（每任务 1-15 人天） -- [ ] 并行小组划分避免了资源冲突 -- [ ] 依赖图标注了 Stage 间的串行/并行关系 -- [ ] 每个里程碑有可量化、可验证的准出条件 -- [ ] 团队规划与实际资源匹配（未过度承诺） - ---- - -## P5: 编码规范与开发标准 - -### 目标 - -建立统一的编码规范、代码风格、错误处理范式、内存管理策略，确保多人协作时代码质量一致、可维护。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 技术选型 | P2 产出 | 编程语言、编译器版本 | -| 团队经验 | 团队 | 现有代码风格与偏好 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 编码规范文档 | Markdown | 命名/格式/注释/头文件/类/错误处理/内存管理完整规范 | -| .clang-format 配置 | YAML 文件 | 自动化格式化规则 | -| clang-tidy 检查配置 | 命令行参数 | 静态分析规则集 | -| .editorconfig | 配置文件 | 编辑器通用配置 | -| 快速检查清单 | 附录 | 提交前自查列表 | - -### 编码规范核心内容 - -#### 命名规范 - -| 元素 | 风格 | 示例 | -|------|------|------| -| 命名空间 | `snake_case` | `project::core`, `project::module` | -| 类/结构体 | `PascalCase` | `PluginManager`, `DocumentService` | -| 接口 (I 前缀) | `IPascalCase` | `IPlugin`, `IDocumentService` | -| 枚举类型 | `PascalCase` | `FeatureType`, `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` | `VD_ASSERT`, `VD_VERSION_MAJOR` | -| 文件名 | `snake_case` | `plugin_manager.cpp` | - -#### 注释规范 - -```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& 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` / `PROJECT_ASSERT` | 立即崩溃，CI 中暴露 | -| 可恢复错误 | `std::expected` (C++23) 或自定义 `Result` | 调用方必须处理 | -| 不可恢复错误 | 抛异常 | 核心引擎异常等 | -| 构造函数失败 | 工厂方法 + 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` | -| 魔法数字 | 命名常量或 constexpr | -| `goto` | 结构化控制流 | - -#### Python 编码规范（如项目含 Python） - -- 遵循 PEP 8，用 Black 自动格式化（line-length=100） -- isort 排序 import，mypy 类型检查（严格模式） -- 命名: 类 PascalCase，函数/变量 snake_case，常量 UPPER_SNAKE -- 私有成员前缀 `_`，类型注解强制 - -### 工具链配置 - -```bash -# C++ 格式化（CI 阻断） -clang-format --style=file --dry-run -Werror - -# 静态分析（CI 阻断） -clang-tidy --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 -``` - -### 检查清单 - -- [ ] 命名规范覆盖所有语言元素（命名空间/类/函数/变量/常量/枚举/宏/文件） -- [ ] 代码格式有自动化工具保障（clang-format / black） -- [ ] 静态分析已集成到 CI 门禁（clang-tidy / mypy） -- [ ] 注释规范区分了强制/推荐/建议三级 -- [ ] 错误处理策略覆盖了断言/Result/异常三种场景 -- [ ] 禁止事项清单明确（裸 new/delete、C 风格转换、魔法数字、goto 等） -- [ ] 编译器警告视为错误 (`-Werror`) -- [ ] 有快速检查清单供开发者在提交前自查 - - - - ---- - -## P5.5: 国际化 (i18n) 与本地化 (L10n) 开发规范 - -### 目标 - -建立从代码编写到翻译交付的完整国际化工作流，确保产品可以低摩擦地支持多语言。 - -### 核心原则 - -1. **代码中禁止硬编码用户可见字符串**：所有面向用户的文本必须通过 i18n 框架获取 -2. **开发和UI语言分离**：开发使用英文 Key，翻译文件提供各语言文本 -3. **翻译先于发布**：Translation Freeze 早于 Code Freeze（给翻译团队留出时间） -4. **上下文即注释**：每个翻译 Key 必须附带上下文说明（在哪里显示、什么用途） - -### 字符串外置规范 - -```cpp -// ❌ 禁止: 硬编码字符串 -label->setText("打开文件"); -errorMessage("文件格式不支持"); - -// ✅ 正确: 使用 i18n Key -label->setText(tr("menu.file.open")); // Qt 方式 -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` | - -### 翻译文件格式 - -```json -// 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 - -构建阶段: - CMake 中将 .json 编译为 .qm 或其他二进制格式 - 打包时包含所有语言文件 -``` - -### 翻译覆盖率检查 - -```bash -# 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 - ---- - -## P6: 构建系统与环境搭建 - -### 目标 - -建立可重现、跨平台、声明式的构建系统，降低新开发者入职门槛，确保 CI/CD 流水线一致性。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 技术选型 | P2 产出 | 编译语言、目标平台、依赖库清单 | -| 第三方依赖清单 | P2 产出 | 所有直接和间接依赖的版本与 License | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 构建系统架构文档 | Markdown | CMake 结构、Target 依赖图、编译配置 | -| CMake Presets | JSON | 开发 / CI / Release 多配置预设 | -| vcpkg manifest | JSON | 声明式依赖清单，含版本约束 | -| 第三方依赖清单 | 表格 | 名称/版本/用途/License/风险等级/隔离策略 | -| 开发者入职指南 | Markdown | 环境搭建、IDE 配置、首次构建、常见问题 | - -### 构建系统设计原则 - -1. **单体仓库 (Monorepo)**：Shell + 所有官方插件在同一仓库 -2. **声明式依赖**：通过 vcpkg.json 明确声明所有依赖及版本 -3. **可重现构建**：lockfile + 固定依赖版本 -4. **增量编译**：模块化 CMake target，最小化重编译 -5. **统一配置**：所有插件共享编译选项、警告级别、静态分析规则 - -### CMake 项目结构 - -``` -{项目名}/ -├── CMakeLists.txt # 根配置：全局选项、子目录索引 -├── cmake/ -│ ├── CompilerWarnings.cmake # 警告级别配置 -│ ├── StaticAnalyzers.cmake # clang-tidy/cppcheck 集成 -│ ├── InstallRules.cmake # 安装规则 -│ └── Packaging.cmake # CPack 打包配置 -├── vcpkg.json # 根 manifest（公共依赖） -├── src/ -│ └── shell/ # Shell 入口 + 核心服务库 -├── plugins/ # 插件（每个独立 CMake target） -│ ├── {项目前缀}-{示例插件}/ -│ │ ├── CMakeLists.txt -│ │ ├── vcpkg.json # 插件专属依赖(可选) -│ │ ├── src/ -│ │ └── tests/ -├── sdk/ # 插件 SDK (header-only + 薄库) -├── tests/ # 集成测试 -├── tools/ # 构建/发布脚本 -└── docs/ # 文档 -``` - -### Target 依赖图 - -``` -{项目前缀}_shell (exe) - ├── {项目前缀}_core (static lib) ← 核心服务(PluginManager/EventBus/CommandService...) - │ ├── Qt6::Core, Qt6::Widgets - │ └── spdlog::spdlog - └── {项目前缀}_sdk (header-only) - -{项目前缀}_plugin_xxx (shared plugin) - ├── {项目前缀}_sdk ← 插件 SDK 接口 - ├── 领域引擎依赖 - └── 其他库... -``` - -### 第三方依赖清单模板 - -| 库 | 版本 | 用途 | License | 风险等级 | 隔离方式 | -|----|------|------|---------|----------|----------| -| 核心库1 | 1.0+ | 核心功能 | LGPL | 低 | 动态链接 | -| GPL库 | 2.0+ | 辅助功能 | GPL 2 | 高 | 独立进程 CLI 调用 | -| 工具库 | 1.5+ | 工具 | MIT | 低 | 动态链接 | - -### GPL 依赖隔离策略 - -``` -● LGPL 依赖 ── 允许动态链接，无需开源 -● GPL 依赖 ── 独立进程，通过 CLI/文件通信 → 不触发 GPL 传染 -``` - -### 开发者入职路线 - -``` -第 1 天: - □ 完成环境搭建，成功编译运行 - □ 阅读功能需求文档 + 系统架构文档 - -第 2 天: - □ 阅读编码规范 + 开发工作流文档 - □ 找一个 Good First Issue - □ 提交第一个 PR - -第 3-5 天: - □ 熟悉当前 Phase 代码 - □ 认领一个功能模块 -``` - -### 检查清单 - -- [ ] 构建系统支持三平台（Windows / Linux / macOS） -- [ ] CMake Presets 覆盖开发/Debug/Release/CI 多种场景 -- [ ] 所有第三方依赖在 vcpkg.json 中声明，含版本约束 -- [ ] GPL 依赖有明确的隔离策略 -- [ ] 编译器缓存已配置（ccache/sccache） -- [ ] 预编译头 (PCH) 已配置（加速编译） -- [ ] 开发者入职指南覆盖环境搭建/IDE 配置/首次构建/常见问题 -- [ ] 有脚本化的一键构建与发布流程 - - - - ---- - -## P6.5: 多环境管理规范 - -### 目标 - -建立开发、测试、预发布和生产环境的标准管理体系，确保环境间配置隔离、数据安全，并实现环境的快速创建和销毁。 - -### 环境层级定义 - -| 环境 | 缩写 | 用途 | 数据来源 | 部署方式 | 谁可访问 | -|------|------|------|---------|---------|---------| -| Local | LCL | 开发者本机开发调试 | Mock / 本地数据库 | 手动 | 仅本人 | -| Development | DEV | 联调、功能验证 | 匿名化测试数据 | 自动 (每次合并到 develop) | 开发团队 | -| Test | TST | QA 测试、集成测试 | 匿名化测试数据 | 自动 (每次 release 分支) | QA + 开发 | -| Staging | STG | 预发布验证、性能测试 | 脱敏生产数据 | 手动触发 | 核心团队 | -| Production | PRD | 线上服务 | 真实数据 | 严格审批后手动 | 运维 + On-Call | - -### 核心铁律 - -``` -❌ 禁止生产数据出现在非生产环境（未经脱敏） -❌ 禁止非生产环境访问生产服务（数据库/API/存储） -❌ 禁止跨环境配置混用 -❌ 禁止在生产环境手动执行命令（通过 CI/CD 流水线） -✅ 所有环境通过代码（IaC）定义，Git 仓库中可审计 -✅ 环境销毁后 24h 内可重建 -``` - -### 配置管理策略 - -```yaml -# 配置分层模型 -配置来源（优先级从高到低）: - 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 → 替换为无效值 -- 业务数据 → 保留（用于真实测试），但金额等敏感字段需模糊化 - -### 环境创建与销毁 - -**新环境创建模板**： -```bash -# 一键创建新环境（通过 IaC） -make env-create NAME=perf-test ENV=stg TEMPLATE=stg - -# 环境包含: -# - 计算资源（容器/VM） -# - 数据库（含初始 Schema + Migration） -# - 消息队列/缓存 -# - DNS/负载均衡配置 -# - 监控告警规则 -# - 测试账号 -``` - -**环境自动回收**： -- STG/TST 环境超过 7 天无活动 → 自动通知 -- Feature 分支环境在分支合并后 24h 自动销毁 -- 长期保留的环境需标记 `persistent: true` - -### 环境间隔离验证 - -```bash -# CI 自动检查: 验证环境隔离 -tools/check_env_isolation.sh - -# 检查项: -# 1. STG 是否能访问 PRD 数据库 → 必须拒绝 -# 2. DEV 是否使用了 PRD API Key → 必须拒绝 -# 3. 各环境日志是否混入生产数据 → 必须拒绝 -``` - -### 检查清单 - -- [ ] 五层环境体系已建立（LCL → DEV → TST → STG → PRD） -- [ ] 所有环境通过 IaC 定义，Git 仓库可审计 -- [ ] 敏感配置通过环境变量注入，不入库 -- [ ] 生产数据脱敏脚本就绪（PRD → STG） -- [ ] 环境间网络隔离已验证（DEV 不能访问 PRD） -- [ ] 环境自动回收策略已生效 -- [ ] 新成员入职 1 小时内可构建完整 DEV 环境 - ---- - -## P7: 测试策略与质量保障 - -### 目标 - -建立分层测试体系，确保代码质量和功能正确性，将测试融入开发流程和 CI/CD 流水线。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 功能需求文档 | P1 产出 | 需验证的功能点 | -| 系统架构文档 | P2 产出 | 测试隔离策略 | -| 编码规范 | P5 产出 | Mock 策略 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 测试策略文档 | Markdown | 测试金字塔、测试类型、工具链 | -| 测试用例模板 | 代码模板 | 单元测试/集成测试/性能测试模板 | -| 回归测试数据集 | 文件 | 标准测试数据/输入文件 | -| CI 测试流水线配置 | YAML | 自动化测试触发与门禁规则 | - -### 测试金字塔 - -``` - ╱───────╲ - ╱ E2E ╲ 端到端测试: 全流程手动+自动 (10%) - ╱─────────────╲ - ╱ Integration ╲ 集成测试: 多插件协作场景 (30%) - ╱───────────────────╲ - ╱ Unit Tests ╲ 单元测试: 每插件独立 (60%) - ╱─────────────────────────╲ -``` - -### 单元测试规范 - -**每个插件必须覆盖**： -- 核心业务逻辑: 80% 行覆盖率 -- 命令执行: 所有命令至少 1 个正向 + 1 个异常用例 -- 数据序列化: 往返测试（serialize → deserialize → equals） -- 边界条件: 空输入、极值、null - -**框架与工具**： - -| 语言 | 框架 | 覆盖率工具 | -|------|------|-----------| -| C++ | GoogleTest + gMock | gcov / lcov | -| Python | pytest | coverage.py | -| Qt/UI | QtTest | - | - -### Mock 策略 - -```cpp -// 插件单元测试使用 Mock 核心服务，无需启动 Shell -class PluginTest : public ::testing::Test { -protected: - void SetUp() override { - mockContext = std::make_unique(); - mockDocService = std::make_unique(); - - ON_CALL(*mockContext, documentService()) - .WillByDefault(Return(mockDocService.get())); - } -}; -``` - -### 领域专项测试（按项目领域定制） - -**领域示例**： -- **核心逻辑正确性验证**：核心数据结构 拓扑一致性（isValid/isClosed/isSolid）、核心运算体积期望 -- **算法正确性验证**：确定性验证（相同输入 → 相同输出）、回归测试集（100+ 算法场景） -- **文件 I/O 往返测试**：导出 → 重导入 → 比较业务数据属性（体积/面数/边界盒） -- **回归测试数据集**：标准业务对象 JSON、标准特征参数、标准聚合实体、标准导入文件 - -### 性能基准测试 - -| 场景 | 目标 | CI 门禁 | -|------|------|---------| -| 场景A | 10% | -| 场景B | >Y fps | 不低于目标值 | -| 场景C | 80% -- [ ] 文件 I/O 往返测试覆盖所有支持格式 -- [ ] 性能基准测试已集成 CI，不允许回退 >10% -- [ ] 跨平台测试矩阵覆盖所有目标平台 -- [ ] 安全测试（模糊测试/静态分析/漏洞扫描）已纳入流水线 -- [ ] CI 门禁分层：快速检查（PR）→ 完整检查（合并前）→ 发布前检查 - ---- - -## P8: 开发工作流与协作规范 - -### 目标 - -定义团队协作的 Git 工作流、代码审查标准、发布管理流程，确保多人协作高效有序。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 团队规模与结构 | 管理层 | 并行小组数、成员角色 | -| 发布节奏要求 | 产品团队 | 迭代周期、用户期望 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 开发工作流规范文档 | Markdown | Git 分支策略、Commit 规范、PR 流程、Code Review 标准 | -| PR 模板 | Markdown | GitHub PR 描述模板 | -| Issue 模板 | Markdown | Bug / Feature / Question 模板 | -| 发布管理流程 | 文档 | 版本号规范、发布检查清单、Changelog 规范 | -| CI/CD 门禁规则 | 配置文件 | 各阶段自动检查规则 | - -### Git 分支策略（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 规范 - -``` -(): <简短描述> - -[可选的详细描述] - -[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 流程 - -``` -创建 Feature 分支 → 开发 → 提交 Draft PR → CI 自动检查 - ↓ -通过检查 → 标记 Ready for Review → 至少 1 人 Code Review - ↓ -Review 通过 → 合并到 develop → 删除 feature 分支 -``` - -**PR 规则**： -- PR 大小限制：单 PR 不超过 500 行变更（超过则拆分） -- Draft PR 机制：开发初期创建 Draft PR 获取早期反馈 -- PR 模板：描述（做了什么/为什么/怎么测试）、关联 Issue、检查清单 - -### 代码审查标准 - -| 维度 | 审查要点 | -|------|----------| -| 正确性 | 逻辑是否正确、边界条件是否处理、错误处理是否完善 | -| 安全性 | 是否有注入风险、文件路径是否安全、内存是否正确管理 | -| 性能 | 是否有不必要的拷贝、算法复杂度是否合理 | -| 可维护性 | 命名是否清晰、是否有重复代码、是否符合 SOLID | -| 测试 | 是否覆盖正向+异常用例、测试是否合理 | -| 规范 | 是否符合编码规范、clang-format/clang-tidy 是否通过 | - -**评论标签**： -- `[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 周: - □ Feature Freeze（不再接新功能） - □ 代码冻结（只合 Bug 修复） - □ 翻译冻结 - -发布前 1 周: - □ RC 版本构建 - □ 社区 Beta 测试 - □ 更新 Changelog - □ 更新文档 + 截图 - -发布日: - □ 签名 + 上传 + 发布公告 - □ 社交媒体通知 - □ 邮件通知关键用户 -``` - -### 检查清单 - -- [ ] Git 分支策略明确（分支类型/命名规则/合并目标） -- [ ] Commit Message 规范有 type + scope 枚举 -- [ ] PR 模板覆盖"做了什么/为什么/怎么测试/关联 Issue" -- [ ] Code Review 标准覆盖 6 个维度 -- [ ] CI 门禁自动化（lint → test → build → performance） -- [ ] 发布流程有明确的 Feature Freeze / Code Freeze 时间窗口 -- [ ] Bug/Feature/Question Issue 模板已创建 - ---- - -## P9: 部署与运维 - -### 目标 - -建立应用打包、分发、云端部署、监控告警的完整方案，确保产品稳定交付和运行。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 目标平台列表 | P2 产出 | 需要支持的 OS 和分发渠道 | -| 云端架构设计 | P2 产出 | 云端服务组件与依赖 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 部署与运维方案 | Markdown | 全链路部署运维文档 | -| CI/CD 流水线配置 | YAML | 从构建到部署的完整流水线 | -| 监控告警规则 | 配置 | Prometheus/Grafana 告警规则 | -| 备份恢复方案 | 文档 | RPO/RTO 定义与恢复流程 | - -### 应用分发 - -| 平台 | 格式 | 工具 | 自动更新 | -|------|------|------|----------| -| Windows | .msi / .exe | WiX Toolset + WinSparkle | WinSparkle | -| macOS | .dmg（签名+公证） | create-dmg + codesign | Sparkle | -| Linux | .AppImage / .deb / .rpm / Flatpak | linuxdeploy + CPack | 包管理器 + AppImageUpdate | +## 项目结构 -**安装包目录结构**： ``` -{应用名}/ -├── bin/ -│ ├── {应用名}.exe -│ └── 工具CLI.exe -├── lib/ # 运行时依赖 -├── plugins/ # 插件目录（用户可自行添加） -├── sdk/ # 插件 SDK -├── resources/ # 图标/材质/模板/翻译 -│ ├── icons/ -│ ├── metadatas/ -│ ├── templates/ -│ └── translations/ +dev-docs/ +├── README.md ← 本文件（项目说明） +├── 软件设计开发需求流程.md ← 核心文档（通用流程模板，给 AI 或人使用） └── docs/ + ├── design/ ← 设计文档（按阶段编号 00-39） + └── plan/ ← 计划文档（里程碑 + 执行计划） ``` -### 云端服务部署 +## 文档说明 -**架构**：CDN/WAF → Load Balancer → API/WS/Web Pods (K8s) → PostgreSQL/Redis/S3 - -**部署模式**： - -| 模式 | 适用 | 说明 | -|------|------|------| -| 单机部署 | 小型团队 <20 人 | Docker Compose | -| 高可用部署 | 中大型企业 | K8s / Docker Swarm | -| 气隙部署 | 军工/涉密 | 离线安装包，无外网连接 | -| 混合部署 | 云端+本地 | 数据本地、AI 调用云端 | - -### 监控与可观测性 - -**三支柱**: Metrics (Prometheus) + Logs (Loki) + Traces (Tempo) - -**关键指标**： -- 应用: 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） -- [ ] 自动更新机制已实现（含增量更新 + 签名校验 + 回滚） -- [ ] 云端部署支持 K8s + Docker Compose 双模式 -- [ ] 企业 License Server 支持内网私有部署 -- [ ] 监控覆盖应用/业务/系统三层指标 -- [ ] 告警规则分 P1/P2/P3 三级，有明确升级路径 -- [ ] 备份策略定义了 RPO/RTO，有定期恢复演练计划 - - - - ---- - -## P9.5: 线上事故响应流程 - -### 目标 - -建立明确的线上事故分级、响应、升级和复盘机制，确保故障能得到快速有效的处理，并通过事后复盘持续改进系统可靠性。 - -### 事故等级定义 - -| 等级 | 定义 | 判定标准 | 响应时间 | 解决时间 | -|------|------|---------|---------|---------| -| 🔴 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 模板（事故复盘） - -```markdown -# 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 | 确认恢复，关闭事故 | +| `软件设计开发需求流程.md` | 通用流程模板，包含 14 个主章节 + 8 个附录 + PA 章（AI Agent 操作规范） | +| `README.md` | 本文件，项目介绍与使用说明 | +| `docs/design/` | 设计文档目录，按阶段编号（00-39），每个文件对应流程中的一个阶段 | +| `docs/plan/` | 计划文档目录，包含里程碑和执行计划 | -## 根因 -{用 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 追踪 -- [ ] 每月至少一次桌面推演 -- [ ] 回滚操作一键化（单命令/单按钮） -- [ ] 告警通知通道有冗余（主通道 + 备用通道） - - - ---- - -## P9.6: 功能开关 (Feature Flag) 与灰度发布 - -### 目标 - -通过功能开关实现发布与部署的解耦，支持灰度发布、A/B 测试和紧急功能关闭，降低发布风险。 - -### 功能开关分类 - -| 类型 | 生命周期 | 示例 | 动态更新 | -|------|---------|------|---------| -| Release Flag | 短期（1-2 个版本） | 隐藏未完成功能，直到开发完毕 | ✅ | -| Kill Switch | 长期（保留） | 紧急关闭高负载/有问题的功能 | ✅ | -| Experiment Flag | 中期（A/B 测试周期） | 对比新旧 UI/算法效果 | ✅ | -| Ops Flag | 长期（保留） | 维护模式、降级开关 | ✅ | -| Permission Flag | 长期（保留） | 按用户等级开启功能 | ✅ | - -### 功能开关实现规范 - -```cpp -// ✅ 推荐：通过配置中心动态控制 -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 实时可见 - ---- - -## P10: 用户反馈与迭代闭环 - -### 目标 - -建立多渠道用户反馈收集、Feature Request 优先级投票、产品迭代节奏和 NPS 满意度追踪机制。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 产品定位与用户画像 | P0 产出 | 反馈渠道选择依据 | -| 发布节奏 | P8 产出 | 迭代周期对齐 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 用户反馈体系文档 | Markdown | 渠道矩阵、分类标准、处理流程 | -| Feature Request 投票机制 | 文档 | 投票规则、从投票到 Roadmap 的流程 | -| 发布节奏与迭代规范 | 文档 | 版本号策略、发布窗口、发布清单 | -| NPS 与留存追踪方案 | 文档 | 调查时机、计算方式、转化漏斗 | - -### 反馈渠道矩阵 - -| 渠道 | 目标用户 | 反馈类型 | 工具 | -|------|---------|----------|------| -| 应用内反馈 | 所有用户 | Bug / Feature / 满意度 | 内置表单 + 截图标注 | -| GitHub Issues | 开发者 | Bug / Feature | GitHub | -| GitHub Discussions | 社区 | 想法 / 讨论 | GitHub（投票功能） | -| Discord | 活跃社区 | 实时讨论 | Discord | -| 邮件 | 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 | -| Feature Request | 按投票数 | 1 周 | Roadmap 排期 | - -**Triage 流程**：新 Issue → 自动打标签(bot) → 人工分类(维护者轮值，每天 15 分钟) → Bug/Feature/Question 分流 - -### Feature 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 种（应用内 / GitHub / 社区 / 企业邮件） -- [ ] 反馈分类有明确的优先级定义和 SLA（首次响应/解决周期） -- [ ] Feature Request 有投票机制，且票数与 Roadmap 排期挂钩 -- [ ] 发布节奏有明确的版本号策略和发布窗口 -- [ ] NPS 调查触发时机合理，有流失原因收集机制 - ---- - -## P11: 技术债务与风险管理 - -### 目标 - -建立技术债务的识别/记录/偿还机制和项目级风险的识别/评估/缓解体系，防止技术债务失控积累和风险突然爆发。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 所有技术决策 | P2 产出 | ADR 中的风险记录 | -| 当前开发进度 | P4 产出 | 进度偏差 | -| 第三方依赖清单 | P6 产出 | 外部依赖风险 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 技术债务管理策略 | 文档 | 债务类型/等级/追踪方式/偿债时间分配 | -| 风险登记册 | 表格 | 风险描述/概率/影响/等级/缓解措施/触发条件 | -| 零容忍红线清单 | 列表 | 绝对不允许产生或延期的债务类型 | - -### 技术债务管理 - -**核心原则**： -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（改善项） - -**债务登记模板**： -```markdown -### 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 合规风险 | 合规 | 低 | 高 | 🟡 | GPL 隔离(独立进程)+License 审计 | 法律审查 | - -### 风险应对流程 - -``` -识别 → 评估(概率×影响) → 登记 → 制定缓解措施 → 主动监控(每月)/定期审查(每 Phase) - -触发条件满足 → 升级为 Issue → 进入问题追踪流程 -``` - -**风险状态**：🟢 监控中 / 🟡 预警 / 🔴 已触发（转 Issue）/ ✅ 已消除 - -### 检查清单 - -- [ ] 技术债务有分类体系（7 类）和严重等级 -- [ ] 每笔债务有登记模板（类型/等级/引入Phase/偿还计划/负责人） -- [ ] 偿债时间分配随 Phase 递增（10% → 30%） -- [ ] 零容忍红线清单明确且可执行 -- [ ] 风险登记册覆盖技术/人员/进度/外部依赖 4 类 -- [ ] 每个风险有概率×影响评估和具体缓解措施 -- [ ] 风险触发条件明确，触发后自动升级为 Issue - ---- - -## P12: 项目记忆与知识管理 - -### 目标 - -维护一份随仓库分发的"项目记忆"文档，让任何新加入者无需重新探索即可获知全貌。 - -### 输入物 - -| 输入 | 来源 | 说明 | -|------|------|------| -| 所有前述文档 | P0-P11 | 项目全部知识 | - -### 产出物 - -| 产出 | 格式 | 说明 | -|------|------|------| -| 项目记忆文档 | Markdown | 项目速览/结构速查/核心服务清单/构建发布/技术决策/已知陷阱/当前状态/文档索引 | - -### 项目记忆文档模板 - -```markdown -# {项目名} 项目记忆 - -> 此文件随仓库分发，克隆工程后即可获知全貌，无需重新探索。 -> 每次重大变更后同步更新。 - ---- - -## 一、项目速览 - -| 项目 | 说明 | -|------|------| -| **产品** | {一句话描述} | -| **阶段** | Phase N ({阶段名称}) | -| **版本** | vX.Y.Z | -| **进度** | {关键进度百分比} | -| **测试** | {测试数量/通过率} | -| **编译** | {编译器/工具链} | - -## 二、文件结构速查 - -{项目完整目录树，标注每个目录的用途} - -## 三、核心服务/模块清单 - -| 服务 | 类/模块名 | 说明 | -|------|-----------|------| - -## 四、构建与发布 - -{一键构建命令 / 发布命令 / 环境要求} - -## 五、技术决策 - -{关键架构决策、编译器选择、依赖策略、命名规范} - -## 六、关键规则 - -{插件系统关键规则 / 生命周期规则 / API 约束} - -## 七、已知陷阱 - -{容易踩的坑、常见编译/运行时问题及解决方案} - -## 八、当前状态 - -{当前 Phase 完成百分比、已完成/推迟任务清单} - -## 九、关联文档索引 - -| 目的 | 文档 | -|------|------| -| 功能全景 | 01-功能需求文档.md | -| 架构全貌 | 02-系统架构与技术选型.md | -| 进度跟踪 | 31-开发进度跟踪.md | -| 问题记录 | 32-开发问题记录表.md | -| 编码规范 | 16-编码规范.md | -``` - -### 更新规则 - -- 每次重大变更后同步更新（功能完成、架构调整、重大 Bug 修复） -- "已知陷阱"部分看到新人踩坑就追加 -- "关联文档索引"保持最新链接 - -### 检查清单 - -- [ ] 项目速览表能让人 30 秒了解项目状态 -- [ ] 文件结构速查标注了关键目录的用途 -- [ ] 核心服务/模块清单完整且每个有简短说明 -- [ ] 构建命令经新人验证可用 -- [ ] 已知陷阱随时追加（每次有人踩坑就记录） -- [ ] 关联文档索引指向正确的文件路径 -- [ ] 文档在每次重大变更后更新 - ---- - - - - ---- - -## P13: 安全开发生命周期 (SDL) - -### 目标 - -将安全实践嵌入软件开发生命周期的每个阶段，而非"事后打补丁"。遵循"安全左移（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 部署运维: 安全配置基线 + 密钥管理 + WAF -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、密码强度策略、会话管理 | 认证流程测试 | -| 敏感数据泄露 | 传输加密(TLS 1.3)、存储加密(AES-256)、日志脱敏 | 敏感信息扫描 | -| XXE | 禁用外部实体解析 | XML Parser 配置 | -| 访问控制失效 | 最小权限原则、服务端权限校验 | 权限矩阵测试 | -| 安全配置错误 | 安全基线模板、云安全态势管理 | 配置合规扫描 | -| XSS | 输出编码、CSP 头 | XSS 测试用例 | -| 不安全反序列化 | 白名单类名、签名校验 | 反序列化安全测试 | -| 使用含已知漏洞的组件 | SBOM + CVE 监控 + 自动升级 | 依赖扫描 | -| 日志和监控不足 | 审计日志、异常检测、告警 | 日志完整性检查 | - -### 安全工具链集成 - -| 阶段 | 工具 | 触发条件 | -|------|------|---------| -| 编码时 | IDE 安全插件（SonarLint） | 实时 | -| 提交时 | Pre-commit hooks（密钥扫描: gitleaks/truffleHog） | 每次 commit | -| PR 时 | SAST（CodeQL/Semgrep/SonarQube） | 每次 PR | -| 构建时 | 依赖扫描（Trivy/Dependabot/Snyk） | 每次构建 | -| 部署前 | 容器镜像扫描 + IaC 安全扫描 | 每次部署 | -| 运行时 | DAST（OWASP ZAP）+ RASP | 定期/持续 | - -### 密钥管理 - -``` -❌ 禁止: 密钥硬编码在源码中 -❌ 禁止: 密钥通过 Slack/微信/邮件明文传递 -❌ 禁止: 生产密钥与开发密钥相同 - -✅ 使用密钥管理服务（HashiCorp Vault / AWS Secrets Manager） -✅ 密钥定期轮换（90天） -✅ 密钥访问审计日志 -✅ 开发环境使用独立密钥 -``` - -### 安全事件响应 - -当安全漏洞被发现时（内部发现或外部报告）： - -| 时间 | 行动 | -|------|------| -| 0-4h | 确认漏洞真实性、评估影响范围 | -| 4-24h | 制定修复方案、准备补丁 | -| 24-72h | 发布修复、通知受影响用户 | -| 72h+ | Postmortem + 改进安全流程 | - -### 检查清单 - -- [ ] 每 Phase 新功能有威胁建模文档 -- [ ] 安全编码规范已纳入 P5 编码规范 -- [ ] SAST/DAST/依赖扫描已集成到 CI 流水线 -- [ ] 密钥管理方案已就绪（不入库、定期轮换） -- [ ] 安全漏洞报告通道对外公开（security@域名 / Bug Bounty） -- [ ] 第三方依赖 CVE 有自动监控和升级策略 -- [ ] 定期渗透测试（至少每年一次） - - - ---- - -## P14: 合规性管理 - -### 目标 - -确保软件产品在开发、分发和运营过程中满足适用的法律法规和行业标准要求。 - -### 适用范围 - -根据产品定位和分发区域，确定需遵守的法规框架： - -| 法规 | 适用范围 | 核心要求 | -|------|---------|---------| -| 中国《个人信息保护法》(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 | 加密传输 (TLS 1.3)、加密存储 (AES-256)、审计日志 | -| P10 | 用户权利响应（数据下载/删除请求处理 SLA） | -| P13 | 安全措施与合规要求的对应关系 | - -### 数据分类分级 - -| 级别 | 标签 | 示例 | 存储要求 | 传输要求 | 访问控制 | -|------|------|------|---------|---------|---------| -| 公开 | Public | 产品文档、开源代码 | 无需加密 | 无需加密 | 所有人 | -| 内部 | Internal | 设计文档、开发日志 | 加密存储 | TLS | 团队成员 | -| 机密 | Confidential | 用户 PII、业务数据 | 加密+AES-256 | TLS 1.3 | 最小权限 | -| 绝密 | Restricted | 密钥、支付信息、健康数据 | 加密+HSM | TLS 1.3+ | 审计+审批 | - -### 隐私设计检查清单（PbD: Privacy by Design） - -- [ ] 数据收集: 是否只收集了必要的数据？（数据最小化） -- [ ] 数据用途: 用户是否明确知道数据将如何被使用？ -- [ ] 同意管理: 用户是否可以撤回同意？ -- [ ] 数据删除: 用户是否可以请求删除其数据？（"被遗忘权"） -- [ ] 数据导出: 用户是否可以导出其数据？（数据可移植性） -- [ ] 数据留存: 是否定义了数据保留期限？过期数据是否自动删除？ -- [ ] 第三方共享: 用户数据是否与第三方共享？是否已披露？ -- [ ] 儿童数据: 是否涉及 14 岁以下儿童数据？（需监护人同意） - -### 合规审计 - -| 审计类型 | 频率 | 负责方 | -|---------|------|--------| -| 内部合规自查 | 每季度 | 安全/法务团队 | -| 第三方渗透测试 | 每年 | 外部安全公司 | -| 等保测评 | 每 2 年（三级） | 等保测评机构 | -| SOC 2 审计 | 每年 | 审计事务所 | -| ISO 27001 审核 | 每年（监督审核）/ 每 3 年（重认证） | 认证机构 | - -### 检查清单 - -- [ ] 适用法规清单已确定并随产品迭代更新 -- [ ] 数据分类分级方案已实施 -- [ ] 隐私政策已发布且保持更新 -- [ ] 用户数据删除/导出请求处理流程就绪 -- [ ] 敏感数据加密存储和传输 -- [ ] 合规审计频率满足行业和法规要求 -- [ ] 员工数据安全培训完成（每年复训） - - - ---- - -## P15: 供应链安全 - -### 目标 - -管理软件供应链的安全风险，确保所有第三方依赖、构建工具和分发渠道的完整性和安全性，防范供应链攻击。 - -### 核心原则 - -1. **零信任**：不信任任何第三方依赖，默认需要验证 -2. **可追溯**：所有依赖的来源、版本、许可证、CVE 状态可审计 -3. **最小依赖**：优先使用标准库，减少依赖数量 -4. **锁定版本**：所有依赖锁定具体版本（含哈希），禁止 `latest` 标签 - -### SBOM（软件物料清单） - -**要求**：每次发布必须生成 SBOM，格式为 SPDX 或 CycloneDX。 - -```yaml -# 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: SHA-256 - content: a1b2c3... - - - name: nlohmann_json - version: "3.11.3" - purl: pkg:github/nlohmann/json@3.11.3 - licenses: - - license: - name: MIT -``` - -**SBOM 用途**： -- 许可证合规审计 -- CVE 影响范围快速定位（Log4Shell 级别的应急响应） -- 企业客户安全审查 - -### 依赖安全策略 - -| 策略 | 规则 | -|------|------| -| 来源可信 | 仅从官方仓库/包管理器拉取，禁止从随机 GitHub fork 引用 | -| 版本锁定 | 所有依赖锁定到具体版本，通过 lockfile 管理 | -| 哈希校验 | CI 中校验下载的依赖包哈希是否与 lockfile 一致 | -| CVE 监控 | 自动扫描依赖的已知漏洞，高危漏洞 7 天内修复 | -| 许可证审计 | 所有依赖的许可证必须通过审核，禁止引入 GPL/AGPL 传染性依赖（或隔离处理） | - -### 依赖风险等级 - -| 风险 | 判定标准 | 处理方式 | -|------|---------|---------| -| 🔴 阻断 | 已知 CVE Critical/High + 有公开 Exploit | 立即升级或替换 | -| 🟠 高风险 | 已知 CVE Critical/High，无公开 Exploit | 1 个 Sprint 内升级 | -| 🟡 中风险 | 已知 CVE Medium/Low | 2 个 Sprint 内升级 | -| 🟢 低风险 | 无已知 CVE | 定期维护 | - -### 构建管道安全 - -``` -构建环境安全要求: - □ 构建在隔离环境中执行（容器/VM），每次构建后销毁 - □ 构建产物签名（代码签名证书） - □ SBOM 自动生成并归档 - □ 构建日志保留 90 天 - □ 构建依赖缓存独立，不同项目不共享 - -签名验证链: - 源代码 → CI 构建 → 产物签名 → 签名验证 → 分发渠道 → 用户端验签 -``` - -### 私有包/镜像仓库 - -国内网络环境下，推荐搭建私有代理仓库： - -```bash -# Conan 私有源 -conan remote add private https://conan.internal.example.com - -# Docker 镜像加速 -registry-mirrors: ["https://mirror.internal.example.com"] - -# npm 私有源 -npm config set registry https://npm.internal.example.com -``` - -**私有仓库安全要求**： -- 访问控制（谁可以发布/拉取） -- 包扫描（上传时自动 CVE 扫描） -- 审计日志（谁在什么时候拉取/发布了什么） - -### 检查清单 - -- [ ] SBOM 在每次发布时自动生成并归档 -- [ ] 所有依赖锁定具体版本 + 哈希 -- [ ] CVE 监控自动化，Critical 漏洞 7 天内修复 -- [ ] 构建在隔离环境中执行 -- [ ] 构建产物有代码签名 -- [ ] 第三方依赖来源审核完成（无不可信来源） -- [ ] 许可证合规检查已集成（阻断 GPL 传染性依赖） -- [ ] 私有包仓库安全策略已就绪 - - - ---- - -## P16: 无障碍访问 (a11y) 规范 - -### 目标 - -确保软件产品可以被残障用户（视力障碍、听力障碍、运动障碍、认知障碍）正常使用，满足 WCAG 2.1 AA 标准。 - -### 为什么需要 - -- **法律要求**：欧美政府采购和政府客户普遍要求 WCAG 2.1 AA 合规 -- **扩大用户群**：全球约 15% 人口有某种形式的残障 -- **更好的用户体验**：无障碍设计通常让所有用户受益（如键盘操作、高对比度） - -### WCAG 2.1 AA 核心要求速查 - -| 原则 | 要求 | 具体实现 | -|------|------|---------| -| 可感知 | 文本替代 | 所有非文本内容（图片/图标）有文本描述 | -| 可感知 | 时间媒体 | 视频有字幕，音频有文字稿 | -| 可感知 | 可适配 | 内容在不同屏幕方向和缩放比例下可用 | -| 可感知 | 可辨别 | 颜色不是传达信息的唯一方式，对比度≥4.5:1 | -| 可操作 | 键盘可访问 | 所有功能可通过键盘完成（Tab/Enter/Esc） | -| 可操作 | 足够时间 | 无强制时间限制，或可延长/关闭 | -| 可操作 | 导航 | 有跳过导航的机制、有意义的页面标题 | -| 可理解 | 可读 | 语言可编程式检测，缩写有解释 | -| 可理解 | 可预测 | 组件行为一致，不自动触发上下文变化 | -| 可理解 | 输入辅助 | 错误提示明确、有纠正建议、有确认机制 | -| 健壮 | 兼容 | 兼容屏幕阅读器等辅助技术 | - -### 开发实现规范 - -#### 1. 键盘导航 - -```cpp -// 所有交互元素必须支持键盘操作 -// 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. 屏幕阅读器支持 - -```cpp -// 设置可访问名称和描述 -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 | - -```css -/* 不要仅用颜色区分状态 */ -/* ❌ 错误: */ -.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 集成**： -```bash -# 自动化无障碍检查（在 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 -- [ ] 无障碍声明在官网发布 - - - ---- - -## P17: 依赖升级管理 - -### 目标 - -建立系统化的第三方依赖升级评估和执行流程，在"保持最新"和"维护稳定"之间找到平衡，避免依赖腐烂。 - -### 升级策略 - -| 类型 | 频率 | 触发条件 | -|------|------|---------| -| 安全补丁 | 立即 | CVE Critical/High 披露 | -| 小版本升级 (Patch) | 每月 | 无 Breaking Change | -| 中版本升级 (Minor) | 每季度 | 无 Breaking Change | -| 大版本升级 (Major) | 每年评估 | 有 Breaking Change | - -### 升级评估模板 - -```markdown -# 依赖升级评估: {库名} v{当前版本} → v{目标版本} - -## 基本信息 -- 库: {名称} -- 当前版本: v1.2.3 -- 目标版本: v2.0.0 -- 升级类型: Major - -## 变更分析 -- Breaking Changes: {数量}（详见 Changelog） -- 新增功能: {列表} -- 安全修复: {列表} -- 性能改进: {列表} - -## 影响评估 -| 影响范围 | 说明 | -|---------|------| -| API 变更 | {需要修改的调用点数量} | -| 行为变更 | {是否有默认行为变化} | -| 平台兼容 | {Win/Mac/Linux 是否都支持新版本} | -| 许可证变更 | {许可证是否变化，是否仍合规} | -| 依赖冲突 | {是否引入新的传递依赖或版本冲突} | - -## 测试要求 -- [ ] 现有单元测试全量通过 -- [ ] API 兼容性自动检查（对比旧版本 vs 新版本 MIDL） -- [ ] 性能基准对比（升级前后 Benchmark） -- [ ] 跨平台编译通过 - -## 决策 -- [ ] 批准升级 -- [ ] 延期（原因: ___） -- [ ] 拒绝（原因: ___） -``` - -### 自动化依赖监控 - -```yaml -# CI 配置: 依赖升级检查（每周自动执行） -dependency-update-check: - schedule: "0 9 * * 1" # 每周一 09:00 - steps: - - name: Check outdated dependencies - run: | - vcpkg 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 版本升级有评估模板 -- [ ] 依赖腐烂指标在项目仪表盘中可见 -- [ ] 关键依赖（核心引擎库等）有备选方案 - - - ---- - -## P18: 团队沟通与知识传递 - -### 目标 - -建立高效的团队沟通节奏和知识传递机制，确保信息在分布式/远程团队中流畅传递，减少信息孤岛和重复踩坑。 - -### 沟通节奏 - -| 活动 | 频率 | 时长 | 参与者 | 目的 | -|------|------|------|--------|------| -| 每日站会 (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 | 全团队 | 同步路线图进展和调整 | - -### 异步沟通规范 - -远程团队应默认异步沟通： - -| 事项 | 沟通方式 | 期望响应时间 | -|------|---------|------------| -| 日常讨论/问题 | 项目频道 (飞书/Slack) | 工作时间内 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 制度） -- [ ] 知识传递机制涵盖结对编程/技术分享/文档归档 -- [ ] 远程协作规范已明确（核心重叠时间 + 会议纪要要求） -- [ ] 团队日历和休假制度公开透明 - - ---- - -## PA: 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 必须验证自身运行环境完整可用。自检失败 → 记录缺失项 → 求助人类 → 等待解决。 - -#### 自检清单 - -```yaml -# Agent 环境自检 — 每一项必须 PASS 才能开始工作 - -environment_checklist: - # ---- 基础工具 ---- - - check: "git --version" - required: true - fix_hint: "请安装 git 或确保其在 PATH 中" - - - check: "cmake --version" - required: true - fix_hint: "请安装 CMake >= 3.28" - - # ---- 编译器 ---- - - check: "gcc --version || clang --version || cl.exe" - required: true - fix_hint: "请安装 C++ 编译器（GCC >= 13 / Clang >= 16 / MSVC 2022）" - - # ---- 包管理器 ---- - - check: "vcpkg version || conan --version" - required: false - warn_if_missing: "vcpkg 或 conan 未安装，依赖管理需手动处理" - - # ---- 代码格式化 ---- - - check: "clang-format --version" - required: true - fix_hint: "请安装 clang-format" - - # ---- 静态分析 ---- - - check: "clang-tidy --version" - required: false - warn_if_missing: "clang-tidy 未安装，将跳过静态分析检查" - - # ---- 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 通过 → 输出"环境就绪"确认 → 开始执行任务 -``` - -#### 自检输出格式 - -```markdown -## 环境自检结果 - -| 检查项 | 状态 | 说明 | -|--------|------|------| -| git | ✅ PASS | git version 2.43.0 | -| cmake | ✅ PASS | cmake version 3.28.1 | -| gcc | ❌ FAIL | 未找到，请安装 GCC >= 13 | -| clang-format | ✅ PASS | clang-format version 18.1.0 | - -结果: ❌ 环境未就绪 — 1 项缺失 -需要人类协助: 安装 GCC >= 13 -``` - ---- - -### PA.1: 项目状态文件 (PROJECT_STATE.yaml) - -#### PA.1.1 为什么需要 - -AI Agent 每次会话醒来没有记忆。状态文件是 AI 的"外部工作记忆"，让 Agent 在任何时候重启都能准确知道：项目在哪个阶段、完成了什么、正在做什么、下一个任务是什么、有什么阻塞或问题。 - -#### PA.1.2 状态文件规范 - -```yaml -# 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） - -```markdown -# {项目名} 摘要 - -## 定位 -{一句话，30 字以内} - -## 核心差异化 -- {差异化 1} -- {差异化 2} -- {差异化 3} - -## 技术栈 -- 语言: {语言和版本} -- 构建: {构建系统} -- UI: {UI框架} -- 关键依赖: {列表} - -## 架构 -微内核 + 插件化。Shell 提供 PluginManager/EventBus/CommandService。 -插件独立编译单元，通过 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 对操作的置信度低于以下阈值时，必须求助人类： - -```yaml -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: 项目启动 - -``` -Step 1: 信息采集 - - 向人类确认: 一句话定位 / 目标用户 / 核心差异化 / 技术偏好 - - 信息不完整 → 使用合理假设 + 标注不确定性 - - 输出项目信息卡片，请求人类确认 - -Step 2: 竞品分析与可行性 - - 自动搜索 Top 3-5 竞品信息 - - 生成功能矩阵 + 五维可行性评分 - - 标注信息准确度 - -Step 3: 生成 D-001 项目章程 -Step 4: 生成 D-002 技术预研报告 -Step 5: 初始化仓库骨架（目录 + 构建系统） -Step 6: 自检 → 请求人类评审 -``` - -##### P1: 需求分析 - -``` -Step 1: 读取 P0 产出 + 竞品矩阵 -Step 2: 生成 D-100 FRD - - 每个模块: 功能描述 + 输入/输出 + 交互流程 + 异常处理 - - 标注优先级和模块间依赖 -Step 3: 生成 D-101 NFR（所有指标必须可量化） -Step 4: 自检 - - 搜索"适当的""合理的""足够的"等模糊词 → 全部消除或量化 - - 竞品有的功能是否全部覆盖了？ - - 每个模块的异常处理是否定义了？ -Step 5: 请求人类评审 FSD（强制执行，不可跳过） -``` - -##### P2: 架构设计 - -``` -Step 1: 读取 P1 FRD + NFR -Step 2: 生成 D-200 SAD（分层架构 + 组件关系 + 数据流） -Step 3: 对每个重大技术决策 → 生成 ADR（至少 2 个备选方案） -Step 4: 生成 D-210 MIDL（每个插件模块的接口签名） -Step 5: 自检 - - FRD 的所有功能都有对应的架构组件吗？ - - 有没有循环依赖？ - - 有没有只有一个选项的假决策？ -Step 6: 请求人类评审 SAD（强制审批，高危阶段） -``` - -##### P_CODE: 编码实现 - -``` -Step 1: 读取 MIDL + DM + CSG + TCS -Step 2: 从 MIDL 生成接口头文件 -Step 3: 从 DM 生成数据模型代码（struct + 序列化） -Step 4: 从 TCS 生成测试骨架 -Step 5: 填充实现逻辑 -Step 6: 逐文件自检循环（编译 -> lint -> AI黑名单 -> 格式 -> 测试） -Step 7: 循环直到全部通过 -Step 8: 提交 PR，请求人类 Review -``` - ---- - -### 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` 或 `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: 格式检查 → clang-format → 通过 -Round 5: 运行相关单元测试 → 失败 → 分析 → 修复 → 重试 (<3次) - -全部通过 → 标记完成 → 更新 PROJECT_STATE -超过 3 次重试 → 记录详细错误 → 求助人类 -``` - -#### PA.5.4 代码生成模板（头文件） - -```cpp -//===--------------------------------------------------------------===// -// {项目名} - {一句话描述} -// -// 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 用例编号对应 -- [ ] clang-tidy 零警告 -- [ ] clang-format 通过 -- [ ] 无 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 等待。Git 合并冲突 → 尝试自动合并 → 失败则求助 -- **依赖**: 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 执行任务时，应使用以下标准提示词框架： - -```markdown -## 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 任务启动提示词模板 - -```markdown -## 启动任务: {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 + CMake + vcpkg - 2. 目标平台 → 默认: Win/Mac/Linux - 3. 开源策略 → 默认: AGPL v3 - 4. 团队/周期 → 默认: 小团队, 无时间压力 - -第三轮: 合理假设（不需要确认） - 1. 编码规范 → 按 P5 标准 - 2. 测试策略 → 按 P7 标准 - 3. 项目结构 → 按 P6 目录结构 -``` - -#### PA.11.2 项目类型识别 - -| 项目类型 | 识别关键词 | 默认技术栈 | 初始化模板 | -|---------|-----------|-----------|-----------| -| 桌面应用 | "桌面""本地""客户端" | C++/Qt | P6 CMake 结构 | -| 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 通信格式模板 - -##### 请求人类决策 - -```markdown -## 🔔 需要决策: {决策标题} - -**上下文**: {正在进行 P2 架构设计，在选择渲染引擎} - -### 选项对比 - -| 维度 | 方案 A: {名称} | 方案 B: {名称} | 方案 C: {名称} | -|------|--------------|--------------|--------------| -| 技术成熟度 | {高/中/低} | {高/中/低} | {高/中/低} | -| 许可证 | {MIT/GPL/...} | {MIT/GPL/...} | {MIT/GPL/...} | -| 学习曲线 | {陡/中/平} | {陡/中/平} | {陡/中/平} | -| 社区活跃度 | {活跃/一般/停滞} | {活跃/一般/停滞} | {活跃/一般/停滞} | -| 预估集成工时 | {N 天} | {N 天} | {N 天} | - -### AI 推荐 -**推荐方案 A**，理由: {1-2 句话核心理由} - -### 你需要做什么 -- [ ] 选择一个方案，或提出新的选项 -- [ ] 如有补充条件，请说明 -``` - -##### 请求人类提供信息 - -```markdown -## ❓ 需要信息: {问题标题} - -**上下文**: {正在做 P1 FRD，定义了 X 模块} - -**缺少的信息**: -1. {具体问题 1} -2. {具体问题 2} - -**AI 的合理假设**（如果人类不回答，将按此进行）: -- 假设 1: {假设内容} -- 假设 2: {假设内容} -``` - -##### 进度汇报（自动，不阻塞） - -```markdown -## 📊 进度更新 - -- **Phase**: P2 架构设计 (45% → 60%) -- **完成**: D-200 SAD 初稿、D-201 ADR-001 -- **进行中**: D-210 MIDL (3/5 个模块) -- **下一步**: D-300 数据模型设计 -- **需要关注**: {如果有} -``` - -##### 完成通知 - -```markdown -## ✅ 阶段完成: {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 中断恢复检查 - -```yaml -# 恢复执行前的检查 -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 异常分类与预案 - -```yaml -exception_handlers: - - # ---- 环境类 ---- - E_ENV_DEPENDENCY_UNAVAILABLE: - description: "vcpkg/conan/npm 无法下载依赖（网络不通、源不可达）" - severity: "HIGH" - action: - - "尝试切换镜像源（优先国内镜像）" - - "如果 3 次失败 → 记录缺失的依赖清单 → 求助人类" - - "建议人类: 手动安装、使用代理、或替换为已有依赖" - fallback: "如果依赖可选 → 用 #ifdef 包裹，生成降级版本" - - E_ENV_DISK_FULL: - description: "磁盘空间不足，无法继续写入" - severity: "CRITICAL" - action: - - "立即停止所有写入操作" - - "记录当前磁盘使用情况" - - "求助人类: 清理空间或扩容" - fallback: "无降级方案，必须等待人类解决" - - E_ENV_BUILD_TOOL_BROKEN: - description: "CMake/编译器本身损坏或配置错误" - 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) | clang-format ✅ - -Agent → 人类: - ## ❌ 环境未就绪 - | 检查项 | 状态 | 说明 | - |--------|------|------| - | gcc | ❌ FAIL | 未找到 GCC | - - 需要: 安装 GCC >= 13，或告诉我要用哪个编译器。 - -人类: 用 clang，已经装了 -Agent: 重新自检... 全部通过 ✅ -``` - -#### 第 1 步: 信息采集 (PA.11) - -``` -Agent → 人类: - ## ❓ 项目信息确认 - - 在开始之前，请确认: - 1. 一句话定位: {?} - 2. 目标用户: {?} - 3. 核心差异化: {?} - 4. 技术栈偏好: 默认 C++20/Qt/CMake/vcpkg（可改） - -人类: 做一个跨平台的 3D 打印切片软件，目标是桌面端 Maker 用户， - 核心差异化是内置 AI 自动优化支撑结构生成，全部本地运行。 -``` - -#### 第 2 步: 竞品分析 + 可行性 (P0.5) - -``` -Agent: 搜索竞品... 找到 PrusaSlicer, Cura, Bambu Studio, OrcaSlicer -Agent: 生成竞品功能矩阵 → 五维可行性评分 -Agent: 技术可行性 3.8/5、市场可行性 已确认 3 个差异化维度 - -Agent → 人类: - ## 📊 可行性分析摘要 - - | 维度 | 评分 | - |------|------| - | 技术 | 3.8/5 — 本地AI推理+3D渲染，技术可行但集成为挑战 | - | 市场 | 已有 PrusaSlicer/Cura，但无人做深度本地AI切片 | - - ### AI 推荐: GO ✅ - - **需要你确认后进入正式开发** - -人类: 确认，开始吧 -``` - -#### 第 3 步: P0 项目启动 - -``` -Agent: 更新 PROJECT_STATE → current_phase: P0 -Agent: 生成 D-001 项目章程... -Agent: 自检: 一句话定位清晰 ✅ | 差异化可持续 ✅ -Agent: 生成 D-002 技术预研报告... -Agent: 初始化仓库骨架 (CMake + vcpkg + 目录结构)... -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 处 → 已量化 ✅ - - 竞品功能交叉检查 → PrusaSlicer 的可变层高未覆盖 → 已追加 ✅ - - 每个模块有异常处理 → ✅ - -Agent: 生成 D-101 NFR... - - 渲染: 100万三角面 >30fps - - 切片: 标准模型 <30s - - AI推理: 支撑生成 <5s (本地) - - 兼容: Win10/11, macOS 14+, Ubuntu 22.04 -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 在每次任务完成后记录改进点： - -```yaml -# 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 中记录使用的规范版本 -``` - ---- - -## 附录: 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/Qwen 本地部署) -├── Embedding + VectorDB (文档/设计语义搜索) -├── Agent 编排框架 (ReAct/Plan-Execute) -└── MCP 协议服务 (工具注册/调用/结果返回) - -数据层 (Data Layer) -├── 业务知识库 (业务数据/规则/模板/标准) -├── 历史项目语料 (业务模式/常见错误) -├── 用户行为日志 (偏好学习) -└── 仿真结果数据库 (代理模型训练) -``` - -### AI 功能开发优先级 - -| Phase | AI 能力 | 说明 | -|-------|---------|------| -| P1 | AI Core (LLM 推理/Embedding/VectorDB) | 基础设施嵌入 Shell | -| P2 | AI Copilot v1 (自然语言→命令) | 基础对话式交互 | -| P3 | AI Copilot v2 + SubEntity AI + Generative AI | AI 成为核心交互方式 | -| P4 | AI Sim + AI Mfg + Knowledge Graph + AI Collab | AI 覆盖全链路 | - -### 数据流与模型训练规范 - -``` -用户使用(推理) - 本地 LLM 推理 → 工具调用(MCP) → 执行结果 → 上下文更新 - │ (可选) - └→ 复杂任务 → 云端大模型 → 结果回传 - -模型改进(训练/微调) - 脱敏后的匿名使用数据 → 云端训练 pipeline → 模型评估 → A/B 测试 → 推送更新 -``` - -### 隐私与安全 - -- 用户设计数据**绝不**上传到云端（本地 LLM 推理） -- 可选：仅脱敏后的匿名统计数据用于模型改进 -- Enterprise 版支持完全气隙部署（所有 AI 能力本地运行） - ---- - -> **文档结束** -> -> 本流程文档基于中大型软件项目的全流程设计文档提炼而成。 -> 核心方法论可迁移至任何中大型软件项目。 -> 各阶段的具体产出物模板和检查清单可直接复用，按项目特点裁剪即可。 -*（内容由AI生成，仅供参考）* -*（内容由AI生成，仅供参考）* -*（内容由AI生成，仅供参考）* -*（内容由AI生成，仅供参考）* +- **文件驱动设计（DDD）**: 文件即契约，单一事实来源，先文档后代码 +- **微内核 + 插件化**: 最小内核 + 功能通过插件扩展 +- **渐进式交付**: 分阶段路线图，每阶段有明确里程碑与验收标准 +- **AI 嵌入全链路**: 需求→设计→编码→测试→运维，AI 作为第一公民