inkcheck

Механическое QA для историй ink. Проверки компиляции, ограниченное систематическое исследование ветвлений, пути воспроизведения ошибок времени выполнения и обнаружение мёртвого контента — как автономный CLI для писателей и команд, с опциональной интеграцией в CI и MCP.

Агенты начинают здесь → SKILL.md — когда вызывать этот инструмент, рабочие примеры, MUST/MUST NOT. Семейный контракт: FAMILY.md.

inkcheck — это инструмент QA, а не инструмент для написания текстов. Он не генерирует, не переписывает и не отправляет ни слова прозы. Он существует для того, чтобы историю, которую вы написали, можно было проверить механически: скомпилировать её официальным компилятором ink, исследовать пути выбора в явных пределах и воспроизводить сбои до того, как их найдёт игрок.

Использует ли он ИИ?

Нет. Сам inkcheck не использует ИИ, машинное обучение, LLM или генеративные модели для тестирования историй. Он не обучается на вашем исходном коде, не делает выводов об изменениях прозы, не переписывает текст истории и не отправляет содержимое истории в ИИ-сервис.

Он спроектирован так, чтобы люди, системы CI и опциональные ИИ-агенты могли управлять одними и теми же механическими проверками QA. Фактическая проверка — это детерминированный код: официальный компилятор ink, среда выполнения ink, ограниченное исследование ветвлений и структурированные отчёты.

Related MCP server: RenForge MCP

Попробуйте за две минуты

С Node.js 18 или новее:

npx -y inkcheck path/to/main.ink

Хотите увидеть отчёт о путях сбоев, прежде чем пробовать свою историю? Запустите двухминутное синтетическое демо.

Обещание продукта

Inkcheck — это ограниченное механическое QA для историй ink. Он не доказывает, что каждый путь работает в большой истории. Он детерминированно исследует достижимые состояния истории в явных пределах, сообщает точные пути воспроизведения для найденных проблем и показывает, где — и почему — покрытие было частичным, чтобы авторы могли использовать его как дешёвую, повторяемую страховку от регрессий.

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

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

Это проект QA с открытым исходным кодом, потому что эта граница важна. Если отчёт завышает результаты, пропускает очевидный паттерн, нуждается в лучшей стратегии обхода или не работает на форме истории, которой вы можете безопасно поделиться, пожалуйста, принесите фикстуру или issue. Дорожная карта направлена на то, чтобы сделать частичное покрытие более прозрачным и более ценным, а не на то, чтобы притворяться, что частичное покрытие становится доказательством.

Направление продукта и самооценка

Будущая ценность inkcheck планируется как воспроизводимый гибрид: широкие посевные пробы, систематическое локальное исследование, ограниченный поиск разнообразия и специалисты, знающие Ink, для гейтов, циклов, утверждений и доступности сторилетов. Специалисты должны оставаться ограниченными и зарабатывать больше работы через новые доказательства портфеля, потому что они тоже могут стать ловушками бюджета.

Та же сделка применима к оборудованию. Локальный CLI и одноразовые проверки портфеля MCP по умолчанию используют детерминированный живой пилот на 1 024 состояния, который держит небольшие, ограниченные по глубине и насыщенные авторским фронтом задания последовательными и активирует ограниченных воркеров только для открытого устойчивого фронта. Каждое состояние пилота учитывается в исходном глобальном пределе; поиск не перезапускается для принятия решения. Сопоставленная оценка сохранила точные доказательства и улучшила один запуск The Intercept с 5M состояний и глубиной 100 на 25,6%, в то время как ограниченные и размещённые задания сохраняют явные последовательные пределы. См. оценку конкурентности.

Это отдельные оценки, а не среднее. Высокая оценка доверия не может компенсировать потерянную ошибку времени выполнения. Подробный табель оценок продукта и инженерных истин определяет каждую цель 10/10, текущие доказательства, инженерные ограничения и протокол переоценки, используемый на каждом эпике или релизе. Первая полная оценка продвижения политики v2 оставляет динамическое распределение экспериментальным, а не превращает смешанные доказательства в заявление о запуске.

Область inkcheck 0.6

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

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

Inkcheck 0.7: Правила, которые имеют значение

Inkcheck 0.7 делает объявленные автором инварианты первоклассными в размещённом чекере, а также в локальной конфигурации, CI и MCP. Писатель может добавить одно опциональное числовое правило, например gold >= 0, в веб-потоке; оно показывается на простом языке и генерирует типизированную конфигурацию до запуска, проверяется во время обычного ограниченного QA и сообщается с точным свидетелем воспроизведения при нарушении. Веб-поток обнаруживает объявленные переменные Ink для помощи в выборе, но сервер остаётся авторитетным: неизвестные переменные, недопустимые типы и неподдерживаемая грамматика приводят к сбою до исследования; временная конфигурация правил удаляется вместе с загрузкой. Агенты могут черновик типизированных предложений правил, но не могут молча авторизовать их. Версия 0.7.2 также добавляет приватные пины доказательств QA: одобренный свидетель времени выполнения, утверждения или цели может быть перепроверен после редактирования без нового поиска, в то время как свежий ограниченный запуск остаётся необходимым для широкой проверки.

Отдельный специалист, направленный на утверждения, остаётся опциональным и экспериментальным. Он не получает бюджет по умолчанию, не меняет табель оценок и не претендует на лучшее покрытие, пока не пройдёт свой предварительно зарегистрированный гейт доказательств. Контракт Rules That Matter определяет обе границы.

Политики кампаний агентов

Агенты MCP могут начать долговременную кампанию с высокоуровневым режимом quick, balanced, deep, overnight или campaign вместо изобретения весов исследователя. balanced — это значение по умолчанию для новых агентов; fixed сохраняет явные устаревшие элементы управления. Ограниченные переопределения могут изменить позицию состояния/окна/времени/памяти/диска/дедлайна, скудные/сбалансированные/обильные ресурсы, предпочтительную ценность (broad_qa, runtime_assertions, outcomes или approved_goals), защищённую длиннохвостовую работу и остановку ceilings против knee. Точные базовые окна остаются свободными от утверждений и целей и возобновляемыми. Защищённые длиннохвостовые выделения теперь запускают детерминированные дочерние элементы портфеля, начинающиеся с корня, с альтернативным сидом поиска и более глубокой границей, сохраняя точную базовую контрольную точку. Кампания runtime_assertions может добавить проверенные окна утверждений с помощью add_assertions; кампания approved_goals может добавить проверенную цель с помощью add_goal. Каждый дочерний элемент использует явный грант, сохраняет отдельный отчёт о доказательствах и получает кредит только за новые для кампании критические, интентные, авторские узлы или терминальные доказательства.

Первая оценка дочерних элементов кампании на авторских историях нашла один правдоподобный лид по устаревшей переменной и одну отклонённую гипотезу утверждения на The Intercept. Его поэтапная цель не удалась, оба высокобюджетных дочерних элемента остановились на памяти до 5M, а общая база 500K превысила лимит компактной контрольной точки. Это многообещающая ценность утверждений плюс явное предупреждение: правила, созданные агентом, нуждаются в проверке человеком, специалистам нужна экономика от пробы к расширению, а компактные контрольные точки необходимы, прежде чем большие кампании станут рутинными.

Сопоставленная независимая длиннохвостовая оценка затем сравнила растущий общий фронт с защищёнными разделами портфеля, начинающимися с корня. В кампании 5M Intercept общая ветвь остановилась на памяти на 786 559 общих состояниях; девять независимых дочерних элементов завершили все 5M при более низком пиковом heap и зачислили 3 558 новых терминальных вариантов кампании против 407. Они не нашли новых критических проблем, авторских узлов или видимых концовок. Это доказательство ресурсоэффективного разнообразия и измеримой убывающей отдачи, а не универсальное утверждение ценности QA.

