外掛程式 API 參考

本頁說明目前的開發合約。「能力總覽」(Capabilities Explorer)列出即時目錄、確切的方法名稱、簽章與原始碼宣告。已發布的應用程式或公開範本可能使用較舊版本；請將你的 requires 範圍對應到已測試的主控端。

套件與 manifest

外掛程式包含 manifest.json 與一個自包含的 ES 模組，通常是 main.js。請將原始碼與所需資源與套件一起保留以供審查。

欄位	說明
`id`, `name`, `version`	穩定命名空間、顯示名稱與套件版本。ID 須與資料夾名稱相符。
`schemaVersion`	外掛程式私有資料結構的正整數版本；與套件版本無關。
`requires`	能力 ID 與 semver 範圍，分組為 `domains`、`contributions`、`services` 與 `schemas`。
`permissions`	語意權限，例如 `library:read` 或 `service:llm`。
`settingsAccess`	針對確切路徑或明確的區段群組，分別授予 `discover`、`read` 與 `write` 權限。
`networkAccess`	Network 2.x 允許的 HTTP(S) 來源；需與 `service:network` 同時宣告。
`minAppVersion`	選用的應用程式最低版本門檻，在能力需求之外額外設定。
`main`	相對的進入點模組；預設為 `main.js`。
`settings`, `schedules`, `themes`, `fonts`	由主控端解讀的宣告。
`services`	供跨外掛程式呼叫的版本化、型別化模組服務匯出。

沒有任何 manifest 欄位會授予任意的檔案系統、SQL、DOM 或原生 IPC 存取權。

內容與物件範圍

主控端會呼叫 activate(ctx)，並提供 ctx.domains、ctx.contributions、ctx.services，以及 manifest、locale、應用程式版本、生命週期階段、能力版本與不可變的書籍授權。

ctx.grants.book 的值為 all、current 或指定的 book。主控端透過同意流程選取。讀取、記憶、對話、指令與資源在呼叫與回呼之間都會維持該範圍。目前的書籍變更可能使未完成的讀取、控制代碼、提案與觀察結果失效。

領域寫入權限包含讀取權限。設定授予仍依操作個別獨立。受權限控管的命名空間或方法可能不存在；主控端仍會在每次呼叫時執行檢查。使用 ctx.services.session.operationAvailability(...) 進行支援的預先檢查查詢，且在取得肯定結果後仍須處理執行失敗的情況。

領域

領域	提供的功能	限制
`library`	書籍與收藏、目錄、精確位置搜尋、範圍、參考與圖片、匯入、文字任務、中繼資料、重複合併與移除。	來源版本、書籍範圍、受限讀取、參與者擁有的任務，以及獨立的檔案清理收據。
`reading`	工作階段快照、導覽、選取、播放與模式控制、進度、閱讀時間與洞察。	目前工作階段保護、已定案與待處理狀態、供應商可用性與取消。
`annotations`	頁面、檢查與觀察；建立劃線或筆記；條件式編輯/刪除批次。	使用使用者決定前的修訂版本。擷取的範圍也需要 Library 存取權。
`conversations`	授權的對話紀錄、儲存的摘要、執行期與輪替要求狀態；執行緒控制與提議的輪替。	主控端核准後才會開始提議的輪替。全域執行緒操作需要全部書籍的存取權。外掛程式不會取代聊天執行期。
`settings`	目錄探索、解析後快照、選項、模型中繼資料、觀察、更新與閱讀重設。	確切路徑、目標政策，以及外部供應商工作的額外授權。
`memory`	搜尋與頁面、檢查、修正/遺忘、個人資料、實體、分類、圖表與任務、內容封存。	書籍授權與條件式修訂。全域身分/個人資料操作需要全部書籍的存取權；產生內容也需要模型授權。

來源文字與導覽

