AOCI-CODE：给编码 Agent 一份可 Git 版本化的全系统地图，本地优先的 MCP 代码索引服务
AOCI-CODE 是一个用 Go 编写的本地优先 MCP 服务 + CLI，在仓库中维护一份持久、可被 Git 版本化的全系统索引，让 Claude Code、Codex、Cursor、opencode 等 Agent 在动手前先读懂整个系统。模型负责语义、它负责治理，只读本地源码与库表结构，不联网、不存储凭据。
相关标签
项目概览
在 Codex、Claude Code、Cursor、OpenCode 这类编码 Agent 里，模型每接到一个任务，都要先从零把代码库重新”摸”一遍：搜文件、读源码、拼调用关系，然后才开始真正干活。AOCI-CODE 想做的事很直接——在代码库里放一份持久、可被 Git 版本化的”全系统地图”，让 Agent 在动手之前就先读懂整个系统。
AOCI-CODE 是一个用 Go 编写的 本地优先（local-first）MCP 服务 + CLI：它维护一份受治理的代码知识索引，为 Claude Code、Codex、Cursor、opencode 等 Agent 提供长期上下文、记忆与代码智能。索引与代码放在同一个仓库里、由 Git 一起版本化——所以当项目换人接手、切换 Agent、或者开一个新会话时，只要读一遍索引就能接上之前的进度，不必从头再来。
项目地址：https://github.com/aoci-spec/aoci-code
它解决什么问题
- 不必每次都重读代码库。 Agent 一上手就知道每个文件是干什么的、依赖什么、什么不能改坏，于是不再为每个请求都重新搜索和通读源码。
- 一步接管既有系统。 把 Agent 指向一个最多约 50 万行的既有代码库让它建索引，它会报告自己对各区域的掌握程度，然后直接开始后续开发。真正的上限是索引体积而非代码行数——按官方说法，目前已有 70 万行的商业系统以这种方式开发，其索引约为 30 万 token。
- 换人、换 Agent、换会话无需重来。 索引就在仓库里，跟着代码走。
- 首次建索引之后，维护是自动的。 MCP 服务会检测代码变化并给出需要更新的条目，Agent 在完成每个任务时顺手补上，索引始终与当前代码一致。
需要提前知道的预期：首次建索引是要花时间的，大约每 20 万行代码需要一小时，具体取决于模型与 Agent 速度；过程分批进行，中断后可续。
核心概念：FRAS 条目
索引以”一行一个文件“的形式呈现，每个条目由模型根据真实源码撰写。以下是该项目自身索引里的一条真实条目：
atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_exchange_windows.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteCAS,AtomicCreateCAS,AtomicMoveCAS | S:Native publication never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state
这四个字段就是 FRAS：
| 字段 | 回答的问题 | 含义 |
|---|---|---|
| F — Function | 这个对象的核心职责是什么？ | 该对象负责什么 |
| R — Relations | 改动它时必须一起看什么？ | 必须同时理解的强关联对象 |
| A — API | 外部调用方可以依赖什么？ | 它暴露的接口、命令、格式或可观察契约 |
| S — Non-obvious constraints | 还有哪些 F/R/A 之外的重要信息？ | 无法从普通结构推断、但绝不能搞错的关键约束（事务、鉴权、并发、缓存、部署、兼容性、历史包袱等） |
条目末尾的 [CG9L] 是紧凑标签，为对象标注架构层次、功能域、重要度、可选技术特征与规模。几百行这样的条目就能覆盖一整个系统，Agent 一遍就能读完。
索引的组织：Cognition Volumes
AOCI-CODE 维护一份逻辑上的 Whole-Index，但每一类索引各自拥有独立的文件、归属与生命周期：
| Volume | 职责 |
|---|---|
| Root | 声明当前 CognitionSet 的组成、依赖与激活入口；最后发布，以免不完整的资产被误认为完整集合 |
| Meta | 存放标签字典、FRAS 规则、配额与模型撰写契约 |
| Code | 存放代码、测试、配置、文档与运维资产的条目 |
| Database | 存放可选的表级条目，并绑定到已接受的 schema 证据 |
对应到文件即 aoci.txt（Root）、aoci.meta.txt（Meta）、aoci.code.txt（Code）、aoci.database.txt（Database）。每个对象都只有一个合法归属，放错 Volume 会造成归属冲突；而 AOCI-CODE 只在机器能够证明”错误归属者、正确归属者与当前对象事实”时才修复，绝不靠相似命名去猜归属。
与 repo map、RAG、LSP、代码图谱的区别
README 把定位说得很清楚：搜索、AST、LSP、代码图谱、RAG 都擅长结构与检索类问题，而 AOCI-CODE 做的是另一件事——维护一份覆盖受管范围、并随软件增量演进的、带版本的系统描述。它提供的是 Whole-Index（一张完整的系统地图，而非每次任务临时拼凑的碎片）、FRAS 条目、跨会话持久化、显式 Managed Scope、漂移检测、受治理的更新流程与投递证明，以及从权威索引派生出的 Lineage / Relations / Impact / Snapshot / Evolution 等系统投影。
| 方式 | 最擅长回答 | AOCI-CODE 额外补上什么 |
|---|---|---|
| RAG / 搜索 | 与当前问题相关的源码文本在哪里？ | 一份在提问之前就已存在的受管范围描述，包括哪些内容被刻意排除、以及治理状态 |
| AST / LSP / ctags | 符号、类型、定义、引用在哪里？ | 跨源码、测试、配置、数据库与运维资产的职责、意图与维护约束 |
| CodeGraph / 调用图 | 谁和谁相连、路径怎么走？ | 模型撰写的业务语义、长期约束、范围、归属、版本身份与事务化更新 |
| 普通 repo map / 摘要 | 项目大概长什么样？ | 源码绑定、漂移检测、增量维护、评审、恢复与审计 |
| 编码 Agent 本身 | 如何读源码、定计划、改代码、跑工具 | 位于 Agent 之下，提供持久的系统认知，并治理这份认知如何随软件演进 |
结论是互补而非替代：AOCI-CODE 提供全局的、可版本化的系统认知，检索与图谱类工具继续负责它们擅长的局部问题。
分工：模型负责语义，AOCI-CODE 负责治理
这是理解这个项目最关键的一条分界线。
模型拥有”意义”。 宿主模型去读源码、测试、配置、文档等证据，然后判断：某个对象真正负责什么、改动它必须一并考虑哪些强关联、它对外暴露了哪些契约、以及哪些事务/鉴权/并发/缓存/部署/兼容性约束无法从普通结构中推断出来。AOCI-CODE 不会根据文件名、路径、扩展名、AST 或模板去拼装 FRAS，也不会悄悄改写模型写下的内容。
AOCI-CODE 拥有”治理”。 它负责建立安全清单、受管范围与当前 Baseline；投递当前的 Whole-Index 并确认其身份；生成确定性的计划、目标集合与源文件 SHA-256；校验候选结构、标签字典、关系身份、范围、归属、预算与影响区间；保留 check / diff / review 之间的绑定；以跨进程锁、CAS 与原子写提交完整批次；推进 Baseline、追加账本并在写入后失败时保留恢复证据。
值得一提的是它对自身结论的诚实态度：机器全绿（all-green）只代表”结构与治理契约成立”，并不代表模型写下的每一句话都是对的。 README 甚至在 FAQ 中专门澄清，全绿结果不能证明语义正确。
技术栈与安全边界
| 方面 | 实现 |
|---|---|
| 核心语言 | Go（以 go.mod 为版本权威） |
| 分发方式 | 单个 CGO-free 可执行文件 |
| Agent 协议 | stdio MCP，恰好九个工具；CLI 与 MCP 共用同一治理内核 |
| 索引文件 | UTF-8 纯文本 Cognition Volumes，可 diff、可随 Git 版本化 |
| 机器状态 | JSON/JSONL、SHA-256、Baseline、manifest、receipt、ledger 与恢复机制 |
| 写入安全 | 跨进程锁、CAS、同目录临时文件、平台原子替换、失败即关闭（fail-closed） |
| 数据库 | 核心运行不依赖业务数据库；可选的 PostgreSQL / MySQL / openGauss schema 证据使用纯 Go 驱动 |
边界相当克制：只读地读取你的源码与数据库表结构，不读业务数据；写入仅限项目目录内的索引文件与自身状态，以及用户缓存目录里的状态页注册；不联网、不上传任何内容，唯一对外连接是你声明的数据库（仅取目录元数据）与它自己的回环状态页；数据库凭据以环境变量名引用，从不存储。它也不需要 Neo4j、不需要向量数据库、不需要常驻守护进程，更不需要什么 AOCI 云服务。
快速开始
官方推荐的做法是让 Agent 自己完成安装与接入。把下面这段指令交给你的 Agent：
AOCI-CODE project: https://github.com/aoci-spec/aoci-code
Download the latest release package for this operating system and CPU architecture from
https://github.com/aoci-spec/aoci-code/releases, and follow the installation instructions
on the Release page to verify it. If no compatible release package exists, or if I
explicitly request the latest source, build it from the official repository.
After extracting the package, place aoci (aoci.exe on Windows) at a stable absolute path.
Then use that absolute path to do the following for my project:
1. Run init to initialize AOCI and integrate MCP for the current host
2. Run scan
3. Tell me to restart the agent so the newly written MCP server takes effect
Stop after those three steps and do not build the index yet.
重启 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.
这里有个容易踩的坑：scan 的文件清单来自 Git，因此不要把 init 写出的认知资产（aoci.txt、aoci.meta.txt、aoci.code.txt、AGENTS.md）加入 .gitignore 或 .git/info/exclude——被忽略的资产会被静默跳过，索引就建不起来。必须重启的原因也很实际：索引是通过 AOCI 的 MCP 工具写入的，而执行 init 的那个会话还没加载刚写好的 MCP 服务。
从源码构建也很简单：
git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --version
常用命令与本地面板
| 命令 | 用途 |
|---|---|
aoci init |
安装仓库契约与初始 Volumes 布局（不含业务语义） |
aoci scan |
首次集成时建立 Baseline；已有 Baseline 下的范围变化进入 Scope Change |
aoci ui |
本地只读面板：原样展示索引、覆盖源码与压缩比、chunk 计划、漂移、运行中的服务与推荐输入 |
aoci verify |
报告 Missing / Orphan / Stale / Unbaselined 事实 |
aoci check |
运行聚合的治理门禁 |
aoci index agent guide |
进入确定性的宿主 Agent 工作流 |
aoci capabilities |
展示当前二进制提供的能力 |
aoci doctor |
诊断仓库与宿主集成 |
aoci database |
显式配置并校验 PostgreSQL / MySQL / openGauss 的 schema 证据 |
其中 aoci ui 面板值得单独一说：它只监听回环地址（其他绑定一律拒绝），只响应 GET 与 HEAD，不取锁、不写账本、不改动仓库任何一个字节；面板页面支持中英文切换，刷新间隔可选（默认 30 秒）。用 aoci ui –detach –json 可以在后台启动并直接拿到链接。
项目状态与许可
- 当前版本：v0.1.0-rc17（Release Candidate）
- 许可：FSL-1.1-MIT，属 Fair Source / source-available 软件
- 仓库数据：Go 语言，约 889 stars / 136 forks，2026 年 8 月初创建，主分支
main - 支持宿主：Codex、Claude Code、Cursor、OpenCode 等支持标准 stdio MCP 的宿主；README 特别说明——AOCI-CODE 集成的是 MCP 宿主而非模型厂商 API，模型名字本身并不等于兼容
获取与了解
- 项目主页：https://github.com/aoci-spec/aoci-code
- Release 下载（v0.1.0-rc17）：https://github.com/aoci-spec/aoci-code/releases/tag/v0.1.0-rc17
# 使用 GitHub CLI 下载已签名的 Release 资产
gh auth login
gh release download v0.1.0-rc17 --repo aoci-spec/aoci-code
更多资讯
想看更多优质内容？
浏览所有资讯