Последующий трёхсемейный гейт продвижения 0.6 не продвинул динамическую остановку или расширение. Dog Ink Adventure и Heresy II оба достигли ресурсного потолка, прежде чем их база 500K произвела возобновляемую контрольную точку, поэтому никакая длиннохвостовая политика не могла действовать. На The Intercept независимые разделы достигли 4,66M состояний при 1,40 ГиБ пикового heap, в то время как растущий фронт остановился на 787K состояний и 3,70 ГиБ; повторное открытие терминалов выросло с 34% до 94%, без новых критических проблем, авторских узлов или видимых исходов. Inkcheck оставляет эти рекомендации только в теневом режиме и рассматривает динамический размер первого окна как более сильное следующее требование продукта.

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

После завершения независимых дочерних прогонов компактное решение также включает версионированную теневую рекомендацию для длинного хвоста: расширить то же семейство, переключиться на другой раздел или остановиться после защищённого минимума. Оно использует значение campaign-new при выбранном предпочтении, сообщает недавнюю доходность по состоянию и секунде, требует прогрессивно больше сухих проб для скудных/сбалансированных/обильных позиций и раскрывает компактное повторное обнаружение выбранного значения плюс фактические пробелы обнаружения в рамках отчёта. Старые реестры помечают эти сигналы как недоступные. Повторное обнаружение — это пересечение идентичностей с более ранними отчётами кампании, а не сырая работа с дублирующими состояниями; расширяющиеся пробелы — это наблюдения, а не доказательство плато. liveEffect: false означает, что эти данные пока не могут изменить распределение.

Люди могут использовать ту же долговечную политику, не изучая её элементы управления: inkcheck campaign story.ink запускает сбалансированное намерение, а --mode quick, deep или overnight выбирает позицию «результат-и-время». Он возвращает неизменяемые привязанные к источнику окна результатов по мере выполнения работы, сохраняет последний частичный отчёт при завершении по сроку или отмене между окнами и оставляет технические потолки состояния/времени/памяти/диска доступными как экспертные переопределения. Окна результатов разделяют затраченную работу, практическую доходность, неопределённость прогноза и возможность продолжения поиска. Тихий интервал обнаружения или наблюдаемое колено никогда не описываются как полное покрытие.

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

С Node.js 18 или новее:

npx -y inkcheck path/to/main.ink

Глобальная установка не требуется. При первом запуске загружается закреплённый официальный компилятор ink, проверяется его SHA-256 хэш, и история обрабатывается локально.

Конфигурация проекта

Зафиксируйте inkcheck.yml, когда проект должен использовать одну и ту же точку входа и ограниченные настройки CI для каждой сессии человека или агента:

schemaVersion: 1
entrypoint: story.ink
ci:
  maxDepth: 100
  maxStates: 1000000
  goalMaxStates: 250000
  seed: 1
  storySeed: 1
  search: portfolio
  concurrency: auto
  strict: true
assertions:
  - id: gold_nonnegative
    description: Gold never goes negative
    when: always
    condition:
      left: { variable: gold }
      operator: ">="
      right: { literal: 0 }
goals:
  - id: depleted_gold
    description: Seek paths where the player runs out of gold
    condition:
      left: { variable: gold }
      operator: "<="
      right: { literal: 0 }

Запустите inkcheck validate-config для проверки. Из этого каталога inkcheck использует настроенную точку входа и значения по умолчанию; явные флаги CLI по-прежнему имеют приоритет. Неизвестные ключи приводят к ошибке валидации, поэтому неподдерживаемое внешнее поведение и поля политики редактирования не могут выглядеть реализованными. Опубликованный контракт — схема конфигурации v1.

Утверждения — это типизированные данные, никогда не JavaScript и не произвольные выражения Ink. Операнды — это переменные или скалярные литералы; сравнения используют ==, !=, <, <=, > или >=, а условия могут комбинироваться с помощью all, any и not. Правила выполняются всегда, в терминальных состояниях или при входе в именованный узел. Неизвестные переменные/узлы и некорректные сравнения между типами приводят к сбою до того, как исследование исчерпает свой бюджет состояний. Нарушение всегда приводит к сбою CI и включает наблюдаемые значения плюс точное индексированное повторяемое свидетельство. Ограниченный чистый прогон означает только «нарушение не наблюдалось»; только исчерпывающий прогон сообщает правило как исчерпывающе проверенное.

Цели используют ту же неисполняемую грамматику условий, но направляют исследование вместо сбоя CI. Общее исследование всегда получает полный бюджет maxStates. Установите goalMaxStates в конфиге или --goal-states в CLI, чтобы добавить явный детерминированный срез близости к цели; по умолчанию он равен нулю, и объединённый бюджет не может превышать 100 000 000 состояний. Цели по-прежнему наблюдаются во время обычного исследования, когда дополнительный срез не запрашивается. Достигнутая цель включает точные индексы выбора; промах сообщает not_reached_within_limits, если только исчерпывающее исследование не докажет фактическую недостижимость. Отчёты раскрывают базовый, целевой и общий бюджеты отдельно, чтобы управление не могло незаметно вытеснить общие результаты QA. См. сравнительные данные в экспериментах поиска.

Для поздней составной зависимости замените condition на два или более упорядоченных stages. Каждый этап использует ту же типизированную грамматику. Inkcheck ищет первую невыполненную совокупную веху, поэтому более поздний этап достигается только на пути, состояние которого также удовлетворяет каждому более раннему этапу. Пропущенная предпосылка оставляет более поздние этапы как blocked_by_stage; это не называет их недостижимыми. Этот первый поэтапный контракт использует один общий дополнительный бюджет целей и детерминированно перезапускается от корня истории, а не сериализует контрольные точки времени выполнения.

Для нового проекта с одним файлом .ink команда inkcheck init создаёт эту конфигурацию. Многофайловые проекты должны указать корень с помощью --entrypoint. inkcheck agent-kit --format codex добавляет конфигурацию при необходимости, пример закреплённого GitHub Actions, правила игнорирования артефактов .inkcheck/ и компактные инструкции агента, соответствующие версии. Обе команды идемпотентны и выполняют предварительную проверку каждой цели; они отказываются от всей операции, а не перезаписывают или частично изменяют существующие авторские файлы. Артефакт npm также включает канонический skills/inkcheck/SKILL.md, прогрессивные ссылки на Ink/рабочие процессы и десять исполняемых золотых упражнений. inkcheck capabilities --json рекламирует это как features.bundledAgentSkill и остаётся авторитетом для установленного контракта схемы.

--save-report атомарно сохраняет версионированный отчёт в .inkcheck/reports/ и возвращает его стабильный идентификатор, производный от содержимого и точки входа. Более поздняя сессия может использовать inkcheck artifacts list --json и inkcheck artifacts show <report-id> --json; повторное открытие сообщает, является ли сохранённое свидетельство current, stale или path_changed относительно текущей точки входа. Отчёты могут содержать текст истории, переменные и точные свидетельства, поэтому набор агента игнорирует их по умолчанию. См. локальные артефакты отчётов для контракта доверия, конфиденциальности и совместимости.

