Aptu Coder

aptu-coder

一个模型上下文协议（MCP）代码智能服务，为 AI 编码 Agent 提供预解析的符号表和调用图，而非原始文件字节；在引用的基准测试条件下，最多可减少 59% 的 token 使用量（参见 基准测试）。已获 OpenSSF 银级认证：达到此级别的开源项目不到 1%。

说明

原生 Agent 工具（正则搜索、路径匹配、文件读取）很适合处理有针对性的查找。aptu-coder 负责机械性的非 AI 工作：映射目录结构、提取符号和追踪调用图，让编码 Agent 的上下文窗口用于推理，而不是每次调用时重新推导结构。

大多数面向 AI Agent 的代码智能工具会将代码库索引到云端嵌入或向量存储中，并通过相似度搜索检索。aptu-coder 则使用 tree-sitter 在设备本地将代码库解析为结构图，并通过 MCP 在本地提供服务：源代码不会离开设备，检索结果是精确的（符号表和调用图），而非近似的（最近邻相似度）。

基准测试

在 Claude Code 上针对 Django（Python）源代码树执行的身份验证迁移任务。完整方法。

模式	Sonnet 4.6	Haiku 4.5
MCP	112k tokens，$0.39	406k tokens，$0.42
原生	276k tokens，$0.95	473k tokens，$0.53
节省	减少 59% 的 tokens，节省 59% 的费用	减少 14% 的 tokens，节省 21% 的费用

在 Claude Code 上针对 OpenFAST（Fortran）源代码树执行的 AeroDyn 集成审计任务。完整方法。

模式	Sonnet 4.6	Haiku 4.5
MCP	472k tokens，$1.65	687k tokens，$0.72
原生	877k tokens，$2.85	2162k tokens，$2.21
节省	减少 46% 的 tokens，节省 42% 的费用	减少 68% 的 tokens，节省 68% 的费用

在此仓库上进行的一次真实端到端多 Agent 运行：由 coder skill 在一次编排会话中修复五个重构问题（#1578–#1582）——启动 23 个子 Agent（5 个侦察、1 个守卫、10 个构建、7 个检查），耗时约 1 小时 42 分钟，期间有三次人工干预——最终生成 PR #1584–#1588，全部合并且 CI 通过。案例研究。

基准测试结论的适用范围

上述 token 节省数据来自一些单一、专注的理解任务，在这些任务中，Agent 使用 aptu-coder，而非 shell 搜索。Agentic 编码循环可以使用 bash 和 ripgrep，直接搜索代码仓库。v19 基准测试计划（N=20 个配对会话，预注册的结论门槛）测量了 aptu-coder 在这些循环中的表现：在结构性扇入任务上，与 bash + ripgrep 相比，答案质量没有可测量的提升（汇总配对 F1 差值均值 -0.071，95% CI [-0.179, +0.038]；门槛结论为 NOT-SUPPORTED）；直接呈现工具时，工具本身的激活表现可靠。推荐用途：确定性验证（使用 verify_anchors 核验伪造的 path:line 引用）、为多 Agent 工作流提供前提依据，以及用于非 Agentic MCP 消费者（IDE 助手、CI 作业、评分流水线）。

概述

aptu-coder 是面向编码 Agent 的理解层：它为 Agent 框架提供关于代码库、目录树、符号定义和调用图的精确结构上下文，无需 Agent 读取原始文件或在每次调用时重新推导结构。这能避免 Agent 在大型或陌生代码库中遭遇上下文匮乏，同时将结果集控制在足够小的范围内，以适配模型的上下文窗口。它支持 18 种语言（参见支持的语言），并可与任何兼容 MCP 的编排器集成。

结构上下文只需构建一次，之后即可重复使用：基于 blake3 内容哈希键控的磁盘缓存，能确保并发写入期间的结果仍然准确。下方的知识图谱资源接口也基于同一结构图构建。对于持有源代码文本但没有磁盘路径的使用方，aptu-coder-core 还通过公共 Rust 库 API 提供 analyze_str（参见 ARCHITECTURE.md）。

有关设计理念的延伸阅读：Agentic SDLC 治理技术栈、面向多 Agent 可靠性的上下文工程和编排 AI Agent：子 Agent 架构。

支持的语言

