computer-automation

桌面计算机自动化

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

1. 绝不要在后台运行 midscene 命令。 每条命令都必须同步运行，以便你读取其输出（尤其是屏幕截图）后再决定下一步操作。后台执行会破坏“截图—分析—操作”循环。
2. 一次只能运行一条 midscene 命令。 等待上一条命令完成并读取屏幕截图，然后再决定下一步操作。绝不要串联运行多条命令。
3. 为每条命令预留足够的完成时间。 Midscene 命令涉及 AI 推理和屏幕交互，耗时可能比典型的 shell 命令更长。通常一条命令需要约 1 分钟；复杂的 act 命令可能需要更久。
4. 结束前务必汇报任务结果。 自动化任务完成后，你必须主动向用户总结结果，包括找到的关键数据、完成的操作、拍摄的屏幕截图，以及任何相关发现。最后一个自动化步骤完成后，绝不要不作说明就结束；用户期望在一次交互中获得完整答复。
5. 只最小化窗口，除非用户明确要求，否则绝不要关闭窗口。 需要让窗口消失或不再碍事时，应将其最小化，而不是关闭。除非用户明确要求，否则不要关闭任何应用或窗口。

使用 npx -y @midscene/computer@1 控制桌面（macOS、Windows、Linux）。每条 CLI 命令都直接对应一个 MCP 工具——你（AI Agent）是负责根据屏幕截图决定采取哪些操作的“大脑”。

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"

示例：Qwen 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"
# If using OpenRouter, set:
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

示例：Doubao 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"

常用模型：Doubao Seed 2.0 Lite、Qwen 3.5、Zhipu GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

如果尚未配置模型，请让用户进行设置。支持的提供商请参阅模型配置。

命令

连接到桌面

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

通过 RDP 连接

使用 RDP 模式操作远程 Windows 桌面，而不是本地机器。提供 --host 会将 connect 切换为 RDP 模式，并通过 @midscene/computer 附带的 RDP 辅助二进制文件路由所有后续命令（act、tap、take_screenshot、assert、disconnect）。不会触碰本地鼠标或键盘。

最简示例：

npx -y @midscene/computer@1 connect \
  --host rdp.example.com \
  --username Administrator \
  --password "$RDP_PASSWORD"

connect 的所有 RDP 选项（设置 --host 时会启用 RDP 模式；其他标志均为可选）：

• --host <fqdn-or-ip> — RDP 主机。进入 RDP 模式时必填。
• --port <number> — RDP 端口（默认值为 3389）。
• --username <user> — RDP 用户帐户。
• --password <secret> — RDP 密码。建议从环境变量、密钥管理器或交互式提示中读取；切勿将其粘贴到共享的记录中。
• --domain <domain> — Active Directory / NTLM 域。
• --security-protocol <auto|tls|nla|rdp> — 安全协议协商。默认值为 auto。
• --ignore-certificate — 跳过 TLS 证书验证。仅用于使用自签名证书的可信开发主机。
• --admin-session — 连接到管理员/控制台会话（等同于 mstsc /admin）。
• --desktop-width <px> 和 --desktop-height <px> — 请求特定的远程桌面分辨率。实际尺寸取决于 RDP 服务协商返回的结果；例如，向固定使用 1280x720 的主机请求 1024x768，最终仍会得到 1280x720。连接后，使用 listdisplays --host ... --username ... --password ... 确认协商后的尺寸。

RDP 模式专属说明：

• 在 RDP 模式下，--displayId 和 --headless 会被忽略。已连接的 RDP 会话始终只显示一个虚拟显示器，其尺寸取决于服务协商结果。
• 有两个显示器列表命令，行为各不相同，请选择正确的命令：
  • list_displays（带下划线，平台工具）— 仅枚举本地物理显示器。不接受 RDP 标志。在 RDP 连接后毫无用处。
  • listdisplays（不带下划线，操作工具）— 接受与 connect/take_screenshot/等相同的 RDP 标志。在 RDP 模式下，它会返回协商后的虚拟显示器，例如 [{ "id": "...", "name": "RDP 10.70.86.26:3389 (1280x720)", "primary": true }]。使用此命令确认实际分辨率。
• RDP 传输使用随 @midscene/computer 一同提供的原生辅助程序二进制文件。如果出现 RDP helper binary not found 错误，说明安装包中缺少可选的 bin/<platform>/rdp-helper，请重新安装该包或解压新的 tarball。
• 将 RDP 凭据视为密钥：不要将包含 --password 的 .env 文件提交到仓库；建议在当前 shell 中使用 export RDP_PASSWORD=...，并通过 --password "$RDP_PASSWORD" 引用。
• 延迟预期：每次 CLI 调用都会启动一个全新的 Node 进程，因此每条命令都会重新建立 RDP 会话。大致预留：
  • connect / take_screenshot / keyboardpress / scroll：约 5 秒（Node 启动 + RDP TLS+NLA 握手 + 首帧）。
  • act / assert / tap --locate：约 5 秒 + AI 推理 + 任何计划中的子操作；典型交互端到端预计需要 8–20 秒。
  • RDP 握手本身约需 700 毫秒；CLI 的运行方式决定了其余冷启动开销无法避免。
