@temsmie/dsh-tool-keymouse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dsh-tool-keymouse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# 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()` → `read_image(path)` 看图再操作。
+
+## 安装
+
+本地目录方式（开发/内网）：
+
+```
+dsh plugin --profile <name> add D:\AI_production\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`（预编译、按需分发）随包提交。
+
+## 平台
+
+仅支持 Windows（helper 使用 Win32 `SendInput`/`GetSystemMetrics`/`EnumWindows`）。DPI-aware，主屏物理像素坐标基准，单屏。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-keymouse bundle patch: mount the plugin under its package name,
+# resolved through the profile's node_modules. DSH loads lib/index.js and
+# calls apply(ctx) to spawn the helper and register the key/mouse tools + skill.
+
+- insert:
+    - id: tool-keymouse
+      name: '@keymouse/dsh-tool-keymouse'

package/lib/index.d.ts

@@ -0,0 +1,36 @@
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "tool-keymouse";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<{
+    helperPath: z<string, string>;
+    timeoutMs: z<number, number>;
+}>, Schemastery.ObjectT<{
+    helperPath: z<string, string>;
+    timeoutMs: z<number, number>;
+}>>;
+export interface KeymouseConfig {
+    helperPath?: string;
+    timeoutMs?: number;
+}
+export interface HelperResult {
+    ok: boolean;
+    error?: string;
+    /** capture 指令返回的 PNG 绝对路径与尺寸(仅截图时)。 */
+    path?: string;
+    width?: number;
+    height?: number;
+    /** 窗口工具返回的字段(仅窗口类指令)。 */
+    hwnd?: number;
+    title?: string;
+    pid?: number;
+    process?: string;
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    /** 窗口是否可见(false = 最小化到托盘隐藏状态)。 */
+    visible?: boolean;
+}
+declare function apply(ctx: Context, config?: KeymouseConfig): void;
+export { apply };

package/lib/index.js

