建置外掛
從公開的 TypeScript 範本開始，宣告最小的能力集合，並在 ReadAware 桌面應用程式中執行建置後的套件。宿主負責生命週期、權限、呈現和回復；外掛負責自己的行為和私有資料。
前置條件
- ReadAware 桌面應用程式，並可存取「設定 → 外掛」。
- Bun，用於執行儲存庫指令碼。
- readaware-plugins 儲存庫的複本或 fork。
建立套件
- 將
template/複製到plugins/<your-plugin-id>/。 - 保持資料夾名稱、manifest 的
id和執行階段命名空間完全一致。 - 編輯
manifest.json和src/main.ts。 - 刪除不使用的範本貢獻，並移除對應權限。
- 建置 ReadAware 將載入的自包含
main.js。
bun run build
bun run typecheck
bun test
bun run validate先設計 manifest，再實作
依照以下順序檢查 manifest：
- 身分：穩定 ID、名稱、套件版本、作者和最低應用程式版本。
- 資料：正整數
schemaVersion和遷移路徑。 - 相容性：為每個使用的 API 和 schema 在
requires中寫入 semver 範圍。 - 授權：語意
permissions和精確的settingsAccess授權。 - 宣告：設定、排程任務、主題、字型和進入模組。
安裝前使用能力瀏覽器和權限預覽。要求是相容性宣告，不是使用者授權；即使能力不需要權限，只要外掛依賴其契約，也必須寫入 requires。
選擇正確的能力
- ReadAware 擁有某種狀態或行為時，使用領域。
- 提供選擇、動作或供應商時，使用貢獻。
- 需要受限的宿主操作時，使用服務。
- 外掛儲存只用於外掛擁有的資料。
- 現有形態都不合適時，請求新的型別化宿主能力。
不要把書籍、進度、標註、設定或記憶複製到外掛儲存。影子狀態會繞過產品不變條件、已提交事件、投影重建、同步語意和助理上下文。
讓啟用保持宣告式
在 activate(ctx) 期間檢查環境，並註冊動作、命令、供應商、訂閱和排程任務。不要執行業務寫入或外部工作。宿主會一直暫存每項註冊，直到啟用 RPC 完成且 Worker 回覆健康檢查。
晉升後，從已註冊的處理常式啟動執行階段工作。如果處理常式回傳 promise，讓宿主顯示載入和失敗狀態。只有在可選的 deactivate() 必須關閉外部資源時，才保留這些資源的參照；宿主註冊和訂閱會自動釋放。
明確為私有資料建立版本
schemaVersion 為外掛 KV 和文件集合建立版本；它獨立於套件版本。只有私有資料形態改變時才修改它。在 schema 提交後，為每個支援的升級和降級匯出 migrate(storageCtx, change)。
- 遷移只能接收儲存：不能使用領域、設定、金鑰、網路、UI、LLM 或貢獻。
- 讓每次轉換都具備確定性和冪等性。
- 測試部分寫入後發生失敗的情況；宿主必須精確恢復 KV、文件、檔案和 schema 中繼資料。
- 不要用套件版本檢查取代資料 schema。
安裝工作資料夾
- 執行建置和檢查。
- 開啟 ReadAware → 設定 → 外掛 → 安裝外掛。
- 選擇建置出的外掛資料夾並檢查同意摘要。
- 在桌面應用程式中執行實際功能。
- 重新建置並安裝，以測試更新。
一般瀏覽器無法驗證外掛安裝、Worker IPC、SQLite 持久性、原始書籍存取、閱讀器整合或回復。請測試用於發佈的 Tauri 應用程式。
測試生命週期，而不只是成功路徑
- 全新安裝、啟用、停用，以及不重新啟動應用程式再次啟用。
- 使用真實資料完成成功更新和降級。
- 啟用逾時、處理常式拒絕、遷移失敗和精確回復。
- 解除安裝清理：不殘留動作、監聽器、排程、供應商或 Worker。
- 更新期間移除權限和擴充權限。
- 長標籤、空狀態、鍵盤導覽和所有宿主主題。
了解目前限制
ReadAware 開啟期間，排程任務至少按宣告的頻率執行，逾期時會在啟動時補執行。它們不是持久任務：應用程式關閉時不會執行，沒有持久佇列、重試／退避契約或當機恢復保證。
UI 只在現有的型別化貢獻點可用。缺少掛載位置時，需要宿主持有的貢獻點和消費者；不會為了走捷徑加入任意 HTML 或通用原生 invoke API。