企业官网建设流程全解析

AI 编码工具为了审查一次改动，常常要重新读取代码库的大部分内容。code-review-graph用 Tree-sitter 构建代码的结构图，增量保持更新，并通过 MCP 提供紧凑的上下文，让助手只读取改动涉及的文件。

快速开始

pip install code-review-graph # or: pipx install code-review-graph code-review-graph install # detect installed AI coding tools and configure each one code-review-graph build # parse the codebase

install会检测你安装了哪些 AI 编码工具，为每个工具写入一条 MCP 服务器配置，在平台支持的地方安装钩子和技能，并把图谱说明加入平台的规则文件。在 Poetry 或 uv 项目环境中，MCP 配置使用poetry run或uv run；当 PATH 上有uvx时使用uvx code-review-graph serve；否则使用当前的 Python 解释器。安装后请重启编辑器或工具。

只配置一个平台时，给--platform传入codex、claude-code、cursor、windsurf、zed、continue、opencode、antigravity、gemini-cli、qwen、kiro、qoder、copilot、copilot-cli、codebuddy或hermes之一：

code-review-graph install --platform cursor code-review-graph install --platform codebuddy

配置文件的位置列在 docs/USAGE.md 中。需要 Python 3.10+。

uninstall会从 Git 或 SVN 工作树中移除 CRG 自己写入的文件和配置项，不动其他 MCP 服务器、钩子、技能和 JSONC 注释。在工作树内的任意位置运行即可。共享配置文件采用原子替换，写入失败时原文件保持完整。

code-review-graph uninstall --dry-run # preview only code-review-graph uninstall # preview, confirm, apply code-review-graph uninstall --yes # apply without prompting code-review-graph uninstall --all-repos # also clean every registered repository code-review-graph uninstall --keep-data # remove integrations, keep graph databases code-review-graph uninstall --keep-user-configs --repo . # this project only

然后打开项目，对助手说：

Build the code review graph for this project

构建时间随仓库规模增长；一个约 3,000 个文件的仓库冷构建约需 40 秒（实测）。之后由钩子和 watch 模式保持图谱更新。如果部分文件解析失败，结果状态为partial并在摘要中列出这些文件；CLI 还会在 stderr 上打印一行Warning:，这些文件保留原有的图谱记录。

工作原理

仓库通过 Tree-sitter 解析为 AST，并以节点（函数、类、导入）和边（调用、继承、测试覆盖）的形式存为图谱。审查时查询图谱，得到助手需要读取的最小文件集合。

影响半径分析

文件变更时，图谱会追踪所有可能受影响的调用者、依赖方和测试。助手读取这些文件，而不是扫描整个项目。

增量更新

钩子、pre-commit 钩子和 watch 模式都会触发增量更新。更新时对变更文件做 diff，沿图谱的导入边和调用边找出依赖方，并只重新解析 SHA-256 哈希发生变化的文件。在一个约 3,000 个文件的项目（django）上，修改两个文件后沿钩子路径重新索引约需 2.5 秒，其中约 1.4 秒是进程启动；空更新只花这段启动时间。参见增量更新延迟。

整个代码库，还是有的放矢的回答？

图谱不会把整个语料喂给模型，而是返回按问题裁剪的切片。在 2026-08-02 对本仓库84bde354的快照中，208,821 个源码 token 变成每个问题约 3,190 个 token。此后仓库增长了很多，所以今天这两个数字都更大。

语言覆盖与笔记本

解析器提取函数、类、导入、调用点、继承和测试：有语法的地方用 Tree-sitter，其他地方用有针对性的回退解析。支持范围：Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、VB.NET、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、shell 脚本、Elixir、Zig、PowerShell、Julia、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Terraform/OpenTofu（.tf；其他.hcl文件只生成文件节点）、Ansible YAML（playbook、role、task）、Spring Boot 应用配置（application.properties、application.yml、application.yaml及其application-<profile>变体；只记录键名和值的类型，绝不记录值）、Vue/Svelte 单文件组件、Astro 文件（用 TypeScript 语法解析）、Jupyter 和 Databricks 笔记本（.ipynb），以及 Perl XS 文件（.xs）。其他 YAML 和其他.properties文件不被当作源代码。

PHP 项目还会得到仓库范围内的 Composer PSR-4 解析、Blade 模板引用，以及在源码中出现明确的框架导入、模型继承和接收者证据时生成的 Laravel Route 与 Eloquent 边。

