前言¶
在 DeepSeek Harness（DSH）裏排查界面、對照截圖時，常見做法是另開畫圖工具圈點，再粘貼圖片並文字說明位置。圖片和說明容易脫節，模型也不容易把「第幾處」和圖上的標記一一對應。社區插件 dsh-sidebar-annotate 把批註做在右側邊欄預覽區上方：不彈居中對話框、不遮暗背景，在原圖座標上疊一層畫布，發送時合成 PNG，並附帶編號說明列表，走與粘貼圖片後回車相同的官方草稿路徑進入對話。
這是什麼¶
dsh-sidebar-annotate 由維護者 HuaLQIn 發佈（首版 2026-10-31，當前資料中版本爲 0.7.0，MIT 許可證）。它掛載在 DSH 客戶端文檔預覽相關能力上：在右側欄打開圖片後，預覽區標題欄會出現 Annotate 按鈕；進入批註模式後，工具條以半透明膠囊形式出現在圖片下方，批註層與預覽中的 <img> 矩形對齊，縮放、滾動與官方渲染器不被插件改寫。
生態上，DSH 強調「一切皆插件」；SkillHub 目錄頁 是社區收錄站點，與 DeepSeek / 幻方無官方從屬關係。插件分類爲客戶端，未發佈到 npm，需通過 dsh plugin add 從 GitHub 倉庫安裝。
核心功能¶
下面介紹 README 中已列出的能力，與「Compatibility notes」中明確未實現的部分分開說明。
原地批註與發送¶
- 在右側欄打開支持的圖片格式（png、jpg、jpeg、webp、gif、bmp、ico）。
- 點擊 Annotate，在圖上使用工具繪製或打點。
- 點擊 Send：插件將原圖與墨跡合成導出爲 PNG（最長邊超過 4096 px 時會先降採樣），並生成編號說明；一併提交到當前對話。
發送後說明列表示例形態如下（摘自 README）：
I marked spots on this image:
1. the button in the top right
2. the spacing here
The numbers in the image match the list above.
六種工具¶
| 工具 | 作用 |
|---|---|
Mark（V） |
單擊放置帶編號的標記，並輸入一行說明 |
Pen（P） |
按住拖動自由畫線 |
Arrow（A） |
拖動繪製箭頭，箭頭在終點 |
Rectangle（R） |
從按下的一角拖出矩形 |
Square（S） |
同上，邊長鎖定爲相等，取長邊 |
Triangle（T） |
同上，底邊在下、頂點居中 |
Mark 爲藍色圓點、白環與白字編號，錨定在歸一化座標上，窗口尺寸變化時仍可對齊。撤銷 / 重做按操作時間順序，而非按工具類別；整筆筆畫或整顆標記作爲一步撤銷，不支持局部擦除（文檔寫明無 eraser）。
顏色、線寬與視圖¶
膠囊工具條從左到右包含：六個工具格、四檔預設色加自定義取色、三個線寬點加 1–12 px 滑塊（與 [ / ] 切換預設聯動）、撤銷 / 重做 / 清空、標記計數、取消與發送。滾輪可放大查看細節；按住 Space 可平移。關閉批註層後恢復原圖展示。
鍵盤與輸入法¶
批註層聚焦時：Ctrl+Z 撤銷，Ctrl+Shift+Z 或 Ctrl+Y 重做，Esc 先關說明卡片再退出層。說明卡片獲得焦點時快捷鍵不搶鍵，便於 IME 輸入中文說明。
邊界行爲（文檔已說明）¶
- 僅圖片；PDF、瀏覽器標籤、元素拾取、文本批註未實現。
- 連續三次圖片查找失敗（約 1.2 s）會關閉批註層；同標籤切換文件會清掉舊墨跡。
- 圖片滾出視口時層隱藏但保留狀態；對話正在提交附件時會拒絕發送並提示，而非靜默排隊。
- 超大圖導出可能耗時，發送按鈕會顯示 sending 狀態。
安裝與啓用¶
安裝前需要 Node.js 20 或更新版本（package.json 中 engines.node）。主機需提供插槽 sidebar.right.tab.document.actions（與 document-preview 包一併引入）；README 寫明在 DeepSeek Harness desktop 0.2.1-rc.2 與對應 web 客戶端構建上做過測試，其他版本未測。package.json 有意不聲明 engines.dsh 與 @deepseek-ai/* peer，是爲避免 semver 拒絕 0.2.1-rc.2 這類預發佈號導致安裝被靜默跳過。
推薦從倉庫直接安裝（命令來自 README 原文）：
dsh plugin --profile <your-profile> add git+https://github.com/HuaLQIn/dsh-sidebar-annotate.git
<your-profile> 爲實際使用的 profile：web 對應瀏覽器構建，desktop 對應桌面應用。包名爲 dsh-sidebar-annotate；CLI 會寫入 profile 的 package.json 依賴與 dsh.profile.bundles 條目，不要用不同名稱重複安裝同一插槽。
安裝後必須完全退出 DSH 再重新打開；僅刷新窗口不會加載新插件客戶端 bundle。
自檢是否只註冊一份：
dsh --profile <your-profile> --dump-config | rg "id: dsh-sidebar-annotate"
應恰好一行。在運行中主機瀏覽器控制台：
window.__DSH_BOOT__.entries.find(({ id }) => id === 'dsh-sidebar-annotate')
應返回帶 url 的條目；若爲 undefined 表示未加載。
卸載：
dsh plugin --profile <your-profile> remove dsh-sidebar-annotate
也可手動刪除 profile package.json 中的依賴與 bundles 項後同樣完全重啓；批註狀態僅在內存中，關閉層即丟棄。
典型用法¶
交互流程可概括爲：
右側欄打開圖片 → 預覽標題 [Annotate] → 膠囊工具條出現在圖下
→ 選工具繪製 / Mark 寫說明 → [Send]
→ 合成 PNG + 編號說明列表 → 進入對話（同粘貼圖片回車路徑）
先做 Mark 標關鍵 UI 元素並各寫一行，再用 Arrow 或 Rect 框區域，是 README 演示中常見的組合；發送前可用 undo / redo 調整順序。若對話 busy，需等待提交完成再 Send。
適用場景與注意¶
適合需要在 DSH 會話裏指着截圖講清楚的場景：前端佈局、設計稿覈對、日誌截圖裏的異常位置等。相比外置標註工具，優勢是座標與右側預覽一致，且輸出帶編號列表，便於模型對齊「圖中數字 ↔ 文字條目」。
安裝與使用前請注意：
- 插件以當前 DSH 進程權限在客戶端運行；安裝前應自行查看 GitHub 源碼 與 MIT 許可證，確認符合你的安全與合規要求。
- 不要用
cordis.patch.yml手工重複插入同一插件 id；遵循 README 的 Do / Don’t。 - 問題反饋可走倉庫 Issues。
結尾¶
dsh-sidebar-annotate 把圖片批註收進 DSH 右側欄預覽流程：六種工具、編號 Mark、合成圖與說明列表一次回傳，減少截圖與文字錯位。進一步瞭解可訪問社區目錄 SkillHub：dsh-sidebar-annotate 與源碼倉庫 github.com/HuaLQIn/dsh-sidebar-annotate。
