dsh-ui-beautify

> 给 DeepSeek Harness（DSH）Web UI 换一套好看的外观：配色预设、整页背景图、VSCode 式卡片布局（面板停靠 / 浮动 / 标签页宿主），全部可撤销、可记忆。

✨ 功能特性

• 四套配色预设（默认 / 深海蓝 / 暖沙 / 松石绿），浅色 / 深色模式各有适配，一键切换；
• 全局强调色跟随：文件夹图标、加载螺旋、标签高亮、Deep Diving、超链接等蓝色元素随预设变化；
• 整页背景图：本地图片一键上传（自动压缩 + 可读遮罩），侧边栏与主区都显示；
• VSCode 式卡片布局：侧栏 / 对话 / 停靠卡三张卡片，可拖出浮动（毛玻璃）、吸附到上 / 下 / 左 / 中 / 右任一区域；
• 吸附与缩放：停靠手柄拖宽（双击重置默认宽度）、浮动窗四边四角缩放、拖拽收起侧栏图标栏；
• 插件面板（统一插件入口）：所有注册插件自动出现在插件面板——卡片模式占停靠卡、经典模式为右侧停靠面板（可拖宽 / 标题拖出浮动），插件列表（默认单行芯片横向滚动、拉高分隔条变网格、溢出菜单带搜索）+ 标签页宿主，标题栏「插件面板」按钮一键开合；
• 设置自动记忆：配色、背景图、布局（位置 / 宽度 / 浮动 / 面板开关）保存在浏览器本地，重启自动恢复；
• 完全可撤销：「清除」「重置」「切回经典模式」即时还原，卸载无残留。

安装

前置要求

• DSH 0.1.0-rc.7（本插件针对该版本的 Web 客户端编写，见「兼容性」）
• 官方安装方式需要 pnpm（npm install -g pnpm）

官方方式（推荐）

dsh plugin --profile web add github:Zalpha263/dsh-ui-beautify

• 发布到 npm 后可直接：dsh plugin --profile web add dsh-ui-beautify
• 装完重启 DSH，然后打开「设置 → 外观美化」即可使用
• 升级 / 卸载：dsh plugin --profile web update/remove dsh-ui-beautify

<details> <summary>旧版手动安装（仅 v1.2 之前使用，已不推荐）</summary>

DSH 旧版本没有 dsh plugin 流程，需要把本包复制到两处并手工注册：

1. 复制包到 profile 目录：$DSH_HOME/profiles/<profile>/node_modules/dsh-ui-beautify 2. 复制包到 dsh 安装目录：<npmRoot>/@deepseek-ai/dsh/node_modules/dsh-ui-beautify 3. 在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 追加注册行：

- insert:
    - id: ui-beautify
      name: dsh-ui-beautify

4. 重启 DSH。 </details>

使用说明

打开「设置 → UI设置」（外观美化与布局设置已合并于此）：

卡片布局速览

• 拖出即浮动：按住卡片顶部抓取条（或插件面板的拖条 / 标题栏）拖动，松手在停靠区（上 / 下 / 左 / 中 / 右）= 吸附回位，否则 = 就地浮动；Esc 取消。
• 缩放：浮动窗四边 / 四角拖动缩放；停靠态手柄调宽（拖到最左 <140px 收起图标栏 / 关闭停靠卡），双击手柄重置默认宽度。
• 插件面板：卡片模式占停靠卡、经典模式为右侧停靠面板（左边缘拖宽、标题拖出浮动 / 回停靠 / × 收起全部）；顶部拖条悬停显示小横条 + 高亮；插件列表默认单行芯片（横向滚动、拉高分隔条变网格、溢出「···」菜单带搜索），打开的插件显示为标签页（切换 / 关闭 / 浮动）。
• 设置避让：浮动状态下打开设置窗口，设置保持全屏居中、不被遮挡。

> 提示：配色预设不仅改变背景与气泡，还会把 DSH 界面中的蓝色强调元素统一成预设的强调色；点「默认」即可恢复 DSH 原生蓝色。

设置保存在浏览器 localStorage 中：刷新页面、重启 DSH 都会自动恢复；清除浏览器站点数据会重置。

卸载

dsh plugin --profile web remove dsh-ui-beautify

重启 DSH 后插件不再加载，页面样式全部还原，无残留。

常见问题（FAQ）

兼容性

• 目标版本：DSH 0.1.0-rc.7，Web 界面（Windows / Linux / macOS）
• 部分样式选择器（消息气泡、发送按钮、侧边栏淡出层等）针对该版本的客户端产物编写，DSH 大版本升级后可能失效，升级后请在「外观美化」里复核效果
• 背景图以压缩后的 data URL 存在浏览器 localStorage（约 5MB 配额内）；超大图片上传时会自动压缩到最长边 ≤2560px

