鲸鱼娘游戏陪玩 bigk5780/dsh

dsh-game-pet 🎮🐾

打游戏时的桌宠参谋：你玩游戏的时候它自动开口——不用点任何东西，不用每次丢截图。

它在后台每几秒看一眼「前台窗口是不是游戏」，是的话就按节奏：

自动截屏（只截游戏窗口 / 可按需截整屏） → 第 1 步：识图 = 只抽【这是哪款游戏 + 现下关键局势】，不做画面描述 → 第 2 步：结合「这款游戏该怎么打」出一句建议（活泼小鲸鱼娘口吻，不念屏幕） → 透明置顶小窗里的桌宠弹气泡说出来

切走游戏（或关掉开关）就立刻停手：不再截屏、不再调模型。

为什么识图和出话要拆两步：一开始合成一次调用，模型就把界面逐项翻译给用户听（「画面里有血条和敌人」）——那不是建议，是念屏幕。拆开之后第一步只产出结构化线索（游戏名 + 玩家状态 / 对面状态 / 眼前目标 / 可用手段），第二步才有空间去「按这款游戏该怎么打」说话。

它长什么样

复用 dsh-pet 的动画素材（同一批透明 .webm），只住在一个独立透明置顶小窗里：

- 窗子永远在最上层、跳过任务栏，游戏窗口化 / 无边框时能盖在游戏上面
- 只有桌宠身体那一块能交互，其余透明像素点击穿透到下层应用
- 按住桌宠就能拖：按屏幕坐标挪窗，不依赖 app-region / 焦点——置顶窗是 focusable: false， -webkit-app-region: drag 实测按上去没反应，所以走「渲染层报指针位移 → 宿主 screen.getCursorScreenPoint() 挪窗」。
拖完位置自动记住，下次还放那儿
- 气泡停留 14 秒；失败原因用小字直说，不装没事
- 没有游戏名小字标题（原本那枚徽章已去掉）
- 网页里没有任何浮层：shell.overlay 不再注册，DSH 页面里不会再多出一个小人和气泡，只留设置页。浮层那份实现还在 client.js 里（Companion / PetSprite），要恢复就把那三行注释放开

宠物形象不依赖 dsh-pet

本插件自带 10 段游戏陪聊常用的透明动画（assets/webm/，约 4.4 MB，取自 dsh-pet，素材许可：开源可用、禁止商用）。
素材回落链是：

本插件自带 assets/webm/<名>.webm → dsh-pet 的 /thumb/main/<名>.webm（用它的自定义动画时才走到这） → 本插件自带的「待机呼吸休闲」 → dsh-pet 的待机 → 占位块（气泡照常说话）

为什么自带：早先完全依赖 dsh-pet 的路由，它一旦被停用/卸载，/dsh-pet-7340/thumb/... 整条路由就没了——表现是「只剩一个气泡、小人不见了」。自带之后 dsh-pet 变成可选。

全屏独占游戏里任何窗口都盖不上去（系统限制，与浮层无关）；游戏用窗口化 / 无边框窗口化就能看到。

安装

--profile 填你实际在用的那个：桌面应用 → desktop；dsh web → web
dsh plugin --profile desktop add dsh-game-pet

装完重启桌面应用（dsh web 用户重启 dsh web）才生效——宿主加载插件是启动期行为。

本插件自带组合补丁（dsh.bundle.patch），所以 add 会自动完成「挂载插件行 + 注册浏览器半侧」，不需要手改任何文件。装好后去 DSH 设置 → 桌宠参谋 配一下识图（见下面「⚙️ 配置」）。

首次配置要做的事

1. 打开 DSH 设置 → 桌宠参谋 → 视觉模型 API
2. 填接口地址与模型名。任何 OpenAI 兼容（或 Anthropic 风格）的视觉服务都行，例如本地 Ollama：
- 地址 http://127.0.0.1:11434/v1，模型 qwen2.5vl
3. 需要鉴权的服务填 API Key，然后点 测一下通不通 —— 它会真发一张测试图，能读懂才算通
4. 什么都不填也能跑：会自动退到免 Key 的匿名视觉模型兜底（有限速，建议自备）

卸载

dsh plugin --profile desktop remove dsh-game-pet

