前言¶
在 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
