AOCI-CODE

AOCI-CODE

一份持久化、由 Git 版本管理的整个代码库地图——由你的编码智能体编写，由本地 MCP 服务器治理。 智能体读一次就能了解整个系统，而不必在每个任务中重新阅读仓库。

🇺🇸 English | 🇨🇳 简体中文

它做什么

构建大型系统而不迷失方向。 在 Codex、Claude Code、Cursor、OpenCode 及类似智能体中，你的智能体在开始每个任务时就已经了解整个系统：每个文件的用途、它依赖什么、以及什么不能破坏。它不再为每个请求搜索并重新阅读代码库。非专业开发者可以持续迭代自己的系统；专业开发者可以把整个系统交给智能体，同时把注意力集中在架构和设计上。

一步接管现有系统。 让智能体指向一个最多约 50 万行的现有代码库，并要求它构建索引。它会报告自己对每个领域的了解程度，然后从那里继续开发。实际限制是索引的大小，而不是行数：一个 70 万行的商业系统目前就是这样开发的，其索引约为 30 万 token。

更换人员、智能体或对话时无需从头开始。 索引与代码一起存放在仓库中，并由 Git 进行版本管理。当项目易手、切换智能体或开启新对话时，只需读一次索引就能接着上次的进度继续。

首次建立索引后，维护是自动的。 MCP 服务器检测代码变更，并下发需要更新的条目。智能体在完成每个任务时填写这些条目，因此索引与当前代码保持一致，你无需停下来维护它。

它长什么样

每个文件一行，由模型根据实际源码编写。这是本仓库自身索引中的一个真实条目：

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

F 是该文件负责的内容，R 是必须与它一起阅读的内容，A 是调用方所依赖的内容，S 是无法从代码推断但绝不能弄错的内容。标签 [CG9L] 按层、领域、重要性和规模为文件定位。几百行这样的条目就能覆盖整个系统，智能体可以一次读完。条目格式解释了每个字段。

这与 CodeGraph 有何不同？

• CodeGraph 将你的代码解析为符号和调用的图。当智能体提问时，它返回确切的源码和调用路径。它是针对当前任务的精确查找工具。
• AOCI-CODE 让模型为每个文件和表写一行：它的用途、它连接什么、以及什么不能破坏。智能体先读整个索引，因此在任务开始前就了解系统。索引存放在 Git 中，并与代码保持同步。
• 两者结合使用：用索引了解系统，用 CodeGraph 在工作时获取确切的代码。

完整对比还涵盖了 RAG、LSP 和仓库地图。

预期情况

首次建立索引需要一些时间。 智能体会读取每个受管文件，并为每个文件写一个条目：每 20 万行代码约需一小时，具体取决于模型和智能体的速度。它分批运行，如果中断会从停止处继续。

有数据库？也把它索引起来。 支持 MySQL 和 PostgreSQL，以及带约束的 openGauss 6.0.5。MySQL 指 5.7.6 及更高版本；不支持 MariaDB。先构建代码索引，再构建数据库索引。代码和表级知识一起提供时，智能体能更完整地理解系统。

仅本地：对你的系统只读，无互联网，不存储凭据。 AOCI-CODE 读取你的源代码和数据库表结构，绝不读取业务数据。它把索引文件及其自身状态写入项目目录内，另外在用户缓存目录中注册状态页。它从不访问互联网，也不上传任何内容：它唯一打开的连接是连接你声明的数据库（用于目录元数据）以及它自己的回环状态页。数据库凭据通过环境变量名引用，从不存储。索引文本由你自己的智能体通过你已在使用的模型通道在本地写入；AOCI-CODE 不增加任何新的数据出口。

快速开始

把以下指令交给你的智能体，以下载 AOCI-CODE 并完成接入。重启智能体后，发送第二条指令来构建索引。

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; if this host does
   not write project configuration (Cursor, for example), give me the configuration I
   need to paste myself
2. Run scan

   scan takes its file inventory from Git, so do not add the cognition assets
   init writes (aoci.txt, aoci.meta.txt, aoci.code.txt, AGENTS.md) to .gitignore
   or .git/info/exclude — an ignored asset is silently skipped and the index
   cannot be built. Leave the host-config ignore init writes for itself as it is.

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 — I will tell you to continue
after the restart.

重启智能体后，发送这一条：

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 ui --detach --json 在后台启动面板，并把链接交给你。AOCI 面板介绍了它显示的内容及其其他命令。

为什么要重启：索引是通过 AOCI 的 MCP 工具写入的，而运行 init 的会话尚未加载 init 刚写入的 MCP 服务器。动态加载 MCP 服务器的主机可能不需要重启；主机集成说明了如何判断。

如果你的项目有数据库（支持 PostgreSQL 和 MySQL，以及带约束的 openGauss 6.0.5），也把它索引起来。按数据库认知所述声明数据源，在主机环境中提供连接字符串环境变量（AOCI 不存储凭据），然后发送：

Build the AOCI database index for this project.

如果上下文已被压缩，或者你希望智能体重建对系统的认识，发送这一条：

Using only AOCI, establish whole-framework cognition of this project, tell me your mastery of each area as a percentage, and whether you can take over development.

工作原理

AOCI（AI-Oriented Cognition Infrastructure，面向 AI 的认知基础设施） 是方法与协议：位于编码智能体与软件系统之间的一层。模型负责推理，智能体负责规划与执行，AOCI 则维护一份关于系统的最新描述，涵盖代码、配置、测试和数据库结构，供智能体在行动前阅读。AOCI-CODE 就是本项目：aoci CLI、MCP 服务器，以及它们维护的索引。

AOCI-CODE 将理解和修改系统真正重要的内容提炼为一份密集的纯文本索引，结合了符号与含义。当模型上下文有限时，智能体先读索引，一次就能获得项目的大部分关键信息，然后开始任务。这减少了重复搜索和重新学习，并让理解在任务和会话之间延续。

