CompareGraph

CompareGraph

已经安装？运行 comparegraph doctor。

使用 Claude Code、Codex、Cursor、Gemini CLI、Windsurf、OpenCode 和另外六种 Agent 比较多个代码仓库

将多个克隆整合为一张图 · 每个单元格的结论都有引用 · 支持 29 种语言 · 100% 本地运行，不调用模型
单个 Rust 二进制文件

使用方法 · 命令 · MCP 工具 · 常见问题 · 故障排除 · 路线图 · 报告

CompareGraph 会将多个克隆的代码仓库解析到一个 SQLite 图中。它会根据分类体系（即一组功能）为每个克隆评分，并针对每个克隆和功能记录判定结果，同时引用文件及行范围。它是一个包含 CLI 和 MCP 服务的 Rust 二进制程序。它只读取克隆，不会运行它们，也不会调用模型。

快速开始

无需安装运行时：只需一个二进制程序。Node 用户可以通过 npx -y @massrelay-ai/comparegraph 运行同一个二进制程序。

1. 安装二进制程序

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/massrelay-ai/comparegraph/main/scripts/install.sh | sh

# Windows x64 (PowerShell)
irm https://raw.githubusercontent.com/massrelay-ai/comparegraph/main/scripts/install.ps1 | iex

_{安装程序会根据发行版的 SHA256SUMS 校验文件（linux-x64、linux-arm64、darwin-arm64、darwin-x64、win32-x64；从 v0.1.2 起还可验证来源：gh attestation verify <asset> -R massrelay-ai/comparegraph），然后将其写入 ~/.local/bin（Windows：%LOCALAPPDATA%\Programs\comparegraph，并添加到用户的 PATH；请在该目录打开新终端）。COMPAREGRAPH_VERSION=v0.1.1 可固定发行版；COMPAREGRAPH_INSTALL_DIR 可更改二进制程序的安装位置。}

2. 配置 Agent

comparegraph setup --apply      # omit --apply for the plan; --scope project for an entry you commit
comparegraph doctor             # each client's state: aligned, stale, conflict, missing, plugin

_{为本机上找到的所有 Agent（共十二个：Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Hermes、Windsurf、Antigravity、Kiro、Copilot、Copilot CLI、Qwen Code）注册 MCP 服务，在工作区的指令文件中写入简短的规则区块，并为 Claude Code 添加会话启动钩子。它只配置 Agent，不会建立索引。}

/plugin install comparegraph --marketplace massrelay-ai/comparegraph

3. 添加并构建克隆

comparegraph add ../some-clone --name some
comparegraph build some

_{克隆只会被读取，不会运行。每个工作区使用一个存储库，位于 .comparegraph/ 下。增量重建的结果与 build --full 的哈希相同。}

4. 比较

comparegraph family add families/example-code-graph-tools   # the taxonomy
comparegraph map some example-code-graph-tools              # ranked candidates per feature, writes nothing
comparegraph claim some symbols.extraction has --author me --at <path>:<start>-<end>
comparegraph matrix example-code-graph-tools                # features x clones, prevalence, gaps

_{示例套件随仓库一起提供，不包含在二进制文件中，因此请在仓库克隆副本中运行这些内容。下方示例会使用实际输出，演示如何对随附示例执行所有这些步骤。}

快速开始：使用随附示例

示例套件和示例仓库随仓库一起提供，不包含在二进制文件中。使用指南会以实际输出演示如何对照十项功能的示例套件检查 fixtures/typescript，从 add 到 export vault。

如需卸载，请参阅Agent、平台与卸载。

为什么选择 CompareGraph

在六个研究副本和 30 项功能上测得，二进制版本为 0.1.1：数据见 docs/assets/cost.json，方法和注意事项见答案大小报告。

你有许多仓库，想弄清楚谁具备什么能力。逐个手动阅读无法扩展；没有行号的摘要无法核查；代码一旦变动，笔记就会过时。五项特性，每一项都可以验证：

