# deepseek-harness-desktop

> 为 DeepSeek Harness Web UI 添加全屏鲸鱼粒子背景，识别页面状态自动调整密度与速度，不替换当前皮肤。

## Metadata

- Author: [@ningbainb](https://github.com/ningbainb)
- Repo: <https://github.com/ningbainb/deepseek-harness-desktop.git>
- GitHub: [ningbainb/deepseek-harness-desktop](https://github.com/ningbainb/deepseek-harness-desktop)
- Stars: 156
- Language: TypeScript
- License: [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
- Homepage: <https://ningbainb.github.io/deepseek-harness-desktop/>
- Topics: `ai-agent`, `ai-coding-assistant`, `codex`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `electron-app`, `gui`, `open-source`, `plugin-system`, `plugins`, `remote-access`, `skills`, `ssh-client`, `windows`, `windows-desktop`
- Forks: 5
- Open Issues: 6
- Last push: 2026-08-20T05:29:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-particle-theme
```

## Wiki

## 一句话定位
为 DeepSeek Harness Web UI 额外叠加一层覆盖整个工作界面的鲸鱼粒子背景。插件识别用户当前所处页面状态，自动降低输入区与弹窗前后的粒子强度，让画面生动但不打扰内容。

## 核心能力
- 挂载一张全屏、不接收鼠标/键盘交互的画布，在主界面背景绘制鲸鱼与漂浮粒子
- 根据页面状态切换五档表现：普通、输入框聚焦、对话框打开、减少动效、页面隐藏
- 提供设置卡片调整粒子密度、透明度、运动速度，并支持一键关闭主题
- 通过自适应帧耗时机制自动升降画面质量，长时间慢帧降低粒子数，稳定快帧再恢复
- 检测系统 `prefers-reduced-motion: reduce` 偏好，触发后画面自动静止
- 注册全新的粒子场景只需向 `ParticleThemeRegistry` 写入一个 ID 与 `update`/`dispose` 实现，无需修改控制器

## 技术实现
- **语言**: TypeScript + React 18
- **关键依赖**: `@deepseek-ai/cordis`（插件运行时）、`@deepseek-ai/dsh-client-runtime`（设置 scope / slots / locale）、`@deepseek-ai/dsh-client-ui-settings`（设置卡片 UI）、`schemastery`（配置 schema）
- **架构模式**: 标准 cordis bundle 插件（`cordis.patch.yml` 注册 `particle-theme`），host 半区（`src/index.ts`）只声明 settings namespace，浏览器半区（`src/client/`）注册 locale、绑定 settings scope、注入设置卡片并启动 canvas 控制器；通过 `ctx.slots.inject('web-ui.plugin.item', …)` 在设置页露出入口
- **入口文件**: `src/index.ts`（host 半区）、`src/client/index.ts`（browser 半区导出 `apply`）

## 适用场景
想让 DSH 工作界面看起来更生动、但又不想换掉当前主题的用户。粒子背景在工作内容之上独立运行，能在不影响阅读的前提下让长时间使用显得不那么单调；对喜欢自定义视觉氛围、想要把启动页的鲸鱼延续到工作流的用户尤其有用。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 平台 SDK | `>=0.1.0-rc.7` | peer/devDependencies 中 `@deepseek-ai/dsh-client-*` 系列均要求 `^0.1.0-rc.7` |
| React | `^18.2.0` | package.json peerDependencies |
| Node 运行时 | 未声明 | package.json 未声明 engines 字段 |
| 平台 | 跨平台（浏览器 Web 端） | dsh.client.platform = web；运行于 DSH Web UI 浏览器半区，无原生模块依赖 |
| 原生模块 | 无 | 仅依赖 schemastery，无 node-pty、sqlite 等原生绑定 |

## 安装方式
```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-particle-theme
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `enabled` | 布尔 | 是否挂载全局粒子画布。关闭后立即移除，无需重启 | `true` |
| `theme` | 字符串 | 选择已注册的场景。当前 schema 仅接受内置 `whale`；扩展新场景需同时扩展枚举值 | `whale` |
| `density` | 数字（0.35–1.5） | 缩放画面里粒子点的总数 | `1` |
| `opacity` | 数字（0.08–0.55） | 缩放画面的整体透明度，默认值优先保证文字清晰 | `0.26` |
| `speed` | 数字（0.4–1.6） | 缩放鲸鱼摆尾与环境粒子的运动速度；系统级「减少动态效果」时会被自动静止 | `1` |

## 常见问题

**Q: 启用后会影响聊天界面的内容显示吗？**

A: 画布设置 `pointer-events: none` 且 `aria-hidden="true"`，既不会拦截鼠标点击，也不会被屏幕阅读器读出；输入框获得焦点或弹窗打开时，控制器自动把密度、透明度、速度都降低一档，文字对比度优先。

**Q: 性能较弱的电脑能跑吗？**

A: 可以。`AdaptiveFrameBudget` 会基于持续帧耗时动态降级：连续 40 帧超过 26ms 就降低粒子数（最低 0.45 倍），连续 180 帧低于 18ms 再恢复；设备像素比被限制在 1.5 以内，页面隐藏时整个渲染循环会暂停。

**Q: 设置项改了不生效怎么办？**

A: 设置通过标准 settings scope 即时发布到浏览器侧画布，正常情况下修改后下一帧就生效；若界面提示「未向设置页暴露粒子主题配置」，说明当前 DSH 版本设置桥未包含此插件，需要升级 Web UI 设置桥或在 settings.yaml 直接配置 `particle-theme` 命名空间。

**Q: 怎样停用而不卸载？**

A: 在「设置 > 插件配置 > 鲸鱼粒子主题」里把启用开关关闭，画布会立即从页面移除，不影响其他功能，下次启用时无需重启。

**Q: 会消耗模型 Token 或增加请求延迟吗？**

A: 不会。本插件纯渲染端实现，不读取对话内容、不发送网络请求、不进入模型调用链路；安装前后模型体验完全一致。

**Q: 如何扩展自己的粒子场景？**

A: 客户端导出 `ParticleThemeRegistry` 与 `ParticleThemeDefinition` 接口，新场景写一个返回 `{ update(state), dispose() }` 的工厂，注册时分配一个唯一 id 即可；控制器会自动复用既有的生命周期、设置订阅和页面感知逻辑。

**Q: 在手机或平板浏览器上能用吗？**

A: 可以，但画布会按窗口尺寸自适应，没有专门的移动端交互适配；建议在手机端关闭主题以节省电量。

**Q: 卸载后会有残留文件吗？**

A: 不会。插件不写本地存储也不创建外部资源，卸载后画布在控制器 `dispose()` 时即从 DOM 移除并解绑全部订阅/监听。

## 上手难度
入门 — 安装后默认配置即可看到效果，所有参数都在设置页里有图形化滑块，不需要写代码或读文档就能调出自己想要的氛围。

## 已知问题与限制
- 设置 schema 的 `theme` 字段目前只接受内置 `whale` ID；新场景包除了注册定义外，还需扩展可选主题枚举才能在设置卡片里被选到（`src/index.ts:17`）
- 自适应质量依据持续帧耗时而非 GPU 遥测；在 GPU 实际紧张但帧率尚可的设备上不会主动降级（`README.zh.md:53`）
- 画布 `z-index: 3`，若其他皮肤或插件在更高层放置覆盖元素，可能在视觉上压住粒子层
- 安装时版本号为 `0.1.15`，处于早期迭代阶段，配置字段或档位数值后续可能调整

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-desktop](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-particle-theme)
Wiki generated by AI (model: `MiniMax-M3`)