プラグインAPIリファレンス

プラグインはmanifest.jsonとビルド済みESモジュールを含むフォルダーです。公開されるTypeScript契約の正確な定義は readaware-pluginsリポジトリのtypes/plugin-api.d.tsとして提供されています。このページでは各要素の関係を説明します。

パッケージ構成

tree

my-plugin/
  manifest.json
  main.js
  src/main.ts       # 推奨。レビュー用にコミット
  assets/           # 任意。マーケットプレイスへのインストール時に明示的に列挙

main.jsはライフサイクルオブジェクトをdefault exportします。ReadAwareは専用のモジュールWorkerで実行し、activateにはアクター単位のコンテキストを渡します。

typescript

export default {
  activate(ctx) {
    // 検査して登録する。この段階では副作用がブロックされる。
  },
  migrate(storageCtx, change) {
    // 任意: プラグイン専用のKVとドキュメントを変換する。
  },
  deactivate() {
    // 任意: プラグイン自身の外部リソースを解放する。
  },
};

マニフェスト

json

{
  "id": "theme-schedule",
  "name": "テーマスケジュール",
  "version": "0.1.0",
  "schemaVersion": 1,
  "minAppVersion": "0.3.0",
  "requires": {
    "domains": { "settings": "^1.0.0" },
    "contributions": {
      "commands": "^1.0.0",
      "settingsOptions": "^1.0.0"
    },
    "services": {
      "storage": "^1.0.0",
      "schedules": "^1.0.0",
      "ui": "^1.0.0"
    },
    "schemas": { "settings": "^1.0.0" }
  },
  "settingsAccess": {
    "discover": ["appearance.theme", "reading.theme"],
    "write": ["appearance.theme", "reading.theme"]
  },
  "main": "main.js"
}

フィールド	契約
`id`	小文字、数字、ハイフンで構成し、最大64文字。恒久的な名前空間であり、フォルダー名と一致させます。
`name`、`version`	ユーザー向けの名前とパッケージバージョン。
`schemaVersion`	プラグイン専用KVとドキュメントデータ用の必須の正整数。パッケージバージョンとは独立します。
`requires`	ケイパビリティIDからsemver範囲への必須マップ。ドメイン、コントリビューション、サービス、スキーマごとにグループ化します。
`permissions`	ユーザーに要求する任意の意味的権限。不明な値は検証に失敗します。
`settingsAccess`	正確な設定パスまたは明示的な`section.*`グループに対する、任意のdiscover/read/write許可。
`minAppVersion`	任意のアプリバージョン下限。新しく提供されたケイパビリティに依存する場合に使用します。
`settings`	ホストが描画する任意のプラグイン設定フィールド。
`schedules`	任意の繰り返しタスク。ハンドラーをバインドする前に宣言します。
`themes`、`fonts`	任意の宣言的テーマおよびフォントのコントリビューション。`ui:themes`が必要です。
`main`	フォルダーからの相対パスで示すエントリーモジュール。既定値は`main.js`です。

完全な一覧と権限の語彙については、ケイパビリティブラウザーを参照してください。要件は常に互換性に関する宣言であり、権限を付与するものではありません。

ランタイムコンテキスト

名前空間	内容
`ctx.manifest`	検証済みのマニフェスト（読み取り専用）。
`ctx.appVersion`、`ctx.locale`	ホストのバージョンと現在のUIロケール。
`ctx.lifecycle.phase`	`activating`、`migrating`、または`active`。
`ctx.capabilities`	このプラグインアクターに公開されるケイパビリティのバージョンのみ。
`ctx.domains`	許可された、ReadAwareが所有する状態と振る舞い。
`ctx.contributions`	プラグインが実装を提供できるレジストリ。
`ctx.services`	範囲を制限したホスト操作と、プラグイン専用の基盤。

権限で制御される名前空間は、許可されていない場合は存在しません。すべてのWorker呼び出しはホスト側でも認可されるため、メソッドを隠すだけがチェックではありません。登録は破棄可能オブジェクトを返し、アクティベーションに失敗した場合やプラグインを無効化した場合は逆順で回収されます。

ドメイン

ドメインはqueries、任意のcommands、コミット済みイベントのevents.subscribeを公開します。コマンドはReadAwareと同じイベントソース型の書き込み経路を使い、plugin:<id>に帰属します。書き込み権限には読み取り権限も含まれます。