Длительные общие базовые прогоны также могут сохранять свой точный живой фронтир локально. Начните с --search=shared --no-min-repro --save-checkpoint, затем продолжите позже с inkcheck resume <checkpoint-id> --max-states N; N — это больший общий грант, а не дополнительная скрытая работа. inkcheck checkpoints list/show сообщает ограниченные метаданные, долговечный сжатый размер, кодировку хранения и свежесть источника. Новые файлы контрольных точек — это потоковые артефакты gzip; старые обычные JSON schema-v1 остаются читаемыми. Контрольные точки являются приватными, атомарными, привязанными к источнику/конфигурации, игнорируются по умолчанию и ограничены по хранению; они могут содержать авторский текст и состояние выполнения. См. локальные возобновляемые контрольные точки. Общие проходы также раскрывают ограниченный реестр наблюдаемости ресурсов/доходности, который поддерживает детерминированный логический учёт отдельно от живых наблюдений heap/RSS. Агенты MCP могут использовать тот же точный фундамент через долговечные окна результатов start_search / inspect_search / continue_search / cancel_search. Они также могут использовать add_goal для явного аддитивного направленного зонда, который начинается от корня истории и оставляет этот точный базовый фронтир нетронутым. Портфель, общие переменные, утверждения, направленное возобновление фронтира и размещённые задания пока не используют этот контракт контрольных точек.

Размещённый проверщик

Репозиторий теперь включает самостоятельно размещённый веб-интерфейс для авторов, которые не хотят использовать терминал. Размещённый режим временно загружает авторизованный исходный код .ink, предлагает намерения Quick (более ранний результат на 250K состояний) и Balanced (более глубокий результат на 1M состояний), создаёт недолговечное приватное задание, транслирует реальную работу, доходность и сигналы неопределённости и удаляет временный каталог задания после завершения, отмены или сбоя. Завершённые размещённые проверки возвращают привязанную к источнику идентичность окна результатов и стабильные идентификаторы находок. Он не делает отчёты публичными и не сохраняет текст истории в журналах приложения. Необязательные показатели использования первой стороны хранят ежедневные агрегированные счётчики плюс конфиденциальную приблизительную ежедневную оценку уникальных браузеров: никакие IP-адреса, пользовательские агенты, токены браузера или профили посетителей не сохраняются.

Локальный CLI остаётся вариантом с приоритетом конфиденциальности, поскольку загрузка истории не происходит. См. Развёртывание размещённого проверщика для модели угроз, развёртывания Docker, эксплуатационных ограничений и текущего бюджета менее 50 долларов в месяц.

Что он обнаруживает

• Ошибки компиляции и предупреждения — сломанные переходы, неразрешённые переменные, незавершённые концы, с номерами файлов и строк (через inklecate, официальный компилятор)

• Ошибки выполнения с путём воспроизведения — точная последовательность выборов, которая вызывает деление на ноль, плохой внешний вызов или выход за пределы контента, например repro: [Enter in darkness → Descend to the cellar]

• Возможные бесконечные циклы принудительного выбора — консервативное предупреждение обзора, когда единственный доступный выбор возвращается к тому же контрольному состоянию с теми же видимыми автору переменными; необязательные выходы, случайное поведение, счётчики ходов, счётчики посещений и вызовы EXTERNAL намеренно исключены

• Непосещённый контент, классифицированный — узлы, которые ни один исследованный путь не посещает в пределах настроенных ограничений, каждый классифицируется сканированием входящих переходов: «нет авторских точек перехода здесь — возможный сирота» против «есть входящие переходы — вероятно, за пределами ограничений этого прогона»

• Различные терминальные состояния — с трассой выборов, достигающей каждого из них; различающиеся конечные переменные сохраняются как отдельные результаты

Сравнение с альтернативами

Компилятор сообщает вам, что история валидна. Кликанье сообщает вам, что пути, по которым вы случайно кликнули, работают. Ink-Tester многократно выбирает случайные прохождения и сообщает частоту на уровне строк; inkcheck вместо этого систематически обходит состояния выбора и возвращает короткие пути сбоя. Ключевое различие — воспроизводимость: после исправления сообщённого пути тот же настроенный прогон может проверить этот путь снова. Подходы дополняют друг друга, особенно для историй со случайностью или интеграциями движка.

Пример

$ inkcheck examples/manor.ink
✓ compiled — 92 words, 7 knots, 6 choices
✓ explored 18050 states within limits (depth 100, 10000000 states, seed 1) — exhaustive (every reachable state visited) — 5 distinct terminal state(s)
    terminal via [Enter in darkness → Search the study → Leave with your loot]: "You slip out the servant door, heavier by half a purse."
    ...
✗ 1 runtime error(s):
    obj is null or undefined (at cellar.3)
      repro: [Enter in darkness → Descend to the cellar] (found by dfs:last)
⚠ 1 knot(s) never visited on any explored path — unreached is not necessarily unreachable:
    treasure_vault (manor.ink line 35) — no authored divert points here — possible orphan

Когда прогон прерывается, отчёт называет ограничение, которое фактически его ограничило, — например ⚠ coverage is partial, not a proof — paths were cut at 30 choices deep; raise --max-depth to follow longer trails. Глубина и бюджет состояний — это отдельные оси: в локальных прогонах The Intercept повышение --max-depth с 30 до 100 достигло большего количества позднего контента истории с бюджетом в 1 000 000 состояний, чем бюджет в 10 раз больше при глубине 30.

Код выхода ненулевой при ошибках компиляции или выполнения. Добавьте --strict, чтобы также завершаться сбоем при предупреждениях, непосещённых узлах, усечении или внешних заглушках, чтобы частичное покрытие не могло незаметно пройти CI.

История не обязательно должна быть длинной, чтобы превысить бюджет по умолчанию. Опубликованный The Intercept от Inkle считается сообществом относительно небольшим исходным файлом, однако Inkcheck всё равно сообщает о нём как о частичном при 5 000 000 состояний: ветвление плюс постоянные переменные создают граф достижимых состояний, гораздо больший, чем предполагает видимое количество выборов. Исчерпание — это наблюдаемое доказательство, а не ожидание, выведенное из размера источника. История с конечными значениями может быть в принципе исчерпываемой, но непрактичной для перечисления; состояние ходов, случайных или неограниченных переменных может сделать семантический граф неограниченным. Ограниченный прогон останавливается на том, что наступит первым — состояние, глубина, время или память — и сообщает, что именно. Размещённый проверщик ограничивает общие задания 1 000 000 состояний; более крупные задания (до потолка CLI в 100M) принадлежат локальной среде. См. Производительность и память для рекомендаций по масштабированию.

В рамках одного запуска inkcheck распределяет свой бюджет состояний по взаимодополняющим проходам поиска, а не ставит всё на один порядок обхода. Текущий портфель CLI исследует срезы DFS «последний выбор первым», «первый выбор первым» и «изнутри наружу», добавляет срез детерминированной случайной выборки, который варьирует префиксы ранних выборов, которые детерминированные проходы склонны повторять, добавляет луч разнообразия с ограниченным фронтом, который продвигается уровень за уровнем, как BFS, сохраняя по одному состоянию на линию сигнатуры переменных, а затем резервирует небольшой срез поиска в ширину для сокращения путей воспроизведения. Случайный срез использует фиксированное начальное значение по умолчанию, а лучу начальное значение не нужно вовсе, поэтому запуски остаются воспроизводимыми в CI; каждый сообщённый конец и ошибка времени выполнения называют проход (и начальное значение), который их обнаружил. Это часто находит больше концов и достижимых узлов при том же лимите --max-states, но это всё ещё ограниченная проверка качества: усечённый отчёт — полезное свидетельство, а не исчерпывающее доказательство.

