桌面鲸鱼助手 HeiBai-king/dsh-pet

dsh-pet

一键截图问 DSH —— 让 DSH 看见并指导你操作它自己够不到的地方。

⚠️ 装之前先看这个：环境要求

| 要求 | 具体 |
| 操作系统 | 必须是 Windows。package.json 里写死了 os: ["win32"]。Linux / macOS 装不了，装了也不显示球 —— 球是 PowerShell + WPF 做的 |
| DSH | 已安装并能正常开页面。验证过的版本：0.2.0-rc.2（web profile）。用的是 DSH 内部接入点，版本差太多可能完全不显示挂件 |
| Node | >= 20（DSH 自带，正常不用管） |
| PowerShell | 5.1（Windows 10/11 自带） |
| 不需要 | npm 装包、改浏览器调试端口、任何配置文件、任何外部服务 |

不满足上面任何一条就别装。 装完还要做两件事才生效： ① 重启 DSH　② 先选一段会话（不选就点「问一下」会提示"还没选会话"）。

DSH 只能看到自己的窗口和它能读的文件。别的软件、系统弹框、装机界面、游戏、别人电脑上那个报错窗口 —— 它看不见，也摸不着。这个插件补的就是这一段。

它到底干什么

屏幕上浮着一只鲸鱼娘（叫"桌面球"）。你卡在某个 DSH 够不到的界面上时：

点一下球 → 截当前屏 → 发给 DSH 里某一段会话 → 会话看一眼告诉你点什么 → 答案回到球上的气泡

你自己动手，它只负责递画面和拿答案。

不用切回 DSH、不用复制粘贴、不用费劲描述"我屏幕上现在是啥"。

它不能替你操作。 点击、装软件、改设置都是你自己来。
这不是自动化工具，是一个"让 DSH 长出一双眼睛"的通讯器。

长什么样 / 怎么用

① 插件装好后，桌面球会自己出来（不用点任何东西）

球是核心，所有功能都在球上。页面右下角那个鲸鱼小圆图标（叫"胶囊"）只是个附加开关 ——它靠注入进 DSH 页面才出现，某些环境下注入不成功，那时候没有胶囊也能正常用。

- 左键点胶囊 → 桌面球出现 / 消失
- 右键拖着它 → 挪位置（会记住）
- 不想要球一开 DSH 就冒出来 → 配置里写 {"ball":{"autoStart":false}}，改成点胶囊叫

② 桌面球浮在所有窗口之上

- 可以直接拖，也能缩放，位置大小都会记住
- 拖到屏幕左半边，角色会自己转过来面向屏幕内

③ 鼠标移到角色身上 → 右上角浮出菜单按钮 → 点开，有这些：

| 菜单项 | 干什么 |
| 大小 | 滑块调球的大小 |
| 翻转 | 自动翻转开关 |
| 当前会话：XXX | 只读。告诉你消息会发给谁 —— 点之前先看这行 |
| 截当前屏幕问会话 | 截整屏，可以附一句补充说明，发给会话 |
| 发消息（不截图） | 只发一句话过去 |
| 选择会话… | 弹窗选会话（按工作区分组），点一下即选中并关闭 |
| 收起鲸鱼球 | 关掉球（下次开 DSH 会自动回来，或者点胶囊叫） |

④ 气泡上会显示什么

- 球刚启动时什么都不显示（不会把上一轮的话又翻出来）
- 点过按钮之后才开始显示
- 点「问一下」→ 先显示「正在思考…」
- 回答回来后 → 一直挂着，直到你下次提问

第一次用，就三步

1. 屏幕上应该已经有一只鲸鱼球（没有的话：点右下角胶囊，或在 DSH 窗口按 Ctrl+R）
2. 鼠标移到角色上 → 点浮出的菜单按钮 → 「选择会话…」 → 展开工作区 → 点一段会话
3. 回到菜单，看「当前会话」是不是你选的那段 → 点「截当前屏幕问会话」

第 2 步不做就点「问一下」的话，球上会提示「还没选会话」。

安装

前置条件

| 要什么 | 说明 |
| Windows | 只能 Windows（球是 PowerShell + WPF 做的） |
| DSH | 装好能用。验证过 0.2.0-rc.2 |
| 别的 | 没了。不用 npm 装包、不用改浏览器设置、不用配置文件 |

装法一：一条命令（推荐）

git clone https://github.com/HeiBai-king/dsh-pet.git "$env:USERPROFILE\dsh-pet"
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\dsh-pet\tools\install.ps1"

脚本会做三件事（和手工装完全一样）：建目录联接、往 profile\package.json 的 dependencies 里加一条、往 dsh.profile.bundles 里加一条。改之前自动备份 package.json。

没有 git 就下载 zip 解开，然后：

powershell -ExecutionPolicy Bypass -File "<解压出来的目录>\tools\install.ps1"

装法二：DSH 没在跑时用命令行

dsh plugin --profile web add link:"<包目录，正斜杠>"

（DSH 正在跑的话这条会报 EPERM —— native 模块被占用。这时用装法一。）

装完必须重启 DSH

模块图和注入表都是 DSH 启动时定死的，不重启不生效。

