dsh-customui-plugin

Readme

# dsh-customui-plugin（个性化）

给 DeepSeek Harness（DSH）网页版加一个 **「个性化」设置页**：自定义侧边栏 Logo、空对话欢迎区（Logo + 文案）、对话区域背景图。**修改实时生效，无需重启 DSH。**

```
┌ 设置（侧边导航） ────────────────────────────┐
│  通用设置                                    │
│  模型                                        │
│  插件                                        │
│  Agent 预设                                  │
│  个性化            ← 本插件（此位置）          │
│  文件提及                                    │
│  侧边卡片                                    │
└──────────────────────────────────────────────┘
```

## 功能

| 设置项 | 说明 |
|---|---|
| **左上角 Logo** | 替换侧边栏左上角的品牌标识（侧边栏展开状态）。建议横版 SVG，显示高度 24px。 |
| **欢迎区 Logo** | 替换空对话欢迎区的小鱼图标，显示高度 34px。 |
| **欢迎区文案** | 留空保持原版欢迎语；填写后仅显示该文案（Logo 可同显）。 |
| **对话背景图** | 铺在对话区域（消息 + 输入框）后的背景，支持「铺满/完整显示」与 0–100% 透明度（低于 100% 时对话区底色透出，浅色/深色背景都能融合）。建议 1600×900（16:9 横版）。 |

每个图片项都支持 **上传本地图片**（客户端自动压缩：位图缩放到 ≤1920px、转 JPEG/PNG；SVG 原样保留）或 **粘贴图片链接**（https URL）。

## 实时生效的原理

纯浏览器端 DOM 覆盖，不改宿主构建：

- 用**稳定的设计常量**做锚点（不是会随构建变化的哈希 class 名）：
  - 品牌字标 `svg[viewBox="0 0 182 24"]`
  - 欢迎区小鱼 `svg[viewBox="0 0 23.16 17.04"]`
  - 对话区域 `[data-conversation-scroll]`
- `MutationObserver` 监听 DOM，React 重渲染 / 切换会话 / 侧边栏折叠后再把自定义补回来；应用逻辑幂等，不会无限循环。
- 配置写入 DSH 设置命名空间 `customui`（随 profile 持久化），命名空间一变更立即重新应用 —— 所以在设置页里改，界面马上变。

## 安装

需要已有一个 DSH web 部署（`dsh web` 或桌面版）。

```bash
# 方式一：本仓库目录（开发期 link: 软链安装，改动即时生效）
bash scripts/install.sh

# 方式二：npm / GitHub
bash scripts/install.sh dsh-customui-plugin@1.0.0
bash scripts/install.sh git+https://github.com/<owner>/dsh-customui-plugin.git
```

等价的手工步骤（`-w` 必需：profile 是 pnpm workspace 根）：

```bash
dsh plugin --profile web add -w /path/to/dsh-customui-plugin
```

**然后重启 DSH 一次。** 说明：

1. 插件启动时会把 `customui` 设置命名空间幂等地加入 Web 设置页的 api-proxy 白名单
   （`dsh-host-apiproxy` 的 `WEB_SETTINGS_NAMESPACES`），因此「个性化」导航项与设置写入在
   **下一次启动**后出现；
2. 之后所有配置修改都是热生效的，不再需要重启；
3. 卸载：`dsh plugin --profile web rm dsh-customui-plugin` 后重启，再点「恢复默认」清掉已存配置。

> 桌面版更新（覆盖安装）会重置 api-proxy 白名单文件，重启后插件会再次自动打补丁。

## 开发

- 无构建步骤：`lib/index.js`（宿主侧，注册设置 + 打白名单补丁）、`lib/client.js`（浏览器侧，设置页 + 实时应用）均为纯 JS。
- 语法检查：`node --check lib/index.js && node --check lib/client.js`。

## 文件

```
├── package.json          # dsh.bundle.patch + dsh.client.inject 声明
├── cordis.patch.yml      # 宿主 bundle 树插入
├── dsh.plugin.json       # 插件清单
├── lib/
│   ├── index.js          # 服务端：customui 设置命名空间 + api-proxy 白名单自补丁
│   └── client.js         # 浏览器端：个性化设置页 + 实时 DOM 应用引擎
├── scripts/install.sh
├── LICENSE
└── README.md
```

## 已知边界

- 侧边栏**折叠**（rail）状态下只显示图标，不渲染字标 —— 此时左上角 Logo 不生效；展开后恢复。
- 欢迎区仅在**空对话**时显示；有消息后该区域消失（背景图不受影响）。
- 背景图铺在 `[data-conversation-scroll]` 容器上（经 `::before` 伪元素，`z-index:-1`，透明度为真 CSS opacity）；若某版本消息气泡自带不透明底色，可降低透明度或换图。
- 图片以 data URL 存进 profile 的设置文件（`~/.dsh/settings.yaml` 的 `customui` 段）；上传时已自动压缩，但仍建议用几十 KB～几百 KB 的图。

## License

MIT