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

Начните с одного полезного действия. Держите на виду совместимость, полномочия и поведение во время выполнения по мере добавления возможностей.

Получите шаблон и типы

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

Используйте Bun для скриптов репозитория. Скопируйте template/ в plugins/<your-plugin-id>/ и сохраняйте имя каталога равным идентификатору манифеста.

Минимальная команда

В этом примере команда регистрируется во время активации и выполняет свой эффект в интерфейсе только когда пользователь её запускает.

json

{
  "id": "hello-reader",
  "name": "Hello Reader",
  "version": "0.1.0",
  "schemaVersion": 1,
  "main": "main.js",
  "requires": {
    "contributions": { "commands": "^1.1.0" },
    "services": { "ui": "^1.17.0" }
  }
}

typescript

export default {
  activate(ctx) {
    ctx.contributions.commands.register({
      id: "hello",
      title: "Say hello",
      run: () => ctx.services.ui.showToast("Hello, reader!"),
    });
  },
};

Скомпилируйте входной модуль в автономный main.js. Манифест выше намеренно требует текущие документированные версии; используйте более старые диапазоны только после проверки и тестирования этих контрактов.

Добавьте минимально необходимое полномочие

Используйте Explorer, чтобы найти метод и скопировать его начальный фрагмент манифеста. Фрагмент объявляет возможность; дополните разрешения, необходимые для конкретной операции.

Чтение данных библиотеки требует library:read; изменение — library:write.
Настройки используют точные пути settingsAccess и операции.
Произвольный HTTP требует service:network плюс разрешённые networkAccess.origins.
Метод, связанный с чтением, в сервисе без разрешений UI может всё равно требовать reading:read или reading:write.
Разрешения на книги выбираются через согласие хоста и доступны в ctx.grants.book; манифест не может сам предоставить себе доступ к другой книге.

Проверяйте ctx.capabilities и обрабатывайте отсутствующие необязательные пространства имён. Храните данные ReadAware в их доменах; хранилище плагина предназначено для ваших собственных записей, настроек и контрольных точек.

Работа с наблюдениями и отменой

Освобождайте дескрипторы, когда они больше не нужны. Для поддерживаемых вызовов передавайте AbortSignal и ожидайте фактический результат. Отмена не отменяет запись или удалённый побочный эффект, который уже произошёл.

Автоматическая реакция использует ctx.withEvent(delivery) для последующей работы, в том числе после await. Причинным подпискам давайте стабильный ruleId, где это требует контракт. Действия, инициированные пользователем, используют исходный контекст активации. Это позволяет хосту обнаруживать циклы, не смешивая независимые действия.

Сборка и локальная установка

Следуйте скриптам пакета из проверенной копии. В публичном репозитории плагинов обычные проверки:

bash

bun run build
bun run typecheck
bun test
bun run validate

Откройте ReadAware → Settings → Plugins → Install plugin, выберите собранную папку и просмотрите сводку согласий. Проверьте функцию в настольном приложении. Пересоберите и переустановите, чтобы проверить обновление.

Версионирование приватных данных

schemaVersion не зависит от версии пакета. Когда изменяется форма хранимых KV-данных или документов, предоставьте поддерживаемые переходы обновления и понижения через migrate(storageCtx, change).

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

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

Проверяйте фактическое поведение в Worker/Tauri, отказы разрешений и книжных областей, отмену, отключение/повторное включение и восстановление после сбоев. Для UI-плагина включите навигацию с клавиатуры, длинный текст и узкие окна. Для плагина, изменяющего данные, включите одновременные изменения и перезапуск, где важна сохраняемость.

Расписания выполняются, пока приложение открыто; долговременные задания поддерживают только типизированные планы хоста. Ни то, ни другое не является общим фоновым процессом или средой выполнения произвольного кода. Справочник по API описывает эти ограничения.

Публикация

Когда собранный пакет работает с объявленными минимальными контрактами, следуйте Публикации.