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

Гарантия цели

Статус: актуально Область: проверки приёмки цели и свежесть источников Последняя проверка: 2026-09-14 Владелец: сопровождающие среды выполнения AX Code

Планы изменений кода, которые порождает планировщик цели, объявляют исполнимые проверки приёмки. Каждая проверка называет исход, который покрывает, точную команду, назначение и задуманное окружение. AX Code записывает свидетельства выполнения, когда агент запускает verify_project с идентификатором goalCheck этой проверки.

{ "goalCheck": "invoice-parity" }

Команда берётся из замороженного плана цели. Через этот вызов агент не может заменить её другой командой. Существующие разрешения bash по-прежнему применяются. Завершение цели требует, чтобы последняя попытка каждой объявленной проверки прошла с совпадающими целью, сессией, рабочей областью, контрактом и содержимым источников. Проза приёмки объясняет результат; она не заменяет выполненные проверки. Обычные запуски оболочки и проверки, которые были целиком пропущены, не могут дать это свидетельство.

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

Подготовка проекта миграции

Дайте авторитетный устаревший источник или экспорт с идентификаторами ревизий, ограниченный инвентарь покрытия и скрипты проверок, которые завершаются ошибкой, когда утверждения нельзя проверить. Комментарии и более ранние реализации миграции считайте зацепками для исследования. Записывайте одобренные изменения поведения отдельно от требований паритета с устаревшей системой.

Выбирайте проверки для слоёв, которые запрошенное изменение действительно затрагивает:

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

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

Что записывает план

Планировщик даёт объект assurance. Этот пояснительный фрагмент предполагает, что у проекта есть упомянутый экспорт источника и скрипт проверки:

{
  "version": 1,
  "sourcePaths": ["src", "checks", "package.json"],
  "sources": [
    { "role": "legacy", "reference": "legacy/invoice-schema.sql at export-v1" },
    { "role": "requirement", "reference": "Invoice acceptance criteria supplied by the user" }
  ],
  "checks": [
    {
      "id": "invoice-parity",
      "acceptanceIds": ["AC1"],
      "command": "node checks/invoice-parity.cjs",
      "purpose": "Assert invoice behavior, database mappings and target identity",
      "environment": "Staging migration target, schema ERP"
    }
  ]
}

Все идентификаторы приёмки должны быть покрыты. Команды выполняются из корня рабочей области. Объект гарантии замораживается вместе с контрактом приёмки. Агент получает проверенную область, ссылки на источники, идентификаторы проверок и объявленные цели в продолжающемся контексте цели. Отсутствующие или изменённые контракты дают уведомление о восстановлении. Порождённые сводки разговора остаются подверженными ошибкам; объявленные ссылки и подписи целей — требования, а не независимо наблюдённые факты.

Диапазоны Git, которые меряют, что изменила эта цель, должны использовать {BASELINE} как состояние «до». Планировщик переписывает этот заполнитель в SHA HEAD, снятый в момент отправки плана, чтобы уже существующие коммиты впереди origin/main или грязное рабочее дерево не сделали цель незавершаемой. Ссылки отслеживания удалённого репозитория (origin/main, @{u}, refs/remotes/…) отвергаются как это состояние «до», если цель не называет удалённый репозиторий. Уже разошедшиеся или грязные пути запишите в риски; не замораживайте запирающую проверку, которая уже падает, если цель не в том, чтобы исправить этот сбой.

Свежесть и пределы

Отпечатки источников Git включают фактические байты отслеживаемых и неотслеживаемых, но не игнорируемых файлов внутри объявленного sourcePaths. Явные пути файлов также включают игнорируемые файлы конфигурации; пути каталогов сохраняют правила игнорирования Git. Изменяемые контрольные списки плана цели исключены; их замороженные требования проверяются через дайджест контракта. Проекты не на Git рекурсивно снимают отпечаток объявленного sourcePaths, включая отсутствующие пути. Включите в эту область каждый относящийся источник, файл конфигурации и скрипт проверки.

