---
description: 只读校验 KB 变更状态、知识库更新清单、OKF 两级 index 与提交白名单，不修改文件。
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"`。

## 用户输入

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

---
对指定 KB 变更执行**只读一致性校验**。本命令不修复问题、不写入文件，只输出阻断项和建议下一步。

**输入**：可选。指定中文变更名称时校验该变更目录；不指定时校验所有在途变更、两级 index 与 OKF 合规。

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

## CodeGraph 门禁（警告级）

本命令可做 CodeGraph 只读核对，但**不硬阻断**。建议先跑机器门禁；失败或 MCP 不可用时**只记警告**，继续其余校验。执行：

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

门禁通过后，再确认 MCP 工具 `codegraph_*`（至少能调用 `codegraph_explore`（或 `codegraph_status`））可用。若工具不可用：记警告，不阻断；指引用户从插件示例复制项目级 MCP 配置：

按 [kb-codegraph.md](../skills/kb-workflow/references/kb-codegraph.md) §一，从 `${PI_KB_ROOT}/bootstrap/examples/mcp/` **只写当前宿主**对应文件（Claude/其他 → 根 `.mcp.json`；Cursor → `.cursor/mcp.json`；禁止无脑双写），配置后 Reload / 重启会话，再重试核对。

## 约束

- **只读**：禁止修改 `00-manifest.json`、Markdown、业务代码、索引或 git 状态。
- **不执行重验证**：不主动运行 `flutter analyze`、`dart analyze`、`cargo check`、部署、迁移 SQL 或测试命令。
- **优先机器状态**：`00-manifest.json` 用于阶段和任务状态判定；Markdown 用于说明。
- **manifest schema 校验（阻断）**：对变更目录 `00-manifest.json` **须先**执行机器校验（与下方字段检查互补；schema 失败即阻断）：

```bash
node "${PI_KB_ROOT}/scripts/kb-manifest-validate.mjs" --target "$(pwd)"
# 或单文件：
node "${PI_KB_ROOT}/scripts/kb-manifest-validate.mjs" --file <变更目录>/00-manifest.json
```

- **先查局部 index**：新增、删除、重命名知识文件时，先检查所属领域/领域子目录/平台/工程平台分区 `index.md`；只有总入口变化或总索引引用失效才要求总索引更新。
- **CodeGraph 只读核对**：见上文「CodeGraph 门禁（警告级）」；涉及代码文件的变更，用 `codegraph_explore` / `codegraph_impact` 抽样核对知识库更新范围；索引或 MCP 不可用只记警告，不自动修改文件。
- **OKF 与图谱**：合规细则见 [kb-okf.md](../skills/kb-workflow/references/kb-okf.md)；内部链接、关系字段与孤儿规则见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)。可用脚本复述结果（仍只读，含图谱检查）：

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


## 校验项

### 1. 变更目录与 manifest

- **schema**：`kb-manifest-validate.mjs` 须 exit 0（见上文「manifest schema 校验」）；失败为阻断。
- 目录名是否为 `<YYYYMMDDHHMMSS>-<中文名称>`（前缀须为 14 位数字 `^[0-9]{14}-`，非占位整点或 8 位日期）。
- `00-manifest.json` 是否包含 `name`、`flow`、`stage`、`tasks`、`reviews`、`revisions`、`files`、`updated_at`。
- `files[].path` 是否为仓库根目录相对路径，且所列文件存在；`status = removed` 必须能从 Markdown 或 diff 证明删除意图。
- `files[].kind` 是否能区分 `code`、`knowledge`、`change_doc`、`index`、`config` 或 `other`。

### 2. 任务与评审闭环

适用于拟归档或 `stage` 接近 archive（含 `tested` / `reviewed` 且用户意图归档）时的门禁；与 `/kb-archive` 2B/4A 口径一致。

- **`reviews[].status = "open"` → 阻断**：不得归档为完成（不论 `flow`）。
- **`accepted_debt` 只能归档为 `archived_with_debt`**（写成普通 `archived` → 阻断）。
- **`flow = standard`**：缺少 `04-review.md` → **阻断**（归档前必须有评审产物）。
- **`flow = lite`**：**豁免**缺 `04-review.md`（不因无 04 阻断）。
- **不因缺少 `06-automation-test.md` 阻断**（archive 不强制 06）。
- 评审修复应能追溯到任务 ID 或修复文件。
- **警告（可选）**：存在可执行验收约定（用户明示命令 / `03` 定向命令 / `auto_test/` 入口），且 `stage = tested`，但 `06-automation-test.md` 无执行记录行 → 警告「tested 缺执行证据」，建议补跑 `/kb-test`；**勿过度**（无可执行约定时不因缺 06 报警）。