• 不是一次性摘要。 索引随系统演进，并留在项目中，你可以用 Git 对它进行 diff、审查、版本管理和回滚。
• 不止于“文件在哪里”。 它记录职责、强关系、公共契约、事务边界、兼容性约束，以及其他难以从代码结构推断的内容。
• 可移植。 索引与项目一起存储，不绑定于某个模型、智能体或会话。只要它与代码保持一致，任何智能体和任何后续会话都可以复用它，而无需从头重建理解。
• 代码与数据库结合。 模型可以为数据库表构建单独的表级索引。两者一起提供时，能让智能体对系统有更完整的认识。

索引是一组与项目一起存储的受治理纯文本文件：

• Root（aoci.txt） 声明当前索引由什么构成，是它的激活入口。
• Meta（aoci.meta.txt） 保存标签字典、FRAS 规则和编写约束。
• Code（aoci.code.txt） 保存模型为代码和其他仓库资产编写的条目。
• Database（aoci.database.txt） 在启用数据库认知时保存可选的表级条目。

Root、Meta 以及参与的对象 Volume 共同构成 Whole-Index。其上的工作流分为三个阶段：

1. 在治理下构建索引。 模型阅读源代码和已接受的证据。AOCI-CODE 通过 index 角色治理受管范围以及模型为每个受管对象编写的条目。
2. 行动前先阅读。 智能体阅读项目规则、实时指南和当前 Whole-Index，然后针对手头任务检查源码和其他证据。
3. 在验证变更后维护。 一旦代码和测试稳定，项目规则和 MCP 工作流会让智能体更新受影响的条目，使索引回到 aligned。

由于这些文件是仓库中的纯文本，Git 会对它们进行版本管理。只要索引与当前系统版本保持一致，任何智能体和任何后续会话都可以读取并复用同一份 Whole-Index。

手动集成

从规范源获取 AOCI-CODE，或使用 GitHub Releases 中的签名包。在使用预构建二进制文件之前，请遵循安装指南中的基本、推荐或完整验证级别，并报告完成了哪个级别。将本 README 和已验证二进制文件的稳定绝对路径交给你信任的编码智能体，例如 Codex、Claude Code、Cursor 或 OpenCode。智能体可以按照项目内说明初始化 AOCI、集成 MCP 并构建首个索引。

首次建立索引所需时间取决于仓库大小。正常的集成分为四步：准备二进制文件，让智能体或你自己初始化目标仓库，要求主机“构建索引”，并验证一致性。之后你无需在每个请求末尾加上“维护索引”。每当受管对象发生变化时，项目规则和 MCP 工作流会让智能体增量维护索引。

要求

• 一个已验证的发布包，或规范 AOCI-CODE 源码仓库的检出副本。
• 仅源码构建需要：go.mod、make 声明的 Go 工具链，以及仓库所需的其他工具。
• 一个受支持的 MCP 主机，例如 Codex、Claude Code、Cursor 或 OpenCode。
• 对目标仓库的正常读写权限。

AOCI-CODE 与 MCP 主机集成，而不是与模型提供商的 API 集成。当运行 DeepSeek 及其他模型的智能体或主机支持标准 stdio MCP 并能遵循工具契约时，这些模型 也可以使用 AOCI-CODE；仅凭模型名称并不能确立兼容性。

签名包途径和可执行文件验证命令见安装指南。源码构建途径如下。

当前 RC：使用已验证的包或从源码构建

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 是当前的发布候选版本。它是 FSL-1.1-MIT 下的 Fair Source/源码可用软件；参见 LICENSE。请从规范源码构建，或在遵循发布验证流程后使用 v0.1.0-rc22 GitHub Release 中的签名包。

签名的 Release 二进制文件自报为 aoci version 0.1.0-rc22。源码构建则标识确切的检出副本，并可能报告诸如 v0.1.0-rc22-1-g<short-commit>（适用时加上 -dirty）之类的开发版本，以及其 Git 提交。这些是不同的构建输入，而不是版本冲突。

要使用 GitHub CLI 下载，请先进行身份验证，然后下载带标签的 Release 资产：

gh auth login
gh release download v0.1.0-rc22 --repo aoci-spec/aoci-code

如需匿名下载，请在浏览器中打开 v0.1.0-rc22 Release 页面 并下载你需要的归档文件和验证资产。

要从源码构建，请克隆规范仓库、构建二进制文件，并保持生成的路径稳定：

git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --version

在 Windows 上，请在 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

然后，将本 README 交给你已经信任其处理该项目的智能体，并请求：

Read this AOCI-CODE README and use the built aoci binary at its stable absolute path
to initialize AOCI for the current project, integrate MCP, and run scan. Stop there and
tell me to restart the agent; I will ask you to build the index afterwards.

智能体应识别项目根目录，使用指向已构建二进制的稳定绝对路径，运行适合当前宿主的初始化流程，并在需要重启宿主或需要真实人工批准时明确告知你。二进制可以留在 AOCI-CODE 检出目录中，也可以移动到共享工具目录，只要 MCP 配置指向正确的绝对路径即可。

手动初始化

要自行初始化 AOCI，请在目标仓库根目录下运行以下命令，或通过 --repo 传入显式路径：

AOCI=/absolute/path/to/aoci-code/build/aoci
"$AOCI" --repo . init --locale en-US --agent codex
"$AOCI" --repo . scan

init 会写入区域设置配置、受管理的 AGENTS.md 规则块、Git 边界以及一个空的索引骨架。配置和提示方式因宿主而异；参见宿主集成。它不会根据文件名、目录或 AST 臆造业务含义。

对于新仓库，第一次 scan 会建立受管理的 Baseline。对于已有受治理 Baseline 的项目，添加、移除或更改受管理范围必须走正式的 Scope Change 工作流；scan --force 不是重新定义治理事实的捷径。--force 也无法抹除未解决的漂移、回执或恢复边界。

$Aoci = (Resolve-Path "C:\path\to\aoci-code\build\aoci.exe").Path
& $Aoci --repo . init --locale en-US --agent codex
& $Aoci --repo . scan

让智能体构建第一个索引（重要）

初始化与 scan 完成后，检查智能体会话是否已暴露 AOCI 工具；如果没有，请刷新或重启会话。然后在智能体中针对目标项目输入以下内容：

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 ui --detach --json 在后台启动面板，并把链接交给你。AOCI 面板介绍了它显示的内容及其其他命令。

