oxcode

oxcode

oxcode 会将源代码索引到图中，并将其提供给编码 Agent。它基于 oxgraph 构建——这是一个适用于 Rust、与存储无关且支持零拷贝的图／超图拓扑底层框架——并将索引存储在 .oxcode/index.oxgdb/ 下的原生 oxgraph 数据库中。

CLI 保留了原始 OxQL 的使用方式，但 Agent 通常应从 context、symbols、files 和调用图命令开始导航，因为这些命令会将图 ID 展开为函数名、定义范围、签名、文档字符串、源代码预览和调用位置的源代码上下文。

快速开始

1. 安装

预编译二进制文件（推荐——无需 Rust 工具链；语法解析器已静态链接，因此可离线运行）：

# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://github.com/oxgraph/oxcode/releases/latest/download/oxcode-cli-installer.ps1 | iex"

或者从 Releases 页面下载压缩包。也可以使用 Cargo 安装：

cargo binstall oxcode-cli   # prebuilt, no compile
cargo install --force oxcode-cli   # build from source

这会安装一个 oxcode 二进制文件——其中包含 CLI 和 MCP 服务（oxcode mcp）。（由于 crates.io 上的 oxcode 名称已被占用，crate 名为 oxcode-cli；命令仍为 oxcode。）要替换现有安装，请重新运行安装程序（或运行 cargo install --force oxcode-cli）；升级到 v0.1.2+ 后，oxcode mcp 也会在启动时自动更新。

2. 为项目建立索引

cd your-project
oxcode index
oxcode context "How does authentication work?"

3. 接入 Agent（MCP）

将服务添加到你的 Agent。对于 Claude Code（~/.claude.json）：

{
  "mcpServers": {
    "oxcode": { "type": "stdio", "command": "oxcode", "args": ["mcp"] }
  }
}

接入后，让 Agent 调用一次 oxcode_watch：它会构建索引，并在文件发生变化时保持索引最新。如果省略 path，项目根目录将从 OXCODE_ROOT、CLAUDE_PROJECT_DIR 或 WORKSPACE_FOLDER_PATHS 获取，而不是从 MCP 进程的 cwd 获取（宿主通常会在 $HOME 中启动服务）。同一代码库上的多个 Agent 会通过文件锁选出一个写入者（负责监听／重新索引），其余 Agent 则提供读取服务，因此你可以按需运行任意多个 Agent。然后通过 oxcode_explore 提问。

你也可以在 ~/.claude/settings.json 中设置自动允许这些工具（查询工具为只读；oxcode_watch 只会构建／维护本地索引）： mcp__oxcode__oxcode_watch、_explore、_search、_callers、_callees、 _symbol、_files、_status。

Claude Code 插件（一条命令安装）

无需手动编辑上述配置，只需从 oxgraph marketplace 安装捆绑插件——它会为你接入 MCP 服务：

/plugin marketplace add oxgraph/oxgraph
/plugin install oxcode@oxgraph

插件仍需要你的 PATH 中有 oxcode 二进制文件，并且项目已建立索引 （步骤 1–2）。请参阅 claude-plugin/README.md。

其他 MCP 客户端（注册表／npm）

oxcode 已列入官方 MCP Registry，条目为 io.github.snowmead/oxcode，因此支持注册表的客户端可以发现它。对于更倾向使用 npx 启动命令的客户端，也提供了一个 npm 包：

{
  "mcpServers": {
    "oxcode": { "command": "npx", "args": ["-y", "@snowmead/oxcode-mcp"] }
  }
}

@snowmead/oxcode-mcp 是一个运行 oxcode mcp 的轻量封装，因此仍需要你的 PATH 中有 oxcode 二进制文件（步骤 1）——如果已安装，使用上面的 command: "oxcode" 配置会更简单。

索引工作原理

1. 提取 — tree-sitter 将每个源文件解析为语法树。按语言实现的提取器会遍历语法树（手写），或运行 tree-sitter 查询（通用），生成符号节点（文件、模块、类、结构体、trait、接口、函数、方法、字段等）和边（contains、calls、imports、references、implements）。无论语言本身使用何种分隔符，限定名称都会统一规范化为以 :: 连接的内部形式，因此解析器和图都与语言无关。
2. 解析 — 引用会按以下层级解析到跨文件的定义：精确限定名称 → 外层模块作用域 → 作用域内的导入 → 接收者类型 → 简单名称。遇到匹配不唯一的情况时，会保留并标记，而非丢弃。
3. 存储 — 解析后的图会与 oxgraph 数据库协调，使用稳定的符号标识，因此重新索引的复杂度为 O(change)，而非 O(repo)。图上的个性化 PageRank 为 context 命令提供有界且按相关性排序的输出。

