dsh-whale-tools

Name: ankhishtar2-lang/dsh-whale-tools
Author: ankhishtar2-lang

[!WARNING] 本仓库是 vibe coding 产物。 代码由作者与 AI（DeepSeek Harness 会话）对话生成、多轮迭代而来，没有经过人工逐行审计，也只在作者本机环境（WSL2 + dsh 0.1.5-rc.1 系列）实测过。请自行审阅后再使用；不要直接用于生产或安全敏感场景。代码按 MIT「按原样（AS IS）」提供，不附带任何担保，风险自负。

A vibe-coded satellite plugin for dsh-whale-widget: drop in any image and the built-in cutout pipeline replaces the whale mascot; plus a session-header restart dsh button, a browser heartbeat and a boot-time self-heal.

给 dsh 的小鲸鱼挂件配上「任意图片一键换装」，顺手补两个运维小工具。

1. 它做什么

能力	说明
设置项：小鲸鱼图片（自动抠图）	设置 → 外观页最下方：选图 → 服务端跑抠图流水线（裁剪 → 边界洪水填充去白底 → 只留最大连通域 → 居中缩放 610×610 透明 PNG）→ 同时覆盖「用户路径图」与「抠图真源」
立即换图，不依赖补丁	浏览器半把 `.dshwv-img` 的 `src` 指向 `/dsh-whale-tools/current.png`（每次请求现读文件），抠图成功后当场换图，无需重启
图片持久化	配合 `tools/dsh-whale-mascot-apply.sh` 给 `dsh-whale-widget` 打「用户路径优先」补丁，并把它铺到 `$DSH_HOME/dsh-whale-widget/image.png`
启动自愈	插件 boot 时幂等重放上面那个补丁脚本 —— 因为 pnpm 任何 install/add/update 都会重链 `node_modules`，把手改的补丁冲掉
会话头部「重启 dsh」按钮	`order: -20`（在「打开文件管理器」左边），点一下走完整重启流程：确认 → 遮罩 → 调服务重启 → 轮询探测 → 自动刷新
浏览器心跳	每 30 秒 `GET /dsh-whale-tools/heartbeat`，host 半 touch `$DSH_HOME/.dsh-browser-heartbeat`；启动脚本据此判断「浏览器里已经有 DSH 页面」从而不再新开页面
手机端拖得动小鲸鱼	注入一段 CSS 修掉挂件的触屏缺陷（见第 7 节）

2. 依赖声明（重要）

2.1 硬依赖：`dsh-whale-widget` 插件

必须已安装官方鲸鱼挂件（本插件接管它的图片显示、并给它打补丁）：

挂件类名：.dshwv-root / .dshwv-img（浏览器半按这两个类名工作）；
挂件图片候选列表 IMAGE_CANDIDATES（apply 脚本按这个锚点注入用户路径）。

2.2 硬依赖：外部程序

程序	必需	用途	缺失时
`sharp`（Node 库）	✅	`tools/dsh-whale-mascot-cutout.cjs` 的图像处理	抠图报错；`npm i sharp` 或用 `DSH_SHARP_PATH` 指向已有安装
`python3`	✅	`tools/dsh-whale-mascot-apply.sh` 做文本补丁注入	自愈与打补丁跳过
Node	✅	`>= 20`（全局 `fetch`）	—
`systemctl --user`	❌	头部「重启 dsh」按钮	按钮仍在，但重启会失败

2.3 dsh 版本与平台

项目	要求
dsh 核心	在 `0.1.5-rc.1` 系列的 web profile 上验证；其它版本自测
profile	`web`（`$DSH_HOME/profiles/web`）
平台	Linux / WSL2
Node	`>= 20`

2.4 `package.json` 里的声明

"peerDependencies": { "dsh-whale-widget": "*" },
"dshDependencies": {
  "plugins": [{ "name": "dsh-whale-widget", "required": true, "provides": "小鲸鱼挂件本体" }],
  "programs": [{ "name": "sharp", "required": true }, { "name": "python3", "required": true }]
}

