📄 本页由源文件 skills/dev-flow/steps/step-3-plan.md 自动投影生成（单一权威源）。请勿直接编辑本页。

步骤 3：制定方案 + 执行计划

本文件仅在执行步骤 3 时加载。执行完毕后输出完成标记 JSON，通过门控后加载步骤 4。

目标

先追根因再修复，复用已有逻辑，严格隔离影响范围。制定结构化执行计划。

执行规范

1. 方案制定

调用 use_skill('design-advisor') design-guide 模块辅助方案设计。

迭代修复场景：在原方案基础上做增量调整。详见 references/iteration-fix.md。

1.5 历史类似改动参考（信号 2 驱动，默认沉默）

让方案设计从"AI 凭空想"变成"基于项目历史惯例"，大幅降低"改出来不符合项目风格"的风险。 只在命中信号 2 时触发，其余场景静默跳过（不读配置文件、不调 MCP）。

信号 2：方案需要历史参考（任一命中即触发）：

触发条件	数据来源	说明
需求含扩展类动词且项目已接入 知识库平台	需求文本匹配 + remote-knowledge.md §二 项目映射表	匹配关键词：新增/对接/接入/集成/重构/新增配置项/升级
modules_count ≥ 2	步骤 2 JSON	非单文件改动
用户命令 dev:mr	CLI 触发	强制查历史 MR

不触发（静默跳过，不加载配置文件、不调 MCP）：

• 项目未接入 知识库平台（映射表未命中）
• 单文件 bug 修复 / 极简类需求（描述短 + 关键词正则/文案/常量）
• 用户明确 --no-remote-kb

执行方式（命中后由步骤 3 本步骤主动发起 1 次 git_merge_request 检索，按 remote-knowledge.md §三 节点触达规则：最大 1 次调用，Token 预算 ≤2k，top_k=3）：

{
"serverName": "{knowledge | remote_kb}",
"toolName": "knowledgebase_search",
"arguments": {
"knowledge_uuid": "{从映射表取值}",
"data_type": "git_merge_request",
"search_domain": "{当前项目的 git_merge_request 域，限当前项目}",
"query": "{需求主题一句话}",
"keyword": "{预期 MR 标题可能出现的关键词；中英混合}"
}
}

取前 3 个相关度最高的 MR，读取 description，作为方案参考。只采纳「笼统打包类似」的条目；弱相关的直接舍弃，禁止为凑数照搬。

信息压缩：MR description 超过 500 token 的部分必须摘要为 ≤200 token 再写入步骤 3 输出区块，原文仅保留链接。

输出区块（仅命中时输出，未命中时静默跳过，不用证伪标注）：

### 历史类似改动（参考）
| MR | 标题 | 类似点 | 可借鉴的做法 |
| --- | --- | --- | --- |
| !{编号} | {标题} | {一句话说明与本需求的交集} | {从 MR 中提炼的可复用模式/分层/命名/注册点} |

最终制定方案时，如实际借鉴了某 MR 的做法，在执行步骤表格的"改动内容"列或"技术方案摘要"中标注「参考 !{MR 编号}」。

2. 输出结构化执行计划（必须）

计划粒度选择（AI 根据任务复杂度自动判断）：

条件	粒度	说明
单文件、改动极小（如正则/文案/常量）	极简模式	方案 1 句话 + 执行步骤 1 行 + 边界 1 行
步骤 ≤5 且风险低	标准模式（默认）	表格形式，每行一个操作
步骤 >5 或风险中/高 或用户要求	详细模式	每步含完整代码片段、精确行号、预期输出
涉及 TDD 场景	在对应步骤标注 [TDD]	步骤 5 将按 TDD 流程执行该步

极简模式模板（遵循 flow.md 产出物真实性原则）

适用于单文件、改动极小、根因显然的任务（如邮箱正则修复、文案调整、常量值改动）。禁止为了"显得完整"而扩充为标准模式。

⚠️ 极简模式硬性准入清单（机器可校验，防"伪装简化"）

以下条件必须全部满足才能使用极简模式，任一不满足 → 自动禁用极简模式，必须使用标准模式：

#	准入条件	数据来源	反例（任一出现则禁用极简）
1	related_files_count ≤ 2	步骤 1 JSON	研究发现 ≥ 3 个相关文件
2	upstream_deps.length === 0	步骤 1 JSON	存在任何上游调用方
3	modules_count === 0	步骤 2 JSON	涉及 ≥ 1 个独立功能模块
4	files_count === 1	步骤 2 JSON	修改 ≥ 2 个文件
5	impact_levels.linked === 0	步骤 2 JSON	存在联动影响文件
6	sufficiency_check.confidence === "high"	步骤 1 JSON	置信度 medium 或 low
7	改动行数预估 ≤ 20 行	本步骤自评	预估改动超过 20 行
8	risk_level === "low"	本步骤自评	风险等级 medium 或 high