使用 library.queries.books.searchLocations 取得可導覽的來源比對結果，使用 readRange 取得受限的來源文字。請保留回傳的來源版本與位置。衍生的 searchText 命中結果僅供預覽，不可互換作為導覽錨點。明確的文字準備會回傳一個任務，必須觀察其進度與結果。

條件式寫入

在顯示編輯前檢查目前物件並保留其修訂版本。針對該修訂版本送出條件式變更。若發生衝突，請重新讀取並讓使用者決定；靜默取代預期的修訂版本會覆蓋其他變更。

annotations.commands.applyChanges、記憶變更、私有文件提交與交易預覽各自有其型別化合約。一般指令不會自動成為可復原或分散式交易。

觀察與反應

使用授權的觀察取得目前狀態，使用已提交的訂閱取得事件。序號可以排序傳遞項目，但它不是資料庫游標或條件式寫入的修訂版本。失敗的觀察必須能與空結果區分。

使用 ctx.withEvent(delivery) 進行自動的後續工作，並在需要時於因果訂閱上使用穩定的規則 ID。透過非同步呼叫維持綁定的內容。主控端會拒絕因果迴圈與已過期的傳遞；獨立的使用者動作使用原始內容。

貢獻

貢獻	外掛程式提供的內容
`selectionActions`, `headerActions`, `contextActions`, `commands`, `uriHandlers`	在型別化的主控端介面上的動作、指令面板指令與命名空間 URI 處理。
`settingsOptions`	已宣告外掛程式設定的動態選項。
`voiceProviders`, `contentProviders`, `readerModes`	語音合成、虛擬書籍內容與內建的閱讀器分段模式。
`agentTools`, `agentContextProviders`, `agentRetrievalProviders`	工具、受限的每輪內容，以及可搜尋的外掛程式自有來源。
`memoryCandidateProviders`	供主控端驗證與接受的候選記憶。
`themes`, `fonts`	manifest 宣告的外觀選項。
`syncTransports`	不透明加密同步信封與中繼物件的儲存。

動作可以在支援的地方更新其擁有的可見/啟用/勾選狀態。註冊與可釋放資源屬於單次啟用。回傳檢視不會授予回呼額外的領域授權。

記憶候選與直接的 Memory 指令是不同路徑：候選會經過主控端接受，而直接指令需要對應的 Memory 授權與修訂版本。兩者都不允許注入系統規則或取代核心代理程式。

主控端服務

服務	用途	主要限制
`storage`	私有 KV、文件集合、條件式提交、頁面、觀察與使用政策。	外掛程式命名空間與配額；過期的游標需要重新取得基準。
`resources`	使用者挑選的檔案/目錄、密封的位元組控制代碼、匯出、圖片與私有二進位資源。	沒有環境隱含路徑。控制代碼有擁有者、限制與生命週期。
`secrets`	外掛程式私有的加密憑證插槽。	無法存取其他外掛程式的密碼。
`network`	來源範圍的 HTTP、受限的緩衝請求與串流。	每次重新導向都會檢查；不會自動重送任意的寫入。
`llm`	文字或結構化推論、串流、圖片資源、請求回執與預算。	使用者設定、隱私規則、取消與主控端/供應商限制。
`clipboard`	寫入文字或密封的圖片。	明確權限與支援的資源型別。
`ui`	檢視、toast、原生儲存/開啟流程、工作區與指令導覽、閱讀器面板與視窗。	方法特定的領域授權與主控端擁有的呈現。
`session`	非敏感的環境中繼資料與操作可用性。	沒有舊的閱讀工作階段訂閱；請使用 Reading 領域。
`schedules`	宣告的週期性處理常式與擁有的延遲要求。	工作只在應用程式開啟時執行；時間並非精確。
`jobs`	支援的持久性計畫、檢查點、觀察與控制。	型別化的主控端操作，而非任意的 JavaScript 執行。
`changes`	限範圍的持久性變更游標。	重新整理提示，而非原始事件記錄或歷史值。
`transactions`	預覽、提交、回執查詢與條件式復原預覽。	受支援的本機操作與原始授權；未知結果需要查詢回執。
`plugins`	檢查註冊、觀察變更、探索與呼叫型別化的外掛程式服務。	呼叫端/被呼叫端授權交集、範圍、版本與隔離的服務執行。
`maintenance`	狀態與主控端擁有的備份、連線測試與更新流程。	主控端保留憑證、檔案對話框與重大確認。
`sync`	授權的同步狀態、積壓與主控端管理的帳戶或同步流程。	沒有加密金鑰或原始帳戶憑證。
`diagnostics`, `logging`	經審查的診斷匯出與受限的結構化開發者事件。	沒有任意內容、密碼或透過日誌 API 的自動回報。

