前言¶
在 DeepSeek Harness（DSH）裏讓智能體改網頁或遊戲 UI 時，常見問題是：還沒弄清座標系、單位、斷點和層疊規則就開始寫樣式。改完只能靠肉眼判斷有沒有溢出、遮擋或點擊區域過小，審計結論也難以在後續改動後仍然有效。
dsh-ui-layout 由維護者 FM1503 發佈，歸類爲客戶端插件。它把 UI 相關工作收成 契約 → 測量 → 審計 的閉環，並在工作區內對 UI 源文件寫入做軟門禁：未聲明佈局契約前，不宜直接落筆 html、css、jsx 等文件。同一套流程也覆蓋 Godot .tscn 場景與聲明式 layout JSON，不依賴瀏覽器即可完成部分測量。
這是什麼¶
一句話：給 DSH 智能體提供佈局契約、無頭測量與規則化審計，並附帶 Web 側「UI 佈局」面板查看違規與斷點矩陣。
公開倉庫：FM1503/dsh-ui-layout。社區目錄頁：skillhub.cn 插件頁。當前 npm 包版本爲 1.0.0，許可證 MIT。DSH 生態主張「一切皆插件」；社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
核心功能¶
下面按 README 所述能力歸納，均可在安裝後通過工具調用與面板使用。
契約、測量、審計¶
- ui_contract — 在寫 UI 代碼之前聲明佈局事實：座標系、單位、視口、斷點、網格、間距與字號刻度、層疊、命名區域、可交互控件最小尺寸等。
- ui_measure — 對本地 HTML 或 localhost 頁面用無頭 Chrome 在聲明視口下渲染，記錄真實幾何（包圍盒、計算樣式、滾動溢出、層疊與命中測試等）。Godot 場景與 layout JSON 可在無瀏覽器路徑下按錨點/偏移或畫布座標解析。
- ui_audit — 對測量快照跑確定性規則，輸出違規項（選擇器、證據、修復提示）。修復源碼後重跑，直至
verdict爲pass。 - ui_diff — 對比兩次快照，按像素閾值報告出現/消失/移動/縮放的節點，用於證明改動是否局部化。
- ui_matrix — 一次掃過所有聲明斷點，生成規則 × 斷點矩陣、各斷點 PNG、帶標註的違規圖（紅框與圖例）及自包含 HTML 驗收頁。
門禁與提示注入¶
- 軟門禁：工作區內對多種 UI 擴展名寫入進行限制，直至存在契約。
- 系統提示：注入「UI layout protocol」段落，引導智能體先聲明契約、再推導尺寸、審計與 diff。
- 陳舊審計提醒：頁面在最後一次
ui_audit/ui_matrix之後若已變更，運行時會提示審計過期並要求重跑，避免引用舊 PASS 報告。
Web GUI（客戶端）¶
啓用 bundle 後，DSH Web UI 左側欄會出現 「UI 佈局」（README 亦寫作 UI layout guard），中央面板分 tab：概覽（契約與最新審計/matrix 結論）、違規（卡片展示 rule、嚴重度、選擇器、fix hint）、斷點（矩陣與可點擊標註截圖）、佈局樹等，無需在文件樹裏翻報告。
遊戲與聲明式佈局¶
引擎側同源審計循環：Godot .tscn（Control 錨點/偏移）與聲明 layout JSON（畫布像素）無瀏覽器測量，以 SVG/HTML 場景預覽替代整頁截圖。
安裝與啓用¶
從插件市場（npm）¶
市場索引由 jsDelivr 提供，與包版本一致：
https://cdn.jsdelivr.net/npm/dsh-ui-layout@1.0.0/market-index.json
在 DSH Discover → Index sources 添加上述 URL，再從市場列表安裝 dsh-ui-layout@1.0.0。等價命令：
plugin_manager action=install_bundle target="dsh-ui-layout@1.0.0"
本地 checkout / 開發¶
bundle 位於倉庫 plugins/dsh-ui-layout 時，可按 profile bundle 安裝：
plugin_manager action=install_bundle target="<absolute path to plugins/dsh-ui-layout>"
已鏈接的 checkout 修改代碼後，可在運行中的 host 上切換啓用狀態以重載：
plugin_manager action=set_bundle target="dsh-ui-layout" enabled=false
plugin_manager action=set_bundle target="dsh-ui-layout" enabled=true
npm pack 生成的 .tgz 同樣用 install_bundle 指向 tarball 路徑，最接近真實市場安裝。
運行要求¶
- 機器上需 Google Chrome（或 Edge / Chromium）；通過
CHROME_PATH/PUPPETEER_EXECUTABLE_PATH或常見系統路徑定位。 - puppeteer-core 需能從 DSH profile、
DSH_HOME、進程 cwd 或插件目錄解析。 package.json聲明：Node^22.19.0 || >=24.0.0，dsh>=0.2.0。
替換已安裝的 npm 包後通常需重啓應用；鏈接的本地 checkout 可通過 bundle 開關重載。application: "applied" 表示組合已重組；application: "failed" 時查看 diagnostic 字符串。
典型用法¶
README Quick start 中的調用順序可作爲最小可復現路徑。
1. 聲明契約（缺省字段會回落到安全默認值）：
ui_contract action="set" contract={
"platform": "web",
"viewports": [{"id":"mobile","width":390,"height":844},{"id":"desktop","width":1440,"height":900}],
"regions": [{"id":"header","selector":"header"},{"id":"main","selector":"#main"}],
"interactive": {"minSize": 24, "recommendedSize": 44},
"safeArea": {"insets": {"top": 0, "right": 0, "bottom": 34, "left": 0}}
}
2. 渲染並測量本地文件：
ui_measure source={"type":"file","path":"src/index.html"}
3. 審計（可對已有 snapshotId，或一步傳入 source 完成測量+審計）：
ui_audit snapshotId="e73f4cd3cc8b"
ui_audit source={"type":"url","url":"http://127.0.0.1:5173/"}
4. 證明改動範圍（thresholdPx 爲像素閾值）：
ui_diff before={"snapshotId":"08974af9e9b5"} after={"snapshotId":"e74e99cc31a3"} thresholdPx=4
5. 斷點矩陣與標註截圖：
ui_matrix source={"type":"file","path":"src/index.html"} annotate=true
智能體退出條件：ui_audit 返回 verdict: pass，或每條剩餘違規經用戶明確接受。ui_audit 報告含 rule、severity、viewportId、message、selector、fixHint 等字段。ui_matrix 產出各斷點 verdict、responsive 說明、截圖路徑、標註 PNG 路徑及 reportPath / htmlPath；瀏覽器打開 matrix.html 可查看規則 × 斷點表與違規列表。annotate=false 可跳過額外標註渲染。
適用場景與注意¶
適合誰
- 用 DSH 智能體迭代 Web 前端，需要可重複的溢出、重疊、z-order、間距漂移與可點擊區域檢查。
- 需要在多斷點下一口氣驗收，並保留帶標註截圖與 HTML 報告。
- 在 Godot UI 或聲明式 layout JSON 上希望與 Web 共用同一套契約—測量—審計心智。
使用前請注意
- 插件在 當前 dsh 進程的權限與環境中運行；安裝前請閱讀倉庫源碼與 MIT 許可證，確認 puppeteer-core 與 Chrome 調用方式可接受。
- 無頭測量會啓動本機瀏覽器進程，CI 或無圖形環境需自行確認 Chrome 可用。
- 勿在契約缺失時強行寫入 UI 文件；契約變更後應重新測量與審計，並留意運行時的陳舊審計提示。
結尾¶
dsh-ui-layout 把「先聲明佈局事實、再測量、再規則審計」固化爲工具鏈與軟門禁，並用客戶端「UI 佈局」面板集中展示契約、違規與斷點矩陣，減少智能體盲畫 UI 與報告陳舊的問題。
- 目錄頁：https://www.skillhub.cn/plugins/FM1503/dsh-ui-layout
- GitHub：https://github.com/FM1503/dsh-ui-layout
- npm 包：
dsh-ui-layout@1.0.0