语言	扩展名
Astro	.astro
C/C++	.c、.cc、.cpp、.cxx、.h、.hpp、.hxx
C#	.cs
CSS	.css
Fortran	.f、.f77、.f90、.f95、.f03、.f08、.for、.ftn
Go	.go
HTML	.html、.htm
Java	.java
JavaScript	.js、.mjs、.cjs
JSON	.json
Kotlin	.kt、.kts
Markdown	.md、.mdx
Python	.py
Rust	.rs
TOML	.toml
TSX	.tsx
TypeScript	.ts
YAML	.yaml、.yml

安装

Homebrew（macOS 和 Linux）

brew install clouatre-labs/tap/aptu-coder

更新：brew upgrade aptu-coder

cargo-binstall（无需 Rust）

cargo binstall aptu-coder

cargo install（需要 Rust 工具链）

cargo install aptu-coder

快速开始

从源代码构建

cargo build --release

二进制文件位于 target/release/aptu-coder。

配置 MCP 客户端

有两种传输方式可用。使用会启动委派任务的编排器（例如 goose coder）时，建议使用 Streamable HTTP：编排器和所有 Agent 共享一个服务进程，避免每个 stdio 子进程都有独立实例时出现的扩展漂移。

Streamable HTTP（多 Agent 设置推荐）

使用 Homebrew，一条命令即可让服务在登录时启动并保持运行：

brew services start aptu-coder

Homebrew formula 默认在端口 49200 上启动服务。然后只需将扩展添加一次到 ~/.config/goose/config.yaml：

extensions:
  aptu-coder:
    type: streamable_http
    uri: http://127.0.0.1:49200/mcp
    name: aptu-coder
    timeout: 300

或者用于 Claude Code：

claude mcp add --transport http aptu-coder http://127.0.0.1:49200/mcp

若要使用其他端口，请在重启前设置 APTU_CODER_PORT：

APTU_CODER_PORT=4000 brew services restart aptu-coder

若要不通过 brew services 直接启动：

aptu-coder --port 49200
# or equivalently
APTU_CODER_PORT=49200 aptu-coder

stdio（单客户端使用）

适用于只有一个进程需要该服务的情况。客户端负责进程生命周期管理，并会自动启动服务：

claude mcp add --transport stdio aptu-coder -- aptu-coder

或者在项目根目录的 .mcp.json 中手动添加（通过版本控制与团队共享）：

{
  "mcpServers": {
    "aptu-coder": {
      "command": "aptu-coder",
      "args": []
    }
  }
}

工具

所有可选参数均可省略。analyze_directory、analyze_file 和 analyze_symbol 的共享可选参数：

参数	类型	默认值	描述
summary	boolean	auto	紧凑输出；超过 50K 字符时自动触发
cursor	string	--	上一条响应中 next_cursor 的分页游标

页面大小由服务端控制；客户端没有 page_size 参数（传入该参数会返回 INVALID_PARAMS）。

工具	用途	语言
analyze_directory	显示目录树以及代码行数、函数和类的数量；遵循 .gitignore；输出中的文件路径相对于工作目录	所有
analyze_file	显示函数、类和导入项，以及签名和行范围；对于不支持的扩展名，返回正常回退结果（行数、文件开头内容、不含 AST）	所有
analyze_module	轻量级函数和导入项索引（比 analyze_file 小约 75%）；对于不支持的扩展名，返回正常回退结果（空索引并附注释）	所有
analyze_symbol	跨目录查询指定符号的调用图；调用方、被调用方、调用深度	所有
edit_overwrite	创建或覆盖文件；会创建父目录	任意文件
edit_replace	替换唯一匹配的精确文本块，或替换所有不重叠的匹配项（replace_all=true）；匹配项为零个或多个时会报错；new_text 为空时删除该文本块；匹配前会将 CRLF 规范化；可选的 expected_content_hash（原始字节的 blake3 十六进制值）会拒绝过时的编辑；对同一文件的并发编辑会按路径串行处理；返回 occurrences_replaced 数量。批量形式：传入 edits[]（包含 {old_text, new_text, replace_all} 的数组）来替代 old_text/new_text，从而对单个文件原子地应用多项替换（任意编辑无效都会中止，并返回按索引排列的错误，不写入文件）	所有
exec_command	运行 shell 命令；返回 stdout、stderr 和退出代码；输出有长度上限并经过筛选；请求取消时会终止命令；服务端控制退出后的排空窗口（默认 500 ms）；在启动前会拒绝 heredoc（文件写入模式、消耗 stdin 的标志、stdin 参数冲突或缺少结束分隔符）；structuredContent 仅携带元数据（退出代码、截断标志、采集错误标志），命令输出位于文本流中	任意
verify_anchors	批量验证相对于工作区根目录的路径:行号[:符号]锚点：文件存在、1 起始的行号在范围内，以及可选的符号在前后 2 行窗口内匹配（按单词边界匹配）；采用失败即关闭语义，绝不伪造成功；structuredContent 为每个锚点携带一项判定（exists、in_range、symbol_found、window_line）	所有

