---
description: 只读巡检知识库长期健康度，发现过期、重复、失效引用与状态漂移
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"`。

## 用户输入

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

---
对 `knowledge/` 执行**只读健康巡检**。本命令用于发现知识库衰减，不修改文件、不推进流程、不替代 `/kb-check <中文名称>` 的单变更闸门。

**输入**: 可选。可指定巡检范围：`知识地图`、`业务域`、`工程平台`、`变更`、`索引`；不指定时全量巡检。

## 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 / 重启会话，再重试核对。

## 约束

- **只读**：禁止修改知识文件、变更目录、OKF index、manifest 或 git 状态。
- **不做业务验证**：不主动运行 `flutter analyze`、`dart analyze`、`cargo check`、测试、部署或迁移 SQL。
- **不做自动修复**：只输出问题、证据和建议命令；元数据漂移建议 `/kb-repair`，知识正文过期建议 `/kb-sync` 或对应 `/kb-archive`。
- **优先机器可判定**：先检查 schema、路径、引用、重复标题、两级索引覆盖与知识图谱健康，再补充主观质量风险。
- **输出克制**：每类问题只列高信号样例，避免粘贴长文档。

## 子 Agent 编排

- 可并行派发只读 `Task`：`知识地图` 一组、`业务域` 按领域分组、`工程平台` 一组、`变更` 一组、`索引` 一组。
- 代码映射相关巡检必须优先使用 CodeGraph（见上文「CodeGraph 门禁（警告级）」）；索引或 MCP 不可用时只报告“代码映射无法确认”，不要用全仓扫描冒充精确结论。
- 主 Agent 汇总去重，不派发任何写入型子 Agent。

## 巡检项

### 1. manifest 结构健康

扫描：

```bash
knowledge/变更/**/00-manifest.json
```

检查：
- 是否符合业务仓 `.kb/kb-manifest.schema.json`。
- `files[].path` 是否存在；`status = removed` 是否能从说明中证明删除意图。
- `stage` 是否与目录位置一致：归档目录应为 `archived` 或 `archived_with_debt`。
- `reviews[].status = open` 是否仍被归档为完成。

### 2. Markdown 与 manifest 漂移

检查：
- `05-summary.md` 的「实际变更」是否覆盖 `manifest.files` 中的 `code|config|other`。
- `05-summary.md` 的「知识库更新」是否覆盖 `knowledge|index`。
- 同一变更目录是否缺少 `00-manifest.json`，或文件命名导致阶段不可判定。

### 3. 两级索引覆盖

检查：
- `knowledge/index.md` 是否只通过 wikilink 引用 `knowledge/知识地图.md`、业务域 `index.md`、工程平台 index（见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md) §6）。
- 业务域根目录、业务域子目录或工程平台分区叶子文件新增、删除、重命名后，所属 index 是否漏引或保留失效 wikilink。
- 业务域子目录存在时，领域 index 是否只维护根总览文件和子目录入口；子目录叶子文件是否由子目录 index 管理。
- `knowledge/工程平台/index.md` 是否只维护分区入口；工程平台根目录除 `index.md` / `log.md` 外是否仍有叶子文件。
- `knowledge/变更/归档/` 是否被错误纳入总索引或局部 index 的日常主体。
- 总索引与局部 index 的 wikilink 目标是否可解析为实际文件。

### 3.1 知识图谱健康（kb-graph）

细则 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)；可复述 `kb-okf-check.mjs` 图谱节：

- **断链**：正文、`## 相关` /「十一、相关」、`index.md` 列表中的 `[[wikilink]]` 目标不存在。
- **孤儿**：除根 `knowledge/index.md` 与各层 `index.md` 外，长期无任何入边（不被 index、wikilink、`related` / `depends_on` 引用）。
- **关系字段**：概念文件缺 `related` / `depends_on`（变更 `01`～`07` 暂不强制）；缺「相关」段。
- **一致性**：frontmatter `related` ∪ `depends_on` 与正文「相关」段 wikilink 集合不一致。
- **内链口径**：`knowledge/` 内仍用 `[标题](相对路径.md)` 互链（应仅 wikilink；外部 URL 仍用 Markdown）。
- **时效**：`status: superseded` 残留（是否仍被 index 主推）；非法 `status` / 断链 `supersedes`（okf-check 阻断项须上报）。
- 建议修复：`/kb-okf-migrate`（存量）、`/kb-index`（index 列表）、`/kb-sync`（正文与关系字段）。

