鲸鱼粒子背景 kviiinh/dsh-whale-particles-bg

dsh-whale-particles-bg

用于 DeepSeek Harness（dsh）Web UI 的动画鲸鱼粒子背景——WHALE 轮廓粒子场加上官方点阵网格层，注册到横跨整个框架的 shell.overlay 座位中。

主题：dsh-plugin · deepseek-harness · cordis-plugin

预览

12 秒的录制，展示了鲸鱼粒子场从散开的壳层中汇聚、在空闲时呼吸，以及被指针推动的效果（src/preview.gif，动画 GIF，720×360，10fps，12.6s，2.8 MB）：

whale particle background preview

它是什么

| 层 | 内容 |
| 鲸鱼（z-index 1） | 从 WHALE SVG 路径采样的粒子场（24×18 viewBox，6× 离屏栅格化，每 2px 采样一次）。粒子从散开的壳层中汇聚，空闲时呼吸，并在 4.9 世界单位半径内沿每个粒子旋转的角度被指针推开。 |
| 点阵网格（z-index 0） | 90px 方形点阵，带相邻连线，以及 140px 的指针吸引效果，使点膨胀。 |

两层都是固定的、覆盖整个视口的、可点击穿透的 canvas。主题在每一帧从 body[data-ds-dark-theme] 读取（深色：rgb(215,232,255)，浅色：rgb(50,82,135)），因此浅色/深色无需订阅即可跟随。动画运行在 requestAnimationFrame 上，节流至约 30fps，这也会在标签页隐藏时暂停动画。

安装

前提条件：一个 dsh 部署，且 dsh CLI 在 PATH 上（或者一个源码检出，其中 pnpm dsh … 可用）。

dsh plugin --profile web add git+https://github.com/kviiinh/dsh-whale-particles-bg.git

other sources:
local path : dsh plugin --profile web add /abs/path/to/this/repo
npm : dsh plugin --profile web add dsh-whale-particles-bg (if published)

这个包是一个 bundle：它声明了 dsh.bundle，因此安装时会把它追加到 profile 的 dsh.profile.bundles 中，并且该包自己的 cordis.patch.yml 会插入插件行（id: whale-particles-bg）。无需手动编辑任何内容，而 dsh plugin --profile web remove dsh-whale-particles-bg 会同时移除依赖和该层。

重启 harness（dsh web）。Settings → Plugins → Plugin list → Global plugins 随后会将 whale-particles-bg 列为正在运行，并且鲸鱼背景会出现在 UI 后面。

lib/ 是有意提交的。浏览器那一半必须是由 dsh 自己的 tsdown 预设（packages/client/tsdown.client.ts）生成的 window.__ModuleLoader__.load({ id, factory }) bundle，而该预设只存在于 dsh 检出中。发布构建产物正是让通过 git 安装的副本无需构建步骤即可加载的原因，并且它使安装过程不会出现任何 prepare 脚本权限提示。这里有意不设 prepare 脚本。

在 dsh 升级后重新构建

markdown
scripts/build.sh /path/to/deepseek-harness # 或：DSH_CHECKOUT=/path/to/deepseek-harness scripts/build.sh

检出目录始终显式指定——脚本不假设任何个人目录布局。它将源码暂存到 /packages/client/dsh-whale-particles-bg/，依次运行 pnpm install → tsc -b → tsdown --env.DSH_BUILD_FACE client，将 lib/ 复制回此处，然后删除暂存的副本，并从预先拍摄的快照中恢复 pnpm-lock.yaml 和 pnpm-workspace.yaml——即使构建失败也是如此。

最后一步是 scripts/sanitize-artifacts.mjs，它会清除构建产物中特定于机器的内容，并且如果任何此类内容残留，就会使构建失败。它之所以存在，是因为客户端预设会将包含绝对源码路径的虚拟模块 id（例如 \0dsh-global-css:/global.css.mjs）写入 lib/client.js 中的 //#region 注释——这是每个加载该插件的浏览器都会下载的字符串，会泄露主机用户名、主目录布局和检出位置。该清理还会重写 sourcemap 的 sources，使其从 lib/ 解析到此包中，而不是命名构建暂存路径。