宿主会读取项目的 AOCI 规则和实时指南，检查源代码、测试、配置和相关证据，然后为每个角色为 index 的受管理对象写入 FRAS 候选。你无需自己编排 Plan、Stage、Check、Diff、CAS 或 Apply。

第一个索引完成后，照常发送普通开发请求即可，例如：

Add priorities to tasks, including the frontend, backend, database, and test changes.

你无需在末尾追加“最后维护 AOCI 索引”。项目规则和 MCP 会让智能体在代码和测试稳定后检查索引变更，然后通过正式工作流更新受影响的条目。当项目使用 automation.mode=auto 时，AOCI-CODE 仅在需要真实人工批准、必须执行外部操作、无法证明恢复、安全检查失败或发现第三方并发冲突时才会打断你。其他自动化模式遵循各自的运行时契约。

验证一致性

入门流程完成后，运行：

"$AOCI" --repo . verify
"$AOCI" --repo . check

索引与当前受管理源代码应收敛回 aligned。如果未收敛，请先查阅实时指南；不要在包装脚本中重复实现内部状态机：

"$AOCI" --repo . index agent guide --agent codex --json

运行基本诊断

"$AOCI" --repo . capabilities
"$AOCI" --repo . doctor

要确认宿主实际连接的是哪个 AOCI，请读取服务器对自身的报告，而不是磁盘上的内容。在任何 aoci_overview check_only 响应或任何 aoci_maintain 响应中，cognition_receipt.mcp_service_version 是正在运行的版本，runtime_repository_root 是它所治理的仓库。匹配的二进制路径是项目 .mcp.json 中的 command，或等效的宿主配置：.codex/config.toml、opencode.json 或 .cursor/mcp.json。替换磁盘上的字节不会改变正在运行的 MCP 进程，因此在升级或回滚后请根据这些事实重新核对。

如需一次性演练，请在仓库中使用 examples/minimal-repository。

make fast

make full
./build/aoci --version

mkdir -p build
CGO_ENABLED=0 go build -o build/aoci ./cmd/aoci

初始化后会出现什么

典型仓库包含以下索引文件：

aoci.txt                    Root: declares the current CognitionSet and participating Volumes
aoci.meta.txt               Meta: tag dictionary, FRAS rules, and authoring constraints
aoci.code.txt               Code: model-authored entries for code and repository assets
aoci.database.txt           Database: optional table-level entries; absent by default
.aoci/
├── config.json             Team policy, Locale, Scope, and budgets
├── baseline.json           Governed Baseline for source, index, and database bindings
├── curation.json           Optional file-level include/exclude decisions
└── ...                     Drafts, Ledger, transactions, and recovery evidence; normally not committed to Git

初始化新项目会创建 Root、Meta 和一个空的 Code Volume；默认不包含 Database。AOCI-CODE 不会自行生成仓库或数据库的业务含义。

aoci init --agent <name> 还会写入宿主集成配置 （.mcp.json、.claude/settings.json、.codex/config.toml 或 opencode.json）， 其命令和仓库路径是与机器绑定的绝对路径。请将这些文件加入仓库的 .gitignore 并且不要提交：提交的副本在其他每台机器上都会失效，而且由于安装程序通过键是否存在来检测现有条目，在那里重新运行 init 会静默保留损坏的路径。

开发任务如何运行

下面两张图展示的是你实际体验的工作流，而不是 AOCI 的内部实现。

新项目：先构建简单系统，再引入 AOCI

flowchart TD
    I["The user proposes a product idea and requirements"] --> S["Use the agent's existing capabilities to build a simple new system"]
    S --> Q["Integrate AOCI MCP"]
    Q --> V["The agent builds the Whole-Index and verifies aligned"]
    V --> N["The user continues with ordinary development requests"]
    N --> M["The agent completes code, tests, and incremental index maintenance"]
    M --> N

新系统不需要从第一行代码就使用 AOCI-CODE。先用智能体现有能力构建原型；大约 10,000–30,000 行是引入它的合适时机（并非硬性阈值）。希望更早获得跨会话连续性的团队可以更早集成。

现有项目：为仓库建立索引，然后迭代

flowchart TD
    R["Existing repository, tests, configuration, and optional Schema"] --> B["Build AOCI-CODE from canonical source<br/>Request index generation"]
    B --> E["The agent inspects the existing system and writes the first index"]
    E --> V["Verify, Check, and Guide converge to aligned"]
    V --> T["The user submits an ordinary development task"]
    T --> C["The agent modifies code and runs quality checks"]
    C --> U["MCP guides the agent through index maintenance"]
    U --> G["The index and the current system return to aligned"]
    G --> T

第一个索引完成后，两种流程在日常工作中方式相同：你描述业务或工程需求；智能体结合 Whole-Index 与当前证据，完成开发与验证，并在任务收尾时通过 MCP 更新变更的对象。你无需学习内部的 Plan、Stage、Diff、CAS 或 Baseline 命令，也无需在每个提示中重复维护要求。

如果完整批次在任何正式写入开始前被拒绝，索引保持不变。如果工作流在正式写入开始后中断，系统会保留不可变意图、写入证据和恢复状态，然后要么从可证明的后像恢复，要么回滚到精确的前像。第三方字节冲突会失败关闭；AOCI-CODE 绝不会覆盖外部修改来“完成写入”。

最终状态始终是 applied、repair_required 或 stopped 之一。stopped 不是成功，也不一定意味着没有写入任何内容；请检查 failed_step、正式写入证据以及指南返回的恢复操作。

谁做什么：模型与 AOCI-CODE

模型负责含义

宿主模型读取源代码、测试、配置、文档以及所需的任何证据，然后决定：

• 某个对象实际负责什么；
• 哪些文件、模块或数据库对象是强关系，必须考虑才能安全地更改它；
• 它暴露哪些 API、命令、格式或可观察契约；
• 哪些事务、授权、并发、缓存、部署、兼容性或历史约束无法仅从普通结构推断。

AOCI-CODE 不会从文件名、路径、扩展名、AST 或模板组装 FRAS，也不会静默重写模型写入的内容。

AOCI-CODE 负责治理

AOCI-CODE 负责：

