dsh-ui-beautify

Readme

# dsh-ui-beautify

> 给 DeepSeek Harness（DSH）的 Web 界面换一套更顺眼的外观，并把原本固定的三栏布局变成可以随手摆放的卡片：配色预设、整页背景图、卡片停靠与浮动，以及一个把所有插件界面收拢到一起的「插件面板」。所有改动都保存在浏览器本地，随时可以一键还原。

## 它做什么

**外观美化**：内置四套配色预设（默认 / 深海蓝 / 暖沙 / 松石绿），浅色与深色模式各有适配，切换时不只是换背景和气泡，连 DSH 界面里的蓝色强调元素（文件夹图标、加载动画、标签高亮、链接等）也会一起换成预设色；此外可以上传一张本地图片作为整页背景，插件会自动把它压缩到最长边 2560px 以内、并为上层文字加上可读遮罩，侧边栏与主区都会显示。

**卡片布局**：侧栏、会话区、停靠区在这里是三张卡片，按住卡片顶部的抓取条就能把它拖出成浮动窗口（毛玻璃质感），松手落在上 / 下 / 左 / 中 / 右任一区域就吸附回去，按 `Esc` 取消。一个区域只能停一张卡，原本停在里面的卡片会被自动挤成浮动卡，等区域空出来再自动回位；停靠态拖动边缘手柄调宽、双击手柄恢复默认宽度，浮动窗支持四边四角缩放，侧栏拖窄到 240px 以下会折叠成图标栏，会话区则始终保底 480px，不会被两侧卡片挤没。

**插件面板**：所有向 ui-beautify 注册过的插件都会自动出现在这里——卡片模式下它占用停靠卡，经典模式下它是右侧可拖宽的面板。面板顶部是「插件列表」（单行芯片、横向滚动、把分隔条拉高会变成网格、溢出时用「···」菜单搜索），下面是「标签条」（按**打开顺序**排列、横向滚动、最左侧常驻 `▾` 菜单，可以切换 / 浮动 / 关闭任意已打开插件）；插件接入的完整规范见 [`docs/plugin-panel-integration.md`](docs/plugin-panel-integration.md)。

**记忆与撤销**：配色、背景图、卡片位置与宽度、插件面板的开合状态与标签顺序都保存在浏览器 `localStorage` 里，刷新页面或重启 DSH 都会自动恢复；「恢复默认布局」和「重置全部」随时可以回到出厂状态，卸载插件后所有注入的样式都会被移除。

## 安装