布局

| 路径 | 用途 |
| src/client/index.tsx | 浏览器部分：两个 canvas 组件以及 shell.overlay 注册 |
| src/client/whale-path.ts | WHALE 路径常量 |
| src/client/global.css | 页面背景颜色/渐变（在工厂执行时作为带标签的 注入） |
| src/preview.gif | 动画 GIF 预览（720×360，10fps），由上方 Preview 部分嵌入 |
| src/index.ts | Node 部分：一个空的 apply（纯 UI 插件只需存在于 Loader 中） |
| cordis.patch.yml | 打包层：插入 whale-particles-bg 行 |
| lib/ | 构建产物：index.js（Node 部分）+ client.js + client.js.map |
| scripts/build.sh | 针对检出目录重新构建，将产物复制回来，然后对其进行清理 |
| scripts/sanitize-artifacts.mjs | 从 lib/ 中剥离特定于机器的内容，如果任何内容残留则使构建失败 |

在插件市场中上架

社区市场（dsh-market）由精选的 awesome-dsh-plugin 注册表提供服务，因此进入该注册表才能使插件可从 Settings → Plugin Market 安装。有三件事能让插件进入该注册表：

1. 仓库带有 dsh-plugin GitHub 主题；
2. 包声明了 dsh.bundle 清单（本插件已声明）；
3. 通过拉取请求向注册表的 UI Enhancements 类别提交一个条目。

说明与限制

- global.css 使用 !important 覆盖 body 背景，因此它会影响整个页面。使其可配置意味着注册一个设置命名空间，并在 Plugins 设置标签页中提供一个卡片。
- 没有设置命名空间，也没有宿主侧行为，因此无需按包审批。用 dsh plugin --profile web remove dsh-whale-particles-bg 禁用它，或在 profile 补丁中该行上设置 disabled: true。
- 树外插件带有 @deepseek-ai/cordis 对等依赖；在 dsh 大版本升级后，如果对等依赖不再匹配，请重新构建该包。

鲸鱼粒子背景 —— dsh web 客户端的正式插件包（bundle 形态，可 dsh plugin add 一键安装，替代只在进程内存里存活的动态 Cordis 插件）。

- 鲸鱼层（z-index 1）：从 WHALE 路径栅格化采样的粒子场（24×18 viewBox，6 倍离屏栅格化、每 2px 采样），入场从散点聚合、空闲呼吸与尾部波浪、指针 4.9 世界单位半径内的旋转斥力
- 点线网格层（z-index 0）：90px 点阵 + 邻居连线 + 指针 140px 吸引/放大
- 主题适配：每帧读 body[data-ds-dark-theme]；深色 rgb(215,232,255) / 浅色 rgb(50,82,135)
- 挂载点：shell.overlay（由 @deepseek-ai/dsh-client-ui-layout 声明的 root 作用域 list 槽位），两个全屏 fixed canvas、pointer-events: none
- 帧率：requestAnimationFrame 限 30fps（FRAME_MS = 33）；页面隐藏时浏览器自动暂停 rAF

预览

12 秒录屏：粒子从散点聚合、空闲呼吸，以及指针进入时的旋转斥力（动图 src/preview.gif，720×360，10fps，12.6s，2.8 MB）：

鲸鱼粒子背景预览

目录

| 文件 | 说明 |
| src/client/index.tsx | 浏览器半边：两个 canvas 组件 + shell.overlay 注册 |
| src/client/whale-path.ts | WHALE 路径常量（从原动态插件备份机械提取，md5 一致） |
| src/client/global.css | 页面背景色/渐变（构建时以带标记的 注入） |
| src/preview.gif | 上方「预览」内嵌的动图（720×360，10fps） |
| src/index.ts | Node 半边：空 apply（纯 UI 插件只需在 Loader 里出现） |
| cordis.patch.yml | bundle 层：插入 whale-particles-bg 这一行 |
| lib/ | 构建产物：index.js（node 半）+ client.js（__ModuleLoader__ 工厂 bundle）+ sourcemap |
| scripts/build.sh | 在指定 checkout 中重新构建、拷回产物，并做脱敏 + 校验 |
| scripts/sanitize-artifacts.mjs | 清除 lib/ 里的本机信息，若有残留则让构建失败 |