1. 建立 Safe Inventory、Managed Scope 和当前 Baseline；
2. 交付当前 Whole-Index 并确认其身份；
3. 生成确定性计划、目标集和源 SHA-256 值；
4. 验证候选结构、标签字典、关系身份、范围、所有权、预算和受影响范围；
5. 保持检查、差异和审查内容之间的绑定；
6. 通过跨进程锁、CAS 和原子写入提交完整批次；
7. 在写入后失败时推进 Baseline、追加账本并保留恢复证据；
8. 通过 Verify、Check 和指南再次证明当前治理状态；
9. 从权威资产派生 Lineage、Relations、Impact、Snapshot 和 Evolution 观察结果，而不创建第二个事实来源。

全绿的机器结果仅表示所编码的结构和治理契约成立；它们并不意味着模型写入的每条陈述都正确。

索引如何组织

AOCI 索引有两层：索引规则和索引条目。产品支持两种物理布局，它们不是同一种文件格式。

Volumes v1 布局

Volumes 项目按职责分离：

• aoci.txt 仅是 Root。它声明参与当前 CognitionSet 的 Volumes。
• aoci.meta.txt 存放 Meta：标签字典、FRAS 规则、预算和编写契约。
• aoci.code.txt 存放代码对象的条目。
• aoci.database.txt 在启用 Database Cognition 时存放数据库对象的条目。

Code 和 Database Volume 共享相同的 FRAS 行结构，但它们具有独立的对象身份、证据绑定、所有权和生命周期。Root、Meta 和对象 Volume 共同构成 Whole-Index；仅读取 aoci.txt Root 不足以声称你已阅读整个系统。

可以把它想象成一张地图：

• 索引规则是地图的图例和坐标系。
• 索引条目是描述每个位置的标记。
• Root 是当前地图集的目录和版本入口。
• Volume 是受同一协议治理但拥有自己证据来源和生命周期的独立图幅。

索引头部是什么样子

Root 和 Meta 都以机器读取的头部行开头。以下是 aoci init 为名为 my-service 的新 en-US 项目写入的内容，从作为激活入口的 Root 开始：

#AOCI-ROOT-MANIFEST: 1
#Format-Version: cognition-volumes/v1
#Locale: en-US
#Project: my-service
#Global-Invariants: -
#Volume: id=meta kind=meta path=aoci.meta.txt format=meta-v1 depends=- state=enabled
#Volume: id=code kind=code path=aoci.code.txt format=object-fras-v2 depends=meta state=enabled

每个 #Volume: 行声明一个参与 Volume 及其身份、类型、路径、格式、依赖和激活状态。未在此声明的 Volume 不属于当前 CognitionSet，无论工作树中还包含什么。启用 Database Cognition 会再增加一行：#Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled。

Meta 随后以治理每个条目的规则开头：

#AOCI-META-VOLUME: 1
#Object-Protocol: repository-cognition-object/v2
#FRAS-Discipline: 2
#FRAS-v2-Limits-Authority: machine-contract
#S-Admission: non-inferable-and-error-preventing
#S quota: C9-8≤600 C7-4≤200 C3-1≤50
#Object-Kinds: code=file database=table

#FRAS-v2-Limits-Authority: machine-contract 是关键行：字段限制属于二进制，而不属于此文本，因此项目无法通过编辑自己的 Meta 来放宽限制。#S-Admission 和 #S quota 专门治理 S 字段：那里究竟可以记录什么，以及每个重要性等级可以花费多少字符。标签字典紧随这些行之后；下文将完整展示。

Code Volume 以单行 #AOCI-CODE-VOLUME: 1 开头，其后所有内容都是目录节和条目。

这些是新项目的起始值，而非固定的协议常量。此后每个仓库自己的 Root 和 Meta 才是权威：较旧的项目可能带有自定义标签字典，而使用 --locale zh-CN 初始化的项目会写入 #Locale: zh-CN 并相应地本地化 #S quota: 键。

索引规则定义了哪些内容

在 v1 的 Volume 中，项目的 Meta Volume 存储这些规则；在 Legacy 布局中，它们位于单体头部。项目可以使用不同的标签字典，而基本 FRAS 结构保持不变。

本 README 仅说明如何阅读这些规则。对于具体、可执行的规则，请以当前项目的 Meta 或 Legacy 头部、AOCI 指南和正式规范为准。

一条条目记录什么（FRAS）

规则就位后，模型会为每个具有 index 角色的受管对象写一条条目。observe 角色仅参与变更观察，exclude 角色标记被有意排除的内容；两者都不拥有正式条目。AOCI 使用 FRAS 来组织条目中最重要的四类信息：

• F — 功能：该对象负责什么。
• R — 关系：要理解或安全地修改它，还必须考虑哪些其他对象。
• A — API：它暴露哪些接口、命令、格式或可观察契约。
• S — 非显而易见的约束：F、R、A 未覆盖、但理解或安全修改该对象所需的重要信息，例如关键约束、例外、边界和特殊语义。S 不应重复前三个字段。

例如，在 ===.../internal/fs/=== 目录段内，条目使用基名：

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 

目录段和基名解析为代码对象标识。对于跨 Volume 或系统投影，它会展开为规范标识，例如 code:internal/fs/atomic.go。数据库对象使用自己的规范标识，例如 database://primary/public/orders。

条目分为两部分：

atomic.go [CG9L]
└─ object ─┘ └ tags ┘

F: Core responsibility
R: Strong relationships that must be understood together
A: External interface or contract
S: Important additional information beyond F, R, and A

紧凑标签为每个对象提供架构层、功能域、重要性、可选技术特征和规模的坐标。标签字典由项目的 Meta Volume 或 Legacy 头部定义。程序校验字典和结构；它不决定业务含义。

S 不是梗概、普通摘要或对 F、R、A 的重复。 它补充前三个字段未覆盖、且影响理解或工程正确性的重要信息，例如：

• Redis 访问失败必须回退到数据库；
• 某张表不得进入 AutoMigrate；
• 遗留兼容分支不得被普通清理移除；
• 写入失败后必须保留原始文件。

模型根据实际源代码和证据编写此内容。AOCI-CODE 校验条目的结构，将其绑定到源文件，并治理其进入正式索引的方式。

阅读起始标签字典

