前言¶
在 DeepSeek Harness（DSH）中使用 PDF 時，右側文件預覽區域僅提供基礎翻頁和縮放功能。打開有目錄結構的 PDF 時，無法快速定位章節；閱讀過程中無法記錄當前閱讀位置，切換任務或重啓桌面版後需要重新查找。現有文檔工具或瀏覽器擴展難以直接與 DSH 側邊欄集成。
dsh-pdf-bookmarks 在 DSH 右側文件預覽中增加 PDF 書籤查看器，提供文檔目錄（outline）與本地閱讀書籤。插件以 dsh bundle 機制運行，不修改 PDF 文件本身，不把書籤數據發送到模型請求或賬號配置中。
插件定位¶
dsh-pdf-bookmarks 是 DSH 的客戶端插件，由維護者 woody-dx 開發。它只增強已有工作區 PDF 的右側預覽，提供內嵌目錄與個人閱讀書籤，不增加模型工具或會話持久狀態。社區目錄中的會話書籤與文件路徑收藏也不等同於 PDF 頁內閱讀位置。
核心功能¶
文檔目錄（outline）¶
打開 PDF 後，在文件頭部的查看器菜單選擇「PDF 書籤」。工具欄的「☰」開關導航，側欄以覆蓋面板形式顯示文檔自帶章節，可展開層級並點擊跳轉。
對於沒有內置目錄的 PDF，側欄會顯示說明，仍可添加個人書籤。
個人閱讀書籤¶
點擊工具欄的「☆ 書籤」收藏當前閱讀位置，可直接輸入名稱並保存。「我的書籤」支持點擊跳轉、行內改名和刪除。重開同一 PDF、切換任務或重啓桌面版後仍可讀取。
書籤數據保存在桌面應用自身 origin 的 localStorage 中，鍵前綴爲 dsh-pdf-bookmarks:v1:。只保存文檔內容 SHA-256、名稱、頁碼、頁內相對位置和創建時間。同一內容的 PDF 副本共用書籤；內容變更後使用新的集合。
側欄與正文操作¶
較窄的側欄以覆蓋面板顯示導航，點擊目標後自動收起。工具欄提供頁碼跳轉、適應寬度和固定縮放；正文支持連續滾動和文字選取。
安裝與啓用¶
當前僅驗證 dsh Desktop 0.2.1-rc.2 在 macOS Apple Silicon 上的可用性。其他版本默認禁用此查看器。
從源碼安裝¶
從 GitHub 倉庫下載源碼 ZIP 並解壓，在桌面版「插件 → 添加插件」中輸入解壓後的插件目錄絕對路徑，然後在「已安裝插件」中啓用 dsh-pdf-bookmarks。
從 Release 安裝¶
從 GitHub Release 下載 .tgz，在桌面版添加插件時填寫該文件的絕對路徑。
插件遵循 dsh.bundle 組合包機制，啓動保護從當前 profile 的包解析找到自身，不要求源碼位於特定用戶名或 ~/.dsh/plugins 路徑。在「插件 → 已安裝插件」中可啓停和卸載；列表未更新時點擊「刷新」。
禁用與卸載¶
停用可在 dsh 插件列表中禁用本插件，或在 profile patch 最後增加：
- id: pdf-bookmarks
disabled: true
再次啓用前刪除這條手工禁用覆蓋。停用或使用查看器菜單切回「PDF」後，內置查看器繼續工作。刪除本地源碼目錄前應先停用並移除 profile 引用。
卸載插件不清空書籤；清除桌面應用的全部網站存儲則會移除這些書籤。
兼容性與故障回退¶
啓用條件位於 cordis.patch.yml：在加載插件入口前，調用 guard.cjs 覈對精確版本白名單以及兩個構建文件的 SHA-256。檢查異常、版本未驗證、文件缺失或哈希不匹配均僅禁用本插件。
Host 入口 index.js 無運行時依賴、不提供或替換任何核心服務。正式插件不安裝 dsh-tools、Cordis 或其他 dsh 核心包。客戶端接口註冊異常會被捕獲；PDF 引擎在打開 PDF 時才加載，加載失敗會移除增強預覽定義並交回內置查看器；正文錯誤邊界提供「使用內置 PDF 預覽」。
適用場景¶
適合需要在 DSH 側邊欄中快速瀏覽 PDF 目錄、記錄閱讀進度的開發者與研究者。插件僅運行在桌面版進程內，不涉及網絡請求或模型調用。
使用前應確認本地已安裝 dsh Desktop 0.2.1-rc.2，並從官方渠道獲取插件源碼或 Release 文件，覈對 LICENSE 與 THIRD_PARTY_NOTICES.md。
總結¶
dsh-pdf-bookmarks 在 DSH 右側側欄提供 PDF 目錄與本地閱讀書籤，支持點擊跳轉、行內改名和刪除，書籤數據本地持久化，重啓任務或桌面版後仍可讀取。插件以 dsh bundle 機制運行，對已驗證版本提供故障回退，不修改 PDF 文件本身。
- 插件目錄頁：https://www.skillhub.cn/plugins/woody-dx/dsh-pdf-bookmarks
- GitHub 倉庫：https://github.com/woody-dx/dsh-pdf-bookmarks
