ArimaKana-Akane/dsh-whale-tools

dsh-whale-tools

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

一个为 dsh-whale-widget 打造的 vibe coding 卫星插件：
放入任意图片，内置抠图流水线就会替换掉鲸鱼吉祥物；
另外附带一个会话头部的重启 dsh 按钮、一个浏览器心跳，以及一个启动时自愈机制。

给 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 才开），并且：
- 换图的主防线是浏览器端接管 （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 产物，未经人工逐行审计，按「原样」提供，风险自负。