商业产业 Hacker News AI 2026-08-05T05:05 正文 ok 1568 words

🔶 Compass：一款用 Rust 构建、面向人类与 AI Agent 的本地优先代码图谱

英文标题：🔶 Compass, a local-first code graph built in Rust for humans and AI agents

Compass 是一款用 Rust 编写的本地优先代码知识图谱工具，可将源代码和项目工件转化为可搜索、查询、可视化和跨 Git 历史比较的图。它提供确定性、只读且具资源限制的 CompassQL，并支持架构分析、依赖与影响范围追踪、版本化图谱差异以及面向编程助手的聚焦上下文。结构化提取和图查询可完全本地运行，无需 Python、嵌入模型、向量数据库、模型凭据或运行时解析器下载。对开发者而言，Compass 试图用可追溯证据和更小的上下文范围，提升大型代码库理解、变更评估及 AI 编程助手协作的效率。

打开原文相关 3 · 机会 1

4.8 KB

58.6 KB

中文

一个快速、本地优先的知识图谱，用于理解代码库。

Compass 将源代码和项目工件转换为图谱，你可以对其进行搜索、查询、可视化、跨 Git 历史比较，并与开发工具共享。

large codebase
     |
     v
  Compass  ----->  architecture map
     |           \-> dependency and impact answers
     |            \-> exact CompassQL results
     |             \-> historical graph diffs
     |              \-> focused context for assistants
     v
less searching, smaller context, traceable evidence

开始使用 · 阅读文档 · 查看路线图 · 查看发布版本

可通过官方提供的 VS Code Compass Codegraph 扩展，在编辑器内使用 Compass。有关当前图谱、以光标为根的调用图、架构流程、查询及精确 Git 演进，请参阅 VS Code 扩展指南。

需求	Compass 能力
理解陌生的仓库	社区发现、架构报告、God Node 检测和交互式 HTML
查找实现路径	自然语言图谱发现、符号解释和有向路径
评估变更影响	反向依赖遍历和版本间拓扑差异
自动化结构检查	确定性、只读的 CompassQL，支持 JSON 和 JSONL 输出
查询旧版本相关问题	针对精确 Git 提交的不可变图谱实例
为助手提供聚焦上下文	原生 Skills、Hooks、MCP 服务和紧凑图谱查询
连接其他工具	Graph JSON、GraphML、SVG、Wiki、Obsidian、Neo4j、FalkorDB 及其他导出格式

结构化提取和图谱查询均在本地运行。它们不需要 Python、嵌入、向量数据库、模型凭据或运行时解析器下载。

Compass 会发现项目文件、提取实体和关系、解析跨文件引用、分析生成的图谱，并发布一个一致的快照。

function / class / file / document / schema object       node
CALLS / IMPORTS_FROM / USES / CONTAINS                   relationship
dense group of related nodes                             community
direct / resolved / uncertain evidence                   provenance

关系会保留其方向、源位置和来源证明：

CheckoutHandler
    |
    +-- CALLS [EXTRACTED] --> authorizePayment()
    |                              |
    |                              +-- USES --> PaymentGateway
    |
    +-- CALLS [INFERRED]  --> reserveInventory()

有关完整管线，请阅读Compass 的工作原理；有关数据模型，请阅读图谱模型。

Compass 的灵感来源于并以 Graphify 为参考模型。Graphify 奠定了核心工作流：将代码库提取为知识图谱，分析其社区，并使用聚焦图谱查询浏览复杂项目。

Compass 明确致谢这一基础，但如今它是拥有自身实现、命令、配置、工件和测试套件的独立产品。Compass 不执行 Graphify，也不依赖 Graphify。

领域	Compass 扩展
运行时	单个原生 Rust 可执行文件，无 Python 或 Graphify 依赖
精确查询	CompassQL：确定性、有边界、只读的 openCypher 子集
版本化图谱	面向精确提交、历史查询、导出和差异比较的不可变实例
增量运行	复用兼容且未变化的提取工作，并以原子方式发布图谱和清单
查询安全性	显式的行数、路径、展开、内存和时间限制
原生分发	为支持的图谱、媒体、数据库和服务边界提供链接解析器及原生实现

有关 Compass 自有契约，请参阅兼容性；有关一次性硬切换，请参阅从 Graphify 迁移。

