# CodeGraph 接入规范细则

> 本文件是 KB 流程 CodeGraph 接入规范细则的**唯一出处**，由 SKILL.md「CodeGraph 接入规范」一节引用。

CodeGraph 是 KB 流程的代码事实入口；知识库解释业务现状，CodeGraph 校对实际实现。凡涉及「代码现状、调用链、影响面、类似实现、依赖图、评审范围、知识库与代码一致性」的步骤，必须优先使用 CodeGraph，再按需读取具体文件。

## 一、MCP 配置（SSOT）

插件**不再**通过 `plugin/.mcp.json` 或 `plugin.json` 的 `mcpServers` 强制注入 CodeGraph MCP。业务仓须在**项目级**自行配置 MCP；`kb-bootstrap.mjs` **不**自动写入 MCP 文件。

### 1.1 项目级配置位置

| 运行时 | 配置文件 | 说明 |
|--------|----------|------|
| Claude Code | 仓库根 `.mcp.json` | 项目级 MCP 声明 |
| Cursor | `.cursor/mcp.json` | 项目级 MCP 声明 |

### 1.2 从插件示例复制（推荐）

插件包内提供可复制模板，路径：`${PI_KB_ROOT}/bootstrap/examples/mcp/`。

1. **Claude Code**：将 `claude.mcp.json` 复制到业务仓根目录并重命名为 `.mcp.json`（若已有 `.mcp.json`，合并 `codegraph` 条目，避免重复 server 名冲突）。
2. **Cursor**：将 `cursor.mcp.json` 复制到业务仓 `.cursor/mcp.json`（若已有该文件，合并 `codegraph` 条目；保留你自行配置的其他 MCP，勿与重复条目冲突）。
3. **示例默认使用 npx 直连**（不依赖 `PI_KB_ROOT`）；Cursor 示例用 `${workspaceFolder}` 指向项目根。说明见同目录 `README.md`。
4. **工具面**：示例通过 `CODEGRAPH_MCP_TOOLS` 显式开放 KB 所需工具（见 §1.6）；配置变更后执行 **Developer: Reload Window**。

### 1.3 launcher（可选）

插件保留跨平台 launcher，供项目级 MCP 可选引用（示例默认不走此路径）：

```json
{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["${PI_KB_ROOT}/scripts/codegraph-mcp.cjs"]
    }
  }
}
```

- **launcher 脚本**：`${PI_KB_ROOT}/scripts/codegraph-mcp.cjs`（随插件安装，bootstrap 不复制到业务仓）。
- **解析项目根**：按 `--project-dir` → `CLAUDE_PROJECT_DIR` / `CURSOR_WORKSPACE` 等环境变量 → 向上查找 `kb.project.json` / `.git` → `cwd`。
- **跨平台**：Windows 下 `npx` 使用 `shell: true`；launcher 内部通过 `npx -y @colbymchenry/codegraph@1.5.0` 拉取，无需全局安装。
- **Cursor 注意**：项目级 `.cursor/mcp.json` 通常无 `PI_KB_ROOT`；若要用 launcher，请写已安装插件的 `codegraph-mcp.cjs` 绝对路径，或继续用示例中的 npx 写法（`${workspaceFolder}` 可用）。
- **npx 直连**（示例默认；Claude 用 `--path .`，Cursor 用 `--path ${workspaceFolder}`）：见 `bootstrap/examples/mcp/`。

### 1.4 索引

业务仓在首次接入或 `codeRoots` 变更后执行：

```bash
npx -y @colbymchenry/codegraph@1.5.0 init
npx -y @colbymchenry/codegraph@1.5.0 index
```

索引建立后再依赖 MCP 工具；细则见 SOP §二「环境准备」。**不要**让 Agent 擅自 `init`/`index`（索引是用户决策）；硬门禁阶段应阻断并提示人操作。

### 1.5 从旧版迁移

曾依赖「插件启用后 MCP 自动连接」的业务仓，须改为 §1.1～§1.2 的项目级配置。可保留已有 `.cursor/mcp.json` 中与 CodeGraph 等价的条目；若与示例 `codegraph` server 重复，删除其一即可。

若配置仍含已废弃的 `codegraph_context` 或未设置 `CODEGRAPH_MCP_TOOLS`，请按 §1.6 更新后 Reload。

### 1.6 工具面（`CODEGRAPH_MCP_TOOLS`）

上游默认往往只列出 `codegraph_explore`。KB 流程还需要门禁探测与结构化影响面，示例 / launcher **显式**设置：

