桌面电脑自动化

关键规则 — 违反将导致工作流中断：

永远不要在后台运行 midscene 命令。 每个命令必须同步运行，以便你可以读取其输出（尤其是截图），然后再决定下一步操作。后台执行会破坏截图-分析-操作的循环。

一次只运行一个 midscene 命令。 等待上一个命令完成，读取截图，然后决定下一步操作。永远不要将多个命令链接在一起。

为每个命令留出足够的完成时间。 Midscene 命令涉及 AI 推理和屏幕交互，可能比普通 shell 命令耗时更长。典型命令需要约 1 分钟；复杂的 act 命令可能需要更长时间。

完成前始终报告任务结果。 完成自动化任务后，你必须主动向用户总结结果 — 包括找到的关键数据、完成的操作、拍摄的截图以及任何相关发现。永远不要在最后一个自动化步骤后默默结束；用户期望在单次交互中获得完整响应。

只最小化窗口，除非明确要求否则不要关闭。 当你需要隐藏或移开窗口时，最小化它而不是关闭。除非用户明确要求，否则不要关闭任何应用或窗口。

使用 npx @midscene/computer@1 控制桌面（macOS、Windows、Linux）。每个 CLI 命令直接映射到一个 MCP 工具 — 你（AI 代理）作为大脑，根据截图决定采取哪些操作。

`act` 能做什么

在桌面上的单次 act 调用中，Midscene 可以移动鼠标、点击、双击、右键点击、拖拽项目、输入或清除文本、滚动、按下单个键或键盘快捷键，并在所选显示器上可见的内容上完成多步交互。

前置要求

Midscene 需要具有强大视觉定位能力的模型。必须配置以下环境变量 — 可以作为系统环境变量或在当前工作目录的 .env 文件中配置（Midscene 会自动加载 .env）：

MIDSCENE_MODEL_API_KEY="your-api-key"
MIDSCENE_MODEL_NAME="model-name"
MIDSCENE_MODEL_BASE_URL="https://..."
MIDSCENE_MODEL_FAMILY="family-identifier"

示例：Gemini (Gemini-3-Flash)

MIDSCENE_MODEL_API_KEY="your-google-api-key"
MIDSCENE_MODEL_NAME="gemini-3-flash"
MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_FAMILY="gemini"

示例：通义千问 3.5

MIDSCENE_MODEL_API_KEY="your-aliyun-api-key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
# 如果使用 OpenRouter，设置：
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

示例：豆包 Seed 2.0 Lite

MIDSCENE_MODEL_API_KEY="your-doubao-api-key"
MIDSCENE_MODEL_NAME="doubao-seed-2-0-lite"
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_FAMILY="doubao-seed"

常用模型：豆包 Seed 2.0 Lite、通义千问 3.5、智谱 GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

如果模型未配置，请要求用户设置。参见模型配置了解支持的提供商。

命令

连接到桌面

npx @midscene/computer@1 connect
npx @midscene/computer@1 connect --displayId <id>

列出显示器

npx @midscene/computer@1 list_displays

截屏

npx @midscene/computer@1 take_screenshot

截屏后，读取保存的图像文件以了解当前屏幕状态，然后再决定下一步操作。

执行操作

使用 act 与电脑交互并获取结果。它在内部自主处理所有 UI 交互 — 点击、输入、滚动、等待和导航 — 因此你应该将复杂的高层任务作为整体给出，而不是分解成小步骤。用自然语言描述你想做什么以及期望的效果：

# 具体指令
npx @midscene/computer@1 act --prompt "在搜索框中输入 hello world 并按回车"
npx @midscene/computer@1 act --prompt "将文件图标拖到回收站"

# 或目标导向指令
npx @midscene/computer@1 act --prompt "使用 Chrome 浏览器搜索上海天气，告诉我结果"

使用参考图像精确定位

当用户提供截图、图标、徽标或参考图像并希望精确视觉匹配时，优先使用 tap --locate 而不是通用的 act --prompt。将 --locate 作为 JSON 传递。prompt 描述目标，images 提供命名参考图像，当图像 URL 可能无法被模型直接访问时，convertHttpImage2Base64: true 很有用。

npx @midscene/computer@1 tap --locate '{
  "prompt": "点击包含图像的区域",
  "images": [
    {
      "name": "目标图像",
      "url": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
    }
  ],
  "convertHttpImage2Base64": true
}'

相同的 locate JSON 格式也适用于其他接受 locate 参数的命令。

断开连接

npx @midscene/computer@1 disconnect

工作流程模式

由于 CLI 命令在调用之间是无状态的，请遵循以下模式：

连接建立会话
健康检查 — 观察 connect 命令的输出。如果 connect 已执行健康检查（截图和鼠标移动测试），则无需额外检查。如果 connect 未执行健康检查，手动执行：截屏并验证成功，然后将鼠标移动到随机位置（act --prompt "将鼠标移动到随机位置"）并验证成功。如果任一步骤失败，停止并排除故障后再继续。只有在两项检查都无错误通过后，才能继续下一步。
启动目标应用并截屏 查看当前状态，确保应用已启动并在屏幕上可见。
执行操作 使用 act 执行所需操作或目标导向指令。
断开连接 完成后
报告结果 — 总结完成的内容，呈现任务期间提取的关键数据和发现，列出所有生成的文件（截图、日志等）及其路径

