待翻譯：Compass, a local-first code graph built in Rust for humans and AI agents

AI 服務暫時不可用，以下為來源正文，待恢復後補全翻譯。

Uh oh! There was an error while loading. Please reload this page. Notifications You must be signed in to change notification settings Fork 5 Star 91 BranchesTags Open more actions menu Folders and files NameName Last commit message Last commit date Latest commit History 1,045 Commits 1,045 Commits .cargo .cargo .github .github advisor-plans advisor-plans apps/web apps/web benchmarks/performance benchmarks/performance completions completions crates crates docs docs editors/vscode editors/vscode fixtures fixtures fuzz fuzz packages/compass-viewer packages/compass-viewer scripts scripts tests tests tools/skillgen tools/skillgen vendor vendor .gitattributes .gitattributes .gitignore .gitignore .impeccable.md .impeccable.md .vercelignore .vercelignore AGENTS.md AGENTS.md CHANGELOG.md CHANGELOG.md CODE_OF_CONDUCT.md CODE_OF_CONDUCT.md COMPATIBILITY.md COMPATIBILITY.md CONTRIBUTING.md CONTRIBUTING.md Cargo.lock Cargo.lock Cargo.toml Cargo.toml LICENSE LICENSE LICENSE-APACHE LICENSE-APACHE LICENSE-MIT LICENSE-MIT MIGRATION.md MIGRATION.md Makefile Makefile PERFORMANCE.md PERFORMANCE.md README.md README.md SECURITY.md SECURITY.md SUPPORT.md SUPPORT.md THIRD_PARTY_NOTICES.md THIRD_PARTY_NOTICES.md deny.toml deny.toml package-lock.json package-lock.json package.json package.json rust-toolchain.toml rust-toolchain.toml tsconfig.base.json tsconfig.base.json vercel.json vercel.json Repository files navigation 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. What Compass gives you 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. How it works 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. Project lineage 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. Compass capabilities 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. Performance 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. Quick start 1. Install 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 upgrade 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 4. Ask useful questions 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 compass install 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 compass program callers compass program explain-call src/lib.rs:240 compass program query \ "MATCH (f) WHERE f.kind = 'program_function' RETURN f LIMIT 20" [truncated for AI cost control]