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}}，改成点胶囊叫

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

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

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

④ 气泡上会显示什么

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

第一次用，就三步

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

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

安装

前置条件

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

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。没有它就是全默认。

也支持环境变量（优先级高于 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"

出问题怎么办

先看日志，再看这张表：

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

环境与依赖

它明确不做的

• 不会自己截屏。 只有你点按钮才截。
• 不会替你操作。 见上面。
• 不读网页 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 打一行自检：

设计上每处都 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 覆盖范围内 —— 那是社区素材，非本仓库原创。