前置要求是 DSH `0.1.1-rc.2` 及以上（本插件针对当前 Web 客户端编写），官方安装方式还需要 [pnpm](https://pnpm.io/zh/)（`npm install -g pnpm`）。

```bash
# 发布态（推荐：钉死提交，避免 install 时回退到旧版本）
dsh plugin --profile web add github:Zalpha263/dsh-ui-beautify#<完整40位commit>

# 开发态（本地源码目录）
dsh plugin --profile web add file:<你的源码路径>

# 升级与卸载
dsh plugin --profile web install     # 改过 profile 里钉住的提交号后重装
dsh plugin --profile web remove dsh-ui-beautify
```

装完**重启 DSH**，打开「设置 → UI设置」即可使用；升级时把 profile 的 `package.json` 里钉住的提交号改成新提交（无 BOM 保存）再执行 `install`，然后重启或硬刷新。

## 使用说明

所有开关都集中在「设置 → **UI设置**」（外观美化与布局设置已合并到同一页）：

| 区域 | 控件 | 作用 |
|------|------|------|
| 外观美化 | 配色预设 | 一键切换整套配色，点「默认」还原 DSH 原生蓝 |
| 外观美化 | 选择图片 / 清除 | 上传本地图片作为全页背景，或移除背景图 |
| 外观美化 | 重置全部 | 恢复默认外观并清除已保存的外观设置 |
| 布局 | 布局模式 | 「经典」是出厂三列 UI，「卡片」是卡片布局引擎（默认开启） |
| 布局 | 插件面板 打开 / 关闭 | 开关插件面板（插件列表 + 单行标签条） |
| 布局 | 恢复默认布局 | 重置所有卡片的位置、宽度与浮动状态 |

### 卡片布局速览

- **拖出即浮动**：按住卡片顶部抓取条（或插件面板的拖条 / 标题栏）拖动，松手时落在停靠区（上 / 下 / 左 / 中 / 右）就吸附回位，否则就地浮动，按 `Esc` 取消。
- **缩放与折叠**：浮动窗四边 / 四角均可拖动缩放；停靠态用手柄调宽，**双击手柄恢复默认宽度**；侧栏拖到 240px 以下折叠成图标栏、停靠卡拖到 140px 以下关闭，两者最小都能缩到 120px。
- **宽度保底**：会话区占据中间区域时保底 480px，内部按钮行与输入工具行不会重叠；会话区吸附到左 / 右侧后，空出来的中间区域不再保底，会话区可以占满「窗口 − 对侧卡」，小窗会自动钳制上限，因此任意拖动、吸附或缩放窗口都不会溢出、也不会把会话区挤没；其他卡片吸附回中间区域时，中间区恢复 480px 保底，两侧卡自动让出空间。
- **插件面板**：卡片模式占停靠卡，经典模式是右侧停靠面板（左边缘拖宽、标题栏拖出浮动 / 回停靠 / × 收起全部），顶部拖条悬停会显示小横条并高亮；打开的插件以单行标签条呈现，标签按打开顺序排列（先打开的靠左、重新打开排到末尾、关闭当前标签后焦点交给左邻），刷新后顺序保持。
- **设置避让**：浮动状态下打开设置窗口时，设置会保持全屏居中，不会被浮动卡遮挡。

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

## 常见问题

| 问题 | 原因与解决 |
|------|-----------|
| 「设置」里没有「UI设置」 | 安装后没有重启 DSH（插件在启动时加载），重启后再看 |
| 布局错乱 / 想恢复出厂 | 「UI设置 → 布局 → 恢复默认布局」，或清除浏览器站点数据 |
| 卡片拖到某个区域后另一张卡不见了 | 一个区域只能停一张卡，原来的卡片会被挤成浮动卡并在区域空出后自动回位，浮动的卡片顶部有抓取条可以拖回 |
| 换浏览器 / 清缓存后设置不见了 | 设置存在浏览器 `localStorage`，这是预期行为 |
| 卸载后还有样式残留 | 插件样式随插件注入并在卸载时移除，仍有残留请硬刷新（Ctrl+F5） |
| 其他插件更新 / 热重载后界面异常 | v1.15.1 已修复：宿主热重载会替换框架节点，引擎现在会自动识别并重新接管，最迟 1 秒内恢复；若仍异常请硬刷新并反馈 |

## 兼容性

本插件面向 DSH `0.1.2-rc.1` 的 Web 界面（Windows / Linux / macOS）编写。部分样式选择器（消息气泡、发送按钮、侧边栏淡出层等）针对当前客户端产物，**DSH 大版本升级后可能失效**，升级后请在「外观美化」里复核效果；布局引擎则按宿主稳定的 `data-slot` 锚点与三列网格交互，并在每次操作前重新定位宿主框架，因此任意插件热重载导致的宿主重渲染都能自愈。背景图以压缩后的 data URL 存在浏览器 `localStorage`（约 5MB 配额内），超大图片上传时会自动压缩。

## 开发者

单文件实现，Host 半区 `lib/index.js` 是空壳（仅用于注册），全部逻辑在 `lib/client.js`；这是手写的 `__ModuleLoader__.load` 格式，不是构建产物，改完**刷新页面即可生效**。调色板在 `PRESETS` 常量里，布局常量有 `CONV_MIN_W`（会话区最小宽度 480）、`FLOAT_MIN_W` / `FLOAT_MIN_H`（浮动卡最小尺寸）、`SIDEBAR_RAIL`（折叠栏宽 56）。

**插件接入规范**：[`docs/plugin-panel-integration.md`](docs/plugin-panel-integration.md) 是 `dock` 服务（`apiVersion = 2`）的完整契约，包含最小骨架、面板定义字段、API 表、`mount` 生命周期、标签顺序语义、持久化结构、反模式清单与自测清单；`package.json` 的 `files` 已包含 `docs`，文档随包发布。改 `dock` API 时必须同步更新它——消费方要用 cordis 的可选依赖写法 `ctx.inject(['dock'], (c) => { const d = c.dock.registerPanel(def); return () => d() })`（注意回调必须是箭头函数），既不要把 `dock` 写进 `inject: [...]`，也不要用 `ctx.get('dock')` 做身份比对。

## 更新日志

### v1.15.1
- 修复：宿主热重载会替换整个框架节点，而布局引擎的观察者仍挂在旧节点上，导致尺寸丢失、覆盖层与插件面板不再渲染（表现为「更新任意插件后 ui-beautify 整体消失」）；现在引擎会识别节点更换并自动重新接管，另有每秒一次的轻量体检兜底。

### v1.15.0
- 新增：插件面板标签按打开顺序排列，重新打开排到末尾，关闭当前标签后焦点交给左邻，刷新后顺序保持。
- 新增：`dock` API 升到 v2 —— `apiVersion` / `has` / `active` / `focusPanel`，重复注册改为「刷新定义」且返回的 disposer 一定可用。
- 变更：标签条与滚动条之间留出固定间距，并改用宿主统一的 8px 主题滚动条。
- 修复：芯片行溢出时芯片被上下裁切。
- 新增：[`docs/plugin-panel-integration.md`](docs/plugin-panel-integration.md) 接入规范。

### v1.14.0
- 新增：标签条改为单行横向滚动，不再随插件数量换行；最左侧常驻 `▾`「全部已打开插件」菜单，标签标题限宽省略。

### v1.13.2
- 修复：`dock` 服务从未真正对外提供（原调用被宿主拒绝），改用正式契约 `ctx.provide`，下游插件的面板集成自此可用。

### v1.13.1
- 修复：任意插件热重载后，引擎写入已失效节点导致的面板消失与布局错乱；门户注入增加连接校验。

### v1.13.0
- 变更：适配 DSH 0.1.2-rc.1 —— 迁移失效的样式选择器、移除已失效的「消息时间悬停」扩展、清理幽灵依赖声明。
- 修复：宿主重挂载后拖动状态残留导致抓手条消失；标题栏拖动监听缺 `pointercancel` 兜底。

### v1.12.14
- 修复：会话区停靠左 / 右侧时最小宽度提升到 480px，头部按钮行与输入工具行不再重叠。

### v1.12.13
- 修复：中间栏吸附右侧时的缩放与溢出问题，停靠把手贴合卡片真实边缘。

### v1.12.9
- 修复：缩放上限溢出；被挤成浮动的卡片在区域空出后自动回位。

### v1.12.8
- 新增：会话区 480px 保底；侧栏拖窄到 240px 以下折叠成图标栏。

### v1.12.7
- 变更：两侧卡片缩放下限恢复 120px，停靠卡拖窄到 140px 以下关闭。

### v1.12.6
- 新增：会话区 320px 保底，防止被两侧卡片挤没（v1.12.8 提高到 480）。

### v1.12.4
- 修复：恢复默认布局后插件面板状态自愈。

### v1.12.3
- 修复：经典模式切换残留导致中间列卡死。

### v1.12.2
- 变更：浮动停靠卡最小宽度 360 → 280。

### v1.12.0
- 新增：经典三栏插件面板（作为右侧列渲染、可拖宽、可拖出浮动）与 8 向缩放手柄。

### v1.11.1
- 修复：插件面板因图标组件 props 解构错误而崩溃。

### v1.11.0
- 变更：清理重构，抽出共享过渡常量。

### v1.10.x
- 变更：面板细节打磨（关闭按钮尺寸、列表与关闭交互、对话框圆角）。

### v1.9.x
- 变更：界面归一化到 DSH 设计系统与 Apple HIG，设置窗口置顶、浮动卡点击置前。

### v1.8.x
- 新增：统一的插件面板（启动器 + 标签页宿主，卡片与经典两种模式共用）。

### v1.7.x
- 新增：五区域通用吸附，任意卡片都能停靠到上 / 下 / 左 / 中 / 右。

### v1.6.0
- 修复：停靠位置白名单、右停靠错位、框架重挂载自愈。

### v1.5.x
- 变更：接缝线体系与观感修正。

### v1.4.x
- 新增：卡片布局引擎上线（三卡停靠 / 浮动 / 标签面板宿主）。

### v1.3.x
- 新增：设置记忆完善（背景图持久化、配额超限自动降质、全局强调色）。

### v1.2.0
- 新增：支持官方 bundle 安装方式。

### v1.1.x
- 修复：背景图持久化（自动压缩上传、切换预设不再覆盖、重启不丢失）。

### v1.0.0
- 初版：配色预设 + 整页背景图 + 全部可撤销。

## License

MIT