前言¶
在 DeepSeek Harness（DSH）里做「能看屏幕、能点鼠标」的智能体，常见做法是写脚本或接模拟器，但 KARDS 这类桌面游戏需要的是本机真实输入，而不是假设备。下面介绍的 dsh-kards-pilot（包名 @local/kards-pilot）由社区维护者 acae2w3 发布，归类为模型推理相关插件；它给当前会话挂一套 Windows 侧工具，并通过悬浮球一键把智能体拉进对局流程。
这是什么¶
KARDS 悬浮球手柄 的定位是：给 DSH 装一个悬浮球，点一下即可唤醒当前会话的智能体进入 KARDS 对局；智能体可以截屏、移动真实鼠标、点击与按键，操作的是这台电脑上的桌面，而不是游戏内模拟器。
插件在 GitHub 仓库 acae2w3/dsh-kards-pilot 开源，许可证为 MIT（见 package.json），当前资料中的版本号为 0.1.0。社区目录页：skillhub.cn 插件页。DSH 生态强调「一切皆插件」；SkillHub 等目录为独立社区站点，与 DeepSeek / 幻方无官方从属关系。
智能体获得的工具¶
Host 侧在 index.js 注册三个工具，底层由 PowerShell 助手 helper/kards-helper.ps1 通过 JSON 行协议完成截屏与输入。
| 工具 | 作用 |
|---|---|
kards_windows |
列出窗口（标题、pid、位置尺寸、是否前台、是否最小化），以及虚拟屏幕尺寸与光标位置；用于先定位 KARDS 窗口。 |
kards_screen |
整屏或指定窗口截屏（指定窗口时会先将其提到前台），以图片返回，并给出「图片像素 ↔ 屏幕像素」的换算关系。 |
kards_act |
真实移动鼠标并执行 click / double_click / right_click / drag / move / wheel / key / focus / wait；默认每次动作后自动附一张新截图，便于智能体确认是否生效。 |
坐标约定：kards_act 的 x/y 默认对应最近一次 kards_screen 返回图片的像素坐标，由插件换算为屏幕坐标；若传 space:"screen" 则直接使用桌面像素。流程上是「看图 → 点图上位置」，无需自行算 DPI 缩放。
截图经 ctx.attachments.saveImage 持久化为附件后再作为图片块返回给模型。
两处悬浮球¶
桌面级浮球（对局时优先用这个）¶
脚本路径为 helper/orb.ps1，独立 WinForms 进程：置顶、无边框、圆形，默认贴在屏幕右缘约三分之一高度，可拖动；位置保存在 ~/.dsh/kards-orb/position.json。它绘制在其他窗口之上，全屏打 KARDS 时仍可见、可点。
- 单击：唤醒或结束对局（插件通过
~/.dsh/kards-orb/下的state.json与command.json通信）。 - 右键：唤醒/结束、切到 Harness 窗口、收起、退出。
- 状态颜色：蓝=空闲，黄=唤醒中，绿=对局中（带脉冲环），红=出错。
- 单实例：插件启动时会探测，已有浮球则不重复启动。
- 若宿主超过 12 秒未更新状态文件，单击会退化为将 Harness 窗口提到前台。
该脚本须保存为 UTF-8 with BOM，否则 Windows PowerShell 5.1 可能因中文解析失败。
页面内浮球¶
client.js 注册在 shell.overlay，位于 Harness 窗口右下角、可拖动。全屏游戏挡住 Harness 时无法点击，因此对局场景应使用桌面浮球。
安装与生效¶
在 Harness 内通过 plugin_manager 安装本地 bundle，官方 README 给出的方式为：
# 在 Harness 里用 plugin_manager：
# action: install_bundle, target: <本目录绝对路径>
将 <本目录绝对路径> 换成本机克隆或解压后的插件根目录绝对路径。请勿凭仓库名自行拼接未在文档中出现的安装命令。
客户端与 Host 模块在进程启动时快照：修改 client.js 或 index.js 后须重启 Harness 才生效，仅刷新页面不够。桌面浮球在 Host 激活时启动，同样随重启更新。
典型用法（流程）¶
- 安装 bundle 并重启 Harness，确认桌面浮球或页面浮球可用。
- 在 KARDS 中进入可对局状态；单击浮球，插件通过
sessionController.prompt唤醒当前会话。 - 智能体先调用
kards_windows找到 KARDS 窗口，再用kards_screen获取局面截图。 - 根据截图与提示词中的规则，用
kards_act在图片坐标系下点击、拖牌或按键；每次动作后的附带回图用于校验。 - 对局结束可通过浮球或会话内指令结束唤醒状态。
具体提示词与牌局规则由使用者自行编写；插件不提供除视觉与输入以外的「读内存」类通道。
适用场景与注意¶
适合：已在 DSH 中开发 Windows 端智能体、希望用真实键鼠玩 KARDS、并愿意维护对局提示词与截图决策链路的开发者。
环境与权限：
- 实现依赖 Windows（PowerShell 助手、WinForms 浮球、GDI+ 截屏等）；资料未描述 Linux/macOS 支持。
- 插件以当前 DSH 进程权限操作真实桌面；安装前应阅读源码与 MIT 许可证，确认可接受键鼠被临时接管的行为。
- 点击期间请勿与智能体同时移动鼠标；全屏时若页面浮球不可用，先用桌面浮球或切回 Harness，必要时浮球会把游戏窗口重新提到前台。
- 判断完全来自截图所见与提示词，无其他取巧数据通道。
结尾¶
dsh-kards-pilot 把「悬浮球触发会话」与「Windows 真实视触输入」收成一个小 bundle，适合在 DSH 里做 KARDS 对局实验。更多信息见 社区目录页 与 GitHub 仓库。
