Plan 模式协作流程
本文档定义 Plan 模式的工作流程、禁止动作与协作规范，确保团队在实施前达成一致。
1. Plan 模式定义
Plan 模式是一种只读探查 + 方案设计的协作流程，用于：
- 复杂功能的实施前规划
- 多模块改动的影响分析
- 架构决策的方案对比
核心原则：
- 只读探查，不修改代码或配置
- 输出可执行的实施方案
- 明确假设、约束与回滚策略
2. 工作流程（固定四步）
2.1 只读探查
目标： 理解现状、识别改动点、评估影响范围
允许的操作：
- ✅ 读取代码文件（Read、Glob、Grep）
- ✅ 查看 git 历史与分支
- ✅ 阅读文档与配置
- ✅ 分析依赖关系
禁止的操作：
- ❌ 修改任何文件（Edit、Write）
- ❌ 运行会改变源码的命令（如格式化、代码生成）
- ❌ 执行测试或构建（除非明确需要验证现状）
2.2 意图确认
目标： 与团队确认需求理解、边界与优先级
输出：
- 需求澄清（如有歧义）
- 改动范围确认
- 非目标明确（什么不做）
工具：
- 使用 AskUserQuestion 与团队确认关键决策点
2.3 实施方案
目标： 输出结构化的实施计划
必须包含：
- 改动文件清单与改动类型
- 接口/API 变更说明
- 测试策略与验收标准
- 回滚方案
- 假设与依赖
模板： 见 Plan 模式计划模板
2.4 切执行模式
目标： 获得批准后，切换到执行模式实施
检查清单：
- [ ] 方案已评审通过
- [ ] 关键假设已验证
- [ ] 回滚策略已明确
- [ ] 测试策略已就绪
3. Plan 模式禁止动作（明确边界）
| 动作类型 | 是否允许 | 说明 |
|---|---|---|
| 读取文件 | ✅ 允许 | Read、Glob、Grep |
| 修改文件 | ❌ 禁止 | Edit、Write、NotebookEdit |
| 运行测试 | ⚠️ 谨慎 | 仅用于验证现状，不修改代码 |
| 执行构建 | ⚠️ 谨慎 | 仅用于验证现状，不修改代码 |
| Git 操作 | ⚠️ 谨慎 | 仅查看历史，不提交或推送 |
| 代码生成 | ❌ 禁止 | 包括格式化、lint 修复等 |
4. 输出物要求
4.1 计划文档
使用 Plan 模式计划模板 输出结构化计划，包含：
- 目标与范围
- 改动清单
- 接口变更
- 测试策略
- 回滚方案
- 假设与依赖
4.2 决策记录
对于关键架构决策，记录：
- 决策背景
- 备选方案
- 选择理由
- 取舍分析
5. 协作规范
5.1 何时使用 Plan 模式
必须使用：
- 跨模块的架构改动
- 涉及 API 契约变更
- 需要数据库迁移
- 影响多个团队的改动
可选使用：
- 单模块内的重构
- 新增独立功能
- 文档更新
5.2 评审要求
- 计划文档需至少一人评审
- 涉及 API 变更需产品/架构评审
- 涉及数据迁移需 DBA 评审
5.3 批准后执行
- 获得批准后，创建新分支开始实施
- 实施过程中如发现计划偏差，及时更新计划或重新评审
- 完成后验证是否符合计划的验收标准
6. 示例场景
场景 A：新增多模态端点
Plan 模式输出：
- 探查现有
/api/v1/ai/chat实现 - 识别需要新增的路由、中间件、配置
- 设计
/api/v1/ai/chat/multimodal接口契约 - 明确 fallback 策略与错误码
- 输出实施计划与测试用例
执行模式：
- 创建分支
feature/multimodal-endpoint - 按计划实施代码改动
- 运行测试验证
- 提交 PR 并关联计划文档
场景 B：NPU 分层部署策略
Plan 模式输出：
- 探查现有部署文档结构
- 调研 NPU 硬件分层与模型档位
- 设计配置映射与灰度策略
- 输出文档结构与内容大纲
执行模式：
- 创建分支
docs/npu-tiered-deployment - 按计划编写文档
- 更新相关入口与导航
- 提交 PR 并关联计划文档