3. 安装

git clone https://github.com/ankhishtar2-lang/dsh-whale-tools.git
cd dsh-whale-tools
bash scripts/install.sh
systemctl --user restart dsh-web-profiled.service      # 由你手动执行

手动安装 = 把整个目录拷到 $DSH_HOME/profiles/web/node_modules/dsh-whale-tools/，再把 "dsh-whale-tools" 追加进 profile package.json 的 dsh.profile.bundles，然后重启。

⚠️ 硬红线：host 半必须存在 export function apply。dsh 的插件加载器是 fail-fast 且不隔离的，缺 apply 会让整棵插件树 boot 失败、dsh web 完全起不来。改这个插件的 host 半之前先记住这条。

3.1 准备你自己的图片

抠图需要一个「真源」图片。三种方式任选：

放到 assets/whale-mascot/DSniang1.custom.png（仓库自带该目录，但不含图片 —— 作者的自定义图有版权，不随仓库分发）；
放到 $DSH_HOME/dsh-whale-widget/source.png；
用 DSH_WHALE_SOURCE_IMAGE=<绝对路径> 指定。

也可以完全不用真源：直接在设置项里上传图片走抠图流水线，结果会写进 $DSH_HOME/dsh-whale-widget/image.png 并同步真源。

安装方式补充：从 npm 安装（可选）

本包的 package.json 已按 npm 发布要求准备好（去掉 private、用 files 白名单控制内容）。发布到 npm 后即可用 dsh 自己的命令安装（dsh plugin add 本质就是 pnpm add）：

dsh plugin --profile web add dsh-whale-tools

自己发布（需要你自己的 npm 账号；scripts/publish.sh 不接触也不保存任何 token）：

npm login
bash scripts/publish.sh --dry     # 自检 + 列出将要发布的文件，不发布
bash scripts/publish.sh           # 真正发布（改过代码要先升 version，同版本号不可覆盖）

发布后请同步更新 README 与上游收录表的描述，保持「描述属实」这一条成立。

4. 配置（环境变量）

变量	默认	说明
`DSH_WHALE_SOURCE_IMAGE`	见 3.1 的探测顺序	抠图真源图片
`DSH_WHALE_CUTOUT_CLI`	`tools/dsh-whale-mascot-cutout.cjs`	抠图 CLI
`DSH_WHALE_APPLY_SCRIPT`	`tools/dsh-whale-mascot-apply.sh`	补丁/铺图脚本
`DSH_WHALE_ALLOW_REMOTE_ADMIN`	未设	设为 `1` 时取消「仅电脑端」闸门（见第 6 节，不建议）
`DSH_HOME`	`~/.dsh`	dsh 数据目录（用户图片路径由它推导）

路径解析顺序：环境变量 → 插件包内自带（tools/、assets/）→ 作者本机历史路径。

5. HTTP 路由

注册在 dsh web（默认 3080）上，只接受回环来源：

方法	路径	仅电脑端	说明
GET	`/dsh-whale-tools/status`	否	当前图状态（是否存在/字节数/mtime/md5）
GET	`/dsh-whale-tools/current.png`	否	当前图（`no-store`，现读文件）—— 挂件图片就走这里
GET	`/dsh-whale-tools/heartbeat`	否	浏览器心跳（touch 心跳文件，204）
POST	`/dsh-whale-tools/cutout`	✅	上传图片字节（≤20 MB）→ 跑抠图 → 覆盖用户图与真源
POST	`/dsh-whale-tools/restart`	✅	先回包、再延迟 300 ms `systemctl --user restart`

6. 安全说明

dsh-mobile 的移动网关会把已配对设备的请求带着特权 cookie 转发到 3080，来源地址也是 127.0.0.1。作者实测：加固前，手机经隧道 POST /dsh-whale-tools/restart 返回 200，dsh 真的被重启了。

因此变更类路由要求一个自定义头（网关转发时会剥掉它，电脑端直连时保留）：

x-dsh-whale-tools-desktop: 1

