ai_stp

# Наблюдение Эти четыре команды смотрят на эту установку и печатают то, что нашли. Они не создают устройство, паспорт, файл конфигурации и проект. Исполняемый файл — `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` значит, что команда наблюдает. Отсутствующее устройство, пустой реестр или файл конфигурации, который никогда не создавали, — типизированный ответ, а не повод что-то создать. ## Типичный путь Повседневная сессия агента: ```bash ai-stp task intents --json ``` Expert observe / здоровье, если пользователь спросил, что сломано: ```bash ai-stp version --json ai-stp doctor --json ``` Expert: каждый command path этого билда: ```text ai-stp capabilities --json ``` Expert: полный реестр этой установки: ```text ai-stp help --agent --json ``` Читайте `doctor` до того, как придумывать ритуал восстановления. Если проверка в состоянии `needs_user_action`, следуйте этой проверке. `capabilities` отвечает уже, чем `version`: с какими поверхностями этот *билд* умеет говорить прямо сейчас. Поддержку harness нельзя выводить из строки версии. `help --agent` — парсер *этой* установки. Документация группирует команды, чтобы человек нашёл страницу. Агент не должен восстанавливать флаги из памяти, когда CLI уже отвечает continuation `argv`. ## `version` Сообщить о запущенном билде и версиях контрактов, на которых он говорит. ```bash ai-stp version --json ``` Нужна, чтобы убедиться, что оболочка говорит с тем `ai-stp`, который только что установили, а не с другой копией раньше в `PATH`. Сеть, устройство и каталог она не проверяет. Успешный `data` называет: | Поле | Что это | | --- | --- | | `cli_version` | версия запущенного CLI | | `python_version` | интерпретатор этого процесса | | `schema_version` | major локальной схемы, на которой говорит этот билд | | `wire_schema_version` | major wire-схемы, на которой говорит этот билд | ## `doctor` Сообщить о состоянии установки этой инсталляции, ничего не меняя. ```bash 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` Выдать полный реестр команд для агента. ```text 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` Сообщить, что эта установка может делать прямо сейчас. ```text 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.md) (`toolchain harnesses`) и [Программа harness](harness.md) (`harness status`). Не считайте `catalog_enabled: false` аварией платформы. Это значение конфигурации. См. [Конфигурация](config.md). ## Что содержит успешный конверт При `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](../harnesses.md) | | команды нет в `help --agent` | этой установки её нет | остановиться; не подменять похожей командой | | `ok: false` и `retryable: false` | тот же argv не поможет | читать `error.code` и `next_actions` | ## Связанные страницы | Страница | Зачем | | --- | --- | | [Быстрый старт для ИИ-агента](../quickstart/agent.md) | ритуал сессии | | [CLI](index.md) | конверты, mutability и группы команд | | [Карта команд](commands.md) | по одной строке на команду | | [Конфигурация](config.md) | значения, которые эта установка должна соблюдать | | [Устройство](device.md) | идентичность этой установки | | [Паспорта](passport.md) | факты разработчика и устройства | | [Toolchain](toolchain.md) | управляемые инструменты и обзор harness | | [Agent Skill CLI](skill.md) | skill самого CLI, не kind `skill` | | [Диагностика](../troubleshooting/index.md) | что делать после красной проверки | !!! note "Флаги из `ai-stp help --agent --json`" Если `help --agent` расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора.