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 對它進行差異比對、審查、版本控管與回復。
• 不只是「檔案在哪裡」。 它記錄了職責、強關聯、公開契約、交易邊界、相容性約束，以及其他難以從程式碼結構推斷的內容。
• 可攜。 索引與專案一同存放，不綁定於某個模型、代理或工作階段。只要它與程式碼保持一致，任何代理與任何後續工作階段都能重複使用，無須從頭重建理解。
• 程式碼與資料庫並重。 模型可為資料庫資料表建立一份獨立的資料表層級索引。兩者一同提供時，能讓代理對系統有更完整的認識。

索引是一組受治理的純文字檔案，與專案一同存放：

• 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 角色，治理受管理範圍（Managed Scope）以及模型為每個受管理物件所撰寫的條目。
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 指令，也不需要在每個提示中重複維護要求。

若完整批次在任何正式寫入開始前被拒絕，索引維持不變。若工作流程在正式寫入開始後中斷，系統會保留不可變的意圖、寫入證據與復原狀態，然後從可證明的後像（postimage）繼續，或回滾到確切的前像（preimage）。第三方位元組衝突會以失敗關閉（fail closed）；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 Volumes 共用相同的 FRAS 行結構，但具有獨立的物件身分、證據綁定、所有權與生命週期。Root、Meta 與物件 Volumes 共同構成 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: 鍵在地化。

索引規則定義了什麼

在 Volumes v1 中，專案的 Meta Volume 儲存這些規則；在 Legacy 配置中，它們位於單體式標頭檔。專案可使用不同的標籤字典，而基本 FRAS 結構維持不變。

本 README 僅說明如何閱讀這些規則。具體、可執行的規則，請以當前專案的 Meta 或 Legacy 標頭檔、AOCI 指南與正式規格為準。

單一條目記錄的內容（FRAS）

規則就位後，模型會為每個具有 index 角色的受管理物件撰寫一個條目。observe 角色僅參與變更觀察，exclude 角色則標示刻意排除的內容；兩者皆不擁有正式條目。AOCI 使用 FRAS 來組織條目中最關鍵的四類資訊：

• F — Function（功能）：該物件負責什麼。
• R — Relations（關聯）：要理解或安全地變更它時，還必須一併考量的其他物件。
• A — API：它對外暴露的介面、命令、格式或可觀察的契約。
• S — Non-obvious constraints（非顯而易見的限制）：F、R、A 未涵蓋、但理解或安全變更該物件所需的重要資訊，例如關鍵限制、例外、邊界與特殊語意。S 不應重複前三個欄位。

例如，在 ===.../internal/fs/=== 目錄區段內，條目使用其 basename：

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 

目錄區段與 basename 會解析為一個程式碼物件身分。對於跨 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 沒有 baseline」的半完成狀態。

主機整合

aoci init 一律寫入受管理的代理規則，但主機整合方式各異：

• Codex 取得專案層級 MCP 設定，並在啟用 --hooks 時取得上下文壓縮提示與 SessionStart(compact)。它仍不安裝檔案編輯 hook。
• Claude Code 可安裝 PreToolUse hook。
• 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 hook 無法注入主機壓縮輸入，也無法從中刪除歷史，因此無法單獨強制執行此限制。在依賴它之前，請透過 Codex /hooks 審查並信任已安裝的專案 hook。

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 程序及其儲存庫，透過頂部分頁切換，並標示二進位檔已在磁碟上被替換的伺服器。 邊界：它只綁定 loopback 位址（任何其他綁定都會被拒絕），只回應 GET 與 HEAD，不取得鎖，不向帳本附加任何內容，也不更動儲存庫的任何一個位元組。它是與 aoci mcp 無關的獨立程序；MCP 伺服器仍然不開啟任何 socket。背景面板的註冊資訊存放在使用者的快取目錄中，絕不會放在儲存庫裡。

常用 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 的標頭、條目、chunk、challenge 或 attestation 內容。複製到該交接內容中的索引內容或收據，無法證明模型目前的全貌是可靠的。

在已知壓縮後繼續業務工作之前，代理會在規則已無法可靠取得時重新載入規則，以新的事件 ID 宣告 context_compaction，並完成一次一般的完整 Overview 游標、確認與 attestation 序列。check_only 與 cognition probe 都不是替代方案。在全新完整傳輸之後，既有的部分或失敗 attestation 規則仍允許以來源為依據繼續進行，而無需第二次自動 Overview。對於沒有已知壓縮的語意變更或重大階段邊界，AOCI 提供重新整理閾值、檢查點與身分事實，由模型決定是否需要為該任務還原其系統層級全貌。

每份完整 Overview 的內容由起始標記、目前形式索引的完整內容，以及結束標記組成。

當 Overview 超過專案的 chunk 預算時：

