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

一个 DeepSeek Harness（DSH）插件： 给 agent 加上操控游戏的手——扫描码级键盘输入（长按键移动）、鼠标相对位移（控视角）、 带时序的连招序列、屏幕截图与窗口管理。全部通过 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 profile 请走桌面端插件面板。

卸载

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

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

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

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

agent 会自行组合 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 会自动装进 profile
• 需要 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