Compass 的性能基于 Compass 自有基线进行评估，同时保持图谱正确性和确定性输出。有关证据策略和基准测试命令，请阅读性能评估。

在 macOS 或 Linux（Apple Silicon/ARM64 或 Intel/AMD64）上：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/crabbuild/compass/releases/latest/download/install.sh | sh

在 Windows x64 或 ARM64 上，运行会验证校验和的 PowerShell 安装程序：

irm https://github.com/crabbuild/compass/releases/latest/download/install.ps1 | iex

如需离线安装，请从最新发布版本下载相应的归档文件和 .sha256 文件，验证校验和，解压文件，然后将包含 compass.exe 的目录添加至 PATH。

或者，使用锁定版本的 Rust 1.97.1+ 工具链从源代码构建：

git clone https://github.com/crabbuild/compass.git
cd compass
make install

make install 会使用现有的 ~/.cargo/bin；如不存在，则创建并使用 ~/.local/bin。如需指定其他位置，请运行 make install BINDIR="$HOME/bin"。

也可以直接通过 Cargo 安装：

cargo install --locked --path crates/compass-cli --bin compass

使用以下方式，可将任意已安装的 Compass 可执行文件升级至最新稳定版本：

Compass 会在替换可执行文件前验证官方发布的校验和。如果没有可用的新版本，它将成功退出，并报告已安装版本已是最新版本。

2. 安装 VS Code 扩展（可选）

安装 Compass CLI 后，请在 VS Code Marketplace 的 Compass Codegraph 页面选择 Install 进行安装。你也可以从终端安装：

code --install-extension crabbuild.crabbuild-compass-vscode

在 VS Code 中打开你的仓库。扩展会检测已安装的 Compass CLI，并引导你通过 Compass 侧边栏初始化仓库。

3. 初始化并构建本地图谱

cd your-project
compass init

compass init 会预览符合条件的语料库，将项目范围保存到 .compass/config.toml，并执行首次结构化构建。对于自动化任务或需要聚焦 Monorepo 范围的场景：

compass init . --include src --include 'services/*/src' --exclude '**/generated/**' --yes

完成设置后，compass update 和 compass watch 会自动复用已保存的范围。

Compass 会写入：

compass-out/
├── graph.json        机器可读图谱
├── GRAPH_REPORT.md   架构和社区摘要
├── graph.html        在规模允许时生成交互式可视化
└── manifest.json     增量构建状态


compass query "where is authentication enforced?"
compass explain TokenVerifier
compass path ApiHandler TokenVerifier
compass affected TokenVerifier --depth 3

这些命令读取已保存的图谱，不会调用模型。

Compass 专属工作流

使用 CompassQL 查询精确图谱模式

compass query --cql \
  "MATCH (caller)-[:CALLS]->(target)
   WHERE target.label = 'authorizePayment()'
   RETURN caller.id, target.id
   LIMIT 20" \
  --format json

CompassQL 是确定性、只读、参数化且具有资源边界的语言。请参阅语言契约和支持矩阵。

穿行于图谱历史

compass history enable --code-only
compass history build main
compass history build HEAD --profile-from main
compass query "authentication" --at HEAD~20
compass diff main HEAD
compass diff main HEAD --format html --output semantic-diff.html

历史构建使用精确的 Git 提交和不可变提取指纹。当前图谱和历史图谱均可查询、比较和导出，无需将生成的图谱数据提交到 Git。语义差异会优先呈现可能的破坏性变更、行为变化、受影响的调用方/模块和测试证据；使用 --all 可展开常规符号变动。默认文本输出会报告超出其显示预算的发现；使用 --limit N 可提高该预算，或使用 --all 获得完整输出。HTML 输出是一份自包含的交互式审阅报告，包含语义发现、增强的统一/分栏源代码差异，以及包含完整节点/边增量列表的变更子图视图。源代码视图由锁定版本的 @pierre/diffs 库渲染，并保留精确的 Git 补丁作为离线回退。HTML 输出需要显式指定 --output 路径。

请阅读版本化历史指南和存储设计。

连接编程助手

在 Git 仓库中，Compass 会检测已安装的编程 Agent，并在仓库根目录对其进行配置。Codex、Gemini CLI、OpenCode、Copilot 和通用 Agent Skills 客户端共用一个可移植的 .agents/skills/compass 包；Claude Code、Kiro 和 Cline 使用其原生 Skill 根目录。若需要显式选择，请使用可重复指定的 --platform 标志：