1. 确定性。 相同的克隆副本和版本会生成相同的 store_hash。comparegraph check 会重建并进行比较；增量构建必须与 build --full 相同（在计划 6 报告中的两棵大型代码树上结果相同）。
2. 每个答案都带有证据类别。 每个封装都会标明 observed、derived、inferred 或 unknown，并附上引擎无法查看的内容列表 limitations[]。
3. 每项声明都需要一条当前有效的引文。 has 和 partial 需要与已存储节点匹配的 --at path:start-end；否则引擎会拒绝。引文对应的代码移动后，经 check 检查会显示为 unknown*。
4. none 需要缺失证据。 可以提供搜索结果为空的 --searched 词条；也可以提供同一组词条，并在 --read-hits 中列出所有已打开并排除的命中项；还可以通过图检查：四个渠道（符号、路径、社区词条和节点类型）均为空。带有 --searched 的 none 必须将 absent-check --searched 返回的排名前 10 个候选项（read_set）列为已阅读；超过上限的候选项会记录为 read_capped 限制。排名前 10 中有未阅读的候选项时，引擎会拒绝该声明并指出该候选项。
5. 引擎中没有模型。 分数、等级、描述和候选项都根据已存储的事实计算。Agent 可以负责阅读；引擎只负责存储、检查和拒绝。

适用场景：团队将自己的产品与同领域项目进行比较；对一组项目开展尽职调查；新手绘制领域图谱（family propose 会起草分类体系）；以及需要通过 MCP 获取精简事实的编码 Agent。

工作原理

1. 引擎绝不会调用模型。 所有分数、等级、描述和候选项均根据已存储的事实计算。
2. 声明需要一条当前可解析的引用。 has 和 partial 需要与已存储节点匹配的 --at path:start-end。 none 需要能查无结果的 --searched 词项，或图谱检查。否则，引擎会拒绝，或写入 unknown。
3. 声明和决策只能追加，由数据库强制执行。 更改会新增一行，并注明其取代的记录。 以最新记录为准，变更轨迹会保留。

search 或 map 得出的候选项会标记为 candidate，绝不会标记为 has。设计文档： docs/design.md。

流程和代码环图示：docs/design.md。

图谱中的一个家族

家族是一种分类体系：由若干特征组构成，每个特征都有定义和一项测试，用于判断是否具备该特征。一个单元对应一个克隆与一个特征，包含一个结论（has、partial、none），而 has 和 partial 还需附带引用。图中展示了家族 code-graph-tools 及映射基准数据中双方达成一致的单元；在 Obsidian 中运行 comparegraph export vault，即可查看同一图谱的实时版本。

插件和第二引擎

外部提供程序是任何通过 stdin 和 stdout 传输 JSON 行的可执行程序：宿主写入一行请求后关闭 stdin，并读取答复行，直到收到第一条 ok 答复。它输出的所有内容都是数据，并会解析为我们自己的类型。在 comparegraph.toml 中注册提供程序（[providers.mine] command = "tools/my-provider"），或将其作为 comparegraph-provider-<name> 放在 PATH 上，并在旁边放置 comparegraph-plugin.toml 清单（kind、name、protocol = "1"、languages、network）。没有清单时，只有使用 --allow-unverified 才会运行。

完整协议、防护措施、一个 25 行的 Python 提供程序，以及 code-review-graph 适配器（作为第二引擎，由 build --providers reference,crg 调用）：docs/dev/plugin-protocol.md。

家族和七项技能

家族是一个包含 rows.md 的目录。随附两个包：families/example-code-graph-tools（10 个特征，快速入门）和 families/code-graph-tools（30 个特征，映射基准）。列规则、同义词和 family propose 见用法。

这套方法由 skills/ 中的七项纯 Markdown 技能构成，任何 Agent 都可以阅读。每项技能都会说明何时使用相应动词、准确的命令、引擎会拒绝哪些操作，以及如何检查。在 Claude Code 中，这些技能和 MCP 服务会作为一个插件一起提供（开始使用）；其他 Agent 可从克隆的仓库中读取 skills/ 目录。

使用方法

docs/ 下的四个页面包含参考资料；从这里出发，点击几次即可到达。

你将获得什么

四个层级，每个层级都回答它如何得知：仓库概况、模块社区、符号（调用方、被调用方、影响范围、测试、入口点、潜在死代码）以及声明（判定、引文、作者、轨迹）。每个答案都是一个带有证据类别的 JSON 信封。使用说明中有表格和一个真实的 show 答案。

CLI 参考

全局选项 --root 和 --pretty，然后是分为四组的动词：构建与检查、图查询、家族与声明、导出与 Agent。命令列出了每个动词及其重要标志。

MCP 工具

comparegraph mcp 通过 stdio 提供十八个工具（十七个只读，一个写入：comparegraph_claim）；刻意不提供 decide 工具。MCP 工具中有表格；docs/catalog.json 是机器可读的来源，CI 中的 catalog --check 会对其进行检查。

知识库、配置、库

comparegraph export vault --out ./vault 会写入一个 Obsidian 风格的 Markdown 知识库，其中的笔记带有生成的描述。设置项为 --root 和 COMPAREGRAPH_* 环境变量，而 crate 会将每个动词作为一个函数公开。这三项内容都在使用说明中。

