# https://github.com/web-infra-dev/midscene 项目说明书

生成时间：2026-06-19 05:28:01 UTC

## 目录

- [项目概览与整体架构](#page-1)
- [核心引擎:Agent、多模态模型与 AI 工作流](#page-2)
- [平台集成:Web、Mobile、桌面与自定义接口](#page-3)
- [开发者工具、扩展能力与运维](#page-4)

<a id='page-1'></a>

## 项目概览与整体架构

### 相关页面

相关主题：[核心引擎:Agent、多模态模型与 AI 工作流](#page-2), [平台集成:Web、Mobile、桌面与自定义接口](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)
- [packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)
- [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- [packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)
- [packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)
- [packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)
- [packages/computer-mac/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/computer-mac/package.json)
- [packages/shared/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/README.md)
- [packages/visualizer/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/visualizer/README.md)
- [packages/core/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/core/README.md)
- [packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)
- [apps/chrome-extension/package.json](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/package.json)
- [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- [packages/shared/src/us-keyboard-layout.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/us-keyboard-layout.ts)
</details>

# 项目概览与整体架构

## 一、项目定位与核心价值

Midscene.js 是一套**基于视觉的 AI 驱动 UI 自动化 SDK**，核心目标是用自然语言描述操作步骤，替代传统依赖 DOM 选择器或可访问性树的脆弱自动化方案。其设计哲学明确写在根目录 [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md) 中：只要人类能看见的元素，Midscene 就能定位与操作，从而覆盖 `<canvas>`、原生应用、跨域 iframe 等传统工具无法触及的界面。

主要应用场景包括：
- **Web 端 UI 自动化与测试** —— 与 [Playwright](https://midscenejs.com/integrate-with-playwright) 或 Vitest 集成（[packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)）。
- **多端覆盖** —— Android、iOS、桌面（Computer）以及 HarmonyOS（[packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)）。
- **AI Agent 模式** —— 通过 Skills 与 MCP 让模型自主驱动测试与操作（[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)）。

当前最新发布版本为 `v1.9.7`，采用 MIT 许可证（[packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)、[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)）。

## 二、仓库结构与包划分

项目采用 monorepo 模式（`@midscene/*` workspace），按"核心能力 + 平台适配 + 工具"进行分层。下表汇总了主要包及其职责：

| 包名 | 目录 | 职责与入口 |
|------|------|-----------|
| `@midscene/core` | [packages/core](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json) | 核心 SDK：AI 模型抽象、任务规划、设备抽象、工具函数（`./utils`、`./ai-model`、`./device`） |
| `@midscene/web` | [packages/web-integration](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json) | 浏览器集成：Playwright、Puppeteer、桥接模式（`./bridge-mode`） |
| `@midscene/ios` | [packages/ios](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json) | iOS 模拟器自动化，含 CLI (`midscene-ios`) 与 MCP server |
| `@midscene/android` | （由 cli package 引用） | Android 设备自动化 |
| `@midscene/harmony` | （由 cli package 引用） | HarmonyOS 鸿蒙端 UI 自动化 |
| `@midscene/computer` | （由 cli package 引用） | 桌面操作抽象层，依赖 libnut 原生控制（[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)） |
| `@midscene/computer-mac` | [packages/computer-mac](https://github.com/web-infra-dev/midscene/blob/main/packages/computer-mac/package.json) | macOS 桌面自动化实现 |
| `@midscene/shared` | [packages/shared](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/README.md) | 公共类型、录制器（recorder）、键盘布局、坐标系统 |
| `@midscene/visualizer` | [packages/visualizer](https://github.com/web-infra-dev/midscene/blob/main/packages/visualizer/README.md) | 可视化与回放组件 |
| `@midscene/cli` | [packages/cli](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json) | 统一命令行工具（`midscene`），聚合各平台 |

应用层（`apps/`）目前以 [apps/chrome-extension](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/package.json) 为主，提供浏览器扩展形式的录制与回放能力，封装了 `openai` 客户端并使用 `rsbuild` 构建。

## 三、核心架构与数据流

Midscene 的运行时遵循"**截图 → AI 规划 → 平台执行 → 回放/断言**"的闭环：

```mermaid
flowchart LR
  A[用户自然语言指令] --> B[AI 规划层<br/>core/ai-model]
  B --> C[设备抽象层<br/>core/device]
  C --> D{平台适配}
  D -->|Web| E[web-integration<br/>Playwright/Puppeteer]
  D -->|Mobile| F[iOS / Android / Harmony]
  D -->|Desktop| G[computer / computer-mac<br/>libnut]
  E & F & G --> H[截图与事件回放]
  H --> I[Visualizer / Chrome Extension<br/>录制报告]
  I --> J{断言/导出}
  J -->|通过| K[CI 测试或 Agent 循环]
  J -->|生成脚本| L[Playwright/YAML/Markdown]
```

关键模块说明：
- **录制与回放抽象** 由 [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts) 定义事件模型（`MidsceneRecorderTarget`、`MidsceneRecorderGeneratedCode`），统一支持导出 Markdown、YAML 与 Playwright 脚本——回应了社区 #2240 关于"导出 AI 步骤为可复用 Playwright 脚本"的需求。
- **键盘输入层** 在 [packages/shared/src/us-keyboard-layout.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/us-keyboard-layout.ts) 通过 `transformHotkeyInput` 将自然语言按键转换为 `KeyInput`，覆盖 `Numpad0-9`、`ArrowUp` 等完整 US 键盘布局。

## 四、平台支持与集成方式

- **浏览器自动化**：通过 [packages/web-integration](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json) 暴露 `bridge-mode` 与 `bridge-mode-browser` 子入口，可注入到任意已有浏览器控制栈。
- **命令行**：`@midscene/cli` 聚合了 `android`、`computer`、`harmony`、`ios`、`web` 等子命令（[packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)），适合在 CI 中以 YAML 脚本驱动。
- **MCP 集成**：`@midscene/harmony` 与 `@midscene/ios` 都提供 `mcp-server` 子包，遵循 [Model Context Protocol](https://modelcontextprotocol.org/) 标准，可被外部 Agent 调度。
- **桌面操作**：底层使用 [libnut](https://github.com/nut-tree/libnut-core) 进行跨平台原生键鼠控制（[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)）。

## 五、社区生态与已知限制

Awesome Midscene 收录的社区扩展（[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)）已经覆盖：
- iOS 镜像（[midscene-ios](https://github.com/lhuanyu/midscene-ios)）
- PC 端跨平台（[midscene-pc](https://github.com/Mofangbao/midscene-pc)）
- Python / Java 多语言 SDK

当前仍在演进的方向与社区关注点（[community_context](https://github.com/web-infra-dev/midscene/issues)）：
1. **RAG 与领域知识**（#426）—— 当前通用 LLM 对高层或领域化指令理解不足，社区希望引入检索增强机制。
2. **视口外元素**（#179）—— 滚动后定位、长表单、商品页等场景需要自动滚动并重定位。
3. **鸿蒙原生支持**（#1594）—— 仓库已新增 `@midscene/harmony` 与 `@midscene/harmony-mcp` 作为初步落地。
4. **Playwright 脚本导出**（#2240）—— `MidsceneRecorderGeneratedCode` 接口已预留 `playwright` 字段，CLI 端持续完善中。
5. **桌面 Agent 化**（#1389）—— 鼓励社区基于"任意接口集成"能力扩展 Windows / Linux 桌面 Agent。

## See Also

- [核心 SDK 与 AI 模型抽象]()
- [浏览器集成：Playwright / Puppeteer / Bridge Mode]()
- [录制器与回放报告]()
- [多平台 CLI 使用指南]()
- [MCP 与 Agent 集成]()
- [社区扩展与 Awesome Midscene]()

---

<a id='page-2'></a>

## 核心引擎:Agent、多模态模型与 AI 工作流

### 相关页面

相关主题：[项目概览与整体架构](#page-1), [平台集成:Web、Mobile、桌面与自定义接口](#page-3), [开发者工具、扩展能力与运维](#page-4)

```markdown
<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)
- [packages/core/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/core/README.md)
- [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- [packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)
- [packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)
- [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- [packages/shared/src/constants/example-code.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/constants/example-code.ts)
- [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)
- [packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)
- [packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)
- [packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)
- [packages/visualizer/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/visualizer/README.md)
</details>

# 核心引擎:Agent、多模态模型与 AI 工作流

## 一、核心引擎的定位与设计哲学

Midscene 的核心引擎位于 `@midscene/core` 包中，定位为"基于 AI 的 UI 自动化 SDK"——通过自然语言即可驱动页面操作、断言与数据抽取 [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)。其包描述明确指出，核心包对外提供多组入口：`./ai-model`、`./device`、`./tree`、`./utils` 以及根入口 [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)，分别对应 AI 模型适配、设备抽象、页面树结构与通用工具。

与依赖 DOM 或可访问性树的传统方案不同，Midscene 强调"以截图作为唯一视觉输入"的设计理念：只要人类能看到的目标，引擎就能定位与操作，对 `<canvas>`、原生应用和跨域 iframe 同样有效 [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)。这一设计在 Issue #179（视口外元素支持）以及 Issue #1389（PC 设备接入 `midscene-pc`）等社区讨论中被反复印证是引擎扩展性的根基。

## 二、Agent 工作流与任务模型

Midscene 的 Agent 围绕一组语义化动作构建，这些动作在 YAML 任务脚本与录制器输出中保持一致 [packages/shared/src/constants/example-code.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/constants/example-code.ts)：

| 任务类型 | 用途 | 关键参数 |
| --- | --- | --- |
| `ai` / `aiAct` | 自然语言驱动的自动规划交互 | `cacheable` |
| `aiTap` / `aiDoubleClick` / `aiHover` | 瞬时点击/双击/悬停 | 元素描述 + 可选 `xpath` |
| `aiInput` | 文本输入 | `text value` + 定位 |
| `aiScroll` | 滚动 | `direction`、`scrollType`、`distance` |
| `aiAssert` | 视觉断言 | 期望状态描述 |
| `sleep` | 延时控制 | 毫秒数 |

任务层还支持 `continueOnError` 容错控制与 `cacheable` 缓存选项，后者与文档中提到的"caching feature"配合，可在多模态模型推理时复用结果以降低成本 [packages/shared/src/constants/example-code.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/constants/example-code.ts)。如下图为典型 Agent 工作流：

```mermaid
flowchart LR
    A[自然语言指令 / YAML 任务] --> B[截图采集<br/>device 抽象]
    B --> C[多模态模型<br/>@midscene/core/ai-model]
    C --> D{规划结果}
    D -- 交互 --> E[执行动作<br/>aiTap / aiInput / aiScroll]
    D -- 断言 --> F[视觉比对<br/>aiAssert]
    E --> G[页面状态更新]
    F --> G
    G --> B
```

需要注意的是，Issue #179 反馈的"视口外元素"问题正是在该循环中通过 `aiScroll` 暴露的：当目标不在当前视口时，引擎需要多次截图-规划-滚动才能收敛。

## 三、多模态模型与平台适配

引擎通过 `@midscene/core` 暴露 `./ai-model` 子入口，封装了与多模态大模型的协议对接 [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)。围绕该入口，平台适配层以 npm workspace 形式分发独立包：

- **Web** `@midscene/web`：与 Playwright、Puppeteer 集成，并提供 Bridge Mode 用于远程脚本控制 [packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md) [packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)。
- **CLI** `@midscene/cli`：聚合 Web/Android/iOS/Harmony/Computer 等子包，提供 `midscene` 命令行入口 [packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)。
- **iOS** `@midscene/ios`：提供 `midscene-ios` 命令及 `mcp-server` 子入口，支持模拟器自动化 [packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)。
- **Harmony MCP** `@midscene/harmony-mcp`：基于 `@modelcontextprotocol/sdk` 的鸿蒙适配，对应社区 Issue #1594 关于"鸿蒙 UI 自动化最后一块拼图"的诉求 [packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)。
- **Visualizer** `@midscene/visualizer`：用于执行过程可视化与回放 [packages/visualizer/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/visualizer/README.md)。

统一的设备抽象（`./device`）和树结构（`./tree`）使多模态模型在不同平台下复用相同的提示词与规划策略 [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)。这也是社区 Issue #1389 中 `midscene-pc` 能直接接入 AI agent 的根本原因。

## 四、录制器与工作流代码生成

Chrome 扩展内的录制器是 Agent 工作流的"逆向入口"——用户操作被记录为结构化事件，再由 AI 转换为可复用的脚本 [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)。`MidsceneRecorderTarget` 抽象了 `platformId`、`deviceId`、`label` 与 `values`，覆盖不同平台的录制目标 [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)。

录制器支持三类代码输出：
- **Markdown**：保留完整事件描述，支持 `maxScreenshots`（默认 20）张截图嵌入 [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)。
- **YAML**：与 `example-code.ts` 中定义的任务格式保持一致，便于直接进入 CI 流水线 [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)。
- **Playwright**：直接生成可执行的 `.spec` 脚本，对应 Issue #2240 中"将 AI 执行步骤导出为可复用 Playwright 脚本"的需求 [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)。

录制器还提供 `exportAllEventsToZip` 工具，可将会话、截图与代码打包下载，便于团队共享与回归测试 [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)。

## 五、典型失败模式与建议

- **视口外元素定位失败**：若未在任务序列中加入 `aiScroll`，模型可能直接放弃，参考 Issue #179 建议改用滚动-重定位-操作的循环。
- **领域术语误识别**：社区 Issue #426 指出通用 LLM 难以理解产品域指令，可结合提示词微调或在任务脚本中显式给出 `locate` 描述以约束模型。
- **录制器输出无截图**：检查 `MidsceneRecorderMarkdownScreenshotOptions.maxScreenshots` 是否被业务层覆盖 [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)。

## See Also

- 核心包导出与 AI 模型入口：[packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- Web 集成与 Bridge 模式：[packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)
- 录制事件结构与代码生成：[packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- 任务脚本示例与缓存开关：[packages/shared/src/constants/example-code.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/constants/example-code.ts)
- Chrome 扩展录制器工具集：[apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)

---

<a id='page-3'></a>

## 平台集成:Web、Mobile、桌面与自定义接口

### 相关页面

相关主题：[核心引擎:Agent、多模态模型与 AI 工作流](#page-2), [开发者工具、扩展能力与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)
- [packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)
- [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- [packages/core/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/core/README.md)
- [packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)
- [packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)
- [packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)
- [packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)
- [packages/visualizer/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/visualizer/README.md)
- [packages/shared/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/README.md)
- [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- [packages/shared/src/us-keyboard-layout.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/us-keyboard-layout.ts)
- [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)
</details>

# 平台集成:Web、Mobile、桌面与自定义接口

## 概览

Midscene 是一个面向 UI 自动化的多模态 SDK，定位为"视觉驱动的 AI Operator"，通过截图与多模态模型完成元素定位、断言与数据抽取。其核心设计原则是"多平台统一接入":同一套自然语言 API 可以在 Web、Mobile、桌面乃至自定义接口上复用。

项目以 monorepo 形式组织,核心抽象位于 `@midscene/core`,各平台包通过 `device` 接口与核心解耦 资料来源：[packages/core/package.json:1-50]()。上层入口由 `@midscene/cli` 统一调度 Web、Android、iOS、HarmonyOS 与 computer 五个平台 资料来源：[packages/cli/package.json:1-30]()。

## Web 平台集成

`@midscene/web`(原 `web-integration`)是 Web 端的主入口,提供三条主要接入路径:

| 集成方式 | 适用场景 | 包导出 |
| --- | --- | --- |
| Playwright | 现代 E2E 测试 | `./` |
| Puppeteer | 遗留/轻量场景 | `./` |
| Bridge Mode | 跨进程/跨语言 | `./bridge-mode` |

导出项中除主入口外,还显式暴露了 `./bridge-mode`、`./bridge-mode-browser` 与 `./utils` 等子路径,方便按需打包 资料来源：[packages/web-integration/package.json:1-60]()。README 中也分别给出 Playwright、Puppeteer 与 Bridge Mode 的官方文档链接 资料来源：[packages/web-integration/README.md:1-10]()。

Bridge Mode 是社区与[#2240](https://github.com/web-infra-dev/midscene/issues/2240)中"将 AI 执行步骤导出为可复用 Playwright 脚本"诉求的重要基础——它让 AI 推理过程可在独立进程运行,从而支持回放与脚本化。

## Mobile 平台集成

Mobile 端按操作系统拆分为独立包:

- **iOS**:`@midscene/ios` 提供 SDK、CLI(`midscene-ios`)与 MCP Server 入口 资料来源：[packages/ios/package.json:1-40]()。
- **Android**:`@midscene/android` 通过 CLI 统一调度入口 资料来源：[packages/cli/package.json:1-20]()。
- **HarmonyOS**:`@midscene/harmony` 与 `@midscene/harmony-mcp` 提供鸿蒙设备驱动与 MCP 适配层 资料来源：[packages/harmony-mcp/package.json:1-15]()。

各 Mobile 包共享 `@midscene/core` 的设备抽象,使得 `aiAct`、`aiQuery`、`aiAssert` 等高层 API 在三端语义一致。社区对 HarmonyOS 自动化的强烈呼声([#1594](https://github.com/web-infra-dev/midscene/issues/1594))促使项目将鸿蒙纳入主仓,而非作为外部扩展。

## 桌面与 Computer 集成

桌面端由 `@midscene/computer` 包提供,能力包括跨平台键盘鼠标控制与滚动事件归一化(例如近期修复的"libnut 滚动 tick 触发完整 WHEEL_DELTA")。CLI 顶层依赖中已包含该包 资料来源：[packages/cli/package.json:1-20]()。

桌面交互需要把抽象键名映射到平台键码,`@midscene/shared` 中的 `us-keyboard-layout.ts` 与 `transformHotkeyInput` 工具负责将自然语言热键拆分为可识别的键输入序列 资料来源：[packages/shared/src/us-keyboard-layout.ts:1-80]()。

社区项目 `midscene-pc` 进一步将桌面能力扩展为 Windows/macOS/Linux 上的统一代理([#1389](https://github.com/web-infra-dev/midscene/issues/1389)),印证了"通过统一 device 接口对接任意 UI"这一架构路线的可扩展性。

## 自定义接口与生态扩展

当内置平台不满足需求时,Midscene 通过以下机制支持自定义接入:

1. **Bridge Mode**:将浏览器或任意客户端桥接到独立 AI 推理进程,适合 WebView、Electron、跨语言客户端 资料来源：[packages/web-integration/package.json:1-60]()。
2. **Recorder 数据模型**:`@midscene/shared` 暴露统一的 `MidsceneRecorderEvent`、`MidsceneRecorderTarget`、`MidsceneRecorderGeneratedCode` 等类型,涵盖 click、drag、scroll、input、navigation、setViewport、keydown 等事件,并支持 `web` / `android` / `ios` / `computer` / `harmony` 等平台 ID 资料来源：[packages/shared/src/recorder.ts:1-80]()。这使得任何实现了 recorder 协议的工具都能被纳入 Midscene 生态。
3. **Chrome 扩展**:`apps/chrome-extension` 内的 recorder 工具(例如 `utils.ts` 中的 Mermaid mindmap 生成逻辑)展示了如何把浏览器操作转为可回放、可文档化的脚本 资料来源：[apps/chrome-extension/src/extension/recorder/utils.ts:1-40]()。
4. **社区 SDK**:Awesome Midscene 列出 iOS Mirror、PC 设备、Python、Java 等第三方绑定,共同构成多语言生态。

针对[#179](https://github.com/web-infra-dev/midscene/issues/179)中"视口外元素"的诉求,RAG 增强([#426](https://github.com/web-infra-dev/midscene/issues/426))通常与自定义接口结合:将产品领域知识注入上层 Agent,使 AI 在跨平台执行时能更好地理解长表单、滚动加载等场景。

```mermaid
flowchart LR
  Core["@midscene/core<br/>(device 抽象)"] --> Web["@midscene/web<br/>(Playwright/Puppeteer/Bridge)"]
  Core --> Android["@midscene/android"]
  Core --> iOS["@midscene/ios"]
  Core --> Harmony["@midscene/harmony + MCP"]
  Core --> Computer["@midscene/computer"]
  Core --> Shared["@midscene/shared<br/>(recorder/keyboard)"]
  Web --> Bridge["bridge-mode<br/>(跨进程)"]
  Shared --> Chrome["Chrome Extension Recorder"]
  Shared --> Community["PC / iOS Mirror / Python / Java"]
```

## See Also

- 模型策略与多模态选型
- YAML 脚本与 Playwright 集成
- Bridge Mode 跨进程自动化
- Awesome Midscene 社区扩展清单

---

<a id='page-4'></a>

## 开发者工具、扩展能力与运维

### 相关页面

相关主题：[核心引擎:Agent、多模态模型与 AI 工作流](#page-2), [平台集成:Web、Mobile、桌面与自定义接口](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)
- [packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- [packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)
- [packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)
- [packages/computer-mac/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/computer-mac/package.json)
- [packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)
- [packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- [packages/shared/src/us-keyboard-layout.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/us-keyboard-layout.ts)
- [apps/chrome-extension/src/extension/recorder/utils.ts](https://github.com/web-infra-dev/midscene/blob/main/apps/chrome-extension/src/extension/recorder/utils.ts)
- [README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)
</details>

# 开发者工具、扩展能力与运维

## 概述

Midscene 是一套面向 UI 自动化的多模态 AI 引擎,以"截图即操作"为核心抽象,通过 monorepo 组织多个 npm 子包,并以 CLI、Chrome 扩展、MCP 服务器、录制器与 Visualizer 等组件支撑开发、调试与运维全流程。本页围绕社区关注的扩展诉求(RAG、视口外元素定位、PC 与鸿蒙平台支持、AI 步骤导出为 Playwright 脚本等),梳理这些工具的能力边界、协作方式与可扩展点。

## 包结构与命令行入口

仓库采用 pnpm 工作区管理多个独立发布的子包,核心能力按平台与职责拆分:

| 包名 | 角色 | 关键依赖/入口 |
|---|---|---|
| `@midscene/cli` | 命令行聚合入口,统一调度各平台驱动 | 依赖 `@midscene/web`、`@midscene/android`、`@midscene/ios`、`@midscene/harmony`、`@midscene/computer`、`@midscene/core`、`@midscene/shared`;通过 `bin.midscene` 暴露可执行命令 |
| `@midscene/core` | 核心抽象:AI 设备、树结构、模型路由、YAML 播放器 | `exports` 暴露 `./utils`、`./ai-model`、`./tree`、`./device` 等子路径 |
| `@midscene/web` | Playwright/Puppeteer 集成、Bridge 模式 | 暴露 `./bridge-mode`、`./bridge-mode-browser`、`./ui-utils` 入口 |
| `@midscene/ios` | iOS 模拟器自动化 + MCP Server 子入口 | `bin.midscene-ios` 与 `./mcp-server` 导出 |
| `@midscene/computer-mac` | macOS 桌面自动化运行时 | 仅依赖 `@midscene/computer` |
| `@midscene/harmony-mcp` | 鸿蒙 MCP 集成 | 依赖 `@modelcontextprotocol/sdk@1.10.2` |

`@midscene/cli` 在 `package.json` 中以 `workspace:*` 引用所有平台驱动,并通过 `"bin": { "midscene": "./bin/midscene" }` 提供统一 CLI,使得一次安装即可对任意平台发起操作。资料来源:[packages/cli/package.json:1-31]()。

`@midscene/core` 是所有上层包的依赖底座,其 `exports` 字段按子路径分发,便于 CLI、Chrome 扩展与第三方 SDK 按需引用,避免打包冗余。资料来源:[packages/core/package.json:1-46]()。

`@midscene/web` 在 `exports` 中额外声明 Bridge 模式相关子路径,这是社区 Issue #2240 建议的"导出 Playwright 脚本"功能落地的关键依赖:录制产物可直接复用 Web 集成侧的桥接与代码生成能力。资料来源:[packages/web-integration/package.json:1-46]()。

## Chrome 扩展与录制器

Chrome 扩展(`apps/chrome-extension`)是开发者最常用的录制入口,负责捕获用户在浏览器中的操作,并在结束时生成结构化的会话描述、可视化思维导图与可回放的测试脚本。扩展内部将采集到的会话数据序列化为 JSON,再驱动大模型生成 Mermaid 思维导图,要求保留完整的事件顺序、页面流转与输入值,不允许缩写或截断,以确保回放与交接的完整性。资料来源:[apps/chrome-extension/src/extension/recorder/utils.ts:1-19]()。

底层数据结构由 `@midscene/shared` 统一定义,核心类型包括:

- `MidsceneRecorderTarget`:描述一次录制目标(平台 ID、设备 ID、标签、键值参数);
- `MidsceneRecorderGeneratedCode`:录制产物,可同时输出 Markdown、YAML 与 Playwright 三种脚本,以及更新时间戳;
- `MidsceneRecorderMarkdownScreenshotAsset`:截图资产元数据,关联事件索引、哈希、相对路径、MIME 类型与 base64 数据;
- `DEFAULT_MIDSCENE_RECORDER_MARKDOWN_MAX_SCREENSHOTS = 20`:控制单次录制嵌入 Markdown 的截图上限,避免文档膨胀。

这些类型被 CLI、Visualizer 与第三方 SDK 共享,确保"录—存—放—生成"流水线各阶段对同一事件有统一理解。社区 Issue #2240 关注的 Playwright 脚本导出正是基于 `MidsceneRecorderGeneratedCode.playwright` 字段在 UI 层提供一键导出。资料来源:[packages/shared/src/recorder.ts:1-31]()。

此外,`@midscene/shared` 还导出 US 键盘布局与 `transformHotkeyInput` 等工具函数,负责将自然语言中的快捷键(如 `page down`、`ctrl a`)映射到具体的键码定义,支撑跨平台快捷键操作的语义一致性,这也是后续 RAG(Issue #426)中"理解产品领域快捷键"诉求的基础设施。资料来源:[packages/shared/src/us-keyboard-layout.ts:1-15]()。

## MCP 集成与跨平台扩展

社区 Issue #1594 关注的 HarmonyOS 自动化已通过 `@midscene/harmony-mcp` 进入路线图。该包在 `devDependencies` 中显式引入 `@modelcontextprotocol/sdk@1.10.2`,并提供 `@modelcontextprotocol/inspector` 用于调试 MCP Server,意味着鸿蒙设备将以 MCP 协议对外暴露自动化能力,可被任意 MCP 客户端(如 Claude Desktop、Cursor)直接调用。资料来源:[packages/harmony-mcp/package.json:1-8]()。

iOS 端同样提供 MCP 入口。`@midscene/ios` 在 `exports` 中声明 `./mcp-server` 子路径,并通过 `bin.midscene-ios` 提供独立 CLI,使 iOS 模拟器自动化既可作为库调用,也可作为 MCP Server 独立部署。资料来源:[packages/ios/package.json:1-35]()。

桌面端由 `@midscene/computer` 与平台绑定包(如 `@midscene/computer-mac`)协作。`computer-mac` 仅依赖 `@midscene/computer`,作为 macOS 平台的轻量运行时绑定;README 致谢的 `libnut` 提供跨平台原生键鼠控制,与社区项目 `midscene-pc` 共同覆盖 Windows、macOS 与 Linux(见 Issue #1389)。最新 v1.9.7 还修复了 libnut 滚动事件中 `WHEEL_DELTA` 的发送问题,以保证桌面端录制与回放的滚动手势一致性。资料来源:[packages/computer-mac/package.json:1-15]()。

## 可视化与日常运维

根 README 将 Midscene 定位为面向 UI 测试的多模态 SDK,推荐接入 Playwright、Vitest 等既有测试体系,或通过 Skills / MCP 让 AI Agent 自治执行。Visualizer `@midscene/visualizer` 与 `@midscene/shared` 提供回放 UI、报告与断言可视化,是日常运维与回归分析的主要入口。资料来源:[README.md:1-10]()。

`@midscene/web` 同时提供 Bridge 模式(`./bridge-mode` 与 `./bridge-mode-browser`),允许将页面控制权移交至独立 Node 进程,便于在 CI、长任务或分布式执行环境中保持浏览器连接稳定,这也是社区在生产环境部署 Midscene 时常用的运维手段。资料来源:[packages/web-integration/README.md:1-10]()。

针对社区反馈的两个痛点——"视口外元素的滚动定位"(Issue #179)与"AI 步骤导出为 Playwright 脚本"(Issue #2240)——前者依赖多模态模型对截图中长内容的理解,需要在 AI 设备层配合滚动策略;后者可直接复用 `MidsceneRecorderGeneratedCode` 中已有的 `playwright` 字段,在 CLI 或 Visualizer 中暴露一键导出即可落地。

## See Also

- 包结构与 CLI:[packages/cli/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/cli/package.json)、[packages/core/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/core/package.json)
- 录制与代码生成:[packages/shared/src/recorder.ts](https://github.com/web-infra-dev/midscene/blob/main/packages/shared/src/recorder.ts)
- 跨平台 MCP:[packages/harmony-mcp/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/harmony-mcp/package.json)、[packages/ios/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/ios/package.json)
- Bridge 与 Web 集成:[packages/web-integration/package.json](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/package.json)、[packages/web-integration/README.md](https://github.com/web-infra-dev/midscene/blob/main/packages/web-integration/README.md)
- 整体定位与社区资源:[README.md](https://github.com/web-infra-dev/midscene/blob/main/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：web-infra-dev/midscene

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models。

## 1. 配置坑 · 来源证据：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Feature]: Let MIDSCENE_MODEL_REASONING_ENABLED disable thinking for self-hosted Qwen models
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2063 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `midscene` 与安装入口 `@midscene/web` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npm install @midscene/web`
- 证据：identity.distribution | https://github.com/web-infra-dev/midscene | repo=midscene; install=@midscene/web

## 3. 安装坑 · 来源证据：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Raw \x1b[1A\x1b[2K ANSI escape sequences polluting logs in non-TTY / Kubernetes Pod environment
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2689 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 配置坑 · 来源证据：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bridge 模式下 fileChooserAccept 报错 -32000 Not allowed
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/web-infra-dev/midscene/issues/2691 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/web-infra-dev/midscene | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/web-infra-dev/midscene | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/web-infra-dev/midscene | no_demo; severity=medium

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/web-infra-dev/midscene | release_recency=unknown

<!-- canonical_name: web-infra-dev/midscene; human_manual_source: deepwiki_human_wiki -->