以下摘录逐字复制自当前 en-US Volume Meta 模板（textassets/en-US/templates/volume-meta.txt.tmpl）。它是起始字典，不是通用词汇表：每个仓库的正式 Meta 仍是权威。起始字典未声明 D 字典；D 仍是可选轴，仅当当前正式 Meta 声明它时才可使用。

#Canonical-Tag-Authoring: compact A+B+C+[D]+E; dotted form is read compatibility only
#Code canonical identity example: code:path/to/file.go
#Code Entry example: file.go[EG7T]: F:Runs the example application | R:code:config/load.go | A:main | S:Exits non-zero when the config file is missing; it never falls back to built-in defaults
#[Tag dictionary: code]
#A Layer: C-SharedFoundation E-EntryBoundary A-ApplicationOrchestration D-DomainLogic K-AlgorithmComputation M-Middleware P-Persistence I-IntegrationAdapter R-RuntimeFoundation L-LibrarySDK F-DeclarativeConfiguration O-OperationsDelivery T-TestValidation S-DocumentationSpecification X-DevelopmentTooling Z-Other
#B Module: G-CrossDomain U-UserInteraction B-CoreBusiness D-DataState I-IdentityAccess N-NetworkProtocol M-MessageEvent S-SecurityPrivacy C-ConfigurationPolicy O-Observability R-ReliabilityRecovery P-PerformanceResource W-WorkflowScheduling A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityAssurance E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100
#[Tag dictionary: database]
#A Layer: E-EntityMaster T-TransactionFact R-RelationMapping M-DetailDependent C-ReferenceDictionary S-StateStorage H-HistoryVersion L-LogAudit Q-QueueOutbox A-AggregateProjection K-KeyValueConfiguration B-DocumentLargeObject Z-Other
#B Module: G-CrossDomain B-CoreBusiness I-IdentityAccess T-OrganizationTenant U-UserExperience F-FinanceBilling K-ContentKnowledge C-ConfigurationPolicy W-WorkflowTask M-MessageEvent N-ExternalIntegration S-SecurityPrivacy O-ObservabilityAudit R-ReliabilityRecovery P-PerformanceResource A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityTesting E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100

在起始代码字典下，[CG9L] 表示 C SharedFoundation、G CrossDomain、9 最高重要性、L 大规模；不存在 D 值。这解释如何阅读现有条目，而不是模型应如何分配标签。模型仍根据源代码和已接受的证据，从当前项目 Meta 中选择标签。

认知 Volume

AOCI-CODE 维护一个逻辑上的 Whole-Index，而每种索引都有自己的文件、归属和生命周期。

每个对象恰好有一个有效所有者。将对象放入错误的 Volume 会产生归属冲突。AOCI-CODE 仅在机器能够证明错误所有者、正确所有者和当前对象事实时才修复它；它不会根据相似名称猜测归属。

Code Volume、Database Volume 和范围可以一起演进，但它们共享一个受治理的提交边界。应用一个域不得丢弃另一个域现有的 Baseline 投影。Volume 应用、Baseline 更新和相关范围投影作为一个一致的事务结果发布，或进入可证明的恢复。它们绝不会留下“文件成功但另一个 Volume 没有基线”的半完成状态。

宿主集成

aoci init 始终写入受管代理规则，但宿主集成有所不同：

• Codex 获得项目级 MCP 配置，并在启用 --hooks 时获得上下文压缩提示和 SessionStart(compact)。它仍不安装文件编辑钩子。
• Claude Code 可以安装 PreToolUse 钩子。
• OpenCode V1 获得严格的项目级 opencode.json。
• Cursor 仅返回参考配置片段；不会向项目写入任何内容。

配置后，检查当前宿主会话是否已暴露 AOCI 工具。仅当该会话尚未加载新服务器时，才刷新或重新打开该项目会话。新会话通常读取一次规则和 Whole-Index。在索引标识保持有效且未发生已知宿主压缩的情况下，后续任务复用模型已有的内容；整个索引不会被机械地再次注入。

aoci --repo /absolute/path/to/repository init --agent codex
aoci --repo /absolute/path/to/repository init --agent codex --hooks
aoci --repo /absolute/path/to/repository init --agent claude --hooks
aoci --repo /absolute/path/to/repository init --agent opencode
aoci --repo /absolute/path/to/repository init --agent cursor

Codex --hooks 将压缩交接限制为回执标识、未完成的写入或恢复状态，以及立即重新加载指令；它不得保留或总结 Whole-Index 或 Overview/Attestation 正文。PreCompact 钩子无法注入宿主压缩输入或从中删除历史，因此无法单独强制执行此限制。在依赖已安装的项目钩子之前，请通过 Codex /hooks 审查并信任它。

Legacy 输出保留 Levels 0–4，以兼容现有宿主和报告。当前的 cognition-state/v2 将模型对系统的图景可用程度表示为 Levels 0–3，并将严格证明和治理事实分离为独立维度：

这些维度不能相互替代。Attestation 仅证明当前材料的交付覆盖和标识一致性；它并不意味着代理已完全理解所有可能的未来任务。只有 current_system_cognition_reliable=true 允许无保留地声称对当前系统有完整理解。

AOCI 面板

aoci ui 在本机提供只读面板，让你无需询问代理即可查看索引状态：

• 索引头部和 Code / Database Volume 逐字显示（=== 段行保持原样，可过滤，可整体复制）；“All”标签页是代理通过 Overview 收到的完整索引
• 索引 token 与预算对比，以及 Overview 分块计划
• 索引覆盖多少代码：文件、行、token 和压缩比；多少数据库表
• 治理状态与漂移、Managed Scope、宿主集成，以及正在运行的 aoci mcp 进程
• 接下来给代理的命令和提示，带复制按钮

页面可在中文和英文之间切换；刷新间隔可选（默认 30 秒）。

一个 WSL 中有多个 aoci mcp 服务器？在 Linux 和 WSL 上，面板会发现当前用户的每个 aoci mcp 进程及其仓库，通过顶部标签在它们之间切换，并标记磁盘上二进制已被替换的服务器。 边界：它只绑定回环地址（任何其他绑定都会被拒绝），只应答 GET 和 HEAD，不获取锁，不向账本追加任何内容，也不改动仓库中的任何一个字节。它是一个独立进程，与 aoci mcp 无关；MCP 服务器仍然不打开任何套接字。后台面板的注册信息存放在用户的缓存目录中，绝不会写入仓库。

