AOCI-CODE 代码库认知索引系统

关注

原创 2026-10-09 16:07:53 290 阅读 AI 写同款· GEO 优化 ›

大模型代码理解工具选型：CodeGraph、AOCI与Understand Anything对比在大模型辅助编程中，上下文窗口限制和token消耗是常见瓶颈。代码理解工具通过将代码压缩为结构化表示，减少无效信息，从而节省token。其原理包括抽象语法树解析、图结构构建和语义索引，技术价值在于提升代码分析效率。应用场景涵盖依赖分析、重构评估和大型仓库检索。本文对比CodeGraph、AOCI和Understand Anything三款工具，基于实测给出选型建议，帮助开发者在不同场景下优化token使用。阅读详情

AOCI-CODE 关注点速记

适用版本：v0.1.0-rc19（FSL-1.1-MIT，Fair Source）
文档生成日期：2026-10-09

1. AOCI-CODE 是什么

一个由编码代理（LLM）维护、随 Git 版本管理的代码库认知索引系统。它生成一份由代理一次性写就、随代码自动演进的"系统蓝图"（Whole-Index），让 AI 代理在每次任务开始前就能理解整个项目结构，避免重复阅读代码。

核心价值：

大型项目（实测 70 万行 / 索引约 30 万 token）下，代理先通读索引再动手，减少多路径遗漏、接口契约猜测、模式不一致等缺陷。
索引本身本地、纯文本、可 Git 版本化，跨会话、跨人、跨代理持续可用。
首次索引后维护自动化，MCP 检测变更 → 触发增量更新 → 用户无需手动维护。

2. 与 GitNexus 的对比

维度	AOCI-CODE	GitNexus
核心方法	LLM 写语义摘要（FRAS）	Tree-sitter 解析符号图谱
确定性	半确定（受模型影响）	完全确定
构建成本	高（首次约 1 小时/20 万行）	低（即时）
Token 效率	极高（20.25% 预算，1.71x 性能）	高（预计算结构）
语义深度	深（捕获非显性约束）	浅（仅结构）
精确检索	弱（强项是"先通读"）	强（impact/query/context）
数据库支持	支持（PG/MySQL/openGauss）	不支持
版本化	Git 版本化、可回滚	不版本化
上手难度	中高（需理解协议）	低（输入 URL 即用）
商业许可	FSL-1.1-MIT	PolyForm Noncommercial
适合场景	大型长生命周期系统、需要语义理解与可治理索引	快速接入、轻量级依赖分析

AOCI 自述与 CodeGraph 类工具互补使用——索引负责"知道系统"，CodeGraph 负责"工作中精确取代码"。

3. 组件与原理

AOCI 由三部分组成：(1) 模型负责语义——LLM 阅读源码、测试、配置与数据库结构，为每个托管对象写一条 FRAS 摘要（F 职责 / R 强关联 / A 公共契约 / S 非显性约束），并附上架构定位标签；(2) AOCI-CODE 负责治理——它通过本地 MCP 服务器维护一份由 aoci.txt（Root）、aoci.meta.txt（Meta，存标签字典与 FRAS 规则）、aoci.code.txt（Code 卷）、aoci.database.txt（Database 卷，可选）组成的 Whole-Index，用 SHA-256 校验、CAS 原子写与 Ledger 机制保证索引与代码在 Git 中同步演进、可 diff、可回滚；(3) 代理按"读—做—养"循环工作——任务开始前先通读 Whole-Index 取得全局认知，开发完成后 MCP 自动检测变更并触发增量更新。运行时不联网、不存储凭据。

关键文件布局：

aoci.txt                      Root：当前 CognitionSet 入口
aoci.meta.txt                 Meta：标签字典、FRAS 规则、撰写约束
aoci.code.txt                 Code：模型写的代码/资产条目
aoci.database.txt             Database：可选表级条目
.aoci/
├── config.json               团队策略、Locale、Scope、预算
├── baseline.json             Source/Index/Database 的治理 Baseline
├── curation.json             文件级 include/exclude 决策
└── ...                       Drafts、Ledger、事务、恢复证据（默认不入库）

4. 是否需要单独配置 LLM / 调用外部模型

不需要单独配置，但确实依赖外部模型。 具体表现为：

AOCI-CODE 本身不是 LLM 调用客户端，它只是本地 CLI + MCP 服务器，不会自己去请求任何模型 API。
整个 FRAS 摘要生成、Whole-Index 阅读、增量更新——这些"思考"环节都由当前 MCP 主机里已经在跑的代理模型完成（Claude Code / Cursor / Codex / OpenCode 等）。
不需要为 aoci 单独配 API Key、模型名、base_url，也不需要单独写 prompt 模板。
DeepSeek 等模型可用，但前提是代理宿主支持标准 stdio MCP 并能遵循工具契约——只有模型名并不保证兼容。
如果代理没接好模型，索引构建不起来，因为 FRAS 这件事 aoci 干不了。

实际模型使用形态：首次构建索引 ≈ 让代理逐文件读源码并写 FRAS，token 消耗大；这部分调用走的是代理自身的模型通道。日常开发也复用同一个模型。

5. 索引与 Git 仓库的关系

索引直接放在代码仓库内，不是单独一个仓库。

索引文件（aoci.txt / aoci.meta.txt / aoci.code.txt / aoci.database.txt）与源代码位于同一个 Git 仓库的根目录，共享同一份版本历史。
配套状态目录 .aoci/（config.json、baseline.json、curation、ledger 等）也在仓库内。
通过同一套 Git 工作流管理：可以 diff、review、commit、rollback，与代码改动一同进入 PR 流程。
这样设计的好处：可治理（FRAS 摘要随代码改动一起进 PR，code review 时可一并审查）、跨会话/跨人/跨代理无感切换、可回滚（索引改坏了，git revert 就能回到上次对齐状态）。

路径	是否入库	说明
`aoci.txt`、`aoci.meta.txt`、`aoci.code.txt`、`aoci.database.txt`	✅ 必须提交	索引本体，Whole-Index 的一部分
`AGENTS.md`	✅ 必须提交	AOCI 的规则块，代理据此行为
`.aoci/config.json` / `baseline.json` / `curation.json`	✅ 通常提交	团队策略、Scope、Baseline 等治理事实
`.aoci/` 下的 Drafts / Ledger / 事务 / 恢复证据	❌ 默认不入库	`.gitignore` 已默认排除
`.mcp.json` / `.claude/settings.json` / `.codex/config.toml` / `opencode.json`	❌ 必须忽略	路径是机器绑定的绝对路径，换机器必坏

易踩坑的点：

init 写入的 aoci.*.txt 和 AGENTS.md 不能放进 .gitignore，否则 scan 会直接跳过这些资产，索引永远建不起来。
首次 init 还要确认已存在的 .gitignore 是否已经忽略这些资产，如果有要清掉。
Database Cognition 涉及的连接字符串只允许用环境变量名引用，凭据本身不入索引、不入库。