---
description: 按 OKF 两级 index 检索知识：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"`。

## 用户输入

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

---
基于 OKF 两级 `index.md` 与知识图谱 wikilink 执行精确知识检索。链接与关系字段细则见 [kb-graph.md](../skills/kb-workflow/references/kb-graph.md)。

**输入**：要查询的问题或关键词。

## 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。开始前**必须**先跑机器门禁；失败则停止并输出脚本指引，禁止继续。执行：

`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 / 重启会话，再重试本命令。

## 检索路径

固定按以下顺序读取：

1. `knowledge/index.md`：根据 wikilink 列表判断应进入知识地图、哪个业务域 `index.md`，或工程平台 index。
2. `knowledge/业务域/<领域>/index.md` 或 `knowledge/工程平台/index.md`：根据 wikilink 清单、职责边界、推荐阅读路径选择 `01-概览`、编号子模块文件、业务域子目录 index 或工程平台分区 index。
3. 可选读取 `knowledge/业务域/<领域>/<中文子目录>/index.md` 或 `knowledge/工程平台/<中文平台分区>/index.md`：当入口 index 指向局部分区时，用局部 index 选择具体知识文件。
4. 具体知识文件：读取 `01-概览.md`、相关编号子模块文件等，并按问题补读相邻文件；子模块文件按十段式（接口看「五」、数据看「六」、流程看「四」、关联看「十、相关」）。
5. **可选图谱扩展**：当前文件 frontmatter 的 `related` / `depends_on` 或正文 `## 相关` /「十、相关」/「十一、相关」中的 `[[wikilink]]` 与问题相关时，沿出链补读目标概念文件（变更目录 `01`～`07` 暂不强制关系字段）。
6. **贡献分重排（EvoRAG-lite）**：得到 ≥2 个候选概念文件后，由子 Agent shell 执行：

```bash
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" rank \
  --target "$(pwd)" --query-files "<逗号分隔相对路径>" --json
```

按返回 `ranked` **高分优先**深入阅读。细则 [kb-knowledge-evolve.md](../skills/kb-workflow/references/kb-knowledge-evolve.md)。

## 推理规则

- 系统整体能力或业务域关系：先读 `knowledge/知识地图.md`。
- 具体业务问题：先读对应 `knowledge/业务域/<领域>/index.md`。
- 跨域工程、端工程、协议或基础设施：先读 `knowledge/工程平台/index.md`。
- 领域 index 指向子目录时，继续读取子目录 index；不得跳过子目录 index 直接遍历全部叶子文件。
- 平台根 index 指向分区时，继续读取分区 index；不得跳过分区 index 直接遍历全部叶子文件。
- index 未覆盖但目录中存在相关文件时，回答时标记“局部 index 可能失真”，并建议运行 `/kb-index 业务域/<领域>`、`/kb-index 业务域/<领域>/<中文子目录>`、`/kb-index 工程平台` 或 `/kb-index 工程平台/<中文平台分区>`。
- 优先沿 index wikilink 导航；`related` / `depends_on` 与正文 `[[wikilink]]` 仅作补充路径，不得跳过两级 index 直接全目录遍历（除非 index 已失真且用户确认）。
- **`status: superseded`**：默认跳过或最后阅读；用户明示「含已取代」时例外。
- 回答采用后，对实际引用的知识路径 `bump`（主 Agent 派 inspector/librarian 经 shell，**不**口头假装已写）：

```bash
node "${PI_KB_ROOT}/scripts/kb-knowledge-utility.mjs" bump \
  --target "$(pwd)" --paths "<逗号分隔相对路径>" --delta 1
```

## CodeGraph 补充核对

- 当问题涉及真实代码行为、调用链、接口实现、数据结构或知识库可能过时时，必须在知识库路径之后调用 `codegraph_explore` 核对代码事实；只在仍不足或 staleness 列出的文件时读取具体文件。
- 回答中区分“知识库记载”和“CodeGraph 核对到的代码现状”；二者冲突时标记知识库可能过时，并建议 `/kb-sync <范围>`；确认知识误导时对相关路径 `penalize`（`--delta 0.5`）。

## 输出格式

```markdown
## 回答

<基于知识库的回答>

**检索路径**：`knowledge/index.md` -> `knowledge/业务域/礼物/index.md` -> `knowledge/业务域/礼物/0X-<子模块>.md`（「五、接口」段）
**信息来源**：<实际读取的文件路径>
**贡献分**：已 rank / 已 bump <路径>；或单候选跳过 rank
**代码核对**：<如使用 CodeGraph，写关键符号或调用链；未使用则写“未涉及代码核对”>
```

## 示例

| 问题 | 推理路径 |
|------|---------|
| 认证流程是什么？ | `index.md` -> `业务域/认证/index.md` -> `01-概览.md`、相关子模块「四、客户端流程」 |
| 送礼扣款怎么做？ | `index.md` -> `业务域/礼物/index.md` -> 送礼子模块「五、接口」「六、数据」 |
| 后端有哪些分层？ | `index.md` -> `工程平台/index.md` -> `工程平台/Rust服务端/index.md` |
| user_wallets 表结构？ | `index.md` -> `业务域/钱包/index.md` -> 钱包数据子模块「六、数据」 |