常用 CLI 命令

常用组合：

# Initialization and first Baseline
aoci --repo . init --locale en-US --agent codex
aoci --repo . scan

# Verification and governance gates for Cognition Volumes
aoci --repo . verify --json
aoci --repo . check --json

# Live Guide; do not duplicate the state machine in a wrapper
aoci --repo . index agent guide --agent codex --json

# Capabilities and diagnostics
aoci --repo . capabilities
aoci --repo . doctor

# Database Evidence, Access, and Cognition lifecycle
aoci --repo . database --help
aoci --repo . database source access --source primary --json
aoci --repo . database cognition status
aoci --repo . cognition plan --help

# Derived System Cognition observations
aoci --repo . cognition system lineage
aoci --repo . cognition system relations

# MCP stdio Server
aoci --repo . mcp

Plan、Stage、Check、Diff、Apply、Curation、Scope Change、Bootstrap、Migration 和恢复命令仍然存在。请遵循运行中的二进制文件返回的指南；不要将内部状态机复制到脚本中。

关于“只读”命令

对于 verify、check、index score 和 index inventory，“只读”意味着不修改正式索引和 Baseline；它并不意味着严格零文件系统写入。启用 Ledger 时，这四个命令都可能向本地 Ledger 追加内容，verify 还会尝试写入 Verify History。审计写入失败不会改变现有的退出码或治理标准。

如果需要严格零文件写入的操作，请使用隔离副本；当前公开 CLI 不提供可禁用所有 Ledger 和 Verify History 写入的全局开关。System Cognition 命令不会创建第二个正式状态，但普通 CLI 调用仍遵循当前版本的运行时契约来处理 Ledger 和本地历史记录。

MCP 服务器

aoci mcp 不需要常驻守护进程，并通过 stdio 恰好暴露九个工具：

在 MCP 模式下，stdout 保留给 JSON-RPC；日志和诊断信息输出到 stderr。运行中的二进制文件提供的工具描述、JSON schema 和机器状态值是权威依据；本 README 仅是起点。

当前版本通过现有 CLI 和治理内核提供 System Cognition 能力。它们不会增加第十个 MCP 工具，也不会改变现有九个工具的名称、用途或 stdio 契约。

长时间会话与 Whole-Index 交付

在新对话开始时，代理通常会加载一个完整的 Overview，以获得与当前仓库、索引版本和 AOCI 服务身份相匹配的系统全貌。只要模型仍可依赖该全貌，就不需要在每个任务或工具调用之前重新加载。

在同一对话中，模型根据自身状态决定是否再次加载，但已知的宿主上下文压缩之后除外。压缩后的交接可能只保留回执身份、未完成的写入或恢复状态，以及立即重新加载的指令；它不得保留或摘要 Whole-Index 或 Overview 的头部、条目、分块、挑战或证明正文。复制到该交接中的索引内容或回执不能证明模型当前的全貌是可靠的。

在已知压缩之后继续业务工作之前，如果规则已不再可靠存在，代理会重新加载规则，使用新的事件 ID 声明 context_compaction，并完成一次普通的完整 Overview 游标、确认和证明序列。check_only 和认知探测不能替代此过程。在全新的完整传输之后，现有的部分或失败证明规则仍允许基于来源的继续，而无需第二次自动 Overview。对于没有已知压缩的语义变更或重大阶段边界，AOCI 提供刷新阈值、检查点和身份事实，模型决定是否需要为任务恢复其系统级全貌。

每个完整 Overview 的正文由起始标记、当前正式索引的精确内容和结束标记组成。

当 Overview 超出项目的分块预算时：

1. 交付立即从第 1 块开始；
2. 代理必须自动遵循 next_cursor 直到最后一块；
3. 代理使用已交付的 Whole-Index 提交一次证明；
4. 本地搜索、旧记忆、补充源阅读或直接文件读取不得被呈现为完整交付；
5. 待处理的恢复或不一致的快照会失败关闭，不混合内容。

overview_delivery.chunk_tokens 是唯一的交付大小设置。其默认值为 7000，有效范围为 4000 到 24000。check_only=true 是不带分块链的紧凑检查点。

AOCI 在 aoci_overview 上声明每个工具的结果大小限额。如果宿主原本会将大型工具结果持久化到磁盘、只在模型上下文中保留预览（对于索引交付而言，这是一种静默失败），则仅针对此工具提高该阈值。在 Claude Code 上，这使得完整的 24000 可用，以三个分块而非五个分块交付 480 个对象的索引。不进行任何探测：该声明是静态的，不识别它的宿主会忽略它，这符合 MCP 规范的要求。

刷新阈值默认为 30 个不同的语义路径，也可以按项目配置。关于精确的计数规则，请以 Cognition Refresh 文档和运行时契约为准。

Database Cognition

AOCI-CODE 可以将数据库结构纳入同一索引和同一治理之下，其访问边界明确且狭窄：

Explicit database command
  → Read-only PostgreSQL/MySQL/openGauss system catalogs
  → Canonical schema evidence
  → Human acceptance of the evidence hash
  → The host model writes table-level FRAS from complete evidence
  → Entries are bound to the evidence and enter governed apply

• 未配置数据库或未运行显式数据库命令时，不会发生任何数据库网络访问。
• 只读取基表的模式元数据，不读取业务行；视图、例程和注释不在当前收集范围内。
• 不执行任何 DDL 或 DML。
• 主机名、用户名、DSN 和凭据值绝不会写入索引文件。
• Database Cognition 应用过程离线运行，写入期间不会重新连接数据库。
• 程序保留并比较结构证据，但表职责、关系和高价值约束仍由模型编写。

MySQL 支持覆盖 5.7.6 及更高版本。收集器读取服务器版本，并且只运行该版本能够应答的目录查询：CHECK 约束从 8.0.16 起，索引表达式从 8.0.13 起，索引可见性从 8.0.0 起。5.7 服务器会记录一个空的检查列表，因为 5.7 会解析 CHECK 语法但不存储任何内容；在所有受支持的版本上，证据具有相同的形状。不支持 MariaDB，会拒绝它而不是将其作为 MySQL 读取。

