Проект

Проект в 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 берут идентификатор локального проекта и связь организации.

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

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

Перечислить проекты внутри названного каталога. Больше ничего не сканирует.

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

Проиндексировать один корень проекта, ограниченно, пропуская секреты и двоичное содержимое.

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

Прочитать публичные символы проекта, точки входа и тесты. Графа вызовов нет.

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 и конфигурацию.

ai-stp project passport --root <root> --json

Результат — вид паспорта (kind равен project) с stable_id, revision_id, parent_revision_ids, owner_id, facts, created_at и schema_version. Как читать эту форму — Паспорта.

Факты закрепляют то, что наблюдали, а не то, что вы хотели бы видеть. Изменить дерево и записать снова — добавить ревизию. Предыдущую это не правит.

Локальный паспорт не находится в 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 квитанции

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

Страница	Зачем
Паспорта	как читать вид паспорта
Конфигурация	projects.discovery_roots
Выбор	паспорт проекта якорит сессию
Target	ежедневное состояние одного проекта и harness
Команды компонента	нативные компоненты внутри проекта
Быстрый старт для человека	путь первого запуска не требует проекта

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

Если help --agent расходится с флагом на этой странице, прав CLI. Необязательные флаги здесь не перечислены. Читайте их из дескриптора. Discover, index, symbols и passport требуют --root. Revision push и pull — нет.