---
description: 业务 PRD 澄清与落盘，external 可选；01-proposal 为产品需求正文；技术设计见 /kb-design
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**（`01-proposal.md`），完成本地闸门（Figma 确认、类型与优先级），并按需调用外部同步（登记 + 通知）。

**执行 Agent**：**kb-scribe**（+ **kb-release** 当启用外部 integrations 时；工种见 [kb-agent-roles.md](../skills/kb-workflow/references/kb-agent-roles.md)）

**写 PRD / 需求文档 / 外部登记** 均使用本命令，**不要**使用已废弃的 `/prd-creator` 或 `（已废弃）`（请读下方参考文件）。

**输入**：变更名称（**必须为中文**）+ 需求描述（产品/功能需求或 Bug）。

**详细规则（执行前必读）**：

- [kb-external-sync.md](../skills/kb-workflow/references/kb-external-sync.md) — 事件目录、dispatcher 用法、`integrations` 判定与 SKIP 口径
- [kb-external-writeback.md](../skills/kb-workflow/references/kb-external-writeback.md) — `manifest.external` 幂等字段、回写与复核

**变更目录时间前缀（必遵）**：[`skills/kb-workflow/references/kb-change-directory-id.md`](../skills/kb-workflow/references/kb-change-directory-id.md) — 须用 shell 取 `Asia/Shanghai` 的 14 位 `YYYYMMDDHHMMSS`，禁止脑填占位时间。

## 可选外部同步（registry / notifications）

**统一入口**（子 Agent 调用，禁止在命令正文硬编码 provider 脚本路径）：

```bash
node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event registry.propose --scan-id <14位前缀>
node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event notify.propose_created --scan-id <14位前缀>
```

| 项 | 要求 |
|----|------|
| 配置来源 | 业务仓 `kb.project.json` 的 `integrations.registry` / `integrations.notifications` |
| 未配置或未启用 | dispatcher **退出码 0**、stdout 含 `SKIP`；**不阻断** design/plan/apply 等主流程 |
| 已启用 registry | PRD 本地确认 + 本地闸门通过后调 `registry.propose`；细则见 kb-external-writeback.md |
| 已启用 notifications | 登记成功后调 `notify.propose_created`（或 provider 内聚在 register 流程中） |
| 幂等 | 以 manifest 为准；细则见 kb-external-writeback.md |

## 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)"`

## 约束

- 变更目录：`knowledge/变更/进行中/<YYYYMMDDHHMMSS>-<中文名称>/`（`<YYYYMMDDHHMMSS>` 由子 Agent 执行 `TZ=Asia/Shanghai date +%Y%m%d%H%M%S` 得到，见上文引用）
- 禁止 kebab-case、camelCase 或英文作变更名称
- **本阶段禁止**：CodeGraph、编写 `02-design.md`、修改各端业务源码；PRD 正文禁止技术实现描述

## 子 Agent 编排（必遵）

- 读知识库、撰写/修订 `01-proposal.md`、外部同步、更新 `00-manifest.json` 由子 Agent 执行。
- 主 Agent：澄清、审核 PRD、推动**本地**阶段闸门；**阶段 4 成功后先自动判定是否需要 Figma 设计图：明确不需要则自动落盘并继续，判为需要/不确定时才向用户确认并等待答复**，再确认类型/优先级；**不**直接写文件、**不**直接调用 provider API。
- 外部同步前须 shell 读 `kb.project.json` 判定是否启用；未启用则跳过并注明 SKIP。

## 外部登记幂等（已启用 integration 时必遵）

外部同步开始前，**必须先读磁盘**上的 `00-manifest.json`（用 shell `cat`/`python -c json.load`，**不得**仅凭 IDE Read 缓存判断）：

| 条件 | 动作 |
|------|------|
| `external.registry_record_id` 已存在 | **跳过** `registry.propose`；向用户汇报已有登记链接 |
| `external.prd_doc_url` 存在但无登记记录 ID | 若 `figma_confirmed` 未为 `true`，**先补跑 Figma 闸门**；落盘后再调 `registry.propose`；**禁止**重复创建在线文档 |
| `external.notified_events` 含 `"created"` | **禁止**再次调 `notify.propose_created` |
| 子 Agent 回报成功但 manifest 无 `external` | 先用 shell 复核磁盘；仍缺失时才**重派同一子 Agent 补写 manifest**，**禁止**主 Agent 自行重跑全流程 |

**禁止**：子 Agent 已成功完成外部登记后，主 Agent 因「Read 工具看不到 external」而再次登记或重复通知。

## 执行步骤

### 1. 确认变更名称并创建目录

**时间前缀（子 Agent 必做，创建目录前；防「2 份相同内容变更 ID」）**：