工具参数、约束和示例可通过 MCP 客户端的工具检查器或 tools/list 响应查看。

知识图谱

analyze_symbol 会在执行过程中为代码库构建结构图：将文件、符号和模块作为节点，并通过类型化边（contains、calls、imports）连接起来。该图会作为 MCP 资源模板提供给 Agent，用于探索超出单个符号直接调用图范围的关系。资源通过 URI 寻址；使用 resources/templates/list 发现可用模板。

URI 模板	描述
aptu-coder://graph/{repo_hash}/blast-radius/{symbol}?depth={depth}&format={format}	从一个符号开始进行 BFS 遍历，向外扩展至可配置深度（默认值：3）。以放射状布局返回调用方／被调用方链。
aptu-coder://graph/{repo_hash}/subgraph/{symbol}?format={format}	单个符号的完整子图（调用方、被调用方及其连接）。
aptu-coder://graph/{repo_hash}/blast-radius-bidirectional/{symbols}?max_nodes={max_nodes}&depth={depth}&format={format}	从一个或多个以逗号分隔的种子符号开始进行双向 BFS，同时遍历调用方和被调用方。

分页： 结果会分页；传入上一次响应中的不透明 cursor 值，以获取下一页。

深度参数： blast-radius 和 blast-radius-bidirectional 模板接受可选的 depth 查询参数（整数，范围为 1-5，默认值为 3）。

最大节点数参数： blast-radius-bidirectional 模板接受可选的 max_nodes 查询参数（整数，默认值为 50），用于限制遍历过程中访问的节点集合大小。

格式参数： 三种查询类型均接受可选的 format 查询参数（text 或 json，默认值为 json）。当 format=text 时，响应会由 render_subgraph_text 生成为可直接用作提示词的纯文本表示，而非 JSON 节点／边结构。

冷缓存： 首先对目录调用 analyze_symbol 以构建图。图尚未就绪时，资源会返回一条提示信息。

输出管理

对于大型代码库，有几种机制可防止上下文溢出。

分页

如果输出被截断，analyze_file 和 analyze_symbol 会附加一行 NEXT_CURSOR:。将此令牌作为 cursor 传回即可获取下一页。summary=true 和 cursor 不能同时使用；同时传入二者会返回错误。

# Response ends with:
NEXT_CURSOR: eyJvZmZzZXQiOjUwfQ==

# Fetch next page:
analyze_symbol path: /my/project symbol: my_function cursor: eyJvZmZzZXQiOjUwfQ==

exec_command 输出上限

exec_command 会应用三个相互独立的字节级上限，防止大型命令输出占满上下文：

流	上限	行为
stdout	30,000 个字符	保留末尾；保留最后 30k 个字符
stderr	10,000 个字符	保留末尾；错误会显示在末尾
combined output_text	50,000 个字符	交错输出后的安全上限

30k 的 stdout 上限是根据数据设定的：对 27,981 次已观察到的 exec_command 调用进行分析后发现，只有 0.33% 超出此上限。触发任意上限时，响应中会设置 output_truncated: true，并将其记录在 JSONL 指标中。

恢复受限输出： 输出达到上限时，响应会包含 MCP 资源链接（aptu-overflow://slot-{seq}/stdout、/stderr、/interleaved），指向该次调用的完整原始捕获内容（以最近一次运行的结果为准）；通过 resources/read 读取。如果输出因过滤器而受限，提示行会指向过滤前的捕获文件。

服务端会在进程退出后设置一个排空等待窗口（500 ms），等待仍占用管道的后台子进程。如果等待窗口结束时管道尚未关闭，exit_code 将为 null，并设置 output_truncated: true。

exec_command 输出过滤器

内置过滤器表会在输出传给模型之前，抑制会产生大量冗余内容的 CLI 工具按文件输出的噪声。过滤器仅在命令成功时应用于 stdout、stderr 和交错输出；命令失败时始终保留原始输出。