### 3.2 贡献分健康（knowledge-utility）

只读执行（缺文件则记警告「未初始化，建议 `/kb-init` 或 bootstrap」）：

```bash
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" summary --target "$(pwd)" --json
```

报告：低分（score &lt; 1 且 hits ≥ 1）、高分样例、节点总数。不自动改分。细则 [kb-knowledge-evolve.md](../skills/kb-workflow/references/kb-knowledge-evolve.md)。

### 4. 知识正文衰减

检查：
- 知识地图、业务域、工程平台是否存在高度重复标题或明显重复段落。
- 同一接口、数据结构、用户功能是否在多个文件中给出冲突描述。
- 文件是否超过 3000 字符，或把历史变更过程写进当前生效说明。
- 业务域主题是否职责混杂：领域根文件或子目录文件超过 3000 字符、包含 3 个以上独立主题，或领域 index 堆叠子目录叶子清单时，建议拆入 `接口/`、`数据/`、`流程/`、`规则/`、`运营/` 等子目录。
- 工程平台主题是否职责混杂：分区文件超过 3000 字符、包含 3 个以上独立主题，或分区 index 叶子清单过长时，建议在分区内继续拆分。
- 是否出现“待补充”“稍后同步”“临时说明”等长期占位。

### 5. 代码映射风险

只做轻量映射，不深挖业务实现：
- `doger_proto/`、`rust_server/src/endpoints/`、`vkk_client_flutter/lib/`、`quasar/src/` 的近期变更，是否有对应业务域或工程平台说明。
- 若无法确定是否过期，标记为警告，不直接判阻断。

CodeGraph 口径（警告级，不阻断）：
- 先按上文门禁建议跑 `kb-codegraph-check.mjs` 并确认 `codegraph_explore`（或 `codegraph_status`）可用；不可用只记警告。
- 对高风险或近期变更主题运行 `codegraph_explore`，核对是否存在对应知识文件。
- 涉及公共接口、服务、组件或数据结构时，用 `codegraph_impact` 抽样判断影响面是否被知识库覆盖。

### 6. 流程度量汇总

只读扫描 `knowledge/变更/**/00-manifest.json`，汇总流程度量，不做阻断判定：

- `metrics` 计数：`redispatch`（重派次数）、`check_blocked`（/kb-check 阻断次数）及扩展键，按变更目录列出并合计。
- 可推导度量：`external.acceptance.rounds` 轮数（验收回退轮次）、`reviews[].status` 分布（open / fixed / accepted_debt / false_positive）、`revisions` 轮次数。
- 输出按「变更目录 → 度量」表呈现，并给出全库合计；缺失 `metrics` 字段的目录记为「无数据」，不视为问题。
- 该汇总供 `/kb-evolve` 提案优先级参考。

## 输出格式

```markdown
## KB 健康报告

| 项目 | 结果 |
|---|---|
| manifest schema | 通过 / 警告 / 风险 |
| manifest 与 Markdown | 通过 / 警告 / 风险 |
| 两级索引 | 通过 / 警告 / 风险 |
| 知识图谱 | 通过 / 警告 / 风险 |
| 贡献分 / superseded | 通过 / 警告 / 风险 |
| 知识正文 | 通过 / 警告 / 风险 |
| 代码映射 | 通过 / 警告 / 风险 |
| 流程度量 | 汇总表 / 无数据 |

## 高优先级问题
- <没有则写“无”>

## 普通问题
- <没有则写“无”>

## 建议下一步
- <例如：/kb-repair <中文名称>、/kb-sync 礼物、/kb-index 业务域/礼物、/kb-okf-migrate dry-run>
```

## 退出口径

- `/kb-health` 发现风险不自动阻断当前开发；只有 `/kb-check` 针对具体变更给出阻断时，才作为阶段闸门。
- health 报告中的高优先级问题应优先转为 `/kb-repair`、`/kb-sync` 或新的标准 KB 变更。