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
parent 8f55c962bb
commit ae44be31d5
364 changed files with 46779 additions and 2812 deletions
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/references/midscene-official-notes.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/references/midscene-official-notes.md
@@ -0,0 +1,159 @@
+# 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` 做修复。