流体动态背景 pxyzy99/dsh-webgl-fluid

dsh-webgl-fluid

为 DeepSeek Harness（DSH）桌面端 Web UI 提供实时 GPU 流体（Navier-Stokes）动态背景的插件。

默认视觉对齐参考页的深色克制观感：近黑底色为主 + 少量低饱和冷色染料，整体接近「静止深色背景 + 轻微局部扰动」，鼠标移动只在指针附近激起局部水波。

- 参考效果：<https://paveldogreat.github.io/WebGL-Fluid-Simulation/>
- 上游实现：<https://github.com/PavelDoGreat/WebGL-Fluid-Simulation>（MIT）

主界面：全窗口深色克制流体背景，UI 完全可读

预览

| 场景 | 截图 |
| 主界面（全窗口背景，UI 无遮挡、无模糊） | |
| 会话页（长文本可读性） | |
| 设置：启用开关 + 流动强度 | |
| 原始背景层：空闲态（近黑、近乎静止） | |
| 原始背景层：鼠标局部扰动（仅指针附近） | |
| 颜色风格：深海 ocean | |
| 颜色风格：暗焰 ember | |
| 颜色风格：静谧 mono | |

特性

- 真实流体解算：对流（advection）+ 涡量约束（vorticity confinement）+ Jacobi 压力投影，来自 Pavel Dobryakov 的 stable-fluids 实现，在单个全屏 WebGL canvas 上运行。
- 单一全局背景层：position: fixed; inset: 0; z-index: -1; pointer-events: none，覆盖整个客户端窗口（含侧边栏、标题栏区域、聊天区、输入框上方），侧边栏 / 聊天 / 输入框 / 菜单都作为半透明表层浮在同一块连续背景之上，无拼接边界。
- 局部鼠标扰动：指针移动只在附近注入速度与染料，其余区域不被拖动，扰动随后自然消散。
- 深色克制底色：四锚点近黑渐变（最大通道 ≤ ~0.07）仅带轻微色相偏移，无左右分裂、无接缝。
- 颜色收敛：染料为低饱和冷色（青 / 蓝 / 紫 / 海绿 / 钢蓝），display 通道不做饱和度增强，避免发艳或发灰。
- 不遮挡 UI：照常点击聊天、输入框、按钮与菜单；不会对面板做 backdrop-filter 模糊，文字始终清晰（见下方「已知限制」）。
- 设置行（设置 → 通用 → WebGL 流体动态背景）：启用开关、流动强度、颜色风格、性能档位，配置持久化到 localStorage。
- 资源管理：失焦 / 切后台暂停；高 DPI 按档位限制 DPR；WebGL 上下文丢失后自动重建；关闭开关立即销毁 canvas 与 GL 上下文。

环境要求

- DSH 桌面端（Web 前端，需要 WebGL）。已在 DSH 桌面端 0.2.1-rc.2（Windows x64） 实测。
- 需要 WebGL2 或 WebGL1 + 必要的浮点纹理扩展；不满足时插件静默降级，不阻塞界面。

安装

插件是一个独立的 DSH bundle 包，放到任意目录后以 link: 依赖 + dsh.profile.bundles 启用。

方式 A：直接下载 zip（无需 GitHub 账号、无需 git）

| 方式 | 链接 | 解压后得到 |
| 发行包（推荐） | <https://github.com/pxyzy99/dsh-webgl-fluid/releases/download/v1.1.1/dsh-webgl-fluid-1.1.1-github.zip> | dsh-webgl-fluid-1.1.1/ |
| 源码快照 zip（v1.1.1 tag） | <https://github.com/pxyzy99/dsh-webgl-fluid/archive/refs/tags/v1.1.1.zip> | dsh-webgl-fluid-1.1.1/ |

两个压缩包内容一致。把解压出的 dsh-webgl-fluid-1.1.1 目录重命名为 dsh-webgl-fluid，放进 <DSH_HOME>\local-plugins\（默认 C:\Users\<user>\.dsh\local-plugins\），再按下方方式配置 profile 即可。

方式 B：git clone

