游戏操控 hezhaochao/dsh-game-control

dsh-game-control 🎮 游戏操控工具集

一个 DeepSeek Harness（DSH）插件：给智能体加上操控游戏的手——扫描码级键盘输入（长按键移动）、鼠标相对位移（控视角）、带时序的连招序列、屏幕截图与窗口管理。全部通过 MCP 工具暴露，装好即用，零额外依赖。

这是给谁用的

- 让 AI 玩/测试单机游戏：走位、点菜单、开技能、读屏决策
- 给游戏脚本/攻略测试做自动化：定时按序列按键、模拟长按、控制镜头
- 任何「游戏只认原始输入」的场景——普通 UI 自动化（SendMessage/SendKeys）在游戏里大多无效，本插件走 SendInput 扫描码，这是 DirectInput/多数游戏引擎实际读取的层

工具一览（装好后模型看到 mcp__gamectl__<名>）

| 工具 | 作用 | 游戏场景 |
| key | 扫描码按键，tap/down/up 三种模式 | 点技能、长按 W 走路（down…up） |
| mouse_move | 绝对移动（x,y）或相对位移（dx,dy） | 拖动镜头、甩视角、瞄准 |
| mouse_click | 左/右/中键，单击/双击/按住 | 攻击、开镜、拖拽物品 |
| mouse_wheel | 垂直/水平滚轮 | 切换武器、缩放地图 |
| sequence | 一条调用里按毫秒时序执行组合键序列 | 连招：w down → 200ms → shift+q → … |
| screenshot | 全屏/区域截图存 PNG，返回路径与尺寸 | 给视觉模型看画面再决策 |
| windows | 列出可见窗口（标题/pid/矩形） | 找到游戏窗口 |
| focus | 按 pid 或标题把窗口带到前台 | 开局聚焦游戏 |

按键名支持 a-z、0-9、f1-f12、方向键、space/enter/esc/tab/shift/ctrl/alt、 home/end/pgup/pgdn/insert/delete、小键盘、minus/equal/bracket_left/…、win。

安装

npm 渠道（推荐）
dsh plugin --profile <你的 profile> add dsh-game-control

或从 GitHub
dsh plugin --profile <你的 profile> add github:hezhaochao/dsh-game-control

或本地 link（克隆本仓库后开发调试用）
dsh plugin --profile <你的 profile> add link:"<本仓库绝对路径>"
link: 方式不会自动装 peer 依赖，需在 profile 目录手动补：
node <dsh 内置 pnpm 的 pnpm.cjs> add @deepseek-ai/dsh-mcp-client

安装后完全退出 DSH（含托盘）再重启。desktop 配置档请走桌面端插件面板。

卸载

dsh plugin --profile <你的 profile> remove dsh-game-control

典型用法（对话里直接说）

"聚焦标题带『Stellaris』的窗口，截个图看看现在什么局面，然后帮我点开左上角的舰队菜单"

"按住 W 三秒往前走，然后连招：q、等 300ms、e、等 200ms、右键"

智能体会自行组合 focus → screenshot → sequence 完成任务。
截图拿到的是 PNG 路径，配合视觉工具/模型读画面即可形成「看 → 想 → 打」的循环。

工作原理

DSH (cordis)
└─ dsh-game-control (mcp/dsh-plugin.mjs 适配器) └─ ctx.plugin(@deepseek-ai/dsh-mcp-client, { serverName: "gamectl", transport: "stdio", command: process.execPath + ELECTRON_RUN_AS_NODE=1,
args: [mcp/server.mjs] })
└─ MCP stdio 服务器（零依赖裸 JSON-RPC, 2024-11-05） └─ spawn powershell.exe -File scripts/gamectl.ps1（SendInput 后端）

- 键盘：SendInput + KEYEVENTF_SCANCODE（wVk=0），游戏读到的是硬件扫描码；导航键/Win 键自动加 KEYEVENTF_EXTENDEDKEY
- 鼠标：绝对移动走 MOUSEEVENTF_ABSOLUTE（归一化 0-65535），相对位移走裸 MOUSEEVENTF_MOVE（dx,dy 像素增量，镜头控制专用）
- 进程：启动即 SetProcessDPIAware()，所有坐标都是物理像素；后端 stdout 强制纯 ASCII（非 ASCII 转 \uXXXX），不受控制台编码影响
- 聚焦：AttachThreadInput 前台锁规避 + IsIconic 恢复 + 结果校验

兼容性

- 声明 engines.dsh: ">=0.2.0-rc.1 <0.3.0-0"，已在 v0.2.1-rc.3（当前最新版）上完成安装 / 配置树组合 / 卸载验证
- peer 依赖 @deepseek-ai/dsh-mcp-client >=0.1.0-rc.2 || >=0.2.0-rc.2，正常渠道安装时 pnpm 会自动装进配置档
- 需要 Windows 10/11 + PowerShell 5.1（系统自带），Node 由 DSH 内置运行时提供

安全与游戏道德（请务必读）

- 只用于单机游戏，或你有权自动化的场景。任何网游里使用输入自动化都可能违反用户协议并导致封号——本插件不提供、也不会提供任何反检测/反作弊规避能力
- 输入是真实系统级注入：sequence 有 30 秒硬上限、单键 hold 上限 5 秒、click hold 上限 10 秒，避免失控长按
- 聚焦/按键前请先手动保存工作；插件不知道你切了窗口，盲发按键会打进当前前台程序
- 部分游戏（尤其是带内核级反作弊或独占全屏的）可能忽略合成输入或拒绝被聚焦，属预期行为——改用窗口化/无边框模式通常可解

开发与测试

git clone https://github.com/hezhaochao/dsh-game-control.git
cd dsh-game-control
npm test # MCP 协议层：握手/工具清单/全链路（Windows 上含截图实拍）
npm run test:backend # 真实输入 E2E：鼠标往返归位、扫描码注入 choice.exe、窗口列表

E2E 的按键验证方式：spawn 一个等待按键的 choice.exe 控制台，聚焦后注入扫描码 b，choice 立即返回 B 即证明合成输入到达了真实程序（收不到则 20s 超时返回 A，测试失败）。

本地真机验证插件挂载：

dsh plugin --profile zz-test add link:"<本仓库绝对路径>"
dsh --profile zz-test --dump-config # 应能看到 id: mcp-game-control 条目

已知限制

- 相对位移的像素精度受系统指针加速影响，游戏内「转多少度」需要按游戏实测校准
- 独占全屏游戏可能拒绝被聚焦（返回 ok:false 与提示），建议无边框窗口
- 部分游戏使用原始输入驱动（Raw Input / 驱动级鼠标），SendInput 可能无效——这类游戏本插件不打算支持（也没有安全的方式支持）
- 多显示器下 screenshot 默认抓虚拟屏全图，region 用物理屏幕坐标

许可

MIT © hezhaochao