Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Вики репозитория AX Wiki

Статус: действует
Область: текущее состояние
Последняя проверка: 2026-10-03 Владелец: среда выполнения AX Code

AX Wiki — собственный компилятор вики репозитория в AX Code. Он превращает отслеживаемый исходный код, конфигурацию, тесты, рабочие процессы и уже существующую документацию в небольшую базу знаний Markdown с опорой на исходники в .ax-wiki/. Он использует ту же конфигурацию провайдера и маршрутизацию моделей, что и AX Code. Отдельного исполняемого файла и хранилища учётных данных нет.

ax-code wiki viz рисует скомпилированные страницы и файлы, которые они цитируют. Скриншоты этой карты — в визуализации свидетельств Wiki.

Где это уместно

Проза вики — скомпилированный слой навигации, а не структурное доказательство. Если вики расходится с кодом, верьте коду и выполните ax-code wiki update.

Быстрый старт

Подключите провайдера AX Code, затем выполните:

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki порождает AGENTS.md, вставляет блок указателя AX Wiki и компилирует вики одним рабочим процессом. Используйте --wiki-only-agents, чтобы добавить указатели без вызовов модели.

Команды

Параметры генерации включают --model provider/model, --dir <relative>, --quiet, --skip-agents и --force. --force намеренно обязателен, чтобы заменить порождённое содержимое, вручную изменённое вне защищённых разделов.

Каталог репозитория

С v7.22.2 каталог вывода по умолчанию — .ax-wiki/. Скрытый префикс обозначает знание репозитория, которое ведёт AX Code. Файлы из-за него не игнорируются Git: решите, фиксировать ли это знание, или добавьте /.ax-wiki/ в .gitignore репозитория.

Используйте wiki.dir в ax-code.json или --dir docs/knowledge, чтобы выбрать другой относительный каталог. Флаг CLI важнее. Вся генерация, статус, указатели агента, фоновое обслуживание и визуализация используют этот выбор. Компилятор сам не обнаруживает, не переносит и не сливает более старый каталог ax-wiki/. Имена пакета и генератора, ax-wiki.config.json и ax-wiki.instructions.md не меняются.

Порождённый контракт

AX Wiki пишет страницы Markdown и .ax-wiki/.manifest.json. У каждой страницы есть frontmatter, содержащий:

• generated_by: ax-wiki
• краткий summary
• точные symbols, возвращённые генерацией с опорой на свидетельства
• относительный к репозиторию sources, которым компилировалась страница

Манифест хранит хеш детерминированного плана, хеши исходников репозитория, хеши страниц, модель генерации, ревизию git и время генерации. Страницы пишутся атомарно. Манифест пишется последним и только после того, как полный кандидат в памяти проходит валидацию.

Обнаружение исходников предпочитает список отслеживаемых и не игнорируемых файлов Git, исключает каталоги порождения, сборки, вендоров и саму вики, пропускает двоичные и слишком большие файлы и отвергает пути и символические ссылки вне репозитория.

Навигация по подсистемам

План по умолчанию сохраняет страницы быстрого старта, архитектуры и разработки. Модуль, который превышает бюджет числа исходников или байтов свидетельств одной страницы, может также получить узкие страницы вроде modules/core/src/session.md. Эти страницы покрывают прямые подкаталоги в каталоге модуля src, lib или app, при не менее трёх файлах кода на подсистему и двух подходящих подсистемах в модуле.

Страницы подсистем включают своё поддерево реализации и совпадающие файлы в каталоге модуля test или tests. Их инструкции генерации запрашивают точки входа, поток среды выполнения, границы, конкретные места изменений и относящиеся тесты. Страницы модулей ставят до двух тестовых файлов сразу после исходника с наивысшим рангом, чтобы тесты могли участвовать в ограниченном отборе свидетельств.

Общий бюджет по умолчанию остаётся 12 страницами, включая три обзорные. Обзоры модулей и страницы подсистем соревнуются за оставшиеся слоты по числу исходников. Подсистема включается только после обзора своего родителя. Более крупные подсистемы могут поэтому вытеснить меньшие страницы пакетов. Предпросмотр результата — через ax-code wiki plan. Увеличьте maxPages (до 40 для автоматических планов) или настройте явные pages, когда конкретной подсистеме нужно гарантированное покрытие. Явные планы остаются авторитетными и не получают автоматических страниц подсистем.