本机开发（源码直接跑）

把源码同步进 profile 的 node_modules（改完代码需要重启应用才加载新模块） Copy-Item '<你的源码目录>\dsh-game-pet\' "$env:DSH_HOME\profiles\desktop\node_modules\dsh-game-pet" -Recurse -Force

也可用官方支持的「路径行」挂载：在 profile 的 cordis.patch.yml 里 insert 一行 name: '<绝对路径>/dsh-game-pet/index.js'，不用碰 node_modules。
⚠️ 但不要在 profile patch 里重复 insert 同一个 id——包内补丁已经插了一行，两行同 id 会让宿主整行都不挂（这个坑真踩过）。

配置

配置有两种改法，推荐用设置页（DSH 设置 → 桌宠参谋）：

| 改法 | 落在哪 | 生效 |
| 设置页图形化 | $DSH_HOME/dsh-game-pet.json | 保存即生效（已写盘，重启后仍在）；只有「浮层形态」与小窗位置要重启 |
| 手写 cordis.patch.yml 的 config | profile 的 patch（组合层） | 要重启应用 |

两者关系是叠加：patch 里的 config 是基础（出厂/部署默认），设置页改的覆盖在上面。
所以手写注释不会被设置页覆盖，设置页改的也不会去动你的 patch。

设置页里有什么

| 卡片 | 内容 |
| 开关与时机 | 启用 / 多久说一句 / 开场预热 / 最短间隔 / 检测频率 / 单次超时 |
| 哪些游戏算 | 白名单（一行一个）/ 全屏才算 / 忽略最小化 / 截图范围 |
| 浮层（它住在哪儿） | 独立置顶小窗 ⇄ 只画在网页 / 小窗 X、Y（留空=右下角，拖一下更省事） |
| 模型 | 出话 provider/model、识图 provider/model + 实时识图状态与候选列表 |
| 视觉模型 API（自己填一个） | 接口地址 / 模型名 / API Key / 协议（OpenAI 兼容 · Anthropic 风格）/ 最大输出 + 测一下通不通 |
| 它怎么说话 | 人设 / 上下文句数 / 截图复用时长 |
| 底部按钮 | 立刻试一轮（真跑一遍截屏→识图→出话）、只看当前前台窗口、刷新识图状态 |

「视觉模型 API」是最省事的一条出路：DSH 的模型注册表里没有可用的识图模型时（本机实测就是空的：
ctx.llm.listProviders() 返回 []，vision-http 只是 dsh 的"可配置 provider"，并没注册成 LLM adapter），
直接填一个 OpenAI 兼容（或 Anthropic 风格）的视觉服务即可——本地 Ollama / LM Studio、自建网关、云端 API 都行。填了并启用后，识图和出话两步都走它（一个 Key 全包，不再依赖 DSH 会话里的模型；出话失败会自动回落会话模型）。

本机现在用的就是这一条（阿里云百炼 MaaS 兼容模式，实测可用）：

