省token利器实测：CodeGraph、AOCI与Understand Anything怎么选

大家好，我是邵奈一，一个爱折腾的实战派技术博主。
文章对你有帮助是我的荣幸，欢迎评论区交流。

0x00 为什么你的 token 账单在悄悄爆炸

大模型编程助手普及之后，开发者普遍遇到一个反直觉的现象：代码没多写几行，token 消耗却逐月攀升。根因不在“模型爱废话”，而在“上下文喂法”低效。

传统做法把整仓库塞进上下文，或让 Agent 反复 grep、反复读同一个文件。仓库越大，重复扫描、重复加载的 token 越多，账单随之膨胀。更麻烦的是“符号—语义双编码”问题：代码里只有符号（函数名、类型），Agent 缺少“这段业务为什么这么写”的语义，只能靠反复读源码去猜，token 进一步浪费。

本文横评三款面向代码的“认知工具”——它们解决的是同一件事：让 Agent 一次拿到该拿的知识，少做无效扫描，从而压住 token 账单。三者定位不同、配合使用效果最佳：

• CodeGraph：按需检索。把仓库建成知识图谱，Agent 用 query/callers/context 精准取相关代码，不整库塞上下文。
• AOCI-CODE：持久认知。把代码与数据库知识蒸馏成“可版本化、一次读全”的认知索引，Agent 读索引而非逐文件扫源码。
• Understand Anything：可视化。多智能体流水线把仓库变成可交互知识图谱仪表盘，人和 Agent 都能快速定位。

说明：本篇 CodeGraph 部分为本机真跑（@colbymchenry/codegraph 0.9.6，codegraph –version 确认；注意 npm 当前最新为 1.6.0，0.9.6 与 1.x 行为有差异，本文按 0.9.6 实测并逐处标注；npm 安装名为 @colbymchenry/codegraph，并非同名裸包 codegraph——裸 codegraph v1.0.0 在 npm 上是另一个无仓库链接的空包，避免误装）；AOCI-CODE 与 Understand Anything 因运行形态所限（前者未在本机安装、后者是 Claude Code 等 14+ 平台插件），按官方 README / INSTALLATION_GUIDE / USAGE_GUIDE 逐命令核对，与官方文档不符、照抄会报错的命令都已单独标出。

0x01 三款工具定位与分工

AOCI-CODE 论文（arXiv:2605.02421，Jinshi Liu 等）用两组硬数据验证了“省 token”这条路：一组是 4 个项目 × 3 模型 × 6 上下文长度（每组合再跑约 30 个任务，合计 2160 次评估），AOCI 准确率优于所有可部署基线、仅次于 Oracle 上界；另一组是跨 5 个系统的 19 个工业任务，AOCI 实现零最终缺陷，而三个主流 agent 工具在 12 个任务里引入了缺陷、且多消耗 4–130× token（p<0.001）。这套“用结构化认知替代暴力上下文”的思路，正是本文三款工具的共同底层逻辑（4–130× 的量化结论来自 AOCI 的评估，CodeGraph / UA 是机制同源的设计）。

0x02 三款工具快速上手（安装 / 配置 / 首用）

下面给三款工具各写一条“能直接照抄跑通”的入门路径，命令均来自各自官方 README / INSTALLATION_GUIDE（colbymchenry/codegraph、aoci-spec/aoci-code、Egonex-AI/Understand-Anything），未脱离官方文档编造。先记一条总纲：这三款都迭代极快，README 命令可能和你装到的版本不一致，装完先 –help 再写命令。

CodeGraph：五分钟给 Agent 装个导航

前提：macOS / Linux 用下面命令；Windows 把 install.sh 换成 install.ps1、用 PowerShell。装完务必开一个新终端——安装器不改当前 shell 的 PATH，旧终端里 codegraph 仍找不到。

# 1) 安装（二选一）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh # 无 Node 依赖，自包含（推荐）
npm i -g @colbymchenry/codegraph # 已装 Node 则用 npm

# 2) 接入编码助手（自动写宿主 MCP 配置，不索引代码）
codegraph install # 自动识别 Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Kiro 等（1.x）

# 3) 进项目初始化
cd your-project
codegraph init # 官方新版 README：一步建好 .codegraph/ 并构建图谱
# 本机 0.9.6 实测为 init 后再 codegraph index（见 0x03），以你装的版本 –help 为准

