CompareGraph

CompareGraph

逐项对比多个代码仓库的功能：哪个仓库具备哪些功能，以及能证明这一点的文件和代码行。

快速开始 · 用法 · 命令 · MCP 工具 · 常见问题 · 故障排除 · 报告

你会保留自己和他人的项目克隆，并记下想要对比的功能。CompareGraph 会将每个克隆读入同一张图中，帮助你或编码 Agent 填写一张对比各个仓库功能的表格。每项结果为 has、partial 或 none，并且都指向相关代码，或者指向未找到结果的搜索。它免费且开源（Apache-2.0），是运行在你电脑上的单个程序；它会读取克隆，但不会运行它们，而且引擎绝不会调用 AI 模型或访问网络。

**十分钟后你将看到：**安装并运行六条命令后，屏幕上会显示一张小型样例的同类表格。在自己的克隆上构建：在我们的主机上，处理 85 个文件耗时 0.82 s，处理 797 个文件耗时 6.20 s（计时报告）。

快速开始

单个二进制文件，无需运行时环境。支持 Linux x64 和 arm64、macOS arm64 和 x64、Windows x64；其他平台请从源代码构建。

1. 安装二进制文件

安装脚本会下载一个文件，即适用于你平台的 comparegraph 二进制文件，将其与此版本的 SHA256SUMS 校验，并复制到 ~/.local/bin。它不会使用 sudo，也不会更改其他内容。你可以先阅读脚本：

# macOS / Linux: fetch the script from the v0.1.3 tag, read it, then run it
curl -fsSLO https://raw.githubusercontent.com/MassRelayAI/comparegraph/v0.1.3/scripts/install.sh
less install.sh
COMPAREGRAPH_VERSION=v0.1.3 sh install.sh

# the same in one line, script from main, latest release
curl -fsSL https://raw.githubusercontent.com/MassRelayAI/comparegraph/main/scripts/install.sh | sh

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

_{Windows：文件会写入 %LOCALAPPDATA%\Programs\comparegraph，并将该目录添加到用户的 PATH；请打开新的终端。COMPAREGRAPH_INSTALL_DIR 可以更改二进制文件的安装位置。脚本只会检查校验和。v0.1.2 起的版本还附带构建来源证明，但脚本不会检查该证明；请自行使用 gh attestation verify <asset> -R MassRelayAI/comparegraph 进行检查（发行说明）。}

2. 在示例上试运行

示例仓库和功能示例列表都在此仓库中，而不在二进制文件里，因此第一条命令会下载该仓库的副本。你可以在任意文件夹中运行这些命令；它们会在同一目录下创建 comparegraph 和 cg-try 两个文件夹。

git clone --depth 1 https://github.com/MassRelayAI/comparegraph   # the sample lives here
mkdir cg-try && cd cg-try                                           # your workspace
comparegraph add ../comparegraph/fixtures/typescript --name tsfix   # read, never run
comparegraph build tsfix                                            # parse it
comparegraph family add ../comparegraph/families/example-code-graph-tools
comparegraph map tsfix example-code-graph-tools                     # places to read
comparegraph claim tsfix symbols.extraction has --author me --at src/util.ts:11-11
comparegraph matrix example-code-graph-tools                        # the table

该表为 symbols.extraction 显示 has，其他九项功能显示 -（尚未回答）。所有命令总共不到一秒即可运行完毕。用法展示了每一步的实际输出。

3. 比较你自己的仓库

示例包描述的是代码图工具。对于你自己的领域，需要自行编写功能列表，放在一个简短的 rows.md 文件中；起步时写三行就足够了。

comparegraph add ../your-lib --name mine --as-root   # any clones on your disk
comparegraph add ../their-lib --name theirs
comparegraph build mine && comparegraph build theirs
comparegraph family propose libs --repos mine,theirs # optional draft

family propose 会起草一份共用词列表（name、file、extract 等），而不是功能列表；保留有用的词，为它们编写定义，并将文件保存为 families/libs/rows.md：

---
family: libs
description: the three features I want to compare
---
| id | group | feature | definition | counts_as_has | tier | weight |
|---|---|---|---|---|---|---|
| search.fulltext | search | Full-text search | Search over names or text through an index | a query entry point over a full-text index | basics | 2 |
| search.embeddings | search | Embedding search | Search by vector similarity | code that embeds text and ranks by similarity | extra | 1 |
| graph.communities | graph | Module communities | Groups of related code found from the graph | a clustering pass over the graph | extra | 1 |

然后像第 2 步一样运行 comparegraph family add families/libs、map、claim 和 matrix libs。map 会提供可供查阅的位置，而不是结论：由你或你的 Agent 打开这些位置，并编写每项声明。列规则见用法。

4. 接入你的 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 注册 MCP 服务（共 12 个：Claude Code、Codex、Cursor、Gemini CLI、OpenCode、Hermes、Windsurf、Antigravity、Kiro、Copilot、Copilot CLI、Qwen Code），将一段简短的规则写入工作区的指令文件，并为 Claude Code 添加一个会话启动钩子。它只接入 Agent；不会建立索引。已经安装？comparegraph doctor 会告诉你哪些已接入。}

/plugin install comparegraph --marketplace MassRelayAI/comparegraph

如需卸载，请参阅Agent、平台与卸载。免费且开源，没有付费版本；如有疑问或发现 Bug，请前往 GitHub issues，安全问题请报告至 SECURITY.md。

Why 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 才会运行。清单只是声明，不是签名：程序不会检查可执行文件的哈希值，提供方会以独立程序的形式在你的权限下运行。优先使用 comparegraph.toml 中的路径；它会先于 PATH 中找到的名称进行查找。清单中的 network 值会作为 COMPAREGRAPH_NETWORK 传递给提供方，但不会强制执行。

完整协议、安全防护、一个 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 是机器可读的来源，catalog --check 会在 CI 中对其进行校验。

知识库、配置、库

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。它构建一个含 38,258 个文件的仓库耗时 499.6 秒，并能在 2.5 秒内回答针对含 129 万条边的图的 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 可强制写入。若不带参数的 comparegraph 命令在 PATH 中解析到已注册的二进制文件，则视为已对齐。setup --apply 只会添加配置，并创建名为 <file>.bak-<unix-seconds> 的备份；如果配置项不同，除非传入 --force，否则不会修改。

setup 还会向 Agent 的指令文件写入规则块，并为 Claude Code 添加一个 SessionStart hook；详情请参阅用法。

平台：每个版本都会在各自的运行器上构建 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 导出；导出功能统计；导入声明以及 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。