AOCI-CODE：给编码智能体的代码库认知索引
把整个代码库与数据库结构压缩成一份 Git 版本化的认知索引，让编码智能体开工前先读懂系统。
- Star 数
- ★ 1.4k
- 最近更新
- 今天
- License
- NOASSERTION
- 主语言
- Go
- FA 评分
- 52/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude CodeClaude.ai（部分支持）
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 接手一个没有文档的存量系统：把智能体指向最多约 50 万行的代码库，让它建索引并报告对各区域的掌握百分比，再继续开发。
- 不适合
- 代码规模远超约 50 万行、且不愿承担首次建索引时间成本的项目
- 只想一键托管、不希望自行准备二进制和 MCP 配置的用户
- 源码审查
- 52/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
AOCI-CODE（AI-Oriented Cognition Infrastructure）是一个用 Go 编写的本地优先工具，包含 aoci CLI 和基于 stdio 的 MCP 服务器，为 Claude Code、Codex、Cursor、OpenCode、Qoder 等宿主提供持久化的项目认知。它让模型为每个受管文件或数据表写一行 FRAS 条目（F 职责、R 强关联、A 对外契约、S 不可推断的约束），并按标签字典给对象打上层次、领域、重要度与规模坐标。这些条目以纯文本形式存放在仓库根目录的 aoci.txt、aoci.meta.txt、aoci.code.txt、aoci.database.txt 中，随代码一起被 Git 版本化、可 diff、可回滚。MCP 服务器只暴露九个工具，负责读取索引、维护条目并生成确定性计划，用 CAS 与原子写入保证提交要么完整落地、要么可证明地恢复。整个运行过程不联网、不上传代码，数据库访问仅在显式命令下读取系统目录，且只保存凭据的环境变量引用名。
aoci init 写入 Root/Meta 骨架、受管的 AGENTS.md 规则块、Git 边界以及宿主 MCP 配置；aoci scan 以 Git 文件清单建立受管基线；随后由宿主模型通过 MCP 工具逐对象写出 FRAS 条目。运行中的 aoci mcp 提供九个工具：读取类的 aoci_rules、aoci_overview、aoci_get_entries、aoci_search，维护类的 aoci_maintain、aoci_update_entry、aoci_remove_entry，以及证据类的 aoci_header、aoci_report。当索引超过分块预算时，aoci_overview 按 next_cursor 分块投递整份 Whole-Index，并要求模型提交 attestation。aoci verify 报告 Missing/Orphan/Stale/Unbaselined，aoci check 执行治理门禁，aoci index agent guide 给出确定性的宿主工作流。数据库侧通过 aoci database source add 声明来源、aoci database source access 做只读预检、aoci database cognition bootstrap 开启数据库认知，只读 PostgreSQL/MySQL/openGauss 的系统目录元数据。aoci cognition system lineage/relations/impact/snapshot/evolution 在既有权威资产之上给出派生的系统认知视图，结果标记 derived=true 且不落新的事实。aoci ui --detach --json 启动仅绑定回环地址的只读面板，展示索引原文、覆盖行数、压缩比与漂移状态。
- 接手一个没有文档的存量系统：把智能体指向最多约 50 万行的代码库，让它建索引并报告对各区域的掌握百分比，再继续开发。
- 在 Codex / Claude Code / Cursor / OpenCode 中跨会话开发：索引随仓库走，换人、换智能体或新开对话时一次读取即可接上进度。
- 非专业开发者长期迭代自己的项目：让智能体先建立整体认知，避免每次任务都重新检索和重读代码库。
- 同时管理代码与数据库：先建代码索引，再用
aoci database cognition bootstrap建立表级索引，让模型同时理解业务代码与表结构约束。 - 评估数据库变更影响面：用
aoci cognition system impact --object database://primary/public/orders沿模型写下的正式 R 关系找出可能受影响的代码对象。 - 团队需要审计与回滚：索引是纯文本且被 Git 版本化，可 review、diff、回滚，并可通过面板查看索引覆盖与治理状态。
如何安装或部署这个 Agent？
官方推荐使用签名发布包。先用 GitHub CLI 下载 v0.1.0-rc19 的发布资源，并按其安装文档中的验证等级核对签名：
gh auth login
gh release download v0.1.0-rc19 --repo aoci-spec/aoci-code也可以从规范仓库构建源码（需要 Go 工具链与 make）：
git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --versionWindows PowerShell 下的等价构建：
git clone https://github.com/aoci-spec/aoci-code.git
Set-Location .\aoci-code
New-Item -ItemType Directory -Force .\build | Out-Null
make build
.\build\aoci.exe --version不论哪种方式，都要把二进制放在稳定的绝对路径上，MCP 配置会引用该路径。注意：该许可证标注为 FSL-1.1-MIT，仓库声明为 source-available（Fair Source）。
如何使用这个 Agent？
在目标仓库根目录初始化并建立基线：
AOCI=/absolute/path/to/aoci-code/build/aoci
"$AOCI" --repo . init --locale en-US --agent codex
"$AOCI" --repo . scaninit 会写入宿主 MCP 配置（.mcp.json、.claude/settings.json、.codex/config.toml 或 opencode.json），其中的路径是机器绑定的绝对路径，应加入 .gitignore。不要把 aoci.txt、aoci.meta.txt、aoci.code.txt、AGENTS.md 加进 .gitignore，否则资产会被静默跳过。
然后重启或刷新宿主会话，让新写入的 MCP 服务器生效，再要求智能体建立索引：
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.索引完成后校验对齐状态并查看面板：
"$AOCI" --repo . verify
"$AOCI" --repo . check
"$AOCI" --repo . ui --detach --json如项目含数据库，先声明来源（凭据只以环境变量名引用，例如 primary 对应 AOCI_DB_PRIMARY_DSN），再做只读预检：
aoci --repo . database source add \
--source-id primary \
--engine postgresql \
--database-name app \
--namespace public
aoci --repo . database source access --source primary --json这个 Agent 有哪些优点和局限？
- 索引以纯文本存放在仓库内并由 Git 版本化，可 diff、review、回滚，换人或换智能体后可复用，不绑定具体模型或会话。
- 本地优先：不联网、不上传代码，只在使用显式数据库命令时读取系统目录元数据，凭据只保存环境变量引用名。
- 写入路径有治理：确定性的计划与源文件 SHA-256、跨进程锁、CAS 与原子写入，失败时要么可证明恢复、要么回滚到原像。
- 索引按 30 秒默认刷新的只读面板展示原文、覆盖行数、压缩比、分块计划与漂移状态，便于人工审计。
- 开箱支持多宿主：Codex、Claude Code、OpenCode 写项目级配置，Cursor 提供参考配置片段，Qoder 写入 .mcp.json。
- 首次建立索引耗时明显，官方给出约每 20 万行代码一小时的经验值，且没有批量跳过机制。
- 索引质量取决于宿主模型的写作质量；机器校验只能证明结构与治理契约成立，不能证明模型写的每条语义都正确。
- 许可证标注 NOASSERTION、README 表述为 FSL-1.1-MIT（Fair Source / source-available），并非标准 OSI 开源许可，商用前需自行核对条款。
- 软件本身免费但必须自备支持 stdio MCP 的宿主与模型，模型调用费用由用户承担；未提供托管服务。
- 数据库认知当前只支持 PostgreSQL、MySQL 与受限的 openGauss 6.0.5 LTS，且数据库认知下查询等部分默认不启用。
- 仍处于 v0.1.0-rc19 发布候选阶段，接口与 CLI 状态可能在稳定版前变化。
这个 Agent 与同类方案有什么区别？
README 明确对比了 CodeGraph：CodeGraph 把代码解析成符号与调用图，回答具体问题时返回精确源码与调用路径，是针对当前任务的精确查找工具；AOCI-CODE 则让模型为每个文件写一行 FRAS 摘要，智能体先通读整份索引以建立系统级认知，再开始任务。README 建议两者并用：用索引了解系统，用 CodeGraph 取精确代码。此外 README 还说明其与 RAG、LSP 和 repo map 的差异，但未在可见部分展开这些替代方案的具体名称。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| AOCI-CODE：给编码智能体的代码库认知索引 当前 | 52 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.4k | 今天 | Go | Codex · Claude Code |
| Headroom：AI 代理的上下文压缩层 | 59 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 75k | 今天 | Python | Codex · Claude Code · OpenAI API · Claude API |
| Piia Engram | 88 · 表现良好 | 命令行工具免费 | ★ 163 | 1 天前 | Python | Codex · Claude Code |
| Remnic 智能体记忆 | 85 · 表现良好 | 命令行工具免费 + 模型费 | ★ 218 | 2 天前 | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
README 与 SECURITY.md 明确声明本地优先、只读源码与数据库目录元数据、不联网、凭据仅以环境变量名引用、MCP stdout 仅用于 JSON-RPC、正式资产更新使用校验/锁/CAS/原子写与恢复，least_privilege、data_flow_transparency、sensitive_data_handling、external_effects、rollback 均有可指认的文本支撑，故给 2。但 user_confirmation 仅以 automation.mode=auto 的模糊描述带过，未给出默认模式或具体确认点，扣至 1；source_attribution 只有 FSL-1.1-MIT 与 Copyright 2026 Liu JinShi，发布者身份未经验证、无签名/来源链说明，扣至 1。
CI 工作流覆盖 go mod verify、go mod tidy 后 diff 校验、单元测试、staticcheck、govulncheck、跨平台编译与黑盒协议套件，self_consistency 与 dependency_availability 有实质证据，给 2。failure_messages 仅在 README 提到 verify/check 收敛到 aligned，未展示具体错误文案或诊断输出，扣至 1。
README 明确支持 Codex、Claude Code、Cursor、OpenCode 等 MCP 宿主，并说明 DeepSeek 等模型需宿主支持 stdio MCP，audience_and_scenarios 与 capability_boundaries 清晰，给 2；environment_fit 覆盖 Linux/macOS/Windows 与 CGO-free 构建，给 2。trigger_precision 依赖 agent 自行判断何时维护索引，缺少确定性触发条件，扣至 1。
information_architecture 与 install_notes 结构完整，含快速开始、手动集成、验证步骤与 Windows PowerShell 示例，给 2；license 为完整 FSL-1.1-MIT 文本，给 2。naming_stability 因 rc19 版本号与 README 中多处硬编码路径/版本，扣至 1；examples_and_faq 仅有 examples/minimal-repository 一句提及，扣至 1；known_limitations 只提到首次索引耗时与规模上限，未系统列出限制，扣至 1；versioning_changelog 无 CHANGELOG 文件，扣至 1；maintenance_responsibility 未明确维护者与响应时限，扣至 1。
output_usability 有具体 FRAS 条目示例与字段解释，给 2；marginal_value 与 CodeGraph/RAG/LSP 的对比属自述，缺少独立佐证，扣至 1；cost_benefit 承认首次索引约每 20 万行一小时，但未给出与替代方案的量化收益，扣至 1。
claim_traceability 的多数性能与规模声明（70 万行、30 万 token 索引）无仓库内可核验数据，扣至 1；cross_source_corroboration 仅 README 与 CI 部分互证，扣至 1；fact_inference_separation 未明确区分事实与推断，扣至 1。
- 发布者身份未经验证，README 中的性能与规模声明（70 万行、30 万 token 索引）缺少仓库内可核验数据，不应据此推断可靠性。
- 首次索引成本较高（约每 20 万行一小时），且依赖 agent 自行判断维护时机，缺少确定性触发条件。
- 许可证为 FSL-1.1-MIT（Fair Source），存在竞争性使用限制，商用前需确认合规。
- 本评估为静态源码审查，未执行任何构建、测试或运行验证，置信度低。