• 连接失败诊断：connect 失败时，stderr 的第一行是可操作的错误信息（例如 connect_failed: Failed to connect to RDP server: ERRCONNECT_LOGON_FAILURE: Logon failed.）。后续堆栈跟踪只是诊断噪声 — 读取第一行，然后检查凭据/网络。常见的 ERRCONNECT_* 原因：
  • LOGON_FAILURE — 用户名/密码/域错误。
  • CONNECT_TRANSPORT_FAILED — 主机无法访问或 RDP 端口被阻止。使用 nc -zv <host> 3389 验证。
  • TLS_CONNECT_FAILED — TLS 握手被拒绝。对于使用自签名证书的开发主机，可尝试 --ignore-certificate；也可指定 --security-protocol nla。

connect --host ... 成功后，其余工作流（act、tap --locate、assert、take_screenshot、listdisplays、report-tool、disconnect）与本地模式相同 — 只需记得在后续每条命令中都传入相同的 --host/--username/--password/--ignore-certificate 标志，因为每次 CLI 调用都是无状态的，并会重新连接。

列出显示器

npx -y @midscene/computer@1 list_displays

截取屏幕截图

npx -y @midscene/computer@1 take_screenshot

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

执行操作

使用 act 与计算机交互并获取结果。它会在内部自主处理所有 UI 交互，包括点击、输入、滚动、等待和导航，因此应将复杂的高级任务作为一个整体交给它，而不是拆成多个小步骤。用自然语言描述你想做什么以及期望达到的效果：

# specific instructions
npx -y @midscene/computer@1 act --prompt "type hello world in the search field and press Enter"
npx -y @midscene/computer@1 act --prompt "drag the file icon to the Trash"

# or target-driven instructions
npx -y @midscene/computer@1 act --prompt "search for the weather in Shanghai using the Chrome browser, tell me the result"

断言当前屏幕状态

使用 assert 验证当前屏幕是否满足自然语言条件。它不会执行 UI 操作，只会检查可见的屏幕状态，并且仅在断言为真时通过。可在验证、QA 检查以及 act 执行后的最终状态验证中使用。

npx -y @midscene/computer@1 assert --prompt "there is a login button visible"
npx -y @midscene/computer@1 assert --prompt "the active window shows a saved confirmation message"
npx -y @midscene/computer@1 assert --displayId 1 --prompt "the file picker is open"

默认情况下，断言失败时会抛出 AI 生成的原因。传入 --message 可改为抛出自定义错误消息，这有助于在 QA 和 CI 日志中显示预期结果。

npx -y @midscene/computer@1 assert \
  --prompt "the export completed dialog is visible" \
  --message "the export should finish after clicking Save"

如果断言需要与参考图像（图标、徽标、屏幕截图）进行比较，请传入 --image 指定 URL/路径，并传入 --image-name 指定其显示名称。每个 --image 可以是 http(s) 链接、data: URI 或本地文件路径。需要附加多张图像时，按对应顺序重复这两个标志。如果模型无法直接访问 URL，请添加 --convertHttpImage2Base64 true。需要 @midscene/[email protected]+。

npx -y @midscene/computer@1 assert \
  --prompt "the active window matches the supplied reference screenshot" \
  --image "https://example.com/reference.png" \
  --image-name "reference" \
  --convertHttpImage2Base64 true

# or with a local file
npx -y @midscene/computer@1 assert \
  --prompt "the visible icon matches the supplied logo" \
  --image "./fixtures/logo.png" \
  --image-name "logo"

# multiple reference images — pair --image and --image-name by order
npx -y @midscene/computer@1 assert \
  --prompt "the active window matches both the icon and the logo" \
  --image "./fixtures/icon.png" --image-name "icon" \
  --image "./fixtures/logo.png" --image-name "logo"

录制并断言瞬时 UI

如果待验证的状态可能在当前屏幕断言运行前消失，例如 toast、加载横幅、动画或过渡效果，请使用录制：

# Terminal 1: keep this foreground command running
npx -y @midscene/computer@1 record start --displayId 1 \
  --output ./save-observation.json

# Terminal 2, while Terminal 1 records
npx -y @midscene/computer@1 act --displayId 1 \
  --prompt "click the Save button"

# Send Ctrl+C to Terminal 1 and wait for the saved-path message, then assert
npx -y @midscene/computer@1 assert --displayId 1 \
  --record ./save-observation.json \
  --prompt "a saved confirmation appeared"

