computer-use-plus

低 token、低延迟的 Windows computer-use MCP 服务。服务按“预测记忆 -> Windows UIA/Win32 或浏览器 CDP Accessibility Tree -> 本地坐标 OCR -> 严格结构化视觉”逐级选择识别方式，在本地完成语义定位、输入执行、动作批处理、验证和记忆更新。

环境

• Windows 10/11

• Node.js 20 或更高版本

• PowerShell 5.1（系统自带即可）

当前运行时不依赖 npm 第三方包，也不要求安装 .NET SDK。首次创建专用桌面时，PowerShell 5.1 会用系统自带 C# 编译器生成约十几 KB 的本地代理，并按源码哈希缓存在数据目录。

Related MCP server: EZComputerCtrl MCP

启动

在项目目录执行：

npm start

服务使用 MCP JSON-RPC stdio，每行接收一个 JSON 请求并输出一行 JSON 响应。MCP 客户端配置示例：

{
  "mcpServers": {
    "computer-use-plus": {
      "command": "node",
      "args": ["D:/projects/computer-use-plus/src/index.js"]
    }
  }
}

本地记忆、隔离代理和运行日志默认写入项目下的 .data/，可通过 COMPUTER_USE_PLUS_DATA_DIR 指定目录。Windows 默认启用 backgroundOnly：computer.state、computer.inspect 和 computer.act 都只操作专用执行桌面。仅调试旧的前台模式时可设置 COMPUTER_USE_PLUS_EXECUTION_MODE=foregroundAllowed。

当前工具

• computer.state：窗口、焦点、能力、记忆统计、运行指标和专用执行桌面状态；includeUi: true 时返回一次可直接操作的紧凑 UI 快照、短期 ref 和最近状态转换。

• computer.inspect：按窗口和文本/角色查询 UIA 元素；UIA 找不到目标时可对隔离窗口执行 PrintWindow 截图并交给本地 OCR，截图只在 .data 中短暂存在。

• computer.wait：按窗口标题/进程/类名或元素文本/角色等待出现或消失，减少跨应用流程中的固定延迟。

• computer.screenshot：默认只返回最多 20 个窗口的边界元数据；传 mode: "image" 才返回短期 base64 图像。

• computer.act：批量执行 click、setValue、hotkey、keys 和 wait。

• computer.fast：可选的低延迟 AI 只规划并执行当前动作，不写长期记忆。

• computer.shortcut：由主 AI 显式保存、列出、运行或整理命名动作链；支持单窗口和独立的跨窗口作用域。

• computer.execution：创建、启动应用、查看状态或销毁 Windows 专用执行桌面；diagnose 会只读返回该 desktop 的窗口、启动根进程和 Job Object 内存活进程。该桌面不会被切换到用户前台。

• computer.browser：使用项目 .data 下的独立浏览器 profile，通过 CDP 页面目标、Accessibility Tree 和 DOM 边界操作公开页面；支持 launch、list、inspect、click、setValue、keys 和 stop，不会连接用户现有浏览器 profile。

服务端在每次 computer.act 后自动更新底层 UI 定位记忆，模型不能直接改写定位器和状态转换统计；主 AI 可以通过 computer.shortcut 显式管理可复用动作链。 computer.state.metrics 只负责累计动作策略、OCR 次数与耗时、截图次数和实际图像字节数，用于成本/延迟评估；它不是动作链本体。供模型一次规划完整链路的数据来自 computer.state.snapshot、最近 transitions 和已保存的 computer.shortcut。 缓存定位器失效时，服务会自动降权并先用原始 UIA 查询重新发现，只有 UIA 失败才进入 OCR，OCR 无法消歧且视觉 provider 已配置时才进入结构化视觉；代理启动时还会清理过期临时截图、旧日志和旧版本代理二进制。

一次规划与 Shortcut

先获取一次 action-ready 快照：

{"window":"123","includeUi":true,"maxNodes":30,"includeTransitions":true}

模型随后可以用快照中的 ref 一次提交完整动作链：

{"window":"123","actions":[{"click":{"ref":"s1n1"}},{"wait":{"seconds":0.3}},{"click":{"ref":"s1n2"}}]}

高层等待统一使用秒并允许小数，0.3 表示 300 毫秒。只有精确键盘时间轴 kbops.at 保留毫秒；执行层会把秒换算为整数毫秒。

主 AI 可以显式保存模板化 shortcut，后续复用不需要再次调用 AI。可选 AI 配置和用户拒绝时的跳过流程见 agent.md。快速 AI 与整理 AI 使用同一个 API key，不配置也不影响本地功能：

$env:COMPUTER_USE_PLUS_AI_KEY_FILE='C:\path\to\provider-key.txt'
$env:COMPUTER_USE_PLUS_AI_BASE_URL='https://api.openai.com/v1'
$env:COMPUTER_USE_PLUS_AI_MODEL='gpt-4o-mini'

{"action":"save","scope":"single","window":"123","name":"切换资源包","params":{"name":"objmc","mywait":0.3},"actions":[{"wait":{"seconds":"{{mywait}}"}}]}
{"action":"run","window":"123","name":"切换资源包","params":{"name":"objmc","mywait":0.3}}

跨窗口动作使用窗口别名和独立的有序窗口路径，不会与单窗口记忆竞争：

{"action":"save","scope":"cross","name":"下载并打开","windows":{"browser":"123","explorer":"456"},"actions":[{"window":"browser","click":{"text":"Download"}},{"window":"explorer","click":{"text":"Open"}}]}

organize 默认只返回本地脚本无法确定的候选；明确传入 useAi:true 才调用共享 API key 的整理 AI，但默认只返回 proposal，不会修改长期记忆。主 AI 可以通过 apply 明确执行 merge、rename 或 archive；也可以在请求 AI 整理时同时传入 applyAi:true，明确应用 AI proposal。状态中的 memory.organization.due 仅表示达到低频整理阈值，不会自动在每次操作后调用 AI。

开发验证

npm test

npm test 包含专用执行桌面的真实 Windows 集成测试，适合有交互桌面的本机。GitHub-hosted Windows runner 不具备可捕获的隔离 desktop，因此 CI 运行 npm run test:ci：覆盖全部单元测试、FFmpeg 本地媒体流程、MCP stdio 协议和 Harness 工具档；专用桌面端到端验收仍在真实 Windows 桌面环境执行。

无 Windows UIA 环境时可用模拟驱动验证协议和动作事务：

$env:CUP_MOCK='1'
npm start

已知范围

视觉 provider 通过可选 API key 启用；它只接收受限局部截图，并且必须返回布局 schema，不能直接返回动作。预测快照保存节点摘要、环境兼容条件和验证统计，不保存长期截图。隔离模式禁止全局物理坐标输入，代理会拒绝不属于专用 desktop 的 HWND；优先使用 UIA Pattern，原生 HWND 控件降级为窗口消息，OCR/视觉坐标点击也转换为隔离窗口消息。wait.state 暂时会明确返回不支持，避免将未经验证的延迟误报为成功。

专用执行桌面

专用桌面会在第一次状态查询或动作时自动创建，也可以显式创建后启动应用：

{"action":"create"}
{"action":"launch","commandLine":"notepad.exe"}

专用桌面中的 agent 通过命名管道受主服务管理，不调用 SwitchDesktop，因此不会抢占用户正在使用的桌面。窗口枚举、UIA 检查、点击、ValuePattern 输入和键盘序列都由该 agent 执行；启动的进程会在恢复运行前加入带 KILL_ON_JOB_CLOSE 的 Windows Job Object，销毁或异常退出时由内核回收整个进程树。

紧凑键盘动作示例：

{"window":"12345","actions":[{"kbseq":["w","a","a","s"]}]}
{"window":"12345","actions":[{"kbops":[{"op":"w","at":0},{"op":"a","at":1000},{"op":"s","at":2000},{"op":"d","at":3000}]}]}

kbops.at 是相对本批动作起点的绝对毫秒值，服务端会转换为相邻按键间延迟，模型不需要重复计算等待动作。

Native tool-call 快速路径

快速 AI 优先返回协议级工具调用，而不是可见的长文本 JSON。MCP 客户端也可以直接调用 computer.invoke 或 shortcut.run：

{"window":"123","shortcut_id":"switch_resource_pack","params":{"name":"objmc","wait_seconds":5}}

服务端会在本地校验参数、解析 shortcut、执行 UIA/CDP/OCR 路径，并只返回增量结果。旧的 computer.act 和 JSON actions 仍然兼容。

支持 OpenAI-compatible chat completions、Responses、Anthropic Messages 和 Gemini function calling。provider 不会直接执行电脑动作，所有动作都经过本地窗口、权限和风险校验。

本地 action-ID 路由支持注入可选分类器。确定性的名称、ID 和别名匹配始终优先；只有未命中时才调用分类器。分类器只能从当前窗口作用域已有 shortcut 中返回一个 ID，默认置信度阈值为 0.85，未知 ID 或低置信度结果会被拒绝并回退到快速 AI/常规观察。computer.state.metrics 会记录 classifierCalls、classifierHits 和 classifierLatencyMs。

Benchmark

npm run benchmark -- .data/benchmark-samples.json .data/benchmark-summary.json

样本支持 application、strategy、success、latencyMs、token、MCP 往返、截图次数/字节和失败原因，输出 P50/P95、成功率、分应用统计和累计成本。

真实应用 Benchmark Suite

docs/benchmarks/ 内置 Edge、Minecraft、微信的声明式 smoke suite。默认只做 dry-run：校验 Windows 平台、独立应用启动命令和步骤结构，不启动应用，也不会操作用户前台桌面。

npm run benchmark:suite -- docs/benchmarks/edge.json

在已配置独立应用启动命令后，才可显式执行（会创建专用执行桌面，并且执行 suite 中的操作）：

npm run benchmark:suite -- docs/benchmarks/edge.json --execute --output .data/edge-benchmark.json

真实执行需要将 runner 接入 MCP 客户端，并显式提供独立实例启动配置。使用以下环境变量作为前置条件，而不是复用用户现有实例：

• COMPUTER_USE_PLUS_BROWSER_EXECUTABLE

• COMPUTER_USE_PLUS_MINECRAFT_COMMAND

• COMPUTER_USE_PLUS_WECHAT_COMMAND

验证与风险策略

computer.verify 支持窗口指纹、标题、元素状态、CDP URL 与允许目录内文件的断言。每项结果包含 expected、actual、passed。

高风险动作默认需要一次性确认令牌。可通过 COMPUTER_USE_PLUS_RISK_POLICY_FILE 指向 JSON 策略文件；示例见 risk-policy.example.json。策略可按进程和窗口标题匹配并给出 allow、confirm 或 deny，跨窗口 shortcut 以整条动作链生成确认摘要。

DeepSeek Harness

DeepSeek Harness 可通过官方 @deepseek-ai/dsh-mcp-client 直接连接本服务。Harness 当前要求 Node.js ^22.19.0 或 >=24。先为目标 profile 安装 bridge 依赖，再把 adapters/deepseek-harness/cordis.yml 作为 --patch 传入；它是可直接加载的 insert overlay。项目不位于默认位置时设置 COMPUTER_USE_PLUS_ROOT。

适配档只公开六个高层、下划线命名的工具，避免 Harness 对点号工具名进行哈希化：shortcut_run、computer_invoke、computer_state、computer_inspect、computer_verify、computer_cancel。完整配置和调用原则见 adapter README。