---
description: 维护 OKF 两级 index.md：总入口只列入口，局部 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 两级索引（OKF `index.md`）。`knowledge/index.md` 是总入口，不展开全部叶子文件；具体文件清单由领域或平台分区 `index.md` 维护。列表格式与 wikilink 细则见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)；OKF 保留名与 type 见 [kb-okf.md](../skills/kb-workflow/references/kb-okf.md)。

**输入**：可选，支持：
- `总索引`：只维护 `knowledge/index.md`
- `业务域/<领域>`：维护 `knowledge/业务域/<领域>/index.md`
- `业务域/<领域>/<中文子目录>`：维护 `knowledge/业务域/<领域>/<中文子目录>/index.md`
- `工程平台`：维护 `knowledge/工程平台/index.md`
- `工程平台/<中文平台分区>`：维护 `knowledge/工程平台/<中文平台分区>/index.md`
- 不指定：先维护所有局部 index，再按需维护总索引

## 触发条件

### 必须更新局部 index
- `knowledge/业务域/<领域>/` 下知识文件新增、删除、重命名。
- `knowledge/业务域/<领域>/<中文子目录>/` 下知识文件新增、删除、重命名。
- `knowledge/工程平台/` 根目录除 `index.md` / `log.md` 外出现平台知识文件时，应迁入中文平台分区并更新平台根 index。
- `knowledge/工程平台/<中文平台分区>/` 下知识文件新增、删除、重命名。
- 普通知识文件正文变化导致 index 的一句话用途、职责边界或推荐阅读路径失真。

### 必须更新总索引
- `knowledge/知识地图.md` 入口变化。
- 新增、删除、重命名 `knowledge/业务域/<领域>/index.md`。
- 新增、删除、重命名 `knowledge/工程平台/index.md`。
- 总索引引用失效或入口摘要失真。
- 业务域子目录 index 的新增、删除、重命名只更新所属领域 index，不直接触发总索引。
- 工程平台分区 index 的新增、删除、重命名只更新 `knowledge/工程平台/index.md`，不直接触发总索引。

### 不触发总索引
- 业务叶子文件正文变化，且所属 index 仍准确。
- 只新增、删除、移动 `knowledge/变更/归档/**`。
- 只修改变更目录 `00`～`07`，且未影响当前知识入口。

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

## 执行步骤

1. 识别输入范围：`总索引` / `业务域/<领域>` / `业务域/<领域>/<中文子目录>` / `工程平台` / `工程平台/<中文平台分区>` / 全量。
2. 维护局部 index（**无 frontmatter**；列表形 `* [[wikilink]] - description`，见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md) §6）：业务域 `index.md` 列出 `[[01-概览]]` 与编号子模块（及直属子目录 `[[子目录/index|显示名]]`）；子目录 index 列出子目录内编号子模块；工程平台根 index 只列直属分区 index；分区 index 列出分区叶子文件。
3. 业务域子模块膨胀时拆成更多编号子模块文件；仍庞大时才拆入中文子目录（结构见 [`knowledge/AGENTS.md`](../../bootstrap/knowledge/AGENTS.md)）；领域 `index.md` 不得堆叠子目录叶子文件。
4. 工程平台内容一律进入中文平台分区；根目录除 `index.md` / `log.md` 外不得继续新增平台叶子文件。
5. 维护总索引：只列 `knowledge/知识地图.md`、各 `knowledge/业务域/<领域>/index.md`、`knowledge/工程平台/index.md`；根 `index.md` 保留 `okf_version: "0.1"`。
6. 校验 wikilink 目标存在（同目录短名与跨目录路径均可解析）；总索引不得列 `01-概览`、编号子模块、业务域子目录 index 叶子展开或工程平台分区叶子文件。
7. 结构性入口变更追加同目录 `log.md`（若适用）。
8. 输出报告。

## 输出格式

```markdown
## 知识索引维护报告

- 输入范围：总索引 / 业务域/<领域> / 业务域/<领域>/<中文子目录> / 工程平台 / 工程平台/<中文平台分区> / 全量
- 局部 index：已更新 X 个 / 无需更新
- 总索引：已更新 / 无需更新
- 未覆盖或失效引用：无 / <路径列表>
```