ReadAware

外掛 API 參考

本頁說明開發契約,其內容可能領先最新正式版本。文末的完整參考列出每項能力,包含其開發版本與最新正式版本中的版本號、所需權限,以及各方法的解析簽名與文件。能力總覽提供相同目錄的互動式版本。公開外掛儲存庫中的型別與最新正式版本一致。

套件與 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 權限。
networkAccessNetwork 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, fontsmanifest 宣告的外觀選項。
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 寫入授權。

生命週期與相容性

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

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

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

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

完整參考

開發合約的每項能力,依類別分組。若外掛要供目前使用者使用的版本,應以最新正式版所列的版本號為最低需求。

領域

domains:library

檢視書籍、來源文字、目錄、精確位置、範圍、圖片與集合;匯入、整理並管理文字工作。

  • 開發版:v1.35.0
  • ReadAware 0.6.12:v1.35.0
  • 授權: library:read / library:write
ctx.domains.library.commands.books.addVirtualBook
(input: { providerId: string; key: string; title: string; author?: string; }): Promise<BookSummary>
ctx.domains.library.commands.books.cancelImportTask
(taskId: string): Promise<BookImportTaskSnapshot>
ctx.domains.library.commands.books.cancelTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>

Cancels only this activation's request; shared work or dispatched writes may continue.

ctx.domains.library.commands.books.editMetadata
(bookId: string, patch: { title?: string; author?: string; }): Promise<void>
ctx.domains.library.commands.books.importBook
(input: { fileName: string; data: ArrayBuffer | Uint8Array; }, options?: PluginCallOptions): Promise<BookSummary>
ctx.domains.library.commands.books.importResource
(id: string, options?: PluginCallOptions): Promise<BookImportReceipt>

Library 1.19 adds per-call cancellation. Before the first durable write, cancellation prevents admission; afterward await the actual imported/duplicate receipt or failure. No whole-file transfer, opening or resource release.

ctx.domains.library.commands.books.invalidateVirtualBook
(input: { providerId: string; key: string; }): Promise<{ bookId: string; revision: string; }>

Announce already-saved source changes. Does not reload or move the reader. revision is a process-local invalidation fence, not a content hash. Library 1.15.

ctx.domains.library.commands.books.mergeDuplicates
(input: BookMergeRequest): Promise<BookMergeReceipt>

Conditional record merge with the host's deterministic keeper; not file deletion or undo.

ctx.domains.library.commands.books.pauseTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>
ctx.domains.library.commands.books.prepareText
(bookId: string, options?: BookTextPrepareOptions): Promise<BookTextTaskSnapshot>

Library 1.31: starts an actor-owned background request. A receipt is not completion. Current-book grants fence admission and the lease through pause/resume; switching books cancels only this request, without undoing accepted writes.

ctx.domains.library.commands.books.remove
(bookId: string): Promise<void>
ctx.domains.library.commands.books.removeMany
(bookIds: string[]): Promise<BookRemovalReceipt>

1-1000 IDs, deduplicated. Atomic record deletion; local file release is separately reported.

ctx.domains.library.commands.books.removeVirtualBook
(input: { providerId: string; key: string; expectedBookId?: string; }): Promise<void>
ctx.domains.library.commands.books.resumeTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>

Library 1.21: reacquires this paused request using saved checkpoints and the same handle.

ctx.domains.library.commands.books.retryEnrichment
(bookId: string): Promise<BookEnrichmentReceipt>

Retry unchecked covers and missing/filename-derived metadata using the shared queue, without forcing replacement or download.

ctx.domains.library.commands.books.retryRemovalCleanup
(bookIds: string[]): Promise<BookFileReleaseReceipt>

Retry file release only. Refuses any ID now present in the library; never deletes records.

ctx.domains.library.commands.books.setStarred
(bookId: string, starred: boolean): Promise<void>
ctx.domains.library.commands.books.setTextTaskPriority
(bookId: string, taskId: string, priority: BookTextPriority): Promise<BookTextTaskSnapshot>

Library 1.21: pauses only this request by releasing its lease; other consumers and dispatched I/O may continue.

ctx.domains.library.commands.books.startImport
(input: BookImportRequest, options?: PluginCallOptions): Promise<BookImportTaskSnapshot>

Start a task over owned sealed resources or <=64 MiB file bytes (wire limits still apply). Queued is not imported. options.signal cancels admission only; use cancelImportTask after the receipt. At most 2 physical task executions per activation, 4 in the app; direct imports/picker jobs are outside this task quota. Tasks do not resume after restart. Accepted writes finish despite cancellation.

