deep-review 1.0.0

DeepReview

【使用手册-命令行】

install：安装

# 首次安装
pip install deep-review

# 安装：支持平台 codex, claude, claude-code, codebuddy, cursor, windsurf, zed, continue, opencode, antigravity, gemini-cli, qwen, kiro, copilot, copilot-cli
dr install --platform claude-code

uninstall：卸载

# 解绑平台 MCP 注册
dr uninstall --platform claude-code
# 全删（skills+hooks+用户目录+图数据）
dr uninstall

# 安全相关参数
dr uninstall --dry-run                # 只看计划,什么都不动
dr uninstall --all-repos              # dr uninstall + 所有注册的仓库

build：构建

• ① 解析：用 Tree-sitter 把源码读进来，把代码里的"实体"和"关系"抽出来写进数据库。
• ② 签名 + FTS：给 ① 里的节点补上"可被搜索"的元数据。
  • 签名（signature）：给每个函数/类算一个规范化签名串（参数、返回类型等），存进 nodes.signature 列。这样查函数时能看到它的形参签名。
  • FTS 全文索引：建一张 nodes_fts 虚拟表（SQLite FTS5），把节点的名字、限定名、文件路径、签名都塞进去做倒排索引。
• ③ 社区：在 ① 的关系网基础上跑图算法，挖出更高层的结构。
  • 执行流（flow）：从某个入口点（HTTP handler、CLI 命令、测试函数等）出发，顺着 CALLS 边一路追踪，还原出"一次调用会经过哪些函数"的完整路径，并算关键度评分。
  • 社区（community）：用 Leiden 算法把关系紧密的节点聚成一个个"社区"——通常对应代码里的模块/子系统边界。每个社区算内聚度、主导语言、大小等。

# 全量构建：一次性执行解析、签名+FTS、社区/执行流，构建速度很快，后续用 update 增量维护即可。
dr build

# 构建同时刷新嵌入索引（启用语义搜索）
dr build --embedding-provider local --embedding-model all-MiniLM-L6-v2

update：更新

HEAD~1  ──►  HEAD (最新)  ◄───────  暂存区  ◄───────  工作区
  (历史)        (仓库)      commit (Staged)   add   (Unstaged)
                  │                 │                  │
                  └─── git diff ────┴──────────────────┘ (默认 diff 工作区与 HEAD/暂存区)

# 解析从上次构建到现在的所有变更文件，一次性追平。不用关心中间过了几个 commit。
dr update
# 一个命令同时 刷新图谱 + 看这次变更影响了什么、省了多少 token。
dr update --brief

# 想确认"省 token"的估算准不准，用真实分词器校准，需在 .env 指定分词器。
dr update --brief --verify

#  base = 比较或合并时的参照点，可以是分支、tag、commit hash、HEAD~1
# 解析"本地相对 origin/main 有差异的文件"——也就是你本地正在改、还没推的那些。
dr update --base origin/main

# update 默认不更新向量。 它只更新图谱结构（节点/边/FTS/社区/执行流），完全不动 embeddings 表。
# 是否开启语义（首次）：关键词匹配，同义词、接受自然语言查询、跨语言匹配。
dr embed --provider local
# 启用了嵌入（embed），日常维护必须带这俩 flag，否则图谱结构和语义索引会不同步。
dr update --embedding-provider local --embedding-model all-MiniLM-L6-v2

支持两种 provider：

• local（默认）：sentence-transformers，离线，模型经 DR_EMBEDDING_MODEL 或 --model 指定。
• openai：任何遵循 OpenAI /v1/embeddings 的端点。配置好后：

  dr embed --provider openai
  dr update --embedding-provider openai --embedding-model text-embedding-3-small
  

  CLI/MCP 的 --provider/--model 可覆盖 .env；未传则回落 .env。

detect-changes：变更分析

命令	输出形式	基准	风险评分	Token 估算
dr detect-changes	完整 JSON	HEAD（默认）	基础	附带估算
--churn	同上	同上	+ 变更频率项	同上
--base 分支	同上	origin/main	基础	同上
--brief	紧凑面板	HEAD	摘要	估算面板
--brief --verify	紧凑面板	HEAD	摘要	+ tiktoken 真实验证

dr detect-changes
# 给风险评分加一个“这文件最近改得勤不勤”的加权项（最多 +0.15）。
dr detect-changes --churn
dr detect-changes --base origin/main
dr detect-changes --brief
dr detect-changes --brief --verify
# 也支持 --repo PATH

detect-changes vs update—— 选哪个？

• detect-changes --brief：只读。询问"我当前变更对现有图谱的影响是什么？快速（约 1 秒）。当图谱已是最新时使用（如果安装了 hooks，默认如此）。
• update：先将变更文件重新解析到图谱，然后在末尾运行相同分析。在 rebase 后、大型变更集后，或任何怀疑图谱过时时使用。

watch：半自动更新

# 后台监听文件变更，一有改动自动增量更新，Ctrl+C 停止。适合开发过程中挂着。
dr watch
# 监听同时增量刷新嵌入索引
dr watch --embedding-provider local --embedding-model all-MiniLM-L6-v2