ドメイン	クエリとコマンド	権限
`library`	書籍、メタデータ、元の章テキスト、目次、コレクション。インポート、編集、スター付け、削除、仮想書籍、コレクション操作のコマンド。	`library:read` / `library:write`
`reading`	書籍ごとおよび集計の読書統計。読了にする、書籍を開く、CFIまたはhrefへ移動する操作。	`reading:read` / `reading:write`
`annotations`	ハイライト、ノート、受動的な質問履歴の絞り込み。ハイライトやノートの作成、編集、色変更、削除。	`annotations:read` / `annotations:write`
`conversations`	書籍スレッドの読み取り、グローバルスレッドの一覧、スレッドの読み取り。書き込みはチャットランタイムが担います。	`conversations:read`
`settings`	許可されたカタログ項目の検出、解決済みの値の読み取り、対応する対象の更新、コミット済み変更の購読。	正確な`settingsAccess`許可

shelfやappearanceドメインはありません。ライブラリデータと現在の読書の振る舞いは分離されています。外観は設定内のセクションです。

設定へのアクセス

discover、read、writeは独立しています。可能な限り正確なパスを許可し、appearance.*のようなセクショングループは、その機能が本当にセクション全体を必要とする場合だけ使います。更新はカタログの検証、対象ポリシー、永続化、コミット後の効果を通過します。

typescript

const entries = await ctx.domains.settings.queries.discover({
  section: "appearance",
});

await ctx.domains.settings.commands.update([
  {
    path: "appearance.theme",
    value: "dark",
    target: { kind: "global" },
  },
]);

コントリビューション

レジストリ	プラグインが提供するもの	権限
`selectionActions`	トーストまたはホスト描画ビューを返す選択アクションとハンドラー。	なし
`headerActions`	リーダーまたはライブラリのアクション、配置メタデータ、ビューコールバック。	なし
`commands`	コマンドのメタデータとハンドラー。	なし
`settingsOptions`	宣言済みの1つのプラグインフィールドに対する動的な選択肢。	なし
`voiceProviders`	音声リストとエンコード済み音声の合成。	なし
`contentProviders`	仮想書籍キーのセクション。	なし
`readerModes`	範囲を制限したリーダー分割モード。現在はバンドルされたものに限定。	`reader:modes`
`agentTools`	ツールスキーマ、人間向けラベル、説明、実行関数。	`agent:tools`
`agentContextProviders`	範囲を制限した現在ターンの参照ブロック。	`agent:context`
`agentRetrievalProviders`	プラグインが所有するデータからの検索結果。	`agent:retrieval`
`memoryCandidateProviders`	永続化候補となる事実、嗜好、洞察、要約。	`agent:memory`
`themes`、`fonts`	マニフェストで宣言する意味的なテーマおよびフォントデータ。	`ui:themes`
`syncTransports`	同期バックエンドのセッション：封印済みイベントバッチ・blob・メタオブジェクトをプラグインが選ぶリモートに保存。	`sync:transport`

すべてのコントリビューションIDはプラグインごとの名前空間に属し、すべての登録は所有者を追跡でき検査可能です。古い破棄可能オブジェクトが新しい置き換えを削除することはありません。新しいコントリビューション種別には、意図的に用意したホスト側の利用者が必要です。それが用意されれば、アプリ側で名前を列挙しなくても互換性のあるプラグインを登録できます。

エージェント拡張の境界

コンテキストプロバイダーは1ターンだけ実行されます。ホストは出所情報を付加し、サイズを制限し、出力を信頼されていない参照データとしてシリアライズします。
検索プロバイダーは、ホストが所有するquery/limitスキーマと切り詰めた結果を持つ、名前空間付きのツールになります。
メモリ候補プロバイダーはターン後に範囲を制限した候補を提案します。ホストがスコープを検証し、重複を排除し、必要な永続書き込みを実行します。

プラグインがメモリポートを受け取ることはなく、システムルールを注入したり、長期メモリへ直接書き込んだりすることもできません。

同期トランスポート