compass install --platform codex --platform claude
compass install --all --dry-run
compass install --user --format json

该 Skill 会指导助手将现有 Compass 图谱作为第一层导航，获取聚焦子图，并且仅打开验证答案所需的源文件。安装不会构建图谱；在首次遇到涉及全仓架构、依赖、历史或影响范围的问题时，助手可以运行本地确定性构建，然后自动继续。

architecture question
        |
        v
read GRAPH_REPORT.md
        |
        v
run a focused Compass query
        |
        v
inspect the smallest useful source set

有关支持的平台、范围、严格模式、升级和卸载，请参阅助手设置。

使用证据检查程序行为

原生 init、update、extract 和 watch 构建默认发布结构图谱。当某个场景需要 program.json 时，请传入 --program；该文件是可选的、语言无关的 Program IR，包含函数、保守基本块、操作、调用候选项、能力覆盖范围、来源证明和派生摘要。--program-artifact 同样会启用它。这个离线优先管线将 Rust 与 TypeScript 系列语言的 Tree-sitter 语法证据，同磁盘上已有的任何 SCIP 索引相结合。Compass 不会调用索引器、编译器、语言服务器、模型或网络服务来构建这一工件。

Schema http://crab.build/compass/v1 会将每项能力报告为 complete、partial、indeterminate 或 failed，并为每一种非完整状态提供机器可读的原因。无法解析的调用会作为不确定性保留，绝不会被视为不存在下游目标的证明。

无需编写自定义 JSON 脚本，即可检查或查询当前工件：

compass program summary
compass program coverage
compass program functions --language rust --name build
compass program show <symbol-id>
compass program callers <symbol-id>
compass program explain-call src/lib.rs:240
compass program query \
  "MATCH (f) WHERE f.kind = 'program_function' RETURN f LIMIT 20"

使用可重复指定的 --program-artifact path/to/index.scip 选项提供额外的离线证据。解码后的索引会按工件摘要缓存，而新鲜度和规范化则会针对每个已索引文档失效。

结构化与语义模式

选择能回答问题的最小模式：

命令	网络行为	最适合用于
`compass update .`	仅本地	常规源代码图谱更新
`compass extract . --code-only`	仅本地	明确禁止模型的提取
`compass extract . --code-only --cargo`	仅本地	代码加上 Cargo 依赖边
`compass extract docs --backend …`	使用已配置的提供商	从受支持文档和媒体中提取语义事实

语义提取是可选功能。仅当你选择由提供商支持的工作流时，Compass 才会联系模型提供商。在处理敏感仓库前，请阅读安全与隐私。

文档中心链接了所有概念、指南、设计文档、实现说明、配方和参考资料。

社区与贡献

开发检查、架构边界和贡献预期记录在 CONTRIBUTING.md 中。支持和披露边界见 SUPPORT.md 与 SECURITY.md。

Compass 的原创工作采用 MIT 或 Apache-2.0 双重许可。第三方组件保留

English / 原文

A fast, local-first knowledge graph for understanding codebases.

Compass turns source code and project artifacts into a graph you can search, query, visualize, compare across Git history, and share with development tools.

large codebase
     |
     v
  Compass  ----->  architecture map
     |           \-> dependency and impact answers
     |            \-> exact CompassQL results
     |             \-> historical graph diffs
     |              \-> focused context for assistants
     v
less searching, smaller context, traceable evidence

Get started · Read the documentation · Explore the roadmap · View releases

Use Compass inside your editor with the first-party Compass Codegraph extension for VS Code. See the VS Code extension guide for current graphs, cursor-rooted call graphs, architecture flow, queries, and exact Git evolution.

Need	Compass capability
Understand an unfamiliar repository	Communities, architecture reports, god-node detection, and interactive HTML
Find implementation paths	Natural-language graph discovery, symbol explanations, and directed paths
Estimate change impact	Reverse dependency traversal and version-to-version topology diffs
Automate structural checks	Deterministic, read-only CompassQL with JSON and JSONL output
Ask questions about old revisions	Immutable graph realizations for exact Git commits
Give assistants focused context	Native skills, hooks, MCP serving, and compact graph queries
Connect other tools	Graph JSON, GraphML, SVG, Wiki, Obsidian, Neo4j, FalkorDB, and other exports