语言

运行 oxcode languages 可列出已注册的提取器。支持程度分为以下等级：

语言	扩展名	等级
Rust	.rs	高保真
Go	.go	高保真
TypeScript	.ts .tsx .mts .cts	高保真
JavaScript	.js .jsx .mjs .cjs	高保真
Python	.py .pyi	通用
Java	.java	通用
C	.c .h	通用
C++	.cpp .cc .cxx .hpp .hh .hxx	通用
C#	.cs	通用
PHP	.php	通用
Ruby	.rb	通用
Swift	.swift	通用
Kotlin	.kt .kts	通用
Scala	.scala .sc	通用
Dart	.dart	通用
Lua	.lua	通用
Luau	.luau	通用
Objective-C	.m .mm	通用
Pascal/Delphi	.pas .dpr .dpk .lpr	通用
Svelte	.svelte	嵌入式脚本
Vue	.vue	嵌入式脚本
Liquid	.liquid	已识别

• 高保真 — 手写的提取器，可解析接收者类型的方法调用（self/this/Go 接收者）、精确限定名称和导入（包括基于 TypeScript 路径的 ESM 导入）。
• 通用 — 由上述所有语言共用的查询驱动型提取器。每种语言对应一个 tree-sitter 查询和一个配置项（crates/oxcode-core/src/extract/profiles.rs）；包含关系根据字节范围的嵌套关系确定。它会生成符号和近似调用边，并在作用域级别或简单级别解析这些边（不识别接收者类型），因此部分边会被标记为匹配不唯一。
• 嵌入式脚本 — Svelte/Vue 的 <script> 块会作为 TypeScript 提取，且偏移位置与原组件文件精确对应。
• 已识别 — 文件类型已知，但尚未编入索引；此类文件会报告为已跳过，而非静默丢弃。

添加一种语言只需新增一个 tree-sitter 查询和配置项；若要将其提升为高保真支持，则需编写手动提取器并复用共享的 extract/walker.rs 框架。

快速入门

oxcode index --path path/to/rust/project
oxcode status --path path/to/rust/project
oxcode context "How does entry reach helper?" --path path/to/rust/project --limit 8 --json
oxcode symbols "entry helper" --path path/to/rust/project --limit 20 --json
oxcode symbols "entry helper" --path path/to/rust/project --kind function --kind method
oxcode files "runtime scheduler" --path path/to/rust/project --limit 20 --json
oxcode symbol crate::entry --path path/to/rust/project --json
oxcode calls crate::entry --depth 2 --path path/to/rust/project
oxcode callers crate::helper --depth 2 --path path/to/rust/project
oxcode query "MATCH ELEMENTS WHERE qualified_name = 'crate::entry'" --path path/to/rust/project
oxcode query "MATCH RELATIONS TYPE calls" --format expand --path path/to/rust/project
oxcode query "GRAPH calls WALK FROM 12 DEPTH 2 DIRECTION both LIMIT 100" --path path/to/rust/project

生成的 .oxcode/ 目录会写入自己的 .gitignore，因此索引不会意外提交。

导航命令的实用选择器：

• element:<id>：指定的 OxGraph 元素 ID
• 完整的 crate 限定名称，例如 my_crate::auth::tenant_middleware （限定名称以 crate 为起点，因此第一段是包名称，其中的 - 会规范化为 _）
• name:<name>：简单的函数名称
• file:<path>:<line>：覆盖源代码行的最内层符号

symbols 接受可重复指定的 --kind <kind> 筛选器。有效类型包括：

• file、module、namespace、package、class、struct、enum、 trait、interface、impl_block、function、method、field、 variable、constant、type_alias、macro

context 是确定性的，并从图中生成。它会根据任务文本为入口点符号排序，然后扩展附近的 calls、contains、references 和 implements 关系。

query 和 explain 执行原始 OxQL/Cypher。要发现关键词，请使用 symbols；不要将普通英语短语传给 query。

支持的 OxQL 配置：

