跳到正文
heyaican
中文EN

AOCI-CODE

一个 Go 写的 CLI 加一个本地 MCP 服务器，为一个仓库维护同一份纯文本地图：每个受管文件一行，写明它负责什么、要和什么一起读、对外提供什么、什么不能弄坏——于是编码 agent 只读一次这个系统，而不必在每个任务里重读代码。

源码 提交更正
Screenshot of AOCI-CODE
编辑截图， 30 Sep 2026AOCI-CODE ↗

这是什么

AOCI-CODE 为一个仓库维护一张持久、随 Git 版本化的地图，编码 agent 在动手之前先读它。它是一个不含 CGO 的 Go 单体程序，既是 CLI，也是一个只暴露九个工具的 stdio MCP 服务器；它所治理的是一份纯文本：Root 声明哪些 Volume 参与，Meta 装着标签字典与写作规则，Code Volume 里每个受管文件一行 FRAS，另有可选的 Database Volume 建立在被接收的 schema 证据之上。每一行记录对象负责什么（F）、必须与它一起读什么（R）、调用方可以依赖什么（A），以及无法从代码推断出来的约束（S）。含义归模型，治理归二进制——范围、Baseline、源码摘要、结构校验、跨进程锁与 CAS 写入、Ledger、恢复，以及证明整份索引确实被完整投递的 attestation。README 给出的许可是 FSL-1.1-MIT——属于 fair source／源码可见，不是 OSI 认证的开源许可。

谁做的仓库属于 aoci-spec 这个组织账号，而不是某个人的账号，里面的提交也分得不均：193 次提交里有 163 次署名 alkor2000，其中 155 次关联到该 GitHub 账号。dayebishouji 占 25 次，funfitx 3 次，DaisyHunter 1 次；193 次提交里有 161 次带共同作者尾注，其中 153 条写的是一个 Claude 模型。周围还有 689 个星、118 个 fork、13 个未关闭的 issue。

它是怎么搭起来的

组成 · 6

一层本地优先的治理内核，包着一个文本文件。索引是仓库里的纯文本，每个受管对象一行，于是 Git 可以 diff、评审、回滚它；二进制从不发明含义，模型也从不写治理事实。这条分工贯穿整个布局——Root 与 Meta 负责声明与约束，Volume 装着条目，而一个仓库只能把机器允许的收紧、不能放宽，因为字段上限是编进二进制里的，不是从项目里读回来的。又因为这件产物是一个模型要花几小时分批编辑的文件，几乎所有工程都花在证明它身上发生了什么：确定性的 plan 与源码摘要、对照标签字典与受管范围做的候选校验、跨进程锁加 CAS 发布、Ledger 与收据、每个对象的 Baseline 指纹，以及一条 fail-closed 的恢复路径——要么从一个可证明的后像续上，要么退回精确的前像，而不是覆盖第三方。之所以存在两套物理布局，是因为更早的单体头文件已经在线上了：新项目走 Volumes v1，Legacy 布局保持可读，其专属命令排进了移除计划。

internal/
那个 Go 程序，按它自己的治理词汇切分：internal/cli 有 225 个文件 1.5 MB，internal/mcptools 有 107 个文件 1.2 MB，其余的分别管数据库证据、索引与 Baseline、范围变更、迁移、上手流程、宿主钩子、Ledger、状态页、安全检查，以及必须与契约文本对得上的机器词表。
spec/public/
二十份纯文本契约、179 KB，随公开树一起发布：认知卷、overview 投递、认知刷新与认知状态、索引格式、对象 FRAS、两种语言的 S 字段纪律、受管范围与预算、安全盘点、数据库证据与数据库表 FRAS、宿主能力与消息，以及 MCP、CLI、配置和系统认知的运行契约。
scripts/blackbox/
516 个文件、3.8 MB 的套件与夹具：一致性、场景、生命周期和升级四套测试线，加三个冻结仓库，其中一个是 453 文件的分层服务。夹具里还有专为被跳过而存在的文件——1.1 MB 的文本转储、69 字节的图片、零字节的空文件。
textassets/
二进制要吐出来的那些字符串，按数据而不是按代码存放：en-US 138 个文件、zh-CN 138 个文件，298 KB 与 264 KB，背后是一个 11.9 KB 的目录和一份 9.7 KB 的完整性测试，覆盖 guide 指令、帮助文本、模板，以及写进宿主仓库的受管区块。
docs/ 与 AGENTS.md
二十个文档、219 KB，领头的是 24 KB 的 Windows 宿主指南、22.9 KB 的认知卷文档、22.5 KB 的排障文件与 21.5 KB 的范围与预算文档，另有 4.5 KB 的契约权威说明及其 3.5 KB 原文。AGENTS.md 18.4 KB，既装着仓库规则，也装着 AOCI 写进去的受管认知区块。
发布工装
四个工作流——发布 29.6 KB、全信心 17.9 KB、持续集成 9 KB、发布彩排 3.8 KB——由 15.5 KB 的 Makefile 和 1.7 KB 的 GoReleaser 配置驱动，另有八个发布脚本（含一个 manifest 签名器与一个 clean-room 冒烟测试），以及一份 104 KB 的 changelog，配上为 1.2 KB 的 go.mod 准备的 88.8 KB 第三方声明文件。

