桌面操控 JohnXu22786/computer-control

computer-control — 桌面控制插件（for dsh）

让 agent 直接操作电脑桌面：截屏观察、鼠标/键盘注入、通过可访问性树实现的语义操作（语义优先、像素坐标兜底），并内置急停、允许/拒绝规则、确认流与空闲待机等安全护栏。

插件自包含、可被 dsh 直接加载：通过 manifest.json 声明工具与事件，以行分隔 JSON-RPC 2.0（stdio）为传输协议，python -m computer_control serve 即入口。

功能总览

| 能力 | 说明 |
| 截图 screen.capture | 全屏或区域截图，支持 PNG/JPEG、缩放、灰度——token 成本可控 |
| 鼠标 pointer. | 移动、左/中/右键单击（含双击/三击）、拖拽、滚轮（横/纵） |
| 键盘 keyboard. | 单键、组合键（扫描码注入，与键盘布局无关）、任意 Unicode 文本输入 |
| 等待 wait.pause | 动作间暂停，让界面稳定后再截图 |
| 语义操作 a11y. | 可访问性树分级摘要（skeleton/standard/full）、语义激活/输入——先走 UIA 模式，失败自动降级为包围盒像素点击 |
| 批量 batch.execute | 一次调用执行多个动作，减少模型往返；可整批确认、可遇错继续 |
| 能力广播 | tools.list/system.status 报告各后端是否可用，语义工具仅在 UIA 可用时暴露 |

安全护栏（详见「安全」一节）：

- 急停：全局热键（默认 Ctrl+Alt+F12，可配）、协议指令、panic 文件三重触发；屏幕角落显示 STOP 横幅
- 允许/拒绝规则：按工具名与参数匹配，拒绝永远优先；可切换白名单模式
- 确认流：高风险动作（含 win 键或 ctrl+alt 的组合键等）等待人工批准，超时自动拒绝
- 空闲待机：无操作超过阈值自动进入待机，拒绝一切动作直到恢复
- 演练模式：platform: "dry-run" 只记录不执行，用于安全排练

目录结构

computer-control/
├── manifest.json # dsh 插件清单（工具/事件/入口/传输） ├── pyproject.toml # 打包元数据与依赖声明 ├── requirements.txt # 核心依赖（仅 Pillow） ├── requirements-optional.txt# 可选能力依赖（UIA/mss/热键） ├── README.md ├── docs/ # integration / protocol / actions / configuration ├── examples/ # 配置示例、会话示例、演示脚本 ├── computer_control/ # 插件实现（Python 包） │ ├── cli.py __main__.py # 入口：serve / check / list │ ├── session.py # 会话生命周期与动作串行执行 │ ├── engine.py # 动作执行引擎（坐标映射、事件） │ ├── policy.py # 安全门：规则/确认/急停/看门狗 │ ├── actions.py # 动作注册表与参数校验
│ ├── geometry.py # 模型画布 <-> 物理像素 映射
│ ├── protocol.py server.py# JSON-RPC 路由与 stdio/HTTP 传输 │ ├── client.py # 供 harness/脚本使用的客户端 │ ├── overlay.py # 急停可视横幅（可选，tkinter） │ ├── drivers/ # 执行层抽象 + windows 实现 + 演练驱动 │ └── a11y/ # 可访问性树摘要 + Windows UIA 桥 └── tests/ # 纯逻辑与协议测试（不触碰真实硬件）

在 dsh 中安装

dsh plugin --profile demo add github:JohnXu22786/computer-control

卸载：

dsh plugin --profile demo remove computer-control

dsh bundle

仓库同时提供 Cordis bundle，凡是消费 dsh.bundle 清单的环境都可以同样方式安装：package.json 声明 dsh.bundle.patch 指向 cordis.patch.yml，index.js 即 dsh profile 加载的桥接层。它以子进程方式启动 python -m computer_control serve，把 manifest.json 中声明的全部工具经 stdio 协议重新暴露给 harness—— Python 核心保持不变。profile 级设置可通过 patch 行的 config 固定（例如 platform.name: dry-run 实现只演练安装）。

桥接层要求：node >= 18 和 Python 3.9+。请将本包及其核心依赖安装到 dsh 使用的 Python 环境中；以下命令可在任意目录运行：

python -m pip install git+https://github.com/JohnXu22786/computer-control.git

安装

要求：Python 3.9+，Windows 10/11（完整功能）；其他平台见「平台支持」。

核心（截图 + 输入注入）
python -m pip install .

可选能力（推荐）： comtypes -> 可访问性树（UIA）语义操作 mss -> 更快的多显示器截图后端
pip install -r requirements-optional.txt

自检环境：

python -m computer_control check

输出平台、DPI 模式、虚拟桌面几何、截图后端、UIA 可用性、热键等诊断。

快速开始

查看声明的工具与事件
python -m computer_control list

启动插件服务（stdio，供 dsh 加载）
python -m computer_control serve

用 examples/demo.py 跑一个演练会话（默认 dry-run，不触碰真实桌面）：

python examples/demo.py

dsh 接入（摘要）

完整接入说明见 docs/integration.md。