1. 傳遞會立即從 chunk 1 開始；
2. 代理必須自動遵循 next_cursor 直到最後一個 chunk；
3. 代理使用所傳遞的 Whole-Index 提交一次 attestation；
4. 本機搜尋、舊記憶、補充來源閱讀或直接讀取檔案，都不得被呈現為完整傳遞；
5. 待處理的復原或不一致的快照會以 fail-closed 方式失敗，且不會混入內容。

overview_delivery.chunk_tokens 是唯一的傳遞大小設定。其預設值為 7000，有效範圍從 4000 到 24000。check_only=true 是沒有 chunk 鏈的精簡檢查點。

AOCI 會在 aoci_overview 上宣告每個工具的結果大小容許量。若主機原本會將大型工具結果持久化到磁碟，只在模型上下文中留下預覽（對索引傳遞而言即為無聲失敗），則會單獨為此工具提高該閾值。在 Claude Code 上，這讓完整的 24000 變得可用，以三個 chunk 而非五個 chunk 傳遞 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

• 未設定資料庫或未執行明確的資料庫指令時，不會發生任何資料庫網路存取。
• 只讀取基底資料表的 schema 中繼資料，不讀取業務資料列；檢視、常式與註解不在目前的收集範圍內。
• 不會執行任何 DDL 或 DML。
• 主機名稱、使用者名稱、DSN 與憑證值絕不會寫入索引檔案。
• Database Cognition apply 會離線執行，寫入期間不會重新連線至資料庫。
• 程式會保留並比較結構證據，但資料表職責、關聯與高價值限制仍由模型撰寫。

MySQL 支援涵蓋 5.7.6 及更新版本。收集器會讀取伺服器版本，並且只執行該版本能回答的目錄查詢：CHECK 限制從 8.0.16 起、索引運算式從 8.0.13 起、索引可見性從 8.0.0 起。5.7 伺服器會記錄空的 check 清單，因為 5.7 會解析 CHECK 語法但不儲存任何內容；證據在所有支援的版本上都具有相同的形狀。不支援 MariaDB，且會予以拒絕，而不是當作 MySQL 讀取。

初始的 openGauss 設定檔刻意僅限於 A/PG 相容模式下的 openGauss 6.0.5 LTS 與一般非分割基底資料表。不支援的目錄功能會以 fail-closed 方式失敗，而不是被無聲地簡化為 PostgreSQL 事實；這並不表示支援 MogDB、GaussDB、Dolphin/B/MySQL 模式、分割區或子分割區、column-store、MOT、外部或暫存資料表、檢視、常式或觸發器。

在此，fail-closed 偵測適用於具有不支援語意的選定可見類資料表物件。常式與觸發器仍不在 v1 資料表物件範疇內，且絕不會被表示為資料表事實。

openGauss 路徑使用 AOCI 在官方 Connector v1.0.8 原始碼上經審查的本機修補。其嚴格解析器只接受經審查的連線參數，且不會取用環境中的 PG*、service、password-file、家目錄或 logger 設定。數值 loopback 位址以外的 TCP 連線必須明確使用 sslmode=verify-full（若提供，還需在 sslrootcert 中指定絕對的受信任根路徑），並以 TLS 1.2 為最低要求；TLS 降級模式會被拒絕。sslmode=disable 僅在明確的 Unix socket 或作為本機/測試邊界的數值 loopback 位址時才被接受。資料庫管理員仍須負責在對話之外提供該 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-native 模式下的資料處理取決於您選擇的主機及其產品政策；AOCI-CODE 不會代替主機上傳資料。
• 資料庫網路存取必須明確觸發，且僅限於唯讀的結構描述中繼資料。
• 帳本、草稿、交易與復原證據預設儲存於 .aoci/ 之下，通常由 Git 忽略；索引檔案與團隊治理資產則可提交至 Git。
• 系統認知投射由現有權威資產在本地計算，不需要圖形資料庫、向量資料庫或遠端圖形服務。

與 repo map、RAG、LSP 或程式碼圖的差異

搜尋、AST、LSP、程式碼圖與 RAG 擅長結構性與檢索性問題。AOCI-CODE 做的是不同的工作：它維護一份涵蓋受管理範圍、隨軟體增量演進的版本化系統描述。您可獲得：

• Whole-Index。 涵蓋目前受管理範圍的單一系統地圖，而非為每個任務臨時拼湊的片段。
• FRAS 條目。 為每個具有 index 角色的物件記錄職責、強關聯、公開契約與高價值約束。
• 跨工作階段持久化。 索引檔案與儲存庫共存，因此後續工作階段與其他代理可重用相同版本。
• 受管理範圍（Managed Scope）。 明確記錄哪些物件進入索引、哪些僅被觀察變更，以及哪些被刻意排除。
• 漂移偵測。 區分 Missing、Orphan、Stale、Unbaselined、行尾變更、策展差異，以及被排除於撰寫之外的來源（空白、二進位、過大）。
• 受治理的更新。 候選項透過來源綁定、計畫、驗證、審查、CAS、原子寫入、Baseline 與復原工作流程進入正式檔案。
• 交付證明。 Chunk、cursor、receipt 與 challenge 證明 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 結構描述與專案的 CI 文件為準。

