Наблюдение

Эти четыре команды смотрят на эту установку и печатают то, что нашли. Они не создают устройство, паспорт, файл конфигурации и проект.

Исполняемый файл — ai-stp. Пакет на PyPI — ai-stp-cli. Каждую команду с этой страницы копируйте с --json, чтобы в stdout был ровно один конверт.

Команды

Команда	Mutability	Confirmation	Когда
ai-stp version	read	none	Сообщить текущий билд и версии контрактов, на которых он говорит.
ai-stp doctor	read	none	Состояние этой установки, без изменений.
ai-stp help	read	none	Отдать полный реестр команд для агента.
ai-stp capabilities	read	none	Что эта установка умеет прямо сейчас.

mutability: read значит, что команда наблюдает. Отсутствующее устройство, пустой реестр или файл конфигурации, который никогда не создавали, — типизированный ответ, а не повод что-то создать.

Типичный путь

Повседневная сессия агента:

ai-stp task intents --json

Expert observe / здоровье, если пользователь спросил, что сломано:

ai-stp version --json
ai-stp doctor --json

Expert: каждый command path этого билда:

ai-stp capabilities --json

Expert: полный реестр этой установки:

ai-stp help --agent --json

Читайте doctor до того, как придумывать ритуал восстановления. Если проверка в состоянии needs_user_action, следуйте этой проверке. capabilities отвечает уже, чем version: с какими поверхностями этот билд умеет говорить прямо сейчас. Поддержку harness нельзя выводить из строки версии.

help --agent — парсер этой установки. Документация группирует команды, чтобы человек нашёл страницу. Агент не должен восстанавливать флаги из памяти, когда CLI уже отвечает continuation argv.

version

Сообщить о запущенном билде и версиях контрактов, на которых он говорит.

ai-stp version --json

Нужна, чтобы убедиться, что оболочка говорит с тем ai-stp, который только что установили, а не с другой копией раньше в PATH. Сеть, устройство и каталог она не проверяет.

Успешный data называет:

Поле	Что это
cli_version	версия запущенного CLI
python_version	интерпретатор этого процесса
schema_version	major локальной схемы, на которой говорит этот билд
wire_schema_version	major wire-схемы, на которой говорит этот билд

doctor

Сообщить о состоянии установки этой инсталляции, ничего не меняя.

ai-stp doctor --json

Это отчёт, а не приговор, который надо «починить» одним движением. state — худшее состояние среди проверок, поэтому вызывающий, который читает одно поле, всё равно получает правду. У каждой проверки есть name, state и detail.

state у отчёта и у проверки — одно из ready, needs_user_action, partial или failed.

Проверки, которые этот билд сейчас называет:

name	На что смотрели
python_runtime	проходит ли интерпретатор нижнюю границу
configuration	можно ли соблюдать файл конфигурации, если он есть
local_registry	можно ли пользоваться файлом локального реестра
catalog	включён ли публичный каталог в конфигурации
credential_store	где хранились бы секреты (os_keyring или file)
device_identity	есть ли у этой установки устройство
file_permissions	закрыты ли частные пути только владельцу
interrupted_operations	операции, которые остановились без исхода
component_layouts	разбираются ли ещё известные раскладки компонентов
composition_passports	есть ли у записанных композиций голова
addressable_objects	есть ли у каждого локального объекта головная ревизия
provider_binding	резолвится ли ещё запомненный provider
cli_update	прервано ли self-update CLI или в кэше есть более новый wheel

doctor не создаёт устройство, когда device_identity пуст. Он не ставит toolchain, Agent Skill и программу harness. Это отдельные команды, к которым вы переходите после чтения отчёта.

Отсутствие — это ответ

Команда чтения на свежей установке возвращает типизированную пустоту. Она не запускает молча device init.

help

Выдать полный реестр команд для агента.

ai-stp help --agent --json

--agent называет вызывающего. Машинный реестр — единственный ответ этой команды, с этим флагом или без. Оставляйте --agent в вызове: остальные страницы этого справочника считают ai-stp help --agent --json парсером.

Успешный data называет:

Поле	Что это
cli_version	версия запущенного CLI
commands	каждая объявленная команда: path, summary, mutability, confirmation, parameters, parameter rules, result schema и next_actions
error_codes	закрытый реестр ошибок, которые этот билд умеет выдавать
global_options	опции, которые принимает каждая команда, включая --json
schema_version	major схемы этого конверта

Команда, которую эта установка не умеет выполнить, отсутствует в commands, а не описана как «not implemented». Если страница называет команду, которой нет в help, остановитесь. Не подменяйте похожим путём.

capabilities

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

ai-stp capabilities --json

Это нарочно не копия реестра команд. Здесь те немногие факты, по которым решается, стоит ли вообще делать следующий вызов. command_paths — указатель в help --agent, а не его замена.

Успешный data называет:

Поле	Что это
cli_version	версия запущенного CLI
command_paths	пути команд, которые объявляет этот билд
supported_harnesses	идентификаторы harness, которые этот билд умеет назвать
catalog_enabled	обращается ли конфигурация сейчас к публичному каталогу
sync_enabled	включена ли облачная синхронизация
schema_version	major локальной схемы
wire_schema_version	major wire-схемы

supported_harnesses — продуктовый набор, который знает этот билд: claude-code, codex, pi, opencode, grok-build, cursor, antigravity. Присутствие в списке не доказывает, что программа установлена на этой машине. Для этого — Toolchain (toolchain harnesses) и Программа harness (harness status).

Не считайте catalog_enabled: false аварией платформы. Это значение конфигурации. См. Конфигурация.

Что содержит успешный конверт

При ok: true результат в data. Конверт также несёт warnings, next_actions, request_id, operation_id и schema_version. warnings всё равно стоит показать. next_actions называет разумную следующую команду, а не разрешение.

При ok: false error.code — стабильный код из закрытого реестра; error.retryable говорит, можно ли повторять. Не угадывать следующий шаг по классу кода выхода.

Чего эти команды никогда не делают

• не вызывают model API и не просят ключ модели;
• не пишут target harness — это делает только public provider;
• не создают устройство, паспорт и файл конфигурации;
• не ставят toolchain, Agent Skill и программу harness;
• не считают author_verified доказательством безопасности версии компонента.

Типичные отказы

Что видно	Что это значит	Что делать
ai-stp not found	инструмента нет или он не в PATH	переустановить uv tool install ai-stp-cli, затем uv tool list
у doctor device_identity не ready	идентичность не создавали или хранилище её не читает	ai-stp device init --json, если её не создавали; иначе читайте detail
у doctor local_registry не ready	файла реестра нет, он не читается или это не реестр	следуйте detail; не удаляйте файл, чтобы «повторить»
capabilities не называют harness	этот билд не умеет вести эту цель	оставайтесь на primary harness или читайте Harnesses
команды нет в help --agent	этой установки её нет	остановиться; не подменять похожей командой
ok: false и retryable: false	тот же argv не поможет	читать error.code и next_actions

Связанные страницы

Страница	Зачем
Быстрый старт для ИИ-агента	ритуал сессии
CLI	конверты, mutability и группы команд
Карта команд	по одной строке на команду
Конфигурация	значения, которые эта установка должна соблюдать
Устройство	идентичность этой установки
Паспорта	факты разработчика и устройства
Toolchain	управляемые инструменты и обзор harness
Agent Skill CLI	skill самого CLI, не kind skill
Диагностика	что делать после красной проверки

Флаги из ai-stp help --agent --json

Если help --agent расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора.