Référence de l’API des plugins
Cette page explique le contrat de développement actuel. L’Explorateur de capacités répertorie le catalogue actif, les noms exacts des méthodes, leurs signatures et leurs déclarations source. Une application publiée ou le modèle public peut exposer des versions plus anciennes ; faites correspondre vos plages requires à un hôte testé.
Paquet et manifeste
Un plugin contient manifest.json et un module ES autonome, généralement main.js. Gardez le code source et les ressources nécessaires dans le paquet afin de permettre la révision.
| Champ | Signification |
|---|---|
id, name, version | Espace de noms stable, nom affiché et version du paquet. L’ID correspond au nom du dossier. |
schemaVersion | Entier positif du schéma de données privées du plugin, indépendant de la version du paquet. |
requires | ID de capacités et plages semver, regroupés en domains, contributions, services et schemas. |
permissions | Autorité sémantique, par exemple library:read ou service:llm. |
settingsAccess | Autorisations séparées discover, read et write pour des chemins exacts ou des groupes de sections explicites. |
networkAccess | Origines HTTP(S) autorisées pour Network 2.x ; obligatoire avec service:network. |
minAppVersion | Plancher facultatif de version de l’application, en plus des exigences de capacités. |
main | Module d’entrée relatif ; sa valeur par défaut est main.js. |
settings, schedules, themes, fonts | Déclarations interprétées par l’hôte. |
services | Exports de services de module typés et versionnés pour les appels entre plugins. |
Aucun champ du manifeste n’accorde un accès arbitraire au système de fichiers, à SQL, au DOM ou à l’IPC natif.
Contexte et portée des objets
L’hôte appelle activate(ctx) avec ctx.domains, ctx.contributions et ctx.services, ainsi qu’avec le manifeste, la langue, la version de l’application, la phase du cycle de vie, les versions des capacités et l’autorisation de livre immuable.
ctx.grants.book vaut all, current ou un book donné. L’hôte le choisit lors du consentement. La lecture, la mémoire, les conversations, les commandes et les ressources conservent cette portée dans les appels et les callbacks. Un changement de livre courant peut invalider les lectures, handles, propositions et observations en cours.
La permission d’écriture d’un domaine inclut la lecture. Les autorisations de réglages restent séparées par opération. Les espaces de noms ou méthodes protégés par permission peuvent être absents ; les contrôles côté hôte s’exécutent tout de même à chaque appel. Utilisez ctx.services.session.operationAvailability(...) pour les vérifications préalables prises en charge et gérez l’échec d’exécution même après un résultat positif.
Domaines
| Domaine | Travail disponible | Limites |
|---|---|---|
library | Livres et collections, sommaires, recherche d’emplacements exacts, plages, références et images, importations, tâches de texte, métadonnées, fusion de doublons et suppression. | Versions de source, portée du livre, lectures limitées, tâches appartenant à l’acteur et reçus distincts de nettoyage des fichiers. |
reading | Instantanés de session, navigation, sélection, contrôles de lecture et de mode, progression, temps de lecture et informations. | Gardes de session actuelle, états stabilisés ou en attente, disponibilité des fournisseurs et annulation. |
annotations | Pages, inspection et observations ; création de surlignages ou de notes ; lots de modifications et suppressions conditionnelles. | Utilisez la révision observée avant la décision de l’utilisateur. Les plages capturées exigent aussi l’accès à Library. |
conversations | Transcriptions autorisées, résumés enregistrés, état d’exécution et des demandes de tour ; contrôles de fils et tours proposés. | L’approbation de l’hôte démarre un tour proposé. Les opérations sur les fils globaux exigent l’accès à tous les livres. Les plugins ne remplacent pas le runtime de discussion. |
settings | Découverte du catalogue, instantanés résolus, options, métadonnées de modèles, observation, mises à jour et réinitialisations de lecture. | Chemins exacts, politique de cible et autorité supplémentaire pour le travail d’un fournisseur externe. |
memory | Recherche et pages, inspection, correction et oubli, profils, entités, classification, graphes et tâches, archives de contexte. | Autorisations de livre et révisions conditionnelles. Les opérations d’identité et de profil globales exigent l’accès à tous les livres ; la génération exige aussi l’autorité du modèle. |
Texte source et navigation
Utilisez library.queries.books.searchLocations pour les correspondances de source navigables et readRange pour le texte source limité. Conservez la version de source et l’emplacement renvoyés. Les résultats searchText dérivés sont des aperçus et ne remplacent pas les ancres de navigation. La préparation explicite du texte renvoie une tâche dont la progression et le résultat doivent être observés.
Écritures conditionnelles
Inspectez l’objet actuel et conservez sa révision avant d’afficher une modification. Soumettez la mutation conditionnelle avec cette révision. En cas de conflit, relisez l’objet et laissez l’utilisateur décider ; remplacer silencieusement la révision attendue écraserait une autre modification.
annotations.commands.applyChanges, les mutations Memory, les commits de documents privés et les prévisualisations de transactions ont chacun leur propre contrat typé. Les commandes ordinaires ne sont pas automatiquement annulables ni des transactions distribuées.
Observations et réactions
Utilisez les observations autorisées pour l’état actuel et les abonnements validés pour les événements. Un numéro de séquence peut ordonner les livraisons sans être un curseur de base de données ni une révision d’écriture conditionnelle. Les observations échouées doivent rester distinguables des résultats vides.
Utilisez ctx.withEvent(delivery) pour le travail de suivi automatique et des identifiants de règle stables sur les abonnements causaux lorsque cela est requis. Conservez le contexte lié dans les appels asynchrones. L’hôte rejette les cycles causaux et les livraisons expirées ; les actions utilisateur indépendantes utilisent le contexte d’origine.
Contributions
| Contribution | Ce que fournit le plugin |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Actions sur les surfaces typées de l’hôte, commandes de palette et gestion d’URI avec espace de noms. |
settingsOptions | Options dynamiques pour un réglage de plugin déclaré. |
voiceProviders, contentProviders, readerModes | Synthèse audio, contenu de livres virtuels et modes de segmentation du lecteur intégrés. |
agentTools, agentContextProviders, agentRetrievalProviders | Outils, contexte limité par tour et sources de plugin consultables. |
memoryCandidateProviders | Mémoires candidates soumises à la validation et à l’acceptation de l’hôte. |
themes, fonts | Choix d’apparence déclarés dans le manifeste. |
syncTransports | Stockage d’enveloppes de synchronisation chiffrées opaques et d’objets méta. |
Les actions peuvent mettre à jour leur état visible, activé ou coché lorsqu’il est pris en charge. Les enregistrements et les disposables appartiennent à une activation. Le retour d’une vue n’accorde pas au callback une autorité supplémentaire sur les domaines.
Les candidates de mémoire et les commandes Memory directes sont deux chemins distincts : les candidates passent par l’acceptation de l’hôte, tandis que les commandes directes exigent l’autorisation Memory et la révision correspondantes. Aucun de ces chemins ne permet d’injecter des règles système ni de remplacer l’agent principal.
Services hôte
| Service | Utilisation | Limite principale |
|---|---|---|
storage | KV privé, collections de documents, commits conditionnels, pages, observations et politiques d’utilisation. | Espace de noms et quotas du plugin ; les curseurs obsolètes exigent une nouvelle base. |
resources | Fichiers et répertoires choisis par l’utilisateur, handles d’octets scellés, exports, images et ressources binaires privées. | Aucun chemin ambiant. Les handles ont des propriétaires, des limites et une durée de vie. |
secrets | Emplacements d’identifiants chiffrés privés au plugin. | Aucun accès aux secrets d’un autre plugin. |
network | HTTP limité par origine, requêtes mises en mémoire tampon et flux. | Chaque redirection est contrôlée ; aucune relecture automatique d’écritures arbitraires. |
llm | Inférence textuelle ou structurée, streaming, ressources image, reçus de requête et budgets. | Configuration utilisateur, règles de confidentialité, annulation et limites hôte/fournisseur. |
clipboard | Écrire du texte ou une image scellée. | Permission explicite et type de ressource pris en charge. |
ui | Vues, notifications, flux natifs d’enregistrement/ouverture, navigation des espaces de travail et commandes, panneaux et fenêtres du lecteur. | Autorisations de domaine propres aux méthodes et présentation gérée par l’hôte. |
session | Métadonnées d’environnement non sensibles et disponibilité des opérations. | Aucun ancien abonnement à la session de lecture ; utilisez le domaine Reading. |
schedules | Gestionnaires récurrents déclarés et demandes différées possédées. | Le travail s’exécute lorsque l’application est ouverte ; le minutage n’est pas exact. |
jobs | Plans durables pris en charge, points de contrôle, observation et contrôle. | Opérations hôte typées, pas une exécution JavaScript arbitraire. |
changes | Curseurs persistants de changements limités. | Indications de rechargement, pas journal brut d’événements ni valeurs historiques. |
transactions | Prévisualisation, commit, recherche de reçus et prévisualisation d’annulation conditionnelle. | Opérations locales prises en charge et autorisations d’origine ; les résultats inconnus exigent une recherche de reçu. |
plugins | Inspection des enregistrements, observation des changements, découverte et appel de services de plugins typés. | Intersection des autorités appelant/appelé, portée, versions et exécution isolée du service. |
maintenance | État et flux hôte de sauvegarde, test de connexion et mise à jour. | L’hôte conserve les identifiants, les dialogues de fichiers et les confirmations importantes. |
sync | État de synchronisation autorisé, retard et flux de compte ou de synchronisation gérés par l’hôte. | Aucune clé de chiffrement ni identifiant brut de compte. |
diagnostics, logging | Exports de diagnostics révisés et événements développeur structurés limités. | Aucun contenu arbitraire, secret ou signalement automatique via l’API de journalisation. |
Réseau et inférence
Network 2.x exige à la fois une permission sémantique et des origines explicites :
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Remplacez l’origine d’exemple par l’endpoint réellement utilisé. Les origines comprennent le schéma, l’hôte et le port ; ce ne sont ni des chemins d’URL ni des jokers de sous-domaines. Les redirections doivent rester autorisées. Les appelants de flux ferment les flux dont ils sont propriétaires une fois leur utilisation terminée. La nouvelle tentative sûre facultative se limite aux requêtes de lecture prises en charge avant la livraison d’une réponse ; l’annulation n’annule pas un effet distant.
Pour l’inférence, utilisez readingContext pour le contexte du livre afin que l’hôte applique les règles de confidentialité et de portée. Utilisez les identifiants de ressources scellées pour les images prises en charge. Les métadonnées de requête et les budgets de sortie aident à contrôler le travail ; ils ne constituent ni un relevé de facturation ni une garantie du respect des règles par le fournisseur.
Travail en arrière-plan et transactions
Utilisez une planification pour organiser l’appel d’un gestionnaire, une demande différée possédée pour un travail ultérieur pendant que l’application s’exécute, et une tâche durable uniquement lorsque son plan typé prend l’opération en charge. La récupération après redémarrage peut exiger une intervention plutôt que répéter aveuglément un résultat externe incertain.
Les transactions combinent des opérations prises en charge de réglages, de documents privés et de domaines avec les autorisations d’origine. La prévisualisation fige le travail proposé ; le commit consomme cette prévisualisation. Après une réponse inconnue, consultez le reçu avant de réessayer. L’annulation est conditionnelle : l’état doit toujours correspondre au résultat précédent.
Services entre plugins
Déclarez dans le manifeste du fournisseur l’ID, la version, la portée, les permissions requises et les schémas d’entrée/sortie du service, puis exportez son gestionnaire dans l’objet services du module. Découvrez-le et appelez-le via le service Plugins. L’hôte exécute un nouveau domaine de service isolé avec l’autorité intersectée ; il n’active pas le runtime d’interface ordinaire du fournisseur pour cet appel. Les appels provenant de l’agent conservent leur exigence d’approbation.
Vues, réglages, thèmes et polices
Les plugins renvoient des données de vue déclaratives. L’hôte rend les listes, formulaires, markdown, détails et mises en page de blocs prises en charge. Utilisez des résultats de vue typés et des mises à jour de vue en direct ; gardez distincts les états de chargement, de conflit, vide et d’erreur. Le code du plugin n’a accès ni à React, ni au DOM, ni aux iframes, ni au CSS arbitraire.
Les champs de réglages sont rendus par l’hôte. Les champs secrets écrivent dans des emplacements chiffrés et ne deviennent ni des valeurs ordinaires de formulaire ni des réglages visibles par le modèle. Fournir un thème ou une police exige ui:themes ; en sélectionner un utilise l’autorisation d’écriture Settings correspondante.
Cycle de vie et compatibilité
- Activation : lectures et enregistrements pris en charge ; les contributions en attente ne sont pas encore visibles.
- Migration : stockage privé uniquement, avant la validation d’un schéma modifié.
- Actif : les gestionnaires promus peuvent utiliser les capacités accordées.
L’hôte vérifie la santé et promeut un candidat après la réussite de l’activation et de toute migration. En cas d’échec, il restaure le paquet et les données précédents. Le déchargement libère les enregistrements, callbacks et ressources possédées ; les données durables suivent leur propre contrat de conservation. Dans le développement actuel, la désinstallation supprime les collections de documents privés et les ressources binaires tout en conservant l’état KV/secret/schema défini pour la réinstallation.
Déclarez indépendamment chaque capacité et chaque schéma utilisés. Un numéro de version prouve la compatibilité du contrat, pas que chaque système d’exploitation, fournisseur ou scénario d’échec a été accepté de bout en bout. Vérifiez le workflow de bureau réel que vous livrez.