Troubleshooting

Частые проблемы при разработке расширений и их решения.

PrimeVue без стилей

Симптом: кнопки/карточки рендерятся, но без темы PrimeVue — «голый» HTML.

Причина: PrimeVue или его CSS попали в bundle extension вместо host shim, либо импортирован CSS в extension.

Решение:

1. Импортируйте компоненты через primevue или primevue/component — не копируйте source PrimeVue
2. Не импортируйте primevue/resources/... CSS в extension
3. Проверьте размер bundle — должен быть ~10–20 KB, не 80+ KB
4. Убедитесь, что ahExtensionFrontendViteConfig используется в vite.config.ts

См. Host-модули, Стили.

Template.artifactType: value is not an accepted option

Симптом: ошибка при создании Template с типом extension (notes-doc, registry-test-doc).

Причина: поле artifactType в Keystone list Template было hardcoded select (document/table/bpmn).

Решение: в core backend Template.artifactType — text field; extension types регистрируются через app.artifactTypes. Перезапустите backend после обновления schema.

Проверьте, что key в app.artifactTypes совпадает со значением в Template.

AI: generation works, finalize/save fails (auth)

Симптом: агент генерирует контент, но сохранение ArtifactVersion падает с authorization error.

Причина: finalize от service token требует author.connect.id, не только session user id.

Решение: убедитесь, что backend актуален (ArtifactVersion validateInput принимает service token). Перезапустите backend и ai-agent-service.

Пустой createTools — агент не редактирует

Симптом: AI session стартует, но нет tools для правки текста.

Причина: driver не реализует createTools, и fallback не срабатывает.

Решение: для plain-text artifacts:

1. buildSessionContent должен возвращать { text: string }
2. Либо оставьте createTools() { return {} } — host добавит plain-text tools
3. Либо реализуйте explicit tools как в project-notes/text-driver.ts

См. Artifact drivers.

Failed to resolve import "primevue/..."

Симптом: сборка extension падает на subpath import.

Причина: prefix не в HOST_SUBPATH_PREFIXES.

Решение:

1. Проверьте, что prefix есть в packages/extension-build/src/host-subpath-shim-plugin.ts
2. Если новый пакет — добавьте prefix + host registration (PR)
3. pnpm extension-build:build

Extension не появляется в UI

Чеклист:

• [ ] pnpm build:extensions && pnpm install:extensions
• [ ] Файл apps/backend/data/extensions/<slug>/.install-complete существует
• [ ] manifest.json в data dir содержит frontend entry path
• [ ] Keys в manifest extendsRegistries совпадают с .register() keys
• [ ] Backend запущен — frontend получает список extensions через API
• [ ] Console browser — ошибки dynamic import /extensions/.../frontend/index.js

Duplicate Vue / "inject() can only be used..."

Причина: Vue забандлен в extension вместо host singleton.

Решение: проверьте external/shim config; не добавляйте vue в dependencies extension (только peer + dev for types).

Conflict: registry key already claimed

Симптом: resolveExtensionsForLoad error — key занят другим extension.

Решение: используйте уникальный key (prefix extension id: my-ext-sidebar). Проверьте extendsRegistries на дубликаты между extensions.

Backend migration failed

Симптом: extension не загружается, ошибка Kysely migration.

Решение:

1. Проверьте SQL в up() — schema ext.*, valid FK references
2. Лог backend при bootstrap
3. Для dev: drop table ext.my_table и re-run (осторожно с data)

Bundle слишком большой

pnpm build:extensions
# inspect packages/extensions/my-ext/dist/frontend/index.js

Если > 50 KB — вероятно bundling host libs. Audit imports: Зависимости.

Cannot POST /api/... (404 HTML) на демо или под-пути

Симптом: LDAP login, комментарии или другой extension API возвращает Cannot POST /api/... вместо JSON.

Причина: frontend extension вызывает fetch('/api/...') или window.location.href = '/dashboard' без учёта BASE_URL (например /demo на демо-стенде).

Решение:

1. Auth: getProviderLoginUrl из @artiroute/host/auth
2. GraphQL / REST / файлы: @artiroute/host/api (getGraphqlUrl, fetchGraphql, getExtensionApiUrl, withAppBase)
3. Пересоберите extension: pnpm build:extensions, переустановите на инстансе
4. Убедитесь, что хост зарегистрировал @artiroute/host/api (актуальный frontend)

Проверка: pnpm lint:extensions-api — скрипт ищет хардкод '/api/ в packages/extensions/**/frontend.

Где искать help

• Быстрый старт
• Reference: project-notes, registry-test
• Builder: packages/extension-build/README.md
• SDK types: packages/extension-sdk/src/extension/index.ts