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 设置 → 桌宠参谋）：

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

设置页里有什么

「视觉模型 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 这类"自动识图包装"——那类包装靠让模型发起识图工具调用来实现，
插件直接把图塞给它，模型会把工具调用标记当正文吐出来（气泡里就出现"代码"）。

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

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

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。

验证状态（诚实版）

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

市场（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