status、visualize、wiki

# 查看图谱信息
dr status
dr status --json     # 输出单个机器可读的 JSON 对象（便于脚本消费）

# HTML 可视化代码知识图谱
dr visualize
--serve：生成 HTML 后，起一个本地静态 HTTP（localhost:8765），方便加载本地资源
--format：html、json、cypher、svg、graphml、obsidian

# 从代码知识图谱的社区结构生成一套可导航的 Markdown 文档 wiki
dr wiki

register：多仓库

# 注册仓库
dr register <path> [--alias name]
# 从注册表移除
dr unregister <path_or_alias>
# 列出已注册仓库
dr repos

daemon：多仓库监听

# 带--foreground：fork 到后台运行，脱离终端，关闭 shell 还在
dr daemon start [--foreground]
# 停止守护进程
dr daemon stop
# 重启
dr daemon restart [--foreground]
# 显示状态和仓库列表
dr daemon status
# 仓库加进守护进程
dr daemon add <path> [--alias NAME]
# 从配置移除仓库
dr daemon remove <path_or_alias>

# --repo ALIAS：看指定仓库的日志（<log_dir>/<alias>.log）；不带则看主守护进程日志（daemon.log）。
# --lines N / -n：显示最后 N 行（默认 50）。
# --follow：持续追踪日志输出（tail -f）。
dr daemon logs [--repo ALIAS] [--lines N] [--follow]

query、impact、search、flow：查询

# 查关系：callers_of / callees_of / imports_of / importers_of / children_of / tests_for / inheritors_of / file_summary
dr query callers_of my_func
dr query tests_for MyService
dr query file_summary src/api.py

# 从指定变更文件出发，沿边做 BFS 找受影响的下游节点，输出"爆炸半径"。
dr impact --files src/api.py --depth 2 --max-results 500 --base HEAD

# 按自然语言或关键字定位"大概是哪个函数/类"，省去 Grep 整库扫。
dr search "登录鉴权" --kind Function --limit 20

# 列出"最重要的调用路径"，定位系统热点入口。
dr flows --sort criticality --limit 50 --kind http
# 看某条具体调用链的逐步展开（含源码），等价于"这条请求会经过哪些函数"
dr flow --id 3 --source           # --source 带上源码片段

# 列出代码库里"自然分成的子系统"，看模块边界是否合理。
dr communities --sort size --min-size 3
# 看某个子系统具体包含哪些函数/类。
dr community --name "auth-module" --members

# 架构概览
dr architecture --detail-level minimal   # 或 standard（更细）

# 定位"该拆分的长函数/大类"，做重构排期。
dr large-functions --min-lines 50 --kind Function --path src/ --limit 50

refactor：重构预览

# 重命名前的"影响点清单"预演。
dr refactor rename --old-name oldFn --new-name newFn --kind Function
# 圈定可安全删除的代码。
dr refactor dead_code --kind Function
# 让图谱主动给"哪里该重构"的提示。
dr refactor suggest

dead-code：死代码检测

# 找没有任何调用方、也没有测试引用的函数 / 类
dr dead-code
dr dead-code --kind Class/Function --file-pattern src/legacy --limit 100
dr dead-code --json    # 输出机器可读 JSON 数组

静态分析对动态调用有盲区，删前必须人工复核（框架自动分派、注册式入口等间接调用）。

【使用手册-SKILL】

总览

Skill	一句话定位	典型场景数
/dr-build-graph	构建或更新知识图谱，等价于 dr build	2
/dr-explore-codebase	从整体指标→架构→社区→语义搜索，理解陌生仓库	2
/dr-review-changes	审查当前工作区变更（基线 HEAD），结构化风险报告	2
/dr-review-delta	仅审查工作区未提交变更（变更+2跳邻居），极省 token	2
/dr-review-pr	审查整个 PR/分支 vs main，全面但聚焦高风险文件	2
/dr-debug-issue	搜索→追踪调用链→执行流→近期变更→影响半径，系统性调试	2
/dr-refactor-safely	重构前看依赖关系，避免改一个名字炸一片	2

三个审查 skill 的区别

	dr-review-changes	dr-review-delta	dr-review-pr
范围	当前工作区变更	工作区未提交增量	整个 PR/分支 vs main
基线	HEAD	HEAD	main
token 策略	标准结构化审查	极省（变更+2跳邻居）	全面但聚焦高风险文件
适用	"我改的这些代码 OK 吗"	"快速过一眼工作区改动"	"这个 PR 能不能合并"

---

各 Skill 典型场景

/dr-build-graph

构建或更新本仓库的知识图谱。图谱会在编辑/提交时通过钩子自动更新，因此手动构建很少需要。

1. 首次接手仓库：刚 clone 一个项目，还没有图谱。跑一次全量构建，把源码里的函数、类、调用关系、依赖关系全部解析进本地数据库，后续所有审查、调试、探索都建立在这个基础之上。
2. 大重构或图谱脱节后追平：删除了一整个目录、合并了一长串提交，或文件监听没跑起来导致图谱落后于代码。用增量更新只重新解析变更过的文件，把图谱追平到当前状态，避免全量重建的开销。