取舍，以及它替代了什么

  • 把索引拆成 Volume，而不是一个大头文件 替代 让单文件的 Legacy 布局继续做新仓库的正路

    Root、Meta、Code 和 Database 各自拥有文件、证据来源与生命周期，而 Root 最后发布，于是一份残缺的资产集不会被误认成完整集合。Legacy 布局仍然可读、命令仍然可用，但 README 已把它标为 deprecated，并把 Legacy 专属命令排进移除计划，因为旧格式装不下按 Volume 分的证据与归属。

  • 把字段上限编进二进制，而不是交给项目 替代 允许仓库从自己的 Meta 文本里放宽 FRAS 限制

    Meta Volume 带着 #FRAS-v2-Limits-Authority: machine-contract，README 称这一行是承重墙：上限属于二进制，项目改自己的文本也放宽不了。同一种直觉也钉住了二进制名、九工具 MCP 面与 stdout 保留，AGENTS.md 要求任何改动都得保住它们。

  • 含义归模型，治理归二进制 替代 让程序用路径、扩展名、AST 或模板拼出条目

    README 把它写成一份分工：程序不用文件名或结构拼装条目，也不悄悄改写模型写下的东西；而范围、plan、源码摘要、校验、原子发布、Ledger 与恢复归它。README 和 FAQ 都写明，全绿的机器结果只证明被编码的结构与治理条件成立，不证明模型写下的那些陈述是对的。

  • 在进程之外、只用公开协议测那个真正发布的二进制 替代 只测进程内的各个包

    四套套件只说 stdio MCP 与 CLI，除了一个已构建的二进制外只需要 Python 3 和 git，并允许用环境变量指向另一个二进制，于是 fork 或平台移植也能拿同一批契约来验。升级轴之所以存在，是因为另外三套用被测二进制现造夹具，因此看不见版本之间变化过的前像。

  • MCP 面就停在九个工具 替代 每加一项能力就多开一个工具

    系统认知——lineage、relations、impact、snapshot、evolution——是以 CLI 命令的形式落在既有治理内核上的，README 明确说它没有加第十个工具，也没有改动原有九个的名字或 stdio 契约。AGENTS.md 把九工具面列进必须保住的清单，而 stdout 的保留正是日志要走 stderr 的原因。

依据AGENTS.md（18,391 字节）、README.md（75,265 字节）与 README.zh-CN.md（67,381 字节）、spec/public/ 下二十个文件及其体积、docs/ 下二十个文档、四个工作流与 15,453 字节的 Makefile、scripts/blackbox/README.md、go.mod，以及完整的 1,812 个文件树及其字节体积。

制作过程