手机端照旧可以看状态与显示小鲸鱼（只读路由不设闸门）；
手机端不能换图、不能重启 dsh；
逃生舱：DSH_WHALE_ALLOW_REMOTE_ADMIN=1。

7. 关于触屏：为什么还要注入一段 CSS

dsh-whale-widget 是为鼠标写的：.dshwv-root / .dshwv-img 都是 pointer-events: none，靠 document 级捕获 + canvas 像素 alpha 命中来决定要不要开始拖拽，全篇没有一个 touch-action。在触屏上，手指按下的命中目标是下层的应用元素，浏览器据此把这次手势判定为「页面滚动」→ 抛 pointercancel → 挂件直接 endDrag()。结果就是鼠标能拖、手指拖不动。

本插件注入：

.dshwv-img { touch-action: none !important; pointer-events: auto !important }
.dshwv-root.dshwv-dragging, .dshwv-root.dshwv-dragging * { touch-action: none !important }

只作用于鲸鱼图片那一小块，不影响页面其它区域滚动，也不改变挂件自己的命中逻辑。（注意：CDP 合成触摸无法验证这类修复——它绕过合成器的滚动判定——只能真机确认。）

8. 已验证 / 已知限制

已验证

抠图流水线在本机跑通（610×610 透明 PNG，结果 md5 与预览一致）；
设置项、头部按钮、心跳、启动自愈的桩测试全部通过；dump-config 退出码 0；
手机端拖动修复：作者真机确认可用（代码层面无法用合成事件验证）。

已知限制

dsh-whale-widget 在模块 import 期就定死了 IMAGE_CANDIDATES，所以「打补丁」这件事要到下一次重启才生效；本插件的浏览器半因此做了主防线（直接改 img.src），不再依赖补丁才能换图；
pnpm 重链会冲掉对 node_modules 里挂件的任何手改，所以自愈脚本是必需的，不是可选项；
抠图对「白底、单一主体」的图效果最好；复杂背景可能残留杂边，可调 tools/dsh-whale-mascot-cutout.cjs 里的阈值与裁剪比例参数；
「重启 dsh」按钮依赖 systemd user 服务名 dsh-web-profiled.service（写死在 host 半，要换服务名请自行改 lib/index.js）。

9. 卸载

bash scripts/uninstall.sh
systemctl --user restart dsh-web-profiled.service

卸载不会还原小鲸鱼图片、也不会撤销打过的挂件补丁。想回到官方小鲸鱼：删掉 $DSH_HOME/dsh-whale-widget/image.png，并让 dsh-whale-widget 重新安装一次（或在它的 lib/index.js 里移除带 >>> dsh-whale-mascot-apply 标记的那一行）。

10. 目录结构

dsh-whale-tools/
├── package.json                         # dsh.bundle / dsh.client / dshDependencies
├── cordis.patch.yml                     # loader 条目：id=whale-tools
├── lib/
│   ├── index.js                         # host 半：5 条路由 + 启动自愈 + 桌面闸门
│   └── client.js                        # 浏览器半：设置项 + 头部重启按钮 + 图片接管 + 触屏 CSS
├── tools/
│   ├── dsh-whale-mascot-cutout.cjs      # 抠图流水线（sharp）
│   └── dsh-whale-mascot-apply.sh        # 铺用户图 + 给挂件打补丁（幂等）
├── assets/whale-mascot/                 # 放你自己的真源图（默认空，见 3.1）
├── scripts/                             # install.sh / uninstall.sh
├── LICENSE
└── README.md

11. 许可

dsh-whale-tools

[!WARNING] 本仓库是 vibe coding 产物。 代码由作者与 AI（DeepSeek Harness 会话）对话生成、多轮迭代而来，没有经过人工逐行审计，也只在作者本机环境（WSL2 + dsh 0.1.5-rc.1 系列）实测过。请自行审阅后再使用；不要直接用于生产或安全敏感场景。代码按 MIT「按原样（AS IS）」提供，不附带任何担保，风险自负。