```text
CODEGRAPH_MCP_TOOLS=explore,status,search,callers,callees,impact,node,files
```

| 档位 | 环境变量 | 适用 |
|------|----------|------|
| **KB 默认（推荐）** | 上表 allowlist | 强模型；explore 为主，status/impact 等按需 |
| **上游极简** | 不设或仅 `explore` | 只要探索、不要 KB 硬门禁细工具 |
| **弱模型 / 控上下文** | `search,impact,node,callers,callees,files,status`（可不含 explore） | 先结构后定向 Read，避免 explore 大段灌源码 |

**已废弃**：`codegraph_context`（勿再写入规范、prompt 或 allowlist）。一律用 `codegraph_explore` 承担「摸底 + 源码 + 调用路径 + blast radius」。

## 二、门禁

### 2.1 机器脚本（硬门禁前置）

在硬门禁命令执行前，可用脚本探测索引与 MCP 就绪情况：

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

脚本硬检业务仓 `.codegraph/` 索引（并尽量跑 `codegraph status`）；**不**探测 MCP 是否已连接。退出非 0 时，硬门禁命令应阻断并提示按 §一 补齐索引与项目级 MCP。MCP 工具可用性由 Agent 按 §2.2 确认。

### 2.2 Agent 确认

进入须用 CodeGraph 的阶段时，Agent **必须**确认「CodeGraph 可用」。下列**任一**即可（索引门禁 `kb-codegraph-check.mjs` 通过 ≠ 工具名已暴露）：

1. 宿主 MCP：`codegraph_*`（至少 `codegraph_explore`；若已开放可再确认 `codegraph_status`）
2. Cursor + pi bridge：`pi__codegraph_*`（与 `codegraph_*` **等价**；子 Agent prompt 须写清实际暴露名，如 `pi__codegraph_explore`，勿只写裸名导致对不上）
3. CLI 等价路径：本机 `codegraph` / `npx -y @colbymchenry/codegraph@…` 能查 status/explore（须在报告声明「经 CLI，非 MCP」）

**降级顺序**（索引门禁已通过时）：MCP/bridge 工具名均未暴露 → **不得**空转 blocked，应尝试 CLI；CLI 也失败才硬阻断（或用户明示跳过）。仅用 CLI/文件兜底时须声明「未完成 MCP CodeGraph 核对」，不得冒充已 MCP 核对；不得用大范围 grep/read 代替可调用的 CodeGraph 路径。

### 2.3 硬门禁 vs 警告

| 级别 | 命令 / 阶段 |
|------|-------------|
| **硬门禁**（须 CodeGraph 可用：MCP / `pi__*` / CLI 任一） | `/kb-design`、`/kb-plan`、`/kb-apply`、`/kb-revise-apply`、`/kb-review`、`/kb-archive`、`/kb-explore`、`/kb-query`、`/kb-sync`、`/kb-verify-issue` |
| **禁止 CodeGraph** | `/kb-propose`（业务 PRD，不写技术实现） |
| **警告级**（索引不可用记警告，不阻断只读校验） | `/kb-check`、`/kb-health` |

硬门禁命令在索引不可用、且 MCP/bridge/CLI **均**不可用时应停止推进，并提示用户完成 §一 配置、`init`/`index` 与 Reload；允许在明确告知风险后改用只读文件检索**兜底汇报**，但不得冒充已完成 CodeGraph 核对。

## 三、LLM 操作规范（最佳实践）

### 3.1 使用顺序

1. 运行前按 §2.2 确认 MCP `codegraph_*`、bridge `pi__codegraph_*` 或 CLI **任一**可用；索引不可用则按 §二 阻断/警告，兜底时须声明「未完成 CodeGraph 核对」/「未完成 MCP CodeGraph 核对」。
2. **默认入口**：几乎所有结构/流程/定位/改前摸底问题，先调一次 explore（宿主名 `codegraph_explore` 或 bridge 名 `pi__codegraph_explore`；CLI 则等价命令）。  
   - `query` 可以是自然语言任务，或「符号名 + 文件名」袋。  
   - 流程类问题（「X 如何到 Y」）在 query 中同时点名两端符号。  
   - 返回的行号源码视为**已 Read**，不要对同一批文件再循环 `Read`。
3. 需要精确控制时再拆工具：`codegraph_search` / `pi__codegraph_search` 定位 → impact / callers / callees → node；CLI 路径用对应子命令并声明非 MCP。
4. 仅当图未覆盖（配置、文档、非索引路径）或 §3.3 staleness 列出的文件，才定向 `Read`/`Grep`。
5. CodeGraph 返回的是代码事实，不替代需求澄清、知识库索引判断、manifest 状态、编译器/测试或用户确认。

