AOCI-CODE

AOCI-CODE

Постоянная, версионируемая в Git карта всей вашей кодовой базы — написанная вашим кодирующим агентом и управляемая локальным MCP-сервером. Агенты читают её один раз и знают систему, вместо того чтобы перечитывать репозиторий при каждой задаче.

🇺🇸 English | 🇨🇳 简体中文

Что это делает

Стройте большие системы, не теряя нить. В Codex, Claude Code, Cursor, OpenCode и подобных агентах ваш агент начинает каждую задачу, уже зная всю систему: для чего нужен каждый файл, от чего он зависит и что не должно сломаться. Он перестаёт искать и перечитывать кодовую базу при каждом запросе. Люди, не являющиеся профессиональными разработчиками, могут продолжать развивать свои системы; профессиональные разработчики могут передать всю систему агенту и сосредоточить внимание на архитектуре и проектировании.

Примите существующую систему за один шаг. Укажите агенту на существующую кодовую базу объёмом примерно до 500 000 строк и попросите построить индекс. Он сообщит, насколько хорошо знает каждую область, и продолжит разработку оттуда. Практический предел — это размер индекса, а не количество строк: коммерческая система на 700 000 строк разрабатывается так уже сегодня, с индексом около 300 тыс. токенов.

Меняйте людей, агентов или диалоги, не начиная заново. Индекс хранится в репозитории рядом с кодом и версионируется через 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 и карты репозиториев.

Чего ожидать

Первый индекс занимает некоторое время. Агент читает каждый управляемый файл и пишет одну запись на файл: примерно час на каждые 200 000 строк кода, в зависимости от модели и скорости агента. Работа идёт пакетами и возобновляется с места остановки при прерывании.

Есть база данных? Проиндексируйте и её. Поддерживаются MySQL и PostgreSQL, а также openGauss 6.0.5 с ограничениями. MySQL означает 5.7.6 и новее; MariaDB не поддерживается. Сначала постройте индекс кода, затем индекс базы данных. Когда знания об коде и таблицах предоставляются вместе, агент понимает систему полнее.

Только локально: только чтение в вашей системе, без Интернета, без хранения учётных данных. AOCI-CODE читает ваш исходный код и структуры таблиц базы данных, но никогда — бизнес-данные. Он записывает свои файлы индекса и собственное состояние внутри каталога проекта, а также регистрацию страницы состояния в каталоге кэша пользователя. Он никогда не обращается к Интернету и ничего не загружает: единственные соединения, которые он открывает, — это соединения с объявленной вами базой данных для метаданных каталога и с собственной страницей состояния на loopback. Учётные данные базы данных указываются по имени переменной окружения и никогда не хранятся. Текст индекса записывается локально вашим собственным агентом через уже используемый вами канал модели; 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 описывает, что она показывает, и другие её команды.

Почему нужен перезапуск: индекс записывается через MCP-инструменты AOCI, а сессия, выполнившая init, не загрузила MCP-сервер, который только что записал init. Хост, загружающий 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) — это метод и протокол: слой между кодирующими агентами и программными системами. Модели рассуждают, агенты планируют и выполняют, а AOCI поддерживает актуальное описание системы, охватывающее код, конфигурацию, тесты и структуру базы данных, чтобы агенты читали его перед действием. AOCI-CODE — это данный проект: CLI aoci, MCP-сервер и индекс, который они поддерживают.

AOCI-CODE дистиллирует то, что действительно важно для понимания и изменения системы, в плотный текстовый индекс, сочетающий символы и смысл. Когда контекст модели ограничен, агент сначала читает индекс, за один проход получает большую часть ключевой информации о проекте и затем приступает к задаче. Это сокращает повторный поиск и переобучение и переносит понимание между задачами и сессиями.