Java 项目会得到 Spring 依赖注入的调用解析、请求端点与 WebFlux 路由、定时触发器、应用事件的发布者到监听者的边，以及 Temporal 工作流与活动的边。每个解析器都在解析之后运行，并且需要被注入的字段、发布的事件或工作流 stub 在仓库中可见。

添加你自己的语言

如果你的仓库使用了解析器尚未覆盖的语言，在.code-review-graph/中添加一个languages.toml，把文件扩展名映射到tree_sitter_language_pack中自带的任意语法，并给出函数、类、导入和调用的节点类型：

[languages.erlang] extensions = [".erl"] grammar = "erlang" function_node_types = ["function_clause"] class_node_types = ["record_decl"] import_node_types = ["import_attribute"] call_node_types = ["call"]

提取工作由通用的 tree-sitter 遍历器完成。内置语言不能被覆盖。schema、校验规则和完整示例见 docs/CUSTOM_LANGUAGES.md。

在 CI 中做风险评分的 PR 审查（GitHub Action）

同样的分析也以组合式 GitHub Action 的形式运行。图谱在你的 CI runner 上构建和查询，不会把源代码发送给外部服务。每个 pull request 上，该 action 会发布一条常驻评论，列出风险评分的函数、受影响的执行流和测试缺口，并在每次推送时就地更新。可选的fail-on-risk输入可以把它变成合并门禁。

# .github/workflows/code-review-graph.yml on: pull_request: permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: tirth8205/code-review-graph@v2.3.9 with: github-token: ${{ secrets.GITHUB_TOKEN }}

输入参数、风险等级和缓存见 docs/GITHUB_ACTION.md，本仓库自己运行的工作流见 .github/workflows/pr-review.yml。

基准测试

6 个仓库上每个问题的 token 减少中位数约为63 倍（全语料基线对比图谱查询）。358 倍的最大值只属于一个仓库（fastapi，语料最大），不是典型结果。

所有数字都来自针对 6 个开源仓库（13 次提交）的评估运行器。每个配置都固定了上游 SHA，Leiden 使用固定随机种子，嵌入在 CPU 上是确定性的，因此不同机器上的两次运行得到相同的数字。复现步骤见 docs/REPRODUCING.md。在两个最小配置上的每周只读运行位于 .github/workflows/eval.yml。

Token 效率：每个问题减少中位数约 63 倍（范围 35 倍到 358 倍；全语料对比图谱查询）

对于典型的智能体问题（"how does authentication work"、"what is the main entry point"等），图谱返回约 2,200 到 3,900 个 token 的搜索命中加邻接边，而不是每一个源文件。表格对code_review_graph/token_benchmark.py中定义的 5 个样例问题取平均。

2026-08-02 从固定 SHA 的干净克隆中采集（crg 2.3.7，本地all-MiniLM-L6-v2嵌入）。这些数字低于它们取代的 2026-05-25 采集：节点嵌入文本变得更丰富，因此每个仓库的avg graph_tokens都上升了。fastapi 按当前固定的22381558测量，而不是已退役的0227991a。

减少倍数一列是naive_corpus_tokens / avg graph_tokens，因此可以由旁边两列直接除出来。基准测试自己的average_reduction_ratio取的是五个问题各自比率的平均值，那个值总是更高；每个问题的数字见 docs/REPRODUCING.md。

code-review-graph这一行是快照，不是当前测量值。仓库自84bde354以来有所增长，其语料和图谱今天都大得多。

全语料基线是任何真实智能体都不会付出的上限；智能体会 grep 标识符并读取最匹配的文件。agent_baseline评估基准测量的就是这种情况（纯 Python 对语料做 grep，按匹配数取前 3 个文件，再与图谱查询开销做 token 对比）。它写入evaluate/results/<repo>_agent_baseline_<date>.csv；目前还没有发布过权威采集结果。

正式的token_efficiency基准测量的是另一个场景：完整的get_review_context()JSON 对比一次提交中仅变更文件的内容；对于小提交，它报告的比率低于 1，因为响应里带有影响半径的边和源码片段。这两个基准回答的是不同的问题，见 docs/REPRODUCING.md。

审查和影响类工具会在响应中附带紧凑的context_savings估算。CLI 在Token Savings面板中显示同样的数字（见下文使用方式），--verify会把它们与 OpenAI 的cl100k_base分词器做对比。在 222 个样本文件上的校准表明，总体估算与真实 token 的偏差约在 1% 以内（数据）。