--search=shared включает экспериментальную альтернативу: глубокие, ориентированные на новизну и посеянные представления черпают из одного дедуплицированного фронта, и каждое достижимое состояние расширяется не более одного раза. Это может расходовать ограниченный бюджет эффективнее, когда несколько стратегий в противном случае заново обнаруживали бы одно и то же состояние. JSON-телеметрия разделяет ожидающие и активные контрольные точки JSON/переменных, сохранённую родословную свидетелей, индексы дедупликации и семантики, ссылки на фронт и находки; она также сообщает об освобождённой родословной и уплотнениях устаревших представлений. Это детерминированные учтённые оценки полезной нагрузки/структуры, а не точное использование кучи V8. Это пока не значение по умолчанию: некоторые структуры ранних выборов всё ещё могут отдавать предпочтение независимым случайным и лучевым проходам портфеля.

Потребители библиотеки, оценивающие долго выполняющиеся общие задания, могут использовать exploreSharedResumable(...). Когда бюджет остаётся, он возвращает привязанную к источнику версионированную контрольную точку JSON, содержащую точный живой общий фронт; последующий вызов повышает общий грант (например, со 100k до 1m) и продолжает без повторного воспроизведения первых 100k. Эквивалентность разделённого запуска регрессионно тестируется против непрерывного запуска. Это фундамент движка, а не пока функция персистентности CLI: контрольные точки могут содержать авторский текст, переменные, состояние времени выполнения и пути свидетелей, а схема v1 намеренно исключает утверждения, цели и режимы shared с учётом переменных/целей. См. схему контрольной точки shared v1.

--search=shared-variable — более узкий эксперимент, который отдаёт 12,5% выборов общего фронта состояниям, достигнутым через необычные снимки переменных или переходы. Усиление ограничено, а глубокие, новизнные и посеянные представления остаются активными. Это может помочь механически управляемым графам сторилетов, но не является равномерно лучшим; включённая в репозиторий таблица сравнения содержит как выигрыши, так и регрессии.

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

Ограниченный поиск против случайной выборки

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

Случайная выборка остаётся полезной, особенно для историй со случайностью или огромными пространствами состояний. Относитесь к подходам как к взаимодополняющим: случайная игра может наткнуться на удивительные пути, тогда как inkcheck даёт детерминированные, удобные для CI свидетельства в пределах объявленного бюджета.

В локальном тесте The Intercept при лимите глубины 30 более высокие бюджеты находили больше терминальных состояний, но всё равно не доказывали полное покрытие. Времена получены на одной локальной машине разработки, и их следует читать как свидетельство масштаба, а не универсальный бенчмарк:

Это и есть предполагаемая интерпретация: каждый запуск проверяет реальные достижимые состояния и может выявить реальные сломанные пути, но усечённый отчёт — это свидетельство о том, что было посещено, а не доказательство того, что всё было достижимо или корректно.

Производительность и память

Бюджет по умолчанию — 10 000 000 состояний, а потолок — 100 000 000, поэтому стоит знать, сколько стоит большой запуск. Два ресурса ограничивают запуск: время и память. Маленькие или исчерпываемые истории не касаются ни одного из них — портфель рано выходит, как только систематический проход доказывает полноту достижимого пространства, поэтому inkcheck small.ink завершается на тех нескольких состояниях, которые у него есть, независимо от значения по умолчанию. Числа ниже важны только для больших, неисчерпываемых историй.

Время масштабируется примерно линейно с количеством исследованных состояний. На одной машине разработки The Intercept работал около 200 секунд на миллион состояний (см. таблицу выше), поэтому запуск на 10M состояний — это десятки минут, а на 100M — часы. На локальном CLI нет ограничения по настенному времени, поэтому для CI или интерактивного использования закрепите --max-states на том покрытии, которое вам действительно нужно, а не полагайтесь на значение по умолчанию — или запустите значение по умолчанию с --progress (включён по умолчанию в интерактивном терминале), чтобы вы могли наблюдать и прервать.

Память — это сумма членов с разным ростом, и именно поэтому потолок высок, а не опасен:

Два практических правила из этого:

• Бюджетируйте кучу, а не только состояния. В качестве оценки наихудшего случая (без дедупликации состояний) планируйте примерно 2 ГБ кучи на 10M различных состояний. Истории с циклами сильно дедуплицируются и используют гораздо меньше; история с низкой дедупликацией приближается к наихудшему случаю. Таким образом, наихудший случай запуска на 10M состояний (~2 ГБ) находится рядом с лимитом кучи Node по умолчанию: история с большим числом циклов остаётся значительно ниже него, но большая история с низкой дедупликацией может достичь предохранителя памяти до завершения даже при бюджете по умолчанию. Запуск на 100M состояний превышает обычную кучу по умолчанию и остановится на предохранителе, если вы не поднимете --max-old-space-size. В любом случае он чисто останавливается с частичным отчётом — предохранитель — это то, что делает высокий потолок безопасным для указания, а не обещание, что запуск завершится.

• Предохранитель памяти — реальный ограничитель, а не потолок. Запуск чисто останавливается на 85% кучи V8 (или вашего --max-memory) и возвращает частичный отчёт с truncatedBy.memory, а не падает. Поэтому установка --max-states 100000000 не безрассудна — на обычной машине предохранитель, а не потолок, решает, где он остановится. Чтобы пойти дальше, дайте Node больше кучи: NODE_OPTIONS=--max-old-space-size=8192 inkcheck big.ink --max-states 100000000.

• Пределы безопасности — это не решения об эффективности. Ограничения состояния, времени и памяти отвечают на вопрос «насколько далеко может зайти это задание?» Они не утверждают, что использование всей машины ценно или что видимое плато полно. Исследовательский путь 0.6 измеряет новые находки портфеля во времени, пропускную способность, пробелы восстановления, пиковый RSS и байты удерживаемого фронта, чтобы будущие политики quick/balanced/deep могли выбирать полезные окна результатов, сохраняя при этом зонды длинного хвоста. Фиксированные лимиты остаются доступными для CI и аудита.

Рычаги в порядке влияния, когда история слишком велика, чтобы завершиться: поднимите --max-old-space-size (больше запаса), передайте --no-min-repro (убирает суперлинейный фронт BFS), снизьте --max-states (ограничивает и время, и память) или разделите историю и проверяйте части отдельно. В экспериментальном режиме shared установите --max-frontier-memory или --max-frontier-states, когда самой очереди ожидающих контрольных точек нужен более жёсткий предел, и поднимайте эту оболочку только тогда, когда её отчёт показывает, что полезные свидетельства продолжают поступать. Вердикт nextRun называет ограничивающий лимит после каждого запуска, чтобы вы знали, какой рычаг применить.

Измеренная оценка ресурсобезопасных глубоких запусков фиксирует, как предохранители ведут себя на авторских заданиях с потолком 5M, включая свидетельства максимальных отметок ожидающих состояний общего фронта и сериализованных байтов.

MCP-сервер

Инструменты для ИИ-агентов, работающих над историями ink:

Добавьте в Claude Code:

claude mcp add inkcheck -- npx -y inkcheck mcp

или в конфигурацию любого MCP-клиента:

{
  "mcpServers": {
    "inkcheck": { "command": "npx", "args": ["-y", "inkcheck", "mcp"] }
  }
}

Профиль MCP по умолчанию предоставляет пять инструментов: inkcheck_capabilities, inspect_story, compile_story, start_search и inkcheck_workflow. Это позволяет держать стартовый контекст нового агента небольшим; capabilities перечисляет логические операции и поля запросов маршрутизатора. Установите INKCHECK_MCP_PROFILE=full только для клиентов, которым требуется каждая операция как отдельный именованный инструмент.

