Plugin erstellen

Beginne mit der öffentlichen TypeScript-Vorlage, erkläre die kleinstmögliche Fähigkeitsmenge und führe das gebaute Paket in der ReadAware-Desktop-App aus. Der Host besitzt Lebenszyklus, Berechtigungen, Darstellung und Rollback; dein Plugin besitzt sein Verhalten und seine privaten Daten.

Voraussetzungen

• ReadAware Desktop mit Zugriff auf Einstellungen → Plugins.
• Bun für Repository-Skripte.
• Ein Checkout oder Fork des readaware-plugins-Repository.

Paket erstellen

1. Kopiere template/ nach plugins/<your-plugin-id>/.
2. Halte Ordnername, Manifest-id und Laufzeitnamensraum identisch.
3. Bearbeite manifest.json und src/main.ts.
4. Lösche nicht verwendete Vorlagenbeiträge und entferne ihre Berechtigungen.
5. Baue die eigenständige main.js, die ReadAware lädt.

bun run build
bun run typecheck
bun test
bun run validate

Manifest vor der Implementierung entwerfen

Prüfe das Manifest in dieser Reihenfolge:

1. Identität — stabile ID, Name, Paketversion, Autor und Mindestversion der App.
2. Daten — positive Ganzzahl schemaVersion und Migrationspfad.
3. Kompatibilität — ein Semver-Bereich in requires für jede verwendete API und jedes Schema.
4. Berechtigung — semantische permissions und genaue settingsAccess-Freigaben.
5. Deklarationen — Einstellungen, Zeitpläne, Designs, Schriften und Einstiegsmodul.

Verwende den Fähigkeitsbrowser und die Berechtigungs-Vorschau vor der Installation. Anforderungen sind Kompatibilitätsaussagen, keine Nutzerberechtigungen; auch berechtigungsfreie Fähigkeiten gehören in requires, wenn dein Plugin von ihrem Vertrag abhängt.

Richtige Fähigkeit auswählen

1. Verwende eine Domäne für Zustand oder Verhalten, das ReadAware besitzt.
2. Verwende einen Beitrag, um eine Auswahl, Aktion oder einen Anbieter bereitzustellen.
3. Verwende einen Dienst für eine begrenzte Host-Operation.
4. Verwende den Pluginspeicher nur für pluginspezifische Daten.
5. Fordere eine neue typisierte Host-Fähigkeit an, wenn keine vorhandene Form passt.

Spiegle Bücher, Fortschritt, Anmerkungen, Einstellungen oder Gedächtnis nicht im Pluginspeicher. Schattenzustand umgeht Produktinvarianten, festgeschriebene Ereignisse, Projektionswiederaufbau, Synchronisationssemantik und Agentenkontext.

Aktivierung deklarativ halten

Während activate(ctx) prüfe die Umgebung und registriere Aktionen, Befehle, Anbieter, Abonnements und Zeitpläne. Führe keine Geschäftsschreibvorgänge oder externe Arbeit aus. Der Host stellt jede Registrierung zwischen, bis die Aktivierungs-RPCs abgeschlossen sind und der Worker auf einen Gesundheits-Ping antwortet.

Starte Laufzeitaufgaben nach der Aktivierung aus einem registrierten Handler. Wenn ein Handler ein Promise zurückgibt, soll der Host Lade- und Fehlerzustände anzeigen. Bewahre Referenzen auf externe Ressourcen nur auf, wenn dein optionaler deactivate() sie schließen muss; Host-Registrierungen und Abonnements werden automatisch freigegeben.

Private Daten ausdrücklich versionieren

schemaVersion versioniert Plugin-KV und Dokumentsammlungen; sie ist unabhängig von der Paketversion. Ändere sie nur, wenn sich die Struktur der privaten Daten ändert. Exportiere migrate(storageCtx, change) für jedes unterstützte Upgrade und Downgrade, nachdem ein Schema festgeschrieben wurde.

• Migrationen erhalten nur Speicher: keine Domänen, Einstellungen, Geheimnisse, Netzwerkzugriffe, UI, LLMs oder Beiträge.
• Mache jede Umwandlung deterministisch und idempotent.
• Teste einen Fehler nach Teilschreibvorgängen; der Host muss KV, Dokumente, Dateien und Schemadaten exakt wiederherstellen.
• Verwende keine Paketversionsprüfung als Ersatz für das Datenschema.

Arbeitsordner installieren

1. Führe Build und Prüfungen aus.
2. Öffne ReadAware → Einstellungen → Plugins → Plugin installieren.
3. Wähle den gebauten Plugin-Ordner und prüfe die Zustimmungsübersicht.
4. Teste die tatsächliche Funktion in der Desktop-App.
5. Baue neu und installiere erneut, um ein Update zu testen.

Ein gewöhnlicher Browser kann Plugin-Installation, Worker-IPC, SQLite- Persistenz, Zugriff auf unveränderte Buchdateien, Reader-Integration oder Rollback nicht überprüfen. Teste die ausgelieferte Tauri-App.

Den Lebenszyklus testen, nicht nur den Erfolgsfall

• Neu installieren, aktivieren, deaktivieren und ohne Neustart erneut aktivieren.
• Erfolgreiches Update und Downgrade mit echten Daten.
• Aktivierungs-Timeout, Ablehnung durch den Handler, Migrationsfehler und exaktes Rollback.
• Bereinigung bei der Deinstallation: keine übrig gebliebene Aktion, kein Listener, Zeitplan, Anbieter oder Worker.
• Berechtigungen während eines Updates entfernen und erweitern.
• Lange Beschriftungen, leere Zustände, Tastaturnavigation und alle Host-Themes.

Die aktuellen Grenzen kennen

Zeitpläne laufen, solange ReadAware geöffnet ist, mindestens in der deklarierten Frequenz; bei Überfälligkeit werden sie beim Start nachgeholt. Es sind keine dauerhaften Aufgaben: Bei geschlossener App gibt es keine Ausführung, keine persistierte Warteschlange, keinen Vertrag für Wiederholung/Backoff und keine Garantie zur Fortsetzung nach einem Absturz.

UI ist nur an vorhandenen typisierten Beitragspunkten verfügbar. Eine fehlende Position erfordert einen vom Host verantworteten Beitrag und Verbraucher; beliebiges HTML oder eine allgemeine native Invoke-API wird nicht als Abkürzung hinzugefügt.

Weiter

Behalte die API-Referenz neben deinem Editor und lies Veröffentlichen, bevor du einen Pull Request für das Register vorbereitest.