前言¶
用 DeepSeek Harness 做智能體或前端協作時，經常要把本地 HTML 原型交給同事或模型看：哪裏缺交互、某一步界面長什麼樣，往往靠截圖加文字說明。原型一改，截圖和說明就對不上；多狀態浮層（彈窗、側欄）更難在一張圖裏說清「這條註釋只在打開設置時出現」。
下面介紹社區插件 dsh-design-annotate（維護者 Yuuuyi，分類：工作流）。它在 Harness 側邊欄裏打開本地 .html / .htm 原型，點選元素寫註釋，並按界面狀態控制 pin 顯隱；還可錄製點擊流程並導出流程圖或單文件標註包，且不修改原型源碼，標註寫在旁邊的 sidecar JSON 裏。
這是什麼¶
dsh-design-annotate 是 DeepSeek Harness 的客戶端插件（package.json 版本 0.11.0，許可證 MIT）。一句話：打開 HTML 原型 → 錨定元素加備註 → 流程走到對應 DOM 狀態時註釋再出現 → 導出可分享的 .annotated.html 或帶批註的流程圖 PNG / 交互 HTML。
插件 Host 提供 /annotate-api 路由（服務原型、讀寫標註、導出、保存及原生文件對話框）；bridge.js 注入原型頁面負責選元素、狀態條件與錄製凍結幀。社區目錄頁：skillhub.cn/plugins/Yuuuyi/dsh-design-annotate；源碼：github.com/Yuuuyi/dsh-design-annotate。目錄站點爲社區維護，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
元素標註與狀態條件¶
- 選中即錨定：點擊原型內元素，記錄穩定選擇器（優先
id、唯一data-*、DOM 路徑）、文本快照與位置；失配時可憑snapshot辨認並重掛。 - 跟着界面狀態出現：標註時採集當前浮層狀態（如
aria-hidden、狀態類is-open、display等），寫入conditions；全部成立才顯示 pin，避免全頁鋪滿。 - 標註模式常開：可連續標多個元素；
Shift輕按開關標註模式，Ctrl/⌘ + Enter保存；在備註框內按Shift打大寫不會誤觸開關。
導出與零安裝分發¶
- 導出標註包：生成只讀
<原型名>.annotated.html，對方雙擊即可查看，無需安裝插件。 - 保存源文件：生成可再次打開的副本；標註可內聯爲
window.__DSH_ANNOTATE_DATA__，繼續編輯時寫入同目錄 sidecar。
流程錄製¶
正常操作原型，每次點擊立刻凍結一幀；無點擊的等待可用「插入步驟」補幀。結束後進入流程看板：卡片懸停時在縮略圖用紅色閃爍框標出觸發位置。可「下載 PNG」（流程圖 + 靜態備註欄）或「下載流程板」（單文件 HTML，懸停步驟編號高亮對應備註）。凍結幀爲靜態 DOM（不執行腳本），自包含原型效果較好。
畫板自適應¶
| 原型 | 判定 | 畫板 |
|---|---|---|
| App / PDA | <meta name="viewport" content="width=480">，寬度 280–700 |
按聲明寬度，高度取渲染後內容高度 |
| PC / Web | 無以上聲明 | 1280×800，等比縮放到面板內 |
環境要求¶
- DeepSeek Harness 桌面端 0.2.x
- 已在 macOS 上驗證；Windows / Linux 的文件選擇與保存對話框通過 PowerShell / zenity 實現
- 無 npm 依賴、無構建步驟；整個插件目錄可任意搬遷
安裝與啓用¶
官方 README 未提供 dsh plugin add github:... 一類命令，安裝方式爲本地目錄註冊：
- 下載本倉庫（ZIP 解壓或按 README 說明獲取源碼）。
- 打開 DeepSeek Harness → 設置 → 插件 → 添加插件，粘貼解壓後含
package.json的那一層絕對路徑，例如：
~/dsh-plugins/dsh-design-annotate
- 完全退出 Harness 再打開，左側應出現「設計標註」。
bridge.js 與 export-viewer.js 由 Host 按相對路徑讀取，無需單獨構建。
典型用法¶
標註¶
- 側邊欄點「設計標註」。
- 點「打開原型」（或「更換」）→ 系統文件選擇器選本地 HTML；對話框不可用時 README 說明可回退到手動輸入路徑或掃描目錄。
- 打開「標註模式」，點原型元素 → 右側寫註釋 → 「保存標註」。
- 照常操作原型；流程到對應狀態時元素右上角出現編號 pin；右側列表點條目可跳轉定位。
再點一次「標註模式」或按 Esc 關閉標註模式。
快捷鍵：
| 快捷鍵 | 作用 |
|---|---|
Ctrl/⌘ + Enter |
保存當前標註 |
Shift（輕按） |
開 / 關標註模式 |
Esc |
退出標註模式 |
流程錄製¶
- 點頂部「流程錄製」。
- 在原型裏操作，每次點擊截取當前頁面；需要時用「插入步驟」補幀。
- 點「結束生成」，進入流程看板，按需下載 PNG 或流程板 HTML。
數據落盤¶
默認 sidecar 與原型同目錄：
index.html
index.html.annotations.json
標註 JSON 含 version、file、annotations（每條含 selector、page、note、status、conditions、snapshot 等）。status 爲 open 或 resolved。
適用場景與注意¶
適合：單文件或可內聯資源的 HTML 原型評審、給 Agent 或同事發「帶狀態說明」的交互包、快速錄一遍點擊路徑出流程圖。
限制（README 已說明）：
- 標註僅支持
.html/.htm單文件（或資源內聯的自包含原型）；多頁面目錄相對跳轉尚無路由映射。 - 流程錄製凍結幀不跑腳本，依賴外部相對資源或 canvas 運行時結果的頁面可能缺內容。
- 原型 DOM 大改後選擇器需重標；流程看板關閉後不持久化，需重新錄製。
安全與權限：插件在當前 DSH 進程權限下運行，可讀寫你選擇的本地 HTML 與 sidecar。安裝前請自行查看 GitHub 倉庫 源碼與 MIT 許可證；第三方依賴含 vendor/html2canvas.min.js（html2canvas 1.4.1，MIT）。
結尾¶
dsh-design-annotate 把「點哪標哪、按狀態顯隱、sidecar 不動原型、單文件分發」和「點擊錄流程、導出 PNG / 交互流程板」收進 Harness 側邊欄，適合 HTML 原型協作與說明。進一步說明與截圖見社區目錄 skillhub.cn/plugins/Yuuuyi/dsh-design-annotate 與 github.com/Yuuuyi/dsh-design-annotate。