效果如何

以下每个数字均摘自本仓库中的报告；引用前请先阅读其中的注意事项。所有数据均于 2026-10-13 在一台共享主机上测得。

在手工标注的调用点金标准上，CompareGraph 的精确率达到 0.995，汇总召回率达到 0.834；相比之下，code-review-graph 通过其适配器运行后的精确率 / 召回率为 0.956 / 0.736，codegraph 为 0.708 / 0.506。它在 499.6 s 内构建了一个包含 38,258 个文件的仓库，并在 2.5 s 内对一个有 1.29M 条边的图完成 impact 查询；下方表格列出了注意事项。数据：accuracy.json、scale.json；一致性报告：引擎一致性。

共解析 29 种语言，其中 5 种会进行深度解析，4 种有经过测量的黄金标准。请查看各层级，而不是只看标题。 每种语法（共 32 个 ID：tsx、jsx 和 mjs 分别计数）都有一个固定样例，并在 fixtures/languages/ 中提交了图摘要，因此，任何会改变图的语法版本升级都会导致 CI 失败，并需要有意重新生成黄金标准。

Agent、平台与卸载

comparegraph setup 会写入条目；comparegraph doctor 会报告每个客户端的状态（aligned、stale、conflict、 missing、unverified、plugin）。--client all 只会作用于看起来已安装的客户端。plugin：启用 comparegraph@comparegraph 并使用 --client all 时，交由 Claude Code 插件处理；指定 --client claude 可强制写入。通过 PATH 解析到已注册二进制文件的裸 comparegraph 命令会被视为已对齐。setup --apply 采用增量方式，并会创建名为 <file>.bak-<unix-seconds> 的备份；除非传入 --force，否则不会改动不同的条目。

setup 还会在 Agent 的指令文件中写入规则块，并为 Claude Code 添加 SessionStart 钩子；详情请参阅用法。

平台：每次发布都会在各自的运行器上构建 linux-x64、linux-arm64、darwin-arm64、darwin-x64 和 win32-x64 版本，并将每个版本作为发布资源提供，资源列表见 SHA256SUMS；Homebrew tap 会跟随发布更新。测试套件仅在 linux-x64 上运行。凡是能运行 Rust 1.85+ 的平台，都可以从源代码构建。仅在本地运行：引擎不会进行网络调用，MCP 服务通过 stdio 通信，存储是一个由你管理的 SQLite 文件。

卸载：删除上方的条目（在 Claude Code 中使用插件时，执行 /plugin uninstall comparegraph），然后删除二进制文件（~/.local/bin/comparegraph、brew uninstall comparegraph 或 cargo uninstall comparegraph），并在每个工作区中执行 rm -r .comparegraph。

常见问题与故障排除

• 常见问题：它与 code-review-graph 和 codegraph 有何不同（以及它们具备而它不具备的功能）、是否使用模型（不使用）、是否会替你采纳代码（不会）、为何某些调用边的值为 0.5，以及它不会做什么。
• 故障排除：列出十二种症状及其原因，从 no workspace 和被拒绝的 none 声明，到无提示的会话启动钩子。
• 从 comparegraph doctor 开始：它会报告存储、每个提供方以及每个客户端的注册状态。

路线图

以下内容目前均未实现，顺序由维护者决定。完整列表及每项背后的测量结果：docs/roadmap.md。

• 下一项经测量验证的改进方向：在存储中添加文本通道（文档注释和签名词元）以及按家族划分的同义词，提升 map 在未见克隆项目上的表现。
• 为已采用的功能提供 port-kit 导出；导出功能统计信息；导入 claim，以及 family import/export。
• 图谱对等查询、C/C++/C# 解析器、按文件分析缓存，以及更多客户端（Zed、Continue）。

文档

贡献、许可和第三方代码

安全问题请发送至 [email protected]，或通过私密安全公告提交（SECURITY.md）；行为准则问题请发送至 同一地址（CODE_OF_CONDUCT.md）。

请先阅读 CONTRIBUTING.md 和 AGENTS.md。修复错误时，先编写一个失败测试；提取逻辑的变更需要扩展一致性测试固定样例；引擎中不得进行模型调用或网络调用。CI 会运行 clippy、测试套件、一致性检查和语言摘要检查，以及 cargo-deny（许可证、安全公告、来源；deny.toml）。随附的解析器层来自 graphmind（MIT）；详见 docs/THIRD_PARTY_NOTICES.md。许可证：Apache-2.0，详见 LICENSE。