網路與推論

Network 2.x 需要同時具備語意權限與明確的來源：

json

{
  "requires": { "services": { "network": "^2.2.0" } },
  "permissions": ["service:network"],
  "networkAccess": { "origins": ["https://api.example.com"] }
}

將範例來源取代為你實際使用的端點。來源包含 scheme、主機與連接埠；它們不是 URL 路徑或子網域萬用字元。重新導向必須維持在授權範圍內。串流呼叫端在完成後關閉其擁有的串流。選擇性的安全重試僅限於回應送達前的受支援讀取要求；取消不會復原遠端副作用。

對於推論，使用 readingContext 取得書籍內容，以便主控端套用隱私與範圍規則。使用密封的資源 ID 作為支援的圖片。請求中繼資料與輸出預算有助於控制工作量；它們不是帳單明細，也不保證供應商合規。

背景工作與交易

使用 schedule 安排處理常式的呼叫，使用擁有的延遲要求在應用程式執行期間安排稍後的工作，並僅在型別化計畫支援該操作時使用持久性 job。重新啟動後的復原可能需要人工介入，而非盲目重複不確定的外部結果。

交易結合受支援的設定、私有文件與領域操作，並在原始授權下執行。預覽會凍結提議的工作；提交會消耗該預覽。在未知回應之後，先查詢回執再重試。復原是條件式的，要求狀態仍與先前結果相符。

跨外掛程式服務

在提供者 manifest 中宣告服務 ID、版本、範圍、所需權限與輸入/輸出結構描述，並在模組的 services 物件中匯出其處理常式。透過 Plugins 服務探索並呼叫它。主控端會以交集後的授權執行全新的隔離服務環境；它不會為了該呼叫而啟用提供者的一般 UI 執行期。代理程式發起的呼叫仍保留其核准要求。

檢視、設定、主題與字型

外掛程式回傳宣告式的檢視資料。主控端會呈現清單、表單、markdown、詳細資訊與支援的區塊版面。使用型別化的檢視結果與即時檢視更新；保持載入、衝突、空白與錯誤狀態可區分。外掛程式程式碼無法使用 React、DOM、iframe 或任意 CSS。

設定欄位由主控端呈現。密碼欄位會寫入加密的密碼插槽，不會成為一般表單值或模型可見的設定。提供主題或字型需要 ui:themes；選取主題或字型會使用對應的 Settings 寫入授權。

生命週期與相容性

啟用中： 支援的讀取與註冊；分階段的貢獻尚未可見。
遷移中： 僅限私有儲存空間，在提交變更的結構描述之前。
啟用完成： 升級的處理常式可以使用授予的能力。

主控端會在啟用與任何遷移成功後進行健康檢查並升級候選版本。失敗時會還原先前的套件與資料。卸載會釋放註冊、回呼與擁有的資源；持久性資料遵循其獨立的保留合約。在目前的開發階段，解除安裝會移除私有文件集合與二進位資源，但保留定義的 KV/密碼/結構描述狀態以供重新安裝。

獨立宣告每個使用的能力與結構描述。版本號碼證明合約相容性，而非每個作業系統、供應商或失敗案例都已通過端對端驗收。請驗證你實際發佈的桌面工作流程。

建立外掛程式 · 能力總覽 · 發布