AI 使用极简模式前必须输出准入清单校验：

【极简模式准入校验】
✅/❌ 1. related_files_count = {实际值} (≤2 要求)
✅/❌ 2. upstream_deps.length = {实际值} (=0 要求)
✅/❌ 3. modules_count = {实际值} (=0 要求)
✅/❌ 4. files_count = {实际值} (=1 要求)
✅/❌ 5. impact_levels.linked = {实际值} (=0 要求)
✅/❌ 6. sufficiency_check.confidence = {实际值} (=high 要求)
✅/❌ 7. 改动行数预估 = {实际值} 行 (≤20 要求)
✅/❌ 8. risk_level = {实际值} (=low 要求)
结论：{全部通过 → 启用极简模式 / 任一不通过 → 禁用极简模式，改用标准模式}

极简模式模板

## 执行计划

**方案**：{一句话描述改什么}
**执行**：修改 `{相对路径}` L行号 — {改动内容}
**不做什么**：{一句话声明边界，如"仅修改正则，不改校验调用链"}
**风险**：{低/中/高，如无真实风险写"无（理由）"}

标准模式模板

## 执行计划（2）

### 技术方案摘要
{一段话描述核心思路}

### 执行步骤
| # | 操作 | 目标文件 | 改动内容 | 风险点 |
| --- | --- | --- | --- | --- |
| 1 | 修改 | `{相对路径}` | {具体改什么} | {可能影响/需验证} |
| 2 | 新增 | `{相对路径}` | {新建什么} | — |

### 改动边界图（可选，复杂度 ≥ 中时推荐）
> 基于 step-1 调用链路图，用高亮标注**本次改动的节点边界**（如 `✏️ 核心改` / `🔗 联动` / `👁️ 仅验证`）。规范见 `references/call-graph-spec.md`。

### 预估影响
- 影响范围：{涉及 N 个文件，M 个模块}
- 风险等级：{低/中/高}
- 预估耗时：{分钟/小时}

### 不做什么（边界声明）
- {明确列出本次不会触碰的区域/文件/逻辑}

详细模式模板（复杂任务/用户要求时使用）

## 执行计划（详细模式）

### 技术方案摘要（2）
{一段话描述核心思路}

### 执行步骤（2）

#### 步骤 1：{操作描述}（约 N 分钟）
- **文件**：`{相对路径}` L{起始行}-L{结束行}
- **改动**：{精确描述改什么}
- **代码**：
```
// 修改前（关键片段）
{当前代码}
// 修改后
{目标代码}
```

- **验证**：{如何确认这步成功，预期输出}
- **风险**：{可能影响}

#### 步骤 2

### 改动边界图（可选，复杂度 ≥ 中时推荐）（2）
>
> 基于 step-1 调用链路图，标注本次改动的节点边界；深度模式下可逐步骤标注改动路径。规范见 `references/call-graph-spec.md`。

### 预估影响（2）

- 影响范围：{涉及 N 个文件，M 个模块}
- 风险等级：{低/中/高}
- 预估耗时：{分钟/小时}

### 不做什么（边界声明）（2）

- {明确列出本次不会触碰的区域/文件/逻辑}

3. 批次规划（大需求自动触发）

触发条件（满足任一即触发批次规划建议）：

条件	阈值	说明
计划步骤数	>8	单次对话难以高质量完成
涉及文件数	>10	改动面过广，风险需分散
涉及模块数	>3	跨模块联动，需分阶段验证
预估改动行数	>500	Token 消耗大，需分次执行
用户主动要求	—	"分批做"/"先做xxx部分"

不触发时：跳过批次规划，正常输出执行计划。

触发时：在执行计划之后，额外输出批次规划建议：

📦 批次规划建议
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

本需求计划步骤较多（{N} 步，涉及 {M} 个文件），建议分 {K} 批执行：

| 批次 | 包含步骤 | 核心目标 | 涉及文件 | 依赖 |
| --- | --- | --- | --- | --- |
| Batch 1 | #1~#3 | {目标描述} | {文件列表} | 无 |
| Batch 2 | #4~#6 | {目标描述} | {文件列表} | Batch 1 |
| Batch 3 | #7~#N | {目标描述} | {文件列表} | Batch 2 |

拆分原则：

