Обнаружение и adopt

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

Повседневная регистрация нативного дерева — intent author. Discover и adopt ниже — expert recovery.

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

Discovery сообщает пути, не открывая файлы с секретными именами, чтобы узнать содержимое. Adopt пути — явное действие: он регистрирует один найденный компонент в локальном реестре. Forget помечает запись удалённой и сохраняет историю.

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

Команда	Mutability	Confirmation	Когда
component discover	read	none	перечислить нативные компоненты в названном проекте или в корнях harness, если проект не назван
ai-stp component inventory	read	none	паспорт-первый инвентарь одного явного дерева авторства
ai-stp component find	read	none	искать в локальном реестре по prefix, phrase, tag или field
component scaffold plan	plan	none	показать точные файлы и digest одного версионированного scaffold
component scaffold apply	apply	plan_digest	создать ровно подтверждённый scaffold; путь не перезаписывать
ai-stp component template render	read	none	отрендерить и проверить portable-шаблон для одного harness
component adopt	apply	none	зарегистрировать один найденный компонент в локальном реестре
ai-stp component forget	apply	none	пометить зарегистрированный компонент удалённым, историю сохранить

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

Expert recovery: discover

discover без --root сканирует корни harness. С --root он смотрит только внутрь этого каталога и не добавляет глобальные home. Ничего не меняет. Путь, похожий на секрет, помечается по имени, а не потому что файл открыли.

inventory --root сначала читает паспорта авторства, затем нативные раскладки, и не считает сгенерированные projections/ независимыми источниками.

Если complete ложно, передайте возвращённый continuation как --cursor с тем же --root. Усечённый список нельзя считать исчерпывающим.

ai-stp component discover --json
ai-stp component discover --root . --json
ai-stp component inventory --root . --json

Поля успеха: components, diagnostics, project, schema_version. У каждого компонента есть candidate_id, component_type, layout_source, native_role, source_path, harness_id, holds_secret, byte_length, entry_points, evidence_refs и registered_stable_id.

Пустой список components — типизированная пустота, не отказ. Он не запускает молча device init и ничего не adopt.

Find

find ищет объекты, уже лежащие в локальном реестре. Без модели и без сети. Непроверенные попадания скрыты, пока не передадите --include-unverified только для этого вызова. Флаг никогда не сохраняется.

ai-stp component find --prefix demo --json
ai-stp component find --phrase "playwright" --tag mcp --json
ai-stp component find --field kind --value skill --include-unverified --json

--tag повторяемый: каждый названный tag должен совпасть. --field и --value вместе точно совпадают с одним объявленным полем.

Поля успеха: hits (у каждого stable_id, lane и fields) и schema_version.

Expert recovery: scaffold plan, затем apply

Scaffold — новый каталог авторства. Сначала plan. Apply создаёт ровно те файлы, которые назвал план, и отказывается перезаписать путь, который уже существует.

--type — одно из instruction, skill, mcp, hook, command, agent, plugin, setting, cli. --language — none для декларативных типов или одно из python, typescript, javascript, rust, go, dart-flutter. --harness — portable или конкретный harness: claude-code, codex, pi, opencode, grok-build, cursor, antigravity. --name — slug в нижнем регистре. --output — новый каталог.

Повседневное авторство:

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

Expert recovery (уже есть digest):

ai-stp component scaffold plan \
  --type skill \
  --language python \
  --harness portable \
  --name demo-skill \
  --output ./components/demo-skill \
  --json

Ответ плана несёт plan_id, plan_digest, output, component_name, descriptor и files. У каждого файла есть path, digest и byte_length. publication_ready равен false. Перед публикацией scaffold всё равно нужен точный источник.

Apply повторяет те же опции и добавляет --expected-plan-digest неизменённого плана. --confirm нет. Digest говорит, какой scaffold.

ai-stp component scaffold apply \
  --type skill \
  --language python \
  --harness portable \
  --name demo-skill \
  --output ./components/demo-skill \
  --expected-plan-digest sha256:... \
  --json

Ответ apply несёт plan_id, plan_digest, output и created. Если каталог уже есть, команда отказывается. Если digest больше не совпадает с пересчитанным планом, команда отказывается как stale.

Template render

Рендер portable UTF-8 шаблона для одного конкретного harness. Это read: он проверяет рендер. Нативные файлы он не пишет.

ai-stp component template render \
  --template ./templates/skill.md \
  --harness codex \
  --name demo-skill \
  --component-root components/demo-skill \
  --json

--harness здесь — harness из закрытого реестра, не portable. --component-root — ограниченный относительный POSIX-путь.

Expert recovery: adopt

Adopt пишет паспорт и сохраняет байты. Назвать --path точным путём из discovery и есть решение. --confirm нет.

ai-stp component adopt --path <exact-path> --json
ai-stp component adopt --path <exact-path> --root . --json

Если один путь отвечает более чем одному harness, назовите --harness. Для общей кросс-продуктовой претензии используйте portable. Если путь отвечает более чем одному kind, назовите --kind.

Ответ — вид паспорта: stable_id, kind, revision_id, parent_revision_ids, owner_id, created_at, facts, schema_version.

Forget

Forget помечает компонент удалённым в локальном реестре и сохраняет историю. Управляемые байты на target harness он не удаляет.

ai-stp component forget --id <stable_id> --reason "replaced by catalog pin" --json

--reason необязателен. Ответ той же формы, что у adopt.

Happy path

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

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

Expert recovery:

component discover --root .
→ component adopt --path <exact>
→ component passport show --id <stable_id>

Или для нового компонента:

component scaffold plan → scaffold apply --expected-plan-digest
→ component adopt --path <output>
→ component passport validate --id <stable_id>

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

Команда	Какие поля читать
discover	components, diagnostics, project
find	hits, у каждого stable_id и lane
scaffold plan	plan_id, plan_digest, files
scaffold apply	plan_digest, output, created
template render	payload отрендеренного шаблона
adopt / forget	stable_id, revision_id, kind, facts

Отказы

Что видно	Что это значит	Что делать
AI_STP_VALIDATION_ERROR	обязательная опция отсутствует или не из закрытого словаря	прочитать дескриптор; не выдумывать type или harness
AI_STP_NOT_FOUND	discovery этот путь не сообщал, или id неизвестен	снова discover или find
AI_STP_USER_DECISION_REQUIRED	путь заявлен более чем одним harness или kind	передать --harness и/или --kind
AI_STP_PLAN_STALE	байты scaffold больше не совпадают с --expected-plan-digest	снова plan, показать файлы, apply с новым digest
AI_STP_CONFLICT	apply перезаписал бы существующий путь	выбрать новый --output
пустой components	нативного ничего не найдено	это успех; не adopt угаданный путь
забыли --include-unverified	непроверенные локальные объекты скрыты	передать флаг только для этого вызова или оставить скрытыми

Не передавайте --confirm в adopt, forget или scaffold apply. Этих флагов нет в декларации. Scaffold apply подтверждается --expected-plan-digest.

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

• Команды компонента
• Паспорт компонента
• Источник компонента
• Публикация компонента
• Компоненты
• Проект
• Реестр
• Согласие

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

ai-stp task intents --json

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

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