命令	行为
git pull	去除 diff-stat 噪声（管道符号、create mode、delete mode、rename、mode change 行）；输出为空时替换为 ok (up-to-date)
git fetch	去除 From 和 ref-range 行；最多保留 10 行；输出为空时替换为 ok fetched
git push	去除 remote: 进度行和 To 目标行；最多保留 10 行；输出为空时替换为 ok pushed
git log	最多保留 20 行
git status	最多保留 20 行
git show	去除补丁块（@@ 标题行以及 +/- 差异行）；最多保留 200 行
git commit	去除 GPG 签名和 gitleaks 钩子输出；最多保留 10 行；输出为空时替换为 ok committed
git diff	去除 ANSI 转义序列；最多保留 100 行；输出为空时替换为 ok (working tree clean)
git add	去除 gitleaks 钩子输出；最多保留 5 行；输出为空时替换为 ok staged
cargo build	去除 Compiling / Checking / Downloading / Fresh 行；输出为空时替换为 ok (build clean)
cargo test	去除 Compiling / Checking / Fresh 行

可以在 .aptu/filters.toml 中添加项目本地规则。解析错误和无法识别的 schema_version 值（version != 1）会回退到内置表，并记录警告；不会发生崩溃。触发过滤器时，structuredContent 中的 filter_applied 会指出匹配的规则。

非交互式流水线

在单次处理的子 Agent 会话中，提示词缓存会写入，但不会被复用。基准测试显示，MCP 响应写入缓存的内容约为仅使用原生工作流时的 2 倍，增加了成本，却没有带来质量提升。设置 DISABLE_PROMPT_CACHING=1（或在 Haiku 专用流水线中设置 DISABLE_PROMPT_CACHING_HAIKU=1），即可避免这项额外开销。

服务自身的指令刻意保持精简，只有一个简短段落：首先使用 analyze_directory 获取包／模块映射，然后使用 analyze_module／analyze_file 查看每个文件的详细信息，并使用 analyze_symbol 获取调用图；此外还会指向 docs/METRICS.md，其中包含 JSONL 指标和 jq 示例。会展示服务指令的 MCP 客户端会自动向 Agent 呈现这些指引。

环境变量

缓存和运行时

变量	默认值	描述
APTU_CODER_DIR_CACHE_CAPACITY	20	目录分析结果的 LRU 缓存大小。
APTU_CODER_DISK_CACHE_DIR	$XDG_DATA_HOME/aptu-coder/analysis-cache	L2 调用图缓存和 analyze_symbol 使用的结构图缓存的共享目录。目录不存在时会自动创建。
APTU_CODER_DISK_CACHE_DISABLED	unset	设置为 1 可完全禁用 L2 调用图磁盘缓存。
APTU_CODER_DISK_CACHE_MAX_BYTES	536870912 (512 MiB)	结构图磁盘缓存的最大字节数。超出时会按修改时间运行 LRU 淘汰。
APTU_CODER_FILE_CACHE_CAPACITY	100	文件分析结果的 LRU 缓存大小。
APTU_CODER_METRICS_EXPORT_FILE	unset	关闭时一次性导出 JSONL 指标的绝对路径。
APTU_CODER_PORT	unset	可流式传输的 HTTP 模式的端口。等同于 --port N；优先使用 --port。未设置且未传入 --port 时，将使用 stdio 模式。
APTU_CODER_BEARER_TOKEN	unset	用于可流式传输的 HTTP 传输身份验证的 Bearer 令牌。值少于 32 个字符时会记录警告。
APTU_SHELL	unset	exec_command 使用的 Shell。默认依次使用 bash 和 /bin/sh。

可观测性

有关 JSONL 架构、OTel 配置和 span 属性策略，请参阅：

• OBSERVABILITY.md（仓库根目录）
• docs/METRICS.md

文档

• AGENTS.md - 贡献者参考：项目结构、命令、rmcp 注意事项、工具参数约束
• ARCHITECTURE.md - 设计目标、模块映射、数据流、语言处理器系统、缓存策略
• CONTRIBUTING.md - 开发工作流、提交约定、PR 检查清单
• DESIGN-GUIDE.md - 设计决策、设计依据，以及构建高性能 MCP 服务的复现指南
• MCP Best Practices - 关于 Agent 循环、编排模式、MCP 工具设计、内存管理和安全控制的最佳实践
• METRICS.md - 指标架构、JSONL 格式和保留策略
• ROADMAP.md - 开发历史和未来方向
• SECURITY.md - 安全策略和漏洞报告

许可证

Apache-2.0。详情请参阅 LICENSE。