Глоссарий и источники

Здесь — определения терминов из анатомии плагинов, фронтенд-поверхностей и предметной области, а также названия, которых нет в bb, и ссылки на исходники в репозитории bb.

Анатомия плагина

Термин	Значение
manifest	`package.json` плагина, ключ `bb`. Не отдельный файл
plugin id	Берётся из имени пакета (последний сегмент без `bb-plugin-`, в нижнем регистре, символы кроме букв и цифр заменяются на `-`). Служит неймспейсом для маршрутов, хранилища, настроек и CLI
server entry	`bb.server`; обязательная серверная точка входа, экспортируемая по умолчанию функция `(bb: BbPluginApi) => void`
host entry	`bb.host`; опциональная, единственная ESM-точка входа на Node 22 в демоне хоста. Работает с полным доверием
host worker	хост-воркер; дочерний процесс (fork) в демоне хоста, который запускает хостовую точку входа одного плагина для одного поколения
generation	Три разных смысла: эпоха загрузки модуля на сервере (`?bbPluginLoad=<rootId>.<epoch>`), `randomUUID()` хостового артефакта и счётчик монтирований клиента
artifact	Результат сборки (`server.js` / `app.js` / `host.js`) с собственным `*.meta.json`
bundled / official plugin	Плагин из поставки bb; поставляется внутри приложения и устанавливается из локальной копии, без сети. `bb-official` — зарезервированное имя маркетплейса
marketplace	Один файл `marketplace.json`, где перечислены плагины с брендингом магазина и npm/git-источником. Никогда не хостит код
collection manifest	`.bb/plugins.json` в корне репозитория, индексирует несколько каталогов плагинов. Это только индекс: не переопределяет ни идентичность, ни точки входа

Названия, которых нет

Три названия, которые читатели ожидают увидеть, но в bb их нет:

Файла bb-plugin.json не существует. Манифест — это package.json плагина, внутри ключа bb.

packages/plugin-registry — это не реестр плагинов, а реестр компонентов shadcn. Реестр установленных плагинов — таблица plugins в SQLite.

Хелпера definePlugin нет. Серверная точка входа — это экспортируемая по умолчанию функция.

В разделе Неймспейсы бэкенда перечислены неймспейсы, которые разработчики пытаются угадать, но в bb их нет.

Фронтенд-поверхности

Термин	Значение
surface	Продуктовая группировка, которую используют документация и карта API: `PluginSurface { id, title, summary, bullets, apiSymbols, … }` внутри семи объектов `SurfaceGroup` (`app-shell`, `command-palette`, `composer`, `home`, `settings`, `extensions`, `headless`)
slot	Точка регистрации в коде, `app.slots.*`. Их 22; полный список — во фронтенд-API
additive / replacement / exclusive	Аддитивные слоты стоят рядом; замещающие при падении откатываются к рендереру bb; `experimental_threadList` — единственный эксклюзивный слот (один список заполняет область прокрутки)
content script	Доверенный JS/TS того же источника (same-origin), монтируется один раз на активное фронтенд-поколение для каждого окна или вкладки, без React-слота. Строго не песочница
nav panel	Слот, который владеет всем маршрутом `/plugins/<pluginId>/<path>/*` и получает собственную строку в боковой панели; компонент принимает `{ subPath }`
fixed tab	Упорядоченная, незакрываемая страница в хостовой панели вкладок у панели навигации: `{ id, panelId, title, icon, component, layout?, experimental_target? }`, где `panelId` должен совпадать с `id` панели
thread panel action	Пункт в списке Actions на правой панели треда; `run({ threadId, openPanel })` решает, что открыть
message directive	Листовое встраивание внутри Markdown от ассистента; `id` — имя директивы, поэтому `inline-vis` совпадает с `::inline-vis{file="demo.html"}`. Атрибуты не считаются доверенными
timeline entry / row	Персистентные строки, из которых состоит транскрипт. Рендерер получает `PluginTimelineRendererRow`, где `kind` равен `"tool"` или `"<pluginId>/<name>"`, а статус — `"pending" \| "completed" \| "error" \| "interrupted"`. `ThreadChatMessageReference` явно не внутренняя строка таймлайна
interaction	Форма в треде, которую бэкенд запрашивает через `bb.ui.requestInput`, а отрисовывает слот `pendingInteraction`. bb хранит только собственный `PluginInteractionDescription` плагина, но не полезную нагрузку и не отправленное значение
composer	Поле ввода чата. «Composer customization» — это `{ id, scopes?, actions?, plusMenu?, banners?, richText? }`; `scope` принимает значения `"thread" \| "queued-message" \| "side-chat" \| "new-thread"`
crash chip	Плашка «plugin `<id>` crashed», которую аддитивный слот рендерит после срабатывания своего предохранителя

Бэкенд и предметная область