# 4) 看效果
codegraph ui # 浏览器开 http://127.0.0.1:4747 看图谱（1.x 支持，需先建好索引；0.9.6 无此子命令）
codegraph context "你要干啥" # 按需吐相关函数，省 token 就在这

全程 100% 本地、无 API key、用 better-sqlite3 内置的 SQLite（WAL），不上传任何代码、路径、符号名、查询内容；1.x 另有一项可选的匿名使用统计（安装时询问，只发本地聚合后的日计数），介意就 codegraph telemetry off。

AOCI-CODE：给 Agent 一套可版本化的认知索引

前提：先从官方 Release 下载签名二进制，或从源码 make build 得到 aoci，放到稳定绝对路径。支持 Codex / Claude Code / OpenCode / Cursor（Cursor 只回配置片段，需手贴）。

# 1) 取二进制（二选一）
gh auth login && gh release download v0.1.0-rc10 –repo aoci-spec/aoci-code # 官方签名 Release
git clone https://github.com/aoci-spec/aoci-code.git && cd aoci-code && make build # 或源码构建

# 2) 初始化 + 扫描（写宿主 MCP 配置）
aoci –repo . init –agent codex # 或 claude / opencode / cursor
aoci –repo . scan

# 3) 重启 Agent 会话，让宿主加载新 MCP；然后让 Agent 建索引（把这句话直接发给 Agent）：
# "First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link."

# 4) 校验
aoci –repo . verify # 校验对齐
aoci –repo . doctor # 诊断

⚠️ 一个反直觉的坑：scan 从 Git 取文件清单，aoci.txt / aoci.meta.txt / aoci.code.txt / AGENTS.md 这些认知资产绝不能加进 .gitignore，否则会被静默跳过、索引建不起来；只有宿主配置（.mcp.json 等）才该 gitignore。

Understand Anything：一行装，可视化看懂仓库

前提：在 Claude Code / Codex / Cursor / Copilot / Gemini CLI 等任一平台里操作。

# 1) 安装
/plugin marketplace add Egonex-AI/Understand-Anything # Claude Code 原生
/plugin install understand-anything
# 其他平台（Codex / OpenCode / Gemini / Kiro / KIMI CLI / Trae / Cline 等）一行脚本：
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
# codex 换成你的平台：opencode / gemini / kiro / kimi / trae / cline / vibe …
# 注意：Codex 用 $understand（美元符），不是 /understand；装完重启 CLI/IDE

# 2) 分析仓库（首次会吃较多 token，建议有订阅或用本地模型）
/understand # 多智能体分析，产物存 .understand-anything/knowledge-graph.json
/understand –language zh # 生成中文节点与仪表盘

# 3) 看 / 问 / 持续更新
/understand-dashboard # 开可交互仪表盘
/understand-chat 支付流程怎么走？ # 自然语言问答
/understand-diff # 未提交改动映射到图谱看影响面
/understand-onboard # 新人 onboarding 指南
/understand –auto-update # 挂 post-commit 钩子增量更新

图就是 JSON，可提交进仓库让队友跳过流水线——特别适合 onboarding 和 PR 评审。

0x03 CodeGraph 全链路实测（本机 0.9.6）

我用一个 4 个函数、带调用关系的小工程做端到端验证。命令全部来自本机 codegraph –help，输出为真实运行结果。

初始化与索引：

$ codegraph init .
┌ Initializing CodeGraph
◆ Initialized in /private/tmp/cg_demo
● Run "codegraph index" to index the project
└ Done
# → 生成 .codegraph/（含 .gitignore + codegraph.db）

$ codegraph index .
◆ Scanning files — 2 found
◆ Parsing code — done
◆ Resolving refs — done
◆ Indexed 2 files
● 7 nodes in 315ms

查看索引状态，关键看后端与体积：

$ codegraph status .
Edges: 9
DB Size: 0.14 MB
Backend: sqlite — better-sqlite3 (full WAL)
Journal: wal
Nodes by Kind: function 4 / file 2 / import 1
Files by Language: python 2
✓ Index is up to date

注意 Backend 是 better-sqlite3 内置的 SQLite（本地 .codegraph/codegraph.db，WAL），不是 Node 内置的 node:sqlite 模块——后者 2024 年才随 Node 22.5 作为实验特性加入，Node 20 根本用不了，与本文“本机 v20 实测”自相矛盾。“需要单独装外部数据库”确实是另一个独立 Rust 实现（Jakedismo/codegraph-rust）的架构——它用 SurrealDB + HNSW 向量索引；而“RocksDB 存储”与官方文档不符，两个项目都不用。在 @colbymchenry/codegraph 0.9.6 上，本工具不依赖任何外部数据库，npm 装完即用。