A vibe-coded satellite plugin for dsh-whale-widget: drop in any image and the built-in cutout pipeline replaces the whale mascot; plus a session-header restart dsh button, a browser heartbeat and a boot-time self-heal.

给 dsh 的小鲸鱼挂件配上「任意图片一键换装」，顺手补两个运维小工具。

1. 它做什么

能力	说明
设置项：小鲸鱼图片（自动抠图）	设置 → 外观页最下方：选图 → 服务端跑抠图流水线（裁剪 → 边界洪水填充去白底 → 只留最大连通域 → 居中缩放 610×610 透明 PNG）→ 同时覆盖「用户路径图」与「抠图真源」
立即换图，不依赖补丁	浏览器半把 `.dshwv-img` 的 `src` 指向 `/dsh-whale-tools/current.png`（每次请求现读文件），抠图成功后当场换图，无需重启
图片持久化	配合 `tools/dsh-whale-mascot-apply.sh` 给 `dsh-whale-widget` 打「用户路径优先」补丁，并把它铺到 `$DSH_HOME/dsh-whale-widget/image.png`
启动自愈	插件 boot 时幂等重放上面那个补丁脚本 —— 因为 pnpm 任何 install/add/update 都会重链 `node_modules`，把手改的补丁冲掉
会话头部「重启 dsh」按钮	`order: -20`（在「打开文件管理器」左边），点一下走完整重启流程：确认 → 遮罩 → 调服务重启 → 轮询探测 → 自动刷新
浏览器心跳	每 30 秒 `GET /dsh-whale-tools/heartbeat`，host 半 touch `$DSH_HOME/.dsh-browser-heartbeat`；启动脚本据此判断「浏览器里已经有 DSH 页面」从而不再新开页面
手机端拖得动小鲸鱼	注入一段 CSS 修掉挂件的触屏缺陷（见第 7 节）

2. 依赖声明（重要）

2.1 硬依赖：`dsh-whale-widget` 插件

必须已安装官方鲸鱼挂件（本插件接管它的图片显示、并给它打补丁）：

挂件类名：.dshwv-root / .dshwv-img（浏览器半按这两个类名工作）；
挂件图片候选列表 IMAGE_CANDIDATES（apply 脚本按这个锚点注入用户路径）。

2.2 硬依赖：外部程序

程序	必需	用途	缺失时
`sharp`（Node 库）	✅	`tools/dsh-whale-mascot-cutout.cjs` 的图像处理	抠图报错；`npm i sharp` 或用 `DSH_SHARP_PATH` 指向已有安装
`python3`	✅	`tools/dsh-whale-mascot-apply.sh` 做文本补丁注入	自愈与打补丁跳过
Node	✅	`>= 20`（全局 `fetch`）	—
`systemctl --user`	❌	头部「重启 dsh」按钮	按钮仍在，但重启会失败

2.3 dsh 版本与平台

项目	要求
dsh 核心	在 `0.1.5-rc.1` 系列的 web profile 上验证；其它版本自测
profile	`web`（`$DSH_HOME/profiles/web`）
平台	Linux / WSL2
Node	`>= 20`

2.4 `package.json` 里的声明

"peerDependencies": { "dsh-whale-widget": "*" },
"dshDependencies": {
  "plugins": [{ "name": "dsh-whale-widget", "required": true, "provides": "小鲸鱼挂件本体" }],
  "programs": [{ "name": "sharp", "required": true }, { "name": "python3", "required": true }]
}

3. 安装

git clone https://github.com/ankhishtar2-lang/dsh-whale-tools.git
cd dsh-whale-tools
bash scripts/install.sh
systemctl --user restart dsh-web-profiled.service      # 由你手动执行

手动安装 = 把整个目录拷到 $DSH_HOME/profiles/web/node_modules/dsh-whale-tools/，再把 "dsh-whale-tools" 追加进 profile package.json 的 dsh.profile.bundles，然后重启。

⚠️ 硬红线：host 半必须存在 export function apply。dsh 的插件加载器是 fail-fast 且不隔离的，缺 apply 会让整棵插件树 boot 失败、dsh web 完全起不来。改这个插件的 host 半之前先记住这条。

