dsh-ui-hub

English | 中文

DSH Web 客户端插件：UI 管家。把页面上每个插件贡献的每个 UI（面板、按钮、图标、图表、输入框……）都枚举出来，支持逐个开关、逐个定位、碰撞避让和一键美观排布，专治插件一多之后的互相遮挡、挤成一团。

✨ 功能

为什么需要它

DSH 是插件生态，每个插件都会往页面塞一点 UI：会话标题栏按钮、输入区下方的徽章、侧边栏底部卡片、右下角浮动药丸、悬浮图表……插件之间互不知道对方在哪，重叠是常态。UI 管家给这些 UI 建立一份统一的「花名册 + 排班表」：

1. 自动发现所有 UI，按插槽分组列出来；
2. 每个 UI 都能关、能挪、能锁定；
3. 浮动控件互相重叠时自动让位；
4. 一键排布，把散落的控件整理成整齐的一列。

📸 界面与功能展示

完整图文说明见 docs/GALLERY.md。

30 秒演示：默认折叠 → 展开官方 UI → 展开分组 → 拖拽模式

界面	文字说明
	面板默认只显示「官方 UI / 插件 UI」两个折叠类别，干净不刷屏
	展开官方 UI：按插槽分组，组默认仍折叠
	展开某组：逐条开关、官方标签、位置模式、⋯ 内部元素
	拖拽模式：虚线框直接拖动移动，右下角手柄改大小，Esc 退出

使用

1. 安装后重启 dsh web，页面右上角出现「UI 管家」胶囊按钮（快捷键 Ctrl+Shift+U / macOS ⌘⇧U），点击打开管理面板；
2. 面板顶层是「官方 UI」/「插件 UI」两个折叠类别（默认全部折叠，只显示类别与数量），点击类别展开其下按插槽分组的组名，再点击组名展开该组的 UI 条目；
3. 条目行：左边开关立即显示/隐藏，右侧 ⋯ 展开详情；
4. 详情里：
   • 位置模式：默认 / 微调 / 浮动；
   • 浮动模式填 X/Y，微调模式填 水平/垂直偏移；
   • 拖拽移动：元素右上角出现抓手，直接拖；
   • 锁定位置：碰撞避让时不移动它；
   • 内部元素：按钮、图标、图表、输入框逐个开关；
5. 顶部工具条：
   • 拖拽模式：开启后直接拖任意 UI 移动位置，拖右下角手柄改变大小，Esc 退出；
   • 自动排布：把所有浮动 UI 沿会话区右缘排成对齐的列；
   • 拾取元素：点击页面上任意元素（哪怕插件没做任何标记）纳入管理；
   • 恢复全部默认：清空全部开关、位置与大小。

编程接口

window.dshUiHub.items()                 // [{ key, label, plugin, category, slot, on, mode, x, y, sw, sh, children: [...] }]
window.dshUiHub.setConfig(key, { on: false })            // 隐藏某个 UI
window.dshUiHub.setConfig(key, { mode: "float", x: 300, y: 200 })
window.dshUiHub.setConfig(key, { sw: 360, sh: 240 })     // 设置宽高
window.dshUiHub.setConfig("child:...", { on: false })    // 隐藏某个内部按钮/图标
window.dshUiHub.arrange()               // 一键自动排布
window.dshUiHub.collisionMode("strict") // off | smart | strict
window.dshUiHub.dragMode(true)          // 开启/关闭直接拖拽模式
window.dshUiHub.open() / close() / reset()

行为细节

• 身份稳定：插槽 UI 以 slot:<插槽名>@<序号> 为身份，跨 React 重渲染自动重新挂接；浮动控件以 data-* 标记（如 data-sticky-disclosure-control）为身份；拾取的元素以结构路径哈希为身份。
• 不用 style 打架：定位通过 data-uihub-float + CSS 变量 + !important 规则实现，其他插件写 inline left/top（非 important）无法覆盖管家设置的位置；去掉标记即恢复插件自己的样式。
• 卸载还原：插件 dispose 时删除全部 data-uihub-* 标记、CSS 变量、样式表和自己的 UI 元素。
• 直接拖拽：拖拽模式只在开启期间拦截指针；插槽里的 UI 拖拽用「平移」（保留在原布局内，点击弹出层会跟着走），脱离插槽的浮动控件拖拽用「浮动」坐标；拖右下角手柄改宽高（浮动模式改浮层大小，默认/微调模式原地固定宽高）。拖拽结束不会给原按钮补发一次 click，普通单击仍原样传给插件；「重置此项」可恢复原样，Esc 退出编辑。
• 浮动弹层跟随：显式设成「浮动」的 UI 若点击后弹出层仍出现在原位置，插件会用独立的 CSS translate 把弹层平移到 UI 的新位置（只作用于锚定在原位置的弹层，居中的整页对话框不受影响）。
• 锁定的项目不动：自动排布与碰撞避让都跳过锁定项，并把其他项绕开它。
• 避让不会无限循环：观察器只对结构/托管元素样式变化触发重算，写 CSS 变量前先比较当前值，收敛后不再写。
• 面板/抓手 z-index 为 80/86，高于插件浮动层、低于应用弹窗层（100+），不会盖住权限与设置弹窗。

安装

需求：Node.js ≥ 20 + DeepSeek Harness（带 dsh plugin 命令的版本）。插件随 dsh web 启动。

方式〇：一键安装（推荐）

irm https://raw.githubusercontent.com/Han-1413141/dsh-ui-hub/main/install.ps1 | iex

方式一：命令行

dsh plugin --profile web add github:Han-1413141/dsh-ui-hub

方式二：本地开发（符号链接）

在本仓库父目录执行：

dsh plugin --profile web add link:./dsh-ui-hub

改 lib/client.js 后刷新页面即生效。卸载：dsh plugin --profile web remove dsh-ui-hub。

测试

python test/verify.py   # Playwright chromium,无外部依赖(仅本机 Python + playwright)

test/mock.html 复刻了平台的 [data-slot] 锚点契约、多个插槽贡献与两个互相重叠的浮动控件；test/verify.py 覆盖发现、官方/插件分类、默认折叠与逐级展开、根/子元素开关、浮动定位、自动排布对齐、严格避让、面板、热键、拾取、直接拖拽移动与拖拽改大小、刷新持久化与卸载还原。

已知限制

• 浮动模式的坐标系：使用 position:fixed。若某个 UI 的祖先元素带 CSS transform，fixed 会相对该祖先定位；这类 UI 建议用「微调」模式。
• 平台 DOM 变更：发现依赖平台公开的 [data-slot] 锚点与各插件的 data-* 标记；平台升级后若改名，对应条目会按新身份重新出现（旧配置仍保留在本地）。
• 子元素身份：内部元素按 DOM 顺序编号，插件重排子元素后配置可能跟随序号落到相邻元素上。
• 插槽内不强制重排：默认/微调模式尊重原插槽布局；跨插槽的「整页重排」请把条目切到浮动后用「自动排布」。