装完怎么自查（三件事，缺一不可）

1. 页面右下角出现鲸鱼小圆图标 ← 没有就是没装上
2. 点它，桌面球出来 ← 出不来就看日志
3. 菜单里选一段会话，点「截当前屏幕问会话」，球上出现「正在思考…」然后出回答

日志在两个地方，出问题先看这个：

C:\Users\<你>\.dsh\pet\pet-host.log 宿主日志（起停、投递、自检、报错） C:\Users\<你>\.dsh\pet\pet-ball.log 球日志（气泡上显示过的每句话）

卸载

powershell -ExecutionPolicy Bypass -File "<包目录>\tools\uninstall.ps1"

会删联接、把 package.json 里那两条去掉（同样先备份），不动你的数据目录 （~\.dsh\pet\，里面有选过的会话和日志）。要一起清掉加 -PurgeData。

卸完也要重启 DSH。

配置（可选，不配也能用）

一个文件：~\.dsh\pet\config.json。没有它就是全默认。

| 键 | 默认 | 干什么 |
| askSession | 空 | 默认发给哪段会话。留空 = 先看你上次在球上选的，再退回 DSH 主 Bot 当前会话 |
| pickWorkspaces | [] | 选择框里只列这几个工作区。留空 = 全部。例：["工作", "测试"] |
| trustedHosts | [] | 只有 DSH 部署在非回环地址时才要填 |
| ball.useRegion | false | 把球窗裁成鲸鱼形状。默认别开，见「踩过的坑」第 2 条 |
| ball.autoStart | true | 插件加载后自动把球叫出来。想改成"点胶囊才出球"就写 false |

也支持环境变量（优先级高于 config.json）：DSHW_PET_ASK_SESSION / DSHW_PET_PICK_WORKSPACES / DSHW_PET_TRUSTED_HOSTS / DSHW_PET_USE_REGION / DSHW_PET_AUTO_START_BALL

数据目录不在 ~\.dsh？ 如果 DSH 是用 DSH_HOME 环境变量改过家目录的，那配置和日志都在 $DSH_HOME\pet\ 下。tools\doctor.ps1 会自动认这个变量。

看当前生效的值
node "<包目录>\tools\write-config.mjs"

出问题怎么办

先看日志，再看这张表：

| 症状 | 多半是 | 怎么办 |
| 右下角没胶囊 | 多半是注入没赶上（不影响用） | 看 pet-host.log：有 自动起球结果 ok=true 就说明球已经起来了，胶囊有没有都能用。想补出胶囊：在 DSH 窗口按一次 Ctrl+R 重载页面 |
| 球没出现 | 球进程起不来 | pet-host.log 找 自动起球 那几行 + ball exit code= |
| 点了没反应 | 请求文件没写 / 投递失败 | pet-host.log 找 ask.request seen；有但是失败就看同一行的 msg= |
| 提示「还没选会话」 | 没选过 | 菜单 →「选择会话…」选一段 |
| 一直「正在思考…」不换 | 会话没把回答写回来 | 看 pet-ball.log 有没有新的 bubble <-；超过 3 分钟会自动超时 |
| 选择框是空的 | 会话列表没 dump 出来 | 等 20 秒再看；还不能就看 ~\.dsh\pet\sessions.json 的 items 长度 |
| 气泡全显示「未命名」 | 会话标题读不到 | pet-host.log 的 sessions dump: N 段（有标题 M，M 远小于 N 就是标题读不到（DSH 改了缓存格式） |

拿日志去问人时记得脱敏 —— 里面有你的会话标题和目录路径。

环境与依赖

| 项 | 值 |
| 平台 | 只能 Windows（package.json 里 os: ["win32"]） |
| 运行时 | 球是 PowerShell 5.1 + WPF 独立进程；宿主跑在 DSH 的 Node 里 |
| npm 依赖 | 零。dependencies 是空的 |
| Node | >=20（DSH 自带） |
| DSH | 验证过 0.2.0-rc.2。用的是内部接入点，版本差太多可能完全不显示 |
| 额外配置 | 不需要 |

它明确不做的

- 不会自己截屏。 只有你点按钮才截。
- 不会替你操作。 见上面。
- 不读网页 DOM、不带规则表、不需要浏览器调试端口（早期版本有，已移除）。
- 不联网。 除了把消息投给你自己的 DSH 会话，不往外发任何东西。

已知限制

- 只能 Windows。
- 多屏 + 不同缩放比没实测（开发机是单屏 150%）。缩放变化有处理，但是防御式写法。
- 透明窗口的命中：透明像素会穿透到下层。好处是球周围能点穿，代价是"鼠标只在画了东西的地方算进入" —— 所以菜单按钮放在角色身上，MouseLeave 有 0.9 秒宽限期。
- 宿主重启后要重新起球（球是宿主拉起来的；宿主没了球还在，但点了没反应）。

给 AI 代理（帮人装的时候看这节）

这一节是给代装 AI 的。人类读者可以跳过。

硬约束

1. 不要自己重启 DSH。 如果你就跑在 DSH 里，重启会杀掉你自己的会话。让用户来。
2. 每一步都要验证，别假设成功。
3. dsh plugin add 在 DSH 运行时会 EPERM，用 tools/install.ps1。

