---
description: KB 工作流总编排：识别意图、串联 /kb-* 阶段、派发子 Agent；归档时迁移→commit+push→可选外部 sync
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"`。

## 用户输入

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

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


理解用户隐含意图，自主选择与串联 `/kb-*` 流程，用 `subagent` 子 Agent 并行或分轮落盘。

**执行 Agent**：**kb-admin**（**默认** `subagent(agent=kb-admin)` 委派整段编排；细则见 [`agents/kb-admin.md`](../agents/kb-admin.md)）

**与 command / 工种的关系**：

- 本命令 = 用户入口；主 Agent 收到 `/kb-orchestrator` 后 **立即** `subagent(agent=kb-admin)` 委派整段编排。
- **inline（例外）**：仅当用户明确要求 inline 时，主 Agent inline 扮演 kb-admin（仍须 subagent 派工种）。
- 工种边界 SSOT：[`kb-agent-roles.md`](../skills/kb-workflow/references/kb-agent-roles.md)

## inline 调度口径（必遵）

- **inline** 仅指「不 spawn 嵌套 kb-admin 子会话」；**不等于**主 Agent 自己写盘、改代码、调外部 provider API。
- 无论 inline 还是 `subagent(agent=kb-admin)`，**所有**文件写入、代码实现、外部 sync 均须 `subagent` 派工种子 Agent。
- **派发前检查清单**：
  1. 本轮回是否有 Task 派工种计划；
  2. 主 Agent **不得**对业务代码、变更目录使用 Write / StrReplace 直接写盘；
  3. integrations 启用且缺 external 时须先派 **kb-release**；
  4. 输出须含「已派发 / 待派发」列表。

**输入**：自然语言目标，或变更目录路径，或「完成功能」等阶段指令。

## 子 Agent 编排（必遵）

- 主 Agent（orchestrator）：意图识别、阶段路由、审核闸门、失败重派与汇总。
- **外部登记与归档 sync 为可选**（由 `kb.project.json` → `integrations` 决定）；未启用时不得阻断 KB 主流程。
- 子 Agent 回报外部同步成功后，orchestrator 必须用 **shell** 复核 manifest 已落盘。

## subagent chain 口径（必遵）

- **design 与 plan 可同 chain**：`subagent(agent=kb-scribe)` 连续产出 `02-design.md` → `03-tasks.md` 允许。
- **禁止 design→plan→apply 三阶段同 chain**：`/kb-apply`（含 builder 并行组）**必须**独立 subagent/chain 派发，不得与 design/plan 串在同一次 `subagent` 或 Task 链内。
- **apply 独立派发**：`timeoutMs` 建议 **≥ 600000**（10 分钟）；多任务按 `03-tasks.md` 依赖图分批，**每批单独派发** builder/scribe，避免单 chain 过长被 harness 杀进程。
- **chain 失败（尤其 exit 143 / SIGTERM）**：主 Agent 回报须含 **exitCode**、**duration**、**acceptance 缺失项**；默认续跑 `/kb-apply` 或 `/kb-check` + `/kb-repair`，**不等用户追问**。
- **apply 中断且已有代码改动**：优先 `/kb-repair` 对齐 manifest 与 `03` 任务状态，或续跑 apply 完成未验收轮次；禁止当作「未开始」重跑已完成任务。

### kb-admin 多轮接力（必遵）

- **单轮 kb-admin** 只做「读 manifest → 派发**下一批**工种 → 回报已派发/待派发 → 结束」；**禁止**单 chain 内等待 apply→review→test→archive 全长完成。
- 「完成功能」由**主 Agent 多轮** kb-admin（或 inline 闸门）接力：builder/reviewer/recorder 完成后 → **新派** kb-admin 推进下一 stage。
- kb-admin 被 kill（exit 143 / ~5min）且**零工种派发**时：主 Agent **默认立即续派** kb-admin 或 inline 派发首批 builder，**不等用户追问**。
- Cursor SDK 子会话工具面见 [kb-cursor-sdk.md](../skills/kb-workflow/references/kb-cursor-sdk.md) §3.1。

### chain 失败摘要口径（必遵）

- Pi harness **stderr 噪声**（如 `figma-mcp-oauth-sync`、MCP 连接日志）**不得**当作 chain 失败根因摘要。
- 真实失败类型须按优先级归类：**Killed/timeout**（exit 143 等）、**Gate failed**（bootstrap/codegraph/manifest validate）、**Acceptance missing**（任务验收或 stage 未达标）。
- 解读 chain 结果时 **exitCode 优先于 stderr**；stderr 仅作辅助上下文，不得单独作为「apply 失败」结论。

## 标准主路径

```
propose → design → plan → apply → review → test → archive（含 commit+push + 可选 external sync）
```

轻量路径：`lite → archive（含 commit+push + 可选 external sync）`

PRD 多轮变更：`revise → [plan] → revise-apply → [review/test] → archive`

外部事件契约：[kb-external-sync.md](../skills/kb-workflow/references/kb-external-sync.md)

## 阶段推进口径（必遵）

- 标准流 `propose → design → plan → apply → review → test → archive`：阶段**成功完成后**须**同会话默认可串联下一跳**，禁止仅为礼貌确认用 `ask_question` / interview 问「下一步是否 design/plan/apply？」。
- **仅当**缺产品决策、存在冲突/风险需用户拍板、硬门禁失败、或用户明示暂停时，才 interview；其余阶段间隙不得拦停。
- 「完成功能」类指令按下文默认序列**直接推进**，阶段间隙不因「是否继续」拦停。

## 归档收尾闸门（必遵）

