dsh-tool-keymouse
Windows 键鼠 + 截图 + 窗口自动化工具插件（DeepSeek Harness）。通过常驻 helper（bin/helper-x64.exe）走管道 + JSON 行协议调用 Win32 SendInput 模拟真实键盘/鼠标输入，用于桌面自动化：打开/唤起应用、登录、点击、输入、拖拽、滚动、截图观察、窗口定位/置顶。
helper 已 DPI-aware：GetSystemMetrics、截图、mouse_move 全部统一到物理像素（如 2560x1600）。模型给坐标 = 截图里看到的坐标 = 物理像素，无需缩放换算。
特性
- 键盘：
key_press / key_up / key_tap，字母数字、空格回车、F1-F12、方向键、Ctrl/Alt/Shift、Tab、Esc 等。
- 鼠标：
mouse_press（按住拖动）、mouse_move（绝对物理坐标）、mouse_roll（滚轮）。
- 截图：
screenshot 抓主屏保存 PNG，返回绝对路径与物理像素尺寸；看图能力取决于宿主环境（见「环境与能力边界」）。
- 窗口：
get_window / win_rect（查位置）、win_find（按进程名找窗口）、win_activate（唤起，含最小化/托盘）、win_minimize / win_restore / win_maximize、win_top / release_top（置顶）。
- 清理：
release_all 一键抬起所有按住项防卡键；release_top 取消所有置顶。
- 自带常驻
keymouse 说明书（runtime skill），模型通过 skill 工具读取使用规则。
工具清单（17）
| 工具 | 参数 | 说明 |
|---|
screenshot() | 无 | 截主屏 PNG，返回 path/width/height（物理像素） |
get_window() | 无 | 当前前台窗口 hwnd/title/process/pid/x/y/w/h |
win_rect(hwnd?) | hwnd? | 窗口位置与尺寸（缺省前台） |
win_find(process) | process | 按进程名找窗口（返回 hwnd/visible，false=托盘） |
win_activate(hwnd) | hwnd | 唤起/前置窗口，处理最小化+托盘 |
win_minimize(hwnd?) | hwnd? | 最小化 |
win_restore(hwnd?) | hwnd? | 还原 |
win_maximize(hwnd?) | hwnd? | 最大化 |
win_top(hwnd, on) | hwnd, on | 置顶/取消置顶 |
release_top() | 无 | 取消所有本插件置顶 |
key_tap(key) | key | 按下+立刻抬起 |
key_press(key) | key | 只按下（组合键用） |
key_up(key) | key | 抬起 |
mouse_press(button) | button | 只按下鼠标按钮 |
mouse_move(x,y) | x, y | 绝对移动（物理像素） |
mouse_roll(up, amount?) | up, amount? | 滚轮滚动 |
release_all() | 无 | 统一抬起全部按住项 |
典型组合：win_find('QQ') → win_activate(hwnd) 唤起窗口（不点图标）；key_press('ctrl') → key_tap('s') → release_all；mouse_press('left') → mouse_move(...) → release_all；screenshot() →（环境支持看图时）查看图像 → 再定位操作。
安装
本地目录方式（开发/内网）：
dsh plugin --profile <name> add <path-to-dsh-keymouse>
npm 方式（发布后）：
dsh plugin --profile <name> add @temsmie/dsh-tool-keymouse
目录结构
dsh-keymouse/
package.json # npm 包契约(peerDeps/files/exports)
tsconfig.json
src/
index.ts # 插件入口: apply 里 spawn helper + 注册工具 + 注册skill
helper.cpp # helper 源码(SendInput + JSON行协议 + 键位表 + 窗口/截图)
skill-content.ts # keymouse 说明书内容(注册为 runtime skill)
skills/
keymouse.md # 说明书可读副本(与 skill-content 一致)
bin/
helper-x64.exe # 预编译 helper(Windows x64)
lib/ # tsc 编译产物(index.js / skill-content.js / *.d.ts)
helper 协议
helper 从 stdin 逐行读 JSON，每行一条指令，每条输出一行 {"ok":true|false,"error":...} 到 stdout。stdin 关闭即退出（退出前自动 release_all）。
指令（get_window/win_* 返回窗口字段，capture 返回 path/width/height）：
{"cmd":"press","key":"space"}
{"cmd":"up","key":"space"}
{"cmd":"tap","key":"enter"}
{"cmd":"mpress","button":"left"}
{"cmd":"mmove","x":800,"y":450}
{"cmd":"mroll","up":true,"amount":1}
{"cmd":"release_all"}
{"cmd":"ping"}
{"cmd":"capture"}
{"cmd":"get_window"}
{"cmd":"win_rect","hwnd":123}
{"cmd":"win_top","hwnd":123,"on":true}
{"cmd":"release_top"}
{"cmd":"win_state","hwnd":123,"action":"minimize|restore|maximize"}
{"cmd":"win_find","process":"QQ"}
{"cmd":"win_activate","hwnd":123}
重新编译 helper
g++ -O2 -std=c++17 src\helper.cpp -o bin\helper-x64.exe -luser32 -lwinmm -lgdiplus -lgdi32
重新编译插件(TypeScript -> lib)
首次需把本机 DSH 的 @deepseek-ai 依赖接(junction)到本项目 node_modules（@deepseek-ai/dsh-tools 等类型来自 DSH 安装目录）：
cmd /c mklink /J "node_modules\@deepseek-ai" "C:\Users\<你的用户名>\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai"
然后：
npm install
npx tsc
说明：该 junction 仅用于本机编译，不在发布白名单(files)内，不影响打包分发。node_modules 已 gitignore，bin/helper-x64.exe（预编译、按需分发）随包提交。
环境与能力边界
- 本插件只做三件事：模拟键鼠输入、截主屏、窗口查询/置顶。不含识图能力。
screenshot 返回 PNG 绝对路径。能否看图由宿主环境决定：
- 当前模型支持图像输入 → 用宿主自带的读图能力打开该路径即可。
- 模型不支持图像输入 → 需环境另有视觉/OCR 能力：安装提供图像理解/OCR 的 DSH 插件，或换用支持图像输入的模型。
- 插件不依赖任何特定视觉插件或工具名；
skill 说明书同样不假设某种识图方式存在，避免在缺该能力的环境里给出无效步骤。
- 想提升体验：用插件市场（
find_dsh_plugin）搜 vision / OCR / image 等关键词安装相应插件；或直接在支持图像输入的模型下使用。
- 键鼠工具本身依赖 Windows 桌面会话（见下）。
平台
仅支持 Windows（helper 使用 Win32 SendInput/GetSystemMetrics/EnumWindows）。DPI-aware，主屏物理像素坐标基准，单屏。
License
MIT