影响准确度：对图谱生成的基准答案平均 F1 为 0.69（召回率 1.0 是循环论证得出的上限）

在全部 13 次评估提交上，影响半径分析都找回了基准答案中的每一个文件。请把它读作上限，而不是"100% 召回"：基准答案（变更文件加上有调用边或导入边指向它们的文件）来自预测器所遍历的同一张图谱。较低的精确率是有意为之；多标一个文件的代价小于漏掉一个被破坏的依赖。

该基准还会运行一种共变更模式：给预测器一个变更文件作为种子，再用作者在同一次提交中改动的其他文件来评分，这是来自 git 历史而非图谱的证据。两种模式都出现在结果 CSV 中（ground_truth_mode列）。在 2026-08-02 的采集中，共变更模式在每个被评分的提交上都返回predicted_files = 0，因此它还不是可用的测量结果，也不引用任何共变更数字。

构建统计

来自上文固定 SHA 的同一次 2026-08-02 干净构建。嵌入数量低于节点数量，因为 File 节点不做嵌入。code-review-graph这一行是那个快照，不是仓库现在的状态。

局限

• 影响分析的"召回率 1.0"是循环论证。历史基准答案来自预测器所遍历的同一批图谱边，因此按构造它就是一个上限。共变更模式还不是可用的测量结果。
• 小的单文件改动。对于琐碎的编辑，图谱上下文可能比直接读文件还大。多出来的是让多文件分析成为可能的结构化元数据。
• 搜索排序。关键词搜索通常能把正确结果排在靠前位置，但排序还需要改进。由于模块模式的命名方式，针对 Express 的查询可能返回零命中。
• 执行流检测。入口点检测对 Python 和 PHP/Laravel 最强。JavaScript 和 Go 的流检测还需要改进。
• 精确率与召回率。影响分析偏保守。它会标出可能受影响的文件，这意味着在大型依赖图中会出现误报。

功能

使用方式

技能

install会为支持技能的平台（Claude Code、Gemini CLI、CodeBuddy Code、Hermes Agent 和 Qoder）写入以下四个技能。按名字调用即可。

Qoder 还会从本仓库的skills/目录得到build-graph、review-delta和review-pr。

CLI 参考

code-review-graph install # Detect and configure all platforms code-review-graph install --platform <name> # One platform code-review-graph uninstall --dry-run # Preview removal of installed artifacts code-review-graph build # Parse the whole codebase code-review-graph update # Incremental update (changed files only) code-review-graph status # Graph statistics code-review-graph watch # Update on file changes code-review-graph forget <path> # Drop already-parsed files from the graph code-review-graph dead-code # Functions and classes with no callers or tests code-review-graph visualize # Interactive HTML graph code-review-graph visualize --format json # Export graph data as JSON code-review-graph visualize --format graphml # Export as GraphML code-review-graph visualize --format svg # Export as SVG (needs matplotlib) code-review-graph visualize --format obsidian # Export as Obsidian vault code-review-graph visualize --format cypher # Export as Neo4j Cypher code-review-graph wiki # Markdown wiki from communities code-review-graph detect-changes --brief # Risk panel + token savings (read-only) code-review-graph detect-changes --brief --base main # Against the merge base of main and HEAD code-review-graph update --brief # Refresh graph + same panel code-review-graph detect-changes --brief --verify # Cross-check against tiktoken code-review-graph register <path> # Register repo in the multi-repo registry code-review-graph unregister <path|alias> # Remove repo from the registry code-review-graph repos # List registered repositories code-review-graph daemon start # Start the multi-repo watch daemon code-review-graph daemon stop # Stop the daemon code-review-graph daemon status # Daemon status and repos code-review-graph eval # Run evaluation benchmarks code-review-graph serve # Start the MCP server (stdio) code-review-graph serve --http # MCP over Streamable HTTP on localhost:5555

这是一份精选列表。code-review-graph --help会列出全部命令，docs/COMMANDS.md 记录了它们的参数。

当detect-changes --base指定的是一个分支时，diff 会针对该分支与 HEAD 的合并基做。提交哈希和其他 revision 按原样使用。

visualize --format svg需要 matplotlib，它随eval附加依赖提供（pip install "code-review-graph[eval]"）。其他导出格式无需额外安装。

