Metadata-Version: 2.5
Name: deep-review
Version: 1.0.1
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: python-dotenv<2,>=1.0
Requires-Dist: pyyaml<7,>=6.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'
Provides-Extra: embeddings
Requires-Dist: numpy<3,>=1.26; extra == 'embeddings'
Requires-Dist: sentence-transformers<6,>=3.0.0; extra == 'embeddings'
Description-Content-Type: text/markdown

### 【使用手册-命令行】
#### install：安装
```bash
# 首次安装
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：卸载
```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

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

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

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

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

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



```bash
# 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 协议。

```bash
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 真实验证 |


```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
```

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

#### 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】
#### <font style="color:#601BDE;">/dr-review-cnc（核中核）</font>
基于代码变更 diff 与影响半径分析，按 CNC 编码规则做增量、省 token 的结构化代码审查。

#### <font style="color:#601BDE;">/dr-review-delta（核心）</font>
上下文打包型：一次调用返回 子图+源码+影响半径+审查指引，token 集中投放。无量化评分，只有粗粒度风险分级，适合日常快速增量审查。

#### <font style="color:#601BDE;">/dr-review-changes（核心）</font>
量化分析型：行级 diff 映射 + 6 因子风险评分 + 优先级排序，产出一份可做合并决策的风险报告。调用多但每次精，适合正式审查，做合并决策。

#### <font style="color:#601BDE;">/dr-review-pr（核心）</font>
全面终审型 PR 审查（对比主干、读全源码、追调用者、找遗漏代码、逐文件报告，适合"合并前把这条分支彻底审一遍"）



#### <font style="color:#D22D8D;">/dr-debug-issue（高阶）</font>
系统性调试工具，从搜索定位到调用链追踪到近期变更核查，一条龙排查问题。

#### <font style="color:#D22D8D;">/dr-refactor-safely（高阶）</font>
重构前的依赖分析工具，避免「改一个名字炸一片」。



#### /dr-build-graph（不常用）
构建或更新本仓库的知识图谱。等同于 `dr build`

#### /dr-explore-codebase（不常用）
理解陌生代码库的导航工具，从宏观到微观逐层下钻。

### 【注意事项】
#### 影响分析
从种子节点（变更文件的内容）出发进行 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`。