最佳实践

始终先运行健康检查：连接后，观察 connect 命令的输出。如果 connect 已执行健康检查（截图和鼠标移动测试），则无需额外检查。如果没有，手动执行：截屏并移动鼠标到随机位置。两者都必须成功（无错误）才能继续任何进一步操作。这可以尽早发现环境问题。
使用此技能前将目标应用置于前台：为了最佳效率，在调用任何 midscene 命令之前，使用其他方式将应用置于前台（例如 macOS 上的 open -a <AppName>，Windows 上的 start <AppName>）。然后截屏确认应用确实在前台。只有在视觉确认后，才能使用此技能进行 UI 自动化。避免通过 midscene 使用 Spotlight、开始菜单搜索或其他基于启动器的方法 — 它们涉及临时 UI、多个 AI 推理步骤，且明显更慢。
对 UI 元素要具体：不要使用模糊描述，提供清晰、具体的细节。说 "Safari 窗口左上角的黄色最小化按钮" 而不是 "按钮"。
尽可能描述位置：通过描述位置来帮助定位元素（例如 "菜单栏右上角的图标"、"左侧边栏的第三项"）。
永远不要在后台运行：每个 midscene 命令必须同步运行 — 后台执行会破坏截图-分析-操作循环。
检查多个显示器：如果你启动了应用但在截图上看不到，应用窗口可能已在其他显示器上打开。使用 list_displays 检查可用显示器。你有两个选择：要么将应用窗口移动到当前显示器，要么使用 connect --displayId <id> 切换到应用所在的显示器。
将相关操作批量放入单个 act 命令：在同一应用中执行连续操作时，将它们合并到一个 act 提示中，而不是分成多个命令。例如，"搜索 X，点击第一个结果，向下滚动查看更多详情"应该是单个 act 调用，而不是三个。这减少了往返，避免不必要的截图-分析循环，且明显更快。
运行前设置 PATH（macOS）：在 macOS 上，如果 PATH 不完整，某些命令（例如 system_profiler）可能找不到。在运行任何 midscene 命令之前，确保 PATH 包含标准系统目录：
```
export PATH="/usr/sbin:/usr/bin:/bin:/sbin:$PATH"
```
这可以防止因缺少系统工具而导致的截图失败。
完成后始终报告结果：完成自动化任务后，你必须主动向用户呈现结果，而不是等待他们询问。这包括：(1) 用户原始问题的答案或请求任务的结果，(2) 执行期间提取或观察到的关键数据，(3) 截图和其他生成的文件及其路径，(4) 所采取步骤的简要总结。不要在最后一个自动化命令后默默完成 — 用户期望在单次交互中获得完整结果。
提供参考图像时优先使用 tap --locate：如果用户分享截图、图标或徽标并希望精确定位该视觉目标，使用 tap --locate 和多模态 locate JSON 对象，如 { "prompt": "...", "images": [...] }，而不是仅依赖 act --prompt。

示例 — 上下文菜单交互：

npx @midscene/computer@1 act --prompt "右键点击文件图标并从上下文菜单中选择删除"
npx @midscene/computer@1 take_screenshot

示例 — 下拉菜单：

npx @midscene/computer@1 act --prompt "打开文件菜单并点击新建窗口"
npx @midscene/computer@1 take_screenshot

故障排除

macOS：无障碍权限被拒绝

你的终端应用没有无障碍访问权限：

打开 系统设置 > 隐私与安全 > 无障碍
添加你的终端应用并启用
授予权限后重启终端应用

macOS：未找到 Xcode 命令行工具

xcode-select --install

API 密钥未设置

检查 .env 文件包含 MIDSCENE_MODEL_API_KEY=<your-key>。

macOS：截图失败，提示 `system_profiler` 未找到

如果 take_screenshot 失败并显示类似 system_profiler: command not found 的错误，PATH 环境变量可能不完整。通过运行以下命令修复：

export PATH="/usr/sbin:/usr/bin:/bin:/sbin:$PATH"

然后重试截图命令。

macOS：截图返回黑屏

如果 take_screenshot 返回完全黑色的图像，Mac 可能已锁定（例如屏幕在登录/锁定窗口）。这是系统级限制 — macOS 禁止在会话锁定时捕获屏幕内容，因此应用层没有解决方法。

推荐修复： 使用屏幕保护程序而不是锁定屏幕。屏幕保护程序保持用户会话活动且未锁定，允许截图正常捕获。

打开 系统设置 > 锁定屏幕
将"屏幕保护程序开始或显示器关闭后要求输入密码"设置为更长的延迟（或在自动化期间关闭）
可选地在 系统设置 > 屏幕保护程序 下配置屏幕保护程序，这样显示器在不活动后仍会变暗但不会锁定

AI 找不到元素

截屏验证元素确实可见
使用更具体的描述（包括颜色、位置、周围文本）
确保元素没有被其他窗口遮挡

`@midscene/*` 依赖版本过旧

检查本地版本：npm ls @midscene/computer @midscene/core @midscene/shared（或 pnpm why @midscene/computer）。
检查最新版本：npm view @midscene/computer version、npm view @midscene/core version、npm view @midscene/shared version。
升级依赖：npm i @midscene/computer@latest @midscene/core@latest @midscene/shared@latest。