ai_stp

# Компоненты Компоненты — строительные части сетапа. Каждый компонент имеет вид, версию, происхождение, ограничения совместимости и паспорт. Один вид не подменяет другой. MCP-сервер остаётся `mcp`, а инструкция по его использованию остаётся содержимым `instruction` или `skill`. Память, правила, параметры и вспомогательные инструменты — содержимое `instruction`, `skill` или `setting`. Это не отдельные виды. `marketplace` — нативная упаковка, не вид компонента. Исполняемый файл — `ai-stp` (пакет `ai-stp-cli`). Всегда передавайте `--json`. Команд `component inspect` и `setup show` нет. Единственный kind-specific validate — `ai-stp component skill validate`. ## Девять глав У каждого вида своя страница. Читайте главу до scaffold или adopt этого вида. Главы держат одну формулу: вопрос, на который вид отвечает, чем он не является, таблица соседей, рекомендуемый пакет, нативные layout, какие проверки реально бегут, путь CLI, затем красные флаги. Сравнивайте виды по этому каркасу; не учите новую форму на каждой странице. | Вид | Глава | Вопрос, на который она отвечает | | --- | --- | --- | | `instruction` | [`instruction`](instruction.md) | что агент должен держать в уме, пока работает? | | `skill` | [`skill`](skill.md) | как агент должен делать этот класс задач? | | `mcp` | [`mcp`](mcp.md) | какой внешний tool-интерфейс подключён? | | `hook` | [`hook`](hook.md) | что должно выполниться автоматически, когда происходит это событие? | | `command` | [`command`](command.md) | какую проверяемую операцию можно вызвать по имени? | | `agent` | [`agent`](agent.md) | какая именованная роль должна нести этот класс работы? | | `plugin` | [`plugin`](plugin.md) | какой пакет расширяет сам харнесс? | | `setting` | [`setting`](setting.md) | какие несекретные параметры нужно закрепить? | | `cli` | [`cli`](cli.md) | какой общий исполняемый файл запускать как процесс? | Столкновения имён, которые главы разбирают отдельно: - вид `skill` против CLI Agent Skill (`ai-stp skill install`); - вид `plugin` против marketplace; - MCP-**сервер** против **клиентского конфига** `.mcp.json` plugin; - `AGENTS.md` (instruction) против вида `agent`. Точные нативные пути даёт конверт intent `author`. У каждой находки есть `layout_source`. Не выдумывайте путь соседа. ## Быстрый выбор | Если нужно | Вид компонента | Почему | | --- | --- | --- | | Добавить правила, память или стиль работы | [`instruction`](instruction.md) | это текстовая политика для агента или харнесса | | Описать повторяемый агентский workflow | [`skill`](skill.md) | skill хранит процедуру, материалы и вспомогательные скрипты | | Подключить внешний инструмент к агенту | [`mcp`](mcp.md) | MCP даёт агенту управляемый интерфейс к сервису или локальному tool | | Выполнить действие на событии харнесса | [`hook`](hook.md) | hook привязан к жизненному циклу и требует осторожности | | Дать человеку или агенту именованную команду | [`command`](command.md) | command делает повторяемый вход понятным и проверяемым | | Добавить роль или специализированного subagent | [`agent`](agent.md) | agent описывает область ответственности и ограничения роли | | Расширить сам харнесс пакетом | [`plugin`](plugin.md) | plugin устанавливает нативное расширение харнесса | | Зафиксировать параметры и режимы | [`setting`](setting.md) | setting хранит конфигурацию без секретов и без поведения | ## Матрица компонентов | Вид | Что содержит | Что проверяет `ai_stp` | Типичный риск | | --- | --- | --- | --- | | `instruction` | Markdown, правила, память, ограничения | происхождение, версию, совместимость, область действия | слишком широкие или противоречивые правила | | `skill` | `SKILL.md`, assets, scripts, references | структуру, совместимость, исполняемые помощники | скрытые side effects в скриптах | | `mcp` | описание MCP-сервера и способ запуска | источник, разрешения, отсутствие секретов в паспорте | внешний доступ к данным или инструментам | | `hook` | событие, действие, условия запуска | событие, target, восстановление, подтверждение | автоматическое изменение состояния | | `command` | slash/CLI-команду и аргументы | имя, область, help, конфликт команд | неоднозначный или опасный shortcut | | `agent` | роль, инструкции, ограничения | границы роли, совместимость, права | слишком широкие полномочия subagent | | `plugin` | нативное расширение харнесса | пакет, версию, источник, install route | supply-chain и post-install поведение | | `setting` | параметры, режимы, preferences | допустимые значения и отсутствие секретов | утечка приватных данных или дрейф конфигурации | Процент карточки каталога и разделение обязательных и необязательных проверок — на странице [Проверки безопасности](../security-checks.md). `author_verified` и `component_verified` — независимые оси. Ни одно не является гарантией безопасности. ## Как компонент попадает в сетап === "1. Паспорт" Компонент описывается паспортом: вид, версия, источник, совместимость, ограничения и результаты проверок. Паспорт — это то, что может читать CLI, каталог и agent. === "2. Кандидат" `ai_stp` выбирает кандидатов из публичного каталога, локального реестра или точно закреплённых пользовательских объектов. Линия доверия влияет на то, можно ли показывать и устанавливать объект автоматически. === "3. Граф сетапа" Сборщик сетапа строит граф компонентов и проверяет, что версии, харнесс, зависимости и ограничения совместимы между собой. === "4. Provider" Итоговое состояние target пишет только публичный provider конкретного харнесса. Перед изменением создаются план, digest и резервная копия. ??? warning "Почему нельзя просто скопировать файлы в target" У разных харнессов отличаются форматы, каталоги, правила безопасности и жизненный цикл. Прямое копирование ломает provenance и rollback. Поэтому `ai_stp` сначала строит проверяемый план, а уже затем передаёт применение provider-слою. Типичный локальный путь: ```bash ai-stp task start --intent author --idempotency-key author-session-01 --json ai-stp task start --intent publish --idempotency-key publish-session-01 --json ``` Общие `.agents/skills` возвращаются один раз, с `harness_id=null`. Пакет MCP-сервера также не принадлежит ни одному харнессу. `undefined` владеет только переносимыми соглашениями; автоматическая установка не считается безопасной. ## Версии Публикуемая версия компонента неизменяема и имеет формат `X.Y`. Патч-номера нет. Если меняется содержимое, появляется новая версия. Обновление компонента внутри сетапа — новая версия сетапа. `--major` у `component version release` открывает следующую мажорную линию, которая является отдельной границей доступа. ## Совместимость Компонент может подходить одному харнессу и быть недопустимым для другого. Механические ограничения совместимости применяются до рассуждений агента. Покрытие discovery различается по харнессам и видам. Ограниченная матрица layout и `layout_source` живут в каждой главе вида и в `ai-stp toolchain harness-capabilities --json`. | Харнесс | Объявленные виды (ограниченная матрица) | | --- | --- | | Claude Code | global и project: instruction, skill, agent, command, setting, MCP, plugin | | Codex | global: instruction, command/prompt, setting, общий skill; project: instruction, setting, agent, hook, общий skill | | Pi | global: instruction, skill, plugin, command, setting; project: skill, plugin, command, setting | | OpenCode | global и project: skill, agent, command, plugin, setting | | Grok Build | global: skill, plugin, hook, setting, общий command; project: skill, plugin, hook, setting | | Cursor | global: instruction, setting, plugin; project: instruction, plugin | | Antigravity | global: setting, plugin, skill, agent, hook, MCP; project: plugin, skill, agent, hook, MCP | | `undefined` | только переносимые соглашения; автоматическая установка не считается безопасной | Plugin packs, доказанные точным манифестом, могут нести вложенных членов других видов. Эти члены сохраняют свои виды. Подробности — на [`plugin`](plugin.md), [`mcp`](mcp.md) и [`hook`](hook.md). Подробнее про статусы: [поддерживаемые харнессы](../harnesses.md). Как готовить дерево: [Авторство](../publishing/authoring.md). Линии доверия: [Доверие и безопасность](../trust-and-safety/index.md). Инвентарь сканов безопасности: [Проверки безопасности](../security-checks.md). CLI discovery: [Обнаружение и adopt](../cli/component-discover.md). ## Связанные страницы - [Сетапы](../setups/index.md) — точные pins этих видов. - [Каталог](../catalog/index.md) — как карточка называет вид. - [Быстрый старт для человека](../quickstart/human.md) — первое чтение каталога. - [Команды компонента](../cli/component.md) — discover → passport → publish.