初始 openGauss 配置有意限定为 A/PG 兼容模式下的 openGauss 6.0.5 LTS 以及普通非分区基表。不支持的目录特性会失败关闭，而不是被静默降级为 PostgreSQL 事实；这并不声称支持 MogDB、GaussDB、Dolphin/B/MySQL 模式、分区或子分区、列存、MOT、外部表或临时表、视图、例程或触发器。

在这里，失败关闭检测适用于选定的、具有不支持语义的可见类表对象。例程和触发器仍不在 v1 表对象域内，绝不会被表示为表事实。

openGauss 路径使用 AOCI 在官方 Connector v1.0.8 源码上经过审查的本地补丁。其严格解析器只接受经过审查的连接参数，不会消费环境中的 PG*、服务、密码文件、主目录或日志记录器配置。在数字回环地址之外的 TCP 连接必须显式使用 sslmode=verify-full（如果提供，还需在 sslrootcert 中使用绝对可信根路径），最低 TLS 1.2；TLS 降级模式会被拒绝。 sslmode=disable 仅在接受显式 Unix 套接字或用作本地/测试边界的数字回环地址时被接受。数据库管理员仍负责在对话之外提供该 DSN，并配置最小权限账户。

Database Volume 默认不存在。只有在项目显式启用 Database Cognition 并完成证据、绑定和生命周期治理之后，它才会进入 Whole-Index。

数据库访问入门：你不需要了解 DSN 细节

你只需为数据库源声明一个非敏感身份。如果省略 --credential-env，AOCI 会从源 ID 派生一个稳定的环境变量引用；例如，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

此命令不会连接数据库、返回凭据值，也不会要求你将 DSN 粘贴到对话中。数据库或基础设施管理员在 AOCI 进程之外提供环境变量，并授予对系统目录的只读、最小权限访问。源配置只存储凭据引用名称，不存储密钥。

当前候选版本仅提供环境凭据提供程序。Vault、Kubernetes Secret 和 AWS/GCP/Azure 等云密钥管理器可能会在后续版本中通过相同的提供程序边界集成；它们目前不可用，本 README 不暗示其他情况。 这种拆分让账户格式、DSN 编码和密钥生命周期管理远离普通用户，同时保持授权显式：AOCI 不会自动发现凭据、扫描 .env、读取密钥文件，也不会绕过数据库管理员的授权边界。

系统认知基础

在代码索引和数据库索引之上，AOCI-CODE 提供了一组派生的系统认知观察。它们回答诸如“这个对象从何而来？”、“数据库变更可能影响哪些代码对象？”以及“历史观察与当前状态之间发生了什么变化？”等问题。它们不会创建新的权威事实层。

# Where an index object came from, with its evidence and receipt bindings
aoci --repo . cognition system lineage

# Volume containment and dependencies plus resolved model-authored R relationships
aoci --repo . cognition system relations

# Find code impact from a database object along formal R relationships
aoci --repo . cognition system impact \
  --object database://primary/public/orders

# Save a historical observation on the caller side
aoci --repo . cognition system snapshot --json > previous.json

# Compare a caller-supplied historical observation with the current derived projection
aoci --repo . cognition system evolution \
  --snapshot-file previous.json

权威边界

每个系统认知结果都会报告 derived=true；关系投影还会额外报告 authoritative=false。认知 Volume、模式证据绑定、Baseline 指纹和回执绑定标识仍是底层权威。未解析的 R 关系会产生不完整结果或诊断信息；程序不会猜测并填充它们。

AOCI-CODE 不是知识图谱系统。 窄范围的关系投影是一种便捷的关系视图，但它不拥有第二套状态管理系统、独立写入路径或新的事实存储。派生输出可以删除，并可从当前权威资产重新计算。如果投影与权威资产冲突，以权威资产为准。

执行模式、隐私和数据边界

• AOCI-CODE 默认本地优先，没有默认云端点、没有托管的源码上传服务，也不需要后台服务器。
• Agent 原生模式下的数据处理取决于你选择的宿主及其产品政策；AOCI-CODE 不会代表宿主上传数据。
• 数据库网络访问必须显式触发，并且仅限于只读模式元数据。
• 账本、草稿、事务和恢复证据默认存储在 .aoci/ 下，通常被 Git 忽略；索引文件和团队治理资产可以提交到 Git。
• 系统认知投影从现有权威资产在本地计算，不需要图数据库、向量数据库或远程图服务。

与仓库地图、RAG、LSP 或代码图的区别

搜索、AST、LSP、代码图和 RAG 擅长结构和检索类问题。AOCI-CODE 做的是另一项工作：它维护一份覆盖受管范围的、带版本的系统描述，并随软件增量演化。你能得到：

• 整体索引（Whole-Index）。 一份覆盖当前受管范围的系统地图，而不是为每个任务临时拼装的片段。
• FRAS 条目。 为每个具有 index 角色的对象记录职责、强关系、公共契约和高价值约束。
• 跨会话持久化。 索引文件与仓库共存，因此后续会话和其他 Agent 可以复用同一版本。
• 受管范围（Managed Scope）。 显式记录哪些对象进入索引、哪些仅被观察变更、哪些被有意排除。
• 漂移检测。 区分 Missing、Orphan、Stale、Unbaselined、行尾变化、策展差异，以及被排除在编写之外的来源（空文件、二进制、超大文件）。
• 受治理的更新。 候选内容通过源绑定、计划、验证、审查、CAS、原子写入、Baseline 和恢复工作流进入正式文件。
• 交付证明。 分块、游标、回执和挑战证明 Whole-Index 已完整交付。
• 数据库认知。 基于显式接受的 PostgreSQL/MySQL/openGauss 模式证据构建并治理的表级条目。
• 系统投影。 从权威索引及其绑定派生的血缘、窄范围关系、数据库到代码影响、快照和演化观察，不复制权威状态；影响仅遍历模型显式编写的 R 关系。

AOCI-CODE 补充现有工具，而不是替代它们。

推荐组合：AOCI-CODE 提供全局语义先验；代码图、LSP、搜索和源码提供精确证据；测试和运行时结果提供最终验收。AOCI 的关系投影不替代精确调用图：它暴露结构性的 Volume 包含关系和 Root 依赖边，而其语义边仅限于模型显式编写的强关系。