1. 加载：dsh 读取 manifest.json，按 entry.command 启动进程，建立 stdio 管道（UTF-8，一行一个 JSON 对象）。
2. 生命周期：先发 session.start（可带配置）→ 收到 session.started 事件后即可调用工具；结束发 session.stop。
3. 调用动作：tools.call（单个）或 tools.call_batch（批量）。响应统一为 {ok, result, error, meta} 信封。
4. 事件：服务端以 event 通知推送 action.started/finished、safety.confirmation_requested 等。
5. 确认流：高风险动作返回 awaiting_confirmation 并发出确认事件；harness 应弹出人工确认，再以 session.confirm 批复；超时自动拒绝。

模型调用动作的推荐循环：screen.capture 观察 → 用画布坐标执行 pointer./a11y. → wait.pause（如需）→ 新截图验证结果。

动作指南（摘要）

全部动作、参数与示例见 docs/actions.md。

| 动作 | 作用 | 风险 |
| screen.capture | 截图（区域/格式/缩放/灰度） | 无 |
| pointer.move | 移动指针 | 中 |
| pointer.click | 单击/双击/三击，可选位置 | 中 |
| pointer.drag | 按住拖拽 | 中 |
| pointer.scroll | 滚轮（横/纵） | 中 |
| keyboard.press | 单键 | 中 |
| keyboard.combo | 组合键（含 win 或 ctrl+alt 时升级为高） | 中/高 |
| keyboard.type | 文本输入（Unicode） | 中 |
| wait.pause | 暂停 | 无 |
| a11y.snapshot | 可访问性树分级摘要 | 无 |
| a11y.activate | 语义激活（模式优先，像素兜底） | 中 |
| a11y.input | 语义文本输入（Value 模式优先） | 中 |
| batch.execute | 批量执行 | 取各项最大风险 |

坐标契约

模型看到的是画布而非原始屏幕：截图被缩放到以 display_width_px（默认 1920）为宽的等比例画布，模型返回的坐标就在这个画布上；插件按 scale = 物理宽 / 画布宽 均匀映射回物理像素后执行。screen.capture 结果中带有 canvas 字段与 display_width_px/display_height_px，模型以此为准。多显示器（含主屏左侧/上方的负坐标区域）与每显示器 DPI 均已在执行层处理。

安全

详见 docs/configuration.md 与 README 下方要点：

- 急停（三重）：默认全局热键 Ctrl+Alt+F12（配置 safety.emergency_hotkey，可置空禁用）；协议方法 control.panic；panic 文件（safety.panic_file，存在即停）。急停后所有动作返回 safety_stopped；session.resume 或再次按热键恢复。急停生效时桌面角落显示红色 STOP 横幅（safety.visual_indicator）。
- 允许/拒绝规则（safety.rules）：{match: {tool: "keyboard.", argument: {name, matcher, value}}, effect: "deny"}；拒绝规则永远优先于允许。safety.default_rule: "deny" 可切换为白名单模式（未显式允许的动作一律拒绝）。规则可运行时通过 session.configure 调整。
- 确认流：safety.confirm_threshold（默认 high）决定哪些风险等级需要人工批准；safety.confirm_timeout_s（默认 30s）超时自动拒绝。批准后动作照常执行并发出 action.finished。
- 空闲待机：safety.idle_timeout_s 大于 0 时启用，无操作超时进入待机（session.idle 事件），session.resume 恢复；idle_action: "none" 则只发事件不停摆。
- 演练模式：platform: "dry-run" 下一切动作只记录不执行，便于接入联调与安全排练。

平台支持

| 平台 | 驱动 | 说明 |
| Windows | drivers/windows.py | 完整实现：SendInput 扫描码注入、每显示器 DPI 感知、虚拟桌面坐标、mss/Pillow 截图、UIA 语义层 |
| macOS / Linux | 接口已抽象 | drivers/base.py 定义了完整驱动契约（capture/pointer/keys/a11y/hotkey）；按契约实现对应平台驱动即可接入（drivers/windows.py 提供了完整示例）。未实现前 platform: "auto" 会给出明确报错 |
| 任何平台 | drivers/dummy.py | 演练驱动：记录一切动作，不触碰硬件 |

依赖与降级：

- Pillow（必需）：截图与编码。缺失时插件拒绝启动。
- mss（可选）：Windows 上更快、多显示器更可靠；缺失自动回退 Pillow ImageGrab。
- comtypes（可选）：UIA 语义操作。缺失时 a11y.* 工具在 tools.list 中标记为不可用，调用返回 backend_unavailable——像素坐标路径（截图+点击）不受影响。
- keyboard（可选，预留）：macOS/Linux 驱动的全局热键将依赖它；当前仅 Windows 与演练驱动随插件发布，Windows 内置 GetAsyncKeyState 轮询，无需该包。

已知限制：

- 安全注意序列（如 Ctrl+Alt+Del）无法通过输入注入触发——系统级保护，插件同样无法绕过。
- UIA 依赖目标程序暴露可访问性接口；不暴露的程序（部分游戏、自绘 UI）只能走像素路径。
- 键盘扫描码注入对 DirectInput/raw input 程序更友好，但仍可能被部分反作弊类程序拒绝（属正常防护行为）。

测试

python -m unittest discover -s tests -v

测试全部使用纯逻辑与演练驱动，不注入真实输入、不触碰真实硬件；Windows 真实链路由 python -m computer_control check 与 examples/demo.py --live 人工验证。