运行 record start 时传入本地显示器或 RDP 目标标志以及 --output，然后等待 Recording. Press Ctrl+C to stop and save.。将录制器作为前台进程运行在专用终端中；切勿添加 shell &。手动执行交互，或在第二个终端中执行交互，然后向录制器发送 Ctrl+C，并等待它打印保存路径后再进行断言。在操作和最终的 assert 中都要重复传入目标标志。可选的捕获标志包括 --interval-ms、--max-frames 和 --watchdog-ms；--max-frames 会限制采样帧数，而清单中可能会额外包含一帧最终代表性画面。默认看门狗会在五分钟后完成并保存录制；--watchdog-ms 0 则会禁用此安全限制。输出内容是 JSON 清单和相邻的 <name>.frames 图像目录，不是编码后的视频或归档文件。清单包含相对 JPEG/PNG 路径，不含 base64 图像数据。请将 JSON 文件和图像目录放在一起保存或移动，并将 JSON 路径传给 assert --record。如果只关心当前屏幕，请使用不带 --record 的普通 assert。

使用参考图像精确定位目标

当用户提供屏幕截图、图标、徽标或参考图像，并要求精确匹配视觉效果时，优先使用 tap --locate，而不是通用的 act --prompt。以 JSON 形式传入 --locate。prompt 用于描述目标，images 用于提供带名称的参考图像；如果模型可能无法直接访问图像 URL，使用 convertHttpImage2Base64: true 会很有帮助。

npx -y @midscene/computer@1 tap --locate '{
  "prompt": "tap the area contains the image",
  "images": [
    {
      "name": "target image",
      "url": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png"
    }
  ],
  "convertHttpImage2Base64": true
}'

接受 locate 参数的其他命令也可以使用相同的 locate JSON 结构。

断开连接

npx -y @midscene/computer@1 disconnect

使用报告文件

建议先使用生成的 HTML 报告供人工阅读。报告包含逐步执行详情和每项操作的回放视频，能让人更容易了解发生了什么并排查问题。

如果其他技能或工具需要使用该报告，请先通过同一平台 CLI 包中的 report-tool 转换报告。对于基于 LLM 的工作流，优先使用 Markdown。如果报告需要通过程序处理，请使用 JSON。

npx -y @midscene/computer@1 report-tool --action to-markdown --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-markdown
npx -y @midscene/computer@1 report-tool --action split --htmlPath ./midscene_run/report/.../index.html --outputDir ./output-data

工作流模式

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

1. 连接以建立会话
2. 健康检查——查看 connect 命令的输出。如果 connect 已执行健康检查（截图和鼠标移动测试），则无需额外检查。如果 connect 未执行健康检查，请手动进行：截取屏幕截图并确认成功，然后将鼠标移动到随机位置（act --prompt "move the mouse to a random position"），并确认成功。如果任一步骤失败，请停止并排查问题，然后再继续。只有两项检查均通过且没有错误后，才能继续下一步。
3. 启动目标应用并截取屏幕截图，查看当前状态，并确保应用已启动且显示在屏幕上。
4. 执行操作，使用 act 执行所需操作或基于目标的指令。使用 assert 检查操作后的屏幕状态；对于瞬时状态工作流，也可以在专用终端中运行 record start --output ...，按 Ctrl+C 停止录制，然后使用 assert --record。
5. 断开连接
6. 报告结果——总结已完成的工作，列出关键发现及任务期间提取的数据，并列出生成的文件（屏幕截图、日志等）及其路径

最佳实践

1. 始终先运行健康检查：连接后，查看 connect 命令的输出。如果 connect 已执行健康检查（截图和鼠标移动测试），则无需额外检查。如果没有，请手动执行：截取屏幕截图，并将鼠标移动到随机位置。两项操作都必须成功（无错误）后，才能继续执行其他操作。这样可以尽早发现环境问题。
2. 使用此技能前，将目标应用置于前台：为了提高效率，请在调用任何 midscene 命令之前，通过其他方式将应用置于前台（例如，在 macOS 上运行 open -a <AppName>，在 Windows 上运行 start <AppName>）。然后截取屏幕截图，确认应用确实处于前台。只有在视觉确认后，才能使用此技能进行 UI 自动化。避免通过 midscene 使用 Spotlight、“开始”菜单搜索或其他基于启动器的方式——这些方式涉及临时 UI、多次 AI 推理步骤，而且速度明显较慢。
3. 明确描述 UI 元素：不要使用含糊的描述，而要提供清晰、具体的细节。例如，说 "Safari 窗口左上角的黄色最小化按钮"，而不是 "按钮"。
4. 尽可能描述位置：通过描述元素的位置来帮助定位（例如，"菜单栏右上角的图标"、"左侧边栏中的第三项"）。
5. 绝不要在后台运行：每条 midscene 命令都必须同步运行——后台执行会破坏截图—分析—操作的循环。
6. 检查是否有多个显示器：如果启动了应用，却无法在截图中看到它，应用窗口可能打开在另一个显示器上。使用 list_displays 检查可用显示器。你有两种选择：将应用窗口移到当前显示器，或者使用 connect --displayId <id> 切换到应用所在的显示器。
7. 将相关操作合并到一条 act 命令中：在同一个应用中连续执行操作时，将它们合并到一条 act 提示中，而不是拆分成多条命令。例如，"搜索 X，点击第一个结果，然后向下滚动查看更多详情" 应作为一次 act 调用执行，而不是三次。这样可以减少往返调用，避免不必要的截图—分析循环，速度也会明显更快。
8. 运行前设置 PATH（macOS）：在 macOS 上，如果 PATH 不完整，可能无法找到某些命令（例如 system_profiler）。运行任何 midscene 命令前，请确保 PATH 包含标准系统目录：

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

   这样可以避免因缺少系统工具而导致截图失败。
