前言¶

DeepSeek Harness（DSH）自帶的文檔預覽是隻讀的：沒有元素選擇器，也沒有批註模型。iframe 使用 sandbox="allow-scripts"，父頁面無法注入腳本。想在預覽裏標註，只能自己渲染預覽。

baigo8 的 dsh-page-annotate 插件就是爲此做的：它註冊自己的邊欄標籤類型，自己建 iframe、注入 overlay，從而建立可控的同源 postMessage 通道，不依賴宿主路由或開發者工具開關。

插件定位¶

• 名稱：dsh-page-annotate
• 維護者：baigo8
• 分類：聯網工具
• 作用：在 DSH 右側邊欄的 HTML 預覽裏直接圈選元素、寫批註，然後把整批批註作爲一條消息發進當前會話，讓模型按批註改頁面。

核心功能¶

頁面批註¶

1. 在會話裏打開一個 HTML 文件的預覽（在工作區文件樹裏點它）。
2. 默認選擇「HTML · 頁面批註」預覽實現，點擊預覽頭部的「批註」。
3. 在同一個 iframe 上開啓選擇，不新增標籤、不重讀文件、不關閉已經打開的彈窗，輸入與腳本狀態保留。升級後請重新打開頁面並確認使用「HTML · 頁面批註」。
4. 直接在頁面上選擇元素：
   - 移動鼠標高亮元素，點擊彈出批註框。
   - 默認只顯示編號、配置按鈕、評論輸入框和 ✓，自動聚焦輸入。
   - 點配置按鈕才展開樣式參數（文字顏色、背景顏色、字號、字重、不透明度）；元素路徑和分類按鈕不再顯示，後臺定位證據照常發送。顏色支持點擊色塊打開可視取色面板，調整明暗/飽和度、色相、透明度或輸入十六進制值；這些參數讀取元素當前值，修改後記錄爲批註目標，不直接修改頁面。
   - Enter 或 ✓ 保存，Shift+Enter 換行，輸入法確認不會誤保存；取色面板打開時 Esc 先關閉取色器，再按 Esc 才取消未保存編輯並退出選擇；已保存批註保留。
5. 保存後不會退出選擇模式，可以連着點若干個元素、逐個寫批註，不必每次重新點「選擇元素」。每個元素上會出現編號角標，點角標可以重新編輯，「刪除」可以移除。

發送批註¶

全部標完後二選一：

• 發送到會話：把所有批註編譯成一條消息，直接進會話隊列。成功後原地退出批註，保留當前彈窗與輸入；失敗則保留批註以便重試。
• 填入輸入框：只寫進輸入框，可以補充說明再自己發。

多條批註是一次發送、一條消息，按編號成組，不是一條一條發。這樣會話側能一次看到全部修改點，也不會觸發多次生成。頁面本身不會被改動——overlay 只在內存裏注入，原文件保持可 diff。

防止修改到錯誤位置¶

每條批註附帶當前 DOM 的精確 CSS 選擇器、匹配數量、所屬區域/彈窗唯一 ID 與標題、經過限長和清理的目標 HTML 片段。麪包屑保留更深祖先，避免多彈窗相似 class 導致混淆。這些是運行時定位證據，不是源文件行號。

消息要求模型先覈對源碼位置，禁止只按相同文案/通用 class 全局替換；不能唯一確定時先詢問，改後檢查同名非目標區域不變。此舉降低誤改風險，但不保證模型完全不會犯錯。藍色序號、選擇框、批註欄均爲臨時工具標記，消息明確禁止將其寫入最終頁面；頁面原有的業務序號列不受此約束影響。

截圖隨批註發送¶

底部默認勾選「附帶截圖」。保存每條批註時留存當前視口 PNG，編輯該條批註後更新它的截圖；發送時同批附帶多張真正的 image 附件。不同彈窗/滾動位置可以保留各自畫面，不再只截髮送時的最後一個視口。

• 按最終批註順序排列圖片，提示詞逐張列出「附圖1（S1）對應批註1」，文件名也標註對應批註；完全相同 PNG 可去重共用一張，映射仍保留。
• 刪除其他批註可能改變最終編號，因此對應表額外保留捕獲任務創建時編號；以對應表和元素定位爲準，不把歷史圖裏的舊編號當作當前順序。
• 排隊後的捕獲、舊會話恢復/失敗後發送時補拍會明確註明不是保存瞬間，絕不聲稱恢復了歷史畫面。截圖僅內存保留，關閉標籤或重啓不持久化。
• 每批最多保留 12 條批註截圖，base64 總量最多 20MiB；超額會阻止帶圖發送，須減少批註或取消附圖，不能靜默丟圖。
• 截圖保留批註編號，併爲各已保存批註對應的目標繪製藍色邊框與淡藍底，編號與位置可以直觀對應；不包含評論輸入浮層或無關的鼠標懸停高亮。邊框只在截圖克隆中繪製，不改原頁面；屏幕外元素以文字定位爲準。
• 可取消勾選，只發送文字；「填入輸入框」目前只填文字，不插入圖片。
• 截圖失敗會明確提示並保留批註，不會自動退回只發文字。模型不支持圖片時可取消勾選再重試。
• 截圖庫離線隨包附帶，不訪問 CDN 或第三方截圖服務；會讀取並可能重新請求頁面自身的資源。
• 技術上是 html2canvas DOM 重繪，不是原生屏幕像素截圖。部分 CSS、無 CORS 授權的跨域圖片、跨域 iframe、視頻/WebGL 可能無法準確還原。發送前請確認頁面可視內容適合分享給會話模型。
• 爲控制體積，截圖最長邊不超過 1600px，不按 Retina 倍率放大。

