ai_stp

# Паспорта Паспорт — версионированное машиночитаемое описание объекта. На этой странице только два паспорта, которые описывают *вас* и *эту машину*: паспорт разработчика и паспорт устройства. Паспорта компонента, сетапа и проекта — другие объекты с другими командами. Паспорт разработчика объявляет предпочтения. Паспорт устройства записывает то, что наблюдается на этой машине. Эти факты нельзя менять местами. Поле окружения на паспорте разработчика отклоняется, а предпочтение не является наблюдением. ## Команды | Команда | Mutability | Confirmation | Когда | | --- | --- | --- | --- | | `ai-stp passport developer init` | `apply` | `none` | создать паспорт разработчика этой установки | | `ai-stp passport developer show` | `read` | `none` | показать паспорт разработчика на текущем head | | `ai-stp passport developer update` | `apply` | `none` | заявить факты разработчика, добавив одну ревизию | | `ai-stp passport device refresh` | `apply` | `none` | создать паспорт устройства или привести его к тому, что сейчас наблюдаемо | | `ai-stp passport device show` | `read` | `none` | показать паспорт устройства на текущем head | `passport developer init` идемпотентен: второй запуск — no-op, а не второй паспорт. `passport device refresh` пишет ревизию, только если что-то действительно изменилось, но историю добавить может, поэтому класс — `apply`. ## Типичный путь После того как идентичность устройства есть: ```bash ai-stp device init --json ai-stp passport developer init --json ai-stp passport developer show --json ai-stp passport device refresh --json ai-stp passport device show --json ``` Чтобы объявить факты разработчика, добавив одну ревизию: ```bash ai-stp passport developer update --set role=<role> --json ai-stp passport developer show --json ``` `--set` на `update` обязателен. Его можно повторять для нескольких полей. Форма — `name=value`; значение через запятую становится списком. Точные имена полей — в `ai-stp help --agent --json` и в отказе, который называет допустимый набор. Для локальной работы аккаунт не нужен. До входа владелец — локальный `account_…`, выпущенный при первом использовании. Вход передаёт владение аккаунту сервера обычной ревизией. Историю он не переписывает. ## Паспорт разработчика Паспорт разработчика держит объявленные факты о человеке, который пользуется этой установкой. Закрытый список полей: | Поле | Для чего | | --- | --- | | `role` | как вы описываете свою роль | | `typical_tasks` | работа, которую обычно просите у агента | | `priorities` | что должно побеждать, когда цели спорят | | `preferred_languages` | языки, на которых вы предпочитаете работать | | `preferred_harnesses` | harness, для которых вы предпочитаете собирать состав | | `autonomy` | как далеко агент может идти, не спрашивая | Этого на паспорте разработчика никогда нет. Это наблюдения окружения, и они принадлежат устройству: - `operating_system` - `architecture` - `installed_harnesses` - `harness_versions` - `tool_versions` Запись одного из них через `passport developer update` отклоняется. ### `passport developer init` Создать паспорт разработчика этой установки. ```bash ai-stp passport developer init --json ``` Создаёт устойчивое состояние. Второй запуск возвращает существующую голову. Предпочтения он не выдумывает: пустые факты допустимы, пока вы не объявите их через `update`. ### `passport developer show` Показать паспорт разработчика на текущем head. ```bash ai-stp passport developer show --json ``` Это чтение. Если паспорт никогда не создавали, команда отказывает с `AI_STP_NOT_FOUND`. Наблюдение его не выпускает. ### `passport developer update` Заявить факты разработчика, добавив одну ревизию. ```bash ai-stp passport developer update --set role=<role> --json ``` Каждый успешный вызов добавляет одну ревизию поверх текущей головы. Предыдущая ревизия остаётся в истории. Правки на месте нет. Неизвестные имена отклоняются. Имена окружения отклоняются. Секреты здесь непредставимы. ## Паспорт устройства Паспорт устройства описывает окружение: операционную систему, архитектуру, установленные harness, версии, которые видит toolchain. Это не идентичность устройства. Идентичность — `device_id` плюс пара ключей; см. [Устройство](device.md). ### `passport device refresh` Создать паспорт устройства или привести его к тому, что сейчас наблюдаемо. ```bash ai-stp passport device refresh --json ``` Если наблюдаемое не изменилось, голова остаётся где была. Если изменилось, записывается новая ревизия. В любом случае команда — apply, а не чтение: ей позволено добавлять историю. Refresh не ставит harness, toolchain и Agent Skill. Он записывает то, что уже есть. ### `passport device show` Показать паспорт устройства на текущем head. ```bash ai-stp passport device show --json ``` Это чтение. Если паспорт никогда не создавали, команда отказывает, и `next_actions` называет `passport device refresh`. ## Что содержит успешный конверт Все пять команд возвращают одну форму в `data`: | Поле | Что это | | --- | --- | | `kind` | на этой странице `developer` или `device` | | `stable_id` | стабильный идентификатор паспорта | | `revision_id` | текущая головная ревизия | | `parent_revision_ids` | от чего происходит эта ревизия | | `owner_id` | локальный владелец или аккаунт | | `facts` | объявленные или наблюдаемые факты на этой голове | | `created_at` | когда записана эта ревизия | | `schema_version` | major схемы этого вида | Это вид, а не сами байты паспорта. Конверт и факты принадлежат модели паспорта. CLI добавляет локальную позицию: какая ревизия текущая и от чего она происходит. Конверт также несёт `ok`, `warnings`, `next_actions`, `request_id`, `operation_id` и `schema_version`. `kind` на других командах может быть ещё `project`, `component` или `setup`. Это не эта страница. Паспорта проекта — [Проект](project.md). Паспорта компонента — [Паспорт компонента](component-passport.md). ## Чего эти команды никогда не делают - не кладут секреты, тела `.env` и токены в паспорт; - не копируют наблюдения ОС или harness на паспорт разработчика; - не копируют предпочтения на паспорт устройства; - не создают идентичность устройства (это `device init`); - не публикуют ничего в каталог; - не пишут target harness. ## Типичные отказы | Что видно | Что это значит | Что делать | | --- | --- | --- | | `AI_STP_NOT_FOUND` на `developer show` | паспорт разработчика никогда не создавали | `ai-stp passport developer init --json` | | `AI_STP_NOT_FOUND` на `device show` | паспорт устройства никогда не создавали | `ai-stp passport device refresh --json` | | `AI_STP_VALIDATION_ERROR` на `update` | неизвестное поле, поле окружения или нет `--set` | взять поле разработчика; допустимый набор в `details` | | `doctor` сообщает, что устройства нет | нет идентичности, поэтому факты устройства нельзя честно наблюдать | сначала `ai-stp device init --json` | | ожидание, что `device show` напечатает факты ОС | это паспорт, не идентичность | `ai-stp passport device show --json` | ## Связанные страницы | Страница | Зачем | | --- | --- | | [Понятия](../concepts/index.md) | что такое паспорт | | [Устройство](device.md) | идентичность, не окружение | | [Проект](project.md) | `project passport` фиксирует индекс | | [Паспорт компонента](component-passport.md) | паспорта принятых компонентов | | [Вход](auth.md) | передача владения при первом входе | | [Синхронизация](sync.md) | отправка головы паспорта разработчика | | [Быстрый старт для человека](../quickstart/human.md) | идентичность и паспорта первого запуска | !!! note "Флаги из `ai-stp help --agent --json`" Если `help --agent` расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора. `passport developer update` требует `--set`.