AOCI-CODE – 为 AI 编程代理提供的持久化、Git 版本控制代码库索引

它是什么

AOCI-CODE 是一个轻量级的 Go 语言命令行工具和本地 MCP (Model-Control-Protocol) 服务器，用于为软件项目建立纯文本索引。该索引记录了每个源文件的用途、依赖关系、提供的公开符号以及任何非显而易见的约束条件。索引与代码并存，通过 Git 进行版本控制，并随着代码变更自动保持更新。

为什么它对 AI 代理很重要

• 一次性理解 – 基于 LLM 的编程助手（例如 Claude Code, Cursor, OpenCode, Codex）可以通过加载 AOCI 索引，在单次传递中读取整个项目，而无需重复扫描存储库。
• 快速交接 – 当新的开发人员或新的代理接手代码库时，只需将代理指向现有的索引；代理即可立即了解每个文件的角色、契约和约束。
• 持续维护 – MCP 服务器会监控存储库；变更后会标记受影响的条目，代理会随之更新，确保索引与实际代码保持一致。
• 仅限本地，隐私优先 – 所有处理都在开发人员的机器上进行；不会将任何源代码或凭证发送到任何地方。

核心概念

概念	描述
FRAS 条目	每个文件一行：F (功能/用途), R (必要读取), A (可用符号), S (安全约束)。示例：atomic.go[CG9L]: F:Provides durable replace CAS …
根文件 (aoci.txt)	声明哪些索引文件属于当前的“认知集”(CognitionSet)。
元文件 (aoci.meta.txt)	存储标签字典、FRAS 规则和编写约束。
代码文件 (aoci.code.txt)	模型为源文件生成的 FRAS 条目。
数据库文件 (aoci.database.txt)	MySQL/PostgreSQL/openGauss 的可选表级条目。
MCP 服务器	在编程代理和索引之间进行协调的本地进程，处理 init, scan, maintain 等操作。

典型工作流程

1. 安装 二进制文件（下载签名版本或 make build）。
2. 初始化 存储库：aoci init --locale en-US --agent codex。这会写入配置文件、.gitignore 条目和空的索引骨架。
3. 扫描 存储库：aoci scan。代理读取每个受管理的文件，模型写入 FRAS 条目，并创建索引文件。
4. 启动 UI (可选)：aoci ui --detach --json – 提供一个网页面板，显示索引健康状况、覆盖率百分比和待处理更新。
5. 正常开发。当代码或测试变更时，MCP 服务器会标记受影响的条目；代理会自动更新它们。
6. 验证一致性：随时使用 aoci verify 或 aoci check。

支持的环境

• 操作系统 – Linux, macOS, Windows (单一二进制文件，无 CGO)。
• 代理 – 任何支持 MCP 协议的基于 LLM 的编程代理（Codex, Claude Code, Cursor, OpenCode 等）。
• 数据库 – MySQL, PostgreSQL, openGauss 6.0.5 (可选表级认知)。

它如何融入 AI 工具链

AOCI-CODE 位于 LLM 模型和代码库之间：

LLM model → (writes) → AOCI index (plain-text) → MCP server → Coding agent → Code / Tests

模型只需要生成简洁的 FRAS 条目；代理消耗索引来规划变更，减少上下文大小并消除重复的存储库扫描。

入门（快速入门片段）

# 1. 下载签名版本或从源码构建
# 2. 将二进制文件放置在稳定的绝对路径，例如 /usr/local/bin/aoci
# 3. 在项目根目录执行：

aoci init --locale en-US --agent codex

aoci scan

# 4. 要求代理启动 UI 并建立索引
首先确认 AOCI MCP 服务器已连接，然后为此项目建立 AOCI 索引。

UI 将返回一个链接，例如 http://127.0.0.1:8080/#/project，显示覆盖率、待处理更新以及 FRAS 条目的可搜索视图。

授权与状态

• 版本 – v0.1.0-rc17 (发布候选版)。
• 授权 – Fair Source License 1.1 + MIT (FSL-1.1-MIT)。
• 成熟度 – 早期阶段，但已用于高达 70 万行代码的商业代码库。