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