---
description: 修复 KB 流程中断或漂移后的 manifest、summary 与清单状态，不修改业务逻辑
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"`。

## 用户输入

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

---
用于 `apply` / `review` / `archive` / `commit` 中断后，修复 KB 元数据漂移。它只处理状态与清单，不补业务代码、不补真实知识库正文。

**输入**: 变更名称（必须为中文，对应 `knowledge/变更/进行中/` 或 `knowledge/变更/归档/` 下目录）。

## 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-check <中文名称>` 的只读口径确认漂移类型。
- **只修元数据**：允许修改 `00-manifest.json`、`05-summary.md` 的清单/勾选/归档说明、必要时修正变更目录位置说明。
- **禁止修业务逻辑**：不得修改 `vkk_client_flutter/`、`rust_server/`、`quasar/`、`doger_proto/` 等业务代码或协议文件。
- **禁止冒充完成**：若发现实现缺失、评审 open 未闭环、知识库正文未更新，停止 repair，回到 `/kb-apply`、`/kb-review` 或 `/kb-archive`。
- **同轮同步**：manifest 状态、`manifest.files`、Markdown 摘要必须同轮同步；修完后输出差异摘要。

## 可修复范围

| 漂移类型 | 可否 repair | 处理方式 |
|---|---|---|
| `manifest.files` 缺少已存在的 `00`～`07` 变更文档 | 可以 | 补入 `kind = "change_doc"` |
| `05-summary.md` 已列文件但 manifest 未列 | 可以 | 按实际文件补入 `manifest.files` |
| manifest 阶段与归档位置不一致 | 可以 | 以实际目录位置和评审闭环状态修正阶段 |
| 两级索引被归档目录变化误触发 | 可以 | 在 `05-summary.md` 写明无需更新原因 |
| 业务域子目录 index 已更新但 manifest 或 summary 漏列 | 可以 | 补齐 `manifest.files` 与「知识库更新清单」 |
| 工程平台分区 index 已更新但 manifest 或 summary 漏列 | 可以 | 补齐 `manifest.files` 与「知识库更新清单」 |
| 归档后 `进行中/` 与 `归档/` 同时存在（半迁移/copy） | 可以 | 按 kb-archive-migrate 判定 canonical，删除重复侧；必要时 `mv` 合并 |
| git 暂存了白名单外文件 | 不直接修 | 停止并要求用户确认；不得擅自重置 |
| 业务代码未实现或知识库正文缺失 | 不可 repair | 回到对应流程补齐 |

## 执行步骤

### 1. 定位变更目录

只读查找在途和归档目录。若**同时**存在同名前缀目录，先按 [kb-archive-migrate.md §半迁移修复](../skills/kb-workflow/references/kb-archive-migrate.md) 判定 canonical 侧：

- `stage = acceptance_reopened` 且进行中文档齐全 → canonical 为 **进行中**，删除 `归档/`  stale 副本
- `stage = archived` 且归档文档齐全、进行中仅 stub → canonical 为 **归档**，删除 `进行中/` stub
- 两侧均完整且 stage/内容冲突 → 停止并输出差异摘要，要求维护者确认后再修

修复后必须 shell 执行迁移门禁（`test ! -d` 源侧 + `test -d` 目标侧），写入修复报告。

### 2. 读取状态与清单

读取：
- `00-manifest.json`
- `05-summary.md`
- 现有 `01`～`07` 文件列表
- 所属领域/平台 `index.md` 与必要时的 `knowledge/index.md` 中相关 wikilink
- 若涉及业务域子目录，读取 `knowledge/业务域/<领域>/<中文子目录>/index.md` 与领域 index 的入口 wikilink
- 若涉及工程平台分区，读取 `knowledge/工程平台/<中文平台分区>/index.md` 与平台根 index 的入口 wikilink
- git 候选文件列表

### 3. 判定是否允许修复

仅当问题属于状态、清单、勾选、归档位置说明漂移时继续。任一真实实现或知识正文缺失，输出阻断项并停止。

### 4. 修复 manifest

可修复字段：
- `stage`
- `files[]`
- `updated_at`
- `archived_at`
- `tasks[]` / `reviews[]` / `revisions[]` 中已能由现有 Markdown 明确证明的状态

不得把无法证明完成的任务写成 `done`，不得把未闭环评审写成 `fixed`。

### 5. 修复 summary

可补齐：
- 「实际变更」文件列表
- 「知识库更新清单」
- 两级索引无需更新原因
- `archived_with_debt` 对应债务说明

不得新增需求、设计、实现说明来掩盖缺失流程。

### 6. 输出报告

```markdown
## KB 修复报告

| 项目 | 内容 |
|---|---|
| 变更名称 | <中文名称> |
| 修复范围 | manifest / summary / 清单 |
| 未修复阻断 | 无 / <阻断项> |

## 已修复
- <条目>

## 仍需处理
- <没有则写“无”>
```

## 退出口径

- 修复后若仍有阻断项，不进入 archive 或 commit。
- 修复只代表元数据一致，不代表业务验证通过。
- 下一步通常是重新运行 `/kb-check <中文名称>`，但不默认执行任何验证命令。