forensic-deepdive

forensic-deepdive

forensic-deepdive 让 AI 编码 Agent 能够深入了解陌生的代码库——它包含持久化知识图谱、MCP 服务和 5 份可长期保存的 Markdown 文档，让 Agent 不必在每次会话中都从头重新探索相同的架构。

uv tool install forensic-deepdive && forensic extract /path/to/repo

与众不同之处： 每条边和每项输出的声明都带有置信度标签—— EXTRACTED（确定性事实）/ INFERRED（通过启发式方法得出明确结论）/ AMBIGUOUS （存在多个候选项，会展示出来，而不是猜测）——让 Agent 在采取行动前就知道哪些内容值得信任。在这一类别中，其他产品都不会标注置信度。

为什么不选 GitNexus / CodeGraphContext / DeepWiki / Sourcegraph

	forensic-deepdive	GitNexus	CodeGraphContext	DeepWiki	Sourcegraph
许可证	Apache-2.0	PolyForm Noncommercial	MIT	专有（开源版本：MIT）	部分开源
持久化代码知识图谱	✅ LadybugDB	✅ LadybugDB	部分支持	❌	部分支持
MCP 服务	✅ 9 个组合工具	✅ 16 个工具	部分支持	❌	❌
逐边置信度分类	✅ EXTRACTED / INFERRED / AMBIGUOUS	❌	❌	❌	❌
将 Git 考古作为一等层	✅	❌	❌	❌	部分支持
可长期保存并提交的 Markdown 文档	✅ 5 个文件	部分支持	部分支持	✅（Wiki）	❌
Agent 洞察层（record_insight / recall_insights）	✅	❌	❌	❌	❌
多平台技能输出	✅ 10 个适配层	部分支持	部分支持	❌	❌
仅限本地（无需云服务）	✅ 同等支持	✅	✅	❌	❌

GitNexus 是这一类别中的绝对领先者——但其 PolyForm Noncommercial 许可证将所有商业用户拒之门外。 forensic-deepdive 是采用 Apache-2.0 许可证的 替代方案：具备同样的持久化图谱加 MCP 架构，此外还提供可信的置信度标签、Git 考古、持久化 Agent 记忆，以及 5 份 Markdown 文档，作为任何不支持 MCP 的 Agent 的备用方案——并且许可证也能通过雇主法务团队的审核。

它会生成什么

forensic-deepdive 可分析任意代码库（支持 9 种语言，兼容多语言项目），并生成：

1. 持久化嵌入式图谱，存放于 <repo>/.deepdive/graph.lbug，包含 File、Symbol、Module、Commit、Author、Endpoint 和 DbTable 节点，以及 DEFINES、MEMBER_OF、IMPORTS、CALLS、EXTENDS、IMPLEMENTS、TOUCHED_BY_COMMIT、AUTHORED_BY、CO_CHANGES_WITH，以及跨边界的 HANDLES / CALLS_ENDPOINT / ROUTES_TO / INJECTS / PERSISTS_TO 边。每条边都带有置信度标签（EXTRACTED / INFERRED / AMBIGUOUS）——不存在隐藏的启发式规则。单个 Endpoint 连接节点统一了五种跨边界协议（HTTP、MCP 工具、注册表分发、gRPC、消息传递/AMQP），因此前端调用可以跨越整个技术栈解析到后端处理程序，形成一条 ROUTES_TO 边。
2. 一个 MCP 服务（forensic serve），提供 9 个组合工具（impact、context、archaeology、flow、query、record_insight、recall_insights、visualize、trace），可供 Claude Code、Cursor、Codex、Continue、Cline、Windsurf 使用，也适用于任何其他支持 MCP 的 Agent。
3. 五份持久化 Markdown 文档，位于 <repo>/docs/codebase/ 下，每次提取时都会根据图谱重新生成：
   • MAP.md — 各内容的位置，按中心性排序。
   • HOTPATHS.md — 依赖热点，每行都带有置信度组合列，准确显示每个符号的解析情况。
   • ARCHAEOLOGY.md — 代码为何如此设计（Git 历史记录、按贡献占比排序的主要作者、巴士系数、协同变更集群、缺陷邻近度）。
   • MENTAL_MODEL.md — 原作者本会撰写的新员工入职文档。
   • AGENT_BRIEF.md — 不超过 5 KB 的明确 Never/Always 规则，每条规则都带有置信度标签。可直接用作任何项目的 CLAUDE.md。
