Forensic-deepdive 完全指南：用代码知识图谱为 AI Agent 打通跨文件调用链

AI 编码 Agent（Claude Code、Cursor、Codex、Windsurf 等）在分析大型代码库时，常常面临一个根本性问题：它们能逐行阅读文件，却难以理解跨文件的深层调用关系。一个前端按钮的点击事件，最终调用了后端哪个 Handler？一个 Logger 类被多少模块引用？修改某个公共接口会影响多少下游代码？

传统的 RAG 方案（将文件内容分块后做向量检索）在结构理解上力不从心，而 forensic-deepdive 提供了一套完全不同的方案——它为代码库建立持久的、可查询的知识图谱，并为 AI Agent 暴露 9 个 MCP 工具，让 Agent 第一次能像资深开发者一样追溯调用链、分析变更影响、理解代码演化历史。

什么是 Forensic-deepdive

forensic-deepdive 是一个开源的代码分析工具（Apache-2.0，Python），核心工作流程分为三步：

1. 抽取（extract）：扫描代码库，构建持久化的知识图谱（基于 LadybugDB 嵌入式图数据库）
2. 服务（serve）：以 MCP 服务端形式暴露 9 个复合分析工具
3. 查询（query）：AI Agent 通过 MCP 工具调用，实时获取代码结构信息

与传统的代码索引工具不同，forensic-deepdive 有四层差异化能力：

• 跨协议端点跟踪：将 HTTP 路由、MCP 工具注册、gRPC 方法、消息队列消费者统一映射为 Endpoint 节点，一条命令即可追溯「前端调用 → 后端 Handler → 数据库操作」的完整链路
• 置信度标签：每条边和声明都带 EXTRACTED（确定性）/ INFERRED（高置信度推导）/ AMBIGUOUS（存在歧义）标签，Agent 可以据此判断信息的可靠程度
• Git 考古学：不仅分析静态结构，还能追踪代码变更历史、核心贡献者、公交因子、共变模块
• 持久化 Agent 记忆：Agent 可以通过 record_insight / recall_insights 工具在知识图谱中存储和检索已验证的分析结论

快速上手

安装只需一条命令（基于 PyPI，依赖 Python 的 uv 或 pip）：

uv tool install forensic-deepdive

分析任意代码库：

forensic extract /path/to/your/repo

命令执行后，你会在仓库目录下看到两个输出：

• .deepdive/graph.lbug——嵌入式知识图谱文件
• docs/codebase/——5 个人工可读的 Markdown 产物

将图谱以 MCP 服务形式暴露给 AI Agent：

forensic serve --repo /path/to/your/repo

在 Claude Code 中，可以直接通过插件市场安装：

/plugin marketplace add Dhevenddra/forensic-deepdive
/plugin install forensic-deepdive@dhevenddra

九大 MCP 工具详解

forensic-deepdive 的核心价值在于它的 9 个 MCP 复合工具。每个工具的设计都经过精心拆分，确保单个工具描述不超过 200 token，从而使整体工具包能够舒适地驻留在 Anthropic 的每轮技能元数据预算内。

实战：追溯一个跨栈调用

假设你在分析一个 Web 应用，前端使用 TypeScript，后端使用 Python FastAPI。传统的代码分析工具很难将前端的 API 调用与后端的路由 Handler 关联起来。Agent 调用 trace MCP 工具并传入参数 symbol="UserProfile.save", direction="downstream", max_depth=5，即可获得：

前端 UserProfile.save 调用 → POST /api/users/:id/profile 端点 → FastAPI Handler update_user_profile → 数据库写入操作的完整调用链，每条边都带有置信度标签。

在终端中直接使用命令行也可以查看同样的结果：

uv run forensic trace "UserProfile.save" --repo /path/to/repo

五份持久化分析报告

每次 forensic extract 执行后，会在 docs/codebase/ 下生成 5 份 Markdown 文件：

