istok context

istok context управляет сохранённым контекстом: короткими правилами, решениями, ограничениями и заметками, которые хранятся вместе с текущим проектом. Агенты читают и обновляют его через MCP. Как записи попадают в запуск и какие бюджеты при этом действуют, читайте в разделе Контекст и знания; как это выглядит со стороны пользователя — в разделе Правила и знания проекта.

Команды

Команда	Назначение
`add TITLE`	Добавить запись контекста.
`list`	Показать записи контекста.
`show [ID]`	Вывести контекст проекта или посмотреть одну запись.
`search QUERY`	Искать по контексту проекта.
`update ID`	Изменить запись контекста.
`enable ID`	Включить инструкцию.
`disable ID`	Отключить инструкцию.
`delete ID`	Архивировать запись контекста.
`preview TASK`	Посмотреть контекст, который получит взятие задачи TASK.
`doctor`	Найти проблемы с ростом и жизненным циклом контекста.

Все команды работают с текущим проектом. У записей есть канонические ID в формате UUIDv7 и ревизии.

Виды записей

Вид	Для чего
`note`	Знания о проекте или заметки о реализации. Вид по умолчанию.
`decision`	Решения, которые должны оставаться доступными для будущей работы.
`instruction`	Указания, которым агенты следуют при работе в проекте.
`constraint`	Правила или ограничения, влияющие на реализацию.

Добавить контекст

istok context add "Public API naming" \
  --kind constraint \
  --body "Public API fields use snake_case." \
  --tag api \
  --tag conventions

--tag можно повторять.

Метаданные записи

Флаг	Значения	По умолчанию
`--source`	`user`, `agent`, `import`	`user`
`--visibility`	`shared`, `local_only`	`shared`
`--sensitivity`	`normal`, `private`	`normal`
`--delivery`	`always`, `ranked`, `manual`	`always` для инструкций, `ranked` для остальных

Записи shared участвуют в обычной работе с проектом; local_only помечает запись, которая должна остаться в текущем окружении Istok. Чувствительность хранится вместе с записью и подсказывает, как обращаться с её содержимым.

Доставка

Режим	Поведение
`always`	Попадает в каждый запуск.
`ranked`	Попадает в запуск, если относится к задаче.
`manual`	Попадает в запуск, только если при взятии задачи запись указана по ID.

Так длинная заметка не попадёт в автоматическую доставку:

istok context add "Legacy billing migration notes" \
  --kind note \
  --delivery manual \
  --body "..."

Записи always держите короткими: они входят в каждый запуск и каждый раз расходуют долговременный бюджет.

Даты жизненного цикла

Даты указываются в формате RFC 3339.

Флаг	Действие
`--review-after`	После этого момента запись по-прежнему доставляется, но помечается как требующая пересмотра.
`--expires-at`	После этого момента запись исключается из автоматической сборки.
`--superseded-by`	UUIDv7 активной записи, которая заменяет эту; запись исключается из автоматической сборки.

istok context add "Feature freeze until the 2.0 release" \
  --kind constraint \
  --expires-at 2026-12-01T00:00:00Z \
  --body "Only bug fixes are accepted on main."

В context update дату можно очистить пустым значением, например --expires-at "".

Инструкции

У записи вида instruction есть дополнительные поля: включена ли она, --priority и --scope.

istok context add "Do not edit generated SDK files" \
  --kind instruction \
  --priority high \
  --body "Regenerate them from the OpenAPI schema instead."

Приоритет — critical, high, normal или low; при сборке контекста инструкции с более высоким приоритетом идут первыми. Область действия — project: инструкция относится к работе в текущем проекте.

Список, просмотр и поиск

istok context list
istok context show
istok context show RECORD_ID
istok context search "naming"

show без ID выводит активный контекст проекта обычным Markdown — его можно сразу вставить куда-нибудь ещё. С ID команда показывает одну запись с метаданными и текущей ревизией; посмотрите её перед изменением, которому нужен --expected-revision.

Флаг	Для команд	Действие
`--include-disabled`	`list`, `show`, `search`	Включить отключённые инструкции.
`--deleted`	`list`, `show`, `search`	Включить архивные записи.
`--limit`	`list`, `search`	Максимальное число записей.
`--kind`, `--source`, `--visibility`, `--sensitivity`	`list`	Фильтры; каждый можно повторять.

Изменить контекст

istok context show RECORD_ID
istok context update RECORD_ID \
  --expected-revision REVISION \
  --delivery ranked

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

Включить и отключить инструкции

istok context disable RECORD_ID --expected-revision REVISION
istok context enable RECORD_ID --expected-revision REVISION

Отключение сохраняет запись и её историю, но исключает её из сборки контекста. Отключённые инструкции не попадают в обычный список, поиск, экспорт и пакеты контекста, если их не запросить явно.

Архивировать контекст

istok context delete RECORD_ID --expected-revision REVISION

Запись архивируется и больше не входит в активный контекст. CLI просит подтверждение; вместе с --json передайте --yes.

Ревизии

update, enable, disable и delete требуют --expected-revision. Если запись изменилась после этой ревизии, команда завершается ошибкой, а не перезаписывает более новое состояние. Прочитайте запись снова и повторите с последней ревизией.

Ограниченная сборка контекста

Когда задачу берут в работу, Istok собирает пакет контекста из:

записей always, причём включённые инструкции упорядочены по приоритету;
записей, указанных через --context-id;
записей ranked, подходящих к названию, описанию, критериям приёмки и заметкам задачи;
кода, найденного в индексе репозитория;
сводки текущих знаний.

Пакет становится снимком контекста запуска. Последующие правки живого контекста его не меняют.

Лимит	По умолчанию
Долговременный контекст	16 KiB
Найденный код	32 KiB
Всего	48 KiB
Долговременных записей	12, расширяется до 64 для обязательных записей `always`
Размер одной записи	12 KiB
Сводка знаний	20 элементов, 4 KiB, считается отдельно

Записи ranked занимают тот долговременный бюджет, что остался после записей always и явно указанных. Истёкшие и заменённые записи пропускаются, а в снимок записывается предупреждение о них. Снимок также предупреждает, если контекст always вырос больше 8 KiB.

Если обязательные записи always или явно указанные не помещаются, взятие задачи завершается ошибкой, а не отбрасывает их. В ошибке перечислены записи и предложено решение: сократить запись, перевести необязательную запись в ranked или задать больший --context-limit.

Предпросмотр контекста для задачи

Посмотрите, что получит взятие задачи 12, не создавая запуск:

istok context preview 12

В выводе — число долговременных записей относительно лимита, расход байт по каждому бюджету, сводка знаний, каждая выбранная запись с её полосой (always, explicit или ranked) и оценкой, а также предупреждения.

preview принимает те же опции контекста, что и istok task claim:

istok context preview 12 --context-id RECORD_ID
istok context preview 12 --context-limit 20

--all-context требует --context-override-reason, а --without-retrieval — --retrieval-override-reason.

Диагностика контекста

istok context doctor

doctor сообщает:

активные записи и их общий размер;
сколько записей использует каждый режим доставки;
истёкшие, заменённые и требующие пересмотра записи;
проблемы с уровнем серьёзности, ID затронутых записей и предлагаемым действием.

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

Вывод JSON

Команды контекста принимают --json и возвращают версионированный ответ. show --json вместо готового Markdown возвращает структурированный список. См. Вывод JSON.

Справка

istok context add --help
istok context update --help
istok context preview --help
istok context doctor --help