Снятие отпечатка ограничено 20 000 записей и 128 МиБ содержимого файлов. Связанный источник, вложенные репозитории Git, специальные файлы, ускользающие пути, меняющиеся файлы и недоступные чтения не могут дать свежее свидетельство. Такие сбои блокируют гарантированное завершение. Артефакты вывода проверки следует класть в игнорируемое место, чтобы порождение отчёта не меняло проверяемый источник.

Игнорируемые файлы, не названные явно, зависимости вне области источников, базы данных и развёртывания нуждаются в утверждениях в команде проекта. Квитанция записывает наблюдение в момент выполнения; она не доказывает, что внешнее состояние осталось неизменным. Перезапустите затронутые проверки после изменения конфигурации, баз данных или развёртываний. AX Code не обнаруживает автоматически всё устаревшее поведение и не удостоверяет паритет миграции.

Когда выполняется планирование

Планирование включается по согласию на обеих поверхностях. /goal <objective> и create_goal без assure запускают цель сразу: замороженных критериев приёмки нет, а завершение судится по рабочему плану (ожидающие дела) плюс успешная проверка после последнего изменения. /goal --assure <objective> и create_goal с assure: true сначала запускают автора плана, и именно это делает квитанции выполненных проверок ниже требованием завершения.

Цель без контракта говорит об этом везде, где показана (/goal view, диалог цели, управляющие сообщения), поэтому её шлюз завершения никогда не нужно выводить самому. /goal replace сохраняет гарантию, когда у заменяемой цели есть действительный контракт.

Контекст планирования и выбор модели

Планирование цели наследует выбранную модель сессии и через /goal, и через инструмент create_goal. Совместимые варианты вызывающей стороны сохраняются. Автор только для чтения получает недавние исходные требования пользователя и ссылки на вложения, с бюджетом записи 16 КиБ. Слишком большая запись останавливает включение более старых записей, с уведомлением, чтобы старые требования не могли молча заменить опущенное исправление; встроенное содержимое медиа не считается осмотренным свидетельством. Для требований, которые есть только в медиа, дайте файлы источников, которые можно осмотреть.

Прогресс и блокировки

get_goal включает текущий статус проверки (пройдена, не пройдена, устарела, выполняется или отсутствует) и недавние идентификаторы свидетельств инструментов. Шлюз завершения всё ещё требует текущих успешных квитанций. Заблокированное обновление требует вида блокировки, причины, требуемого внешнего изменения, идентификаторов исходных свидетельств и подтверждения, что независимой работы не осталось. Причины блокировки — объявления модели, опирающиеся на осматриваемые записи, а не удостоверение, что внешняя служба остаётся недоступной.

Завершённые ходы, которые повторно не дают новых успешных свидетельств инструментов, получают указание восстановления, затем ставят цель на паузу с раскрытой незавершённой работой. Новые результаты исследования могут считаться без правок источников; переписывание дел и повтор одинаковых результатов не считаются. Это ограниченная эвристика, а не доказательство смыслового прогресса. /goal resume начинает ещё одну попытку. Вызовы инструментов, порождённые для более ранней цели, не могут завершить её замену. Цель, созданная инструментом, доступна обновлениям статуса после того, как модель получила результат создания на следующем шаге.

Пересмотр существующего плана

Используйте /goal revise <correction>, чтобы явно пересмотреть активную, поставленную на паузу или заблокированную замороженную цель. Завершённая работа и исчерпанные бюджеты требуют новой цели. Прежний план и дайджест остаются целыми. Пересмотренный план получает свежую личность и локальную запись подготовленного пересмотра, связывающую оба дайджеста и исправление. Текущая личность цели определяет, какой кандидат действительно установлен; неудачные одновременные кандидаты могут остаться на диске для осмотра. Старые квитанции остаются в истории и не могут удовлетворить новый пересмотр. Бюджет токенов и накопленное использование переносятся; пересмотр не даёт свежего бюджета расходов.

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

Результаты рецензии и поздние изменения источников

