Metadata-Version: 2.5
Name: deep-review
Version: 1.0.0
Summary: Local-first knowledge graph for token-efficient code review through MCP and CLI
Project-URL: Homepage, https://github.com/shao-ssq/code-review-graph
Project-URL: Repository, https://github.com/shao-ssq/code-review-graph
Project-URL: Documentation, https://github.com/shao-ssq/code-review-graph/blob/main/docs/INDEX.md
Project-URL: Changelog, https://github.com/shao-ssq/code-review-graph/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/shao-ssq/code-review-graph/issues
Author-email: shaoqisun <1966799809@qq.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-coding-tools,code-review,knowledge-graph,mcp,tree-sitter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: fastmcp<4,>=3.2.4
Requires-Dist: igraph>=0.11.0
Requires-Dist: jedi>=0.19.2
Requires-Dist: mcp<3,>=1.0.0
Requires-Dist: networkx<4,>=3.2
Requires-Dist: numpy<3,>=1.26
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: sentence-transformers<6,>=3.0.0
Requires-Dist: tomli<3,>=2.0.0; python_version < '3.11'
Requires-Dist: tree-sitter-language-pack<1,>=0.3.0
Requires-Dist: tree-sitter<1,>=0.23.0
Requires-Dist: watchdog<7,>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy<3,>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=0.23; extra == 'dev'
Requires-Dist: pytest-cov<8,>=4.0; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.3.0; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown


## DeepReview
### 【使用手册-命令行】
#### install：安装
```bash
# 首次安装
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：卸载
```bash
# 解绑平台 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 算法把关系紧密的节点聚成一个个"社区"——通常对应代码里的模块/子系统边界。每个社区算内聚度、主导语言、大小等。

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

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

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

```bash
# 解析从上次构建到现在的所有变更文件，一次性追平。不用关心中间过了几个 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` 的端点。配置好后：
  ```bash
  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 真实验证 |


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

#### status、visualize、wiki
```bash
# 查看图谱信息
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：多仓库
```bash
# 注册仓库
dr register <path> [--alias name]
# 从注册表移除
dr unregister <path_or_alias>
# 列出已注册仓库
dr repos
```

#### daemon：多仓库监听
```bash
# 带--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>
```

```bash
# --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：查询

```bash
# 查关系：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：重构预览
```bash
# 重命名前的"影响点清单"预演。
dr refactor rename --old-name oldFn --new-name newFn --kind Function
# 圈定可安全删除的代码。
dr refactor dead_code --kind Function
# 让图谱主动给"哪里该重构"的提示。
dr refactor suggest
```

#### dead-code：死代码检测
```bash
# 找没有任何调用方、也没有测试引用的函数 / 类
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. 收集所有到达的节点作为"受影响节点"

#### 忽略模式
默认情况下，以下路径被排除在索引之外：

```plain

__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` 相同）：

```plain
generated/**
vendor/**
*.generated.ts
```

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