Источник компонента

Эти команды считают внешний источник компонента недоверенным структурированным intent, пока не привязан commit, и хранят официальные архивные наблюдения GitHub для одной точной локальной версии.

Parse ничего не скачивает. Resolve привязывает один полный commit SHA. Поиск имён не выбирает кандидата. Команды evidence говорят об архивном состоянии репозитория, а не о том, безопасна ли версия.

Повседневная регистрация — intent author. Source parse/resolve/search и evidence ниже — expert recovery.

ai-stp task start --intent author --idempotency-key author-session-01 --json

Таблица команд

Команда	Mutability	Confirmation	Когда
ai-stp component source parse	read	none	разобрать slug, GitHub-идентичность, локальный путь или коллекцию
ai-stp component source resolve	read	none	привязать GitHub-intent к одному точному полному commit SHA
ai-stp component source search	read	none	искать имена в каталоге; package и GitHub — по флагу
ai-stp component source evidence refresh	apply	none	обновить официальные архивные наблюдения GitHub для одной версии
ai-stp component source evidence show	read	none	показать последние локальные архивные наблюдения и freshness
ai-stp component source evidence history	read	none	ограниченная append-only история архивных наблюдений

--json глобальный. Всегда передавайте его.

Parse

Разобрать строку внешнего источника как структурированный intent. Результат недоверенный, пока resolve (или другое точное доказательство) его не привяжет.

ai-stp component source parse --source owner/repo --json
ai-stp component source parse --source https://github.com/owner/repo --json
ai-stp component source parse --source ./hooks/check --root . --json

--source обязателен. Это может быть опубликованный slug, GitHub- идентичность, локальный путь или коллекция. --root нужен только чтобы нормализовать относительный локальный путь.

Поля успеха: kind, canonical, owner, ref, local_path, collection_owner, collection_handle и provenance_proven. kind — одно из published, github, github/exact, local, collection. provenance_proven остаётся false, пока точная идентичность не доказана.

Resolve

Resolve привязывает GitHub shorthand или credential-free HTTPS URL к одному lowercase SHA коммита из 40 символов.

ai-stp component source resolve --source owner/repo --json
ai-stp component source resolve \
  --source https://github.com/owner/repo \
  --commit abcdef0123456789abcdef0123456789abcdef01 \
  --json

--commit необязателен: опустите, чтобы разрешить названный ref в SHA, или передайте точный SHA, который уже есть. --root только нормализует относительный локальный путь.

Ответ той же схемы идентичности, что у parse. После успешного resolve kind равен github/exact, а provenance_proven — true. Диапазон, плавающий tag без SHA или URL с учётными данными отклоняются.

Search

Поиск только по имени. Он никогда не выбирает кандидата и ничего не устанавливает.

ai-stp component source search --query context7 --json
ai-stp component source search --query context7 --registry-discovery --json

Без --registry-discovery попадания — имена каталога. С флагом добавляются поддерживаемые имена пакетов и известные GitHub-кандидаты. У каждого попадания отдельно держатся source, catalog_status, trust_lane, author_verified и component_verified. GitHub-попадание со статусом not_in_catalog всё равно только имя.

Поля успеха: список кандидатов с name, source (catalog, package или git), exact_coordinate, stable_id, catalog_status, trust_lane, author_verified, component_verified.

Evidence show, refresh, history

Архивные наблюдения GitHub — официальное наблюдение исходного репозитория: архивирован ли он, когда наблюдение скачали, и свежо ли оно. Это не скан безопасности.

ai-stp component source evidence show --id <stable_id> --version 1.0 --json
ai-stp component source evidence refresh --id <stable_id> --version 1.0 --json
ai-stp component source evidence history --id <stable_id> --version 1.0 --json
ai-stp component source evidence history --id <stable_id> --version 1.0 --limit 20 --json

--id и --version обязательны. --version — точный записанный X.Y. --limit в history — сколько новейших наблюдений вернуть, от 1 до 100.

refresh — apply: пишет новое наблюдение. У него confirmation: none. Назвать точные id и версию и есть решение.

Поля успеха show и refresh: stable_id, version, passport_digest, source_repository, repository_id, repository_full_name, repository_state, archived, fetched_at, expires_at, freshness, observation_id. freshness — fresh, stale или unavailable. repository_state — active, archived или unavailable. History возвращает ограниченный список этих наблюдений.

Happy path

Повседневный путь:

ai-stp task start --intent author --idempotency-key author-session-01 --json

Expert recovery:

component source parse --source owner/repo
→ component source resolve --source owner/repo
→ component source search --query <name>
→ setup update plan  or  component adopt

Для уже выпущенной версии:

component source evidence show --id <id> --version 1.0
→ component source evidence refresh --id <id> --version 1.0   # если stale
→ component source evidence history --id <id> --version 1.0

Именованные поля успеха

Команда	Какие поля читать
parse / resolve	kind, canonical, provenance_proven, ref
search	у каждого кандидата name, source, catalog_status, trust_lane
evidence show / refresh	freshness, archived, repository_state, fetched_at
evidence history	ограниченный список наблюдений

Отказы

Что видно	Что это значит	Что делать
AI_STP_VALIDATION_ERROR	нет --source, --id или --version, или значение неверно	исправить запрос; диапазон — не версия
AI_STP_NOT_FOUND	локального объекта или версии нет	component version list --id <id>
AI_STP_DEPENDENCY_UNAVAILABLE	GitHub или реестр недоступны	повторять только если retryable: true; иначе работать из cache
AI_STP_PRECONDITION_FAILED	источник — не credential-free GitHub-идентичность	убрать учётные данные; HTTPS без userinfo
freshness: stale	последнее наблюдение истекло	evidence refresh для этой точной версии
freshness: unavailable	официальный архив наблюдать не удалось	прочитать repository_state; не выдумывать замену
поиск без --registry-discovery	полосы package и GitHub не запрашивались	передать флаг, если эти полосы имелись в виду
считать попадание поиска pin	поиск никогда не выбирает	дальше resolve или plan точной координаты

Не кладите токены в --source. Нигде в этой группе не передавайте NAME=value. Не выдумывайте --commit у parse: эта опция есть только у resolve.

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

• Команды компонента
• Обнаружение и adopt
• Паспорт компонента
• Публикация компонента
• Команды сетапа
• Реестр
• Публикация

Флаги берутся из continuation argv

ai-stp task intents --json

Не дампьте help --agent как прелюдию. Флаги текущей задачи — в continuation argv.

Эта страница группирует команды источника, чтобы человек их нашёл. Если страница и CLI расходятся, следуйте CLI.