deep-review 1.0.1

【使用手册-命令行】

install：安装

# 首次安装
pip install deep-review

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

# 可选：本地向量嵌入，支持语义检索；如果采用 openai 协议则无需安装
pip install deep-review[embeddings]

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

# 构建同时刷新嵌入索引（启用语义搜索，需在 .env 配置）
dr build --embed

update：更新

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

# 更新上次 dr update 或 dr build 到现在的所有变更文件，一次性追平，不关心中间 commit。
dr update

# 一个命令同时 刷新图谱 + 看这次变更影响了什么、省了多少 token。
dr update --brief

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

# base = 比较或合并时的参照点，可以是分支、tag、commit hash、HEAD~1
# origin/main: A --- B --- C
#                       \
# feature-branch:         D --- E（dr update） --- F (你的当前分支，HEAD 在这里)
# dr update：只分析 F 这一个 commit 的变更
# dr update --base origin/main：分析 D、E、F 三个 commit 的所有变更（相对于主分支的全部差异）
dr update --base origin/main

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

支持两种 provider：

• local（默认）：sentence-transformers，离线。
• openai：任何遵循 OpenAI 协议。

dr embed --provider openai
dr update --embed

detect-changes：变更分析

detect-changes vs update—— 选哪个？

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

命令	输出形式	基准	风险评分	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

watch：半自动更新

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

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】

/dr-review-cnc（核中核）

基于代码变更 diff 与影响半径分析，按 CNC 编码规则做增量、省 token 的结构化代码审查。

/dr-review-delta（核心）

上下文打包型：一次调用返回 子图+源码+影响半径+审查指引，token 集中投放。无量化评分，只有粗粒度风险分级，适合日常快速增量审查。

/dr-review-changes（核心）

量化分析型：行级 diff 映射 + 6 因子风险评分 + 优先级排序，产出一份可做合并决策的风险报告。调用多但每次精，适合正式审查，做合并决策。

/dr-review-pr（核心）

全面终审型 PR 审查（对比主干、读全源码、追调用者、找遗漏代码、逐文件报告，适合"合并前把这条分支彻底审一遍"）

/dr-debug-issue（高阶）

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

/dr-refactor-safely（高阶）

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

/dr-build-graph（不常用）

构建或更新本仓库的知识图谱。等同于 dr build

/dr-explore-codebase（不常用）

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

【注意事项】

影响分析

从种子节点（变更文件的内容）出发进行 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。