3.1 准备你自己的图片

抠图需要一个「真源」图片。三种方式任选：

放到 assets/whale-mascot/DSniang1.custom.png（仓库自带该目录，但不含图片 —— 作者的自定义图有版权，不随仓库分发）；
放到 $DSH_HOME/dsh-whale-widget/source.png；
用 DSH_WHALE_SOURCE_IMAGE=<绝对路径> 指定。

也可以完全不用真源：直接在设置项里上传图片走抠图流水线，结果会写进 $DSH_HOME/dsh-whale-widget/image.png 并同步真源。

安装方式补充：从 npm 安装（可选）

dsh plugin --profile web add dsh-whale-tools

自己发布（需要你自己的 npm 账号；scripts/publish.sh 不接触也不保存任何 token）：

npm login
bash scripts/publish.sh --dry     # 自检 + 列出将要发布的文件，不发布
bash scripts/publish.sh           # 真正发布（改过代码要先升 version，同版本号不可覆盖）

发布后请同步更新 README 与上游收录表的描述，保持「描述属实」这一条成立。

4. 配置（环境变量）

变量	默认	说明
`DSH_WHALE_SOURCE_IMAGE`	见 3.1 的探测顺序	抠图真源图片
`DSH_WHALE_CUTOUT_CLI`	`tools/dsh-whale-mascot-cutout.cjs`	抠图 CLI
`DSH_WHALE_APPLY_SCRIPT`	`tools/dsh-whale-mascot-apply.sh`	补丁/铺图脚本
`DSH_WHALE_ALLOW_REMOTE_ADMIN`	未设	设为 `1` 时取消「仅电脑端」闸门（见第 6 节，不建议）
`DSH_HOME`	`~/.dsh`	dsh 数据目录（用户图片路径由它推导）

路径解析顺序：环境变量 → 插件包内自带（tools/、assets/）→ 作者本机历史路径。

5. HTTP 路由

注册在 dsh web（默认 3080）上，只接受回环来源：

方法	路径	仅电脑端	说明
GET	`/dsh-whale-tools/status`	否	当前图状态（是否存在/字节数/mtime/md5）
GET	`/dsh-whale-tools/current.png`	否	当前图（`no-store`，现读文件）—— 挂件图片就走这里
GET	`/dsh-whale-tools/heartbeat`	否	浏览器心跳（touch 心跳文件，204）
POST	`/dsh-whale-tools/cutout`	✅	上传图片字节（≤20 MB）→ 跑抠图 → 覆盖用户图与真源
POST	`/dsh-whale-tools/restart`	✅	先回包、再延迟 300 ms `systemctl --user restart`

6. 安全说明

因此变更类路由要求一个自定义头（网关转发时会剥掉它，电脑端直连时保留）：

x-dsh-whale-tools-desktop: 1

手机端照旧可以看状态与显示小鲸鱼（只读路由不设闸门）；
手机端不能换图、不能重启 dsh；
逃生舱：DSH_WHALE_ALLOW_REMOTE_ADMIN=1。

7. 关于触屏：为什么还要注入一段 CSS

本插件注入：

.dshwv-img { touch-action: none !important; pointer-events: auto !important }
.dshwv-root.dshwv-dragging, .dshwv-root.dshwv-dragging * { touch-action: none !important }

8. 已验证 / 已知限制

已验证

抠图流水线在本机跑通（610×610 透明 PNG，结果 md5 与预览一致）；
设置项、头部按钮、心跳、启动自愈的桩测试全部通过；dump-config 退出码 0；
手机端拖动修复：作者真机确认可用（代码层面无法用合成事件验证）。

已知限制

