code-deep：给 Coding Agent 的两个 MCP 工具 —— 改代码前 explore，改完 review

用 Coding Agent 改代码时的一个常见浪费：上来 grep 关键字 → 读五个文件 → 发现方向不对 → 再 grep ，token 烧完了还没定位准，改完也说不清影响面有多大。

做了个 MCP server 解决这个，MIT ，已发 npm 。

https://github.com/team-harness/code-deep

npm i -g @team-harness/code-deep
code-deep install --target codex,claude

install 会自动给 Codex 和 Claude Code 注册全局 MCP server 、往 ~/.codex/AGENTS.md 和 ~/.claude/CLAUDE.md 写一段带标记的指引、给 Claude 加上对应权限。它保留无关配置、每个改动的文件备份成 <file>.code-deep.bak、可重复执行。装完重启一下 host 。

暴露给 Agent 的接口刻意做得很小，只有两个。

explore：改之前先搞清楚在动什么

code-deep explore \
  "追踪 AuthService login 如何创建和校验 session ，包括调用方和影响面" \
  --path /path/to/project

返回聚焦的相关源码、符号关系、调用路径和下游影响。好的 query 要说清三件事：任务目标、已知的符号或文件、要追踪的关系（ callers / callees / 数据流 / blast radius ）。

跟 grep 的区别是它问的是结构化的图，不是文本匹配 —— 不用「猜哪个关键字能命中」，也不用为了确认调用关系去读整个文件。

review：改完之后看风险在哪

code-deep review /path/to/project                                # 当前工作区，含 staged/unstaged/untracked
code-deep review /path/to/project --base origin/main --head HEAD # 分支或 PR 范围
code-deep review /path/to/project --json                         # 结构化报告

流水线是：unified diff 解析 → hunk 映射到当前符号 → 影响面收集 → 确定性风险打分 → Markdown + 结构化 JSON 报告。

风险信号目前包括：敏感路径、缺少对应测试文件改动、图影响宽度、高置信度的跨边界影响、diff 大小、文件数、删除文件、图分析不完整。整体风险取「全局信号总和」和「单符号最高风险」两者中的较大值 —— 这样一个局部高风险符号不会被整体的低分掩盖掉。

每个报告有按风险排序的 reviewItems，每项对应一个变更符号，带归一化的影响符号、相关测试文件、映射与影响的置信度、parser warning ，以及贡献到该符号风险分的具体原因。测试状态是 linked / changed / missing / unknown 四态。

几个我自己比较在意的设计

风险分只用来排审查优先级，不是「这里有 bug 」的断言。 文档里明说了，不玩「 AI 发现 N 个问题」那套。
图查询失败不会静默变成空结果，而是产生显式的低置信度 warning 并触发 graph-analysis-incomplete 信号 —— 一次失败的查询不能伪装成一次干净的低风险审查。这条我觉得是最关键的，静默降级的工具比没有工具更危险。
删除的文件和符号可能不在当前索引里，所以删除类发现被显式标记为不确定，而不是假装分析过了。
跨边界打分要求 impact 被高置信度解析出来，边界保守地识别在 apps/、packages/、services/、modules/、libs/ 这类 workspace 根，或者 src/ 下的第一层领域目录。
MCP 侧默认只返回风险摘要、信号、紧凑变更行范围和 top 3 review item ，不塞 diff 和图上下文；要完整内容再要 standard。任何截断都通过 reviewItemsOmitted 显式告诉你，不会偷偷砍掉。

也能当库用

import { CodeDeepClient } from '@team-harness/code-deep';

const codeDeep = new CodeDeepClient({ projectPath: process.cwd() });
try {
  const context = await codeDeep.explore('AuthService login');
  const report = await codeDeep.review();
  for (const item of report.reviewItems) {
    console.log(item.risk.level, item.symbol.name, item.tests.status);
  }
} finally {
  await codeDeep.close();
}

其他

底层是 https://github.com/colbymchenry/codegraph （ MIT ），作为精确依赖装进来，不用单独全局装。两者版本独立，桥接层和 reviewer 可以不等上游发版就修问题。

第一次在 Git 仓库里调 explore 或 review 会自动初始化缺失的 .codegraph/，不用手动 init 。code-deep ps 可以看本地的 wrapper 、CodeGraph proxy 、共享 daemon 和 watchdog 进程，只读不改任何东西，也不会仅凭运行时长就把长期进程判成孤儿。

欢迎试，有问题提 issue 或者在这里说。