---
description: 需求变更：主 Agent 多轮追问直至澄清，子 Agent 仅更新变更目录内文档（07/01/02/03），禁止写业务代码；实现请用 /kb-revise-apply
argument-hint: "[变更目录] <修订说明>"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
在**同一变更目录**内处理「已实现或已定稿后，产品 PRD / 需求再次变更」；可重复执行以支持**多轮**变更。

**输入**：变更名称（**中文**，与现有目录 `<时间戳>-<中文名称>` 一致）+ 本轮变更说明（要点、链接或摘录均可）。

## 硬约束（必须遵守）

1. **需求澄清优先**：在把本轮变更写入 `07` / `01` / `02` / `03` 定稿前，主 Agent 必须通过**不断向用户提问**消除歧义；每轮问题控制在少量高价值项（边界、兼容、数据、验收），直到用户明确确认「**变更已澄清，可以落文档**」或你已列出「待确认项 = 无」且用户认可。
2. **本命令只改文档**：**禁止**创建或修改任何业务代码与工程配置（包括但不限于 `vkk_client_flutter/lib/`、`rust_server/src/`、`quasar/`、`doger_proto/`、各端 `pubspec`/`Cargo.toml`、迁移脚本等）。**仅允许**由子 Agent 读写当前变更目录下的 `knowledge/变更/进行中/<时间戳>-<中文名称>/`（及 `knowledge/变更/归档/` 下同名目录）内的 **`.md` 文档**。为澄清需求可对代码与知识库做**只读**查阅。
3. **不写代码**：文档中可描述实现思路，但**不得**在本命令会话内执行 `/kb-apply`、`/kb-revise-apply` 或手写补丁改仓库源码；澄清并由子 Agent 落盘后，由用户另开 **`/kb-revise-apply`**（或常规 `/kb-apply`）做实现。

## 其他约束

- 不新建第二个时间戳目录承载同一主题的微调（避免主线分裂）；**全新子项目**才走 `/kb-propose`。
- 产出：`07-prd-revisions.md`（按轮追加）；就地修订 `01-proposal.md`、`02-design.md`、`03-tasks.md`。
- 会话中打印**关键日志**：待澄清项数量 → 澄清完成 → 本轮 `Rev` 编号、写入路径、01/02/03 修订摘要各一行。

## 子 Agent 编排（必遵）

- **澄清阶段**：必须由主 Agent 与用户交互；子 Agent **不参与**代替澄清。
- **落盘阶段**（用户已确认「可落文档」后）：对「影响面核对 / 与现有 02 冲突扫描 / 03 任务草案」等**只读**工作，**并行**派发 `Task`（`generalPurpose` 只读模式），交付物为 Markdown 片段或表格；子 Agent 必须优先用 CodeGraph 核对现有实现和影响面。主 Agent 只审核和组织修订结构，实际写入 `07`/`01`/`02`/`03` 与 `00-manifest.json` 由子 Agent 执行，且仍**禁止**子 Agent 修改业务代码路径。

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## 执行步骤

### 1. 定位目录

按中文名称匹配 `knowledge/变更/进行中/` 或 `knowledge/变更/归档/` 下目录；多个匹配时用 AskUserQuestion 让用户选一个。
读取 `00-manifest.json`；若变更目录缺失该文件，先由子 Agent 补建，`flow` 写为 `"standard"`，并从现有 `03`/`07` 尽量回填状态。

### 2. 需求澄清循环（写入定稿前必做）

- 阅读现有 `01`、`02`、`03`、`07`（若有）与本轮用户说明，列出**歧义点 / 缺失信息**。
- 使用 **AskUserQuestion** 或分条追问；用户回答后更新「待确认清单」，直至全部关闭。
- **未澄清完成前**：不得把本轮记入 `07` 的定稿行，不得批量改写 `01/02/03`（最多可先口头归纳供用户核对）。
- 用户确认「可以落文档」后，进入步骤 3～6。

### 3. 并行核对（可选，`Task` + `generalPurpose` 只读模式）

在写入定稿前，可并行子 Agent 只做只读核对（例如：与 `02-design` 冲突点、与 `03` 已有任务 ID 重复检查），结果供主 Agent 审核并组织 `07` 与 `01/02/03` 修订；实际落盘另派子 Agent 执行。

涉及代码现状判断时，先用 `codegraph_explore`；涉及公共符号或接口影响时，用 `codegraph_impact`。CodeGraph 结果只用于澄清和文档修订，不允许在本命令中改业务代码。

### 4. 维护 `07-prd-revisions.md`

若不存在则由子 Agent 创建。在末尾**追加**一轮记录（表格或一节），在「澄清完成」后由子 Agent 写入，字段至少包括：

| 字段 | 说明 |
|------|------|
| 轮次编号 | `Rev1`、`Rev2`… 连续递增 |
| 日期 | `YYYY-MM-DD` |
| 变更摘要 | 一句话（澄清后的结论） |
| 动因/来源 | 如「PRD v3 第 2 节」 |
| 与上一版差异要点 | 短条列 |
| 影响范围 | 模块/端 |
| 关联 03 任务 | 新增任务 ID（建议 `T-Rev{n}-01`…），供 `/kb-revise-apply` 解析 |
| 实现状态 | **未开始**（由 `/kb-revise-apply` 完成后改为已完成） |

不在 `07` 中粘贴大段代码；实现细节归 `02`/`03`。

### 5. 滚动更新主文档（仅 .md）

- **`01-proposal.md`**：按澄清结果合并**业务 PRD** 正文；失效表述删除或改写（保持纯业务口径，不写技术实现）。
- **可选 — 同步外部 PRD**：用户确认落盘后，若 `manifest.external.prd_document_id` 存在、integration 已启用且用户要求同步对外文档，子 Agent 按 [kb-external-writeback.md](../skills/kb-workflow/references/kb-external-writeback.md) 覆盖写入同一在线文档（不新建文档）。
- **`02-design.md`**：方案差异、兼容与取舍。
- **`03-tasks.md`**：为本轮增加任务（ID 带轮次）；作废任务标 **已作废**（原因 + `Rev`）；**勿在本命令内勾选「已完成」代码任务**（实现由 `/kb-revise-apply` 负责后再勾）。
- **`00-manifest.json`**：追加 `revisions[]` 记录（`id`、`status: "pending"`、`task_ids`），并将新增任务写入 `tasks[]`。

若任务树需整体重排，提示用户再执行 `/kb-plan <中文名称>`（`/kb-plan` 同样应只改文档，不写业务代码）。

### 6. 收尾

- 打印关键日志。
- 明确提示下一步：**不得在本命令继续写代码**；实现请执行 **`/kb-revise-apply <中文名称>`**（仅跑本轮 `07` 关联任务）。`flow = standard` 下 revise-apply 全部通过后会**同会话强制** `/kb-review` → `/kb-test`（见 `kb-revise-apply.md`）；勿写成「按需再跑」。

## 与标准流程的关系

```
PRD 再变：/kb-revise（澄清 + 仅文档）→（可选 /kb-plan）→ /kb-revise-apply（代码）→ …
```

多次需求变更则重复上述链路。