/dr-explore-codebase

理解陌生代码库的导航工具，从宏观到微观逐层下钻。

1. 接手陌生仓库：第一次进入项目，完全不知道它是干什么的。先看整体规模和架构分层，再定位到核心入口和模块边界，快速建立全局心智模型，避免在细节里迷路。
2. 发现隐藏的耦合与复杂度风险：找出跨模块的意外依赖、一旦改动就影响大片代码的桥接节点，以及最复杂的巨型代码——这些都是改动时必须格外小心的高风险区。

/dr-review-changes

审查当前工作区的未提交变更，给出带风险评分的结构化报告。

1. 提交前的自查：本地改了一批代码，准备提交。先看这次变更整体风险多高、影响了哪些执行路径、关键改动有没有测试覆盖，再决定能不能放心提交，避免把问题带进主干。
2. 甄别机械变更与小改大影响：大规模重命名后几十个文件都变了，需区分真正的逻辑变更与无实质影响的副产品；反之，只改了几行看似无害的代码却波及十几条路径，要提前预警。两种极端都靠影响半径来判定。

/dr-review-delta

只审查最近一次提交以来的增量变更，是最省 token 的审查方式。

1. 快速过一眼最近一次提交：刚提交完一个小改动，想低成本确认没遗漏问题。只把变更代码和它直接相关的邻居代码送给模型审查，而不是读整个仓库，几秒内拿到「风险+问题+影响范围」的紧凑报告。
2. 聚焦审查单个改动点及其波及面：只改了某处代码，自动圈定它以及调用它、被它调用的相关代码，只审查这一小片切片——包括继承关系是否破坏、调用方是否需同步调整，不被无关代码干扰。

/dr-review-pr

审查整个 PR 或分支相对 main 的全部变更，全面但聚焦高风险区域。

1. 合并前的完整审查：PR 涉及多个文件、多次提交，需要判断能不能合并。拿到整个 PR 的变更全貌、算出影响半径、对高风险改动逐一检查测试覆盖，输出「风险评级/逐文件问题/缺失测试/合并建议」的完整报告。
2. 破坏性变更核对与测试缺口门禁：重命名核心接口后确认所有调用方都已同步更新，主动搜索可能遗漏的相关代码；同时对所有变更逐一检查测试覆盖，把未覆盖项作为合并的硬门禁，避免合并后下游大面积报错。

/dr-debug-issue

系统性调试工具，从搜索定位到调用链追踪到近期变更核查，一条龙排查问题。

1. 报错堆栈定位根因：用户反馈某个操作报错。从报错点出发顺着调用链一路往下追，看完整执行路径上哪一步出了问题，定位真正的根因而非表面症状；若是回归 bug，沿依赖关系找出「改了 A、却炸了依赖 A 的 B」这类间接回归。
2. 新问题与性能问题的排查入口：完全不知道问题出在哪时，先拿全局视图看哪些执行流可能相关，再双向追踪缩小范围；性能变慢时，展开完整调用链找出不必要的中间调用、重复解析或绕远的链路。

/dr-refactor-safely

重构前的依赖分析工具，避免「改一个名字炸一片」。

1. 安全重命名与拆分巨型代码：重命名被多处调用的符号时，基于真实调用关系精确找到所有调用点，预览确认后一次性替换，既不漏调用方也不误改注释同名词；拆分超大代码前先看它被多少处依赖、拆分会不会破坏关键路径，把高风险重构变成有把握的动作。
2. 清理死代码与结构整理：找出没有被任何地方引用的代码，但静态分析对动态调用有盲区，必须人工复核排除框架自动分派、注册式入口等间接调用，避免误删；对「某段代码应搬到另一模块」的建议需人工判断收益，机械执行不一定划算。

通用规则：每个 skill 都遵循「先拿最小全局上下文 → 全程用最精简的输出 → 少量工具调用、极少 token」的省 token 原则。

【注意事项】

影响分析

从种子节点（变更文件的内容）出发进行 BFS：

1. 种子 = 变更文件中的所有限定名称
2. 对边界中的每个节点：
   • 追踪前向边（该节点影响的内容），下游影响（调用变更代码的内容）
   • 追踪反向边（依赖该节点的内容），上游上下文（变更代码所依赖的内容）
3. 展开至最多 max_depth 跳（默认：2）
4. 收集所有到达的节点作为"受影响节点"

忽略模式

默认情况下，以下路径被排除在索引之外：

__pycache__/**           *.pyc              .venv/**
venv/**                  dist/**            build/**
.next/**                 target/**          *.min.js
*.min.css                *.map              *.lock
package-lock.json        yarn.lock          *.db
*.sqlite                 *.db-journal

要添加自定义模式，在仓库根目录创建 .deep-reviewignore 文件（语法与 .gitignore 相同）：

generated/**
vendor/**
*.generated.ts

在 git 仓库中，索引基于已追踪文件（git ls-files），因此被 gitignore 的文件会自动跳过。当 git 不可用或需要排除已追踪文件时，使用 .deep-reviewignore。