### 3.2 意图 → 工具

| 意图 | 工具 |
|------|------|
| 怎么工作 / 架构 / 定位 / 改前摸底 / 类似实现 | `codegraph_explore` |
| X 如何到达 Y | `codegraph_explore`（query 含两端符号） |
| 改公共符号会影响谁 | explore 内联 blast radius；不足再用 `codegraph_impact` |
| 谁调用 / 它调用谁 | `codegraph_callers` / `codegraph_callees`（或 explore 关系图） |
| 精确符号名检索（只要位置） | `codegraph_search` |
| 单符号/单文件 Read 对等 | `codegraph_node` 或把路径写入 explore query |
| 索引健康 | `codegraph_status` |
| 业务 PRD（`/kb-propose`） | **禁止** CodeGraph |

### 3.3 新鲜度（staleness）

1. 若工具响应带「部分文件自上次同步后已编辑」类 banner：仅对**列出的文件**用 `Read` 确认；未列出的仍信图。
2. 若提示 auto-sync 已禁用、整库冻结：涉及可能变更的结论须 `Read` 复核，并建议用户修复 watcher / 重新 `index`。
3. 索引明显过期且无法同步时：硬门禁阻断或警告级记风险，不得假装已图核。

### 3.4 影响面纪律

1. 评审与 plan 不得只看 diff 文件列表；须结合调用链 / blast radius。
2. 高扇出工具函数、纯测试调用边易造成噪音：默认关注业务调用方；为工具函数本身改签名时再扩大范围。
3. 发现影响面超出当前任务范围：停止扩散修改并报告，由主流程决定是否扩 scope。

### 3.5 反模式（禁止）

1. 先大范围 `Grep`/`Read` 再补 CodeGraph。
2. 用 `Grep` 复查图结果（AST 图优先于文本搜索）。
3. 手工拼调用链（应一次 explore 点名路径）。
4. explore 已返回源码仍对同文件再 `Read`。
5. 把探索外包给**只会读文件、未要求用 CodeGraph** 的子 Agent。
6. 无索引时 Agent 擅自 `codegraph init`/`index`。
7. 兜底文件检索却冒充「已完成 CodeGraph 核对」。
8. 继续调用或文档化已废弃的 `codegraph_context`。

## 四、写入到 KB 产物

- `01-proposal.md`：**业务 PRD**（`/kb-propose` 产出）；不写技术实现、**不使用 CodeGraph**。
- `02-design.md`：必须含基于 01 业务流程的 Mermaid 流程图与改动对照表（明确不改/改动/新增/删除节点及落点文件）；**十段结构见 [`knowledge/AGENTS.md`](../../../../knowledge/AGENTS.md)「5、变更设计文档结构」**（阿拉伯数字 `## N、` / `### N.M`）；技术影响、参考实现、分层落点、接口/数据约束与 **知识库影响/更新计划** 优先来自 CodeGraph 与知识库。
- `03-tasks.md`：**文件级「1、执行计划 / 2、任务清单」见 AGENTS「6、变更任务文档结构」**；上下文文件、实现范围、依赖图和冲突文件优先由 CodeGraph 影响面生成。
- `04-review.md`：评审范围需结合 diff 与 CodeGraph 调用链/影响面；不能只看改动文件孤立评审。
- `05-summary.md` 与归档知识文件：代码现状核对优先使用 CodeGraph，必要时补读目标文件确认细节；写回业务域知识文件时按 [`knowledge/AGENTS.md`](../../../../knowledge/AGENTS.md) 的编号子模块 + 十段式结构落段。

## 五、子 Agent 提示要求

派发只读或实现子 Agent 时，prompt 必须包含：

1. 先用 explore 获取相关代码上下文（及内联调用路径 / blast radius）；**写清本会话实际可调用名**（`codegraph_explore` 或 `pi__codegraph_explore` 等），勿只写裸名；
2. 需要精确影响面时再用 impact / callers / callees（或对应 `pi__codegraph_*`）；
3. 只有图信息不足、staleness 列出的文件、或索引/工具均不可用时，才读取具体文件；
4. 不得用大范围 grep/read 循环代替 CodeGraph；不得把探索外包给未注入本条的纯文件子任务；MCP/bridge 缺失时按 §2.2 走 CLI 并声明降级。