Plugin-API-Referenz
Diese Seite erklärt den aktuellen Entwicklungsvertrag. Der Capabilities Explorer listet den aktuellen Katalog, exakte Methodennamen, Signaturen und Quelldeklarationen. Eine veröffentlichte App oder die öffentliche Vorlage kann ältere Versionen bereitstellen; gleiche deine requires-Bereiche mit einem getesteten Host ab.
Paket und Manifest
Ein Plugin enthält manifest.json und ein eigenständiges ES-Modul, normalerweise main.js. Halte Quelltext und benötigte Assets zur Prüfung im Paket.
| Feld | Bedeutung |
|---|---|
id, name, version | Stabiler Namespace, Anzeigename und Paketversion. Die ID entspricht dem Ordnernamen. |
schemaVersion | Positive Ganzzahl für das private Datenschema des Plugins, unabhängig von der Paketversion. |
requires | Fähigkeits-IDs und Semver-Bereiche, gruppiert in domains, contributions, services und schemas. |
permissions | Semantische Autorität, etwa library:read oder service:llm. |
settingsAccess | Getrennte Freigaben für discover, read und write, bezogen auf exakte Pfade oder ausdrücklich benannte Abschnittsgruppen. |
networkAccess | Erlaubte HTTP(S)-Ursprünge für Network 2.x; zusätzlich zu service:network erforderlich. |
minAppVersion | Optionaler Mindeststand der App, zusätzlich zu den Fähigkeitsanforderungen. |
main | Relatives Einstiegsmodul; Standard ist main.js. |
settings, schedules, themes, fonts | Vom Host interpretierte Deklarationen. |
services | Versionierte, typisierte Modul-Exporte für dienstübergreifende Plugin-Aufrufe. |
Es gibt kein Manifestfeld, das beliebigen Zugriff auf Dateisystem, SQL, DOM oder native IPC gewährt.
Kontext und Objektumfang
Der Host ruft activate(ctx) mit ctx.domains, ctx.contributions und ctx.services auf, zusammen mit Manifest, Sprache, App-Version, Lebenszyklusphase, Fähigkeitsversionen und unveränderlicher Buchfreigabe.
ctx.grants.book ist all, current oder ein bestimmtes book. Der Host wählt dies über Zustimmung aus. Lesen, Gedächtnis, Unterhaltungen, Befehle und Ressourcen behalten diesen Umfang über Aufrufe und Callbacks hinweg. Ein Wechsel des aktuellen Buchs kann ausstehende Lesevorgänge, Handles, Vorschläge und Beobachtungen ungültig machen.
Die Schreibberechtigung einer Domäne schließt Lesen ein. Einstellungsfreigaben bleiben nach Operation getrennt. Berechtigungspflichtige Namespaces oder Methoden können fehlen; Prüfungen auf Host-Seite laufen bei jedem Aufruf weiter. Verwende ctx.services.session.operationAvailability(...) für unterstützte Vorabprüfungen und behandle einen Ausführungsfehler auch nach einem positiven Ergebnis.
Domänen
| Domäne | Verfügbare Arbeit | Grenzen |
|---|---|---|
library | Bücher und Sammlungen, Inhaltsverzeichnisse, Suche nach exakten Positionen, Bereiche, Verweise und Bilder, Importe, Textaufgaben, Metadaten, Zusammenführen von Duplikaten und Entfernen. | Quellversionen, Buchumfang, begrenzte Lesevorgänge, akteureigene Aufgaben und getrennte Quittungen für Dateibereinigung. |
reading | Sitzungssnapshots, Navigation, Auswahl, Wiedergabe- und Modussteuerung, Fortschritt, Lesezeit und Erkenntnisse. | Sperren der aktuellen Sitzung, festgeschriebener gegenüber ausstehendem Zustand, Anbieter-Verfügbarkeit und Abbruch. |
annotations | Auflisten, Prüfen und Beobachten; Markierungen oder Notizen erstellen; bedingte Änderungs- und Lösch-Batches. | Verwende die Revision, die vor der Entscheidung der nutzenden Person beobachtet wurde. Erfasste Bereiche benötigen zusätzlich Library-Zugriff. |
conversations | Autorisierte Transkripte, gespeicherte Zusammenfassungen, Laufzeit- und Rundenanforderungszustand; Thread-Steuerung und vorgeschlagene Runden. | Host-Genehmigung startet eine vorgeschlagene Runde. Globale Thread-Operationen benötigen Zugriff auf alle Bücher. Plugins ersetzen die Chat-Laufzeit nicht. |
settings | Katalogsuche, aufgelöste Snapshots, Optionen, Modellmetadaten, Beobachtung, Aktualisierungen und Lesezurücksetzungen. | Exakte Pfade, Zielrichtlinien und zusätzliche Autorität für externe Anbieterarbeit. |
memory | Suche und Seiten, Prüfung, Korrektur/Vergessen, Profile, Entitäten, Klassifikation, Graphen und Aufgaben, Kontextarchive. | Buchfreigaben und bedingte Revisionen. Globale Identitäts-/Profiloperationen benötigen Zugriff auf alle Bücher; Generierung benötigt zusätzlich Modellautorität. |
Quelltext und Navigation
Verwende library.queries.books.searchLocations für navigierbare Quelltreffer und readRange für begrenzten Quelltext. Bewahre die zurückgegebene Quellversion und Position. Abgeleitete searchText-Treffer sind Vorschauen und keine austauschbaren Navigationsanker. Die explizite Textaufbereitung liefert eine Aufgabe, deren Fortschritt und Ergebnis beobachtet werden müssen.
Bedingte Schreibvorgänge
Prüfe das aktuelle Objekt und bewahre seine Revision, bevor du eine Bearbeitung anzeigst. Sende die bedingte Mutation gegen diese Revision. Bei einem Konflikt erneut lesen und die nutzende Person entscheiden lassen; ein stilles Ersetzen der erwarteten Revision würde eine andere Änderung überschreiben.
annotations.commands.applyChanges, Gedächtnismutationen, private Dokument-Commits und Transaktionsvorschauen haben jeweils einen eigenen typisierten Vertrag. Gewöhnliche Befehle sind nicht automatisch rückgängig machbar und keine verteilten Transaktionen.
Beobachtungen und Reaktionen
Verwende autorisierte Beobachtungen für den aktuellen Zustand und festgeschriebene Abonnements für Ereignisse. Eine Sequenznummer kann Zustellungen ordnen, ist aber weder ein Datenbankcursor noch eine Revision für bedingte Schreibvorgänge. Fehlgeschlagene Beobachtungen müssen von leeren Ergebnissen unterscheidbar bleiben.
Verwende ctx.withEvent(delivery) für automatische Folgearbeit und, wo erforderlich, stabile Regel-IDs bei kausalen Abonnements. Bewahre den gebundenen Kontext über asynchrone Aufrufe hinweg. Der Host weist kausale Zyklen und abgelaufene Zustellungen zurück; unabhängige Benutzeraktionen verwenden den ursprünglichen Kontext.
Contributions
| Contribution | Was das Plugin bereitstellt |
|---|---|
selectionActions, headerActions, contextActions, commands, uriHandlers | Aktionen an typisierten Host-Oberflächen, Palettenbefehle und Namespace-bezogene URI-Verarbeitung. |
settingsOptions | Dynamische Optionen für eine deklarierte Plugin-Einstellung. |
voiceProviders, contentProviders, readerModes | Audiosynthese, Inhalte virtueller Bücher und gebündelte Segmentierungsmodi des Readers. |
agentTools, agentContextProviders, agentRetrievalProviders | Werkzeuge, begrenzten Kontext pro Runde und durchsuchbare Plugin-eigene Quellen. |
memoryCandidateProviders | Gedächtniskandidaten zur Prüfung und Annahme durch den Host. |
themes, fonts | Im Manifest deklarierte Darstellungsauswahlen. |
syncTransports | Speicherung undurchsichtiger verschlüsselter Sync-Umschläge und Metadatenobjekte. |
Aktionen können, sofern unterstützt, ihren eigenen sichtbaren/aktivierten/markierten Zustand aktualisieren. Registrierungen und Disposables gehören zu einer Aktivierung. Die Rückgabe einer Ansicht verleiht dem Callback keine zusätzliche Domänenautorität.
Gedächtniskandidaten und direkte Memory-Befehle sind getrennte Wege: Kandidaten durchlaufen die Annahme durch den Host, während direkte Befehle die passende Memory-Freigabe und Revision benötigen. Keiner der Wege erlaubt das Einschleusen von Systemregeln oder das Ersetzen des Kernagenten.
Host-Dienste
| Dienst | Zweck | Wichtige Grenze |
|---|---|---|
storage | Privates KV, Dokumentsammlungen, bedingte Commits, Seiten, Beobachtungen und Nutzungsrichtlinien. | Plugin-Namespace und Kontingente; veraltete Cursor benötigen eine neue Ausgangsbasis. |
resources | Von Nutzenden ausgewählte Dateien/Verzeichnisse, versiegelte Byte-Handles, Exporte, Bilder und private Binär-Assets. | Keine Umgebungs-Pfade. Handles haben Besitzer, Grenzen und Lebenszeiten. |
secrets | Verschlüsselte, Plugin-private Zugangsdaten-Slots. | Kein Zugriff auf Geheimnisse anderer Plugins. |
network | Origin-begrenztes HTTP, begrenzte gepufferte Anfragen und Streaming. | Jede Weiterleitung wird geprüft; keine automatische Wiederholung beliebiger Schreibvorgänge. |
llm | Text- oder strukturierte Inferenz, Streaming, Bildressourcen, Anfragequittungen und Budgets. | Nutzerkonfiguration, Datenschutzregeln, Abbruch sowie Host-/Anbietergrenzen. |
clipboard | Text oder ein versiegeltes Bild schreiben. | Ausdrückliche Berechtigung und unterstützter Ressourcentyp. |
ui | Ansichten, Toasts, native Speichern-/Öffnen-Abläufe, Workspace- und Befehlsnavigation, Reader-Panels und Fenster. | Methodenspezifische Domänenfreigaben und Darstellung im Besitz des Hosts. |
session | Nicht sensible Umgebungsmetadaten und Verfügbarkeit von Operationen. | Kein altes Lesesitzungs-Abonnement; verwende die Reading-Domäne. |
schedules | Deklarierte wiederkehrende Handler und eigene aufgeschobene Anfragen. | Arbeit läuft bei geöffneter App; der Zeitpunkt ist nicht exakt. |
jobs | Unterstützte dauerhafte Pläne, Checkpoints, Beobachtung und Steuerung. | Typisierte Host-Operationen, keine beliebige JavaScript-Ausführung. |
changes | Eingegrenzte persistente Änderungscursor. | Hinweise zum Neuladen, kein rohes Ereignisprotokoll oder historische Werte. |
transactions | Vorschau, Commit, Quittungsabfrage und bedingte Rückgängig-Vorschau. | Unterstützte lokale Operationen und ursprüngliche Freigaben; unbekannte Ergebnisse benötigen Quittungsabfrage. |
plugins | Registrierungen prüfen, Änderungen beobachten sowie typisierte Plugin-Dienste entdecken und aufrufen. | Schnittmenge der Autorität von Aufrufer und Ziel, Umfang, Versionen und isolierte Dienstausführung. |
maintenance | Wartungsstatus prüfen und hosteigene Backup-, Verbindungstest-, Update- oder Einstellungsabläufe öffnen. | Der Host verwaltet Zugangsdaten, Dateidialoge und folgenreiche Bestätigung. |
sync | Autorisierten Sync-Status und Rückstand beobachten sowie hostverwaltete Konto- oder Sync-Abläufe anfordern. | Keine Verschlüsselungsschlüssel oder rohen Kontozugangsdaten. |
diagnostics, logging | Geprüfte Diagnoseexporte und begrenzte strukturierte Entwicklerereignisse. | Keine beliebigen Inhalte, Geheimnisse oder automatische Meldung über die Log-API. |
Netzwerk und Inferenz
Network 2.x benötigt sowohl eine semantische Berechtigung als auch explizite Ursprünge:
{
"requires": { "services": { "network": "^2.2.0" } },
"permissions": ["service:network"],
"networkAccess": { "origins": ["https://api.example.com"] }
}Ersetze den Beispielursprung durch den tatsächlich verwendeten Endpunkt. Ursprünge enthalten Schema, Host und Port; sie sind weder URL-Pfade noch Subdomain-Globs. Weiterleitungen müssen weiterhin autorisiert sein. Streaming-Aufrufer schließen eigene Streams nach Gebrauch. Optionale sichere Wiederholungen sind auf unterstützte Leseanfragen vor einer Antwort begrenzt; ein Abbruch macht eine externe Nebenwirkung nicht rückgängig.
Verwende für Inferenz readingContext für Buchkontext, damit der Host Datenschutz- und Umfangsregeln anwenden kann. Verwende versiegelte Ressourcen-IDs für unterstützte Bilder. Anfragemetadaten und Ausgabebudgets helfen bei der Arbeitssteuerung; sie sind weder eine Abrechnung noch eine Garantie für die Einhaltung durch den Anbieter.
Hintergrundarbeit und Transaktionen
Verwende einen Zeitplan für den Aufruf eines Handlers, eine eigene aufgeschobene Anfrage für spätere Arbeit während die App läuft und einen dauerhaften Job nur dann, wenn sein typisierter Plan die Operation unterstützt. Die Wiederherstellung nach einem Neustart kann Aufmerksamkeit erfordern, statt ein unsicheres externes Ergebnis blind zu wiederholen.
Transaktionen kombinieren unterstützte Einstellungen, private Dokument- und Domänenoperationen unter den ursprünglichen Freigaben. Die Vorschau friert die geplante Arbeit ein; der Commit verbraucht diese Vorschau. Frage nach einer unbekannten Antwort die Quittung ab, bevor du wiederholst. Rückgängigmachen ist davon abhängig, dass der Zustand weiterhin dem vorherigen Ergebnis entspricht.
Dienste zwischen Plugins
Deklariere Dienst-ID, Version, Scope, erforderliche Berechtigungen und Ein-/Ausgabeschemas im Provider-Manifest und exportiere den Handler im services-Objekt des Moduls. Entdecke und rufe ihn über den Plugins-Dienst auf. Der Host startet einen neuen isolierten Dienstraum mit der Schnittmenge der Autorität; er aktiviert für diesen Aufruf nicht die gewöhnliche UI-Laufzeit des Providers. Von einem Agenten stammende Aufrufe behalten ihre Genehmigungspflicht.
Ansichten, Einstellungen, Designs und Schriften
Plugins liefern deklarative Ansichtsdaten. Der Host rendert Listen, Formulare, Markdown, Details und unterstützte Block-Layouts. Verwende typisierte Ansichtsergebnisse und Live-Updates; halte Lade-, Konflikt-, Leer- und Fehlerzustände getrennt. Plugin-Code hat keinen Zugriff auf React, DOM, Iframe oder beliebiges CSS.
Einstellungsfelder werden vom Host gerendert. Geheimnisfelder schreiben in verschlüsselte Geheimnis-Slots und werden weder zu gewöhnlichen Formularwerten noch zu modellsichtbaren Einstellungen. Für das Anbieten eines Designs oder einer Schrift ist ui:themes erforderlich; die Auswahl verwendet die entsprechende Schreibfreigabe für Settings.
Lebenszyklus und Kompatibilität
- Aktivierung: unterstützte Lesevorgänge und Registrierungen; vorbereitete Contributions sind noch nicht sichtbar.
- Migration: nur privater Speicher, bevor ein geändertes Schema festgeschrieben wird.
- Aktiv: beförderte Handler dürfen freigegebene Fähigkeiten verwenden.
Der Host führt Gesundheitsprüfungen durch und befördert einen Kandidaten, wenn Aktivierung und jede Migration erfolgreich sind. Bei einem Fehler werden vorheriges Paket und vorherige Daten wiederhergestellt. Beim Entladen werden Registrierungen, Callbacks und eigene Ressourcen freigegeben; dauerhafte Daten folgen ihrem eigenen Aufbewahrungsvertrag. In der aktuellen Entwicklung entfernt die Deinstallation private Dokumentsammlungen und Binär-Assets, behält aber den definierten KV-/Secret-/Schema-Zustand für eine erneute Installation.
Deklariere jede verwendete Fähigkeit und jedes Schema unabhängig. Eine Versionsnummer belegt Vertragskompatibilität, aber nicht, dass jedes Betriebssystem, jeder Anbieter oder jeder Fehlerfall Ende-zu-Ende akzeptiert wurde. Prüfe den tatsächlichen Desktop-Ablauf, den du auslieferst.