# Midscene Official Notes

用于 `airxdb` 的轻量参考，不替代官方文档。

## 选择模式

- Web + 现有 Playwright 项目：
  - 优先 Midscene Playwright 集成
  - 适合浏览器页面复现、E2E、界面交互不稳定问题
- Web + 需要复用本机 Chrome 的 cookies / 已登录状态 / 扩展：
  - 使用 Chrome Bridge Mode
- 桌面应用 GUI：
  - 使用 Midscene Computer 或 Playground
- 需要给上层 Agent / MCP 客户端暴露 GUI 操作：
  - 浏览器用 Web Bridge MCP
  - 桌面用 Computer MCP

## 关键能力

- Midscene 的 UI 操作以纯视觉为主，可用于 Web、移动端、桌面端和 Canvas。
- Midscene 支持生成 HTML 报告，适合作为 GUI debug 证据。
- Midscene 可通过 MCP 暴露截图和动作空间操作。

## 首次模型配置

AirXDB 第一次进入项目时先检查这些变量：

```bash
MIDSCENE_MODEL_NAME
MIDSCENE_MODEL_BASE_URL
MIDSCENE_MODEL_API_KEY
MIDSCENE_MODEL_FAMILY
MCP_SERVER_REQUEST_TIMEOUT
```

前三个是连接模型服务的基本配置。`MIDSCENE_MODEL_FAMILY` 是视觉语义动作必填项，`MCP_SERVER_REQUEST_TIMEOUT` 按模型服务情况补充。

常见 `MIDSCENE_MODEL_FAMILY`：

- `gpt-5`：GPT-5.x 视觉模型，例如 `gpt-5.4`
- `qwen2.5-vl`
- `qwen3-vl`
- `gemini`
- `doubao-seed`
- `vlm-ui-tars`

不要把真实 API key 写入 ADR、C4、debug log 或可提交文档。需要本机持久化时优先使用 `AirPlan/state/airxdb/midscene.local.env`。

## Chrome Bridge Mode

- 官方说明：
  - 需要 Midscene Chrome 插件
  - 终端侧配置模型环境变量
  - 适合复用本地浏览器登录态和页面状态
- 常用依赖：

```bash
npm install @midscene/web tsx --save-dev
```

- 常见入口：

```ts
import { AgentOverChromeBridge } from "@midscene/web/bridge-mode";
```

- 常见运行方式：

```bash
tsx demo-new-tab.ts
```

- 常见模型环境变量：

```bash
MIDSCENE_MODEL_BASE_URL
MIDSCENE_MODEL_API_KEY
MIDSCENE_MODEL_NAME
MIDSCENE_MODEL_FAMILY
```

## MCP

- 浏览器桥接 MCP：

```text
@midscene/web-bridge-mcp
```

- 桌面 MCP：

```text
@midscene/computer-mcp
```

- Computer MCP 常见配置核心：

```json
{
  "command": "npx",
  "args": ["-y", "@midscene/computer-mcp"]
}
```

- 常见 MCP 模型环境变量：

```bash
MIDSCENE_MODEL_BASE_URL
MIDSCENE_MODEL_API_KEY
MIDSCENE_MODEL_NAME
MIDSCENE_MODEL_FAMILY
MCP_SERVER_REQUEST_TIMEOUT
```

## 桌面自动化

- Midscene 支持 Windows、macOS、Linux 桌面自动化。
- 桌面控制包括鼠标、键盘、截图、多显示器。
- Linux 可在 Xvfb 下做无头执行。
- Windows 下 `@midscene/computer-mcp` 的 npx 缓存包可能缺 `dist/screenCapture_1.3.2.bat` 和 `dist/app.manifest`。AirXDB smoke test 会从 `screenshot-desktop@1.15.3` npm 包自动补齐。
- 桌面 GUI 调试可优先考虑：
  - 快速试用：Playground
  - 持续脚本化：Computer SDK / MCP

## AirXDB Smoke Test

```bash
python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"
```

输出：

- `airxdb_smoke=ok`：Computer MCP 连接、截图、语义动作完成。
- `airxdb_smoke=blocked`：缺模型配置或 family 不合法。
- `asset_repair=repaired`：已补齐 Windows 截图脚本。
- `report=<path>`：JSON 报告，API key 已脱敏。

## AirXDB Screenshot Evidence

截图取证不需要模型配置：

```bash
python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action screenshot
```

用于：

- 给 `airdbg` 提供 GUI 错误现场
- 捕获弹窗、遮挡、焦点、布局错位、任务栏/托盘状态
- 记录多显示器和当前桌面状态

截图可能包含敏感信息。写入 ADR/C4/debug log 时记录路径和观察，不复制密钥或隐私内容。

## GUI Debug 推荐策略

1. 先选模式，不要一上来混用多种接入。
2. 先做最小复现，再考虑长期自动化。
3. 保留 HTML 报告、截图和复现命令。
4. 若问题已定位到代码层，把证据交给 `airdbg` 做修复。