`/kb-archive` 的标准收尾顺序：**迁移目录 → commit+push → 可选步骤 10**。orchestrator 串联时规则如下：

**目录迁移硬约束**：子 Agent 归档时必须 `mv` 整目录；细则见 [kb-archive-migrate.md](../skills/kb-workflow/references/kb-archive-migrate.md)。

| 条件 | orchestrator 动作 |
|------|-------------------|
| integrations 未启用 | 步骤 10 **跳过** |
| `external.registry_record_id` 存在，且 `notified_events` **不含** `"completed"` | **必须**派发 kb-release：`sync.archive_completed` |
| `notified_events` 已含 `"completed"` | 跳过，报告注明已同步 |
| 无 `external` 但 `01` 含任务记录链接 | 先补写 `manifest.external`，再 sync |
| 用户明确「跳过外部同步」 | 可省略；报告注明 |

**子 Agent archive sync prompt 必含**：

1. shell 读磁盘 `00-manifest.json` 的 `external`。
2. 确认步骤 9 commit+push 已成功。
3. `node "${PI_KB_ROOT}/scripts/kb-external-sync.mjs" --event sync.archive_completed --scan-id <14位前缀>`
4. 同轮写回 `external.notified_events` 追加 `"completed"`。

## 外部登记闸门（integrations 启用时）

| 时机 | orchestrator 动作 |
|------|-------------------|
| 新建 lite / propose | 实现前**可**派发 kb-release 外部登记（`registry.propose` + `notify.propose_created`） |
| 磁盘已有 `registry_record_id` | **禁止**重复登记/发 created |
| integrations 未启用 | **不得**阻断 design/apply/archive |

## 意图 → 命令路由

| 用户意图 | 命令 |
|----------|------|
| 同步知识库 | `/kb-sync` |
| **新功能 / 改动（默认）** | **`/kb-lite`**（见下方默认分流） |
| 完整 PRD / 已确认标准流 | `/kb-propose` |
| 设计 | `/kb-design` |
| 任务拆解 | `/kb-plan` |
| 实现 | `/kb-apply` |
| 评审 | `/kb-review` |
| 执行验收（尝试跑命令并写 06） | `/kb-test` |
| 归档 | `/kb-archive` |
| 单独提交 | `/kb-commit` |
| 状态修复 | `/kb-repair` |
| 会话失败经验 / 流程复盘 / 自动反馈改进 | `/kb-session-retro` |
| 单条流程吐槽 | `/kb-feedback` |
| 开启/关闭 EvoMap 网络进化 | `/kb-evomap-setup` |
| DeepSeek Search 配置引导 | `/kb-deepseek-search-setup` |
| Cursor Agent 配置引导 | `/kb-cursor-setup` |
| Figma Remote MCP 配置引导 | `/kb-figma-setup` |

### 新建默认分流（必遵）

- **默认 `/kb-lite`**：文案、样式、局部 bug、单端小改、无需正式 PRD。
- **升 `/kb-propose`**：用户明示完整 PRD/标准流；或命中 lite 升级表（契约 / DDL / 资金 / 权限 / 事务；或量化分 ≥3）。细则 `kb-lite.md`。
- 机器探测：`node "$PI_KB_ROOT/scripts/kb-stage-next.mjs" --intent new`（强制标准加 `--force-standard`）。

## stage 状态机（机器 SSOT）

已有变更目录时，**禁止**仅凭对话记忆猜下一跳。派发前：

```bash
node "$PI_KB_ROOT/scripts/kb-stage-next.mjs" --change-dir "<变更目录>"
```

以 JSON `next.*` 为准（含 `independentChain` / `timeoutMsHint` / 可选 `shell` audit）。`blocked` 时先 check/repair。脚本覆盖 `applied`→audit→`applied_audited`→review→test→archive 与 lite 短路径。

## 「完成功能」类指令的默认序列

1. **先** `kb-stage-next.mjs` 判定 `stage` / `flow` / `next`（勿手推阶段表）。
2. integrations 启用且缺 `registry_record_id` → 可先补外部登记。
3. **`flow = lite`**：按状态机走轻量短路径（实现 → 必要时补知识 → `/kb-archive`）；**豁免**强制 `04` 与强制执行测试（4A）。
4. **`flow = standard`**：严格按状态机 `next.command` 多轮接力（design/plan 可同 chain；**apply 必须独立 chain**；applied 后先 audit 再 review→test→archive）。
5. `/kb-archive` 必须包含步骤 9 commit+push 与可选步骤 10 external sync。

**多轮接力（与 kb-admin 单轮边界配合）**：上述序列是**跨多轮** kb-admin + 工种 chain 的总目标，**不是**单次 kb-admin subagent 内阻塞跑完。每轮只派发状态机给出的**一批**工种，回报后主 Agent 再续派。

## 输出结构

1. **判定**：意图 + 当前 stage + 待跑命令序列。
2. **外部同步状态**：external、notified_events、commit+push、本轮回是否步骤 10。
3. **已派发/待派发**：子 Agent 任务列表。
4. **风险或缺口**。

## 注意事项

- `/kb-test` 默认尝试执行用户/`03`/`auto_test` 命令，同批内 **ui>contract>unit**；允许 `auto_test/` 补 Playwright/契约，禁 unit 脚手架；失败不得标 `tested`。
- 不默认全量 `flutter analyze` / 部署；有定向验收命令时须实际跑。
- 未归属 git 改动在 `/kb-commit` 前停止并让用户确认。
- 权威规范：`skills/kb-workflow/SKILL.md`；外部契约：`skills/kb-workflow/references/kb-external-sync.md`、`kb-external-writeback.md`。