Непустой журнал рецензии не устанавливает успешную рецензию. Для требуемых внешних рецензентов используйте проверку, которой владеет проект: она проверяет фактический код выхода, терминальное завершение, личность источника или diff и итоговые находки либо явный вердикт об отсутствии находок. Журналы только с предупреждениями, частичное рассуждение и тайм-ауты должны завершаться ошибкой. Неудачные попытки храните отдельно для диагностики.

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

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

Вывод проверки и контрольные точки цели раскрывают дополнительные пути. Если замороженная команда теста опускает нужные регрессии, запросите /goal revise <correction> и выполните пересмотренные проверки. Включение файла в отпечаток доказывает свежесть, а не то, что тест затронул этот файл. Предпочитайте ограниченные каталоги источников и команды тестов, которые включают новые регрессии, когда планируете открытый поиск дефектов.

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

Свидетельства области коммита

Непустой git log <baseline>..HEAD -- <paths> доказывает только, что коммит совпадает с фильтром. Он не исключает посторонние файлы в этом коммите или другие коммиты. Новые планы изменений кода отвергают распознанные самостоятельные непустые утверждения журнала Git с фильтром пути; более старые замороженные проверки получают указание пересмотра без изменения их дайджеста или проверки во время чтения.

Используйте проверяющий код, которым владеет проект: он проверяет предков базовой линии, требует непустой диапазон и осматривает каждый изменённый путь в каждом коммите без фильтров пути. Включите удалённые файлы и обе стороны переименований, явно обрабатывайте коммиты слияния и отдельно проверяйте требуемые свойства ветви или сообщения. Используйте /goal revise, чтобы усилить существующий контракт; не правьте замороженные требования.

Размер плана и полная повторная отправка

Отрисованный план, включая Markdown и JSON гарантии, должен уместиться в 8 192 байта UTF-8. Цельтесь ниже 7 168 байт. Если отправка превышает потолок, сократите повторяющуюся прозу и отправьте полный объект заново, включая kind и все требуемые поля. Сохраните идентификаторы и проверки приёмки; среда выполнения не обрезает требования и не поднимает предел читателя, чтобы принять слишком большой план.

Квитанции рецензии анимации локального CLI

packages/ax-code/script/verify-cli-review-receipts.ts, которым владеет репозиторий, проверяет артефакты round-* под корнем квитанций, выбранным через --root. Каждому раунду нужен revision.txt, а каждому из grok, claude и codex нужен exit.txt с 0 и одним итоговым вердиктом в stdout.jsonl (текстовые события Grok) или stdout.txt (Claude/Codex). Неудачные попытки храните вне каталогов завершённых раундов; не превращайте сбои в квитанции с нулевым кодом выхода.

dispositions.json содержит массив findings. Каждая запись называет round, cli, id, status (fixed или rejected) и непустой evidence. Фиксированные записи дополнительно требуют объект regression с буквальным путём репозитория file под packages/ax-code/test/cli/tui/ и точным fullName Vitest. Повторные расположения или неоднозначные множественные вердикты завершаются ошибкой.

Проверяющий код запускает эти файлы установленным Vitest с глобальным повтором по умолчанию, равным нулю (параметры отдельного теста могут перекрыть это значение), затем проверяет, что каждое упомянутое утверждение прошло ровно один раз. Отсутствующие, пропущенные, неудачные или неоднозначные утверждения проваливают проверку. Это доказывает, что упомянутые тесты прошли, а не то, что их утверждения по смыслу покрывают находку. Отвергнутые расположения остаются записанными суждениями. Итоговый раунд должен совпадать с текущим HEAD; находки, помеченные исправленными, требуют более новой ревизии и раунда рецензии. Незафиксированные изменения исходников, тестов или конфигурации основного пакета не дают пройти проверку. Держите постороннюю локальную конфигурацию ax-code.json вне коммитов.

Для этого репозитория vitest run --dir test/cli/tui сохраняет исключения обычной дорожки, сканируя каталог TUI. Групповые запускатели всё ещё могут выбрать точные файлы через AX_TEST_FILES; выбор каталога не отключает исключения.