4. 向目标代码库写入十个适配文件——4 个编辑器规则文件（CLAUDE.md、AGENTS.md、.cursor/rules/codebase.mdc、.continue/rules/codebase.md）、.claude/skills/codebase-{exploring,debugging,impact-analysis,refactoring,onboarding}/ 下的 5 个单一意图 Claude 技能，以及一个 .claude-plugin/plugin.json 清单。仅在文件不存在时写入——绝不会覆盖手动编辑的文件。
5. Agent 洞察层——record_insight / recall_insights MCP 工具默认由 <repo>/.deepdive/insights.jsonl 提供支持（零依赖、便于人类阅读、适合 Git 管理）。可选的 [graphiti] 扩展会在代码库规模达到 5 级中的 2 级阈值以上时，升级为时序知识图谱后端。

提取操作还会重新生成 ARCHITECTURE.md——一份展示跨边界图谱的系统级 Mermaid 视图（ROUTES_TO / INJECTS / PERSISTS_TO，并按置信度设置样式）。它是单独的人类验证界面（不属于五份契约文档，与 forensic visualize 和 serve --ui 一样）。可单独运行 forensic diagram --repo <repo> 重新生成。用它来检查图谱是否合理——这里的边有误，其他地方的边也会有误。

添加 --emit-vault，还可在 <output>/vault/ 下写入兼容 Obsidian 的知识库——每份文档都会添加 summary:/tags: frontmatter，交叉引用会变为 [[wikilinks]]，并生成 INDEX.md MOC 将它们关联起来（含 .obsidian/ 配置）。这是适合人类的本地优先第二大脑（图谱视图、反向链接），也适合 Agent 使用（无需打开文件即可按 summary: 分类处理，并可遍历索引）。此功能需主动启用，默认关闭。

状态

v0.10.0“The Upgrade Path”——一个完整性版本。v0.9 发布时一切正确，但随后运行的发现检查捕获到，--refresh-shims 从结构上就无法刷新一半目标，而 909 个测试全都通过了。原因不在于修复——而在于**整个测试套件中的每项测试都写入一个空目录，因此只有首次运行经过了测试。**除了新用户，其他所有人都在走未经测试的路径。

因此，0.10 几乎没有增加任何表层功能。它让已有的保证真正得到落实：在已有上一版本输出的仓库上运行 Deepdive，现在可以证明它会收敛（并且可以证明它不会碰你手动编辑过的文件）；extract 会在生成的 shim 过时时告知你，而不是等你自己知道有这个标志；过时的 examples/ 会导致 CI 失败，而不是等到发布过程中靠人工发现。新增：forensic extract --timings，显示各阶段的墙上时钟时间。

它还包含一项已取消的功能，而这才是更有价值的故事。原计划的性能优化针对 PageRank。动手前进行的性能分析显示，PageRank 在大型提取任务中仅占 0.04 %，而已经批处理的存储写入占 79–87 %。优化在编写之前就已被证伪——参见 docs/findings/v0.10/PROFILE.md。此前，我们误把确认已应用一种已知技术，当成了确认它速度很快。

引擎、图、契约层以及由 5 个产物和 9 个 MCP 工具组成的契约均与 0.9 保持不变；除版本页脚外，生成的内容逐字节一致。

⚠ 如果你安装了 0.8.0 或 0.9.0，并且 forensic serve 停止工作——原因就在这里。这些 版本声明了 mcp>=1.27.1，但没有上限。mcp 2.0.0 移除了 MCP 服务导入的 mcp.server.fastmcp，因此今天全新安装 0.8.0 或 0.9.0会解析到 mcp 2.0.0，并在导入时失败。我们的开发锁定文件固定了 1.27.1，因此所有本地检查都通过了，只有 CI 中干净环境下的 wheel 冒烟测试才能发现这个问题。修复方法：升级到 0.10.0 （它将 mcp 限定为 <2），或者自行固定为 mcp<2。这些版本的其他部分不受影响。

哪些结论已得到证实，哪些尚未得到证实——坦诚说明部分已移至 docs/findings/HONEST.md（内容不变，DEC-119）。简而言之：已证实在真实 Agent 自动发现的场景下可用；尚未证实能端到端、可衡量地加快自主解决问题的速度（受硬件条件限制）。这是一个辅助分析工具，我们不会夸大它的能力。

快速开始

# install from PyPI (puts `forensic` on PATH); or run ephemerally with uvx
uv tool install forensic-deepdive
forensic info            # banner + capability panel
forensic extract /path/to/repo

# …or from source for development:
git clone https://github.com/Dhevenddra/forensic-deepdive && cd forensic-deepdive
uv sync --all-extras

# what can it do? (banner + capability panel: artifacts, protocols, MCP tools, confidence legend)
uv run forensic info

# guided setup: analyze a repo, then wire it up as an MCP server
# (--yes takes every default: scriptable, and the one mode that needs no extra)
uv run forensic onboard --repo /path/to/repo

# run on any repo
uv run forensic extract /path/to/repo