按需检索能力，是真能省 token 的地方。只取相关符号，不加载整库：

$ codegraph query foo
function foo src/utils.py:4 (a: int) -> int
import utils src/main.py:1 from utils import foo, bar

$ codegraph callers helper
Callers of "helper" (1):
function foo src/utils.py:4

$ codegraph callees foo
Callees of "foo" (1):
function helper src/utils.py:1

给一个任务描述，直接吐出相关函数源码，省去 Agent 自己翻文件：

$ codegraph context "compute total of values"
– src/utils.py: foo:4, bar:7
#### run_pipeline (src/main.py:3)
def run_pipeline(values):
total = 0
for v in values:
total += foo(v)
msg = bar("world")
return total, msg
#### foo (src/utils.py:4)
def foo(a: int) -> int:
return helper(a) + 1
#### bar (src/utils.py:7)
def bar(name: str) -> str:
return f"hello {name}"

接 MCP（让编码助手直接调用）：

CodeGraph 的 MCP 走 stdio（codegraph serve –mcp），没有 HTTP 端口，所以不存在“用 curl 测 MCP”这种说法——连上没连上，去宿主的工具列表里看。最省事的是官方一键装，它会自动识别宿主并写入配置：

codegraph install # 自动识别 Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Kiro 等并写入 MCP
codegraph install –target claude –location global # 指定宿主与位置（–target/–location 为真实选项）
codegraph install -y # 非交互：默认 –location=global –target=auto

要手动配，把同一段 JSON 塞进宿主的 MCP 配置文件即可（命令统一是 codegraph serve –mcp）：

{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "–mcp"]
}
}
}

连上后看宿主的工具列表即可确认：0.9.6 的 MCP 暴露 10 个 codegraph_* 工具（search / context / callers / callees / impact / node / explore / status / files / trace）；1.6.0 起收敛为单一 codegraph_explore。

各宿主配置文件位置（国内工具已单列；同款 JSON 套进 mcpServers 字段即可）：

路径以各宿主最新文档为准——这些工具迭代都快，配置文件名也可能变。

0x04 AOCI-CODE：照官方文档落地

AOCI-CODE 的命令以官方 README / INSTALLATION_GUIDE 为准（GitHub 仓库 aoci-spec/aoci-code）。下面把真实用法和几个关键点一次说清，命令逐条对得上官方文档，不瞎编。

• MCP 是原生 stdio，不用自己包。官方 aoci –repo . mcp 直接启动 stdio MCP Server，暴露 9 个工具（aoci_rules / aoci_overview / aoci_get_entries / aoci_search / aoci_maintain / aoci_update_entry / aoci_remove_entry / aoci_header / aoci_report），aoci –repo . init –agent <name> 会把宿主配置一起写进去。
• 语义由模型写，不是 ADR 手写。官方原话 “the model owns semantics”：FRAS（Function / Relations / API / 非显性约束）每条认知由宿主大模型基于源码与证据创作，文档里没有 ADR 这个词；认知资产落在仓库根的 aoci.txt / aoci.meta.txt / aoci.code.txt（数据库卷可选 aoci.database.txt），.aoci/ 只放配置（config.json / baseline.json / curation.json）。

真实命令集（官方文档逐字核对；注意 build / sync / serve / export / entry 都不是 aoci 子命令，源码构建走 make build）：

aoci –repo . init # 初始化 + 集成宿主 MCP
aoci –repo . init –agent <codex|claude|cursor|opencode> # 自动写宿主配置
aoci –repo . scan # 从 Git 取文件清单做索引
aoci –repo . verify / aoci –repo . check / aoci –repo . doctor # 校验 / 检查 / 诊断
aoci –repo . mcp # 启动原生 stdio MCP Server
aoci –repo . cognition plan / bootstrap / migration # 认知规划
aoci –repo . status # 看索引状态
aoci –repo . ui –detach –json # 后台起本地只读面板并回链接（0x02 里 Agent 给的 panel link 就是它）

版本方面，当前最新为 v0.1.0-rc10；授权是 Fair Source（FSL-1.1-MIT），写"开源"不够准确，应说"源码可见"。

0x05 Understand Anything：14+ 平台的仓库仪表盘

