Files

AirCoding ae44be31d5 chore: push all design docs, V2 plan specs, and current working state

Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2,
AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code
changes across packages.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-12 17:12:29 +08:00

4.0 KiB

Executable File

Raw Blame History

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 第一次进入项目时先检查这些变量：

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 插件
- 终端侧配置模型环境变量
- 适合复用本地浏览器登录态和页面状态
常用依赖：

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

常见入口：

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

常见运行方式：

tsx demo-new-tab.ts

常见模型环境变量：

MIDSCENE_MODEL_BASE_URL
MIDSCENE_MODEL_API_KEY
MIDSCENE_MODEL_NAME
MIDSCENE_MODEL_FAMILY

MCP

浏览器桥接 MCP：

@midscene/web-bridge-mcp

桌面 MCP：

@midscene/computer-mcp

Computer MCP 常见配置核心：

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

常见 MCP 模型环境变量：

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

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

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

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

用于：

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

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

GUI Debug 推荐策略

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

4.0 KiB Executable File Raw Blame History Unescape Escape