ReadAware

Créer un plugin

Partez du modèle TypeScript public, déclarez l’ensemble minimal de capacités et testez le paquet compilé dans l’application de bureau ReadAware ; l’hôte gère le cycle de vie, les permissions, la présentation et le retour arrière ; votre plugin gère son comportement et ses données privées.

Prérequis

  • ReadAware Desktop, avec accès à Paramètres → Plugins.
  • Bun pour les scripts du dépôt.
  • Un clone ou fork du dépôt readaware-plugins.

Créer le paquet

  1. Copiez template/ vers plugins/<your-plugin-id>/.
  2. Conservez le nom du dossier, l’identifiant du manifeste id, et l’espace de noms d’exécution identiques.
  3. Modifiez manifest.json et src/main.ts.
  4. Supprimez les contributions du modèle inutilisées et retirez leurs permissions.
  5. Construisez le fichier autonome main.js chargé par ReadAware.
bash
bun run build
bun run typecheck
bun test
bun run validate

Concevoir le manifeste avant l’implémentation

Examinez le manifeste dans cet ordre :

  1. Identité — ID stable, nom, version du paquet, auteur et version minimale de l’application.
  2. Données — entier positif schemaVersion et chemin de migration.
  3. Compatibilité — plage semver dans requires pour chaque API et schéma utilisés.
  4. Autorité — permissions sémantiques et accords settingsAccess exacts.
  5. Déclarations — paramètres, tâches planifiées, thèmes, polices et module d’entrée.

Utilisez le navigateur des capacités et aperçu des permissions avant l’installation. Les exigences sont des déclarations de compatibilité, pas une autorité utilisateur ; les capacités sans permission doivent tout de même figurer dans requires lorsque votre plugin dépend de leur contrat.

Choisir la bonne capacité

  1. Utilisez un Domaine pour l’état ou le comportement géré par ReadAware.
  2. Utilisez une Contribution pour fournir un choix, une action ou un fournisseur.
  3. Utilisez un Service pour une opération d’hôte limitée.
  4. Utilisez le stockage du plugin uniquement pour ses propres données.
  5. Demandez une nouvelle capacité d’hôte typée lorsqu’aucune forme existante ne convient.

Ne recopiez pas les livres, la progression, les annotations, les réglages ou la mémoire dans le stockage du plugin. Un état miroir contourne les invariants du produit, les événements validés, la reconstruction des projections, la synchronisation et le contexte de l’agent.

Garder l’activation déclarative

Pendant activate(ctx), inspectez l’environnement et enregistrez les actions, commandes, fournisseurs, abonnements et tâches planifiées. N’effectuez aucune écriture métier ni travail externe. L’hôte prépare chaque enregistrement jusqu’à la fin des RPC d’activation et à la réponse du Worker au ping de santé.

Lancez le travail d’exécution depuis un gestionnaire enregistré après la promotion. Si un gestionnaire renvoie une promise, laissez l’hôte présenter les états de chargement et d’échec. Ne conservez des références vers des ressources externes que si votre deactivate()facultatif doit les fermer ; les enregistrements et abonnements de l’hôte sont libérés automatiquement.

Versionner explicitement les données privées

schemaVersion versionne le KV et les collections de documents du plugin ; il est indépendant de la version du paquet. Ne le modifiez que lorsque la structure des données privées change. Exportez migrate(storageCtx, change) pour chaque mise à niveau ou rétrogradation prise en charge après la validation d’un schéma.

  • Les migrations ne reçoivent que le stockage : aucun domaine, réglage, secret, réseau, UI, LLM ou contribution.
  • Rendez chaque transition déterministe et idempotente.
  • Testez un échec après des écritures partielles ; l’hôte doit restaurer exactement le KV, les documents, les fichiers et les métadonnées de schéma.
  • N’utilisez pas une vérification de version du paquet à la place du schéma de données.

Installer le dossier de travail

  1. Lancez la compilation et les vérifications.
  2. Ouvrez ReadAware → Paramètres → Plugins → Installer un plugin.
  3. Sélectionnez le dossier compilé et examinez le résumé du consentement.
  4. Testez la fonctionnalité réelle dans l’application de bureau.
  5. Recompilez et réinstallez pour tester une mise à jour.

Un navigateur ordinaire ne peut pas vérifier l’installation du plugin, l’IPC du Worker, la persistance SQLite, l’accès aux livres bruts, l’intégration au lecteur ou le retour arrière. Testez l’application Tauri livrée.

Tester le cycle de vie, pas seulement le cas nominal

  • Installation initiale, activation, désactivation et réactivation sans redémarrage.
  • Mise à jour et rétrogradation réussies sur des données réelles.
  • Délai d’activation, rejet du gestionnaire, échec de migration et retour arrière exact.
  • Nettoyage à la désinstallation : aucune action, écoute, tâche, fournisseur ou Worker résiduel.
  • Retrait et ajout de permissions lors d’une mise à jour.
  • Libellés longs, états vides, navigation clavier et tous les thèmes de l’hôte.

Connaître les limites actuelles

Les tâches planifiées s’exécutent tant que ReadAware est ouvert, au moins selon leur cadence déclarée, avec rattrapage au lancement lorsqu’elles sont en retard. Ce ne sont pas des tâches durables : aucune exécution n’a lieu lorsque l’application est fermée et il n’existe ni file persistante, ni contrat de nouvelle tentative/recul, ni garantie de reprise après crash.

L’UI n’est disponible qu’aux points de contribution typés existants. Un emplacement manquant nécessite une contribution et un consommateur gérés par l’hôte ; du HTML arbitraire ou une API native invoke générique ne sera pas ajouté comme raccourci.

Suite

Gardez la référence de l’API à côté de votre éditeur, puis lisez Publication avant de préparer une pull request pour le registre.