code-deep：给 Coding Agent 的两个 MCP 工具 —— 改代码前 explore，改完 review
dafang:
用 Coding Agent 改代码时的一个常见浪费：上来 grep 关键字 → 读五个文件 → 发现方向不对 → 再 grep ，token 烧完了还没定位准，改完也说不清影响面有多大。
做了个 MCP server 解决这个，MIT ，已发 npm 。
[https://github.com/team-harness/code-deep](https://github.com/team-harness/code-deep)
```bash
npm i -g @team-harness/code-deep
code-deep install --target codex,claude
```
`install` 会自动给 Codex 和 Claude Code 注册全局 MCP server 、往 `~/.codex/[AGENTS.md](http://agents.md/)` 和 `~/.claude/[CLAUDE.md](http://claude.md/)` 写一段带标记的指引、给 Claude 加上对应权限。它保留无关配置、每个改动的文件备份成 `<file>.code-deep.bak`、可重复执行。装完重启一下 host 。
暴露给 Agent 的接口刻意做得很小，**只有两个**。
## explore：改之前先搞清楚在动什么
```bash
code-deep explore \
"追踪 AuthService login 如何创建和校验 session ，包括调用方和影响面" \
--path /path/to/project
```
返回聚焦的相关源码、符号关系、调用路径和下游影响。好的 query 要说清三件事：任务目标、已知的符号或文件、要追踪的关系（ callers / callees / 数据流 / blast radius ）。
跟 grep 的区别是它问的是结构化的图，不是文本匹配 —— 不用「猜哪个关键字能命中」，也不用为了确认调用关系去读整个文件。
## review：改完之后看风险在哪
```bash
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` 显式告诉你，不会偷偷砍掉。
## 也能当库用
```ts
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](https://github.com/colbymchenry/codegraph) （ MIT ），作为精确依赖装进来，不用单独全局装。两者版本独立，桥接层和 reviewer 可以不等上游发版就修问题。
第一次在 Git 仓库里调 explore 或 review 会自动初始化缺失的 `.codegraph/`，不用手动 init 。`code-deep ps` 可以看本地的 wrapper 、CodeGraph proxy 、共享 daemon 和 watchdog 进程，只读不改任何东西，也不会仅凭运行时长就把长期进程判成孤儿。
欢迎试，有问题提 issue 或者在这里说。
---
原文链接：[点击查看](https://www.v2ex.com/t/1235024)
用 Coding Agent 改代码时的一个常见浪费：上来 grep 关键字 → 读五个文件 → 发现方向不对 → 再 grep ，token 烧完了还没定位准，改完也说不清影响面有多大。
做了个 MCP server 解决这个，MIT ，已发 npm 。
[https://github.com/team-harness/code-deep](https://github.com/team-harness/code-deep)
```bash
npm i -g @team-harness/code-deep
code-deep install --target codex,claude
```
`install` 会自动给 Codex 和 Claude Code 注册全局 MCP server 、往 `~/.codex/[AGENTS.md](http://agents.md/)` 和 `~/.claude/[CLAUDE.md](http://claude.md/)` 写一段带标记的指引、给 Claude 加上对应权限。它保留无关配置、每个改动的文件备份成 `<file>.code-deep.bak`、可重复执行。装完重启一下 host 。
暴露给 Agent 的接口刻意做得很小，**只有两个**。
## explore：改之前先搞清楚在动什么
```bash
code-deep explore \
"追踪 AuthService login 如何创建和校验 session ，包括调用方和影响面" \
--path /path/to/project
```
返回聚焦的相关源码、符号关系、调用路径和下游影响。好的 query 要说清三件事：任务目标、已知的符号或文件、要追踪的关系（ callers / callees / 数据流 / blast radius ）。
跟 grep 的区别是它问的是结构化的图，不是文本匹配 —— 不用「猜哪个关键字能命中」，也不用为了确认调用关系去读整个文件。
## review：改完之后看风险在哪
```bash
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` 显式告诉你，不会偷偷砍掉。
## 也能当库用
```ts
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](https://github.com/colbymchenry/codegraph) （ MIT ），作为精确依赖装进来，不用单独全局装。两者版本独立，桥接层和 reviewer 可以不等上游发版就修问题。
第一次在 Git 仓库里调 explore 或 review 会自动初始化缺失的 `.codegraph/`，不用手动 init 。`code-deep ps` 可以看本地的 wrapper 、CodeGraph proxy 、共享 daemon 和 watchdog 进程，只读不改任何东西，也不会仅凭运行时长就把长期进程判成孤儿。
欢迎试，有问题提 issue 或者在这里说。
---
原文链接：[点击查看](https://www.v2ex.com/t/1235024)
评论
暂无评论。