dsh-whale-widget 在模块 import 期就定死了 IMAGE_CANDIDATES，所以「打补丁」这件事要到下一次重启才生效；本插件的浏览器半因此做了主防线（直接改 img.src），不再依赖补丁才能换图；
pnpm 重链会冲掉对 node_modules 里挂件的任何手改，所以自愈脚本是必需的，不是可选项；
抠图对「白底、单一主体」的图效果最好；复杂背景可能残留杂边，可调 tools/dsh-whale-mascot-cutout.cjs 里的阈值与裁剪比例参数；
「重启 dsh」按钮依赖 systemd user 服务名 dsh-web-profiled.service（写死在 host 半，要换服务名请自行改 lib/index.js）。

9. 卸载

bash scripts/uninstall.sh
systemctl --user restart dsh-web-profiled.service

10. 目录结构

dsh-whale-tools/
├── package.json                         # dsh.bundle / dsh.client / dshDependencies
├── cordis.patch.yml                     # loader 条目：id=whale-tools
├── lib/
│   ├── index.js                         # host 半：5 条路由 + 启动自愈 + 桌面闸门
│   └── client.js                        # 浏览器半：设置项 + 头部重启按钮 + 图片接管 + 触屏 CSS
├── tools/
│   ├── dsh-whale-mascot-cutout.cjs      # 抠图流水线（sharp）
│   └── dsh-whale-mascot-apply.sh        # 铺用户图 + 给挂件打补丁（幂等）
├── assets/whale-mascot/                 # 放你自己的真源图（默认空，见 3.1）
├── scripts/                             # install.sh / uninstall.sh
├── LICENSE
└── README.md

ankhishtar2-lang/dsh-whale-tools

dsh-whale-tools

1. 它做什么

2. 依赖声明（重要）

2.1 硬依赖：`dsh-whale-widget` 插件

2.2 硬依赖：外部程序

2.3 dsh 版本与平台

2.4 `package.json` 里的声明

3. 安装

3.1 准备你自己的图片

安装方式补充：从 npm 安装（可选）

4. 配置（环境变量）

5. HTTP 路由

6. 安全说明

7. 关于触屏：为什么还要注入一段 CSS

8. 已验证 / 已知限制

9. 卸载

10. 目录结构

11. 许可

Community comments

ankhishtar2-lang/dsh-whale-tools

dsh-whale-tools

1. 它做什么

2. 依赖声明（重要）

2.1 硬依赖：`dsh-whale-widget` 插件

2.2 硬依赖：外部程序

2.3 dsh 版本与平台

2.4 `package.json` 里的声明

3. 安装

3.1 准备你自己的图片

安装方式补充：从 npm 安装（可选）

4. 配置（环境变量）

5. HTTP 路由

6. 安全说明

7. 关于触屏：为什么还要注入一段 CSS

8. 已验证 / 已知限制

9. 卸载

10. 目录结构

11. 许可

Community comments

ankhishtar2-lang/dsh-whale-tools

dsh-whale-tools

1. 它做什么

2. 依赖声明（重要）

2.1 硬依赖：dsh-whale-widget 插件

2.2 硬依赖：外部程序

2.3 dsh 版本与平台

2.4 package.json 里的声明

3. 安装

3.1 准备你自己的图片

安装方式补充：从 npm 安装（可选）

4. 配置（环境变量）

5. HTTP 路由

6. 安全说明

7. 关于触屏：为什么还要注入一段 CSS

8. 已验证 / 已知限制

9. 卸载

10. 目录结构

11. 许可

Community comments

ankhishtar2-lang/dsh-whale-tools

dsh-whale-tools

1. 它做什么

2. 依赖声明（重要）

2.1 硬依赖：dsh-whale-widget 插件

2.2 硬依赖：外部程序

2.3 dsh 版本与平台

2.4 package.json 里的声明

3. 安装

3.1 准备你自己的图片

安装方式补充：从 npm 安装（可选）

4. 配置（环境变量）

5. HTTP 路由

6. 安全说明

7. 关于触屏：为什么还要注入一段 CSS

8. 已验证 / 已知限制

9. 卸载

10. 目录结构

11. 许可

Community comments

2.1 硬依赖：`dsh-whale-widget` 插件

2.4 `package.json` 里的声明

2.1 硬依赖：`dsh-whale-widget` 插件

2.4 `package.json` 里的声明