### 3. 知识库更新清单

- `02-design.md` 的「必须更新」清单在归档前必须出现在 `05-summary.md`。
- 已声明更新的知识文件必须存在，且路径落在 `knowledge/知识地图.md`、`knowledge/业务域/**`、`knowledge/工程平台/**`。
- 声明“不需要更新”时必须有一句原因。
- `05-summary.md` 的「知识库更新清单」必须覆盖 `manifest.files` 中的 `knowledge|index` 文件。
- 若 `manifest.files` 包含接口、服务、公共类型、组件或数据结构变更，使用 CodeGraph 抽样判断影响面是否需要补充知识库文件；无法判断时列为警告，建议 `/kb-sync <范围>`。

### 3.1 design 文档完整性（`stage >= designed` 且 `flow = standard`）

**警告级**，不阻断 archive，但建议在 `/kb-plan` 前修复：

- `02-design.md` 是否存在 `## 1、业务流程与改动范围` 章节（兼容旧版 `## 一、业务流程与改动范围` 或 `## 业务流程与改动范围`）
- 是否含至少一个 ` ```mermaid ` 代码块（业务流程图，非仅可选分层图）
- 是否存在含「改动」列的「流程步骤与改动对照」表（位于 `### 1.2` 或旧版 `### （二）` 等价表头）

缺失任一项时，报告警告并建议运行 `/kb-design <中文名称>` 补全。

### 3.2 知识文档阿拉伯数字编号（`stage >= designed` 且 `flow = standard`）

**警告级**（过渡期不阻断）；新产出应满足 [`knowledge/AGENTS.md`](../../knowledge/AGENTS.md)「7」第 3 条；变更目录 `04`/`05`/`06` 另见同文件「8」～「10」：

- `02-design.md` 大段标题应匹配 `^## [0-9]+、`；若仍含 `^## [一二三四五六七八九十]+、` 或段内 `^### （[一二三四五六七八九十]+）`，列为**编号口径漂移警告**
- `03-tasks.md`（`stage >= planned`）文件级大段应匹配 `^## [12]、`；执行计划段内应匹配 `^### 1\.[12]`；若仍用中文「一、执行计划」「（一）依赖图」，列为**编号口径漂移警告**
- `04-review.md`（`stage >= reviewed` 或文件存在）：大段应匹配 `^## [1-9]、`；若仍用语义大段（如 `^## 审查范围`、`^## 设计偏差`）或中文序号，列为**编号口径漂移警告**
- `05-summary.md`（`stage >= archived` 或文件存在）：大段应匹配 `^## [1-4]、`；若仍用语义大段（如 `^## 实际变更`、`^## 知识库影响清单`），列为**编号口径漂移警告**
- `06-automation-test.md`（`stage >= tested` 或文件存在）：大段应匹配 `^## [1-7]、`；若仍用中文序号大段（如 `^## [一二三四五六七八九十]+、`），列为**编号口径漂移警告**
- 存量业务/工程平台 knowledge 文件仍用中文编号时仅记警告，建议随 `/kb-sync` 或触达编辑时逐步迁移；**已归档**变更目录 `04`/`05`/`06` 不强制返工，仅对新产出发警告

### 4. 两级 index 覆盖（OKF）

- 业务域叶子文件新增、删除、重命名时，所属 `knowledge/业务域/<领域>/index.md` 必须同步覆盖或移除引用。
- 业务域子目录内叶子文件新增、删除、重命名时，`knowledge/业务域/<领域>/<中文子目录>/index.md` 必须同步覆盖或移除引用；若子目录入口新增、删除、重命名，所属领域 index 必须同步。
- 领域 index 只列领域根总览文件和子目录入口，不应继续堆叠子目录叶子文件；否则报告为领域索引膨胀风险。
- 工程平台根目录除 `index.md` / `log.md` 外不得保留平台叶子文件；若发现根目录叶子文件，报告为结构阻断，建议迁入 `knowledge/工程平台/<中文平台分区>/`。
- 工程平台分区内叶子文件新增、删除、重命名时，`knowledge/工程平台/<中文平台分区>/index.md` 必须同步覆盖或移除引用；若分区入口新增、删除、重命名，`knowledge/工程平台/index.md` 必须同步。
- 领域/平台/分区 index 中 wikilink 目标必须存在。
- 平台根 index 只列分区入口，不应继续堆叠分区叶子文件；否则报告为平台索引膨胀风险。
- 只有新增、删除、重命名领域 index、工程平台 index、知识地图入口，或总索引引用失效/摘要失真时，才要求更新 `knowledge/index.md`。
- `knowledge/index.md` 不得展开全部叶子知识文件、业务域子目录 index 或工程平台分区叶子；列表须为 `* [[wikilink]] - description`；如列出 `01-概览`、编号子模块等叶子展开，报告为总索引口径失真。
- `knowledge/变更/归档/**` 不触发总索引或局部 index。