# graph lands at <repo>/.deepdive/graph.lbug
# 5 markdown artifacts at <repo>/docs/codebase/
# 10 shims at <repo>/.claude/, .cursor/, .continue/, root

# trace a cross-stack feature slice (frontend call -> endpoint -> handler -> tail)
uv run forensic trace <symbol> --repo /path/to/repo

# interactive query REPL over one held-open store (needs the [interactive] extra)
# bare text = natural-language query (no LLM) · :cypher <q> = raw Cypher · :help · Ctrl-D exits
uv run forensic repl --repo /path/to/repo

# full-screen terminal graph browser — the loopback-free sibling of serve --ui
# 1/2/3 = Symbols/Files/Endpoints · type to filter · c/e/l = confidence/edge/language · Enter = context · i/f = impact/flow
uv run forensic browse --repo /path/to/repo

# the session shell: all of the above over ONE held-open graph, with history
# in-session: extract · query · trace · impact · flow · diagram · browse · onboard · serve
uv run deepdive --repo /path/to/repo

# query the graph as an MCP server (point it at the analyzed repo)
uv run forensic serve --repo /path/to/repo

# inspect every repo you've analyzed
uv run forensic list

从 PyPI 安装

已发布为 forensic-deepdive—— 无需克隆：

uv tool install forensic-deepdive        # puts `forensic` on PATH
forensic extract /path/to/repo

# …or run ephemerally, no install:
uvx forensic-deepdive extract /path/to/repo

可选额外依赖：uv tool install "forensic-deepdive[semantic]"（离线 ONNX 自然语言查询）、[interactive]（forensic repl 查询控制台、forensic browse TUI 图浏览器和 deepdive 会话 Shell）、[openapi]（YAML 规范解析）、[graphiti]（时序洞见后端）。

从 0.8 升级

使用 --refresh-shims 重新运行一次 extract。.claude/、.cursor/ 和 .continue/ 下生成的 shim 和技能文件仅在不存在时才会写入，因此直接重新提取会保留 0.8 时代的副本；其中两个技能文件仍引用了 0.9 已移除的内部决策 ID：

forensic extract /path/to/repo --force --refresh-shims

只有 Deepdive 生成的文件会被重写。你手动编辑过的 shim 绝不会被修改。 如果你没有使用 uv，也可以运行 pip install forensic-deepdive。

将其用作 MCP 服务

forensic serve 是一个基于 stdio 的 MCP 服务，可向任何兼容 MCP 的 Agent（Claude Code、Cursor、VS Code/Copilot、Codex、Continue、Cline、Windsurf）开放这 9 个组合工具。先构建一次图谱（forensic extract <repo>），然后配置服务。以下有三种方式，按简便程度排序：

1. Claude Code 插件（可自托管的市场，无需经过 PyPI）：

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

2. 从 MCP Registry 安装——该项目已编入索引，名称为 io.github.Dhevenddra/forensic-deepdive，因此支持注册表的客户端和发现平台 （PulseMCP、MCPJungle、VS Code @mcp 索引）都可以直接找到并安装。

3. 手动配置——使用 forensic mcp-config 生成客户端配置片段，或粘贴：

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

各客户端的复制粘贴配置块（Cursor、VS Code、Codex，以及 GUI 中找不到 uvx 的常见问题） 见 docs/install.md。

支持的 9 种语言

Python、C、Dart、Swift、TypeScript、JavaScript、Java、Go、Rust。

9 个 MCP 工具

工具	功能
impact(symbol, depth, direction, min_confidence)	对 CALLS 边执行按深度分桶、可按置信度筛选的影响范围 BFS。
context(symbol)	一次调用获取全套信息：定义 + 调用方 + 被调用方 + 父级/同级/成员 + 继承/实现关系 + 最近提交 + 主要作者 + 最近洞见。
archaeology(file_or_symbol)	变更频率、主要作者及其占比、公交因子、共同变更集群、缺陷邻近度、最近提交。
flow(entry_point, max_depth)	对 CALLS 执行带环路检测的 DFS。
query(cypher | natural_language)	原始 Cypher，或混合自然语言检索（FTS5/BM25 + 结构化图谱信号 + 可选的离线语义检索，经 RRF 融合并整形），附带每条命中项的来源信息 + 置信度。
record_insight(symbol, claim, evidence, verified_by)	保存经验证的学习成果。
recall_insights(symbol, since, limit)	按存储洞见中的子字符串匹配，按时间从新到旧返回。
visualize(target, format, depth, max_nodes, ...)	生成符号/文件邻域（或 central）的范围受限 Mermaid 图；边线的虚实样式表示置信度。
trace(symbol, direction, max_depth)	通过 Endpoint 连接节点追踪跨栈功能切片：downstream 沿前端调用 → CALLS_ENDPOINT → 端点 → HANDLES → 处理程序 → CALLS 链路追踪；upstream 回答“谁调用了此端点”。

