SKILL.md
Requirement Clarify -- 需求澄清协议
核心原则
先识别类型，再选对路径。 不同类型的需求，分析视角完全不同。
触发条件
用户提出任何涉及代码或架构的需求时自动触发。
Phase 0: 需求类型识别（最先执行）
收到需求后，第一步是判断需求属于哪种类型。不同类型走不同的分析路径。
需求类型分类
| 类型 | 识别特征 | 用户意图 | 分析视角 |
|---|---|---|---|
| A. 实施型 | "加个功能""改个Bug""做个优化""把这个改成..." | 明确要动手写代码 | 开发实现视角（怎么实现） |
| B. 方案讨论型 | "这个怎么做比较好""有没有什么方案""你觉得怎么实现" | 讨论实现路径，尚未决定动手 | 多视角对比（产品/用户/开发） |
| C. 决策型 | "要不要做这个""A还是B""哪个更合适" | 需要利弊分析辅助决策 | 战略视角（成本/收益/风险） |
| D. 探索型 | "这个能不能实现""技术上可行吗""有没有可能..." | 评估可行性，尚未决定做不做 | 技术可行性视角 |
| E. 问题诊断型 | "这个为什么不行""哪里出了问题""帮我看看..." | 定位问题根因 | 调试视角（数据流/状态/日志） |
| F. 纠错型 | "这个需要修复""这里有问题""XX功能不对"（常附截图/录屏） | 快速定位缺陷根因模块 | 感知层→实现层逆向映射 |
类型判断规则
- 用户描述中有明确动作指令（加/改/删/修/建）→ A 实施型
- 用户描述中有疑问词但无动作指令（怎么/如何/哪种/能不能）→ B/C/D
- 用户描述中有症状但无方案（为什么/出问题了/不对）→ E 诊断型
- 用户描述中有缺陷现象+修复诉求（需要修复/这里有问题/XX不对/附截图）→ F 纠错型
- E 与 F 的区分：E 是"为什么会这样"（探究根因），F 是"这里不对，改掉它"（修复诉求+现象描述）；F 先经纠错提问钩子做非技术提问定位，再进入 E 的诊断流程
- 不确定时，直接问用户："你是希望我直接实现，还是先讨论方案？"
各类型的分析路径
A. 实施型 → 走完整澄清 + 实施流程
即"先问清楚再动手"，走 Phase 1-4 完整流程（详见下方）。
B. 方案讨论型 → 多视角分析
目标：不急着写代码，先从多个角度分析方案优劣，帮用户看清全貌。
分析视角矩阵：
| 视角 | 关注点 | 典型问题 |
|---|---|---|
| 产品经理视角 | 用户价值、使用场景、功能优先级、与产品路线图的关系 | "这个功能解决什么痛点？目标用户是谁？使用频率多高？" |
| 终端用户视角 | 操作体验、学习成本、操作路径长度、心智模型匹配 | "用户需要几步完成？会不会觉得困惑？和现有操作习惯一致吗？" |
| 开发实现视角 | 技术复杂度、改动范围、与现有架构的契合度、工期估算 | "需要改几个文件？有没有现成模块可复用？工期多久？" |
| 运维/部署视角 | 是否需要数据迁移、是否影响线上服务、回滚方案 | "需要停服吗？历史数据怎么处理？出问题了怎么回滚？" |
| 安全/合规视角 | 数据泄露风险、权限模型影响、审计需求 | "是否涉及敏感数据？是否需要审计日志？" |
输出格式：
## 需求理解
[复述需求，确认讨论的是同一件事]
## 多视角分析
### 产品经理视角
- 用户价值：...
- 使用场景：...
- 优先级建议：...
### 终端用户视角
- 操作路径：...
- 体验风险：...
### 开发实现视角
- 技术方案概述：...
- 复杂度评估：...
- 工期估算：...
### 其他视角（按需）
- ...
## 方案对比（如有多方案）
| 维度 | 方案 A | 方案 B |
|------|--------|--------|
| 用户价值 | ... | ... |
| 实现复杂度 | ... | ... |
| 工期 | ... | ... |
| 风险 | ... | ... |
## 建议
[给出推荐方案 + 理由]
## 待确认
[列出需要用户决定的关键分歧点]C. 决策型 → 利弊分析 + 建议
目标：帮用户看清"做/不做"或"A/B"的利弊，给出建议但不替用户决策。
分析框架：
对每个选项，从以下维度评估：
1. 收益（用户价值 / 效率提升 / 体验改善）
2. 成本（开发工期 / 维护成本 / 学习成本）
3. 风险（技术风险 / 业务风险 / 对既有功能的影响）
4. 机会成本（做了这个就不能做那个）
5. 可逆性（做了之后能不能反悔/回滚）输出格式：
## 决策分析
### 选项 A: [描述]
- 收益：...
- 成本：...
- 风险：...
- 可逆性：...
### 选项 B: [描述]
- 收益：...
- 成本：...
- 风险：...
- 可逆性：...
### 建议
推荐 [选项X]，因为 [理由]。但最终取决于 [关键决策因素]。D. 探索型 → 可行性评估
目标：评估技术可行性，给出"能做/不能做/有条件能做"的结论。
分析框架：
1. 技术可行性：现有技术栈能否支持？需要引入什么新依赖？
2. 性能可行性：数据量/响应时间/资源消耗是否可接受？
3. 成本可行性：开发工期 + 维护成本是否合理？
4. 约束条件：有哪些硬约束（如断网环境、硬件限制、兼容性）？
5. 替代方案：如果完全实现不可行，有没有降级/折中方案？输出格式：
## 可行性评估
### 结论：[可行 / 有条件可行 / 不可行]
### 技术评估
- 技术可行性：...
- 性能可行性：...
- 关键约束：...
### 实现路径（如可行）
- 方案概述：...
- 预估工期：...
- 主要风险：...
### 替代方案（如不可行或成本过高）
- 降级方案：...
- 折中方案：...E. 问题诊断型 → 定位 + 修复方案
目标：定位问题根因，提出修复方案，确认后再动手。
分析框架：
1. 现象确认：用户描述的症状具体是什么？能否复现？
2. 数据排查：当前数据库/日志中的实际数据是什么？
3. 代码追踪：哪些代码路径会产出这个现象？
4. 根因定位：代码逻辑 vs 业务规则 vs 数据状态，哪里不一致？
5. 修复方案：修代码？修数据？还是两者都修？
6. 影响评估：修复是否影响其他功能？F. 纠错型 → 纠错提问钩子（Error Diagnosis Hook）
目标：用户指出 Bug/UI 缺陷或 AI 发现自己前一轮实现有偏差时，用结构化的非技术提问快速定位根因模块。禁止逐像素检查所有元素的低效模式。
触发场景：
- 用户说"这个需要修复""这里有问题""XX功能不对"
- 用户描述现象 + 附带截图/录屏
- AI 在代码编写过程中发现理解偏差或实现错误（主动触发钩子与用户确认）
提问维度（只问这 4 个，禁止问技术细节）
| 维度 | 提问方向 | 示例 |
|---|---|---|
| 场景 | 用户在什么操作路径下遇到此问题？ | 点击顺序、页面流转、当时的数据状态 |
| 观感 | 视觉上哪里不对劲？ | 布局错位、颜色异常、动画卡顿、内容缺失 |
| 体验 | 交互行为是否违背预期？ | 按钮无响应、弹窗不关闭、输入被清空 |
| 对比 | 实际表现与预期表现的差异点？ | "本来应该显示 X，现在显示 Y" |
提问通过交互式选项提问工具（AskUserQuestion 或宿主 Agent 环境提供的等价交互式提问工具）提交，每问带选项与推荐项，遵循 Grilling 纪律。
推理逻辑：从感知层逆向映射到实现层
从用户回答的非技术问题中，逆向推导到具体模块，建立三层映射：
用户感知层（场景/观感/体验/对比）
↓
业务逻辑层（状态流转/事件链路/数据绑定）
↓
技术实现层（前端组件 / API 接口 / 数据库状态 / WebSocket 推送）每条用户确认的异常现象必须映射到至少一个候选模块，并在输出中注明推断依据。
截图策略
- 现有信息不足以定位时，引导用户补充截图，最多 3 张
- 引导话术必须明确："请截取[具体位置]最严重错误的画面"，禁止模糊表述如"再截个图看看"
- 补充截图前停止会话等待用户上传；补充后若能定位问题，立即停止追问，进入根因分析
执行约束
- 连续追问不超过 2 轮（补充截图不计入提问轮次，属于材料补充）
- 禁止问技术细节（如"是不是 XX API 返回了空值"）
- 禁止问环境细节（如"你用的是 Chrome 还是 Safari"），除非影响面极广
输出格式
## 问题复现路径
[根据用户描述还原操作步骤]
## 关键异常点
- [用户确认的异常现象]
## 推测根因模块
- [模块名]：[理由，基于用户描述的哪个特征推断]
## 待验证假设
- [1-2 个需要进一步确认的技术假设]与现有流程的衔接
- 纠错提问完成后 → 自动转入 E. 问题诊断型流程（Phase 1-2），跳过 A-E 类型识别阶段
- 根因确认后 → 无缝切换到 A. 实施型的多维度澄清
类型转换
需求可能在对话中转换类型：
- 探索型(D) 确认可行 → 转为方案讨论(B) → 确定方案 → 转为实施(A)
- 诊断型(E) 定位到根因 → 转为实施(A) 修复
- 方案讨论(B) 达成一致 → 转为实施(A)
- 纠错型(F) 钩子定位异常 → 跳过类型识别直接进诊断型(E) Phase 1-2 → 根因确认 → 转为实施(A)
每次转换时，重新执行对应类型的分析流程。
A 类实施型完整流程（Phase 1-4）
Phase 1: 代码库理解（内部执行，不输出给用户）
在提问之前，先搜索代码库获取以下上下文：
- 需求涉及的现有模块、文件、函数
- 相关的数据模型和 API 端点
- 相关的 UI 组件和交互流程
- 与既有功能的依赖关系和兼容性
Phase 2: 多维度分析
基于代码库理解，执行以下分析。只提出有歧义或信息缺失的维度的问题，无歧义的不提问。
A. 基础维度澄清（每次必检）
| 维度 | 分析要点 | 典型问题示例 |
|---|---|---|
| 功能边界 | 做什么、不做什么、覆盖范围 | "这个功能是否需要支持批量操作，还是只支持单条？" |
| 数据流 | 数据从哪来、到哪去、中间怎么转换 | "这个字段是从后端实时查询，还是前端缓存？" |
| 交互细节 | 用户操作路径、状态变化、反馈方式 | "点击后是直接生效，还是先弹确认框？" |
| 异常处理 | 错误场景、边界条件、降级策略 | "如果后端返回空数据，显示空状态还是隐藏整个区块？" |
| 前后端分工 | 逻辑在哪一侧、API 设计 | "这个计算是前端做还是后端做？需要新增 API 吗？" |
| 安全/权限 | 谁能用、谁能看、数据隔离 | "这个操作需要管理员权限还是普通用户即可？" |
| 性能约束 | 数据量级、响应时间、并发 | "这个列表最多多少条数据？需要分页吗？" |
| 既有兼容性 | 与现有功能的关系、是否复用 | "这个列表的展示样式是否复用现有的 XXX 组件？" |
| 状态管理 | 数据持久化、缓存、同步策略 | "这个配置是全局生效还是按用户独立？" |
| 视觉/UI | 布局、样式、响应式、暗色主题 | "这个弹窗是居中显示还是从右侧滑出？" |
B. MoSCoW 优先级分层（功能边界维度）
将需求拆解为功能点，按优先级分层确认：
| 层级 | 含义 | 提问模板 |
|---|---|---|
| Must | 没有就不能上线 | "以下哪些是必须有的？[列出功能点]" |
| Should | 重要但可以下一版 | "这些是否本次就要做，还是后续迭代？" |
| Could | 锦上添花 | "是否需要顺便加上 XXX？" |
| Won't | 明确不做 | "以下这些本次确认不做，对吗？" |
作用：防止范围蔓延（用户说"顺便加个"）或过度交付（AI 自作主张加了不该加的功能）。
C. FMEA 失效模式分析（异常处理维度）
对关键功能点，系统化穷举失效场景：
对每个关键操作，列出：
1. 可能出什么错？（网络超时/数据为空/并发冲突/权限不足/数据已删除）
2. 出错了影响多大？（用户无感知/功能降级/数据损坏/系统崩溃）
3. 怎么预防/降级？（重试/提示/回滚/兜底UI）提问模板："[操作X] 在以下场景应该怎么处理？[列出 3-5 个失效场景 + 建议方案]"
作用：比拍脑袋想异常场景更系统化，避免遗漏关键边界条件。
D. Impact Analysis 影响分析（既有兼容性维度）
评估变更对既有系统的连锁影响：
对每个变更点，检查：
1. 哪些现有 API/组件/数据表会被修改？
2. 修改后哪些既有功能可能受影响？
3. 是否需要数据迁移？历史数据怎么处理？
4. 是否需要向后兼容？（旧客户端/旧数据格式）
5. 是否需要 feature flag 灰度发布？提问模板："这个修改会影响以下既有功能：[列出]。这些功能是否需要同步调整？"
作用：防止"改了一个功能，坏了另一个功能"的连锁破坏。
E. Trade-off 权衡分析（存在多方案时）
当实现路径有多个选择时，多维度对比：
对比维度：
- 实现复杂度（开发时间）
- 运行时性能
- 可维护性（后续改动难度）
- 与既有架构的契合度
- 可扩展性（未来加功能的成本）提问模板："实现方案有 A/B 两种，对比如下：[表格]。推荐方案 X，因为 [原因]。你倾向哪个？"
作用：让用户参与架构决策，避免 AI 自作主张选了用户不想要的方案。
F. INVEST 验收标准（定义"做完"）
确保需求可验收：
| 标准 | 检查点 |
|---|---|
| Independent | 能否独立交付，不依赖其他未完成的功能？ |
| Negotiable | 是否有灵活空间，还是硬性要求？ |
| Valuable | 用户能感知到价值吗？验收标准是什么？ |
| Estimable | 工作量能估算吗？有无技术不确定性？ |
| Small | 能否在一个迭代内完成？需要拆分吗？ |
| Testable | 怎么验证做完了？自动化测试还是手动验证？ |
提问模板："做完后怎么验证？[列出验收检查项] 这些对吗？"
Phase 2 执行策略
不是每个需求都需要走完所有维度。按需求复杂度选择：
| 需求类型 | 必做维度 | 按需维度 |
|---|---|---|
| 简单修改（改文案/颜色/样式） | 跳过提问 | - |
| 单点功能（加个按钮/字段） | A 基础澄清 | F 验收标准 |
| 中等功能（新页面/新API） | A + B + F | C + D（涉及既有功能时） |
| 复杂功能（跨模块/架构变更） | A + B + C + D + F | E（存在多方案时） |
| Bug 修复 | A（定位 + 修复范围） | D（影响分析） |
Phase 3: 问题输出格式
分析结论（需求理解、MoSCoW、FMEA、Impact、INVEST）按下方格式输出；需要澄清的问题不再一次性平铺列出，而是按「提问执行引擎」的 frontier 分轮，通过交互式选项提问工具提交。
## 需求理解
[用 1-3 句话复述你对需求的理解，确认方向正确]
## 优先级分层 (MoSCoW)
- **Must**: [列出必须有]
- **Should**: [列出重要但可延后]
- **Won't**: [列出明确不做的]
## 需要澄清的问题
1. **[维度名]** 具体问题？（影响：XXX）
- A: 方案一
- B: 方案二
2. **[维度名]** 具体问题？
...
## 失效场景确认 (FMEA)
| 场景 | 影响 | 建议处理 |
|------|------|----------|
| ... | ... | ... |
## 影响分析 (Impact)
- 修改 XXX 会影响：[列出]
- 需要同步调整：[列出]
## 验收标准 (INVEST)
- [ ] 检查项 1
- [ ] 检查项 2
## 已确认无需澄清的维度
- [维度名]: [你的理解] (如有误请纠正)Phase 4: 分轮提问直到 frontier 清空
- 按「提问执行引擎」分轮提交问题，每轮答案回收后重算 frontier
- 如果回答中又引出新歧义，作为新分支挂入决策树，继续追问直到 frontier 为空
- frontier 清空后，简要总结确认理解，用户确认共识后才开始实施
提问执行引擎（Grilling 纪律）
所有类型（A-F）的提问环节统一按此纪律执行（源自 mattpocock/skills 的 grilling/batch-grill-me 协议，适配交互式选项提问工具）。
决策树与 frontier 分轮
- 把需求建模为决策树：每个决策下面挂着依赖它的后续决策。
- frontier = 前置决策已全部敲定、现在就能问的问题集合。每轮只问 frontier 内的问题；答案依赖本轮未决问题的，属于下一轮，禁止提前猜着问。
- 用户答完一轮，重算 frontier（已敲定的决策会解锁下游问题），进入下一轮，直到 frontier 为空——所有分支走完，没有任何默认假设未被确认。
工具适配（交互式选项提问工具）
- 每轮 frontier 问题必须通过交互式选项提问工具（AskUserQuestion 或等价工具）提交，一次最多 4 问；frontier 超过 4 个时按影响面大小排序分批，同轮内互不依赖。
- 每个问题给 2-4 个具体选项，推荐选项放第一位并标注 (Recommended)，选项描述里写清选择后果。
事实与决策分离
- 事实自己查：能从代码库、文件系统、运行环境查到的信息（现有组件、API 签名、数据结构、配置值、依赖版本），禁止拿去问用户，先查再问。查证与提问可并行：某问题依赖待查事实时，只有它的下游问题等待，其余 frontier 照常提问。
- 决策问用户：取舍、偏好、范围、优先级、验收口径属于用户，逐项提交等待答案，禁止代替用户默认。
共识门禁
- frontier 未清空、或用户未确认理解一致之前，禁止动手写代码。
- 不设问题数上限：问题多说明需求本身欠规格，砍问题数只是掩盖缺口。用户可随时喊停接受当前状态——喊停后已确认部分照确认执行，未确认部分按推荐答案执行并在最终汇报中显式标注。
提问质量要求
- 具体到实现层面：不问"你觉得怎么样"，要问"A 方案还是 B 方案"
- 基于代码库：引用现有代码/组件/API 来提问，如"是否复用现有的 XXX 组件"
- 提供选项：给出 2-4 个可选方案，推荐项放第一位标注 (Recommended)，降低用户思考成本
- 标注影响：说明每个问题影响什么，如"这决定了是否需要新增后端 API"
- 不重复：如果需求描述中已经回答了某个维度，不再提问
- 事实不问人：能自查的事实先查，只把决策交给用户
禁止
- 禁止跳过 Phase 1 直接提问（必须先理解代码库再问）
- 禁止问泛泛而谈的问题（如"有什么特殊要求吗"）
- 禁止在 frontier 清空、用户确认共识前就开始写代码
- 禁止把"没有歧义"的维度也列出来凑数
- 禁止把能自查的事实拿去问用户
- 禁止在同一轮里问存在依赖关系的问题（下游问题必须等上游答案）
- 禁止在纠错型钩子中问技术细节与环境细节（如 API 返回值、浏览器型号），提问维度仅限场景/观感/体验/对比
- 禁止在纠错型钩子中连续追问超过 2 轮