Паспорта¶

Паспорт — версионированное машиночитаемое описание объекта. На этой странице только два паспорта, которые описывают вас и эту машину: паспорт разработчика и паспорт устройства. Паспорта компонента, сетапа и проекта — другие объекты с другими командами.

Паспорт разработчика объявляет предпочтения. Паспорт устройства записывает то, что наблюдается на этой машине. Эти факты нельзя менять местами. Поле окружения на паспорте разработчика отклоняется, а предпочтение не является наблюдением.

Команды¶

Команда	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.

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

После того как идентичность устройства есть:

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

Чтобы объявить факты разработчика, добавив одну ревизию:

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`¶

Создать паспорт разработчика этой установки.

ai-stp passport developer init --json

Создаёт устойчивое состояние. Второй запуск возвращает существующую голову. Предпочтения он не выдумывает: пустые факты допустимы, пока вы не объявите их через update.

`passport developer show`¶

Показать паспорт разработчика на текущем head.

ai-stp passport developer show --json

Это чтение. Если паспорт никогда не создавали, команда отказывает с AI_STP_NOT_FOUND. Наблюдение его не выпускает.

`passport developer update`¶

Заявить факты разработчика, добавив одну ревизию.

ai-stp passport developer update --set role=<role> --json

Каждый успешный вызов добавляет одну ревизию поверх текущей головы. Предыдущая ревизия остаётся в истории. Правки на месте нет. Неизвестные имена отклоняются. Имена окружения отклоняются. Секреты здесь непредставимы.

Паспорт устройства¶

Паспорт устройства описывает окружение: операционную систему, архитектуру, установленные harness, версии, которые видит toolchain. Это не идентичность устройства. Идентичность — device_id плюс пара ключей; см. Устройство.

`passport device refresh`¶

Создать паспорт устройства или привести его к тому, что сейчас наблюдаемо.

ai-stp passport device refresh --json

Если наблюдаемое не изменилось, голова остаётся где была. Если изменилось, записывается новая ревизия. В любом случае команда — apply, а не чтение: ей позволено добавлять историю.

Refresh не ставит harness, toolchain и Agent Skill. Он записывает то, что уже есть.

`passport device show`¶

Показать паспорт устройства на текущем head.

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. Это не эта страница. Паспорта проекта — Проект. Паспорта компонента — Паспорт компонента.

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

не кладут секреты, тела .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`

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

Страница	Зачем
Понятия	что такое паспорт
Устройство	идентичность, не окружение
Проект	`project passport` фиксирует индекс
Паспорт компонента	паспорта принятых компонентов
Вход	передача владения при первом входе
Синхронизация	отправка головы паспорта разработчика
Быстрый старт для человека	идентичность и паспорта первого запуска

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

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