Архитектура

Как расширения загружаются и исполняются в artiroute.

Компоненты

Компонент	Пакет / путь	Роль
Extension SDK	@artiroute/extension-sdk	Реестры, resolve, bootstrap API
Extension Build	@artiroute/extension-build	Vite-сборка frontend/backend/ai
Backend host	apps/backend/src/modules/extensions/	Discovery, migrations, Feathers, hotplug
Frontend host	apps/frontend/src/shared/extensions/	Host modules, bootstrap, UI bridges
AI host	apps/ai-agent-service/	Загрузка AI drivers и artifact types
Data dir	apps/backend/data/extensions/	Установленные расширения (runtime)

Bootstrap (frontend)

sequenceDiagram
  participant App as Frontend App
  participant API as Backend /api/extensions
  participant SDK as extension-sdk
  participant Ext as extension frontend/index.js

  App->>API: GET список расширений
  App->>SDK: resolveExtensionsForLoad
  SDK->>SDK: topo-sort по dependencies
  loop каждое расширение
    SDK->>Ext: dynamic import
    Ext->>SDK: setup(ctx) — register entries
  end
  App->>App: UI читает реестры

1. Frontend запрашивает список включённых расширений у backend
2. resolveExtensionsForLoad валидирует manifest, implied dependencies, semver
3. initializeExtensions импортирует entry каждого target и вызывает setup(ctx)
4. Компоненты хоста читают реестры (AppSidebar, WidgetRenderer, ExtensionSlotHost, …)

Bootstrap (backend)

Backend host (extension-host.ts):

1. Discovery — сканирует data/extensions/, читает manifest.json
2. Readiness — проверяет targets, .install-complete
3. Migrations — выполняет registerMigration из backend setup в schema ext.*
4. Feathers — монтирует registerService routes
5. Hotplug — reload/unload отдельных расширений без полного рестарта (API events)

Bootstrap (AI)

AI-agent-service загружает ai/index.js расширений и регистрирует:

• ai.artifactTypes — метаданные генерации (schema, prompts)
• ai.artifactDrivers — session content, tools, validate/finalize

См. AI: artifact drivers.

Platform Core (backend)

После bootstrap backend extensions могут регистрировать:

• backend.spaceAbilities / backend.spaceRoles
• backend.entityFields
• backend.entityHooks

Подробно: Platform Core.

Implied dependencies

Если расширение B в manifest указывает:

"extendsRegistries": [{ "registryId": "@owner/custom.actions", "keys": ["x"] }]

и реестр @owner/custom.actions объявлен расширением A (declaresRegistries), то B автоматически получает зависимость A: '*'. Setup A выполнится раньше B.

Реестры из KNOWN_HOST_REGISTRY_IDS (например app.sidebar, app.widgets) не создают implied dependency — их объявляет хост.

Expose между расширениями

Расширение может опубликовать API для других:

export default defineExtension((ctx) => {
  ctx.defineExpose({ doSomething: () => {} });
});

Другие расширения: getExtensionExpose('@owner/ext-id').

Сборка frontend bundle

Frontend target собирается как ES lib с host-shims:

• vue, primevue, axios и др. не попадают в bundle
• Subpath imports (primevue/tag) — catch-all shims через @artiroute/extension-build

Подробнее: Host-модули.

Версионирование

• extensionApi: "1" — major API SDK; несовместимость блокирует загрузку
• engines.host — semver-диапазон версии хоста
• extensionDependencies — semver между расширениями

См. Манифест.