Это улучшает навигацию и фокус свидетельств. Порождённую прозу это не проверяет и не гарантирует, что агент прочитает вики. Прежде чем опираться на детали реализации, идите по цитатам к текущему исходному коду.

Как агенты пользуются вики

Агенты доходят до вики тремя путями, от самого дешёвого к самому точному:

1. Индекс в промпте. Когда есть здоровая вики, промпт сеанса несёт короткий блок <repo_wiki>: расположение вики, метку свежести и одну строку на страницу (путь и обрезанная сводка, около 750 токенов для 12 страниц по умолчанию). Сводки лишь указывают, где читать. Они не доказательство.
2. Инструмент repo_wiki. Инструмент только для чтения с тремя операциями: index (карточки страниц со свежестью каждой), read (одна страница плюс цитируемые исходники, какие из них изменились и какие символы frontmatter в этих исходниках не найдены) и related (страницы для символа, упоминания в теле или пути исходника). Он доступен в полных профилях и профилях написания кода и использует право read.
3. Обычные файловые инструменты. read, glob и grep по .ax-wiki/ всё ещё работают.

Свежесть промпта судится по страницам: страница свежа, пока каждый цитируемый ею исходник всё ещё совпадает с хешем манифеста. Добавленный или изменённый файл, который не цитирует ни одна страница, оставляет метку промпта fresh и добавляет замечание, что вики его ещё не покрывает. Изменённый цитируемый исходник помечает метку stale, и промпт просит агента считать вики только навигацией. ax-code wiki status и wiki lint держат более строгий вердикт на весь репозиторий, где любой добавленный, удалённый или изменённый подходящий файл делает вики устаревшей.

Вики никогда не заменяет исходный код: каждый результат read перечисляет файлы для сверки, и если страница и код расходятся, побеждает код.

Пошаговые обновления и ручное содержимое

wiki update сравнивает текущие хеши исходников с манифестом и проводит изменения через селекторы каждой страницы. Смена плана заново порождает все запланированные страницы. Иначе несвязанные страницы не трогаются.

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

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

Защищённые тела переживают регенерацию. AX Wiki отказывается перезаписывать другие ручные правки, если не задан --force. Устаревшие порождённые страницы удаляются, только если их управляемое содержимое не менялось и в них нет защищённого раздела.

Конфигурация

Настройте интеграцию в проектном ax-code.json:

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include, exclude, maxSourceBytes и maxPageSourceBytes управляют обнаружением свидетельств и бюджетами. instructions добавляет указания компилятору, специфичные для проекта. Для полностью отобранного плана настройте записи pages с path, title, purpose и selectors. Явный план должен включать quickstart.md.

generationConcurrency принимает 1 или 2. Собственная облачная генерация по умолчанию делает два одновременных вызова страниц. Локальные движки и провайдеры CLI по умолчанию делают один. Задайте 1, когда провайдер ставит в очередь или ограничивает перекрывающиеся запросы. Планирование не делает недействительным уже существующее содержимое страниц. Повторно используемый пакет остаётся последовательным, если эта настройка не задана.

Каждая страница модели получает не больше двух классифицированных попыток с общим сроком 180 секунд. Относительные ссылки Wiki проверяются по плану страниц до принятия страницы. Ответ со сломанной ссылкой может использовать оставшуюся попытку, чтобы починить эту страницу. Итоговая валидация и защита ручного содержимого всё ещё выполняются до публикации.

Прерванные сборки удерживают проверенные результаты в .ax-wiki/.page-cache/ (или в настроенном каталоге Wiki). Более поздняя сборка повторно использует совпавшие результаты только после проверки текущих свидетельств исходников, плана, генератора, модели и прежнего содержимого. Начальная генерация остаётся неопубликованной, пока полный кандидат не пройдёт валидацию. Успешная публикация удаляет потреблённые записи подготовки. Последующий явный wiki generate всё ещё заново порождает все страницы. Записи кэша ограничены и закрыты правами. Повреждённые или недоступные записи игнорируются.