Understand Anything 是 TypeScript 写的多智能体工具，把仓库变成可交互知识图谱仪表盘。它的 star 数（实测 81,831）在三者里最高，但有两处命令容易踩坑，下面说清。

第一处：安装命令写成 npx -y tokrepo@latest install <UUID> –target claude-code。这个 tokrepo + UUID 的安装方式，在任何官方文档里都查不到。官方主推的是插件市场：

# Claude Code 内执行
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything

# 或一键脚本（支持 Codex / OpenCode / Trae / VS Code Copilot / Cline / KIMI CLI / Gemini CLI / Kiro 等）
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex # codex 换成你的平台；不给会进交互式选择

第二处：/understand-tour 这个命令并不存在，正确的是 /understand-onboard（生成新人 onboarding 指南，仪表盘自带 guided tour）。

真实命令表（核心几条，其余以官方 USAGE_GUIDE 为准）：

它不是 Claude Code 专属——支持 14+ 平台（Trae / Cline / KIMI CLI / VS Code Copilot / Cursor / Codex 等），这正是它能压住 token 账单的延展性：你在哪个编辑器写代码，它就在哪生效。

0x06 横向对比：这三者到底谁更强、怎么选

先给结论：没有“最强”，它们是三道防线，不是三个对手。单比某一维度各有胜负，下面这张图直接把强弱摆出来。

三维度优势对比（直接看结论）

按诉求一句话选型

• 想立刻给 Agent“装个导航”、少掉反复 grep → CodeGraph（门槛最低、见效最快，本机实测 context 只吐相关函数）。
• 想让团队共享一份“代码认知”、跨会话不重算 → AOCI-CODE（省 token 最彻底，索引可版本化提交）。
• 想人和 Agent 一起看懂陌生大仓、要可视化 → Understand Anything（理解最强，但首次分析会吃较多 token，建议有订阅或本地模型）。

场景对照表

三者的“省 token”不是互斥，而是分层：CodeGraph 管“检索时别多拿”，AOCI 管“认知要持久别重算”，UA 管“理解要可视别瞎翻”。组合使用，token 账单的膨胀点被三层同时堵住。

需要提醒：这三款都迭代很快，README 描述的命令可能与你 npm / brew 装到的稳定版不一致。凡是带 rc / beta 的项目，装完先跑 –help 再写命令，比抄教程稳。

0x07 我们的建议：基于实测，怎么落地最划算

先把结论摆前面。本文两路证据支撑同一个判断：与其让 Agent 暴力塞整库上下文，不如用“结构化认知”按需供给。一路是本机真跑 CodeGraph 0.9.6——context 只吐相关函数、不加载整库，机制跑得通、输出可复现（见 0x03）；另一路是 AOCI 论文的硬数据——在跨 5 个系统的 19 个工业任务上实现零最终缺陷，而三个主流 agent 工具在 12 个任务引入缺陷、且多消耗 4–130× token（p<0.001，见 0x01）。三款工具不是取代关系，是三道互补的防线。

落到你手上，建议按这个顺序干：

• 第一步，先用 CodeGraph 跑通一个自己的中等仓库，量一下“Agent 读整库”与“按需 context”的 token 差，建立基线——门槛最低、当天就能见效，先拿到“省 token 真的发生了”的体感。
• 第二步，团队场景上 AOCI-CODE，把 aoci –repo . init 接入宿主后，把认知资产（aoci.txt / aoci.meta.txt / aoci.code.txt 与 AGENTS.md）全部提交进仓库——索引本体是那几个 aoci.*.txt，AGENTS.md 只是 init 写入的规则块，少了前者等于没共享到认知。这样团队共用一份索引、跨会话不重算，省 token 最彻底。
• 第三步，陌生大仓 / 交接场景上 Understand Anything，把 /understand-diff 接进 PR 流程，改动影响面一眼可见，减少来回确认。
• 贯穿全程的一条纪律：教程里的命令先 –help 验证再落笔——本文已替你把“自建 MCP”“手写 ADR”“tokrepo 装 UUID”“RocksDB 存储”等不实命令标了出来，但工具迭代快，自己环境仍以 –help 为准。

0x08 装完到底怎么用：三个工具的真实上手姿势

先泼盆冷水：这三个都不是"装完弹个界面让你点"的独立 App。它们的共同身份是"给你的编程 Agent 装外挂"——把能力注进你已经在用的 Claude Code / Cursor / Codex 里。所以"装好了就直接用吗？“答案是：装好只是第一步；真正的"用"，是你照常跟 Agent 说话，它在后台替你调这些工具。 0x02 讲的是"装”，下面讲"用"，把三款各自的"你每天实际敲什么"讲清楚。