步骤

0. 环境 $env:OS # 必须含 Windows Test-Path "$env:USERPROFILE\.dsh" # 必须 True
node -v # 必须 >= v20

1. 拿包
git clone https://github.com/HeiBai-king/dsh-pet.git "$env:USERPROFILE\dsh-pet"
(Get-Content "$env:USERPROFILE\dsh-pet\package.json" -Raw | ConvertFrom-Json).name # 必须是 dsh-pet

2. 装 powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\dsh-pet\tools\install.ps1" 期望最后几行里有：建好联接 / profile package.json 已更新

3. 单元自检（不需要 DSH）
node "$env:USERPROFILE\dsh-pet\tools\selfcheck.mjs"
期望最后一行：通过 29 项，失败 0 项

4. 告诉用户重启 DSH，然后停下来等他回来

5. 重启后验证 Select-String -Path "$env:USERPROFILE\.dsh\pet\pet-host.log" -Pattern "自检：接入点正常" | Select-Object -Last 1 期望：自检：接入点正常（服务=就绪，注入行 pushed=N reused=M），N > 0

(Get-Content "$env:USERPROFILE\.dsh\pet\sessions.json" -Raw | ConvertFrom-Json).items.Count
期望：> 0

6. 让用户看右下角有没有鲸鱼小圆图标；有就教他：点胶囊 → 菜单「选择会话…」选一段 → 「截当前屏幕问会话」

排查顺序

pet-host.log 的自检行 → ball-start spawned / ball exit code= → ask.request seen
→ pet-ball.log 的 bubble <-。这四层依次对应：加载 / 起球 / 投递 / 回显。

兼容性（升级 DSH 后先看）

用的是 DSH 的内部接入点，不是稳定 API。启动 60 秒后宿主会往 pet-host.log 打一行自检：

| 依赖点 | 断了会怎样 |
| webserver/index-inject 表 | 胶囊不出现（但球会被自动拉起来，功能不受影响） |
| webServer.tapIndex | web 形态不注入 |
| 服务名 webServer / agents / sessionController / sessionQuery | 插件起不来 / 选不了会话 |
| 胶囊 5 秒后才出现 | 正常 —— 注入脚本会先等 5 秒看有没有客户端接管，然后自己挂上 |
| agent.followup + createUserMessage | 点了没反应，日志写"拿不到可投递的 agent" |
| 会话缓存格式 session_projcache | 选择框标题变成"未命名" |

设计上每处都 try/catch，缺什么降级，不崩。

几个踩过的坑（改代码前先看）

1. 别给球的 spawn 加 detached: true —— WPF ShowDialog() 会立刻返回，球 200ms 内正常退出（exit 0、零报错）。
2. SetWindowRgn 是多余的 —— AllowsTransparency 窗口本来就逐像素穿透，裁区域反而硬边+闪烁。
3. 用了 region 后光标移出区域收不到 WM_MOUSEMOVE —— 球的拖动是「16ms 轮询 + GetAsyncKeyState」。
4. 别用 taskkill /PID（不带 /F）关球 —— 关不掉。球用的是停信号文件 stop.flag。
5. 位置持久化不能只挂关闭事件 —— 有强杀路径。球每 3 秒落盘一次。
6. Remove-Item 删 Junction 在 PS 5.1 会抛 NullReferenceException —— 用 [System.IO.Directory]::Delete($p, $false)。
7. 解析 pet-shot.ps1 的输出别写 [^:]+ —— 路径盘符自带冒号，会"截图成功却判失败"。
8. 含中文的 .ps1 必须 UTF-8 BOM，否则 PS 5.1 按 GBK 解码 → 语法崩。
9. PowerShell 变量名大小写不敏感 + [string] 参数强制转换 —— 别把控件叫 $hint 又给 [string]$Hint 赋值。
10. foreach 里创建的回调用不了循环变量 —— 那是同一个变量，全指向最后一次。用 $btn.Tag。
11. WPF TextBox 会先吃掉 Enter —— 用 PreviewKeyDown。

来源说明与免责

说清楚这插件是怎么来的：

- 角色形象是社区的「鲸鱼娘」，不是某个人的独占作品；仓库里的 assets/whale.png 取自社区流传的素材，非本仓库原创。
- 外观与交互风格（右下角小图标 + 可叫出的桌面角色 + 气泡）和 DSH 社区里流行的「余额挂件」那类挂件相似 —— 这是常见形态，风格相似不构成侵权。
代码是本仓库独立写的，没有内嵌、复制或反编译对方的任何代码或资源。
- 本项目是非商业的个人作品，未从分发中获利。

如果权利人觉得哪里不妥：请在仓库 Issues 说一声，会立刻改或下架，不需要走任何流程。

风险自负：插件会截取整块屏幕，并作为附件发给你自己指定的 DSH 会话；落到哪台服务器、哪个模型取决于你自己的 DSH 配置。

许可

代码：MIT（见 LICENSE）。
assets/whale.png 不在 MIT 覆盖范围内 —— 那是社区素材，非本仓库原创。