前言¶
在 DSH 裏讓智能體改界面時，常見做法是口頭描述「把左邊那個卡片標題調大」「這塊挪到右邊一點」。模型看不到你指的位置，容易改到相鄰組件，或者 CSS 選擇器不唯一。開發者工具能給出 DOM 信息，但把路徑、座標和意圖拼成一條可執行的請求仍然費時。
dsh-ui-annotate 是運行在 DSH 客戶端上的純前端插件：在界面上拖框圈選區域，用自然語言寫想改成什麼樣，插件自動整理成帶唯一 CSS 路徑、視口座標和框內子元素列表的「界面調整請求」，插入輸入框草稿，由你確認後再發送。
這是什麼¶
- 定位：客戶端 UI 圈選與標註插件，把「改哪裏、改成什麼」結構化後寫入會話輸入框。
- 維護者：loiter1EM（npm 包作者字段爲 loiter）。
- 當前版本：0.1.2（MIT 許可證，Node >= 20）。
- 宿主側：
lib/index.js爲空，不訪問文件系統、不截圖、不上傳數據，也不新增端口或進程。
插件通過 Cordis 補丁掛到輸入框工具行左側插槽 conversation.input.left，依賴 @deepseek-ai/dsh-client-ui-slots，平臺爲 web。
核心功能¶
圈選與元素解析¶
- 輸入框左側會出現裁剪圖標按鈕，懸停提示「圈選改這裏」。
- 點擊後全屏變暗，拖動矩形框選；實時顯示寬 × 高，
Esc取消。 - 鬆手後以框中心做命中測試，必要時向上收攏到能覆蓋整個框的容器（僅在覆蓋率確實提升時上移）。
- 提取並寫入消息的內容包括：
- 向上拼接到全頁唯一命中爲止的 CSS 路徑（有id也會校驗唯一性）；
- 祖先鏈、元素在視口中的實際位置、框選區域佔該元素的百分比；
- 框內更小元素（按覆蓋面積排序）、class、role/aria-label、文本、data-*、當前樣式。
消息中會區分「元素實際位置」與「請落在這個座標範圍內」，減少改動落到相鄰元素的情況。
描述改動與可選「標記目標位置」¶
圈選結束後彈出面板，標題爲「我想把它改成……」，並展示實際位置與覆蓋比例；回車換行，用「發送」確認。
若需要移動位置但說不清目標在哪，可點面板裏的「標記目標位置」再拖一次框。最終消息會附帶目標框座標、相對元素中心點的位移（dx/dy，正數向右/向下）以及尺寸差異；支持「重畫」「清除」，不標記則與未使用該功能時行爲一致。
點「發送」後，整理好的內容只插入輸入框草稿，不會自動提交，你還可以繼續編輯。
0.1.2 起支持上述「標記目標位置」，並修復了框選位置與實際改動位置不一致的問題。
安裝與啓用¶
在終端執行官方安裝命令（web profile）：
dsh plugin --profile web add dsh-ui-annotate
安裝後完全退出並重新打開 DSH NEXT。客戶端插件的 bundle 僅在啓動時重新掃描並重算 rev，熱重載不足以加載新插件。
成功後，輸入框工具行左側會多出一個裁剪圖標按鈕。插件不依賴宿主側能力，也不申請額外權限。安裝前可按習慣查看 GitHub 倉庫 源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，行爲以倉庫說明爲準。
典型用法¶
下面步驟對應 README 中的可復現流程。
- 打開需要調整的 DSH 頁面，點擊輸入框左側的圈選按鈕。
- 在目標 UI 上拖出矩形框，鬆手後在面板裏用自然語言寫期望效果（例如字號、顏色、文案）。
- 若涉及位移，在面板中「標記目標位置」再框一次目標區域。
- 點「發送」，檢查輸入框裏生成的草稿，必要時增補說明，再自行提交給智能體。
生成消息的大致結構如下（節選，與倉庫示例一致）：
【界面調整請求】我想修改 DSH 界面上的這個位置。
- 目標元素(CSS 路徑): `section#settings-card`(該路徑在全頁唯一命中此元素)
- 元素: <section>
- 祖先鏈: body > div#app > main
- 元素實際位置(視口座標): x=560 y=180 w=320 h=96 / 視口 1440×900 @2x
- 框選區域(視口座標): x=572 y=192 w=290 h=72 —— 佔該元素的 88%
...
我想改成: 標題再大一點,說明文字換成淺灰
智能體收到的是帶選擇器與座標的約束說明，而不是模糊的「上面那塊」。
適用場景與注意¶
適合誰
- 經常在 DSH 對話裏請求改界面樣式或佈局的開發者。
- 希望把 DOM 上下文一次性交給模型、減少來回澄清的場景。
- 需要在 web 客戶端使用、且接受「只改草稿、不自動發送」工作流的用戶。
注意
- 僅面向 web 客戶端（
dsh.client.platform: web），安裝命令需帶--profile web。 - 座標與覆蓋率依賴當前視口與頁面狀態；窗口尺寸或縮放變化後，應重新圈選。
- 社區目錄 SkillHub 條目 與 GitHub 爲獨立來源，與 DeepSeek / 幻方無官方從屬關係；版本與功能以倉庫 README 與
package.json爲準。
結尾¶
dsh-ui-annotate 把「指哪改哪」落成可覈對的選擇器、座標和改動描述，留在你的手心裏完成發送。若要安裝或查看最新說明，可訪問 SkillHub 插件頁 或 GitHub：loiter1EM/dsh-ui-annotate。