1) 放到本地插件目录（默认 DSH_HOME = C:\Users\<user>\.dsh）
git clone https://github.com/pxyzy99/dsh-webgl-fluid.git
"$env:USERPROFILE\.dsh\local-plugins\dsh-webgl-fluid"

2) 编辑 profile package.json（<DSH_HOME>\profiles\desktop\package.json）：

{
"dependencies": {
"dsh-webgl-fluid": "link:C:/Users/<user>/.dsh/local-plugins/dsh-webgl-fluid"
},
"dsh": {
"profile": {
"bundles": [ "...", "dsh-webgl-fluid" ]
}
}
}

3) 重启 DSH 生效。

也可以直接把本仓库目录复制到 <DSH_HOME>\local-plugins\dsh-webgl-fluid，无需 git。

启用与关闭

- 启用：把 dsh-webgl-fluid 加入 dsh.profile.bundles，重启 DSH。
- 关闭：从 dsh.profile.bundles 中移除该项（dependencies 可保留），重启 DSH。
- 运行时开关：设置 → 通用 → 「WebGL 流体动态背景」行内开关。关闭即销毁 canvas 与 GL 上下文，释放 GPU 资源；重新打开会重建。
- 完全卸载：
1. 从 dsh.profile.bundles 与 dependencies 中删除 dsh-webgl-fluid；
2. 删除 <DSH_HOME>\local-plugins\dsh-webgl-fluid 目录；
3. 重启 DSH。
- 回滚：改动 profile 前建议先备份 package.json（Copy-Item package.json package.json.bak），需要时还原备份并重启。

设置

| 项 | 可选值 | 默认 | 说明 |
| 启用 | 开 / 关 | 开 | 关闭立即释放 GPU 资源 |
| 流动强度 | 0.2x – 2.0x | 1.0x | 缩放指针与环境的注入力 |
| 颜色风格 | 深色克制 / 深海 / 暗焰 / 静谧 | 深色克制 | 全部为深底低饱和家族 |
| 性能档位 | 高 / 均衡 / 低 | 均衡 | 分辨率、压力迭代次数与 DPR 上限 |

| 档位 | 模拟分辨率 | 染料分辨率 | 压力迭代 | DPR 上限 |
| 高 | 144 | 1024 | 24 | 2.0 |
| 均衡 | 112 | 720 | 20 | 1.6 |
| 低 | 72 | 420 | 14 | 0.85 |

视觉标定

上游 WebGL-Fluid-Simulation 默认配置为 DENSITY_DISSIPATION 1、VELOCITY_DISSIPATION 0.2、 PRESSURE 0.8、CURL 30、SPLAT_RADIUS 0.25、SPLAT_FORCE 6000、SHADING true、 BACK_COLOR 黑。本插件据此标定，并按要求收敛颜色与运动幅度：

| 参数 | 上游默认 | 本插件 | 目的 |
| DENSITY_DISSIPATION | 1.0 | 1.0 | 拖尾短、不糊 |
| VELOCITY_DISSIPATION | 0.2 | 0.26 | 扩散更克制 |
| SPLAT_FORCE | 6000 | 2800 | 局部水波更柔和 |
| SPLAT_RADIUS | 0.25% | 0.28% | 扰动范围有限 |
| CURL | 30 | 24 | 涡量细节略收敛 |
| 染料注入量 | generateColor() | pickColor() × 0.15 | 低饱和、不发艳 |
| display 饱和度增强 | 1.18x | 移除 | 颜色按注入值原样呈现 |
| 环境注入间隔 / 幅度 | 2.6–5s / 1.0 | 7–13s / 0.5 | 默认更接近静止 |

性能与资源

- 单个全屏 quad，逐帧仅做 1 次 advection、1 次 curl / vorticity、PRESSURE_ITERATIONS 次 Jacobi 与 1 次 gradient subtract，压力迭代次数随档位变化。
- 使用半精度 / 可用时降低内部格式，纹理按档位分辨率分配（非全屏像素级模拟）。
- visibilitychange / blur 时暂停 requestAnimationFrame，不再产生 GPU 工作量。
- webglcontextlost 时注册恢复逻辑，上下文恢复后重建全部纹理与 program。
- 关闭开关后：取消 RAF、解绑全部事件、deleteProgram / deleteTexture / deleteFramebuffer，并通过 WEBGL_lose_context.loseContext() 主动释放上下文。

