jonah791/computer-use

computer-use

让主脑（爱丽丝）自己看屏幕、自己操作鼠标键盘——从而独立走完「开发 → 验证 → 迭代」闭环，
不必再由主人充当眼睛和手。

DSH 插件（host-only）。6 个工具：截屏 · 窗口清单 · 聚焦 · 鼠标 · 键盘 · 环境自检。

为什么是它

改了 GUI 却要等主人帮忙看一眼，迭代速度就被"人"卡住了。本插件把 GUI 世界的感知（截屏 → 亲眼看）
与行动（鼠标键盘注入）变成工具面的一部分，闭环从此在我的循环里跑完。

工具

| 工具 | 说明 |
|---|---|
| cu_probe | 环境自检：屏幕 / 坐标空间 / DPI 声明 / 光标 / 前台窗口 / 窗口总数。行为异常时第一个调用它 |
| cu_screen | 截屏落盘（全屏 / 矩形 / 指定窗口，可缩放）→ 返回路径，交给官方的 read_image 亲眼看 |
| cu_windows | 窗口清单（标题 / 进程 / 位置 / 可见）或定点查询「这个坐标上是哪个窗口」 |
| cu_focus | 把窗口切到前台 |
| cu_mouse | move / click / double / drag / scroll |
| cu_key | 组合键（ctrl+s）与 Unicode 文本（中文也可）；verifyKey 可读回状态自证 |

坐标一律物理像素，与截图像素同空间——一格不用换算。

安全（重要）

cu_mouse / cu_key 是注入类工具，必须声明目标窗口：

cu_key({ keys: "ctrl+s", expectWindow: "Notepad" })     // 前台不是该窗口 → 拒绝执行
cu_mouse({ action: "click", x: 100, y: 200, expectHwnd: 123456 })

- 前台与期望不符 → 返回 INJECTION_REFUSED（fail-closed）；
- 确有需要时用 allowAnyWindow: true 显式放行；
- 闸有两层：工具面静态闸（判"有没有打算"）+ helper 原子闸（注入前一刻复核前台，防"打算了但前台被换掉"）。
- 这条不是凭空加的：2026-09-15 实测事故——测试脚本没找到目标却没停，39 个字符被注入到主人正在使用的窗口。

技术要点（改代码前先读）

1. 不落盘 exe：本机 Defender ASR 规则 01443614-… 禁止运行「全新未签名可执行文件」
（实测拦截我们自己编译的 probe.exe，事件 ID 1121）⇒ native 层只能 Add-Type 内存编译，
helper 必须保持 .ps1 + .cs 形态，不要"优化"成 exe。
2. 坐标一律物理像素：PowerShell 5.1 默认 DPI-unaware（1707×1067 逻辑空间），
helper 加载时调 SetProcessDPIAware()，之后光标读/写与截图同空间（实测 665 × 1.5 = 998）。
3. 每次调用独立进程：实测端到端 528ms（含进程启动 + C# 内存编译），无状态、无保活负担。
4. 注入前验靶：见上「安全」。

配置

| 项 | 默认 | 说明 |
|---|---|---|
| interpreter | C:/WINDOWS/System32/WindowsPowerShell/v1.0/powershell.exe | 本机唯一可用解释器（pwsh 不在 PATH） |
| helperPath | 空（按插件目录解析） | helper/cu-helper.ps1 |
| shotDir | E:/alice/_tmp_review/cu-shots | 截图输出目录 |
| tracePath | E:/alice/.dsh/computer-use-trace.jsonl | 侧车轨迹（一行一阶段） |
| timeoutMs | 30000 | 单次 helper 调用超时 |

测试

pnpm build && pnpm test        # 14 例纯逻辑单测（无需桌面）
node tests/smoke-helper.mjs    # 本机冒烟：能力 + 安全闸尸体测试 + 注入闭环（需桌面）

契约与边界

- 语义文档（不变量 / 契约 / 可证伪验收 / 未决问题）：docs/semantic.md
- 能力 ≠ 沙箱：本插件提供真实输入注入能力，与宿主同权限，不是安全边界。
- 注入成功 ≠ 目标应用接受（模态框、焦点抢占、UAC 提权窗口无法注入）。
- Windows 可能阻止后台进程抢焦点：cu_focus 的 apiOk 只是 API 返回值，以返回的 foreground 为准。

License

MIT