• Не разовый обзор. Индекс развивается вместе с системой и остаётся в проекте, где вы можете просматривать различия, рецензировать, версионировать и откатывать его с помощью Git.
• Больше, чем «где находятся файлы». Он фиксирует обязанности, сильные связи, публичные контракты, границы транзакций, ограничения совместимости и другие вещи, которые трудно вывести из структуры кода.
• Переносимый. Индекс хранится вместе с проектом и не привязан к модели, агенту или сессии. Пока он согласован с кодом, любой агент и любая последующая сессия могут повторно использовать его, не выстраивая понимание с нуля.
• Код и базы данных вместе. Модель может построить отдельный индекс уровня таблиц для таблиц базы данных. Предоставленные вместе, они дают агенту более полную картину системы.

Индекс — это набор управляемых текстовых файлов, хранящихся вместе с проектом:

• Root (aoci.txt) объявляет, из чего состоит текущий индекс, и является точкой входа для его активации.
• Meta (aoci.meta.txt) содержит словарь тегов, правила FRAS и ограничения авторства.
• Code (aoci.code.txt) содержит записи, написанные моделью для кода и других ресурсов репозитория.
• Database (aoci.database.txt) содержит необязательные записи уровня таблиц, когда включено Познание базы данных.

Root, Meta и участвующие тома объектов вместе образуют Whole-Index. Рабочий процесс поверх них состоит из трёх этапов:

1. Построение индекса под управлением. Модель читает исходный код и принятые свидетельства. AOCI-CODE управляет Managed Scope и записями, которые модель пишет для каждого управляемого объекта с ролью 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, объявленный в go.mod, make, и другие инструменты, требуемые репозиторием.
• Поддерживаемый MCP-хост, например Codex, Claude Code, Cursor или OpenCode.
• Обычный доступ на чтение и запись к целевому репозиторию.

AOCI-CODE интегрируется с MCP-хостом, а не с API провайдера модели. DeepSeek и другие модели могут использовать AOCI-CODE, когда агент или хост, запускающий их, поддерживает стандартный stdio MCP и может следовать контракту инструментов; одно лишь имя модели не устанавливает совместимость.

Маршрут подписанного пакета и команды проверки исполняемого файла приведены в руководстве по установке. Маршрут сборки из исходников — ниже.

Текущий RC: используйте проверенный пакет или соберите из исходников

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 — текущий кандидат в релизы. Это программное обеспечение Fair Source/source-available под лицензией FSL-1.1-MIT; см. LICENSE. Собирайте из канонического источника или используйте подписанный пакет из релиза v0.1.0-rc22 на GitHub после выполнения процедуры проверки релиза.

Подписанный бинарный файл релиза идентифицирует себя как aoci version 0.1.0-rc22. Сборка из исходников вместо этого идентифицирует точную рабочую копию и может сообщать версию разработки, например v0.1.0-rc22-1-g<short-commit> (плюс -dirty, если применимо), вместе со своим Git-коммитом. Это разные входные данные сборки, а не конфликт версий.

Чтобы скачать с помощью GitHub CLI, сначала пройдите аутентификацию, затем скачайте ресурсы помеченного релиза:

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

Для анонимного скачивания откройте страницу релиза v0.1.0-rc22 в браузере и скачайте нужные вам архив и ресурсы проверки.

Чтобы собрать из исходников, клонируйте канонический репозиторий, соберите бинарный файл и сохраните полученный путь стабильным:

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 проекта и актуальное руководство, изучает исходный код, тесты, конфигурацию и соответствующие свидетельства, а затем записывает кандидатов FRAS для каждого управляемого объекта, роль которого — index. Вам не нужно самостоятельно организовывать 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 — это репозиторий, которым он управляет. Соответствующий путь к бинарному файлу — это command в .mcp.json проекта или в эквивалентной конфигурации хоста: .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 не собирает FRAS из имён файлов, путей, расширений, AST или шаблонов и не переписывает молча то, что написала модель.

AOCI-CODE владеет управлением

AOCI-CODE отвечает за:

1. установление Safe Inventory, Managed Scope и текущего Baseline;
2. предоставление текущего Whole-Index и подтверждение его идентичности;
3. генерацию детерминированного плана, целевого набора и значений SHA-256 исходного кода;
4. проверку структуры кандидата, словаря тегов, идентичностей связей, области, владения, бюджетов и затронутого диапазона;
5. сохранение связи между содержимым проверки, diff и обзора;
6. фиксацию полного пакета с межпроцессными блокировками, CAS и атомарными записями;
7. продвижение Baseline, добавление в журнал и сохранение свидетельств восстановления после сбоя после записи;
8. повторное доказательство текущего состояния управления через Verify, Check и руководство;
9. вывод наблюдений Lineage, Relations, Impact, Snapshot и Evolution из авторитетных активов без создания второго источника истины.

Всё зелёные машинные результаты означают лишь то, что закодированные структурные контракты и контракты управления соблюдены; они не означают, что каждое утверждение, написанное моделью, верно.

Как организован индекс

Индекс AOCI имеет два слоя: правила индекса и записи индекса. Продукт поддерживает две физические компоновки, и это не один формат файла.

Компоновка Volumes v1

Проект Volumes разделяет обязанности:

• aoci.txt — это только Root. Он объявляет Volumes, участвующие в текущем CognitionSet.
• 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 записывает для нового проекта en-US с именем my-service, начиная с 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 эти правила хранятся в Meta-томе проекта; в раскладке 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/=== запись использует базовое имя:

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 

Раздел каталога и базовое имя разрешаются в идентичность кодового объекта. Для межтомовых или системных проекций она разворачивается в каноническую идентичность, такую как 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-томом или Legacy-заголовком проекта. Программа валидирует словарь и структуру; она не решает бизнес-смысл.

S — это не синопсис, не обычное резюме и не повторение F, R и A. Оно добавляет важную информацию, которую не покрывают первые три поля и которая влияет на понимание или инженерную корректность, например:

• сбой доступа к Redis должен откатываться к базе данных;
• определённая таблица не должна попадать в AutoMigrate;
• ветку совместимости с устаревшим кодом нельзя удалять при обычной очистке;
• исходный файл должен сохраняться после сбоя записи.

Модель пишет это на основе фактического исходного кода и свидетельств. AOCI-CODE валидирует структуру записи, привязывает её к исходному файлу и управляет тем, как она попадает в формальный индекс.

Чтение стартового словаря тегов

