ai_stp

# Проект Проект в `ai_stp` — каталог, который вы называете, а не диск, по которому CLI идёт искать. Discovery сканирует только переданный корень. Домашний каталог отклоняется. Индексация ограничена и пропускает секреты и двоичное содержимое. Паспорт проекта закрепляет этот индекс вместе с toolchain и конфигурацией, которые были в силе. Эти команды не собирают сетап и не пишут target harness. Они описывают одно дерево, чтобы у позднего выбора было на чём стоять. ## Команды | Команда | Mutability | Confirmation | Когда | | --- | --- | --- | --- | | `ai-stp project discover` | `read` | `none` | перечислить проекты внутри названного каталога; больше ничего не сканирует | | `ai-stp project index` | `read` | `none` | проиндексировать один корень проекта, ограниченно, пропуская секреты и двоичное содержимое | | `ai-stp project symbols` | `read` | `none` | прочитать публичные символы проекта, точки входа и тесты; графа вызовов нет | | project passport | `apply` | `none` | записать ревизию паспорта проекта, закрепляющую индекс, toolchain и конфигурацию | | `ai-stp project revision push` | `apply` | `explicit_flag` | опубликовать allowlisted-проекцию локального паспорта в ledger организации | | `ai-stp project revision pull` | `read` | `none` | прочитать redacted-узлы ledger организации для одной связи | `--root` обязателен на discover, index, symbols и passport. Настроенного запасного пути нет, и «текущий каталог» молчанием не подразумевается. Revision push и pull берут идентификатор локального проекта и связь организации. ## Типичный путь ```text ai-stp project discover --root <root> --json ai-stp project index --root <root> --json ai-stp project symbols --root <root> --json ai-stp project passport --root <root> --json ``` `<root>` — точный корень проекта, не домашний каталог и не родитель многих репозиториев, если вы не хотели искать внутри этого родителя. `discover` перечисляет кандидатов внутри каталога. `index`, `symbols` и `passport` каждый принимают один корень проекта. `project index` и `project symbols` — чтения: они ничего не пишут. `project passport` сохраняет ревизию в локальном реестре. Он идемпотентен — неизменённый проект ничего не добавляет — но идемпотентность не есть только чтение. `discover` может вернуть несколько кандидатов. `index`, `symbols` и `passport` каждый принимают одно из этих значений `root`. Не передавайте родителя discovery в `index`, если этот родитель сам не является проектом. Вложенные репозитории перечислены отдельно, чтобы можно было выбрать. ## `project discover` Перечислить проекты внутри названного каталога. Больше ничего не сканирует. ```bash ai-stp project discover --root <root> --json ``` Корень называют, а не ищут. Нет режима, в котором эта команда идёт смотреть сама. Успешный `data` называет: | Поле | Что это | | --- | --- | | `discovery_root` | каталог, который вы назвали, в разрешённом виде | | `complete` | закончилось ли сканирование внутри своих границ | | `candidates` | каждый с `root`, `kind`, `state`, `markers`, `reason` | | `diagnostics` | пропущенные пути, каждый с `code`, `path`, `reason` | | `schema_version` | major схемы этого отчёта | `kind` кандидата — `project` или `nested_repository`. `state` — `new` или `established`. `code` диагностики — `excluded`, `entry_limit`, `symlink` или `unreadable`. Если `complete` равен `false`, список — не всё дерево. Читайте `diagnostics`, прежде чем считать тишину за «здесь ничего нет». ## `project index` Проиндексировать один корень проекта, ограниченно, пропуская секреты и двоичное содержимое. ```bash ai-stp project index --root <root> --json ``` Читает и сообщает. Паспорт, который записывает индекс, — другая команда. Короткий ответ, который выглядит полным, хуже полного ответа, который говорит, где остановились, поэтому `state` — `complete` или `partial`, а `stopped_by` называет границу, когда индекс частичный. Успешный `data` называет: | Поле | Что это | | --- | --- | | `root` | корень проекта, который индексировали | | `state` | `complete` или `partial` | | `stopped_by` | какая граница сработала, или `null` | | `files` | каждый с `path`, `kind`, `language`, `lines`, `size_bytes`, `digest` | | `excluded` | каждый с `path` и `reason` | | `schema_version` | major схемы этого отчёта | `kind` файла — `manifest`, `lock`, `agent_surface`, `source`, `document`, `config` или `text`. Содержимого исключённых файлов в конверте нет. Секретов и двоичных байтов в конверте нет. ## `project symbols` Прочитать публичные символы проекта, точки входа и тесты. Графа вызовов нет. ```bash ai-stp project symbols --root <root> --json ``` Это чтение публичных имён, а не модель того, как они вызывают друг друга. `method` у каждого языка говорит, насколько силён ответ: `syntax_tree` значит, файл читал парсер; `line_scan` значит, слова узнали построчно. Сообщать оба как простые счётчики — скрыть эту разницу. Успешный `data` называет: | Поле | Что это | | --- | --- | | `root` | корень проекта, который читали | | `state` | закончилось ли чтение внутри своих границ | | `stopped_by` | какая граница сработала, или `null` | | `languages` | каждый с `language`, `state`, `method`, `files`, `symbols`, `entry_points`, `tests`, `reason` | | `schema_version` | major схемы этого отчёта | `state` языка — `available` или `not_available`. Язык, который есть в дереве, но для которого в этом билде нет парсера, всё равно перечислен, с причиной. ## `project passport` Записать ревизию паспорта проекта, закрепляющую индекс, toolchain и конфигурацию. ```text ai-stp project passport --root <root> --json ``` Результат — вид паспорта (`kind` равен `project`) с `stable_id`, `revision_id`, `parent_revision_ids`, `owner_id`, `facts`, `created_at` и `schema_version`. Как читать эту форму — [Паспорта](passport.md). Факты закрепляют то, что наблюдали, а не то, что вы хотели бы видеть. Изменить дерево и записать снова — добавить ревизию. Предыдущую это не правит. Локальный паспорт не находится в ledger организации. После связи проекта путь в организацию — `project revision push`, затем `project revision pull`, если другой device уже публиковал, затем `project sync plan` и `project sync apply`. `--local-revision` у плана — это ledger `revision_id` из квитанции push. Собственный `revision_id` паспорта — другой домен дайджеста; план с ним отклоняется как ревизия, которой организация не видела. ## Ledger организации Локальный паспорт остаётся на устройстве, пока вы не опубликуете его allowlisted-проекцию. `project revision push` — эта публикация: дайджесты, счётчики и состояние индекса, никогда пути и исходники. `project revision pull` читает redacted-узлы, которые уже опубликовал другой device. Ни одна из этих команд не двигает указатели `ProjectLink`; это `project sync plan`, затем `project sync apply`. План `local_to_remote` отклоняется, пока ревизии нет в ledger организации. Флаги, подтверждение и схемы результата берите из `ai-stp help --agent --json`. Не копируйте их сюда. ## Что содержит успешный конверт Discover, index и symbols каждый возвращают поля, названные в своих разделах. `project passport` возвращает поля вида паспорта. Каждый конверт также несёт `ok`, `warnings`, `next_actions`, `request_id`, `operation_id` и `schema_version`. Домашние пути в полях `root` и `path` свёрнуты для отображения. Это не другой каталог на диске. ## Чего эти команды никогда не делают - не сканируют домашний каталог и не весь диск; - не держат секретное или двоичное содержимое файлов в индексе; - не строят граф вызовов, граф пакетных зависимостей и embedding модели; - не собирают сетап и не пишут target harness; - не кладут токены и тела `.env` в паспорт проекта. ## Типичные отказы | Что видно | Что это значит | Что делать | | --- | --- | --- | | `AI_STP_VALIDATION_ERROR` нет `--root` | discover, index, symbols и passport его требуют | передать `--root <root>` | | `AI_STP_VALIDATION_ERROR` home directory | discovery отказывается сканировать home | назвать каталог проекта внутри него | | `state: partial` на index или symbols | сработала граница размера, глубины, числа записей или времени | читать `stopped_by`; не считать ответ полным | | `complete: false` на discover | сканирование остановилось внутри границ | читать `diagnostics` | | `AI_STP_VALIDATION_ERROR` unreadable root | пути нет или его нельзя прочитать | передать точный существующий корень проекта | | ожидание, что `index` запишет паспорт | индексация — чтение | `project passport --root <root> --json` | | `AI_STP_PRECONDITION_FAILED` нет паспорта для публикации | revision push проецирует локальный паспорт | `project passport --root <root> --json` | | `AI_STP_PRECONDITION_FAILED` заново наблюдать project link | пустой мигрированный `link_id` — не привязка | `project link show`, затем та же команда | | `AI_STP_PRECONDITION_FAILED` ревизии нет в ledger организации | `--local-revision` плана — не id ledger | `project revision push`, затем план с `revision_id` квитанции | ## Связанные страницы | Страница | Зачем | | --- | --- | | [Паспорта](passport.md) | как читать вид паспорта | | [Конфигурация](config.md) | `projects.discovery_roots` | | [Выбор](select.md) | паспорт проекта якорит сессию | | [Target](target.md) | ежедневное состояние одного проекта и harness | | [Команды компонента](component.md) | нативные компоненты внутри проекта | | [Быстрый старт для человека](../quickstart/human.md) | путь первого запуска не требует проекта | !!! note "Флаги из `ai-stp help --agent --json`" Если `help --agent` расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора. Discover, index, symbols и passport требуют `--root`. Revision push и pull — нет.