元源閱讀能力與章節更新
按需接入更新、EPUB、圖文、聽書和榜單，保持身份、快取和分頁一致。
本頁目錄
按能力接入
核心保持精簡，新功能獨立宣告。當前規範是候選協議；完整欄位以協議倉庫的 Schema 和 OEP 為準。 搭建 Skill 包含對應提交的契約快照，官網下載後設資料記錄來源。
| 能力 | 宣告 | 使用方式 |
|---|---|---|
| 文字與圖文 | 核心 content | text/plain、text/markdown、text/html |
| 章節更新 | top.xxread:chapter-updates | 原目錄 + updates 狀態 |
| EPUB | top.xxread:publications | 整本 publication 檔案 |
| 圖片序列 | top.xxread:image-sequence | image/sequence + images |
| 錄音聽書 | top.xxread:remote-audio | audio/uri + audio |
| 多個榜單 | rankings | 榜單定義 + 分頁條目 |
起步生成專案已經實現文字、瀏覽和更新；其餘能力提供契約與原始參考樣例。不要僅增加能力字串就聲稱支援。
章節更新與快取
新增、修訂、刪除、重排都應更新對應目錄版本。文字的 contentVersion 使用精確正文 UTF-8 位元組的 SHA-256；只比較章節數會漏掉舊文修訂。
擴充套件客戶端先 GET v1/books/{bookId}/updates，再攜帶 catalogVersion 獲取目錄分頁。
發生 409 時重新讀取更新狀態，丟棄舊快照頁。對未宣告此能力的書源，繼續使用原目錄介面，不傳送新的版本查詢引數。
ETag 只驗證某個請求的表示，不能拿不同頁 ETag 當整本版本；304 不能掩蓋舊目錄版本的衝突。 位置和批註繫結內容身份與修訂，頁碼保持為閱讀器當前佈局的派生資訊。
EPUB 與圖文
EPUB 放在 v1/books/{bookId}/publications，附帶穩定檔案身份、絕對下載 URL、媒體型別、位元組數和 SHA-256。
檔案變化時更換 publication ID；保留原文字章節作為舊客戶端路徑。
Markdown 圖片和 HTML 相對地址使用 baseUrl；客戶端仍需做安全渲染。圖片序列有非空 images，按陣列順序閱讀，正文字串為空。
contentTypes 列出章節形式，不把 application/epub+zip 混進去；圖片與音訊形式同時需要相應能力宣告。
錄音與媒體地址重新整理
audio/uri 正文提供 audio.url，正文字串為空，不混入圖片列表。錄音與客戶端 TTS 是兩項不同能力，文章背景配樂仍是獨立的未來設計。
圖片/音訊 URL 使用 HTTP(S)，公開請求提示不包含 Cookie、Authorization 或讀者會話。
過期地址先重新整理同一章節，媒體失敗後最多按配置重新整理一次，地址變化才重試。資源版本覆蓋實際內容與順序，不能用空正文的 SHA-256 代替。 媒體修訂指紋也不能充當檔案校驗值。Range、HLS 和目標平臺編解碼能力都需要實際驗證；參考 WAV 測試透過不能代表真機 HLS 已完成。
多榜單與未來擴充套件
v1/rankings 提供多個榜單，v1/rankings/{rankingId} 提供分頁條目。rank 是整張榜單的絕對排名，snapshotId 變化時重新載入，避免混合快照。
排名屬於源、榜單和快照，不能把獨立書源的排名拼成同一個權威總榜。舊 browse?sort=popular 繼續使用。
評論與段評已有 OEP-0004 草案；身份認證、付費授權、讀者雲同步保持獨立邊界。宣告擴充套件之前，應同時更新契約、實現、示例與實際 HTTP 驗證。
發現文件中的問題？ 提出修正