Компактный цикл агента: inkcheck_capabilities -> inspect_story -> compile_story -> start_search -> маршрутизация операций поиска/воспроизведения/регрессии через inkcheck_workflow -> исправление -> компиляция и проверка. Сессии окон результатов — путь агента по умолчанию, поскольку они устойчивы, ограничены, разбиты на страницы и привязаны к исходникам. Логические операции start_campaign / continue_campaign добавляют агрегированную политику и измеренные расходы/происхождение вокруг того же точного общего фронтира; обычные start_search / continue_search сохраняют явный контроль совокупного гранта. Вызовы синхронны, поэтому отмена надёжна на возвращаемых устойчивых границах, а не как вытеснение в середине окна. inspect_search остаётся минимальным с точки зрения конфиденциальности; add_goal может расходовать отдельно сообщаемый направленный бюджет, не ослабляя точный базовый поиск, а replay_witness — это явная граница, возвращающая одну текущую транскрипцию, траекторию выбора и состояние переменных. При сбоях выполнения, нарушениях утверждений и одобренных свидетелях целей используйте pin_regression перед редактированием и check_regression после — они воспроизводят один точный приватный свидетель без нового запуска поиска. Пин — это не широкая повторная проверка; запускайте новый ограниченный поиск после значимых правок. См. QA evidence pins, встроенный навык и MCP result-window sessions.

Когда автор или агент предлагает правила истории, inkcheck_workflow может сначала запустить review_contract. Проверка валидирует типизированные утверждения и цели против скомпилированной истории, инвентаризирует существующие контракты, требует одобрения автора и по умолчанию рекомендует широкое QA с нулевым направленным бюджетом. Она доступна только для чтения: не может редактировать конфигурацию, расходовать бюджет поиска или молча продвигать пробу цели. См. agent-directed QA contracts.

CLI

inkcheck capabilities [--json]
inkcheck inspect <story.ink> [--json]
inkcheck <story.ink> [--max-depth N] [--max-states N] [--seed N] [--story-seed N] [--search=portfolio|shared|shared-variable] [--concurrency auto|N] [--max-frontier-states N] [--max-frontier-memory MB] [--auto] [--profile] [--next] [--no-min-repro] [--strict] [--save-report] [--save-checkpoint] [--progress=auto|human|ndjson|off] [--human|--json|--json-stream|--markdown]
inkcheck artifacts list [--json]
inkcheck artifacts show <report-id> [--json]
inkcheck artifacts findings <report-id> [--limit N] [--cursor C] [--json]
inkcheck artifacts finding <report-id> <finding-id> [--json]
inkcheck artifacts replay <report-id> <finding-id> [--json]
inkcheck artifacts delete <report-id> [--apply] [--json]
inkcheck artifacts prune --keep N [--apply] [--json]
inkcheck checkpoints list [--json]
inkcheck checkpoints show <checkpoint-id> [--json]
inkcheck resume <checkpoint-id> --max-states N [--json]
inkcheck mcp    # start the MCP server on stdio

inkcheck capabilities --json позволяет агентам проверять версии схем, лимиты, режимы поиска и явно поддерживаемые или недоступные функции перед тем, как на них полагаться. inkcheck inspect story.ink --json выполняет детерминированное обнаружение только по исходникам без компиляции или исследования: он следует за локальными include проекта и возвращает ограниченную карту формы истории, семантики, externals, knots/функций, объявлений/чтений/записей переменных и статических условных гейтов с фактическими местами присваивания. Устойчивая MCP-сессия может превратить один явно выбранный поддерживаемый гейт в отдельный ограниченный запуск цели probe_gate; эта проба, запущенная от корня, сохраняет точный базовый фронтир и сообщает свидетеля или ограниченный промах. Инспекция гейтов и места присваивания — это подсказки-предпосылки, а не доказательство достижимости или изменение распределения поиска по умолчанию. См. compound gate inspection contract и agent discovery contract.

Протокол gate-probe evaluation сравнивает обычный общий поиск с явной пробой того же бюджета на комбинационном замке раннего выбора и опциональной ячейке 5M The Intercept. Это свидетельство того, стоит ли дальнейшее управление предпосылками, а не заявление о покрытии или продвижении.

JSON-проверки используют версионированную схему отчёта. Находки имеют стабильные ID и нормализованные виды; свидетели завершения и ошибок выполнения несут как человеческий текст выбора, так и нулевые индексы выбора, поэтому дублирующиеся метки остаются точно воспроизводимыми через playtest_story. Конверт записывает версию Inkcheck, отпечаток скомпилированной истории, эффективную конфигурацию, лимит привязки и наблюдательный shadowDecision, сохраняя установленные секции compile, stats, explore и nextRun.

--concurrency auto — локальный портфельный режим по умолчанию. Он задаёт потолок в четыре полосы, а не четыре безусловных воркера: один внутренний DFS-проход выполняется не более чем для 1 024 состояний, затем версионированный классификатор остаётся последовательным, когда история исчерпана, глубина ограничена, авторские knots уже насыщены, оборудование имеет одно ядро или память не может безопасно обеспечить воркеров. Открытый устойчивый фронтир держит этот живой проход в родителе, пока нетронутые проходы начинаются в постоянных воркерах. --concurrency 1 — жёсткий последовательный отказ; явные значения 2–16 сохраняют фиксированный потолок воркеров без классификации нагрузки. Общий поиск и запуски с аддитивными целями автоматически остаются последовательными, если только не был явно запрошен несовместимый фиксированный режим.

Отчёты раскрывают concurrencyMode, разрешённый потолок, политику/решение/причину активации, пилотную работу, эффективных воркеров, агрегированный план кучи и дублирующиеся оценки (ноль для производственной политики). Сбой воркера сохраняет последние завершённые доказательства и сообщает truncatedBy.worker; он никогда не маскируется под остановку по бюджету состояний. Хостируемые развёртывания передают свой собственный явный потолок на задачу, по умолчанию один на производственном контейнере, а реальная отмена дочерних процессов очищает временные загрузки. Пиковый RSS может быть выше, потому что накладные расходы V8/рантайма — это не куча; классификатор оценивает форму нагрузки, а не полноту покрытия.

MCP по умолчанию использует компактный машинный вывод: инспекция ограничена 16 КиБ, а компиляция, статистика, одноразовое исследование и ответы окон результатов — 32 КиБ. Пропуск вывода сообщается отдельно от усечения ограниченного поиска. Полные отчёты с историей остаются доступными только через явные вызовы детализации или drill-down.

Сохранённые отчёты поддерживают ограниченный drill-down по находкам без загрузки полного отчёта. artifacts findings возвращает не более 20 сводок с минимальной конфиденциальностью по умолчанию (максимум 100) и курсор, привязанный к отчёту; сводки опускают прозу истории, переменные, текст выбора и пути свидетелей. artifacts finding извлекает одну полную стабильную находку. artifacts replay перекомпилирует сохранённую точку входа и следует индексированным выборам этой находки с сохранённым сидом истории, но только пока свежесть артефакта — current; устаревшие или перемещённые исходники завершаются с ошибкой.

Хранилище отчётов приватно и ограничено: один отчёт может использовать не более 256 МиБ, а все отчёты в одном проекте — не более 1 ГиБ. Сохранение сверх любого потолка завершается ошибкой без удаления старых доказательств. artifacts delete и artifacts prune --keep N по умолчанию показывают предпросмотр и изменяют данные только с --apply; prune сохраняет N новейших отчётов для каждой точки входа и удаляет не более 100 за вызов. Этот явный жизненный цикл предотвращает исчезновение стабильного ID отчёта лишь потому, что завершился другой запуск.