Следующий фрагмент скопирован дословно из текущего шаблона Meta-тома en-US (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 текущего проекта на основе исходного кода и принятых свидетельств.

Тома познания

AOCI-CODE поддерживает один логический Whole-Index, при этом каждый вид индекса имеет собственный файл, владение и жизненный цикл.

У каждого объекта ровно один действительный владелец. Помещение объекта в неправильный том создаёт конфликт владения. AOCI-CODE исправляет его только тогда, когда машина может доказать неверного владельца, правильного владельца и текущие факты объекта; он не угадывает владение по похожим именам.

Том Code, том Database и область могут развиваться вместе, но они разделяют одну управляемую границу коммита. Применение одного домена не должно отбрасывать существующую проекцию Baseline другого домена. Применение тома, обновление Baseline и связанные проекции области публикуются как один согласованный результат транзакции или входят в доказуемое восстановление. Они никогда не оставляют половинчатого состояния, в котором «файл успешно записан, но у другого тома нет baseline».

Интеграция с хостом

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 сохраняет уровни 0–4 для совместимости с существующими хостами и отчётами. Текущий cognition-state/v2 выражает, насколько пригодна картина системы у модели, как уровни 0–3 и отделяет строгие факты доказательства и управления в независимые измерения:

Эти измерения не заменяют друг друга. Attestation доказывает только охват доставки и согласованность идентичности для текущего материала; это не означает, что агент полностью понял каждую возможную будущую задачу. Только current_system_cognition_reliable=true допускает безоговорочное утверждение о полном понимании текущей системы.

Панель AOCI

aoci ui обслуживает панель только для чтения на этой машине, чтобы вы могли видеть состояние индекса, не спрашивая агента:

• заголовок индекса и тома Code / Database дословно (строки раздела === сохраняются как есть, фильтруются, копируются целиком); вкладка «All» — это полный индекс точно в том виде, в каком агент получает его через Overview
• токены индекса относительно бюджета и план чанков Overview
• насколько код покрыт индексом: файлы, строки, токены и коэффициент сжатия; сколько таблиц базы данных
• состояние управления и дрейф, Managed Scope, интеграции с хостами и запущенные процессы aoci mcp
• команды и промпты, которые нужно дать агенту далее, с кнопками копирования

Страница переключается между китайским и английским; интервал обновления выбирается (по умолчанию 30 с).

Несколько серверов aoci mcp в одном WSL? В Linux и WSL панель обнаруживает каждый процесс aoci mcp текущего пользователя и его репозиторий, переключается между ними вкладками вверху и помечает сервер, чей бинарный файл был заменён на диске. Границы: он привязывается только к loopback-адресам (любая другая привязка отклоняется), отвечает только на 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-схемы и значения машинного состояния, которые предоставляет запущенный бинарный файл, являются авторитетными; этот README — лишь отправная точка.

Текущий выпуск предоставляет возможности System Cognition через существующий CLI и ядро управления. Они не добавляют десятый инструмент MCP и не изменяют имена, назначение или контракт stdio существующих девяти.

Длительные сессии и доставка Whole-Index

В начале нового разговора агент обычно загружает один полный Overview, чтобы получить картину системы, соответствующую текущему репозиторию, версии индекса и идентичности сервиса AOCI. Пока модель может полагаться на эту картину, ей не нужно перезагружать её перед каждой задачей или вызовом инструмента.

В рамках одного разговора модель решает, загружать ли снова, исходя из собственного состояния, за исключением случая известного уплотнения контекста хоста. Уплотнённая передача может сохранять только идентичность квитанции, незавершённое состояние записи или восстановления и немедленную инструкцию перезагрузки; она не должна сохранять или суммировать заголовок, записи, чанки, challenge или тела аттестации Whole-Index или Overview. Содержимое индекса или квитанция, скопированные в такую передачу, не могут доказать, что текущая картина модели надёжна.

Перед продолжением деловой работы после известного уплотнения агент перезагружает правила, если они больше не присутствуют надёжно, объявляет context_compaction со свежим ID события и завершает одну обычную полную последовательность курсора, подтверждения и аттестации Overview. check_only и проверка cognition не являются заменой. После свежей полной передачи существующее правило частичной или неудачной аттестации по-прежнему допускает продолжение, привязанное к источнику, без второго автоматического 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 намеренно ограничен openGauss 6.0.5 LTS в режиме совместимости A/PG и обычными несекционированными базовыми таблицами. Неподдерживаемые возможности каталога завершаются отказом, а не молчаливо сводятся к фактам PostgreSQL; это не заявляет о поддержке MogDB, GaussDB, режима Dolphin/B/MySQL, секций или подсекций, column-store, MOT, внешних или временных таблиц, представлений, процедур или триггеров.

Здесь обнаружение с отказом применяется к выбранным видимым таблицеподобным объектам с неподдерживаемой семантикой. Процедуры и триггеры остаются вне домена табличных объектов v1 и никогда не представляются как факты таблиц.

Путь openGauss использует проверенный локальный патч AOCI поверх официального исходного кода Connector v1.0.8. Его строгий парсер принимает только проверенные параметры подключения и не использует внешние PG*, service, password-file, конфигурацию домашнего каталога или логгера. TCP-соединение за пределами числового loopback-адреса должно явно использовать sslmode=verify-full (и абсолютный путь к доверенному корню в sslrootcert, если он указан), с TLS 1.2 в качестве минимума; режимы понижения TLS отклоняются. sslmode=disable принимается только для явного Unix-сокета или числового loopback-адреса, используемого как локальная/тестовая граница. Администраторы баз данных остаются ответственными за предоставление этого DSN вне разговора и за выделение учётной записи с минимальными привилегиями.

Database Volume по умолчанию отсутствует. Он входит в Whole-Index только после того, как проект явно включает Database Cognition и завершает управление свидетельствами, привязкой и жизненным циклом.

Подключение доступа к базе данных: вам не нужно понимать детали 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 предоставляет набор производных наблюдений System Cognition. Они отвечают на такие вопросы, как «откуда произошёл этот объект?», «какие объекты кода может затронуть изменение в базе данных?» и «что изменилось между историческим наблюдением и текущим моментом?». Они не создают новый слой авторитетных фактов.

# 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

Граница полномочий

Каждый результат System Cognition сообщает derived=true; проекция отношений дополнительно сообщает authoritative=false. Cognition Volumes, привязки доказательств схемы, отпечатки Baseline и идентичности, привязанные к квитанциям, остаются нижележащими авторитетами. Неразрешённые отношения R дают неполный результат или диагностику; программа не угадывает и не заполняет их.

AOCI-CODE не является системой графа знаний. Узкая проекция отношений — это удобное представление связей, но она не владеет второй системой управления состоянием, независимым путём записи или новым хранилищем фактов. Производный вывод можно удалить и пересчитать из текущих авторитетных активов. Если проекция противоречит авторитетным активам, побеждают активы.

Режимы выполнения, приватность и границы данных

• AOCI-CODE по умолчанию работает локально: нет облачной конечной точки по умолчанию, нет хостингового сервиса загрузки исходников и нет обязательного фонового сервера.
• Обработка данных в режиме Agent-native зависит от выбранного вами хоста и его продуктовых политик; AOCI-CODE не загружает данные от имени хоста.
• Сетевой доступ к базе данных должен запускаться явно и ограничен метаданными схемы только для чтения.
• Журнал, черновики, транзакции и доказательства восстановления по умолчанию хранятся в .aoci/ и обычно игнорируются Git; файлы индекса и активы командного управления могут быть закоммичены в Git.
• Проекции System Cognition вычисляются локально из существующих авторитетных активов и не требуют графовой базы данных, векторной базы данных или удалённого графового сервиса.

Чем это отличается от карты репозитория, 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 был доставлен полностью.
• Database Cognition. Записи уровня таблиц, построенные и управляемые из явно принятых доказательств схемы PostgreSQL/MySQL/openGauss.
• Системные проекции. Наблюдения Lineage, узких Relations, Impact от базы данных к коду, Snapshot и Evolution, производные от авторитетного индекса и его привязок без дублирования авторитетного состояния; Impact обходит только явные отношения R, созданные моделью.

AOCI-CODE дополняет существующие инструменты, а не заменяет их.

Рекомендуемое сочетание: AOCI-CODE предоставляет глобальный семантический приор; графы кода, LSP, поиск и исходники предоставляют точные доказательства; тесты и результаты выполнения предоставляют окончательную приёмку. Проекция Relations в AOCI не заменяет точный граф вызовов: она раскрывает структурную вложенность Volume и рёбра зависимостей Root, а её семантические рёбра ограничены сильными связями, которые модель явно создала.

Технологический стек

AOCI-CODE не требует Neo4j, векторной базы данных, долго работающего демона или облачного сервиса AOCI. Когда Database Cognition включён, целевая база данных является лишь явным источником доказательств схемы только для чтения, а не собственным хранилищем состояния AOCI.

FAQ

Почему 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; мигрируйте Legacy-репозиторий с помощью aoci cognition migration до этого момента.

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 корректность семантики?

Нет. Зелёный результат доказывает, что закодированные структурные условия и условия управления выполняются. То, что написала модель, всё равно нужно проверять по исходному коду, схеме, тестам, результатам выполнения и человеческой проверке.

Является ли граф System Cognition новым источником истины?

Нет. Текущая возможность — это узкая проекция отношений, а не независимая графовая платформа. Она вычисляет результаты только из формального индекса, доказательств, квитанций и Baseline и не сохраняет новые авторитетные факты. Программа также не генерирует семантические отношения автоматически из импортов, SQL, имён файлов или сходства.

Документация

Ссылки на документацию и публичные контракты закреплены за v0.1.0-rc22, чтобы они оставались действительными, когда этот README читается из бинарного архива Release, который не включает каталоги репозитория docs/ или spec/public/.

Наборы проверок методом чёрного ящика

Репозиторий поставляет четыре автономных набора проверок методом чёрного ящика в scripts/blackbox/, которые проверяют собранный бинарник aoci строго извне процесса, только через публичный протокол stdio MCP и CLI:

• Соответствие протоколу — 53 проверки только на чтение поверхности MCP-протокола, с предложениями, зависящими от локали, повторёнными под zh-CN;
• Сценарии внедрения сбоев — 75 сценариев, охватывающих подмену курсора, восстановление после сбоев, гонки писателей и хук перед записью на одноразовых фикстурных репозиториях;
• Жизненный цикл на замороженных реальных проектах — три зафиксированных фикстурных проекта: repo-a (TypeScript) и repo-b (Python + MySQL) проходят полный жизненный цикл от init до ревыравнивания, а repo-c (многослойный сервис из 453 файлов) дополнительно прогоняет многопакетное авторство на машинном лимите пакетов. Необязательный трек с моделью пропускает реального ИИ-агента — любую модель, которую предоставляет ваша установка OpenCode — через два небольших репозитория и оценивает конечное состояние по публичным поверхностям.
• Ось обновления — 80 проверок на каждую выпущенную версию, по десяти формам репозитория: каждый опубликованный релиз собирает и создаёт авторский репозиторий своим собственным бинарником, затем бинарник под тестом должен управлять им, не перемещая идентичность, не требуя изменения области и не переписывая формальный актив, а то, что он затем создаёт, должно сохранять выравнивание рабочей копии по другому пути; в десятой форме роли меняются местами, и каждый опубликованный релиз должен прочитать репозиторий, записанный бинарником под тестом, без сбоев и без перезаписи. Остальные три набора создают каждую фикстуру бинарником под тестом, поэтому прообраз, изменившийся между версиями, для них невидим по построению.

Им нужны только Python 3 и git поверх собранного бинарника (Docker для набора MySQL; OpenCode плюс ваша собственная подписка на модель для трека с моделью), поэтому клон репозитория может проверить собственную сборку, порт на платформу или форк — и AOCI_BIN может направить наборы соответствия и сценариев на любой альтернативный бинарник, который заявляет публичные контракты в spec/public/. Эти наборы находятся в клоне репозитория; бинарные архивы Release их не включают. См. scripts/blackbox/README.md для команд и интерпретации результатов.

Исследования, интеллектуальная собственность и лицензия

Исследовательские работы и артефакты AOCI-CODE могут публично описывать выпущенные методы, экспериментальные протоколы и результаты. Патентные заявки, предоставленный объём прав, юридический статус, владельцы и территориальное действие являются юридическими фактами, и их не следует добавлять в описания продукта на основании внутреннего README, исторического номера версии или непроверенного пересказа.

Если в будущем потребуется раскрыть конкретный номер патента, дату выдачи или объём прав, правообладатель и юридический консультант должны проверить это по официальным публичным реестрам и разместить в отдельном документе об интеллектуальной собственности, NOTICE или юридическом документе. Этот README должен лишь ссылаться на этот авторитетный файл; он не должен ни сам расширять патентное покрытие, ни представлять патентный статус как программную лицензию.

Сообщество

Отсканируйте код с помощью WeChat или WeCom (企业微信), чтобы присоединиться к проектной группе AOCI и поговорить с сопровождающими и другими пользователями. Сообщайте об ошибках и запросах на функции как о GitHub issues, чтобы они оставались доступными для поиска, а о предполагаемых уязвимостях сообщайте приватно, как описано в SECURITY.md, никогда в группе.

AOCI-CODE — это не про то, чтобы агент видел больше кода. Он даёт агенту актуальное, структурированное, прослеживаемое и управляемое понимание системы перед каждым действием. Git версионирует ваш код, миграции базы данных версионируют ваши структуры данных, а AOCI-CODE версионирует то, что агенты знают о системе, вместе с прослеживаемостью, согласованностью управления и границами восстановления того, как это знание развивается.