开发者

• 单文件实现：lib/client.js（Host 半区 lib/index.js 为空壳，仅用于注册）
• 调色板在 lib/client.js 的 PRESETS 常量中，改完刷新页面即可生效，无需构建
• 本包是手写 loader 格式（__ModuleLoader__.load），不是 tsdown 产物
• 修改提交后，已安装用户通过 dsh plugin --profile web update dsh-ui-beautify 升级

版本历史

• v1.8.8：健壮性与模块化重构（行为不变）——

- 提取统一拖拽会话助手 startDragSession（8 处重复的窗口监听 + rAF 节流 + 拖动标记样板收敛为一处），并新增拖拽注册表：插件卸载/更新时若有拖拽进行中，teardown 统一清理监听器与标记，杜绝泄漏； - 修复 startDockDrag 用视口坐标记录悬浮位置的隐性 bug（改 frame 相对坐标）；所有拖拽处理器先做空值检查再置拖动标记； - waitFrame/waitSettings 重试加入卸载终止标志（不再空转）；registerPanel 卸载时删除持久化面板状态（不再累积 localStorage）；调试探针定时器仅调试开启时运行； - 浮动窗样式提取为 FLOAT_WINDOW_STYLE 常量（PanelFloat / PluginPanelFloat 共用）。

• v1.8.7：吸附区域优化——五区域吸附提示 portal 到 frame 顶层（z-40），不再被拖动中的卡片（z-35）盖住；五个吸附区域（判定 + 显示同步）缩小 10 个百分点：边缘区深度 18%→8%，中心区 x[38%,62%]→[43%,57%]、y[34%,66%]→[39%,61%]。
• v1.8.6：UI 层级修复——停靠卡建立独立层叠上下文（z-index:0），插件面板内部层级（21）被封在卡内，不再盖过 overlay 层与其他卡片；拖动中的卡片提升到 z-35（data-vsc-dragtop），拖到插件面板上方时拖动卡始终在最前（吸附提示 40 仍在最顶）。
• v1.8.5：插件面板拖条 hover 高亮——与卡片抓取条一致，悬停时整条拖条染品牌色 18% 淡色 + 显示小横条。
• v1.8.4：插件面板拖动提示——面板停靠态标题栏上方新增 12px 拖条（data-vsc-ppstrip），hover 显示 48×4 小横条（与卡片抓取条同视觉语言），按下即拖出悬浮；标题栏仍可拖（4px 阈值防误触）；悬浮态由卡片自身抓取条接管。
• v1.8.3：面板标题栏拖出悬浮——卡片模式停靠态下拖动面板顶栏即把停靠卡拖出悬浮（复用卡片拖拽：五区域吸附回停靠、Esc 取消），与经典模式拖标题栏行为一致；带 4px 移动阈值，纯点击标题不会误触浮动。
• v1.8.2：插件面板跟手性 / 悬浮形态修复——

- 卡片模式改为 portal 内嵌停靠卡：插件面板作为停靠卡内部 inset:0 层渲染，随卡片网格原生缩放/拖动/停靠/悬浮——拖动停靠卡手柄不再有每帧 React 定位延迟，跟手性与侧栏/对话卡一致； - 悬浮形态统一：停靠卡拖出悬浮时，卡片的毛玻璃 + 圆角 CSS 直接作用于面板（不再保持吸附态直角实色）；悬浮时隐藏面板标题栏，右上角只保留卡片自带的单个 ×，顶部抓取条可拖动； - 拖动信号统一：所有插件面板拖动（经典左边缘 / 列表分隔条 / 浮动手柄 / 拖出）都标记 frame data-vsc-dragging，file-explorer 借此在拖动中暂停目录树刷新，消除偶发卡顿； - 吸附态颜色沿用侧栏实色底（与侧边栏/停靠卡一致）。

• v1.8.1：插件面板四项修复——

- 吸附外观统一：停靠态改为侧栏实色底（sidebar-fill）、四角直角、仅与对话卡相邻的左侧 1px 分隔线（l3），与停靠卡体系一致；浮动态保持毛玻璃 + 12px 圆角； - 缩放跟手：经典模式停靠面板左边缘、插件列表分隔条拖动改为直接写 DOM 样式（与卡片缩放的 CSS 变量直写同模式），拖动中不再每帧 React 重渲染，松手才刷新；吸附态去除毛玻璃后拖动开销更低； - 浮动窗缩放：经典模式浮动窗补全四边四角 8 方向缩放手柄（与卡片浮动一致），支持 n/s/e/w/nw/ne/sw/se 各向缩放； - 模式切换不丢失：插件面板停靠卡矩形改为由布局状态推导（dockRegionRect），不再依赖 DOM 实测——卡片 ↔ 经典互切后面板必定渲染；并新增 frame 整体重挂载的自愈（400ms 轮询检测陈旧 frame 并重新定位）。