9. 选择合适的验证时机：对于当前屏幕，使用 assert --prompt "..."。对于 toast、横幅、动画或过渡效果，请在专用终端中运行 record start --output ...，执行交互操作，然后按 Ctrl+C 停止录制；等待出现保存路径消息后，再将录制文件传给 assert --record。
10. 完成后始终报告结果：完成自动化任务后，必须主动向用户呈现结果，不要等用户询问。这包括：（1）回答用户的原始问题，或说明所请求任务的结果；（2）执行过程中提取或观察到的关键数据；（3）截图和其他生成文件及其路径；（4）对所执行步骤的简要总结。不要在最后一条自动化命令后就不作说明地结束——用户期望在一次交互中得到完整结果。
11. 提供参考图时，优先使用 tap --locate：如果用户分享了截图、图标或徽标，并希望定位那个确切的视觉目标，请使用带有多模态 locate JSON 对象（例如 { "prompt": "...", "images": [...] }）的 tap --locate，而不要只依赖 act --prompt。

示例 — 上下文菜单交互：

npx -y @midscene/computer@1 act --prompt "right-click the file icon and select Delete from the context menu"
npx -y @midscene/computer@1 take_screenshot

示例 — 下拉菜单：

npx -y @midscene/computer@1 act --prompt "open the File menu and click New Window"
npx -y @midscene/computer@1 take_screenshot

提高精度（Deep Locate / Deep Think）

有两个可选的全局标志，可在 Midscene 难以完成任务时提供帮助。可将它们放在命令中的任意位置（子命令之前或之后）；设置后，相关操作会默认使用它们，因此无需传递单次调用参数。

• --deep-locate — 额外进行一轮视觉推理，以精确定位目标元素。如果操作点击到了错误位置（位置漂移／偏移），请使用此标志。它适用于所有需要定位元素的操作，包括 tap --locate，以及 act 内部执行的定位。
• --deep-think — 使用更深入的推理来规划 act（提供更丰富的上下文并分解子目标）。复杂的多步骤 act 指令适合使用此标志；它只影响规划。

这两个标志都会稍微降低速度以提升效果，也可以同时使用。

# more accurate element location (helps act's internal locating too)
npx -y @midscene/computer@1 act --deep-locate --prompt "click the tiny red close button in the top-left of the window"

# deeper planning for a complex, multi-step act
npx -y @midscene/computer@1 act --deep-think --prompt "open the Export dialog, choose PDF, and save it to the Desktop"

# combine both
npx -y @midscene/computer@1 act --deep-locate --deep-think --prompt "open Preferences and switch to the Advanced tab"

故障排除

macOS：拒绝辅助功能权限

你的终端应用没有辅助功能访问权限：

1. 打开 系统设置 > 隐私与安全性 > 辅助功能
2. 添加你的终端应用并启用它
3. 授予权限后重启终端应用

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 禁止在会话锁定时捕获屏幕内容，因此无法在应用层面绕过。

建议的修复方法： 使用屏幕保护程序，而不是锁定屏幕。屏幕保护程序会让用户会话保持活动且未锁定，从而允许正常截取屏幕。

1. 打开 系统设置 > 锁定屏幕
2. 将“开始屏幕保护程序或关闭显示器后要求输入密码”设置为更长的延迟时间（或在自动化期间关闭此选项）
3. 也可以在 系统设置 > 屏幕保护程序 中设置屏幕保护程序，这样屏幕在不活动时仍会变暗，但不会锁定

AI 无法找到元素

1. 截取屏幕，确认元素确实可见
2. 使用更具体的描述（包括颜色、位置和周围文本）
3. 确保元素没有被其他窗口遮挡

@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。