ctx.domains.library.commands.collections.assignBooks
(bookIds: string[], collectionId: string | null): Promise<void>
ctx.domains.library.commands.collections.create
(name: string): Promise<CollectionSummary>
ctx.domains.library.commands.collections.remove
(collectionId: string): Promise<void>
ctx.domains.library.commands.collections.rename
(collectionId: string, name: string): Promise<void>
ctx.domains.library.events.observeContentState
(bookId: string, handler: PluginObservationHandler<BookContentObservation>, options?: { ruleId?: string; }): PluginDisposable
ctx.domains.library.events.observeEnrichment
(bookId: string, handler: PluginObservationHandler<BookEnrichmentObservation>, options?: { ruleId?: string; }): PluginDisposable
ctx.domains.library.events.observeImportTask
(taskId: string, handler: PluginObservationHandler<BookImportTaskSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Initial snapshot and coalesced monotonic revisions, including terminal failures.

ctx.domains.library.events.observeInvalidation
(handler: PluginObservationHandler<ProjectionInvalidation>): PluginDisposable

Initial and coalesced reload hints, including remote projection changes. Re-query authorized data; not an event log or a conditional-write token.

ctx.domains.library.events.observeTextTask
(bookId: string, taskId: string, handler: PluginObservationHandler<BookTextTaskSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Library 1.32: serial reaction deliveries retain task and history-write sources.

ctx.domains.library.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.library.queries.books.get
(bookId: string): Promise<BookSummary | null>
ctx.domains.library.queries.books.getChapterText
(bookId: string, chapterIndex: number): Promise<string | null>
ctx.domains.library.queries.books.getContentState
(bookId: string, options?: PluginCallOptions): Promise<BookContentState>

Source metadata only; never loads a provider or reveals reading state. Library 1.16.

ctx.domains.library.queries.books.getEnrichment
(bookId: string): Promise<BookEnrichmentSnapshot>

Library 1.9: local cover/source state and the latest process-local enrichment attempt.

ctx.domains.library.queries.books.getImportTask
(taskId: string, waitMs?: number, options?: PluginCallOptions): Promise<BookImportTaskSnapshot>

waitMs (0..30000) waits for terminal state or returns current progress at the deadline. Cancelling this query stops observation only.

ctx.domains.library.queries.books.getNavigationToc
(bookId: string, options?: PluginCallOptions): Promise<BookNavigationToc>
ctx.domains.library.queries.books.getTextState
(bookId: string): Promise<BookTextSnapshot>

Read-only derived-text state. Never starts parsing, fetching, or extraction.

ctx.domains.library.queries.books.getTextTask
(bookId: string, taskId: string): Promise<BookTextTaskSnapshot>
ctx.domains.library.queries.books.getToc
(bookId: string): Promise<ChapterRef[]>
ctx.domains.library.queries.books.inspectResource
(id: string, options?: PluginCallOptions): Promise<BookInspection>

Initialize this activation's sealed resource with the reader parser; no import.

ctx.domains.library.queries.books.list
(): Promise<BookSummary[]>
ctx.domains.library.queries.books.listDuplicates
(query?: DuplicateBookQuery): Promise<DuplicateBookPage>

Library 1.10: same-content groups; live offset pages, limit 1-50.

ctx.domains.library.queries.books.listFormats
(): Promise<BookFormatCapability[]>

Library 1.11: import routing hints; extensions alone do not prove readability.

ctx.domains.library.queries.books.listImages
(input: BookReferencesQuery, options?: PluginCallOptions): Promise<BookImagesPage>

Library 1.29: section-local img/SVG, srcset/authored CSS and PDF image candidates. No remote fetch; PDF operator inspection can decode objects.

ctx.domains.library.queries.books.listImportTasks
(): Promise<BookImportTaskSnapshot[]>
ctx.domains.library.queries.books.listNavigationTargets
(input: BookNavigationTargetsQuery, options?: PluginCallOptions): Promise<BookNavigationTargetsPage>

Library 1.14: bounded source-section or author-supplied page-label catalog; not screen page counts.

ctx.domains.library.queries.books.listReferences
(input: BookReferencesQuery, options?: PluginCallOptions): Promise<BookReferencesPage>

Library 1.12: versioned section references, not extracted chapter indices.

ctx.domains.library.queries.books.listRemovalCleanup
(query?: BookRemovalCleanupQuery): Promise<BookRemovalCleanupPage>

Durable device-local pending file cleanup, including after view/plugin restart. Live keyset page, limit 1-100 (default 50).

ctx.domains.library.queries.books.listTextTaskHistory
(bookId: string, query?: BookTextTaskHistoryQuery): Promise<BookTextTaskHistoryPage>
ctx.domains.library.queries.books.listTextTasks
(bookId: string): Promise<BookTextTaskSnapshot[]>
ctx.domains.library.queries.books.openImageResource
(input: BookImageQuery): Promise<BookImageResource>

Seal an embedded image as this activation's ResourceRef; does not display it or decode pixels.

ctx.domains.library.queries.books.previewMerge
(bookId: string): Promise<BookMergePreview | null>
ctx.domains.library.queries.books.readRange
(input: BookRangeQuery, options?: PluginCallOptions): Promise<BookRangePage>
ctx.domains.library.queries.books.readReference
(input: BookReferenceQuery, options?: PluginCallOptions): Promise<BookReferencePreview>

Plain-text preview and resolved navigation location; never fetches or opens an external URL.

ctx.domains.library.queries.books.resolveId
(bookId: string): Promise<string | null>

Current book ID or merge redirect, null if neither points to a living book.

ctx.domains.library.queries.books.searchLocations
(input: BookLocationSearch, options?: PluginCallOptions): Promise<BookLocationSearchPage>
ctx.domains.library.queries.books.searchText
(input: BookTextSearch, options?: PluginCallOptions): Promise<BookTextHit[]>

Multi-query derived prose search. Single-book may prepare text; shelf search never does. Results are not navigation locations.

ctx.domains.library.queries.collections.booksIn
(collectionId: string): Promise<string[]>
ctx.domains.library.queries.collections.list
(): Promise<CollectionSummary[]>

domains:reading

觀察閱讀工作階段、導覽與選取文字、控制播放與模式,並查詢進度、時間與洞察。

  • 開發版:v2.24.0
  • ReadAware 0.6.12:v2.24.0
  • 授權: reading:read / reading:write
ctx.domains.reading.commands.back
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.clearSelection
(expectedId: string, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingSelectionReceipt>

Clears only the observed selection ID; a replacement selection is never silently cleared.

ctx.domains.reading.commands.close
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<void>
ctx.domains.reading.commands.configureMode
(input: ReadingModeConfiguration, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingModeReceipt>

Configure the host mode; modeKey guards the current provider, selectModeKey selects from session().mode.availableModes. Resolves after real indexing (ready/empty) or deactivation. Failed indexing rejects. Disabling the caller cancels an unfinished change; completed mode preferences remain.

ctx.domains.reading.commands.controlPlayback
(action: "start" | "stop", guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingPlaybackReceipt>

Start resolves on actual audio start. Stop is idempotent; disabling the initiating plugin stops its playback.

ctx.domains.reading.commands.forward
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.goTo
(target: ReadingTarget, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.openBook
(bookId: string, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>
ctx.domains.reading.commands.putEmphasis
(input: ReadingEmphasisWrite, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingEmphasisReceipt>

Temporary owned marks, not annotations. No navigation; replacement requires an observed revision.

ctx.domains.reading.commands.reload
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Reading 2.21: reopen source; virtual sections with identical stable identity/content preserve their location across reorder. Stale/legacy virtual locators restart at the beginning; files still restart. Whole-book contentVersion guards remain strict.

ctx.domains.reading.commands.removeEmphasis
(input: ReadingEmphasisRef, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingEmphasisRemoval>
ctx.domains.reading.commands.returnToMode
(guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Return to the versioned resting unit; wait for renderer navigation and unit restoration before committing history.

ctx.domains.reading.commands.selectRange
(range: BookTextRange, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingSelectionReceipt>

Requires this book to be open; validates its source range, navigates, then waits for the selection overlay commit.

ctx.domains.reading.commands.setControls
(visible: boolean, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingControlsReceipt>

Set reader chrome visibility; completes after UI commit. Does not alter panel preferences or playback.

ctx.domains.reading.commands.setFinished
(bookId: string, finished: boolean): Promise<void>
ctx.domains.reading.commands.step
(direction: ReadingStep, guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingNavigationReceipt>

Reading 2.12: page, source-section and book-boundary navigation; section/boundary jumps enter history.

ctx.domains.reading.commands.stepMode
(direction: "next" | "previous", guard?: ReadingSessionGuard, options?: PluginCallOptions): Promise<ReadingModeStepReceipt>

Step one configured text unit, across sections if necessary; reports book boundaries explicitly.

ctx.domains.reading.events.observeEmphasis
(handler: (snapshot: ReadingEmphasisSnapshot[], delivery?: PluginReactionEvent) => void | Promise<void>): PluginDisposable
ctx.domains.reading.events.observeSession
(handler: (snapshot: ReadingSessionSnapshot, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Immediate and subsequent snapshots carry a live reaction lease. Use withEvent for automatic writes; keep the original context for later user actions. A stable ruleId can resume job causality across activations.

ctx.domains.reading.events.observeTime
(query: ReadingTimeQuery, handler: (event: ReadingTimeObservation, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Immediate sample then a 1s minimum gap after each delivery. Errors are explicit; dispose stops further delivery. Reading 2.24: delivery retains sampling subscription ancestry across timers. It does not identify historical writers of the aggregate.

ctx.domains.reading.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.reading.queries.emphasis
(): Promise<ReadingEmphasisSnapshot[]>

This activation's temporary marks only; attached does not mean visible in the viewport.

ctx.domains.reading.queries.session
(): Promise<ReadingSessionSnapshot>
ctx.domains.reading.queries.stats.forBook
(bookId: string): Promise<BookStats | null>
ctx.domains.reading.queries.stats.insights
(query?: ReadingInsightsQuery): Promise<ReadingInsights>
ctx.domains.reading.queries.stats.list
(): Promise<BookStats[]>
ctx.domains.reading.queries.stats.overview
(): Promise<StatsOverview>
ctx.domains.reading.queries.stats.time
(query?: ReadingTimeQuery): Promise<ReadingTimeSnapshot>

Atomic settled + pending time, with native sampling clock. Reading >=2.7.

domains:annotations

分頁、檢視並觀察螢光標示與筆記;建立標註,或套用經版本檢查的編輯與刪除。

  • 開發版:v2.2.0
  • ReadAware 0.6.12:v2.2.0
  • 授權: annotations:read / annotations:write
ctx.domains.annotations.commands.applyChanges
(changes: AnnotationMutation[]): Promise<AnnotationCommitResult>

Since 2.0 this is the only edit/delete entry. Use the revision observed before the user's decision; 1..100 distinct items, all commit or none.

ctx.domains.annotations.commands.createHighlight
(input: { range?: BookTextRange; bookId: string; text: string; anchor?: string | null; chapterHref?: string | null; color?: HighlightColor; style?: HighlightStyle; }): Promise<HighlightItem>

annotations >=2.1: range validates and preserves the captured source; requires library:read.

ctx.domains.annotations.commands.createNote
(input: { range?: BookTextRange; bookId: string; body: string; quotedText?: string; anchor?: string | null; chapterHref?: string | null; }): Promise<NoteItem>
ctx.domains.annotations.events.observe
(query: AnnotationObservationQuery, handler: PluginObservationHandler<AnnotationObservation>): PluginDisposable

Since 1.4. Initial authorized snapshot, then changed results/errors/recovery. Disposal ends delivery.

ctx.domains.annotations.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.annotations.queries.get
(annotationId: string): Promise<AnnotationItem | null>

annotations >=1.1.0. Missing IDs return null; read failures reject.

ctx.domains.annotations.queries.inspect
(annotationId: string): Promise<AnnotationSnapshot | null>

annotations >=1.3.0. Read an item and its conditional-write token atomically.

ctx.domains.annotations.queries.list
(filter?: { bookId?: string; kind?: "highlight" | "note" | "ask"; query?: string; }): Promise<AnnotationItem[]>
ctx.domains.annotations.queries.page
(input?: AnnotationPageQuery): Promise<AnnotationPage>

annotations >=1.2.0. Live keyset page, not a frozen snapshot across calls.

domains:conversations

讀取經授權的逐字稿、摘要與執行時狀態;提出回合、管理討論串,並使用核准的停止或清除控制項。

  • 開發版:v1.7.0
  • ReadAware 0.6.12:v1.7.0
  • 授權: conversations:read / conversations:write
ctx.domains.conversations.commands.cancelTurnRequest
(id: string): Promise<ConversationTurnRequestSnapshot>
ctx.domains.conversations.commands.clear
(target: ConversationTarget): Promise<ConversationControlReceipt>

Clears transcript/hidden thread state after draining turns, not long-term memory or event history.

ctx.domains.conversations.commands.createThread
(): Promise<ConversationControlReceipt & { draft: true; }>

Creates and selects a global draft; no transcript row until the first message. Does not navigate the app.

ctx.domains.conversations.commands.requestTurn
(request: ConversationTurnRequest): Promise<ConversationTurnRequestSnapshot>

Requires a mounted conversation. Only a host UI confirmation can adopt/send/retry; receipt is not a completed turn.

ctx.domains.conversations.commands.selectThread
(threadId: string): Promise<ConversationControlReceipt>
ctx.domains.conversations.commands.stop
(target: ConversationTarget): Promise<ConversationControlReceipt>

Stops live UI turns and waits for their final transcript writes. Does not undo tool effects.

ctx.domains.conversations.events.observeInvalidation
(handler: PluginObservationHandler<ProjectionInvalidation>): PluginDisposable
ctx.domains.conversations.events.observeRuntime
(handler: PluginObservationHandler<PluginConversationRuntimeSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Conversations 1.6: serial reaction deliveries, with an optional stable rule ID.

ctx.domains.conversations.events.subscribe
<K>(event: K, handler: (event: PluginDomainEvent<K>) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.conversations.queries.getBookThread
(bookId: string): Promise<ChatMessageSummary[]>
ctx.domains.conversations.queries.getInsights
(target: ConversationTarget): Promise<string | null>

Conversations 1.4: stored rolling summary of a book/global thread, or null. No generation, freshness guarantee, raw runtime state or summary writes.

ctx.domains.conversations.queries.getThread
(threadId: string): Promise<ChatMessageSummary[]>
ctx.domains.conversations.queries.listThreads
(): Promise<ThreadSummary[]>
ctx.domains.conversations.queries.runtime
(): Promise<PluginConversationRuntimeSnapshot>
ctx.domains.conversations.queries.turnRequests
(): Promise<ConversationTurnRequestSnapshot[]>

Up to 128 recently retained host requests, filtered to this actor; no text or other actors' requests.

domains:settings

探索精確設定路徑與選項、讀取穩定快照、觀察變更並更新支援的目標。

  • 開發版:v1.11.0
  • ReadAware 0.6.12:v1.11.0
  • 授權: 無
ctx.domains.settings.commands.refreshModelCatalog
(provider: string, options?: PluginCallOptions): Promise<ModelCatalogPage>

Settings 1.9: additionally requires service:network. Shared native refresh, not a connection test.

ctx.domains.settings.commands.resetReading
(request: ReadingSettingsReset): Promise<SettingsUpdateResult>

Settings 1.7: reset the whole reader-preference bundle; every reading path must be writable. defaults restores built-ins; inherit deletes active and remembered book overrides.

ctx.domains.settings.commands.update
(changes: SettingChange[]): Promise<SettingsUpdateResult>
ctx.domains.settings.events.subscribe
(handler: (event: SettingsChangedEvent & PluginReactionEvent) => unknown, options?: { ignoreSelf?: boolean; ruleId?: string; }): PluginDisposable
ctx.domains.settings.queries.discover
(query?: SettingsQuery): Promise<SettingCatalogEntry[]>
ctx.domains.settings.queries.modelCatalog
(query: ModelCatalogQuery): Promise<ModelCatalogPage>

Settings 1.9: cached public model metadata; discover access to primaryModel or fastModel. No network.

ctx.domains.settings.queries.observe
(query: SettingsQuery, handler: PluginObservationHandler<SettingsObservation>): PluginDisposable

Settled snapshots after native, domain, remote, restore and catalog changes. Coalesces slow callbacks.

ctx.domains.settings.queries.options
(query: SettingsOptionsQuery): Promise<SettingsOptionsPage>

Settings 1.8: bounded options; same path grants as discover. Includes installed system families for reading/content fonts without font paths or bytes. Since 1.10, dynamicOptions fields invoke the registered owning provider with saved non-secret form values, never caller-supplied values. Network-enabled providers additionally require this caller's service:network permission. Results are cached for 60 seconds, at most 16 lists / 2000 options per list, 512 characters per label/value and 1 MiB of label/value JSON. Pages retain the returned revision; changed settings/provider or expiry require restart. Four provider loads host-wide, 10-second wait; already-started provider work is not cancelled by this deadline or caller retirement. No writes/synthesis. Plugin-owned option queries require the caller's active phase, not activation/migration. Empty results still allow manual values; provider failures remain failures.

ctx.domains.settings.queries.read
(path: string, target?: SettingsQueryTarget): Promise<SettingReadResult>
ctx.domains.settings.queries.snapshot
(query?: SettingsQuery): Promise<SettingsSnapshot>

Since settings 1.3: one host snapshot after prior queued writes settle, filtered by exact path grants.

domains:memory

搜尋、分頁、檢視與修正記憶;處理個人檔案、實體、分類、圖譜與版本化上下文套件。

  • 開發版:v2.8.0
  • ReadAware 0.6.12:v2.8.0
  • 授權: memory:read / memory:write
ctx.domains.memory.commands.cancelGraphTask
(bookId: string, taskId: string): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.classify
(input: BookClassificationChange): Promise<BookClassificationReceipt>
ctx.domains.memory.commands.completeOnboarding
(input: OnboardingChange, options?: PluginCallOptions): Promise<OnboardingReceipt>

Memory 2.5: confirm the full summary AND seeds before calling. Reuse the same owner-local submissionId and exact candidate after a lost receipt; a different candidate requires a new id and renewed confirmation. Atomic, event-backed.

ctx.domains.memory.commands.context.capture
(selector: ContextBundleSelector, options?: PluginCallOptions): Promise<ContextBundleCaptureReceipt>
ctx.domains.memory.commands.decideEntity
(input: EntityDecision, options?: PluginCallOptions): Promise<EntityDecisionReceipt>

Memory 2.1: resolve an original member or merge known resolved classes using an observed entities1 revision. Present the exact change for confirmation first. Retains original definitions/aliases, may sync to other devices. No blind conflict retry. Cancellation prevents dispatch only; dispatched writes drain to their actual receipt. A transport timeout or lost Worker leaves the outcome unknown: reread, never retry blindly.

ctx.domains.memory.commands.mutate
(input: MemoryMutation): Promise<MemoryMutationReceipt>
ctx.domains.memory.commands.retryGraphTask
(bookId: string, taskId: string, options?: BookGraphTaskOptions): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.startGraphTask
(bookId: string, mode: "catch-up" | "rebuild", options?: BookGraphTaskOptions): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.commands.updateProfile
(input: UserProfileChange): Promise<UserProfileReceipt>

Replace the event-backed summary using the observed profile2 revision. Present the complete candidate for user confirmation before calling. Empty text clears the summary, not memories or historical copies.

ctx.domains.memory.events.observe
(query: MemoryObservationQuery, handler: PluginObservationHandler<MemoryObservation>): PluginDisposable

Initial snapshot, then changed results/errors; re-read when the store announces a change, not an event log. Plugins 1.5 supplies a separate reaction delivery, including graph task updates.

ctx.domains.memory.queries.bookGraph
(bookId: string, query?: BookGraphQuery): Promise<BookGraphResult>

memory >=2.6 only exposes current-source digests; chapter results carry contentVersion for navigation.

ctx.domains.memory.queries.classification
(bookId: string): Promise<BookClassificationSnapshot | null>
ctx.domains.memory.queries.context.export
(query: ContextBundleReadQuery, options?: PluginCallOptions): Promise<ResourceRef>
ctx.domains.memory.queries.context.history
(query: ContextBundleHistoryQuery, options?: PluginCallOptions): Promise<ContextBundleHistoryPage>
ctx.domains.memory.queries.context.read
(query: ContextBundleReadQuery, options?: PluginCallOptions): Promise<ContextBundle | null>
ctx.domains.memory.queries.entities
(query?: EntityQuery, options?: PluginCallOptions): Promise<EntityPage>

Global explicit identities, not book-digest characters. Row-bounded, revision-pinned pages. Memory 2.2 adds canonicalDefinition from the same snapshot. Historical field sizes are not bounded. Aborted/retired callers receive no late page.

ctx.domains.memory.queries.getGraphTask
(bookId: string, taskId: string): Promise<BookGraphTaskSnapshot>
ctx.domains.memory.queries.inspect
(id: string): Promise<MemorySnapshot | null>
ctx.domains.memory.queries.listGraphTasks
(bookId: string): Promise<BookGraphTaskSnapshot[]>
ctx.domains.memory.queries.page
(input: MemoryPageQuery): Promise<MemoryPage>
ctx.domains.memory.queries.profile
(query?: UserProfileQuery): Promise<UserProfilePage>

The event-backed summary projection; read grant, bounded revision-pinned pages.

ctx.domains.memory.queries.profileContext
(query?: ProfileInspectionQuery, options?: PluginCallOptions): Promise<ProfileInspectionPage>

Memory 2.3: inspect the generated summary and provenance, separately from curated profile(). Summary pages count UTF-16 units (4000 default, 16000 max); provenance pages count rows (25 default, 100 max; historical ID sizes are unbounded). Pin every page kind to pctx1. Stale text is inspectable, never current context. Invalid blocks expose no content. Current means source-consistent, not semantic verification or completed consolidation. entityEvidence IDs include proposed no-ops, not proof of emitted events. Read grant; no source text, transcripts, raw traits, registry writes or automatic inference.

ctx.domains.memory.queries.search
(input: MemoryQuery): Promise<MemoryRecord[]>

貢獻

contributions:uriHandlers

透過已註冊的動作處理具命名空間的 ReadAware URI 呼叫。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.uriHandlers.register
(handler: PluginUriHandler): PluginActionRegistration

contributions:selectionActions

為擷取的選取內容、標註或導覽器輸入加入動作。

  • 開發版:v1.2.0
  • ReadAware 0.6.12:v1.2.0
  • 授權: 無
ctx.contributions.selectionActions.register
(action: PluginSelectionAction): PluginActionRegistration

contributions:headerActions

使用宿主算繪檢視加入閱讀器、書庫或代理程式標題列動作。

  • 開發版:v1.2.0
  • ReadAware 0.6.12:v1.2.0
  • 授權: 無
ctx.contributions.headerActions.register
(action: PluginHeaderAction): PluginActionRegistration

contributions:contextActions

為支援的書籍或集合上下文介面加入具型別的動作。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.contextActions.register
(action: PluginContextAction): PluginActionRegistration

contributions:commands

加入具命名空間的命令面板動作並更新其擁有的狀態。

  • 開發版:v1.1.0
  • ReadAware 0.6.12:v1.1.0
  • 授權: 無
ctx.contributions.commands.register
(command: PluginCommand): PluginActionRegistration

contributions:settingsOptions

為已宣告的外掛設定解析動態選項。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.settingsOptions.register
(fieldId: string, provider: (values: PluginFormValues) => PluginSelectOption[] | Promise<PluginSelectOption[]>): PluginDisposable

contributions:settingsPage

在外掛自身的「設定」區塊中註冊一個宣告式頁面,取代其 manifest 設定表單。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.settingsPage.register
(page: { view(): PluginView | Promise<PluginView>; }): PluginDisposable

contributions:voiceProviders

提供朗讀用的語音選項與編碼音訊。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.voiceProviders.register
(provider: PluginVoiceProvider): PluginDisposable

contributions:contentProviders

為儲存的來源等虛擬書籍提供章節。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.contributions.contentProviders.register
(provider: { id: string; load(key: string): Promise<PluginBookContent>; }): PluginDisposable

contributions:agentTools

註冊閱讀助理可以探索與呼叫的具命名空間工具。

  • 開發版:v1.3.0
  • ReadAware 0.6.12:v1.3.0
  • 授權: agent:tools
ctx.contributions.agentTools.register
(tool: PluginToolDefinition): PluginActionRegistration

contributions:agentContextProviders

提供受限的每輪參考區塊與宣告的閱讀意圖來源。

  • 開發版:v1.1.0
  • ReadAware 0.6.12:v1.1.0
  • 授權: agent:context
ctx.contributions.agentContextProviders.register
(provider: PluginAgentContextProvider): PluginDisposable

contributions:agentRetrievalProviders

向助理公開可搜尋的外掛擁有來源。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: agent:retrieval
ctx.contributions.agentRetrievalProviders.register
(provider: PluginAgentRetrievalProvider): PluginDisposable

contributions:memoryCandidateProviders

提出供記憶接納的事實、偏好、洞察或摘要。

  • 開發版:v1.1.0
  • ReadAware 0.6.12:v1.1.0
  • 授權: agent:memory
ctx.contributions.memoryCandidateProviders.register
(provider: PluginMemoryCandidateProvider): PluginDisposable

contributions:themes

在 manifest 中宣告語意化應用程式與閱讀器主題選項。

  • 開發版:v1.2.0
  • ReadAware 0.6.12:v1.2.0
  • 授權: ui:themes
ctx.contributions.themes.readerBases
(): Promise<PluginReaderThemeBase[]>

Themes 1.2: built-in and active plugin reader bases, excluding image themes. Saved copies do not change when the original theme changes.

ctx.contributions.themes.register
(theme: PluginRuntimeTheme): Promise<PluginDisposable>

contributions:fonts

宣告字型中繼資料與封裝的字型資產。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: ui:themes

Manifest 宣告

contributions:syncTransports

在外部遠端儲存與取回不透明的加密事件、blob 與金鑰材料中繼物件。

  • 開發版:v2.0.0
  • ReadAware 0.6.12:v2.0.0
  • 授權: sync:transport
ctx.contributions.syncTransports.register
(transport: PluginSyncTransport): PluginDisposable

服務

services:storage

使用私有 KV 與文件集合、頁面、觀察、條件式提交及配額政策。

  • 開發版:v2.6.0
  • ReadAware 0.6.12:v2.6.0
  • 授權: 無
ctx.services.storage.applyDocuments
(changes: PluginDocumentChange[]): Promise<PluginDocumentCommit>

Storage 2.1: atomically compare and apply 1..100 private document changes. Every expected revision is checked before any write. Does not include KV, core domain events, files, or another plugin's documents.

ctx.services.storage.collection
(name: string): PluginDocumentCollection

A named document collection — structured plugin-private data one tier above the KV (queryable, per-document, optionally book-anchored). Backed by the app's local store; lifecycle belongs to the plugin (uninstall clears it). bookId/anchor are provenance INDEXES, not ownership — documents survive the referenced book's deletion.

ctx.services.storage.documents(collection).delete
(id: string): Promise<void>
ctx.services.storage.documents(collection).get
<T>(id: string): Promise<PluginDocument<T> | null>
ctx.services.storage.documents(collection).list
<T>(filter?: { bookId?: string; limit?: number; oldestFirst?: boolean; }): Promise<PluginDocument<T>[]>

Newest-first by default.

ctx.services.storage.documents(collection).page
<T>(filter?: PluginDocumentPageFilter): Promise<PluginDocumentPage<T>>

Storage 2.1: 1..200 rows (default 50), 4 MiB JSON per page. Cursors bind namespace/filter/order and expire on any collection write. On stale-cursor restart rather than combining different snapshots.

ctx.services.storage.documents(collection).put
(id: string, data: unknown, options?: { bookId?: string; anchor?: string; }): Promise<void>
ctx.services.storage.flush
(): Promise<void>

Wait for outstanding writes in this plugin's namespace.

ctx.services.storage.get
<T>(key: string): T | null
ctx.services.storage.getDurable
<T>(key: string): Promise<T | null>

2.4: keys up to 1024 UTF-16 units, no NUL. Settle accepted writes, then read this private key from SQLite, not the optimistic mirror. Corrupt JSON rejects; null means absent or JSON null.

ctx.services.storage.observeDocuments
<T>(query: PluginDocumentObservationQuery, handler: PluginObservationHandler<PluginDocumentObservation<T>>): PluginDisposable

Storage 2.2: initial and changed private document query snapshots, including errors/recovery. At most 64 active observers per activation. The query is re-read when one of its documents is written (from any surface of this plugin on this device, or another process such as the CLI), and one callback settles before the next. Not a replayable write stream. Dispose or plugin retirement stops delivery; sequence is not CAS.

ctx.services.storage.onChange
(handler: PluginObservationHandler<{ kind: "changed"; }>, options?: { ruleId?: string; }): PluginDisposable

Fires when this plugin's namespace is written from OUTSIDE the plugin — its settings page, the reading agent, another surface editing the same object. Settings-key changes can also echo after own writes. Serial callbacks receive a reaction credential; use withEvent to preserve causes. No initial callback; intermediate changes coalesce. Use it to re-read (or re-derive from) settings you would otherwise have cached at activate().

ctx.services.storage.policy
(): Promise<PluginStoragePolicy>

Storage 2.5: own persisted usage and actual per-store policy. Null quota means no enforced total limit, not unlimited disk. Call flush first when awaiting this activation's pending writes. No names or secret values. Complete backup refers to full app backup, not reading/OPML exports.

ctx.services.storage.remove
(key: string): Promise<void>
ctx.services.storage.set
(key: string, value: unknown): Promise<void>

Reads update optimistically; resolve only after the write is durable.

services:secrets

在外掛私有加密槽中讀寫憑證。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.services.secrets.get
(key: string): Promise<string | null>
ctx.services.secrets.remove
(key: string): Promise<void>
ctx.services.secrets.set
(key: string, value: string): Promise<void>

services:ui

發佈檢視、顯示提示、儲存或開啟資源、導覽工作區與命令,並控制支援的閱讀器面板與視窗。

  • 開發版:v1.18.0
  • ReadAware 0.6.12:v1.18.0
  • 授權: 無
ctx.services.ui.commands.execute
(request: HostCommandRequest): Promise<HostCommandReceipt>

Library write plus each command's setting grant; opening/leaving a reader needs reading:write.

ctx.services.ui.commands.list
(): Promise<HostCommandSnapshot>
ctx.services.ui.commands.observe
(handler: PluginObservationHandler<HostCommandObservation>, options?: { ruleId?: string; }): PluginDisposable

UI 1.16: serial/coalesced snapshots with a reaction delivery and optional stable ruleId.

ctx.services.ui.exportFile
(file: PluginExportFile): Promise<boolean>
ctx.services.ui.openExternal
(url: string): Promise<void>

UI 1.7, requires service:network. Explicit user intent only; HTTP(S), no credentials or local schemes.

ctx.services.ui.publishView
(channel: PluginViewChannel, update: PluginViewUpdate): Promise<PluginViewUpdateReceipt>

Updates only this activation's visible frame. Revision is a nonnegative, increasing safe integer. Receipt confirms host acceptance, not paint; updates cannot navigate or replace the subscription.

ctx.services.ui.reader.closeReferencePreview
(id: string): Promise<ReaderReferenceCloseReceipt>

Only this activation's current preview ID; never closes a native or other owner's note.

ctx.services.ui.reader.focus
(target: ReaderFocusTarget, guard?: ReadingSessionGuard): Promise<ReaderFocusReceipt>

UI 1.14, reading:write. Focus an already visible semantic target, without opening or dismissing UI. not-focused is not success; close your own dialog before returning focus.

ctx.services.ui.reader.image.control
(request: ReaderImageRequest): Promise<ReaderImageReceipt>

reading:write; exact current viewer ID required. Pan deltas are fractions of its viewport.

ctx.services.ui.reader.image.observe
(handler: PluginObservationHandler<ReaderImageSnapshot | null>): PluginDisposable

Plugins 1.6 supplies a separate reaction delivery, including closed/null snapshots.

ctx.services.ui.reader.image.open
(query: BookImageQuery, guard?: ReadingSessionGuard): Promise<ReaderImageOpenReceipt>

UI 1.13: library read + reading write; opens an embedded image in the current book.

ctx.services.ui.reader.image.snapshot
(): Promise<ReaderImageSnapshot | null>
ctx.services.ui.reader.observe
(handler: PluginObservationHandler<ReaderPanelsSnapshot | null>): PluginDisposable

Plugins 1.6 supplies a separate reaction delivery; callbacks are serial and coalesced.

ctx.services.ui.reader.previewReference
(query: BookReferenceQuery, guard?: ReadingSessionGuard): Promise<ReaderReferencePreviewReceipt>

UI 1.8: also needs library:read. Open book only; resolved preview waits for DOM commit.

ctx.services.ui.reader.setPanel
(panel: ReaderPanel, open: boolean, guard?: ReadingSessionGuard): Promise<ReaderPanelReceipt>

Requires reading:write. Opening reveals controls; completion waits for persistence and DOM commit.

ctx.services.ui.reader.setWidth
(panel: ResizableReaderPanel, width: number, guard?: ReadingSessionGuard): Promise<ReaderPanelReceipt>

Persist a shared TOC/chat width (integer 240..640 CSS px); does not open it or focus.

ctx.services.ui.reader.snapshot
(): Promise<ReaderPanelsSnapshot | null>
ctx.services.ui.showToast
(message: PluginToast): void
ctx.services.ui.window.control
(request: HostWindowRequest): Promise<HostWindowReceipt>
ctx.services.ui.window.observe
(handler: PluginObservationHandler<HostWindowObservation>, options?: { ruleId?: string; }): PluginDisposable

UI 1.17: reaction delivery remains valid until the callback settles.

ctx.services.ui.window.snapshot
(): Promise<HostWindowSnapshot>
ctx.services.ui.workspace.navigate
(target: WorkspaceTarget, expectedRevision?: number): Promise<WorkspaceReceipt>

Library write grant; leaving an active reader additionally requires reading:write. UI 1.18: { surface: "annotations" } opens the highlights & notes page, which snapshots report.

ctx.services.ui.workspace.observe
(query: WorkspaceQuery, handler: PluginObservationHandler<WorkspaceSnapshot | null>, options?: { ruleId?: string; }): PluginDisposable

UI 1.16: use the separate reaction delivery even for null/retired snapshots.

ctx.services.ui.workspace.snapshot
(query?: WorkspaceQuery): Promise<WorkspaceSnapshot>

services:schedules

繫結宣告的週期處理常式、檢視與控制排程,並管理擁有的延遲請求。

  • 開發版:v2.1.0
  • ReadAware 0.6.12:v2.1.0
  • 授權: 無
ctx.services.schedules.bind
(scheduleId: string, run: (context: PluginScheduleRun, delivery?: PluginReactionEvent) => void | Promise<void>): PluginDisposable
ctx.services.schedules.cancelDeferred
(id: string, requestId: string, options?: PluginCallOptions): Promise<PluginDeferredReceipt>

Cancel exactly the queued ID, not an in-flight callback or a replacement request.

ctx.services.schedules.control
(id: string, action: "pause" | "resume" | "run"): Promise<PluginScheduleReceipt>

Pause/resume persist; run bypasses pause/cadence once. Neither pause nor cancellation undoes dispatched callback effects.

ctx.services.schedules.defer
(id: string, input: PluginDeferredRequest, options?: PluginCallOptions): Promise<PluginDeferredReceipt>

Schedules 2: enqueue one declared deferred task. Persists before acknowledgement. 1 second..7 days; idle means 5 seconds without host input. Never runs while closed. The most recent request ID is retained for retry; changed input conflicts, another queued ID is busy. A dispatched request is never automatically replayed after a crash. Inspect interrupted and decide explicitly.

ctx.services.schedules.list
(query?: Omit<PluginScheduleQuery, "pluginId">): Promise<PluginSchedulePage>

Bound schedules owned by this plugin only, with the latest persisted attempt/outcome.

ctx.services.schedules.observe
(query: Omit<PluginScheduleQuery, "pluginId">, handler: PluginObservationHandler<PluginSchedulePage>, options?: { ruleId?: string; }): PluginDisposable

services:jobs

啟動、檢視與控制由支援宿主操作組成的持久計畫。

  • 開發版:v1.1.0
  • ReadAware 0.6.12:v1.1.0
  • 授權: 無
ctx.services.jobs.control
(id: string, action: DurableJobControl, options?: PluginCallOptions): Promise<DurableJobSnapshot>
ctx.services.jobs.get
(id: string, options?: PluginCallOptions): Promise<DurableJobSnapshot>
ctx.services.jobs.list
(query?: { offset?: number; limit?: number; }, options?: PluginCallOptions): Promise<{ jobs: DurableJobSnapshot[]; nextOffset: number | null; }>
ctx.services.jobs.start
(plan: DurableJobPlan, options?: PluginCallOptions): Promise<DurableJobSnapshot>

jobs 1.1: event-bound starts preserve their source through restart. Every causal event subscription must have a stable ruleId. Unnamed reactions and isolated service invocations cannot create saved jobs.

services:changes

開啟並讀取可跨重新啟動持久保存的範圍變更游標。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.services.changes.open
(query: ChangesQuery, options?: PluginCallOptions): Promise<{ cursor: string; }>

Open before loading a baseline. Persist the returned cursor only after processing each page. Expired cursors require a new baseline. Notices are conservative reload hints, not events or values; settings hints cover the authorized requested paths in a shared storage namespace.

ctx.services.changes.read
(query: ChangesQuery, cursor: string, limit?: number, options?: PluginCallOptions): Promise<ChangesPage>

services:transactions

預覽並提交支援的本地變更、檢視收據與預覽條件式復原。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.services.transactions.commit
(previewId: string, options?: PluginCallOptions): Promise<AtomicReceipt>
ctx.services.transactions.preview
(operations: AtomicOperation[], options?: PluginCallOptions): Promise<AtomicPreview>
ctx.services.transactions.previewUndo
(receiptId: string, options?: PluginCallOptions): Promise<AtomicPreview>
ctx.services.transactions.receipt
(receiptId: string, options?: PluginCallOptions): Promise<AtomicReceipt | null>

services:session

讀取環境中繼資料並檢查支援操作的可用性。

  • 開發版:v2.18.0
  • ReadAware 0.6.12:v2.18.0
  • 授權: 無
ctx.services.session.environment
(): Promise<HostEnvironmentSnapshot>

Fresh non-sensitive metadata; contains no reading or account state.

ctx.services.session.observeEnvironment
(handler: (snapshot: HostEnvironmentSnapshot, delivery?: PluginReactionEvent) => void | Promise<void>, options?: { ruleId?: string; }): PluginDisposable

Session 2.7: locale effects retain their requester; other system facts keep independent sources.

ctx.services.session.operationAvailability
(query: OperationAvailabilityQuery, options?: PluginCallOptions): Promise<OperationAvailability>

Session 2.11: inspect host command permissions/workspace guards and plugin service contract/authority/capacity (Agent approval remains required), export metadata/save entry and clipboard/browser entry availability (no OS access probe), window support/capacity/target state, sync connection/credentials/provider, inference, book-targeted playback/mode, text preparation and graph prerequisites without executing or probing. Missing permission returns only the permission condition. Unknown remote health is not a local refusal or a success guarantee.

services:plugins

檢視已安裝外掛與註冊項、觀察變更,以及探索或呼叫具型別的外掛服務。

  • 開發版:v1.10.0
  • ReadAware 0.6.12:v1.10.0
  • 授權: 無
ctx.services.plugins.callService
(request: PluginServiceCall, options?: PluginCallOptions): Promise<PluginServiceReceipt>

Executes one declared export in a fresh restricted Worker. No live-root closures, callbacks, binary handles, automatic retries, or resources surviving the call.

ctx.services.plugins.contributions
(query?: PluginContributionQuery): Promise<PluginContributionPage>

Registered identities across extension points, never provider callbacks, data, settings or a grant to invoke another plugin. Offset pages may change.

ctx.services.plugins.list
(query?: PluginDirectoryQuery): Promise<PluginDirectoryPage>

Public installed metadata only, no settings, paths, secrets or raw errors.

ctx.services.plugins.listServices
(query?: PluginServiceQuery, options?: PluginCallOptions): Promise<PluginServicePage>

Plugins 1.8: authorized service contracts; discovery does not execute providers.

ctx.services.plugins.observe
(query: PluginDirectoryQuery, handler: PluginObservationHandler<PluginDirectoryPage>, options?: { ruleId?: string; }): PluginDisposable

Plugins 1.10: serial reaction deliveries with stable rule IDs; reload offset pages after changes.

ctx.services.plugins.observeContributions
(query: PluginContributionQuery, handler: PluginObservationHandler<PluginContributionPage>, options?: { ruleId?: string; }): PluginDisposable

services:maintenance

檢視維護狀態並進入宿主擁有的備份、連線測試、更新或設定流程。

  • 開發版:v1.5.0
  • ReadAware 0.6.12:v1.5.0
  • 授權: 無
ctx.services.maintenance.checkForUpdates
(): Promise<HostMaintenanceSnapshot>

Requires service:network. Uses the host release feed; no caller-supplied URL or silent installation.

ctx.services.maintenance.observe
(handler: PluginObservationHandler<HostMaintenanceSnapshot>, options?: { ruleId?: string; }): PluginDisposable
ctx.services.maintenance.openSettings
(surface: "updates" | "diagnostics" | "plugins" | "backup-import" | "backup-export" | "delete-data" | "ai-connection" | "data-location"): Promise<{ status: "opened"; surface: HostMaintenanceSurface; }>

Maintenance 1.4 adds data-location: shows the directory in host UI, never returns its path or opens the file manager. Also reveals updates/diagnostics/plugins/backup-import/backup-export/delete-data/ai-connection. Does not click controls, open file dialogs, approve installation or bypass typed DELETE.

ctx.services.maintenance.requestBackup
(action: BackupAction, options?: PluginCallOptions): Promise<BackupReceipt>

Reveals a host backup button and awaits the user's click and file dialog. Both directions use the complete encrypted archive (host-only password); import adds host review and confirmation, then reload. Retired v1 JSON library backups are rejected. No passwords, bytes or paths are returned.

ctx.services.maintenance.requestConnectionTest
(options?: PluginCallOptions): Promise<ConnectionTestReceipt>

Maintenance 1.3: reveal native AI test controls; only the user's click starts inference.

ctx.services.maintenance.snapshot
(): Promise<HostMaintenanceSnapshot>

services:diagnostics

要求支援的診斷匯出或回報流程。

  • 開發版:v1.2.0
  • ReadAware 0.6.12:v1.2.0
  • 授權: service:diagnostics
ctx.services.diagnostics.requestProjectionRepair
(options?: PluginCallOptions): Promise<ProjectionRepairReceipt>

Diagnostics 1.2: opens host confirmation; a committed repair requires reload.

ctx.services.diagnostics.requestReport
(action: DiagnosticsReportAction, options?: PluginCallOptions): Promise<DiagnosticsReportReceipt>
ctx.services.diagnostics.verifyProjections
(options?: PluginCallOptions): Promise<ProjectionVerification>

services:logging

寫入受限的結構化開發者事件並檢視記錄政策。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無
ctx.services.logging.policy
(): Promise<{ levels: PluginLogEntry["level"][]; maxEntryChars: number; maxFields: number; perPluginLimit: number; appLimit: number; windowMs: number; delivery: "best-effort"; }>
ctx.services.logging.write
(entry: PluginLogEntry): Promise<PluginLogReceipt>

Logging 1.0: accepted means forwarded to the best-effort host logger, not durably stored or uploaded. Allowed during activation and migration. Debug is development-console-only. Retired activations cannot write.

services:resources

選取檔案與目錄、讀取或建立封裝資源、匯出資料並儲存私有二進位資產。

  • 開發版:v1.6.0
  • ReadAware 0.6.12:v1.6.0
  • 授權: 無
ctx.services.resources.append
(id: string, offset: number, data: ArrayBuffer | Uint8Array<ArrayBufferLike>): Promise<ResourceRef>
ctx.services.resources.assets.delete
(key: string, expectedRevision: string, options?: PluginCallOptions): Promise<{ deleted: true; cleanupPending: boolean; }>
ctx.services.resources.assets.get
(key: string, options?: PluginCallOptions): Promise<PluginAsset | null>
ctx.services.resources.assets.list
(query?: PluginAssetQuery, options?: PluginCallOptions): Promise<PluginAssetPage>
ctx.services.resources.assets.open
(key: string, expectedRevision: string, options?: PluginCallOptions): Promise<ResourceRef>
ctx.services.resources.assets.policy
(options?: PluginCallOptions): Promise<PluginAssetPolicy>
ctx.services.resources.assets.store
(resourceId: string, input: PluginAssetWrite, options?: PluginCallOptions): Promise<PluginAssetReceipt>
ctx.services.resources.commit
(id: string): Promise<ResourceRef>
ctx.services.resources.create
(options: ResourceCreateOptions): Promise<ResourceRef>
ctx.services.resources.listDirectory
(id: string, query?: ResourceDirectoryQuery): Promise<ResourceDirectoryPage>
ctx.services.resources.openAssociated
(id: string, options?: PluginCallOptions): Promise<{ opened: boolean; }>

Resources 1.5: host confirmation then OS association for a temporary document/media copy. No edit-back, arbitrary program/path, or context bundles. True is dispatch, not rendering.

ctx.services.resources.openBook
(bookId: string): Promise<ResourceRef | null>

Requires library:read. Original local file only; no implicit remote download.

ctx.services.resources.openCover
(bookId: string): Promise<ResourceRef | null>

Resources 1.1; requires library:read. No extraction/download when the cover is unavailable.

ctx.services.resources.openDirectoryFile
(id: string, relativePath: string): Promise<ResourceRef>
ctx.services.resources.pick
(options?: ResourcePickOptions): Promise<{ cancelled: boolean; resources: ResourceRef[]; }>
ctx.services.resources.pickDirectory
(): Promise<{ cancelled: boolean; directory: ResourceDirectoryRef | null; }>

Resources 1.4: reader-selected, read-only directory grants; four per activation, one hour. No ambient paths. Listings are live; openDirectoryFile seals the current file bytes.

ctx.services.resources.read
(id: string, offset: number, length: number): Promise<ResourceChunk>
ctx.services.resources.release
(id: string): Promise<void>

Also aborts uncommitted writes.

ctx.services.resources.releaseDirectory
(id: string): Promise<void>
ctx.services.resources.save
(id: string, filename?: string): Promise<{ saved: boolean; }>
ctx.services.resources.stat
(id: string): Promise<ResourceRef>

services:sync

觀察同步狀態與待處理佇列、要求同步並進入宿主管理的帳號或連線流程。

  • 開發版:v1.2.0
  • ReadAware 0.6.12:v1.2.0
  • 授權: service:sync
ctx.services.sync.account
(): Promise<HostSyncAccount | null>

Explicit remote read of the account's tier, usage and limits; null without an account. No email, account ID, keys, session or billing ticket.

ctx.services.sync.backlog
(): Promise<{ events: number; blobs: number; }>

Events and blobs waiting to be pushed.

ctx.services.sync.connectionOptions
(): Promise<{ ref: string; label: string; }[]>

Registered backend references and display labels, never endpoint credentials.

ctx.services.sync.observe
(handler: PluginObservationHandler<HostSyncSnapshot>, options?: { ruleId?: string; }): PluginDisposable

Delivers each new sync snapshot (state, progress, completed cycles) while the handle lives.

ctx.services.sync.openSettings
(): Promise<{ status: "opened"; surface: "dataSync"; }>

Opens the host Data & Sync page; not a login, disconnect or purchase.

ctx.services.sync.requestFlow
(request: HostSyncFlowRequest, options?: PluginCallOptions): Promise<HostSyncFlowReceipt>

Host-owned connect, disconnect, account deletion, upgrade or billing flow. Waits for the final local outcome or external handoff; cancellation cannot undo a started operation.

ctx.services.sync.requestSync
(): Promise<HostSyncReceipt>

Runs one sync round on the configured backend (relay or a transport plugin such as WebDAV) and resolves when it has finished: completed, or already-running when a round was in progress (not queued again). Rejects with a coded error when no round can start (ui/unavailable) or the round fails (classified failures carry sync/* codes).

ctx.services.sync.snapshot
(): Promise<HostSyncSnapshot>

Current sync state: backend, connection, progress, last cycle and last error code.

services:network

發出具來源範圍的 HTTP 請求或讀取受限串流,並選用安全重試。

  • 開發版:v2.2.0
  • ReadAware 0.6.12:v2.2.0
  • 授權: service:network
ctx.services.network.closeStream
(id: string): Promise<void>

Idempotent for this activation's released/unknown IDs. Aborts pending reads; does not undo remote effects or remove data already saved by the plugin.

ctx.services.network.fetch
(input: string | URL | Request, init?: RequestInit, options?: { retry?: "none" | "safe"; }): Promise<Response>

Native HTTP; Request/init semantics and cancellation survive the Worker bridge. Bodies are buffered up to 64 MiB per direction. Calls have a 120s deadline; an abort does not undo a remote side effect already committed by the server. Network 2.0 requires networkAccess for the initial URL and each redirect. HTTPS -> HTTP redirects are denied. At most 10 redirects; manual returns the 3xx response, error rejects. Cross-origin hops drop authorization, proxy-authorization, cookie and referer; custom secret headers are the plugin's responsibility (use redirect:error for authenticated endpoints). Host/content-length are transport-owned. No implicit retry or cookie jar. Network 2.2: options.retry="safe" opts GET/HEAD without a body into at most two retries across the whole redirect chain, before response headers are returned. Other methods and all body reads are never replayed. The original deadline includes backoff; Retry-After above 30s returns the HTTP response. Attempts/uploads/read chunks share per-owner and host cumulative quotas; reactivation does not reset owner debt. policy() reports exact limits. Transport failures carry plugin/network-failed; explicit deadlines carry plugin/network-timeout, aborts plugin/cancelled. Existing structured codes survive unchanged. Unclassified native errors are not guessed from prose. HTTP error statuses still return Response; the consumer decides success.

ctx.services.network.openStream
(input: string | URL | Request, init?: RequestInit, options?: { retry?: "none" | "safe"; }): Promise<PluginNetworkStream>

Network 2.1: headers first; download at most 1 GiB without buffering the whole response. Uploads remain capped at 64 MiB. 8 active requests per activation / 32 host-wide, shared with fetch; no hidden durable queue. Optional safe retry applies only before this opening receipt, as in fetch. init.signal cancels OPENING only; after receipt use closeStream to cancel. Close in finally if not reading to EOF. 120s absolute lifetime, including headers/redirects/reads; unload cancels and drains native resources.

ctx.services.network.policy
(): Promise<PluginNetworkAccess & { maxRedirects: number; maxBodyBytes: number; timeoutMs: number; maxStreamBytes: number; maxChunkBytes: number; maxConcurrentRequests: number; maxHostConcurrentRequests: number; cumulative: { windowMs: number; maxOwnerRequests: number; maxHostRequests: number; maxOwnerBytes: number; maxHostBytes: number; maxOwners: number; }; retry: { maxRetries: number; baseDelayMs: number; maxDelayMs: number; statuses: readonly number[]; }; }>

Network 2.0: this activation's immutable authorization and transport limits. All-origins authorization is ["*"], not a guarantee of endpoint reachability.

ctx.services.network.readStream
(id: string, offset: number, maxBytes?: number): Promise<PluginNetworkChunk>

Sequential, non-replayable reads. offset must equal bytes already delivered. One outstanding read per stream; maxBytes defaults to 64 KiB, max 1 MiB. A lost read receipt is not safely retryable: close and restart explicitly.

services:llm

要求文字、結構化或串流推論、使用封裝圖片資源,並追蹤請求中繼資料與預算。

  • 開發版:v1.6.0
  • ReadAware 0.6.12:v1.6.0
  • 授權: service:llm
ctx.services.llm.ask
(input: PluginInferenceInput & { schema?: never; onText?: (delta: string) => void; }): Promise<string>
(input: PluginInferenceInput & { schema: Record<string, unknown>; onText?: never; }): Promise<unknown>
ctx.services.llm.askDetailed
(input: PluginInferenceInput & { schema?: never; onText?: (delta: string) => void; }): Promise<InferenceResult<string>>
(input: PluginInferenceInput & { schema: Record<string, unknown>; onText?: never; }): Promise<InferenceResult<unknown>>

llm 1.3: same execution as ask, with per-attempt metadata on success. Includes structured retries; failure/cancellation rejects, not a billing receipt.

ctx.services.llm.cancelRequest
(requestId: string): Promise<InferenceRequestReceipt | null>

Requests cancellation independently of the ask RPC. The returned snapshot may still be running; query again for its outcome and provider settlement.

ctx.services.llm.getRequest
(requestId: string): Promise<InferenceRequestReceipt | null>

llm 1.6: last 64 named requests in this plugin's local private storage. Initial metadata commits before inference dispatch; no prompt/output is retained. Includes backup/rollback and uninstall cleanup, not roaming or billing history. requestAvailable identifies this activation's handle. An older unsettled record has interrupted=true: status is last observed, not proof it still runs remotely. No automatic retry/resume; historical IDs cannot control another activation. Late terminal usage is persisted; unknown/evicted IDs return null.

ctx.services.llm.listRequests
(): Promise<InferenceRequestReceipt[]>
ctx.services.llm.policy
(): Promise<{ defaultTimeoutMs: number; maxTimeoutMs: number; perPluginLimit: number; appLimit: number; maxOutputTokensLimit: number; maxImageCount: number; maxImageBytes: number; maxImageTotalBytes: number; maxTotalOutputTokensLimit: number; maxOutputCharsLimit: number; maxInputChars: number; }>

Plugin inference limits, not billing quotas. maxOutputTokensLimit since 1.3.

services:clipboard

將文字或支援的封裝圖片寫入系統剪貼簿。

  • 開發版:v1.1.0
  • ReadAware 0.6.12:v1.1.0
  • 授權: service:clipboard
ctx.services.clipboard.writeImage
(resourceId: string): Promise<ResourceImageReceipt>

Clipboard 1.1. This activation's sealed resource; raster decode stays in the host.

ctx.services.clipboard.writeText
(text: string): Promise<void>

Schema

schemas:views

描述宿主算繪的清單、表單、詳細資料、markdown 與支援的區塊版面。

  • 開發版:v1.12.0
  • ReadAware 0.6.12:v1.12.0
  • 授權: 無

Manifest 宣告

schemas:settings

宣告具型別的外掛設定、條件欄位與動態選項參照。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: 無

Manifest 宣告

schemas:themes

描述語意化應用程式與閱讀器調色盤。

  • 開發版:v1.0.0
  • ReadAware 0.6.12:v1.0.0
  • 授權: ui:themes

Manifest 宣告