AOCI 結果全部通過是否證明語意正確？

否。全部通過僅證明所編碼的結構與治理條件成立。模型所撰寫的內容仍須對照原始碼、結構描述、測試、執行時結果與人工審查進行檢查。

系統認知圖是新的真相來源嗎？

否。目前的能力是狹義的關聯投射，而非獨立的圖形平台。它僅從正式索引、證據、收據與 Baseline 計算結果，且不會持久化新的權威事實。程式也不會從匯入、SQL、檔名或相似度自動產生語意關聯。

文件

文件與公開契約連結皆固定指向 v0.1.0-rc22，因此當本 README 從二進位 Release 封存檔讀取時仍保持有效，該封存檔並不包含儲存庫的 docs/ 或 spec/public/ 目錄。

黑箱驗證套件

儲存庫在 scripts/blackbox/ 下隨附四套獨立的黑箱驗證套件，它們嚴格從 程序外部、僅透過公開的 stdio MCP 協定與 CLI，對已建置的 aoci 二進位檔進行 驗證：

• 協定一致性 — 對 MCP 線路介面進行 53 項唯讀檢查，並在 zh-CN 下重複 執行依地區設定而異的句子；
• 故障注入情境 — 75 個情境，涵蓋游標竄改、當機復原、競爭寫入者，以及在可拋棄式 測試 fixture 儲存庫上的寫入前掛鉤；
• 在凍結的真實專案上執行生命週期 — 三個已提交的 fixture 專案： repo-a（TypeScript）與 repo-b（Python + MySQL）執行完整的 init 到重新對齊的生命週期，而 repo-c（一個 453 檔案的分層服務） 另外在機器批次上限下驅動多批次撰寫。一個可選的模型軌道會讓真實的 AI 代理——你的 OpenCode 安裝所暴露的任何模型——跑過這兩個小型儲存庫，並從公開介面為最終狀態評分。
• 升級軸 — 每個已發佈版本 80 項檢查，涵蓋十種儲存庫形態：每個已發佈的版本都會用 自己的二進位檔建置並撰寫一個儲存庫，接著受測的二進位檔必須治理它，且不得移動任何 身分、要求範圍變更或改寫任何正式資產，而它隨後撰寫的內容必須讓位於另一路徑的 簽出保持對齊；在第十種形態中角色對調，每個已發佈的版本都必須讀取受測二進位檔所 撰寫的儲存庫，且不得當機或改寫它。其餘三套套件都以受測二進位檔鑄造每個 fixture， 因此版本之間發生變化的前像在她們的構造下是看不見的。

它們只需要在已建置的二進位檔之上有 Python 3 與 git（MySQL 套件需要 Docker；模型軌道 需要 OpenCode 加上你自己的模型訂閱），因此儲存庫複本可以驗證自己的建置、平台移植或 分支——而 AOCI_BIN 可以將一致性與情境套件指向任何宣稱符合 spec/public/ 中公開契約的替代二進位檔。這些套件位於儲存庫複本中；二進位 Release 封存檔並不包含 它們。指令與結果解讀請參閱 scripts/blackbox/README.md。

研究、智慧財產與授權

AOCI-CODE 的研究論文與成果可公開描述已發佈的方法、實驗協定與結果。專利申請、已授予 的範圍、法律狀態、所有人與領土效力皆屬法律事實，不應憑藉內部 README、歷史版本號或 未經查證的轉述而加入產品描述。

若未來必須揭露特定專利號、授予日期或範圍，權利人與法律顧問應對照官方公開紀錄加以 查證，並將其置於專屬的 IP、NOTICE 或法律文件中。本 README 應僅連結至該權威檔案； 它本身既不應擴張專利涵蓋範圍，也不應將專利狀態呈現為軟體授權。

社群

使用微信或企業微信掃描程式碼，加入 AOCI 專案群組，與維護者及其他使用者交流。請將 錯誤回報與功能請求提交為 GitHub issues，以便保持可搜尋性；疑似漏洞 請依 SECURITY.md 所述私下回報，切勿在群組中回報。

AOCI-CODE 並非讓代理看見更多程式碼。它讓代理在每次行動之前，對系統擁有當前、結構化、 可追溯且受治理的理解。Git 為你的程式碼建立版本，資料庫遷移為你的資料結構建立版本， 而 AOCI-CODE 為代理對系統所知的一切建立版本，連同該知識演進方式的可追溯性、治理一致性 與復原邊界。