前言¶
讓智能體改網頁，最難的往往不是寫 CSS，而是把問題說清楚。會話裏常見的說法是「這個按鈕偏了」「標題顏色不對」「移動端這裏擠在一起」。模型看到的是文字，看不到你指的是哪一個 DOM 節點、計算樣式實際是什麼、無障礙樹上的角色叫什麼。截一張圖貼進去，也只剩像素，選擇器和佈局數據還是要人再口述一遍。
DeepSeek Harness（命令名 dsh）把智能體運行時拆成可組合的插件：模型、工具、會話、沙箱和界面都可以在 Cordis 內核上增刪。官方倉庫把這件事概括成 Everything is a plugin（一切皆插件）。社區裏因此出現了一批界面增強插件，專門補「人怎麼把視覺信息交給 agent」這一層。
dsh-annotate 做的就是這件事：在 Chrome / Chromium 裏點選頁面元素，把選擇器、DOM 事實、計算樣式、無障礙數據、評論和當前視口截圖，整理成下一輪對話裏 agent 能直接讀的結構化記錄。它由 BrambleXu 維護，社區目錄歸在「界面增強」。
需要先說明：下文引用的目錄頁來自獨立社區站點 DeepSeek Harness 插件庫，該站 About 頁寫明與 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。官方倉庫是 deepseek-ai/deepseek-harness。本文按目錄詳情頁、GitHub README / package.json / src/ / 配套擴展源碼交叉覈對，覈實日期爲 2026-08-18。
這是什麼¶
dsh-annotate 是一款 DeepSeek Harness 瀏覽器元素可視化標註插件。目錄頁和倉庫 README 的定位一致：捕獲 DOM、樣式、無障礙數據、評論與視口截圖，把頁面結構整理成 agent 可參考、可標註的可視化記錄。
倉庫歸屬是 BrambleXu/dsh-annotate，許可證 MIT（目錄頁、GitHub license 字段和倉庫 LICENSE 一致），主要語言 TypeScript。package.json 裏的版本是 0.1.0，要求 Node.js ^22.19.0 || >=24.0.0。截至 2026-08-18，GitHub 顯示 6 星；社區目錄頁當時列出的是 5 星，星標以倉庫頁面爲準。
它不是單獨的截圖工具，也不是通用網頁爬蟲。插件在 dsh 進程裏註冊 /annotate 命令，並在本機 loopback 上開一個 WebSocket；配套的 Chrome 擴展連上這座橋之後，才能進入選擇模式。README 寫明交互受到 pi-annotate 啓發，但實現走的是 Harness 的 human-command、attachment 和 Agent API，用小型 loopback WebSocket，而不是 native-messaging host。
核心功能¶
在頁面上點選，而不是口述¶
在已連接擴展的前提下，會話裏執行 /annotate，擴展會在當前活動標籤頁進入選擇模式。鼠標移到元素上會畫出高亮框；點擊後彈出評論輸入。可以連續點多個節點，點 Submit 一次性提交，Escape 或 Cancel 取消。
如果命令後面帶 URL，例如 /annotate http://localhost:3000，擴展會先把當前標籤頁導航到該地址，等加載完成再開始選擇。源碼裏會對輸入做 new URL(url) 校驗，空輸入則沿用當前頁。
每個元素帶上可覈對的頁面事實¶
擴展的 content.js 和插件側的 protocol.ts 約定了同一套字段。每個被選中的元素會貢獻：
- 選擇器：有
id時用#id，否則沿祖先拼一段最多 4 層的tag.class:nth-of-type路徑 - DOM 事實：標籤名、id、class 列表、截斷後的文本（最多約 500 字符）、前 20 個 HTML 屬性、視口內的矩形位置
- 計算樣式高亮：
display、position、color、backgroundColor、font、margin、padding、border - 無障礙數據：
role（屬性或標籤隱含角色）、名稱、是否可聚焦、是否 disabled - 評論：你在選擇時輸入的那句說明
整次提交還會帶上頁面 URL 和視口寬高。插件把這些內容渲染成 Markdown 風格的文本，再以插件通知的形式 followup 給當前 agent，摘要類似 Captured N browser annotations.。
可選的可見視口截圖¶
擴展在提交時調用 chrome.tabs.captureVisibleTab，格式是 PNG。默認配置 includeScreenshot: true 時，插件會把截圖存成附件 dsh-annotate.png，和文本一起交給模型。README 把範圍限定爲當前可見視口，不是整頁長截圖。
本地橋，而不是把瀏覽器暴露到網上¶
橋的默認地址是 127.0.0.1:43119。apply() 裏如果 host 不是 127.0.0.1、::1 或 localhost，插件直接拋錯退出。WebSocket 的 verifyClient 只接受 chrome-extension:// 來源；擴展連上後先發 hello（協議 version 1 + 擴展 ID）。allowedExtensionId 爲空時接受任意本機已裝擴展，填了則只認這一個 ID。載荷默認上限 16 MiB，請求超時默認 300000 毫秒。
安裝與啓用¶
社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行即可：
dsh plugin add github:BrambleXu/dsh-annotate
如需可復現安裝，目錄頁建議固定 commit 哈希：
dsh plugin add github:BrambleXu/dsh-annotate#commit
把 #commit 換成實際的 commit SHA，不要照抄字面量。官方 CLI 文檔裏 dsh plugin 會轉發到當前 profile 的 pnpm；從倉庫本地檢出安裝時，README 用的是：
dsh plugin --profile demo add ./dsh-annotate
插件只完成 Harness 這一側。配套擴展還要手動裝進 Chrome 或 Chromium：
- 打開
chrome://extensions - 啓用開發者模式
- 選擇加載已解壓的擴展程序，指向倉庫（或已安裝包）裏的
browser-extension目錄 - 打開擴展彈窗，保留默認 bridge 地址
ws://127.0.0.1:43119
彈窗會顯示當前擴展 ID。若要把連接收窄到這一份擴展，把該 ID 寫進後面說的 allowedExtensionId。
目錄頁有一條安全提示，需要原樣理解後再裝：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。 安裝前請檢查源代碼倉庫和許可證。擴展清單是 Manifest V3，申請了 activeTab、scripting、storage、tabs，以及 <all_urls> 的 host 權限——這是它能在任意頁面注入選擇層、截可見標籤頁的原因，裝之前應當自己看過源碼。
典型用法¶
擴展已連接、dsh 進程已加載該插件後，在會話裏執行：
/annotate
/annotate http://localhost:3000
然後在瀏覽器裏：
- 把鼠標移到目標元素上，確認藍色高亮框罩住的就是你要說的節點
- 點擊，在彈出的提示裏寫下評論，例如「桌面寬度下這個主按鈕和次按鈕換行了」
- 需要的話繼續點其他元素
- 點工具條上的 Submit；不想提交就按 Escape
提交成功後，命令返回類似 Sent N browser annotations to the agent. 的提示；agent 下一輪會讀到頁面 URL、視口尺寸、每個元素的選擇器 / 文本 / 樣式 / 無障礙字段 / 評論，以及默認附上的視口 PNG。一個常見用法是：本地前端跑在 localhost，讓 agent 改樣式或修復佈局，你用 /annotate 把「錯的是哪一塊」釘死，而不是再寫一段容易對錯節點的自然語言。
默認配置來自倉庫的 cordis.patch.yml，README 給出的可改項如下（allowedExtensionId 示例是佔位符，請換成彈窗裏的真實 ID）：
- id: dsh-annotate
name: dsh-annotate
config:
host: 127.0.0.1
port: 43119
allowedExtensionId: abcdefghijklmnopqrstuvwxyzabcdef
requestTimeoutMs: 300000
maxPayloadBytes: 16777216
includeScreenshot: true
擴展未連接時，命令會報 The dsh-annotate browser extension is not connected. 改過擴展文件後，需要在 chrome://extensions 裏重新加載已解壓擴展。倉庫開發命令是 pnpm install 和 pnpm run check（類型檢查、測試、構建）。
適用場景與注意事項¶
比較適合這些情況：
- 本地前端開發，agent 負責改 CSS / 組件結構，人負責在真實頁面上指出節點
- 覈對計算樣式、按鈕是否可聚焦、
aria-disabled是否生效這類「截圖裏看不出來」的事實 - 一次提交多個元素，把同一屏上的幾處問題綁在同一輪反饋裏
0.1 版本自己劃定的範圍也很清楚，README 寫明：一臺本地 Chrome/Chromium、一個活動標籤頁、可見視口截圖。 遠程瀏覽器、整頁截圖、編輯過程錄製、可拖拽的行內批註卡片都還沒有。不要指望用它去標遠程真機、Firefox，或把整頁長圖送進模型。
還需要注意：
- 選擇器是啓發式拼出來的，複雜頁面上不一定唯一；評論仍然有用，不要只靠選擇器
- 文本、屬性、祖先層數都有截斷，超長節點不會完整進入上下文
- 橋只綁 loopback，擴展默認連
ws://127.0.0.1:43119；改端口或 host 時兩邊要一起改 allowedExtensionId爲空等於接受本機任意來源爲chrome-extension://的連接，多擴展並存時建議改成精確 ID- 插件跟當前 dsh 進程同權限，擴展又能讀當前標籤頁並截屏。裝的是社區倉庫，不是官方應用商店，源碼和許可證要自己看過再執行安裝命令
小結¶
dsh-annotate 把「用手指一下頁面」接進了 DeepSeek Harness 的對話循環：點選、寫評論、提交，agent 拿到的是選擇器、DOM、樣式、無障礙數據和一張視口截圖，而不是一句含糊的「那邊有點問題」。它目前仍是 0.1 的本地 Chrome 方案，要同時裝 Harness 插件和未打包擴展，安全邊界也明確寫在目錄頁上。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-annotate/
GitHub：https://github.com/BrambleXu/dsh-annotate