0. **单一执行者，串行创建**：目录创建只派发**一个**子 Agent；主 Agent **禁止**为同一中文议题并行或重复派发「创建目录」子任务，已收到 `KB_DIR` 回报后不得再派发创建任务。
1. **原子「查重 → 创建 → 唯一性自检」**：在**同一段 shell** 内一次性完成，命中同名目录即复用、不新建；查重**含 tombstone**（细则见 [kb-change-directory-id.md](../skills/kb-workflow/references/kb-change-directory-id.md)、[kb-archive-purge.md](../skills/kb-workflow/references/kb-archive-purge.md)）：

```bash
NAME="<中文名称>"
EXIST="$(ls -d knowledge/变更/进行中/*-"$NAME" knowledge/变更/归档/*-"$NAME" 2>/dev/null | head -n1)"
if [ -n "$EXIST" ]; then
  KB_DIR="$EXIST"; echo "已存在同名目录，复用：$KB_DIR"   # 继续走 /kb-revise，禁止新建
else
  KB_CHANGE_ID="$(TZ=Asia/Shanghai date +%Y%m%d%H%M%S)"
  KB_DIR="knowledge/变更/进行中/${KB_CHANGE_ID}-${NAME}"; mkdir -p "$KB_DIR"
fi
CNT="$(ls -d knowledge/变更/进行中/*-"$NAME" knowledge/变更/归档/*-"$NAME" 2>/dev/null | wc -l)"
[ "$CNT" -eq 1 ] || echo "❌ 同名目录 $CNT 个，停止：先清理重复仅留一个再推进"
```

2. 若唯一性自检输出 `❌`（同名目录 > 1），**立即停止**，报告重复目录清单并请用户确认保留哪一个，清理后再推进；禁止带着重复目录继续后续步骤。
3. 向主 Agent 回报**实际** `KB_DIR`（复用/新建）与唯一性自检结果；`01` 头部变更 ID 与目录 basename 一致。

初始化 `00-manifest.json`：`flow=standard`，`stage=proposed`，`source=kb-propose`；`updated_at` 与步骤 2 同轮 `TZ=Asia/Shanghai date +%Y-%m-%dT%H:%M:%S%z`。创建前读取**当前流程版本**（shell 解析，口径见 [kb-workflow-version.md](../skills/kb-workflow/references/kb-workflow-version.md)），写入 `workflow_version` 字段。

### 2. 阶段 1～3：知识库、需求澄清、方案检查

未澄清不得写完整 PRD。

若需求依赖**公开**行业模式/竞品能力/外部产品约束：子 Agent（**kb-scribe**）可用 `web_search` 补充，单独成「外部参考」小节并带 Sources，**不得**写成已定产品需求；无工具则引导 `/kb-deepseek-search-setup`。细则：[kb-deepseek-search.md](../skills/kb-workflow/references/kb-deepseek-search.md)。本阶段仍**禁止** CodeGraph。

### 3. 阶段 4：写入并确认 `01-proposal.md`（本地 PRD 落盘，必做）

写入后**直接打开** `01-proposal.md`（通过编辑器命令，如 shell 执行 `cursor "<绝对路径>"`），**不再**在对话中输出相对/绝对路径文本，再询问是否需要修改。

**修订对照（必遵，便于查阅）**：用户在确认 PRD 过程中提出修改意见、且本轮按意见改动后，重新呈现 PRD 时**必须先给出「本轮修改对照」**，逐条标注与**上一份**文档的不同之处（章节定位 + `原：… → 改：…`，或新增/删除标注），让用户一眼看清改了哪里再确认；对照清单只放在对话回复里，**不写入** `01-proposal.md` 正文（正文保持纯业务，不留 diff 痕迹）。每轮修改都重复此对照，直到用户确认无误。

```markdown
---
type: ChangeProposal
title: <产品/功能名称>
description: <一句话需求摘要>
timestamp: <ISO8601>
---

# <产品/功能名称>产品需求文档

> **变更 ID**：`<YYYYMMDDHHMMSS>-<中文名称>`
> **来源**：kb-propose
> **类型**：需求 / Bug（类型优先级确认后补全）
> **优先级**：（类型优先级确认后补全）
> **外部 PRD**：（外部登记成功后补全，无 integration 时写「无」）
> **Figma 设计图**：（Figma 闸门后补全，无则写「无」）
> **任务记录**：（外部登记成功后补全，无 integration 时写「无」）

<!-- 纯业务正文 -->

## 验收标准
```

### 4. 阶段 5：Figma 设计图地址判定与确认（**本地闸门**）