Мейнтейнеры могут сравнивать теневые рекомендации в независимых запусках бюджета с помощью управляемого манифестом shadow policy evaluator. Отдельный search promotion benchmark запускает сопоставленные матрицы baseline/кандидат на проверенном корпусе из 20 семейств плюс закреплённый уровень согласованных авторских проектов, сообщает наблюдения ресурсов и худшие потери семейств/проектов и никогда не объявляет победителя. Первая authored-project evaluation обнаружила паритет там, где ячейки завершались, и значимые ограничения ресурсов формы проекта, а не преимущество policy-v2. Ни один инструмент не называет ограниченный больший запуск оракулом и не меняет политику по умолчанию.

--max-depth принимает 1–1 000, а --max-states — 1–100 000 000, с бюджетом по умолчанию 10 000 000. Эти жёсткие потолки предотвращают случайное отключение границ исследования некорректными вводами автоматизации. Бюджет по умолчанию намеренно амбициозен, потому что три вещи делают большой бюджет безопасным, а не безрассудным: полностью исследуемая история выходит рано в момент, когда систематический проход доказывает её исчерпанность (поэтому маленькие истории всё равно завершаются за несколько состояний), защита памяти останавливается чисто до сбоя из-за нехватки памяти, а отчёт о прогрессе позволяет наблюдать и прерывать длинный запуск. Поэтому большая неисчерпывающая история использует этот бюджет — см. Performance and memory перед запуском в CI и закрепите меньший --max-states там, если ограниченное время выполнения важнее глубины покрытия.

--max-states — это общий бюджет запуска, а не обещание, что один DFS-обход потратит все состояния. По умолчанию CLI делит большую часть этого бюджета между тремя дополняющими DFS-представлениями дерева выбора плюс срез случайной выборки с сидом, и сохраняет небольшой срез поиска в ширину для более коротких путей воспроизведения сбоев и завершений. Используйте --no-min-repro, чтобы потратить этот срез воспроизведения на DFS-портфель, когда сокращение в ширину менее важно, чем более широкий поиск.

--seed (по умолчанию 1) управляет только срезом случайной выборки поиска Inkcheck. --story-seed (по умолчанию 1) независимо задаёт начальное состояние RNG рантайма Ink для RANDOM() и поведения перемешивания. Держите оба фиксированными для воспроизводимого CI и точного воспроизведения свидетелей; меняйте --seed для выборки других путей выбора или намеренно меняйте --story-seed, чтобы задействовать другую допустимую последовательность случайности истории. Авторские команды SEED_RANDOM(...) по-прежнему действуют и могут переопределить начальный сид истории. Inkcheck записывает оба сида и несёт storySeed в инструкциях воспроизведения, но один запуск не перечисляет каждый возможный сид истории. Поле foundBy каждой находки в выводе --json называет проход, который её обнаружил, например dfs:last или random:seed=1.

--search=shared выбирает экспериментальный движок общего состояния с несколькими фронтирами; --search=portfolio — неизменный режим по умолчанию. Общий режим остаётся детерминированным для фиксированного сида и по-прежнему соблюдает контроли глубины, состояния, памяти, времени, прогресса и сокращения воспроизведения.

--save-checkpoint намеренно уже обычного общего поиска: он требует --search=shared --no-min-repro и отсутствия утверждений, целей, --auto, --next или артефакта отчёта в той же команде. Когда остаётся живая работа, JSON-вывод включает ID контрольной точки, привязанной к исходникам. inkcheck resume <id> --max-states N требует совпадения исходников и привязок поиска, а N должно превышать предыдущий общий грант контрольной точки; он автоматически сохраняет следующее поколение. Завершённые и остановленные по ресурсам поиски возвращают свой отчёт, не выдумывая возобновляемую контрольную точку.

--search=shared-variable добавляет небольшой фронтир редкости переменных к общему поиску. Он приоритизирует наблюдаемые необычные значения переменных и меняется механически; он не использует ИИ, не понимает смысл истории и не делает выводов о том, какие значения желательны.

--max-frontier-states и --max-frontier-memory — необязательные предохранительные ограничения общей области поиска для удерживаемых ожидающих контрольных точек. Ни у одного из них нет значения по умолчанию: Inkcheck не навязывает низкий универсальный предел фронта. Если явное ограничение срабатывает, запуск сохраняет свои находки, сообщает truncatedBy.frontier и не помечает остановку как исчерпание бюджета состояний. Те же параметры доступны как ci.maxFrontierStates / ci.maxFrontierMb и входные данные MCP explore_story.

--max-memory <mb> ограничивает, сколько кучи может использовать весь запуск, прежде чем он чисто остановится. Аварийное завершение из-за нехватки памяти V8 heap нельзя перехватить постфактум, поэтому inkcheck следит за памятью во время исследования и — до того, как произойдёт сбой, — останавливается, сохраняет всё найденное на данный момент и сообщает truncatedBy.memory с частичным отчётом, а не теряет запуск. Явные ограничения сохраняют до 25% (максимум 1 ГиБ) для финального построения результата и сброса; ограниченный поток сообщает и полное ограничение, и нижнюю отметку поиска. Ограничение по умолчанию — 85% от лимита V8 heap (который учитывает любой заданный вами NODE_OPTIONS=--max-old-space-size), так что большие запуски на скромном оборудовании деградируют изящно, а не умирают; передайте явное значение, чтобы ужесточить или ослабить его. При остановке по памяти вердикт nextRun — investigate (увеличьте --max-old-space-size, уменьшите --max-states или разделите историю) — никогда не broaden, поскольку дополнительный бюджет только быстрее упёрся бы в стену.

--max-time <s> — это общий аналог по настенному времени: крайний срок начинается до компиляции и сканирования исходников, и запуск сохраняет 10% выделенного времени (с минимумом 250 мс и максимумом 60 секунд) для объединения сохранённых находок и сброса результата. Исследование останавливается с truncatedBy.time вместо того, чтобы идти до бюджета состояний. На локальном CLI нет ограничения времени по умолчанию. Оно предназначено для CI или любого контекста, которому нужно ограниченное время выполнения, но который всё равно хочет получить находки на данный момент — та же идея изящной частичности, что и защита памяти, применённая ко времени. Хостируемый веб-проверщик устанавливает это автоматически, чуть ниже своего жёсткого тайм-аута, так что медленная история возвращает частичный отчёт, а не убивается.

--profile выводит дешёвый статический профиль формы истории — переменные и места их присваивания, плотность выборов, самый длинный путь дивертов — плюс предел глубины и веса проходов, которые inkcheck выбрал бы для этой формы, без запуска какого-либо исследования. --auto применяет эти предложения: он повышает --max-depth, когда статические пути дивертов превосходят значение по умолчанию (никогда не понижает его, и ваши явные флаги всегда побеждают) и передаёт веса проходов из профиля портфелю. Для истории, основной путь которой имеет 40 выборов в глубину, настройки по умолчанию ничего не находят, тогда как --auto достигает концовки и доказывает исчерпывающую проверку истории примерно за 111 состояний.

Интерактивные терминалы по умолчанию показывают краткую строку живого прогресса: реальная фаза, исследованные состояния относительно настроенного рабочего бюджета, находки и прошедшее время. --progress=human принудительно выводит читаемые снимки для журналов CI; --progress=ndjson записывает версионированные события для агентов и парсеров; --progress=off отключает прогресс. Ни один из этих процентов не претендует на покрытие истории. Финальный отчёт stdout остаётся авторитетным, и прогресс никогда не включает прозу истории, выборы, переменные или фрагменты исходников.

