前言¶

在 DSH 裏審閱代碼或文檔時，常見流程是：打開右側文件預覽，發現一個問題，把位置描述成文字粘進輸入框。問題在於，描述“第幾行附近有別扭”這件事本身很費字，而且粘貼後和原文已經斷了關聯，讀消息的人只能靠猜。

對比已有做法：Better Sidebar 的「添加到對話」插入的是文件名與行號，適合整段上下文；想做具體的局部評論，就得自己打引用文字。dsh-file-annotations 走的是另一條路——在預覽裏直接圈選文字或區域，寫成帶座標和裁剪圖的批註，排在輸入框上方隨消息一起發出。

這是什麼¶

DEVbyQIN 維護的 DSH 客戶端插件，名稱爲 dsh-file-annotations，當前版本 0.6.2，節點要求 ^22.19.0 || >=24。它把“預覽期間的臨時草稿”編譯成可發送的引用，解決的是：標註位置和評論內容要麼丟失、要麼退化成一大段手打文字。

需要說明的是，批註是預覽期間的草稿，側邊欄收起、切換標籤頁或切換會話時會保留；確認關閉預覽後，該文件的 JSON、localStorage、待發送卡片、藍色引用和圖片預覽緩存會被清理，10 秒內可點「撤銷」。

核心功能¶

文字批註¶

TXT、JSON、Markdown、源碼等可選文字預覽，以及帶可選文字層的 PDF 支持文字批註。兼容 Better Sidebar 的 CodeMirror 編輯器，文件內容區的選字可以批註；搜索框等普通輸入框不彈批註。

選中文字後，文字與代碼文件上的「批註」和 Better Sidebar 的「添加到對話」顯示爲同一個選區工具條，後者保留原有文件、行號和插入行爲。Better Sidebar 打開的 HTML 可以在渲染網頁中直接選字，也可以點「選元素」再點段落、標題或圖片，對整個元素加批註。跨 DOM 片段和跨行文字按完整引用匹配，保存偏移、上下文和 PDF 頁碼。網頁仍使用原有沙箱，不開啓同源訪問，也不提供 OCR。

區域批註¶

PDF、圖片、HTML 預覽頭部提供「框選」。拖拽接收層只覆蓋內容可見部分，標籤欄和退出按鈕仍可操作；鬆手後出現輸入條，保存後在區域上顯示框和編號，Esc 或再點框選按鈕退出。寫評論期間保留虛線框，取消則清理。

PDF 頁碼讀取預覽器的真實頁標記，未渲染頁不借用相鄰頁的畫布。PDF 和圖片裁剪爲 PNG；HTML 保存元素選擇器、引用文字及元素內座標，不提供裁剪圖。舊版 HTML 只存視口座標，無法可靠推斷原元素，舊記錄保留在歷史中，新舊記錄不會被自動改寫。

待發送列表與歷史¶

批註保存後出現在主輸入框上方的待發送列表，按當前會話隔離。可以摺疊列表、編輯評論、移除批註，或點文件名打開原文件。輸入框裏有一枚簡短的「文件批註」引用，發送時展開爲本輪批註的文件路徑、引用或區域座標、評論和裁剪圖路徑。保存批註不會自動發消息。

刪除藍色引用等價於把本批批註移出待發送列表，其他消息文字和批註歷史保留，刷新後也不會自動加回；需要恢復時，在文件頭部的「批註」歷史中點「加入待發送」。宿主確認接收後批註移入歷史，提交失敗則保留批註並由 DSH 恢復文字草稿，可修改後重試。

存儲¶

<工作區>/.dsh/annotations.json
<工作區>/.dsh/annotations/crops/<批註 id>.png

存儲格式仍爲 version 2，兼容已有記錄。一條記錄包含 id、sessionId、path、rel、quote、comment、createdAt，以及可選的 anchor、htmlAnchor、region、crop、sentAt、detached。其中 sentAt 表示宿主已接收該批消息，不代表 AI 已處理完成。

宿主路由均爲 POST，位於 /api/dsh-file-annotations/ 下，覆蓋 resolve、read、write、crop、crop-preview。縮略圖讀取只接受工作區和批註 id，不接受任意文件路徑。

安裝與啓用¶

桌面版在 DSH 中打開「插件 → 添加插件 → 安裝已有插件」，輸入 dsh-file-annotations 或 github:DEVbyQIN/dsh-file-annotations，安裝並啓用，卸載同樣在應用內插件管理器操作。npm 包地址爲 https://www.npmjs.com/package/dsh-file-annotations。

Web 版安裝命令：

dsh plugin --profile web add dsh-file-annotations@0.6.2
# 或從 GitHub 安裝同一版本
dsh plugin --profile web add 'github:DEVbyQIN/dsh-file-annotations#v0.6.2'

安裝後重啓 DSH。卸載：

dsh plugin --profile web remove dsh-file-annotations

典型用法¶

下面按插件文檔裏的使用流程走一遍。

1. 打開右側文件預覽。選中文字後點選區旁的「批註」，或在 PDF、圖片、HTML 預覽中點「框選」並拖出區域。
2. 輸入評論並保存。批註出現在主輸入框上方的待發送列表，按當前會話隔離。關閉會清理批註的文件預覽前會彈出確認，點「取消」或按 Esc 可繼續批註；沒有批註時直接關閉。
3. 在列表中核對引用、評論和區域縮略圖，可編輯或移除。
4. 在原生輸入框補充總要求，再點 DSH 的發送按鈕或按 Enter。只有批註、沒有額外文字也可以發送。
5. 宿主確認接收後，本次批註移入歷史；失敗則保留批註並恢復文字草稿，可修改後重試。

PDF 默認保持閱讀和選字。手動開啓框選後，寫批註時暫停框選，保存或取消後可繼續框選下一處；切換文件或會話會退出框選。PDF 預覽的虛線矩形圖標用於開啓和退出框選，開啓時變藍，旁邊的「打開 PDF 時默認框選」可設爲自動或手動，設置會記住並應用於以後打開的 PDF，初始爲手動。

快捷鍵方面，macOS 桌面首次加載時會將打開文件改爲 ⌘O、選區批註改爲 ⌘P；網頁端保留 ⌘⇧E（Windows 爲 Ctrl+Shift+E），Linux 網頁端默認不綁定。輸入條內 ⌘Enter / Ctrl+Enter 保存當前批註併發送本會話全部待發送批註。

適用場景與注意¶

適合需要圍繞文件局部內容提問、評審或討論的場景，尤其是 PDF、圖片、HTML 預覽中這類無法用行號表達的區域。

以下幾點在安裝前應該看清：

• 插件以當前 dsh 進程的權限運行，宿主接口暴露了讀寫工作區和生成裁剪圖的能力。安裝前應打開源碼與許可協議覈對，倉庫許可證爲 MIT。
• 只覆蓋右側文件預覽，沒有 diff，也沒有按代碼行號的精確錨定。
• 文件內容變化後不會自動遷移，也不會判定舊批註過期。
• 待發送列表依賴 DSH 的 conversation、sessions 和 inputTriggers 客戶端服務，宿主接口變化需要重新驗證兼容性。
• 多個獨立瀏覽器同時修改同一工作區的存儲仍可能互相覆蓋，目前沒有協同編輯協議。

社區目錄頁與倉庫地址：https://www.skillhub.cn/plugins/DEVbyQIN/dsh-file-annotations 、 https://github.com/DEVbyQIN/dsh-file-annotations