校验

仓库自带一个零依赖的自检脚本，覆盖清单完整性、dsh.bundle.patch 目标、exports 解析、 cordis.patch.yml 挂载、locale 合法性、lib/*.js 语法（node --check），以及背景层的关键契约（z-index: -1、pointer-events: none、backdrop-filter: none、关闭时
loseContext() 释放）：

node scripts/validate.mjs

当前结果：10 passed, 0 failed。

仓库未包含 .github/workflows/：推送令牌需要额外的 workflow scope 才能创建 workflow 文件。
如需 CI，执行 gh auth refresh -s workflow 后把上述命令放进一个 windows-latest job 即可。

已知限制

- 客户端内 x≈704px 处的竖直分隔线以及侧边栏/聊天面板的半透明外观属于 DSH 原生窗格样式，插件不修改核心源码，因此无法移除；插件只负责窗格之下的背景层。
- 插件不修改 DSH 核心代码：仅通过官方 bundle 机制挂载一个客户端模块。
- 若宿主未来更改设置页 DOM 结构，设置行可能不再出现（背景层逻辑不受影响）。

目录结构

dsh-webgl-fluid/
├── package.json # bundle 清单：exports / files / dsh.bundle.patch ├── cordis.patch.yml # 把 webgl-fluid 挂进 cordis 树 ├── icon.svg # 插件图标 ├── lib/ │ ├── index.js # 宿主侧（空实现，插件保持纯客户端装饰） │ └── client.js # 全部实现：流体求解器 + 背景层 + 设置行 + 样式 ├── locale/ │ ├── zh.json # 中文标题与描述 │ └── en.json ├── docs/screenshots/ # README 截图 ├── scripts/validate.mjs # 无依赖校验脚本 ├── LICENSE # MIT（含上游版权声明） ├── THIRD-PARTY-NOTICES.md # 第三方与算法出处 └── README.md

来源与许可证

- 流体解算内核（GLSL 着色器与求解器结构）移植自 Pavel Dobryakov 的 WebGL Fluid Simulation，
MIT，Copyright (c) 2017 Pavel Dobryakov。上游许可证全文保留在 LICENSE 与
THIRD-PARTY-NOTICES.md 中。
- 本插件的封装、调色板、背景渐变、设置面板与适配层为原创。
- 本项目以 MIT 许可发布，见 LICENSE。

变更历史

1.1.1

- 移除针对布局面板（会话右侧栏、侧边栏等）的 backdrop-filter: blur(...) 覆盖。此前该覆盖会只模糊面板背后区域并在面板左边界形成一条硬边，表现为“聊天框右半边模糊 + 中间分界线”。
现对面板强制 backdrop-filter: none，全窗口背景连续、文字清晰。
- 说明：客户端内 x≈704px 处的竖直分隔线是 DSH 原生窗格边框，非本插件产物。

1.1.0

- 收敛颜色：display 通道移除饱和度增强，染料改为低饱和冷色集合。
- 拖尾与扩散更克制（DENSITY_DISSIPATION 1.0、环境注入幅度减半）。
- 新增「颜色风格」「性能档位」设置项。

1.0.0

- 首个版本：全屏 WebGL 流体背景、局部鼠标扰动、独立设置行。

dsh-webgl-fluid 是 DeepSeek Harness 桌面插件，在整个客户端窗口背后单独隔离的背景层上，实时渲染 GPU Navier-Stokes 流体模拟。默认外观刻意克制：接近黑色的底色配低饱和染料，只有指针附近出现涟漪（屏幕其余部分从不被拖动），面板上不加 backdrop-filter 模糊。DSH 设置页提供启用开关、流动强度、颜色风格和性能档位。流体求解器改编自 PavelDoGreat/WebGL-Fluid-Simulation
（MIT，Copyright (c) 2017 Pavel Dobryakov）；插件封装层以 MIT 许可发布。