每个工具的描述均不超过 200 个 token，因此这 9 个工具的总量可轻松控制在 Anthropic 每轮技能元数据预算范围内。

置信度分类

每条边和每项输出的声明都带有 EXTRACTED / INFERRED / AMBIGUOUS 标记：

• EXTRACTED — 根据 AST 或 git log 确定性提取。事实。
• INFERRED — 通过启发式方法明确解析（导入图遍历、接收器类型推断、跨文件唯一的同名候选项）。可信度高，但属于推导结果。
• AMBIGUOUS — 找到多个候选项；解析器无法消除歧义。你可以看到每个候选项，而不是得到一个悄无声息的猜测。

HOTPATHS 会显示每行的置信度构成列，让你一眼看出 Logger（4 个 EXTRACTED + 1458 个 INFERRED——大多明确）和 ChatToolResponse（449 个 AMBIGUOUS——跨文件同名冲突）的区别。

诚实模式（纯静态、零 LLM、零网络）

forensic extract 可以端到端运行，无需 ANTHROPIC_API_KEY、无需 OPENAI_API_KEY、无需 Ollama、无需网络。Graphiti 是可选功能，需安装 PyPI 的 [graphiti] extra，且仓库规模达到 5 项条件中的至少 2 项（≥50 k LOC、≥25 位贡献者、仓库存在时间 ≥18 个月、过去 12 个月 ≥200 个 PR、≥100 个带讨论的问题）。JsonlInsightStore 始终可用，是基础保障。

（GitNexus/CodeGraphContext/DeepWiki/Sourcegraph 的对比表放在上方——它是重点，而不是脚注。）

本地开发

git clone https://github.com/Dhevenddra/forensic-deepdive
cd forensic-deepdive
uv sync --all-extras
uv run forensic --version
uv run pytest -x          # 1000+ tests at v0.10.0
uv run ruff check src/ tests/
uv run forensic extract tests/fixtures/tiny_fixture

进行更改前，请阅读 CLAUDE.md、DECISIONS.md（81 条有效 DEC）和 PROGRESS.md。本仓库以身作则，实践自身的模式：每次会话都从 CLAUDE.md 中的协议开始，每项架构决策都会记录为 DEC-N 条目，产物名称约定（MAP、HOTPATHS、ARCHAEOLOGY、MENTAL_MODEL、AGENT_BRIEF）也是公共 API 的一部分。

致谢

• Aider（Paul Gauthier）：感谢其基于 Tree-sitter 的 PageRank 仓库映射模式。算法在注明出处的基础上移植；我们不依赖 aider 包。
• Graphify（safishamsi）：感谢其 EXTRACTED / INFERRED / AMBIGUOUS 置信度分类法。该分类法通过 DEC-015 产品化，并应用于每个输出器。
• GitNexus（abhigyanpatwari）：感谢其多仓库注册表模式（~/.deepdive/registry.json、DEC-018）、复合 MCP 工具形式，以及为本项目凸显 Apache-2.0 差异化价值提供的许可切入点。
• Kuzu（现已由 Apple 归档）：感谢其嵌入式图引擎；LadybugDB：感谢其仍在维护的社区分支，v0.2 基于该分支发布（DEC-013）。
• Zep / getzep：感谢 Graphiti——为上述阈值以上的洞察后端提供支持的时态知识图谱（DEC-019）。
• Anthropic：感谢其 Skills 格式、Claude Code，以及让这一整套产品形态成为可能的 MCP 协议。
• Astral：感谢其提供的 uv 和 ruff。
• Repomix（yamadashy）：感谢其最初在 v0.1 中将仓库展平的模式；该模式现在已降级为 --legacy-repomix（DEC-017），但仍可用于旧版场景。

参与贡献

欢迎贡献——请参阅 CONTRIBUTING.md，了解开发环境设置、验证关卡和架构不变量（5 项产物约定、Endpoint 核心支柱、置信度分类法）。提交贡献即表示你同意自己的工作采用 Apache-2.0 许可。

许可证

Apache-2.0。请参阅 LICENSE。

如果你重新分发、修改或基于本项目进行构建，则须遵守 Apache-2.0 条款：你必须保留版权声明、LICENSE 文本和 NOTICE 文件，并注明所做的任何更改（许可证 §4）。必须注明出处；本项目版权所有 2026 Dhevenddra（请参阅 NOTICE）。LICENSE 附录中的模板标题（Copyright [yyyy] [name of copyright owner]）是用于将许可证应用到源文件的模板——本身并非强制要求，且 LICENSE 文件会原样保留为官方 Apache-2.0 文本。