• v1.8.0：统一「插件面板」——

- 停靠卡 / 右侧详情列正式改造为插件面板：卡片模式占停靠卡，经典模式渲染为右侧停靠悬浮面板（左边缘拖宽，标题栏拖出浮动 / 回停靠 / × 收起全部）； - 面板内容：插件列表（默认单行芯片横向滚动，拖动分隔条拉高变多行网格，溢出「···」菜单带搜索）+ 标签行（打开 / 关闭 / 浮动）+ 内容区；无插件时显示「暂无插件」； - 标题栏新增「🧩 插件面板」按钮（会话日志按钮旁），两种模式共用，高亮跟随开关状态； - 卡片模式下原生「详情」面板彻底隐藏（工具详情由轨迹面板覆盖），「无活动会话」占位移除； - 打开 / 关闭插件的状态在两种模式间同步持久化；设置「停靠卡」改名为「插件面板」。

• v1.7.10：面板宿主 API 扩展（向后兼容）——dock 服务新增只读方法 mode()（当前布局模式）/ isOpen(id)（面板开关状态）/ subscribe(fn)（状态变更订阅，覆盖打开/关闭/浮动/回停靠/模式切换）；dsh-file-explorer v1.6.0 借此把文件浏览器注册为停靠卡标签面板，卡片模式下与停靠卡体系完全统一。
• v1.7.9：修复卡片模式所有悬停提示被隐藏——v1.4 起用于隐藏原生列宽拖拽手柄的规则 [data-vsc-layout] [data-side]{display:none} 选择器过宽：DSH 的 Tooltip 气泡恰好也带 data-side="top/right/bottom/left"，导致卡片模式下输入框下方统计行（token 消耗 / 请求轮数 / 缓存命中）悬停全文提示、消息操作按钮提示等全部被隐藏。现收窄为仅隐藏原生手柄（data-side="sidebar"/"details"），所有 tooltip 恢复原生行为。
• v1.7.8：消息时间详情行改为文本悬停也可触发——原生只在「用户气泡整行 / 助手回复下方的尾巴区域」悬停时才浮现「时间 · 运行时长 · token/秒」，悬停消息正文本身不触发（诊断探针确认卡片模式下原生机制正常）；现新增悬停委托：悬停任意消息正文即显示该条消息的详情行，移开自动收起，其余行为不变。
• v1.7.7：修复输入区弹层被裁剪——移除 seat 的 mask（它会裁掉溢出 seat 的命令菜单 / 候选列表与权限选择弹层），恢复原生弹出行为；保留 v1.7.6 的淡入颜色修正。
• v1.7.6：输入框过渡颜色修正（淡入末端降为 60% 浓度，与对话区更协调）。
• v1.7.5：输入框过渡改为双向渐变（右侧横向淡出，滚动条槽过渡自然）。
• v1.7.4：对话卡停靠非中心区域时表面微染侧栏色，接缝观感与其他卡片一致。
• v1.7.3：输入框恢复原生 webUI 淡入样式。
• v1.7.2：吸附提示缩小 20%；任意停靠组合的接缝线统一；单卡停靠自动补自由列。
• v1.7.1：修复 v1.7.0 崩溃（五区域槽求解器键名错误导致布局失效）。
• v1.7.0：五区域通用吸附（上 / 下 / 左 / 中 / 右，任意卡片可停靠任意区域）；吸附提示仅悬停时显示。
• v1.6.0：健壮性修复（停靠位置白名单、浮动组合下右停靠错位、frame 重挂载自动重标等）。
• v1.5.x：接缝线体系与观感修正——v1.5.3 统一卡片描边；v1.5.4 改由停靠卡绘制接缝线；v1.5.5 提亮为 border-l3；v1.5.6 停靠卡改用侧栏底色形成色差接缝；v1.5.1 移除双层半透明叠加变暗。
• v1.4.x：卡片布局引擎上线——v1.4.0 三卡停靠 / 浮动 / 标签面板宿主；v1.4.4 拖拽交互修正；v1.4.7-1.4.9 底部接缝确定性行高、归档后停靠卡占位提示等。
• v1.3.x：设置记忆完善——背景图持久化修复、配额超限自动降质重试、全局强调色跟随预设。
• v1.2.0：支持 dsh 官方 bundle 安装方式。
• v1.1.x：背景图持久化修复（自动压缩上传、切换预设不再覆盖图片、重启不丢失）。
• v1.0.0：初始版本——配色预设 + 整页背景图 + 全部可撤销。

License

MIT