CodeGraph：建完索引，之后你啥都不用敲

codegraph install # 写宿主 MCP 配置（Claude Code / Cursor / Codex / opencode …）
cd your-project
codegraph init # 建 .codegraph/
codegraph index # 构建图谱（1.x 一步到位；0.9.6 是 init 后再 index）

索引建好之后，日常你完全不用碰 codegraph 命令。正常在编辑器里让 Agent 改代码即可——它自动通过 MCP 调 codegraph_explore（1.x）这类工具取相关代码，你体感到的只是"它猜得更准、读文件更少"。想亲眼验证省 token，自己敲一句：

codegraph context "实现登录重试逻辑" # 只吐相关函数，不加载整库
codegraph ui # 浏览器开 localhost:4747 看图谱（1.x）

一句话：CodeGraph 的"用"，用在你已有的 Agent 上，不在 codegraph 命令上。

AOCI-CODE：装好二进制后，先让 Agent 建一次索引

# 拿到 aoci 二进制（官方签名 Release 或 make build），放到稳定绝对路径
aoci –repo . init –agent codex # 写宿主 MCP 配置
aoci –repo . scan # 从 Git 取清单建基线
# 重启 Agent 会话，让宿主加载新 MCP

关键一步，很多人卡在这：装好千万别以为能直接受益。你要把这句话直接发给 Agent，让它把语义索引建出来：

First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link.

建完之后，日常你只管让 Agent 干活，它读 aoci.txt / aoci.meta.txt / aoci.code.txt 这几个认知文件，而不是逐文件扫源码。你手动敲的命令基本只剩健康巡检：

aoci –repo . verify # 校验对齐
aoci –repo . doctor # 诊断

如果 Agent 没自动回面板链接，手动跑 aoci –repo . ui –detach –json 也能开本地只读面板。

一句话：AOCI 不是"装完即用"，是"装完 → 让 Agent 建一次索引 → 之后自动用"。 语义是模型写的，第一次必须跑。

Understand Anything：唯一要你主动敲命令的，跑一次 /understand

/plugin marketplace add Egonex-AI/Understand-Anything # Claude Code 内
/plugin install understand-anything
# 其他平台一行脚本：curl -fsSL …/install.sh | bash -s codex；装完重启 CLI/IDE

然后在 Agent 会话里主动触发分析（这是它和前两款最大的不同——你要亲手发令）：

/understand # 多智能体分析，产物落 .understand-anything/knowledge-graph.json
/understand –language zh # 中文节点与仪表盘
/understand-dashboard # 开可交互仪表盘
/understand-chat 支付流程怎么走？ # 自然语言问答
/understand-diff # 未提交改动映射到图谱看影响面

注意平台前缀：Claude Code / Cursor 等用斜杠 /understand；Codex 用美元符 $understand，不是斜杠。装完第一次分析会吃较多 token（建议有订阅或本地模型），之后仪表盘和问答随时调用。

一句话：UA 的"用" = 装完手动跑一次 /understand，后面看板 / 问答随用随取。

三款日常用法一句话对照

• CodeGraph：建索引后躺平，Agent 后台自动调；你想看就 codegraph ui。
• AOCI-CODE：装完先让 Agent 建一次索引，之后自动读，你只做 verify / doctor 巡检。
• Understand Anything：装完主动敲 /understand 分析一次，仪表盘和问答就活了。

共性：它们都不是你的新工作台，是你现有 Agent 的"外挂内存"。 别指望装完有个 App 弹出来——它活在你的编辑器里。

0xFF 总结

token 账单爆炸，根子在“上下文喂法”。CodeGraph、AOCI-CODE、Understand Anything 分别用“按需检索 / 持久认知 / 可视化”三套机制把无效 token 压下去。本文里 CodeGraph 是全链路真跑（0.9.6 实测输出可复现），AOCI 与 UA 的命令均按官方文档逐条核对——网上流传的“自建 MCP”“手写 ADR”“tokrepo 装 UUID”“RocksDB 存储”等说法，照做必错。

工具在进化，命令也在变。把“先 –help、再落笔”刻进工作流，比记住任何一条具体命令都管用。

邵奈一 三百篇原创沉淀，十万+读者同行。感谢你的阅读，咱们下篇接着聊。