ReadAware

Создание плагина

Начните с публичного шаблона TypeScript, объявите минимальный набор возможностей и протестируйте собранный пакет в настольном приложении ReadAware. Хост отвечает за жизненный цикл, разрешения, представление и откат; плагин отвечает за собственное поведение и приватные данные.

Предварительные требования

  • Настольное приложение ReadAware с доступом к разделу «Настройки → Плагины».
  • Bun для скриптов репозитория.
  • Локальная копия или fork репозитория readaware-plugins.

Создайте пакет

  1. Скопируйте template/ в plugins/<your-plugin-id>/.
  2. Сделайте имя папки, идентификатор id манифеста и пространство имён среды выполнения одинаковыми.
  3. Измените manifest.json и src/main.ts.
  4. Удалите неиспользуемые расширения шаблона и соответствующие им разрешения.
  5. Соберите автономный main.js, который загружает ReadAware.
bash
bun run build
bun run typecheck
bun test
bun run validate

Спроектируйте манифест до реализации

Проверяйте манифест в следующем порядке:

  1. Идентичность — стабильный ID, имя, версия пакета, автор и минимальная версия приложения.
  2. Данные — положительное целое число schemaVersion и путь миграции.
  3. Совместимость — диапазон semver в requires для каждого используемого API и схемы.
  4. Полномочия — семантические permissions и точные предоставления settingsAccess.
  5. Декларации — настройки, расписания, темы, шрифты и модуль входа.

Перед установкой используйте каталог возможностей и предварительный просмотр разрешений. Требования заявляют о совместимости, а не предоставляют полномочия пользователя; возможности без разрешений всё равно должны быть указаны в requires, если плагин зависит от их контракта.

Выберите подходящую возможность

  1. Используйте домен для состояния или поведения, которым владеет ReadAware.
  2. Используйте расширение, чтобы предоставить вариант, действие или провайдера.
  3. Используйте службу для ограниченной операции хоста.
  4. Используйте хранилище плагина только для данных, принадлежащих плагину.
  5. Запросите новую типизированную возможность хоста, если ни одна существующая форма не подходит.

Не дублируйте книги, прогресс, аннотации, настройки или память в хранилище плагина. Теневое состояние обходит инварианты продукта, зафиксированные события, восстановление проекций, семантику синхронизации и контекст агента.

Сохраняйте активацию декларативной

Во время activate(ctx) изучите окружение и зарегистрируйте действия, команды, провайдеров, подписки и расписания. Не выполняйте бизнес-записи или внешнюю работу. Хост поэтапно подготавливает каждую регистрацию, пока не завершатся RPC активации и Worker не ответит на проверочный ping.

Запускайте работу среды выполнения из зарегистрированного обработчика после продвижения. Если обработчик возвращает promise, позвольте хосту показывать состояния загрузки и ошибки. Храните ссылки на внешние ресурсы только если ваш необязательный deactivate() должен их закрыть; регистрации и подписки хоста освобождаются автоматически.

Явно версионируйте приватные данные

schemaVersion версионирует KV и коллекции документов плагина; эта версия не зависит от версии пакета. Изменяйте её только при изменении структуры приватных данных. Экспортируйте migrate(storageCtx, change) для каждого поддерживаемого обновления и отката после фиксации схемы.

  • Миграции получают только хранилище: без доменов, настроек, секретов, сети, UI, LLM и расширений.
  • Делайте каждый переход детерминированным и идемпотентным.
  • Проверьте сбой после частичных записей: хост должен точно восстановить KV, документы, файлы и метаданные схемы.
  • Не используйте проверку версии пакета вместо схемы данных.

Установите рабочую папку

  1. Запустите сборку и проверки.
  2. Откройте ReadAware → Настройки → Плагины → Установить плагин.
  3. Выберите папку собранного плагина и изучите сводку согласия.
  4. Проверьте реальную функцию в настольном приложении.
  5. Пересоберите и переустановите плагин, чтобы проверить обновление.

Обычный браузер не может проверить установку плагина, IPC Worker, сохранение в SQLite, доступ к исходным книгам, интеграцию с ридером или откат. Проверяйте поставляемое приложение Tauri.

Тестируйте жизненный цикл, а не только успешный сценарий

  • Чистая установка, включение, отключение и повторное включение без перезапуска.
  • Успешное обновление и откат на реальных данных.
  • Тайм-аут активации, отклонение обработчика, ошибка миграции и точный откат.
  • Очистка при удалении: не должно остаться действий, слушателей, расписаний, провайдеров или Worker.
  • Удаление и расширение разрешений во время обновления.
  • Длинные метки, пустые состояния, навигация с клавиатуры и все темы хоста.

Знайте текущие ограничения

Расписания выполняются, пока ReadAware открыт, как минимум с объявленной периодичностью, а при отставании наверстываются после запуска. Это не постоянные фоновые задачи: при закрытом приложении выполнение не происходит, нет постоянной очереди, контракта повторов/отката или гарантии возобновления после сбоя.

UI доступен только в существующих типизированных точках расширения. Для отсутствующего места нужны расширение и потребитель, принадлежащие хосту; произвольный HTML или универсальный нативный API invoke не будут добавлены в качестве обходного пути.

Далее

Держите справочник API рядом с редактором, затем перед подготовкой pull request для реестра ознакомьтесь с разделом «Публикация».