Каждый отчёт также несёт вердикт nextRun — небольшой закрытый словарь (stop, deepen, broaden, reseed, investigate), вычисляемый детерминированно из самого отчёта, с конкретными флагами, обоснованием, цитирующим использованные поля, и ожидаемым выигрышем, подкреплённым доказательствами. --next действует на него: после проверки inkcheck применяет рекомендованную эскалацию и перезапускает, до трёх раз, останавливаясь на вердикте stop/investigate, на предельных значениях флагов или когда эскалированный запуск не находит ничего нового (фиксированная точка). След запусков попадает в вывод --json как runs; повествование переходов идёт в stderr, чтобы машинный вывод оставался чистым. Рекомендации никогда не превышают документированные жёсткие пределы — когда за увеличением флага нет доказательств, вердикт деградирует до investigate и указывает на узлы, которые стоит пересмотреть.

GitHub Actions:

- uses: actions/setup-node@v4
  with: { node-version: 22 }
- name: Check the story and publish a readable summary
  shell: bash
  run: |
    set -o pipefail
    npx -y inkcheck story/main.ink --strict --markdown --max-states 500000 | tee -a "$GITHUB_STEP_SUMMARY"

Пример закрепляет --max-states 500000, чтобы задание имело предсказуемое время выполнения; бюджет по умолчанию — 10 000 000, который большая неисчерпывающая история действительно израсходует (см. Производительность и память). Закрепляйте бюджет в CI, когда ограниченное настенное время важнее максимального покрытия.

--strict завершается с ошибкой не только при предупреждениях и непосещённых узлах, но и когда исследование усечено или EXTERNAL-функцию пришлось заглушить. Это предотвращает частичную проверку, носящую зелёный значок «завершено».

См. Руководство по QA для InkJam для удобной настройки для писателей и помощи в интерпретации отчёта.

Нашли вводящий в заблуждение результат? Используйте публичные формы для сообщения о неверном или пропущенном результате, предложения лицензированного минимального фикстура или запроса опциональной проверки QA-клиники. Никогда не прикрепляйте частный, находящийся под эмбарго или ограниченный джемом материал истории к публичному вопросу.

Для людей, CI и агентов

inkcheck можно управлять человеком за терминалом, заданием CI или опциональным ИИ-кодирующим агентом. Сам инструмент по-прежнему не использует ИИ; агенты — просто ещё один вызывающий CLI или MCP-сервера.

• Машиночитаемый интерфейс: tool.json в корне репозитория описывает флаги CLI, инструменты MCP, коды выхода и формы вывода --json / --json-stream в одном файле.

• --json выводит весь отчёт как один JSON-объект ({ compile, stats, explore }) в stdout — анализируйте его, а не соскребайте красивый вывод. explore.passes сохраняет ограниченную локальную для прохода discoveryCurve («что нашёл этот исследователь») плюс только для портфеля portfolioMarginalCurve («что этот исследователь добавил первым»), разделяя точные терминалы, видимые исходы, ошибки выполнения, утверждения, цели/этапы, узлы и сопоставимую новизну. Сводки сохраняют первое/последнее состояния находок и факты о сухих промежутках, несмотря на сжатие. Отчёты портфеля также включают кривую по всему запуску в фактическом перемежающемся порядке выполнения; настенное время остаётся наблюдательным в событиях прогресса. explore.schedule показывает, как адаптивные раунды потратили бюджет. Версионированный shadowDecision показывает, что будущая политика «в любое время» рекомендовала бы и почему, включая защищённые минимальные уровни для проходов и неопределённость. Он только для наблюдения (applied: false): он никогда не меняет сегодняшний поиск и не утверждает, что ограниченное покрытие является доказательством.

• --json-stream выводит воспроизводимые числовые свидетельства находок в формате NDJSON, когда они сохраняются, затем ограниченное терминальное резюме вместо материализации полного обогащённого отчёта или одной строки JSON размером с отчёт. В настоящее время требует --concurrency 1, поддерживает один запуск исследования (без --next или --profile) и не может сочетаться с --save-report. Зарезервированный режим числовых тегов поддерживает нейтральную к оракулу оценку InkBench, не раскрывая переменные оракула поиску и не транслируя каждое обычное окончание. Используйте поток для длительных оценок внешних процессов, где частичные доказательства должны пережить жёсткую границу обёртки. См. контракт ограниченного потока свидетельств.

• --progress=ndjson выводит версионированные события жизненного цикла и рабочего прогресса в stderr для агента или парсера журналов CI. statesExplored / stateBudget — это использование бюджета, а не покрытие истории; финальный отчёт stdout остаётся авторитетным. См. контракт прогресса NDJSON.

• --human выводит приоритизированный список исправлений, сгруппированный по ошибкам, предупреждениям и примечаниям, с расположением файл/строка, где доступно, путями выборов для ошибок выполнения и следующим шагом для каждой находки.

• --markdown выводит отчёт, совместимый с GitHub Step Summary, для людей, просматривающих CI.

• Детерминированные коды выхода: 0 чисто · 1 ошибки компиляции/выполнения (или, при --strict, предупреждения, непосещённые узлы, усечение или внешние заглушки) · 2 ошибка использования. Ветвитесь по коду выхода; не грепайте текст.

• MCP: claude mcp add inkcheck -- npx -y inkcheck mcp открывает компактный пятиинструментальный профиль агента. Используйте INKCHECK_MCP_PROFILE=full для каталога совместимости.

• Цикл: редактируйте .ink -> compile_story -> start_search -> направляйте следующее действие по доказательствам через inkcheck_workflow -> исправляйте -> компилируйте и проверяйте. inkcheck — это повторяемая механическая проверка для графа истории, который вы сгенерировали или отредактировали; используйте его для проверки своей собственной работы перед возвратом.

• Цикл покрытия: explore_story (и CLI --json) возвращает nextRun — переключайтесь по его recommendation (stop / deepen / broaden / reseed / investigate) и перезапускайте с nextRun.flags, пока не получите stop: true. Или позвольте CLI управлять этим: inkcheck story.ink --next.

llms.txt в корне репозитория — это компактная, удобная для моделей сводка всего вышеперечисленного.

Как это работает

• Компиляция использует inklecate — канонический компилятор, который ищется через $INKLECATE_PATH, затем через PATH, а при отсутствии автоматически загружается из закреплённого официального релиза ink 1.2.1 в ~/.cache/inkcheck при первом запуске. Загруженные архивы проверяются по закреплённым SHA-256-хешам перед распаковкой. Истории компилируются с флагом -c, чтобы учитывались все посещения узлов (knot).

• Исследование запускает скомпилированную историю в inkjs (официальный порт JS-рантайма), переиспользуя пул экземпляров историй, чтобы скомпилированный JSON разбирался один раз за проход, а состояния откатывались через LoadJson. Inkcheck инициализирует случайность истории из --story-seed (по умолчанию 1), затем сохраняет состояние ГПСЧ Ink в каждой сохранённой ветке; авторский SEED_RANDOM(...) остаётся авторитетным при исполнении. Состояния дедуплицируются по хешу содержимого. Директивы INCLUDE обрабатываются.

