> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 使用 Skills 控制任意平台

[Agent Skills](https://github.com/anthropics/skills) 是一种扩展 AI 编程助手能力的格式。Midscene 提供了 Agent Skills，让 AI 编程工具（如 Claude Code、Cline 等）可以通过 CLI 命令驱动 UI 自动化。

Skills 通过在终端中直接运行 CLI 命令来工作。AI 编程助手充当“大脑”：截图、分析 UI、决定下一步操作。

## 支持的平台

| Skill                       | 包名                   | CLI 命令                   | 说明                                                                                          |
| --------------------------- | -------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| Browser Automation          | `@midscene/web`      | `npx @midscene/web`      | 浏览器自动化，支持三种模式：默认 Puppeteer 无头模式、`--bridge` 桥接用户 Chrome、`--cdp <ws-endpoint>` 通过 CDP 直连已有浏览器 |
| Desktop Computer Automation | `@midscene/computer` | `npx @midscene/computer` | macOS、Windows、Linux 桌面控制                                                                    |
| Android Device Automation   | `@midscene/android`  | `npx @midscene/android`  | 通过 ADB 控制 Android 设备                                                                        |
| iOS Device Automation       | `@midscene/ios`      | `npx @midscene/ios`      | 通过 WebDriverAgent 控制 iOS 设备                                                                 |
| HarmonyOS Device Automation | `@midscene/harmony`  | `npx @midscene/harmony`  | 通过 HDC 控制鸿蒙设备                                                                               |

## 安装

确保已安装 [Node.js](https://nodejs.org)，然后运行：

```bash
# 通用安装
npx skills add web-infra-dev/midscene-skills

# Claude Code
npx skills add web-infra-dev/midscene-skills -a claude-code

# OpenClaw
npx skills add web-infra-dev/midscene-skills -a openclaw
```

Skills 仓库：[github.com/web-infra-dev/midscene-skills](https://github.com/web-infra-dev/midscene-skills)

## 模型配置

Midscene Skills 需要具备极强 UI 定位能力的多模态模型。请配置以下环境变量。你可以把它们设为系统环境变量，也可以写在当前工作目录的 `.env` 文件中（Midscene 会自动加载 `.env`）。

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

支持的模型和配置详情请参考[使用模型 API Key](/zh/model-api-setup.md)。

## 使用 Skills

安装完成后，只需用自然语言把任务描述给你的 AI 编程助手即可。它会自动选择合适的 Skill、运行 CLI、读取截图并决定下一步。例如：

> 打开相册应用，看看相册里的第一张照片是什么。

## 案例：编码 Agent 写完代码后自行验证功能

以下示例中，我们让 Claude Code 开发一个 Electron Todo 应用。写完代码后，它会通过 `desktop-computer-automation` Skill 自行启动应用、操作 UI、截图验证功能是否符合预期。全程无需人工介入，也无需编写测试脚本。

**Prompt：**

```
开发一个 Electron Todo 应用，包含添加、勾选、删除功能。
开发完成后，启动应用并用桌面自动化验证：添加 3 个 todo、勾选其中 1 个、删除 1 个，截图确认最终状态正确。
```

编码 Agent 会自主完成以下工作：编写 Todo 组件 → 启动 Electron 应用 → 连接桌面 → 截图识别 UI → 通过自然语言操作界面 → 截图验证结果。开发者只需描述意图，Skill 赋予 Agent “看屏幕、动鼠标”的能力，让它像人一样验证自己写的代码。

## 更多应用场景

Skills 不仅限于本地桌面测试，通过组合不同 Skill 可以覆盖更多场景：

- **桌面应用自动化测试**：验证 Electron、Qt、WPF 等桌面应用的功能流程
- **远程控制电脑**：通过远程桌面连接操控远程机器上的应用，实现远程运维和调试
- **移动端应用测试**：使用 `@midscene/android` 和 `@midscene/ios` Skill 在真机或模拟器上验证移动应用
- **跨应用工作流**：串联多个应用操作，如从浏览器取数据 → 粘贴到 Excel → 截图发送到 Slack
- **CI/CD 集成**：在 Linux CI 中通过 Xvfb 无头模式运行，无需物理显示器
- **日常任务自动化**：批量填写表单、定时截图监控、自动整理文件等

## 浏览器连接配置（按需使用）

在默认 Puppeteer 模式下，可以通过 `--viewport-width <width>` 和 `--viewport-height <height>` 覆盖默认的 `1440x800` 视口尺寸。这两个参数仅支持默认 Puppeteer 模式，不支持 `--bridge` 或 `--cdp` 模式。

在 CDP 模式下，每个 HTTP header 使用一个独立的 `--extra-http-header 'Name:Value'` 参数。每条 CLI 命令都会创建新的 CDP session，因此所有可能发起请求的独立命令都必须重复携带这些参数：

```bash
npx @midscene/web connect \
  --cdp ws://127.0.0.1:9222/devtools/browser \
  --extra-http-header 'x-use-ppe:1' \
  --extra-http-header 'x-tt-env:ppe_example' \
  --url https://example.com

npx @midscene/web act \
  --cdp ws://127.0.0.1:9222/devtools/browser \
  --extra-http-header 'x-use-ppe:1' \
  --extra-http-header 'x-tt-env:ppe_example' \
  --prompt "click the button"
```

header 会在 `connect --url` 导航前生效，因此初始文档请求也会携带这些 header。不要把敏感鉴权值直接留在 shell 历史中。

如果 Chrome 安装在非标准路径，请将 `MIDSCENE_CHROME_PATH` 设置为 Chrome 可执行文件路径。`MIDSCENE_MCP_CHROME_PATH` 会暂时作为迁移别名继续生效。

## 切换浏览器标签页

使用 `tabs` 列出标签，用 `switch-tab --id <id>` 切换到指定标签。点击会打开新标签的链接前，先保存原标签页 ID；打开后再次列出标签，找到新标签页 ID：

```bash
npx @midscene/web tabs
# 打开新标签页后：
npx @midscene/web tabs
npx @midscene/web switch-tab --id <new-tab-id>
npx @midscene/web take_screenshot
# 新标签页操作完成后返回原标签页：
npx @midscene/web switch-tab --id <original-tab-id>
```

`tabs` 返回包含 `id`、`title`、`url` 和 `active` 的 JSON 数组。`active` 表示 Midscene 当前控制的页面。切换会选中已有标签，不会重新导航或刷新页面，因此能保留页面状态。ID 不存在或标签已关闭时会报错。如果网站异步打开标签，等标签出现后再次运行 `tabs`。

每条命令要保持相同的连接模式。在默认 Puppeteer 和 CDP 模式下，后续命令会继续使用选中的标签。这两种模式会保留新打开的标签，但不会自动切换过去。

在 CDP 模式下，每条命令都需要传入 `--cdp <endpoint>`，或设置 `MIDSCENE_CDP_ENDPOINT` 后传入 `--cdp`。

在 Bridge 模式下，每条命令都需要传入 `--bridge`，并使用更新后的 Midscene Chrome 扩展。切换会激活当前 Chrome 窗口中的指定标签。后续命令连接前台标签，因此手动切换标签也会改变下一条命令控制的页面。

`disconnect` 释放连接。默认 Puppeteer 模式下的 `close` 会关闭整个浏览器，包括所有标签。

## 更多

请参考 [Skills 仓库](https://github.com/web-infra-dev/midscene-skills) 获取更多详情。