SEAF Plugins Toolkit

CLI для разработки и сборки document plugins SEAF ArchTool. Один проект — один плагин. Toolkit устанавливается как dev dependency; создавайте проект отдельно от репозитория toolkit.

Быстрый старт

Нужны Node.js 22.12+ и npm 10.8.3+.

В репозитории toolkit выполните npm pack --ignore-scripts. Затем в отдельном каталоге создайте проект (замените путь к .tgz на фактический):

mkdir my-card
cd my-card
npm init -y
npm install --save-dev --save-exact /path/to/seaf-plugins-toolkit-0.1.0.tgz
npx seaf-plugin init my-card
npm install

init создаёт src/, plugin.json и vite.config.js, добавляет зависимости в package.json, но не устанавливает их — поэтому нужен второй npm install.

Команды

Запускайте из проекта плагина. CLI находит его корень по plugin.json; явно указать корень можно через --workspace /path/to/my-card.

| Команда | Что делает | |---|---| | npx seaf-plugin init [name] | Создаёт плагин; повторный запуск обновляет инструкции AGENTS.md, сохраняя исходники | | npx seaf-plugin dev | Собирает preview в .dev/ и пересобирает при изменениях | | npx seaf-plugin dev --once | Собирает preview один раз, без watcher | | npx seaf-plugin bundle | Собирает релиз и catalog.json в dist/ | | npx seaf-plugin clean | Удаляет только dist/, не затрагивая исходники и preview | | npx seaf-plugin portal up | Запускает Docker-портал для preview | | npx seaf-plugin portal down | Останавливает и удаляет контейнер портала | | npx seaf-plugin portal restart | Перезапускает портал для перечитывания manifests | | npx seaf-plugin portal logs | Показывает последние 100 строк логов | | npx seaf-plugin --help / --version | Справка / версия toolkit |

Базовый цикл разработки

1. Редактируйте Vue-компоненты в src/. Регистрация типов документов — в src/index.js, описание плагина — в plugin.json; типы должны совпадать и быть уникальными.
2. Запустите npx seaf-plugin dev, проверьте результат в портале (см. ниже). После успешной пересборки обновляйте страницу вручную — HMR нет.
3. Выполните npx seaf-plugin bundle. Результат: dist/catalog.json и dist/<plugin-id>/ с JS, CSS и descriptor.
4. Для поставки скопируйте содержимое dist/ в dist/plugins/ портала (или public/plugins/ перед сборкой core). Не затирайте каталог других плагинов: catalog.json задаёт весь список. Для отображения документа добавьте в архитектурный manifest документ с соответствующим type.

После обновления toolkit запустите npx seaf-plugin init: он обновит managed AGENTS.md. Собственные инструкции в этом файле не храните — он перезаписывается.

Подробнее: разработка плагинов. Для работы над самим toolkit: make test, make pack; публикация.

Preview через Docker

Нужен Docker Compose v2. Из проекта плагина:

npx seaf-plugin dev          # терминал 1: дождитесь [preview] Ready
npx seaf-plugin portal up    # терминал 2

Откройте http://localhost:8080 → Plugin development/my-card. Первый запуск скачает образ портала. Docker использует preview из .dev/, а не релизный dist/.

• После правок исходников дождитесь пересборки и обновите страницу.
• После изменения manifest или типов документов выполните npx seaf-plugin portal restart; после изменения vite.config.js перезапустите dev.
• Другой порт: SEAF_PORTAL_PORT=8081 npx seaf-plugin portal up; другой совместимый образ — через SEAF_PORTAL_IMAGE.
• Завершение: Ctrl+C в терминале с dev, затем npx seaf-plugin portal down.