/plan
需求分析与方案设计。输出结构化的实现方案文件，等待人工审批后再执行。
需求分析与方案设计
步骤
Step 1: 理解需求
使用 AskUserQuestion 确认功能行为、边界、是否有类似功能可参考。
判断功能规模：
- 小功能（改动 ≤ 3 个源码文件，无新数据模型）：确认需求后进入 Step 2，Step 5 持久化为可选（问用户是否需要写 plan 文件）
- 中大功能（跨模块 / 新数据模型 / 新 API / 改动 > 3 个源码文件）：如果项目有
docs/spec.md或docs/product-spec.md，基于它设计方案；如果没有，追加结构化提问：- 目标用户是谁？要解决什么问题？
- 核心用户故事（3-5 条）
- In scope / Out of scope
- 验收标准（Given/When/Then）
文件计数：只算源码文件（src/、lib/、app/ 等），不算测试、配置、文档。
判断改动性质（在 Step 2 搜索代码后可调整）：
- 兼容型 — 新增功能，不改已有接口 → 正常流程
- 破坏型 — 修改现有 API 签名 / 数据结构 / 公共接口 → Step 3 先输出接口变更清单
- 横切型 — 一个决策影响大量文件（如 i18n、主题系统、权限模型）→ Step 3 使用横切型四阶段结构
如果在 Step 1 无法确定改动性质，标记为"待定"，Step 2 搜索代码后再判断。
Step 2: 检查现有代码
搜索代码库中已有的类似功能或可复用模块：
- 用 Grep 搜索与需求相关的关键词（功能名、领域词）
- 用 Glob 搜索相关目录结构（如
src/components/**/*.tsx、src/api/**/*.ts） - 列出可复用的组件、工具函数、类型定义
搜索结果如何影响方案：
- 找到可复用模块 → 方案中标注"复用 X"，不重新实现
- 找到类似功能 → 参考其模式和架构风格，保持一致性
- 什么都没找到 → 直接说"无可复用代码"，继续
此时可以重新评估 Step 1 的改动性质判断（如发现影响文件远超预期，调整为横切型）。
Step 3: 输出实现方案
所有方案必须包含的基础结构：
## 方案概述
[一句话描述实现思路]
## 影响范围
- 新建文件：[列出]
- 修改文件：[列出，标注改动点]
- 依赖变更：[列出新增/移除的包]
## 实现步骤
1. [步骤1 - 具体到文件和函数级别]
2. [步骤2]
...
## 非目标（本次不做）
- [明确列出不做的事项及理由，防止范围蠕变]
## 风险点
- [可能出问题的地方及应对措施]中大功能追加（在基础结构前面）：
- 目标与非目标 + 用户故事与验收标准 + 范围边界
- 部署路径验证（M0）：本地→staging→production 的配置差异和验证步骤
- 技术选型决策日志：新引入的技术/框架需记录选型理由和备选方案
破坏型追加（在方案最前面）：
## 接口变更清单
| 变更项 | 变更前 | 变更后 | 受影响的调用方 |
|--------|--------|--------|--------------|
| [接口/类型] | [原签名] | [新签名] | [文件:函数] |横切型替换实现步骤为四阶段：
## 实现步骤（横切型四阶段）
1. **基础设施**：建立横切能力的核心（context/provider/hook/middleware）
2. **数据层**：准备所有横切数据（翻译字典/主题 token/权限矩阵）
3. **批量替换**：改动所有消费方（文件多时可拆多个子代理并行，每个负责一组文件）
4. **测试修复**：统一修复因横切变更断裂的测试横切型阶段 3 是唯一允许子代理并行的场景（文件间无联动依赖）。其他场景涉及 3+ 文件联动修改时，在主上下文顺序执行，不拆子代理。
执行约束（方案确认前自检）：
- 方案中不得出现"或"/"可选"/"也可以"等模糊措辞，每个步骤的技术选型必须唯一确定
- 如果项目有
docs/product-spec.md，每个任务标注它服务的旅程（Journey: §3.x） - 多阶段方案（分阶段交付）—— 每个阶段必须含三件套：①影响范围（新建/修改文件列表，到模块级）②量化验收阈值（可观测/可测试指标，如 "首屏 ≤0.3s"、"覆盖率 ≥80%"、"3 次自动提示触发"）③风险点（阶段级，含尚未决策的技术选型）。不允许出现"能展示"/"可以调整"/"基本可用"等无量化措辞
Step 4: 等待确认
输出方案后，明确问用户："方案是否可以？有需要调整的部分吗？"
处理用户反馈：
- 确认（"可以"/"没问题"/"开始做"）→ 进入 Step 5
- 部分修改（"X 部分换一种方式"）→ 修改方案中对应部分，重新展示变更处，再次确认
- 全面否定（"方案不对，换个思路"）→ 回到 Step 1 重新理解需求
- 追加需求（"再加一个 Y 功能"）→ 评估影响范围，更新方案，再次确认
Step 5: 持久化方案
用户确认后，将方案写入 docs/plans/{slug}.md。
文件格式：
markdown
# {方案名称}
Status: active
Progress: 0/{N}
Date: YYYY-MM-DD
## 目标
[从 Step 1 提炼]
## 任务清单
- [ ] {步骤 1}（`涉及的文件`）
- [ ] {步骤 2}
...
## 关键决策
[重大选型摘要，如有对应 ADR 则链接]命名和索引规则：
- slug 用 kebab-case，纯语义（如
auth-oauth.md、order-export.md） - N = 任务清单条目数
- Status 只允许 4 个值：
active/done/draft/superseded - 如果
docs/plans/不存在则创建 - 如果同名 slug 文件已存在，追加数字后缀（如
auth-oauth-2.md） - 如果
docs/plans/README.md存在，追加一行索引；不存在则跳过
小功能快速路径： Step 1 判断为小功能时，问用户"需要写 plan 文件吗？"。用户说不需要则跳过 Step 5，方案只在对话中交付。
IMPORTANT
- 里程碑拆分原则（中大功能适用）：
- 高技术风险任务前置（如未验证的第三方库、新数据库引擎）
- 每个里程碑独立可交付、可验收
- 接口设计预留后续扩展点（前向兼容）
- 分层递进：基础层 → 功能层 → 体验层 → 质量层
- 方案确认前不修改代码 — /plan 是纯分析阶段，在 Step 4 用户确认前，不要修改任何源码文件
- 方案确认后不自行实现 — 方案写入 plan 文件后停止。代码实现由用户决定何时开始
- Status 值标准化 — 只用
active/done/draft/superseded四个值，不要用complete、completed、approved等近义词 - 消除模糊措辞 — 方案中不得出现"或"/"可选"/"也可以"，每个步骤的选型必须唯一确定
- 小功能可跳过持久化 — 改动 ≤ 3 个源码文件的小功能，持久化为可选，不强制写 plan 文件