.build-report.json отличает страницы, порождённые моделью и взятые из кэша, от страниц written, которые действительно опубликованы. Его необязательный массив pages записывает попытки каждой страницы, длительность, размеры промпта и исходников в байтах и точный расход токенов, когда его даёт провайдер. Неуспешные или отменённые сборки не сообщают опубликованных страниц.

Указания компилятору можно также поместить в ax-wiki.instructions.md, а конфигурацию ядра движка — в ax-wiki.config.json. Явные настройки среды выполнения AX Code переопределяют конфигурацию ядра там, где заданы обе.

Интерактивное обслуживание по умолчанию

Открытие проекта в TUI AX Code по умолчанию включает фоновое обслуживание Wiki. После 30 секунд простоя проекта недостающие артефакты порождаются, а устаревшие обновляются по шагам. Занятые и повторяющие сеансы, работа в очереди и непустой черновик имеют приоритет и отменяют фоновую генерацию. Действуют права чтения и записи текущего агента. Агенты только для чтения не порождают. Этот фоновый процесс не переписывает файлы инструкций агента.

Используйте "wiki": { "auto": false }, чтобы отключить фоновое обслуживание, или enabled: false, чтобы отключить компиляцию и внедрение в промпт. auto по умолчанию истинен и не пишет конфигурацию. Он использует настроенную модель Wiki или модель AX Code по умолчанию, срок задания 10 минут и до трёх автоматических попыток с нарастающей паузой. Явный запрос графа или смена исходников либо конфигурации разрешает ещё одну попытку. Неинтерактивные прогоны и CI интерактивный планировщик не включают. Каталогам не-Git нужен явный запрос. В проектах Git генерация и потребление Wiki используют ближайший корень рабочего дерева, поэтому открытие AX Code в пакете не создаёт отдельную вики пакета.

Боковая панель сеанса и /wiki-viz сразу открывают локальную страницу хода и запрашивают обслуживание. Когда снимок готов, эта страница показывает записанные связи страниц Wiki и исходников. См. визуализацию Wiki.

Маршрутизация агента

Когда есть здоровая вики и wiki.enabled не равен false, промпты сеанса получают компактный протокол <repo_wiki>. Он велит агентам начинать с быстрого старта, загружать только нужные страницы, проверять важные утверждения по цитируемым файлам и использовать инструменты графа и LSP для структурных вопросов.

healthy описывает наличие каталога вики, индекса и манифеста. Отдельное поле freshness равно fresh, stale или unknown. Статус и маршрутизация сеанса сравнивают текущие хеши исходников с действующими настройками включения, исключения и размера, поэтому обнаруживаются незафиксированные правки, добавления и удаления. Проверки не используют закэшированный вердикт свежести повторно. Они сканируют подходящие исходники с ограниченной параллельностью чтения. Отсутствующие или отключённые вики избегают сканирования исходников. Свежесть — это проверка исходников в момент времени, а не валидация каждого порождённого утверждения или страницы. Для валидации артефактов используйте lint.

Устаревшие или непроверенные вики остаются доступны для навигации, с явной инструкцией сверить текущий оригинальный исходный код, прежде чем опираться на утверждения о реализации. Ошибки проверки дают unknown. wiki status завершается с кодом 0, когда каталога вики нет (отчёт — это отсутствующая вики). Когда вики есть, команда завершается неуспешно, если вики нездорова или свежесть не равна fresh.

Свидетельства вики ограничены: каждый выбранный исходник даёт не больше своих первых 32 000 байт в бюджете страницы, а усечение помечается для генератора. GraphContext может добавить выбранные фрагменты, но каждый фрагмент ограничен 80 строками. Эти средства навигации не гарантируют сохранение каждой изменённой функции или нужной защиты. Для рецензии с ограниченной областью передайте необходимый оригинальный код отдельно.

Управляемый блок <!-- AX-WIKI:START --> в AGENTS.md несёт ту же политику маршрутизации, не копируя содержимое вики в инструкции репозитория.

CI

Выполните ax-code wiki update, затем ax-code wiki lint в задании с аутентификацией провайдера и откройте запрос на изменение документации. См. examples/ax-wiki-update.yml. Относитесь к порождённым изменениям вики как к прочей документации: рецензируйте цитаты исходников и не сливайте вывод модели автоматически.

Устранение неполадок