• MAP.md——代码库的结构地图，按中心度排列各模块
• HOTPATHS.md——热路径分析，包含每行的置信度混合比例（让你一眼看出哪些依赖是精确解析的、哪些是推测的）
• ARCHAEOLOGY.md——Git 历史深度分析：变更频率、核心贡献者占比、公交因子、共变簇、缺陷邻近度
• MENTAL_MODEL.md——原作者的思维模型文档，帮助新加入的开发者快速理解设计意图
• AGENT_BRIEF.md——≤5KB 的精简规则文件，含 Never/Always 规则和每条的置信度标签，可直接作为 CLAUDE.md 或 .cursorrules 使用

其中 AGENT_BRIEF.md 是一个精巧的设计——AI Agent 在打开代码库时会自动发现这个文件，从而获得关于项目的关键约束和最佳实践的即时指导。

置信度体系：诚实的知识边界

forensic-deepdive 最令人印象深刻的设计之一是其置信度体系。每条边和每个声明都带有一个标签：

• EXTRACTED（提取）：从 AST 或 git log 中确定性获取的事实。可靠度最高。
• INFERRED（推导）：启发式方法清晰分辨出的结论。高可信度但非确定。
• AMBIGUOUS（歧义）：存在多个候选，无法唯一确定。你会看到所有候选，而非静默猜测。

这一设计让 AI Agent 在使用分析结果时能够做出更明智的判断——当看到一个变量有 4 条 EXTRACTED 边和 1458 条 INFERRED 边时，Agent 知道大部分依赖关系是可信任的；而当出现大量 AMBIGUOUS 标记时，Agent 知道应该更谨慎地处理相关推理。

支持的九种语言

Python、C、Dart、Swift、TypeScript、JavaScript、Java、Go、Rust——涵盖当前主流的技术栈，且支持多语言混用仓库（如前端 TypeScript + 后端 Go + 移动端 Swift 的组合项目）。

与其他工具的对比

GitNexus 在功能上是最强的竞争对手，但其 PolyForm Noncommercial 许可证将商业用户完全排除在外——这正是 forensic-deepdive 的 Apache-2.0 许可策略所要抓住的市场空白。

集成到 AI Agent 工作流

Claude Code 集成

uvx forensic-deepdive extract /path/to/repo

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "forensic-deepdive": {
      "command": "uvx",
      "args": ["forensic-deepdive", "serve", "--repo", "/path/to/repo"]
    }
  }
}

Codex / Cursor / Windsurf 集成

统一的 MCP 配置方式，仅配置文件路径略有不同：

{
  "mcpServers": {
    "forensic-deepdive": {
      "command": "uvx",
      "args": ["forensic-deepdive", "serve", "--repo", "."]
    }
  }
}

适用场景

1. 重构前的变更影响分析：用 impact 工具模拟修改某个接口的影响范围
2. 新入项目 onboarding：阅读 MAP.md + MENTAL_MODEL.md 快速理解项目结构
3. Bug 定位：用 trace 工具跨层追溯调用链，快速定位问题根因
4. 代码审查辅助：context 工具提供被修改代码的完整上下文
5. 持续集成：将知识图谱的构建纳入 CI，确保 Agent 始终能获取最新结构信息

总结

Forensic-deepdive 并不是又一个代码索引工具——它将代码静态分析、Git 历史分析和 MCP 协议有机融合，为 AI 编码 Agent 提供了前所未有的代码理解能力。它的置信度体系解决了「AI 盲目信任分析结果」的问题，持久化 Markdown 产物让不具有 MCP 能力的 Agent 也能受益，而 Apache-2.0 许可证则保证了商业团队可以放心使用。

如果你在使用 AI Agent 重构大型项目时感到「Agent 总是不理解代码库的结构」，forensic-deepdive 可能就是你要找的答案。

相关链接

• GitHub 仓库
• PyPI 包
• MCP Registry