JSON 导出写在本地图谱数据目录中，该目录默认被 Git 忽略。导出内容可能包含绝对路径和代码结构元数据，发布前请先检查。

Token Savings 面板：detect-changes --brief对比update --brief

两个命令打印同一个面板，显示相比把变更文件原样交给智能体，图谱节省了多少 token。它们只有一点不同：是否先刷新图谱。

┌─────────────────────── Token Savings ────────────────────────┐ │ Full context would be: 12,921 tokens │ │ Graph context used: 762 tokens │ │ Saved: 12,159 tokens (~94%) │ │ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83 │ └──────────────────────────────────────────────────────────────┘

给任一命令加上--verify，可以把数字与 OpenAI 的cl100k_base分词器做对比（需要pip install tiktoken）。总体估算与真实 token 的偏差约在 1% 以内；见 docs/REPRODUCING.md。

同样的context_savings元数据也附在get_impact_radius、get_review_context、detect_changes和get_architecture_overview这几个 MCP 工具的 JSON 响应上。

多仓库守护进程

如果你的编辑器不支持钩子（例如 Cursor 或 OpenCode），或者你想在没有编辑器集成的情况下保持图谱新鲜，守护进程会监视你的仓库并更新它们的图谱。它随code-review-graph一起提供，无需单独安装。

# 1. Register the repos to watch crg-daemon add ~/project-a --alias proj-a crg-daemon add ~/project-b # 2. Start the daemon (runs in the background) crg-daemon start # 3. Check on it crg-daemon status # daemon and per-repo watcher status crg-daemon logs --repo proj-a -f # tail logs for one repo crg-daemon stop # stop the daemon and all watchers

也可以用code-review-graph daemon start|stop|status|...。

crg-daemon add写入~/.code-review-graph/watch.toml，你也可以直接编辑该文件：

[[repos]] path = "/home/user/project-a" alias = "proj-a" [[repos]] path = "/home/user/project-b" alias = "project-b"

守护进程会监视这个文件，并随着仓库的增删启动或停止 watcher 进程。每 30 秒一次的健康检查会重启已死的 watcher。

完整配置参考见 docs/COMMANDS.md。

30 个 MCP 工具

图谱构建完成后，助手会使用这些工具。

MCP 提示模板（5 个工作流模板）：review_changes、architecture_map、debug_issue、onboard_developer、pre_merge_check

配置

要把某些路径排除在索引之外，在仓库根目录创建.code-review-graphignore文件：

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

在 git 仓库中只索引被跟踪的文件（git ls-files），因此被 gitignore 的文件会跳过。用.code-review-graphignore来排除被跟踪的文件，或在没有 git 时使用。默认忽略列表见 docs/USAGE.md。

可选依赖组：

pip install "code-review-graph[embeddings]" # Local vector embeddings (sentence-transformers) pip install "code-review-graph[google-embeddings]" # Google Gemini embeddings pip install "code-review-graph[communities]" # Community detection (igraph) pip install "code-review-graph[enrichment]" # Python call-resolution enrichment (Jedi) pip install "code-review-graph[eval]" # Evaluation benchmarks and SVG export (matplotlib) pip install "code-review-graph[wiki]" # ollama client (not used by the current wiki generator) pip install "code-review-graph[all]" # All optional dependencies

环境变量

OpenAI 兼容嵌入（OpenAI、Azure，或自建网关如 new-api、LiteLLM、vLLM、LocalAI，或 OpenAI 模式下的 Ollama）无需额外安装。设置变量并给embed_graph传入provider="openai"：

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1 # or https://api.openai.com/v1 export CRG_OPENAI_API_KEY=sk-... export CRG_OPENAI_MODEL=text-embedding-3-small # whatever your gateway serves # optional: export CRG_OPENAI_DIMENSION=1536 # pin dim (v3 models support reduction) export CRG_OPENAI_BATCH_SIZE=100 # lower for gateways with tight limits # (e.g. Qwen text-embedding-v4 caps at 10)

当 base URL 指向 localhost（127.0.0.1、localhost、0.0.0.0、::1）时，会跳过云端出网警告。

Voyage 嵌入无需额外安装。设置VOYAGE_API_KEY并给embed_graph传入provider="voyage"；默认模型是voyage-code-3：

export VOYAGE_API_KEY=pa-... export CRG_ACCEPT_CLOUD_EMBEDDINGS=1 code-review-graph embed --provider voyage --model voyage-code-3