安装

dsh plugin --profile web add git+https://github.com/kviiinh/dsh-whale-particles-bg.git
或本地路径：dsh plugin --profile web add /绝对路径/dsh-whale-particles-bg

本包是 bundle（声明了 dsh.bundle）：安装时会自动把包追加进 profile 的 dsh.profile.bundles，并由包内自带的 cordis.patch.yml 插入插件行（id: whale-particles-bg）。不需要手改任何补丁文件；dsh plugin --profile web remove dsh-whale-particles-bg 会同时移除依赖与这一层。

重启 dsh web 后生效，插件会出现在 设置 → 插件 → 插件列表 的「全局插件」分组。

若 dsh 不在 PATH 上（源码方式运行），用 pnpm dsh plugin --profile web add 。

上架插件市场

社区市场 dsh-market 的数据来自精选注册表 awesome-dsh-plugin——进了该注册表，才能在 设置 → 插件市场 里一键安装。三个条件：

1. 仓库带 dsh-plugin GitHub 话题；
2. 包声明 dsh.bundle（本包已满足）；
3. 向注册表的 UI Enhancements 分类提一个 PR 条目。

重新构建（DSH 升级后）

scripts/build.sh /path/to/deepseek-harness # 或：DSH_CHECKOUT=/path/to/deepseek-harness scripts/build.sh

checkout 必须显式给出——脚本不假设任何个人目录布局。流程：把源码暂存到 /packages/client/dsh-whale-particles-bg/ → pnpm install → tsc -b → tsdown --env.DSH_BUILD_FACE client → 把 lib/ 拷回本目录 → 删除暂存目录，并从开头的快照恢复 pnpm-lock.yaml 与 pnpm-workspace.yaml（失败时同样会还原）。
最后一步跑 scripts/sanitize-artifacts.mjs：把产物里的本机相关信息脱敏，只要还有残留就让构建失败。之所以需要它：客户端预设会把绝对源码路径写进虚拟模块 id（例如 \0dsh-global-css:/global.css.mjs），出现在 lib/client.js 的 //#region 注释里——而这是每个加载插件的浏览器都会下载的字符串，会泄漏宿主用户名、家目录布局与 checkout 位置。脱敏同时会把 sourcemap 的 sources 改写成从 lib/ 指向本包 src/，不再出现构建暂存路径。

为什么必须暂存进 checkout：共享 tsdown 预设 packages/client/tsdown.client.ts 会按名字在 packages// 下查找包清单，工作区之外的包会直接抛错（no packages///package.json declares the name ...）。

从动态插件移植时的差异

| 项 | 动态插件（whale-bg） | 本包 |
| 外形 | cordis_define 的 JS 函数体字符串 | npm 包（TS/TSX + 构建产物） |
| 槽位 API | ctx.get('slots').inject/register | ctx.slots.inject/register（相同契约） |
| 样式 | styles.insert(...) | import './global.css'（构建时注入带标记 ） |
| 定时器 | ctx.timer.interval(draw, 33) | requestAnimationFrame + 33ms 累加器 |
| 隐藏暂停 | visibilitychange 监听 | 不需要（rAF 自动暂停） |
| 生效范围 | 当前会话、需授权、重启即失 | 全局、随部署启动、无需授权 |

已知限制

- global.css 用 !important 覆盖 body 背景，影响整个页面。如需可配置，可再注册一个 settings 命名空间并在「插件配置」里出卡片。
- 未注册 settings、无 host 半逻辑，因此不需要逐次授权。停用方式：dsh plugin --profile web remove dsh-whale-particles-bg，或在 profile 补丁里给该行加 disabled: true。
- 外部插件对 @deepseek-ai/cordis 有 peer 依赖；DSH 大版本升级后若 peer 不匹配，需要重新构建本包。

License

MIT — see LICENSE.