建立外掛程式
從一個實用的動作開始。在新增功能的過程中,持續讓相容性、權限與執行期行為保持可見。
取得範本與型別
公開外掛儲存庫包含範本、契約、登錄檔及其檢查機制。其中的 types/plugin-api.d.ts 與 types/host-capabilities.json 是由檔頭所標示的最新 ReadAware 版本產生:前者是完整契約,以 @readaware/plugin-api 匯入;後者列出各項能力的版本與解鎖所需的權限。請從中選擇 requires 的版本範圍。本站說明的是開發契約,可能領先該版本;Explorer 會顯示各項能力在最新版本中的版本號。
請使用 Bun,版本以 .bun-version 為準。執行 bun install,將 template/ 複製到 plugins/<your-plugin-id>/,並保持目錄名稱與 manifest ID 一致。
使用 AI 程式設計助手開發
將外掛儲存庫的 checkout 提供給 AI 程式設計助手,並指向 AGENTS.md。這份文件涵蓋了完整的工作流程、manifest 規則、沙盒環境、測試方式、一份經驗證的完整範例,以及 CI 執行的檢查項目。驗證器會對最新版本執行與應用程式相同的安裝檢查,因此 AI 程式設計助手不需要應用程式也能確認相容性。
最小化的命令
此範例會在啟用期間註冊一個命令,並僅在使用者執行時才產生其 UI 效果。
{
"id": "hello-reader",
"name": "Hello Reader",
"version": "0.1.0",
"schemaVersion": 1,
"main": "main.js",
"requires": {
"contributions": { "commands": "^1.1.0" },
"services": { "ui": "^1.17.0" }
}
}export default {
activate(ctx) {
ctx.contributions.commands.register({
id: "hello",
title: "Say hello",
run: () => ctx.services.ui.showToast("Hello, reader!"),
});
},
};將入口模組編譯為自包含的 main.js。上方的清單檔要求使用最新發布版本的版本號;只有在檢查並測試過那些合約之後,才使用較舊的版本範圍。
命令與快捷鍵
命令會顯示在命令面板以及「設定 → 快捷鍵」中,使用者可在此為任何命令綁定或重新綁定快捷鍵。命令可透過 defaultShortcut 建議綁定方式,例如和弦 { "key": "s", "mod": true, "shift": true };mod 在 macOS 上是 ⌘,在其他平台則是 Ctrl。請避免使用 types/host-capabilities.json 中 builtInShortcuts 所列的內建和弦:當兩個快捷鍵共用同一和弦時,按下該鍵將不會觸發任何命令,直到使用者重新綁定其中一個為止。使用者輸入時,快捷鍵不會觸發。
加入最小且實用的權限
使用 Explorer 尋找方法,並複製其起始的資訊清單片段。片段會宣告一項能力;請補齊該操作所需的授權。
- 讀取書庫資料需要
library:read;變更資料則需要library:write。 - 設定使用精確的
settingsAccess路徑與操作。 - 任意 HTTP 需要
service:network以及允許的networkAccess.origins。 - 位於無需權限的介面服務中的閱讀相關方法,仍可能需要
reading:read或reading:write。 - 書籍授權是透過主程式同意而選定,並透過
ctx.grants.book暴露;資訊清單無法自行取得另一本書的存取權。
檢查 ctx.capabilities,並處理缺少的選用命名空間。將 ReadAware 持有的資料保留在其領域中;外掛程式儲存空間僅用於你自己的紀錄、設定與檢查點。
處理觀察與取消
不再需要時,請釋放控制代碼(handle)。對於支援的呼叫,請傳入 AbortSignal 並等待實際結果。取消並不會還原已發生的寫入或遠端副作用。
自動反應使用 ctx.withEvent(delivery) 來處理後續工作,包括在 await 之後。契約要求時,請為因果訂閱提供穩定的 ruleId。使用者發起的動作使用原始啟用上下文。這能讓主程式偵測迴圈,而不會把獨立的動作混為一談。
本地建置與安裝
在外掛儲存庫的根目錄執行檢查。bun run check 與 CI 執行內容相同:驗證器、型別檢查、測試,以及一次必須與每個已提交 main.js 相符的重新建置。
bun install
bun run build
bun run check開啟 ReadAware → 設定 → 外掛 → 安裝外掛,選取建置後的資料夾,並檢視同意摘要。在桌面應用程式中實際操作該功能。重新建置並重新安裝,以驗證更新是否正常。
為私有資料設定版本
schemaVersion 與套件版本相互獨立。當儲存的 KV 或文件結構改變時,請透過 migrate(storageCtx, change) 提供支援的升級與降級轉換。
遷移只會取得儲存專屬的權限。除了成功案例,也請測試失敗的轉換:先前的套件與已提交的資料必須保持可用。一般程式碼更新請避免加入不必要的結構變更。
測試你的功能所用的邊界
檢查其實際的 Worker/Tauri 行為、權限與書籍範圍拒絕、取消、停用/重新啟用,以及失敗復原。若是介面外掛程式,請涵蓋鍵盤導覽、長文字與狹窄視窗。若是變更資料的外掛程式,請涵蓋並行編輯,以及在需要持久化的情況下重新啟動。
排程只會在應用程式開啟時執行;持久性工作僅支援主程式的型別化計畫。兩者都不是一般的背景程序或任意程式碼工作的執行器。API 參考說明了這些限制。
發布
一旦建置後的套件能搭配其宣告的最低契約正常運作,請遵循發布的說明。