"visionApi": {
"enabled": true,
"baseURL": "https://<你的工作空间>.cn-beijing.maas.aliyuncs.com/compatible-mode/v1", "model": "qwen3.8-flash", // 同工作空间里 qwen3.8-max / qwen3.8-27b / kimi-k3 也能看图 "apiKey": "sk-ws-...", "format": "openai", "maxTokens": 1024 }

选模型的经验：qwen-image- 是画图的不是看图的；qwen-vl-max 在这类工作空间里可能不存在（404）。
最稳的办法是在设置页填完地址与 Key，点「测一下通不通」——它会真发一张测试图，能读懂才算通。
注意：有些模型（实测 glm 系列）会回"我没有看到图片，请重新上传"来敷衍，插件把这种也判为失败并继续试下一个候选。

什么都没填时也有免配置兜底：直接打 dsh-vision-router 文档里写明的免费匿名视觉模型（OVHcloud Qwen3.5-397B-A17B，免注册免 Key）。实测能真的读懂截图（"白色背景上，左侧有一个红色圆形…"），但有速率限制（每 IP 每模型约 2 次/分钟）——想让它在 45 秒一句的节奏下稳，最好还是自备一个。

- 接口地址：不带结尾斜杠。OpenAI 兼容会自动补 /chat/completions，Anthropic 风格补 /v1/messages
- API Key：只存在本机 $DSH_HOME/dsh-game-pet.json（明文），设置页永不回显明文，只显示"已保存"；不改就留空（内部用哨兵值表示沿用）
- 测一下通不通：先发一张 1×1 的测试图（成本≈0）真看一眼；服务不认图就退化成纯文本 ping，至少能确认地址与鉴权对不对

⚙️ 配置（cordis.patch.yml 的 config）

- insert:
- id: dsh-game-pet
name: 'dsh-game-pet'
config:
enabled: true # 总开关
games: [] # 游戏白名单：进程名或窗口标题关键字；空数组 = 任何前台窗口都算
requireFullscreen: false
ignoreMinimized: true
checkIntervalMs: 5000 # 多久看一眼前台窗口（很便宜） warmupMs: 15000 # 刚开游戏先看一会儿再开口 intervalSec: 45 # 多久说一句 ← 这就是花钱的节奏 minGapMs: 8000 snapshotTtlMs: 0 # 0 = 每句都重新截屏；>0 则这段时间内复用上一张 captureFullScreen: false # false = 只截游戏窗口（更省 token） timeoutMs: 45000 historyLimit: 6 # 最近几句话当上下文 provider: '' # 留空 = 跟随"当前对话用的模型" model: '' visionProvider: '' # 识图那一步用谁；留空 = 自动探测（见下） visionModel: '' overlay: window # window = 独立透明置顶小窗（可拖）；browser = 只画在网页里 windowX: null # 小窗位置；留 null 会自动放右下角，拖过一次就记住了 windowY: null persona: '' # 留空 = 内置人设（桌宠兼游戏搭子）

games 写进程名最省事（EldenRing、GenshinImpact；带不带 .exe、大小写都行），也可以写窗口标题关键字（原神、艾尔登）。留空就是"只要前台是全屏/窗口应用就说"，看视频写文档时也会插话——想要安静就把白名单填上。

visionProvider / visionModel 留空时的自动探测顺序：① 设置页里启用过的自定义视觉 API（最先）， ② dsh-vision-router 的直连视觉路由 vision-http（本机探测不到，见上）， ③ LLM 注册表里声明支持 image 输入的模型， ④ 两者都没有时退到免配置的免费匿名视觉模型（OVHcloud，免 Key，有速率限制）。
⚠️ 不要填 deepseek-vision 这类"自动识图包装"——那类包装靠让模型发起识图工具调用来实现，插件直接把图塞给它，模型会把工具调用标记当正文吐出来（气泡里就出现"代码"）。

运行期接口（同一台机器、需要应用的会话凭证）

| 方法 | 路径 | 作用 |
| GET | /dsh-game-pet-7341/state | 前端轮询的状态（presence / advice / lastError） |
| GET | /dsh-game-pet-7341/probe | 只看一眼前台窗口，不截屏不调模型（排查「为什么没认出游戏」） |
| POST | /dsh-game-pet-7341/once | 立刻跑一轮，返回这一轮的结论（不看间隔） |
| GET/POST | /dsh-game-pet-7341/config | 读 / 改运行期配置（GET 里 apiKey 只回「有没有」） |
| GET | /dsh-game-pet-7341/vision | 识图自检：自定义 API 状态 + 注册表候选 + 探测到的 provider |
| POST | /dsh-game-pet-7341/vision/test | 拿草稿参数测自定义视觉 API 通不通（先测再存） |
| GET | /dsh-game-pet-7341/overlay | 置顶小窗加载的那一页（纯 DOM，无依赖） |
| POST | /dsh-game-pet-7341/position | 小窗拖动后回传坐标（宿主落盘记住） |
| POST | /dsh-game-pet-7341/ping | 小窗存活探测：宿主没了它自己退出，不留孤儿窗 |
| GET | /dsh-game-pet-7341/anim/<名>.webm | 本插件自带动画（没放素材就 404，前端回落到 dsh-pet） |

它是怎么实现的（给维护者）

index.js 宿主半侧入口（name / inject / apply），并写加载留痕日志 src/host/plugin.mjs 循环与路由：探窗口 → 到点 → 截屏 → 出建议 → 写状态；拉起置顶小窗 src/host/harness-loader.mjs 运行时解析 DSH 自带的包（插件不在安装目录里，见下） src/host/collect.mjs Windows helper 的调用层（探前台窗口 / 截屏） src/host/helper-win.ps1 纯 ASCII 的 PowerShell + C#：DPI 感知的 CopyFromScreen src/host/advise.mjs 两步：识图转文字 → 出话；外加输出消毒 src/host/desktop-window.mjs 置顶小窗进程的拉起 / 重拉 / 停止 runtime/overlay/main.mjs Electron 主进程：透明置顶窗 + 点击穿透 + 位置回传 runtime/overlay/overlay.html 小窗里渲染的那一页（轮询 /state + 播动画 + 气泡） runtime/overlay/preload.cjs 小窗的桥：只暴露 setInteractive / setPosition / quit src/host/config.mjs 配置形状、默认值、白名单匹配 src/host/state.mjs 给前端的 {counter,data} 状态面 src/shared/agent.mjs 心情 → 动画名（纯函数） client.js 浏览器半侧：注册进 shell.overlay（overlay: browser 时用）

几个刻意的选择：

- 状态靠 1 秒轮询（/state 的 {counter,data} 叶子），不用 websocket：和 dsh-pet 同一套协议，少一个能坏的地方；没在玩游戏时退到 3 秒。
- 一次请求同时要「描述」和「台词」：{"screen": "...", "say": "..."}。描述进内存当下一句的上下文（所以它能接着上一幕讲），台词直接进气泡。一句话 = 一次调用，成本可控。
- 截图走附件服务（ctx.attachments.saveImage → {type:'image', attachment} block），和 dsh-vision-router 一模一样；attachments 缺席时退化成纯文本（仍会说话，只是没看图）。
- PowerShell 源保持纯 ASCII：Windows PowerShell 5.1 读无 BOM 的 .ps1 用 OEM 代码页，写中文进源码必然乱码。所以中文只作为 UTF-8 文件数据回传（-Out 参数），不走 stdout。
- Add-Type 的临时目录强制 ASCII：CodeDom 编译在 TEMP 含非 ASCII 时会失败。
- 模型选择跟随当前对话：留空就用 agentDefaultModel.currentSelection()，而本机当前是 deepseek-vision / deepseek-flash——注意这只是「出话」那一步用的；识图那一步单独探测（见下一条）。
- 服务方法不能摘下来再调（踩过的坑）：ctx.llm.listProviders() / listModels(provider) 是挂在服务对象上的方法，内部用 this。写成 const f = ctx.llm.listProviders; f() 会丢 this，异常又被 catch 吞掉 → 表现为「没找到可用的识图模型」，而 vision-http 其实好好地在注册表里。
所以统一走 safeProviders(llmService) / safeModels(llmService, provider)。
- 不能静态 import '@deepseek-ai/dsh-llm'（踩过的坑）：插件装在 profile 的 node_modules，而 DSH 的包在安装目录（Desktop 是 app.asar 内部），Node 从插件目录往上走永远找不到。
静态 import 的后果是整个插件静默失效（路由一条都没注册、页面什么都不出现）。
所以走 harness-loader.mjs：先试裸解析（与 DSH 同装一处时最快），再探 process.resourcesPath / process.execPath 推导出的安装目录（…/app.asar）等位置，定位到文件后 import(fileURL)——Electron 的 asar 路径可以直接作为 ESM import，实测通过。
- 包内 patch 与 profile 那行不能同时 insert 同一个 id（也踩过）：本包的 cordis.patch.yml 因此有意留空，行只由 profile 的 patch 提供。
两边都插的话配置树里会出现两条同 id 的 entry，宿主整行都不挂——和静态 import 那个坑一样，表现是彻底静默。想把「挂载」挪进包内（就不再需要 profile 里那一行）时，必须二选一。
- 配置是 apply(ctx, config) 的第二个参数（也踩过）：Cordis 的 ctx 是个严格代理，没在 inject 里声明的属性一律抛 cannot get property "X" without inject。
所以不能写 ctx.config——那会把整个插件挂掉。官方契约见 cordis-plugin-development/references/host-plugin.md：export function apply(ctx, config) {}。
- 加载留痕：index.js 在模块加载 / apply 进入 / apply 完成（或抛错）时各写一行 $DSH_HOME/dsh-game-pet.log；识图失败时还会多打一行 vision probe: providers=... candidates=...。
插件「到底有没有被加载 / 为什么没生效 / 识图为什么没找到」是最难判断的几件事，这几行日志一加就能定位；别删。

已知边界

- 只在 Windows 上工作（helper 是 PowerShell + user32/gdi32）。
- 全屏独占游戏里任何窗口都盖不上去（系统限制，不是这个插件能绕过的）。
- 每句话要两次模型调用（识图 + 出话）；intervalSec 调小会线性放大消耗。用自备视觉 API 时按你自己的价目计费。
- 截图是整窗口（或整屏）PNG，约 1.5–3 MB；默认只截游戏窗口（captureFullScreen: false）。
- 自带 10 段动画（assets/webm/，约 4.4 MB）。想换形象就替换这里的 .webm，或放进 dsh-pet 的 $DSH_HOME/dsh-pet/main-animation/webm/（回落链见上）。
- 置顶小窗用 $DSH_HOME/electron/electron.exe（DSH 里 dsh-pet 下载的那份 Electron）。
找不到就只告警、只留设置页；可用环境变量 DSH_GAME_PET_ELECTRON 指定别的 Electron。
小窗日志在 $DSH_HOME/dsh-game-pet-window.log。

验证状态（诚实版）

| 环节 | 怎么验的 | 结果 |
| 前台窗口识别 + 中文标题 | 真跑 helper | ✅ 拿到 桌宠自动游戏陪聊插件 — DeepSeek Harness |
| 窗口/整屏截屏 | 真截图 | ✅ 窗口 1.6 MB / 整屏 3.0 MB PNG |
| 自动循环、白名单、warmup/间隔 | 假 ctx 跑真插件 + 真桌面 | ✅ 自动触发、写状态、切走即停 |
| 两步链路（识图→出话） | 假 LLM 记录两次请求 | ✅ 第 1 次 contentTypes: image,text 走 vision-http；第 2 次纯文字 |
| 输出消毒（工具调用标记 / JSON 外壳 / 代码块 / 空） | 拿线上抓到的真实脏输出做用例 | ✅ 脏的丢掉、JSON 拆出正文、正常话照过 |
| HTTP 路由（含 overlay/position/ping/vision/config） | 直接调已注册的 handler | ✅ 全部 200，overlay 页面含命中区与拖拽区 |
| 设置页 UI | stub react 渲染 + 数控件 | ✅ 22 输入 / 5 开关 / 2 文本域 / 2 下拉 / 4 按钮；白名单回填、识图徽章、视觉 API 卡片都在 |
| 视觉 API 出站请求 | 打到本地 stub 服务 | ✅ OpenAI 风格 POST /v1/chat/completions + Bearer；Anthropic 风格 POST /v1/messages + x-api-key；图片是 data URL |
| 免费匿名兜底 | 真打 OVH 端点 + 自造测试图 | ✅ 真的读懂了（"白底、左侧红色圆形、下方 HELLO 123、右侧蓝色长方形"）；同时确认有速率限制 |
| 阿里云 MaaS 实测（qwen3.8-flash） | 真截图 → 真 API → 真出话 | ✅ "画面为 DeepSeek Harness 界面…含 11 轮 621 步、缓存命中 99.8%" → 台词"成功啦，11轮621步还缓存九成八，快接着看输出吧。" |
| 该工作空间的视觉模型挑选 | 列 176 个模型逐个打图试 | ✅ 能看图：qwen3.8-flash / qwen3.8-max / qwen3.8-27b / kimi-k3（qwen-image- 是画图的；qwen-vl-max 不存在） |
| 识图只抽"游戏+局势" | 两张自造游戏图 | ✅ 输出 泰拉瑞亚… HP 70/300 / 骷髅战士Lv.12蓄力 / 任务向东340m，无美术/布局描述 |
| 建议贴游戏玩法 + 鲸鱼娘语气 | 同上，两种类型交叉验证 | ✅ 动作游戏→才70血还跟蓄力骷髅贴脸？本鲸叫你快去矿洞卡它啦！(๑•̀ㅂ•́)و✧；种田游戏→防风草赶紧浇完啦！体力剩这点小心晕倒掉钱哦。 |
| 拖拽（置顶窗） | 真 Electron 窗 + 合成鼠标事件 | ✅ start→move→end 完整；点击穿透下 mousedown 仍可达；修掉"窗口跟手导致 mouseleave 打断拖拽"的抖动 |
| 响应提取规则 | 本地 stub 覆盖三种形态 | ✅ choices[].message.content / Anthropic content[] / 推理模型的 reasoning 字段 |
| Key 处理 | 假 ctx POST /config | ✅ 响应里只有 hasApiKey（无明文）；哨兵 __KEEP__ 不会覆盖已存 Key |
| 配置落盘 | 假 ctx POST /config 后查文件 | ✅ 写进 $DSH_HOME/dsh-game-pet.json，非法字段被丢弃 |
| 视觉 API 自检失败路径 | 打不通的地址 | ✅ 返回结构化失败 带图失败：… 纯文本失败：…，不假装成功 |
| 置顶小窗本体 | 起真 Electron 窗 + 枚举系统窗口 | ✅ 可见、bounds=900,300,340x360、存活回传正常 |
| 真实游戏识别 | 真玩着泰拉瑞亚（全屏）跑一遍 | ✅ Terraria / 泰拉瑞亚第3部：向导归来 / fullscreen: true |
| 从 profile 位置加载整个插件 | 复刻宿主解析环境 import | ✅ 修掉静态 import 坑后通了 |
| 自带动画（不再依赖 dsh-pet） | 真打 /anim/待机呼吸休闲.webm | ✅ 200 + video/webm 441437B；越界名 400 拒绝 |
| 小窗真的渲染出宠物 | 真 Electron 窗 + 截图 + 读图确认 | ✅ 气泡文字正确、下方有蓝发女仆小人（assets/screenshot-1.png 就是这张） |
| 真实环境识图 + 出话 | 应用内 GET /vision、POST /once | ✅ usable: true；出话为鲸鱼娘口吻的游戏建议 |
| 发布前闸门 | tools/check-publishable.mjs | ✅ 33 个文件、无明文凭据、无本机配置、元数据齐全 |

上架到插件市场（给维护者/投稿用）

市场（dsh-market）只收录 awesome-dsh-plugin 精选列表里的来源。要上架，需要两步：

1. 把代码推到公开仓库：bigk5780/dsh（已配置为 package.json 的 repository）。仓库需创建满 1 天、并带有 dsh-plugin topic。
2. 去精选列表提一个 PR，只加一个文件 data/plugins/bigk5780__dsh.yml：

url: https://github.com/bigk5780/dsh
name: bigk5780/dsh
category: fun
description:
en: 'Watches which game you are playing, reads the on-screen situation with a vision model, and has a whale-girl pet pop up short in-game advice in a transparent always-on-top window — no clicks needed.' zh: '打游戏时自动开口的小鲸鱼娘：认出你在玩哪款游戏，结合画面局势给一句贴这款游戏的建议，住在一个透明置顶小窗里，不需要任何点击。'

几条容易踩的规则（摘自官方 contributing.md）：

- 只有 description.en 必填；zh 写不了可以让维护者补
- 描述里含「冒号 + 空格」必须加引号，否则 YAML 解析失败
- 不要在 yml 里手写 npm: 字段（会被校验拒绝；npm 映射自动采集）
- 一个 PR 最多 3 条；描述必须与代码一致（评审会对着源码核，夸大是主要被打回原因）
- package.json 必须声明 dsh.bundle（只写 dsh.client 会被拒）——本插件已声明
- 官方 @deepseek-ai/ 包用 peerDependencies（本插件已按此声明），且 peer 范围要带显式预发布分支，否则会静默排除 harness 的预发布版本
- 发布到 npm 是可选的（只影响市场是否显示下载量）；发的话 repository 字段必须指回该仓库
- 截图：仓库根放 screenshots.json 指向 1–8 张图（本插件已放，指向 assets/screenshot-1.png）

安装方式（未发布 npm 时从 GitHub 装）：

dsh plugin --profile desktop add github:bigk5780/dsh