Computer Use

这是什么

Computer Use 为千手大师提供一套桌面操作能力。它以一个 MCP Server 的形式挂载进主 CLI，服务名固定为 computer-use，工具名形如 mcp__computer-use__<tool>。模型通过这些工具截取屏幕、生成鼠标键盘事件、读写剪贴板、枚举与管理应用窗口。

它的工作是分级的：会话启动时会自动注册这个 MCP Server 并把工具加入允许列表，但任何实际操作前都必须先由模型调用 request_access 向用户申请权限。用户在对话框里批准一组应用后，本次会话才能对这些应用执行截图与输入操作。

平台与权限

三个平台的后端实现方式不同，能力完整度也不同。下表以仓库源码为准。

macOS 系统授权

macOS 需要两项 TCC 权限：辅助功能（Accessibility）与屏幕录制（Screen Recording）。权限缺失时，首次 request_access 不会显示应用列表，而是显示一个 TCC 面板，提供两个选项直接跳转系统设置，并在授权后选择「Try again」重试：

• Open System Settings → Accessibility
• Open System Settings → Screen Recording

Windows 与 Linux 依赖

安装与启用

Computer Use 由编译期 feature flag CHICAGO_MCP 控制，该 flag 已包含在默认构建列表中。日常开发与构建无需额外开关，只有需要显式指定时才手动开启。

1. 确认 feature flag 已启用：开发模式下所有 feature 默认开启；构建产物默认包含 CHICAGO_MCP。如需显式指定，用环境变量形式：
   启用 CHICAGO_MCP 复制

   # 显式指定 CHICAGO_MCP 后启动
   FEATURE_CHICAGO_MCP=1 qsdashi

2. 启动一个交互式会话：
   启动会话 复制

   qsdashi

3. 用自然语言提出任务，例如「打开记事本并输入一段文字」。模型会先调用 request_access，弹出权限申请对话框。
4. 在对话框中批准应用。macOS 若尚未授权 TCC，会先出现系统权限面板（辅助功能 / 屏幕录制），授权后点「Try again」；授权完成后再选择允许的应用。
5. 后续操作自动执行。经批准的应用在本次会话内保持授权，mcp__computer-use__* 工具已加入允许列表，不再逐次弹窗。

独立 MCP Server

Computer Use 本身是一个标准的 stdio MCP Server，可以脱离主 CLI 单独启动，供任意 MCP 客户端使用：

qsdashi --computer-use-mcp

该命令通过 stdio 传输协议通信，收到 stdin 关闭时退出。对应的客户端配置示例：

{
  "mcpServers": {
    "computer-use": {
      "command": "qsdashi",
      "args": ["--computer-use-mcp"]
    }
  }
}

工具与能力

工具按平台分为三组：全平台通用工具 24 个、Windows 专属工具 11 个、教学模式工具 3 个（共 38 个）。通用工具在未绑定窗口时，操作对象是整个屏幕。

通用工具（全平台）

Windows 专属工具

仅在 Windows 平台可见，核心是绑定窗口后的独立操作——通过窗口消息直达目标 HWND，不抢占焦点、不移动真实鼠标键盘。

教学模式工具

request_teach_access · teach_step · teach_batch 三个工具仅在 teachMode 开启时可用，用于把操作拆成分步引导提示。默认关闭。

配置项

Computer Use 的运行时子开关由动态配置 tengu_malort_pedway 读取，普通用户无需修改。下表是离线或未下发配置时的默认值。

实战示例

以下是模型侧工具调用序列的示意，用于说明典型流程。用户只需用自然语言描述任务，模型会自行组织这些调用。

流程一：全屏操作

request_access(apps=["Notepad"], reason="输入并保存一段文本")
open_application(app="Notepad")     # Windows 上自动绑定窗口
screenshot
left_click(coordinate=[500, 300])
type(text="hello world")
key(text="ctrl+s")

流程二：绑定窗口操作（Windows，不干扰用户）

request_access(apps=["Notepad"])
bind_window(action="list")
bind_window(action="bind", title="记事本")
screenshot                                      # PrintWindow 截取绑定窗口
virtual_mouse(action="click", coordinate=[500, 300])
virtual_keyboard(action="type", text="hello world")
virtual_keyboard(action="combo", text="ctrl+s")
mouse_wheel(coordinate=[500, 400], delta=-5)
bind_window(action="unbind")

流程三：按元素名称操作（Windows）

bind_window(action="bind", title="记事本")
screenshot                                        # 附带 GUI 元素列表
click_element(name="保存", role="Button")
type_into_element(role="Edit", text="new content")

常见问题与排错