Structural extraction and graph queries run locally. They do not require Python, embeddings, a vector database, model credentials, or runtime parser downloads.

Compass discovers project files, extracts entities and relationships, resolves cross-file references, analyzes the resulting graph, and publishes one consistent snapshot.

function / class / file / document / schema object       node
CALLS / IMPORTS_FROM / USES / CONTAINS                   relationship
dense group of related nodes                             community
direct / resolved / uncertain evidence                   provenance

Relationships retain their direction, source location, and provenance:

CheckoutHandler
    |
    +-- CALLS [EXTRACTED] --> authorizePayment()
    |                              |
    |                              +-- USES --> PaymentGateway
    |
    +-- CALLS [INFERRED]  --> reserveInventory()

Read How Compass works for the complete pipeline and Graph model for the data model.

Compass is inspired by and modeled after Graphify. Graphify established the core workflow: extract a codebase into a knowledge graph, analyze its communities, and use focused graph queries to navigate complex projects.

Compass gives explicit credit to that foundation, but it is now an independent product with its own implementation, commands, configuration, artifacts, and test suite. Compass does not execute or depend on Graphify.

Area	Compass extension
Runtime	One native Rust executable with no Python or Graphify dependency
Exact queries	CompassQL, a deterministic and bounded read-only openCypher subset
Versioned graphs	Immutable realizations for exact commits, historical queries, exports, and diffs
Incremental operation	Reuses compatible unchanged extraction work and atomically publishes graph plus manifest
Query safety	Explicit row, path, expansion, memory, and time limits
Native distribution	Linked parsers and native implementations for supported graph, media, database, and service boundaries

See Compatibility for Compass-owned contracts and Migration from Graphify for the one-time hard cutover.

Compass performance is qualified against Compass-owned baselines while preserving graph correctness and deterministic output. Read Performance qualification for the evidence policy and benchmark commands.

On macOS or Linux (Apple Silicon/ARM64 or Intel/AMD64):

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/crabbuild/compass/releases/latest/download/install.sh | sh

On Windows x64 or ARM64, run the checksum-verifying PowerShell installer:

irm https://github.com/crabbuild/compass/releases/latest/download/install.ps1 | iex

For an offline install, download the matching archive and .sha256 file from the latest release, verify the checksum, extract it, and add the directory containing compass.exe to PATH.

Or build from source with the pinned Rust 1.97.1+ toolchain:

git clone https://github.com/crabbuild/compass.git
cd compass
make install

make install uses an existing ~/.cargo/bin, otherwise it creates and uses ~/.local/bin. To choose another location, run make install BINDIR="$HOME/bin".

You can also install directly through Cargo:

cargo install --locked --path crates/compass-cli --bin compass

Upgrade any installed Compass executable to the latest stable release with:

Compass verifies the official release checksum before replacing the executable. If no newer release is available, it exits successfully and reports that the installed version is already the latest.

2. Install the VS Code extension (optional)

After installing the Compass CLI, install Compass Codegraph from the VS Code Marketplace by selecting Install on its Marketplace page. You can also install it from a terminal:

code --install-extension crabbuild.crabbuild-compass-vscode

Open your repository in VS Code. The extension detects the installed Compass CLI and guides you to initialize the repository from the Compass sidebar.

3. Initialize and build a local graph

cd your-project
compass init

compass init previews the eligible corpus, saves project scope in .compass/config.toml, and performs the first structural build. For automation or a focused monorepo scope:

compass init . --include src --include 'services/*/src' --exclude '**/generated/**' --yes

After setup, compass update and compass watch automatically reuse the saved scope.

Compass writes:

compass-out/
├── graph.json        machine-readable graph
├── GRAPH_REPORT.md   architecture and community summary
├── graph.html        interactive visualization when size permits
└── manifest.json     incremental build state



compass query "where is authentication enforced?"
compass explain TokenVerifier
compass path ApiHandler TokenVerifier
compass affected TokenVerifier --depth 3

These commands read the saved graph and do not call a model.

Compass-specific workflows

Query exact graph patterns with CompassQL