• CLI использует ограниченный адаптивный портфельный поиск. Дополняющие проходы — «последний выбор первым», «первый выбор первым» и поиск в глубину изнутри наружу, beam-поиск с приоритетом разнообразия и сидированные случайные блуждания — выполняются вперемежку в десяти детерминированных раундах. Начальные веса (примерно 20/20/26/15/20%, или предложение профиля формы при --auto) перераспределяются каждый раунд в сторону проходов, чьи находки всё ещё растут, с целевым дробным минимумом 8% на активный проход. Воспроизведение политики только для исследований превращает это намерение в проверяемое совокупное целочисленное обслуживание и нормализует недавность к наблюдаемым окнам выполнения каждого прохода, а не к глобальному счётчику состояний. Для оценки доходности требуется три окна; сигналы истекают после одного или двух измеренных окон без обновления; экспериментальные наложения распределения допускаются только для обновлённых свидетельств времени выполнения/утверждений или явного прогресса по целям; широкое покрытие остаётся за устоявшимся планировщиком. Производственный планировщик не меняется, пока не пройдёт полный корпус продвижения. Проходы дополняют друг друга: порядки DFS систематически исчерпывают поддеревья, beam распределяет бюджет по линиям с переменными состояниями в пределах жёсткого ограничения фронта, а случайные блуждания перевыбирают каждую точку выбора, так что комбинации ранних выборов сэмплируются, а не повторяются. Находки объединяются в один отчёт, каждая помечена проходом, который её обнаружил, а выполненное расписание появляется в выводе --json.

• Адаптивный --concurrency auto — локальный портфельный режим по умолчанию. Его живой пилот DFS изнутри наружу на 1 024 состояния становится префиксом обычного первого адаптивного раунда, а затем либо продолжается последовательно, либо перекрывается с нетронутыми проходами в ограниченных постоянных воркерах. Если во время этого пилота время или память оказываются в дефиците — или срок наступает до инициализации любого воркера — валидный пилот возвращается как явно усечённый по ресурсам частичный отчёт, никогда не помечаемый как исчерпание бюджета состояний. Шлюз 80 ячеек / 100K сохранил точные находки, доказательства и адаптивные расписания лишь с двумя активациями открытого фронта; сопоставленные шлюзы 5M The Intercept глубина-30/глубина-100 сохранили точные свидетельства, отклонили задание с ограничением глубины и улучшили длительное задание с 657,7 с до 489,0 с. Каждое состояние остаётся в пределах одного потолка, а дублирующих пилотных оценок — ноль. Явное 1 сохраняет последовательное выполнение; явные потолки 2–16 сохраняют фиксированный параллелизм. См. оценку параллелизма.

• Экспериментальный --search=shared сохраняет единую глобальную идентичность состояния и раскрывает ожидающую работу через представления глубины, новизны и сидированного фронта. Состояние, выбранное любым представлением, разворачивается один раз; развёрнутый JSON контрольной точки освобождается немедленно, компактные родительские ссылки сохраняются только пока у ожидающего потомка есть точный путь воспроизведения, а устаревшие идентификаторы представлений периодически уплотняются. Отчёты раскрывают покомпонентный учёт и опциональные явные конверты контрольных точек. Редкость переменных состояний и переменных переходов записывается как телеметрия оценки.

• Экспериментальный --search=shared-variable заменяет один из каждых восьми выборов общего фронта на представление редкости переменных. Его оценка сочетает наблюдаемую частоту снимка переменной назначения и самое редкое изменение на этом ребре; он не может потреблять больше своей фиксированной доли, поэтому новизна графа, глубина и сидированное исследование остаются представленными.

• В момент, когда любой систематический проход посещает все достижимые состояния, не упёршись в ограничение, весь портфель останавливается: каждое дальнейшее состояние было бы избыточным. Небольшая полностью исследуемая история при бюджете по умолчанию в 10 000 000 состояний всё равно завершается за те несколько состояний, которые у неё реально есть — большой бюджет по умолчанию ничего не стоит, когда историю можно исчерпать.

• Проход beam отвечает на вопрос «что должен оптимизировать beam» конкретно: выжившие отбираются по кругу по группам сигнатур переменных (разнообразие в первую очередь), ранжируясь внутри каждой группы по новизне — сначала недавно посещённые узлы, затем новые сигнатуры переменных, затем новые наборы предлагаемых выборов. Он детерминирован без сида и сообщает о запуске как об усечённом всякий раз, когда ему пришлось отсечь достижимое состояние, так что beam никогда молча не заявляет о полном покрытии.

• Если не пропущено флагом --no-min-repro, CLI резервирует около 10% запрошенного бюджета --max-states для среза сокращения воспроизведения в ширину. BFS достигает общих находок по более коротким цепочкам выборов, где это возможно, и может дать дополнительные неглубокие находки.

• Ограничения (--max-depth, --max-states) сдерживают наихудшую комбинаторику; отчёт явно сообщает, когда был усечён.

Ограничения покрытия

• Исследование ограничено. Усечённый отчёт — это свидетельство о посещённых состояниях, а не доказательство по всей истории.

• Отчёты указывают ограничения, в которых они выполнялись (глубина, бюджет состояний, сид поиска и сид истории), и, при усечении, какое именно ограничение сократило покрытие (truncatedBy в --json, включая memory) с адресной рекомендацией, какой флаг поднять.

• Крупный запуск, который исчерпал бы память, останавливается чисто и возвращает частичный отчёт (truncatedBy.memory), а не падает — потребление памяти определяется хеш-множеством дедупликации (~линейно по числу различных состояний) и, на глубоких историях с малым числом циклов, фронтом BFS-сокращения воспроизведения, так что --no-min-repro и более жёсткий --max-states — это рычаги, когда история слишком велика для завершения.

• Для небольших историй часто действует противоположная гарантия: когда систематический проход посещает все достижимые состояния, не упёршись в ограничение, отчёт сообщает об этом (exhaustive), и исчерпание бюджета сэмплирующего среза больше не считается усечением.

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

• Случайное поведение воспроизводимо для указанного сида истории, но один запуск не перечисляет все возможные сиды истории. Сознательно варьируйте --story-seed и держите человеческое игровое тестирование в цикле, когда важна частота исходов.

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

Дорожная карта

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

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

• Качество отчётов: лучшие исходные расположения, более короткие пути воспроизведения, стабильные идентичности проблем и более чёткая группировка ошибок выполнения, непосещённых узлов и ограничений покрытия.

• Авторские утверждения об истории: детерминированные правила проекта, такие как «золото никогда не уходит в минус», «здоровье не превышает максимум» или «обязательные переменные установлены до концовок».

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

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

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

• Компактные контрольные точки кампаний: сохранять и возобновлять полезные фронты больших историй, не позволяя артефактам контрольных точек доминировать над памятью или диском, и деградировать до неизменяемого частичного отчёта до пределов сериализации.

• Публичные фикстуры совместимости: примеры с согласием и синтетические крайние случаи для регрессионного тестирования, сравнения производительности и укрепления доверия.

• Готовность агентов: исполняемый бенчмарк готовности агентов закрепляет протокол без скрытых подсказок, детерминированный фикстур выполнения/утверждений, цели начальной загрузки/инструментов/справочников/безопасности/доказательств, машинный скорер и отдельную атрибуцию инструментов/навыков/моделей/окружения. Два прошедших наблюдательных запуска от различных реализаций агентов остаются шлюзом релиза (#67).

• Харнесс продвижения поиска: широкая, заранее объявленная таблица по структурным семействам, бюджетам, глубинам и сидам, прежде чем любая экспериментальная стратегия сможет изменить значение по умолчанию.

• Ограниченный специализированный поиск: обнаруживать механические формы и запускать небольшие экспертные зонды для составных шлюзов, циклов/счётчиков, пригодности storylet, границ утверждений и разнообразия поведенческого фронта (#107–#112). Специалисты зарабатывают расширение через новую ценность для портфеля и сохраняют защищённую общую/длиннохвостовую работу.

• Контроль производительности больших историй: быстрые, стандартные и глубокие пресеты проверки с более ясными компромиссами времени/покрытия.

• Структурные lint-проверки: опциональные проверки отсутствующих тегов, несогласованных схем тегов или конвенций метаданных, специфичных для проекта.

Лицензия

MIT