@@ -0,0 +1,454 @@
+// index.ts — dsh-keymouse 插件入口
+// apply(ctx) 中:
+//   1. spawn 常驻 helper-x64.exe(通过 stdin 发 JSON 行指令)
+//   2. ctx.tools.register 七个键鼠工具
+//   3. ctx.skills.register 常驻 keymouse 说明书(runtime skill)
+// 只支持 Windows。helper 预编译进 bin/helper-x64.exe。
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+import { KEYMOUSE_SKILL_NAME, KEYMOUSE_SKILL_DESCRIPTION, KEYMOUSE_SKILL_WHEN_TO_USE, KEYMOUSE_SKILL_CONTENT, } from './skill-content.js';
+export const name = 'tool-keymouse';
+export const inject = ['tools', 'skills'];
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_HELPER_PATH = join(__dirname, '..', 'bin', 'helper-x64.exe');
+export const Config = z.object({
+    helperPath: z.string(),
+    timeoutMs: z.number().min(1),
+});
+const HELPER_TIMEOUT_MS = 5000;
+/** 常驻 helper 客户端:一次只发一条指令,等一行 JSON 响应;helper 崩溃后自动重启。 */
+class HelperClient {
+    helperPath;
+    timeoutMs;
+    child = null;
+    rl = null;
+    started = false;
+    chain = Promise.resolve();
+    inFlight = null;
+    constructor(helperPath, timeoutMs) {
+        this.helperPath = helperPath;
+        this.timeoutMs = timeoutMs;
+    }
+    ensureStarted() {
+        if (!existsSync(this.helperPath)) {
+            return Promise.reject(new Error(`helper not found: ${this.helperPath}`));
+        }
+        if (this.started && this.child !== null)
+            return Promise.resolve();
+        this.started = true;
+        const child = spawn(this.helperPath, [], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        this.child = child;
+        this.rl = createInterface({ input: child.stdout });
+        this.rl.on('line', (line) => this.consume(line));
+        child.on('error', (err) => this.failInFlight(err));
+        child.on('exit', () => {
+            this.failInFlight(new Error('helper exited'));
+            if (this.child === child) {
+                this.child = null;
+                this.started = false;
+                this.rl?.close();
+                this.rl = null;
+            }
+        });
+        return new Promise((res, rej) => {
+            child.once('spawn', () => res());
+            child.once('error', (e) => rej(e));
+        });
+    }
+    consume(line) {
+        const cur = this.inFlight;
+        if (cur === null)
+            return;
+        this.inFlight = null;
+        clearTimeout(cur.timer);
+        try {
+            const parsed = JSON.parse(line.trim());
+            const ok = parsed.ok === true;
+            const error = typeof parsed.error === 'string' ? parsed.error : undefined;
+            const path = typeof parsed.path === 'string' ? parsed.path : undefined;
+            const width = typeof parsed.width === 'number' ? parsed.width : undefined;
+            const height = typeof parsed.height === 'number' ? parsed.height : undefined;
+            const hwnd = typeof parsed.hwnd === 'number' ? parsed.hwnd : undefined;
+            const pid = typeof parsed.pid === 'number' ? parsed.pid : undefined;
+            const title = typeof parsed.title === 'string' ? parsed.title : undefined;
+            const process = typeof parsed.process === 'string' ? parsed.process : undefined;
+            const visible = typeof parsed.visible === 'boolean' ? parsed.visible : undefined;
+            const x = typeof parsed.x === 'number' ? parsed.x : undefined;
+            const y = typeof parsed.y === 'number' ? parsed.y : undefined;
+            const w = typeof parsed.w === 'number' ? parsed.w : undefined;
+            const h = typeof parsed.h === 'number' ? parsed.h : undefined;
+            // 成功/无错误时省略 error 键,避免含 undefined 属性被判为 lossy JSON;
+            // 其余字段(截图/窗口)同样仅有值时才挂载。
+            const base = error === undefined ? { ok } : { ok, error };
+            if (path !== undefined)
+                base.path = path;
+            if (width !== undefined)
+                base.width = width;
+            if (height !== undefined)
+                base.height = height;
+            if (hwnd !== undefined)
+                base.hwnd = hwnd;
+            if (pid !== undefined)
+                base.pid = pid;
+            if (title !== undefined)
+                base.title = title;
+            if (process !== undefined)
+                base.process = process;
+            if (visible !== undefined)
+                base.visible = visible;
+            if (x !== undefined)
+                base.x = x;
+            if (y !== undefined)
+                base.y = y;
+            if (w !== undefined)
+                base.w = w;
+            if (h !== undefined)
+                base.h = h;
+            cur.resolve(base);
+        }
+        catch {
+            cur.reject(new Error(`helper returned invalid response: ${line}`));
+        }
+    }
+    failInFlight(err) {
+        const cur = this.inFlight;
+        if (cur === null)
+            return;
+        this.inFlight = null;
+        clearTimeout(cur.timer);
+        cur.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+    /** 串行发送一条指令,helper 响应后解析返回。 */
+    send(cmd) {
+        const run = this.chain.then(async () => {
+            await this.ensureStarted();
+            if (this.child === null)
+                throw new Error('helper is not running');
+            return this.writeAndRead(cmd);
+        });
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+    writeAndRead(cmd) {
+        return new Promise((resolve, reject) => {
+            const child = this.child;
+            const timer = setTimeout(() => this.failInFlight(new Error('helper timed out')), this.timeoutMs);
+            this.inFlight = { resolve, reject, timer };
+            const line = JSON.stringify(cmd) + '\n';
+            child.stdin.write(line, (err) => {
+                if (err)
+                    this.failInFlight(err);
+            });
+        });
+    }
+    /** 退出前统一 release_all,再掐断 stdin 并结束进程。 */
+    async dispose() {
+        const child = this.child;
+        this.child = null;
+        this.started = false;
+        this.failInFlight(new Error('disposed'));
+        if (child !== null && !child.killed) {
+            try {
+                this.inFlight = null;
+                child.stdin.write('{"cmd":"release_all"}\n');
+                child.stdin.end();
+            }
+            catch {
+                // ignore
+            }
+            child.kill();
+        }
+    }
+}
+/** 统一的输出 schema:每次调用返回 ok/error;截图额外带 path/width/height。 */
+const OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ok: { type: 'boolean', required: true },
+        error: { type: 'string' },
+        path: { type: 'string' },
+        width: { type: 'number' },
+        height: { type: 'number' },
+        hwnd: { type: 'number' },
+        title: { type: 'string' },
+        pid: { type: 'number' },
+        process: { type: 'string' },
+        x: { type: 'number' },
+        y: { type: 'number' },
+        w: { type: 'number' },
+        h: { type: 'number' },
+        visible: { type: 'boolean' },
+    },
+};
+/** 生成统一的 render:成功/失败各一条文本,尽量带上调用参数便于模型核对。 */
+function renderOutput(kind) {
+    return (args, value) => {
+        const a = args;
+        const detail = a?.key ??
+            a?.button ??
+            (a?.x !== undefined && a?.y !== undefined ? `${a.x},${a.y}` : undefined) ??
+            undefined;
+        if (value.ok) {
+            return [{ type: 'text', text: detail !== undefined ? `${kind}: ${detail} 完成` : `${kind} 完成` }];
+        }
+        return [{ type: 'text', text: `${kind}失败: ${value.error ?? '未知错误'}` }];
+    };
+}
+/** 截图结果的 render:成功时显示保存路径与尺寸,失败显示错误。 */
+function renderScreenshot(args, value) {
+    if (value.ok) {
+        const text = value.path ? `截图已保存: ${value.path} (${value.width}x${value.height})` : '截图完成';
+        return [{ type: 'text', text }];
+    }
+    return [{ type: 'text', text: `截图失败: ${value.error ?? '未知错误'}` }];
+}
+/** get_window 的 render:显示标题/进程/pid/位置。 */
+function renderGetWindow(args, value) {
+    if (value.ok) {
+        const tex = `当前窗口: ${value.title ?? '(无标题)'} (${value.process ?? ''}, pid=${value.pid ?? '?'}, ${value.x ?? 0},${value.y ?? 0} ${value.w ?? 0}x${value.h ?? 0})`;
+        return [{ type: 'text', text: tex }];
+    }
+    return [{ type: 'text', text: `get_window失败: ${value.error ?? '未知错误'}` }];
+}
+/** win_rect 的 render:显示位置与尺寸。 */
+function renderWinRect(args, value) {
+    if (value.ok) {
+        const tex = `窗口位置: (${value.x ?? 0},${value.y ?? 0}) ${value.w ?? 0}x${value.h ?? 0}`;
+        return [{ type: 'text', text: tex }];
+    }
+    return [{ type: 'text', text: `win_rect失败: ${value.error ?? '未知错误'}` }];
+}
+/** win_find 的 render:显示匹配窗口的句柄/标题/进程/可见性。 */
+function renderFindWindow(args, value) {
+    if (value.ok) {
+        const tex = `找到窗口: hwnd=${value.hwnd} "${value.title ?? '(无标题)'}" (${value.process ?? ''}, pid=${value.pid ?? '?'}, visible=${value.visible ? '是' : '否,最小化到托盘'}, ${value.x ?? 0},${value.y ?? 0} ${value.w ?? 0}x${value.h ?? 0})`;
+        return [{ type: 'text', text: tex }];
+    }
+    return [{ type: 'text', text: `win_find失败: ${value.error ?? '未知错误'}` }];
+}
+function apply(ctx, config = {}) {
+    const helperPath = config.helperPath ?? DEFAULT_HELPER_PATH;
+    const timeoutMs = config.timeoutMs ?? HELPER_TIMEOUT_MS;
+    const client = new HelperClient(helperPath, timeoutMs);
+    // 插件卸载时清理常驻进程。
+    ctx.effect(() => async () => {
+        await client.dispose();
+    });
+    const register = (tool) => ctx.tools.register(tool);
+    register(defineTool({
+        name: 'key_press',
+        description: '按下某个键盘键(不抬起)。用于组合键:先 key_press 其他键,最后必须调用 release_all 抬起,否则键会一直按住。',
+        parameters: {
+            key: { type: 'string', required: true, description: '小写英文键名:字母 a-z、数字 0-9、space/enter/tab/esc/backspace/delete/home/end/pageup/pagedown、方向键 up/down/left/right、f1-f12、ctrl/alt/shift/win/capslock。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('key_press') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'press', key: args.key });
+        },
+    }));
+    register(defineTool({
+        name: 'key_up',
+        description: '抬起某个键盘键。与 key_press 配对;也可单独使用。',
+        parameters: {
+            key: { type: 'string', required: true, description: '小写英文键名,同 key_press。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('key_up') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'up', key: args.key });
+        },
+    }));
+    register(defineTool({
+        name: 'key_tap',
+        description: '按下并立刻抬起单个键(单个动作,不卡键)。用于点按/输入单字符或单个快捷键按键。',
+        parameters: {
+            key: { type: 'string', required: true, description: '小写英文键名,同 key_press。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('key_tap') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'tap', key: args.key });
+        },
+    }));
+    register(defineTool({
+        name: 'mouse_press',
+        description: '只按下鼠标按钮(不抬起)。用于按住左键拖动:mouse_press("left") → mouse_move(...) → release_all。',
+        parameters: {
+            button: { type: 'string', required: true, description: '鼠标按钮:left/right/middle/x1/x2。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('mouse_press') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'mpress', button: args.button });
+        },
+    }));
+    register(defineTool({
+        name: 'mouse_move',
+        description: '把鼠标绝对移动到屏幕坐标 (x,y)。以主屏左上为 (0,0),单屏。',
+        parameters: {
+            x: { type: 'number', required: true, description: '目标屏幕 X 坐标(像素)。' },
+            y: { type: 'number', required: true, description: '目标屏幕 Y 坐标(像素)。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('mouse_move') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'mmove', x: Math.round(args.x), y: Math.round(args.y) });
+        },
+    }));
+    register(defineTool({
+        name: 'mouse_roll',
+        description: '滚动鼠标滚轮。up 为 true 滚上、false 滚下;可指定滚动格数 amount(默认1)。',
+        parameters: {
+            up: { type: 'boolean', required: true, description: 'true 滚上,false 滚下。' },
+            amount: { type: 'number', description: '滚动格数,默认 1。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('mouse_roll') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'mroll', up: args.up, amount: args.amount ?? 1 });
+        },
+    }));
+    register(defineTool({
+        name: 'release_all',
+        description: '抬起所有仍被按住的键与鼠标按钮。每次键鼠操作结束后必须调用一次,避免卡键。',
+        parameters: {},
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('release_all') },
+        async execute(_args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'release_all' });
+        },
+    }));
+    register(defineTool({
+        name: 'screenshot',
+        description: '截取当前主屏(全屏)保存为 PNG,返回图片路径与尺寸。之后用 read_image 读取该路径即可查看屏幕内容,再配合键鼠操作。',
+        parameters: {},
+        output: { schema: OUTPUT_SCHEMA, render: renderScreenshot },
+        async execute(_args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'capture' });
+        },
+    }));
+    register(defineTool({
+        name: 'get_window',
+        description: '获取当前前台窗口的信息:窗口句柄 hwnd、标题 title、进程名 process、pid、位置(x,y,w,h)。用于确认目标窗口、拿到 hwnd 再给 win_rect/win_top。',
+        parameters: {},
+        output: { schema: OUTPUT_SCHEMA, render: renderGetWindow },
+        async execute(_args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'get_window' });
+        },
+    }));
+    register(defineTool({
+        name: 'win_rect',
+        description: '获取窗口位置与尺寸:传入 hwnd(来自 get_window),不传默认当前前台窗口。返回 x/y/w/h。',
+        parameters: {
+            hwnd: { type: 'number', description: '窗口句柄(来自 get_window 的 hwnd)。可选。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderWinRect },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send(args.hwnd !== undefined ? { cmd: 'win_rect', hwnd: args.hwnd } : { cmd: 'win_rect' });
+        },
+    }));
+    register(defineTool({
+        name: 'win_top',
+        description: '置顶(true)/取消置顶(false)指定窗口(置顶后窗口常驻最前)。任务结束统一调 release_top 取消所有置顶,避免干扰。',
+        parameters: {
+            hwnd: { type: 'number', required: true, description: '窗口句柄(来自 get_window 的 hwnd)。' },
+            on: { type: 'boolean', required: true, description: 'true 置顶,false 取消置顶。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('win_top') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'win_top', hwnd: Math.round(args.hwnd), on: args.on });
+        },
+    }));
+    register(defineTool({
+        name: 'release_top',
+        description: '取消所有本插件置顶过的窗口,恢复默认层级。任务结束必须调用一次。',
+        parameters: {},
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('release_top') },
+        async execute(_args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'release_top' });
+        },
+    }));
+    const winState = (action, hint) => defineTool({
+        name: `win_${action}`,
+        description: hint,
+        parameters: {
+            hwnd: { type: 'number', description: '窗口句柄(来自 get_window 的 hwnd)。可选,不传默认当前前台窗口。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput(`win_${action}`) },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send(args.hwnd !== undefined ? { cmd: 'win_state', action, hwnd: args.hwnd } : { cmd: 'win_state', action });
+        },
+    });
+    register(winState('minimize', '最小化指定窗口(不传默认当前前台窗口)。'));
+    register(winState('restore', '还原指定窗口(不传默认当前前台窗口):从最小化或最大化还原。'));
+    register(winState('maximize', '最大化指定窗口(不传默认当前前台窗口)。'));
+    register(defineTool({
+        name: 'win_find',
+        description: '按进程名查找窗口:返回第一个匹配的窗口句柄 hwnd、标题、进程、pid、visible(是否可见,false 表示最小化到托盘)。用于替代鼠标点任务栏图标,定位并唤起某程序窗口。',
+        parameters: {
+            process: { type: 'string', required: true, description: '进程名,如 "QQ"、"QQ.exe"、"firefox"(忽略大小写与 .exe 后缀)。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderFindWindow },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'win_find', process: args.process });
+        },
+    }));
+    register(defineTool({
+        name: 'win_activate',
+        description: '激活/前置指定窗口:自动处理最小化与"最小化到托盘(隐藏)"两种情况,再置前台。配合 win_find 使用,任务结束无需额外清理。',
+        parameters: {
+            hwnd: { type: 'number', required: true, description: '窗口句柄(来自 win_find 或 get_window 的 hwnd)。' },
+        },
+        output: { schema: OUTPUT_SCHEMA, render: renderOutput('win_activate') },
+        async execute(args, exec) {
+            if (exec.signal.aborted)
+                throw new Error('aborted');
+            return client.send({ cmd: 'win_activate', hwnd: Math.round(args.hwnd) });
+        },
+    }));
+    // 注册常驻 skill 说明书(runtime skill,随插件分发)。
+    if (isSkillName(KEYMOUSE_SKILL_NAME)) {
+        ctx.skills.register({
+            name: KEYMOUSE_SKILL_NAME,
+            description: KEYMOUSE_SKILL_DESCRIPTION,
+            whenToUse: KEYMOUSE_SKILL_WHEN_TO_USE,
+            invocation: { modelInvocable: true, userInvocable: false },
+            provider: 'tool-keymouse',
+            source: 'runtime',
+            content: KEYMOUSE_SKILL_CONTENT,
+        });
+    }
+}
+export { apply };

package/lib/skill-content.d.ts

@@ -0,0 +1,4 @@
+export declare const KEYMOUSE_SKILL_NAME = "keymouse";
+export declare const KEYMOUSE_SKILL_DESCRIPTION = "\u952E\u9F20\u63A7\u5236\u5DE5\u5177\uFF1A\u7528 SendInput \u6A21\u62DF\u771F\u5B9E\u952E\u76D8/\u9F20\u6807\u8F93\u5165\u3001\u622A\u5C4F\u3001\u67E5\u8BE2\u4E0E\u7F6E\u9876\u7A97\u53E3\uFF0C\u7528\u4E8E\u684C\u9762\u81EA\u52A8\u5316\uFF08\u6253\u5F00\u5E94\u7528\u3001\u767B\u5F55\u3001\u70B9\u51FB\u3001\u8F93\u5165\u3001\u62D6\u62FD\u3001\u6EDA\u52A8\u3001\u622A\u56FE\u89C2\u5BDF\u3001\u7A97\u53E3\u5B9A\u4F4D/\u7F6E\u9876\uFF09\u3002";
+export declare const KEYMOUSE_SKILL_WHEN_TO_USE = "\u4EFB\u4F55\u9700\u8981\u6A21\u62DF\u771F\u5B9E\u952E\u76D8\u6309\u4E0B/\u62AC\u8D77\u3001\u9F20\u6807\u70B9\u51FB/\u79FB\u52A8/\u6EDA\u8F6E\u3001\u8F93\u5165\u6587\u5B57\u6216\u64CD\u4F5C\u524D\u53F0\u7A97\u53E3\u7684\u81EA\u52A8\u5316\u4EFB\u52A1\u3002";
+export declare const KEYMOUSE_SKILL_CONTENT = "# \u952E\u9F20\u63A7\u5236\uFF08KeyMouse\uFF09\n\n\u901A\u8FC7\u5E38\u9A7B helper \u7528 SendInput \u6A21\u62DF\u771F\u5B9E\u952E\u9F20\u8F93\u5165\uFF0C\u5BF9\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u751F\u6548\u3002\u6240\u6709\u5DE5\u5177\u8C03\u7528\u7ED3\u675F\u540E\u5FC5\u987B\u8DD1\u4E00\u6B21 release_all\u3002\n\n## \u5750\u6807\u4E0E\u952E\u540D\n\n- \u5750\u6807\uFF1A\u7EDD\u5BF9\u5C4F\u5E55**\u7269\u7406**\u50CF\u7D20\uFF08helper \u5DF2 DPI-aware\uFF0C\u65E0\u7F29\u653E\u6362\u7B97\uFF09\uFF0C\u4E3B\u5C4F\u5DE6\u4E0A\u89D2\u4E3A (0,0)\uFF0C\u5355\u5C4F\u3002x \u5411\u53F3\u3001y \u5411\u4E0B\u3002\u622A\u56FE\u5206\u8FA8\u7387\u5373\u7269\u7406\u50CF\u7D20\uFF0C\u8BC6\u56FE\u770B\u5230\u7684\u5750\u6807\u53EF\u76F4\u63A5\u7528\u4E8E mouse_move\uFF0C\u65E0\u9700\u6362\u7B97\u3002\n- \u952E\u540D\uFF08\u5C0F\u5199\u82F1\u6587\uFF09\uFF1A\u5B57\u6BCD `a`-`z`\u3001\u6570\u5B57 `0`-`9`\u3001`space`\u3001`enter`\u3001`tab`\u3001`esc`\u3001`backspace`\u3001`delete`\u3001`insert`\u3001`home`\u3001`end`\u3001`pageup`\u3001`pagedown`\u3001\u65B9\u5411\u952E `up`/`down`/`left`/`right`\u3001`f1`-`f12`\u3001\u4FEE\u9970\u952E `ctrl`\u3001`alt`\u3001`shift`\u3001`win`\u3001`capslock`\u3002\n- \u9F20\u6807\u6309\u94AE\uFF1A`left`\u3001`right`\u3001`middle`\u3001`x1`\u3001`x2`\u3002\n\n## \u5DE5\u5177\n\n### screenshot()\n\u622A\u53D6\u5F53\u524D\u4E3B\u5C4F\uFF08\u5168\u5C4F\uFF09\u4FDD\u5B58\u4E3A PNG\uFF0C\u8FD4\u56DE\u56FE\u7247\u8DEF\u5F84\u4E0E\u5C3A\u5BF8\u3002\u6A21\u578B\u662F\u591A\u6A21\u6001\u7684\uFF0C\u53EF\u76F4\u63A5\u770B\uFF1A\nscreenshot() \u2192 \u62FF\u5230 path \u2192 read_image(path) \u67E5\u770B\u5C4F\u5E55 \u2192 \u518D\u505A\u952E\u9F20\u64CD\u4F5C\u3002\n\n### get_window()\n\u83B7\u53D6\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u4FE1\u606F\uFF1A\u7A97\u53E3\u53E5\u67C4 hwnd\u3001\u6807\u9898 title\u3001\u8FDB\u7A0B\u540D process\u3001pid\u3001\u4F4D\u7F6E (x,y,w,h)\u3002\n\u7528\u4E8E\u786E\u8BA4\u76EE\u6807\u7A97\u53E3\u3001\u62FF\u5230 hwnd \u518D\u5B9A\u4F4D\u6216\u7F6E\u9876\u3002\n\n### win_rect(hwnd?)\n\u83B7\u53D6\u7A97\u53E3\u4F4D\u7F6E\u4E0E\u5C3A\u5BF8\uFF1A\u4F20\u5165 hwnd\uFF08\u6765\u81EA get_window\uFF09\uFF0C\u4E0D\u4F20\u9ED8\u8BA4\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u3002\u8FD4\u56DE x/y/w/h\u3002\n\n### win_find(process)\n\u6309\u8FDB\u7A0B\u540D\u67E5\u627E\u7A97\u53E3\uFF1A\u8FD4\u56DE\u7B2C\u4E00\u4E2A\u5339\u914D\u7684\u7A97\u53E3\u53E5\u67C4 hwnd\u3001\u6807\u9898\u3001\u8FDB\u7A0B\u3001pid\u3001visible\uFF08\u662F\u5426\u53EF\u89C1\uFF0Cfalse \u8868\u793A\u6700\u5C0F\u5316\u5230\u6258\u76D8\uFF09\u3002\u7528\u4E8E\u66FF\u4EE3\u9F20\u6807\u70B9\u4EFB\u52A1\u680F\u56FE\u6807\uFF0C\u5B9A\u4F4D\u5E76\u5524\u8D77\u67D0\u7A0B\u5E8F\u7A97\u53E3\u3002\n\u4F8B\uFF1Awin_find('QQ') \u2192 \u62FF\u5230 hwnd\uFF0C\u518D win_activate(hwnd) \u5524\u8D77 QQ \u4E3B\u7A97\u53E3\u3002\n\n### win_activate(hwnd)\n\u6FC0\u6D3B/\u524D\u7F6E\u6307\u5B9A\u7A97\u53E3\uFF1A\u81EA\u52A8\u5904\u7406\u6700\u5C0F\u5316\u4E0E\"\u6700\u5C0F\u5316\u5230\u6258\u76D8\uFF08\u9690\u85CF\uFF09\"\u4E24\u79CD\u60C5\u51B5\uFF0C\u518D\u7F6E\u524D\u53F0\u3002\u914D\u5408 win_find \u4F7F\u7528\uFF0C\u4EFB\u52A1\u7ED3\u675F\u65E0\u9700\u989D\u5916\u6E05\u7406\u3002\n\n### win_minimize(hwnd?)\n\u6700\u5C0F\u5316\u6307\u5B9A\u7A97\u53E3\uFF1A\u4F20\u5165 hwnd\uFF08\u6765\u81EA get_window\uFF09\uFF0C\u4E0D\u4F20\u9ED8\u8BA4\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u3002\n\n### win_restore(hwnd?)\n\u8FD8\u539F\u6307\u5B9A\u7A97\u53E3\uFF1A\u4ECE\u6700\u5C0F\u5316\u6216\u6700\u5927\u5316\u8FD8\u539F\u5230\u4E4B\u524D\u5927\u5C0F\u3002\u4E0D\u4F20\u9ED8\u8BA4\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u3002\n\n### win_maximize(hwnd?)\n\u6700\u5927\u5316\u6307\u5B9A\u7A97\u53E3\u3002\u4E0D\u4F20\u9ED8\u8BA4\u5F53\u524D\u524D\u53F0\u7A97\u53E3\u3002\n\n### win_top(hwnd, on)\n\u7F6E\u9876\uFF08true\uFF09/\u53D6\u6D88\u7F6E\u9876\uFF08false\uFF09\u6307\u5B9A\u7A97\u53E3\u3002\u7F6E\u9876\u540E\u7A97\u53E3\u5E38\u9A7B\u6700\u524D\u3002\u4EFB\u52A1\u7ED3\u675F\u5FC5\u987B\u7EDF\u4E00 release_top \u53D6\u6D88\u3002\n\n### release_top()\n\u53D6\u6D88\u6240\u6709\u672C\u63D2\u4EF6\u7F6E\u9876\u8FC7\u7684\u7A97\u53E3\uFF0C\u6062\u590D\u9ED8\u8BA4\u5C42\u7EA7\u3002\u4EFB\u52A1\u7ED3\u675F\u65F6\u5FC5\u987B\u8C03\u7528\u4E00\u6B21\u3002\n\n### key_tap(key)\n\u6309\u4E0B\u5E76\u7ACB\u523B\u62AC\u8D77\u5355\u4E2A\u952E\uFF08\u5355\u4E2A\u52A8\u4F5C\uFF0C\u4E0D\u5361\u952E\uFF09\u3002\u7528\u4E8E\u70B9\u6309\u3001\u8F93\u5165\u5355\u5B57\u7B26\u6216\u5355\u4E2A\u5FEB\u6377\u952E\u6309\u952E\u3002\n\u4F8B\uFF1Akey_tap('enter') \u786E\u8BA4\uFF1Bkey_tap('space') \u7FFB\u9875\u3002\n\n### key_press(key)\n\u53EA\u6309\u4E0B\u67D0\u952E\u3001\u4E0D\u62AC\u8D77\u3002\u7528\u4E8E\u7EC4\u5408\u952E\uFF1A\u5148 key_press('ctrl')\uFF0C\u518D\u6309\u5176\u4ED6\u952E\uFF0C\u6700\u540E release_all\u3002\n\u6CE8\u610F\uFF1A\u5FC5\u987B\u914D\u5408 release_all \u62AC\u8D77\uFF0C\u5426\u5219\u952E\u4F1A\u4E00\u76F4\u6309\u4F4F\u3002\n\n### key_up(key)\n\u62AC\u8D77\u67D0\u952E\u3002\n\n### mouse_press(button)\n\u53EA\u6309\u4E0B\u9F20\u6807\u6309\u94AE\u3001\u4E0D\u62AC\u8D77\u3002\u7528\u4E8E\u6309\u4F4F\u5DE6\u952E\u62D6\u52A8\uFF1Amouse_press('left') \u2192 mouse_move(...) \u2192 release_all\u3002\n\n### mouse_move(x,y)\n\u628A\u9F20\u6807\u7EDD\u5BF9\u79FB\u52A8\u5230\u5C4F\u5E55\u5750\u6807 (x,y)\u3002\n\n### mouse_roll(up)\n\u6EDA\u52A8\u9F20\u6807\u6EDA\u8F6E\uFF1Aup \u4E3A true \u6EDA\u4E0A\u3001false \u6EDA\u4E0B\u3002\n\n### release_all()\n\u62AC\u8D77\u6240\u6709\u4ECD\u88AB\u6309\u4F4F\u7684\u952E\u4E0E\u9F20\u6807\u6309\u94AE\u3002\u6BCF\u6B21\u952E\u9F20\u64CD\u4F5C\u7ED3\u675F\u540E\u5FC5\u987B\u8C03\u7528\u4E00\u6B21\uFF0C\u907F\u514D\u5361\u952E\u3002\n\n## \u8FD4\u56DE\n\n\u6BCF\u4E2A\u5DE5\u5177\u8FD4\u56DE ok=true \u8868\u793A\u8BE5\u547D\u4EE4\u5DF2\u4EA4\u7ED9\u7CFB\u7EDF\uFF1B\u8FD4\u56DE error \u8868\u793A\u53C2\u6570\u6216\u952E\u540D\u4E0D\u5408\u6CD5\u3002screenshot \u8FD8\u8FD4\u56DE path\uFF08PNG \u7EDD\u5BF9\u8DEF\u5F84\uFF09\u3001width/height\uFF08\u50CF\u7D20\u5C3A\u5BF8\uFF09\u3002win_find \u8FD8\u8FD4\u56DE hwnd\u3001title\u3001process\u3001pid\u3001visible\u3001x/y/w/h\u3002\n\n## \u5178\u578B\u7EC4\u5408\n\n- Ctrl+S \u4FDD\u5B58\uFF1Akey_press('ctrl')\uFF1Bkey_tap('s')\uFF1Brelease_all\u3002\n- Ctrl+O \u6253\u5F00\uFF1Akey_press('ctrl')\uFF1Bkey_tap('o')\uFF1Brelease_all\u3002\n- \u5DE6\u952E\u62D6\u62FD\uFF1Amouse_press('left')\uFF1Bmouse_move(x2,y2)\uFF1Bmouse_move(x1,y1)\uFF1Brelease_all\u3002\n- \u6EDA\u5230\u9875\u9762\u5E95\u90E8\uFF1Amouse_roll(false)\uFF1Bmouse_roll(false)\uFF1B\u2026\uFF08\u53EF\u591A\u6B21\uFF09\u3002\n- \u89C6\u89C9\u95ED\u73AF\uFF1Ascreenshot() \u5F97 path \u2192 read_image(path) \u770B\u5C4F\u5E55 \u2192 \u952E\u9F20\u64CD\u4F5C\u3002\n- \u5524\u8D77\u7A0B\u5E8F\u7A97\u53E3\uFF08\u4E0D\u70B9\u56FE\u6807\uFF09\uFF1Awin_find('QQ') \u2192 win_activate(hwnd) \u2192 \u524D\u53F0\u51FA\u73B0 QQ \u4E3B\u7A97\u53E3\uFF08\u6258\u76D8\u9690\u85CF/\u6700\u5C0F\u5316\u4E5F\u80FD\u5524\u56DE\uFF09\u3002\n\n## \u89C4\u8303\n\n1. \u64CD\u4F5C\u524D\u5148\u786E\u8BA4\u76EE\u6807\u7A97\u53E3\u4E0E\u9F20\u6807\u4F4D\u7F6E\uFF08\u53EF\u5148 mouse_move \u518D\u89C2\u5BDF\u7ED3\u679C\uFF09\u3002\n2. \u7528\u7EC4\u5408\u952E/\u6309\u4F4F\u540E\uFF0C\u7ED3\u675F\u7EDF\u4E00\u8C03\u7528 release_all\u3002\n3. \u7F6E\u9876\u7A97\u53E3\u540E\uFF0C\u4EFB\u52A1\u7ED3\u675F\u7EDF\u4E00\u8C03\u7528 release_top \u53D6\u6D88\u3002\n4. \u5DE5\u5177\u503C\u662F\u5373\u65F6\u7684\uFF1ASendInput \u5FAE\u79D2\u7EA7\u751F\u6548\uFF0C\u4E0D\u9700\u8981\u7B49\u5F85\u3002\n";

package/lib/skill-content.js

@@ -0,0 +1,94 @@
+// skill-content.ts — 键鼠控制 skill 的固定说明书内容(单一来源)
+// 服务端注册为 runtime skill,模型通过 skill 工具读取;技能名 keymouse。
+// 此为"工具调用说明书",非流程:说明每个工具用途、参数、返回、一个例子,以及用完统一 release_all 的提醒。
+export const KEYMOUSE_SKILL_NAME = 'keymouse';
+export const KEYMOUSE_SKILL_DESCRIPTION = '键鼠控制工具：用 SendInput 模拟真实键盘/鼠标输入、截屏、查询与置顶窗口，用于桌面自动化（打开应用、登录、点击、输入、拖拽、滚动、截图观察、窗口定位/置顶）。';
+export const KEYMOUSE_SKILL_WHEN_TO_USE = '任何需要模拟真实键盘按下/抬起、鼠标点击/移动/滚轮、输入文字或操作前台窗口的自动化任务。';
+export const KEYMOUSE_SKILL_CONTENT = `# 键鼠控制（KeyMouse）
+
+通过常驻 helper 用 SendInput 模拟真实键鼠输入，对当前前台窗口生效。所有工具调用结束后必须跑一次 release_all。
+
+## 坐标与键名
+
+- 坐标：绝对屏幕**物理**像素（helper 已 DPI-aware，无缩放换算），主屏左上角为 (0,0)，单屏。x 向右、y 向下。截图分辨率即物理像素，识图看到的坐标可直接用于 mouse_move，无需换算。
+- 键名（小写英文）：字母 \`a\`-\`z\`、数字 \`0\`-\`9\`、\`space\`、\`enter\`、\`tab\`、\`esc\`、\`backspace\`、\`delete\`、\`insert\`、\`home\`、\`end\`、\`pageup\`、\`pagedown\`、方向键 \`up\`/\`down\`/\`left\`/\`right\`、\`f1\`-\`f12\`、修饰键 \`ctrl\`、\`alt\`、\`shift\`、\`win\`、\`capslock\`。
+- 鼠标按钮：\`left\`、\`right\`、\`middle\`、\`x1\`、\`x2\`。
+
+## 工具
+
+### screenshot()
+截取当前主屏（全屏）保存为 PNG，返回图片路径与尺寸。模型是多模态的，可直接看：
+screenshot() → 拿到 path → read_image(path) 查看屏幕 → 再做键鼠操作。
+
+### get_window()
+获取当前前台窗口信息：窗口句柄 hwnd、标题 title、进程名 process、pid、位置 (x,y,w,h)。
+用于确认目标窗口、拿到 hwnd 再定位或置顶。
+
+### win_rect(hwnd?)
+获取窗口位置与尺寸：传入 hwnd（来自 get_window），不传默认当前前台窗口。返回 x/y/w/h。
+
+### win_find(process)
+按进程名查找窗口：返回第一个匹配的窗口句柄 hwnd、标题、进程、pid、visible（是否可见，false 表示最小化到托盘）。用于替代鼠标点任务栏图标，定位并唤起某程序窗口。
+例：win_find('QQ') → 拿到 hwnd，再 win_activate(hwnd) 唤起 QQ 主窗口。
+
+### win_activate(hwnd)
+激活/前置指定窗口：自动处理最小化与"最小化到托盘（隐藏）"两种情况，再置前台。配合 win_find 使用，任务结束无需额外清理。
+
+### win_minimize(hwnd?)
+最小化指定窗口：传入 hwnd（来自 get_window），不传默认当前前台窗口。
+
+### win_restore(hwnd?)
+还原指定窗口：从最小化或最大化还原到之前大小。不传默认当前前台窗口。
+
+### win_maximize(hwnd?)
+最大化指定窗口。不传默认当前前台窗口。
+
+### win_top(hwnd, on)
+置顶（true）/取消置顶（false）指定窗口。置顶后窗口常驻最前。任务结束必须统一 release_top 取消。
+
+### release_top()
+取消所有本插件置顶过的窗口，恢复默认层级。任务结束时必须调用一次。
+
+### key_tap(key)
+按下并立刻抬起单个键（单个动作，不卡键）。用于点按、输入单字符或单个快捷键按键。
+例：key_tap('enter') 确认；key_tap('space') 翻页。
+
+### key_press(key)
+只按下某键、不抬起。用于组合键：先 key_press('ctrl')，再按其他键，最后 release_all。
+注意：必须配合 release_all 抬起，否则键会一直按住。
+
+### key_up(key)
+抬起某键。
+
+### mouse_press(button)
+只按下鼠标按钮、不抬起。用于按住左键拖动：mouse_press('left') → mouse_move(...) → release_all。
+
+### mouse_move(x,y)
+把鼠标绝对移动到屏幕坐标 (x,y)。
+
+### mouse_roll(up)
+滚动鼠标滚轮：up 为 true 滚上、false 滚下。
+
+### release_all()
+抬起所有仍被按住的键与鼠标按钮。每次键鼠操作结束后必须调用一次，避免卡键。
+
+## 返回
+
+每个工具返回 ok=true 表示该命令已交给系统；返回 error 表示参数或键名不合法。screenshot 还返回 path（PNG 绝对路径）、width/height（像素尺寸）。win_find 还返回 hwnd、title、process、pid、visible、x/y/w/h。
+
+## 典型组合
+
+- Ctrl+S 保存：key_press('ctrl')；key_tap('s')；release_all。
+- Ctrl+O 打开：key_press('ctrl')；key_tap('o')；release_all。
+- 左键拖拽：mouse_press('left')；mouse_move(x2,y2)；mouse_move(x1,y1)；release_all。
+- 滚到页面底部：mouse_roll(false)；mouse_roll(false)；…（可多次）。
+- 视觉闭环：screenshot() 得 path → read_image(path) 看屏幕 → 键鼠操作。
+- 唤起程序窗口（不点图标）：win_find('QQ') → win_activate(hwnd) → 前台出现 QQ 主窗口（托盘隐藏/最小化也能唤回）。
+
+## 规范
+
+1. 操作前先确认目标窗口与鼠标位置（可先 mouse_move 再观察结果）。
+2. 用组合键/按住后，结束统一调用 release_all。
+3. 置顶窗口后，任务结束统一调用 release_top 取消。
+4. 工具值是即时的：SendInput 微秒级生效，不需要等待。
+`;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@temsmie/dsh-tool-keymouse",
+  "description": "Windows key/mouse/screenshot/window automation (SendInput over a persistent helper) for the DeepSeek Harness",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./skill-content": {
+      "types": "./lib/skill-content.d.ts",
+      "default": "./lib/skill-content.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/skill-content.js",
+    "lib/**/*.d.ts",
+    "bin/helper-x64.exe",
+    "skills/keymouse.md",
+    "README.md",
+    "LICENSE",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/keymouse.md

@@ -0,0 +1,87 @@
+# 键鼠控制（KeyMouse）
+
+通过常驻 helper 用 SendInput 模拟真实键鼠输入，对当前前台窗口生效。所有工具调用结束后必须跑一次 release_all。
+
+## 坐标与键名
+
+- 坐标：绝对屏幕**物理**像素（helper 已 DPI-aware，无缩放换算），主屏左上角为 (0,0)，单屏。x 向右、y 向下。截图分辨率即物理像素，识图看到的坐标可直接用于 mouse_move，无需换算。
+- 键名（小写英文）：字母 `a`-`z`、数字 `0`-`9`、`space`、`enter`、`tab`、`esc`、`backspace`、`delete`、`insert`、`home`、`end`、`pageup`、`pagedown`、方向键 `up`/`down`/`left`/`right`、`f1`-`f12`、修饰键 `ctrl`、`alt`、`shift`、`win`、`capslock`。
+- 鼠标按钮：`left`、`right`、`middle`、`x1`、`x2`。
+
+## 工具
+
+### screenshot()
+截取当前主屏（全屏）保存为 PNG，返回图片路径与尺寸。模型是多模态的，可直接看：
+screenshot() → 拿到 path → read_image(path) 查看屏幕 → 再做键鼠操作。
+
+### get_window()
+获取当前前台窗口信息：窗口句柄 hwnd、标题 title、进程名 process、pid、位置 (x,y,w,h)。
+用于确认目标窗口、拿到 hwnd 再定位或置顶。
+
+### win_rect(hwnd?)
+获取窗口位置与尺寸：传入 hwnd（来自 get_window），不传默认当前前台窗口。返回 x/y/w/h。
+
+### win_find(process)
+按进程名查找窗口：返回第一个匹配的窗口句柄 hwnd、标题、进程、pid、visible（是否可见，false 表示最小化到托盘）。用于替代鼠标点任务栏图标，定位并唤起某程序窗口。
+例：win_find('QQ') → 拿到 hwnd，再 win_activate(hwnd) 唤起 QQ 主窗口。
+
+### win_activate(hwnd)
+激活/前置指定窗口：自动处理最小化与"最小化到托盘（隐藏）"两种情况，再置前台。配合 win_find 使用，任务结束无需额外清理。
+
+### win_minimize(hwnd?)
+最小化指定窗口：传入 hwnd（来自 get_window），不传默认当前前台窗口。
+
+### win_restore(hwnd?)
+还原指定窗口：从最小化或最大化还原到之前大小。不传默认当前前台窗口。
+
+### win_maximize(hwnd?)
+最大化指定窗口。不传默认当前前台窗口。
+
+### win_top(hwnd, on)
+置顶（true）/取消置顶（false）指定窗口。置顶后窗口常驻最前。任务结束必须统一 release_top 取消。
+
+### release_top()
+取消所有本插件置顶过的窗口，恢复默认层级。任务结束时必须调用一次。
+
+### key_tap(key)
+按下并立刻抬起单个键（单个动作，不卡键）。用于点按、输入单字符或单个快捷键按键。
+例：key_tap('enter') 确认；key_tap('space') 翻页。
+
+### key_press(key)
+只按下某键、不抬起。用于组合键：先 key_press('ctrl')，再按其他键，最后 release_all。
+注意：必须配合 release_all 抬起，否则键会一直按住。
+
+### key_up(key)
+抬起某键。
+
+### mouse_press(button)
+只按下鼠标按钮、不抬起。用于按住左键拖动：mouse_press('left') → mouse_move(...) → release_all。
+
+### mouse_move(x,y)
+把鼠标绝对移动到屏幕坐标 (x,y)。
+
+### mouse_roll(up)
+滚动鼠标滚轮：up 为 true 滚上、false 滚下。
+
+### release_all()
+抬起所有仍被按住的键与鼠标按钮。每次键鼠操作结束后必须调用一次，避免卡键。
+
+## 返回
+
+每个工具返回 ok=true 表示该命令已交给系统；返回 error 表示参数或键名不合法。screenshot 还返回 path（PNG 绝对路径）、width/height（像素尺寸）。win_find 还返回 hwnd、title、process、pid、visible、x/y/w/h。
+
+## 典型组合
+
+- Ctrl+S 保存：key_press('ctrl')；key_tap('s')；release_all。
+- Ctrl+O 打开：key_press('ctrl')；key_tap('o')；release_all。
+- 左键拖拽：mouse_press('left')；mouse_move(x2,y2)；mouse_move(x1,y1)；release_all。
+- 滚到页面底部：mouse_roll(false)；mouse_roll(false)；…（可多次）。
+- 视觉闭环：screenshot() 得 path → read_image(path) 看屏幕 → 键鼠操作。
+- 唤起程序窗口（不点图标）：win_find('QQ') → win_activate(hwnd) → 前台出现 QQ 主窗口（托盘隐藏/最小化也能唤回）。
+
+## 规范
+
+1. 操作前先确认目标窗口与鼠标位置（可先 mouse_move 再观察结果）。
+2. 用组合键/按住后，结束统一调用 release_all。
+3. 置顶窗口后，任务结束统一调用 release_top 取消。
+4. 工具值是即时的：SendInput 微秒级生效，不需要等待。