模型选择。对于打算长期保留的索引，避免使用-preview、-beta或-exp结尾的模型 ID；预览模型可能更换权重（维度一变就要全量重新嵌入）或被下架。请优先选择正式发布的模型，例如text-embedding-3-small/text-embedding-3-large（OpenAI）、Qwen/Qwen3-Embedding-8B（自建 vLLM 或 LocalAI），或gemini-embedding-001（原生 Gemini 提供方，需要GOOGLE_API_KEY）。

嵌入文本包含标识符、签名、结构上下文，以及有长度上限的首段 docstring 或文档注释摘要。函数体不会被发送。在文档提取功能加入之前创建的图谱，需要先完整执行一次code-review-graph build再重新嵌入。常规构建不会刷新嵌入；要在构建后刷新，请同时传入--embedding-provider和--embedding-model。云端提供方会收到这些由源码派生的文本，并可能据此收费。

工具过滤

CRG 默认暴露 30 个 MCP 工具。要把服务器限制到一个子集，使用--tools或CRG_TOOLS环境变量：

# CLI flag code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool # Environment variable CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve

命令行参数优先于环境变量。两者都未设置时，所有工具都可用。在 MCP 客户端配置中：

{ "mcpServers": { "code-review-graph": { "command": "code-review-graph", "args": ["serve", "--tools", "query_graph_tool,semantic_search_nodes_tool,detect_changes_tool,get_review_context_tool"] } } }

常见问题与对比

答案见 docs/FAQ.md：

• 对比 LSP / 语言服务器：一张持久的跨语言图谱，而不是每种语言一个守护进程；LSP 在单个符号上仍然更精确。
• 对比 RAG / 嵌入：从 AST 解析出的结构化边，而不是相似度分块；嵌入是可选的，只辅助搜索。
• 对比 grep / 智能体搜索：单跳查找 grep 更快；多跳问题（影响半径、调用者的调用者、tests-for、受影响的执行流）图谱更强。
• 对比 Serena、codegraph、claude-context、repomix：对比表格。
• 什么时候不要用它：小仓库、琐碎的单文件 diff、一次性问题。
• 它会回传数据吗？：没有遥测；云端嵌入需要主动开启。
• 怎么确认它在工作？：status、detect-changes --brief、/mcp。

故障排查

更多情况，包括 Windows/WSL，见 docs/TROUBLESHOOTING.md。

pip/pipx无法下载hatchling（或出现Errno 9/Bad file descriptor连 PyPI 的错误）

从源码树安装（例如pipx install .）需要从 PyPI 取构建依赖。如果在一堆连接警告之后看到Could not find a version that satisfies the requirement hatchling，那么该终端里的 Python 可能无法与pypi.org建立 HTTPS 连接。这在编辑器的集成终端里最常见，有时也与 VPN、防火墙或代理有关。

1. 改用 Terminal.app 或 iTerm 运行同一条命令，而不是编辑器的终端。

2. 用 uv 从 checkout 安装，它使用不同的下载机制：

   cd /path/to/code-review-graph uv tool install . --force

3. 在克隆中做开发时，使用uv sync和uv run code-review-graph ...。

诊断方法：python3 scripts/diagnose_pypi_connectivity.py。如果它打印FAILED，问题出在网络环境，而不是包名。

Windows：Invalid JSON: EOF while parsing或MCP error -32000: Connection closed

不要在 Claude Code 配置中使用cmd /c包装。让~/.claude.json直接指向.exe，并通过配置设置 UTF-8：

"code-review-graph": { "command": "C:\\path\\to\\your\\venv\\Scripts\\code-review-graph.exe", "args": ["serve", "--repo", "C:\\path\\to\\your\\project"], "env": { "PYTHONUTF8": "1" } }

参与贡献

git clone https://github.com/tirth8205/code-review-graph.git cd code-review-graph python3 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" pytest

Pull request 请提交到staging（默认分支）。变更按staging→testing→main的顺序推进，版本从main打标签。完整流程见 CONTRIBUTING.md。

要添加内置语言，编辑code_review_graph/parser.py：把扩展名加入EXTENSION_TO_LANGUAGE，并把节点类型映射加入_CLASS_TYPES、_FUNCTION_TYPES、_IMPORT_TYPES和_CALL_TYPES。附上测试 fixture 并提交 PR。如果某种语言只在一个仓库里需要，请改用 languages.toml。