Créer un plugin

Commencez par une action utile. Gardez visibles la compatibilité, l’autorité et le comportement d’exécution à mesure que vous ajoutez des capacités.

Obtenir le modèle et les types

Le dépôt public des plugins contient un modèle, les déclarations, le registre et les vérifications de paquet. Pour les API non publiées, comparez-les au contrat source actuel et utilisez un build de développement correspondant. La dernière application publiée peut être plus ancienne que cette documentation.

Utilisez Bun pour les scripts du dépôt. Copiez template/ vers plugins/<your-plugin-id>/ et faites correspondre le nom du répertoire à l’ID du manifeste.

Une commande minimale

Cet exemple enregistre une commande pendant l’activation et n’effectue son effet d’interface que lorsque l’utilisateur l’exécute.

{
  "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" }
  }
}

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

Compilez le module d’entrée en un main.js autonome. Le manifeste ci-dessus exige volontairement les versions documentées actuelles ; n’utilisez des plages plus anciennes qu’après avoir vérifié et testé ces contrats.

Ajouter l’autorité minimale utile

Utilisez l’Explorateur pour trouver une méthode et copier son fragment de manifeste initial. Un fragment déclare une capacité ; complétez les autorisations nécessaires à l’opération concernée.

• La lecture des données de bibliothèque exige library:read ; leur modification exige library:write.
• Les réglages utilisent des chemins et opérations exacts dans settingsAccess.
• Les requêtes HTTP arbitraires exigent service:network ainsi que des origines autorisées dans networkAccess.origins.
• Une méthode liée au lecteur dans un service d’interface sans permission supplémentaire peut tout de même exiger reading:read ou reading:write.
• Les autorisations de livre sont choisies avec le consentement de l’hôte et exposées dans ctx.grants.book ; un manifeste ne peut pas s’accorder l’accès à un autre livre.

Inspectez ctx.capabilities et gérez les espaces de noms optionnels absents. Conservez les données appartenant à ReadAware dans ses domaines ; le stockage du plugin est réservé à vos propres enregistrements, réglages et points de contrôle.

Travailler avec les observations et l’annulation

Libérez les handles quand vous n’en avez plus besoin. Pour les appels pris en charge, transmettez un AbortSignal et attendez le résultat réel. L’annulation n’annule pas une écriture ou un effet distant déjà produit.

Une réaction automatique utilise ctx.withEvent(delivery) pour le travail qui en découle, y compris après un await. Donnez un ruleId stable aux abonnements causaux lorsque le contrat l’exige. Les actions lancées par l’utilisateur utilisent le contexte d’activation d’origine. L’hôte peut ainsi détecter les boucles sans confondre les actions indépendantes.

Construire et installer localement

Suivez les scripts du checkout. Dans le dépôt public des plugins, les vérifications habituelles sont :

bun run build
bun run typecheck
bun test
bun run validate

Ouvrez ReadAware → Réglages → Plugins → Installer un plugin, sélectionnez le dossier compilé et examinez le résumé du consentement. Exercez la fonctionnalité dans l’application de bureau. Recompilez et réinstallez pour vérifier une mise à jour.

Versionner les données privées

schemaVersion est indépendant de la version du paquet. Lorsque la forme du KV stocké ou des documents change, fournissez les transitions de mise à niveau et de rétrogradation prises en charge via migrate(storageCtx, change).

La migration reçoit une autorité limitée au stockage. Testez une transition échouée ainsi qu’une transition réussie : le paquet précédent et les données validées doivent rester utilisables. N’ajoutez pas de changement de schéma inutile pour une mise à jour ordinaire du code.

Tester les limites utilisées par la fonctionnalité

Vérifiez le comportement réel Worker/Tauri, les refus liés aux permissions et à la portée du livre, l’annulation, la désactivation/réactivation et la récupération après échec. Pour un plugin d’interface, incluez la navigation au clavier, les textes longs et les fenêtres étroites. Pour un plugin qui modifie les données, vérifiez les éditions concurrentes et le redémarrage lorsque la persistance compte.

Les tâches planifiées s’exécutent lorsque l’application est ouverte ; les tâches durables ne prennent en charge que les plans typés de l’hôte. Aucune des deux n’est un processus général en arrière-plan ni un exécuteur de code arbitraire. La référence de l’API décrit ces limites.

Publier

Une fois le paquet compilé fonctionnel avec ses contrats minimaux déclarés, suivez la procédure de Publication.