ReadAware

プラグインを作る

公開TypeScriptテンプレートから始め、最小限の機能セットを宣言し、ビルド済みパッケージをReadAwareデスクトップアプリで実際に動かします。ライフサイクル、権限、表示、ロールバックはホストが担い、プラグインは自身の振る舞いとプライベートデータを担います。

前提条件

  • 「設定 → プラグイン」にアクセスできるReadAwareデスクトップ。
  • Bun（リポジトリのスクリプト実行用）。
  • チェックアウトまたはフォークした readaware-pluginsリポジトリ。

パッケージを作成する

  1. template/を plugins/<your-plugin-id>/へコピーします。
  2. フォルダー名、マニフェストのid、ランタイム名前空間を同じに保ちます。
  3. manifest.jsonとsrc/main.tsを編集します。
  4. 使わないテンプレートのコントリビューションを削除し、対応する権限も削除します。
  5. ReadAwareが読み込む自己完結したmain.jsをビルドします。
bash
bun run build
bun run typecheck
bun test
bun run validate

実装前にマニフェストを設計する

次の順序でマニフェストを確認します。

  1. 識別情報 — 安定したID、名前、パッケージバージョン、作者、最小アプリバージョン。
  2. データ — 正の整数であるschemaVersionと移行パス。
  3. 互換性 — 使用するすべてのAPIとスキーマについて、requiresにsemver範囲を記載します。
  4. 権限 — 意味的なpermissionsと正確なsettingsAccess付与。
  5. 宣言 — 設定、スケジュール、テーマ、フォント、エントリーモジュール。

インストール前に 機能ブラウザーと権限プレビュー を確認してください。要件は互換性の主張であり、ユーザー権限ではありません。権限不要の機能でも、プラグインがその契約に依存するならrequiresに記載します。

正しい機能を選ぶ

  1. ReadAwareが所有する状態や振る舞いにはドメインを使います。
  2. 選択肢、アクション、プロバイダーの提供にはコントリビューションを使います。
  3. 範囲を限定したホスト操作にはサービスを使います。
  4. プラグインストレージはプラグイン所有データだけに使います。
  5. 既存の形が合わない場合は、新しい型付きホスト機能を要求します。

本、進捗、注釈、設定、メモリをプラグインストレージへ複製しないでください。シャドー状態は製品の不変条件、コミット済みイベント、プロジェクション再構築、同期の意味論、エージェントコンテキストを迂回します。

有効化を宣言的に保つ

activate(ctx)では環境を調べ、アクション、コマンド、プロバイダー、購読、スケジュールを登録します。ビジネス書き込みや外部処理は行わないでください。ホストは有効化RPCが完了し、Workerがヘルスチェックに応答するまで、すべての登録をステージします。

昇格後は登録済みハンドラーからランタイム処理を開始します。ハンドラーがPromiseを返す場合、読み込み状態と失敗状態の表示はホストに任せます。任意のdeactivate()で閉じる必要がある場合に限り外部リソースへの参照を保持してください。ホストの登録と購読は自動的に破棄されます。

プライベートデータを明示的にバージョン管理する

schemaVersionはプラグインKVとドキュメントコレクションをバージョン管理し、パッケージバージョンとは独立しています。プライベートデータの形が変わる場合だけ変更してください。スキーマのコミット後に対応するすべてのアップグレードとダウングレードについて、migrate(storageCtx, change)をエクスポートします。

  • 移行が受け取れるのはストレージだけです。ドメイン、設定、シークレット、ネットワーク、UI、LLM、コントリビューションは使えません。
  • 各遷移を決定的かつ冪等にします。
  • 部分的な書き込み後の失敗をテストし、ホストがKV、ドキュメント、ファイル、スキーマメタデータを正確に復元できることを確認します。
  • パッケージバージョンのチェックをデータスキーマの代わりに使わないでください。

作業フォルダーをインストールする

  1. ビルドとチェックを実行します。
  2. ReadAwareで「設定 → プラグイン → プラグインをインストール」を開きます。
  3. ビルド済みプラグインフォルダーを選択し、同意内容の概要を確認します。
  4. デスクトップアプリで実際の機能を動かします。
  5. 更新をテストするため、再ビルドして再インストールします。

通常のブラウザーでは、プラグインのインストール、Worker IPC、SQLite永続化、生のブックアクセス、リーダー統合、ロールバックを検証できません。出荷対象のTauriアプリでテストしてください。

成功経路だけでなくライフサイクルをテストする

  • 再起動せずに、新規インストール、有効化、無効化、再有効化を行います。
  • 実際のデータを使った更新とダウングレードの成功。
  • 有効化のタイムアウト、ハンドラーの拒否、移行失敗、正確なロールバック。
  • アンインストール後の後始末。アクション、リスナー、スケジュール、プロバイダー、Workerが残らないこと。
  • 更新中の権限削除と権限拡張。
  • 長いラベル、空状態、キーボードナビゲーション、すべてのホストテーマ。

現在の制限を知る

スケジュールはReadAwareが開いている間、宣言された間隔以上の頻度で実行され、期限を過ぎていれば起動時に追いつきます。永続ジョブではありません。アプリ終了中の実行、永続キュー、再試行・バックオフ契約、クラッシュ後の再開保証はありません。

UIは既存の型付きコントリビューションポイントでのみ利用できます。配置場所がない場合は、ホスト所有のコントリビューションとコンシューマーが必要です。任意のHTMLや汎用ネイティブinvoke APIを近道として追加することはありません。

次へ

エディターの横にAPIリファレンスを置き、レジストリへのプルリクエストを準備する前に公開を読んでください。