用 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 或者在这里说。
Select Language