消息摺疊與展開¶

插件啓用時，新的批註消息默認摺疊顯示「2條批註 · 2張截圖」，點擊即可展開原樣完整提示詞，再點擊收起。縮略圖仍使用 DSH 原生圖片附件展示。完整文本與圖片照常進入模型上下文，並非刪掉定位信息；刷新會話後仍可從穩定標記識別。關閉插件會回退顯示完整普通消息，舊版已發送的無標記消息不會自動摺疊。「填入輸入框」仍是純文字，不插入圖片、不封裝爲摺疊消息。

安裝與啓用¶

包聲明瞭 dsh.bundle.patch，所以插件管理器會自己完成三件事：裝依賴、把這個包加進 profile 的組合層、插入 Loader 行。不需要手改任何 YAML。

給別人裝（推薦：圖形界面）¶

1. 插件頁 →「安裝插件」
2. 粘貼 tgz 的絕對路徑（~ 不行），或選「本地目錄」
3. 裝完重啓一次 DSH

命令行等價寫法¶

# 注意 flags 緊跟在 profile 名後面，否則會被當成 app 參數
dsh plugin --profile <profile> add /絕對路徑/dsh-page-annotate-0.1.0.tgz

開發時（軟鏈到自己改的目錄）¶

ln -sfn /Users/baigo/Documents/workspace/projects/dsh-page-annotate \
        ~/.dsh/profiles/desktop/node_modules/dsh-page-annotate
# 並在 profile 的 package.json 裏寫：
#   "dsh-page-annotate": "link:/Users/baigo/Documents/workspace/projects/dsh-page-annotate"

軟鏈的好處是改完源碼立刻生效；代價是目錄一移動插件就失效（link: 不是副本）。給別人用請用 tgz，那是 file: 副本，刪掉 tgz 也不影響運行。

重啓只在首次安裝時需要。profile 對插件包的解析在啓動時緩存（profile resolution 不允許熱替換同名包），所以第一次把包掛進去必須重啓一次。

更新預編譯客戶端產物後，建議刷新 DSH 頁面並重新打開 HTML 預覽。宿主包含 HMR 接收機制，但不保證當前安裝環境正在構建或推送更新；若仍是舊版本，再重啓 DSH。

判斷依據：bundle 以 ?rev=<12位hash> 下發且帶 cache-control: immutable，rev 不變瀏覽器就不會重新請求——所以「頁面沒變」通常意味着 rev 沒變（HMR 沒看到文件變化），而不是需要重啓。

怎麼確認自己看到的是哪一次構建：把鼠標停在批註面板左上角的文件名上，tooltip 末尾有 build 2026-10-22 16:34 這樣的本地時間戳（構建時寫入）。沒看到時間戳或時間偏舊，就是舊 bundle 還在跑。

典型用法¶

1. 在會話裏打開一個 HTML 文件的預覽。
2. 默認選擇「HTML · 頁面批註」預覽實現，點擊預覽頭部的「批註」。
3. 在頁面上選擇元素，輸入批註（支持顏色、字號等樣式配置）。
4. 保存後繼續標註下一個元素，不必重新進入選擇模式。
5. 全部標完後選擇「發送到會話」或「填入輸入框」。

適用場景與注意¶

• 只處理 HTML；Markdown/Excel/圖片的預覽不顯示「批註」按鈕。
• overlay 需要 iframe 允許腳本，因此用 sandbox="allow-scripts allow-same-origin"。被標註的頁面裏的腳本會照常運行——和自帶的交互式預覽一致。
• 頁面重掛載時批註會保留（按地址存放在內存 Map 裏），但不跨應用重啓持久化。
• 元素在重掛載後按 CSS 選擇器重新綁定；頁面結構變化後再次標註即可。

插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。

結尾¶

dsh-page-annotate 讓你能在 DSH 預覽裏圈選元素、寫批註，然後把整批批註作爲一條消息發進會話，讓模型按批註改頁面。目錄頁：https://www.skillhub.cn/plugins/baigo8/dsh-page-annotate。GitHub：https://github.com/baigo8/dsh-page-annotate。