dsh-whale-tools

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（每次请求现读文件），抠图成功后当场换图，无需重启
图片持久化	用户路径图存在 $DSH_HOME/dsh-whale-widget/image.png；tools/dsh-whale-mascot-apply.sh 负责铺设它，默认不触碰任何第三方包文件
可选补丁（默认关闭）	想让 dsh-whale-widget 自己也优先读用户路径图，可显式打补丁：bash tools/dsh-whale-mascot-apply.sh --patch。⚠️ 它会改写 node_modules 里那个包的文件（pnpm 重链后会丢），撤销用 --revert；因为会改别人的包，不再自动执行，见第 6 节
会话头部「重启 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	❌	仅在显式打补丁（--patch）时用于文本注入	补丁跳过；本插件主功能不受影响
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 准备你自己的图片

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

1. 放到 assets/whale-mascot/DSniang1.custom.png（仓库自带该目录，但不含图片 —— 作者的自定义图有版权，不随仓库分发）；
2. 放到 $DSH_HOME/dsh-whale-widget/source.png；
3. 用 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_SELFHEAL	未设（关闭）	设为 1 才在 boot 时自动重放补丁 —— 它会改写 dsh-whale-widget 包文件，故默认不做
DSH_WHALE_ADMIN_TOKEN	未设	设了就把它当作「仅电脑端」标识头的值（真凭证，替代公开的 1）
DSH_WHALE_ALLOW_REMOTE_ADMIN	未设	设为 1 时取消「仅电脑端」闸门（见第 6 节，不建议）
DSH_HOME	~/.dsh	dsh 数据目录（用户图片路径由它推导）

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

---

5. HTTP 路由

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

方法	路径	仅电脑端	说明
GET	/dsh-whale-tools/status	否	当前图状态（exists/bytes；mtime+md5 只给电脑端）
GET	/dsh-whale-tools/current.png	否	当前图（no-store，现读文件）—— 挂件图片就走这里
GET	/dsh-whale-tools/heartbeat	否	浏览器心跳（touch 心跳文件，204）。全插件唯一一个会写文件的只读语义路由，只写一个时间戳
POST	/dsh-whale-tools/cutout	✅	上传图片字节（≤20 MB，按 magic bytes 校验必须是位图）→ 跑抠图 → 覆盖用户图与真源
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 真的被重启了。

现在的闸门（三道，全部要过）：

1. 来源地址必须是回环；
2. Origin / Referer 若存在，必须是回环（127.0.0.1 / ::1 / localhost）。 —— 这两个头由浏览器自己填，页面脚本改不了。手机经隧道访问时 Origin 是隧道域名， 恶意网页则是攻击者域名，因此都被拒绝；
3. 请求头 x-dsh-whale-tools-desktop: 1。 设了 DSH_WHALE_ADMIN_TOKEN 时，这里必须是那个令牌的值（真凭证）。

它是什么、不是什么（请如实理解）：

• 第 3 条那个头是区分器，不是认证——它的值公开写在本 README 与源码里。
• 真正的边界是：3080 只绑 127.0.0.1 + 移动网关会剥掉自定义头 + 能在本机发请求的 进程本来就拥有与本插件相同的用户权限（可以直接 systemctl --user restart，不需要绕过插件）。
• 所以本闸门挡的是浏览器跨站请求与经公网隧道的设备，不是把本机进程沙箱化。 想要更强的边界，就设 DSH_WHALE_ADMIN_TOKEN，或干脆别把 3080 暴露出去。

其他：手机端照旧可以看状态与显示小鲸鱼（不含 md5 指纹）；手机端不能换图、不能重启 dsh。 逃生舱：DSH_WHALE_ALLOW_REMOTE_ADMIN=1（等于把上面三道全关掉，除非你清楚后果，否则别用）。

6.1 不会偷偷改别人的包

旧版在每个 boot 都无条件跑补丁脚本、用 python3 改写 node_modules/dsh-whale-widget/lib/index.js。 这属于「无人值守地修改第三方包」：会破坏那个包的文件完整性、pnpm 重链后反复重打、且卸载无法还原。 现在默认关闭（DSH_WHALE_SELFHEAL=1 才开），并且：

• 换图的主防线是浏览器端接管 <img>（client.js 的 overrideWhaleImage），完全不依赖补丁；
• 补丁要打就显式 --patch，要撤就 --revert（脚本会逐字节还原）；
• 补丁没打上（锚点缺失）时脚本以 exit 3 退出，调用方不会再把它记成「自检成功」。

---

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；
• 2026-09-13 加固后的实测（桩测试，只读）：跨站 Origin、隧道 Origin、外部 Referer、 缺标识头 —— 四种情况全部 403；回环 Origin + 标识头放行；非电脑端 /status 不再返回 md5； 上传非图片被 magic bytes 拒；apply.sh 的默认/--patch/--revert（逐字节还原）/--check 四种模式与 exit 2/exit 3 分支均按预期；
• 手机端拖动修复：作者真机确认可用（代码层面无法用合成事件验证）。

已知限制

• dsh-whale-widget 在模块 import 期就定死了 IMAGE_CANDIDATES，所以「打补丁」这件事 要到下一次重启才生效；本插件的浏览器半因此做了主防线（直接改 img.src）， 不再依赖补丁才能换图；
• pnpm 重链会冲掉对 node_modules 里挂件的任何手改，所以补丁会丢；但换图本身不依赖补丁 （浏览器半直接改 img.src），补丁只是可选的第二道防线，故默认不打、也不再自动重放；
• 抠图对「白底、单一主体」的图效果最好；复杂背景可能残留杂边，可调 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

卸载不会还原小鲸鱼图片。若你显式打过挂件补丁（--patch），请先撤销它：

bash tools/dsh-whale-mascot-apply.sh --revert    # 逐字节还原 dsh-whale-widget 的文件

想回到官方小鲸鱼：撤销补丁后删掉 $DSH_HOME/dsh-whale-widget/image.png 即可 （本插件默认不会改写 dsh-whale-widget，所以「没打过补丁」时无需任何还原）。

---

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        # 铺用户图；--patch 打补丁 / --revert 撤销 / --check 查看
├── assets/whale-mascot/                 # 放你自己的真源图（默认空，见 3.1）
├── scripts/                             # install.sh / uninstall.sh / publish.sh
├── LICENSE
└── README.md

---

11. 许可

MIT © 2026 ankhishtar2-lang —— 见 LICENSE。 再次提醒：vibe coding 产物，未经人工逐行审计，按「原样」提供，风险自负。