compass query --cql \
  "MATCH (caller)-[:CALLS]->(target)
   WHERE target.label = 'authorizePayment()'
   RETURN caller.id, target.id
   LIMIT 20" \
  --format json

CompassQL is deterministic, read-only, parameterized, and resource-bounded. See the language contract and support matrix.

Travel through graph history

compass history enable --code-only
compass history build main
compass history build HEAD --profile-from main
compass query "authentication" --at HEAD~20
compass diff main HEAD
compass diff main HEAD --format html --output semantic-diff.html

Historical builds use exact Git commits and immutable extraction fingerprints. Current and historical graphs can be queried, compared, and exported without putting generated graph data into Git. Semantic diff leads with likely breaks, behavior changes, affected callers/modules, and test evidence; use --all to expand routine symbol churn. Default text output reports any findings beyond its display budget; use --limit N to raise that budget or --all for exhaustive output. HTML output is a self-contained interactive reviewer report with semantic findings, an enhanced unified/split source diff, and a changed-subgraph view with exhaustive node/edge delta lists. The source view is rendered by the pinned @pierre/diffs library and retains the exact Git patch as an offline fallback. HTML output requires an explicit --output path.

Read the versioned history guide and storage design.

Connect a coding assistant

Inside a Git repository, Compass detects installed coding agents and configures them at the repository root. Codex, Gemini CLI, OpenCode, Copilot, and generic Agent Skills clients share one portable .agents/skills/compass package; Claude Code, Kiro, and Cline use their native skill roots. Use repeatable --platform flags when you want explicit selection:

compass install --platform codex --platform claude
compass install --all --dry-run
compass install --user --format json

The skill teaches assistants to use an existing Compass graph as the first navigation layer, request a focused subgraph, and open only the source files needed to verify an answer. Installation does not build a graph; on the first repository-wide architecture, dependency, history, or impact question, the assistant can run the local deterministic build and continue automatically.

architecture question
        |
        v
read GRAPH_REPORT.md
        |
        v
run a focused Compass query
        |
        v
inspect the smallest useful source set

See Assistant setup for supported platforms, scope, strict mode, upgrades, and uninstall.

Inspect program behavior with evidence

Native init, update, extract, and watch builds publish the structural graph by default. Pass --program when a scenario needs program.json, the optional language-neutral Program IR containing functions, conservative basic blocks, operations, call candidates, capability coverage, provenance, and derived summaries; --program-artifact also enables it. The offline-first pipeline combines Tree-sitter syntax evidence for Rust and TypeScript-family languages with any SCIP indexes already on disk. Compass does not invoke an indexer, compiler, language server, model, or network service to build this artifact.

Schema http://crab.build/compass/v1 reports each capability as complete, partial, indeterminate, or failed, with machine-readable reasons for every non-complete state. Unresolved calls are retained as uncertainty and are never treated as proof that no downstream target exists.

Inspect or query the current artifact without custom JSON scripts:

compass program summary
compass program coverage
compass program functions --language rust --name build
compass program show <symbol-id>
compass program callers <symbol-id>
compass program explain-call src/lib.rs:240
compass program query \
  "MATCH (f) WHERE f.kind = 'program_function' RETURN f LIMIT 20"

Supply additional offline evidence with repeatable --program-artifact path/to/index.scip options. Decoded indexes are cached by artifact digest, while freshness and normalization are invalidated per indexed document.

Structural and semantic modes

Choose the smallest mode that answers your question:

Command	Network behavior	Best for
`compass update .`	Local only	Normal source-code graph updates
`compass extract . --code-only`	Local only	Explicit no-model extraction
`compass extract . --code-only --cargo`	Local only	Code plus Cargo dependency edges
`compass extract docs --backend …`	Uses the configured provider	Semantic facts from supported documents and media

Semantic extraction is optional. Compass contacts a model provider only when you select a provider-backed workflow. Read Security and privacy before processing sensitive repositories.

The documentation hub links every concept, guide, design, implementation note, recipe, and reference.

Community and contributing

Development checks, architecture boundaries, and contribution expectations are documented in CONTRIBUTING.md. Support and disclosure boundaries live in SUPPORT.md and SECURITY.md.

Compass's original work is dual-licensed under MIT or Apache-2.0. Third-party components retain their original licenses; see THIRD_PARTY_NOTICES.md.