Термин	Значение
thread	Единица работы; содержит одну беседу с провайдером, имеет состояние жизненного цикла и генерирует поток событий, куда можно только добавлять (append-only). Стандартный тред делает работу сам, тред-менеджер координирует другие треды
turn	Один обмен «message sent → provider». Повторную попытку запрашивают по ссылке (`bb.sdk.threads.retry`), а не отправкой сообщения заново
dispatch	Контрольная точка, которую сообщение проходит на пути к провайдеру. На неё реагирует `bb.experimental_hooks`: продолжить, поставить в очередь с указанием причины или отклонить. Пользовательский send-now обходит её намеренно. `PluginDispatchAttemptKind = "start-turn" \| "join-turn"`
event vs hook	События — объявления от ядра, возвращаемое значение обработчика игнорируется; хуки — вопросы, на которые ядро реагирует. «The same split git draws between post-commit and pre-commit hooks»
environment	Контекст выполнения треда, привязывающий рабочий каталог к хосту. Неуправляемое окружение указывает на существующий каталог; управляемое удаляется, как только его перестают использовать неархивированные треды
host	Долгоживущий идентификатор демона машины, которая выполняет работу. Собственный хост сервера — `primaryHostId`
machine	То, что выделяет провайдер машины: машина-исполнитель, в отличие от записи `host`, которая идентифицирует её демона
provider	Перегруженный термин, в коде всегда уточняется. Провайдер агента (`bb.providers.register`) поставляет рантайм модели; провайдер окружения предоставляет место для треда; провайдер машины выделяет машину; провайдеры упоминаний и инструкций дополняют UI и агента
`lifecycleOwnerThreadId`	Неизменяемая, опциональная ссылка на создание, независимая от `parentThreadId` в боковой панели, `sourceThreadId` у форка, видимости и атрибуции. Архивирование и удаление владельца применяются рекурсивно; владение нельзя обновить или удалить
skill	Каталог `skills/<name>/SKILL.md`, который внедряется в треды агента как слой скиллов плагина; `bb.skills` перемещает корень, а `[]` отключает их
status detail	Человекочитаемая строка рядом с `PluginRuntimeStatus`, собранная из базового статуса, проблем со сборкой в dev-режиме, коллизий инструментов агента и проблем с бандлом приложения

Источники: где искать правду

Контракты и карта API

packages/plugin-sdk/src/backend-contract.ts: BbPluginApi
…/app-contract.ts: фронтенд · host-contract.ts · rpc-contract.ts
packages/plugin-api-map/src/surfaces.ts: 7 групп, 46 поверхностей; product-map.tsx (SURFACE_NUMBERS), wireframes.tsx, anatomy-manifest.json
docs/api_to_audit.md: реестр экспериментальных членов и правило отказа от префикса

Рантайм и сборка

apps/server/src/services/plugins/plugin-runtime.ts · plugin-api.ts · routes/plugins.ts
apps/app/src/lib/plugin-frontend.ts · PluginSlotMount.tsx
apps/host-daemon/src/plugin-host-manager.ts · plugin-host-worker.ts
packages/plugin-build/src/runtime-shims.mjs · scope-plugin-utilities.ts · plugin-artifact-meta.ts

Собственные скиллы bb (документация по разработке внутри репозитория)

plugins/bb-guide/skills/bb-plugin-authoring/, с SKILL.md и references/: quickstart.md, backend-foundation.md, backend-events.md, backend-cli-agents.md, backend-sdk.md, backend-ui-lifecycle.md, backend-machines.md, frontend-core-slots.md, frontend-registration.md, frontend-components.md, frontend-hooks-and-ui.md, frontend-renderer-slots.md, providers.md, distribution.md, testing.md
plugins/bb-guide/skills/bb-cli/: references/plugins.md, command-index.md
plugins/bb-guide/skills/submit-a-plugin/: как отправить плагин в community-маркетплейс

Документы и сгенерированные типы

docs/system-overview.md · lifecycle-diagrams.md · environment-provisioning.md · provider-bridge-protocol.md · provider-plugin-api.md · configuration.md · worktrees.md
bundled-types: после npm install актуальная поверхность API находится в node_modules/@get-bb/plugin-sdk/bundled-types/bb-plugin-sdk.d.ts (с комментариями), плюс -app.d.ts и -host.d.ts. Типы генерируются через rollup + rollup-plugin-dts и не коммитятся в git; если плагин не может разрешить SDK, выполните pnpm exec turbo run build:types --filter=@get-bb/plugin-sdk.
Никогда не отвечайте на вопросы об API по собранному бандлу: бандл приложения минифицирован, у сервера и хоста есть sourcemaps, но контракт — это декларации и исходники.

Ни один факт здесь не получен запуском кода: всё это статическое чтение на закреплённом релизе. Отдельно отмечены: отсутствие байтового лимита на RPC плагина; имена bb.sdk.hosts.experimental_* и наличие threads.listRunning() в документации; поведение experimental_contributeEnv и experimental_contributeEnvHealth (ни одного вызова в плагинах из поставки bb); experimental_environments.recheck() и PLUGIN_CLI_OUTPUT_MAX_BYTES (ноль вызовов); bb.http.experimental_websocket (только тесты сервера); порядок цепочки хука диспетчеризации и «single server lock» (комментарий в контракте, а не прочитанная реализация); экранирование ключей секретов в пути; количество ACP-диалектов относительно документации; кэширование availability окружения; абсолютный путь бинарника bb в сборке для macOS; и то, как мобильный клиент загружает бандлы приложения плагина (и загружает ли вообще).