技术栈

AOCI-CODE 不需要 Neo4j、向量数据库、长期运行的守护进程或 AOCI 云服务。启用数据库认知时，目标数据库只是显式的、只读的模式证据来源，而不是 AOCI 自己的状态存储。

常见问题

为什么 Legacy status --deep 仍显示漂移？

status --deep、index score 和 index agent plan 仅限 Legacy。对于 Cognition Volumes 仓库，请运行实时指南，让宿主使用普通的 无参数 aoci_maintain，通过 aoci_update_entry 提交完整的当前批次，并以 Verify、Check 和指南收尾。不要直接修改 Baseline，也不要跳过源绑定和恢复步骤。

Legacy 布局本身已弃用。Volumes v1 是新仓库和迁移仓库的受支持路径，仅限 Legacy 的命令计划在 v0.2.0 中移除；请在此前使用 aoci cognition migration 迁移 Legacy 仓库。

aoci --repo . index agent guide --agent codex --json

为什么宿主启动了错误的 AOCI？

检查项目级 MCP 配置中的可执行文件路径，确保它是稳定的绝对路径，然后运行：

/absolute/path/to/aoci --version
/absolute/path/to/aoci --repo . doctor

要验证已加载的 stdio 服务器而不仅是磁盘上的文件，还应检查宿主进程的实际可执行文件、其命令行 --repo，以及重启后的进程标识。

我必须自己创建数据库账户并提供 DSN 吗？

你不需要理解 DSN 语法，也不应在聊天中发送密钥。在你声明非敏感的源标识后，AOCI 会提供稳定的环境变量引用。数据库管理员仍需创建一个外部的、最小权限的账户，具有只读系统目录访问权限，并将该引用提供给运行时环境。当前版本不会代表组织创建数据库账户，也不会自动读取密钥存储。

可以在 CI 中运行吗？

可以。扫描、验证、治理门禁和确定性检查在运行时不写入新条目。关于确切命令、审计写入和退出码，请以当前二进制的 --help、JSON schema 和项目的 CI 文档为准。

全绿的 AOCI 结果能证明语义正确吗？

不能。绿色结果证明所编码的结构和治理条件成立。模型写入的内容仍需对照源代码、模式、测试、运行时结果和人工审查进行检查。

系统认知图是新的真相来源吗？

不是。当前能力是窄范围的关系投影，不是独立的图平台。它仅从正式索引、证据、回执和 Baseline 计算结果，不持久化新的权威事实。程序也不会从导入、SQL、文件名或相似性自动生成语义关系。

文档

文档和公共契约链接固定指向 v0.1.0-rc22，因此当从二进制 Release 归档中阅读本 README 时它们仍然有效，因为该归档不包含仓库的 docs/ 或 spec/public/ 目录。

黑盒验证套件

仓库在 scripts/blackbox/ 下提供四个独立的黑盒套件，它们严格从进程外部、仅通过公共 stdio MCP 协议和 CLI 来测试已构建的 aoci 二进制文件：

• 协议一致性 — 对 MCP 通信接口进行 53 项只读检查，并在 zh-CN 下重复依赖区域设置的语句；
• 故障注入场景 — 75 个场景，涵盖游标篡改、崩溃恢复、并发写入者，以及在一次性夹具仓库上的写入前钩子；
• 在冻结的真实项目上验证生命周期 — 三个已提交的夹具项目：repo-a（TypeScript）和 repo-b（Python + MySQL）运行完整的 init 到重新对齐的生命周期，而 repo-c（一个 453 文件的分层服务）还额外在机器批次上限下驱动多批次编写。可选的模型轨道会让一个真实的 AI 代理——你的 OpenCode 安装所暴露的任何模型——通过这两个小型仓库，并从公共接口对最终状态进行评分。
• 升级轴 — 每个已发布版本 80 项检查，覆盖十种仓库形态：每个已发布版本都用其自身的二进制文件构建并编写一个仓库，然后被测二进制文件必须在不移动身份、不要求范围变更、不重写正式资产的情况下治理它，并且它随后编写的内容必须使另一路径的检出保持对齐；在第十种形态中，角色反转，每个已发布版本都必须读取被测二进制文件写入的仓库，而不崩溃或重写它。其他三个套件都用被测二进制文件生成每个夹具，因此版本之间发生变化的原像在构造上对它们不可见。

它们只需要在已构建的二进制文件之上安装 Python 3 和 git（MySQL 套件需要 Docker；模型轨道需要 OpenCode 加上你自己的模型订阅），因此仓库克隆可以验证其自身的构建、平台移植或分支——并且 AOCI_BIN 可以将一致性和场景套件指向任何声称符合 spec/public/ 中公共契约的替代二进制文件。这些套件位于仓库克隆中；二进制 Release 归档不包含它们。有关命令和结果解读，请参阅 scripts/blackbox/README.md。

研究、知识产权与许可

AOCI-CODE 研究论文和制品可以公开描述已发布的方法、实验协议和结果。专利申请、已授予的范围、法律状态、所有者和地域效力属于法律事实，不应仅凭内部 README、历史版本号或未经核实的转述就将其添加到产品描述中。

如果将来必须披露具体的专利号、授予日期或范围，权利人和法律顾问应依据官方公开记录进行核实，并将其放入专门的知识产权、NOTICE 或法律文档中。本 README 只应链接到该权威文件；它本身既不应扩展专利覆盖范围，也不应将专利状态呈现为软件许可。

社区

使用微信或企业微信扫描代码，加入 AOCI 项目群，与维护者和其他用户交流。请将错误报告和功能请求作为 GitHub issues 提交，以便它们保持可搜索，并按照 SECURITY.md 所述私下报告疑似漏洞，切勿在群中报告。

AOCI-CODE 并不是让代理看到更多代码。它让代理在每次行动之前，对系统拥有一份当前、结构化、可追溯且受治理的理解。Git 为你的代码提供版本管理，数据库迁移为你的数据结构提供版本管理，而 AOCI-CODE 为代理对系统的认知提供版本管理，并涵盖该认知演进过程的可追溯性、治理一致性和恢复边界。