Наблюдение

Команды чтения: текущий билд, здоровье установки, machine help и возможности этой установки.

Наблюдение

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

Исполняемый файл — 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. Это отдельные команды, к которым вы переходите после чтения отчёта.

!!! note "Отсутствие — это ответ" Команда чтения на свежей установке возвращает типизированную пустоту. Она не запускает молча 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`
Диагностика	что делать после красной проверки

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