computer-use-advance
把 Windows 电脑操控能力挂进 DeepSeek Harness 的 DSH 插件。
挂上之后 agent 就能: 截图观察、移动/点击鼠标、敲键盘、枚举与激活窗口、切换输入法, 还能驱动 Krita 画画。
⚠️ 本仓库只包含给 AI 用的 MCP 部分 —— 它是一个没有界面的后台服务。
不提供托盘图标和全局热键: 那是"给人用"的另一种程序形态(main.py + ui/), 已从本仓库移除。
1 安装
从 GitHub 安装(推荐)
# 1) 装包(dsh plugin 只是把参数转发给 profile 目录里的 pnpm)
dsh plugin --profile web add github:iii993/computer-use-advance
# 2) 启用: 把 "computer-use-advance" 加进 profile 的 package.json -> dsh.profile.bundles
# 路径: $DSH_HOME/profiles/web/package.json
# 3) 重启 DSH(改动 profile 配置也会触发 cordis HMR 热加载)
从本地目录安装
dsh plugin --profile web add file:H:/cu-a
换机器 / 换路径
cordis.patch.yml 里的 python 与仓库路径是绝对路径。换机器跑一次即可自动改写:
powershell -ExecutionPolicy Bypass -File .\install.ps1
这个包由什么组成
| 文件 | 作用 |
|---|
package.json | dsh.bundle.patch 指向 patch —— dsh plugin add 靠这个字段识别它是插件 |
cordis.patch.yml | 向 profile 插入 mcp-computer / mcp-krita 两个 mcp-client 条目 |
lib/index.js | 空壳: 工具 schema 只在 computer_mcp/server.py 维护一份, 不在 JS 里重写 |
install.ps1 | 探测本机 python 与仓库路径并自动改写 patch |
2 工具清单(28 个)
挂载后 agent 会多出这些工具(前缀 mcp__computer__* / mcp__krita__*):
| 工具 | 用途 |
|---|
screenshot | 截取全屏(返回图像) |
get_state | 当前模式 / 光标位置 / 坐标口径 |
zoom / zoom_to_screen | 10X NEAREST 放大镜观察 + 放大图像素换算回坐标 |
list_windows | UIA 无障碍树窗口清单(支持 title 过滤与 wait_seconds 轮询) |
focus_window | 按 hwnd / 标题激活窗口(轮询确认前台真正切换完成才报成功) |
click / drag / slide | 鼠标操作; click 支持 hold_ms 长按、侧键 x1/x2、points 坐标序列 |
move | 只移动不点击, 支持 duration_ms 与 points+gap_ms |
scroll | 移动到指定位置后滚轮 |
press_key / key_down / key_up / combo | 键盘按键与组合键 |
type_text / send_text | 输入文字 / 输入并按组合键提交(如 ctrl+enter) |
get_input_method / switch_input_method | 查/切输入法 —— 中文输入法会吞掉注入的按键 |
switch_mode | 切换 game / draw / work 模式 |
draw_curve / draw_pressure_curve / set_brush | 绘画(曲线 / 压感 / 画笔) |
liquify / smudge | 液化 / 涂抹 |
set_config | 修改白名单内的配置项 |
check_vision | 检测当前模型是否支持图像输入 |
run_actions | 批量按顺序执行多个动作 |
📘 完整接口文档(坐标契约 / 每个工具的参数与返回 / Python API / 新增工具步骤)见 docs/MCP接口文档.md。
坐标口径(重要)
所有坐标类工具都支持 coord=image|screen:
image(默认): 坐标是最近一次 screenshot 返回图像内的像素screen: 屏幕物理像素- 返回值会回显
coord / img_size / screen_size, 可随时核对
3 环境要求
| 项 | 要求 |
|---|
| 系统 | Windows 10 / 11 |
| Python | 3.10+(开发环境 3.14) |
| 依赖 | pynput、Pillow(装到项目 vendor/, 不占 C 盘) |
| Krita 部分 | Krita 需在运行, 且已装 krita_mcp 桥接插件 |
cd H:\cu-a
python -m pip install --target vendor pynput Pillow
4 配置(config.json)
| 路径 | 默认 | 说明 |
|---|
| mouse.move_steps | 24 | 直线移动插值步数 |
| mouse.move_interval_ms | 5 | 每步间隔(ms) |
| mouse.jitter_px | 1.2 | 移动抖动幅度(px) |
| mouse.accel_curve | true | 加速减速曲线 |
| game.tap_interval_ms | 180 | 连点间隔(ms) |
| game.tap_jitter_ms | 30 | 连点间隔抖动(ms) |
| game.slide.smooth_ms | 800 | 滑动时长(ms) |
| game.slide.jitter_px | 2.0 | 滑动抖动(px) |
| game.slide.curve_bend | 0.06 | 弓形弯曲比例 |
| draw.sample_min_dist | 2 | 采样最小位移(px) |
| draw.rdp_epsilon | 4 | RDP 简化容差(px) |
| draw.bezier_segments | 8 | 贝塞尔细分点数 |
| draw.brush.step | 2 | 滚轮每格画笔增减 |
| draw.pen.pressure_min/max | 50/1024 | 压力范围 |
| draw.pen.slow_speed / fast_speed | 50/500 | 速度映射阈值(px/s) |
| work.typing.delay_min_ms / delay_max_ms | 40/120 | 打字速度范围 |
| work.typing.clipboard_threshold | 20 | 剪贴板输入阈值(字符) |
| ai.base_url / model / api_key | 对话相同 | AI 识图模型配置(check_vision 用) |
| ai.max_steps | 20 | AI 任务最大步数 |
| ai.screenshot_scale / quality | 1.0/85 | 截图缩放 / JPEG 质量 |
| ai.whitelist | 10 项 | set_config 可修改的白名单 |
hotkeys.* 字段仍在 config.json 里, 但已不生效 —— 全局热键属于已移除的桌面程序部分。
5 常见问题 (FAQ)
Q: DSH agent 调用 screenshot 报错?
A: DSH 对话模型不支持视觉时会收到 API 报错(正常现象)。在 DSH 设置里切换到支持视觉的模型即可。也可先调 check_vision 自检。
Q: 调 switch_input_method 前要注意什么?
A: 中文(微软拼音)输入法会拦截注入的按键 —— 按键不进目标程序, 甚至吞掉 KeyUp 造成"卡键"(角色一直往一个方向走)。玩游戏 / 连发按键前先 switch_input_method(layout="en"), 并用 get_input_method 复查 is_english=true。
Q: focus_window 返回 ok 了, 按键还是打到别的窗口?
A: SetForegroundWindow 是异步的。本项目已改为轮询确认前台真正切换完成才报成功, 并在返回值里给出 foreground / focus 供核对。若仍打偏, 检查是否有别的程序抢占前台。
Q: 改了 Python 代码不生效?
A: MCP 子进程是常驻的。重启 DSH, 或在 profile 配置里改一处触发 cordis HMR 重载。
Q: 工具描述 / 中文参数乱码?
A: Windows 下 Python 的 stdio 默认走 GBK。patch 里已设 PYTHONIOENCODING=utf-8。
Q: 绘画压力注入外部软件没效果?
A: WM_POINTER 注入对 Win32 传统绘图软件有效; 对 Chrome / UWP 等现代应用无效。可在目标软件中开启"鼠标模拟压力"选项。
Q: 如何让 agent 修改配置?
A: 通过 set_config 工具修改白名单内参数(见 ai.whitelist), 修改立即写入 config.json。
6 项目结构
computer_mcp/ MCP server(DSH 插件的入口, 28 个工具在这里注册)
computer_core/ 操控服务(截图 / 动作 / 白名单配置) + observe.py(10X 放大镜 / 像素反算) + uia.py(UIA 窗口观察)
input_engine/ 鼠标 / 键盘 / 文字 / 触笔压力注入 + ime.py(输入法控制)
modes/ 游戏 / 工作 模式(game/work 被 MCP 直接调用)
ai_mode/ AI 指挥官(识图检测 + 任务循环, 被 MCP 调用)
krita_mcp/ Krita 绘画桥接(MCP server + Krita 插件)
utils/ 配置 / 日志 / 几何算法(RDP)
docs/ 接口文档
tests/ unittest 测试套件
config.json 全部配置(首次运行自动生成)
vendor/ 本地依赖(不入库)
⚠ 免责声明
游戏模式的防检测抖动仅用于合规自动化场景(解放双手 / 辅助操作)。
请遵守目标软件的服务条款与所在地区法律法规。
