istok

istok knowledge

Создание, извлечение, поиск, чтение, проверка, утверждение, замена и экспорт знаний проекта.

istok knowledge работает с заметками знаний: более длинными проверенными документами о проекте, которые хранятся в базе Istok, а не в вашем репозитории. Агенты управляют ими через MCP; CLI удобен, чтобы проверять черновики, смотреть, что написали агенты, и экспортировать заметки. Жизненный цикл «черновик — проверка — утверждение» описан в разделе Контекст и знания.

Команды

Команда Назначение
add TITLE Создать черновик.
distill TITLE Создать черновик с явно указанными источниками.
list (псевдоним catalog) Показать каталог без полных текстов.
search QUERY Искать по знаниям и вернуть записи каталога.
show ID Показать одну заметку целиком.
read ID Прочитать одну заметку целиком.
update ID Изменить черновик.
review ID Записать явную проверку черновика.
promote ID Утвердить проверенный черновик как текущий.
supersede ID REPLACEMENT Заменить текущую заметку проверенной заменой.
export ID Экспортировать заметку в выбранный вами файл.

Все команды знаний работают с проектом Istok, связанным с текущей директорией. Заметки идентифицируются каноническими ID в формате UUIDv7.

Виды и статусы

У каждой заметки есть вид:

Вид Для чего
architecture Как устроена система или её часть.
domain Понятия предметной области и бизнес-правила.
decision Решения и их причины.
runbook Эксплуатационные процедуры.
note Всё остальное. Вид по умолчанию.

И статус:

Статус Значение
draft Предложена. Её можно править, проверять и утверждать.
current Утверждена. Входит в сводки для запусков. Править нельзя.
superseded Заменена другой заметкой. Хранится для истории. Править нельзя.

Кроме того, у заметок есть теги, --visibility (shared или local_only) и --sensitivity (normal или private) — с тем же смыслом, что и у записей контекста.

Создать черновик

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

istok knowledge add "Authentication" \
  --kind architecture \
  --summary "How sessions, refresh tokens, and the JWKS cache fit together" \
  --body-file ./auth-notes.md \
  --tag auth

Текст передаётся либо прямо через --body, либо из файла через --body-file, но не обоими способами сразу. Файл читается один раз: Istok сохраняет содержимое в базе и не хранит ссылку на файл.

Ограничения: название — до 200 байт, краткое описание — до 500 байт, текст — до 1 MiB.

Извлечь черновик из проделанной работы

distill создаёт черновик так же, как add, но требует хотя бы один источник:

istok knowledge distill "Token refresh failure modes" \
  --summary "Why refresh requests time out and how retries behave" \
  --body-file ./findings.md \
  --source task:TASK_ID \
  --source run:RUN_ID \
  --source repository:internal/auth/refresh.go

Источник имеет вид:

TYPE:ID[@REVISION][#DETAIL]

TYPE — одно из task, run, context, knowledge, repository или import. Для task, run, context и knowledge ID — канонический UUIDv7 объекта (для задачи — UUID из istok task show 12 --json, а не номер задачи). Источник repository — нормализованный путь относительно корня репозитория. Источник import — произвольная строка. --source можно повторять, и add его тоже принимает.

Просмотр и поиск

Показать каталог:

istok knowledge list

Отфильтровать его:

istok knowledge list --status current
istok knowledge list --kind runbook --kind decision

list также принимает фильтры --visibility и --sensitivity. По умолчанию возвращается до 50 записей; для больших каталогов используйте --limit (не больше 200) и --offset.

Поиск по названиям, кратким описаниям, текстам, тегам и источникам:

istok knowledge search "JWKS cache"

Результаты каталога и поиска содержат метаданные и короткий фрагмент, а не полный текст.

Прочитать заметку

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

istok knowledge show KNOWLEDGE_ID

istok knowledge read KNOWLEDGE_ID выводит то же самое. Используйте то имя, которое вам удобнее.

Изменить черновик

Менять можно только черновики:

istok knowledge update KNOWLEDGE_ID \
  --expected-revision 2 \
  --summary "Sessions, refresh tokens, JWKS cache, and key rotation"

update принимает новые значения для названия, краткого описания, текста (--body или --body-file), вида, тегов, источников, видимости и чувствительности.

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

Чтобы изменить текущую заметку, создайте новый черновик и замените им текущую.

Проверить черновик

Запишите, что черновик проверен, и опишите, как именно:

istok knowledge review KNOWLEDGE_ID \
  --expected-revision 1 \
  --note "Verified against internal/auth at the current main branch"

Проверять можно только черновики. Заметка о проверке обязательна и ограничена 1000 байт.

Утвердить черновик

Сделайте проверенный черновик текущим:

istok knowledge promote KNOWLEDGE_ID --expected-revision 2

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

Заменить текущую заметку

Замените текущую заметку более новой:

istok knowledge supersede OLD_ID NEW_ID --expected-revision 3

--expected-revision — ревизия заменяемой текущей заметки. Замена должна быть проверенным черновиком или уже текущей заметкой. Проверенный черновик в том же шаге утверждается как текущий, а старая заметка получает статус superseded.

Экспортировать заметку

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

istok knowledge export KNOWLEDGE_ID --output ~/notes/authentication.md

По умолчанию это Markdown с небольшим заголовком метаданных. Для JSON используйте --format json.

Экспорт никогда не перезаписывает существующий файл. Недостающие родительские директории создаются с правами 0700, а сам файл — с правами 0600.

Ревизии

update, review, promote и supersede защищены сравнением с обменом (compare-and-swap) через --expected-revision. Если заметка изменилась с момента чтения, команда завершается ошибкой, а не перезаписывает более новое состояние. Прочитайте её снова через show и повторите с текущей ревизией.

Вывод JSON

Все команды знаний принимают --json и возвращают версионированный ответ с schema_version: "1". См. Вывод JSON.

Справка

istok knowledge distill --help
istok knowledge list --help
istok knowledge export --help