6 个阶段
  1. 01

    十七个候选版本，版本号始终停在 0.1.0

    仓库建于 2026-08-08，当天第一次提交的标题就是「chore: initial public release candidate」——事后看，这一句说完了整个项目。52 天里它提交了 193 次，其中 8 月 109 次、9 月 84 次，并发了 17 个 release，每一个都标着 prerelease：从 2026-08-08 的 v0.1.0-rc1 到 2026-09-29 的 v0.1.0-rc17。没有任何一个被提升出候选版本这条线。比版本号更有意思的是署名：193 次提交里 161 次带共同作者尾注，其中 153 条写着一个 Claude 模型——Fable 5.1 出现七十一次，Opus 5 六十七次，Fable 5 十三次，Opus 5.5 两次。仓库归 aoci-spec 这个组织账号，155 次提交关联到 alkor2000，25 次到 dayebishouji，3 次到 funfitx，1 次到 DaisyHunter；周围是 689 个星和 118 个 fork。

  2. 02

    契约就是文件，pull request 模板照着它逐条打勾

    AGENTS.md 里的仓库规则只有一行：「Public runtime contracts live under spec/public/.」那个目录装着 20 份纯文本文档、179 KB，领头的是 32 KB 的 cognition-volumes 契约、17.9 KB 的 overview-delivery 契约、15.5 KB 的数据库写作契约和 13.3 KB 的刷新契约。让它们成为契约而不是文档的，是两头都可检验：AGENTS.md 同时钉死了二进制名、九工具 MCP 面和「stdout 只留给 JSON-RPC」，而每个 pull request 正文开头都有一张「Affected public contracts」清单，格子正是那几条轴——MCP 名称与响应结构，CLI 命令、旗标与退出码，spec/public/ 文本，internal/machinecontract 里的机器词表，以及索引、Baseline、收据与事务身份。Meta Volume 更进一步，声明了 #FRAS-v2-Limits-Authority: machine-contract；README 称这一行是承重墙，因为「the field limits belong to the binary, not to this text, so a project cannot widen them by editing its own Meta」。

  3. 03

    四套黑盒套件，和一张说明「绿色什么时候不算数」的门禁表

    AGENTS.md 写着 make fast 是 Tier-0 门禁，且「never sufficient evidence on its own」；另有五道闸只在 make full 下跑——clean-room smoke、licenses、race、vuln、database integration——并记着一件旧事：改一次机器默认值曾让 clean-room smoke 单独挂掉，而所有 fast 门禁全绿。单元测试之上是 scripts/blackbox/ 下的四套黑盒套件，它们严格在进程之外驱动一个已构建的二进制：46 项 MCP 线协议的只读一致性检查；64 个故障注入场景，覆盖游标篡改、崩溃恢复与并发写入者；一套跑在三个冻结夹具仓上的生命周期检查（一个 TypeScript 应用、一个带 MySQL 的 Python 服务、一个 453 文件的分层服务）；以及每发布版本 48 项、跨六种仓库形态的升级轴。README 也直说这套东西看不见什么：另外三套用自己的二进制现造夹具，所以「a preimage that changed between versions is invisible to them by construction」。

  4. 04

    什么时候发：一段 soak 窗口，和一串被刻意往后放的东西

    2026-09-21，维护者在一条评审里写道，main 正处于「in the soak window for 0.1.0」，计划是「as long as no product code lands before then」就把当前候选原封不动地提升；只因为这个理由，一个动了数据库采集器的 pull request 被按着不发。对改段头约定的那条改动，回答也是一样：要，但「just not into a 0.1.0 candidate」——因为仍停在旧候选版本上的人读一份中性索引时只拿得到旧的保证，于是它被划到 0.2.0，日后以贡献者本人的署名落地，rebase 由维护者自己做。这份谨慎最清楚的例子是一次依赖升级：MCP SDK 从 1.6.1 到 1.8.0 完全不被当成版本号变动——新的一行会把另一个模块链进二进制，于是许可证清单、THIRD-PARTY-NOTICES 和供应链文档都要改；tools/list 会多出两个字段，而那是被 golden 钉住的响应；它还会默认启用一个没有任何一套黑盒套件会说的无状态协议修订，等于让它未经检验就上线。

  5. 05

    一份错了三次的 bug 报告，和终结它的那些字节

    issue 89 是这个仓库里留档最完整的一次故障。有用户报告 aoci_maintain 的响应偶尔会给出 63 位或 66 位的十六进制摘要而不是 64 位，于是从响应里逐字复制的提交会被拒绝。报告人随后在公开评论里两次修正归因——先归给进程内陈旧的候选缓存，再归给写进磁盘收据的坏值——两次都是读完源码后自己发勘误，第二次的结论是磁盘层根本不可能收下非法长度的值。维护者把服务端翻了一遍，没找到任何能在十六进制串里塞进一个字符的地方，指出这些值是内存里的收据结构体直接经标准编码器出去的、中间没有任何手工拼接，并要求给原始字节而不是再给一个理论。答案来自宿主自己的会话数据库：141 次 AOCI 工具调用里，aoci_maintain 响应中的 1,824 个摘要值全部正好 64 位，而模型自己提交的 aoci_update_entry 请求里，1,530 个值中有 23 个长度不对。损坏发生在抄写环节而不是服务端，作为独立缺陷的姊妹 issue 以 not planned 关闭。

  6. 06

    成本写在最前面，以及一仓库互相校核的文件

    README 在讲怎么开始之前，先讲第一次建索引要多久：大约每 20 万行代码一小时，因为模型要把每个受管文件读一遍、给每个写一条。有人开 issue 问为什么这么慢，回答把两笔成本分开——Baseline 记着每个文件的指纹、日常维护只把改过的发回去，但第一遍躲不掉——并说明当前候选版本已经把每批响应砍了一半、开始按字节预算切批，首建轮数少了两三成。同一种直觉也决定什么值得进索引：一个测试只有在它是「an executable contract someone must run by name」时才配拿到一条 Entry，因为在约 110 token 一条的代价下，把普通的包测试也编进去「would more than double the Whole-Index and buy nothing」。这个仓库对自己也是这么做的：它的 Code Volume 是 195 KB，配着 305 字节的 Root 和 910 字节的 Meta，旁边是 447 KB 的 Baseline；1,812 个文件里还有四个发布工作流、一份 104 KB 的 changelog、两棵各 138 个文件的平行本地化文本资产树，以及一个自带 39.5 KB 补丁的 openGauss 连接器。

相关档案

全部档案 →

第 091 号

OKF Agent Memory

把编码 agent 学到的东西以纯 Markdown 留在仓库里——一个用进程内 BM25 检索的 OKF v0.2 知识 bundle——于是这份记忆可以被 diff、被审阅，而不必住进数据库。

第 090 号

Reverify

一个校验 AI 关于二进制文件所下断言的东西：模型提出 claim，一套确定性工具拿真实字节去查，返回的是带证据的 VERIFIED、REFUTED 或 INCONCLUSIVE——能熬过一次上下文重置的，是这些判决，而不是模型的文字。

第 081 号

pgbot

一个静态 Go 二进制，只读地连上 PostgreSQL，读服务器自己的统计视图，打出一份以 finding 为先的体检报告——因为每次运行都会在本地存一份基线，它还能说出「与上次相比变了什么」；同一批确定性 finding 通过 MCP 交给 AI agent，而可选的 AI 层只被允许解释它们。