- 每批次可独立验证和 commit
- 批次间依赖关系清晰（无循环依赖）
- 每批次 ≤5 个计划步骤（Token 友好）
- 📌 「涉及文件」列按 AI 行为规范「文件/代码位置引用」使用反引号包裹相对路径格式（`` `相对路径` ``）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

批次拆分规则：

规则	说明
独立可验证	每批次完成后代码可编译、可运行、可验证
无循环依赖	Batch N 只依赖 Batch 1~N-1，不依赖 N+1
粒度适中	每批次 3~5 个计划步骤，≤8 个文件
功能内聚	同一功能模块的改动尽量在同一批次
基础设施优先	类型定义、工具函数、数据结构等放在 Batch 1
可并行标注	批次规划表的「依赖」列为「无」的批次，标注 ⚡ 可并行；多个无依赖批次可由不同子 Agent 同时执行（各自走独立的 4.5→7 循环），最终按顺序合并

⛔ 退出自检清单（逐项口播确认后才能输出完成 JSON）

在输出完成标记 JSON 之前，逐项确认并口播：

• [ ] design-advisor 已调用？
• [ ] 信号 2 判定已执行？remote_kb_signal_2_hit / similar_mrs_referenced 字段正确？
• [ ] 执行计划已输出（极简/标准/详细模式）？
• [ ] 极简模式（如适用）→ 8 项准入清单已全部 ✅ 并输出？
• [ ] boundary_declared = true（必须声明"不做什么"）？
• [ ] plan_steps_count > 0？
• [ ] 批次规划已按需触发（>8 步骤 / >10 文件 / >3 模块 / >500 行 / 用户要求）？
• [ ] files_to_modify 或 files_to_create 至少一个非空？
• [ ] 上述全部完成 → 才可输出完成标记 JSON

---

必须输出

步骤推进选项（标准模式必须）

按 steps/step-router.md §「步骤流转交互规则」，完成标记 JSON 输出并状态同步后，必须调用 ask_followup_question 弹出推进选项（先文本表格展示，再调用工具）：

选项	说明
▶️ 继续步骤 4（方案汇报与用户决策）	方案已制定，进入执行深度决策
⏸️ 暂停，我有补充/疑问	暂停等待用户输入
🔁 回退步骤 2 重新确认范围	方案制定过程发现范围有偏差

精简模式：步骤 3→4 无专属豁免，标准模式必须弹出。

结构化完成标记（必须输出，缺字段视为未完成）

{
"step": 3,
"name": "制定方案",
"status": "completed",
"outputs": {
"plan_steps_count": "执行计划步骤数（数字）",
"risk_level": "low | medium | high",
"files_to_modify": ["待修改文件列表"],
"files_to_create": ["待新增文件列表"],
"boundary_declared": true,
"output_mode": "minimal | standard | detailed",
"minimal_mode_gate_passed": "true | false | not_applicable（output_mode=minimal 时必填；其他模式填 not_applicable）",
"estimated_loc_change": "预估改动行数（数字，极简模式必填）",
"batch_suggested": "true | false（可选，触发批次规划时输出）",
"batch_count": "批次数（可选，仅 batch_suggested=true 时）",
"batch_plan": "批次规划数组（可选，仅 batch_suggested=true 时）",
"similar_mrs_referenced": "引用的历史类似 MR 数量（数字，0 表示未触发或未命中）",
"similar_mrs_source": "知识库平台 | not_applicable（知识库平台 不可用或未触发时为 not_applicable）",
"remote_kb_signal_2_hit": "true | false（本步骤是否触发了信号 2：方案需要历史参考）"
},
"working_context_updated": true,
"next_step": 4
}

完成标记校验规则：

• plan_steps_count 必须 > 0（至少有 1 个执行步骤；极简模式下可为 1）
• boundary_declared 必须为 true（必须声明"不做什么"，极简模式下可为 1 行）
• files_to_modify 或 files_to_create 至少有一个非空
• status 为 completed 时才能进入步骤 4

极简模式门控（output_mode === "minimal" 时额外校验）：

• minimal_mode_gate_passed 必须为 true——AI 必须已输出准入清单 8 项全部 ✅
• estimated_loc_change 必须 ≤ 20
• risk_level 必须为 "low"
• 若任一不满足 → status: "blocked"，回退到标准模式重新制定方案

反滑坡规则：禁止 output_mode = "minimal" 且 minimal_mode_gate_passed = false（AI 不得在未通过准入校验的情况下使用极简模式）。

📝 本步骤完成 JSON 不包含 branch_final / branch_source / branch_name_lint_passed 字段。分支命名校验由 steps/step-4-decision.md §4.1 承担。