### 4.1 OKF 合规

运行或复述 `kb-okf-check.mjs` 结果：

- **阻断**：缺 `knowledge/index.md`；残留 `知识索引.md` / `00-README.md` / 应迁移的平台或子目录 `README.md`；概念文件缺 frontmatter 或非空 `type`；非根 `index.md` / `log.md` 含非法 frontmatter。
- **警告**：未知 `type`；正文仍含「变更记录」段；根 index 缺 `okf_version`。
- 存量未迁移时建议 `/kb-okf-migrate`（先 dry-run）。

### 4.2 知识图谱（kb-graph）

运行或复述 `kb-okf-check.mjs` 图谱节结果（细则 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)）：

- **阻断**：概念文件（非 `index.md` / `log.md`；变更目录 `01`～`07` **暂不强制**）缺 `related` 或 `depends_on` 字段（可为 `[]`）；缺「相关」段（`## 相关` / `## 十、相关` / `## 十一、相关`）；`knowledge/` 内互链仍用 `[标题](相对路径.md)`（Markdown 相对链接仅允许外部 `http`/`https`）。
- **阻断**：wikilink 目标不存在（断链）。
- **警告**：长期孤儿节点（除根 `knowledge/index.md` 与各层 `index.md` 外，无任何入边：不被 index、wikilink、`related` / `depends_on` 引用）；frontmatter `related` ∪ `depends_on` 与正文「相关」段 `[[wikilink]]` 集合不一致（正文须 ⊇ frontmatter 并集）；叶子可能未被同目录 `index.md` 覆盖。
- **不写入 manifest**：文档拓扑与图谱关系**不得**塞进 `00-manifest.json`。
- 存量缺关系字段或残留 Markdown 内链时建议 `/kb-okf-migrate`（先 dry-run）。

### 5. 提交前闸门

- 指定变更的 `manifest.stage` 必须是 `archived` 或 `archived_with_debt`。
- 提交白名单来自：`manifest.files` + `05-summary.md` 清单 + 命中的变更目录文件。
- 工作区存在未归属改动时，报告阻断并要求用户确认提交范围。

### 6. 外部 sync（archive 步骤 10，在 commit+push 之后）

- 若 `kb.project.json` 未启用 `integrations`：通过，注明「未配置外部 integration」。
- 若登记记录 ID 存在（`external.registry_record_id`）且 `notified_events` **不含** `"completed"`：报告**警告**（archive 外部 sync 未完成），建议补跑 `/kb-archive` 步骤 10。
- 若 manifest 无 `external` 但 `01-proposal.md` 含任务记录 URL：报告**警告**（external 漂移），建议补写 external 后 sync。
- 若 `notified_events` 含 `"completed"`：通过。
- 若 `flow` 为 `lite` 或 `standard`、integration 已启用且无登记记录 ID：报告**警告**（外部登记未完成），建议补跑 `/kb-lite` 或 `/kb-propose` 外部登记；**不阻断**本地归档结论。
- 若无任何外部登记痕迹且 integration 未启用：通过，注明「未外部登记」。

## 输出格式

```markdown
## KB 校验报告

| 项目 | 结果 |
|------|------|
| 变更名称 | <中文名称或全部在途变更> |
| manifest | 通过 / 阻断 / 警告 |
| 任务闭环 | 通过 / 阻断 / 警告 |
| 评审闭环 | 通过 / 阻断 / 警告 |
| 知识库清单 | 通过 / 阻断 / 警告 |
| design 文档 | 通过 / 警告 |
| 局部 index | 通过 / 阻断 / 警告 |
| 总索引 | 通过 / 阻断 / 警告 |
| OKF 合规 | 通过 / 阻断 / 警告 |
| 知识图谱 | 通过 / 阻断 / 警告 |
| 提交白名单 | 通过 / 阻断 / 警告 |

## 阻断项
- <没有则写“无”>

## 警告项
- <没有则写“无”>

## 建议下一步
- <例如：运行 /kb-okf-migrate、/kb-index 业务域/礼物、/kb-index 总索引、/kb-archive>
```