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

Разобрать, разрешить и искать внешние источники компонента, читать GitHub-архивные evidence.

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

Эти команды считают внешний источник компонента недоверенным структурированным 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

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

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

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

Отказы

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

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

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

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

ai-stp task intents --json

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

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