**前置**：`01-proposal.md` 已确认；`external.figma_confirmed` 不为 `true`。

**主 Agent 职责（不可由子 Agent 代问代答）**：PRD 确认后，**先基于 PRD 正文自动判定本次变更是否涉及界面/视觉**：

- **明确不需要设计图**（纯后端逻辑、数据修复、权限/配置/接口口径、与既有界面无视觉差异的纯文案、埋点/性能等不可见变更）：**不询问用户**，子 Agent 同轮写入 `01` 头部「Figma 设计图」=「无」、`external.figma_confirmed: true`、`external.figma_decision: "auto-none"`，并在总结里一句话说明已自动判定无需设计图。
- **需要 / 无法确定**（新增页面/弹窗/组件、视觉改版、布局样式调整、UI 展示变化等）：**必须立即**用下列话术询问并**停止推进**，直到用户明确回复：

```markdown
本地需求文档已确认。

本次涉及界面/视觉，请确认是否有 Figma 设计图地址需要关联？如果有，请直接发 Figma 链接；如果没有，请回复「没有」。
```

**询问分支处理规则**：

| 用户回复 | 动作 |
|--------|------|
| 提供 Figma 链接 | 子 Agent 写入 `external.figma_url`，`01` 头部「Figma 设计图」填链接 |
| 明确回复没有/暂无/不需要 | 不写 `figma_url`，`01` 头部写「无」 |
| 含糊 | 追问一次，仍不得进入下一阶段 |

无论自动判定还是用户答复，子 Agent **同轮**写入 `external.figma_confirmed: true`（询问分支可附 `figma_decision: "user-confirmed"`）。**未写入 `figma_confirmed` 前禁止进入类型优先级确认与外部登记。**

若后续阶段需**读取** Figma 帧/组件细节：经已 bundled 的 `pi-figma-remote-auth` + `pi-mcp-adapter`（`/figma-remote-auth`）；未登录则引导 `/kb-figma-setup`，见 [kb-figma-remote.md](../skills/kb-workflow/references/kb-figma-remote.md)。产品闸门本身不依赖 MCP。

### 5. 阶段 6：类型与优先级（**本地闸门**）

**前置**：`external.figma_confirmed === true`（阶段 5 已关闭）。

**只在登记前一次性确认**：给出初始判断后，用户确认或一次性调整即定稿，**不就优先级反复追问、不二次确认**；仅当用户主动要求再改才更新。用户确认后写入 `external.task_type`、`external.priority`。确认前**不得**调外部登记或发通知。

### 6. 阶段 7：自动提交并推送（类型优先级确认后）

类型与优先级确认后，由子 Agent **自动**按 `/kb-commit` 白名单口径暂存本次变更目录文件（`00-manifest.json`、`01-proposal.md` 等），提交并默认 `git push`；**禁止**全量 `git add`，未归属改动不纳入。仅用户明确要求「不推送」时跳过。

### 7. 阶段 8：外部登记（可选，`registry.propose`）

**前置**：`external.figma_confirmed === true`；`external.task_type` 与 `external.priority` 已写入；本地 PRD 已 push。

1. shell 读 `kb.project.json`：未启用 `integrations.registry` → **跳过**，报告注明 SKIP，进入下一步 `/kb-design`。
2. 已通过「外部登记幂等」检查；登记记录 ID 不存在时才调 dispatcher。
3. 子 Agent 执行：

```bash
node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event registry.propose --scan-id <14位前缀>
```

4. 成功后按 kb-external-writeback.md 复核 manifest 回写（含 `prd_doc_url`、登记记录 ID、`01` 头部「外部 PRD」「任务记录」）。
5. dispatcher 失败且 integration 已启用：报告失败原因；**不阻断**用户自行决定是否继续 `/kb-design`（除非团队规范要求登记成功才推进）。

### 8. 阶段 9：创建通知（可选，`notify.propose_created`）

**前置**：`integrations.notifications` 已启用；`registry.propose` 已成功或登记记录 ID 已存在；且 `notified_events` 不含 `"created"`。

```bash
node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event notify.propose_created --scan-id <14位前缀>
```

- `notified_events: ["created"]` 仅一次；细则见 kb-external-writeback.md。
- 通知成功后，对 manifest 与 `01` 头部外部字段改动，做一次轻量补提交并推送（`00-manifest.json`、`01-proposal.md`）。

### 9. 输出总结

- 已直接打开 `01-proposal.md`（不再输出路径文本）
- 本地闸门：Figma / 类型 / 优先级
- 外部同步：`registry.propose` / `notify.propose_created` 结果或 SKIP
- 自动提交并推送结果（提交信息、分支）
- 下一步：**`/kb-design <中文名称>`**