ReadAware

建立外掛程式

從一個實用的動作開始。在新增功能的過程中，持續讓相容性、權限與執行期行為保持可見。

取得範本與型別

公開外掛程式存放庫包含範本、宣告、登錄與套件檢查。若涉及尚未發布的 API，請與目前原始碼契約比對，並使用相符的開發版建置。最新發布的應用程式可能比這份文件還舊。

存放庫腳本使用 Bun。將 template/ 複製到 plugins/<your-plugin-id>/，並讓目錄名稱與資訊清單 ID 保持一致。

最精簡的指令

這個範例在啟用期間註冊一個指令，並且只有在使用者執行它時才產生介面效果。

json
{
  "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" }
  }
}
typescript
export default {
  activate(ctx) {
    ctx.contributions.commands.register({
      id: "hello",
      title: "Say hello",
      run: () => ctx.services.ui.showToast("Hello, reader!"),
    });
  },
};

將進入點模組編譯為自足的 main.js。上述資訊清單刻意要求目前文件記載的版本；請在檢查並測試那些契約之後，才使用較舊的版本範圍。

加入最小且實用的權限

使用 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。使用者發起的動作使用原始啟用上下文。這能讓主程式偵測迴圈，而不會把獨立的動作混為一談。

在本機建置與安裝

遵循 checkout 的套件腳本。在公開外掛程式存放庫中，一般檢查如下：

bash
bun run build
bun run typecheck
bun test
bun run validate

開啟 ReadAware → 設定 → 外掛程式 → 安裝外掛程式，選取建置後的資料夾，並檢視同意摘要。在桌面應用程式中實際使用該功能。重新建置並重新安裝以確認更新。

為私有資料設定版本

schemaVersion 與套件版本相互獨立。當儲存的 KV 或文件結構改變時，請透過 migrate(storageCtx, change) 提供支援的升級與降級轉換。

遷移只會取得儲存專屬的權限。除了成功案例，也請測試失敗的轉換：先前的套件與已提交的資料必須保持可用。一般程式碼更新請避免加入不必要的結構變更。

測試你的功能所用的邊界

檢查其實際的 Worker/Tauri 行為、權限與書籍範圍拒絕、取消、停用／重新啟用，以及失敗復原。若是介面外掛程式，請涵蓋鍵盤導覽、長文字與狹窄視窗。若是變更資料的外掛程式，請涵蓋並行編輯，以及在需要持久化的情況下重新啟動。

排程只會在應用程式開啟時執行；持久性工作僅支援主程式的型別化計畫。兩者都不是一般的背景程序或任意程式碼工作的執行器。API 參考說明了這些限制。

發布

一旦建置後的套件能搭配其宣告的最低契約正常運作，請遵循發布的說明。