syncTransports の登録は、もう一つの同期バックエンド — アプリの同期エンジンがプッシュ／プルするリモートのメールボックス — を提供します（ファーストパーティの WebDAV Sync プラグインはこの仕組みで WebDAV と話します）。境界は暗号文です。エンジンはプラグインがデータに触れる前にすべてのイベントと blob を封印するため、トランスポートが運ぶのは不透明な封筒とそのルーティングフィールド（イベント id、HLC スタンプ）だけで、イベント種別・書籍のバイト列・鍵は決して見えません。契約はダムストレージ — デバイスごとの稠密なイベントバッチ、エンジンの封筒形式の blob オブジェクト、先勝ちの鍵素材のための作成専用メタオブジェクトです。順序付け・カーソル・マージ・パスフレーズの儀式・スケジューリングはホスト側に残り、トランスポート接続は ReadAware アカウントと排他です。失敗は安定した sync/* コードを持つ Error を投げて分類し、コードのないエラーは一時的なものとして指数バックオフで再試行されます。

ホストサービス

サービス	契約	権限
`storage`	名前空間付きKV、ドキュメントコレクション、外部変更通知。	なし
`secrets`	名前空間付きの暗号化認証情報スロット。	なし
`ui`	ホストのトーストと保存・エクスポート処理。	なし
`schedules`	マニフェストで宣言した間隔にハンドラーをバインド。	なし
`session`	範囲を制限した読書セッション情報を購読。	なし
`network`	ホストを介したHTTP。	`service:network`
`llm`	ユーザー設定を使い、テキストまたはJSONスキーマで制約したモデル呼び出しを1回実行。	`service:llm`
`clipboard`	システムクリップボードへテキストを書き込み。	`service:clipboard`

ストレージ

小さな設定やチェックポイントにはKVを使います。安定したIDと任意のbookId/anchor出所情報を持つ、プラグイン所有レコード用の名前付きドキュメントコレクションを使います。出所情報はインデックスであり所有権ではないため、参照先の書籍を削除してもドキュメントが残ることがあります。アンインストールではドキュメントコレクションを消去しますが、再インストールとマイグレーションのためKV、シークレットスロット、コミット済みスキーマメタデータは保持します。

スケジュール

マニフェストは{ id, label, everyMinutes }を宣言し、アクティベーション時にctx.services.schedules.bindを通じてハンドラーをバインドします。最短間隔は15分です。アプリが開いている間は少なくともその間隔で実行され、期限を過ぎていれば起動後に追いつき、重複実行はしません。永続的なバックグラウンドジョブでも、厳密な時刻を保証するものでもありません。

宣言的UIと設定

プラグインは実行可能なUIではなく、バージョン管理されたビューのデータを返します。ビューの文法には、Markdown、検索可能なリスト、フォーム、詳細レイアウト、辞書結果、範囲を制限したブロックツリーが含まれます。ハンドラーはサーフェスを維持する、トーストを表示する、ビューを開くまたは置き換える、ナビゲーションをリセットする、サーフェスを閉じる、フィールドエラーを返す、といった操作を行えます。Promiseの読み込み中と失敗の状態はホストが管理します。

マニフェスト設定では、text、textarea、number、time、select、choice、checkbox、toggle、secretの各フィールドにホストのコントロールを使います。条件付きフィールドにはvisibleWhenを使い、動的なselectには登録済みのsettingsOptionsプロバイダーを使います。secretフィールドは暗号化されたシークレットスロットへ直接書き込み、通常の設定オブジェクトやエージェントから見えるカタログには入りません。

テーマとフォント

テーマプラグインはマニフェストで意味的なデータを宣言します。アプリテーマは固定されたホストトークンの語彙を上書きし、リーダーテーマは必須の6色によるページパレットと任意のタイポグラフィ既定値を提供します。ホストは値を検証し、CSSを生成し、承認済みのローカルフォントファイルを読み込みますが、ユーザーが選択するまで適用しません。

選択肢の提供にはui:themesが必要です。選択にはappearance.themeやreading.themeなど、設定への正確な書き込み許可が必要です。一方が他方を意味することはありません。

ライフサイクル段階

アクティベーション中: クエリとプラグイン専用の読み取りが利用可能です。登録はステージングされ、副作用はブロックされます。
マイグレーション中: プラグインのKVとドキュメントコレクションだけが利用可能です。
アクティブ: 昇格されたハンドラーは、許可されたドメイン、コントリビューション、サービスを利用できます。

ホストはアクティベーションRPCを排出し、Workerのヘルスチェックを行い、必要なデータマイグレーションを実行してから、ステージング済みの一式を明示的な1時点で昇格させます。アクティベーションに失敗した場合はステージング中の処理を破棄し、現在のランタイムを置き換えません。

Worker環境

React、Jotai、DOM、WebView、Tauri、SQLite、ファイルシステム、プロセスへのアクセスはありません。グローバルなfetch、WebSocket、EventSource、XMLHttpRequest、BroadcastChannel、IndexedDB、Cache Storageは無効化されています。ネットワーク、永続化、あらゆるホストとのやり取りには型付きコンテキストを使います。

互換性と安定性

ドメイン、コントリビューション、サービス、宣言的スキーマは、それぞれ独立したセマンティックバージョンを持ちます。不明なID、無効なsemver範囲、アクセスできない必須ケイパビリティ、互換性のないホストバージョンがあるとアクティベーションを阻止します。互換性のある追加では、グローバルなプラグインAPI番号ではなく、所有するケイパビリティのバージョンを上げます。

現在のエコシステムはファーストパーティのみであるため、現行のレジストリに基づく契約が基準です。以前のshelf、appearance、またはレジストリ導入前の構造に依存しないでください。