• CATALOG
• MATCH ELEMENTS
• MATCH ELEMENTS HAS LABEL <label>
• MATCH ELEMENTS WHERE <property> = '<value>'
• MATCH RELATIONS TYPE <type>
• GRAPH calls WALK FROM <element-id> DEPTH <n> [DIRECTION outgoing|incoming|both] [LIMIT n]

基准测试

在 Tokio 代码库上的 Agent 任务基准：Agent 分别在使用和不使用每种工具的情况下回答 “tokio 如何调度并运行异步任务？”，并衡量效率和盲评答案质量。oxcode 和 codegraph 使用了不同的 Agent 测试框架，因此可比指标是每种工具相对于自身无工具基线的改进，而不是绝对数值。

组别	答案质量	token 数	成本	工具调用次数	耗时
基线（无工具）	0.98	—	—	—	—
oxcode — codex/gpt-5.5，CLI，n=6	0.96（并列）	+15%	+4%	−4%	+14%
oxcode — codex/gpt-5.5，MCP，n=6	0.93	−74%	−57%	−84%	−60%
codegraph — Opus 4.8，MCP，已发布	未测量	−38%	持平	−57%	−18%

百分比表示相对于该工具自身无工具基线的变化（负值 = 减少，即更好； 质量为盲评 LLM 评审分数，范围为 0–1）。所有 oxcode 数据均来自在 Tokio 上进行的一组 n=6 发布套件。绝对中位数：token 数为 395k（基线）→ 455k（CLI） → 104k（MCP）；成本为 $0.17 → $0.18 → $0.07；工具调用次数为 28 → 27 → 5；耗时为 97s → 111s → 39s。

MCP 服务才是亮点。 通过一次调用的 oxcode_explore MCP 工具提供相同的、范围受限且经 PageRank 筛选的上下文——而不是让 Agent 自行组合 CLI 命令——相较于无工具基线，工具调用次数减少 84%、token 数减少 74%、成本降低 57%、耗时缩短 60%，超过 codegraph 已发布的降幅（工具调用次数 −57% / token 数 −38%）。CLI 组与基线在统计上持平：Agent 将 shell 二进制工具视为自身 grep/read 操作的补充，而非替代品，因此差距始终在于工具交付方式，而非索引质量。质量门槛揭示的一项代价（而像 codegraph 那样不关注质量的基准会掩盖这一点）：MCP 的答案质量降至 0.93，而基线为 0.98，这是精简探索带来的完整性权衡。codegraph 数据来自其 README，并于 2026-06-02 重新验证。

完整的方法、置信区间和复现步骤： docs/agent-eval-results.md 和 docs/agent-eval-methodology.md。

架构

此工作区采用混合式 Rust 架构：

• oxcode-model：供整个工作区共享、与存储无关的词汇体系——代码图谱类型、标识符新类型、图谱架构目录、选择器语法、提取/解析中间表示，以及面向 Agent 的报告数据传输对象
• oxcode-core：索引、提取、引用解析、OxGraph 存储、导航、格式化，以及公开的 ProjectIndex 门面
• oxcode-cli：oxcode 二进制程序——CLI 命令以及 oxcode mcp 子命令。该子命令是一个 MCP 服务（stdio），向编码 Agent 提供只读查询（包括一次调用即可完成操作的 oxcode_explore 工具，以及 oxcode_search、oxcode_callers/oxcode_callees、oxcode_symbol、oxcode_files、oxcode_status），还有 oxcode_watch，它会构建索引并在文件变更时保持索引最新——跨进程文件锁会为每个仓库选出一个写入方，其他实例则提供读取服务

oxcode-core 拆分为多个职责明确的内部模块：scan、extract（包含各语言的提取器和共享的 CST/cargo 辅助工具）、resolve、store::oxgraph（包含其 write 路径）、format、paths 和 error。模型 crate 中的类型化架构是唯一可信来源，存储层据此生成属性注册、读取键缓存和索引。读取操作通过 ProjectIndex 执行，它只打开一次数据库并解析属性键架构；ProjectIndex::with_session 则通过同一个共享快照执行多次读取，确保多步导航在内部保持一致。

extract 模块包含手写提取器（Rust、Go、TypeScript/JavaScript）、由查询驱动的通用提取器（包含各语言的 .scm 查询和配置）、Svelte/Vue 嵌入式脚本宿主，以及静态链接的 grammar 注册表。请参阅上方的 Languages 表格。