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/plugins/airxdb/skills/airxdb/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/skills/airxdb/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: airxdb
+description: Midscene-based GUI debugging workflow. Use when the user invokes /airxdb, asks to debug browser UI, desktop UI, canvas UI, visual regressions, flaky interface interactions, remote GUI/device debugging over SSH, or reproduce graphical issues with Midscene.js. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; collaborate with AirDbg for GUI issues; choose the right Midscene mode for Playwright, Chrome bridge mode, desktop computer automation, MCP, or the AirXDB remote device helper; auto-configure remote screenshot tooling when missing; generate visual reproduction steps and reports; and maintain AirPlan/AGENTS.md, ADR, C4 module, and GUI debug logs whenever GUI-debug tooling or interface behavior changes.
+---
+
+# AirXDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、包名保持原文。
+- `/airxdb` 专用于图形界面和视觉交互层面的调试，不替代 `airdbg` 的通用根因分析职责。
+- 优先与 `airdbg` 配合：
+  - `airxdb` 负责界面复现、视觉定位、交互自动化、Midscene 报告与截图证据。
+  - `airdbg` 负责代码层根因、最小修复、测试验证和通用调试收尾。
+- 先加载或初始化上下文：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`、`AirPlan/docs/debug/gui-debug-log.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要反映真实模块边界，尤其是前端、UI、桌面桥接、自动化测试相关边界。
+- Midscene 路线优先使用视觉复现和 HTML 报告收集证据，不把 GUI 调试退化成纯日志猜测。
+- 截图取证是 AirXDB 的一等能力：即使没有语义模型配置，也可以连接 Computer MCP 截图，为 `airdbg` 提供错误现场、布局状态、弹窗、焦点和多显示器信息。
+- 远程设备、测试机、VM 或 SSH 主机上的 GUI 调试，先调用 `../../scripts/airxdb_remote_device.py`；缺少远程截图工具时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 优先做最小可验证复现和最小必要修复，不顺手大改界面架构。
+- GUI 调试过程中，一定要维护 `AirPlan/AGENTS.md`、ADR、C4 module 和 `AirPlan/docs/debug/gui-debug-log.md`。
+- 如果需要 Midscene 包名、桥接/MCP 配置、常用命令，读取 [references/midscene-official-notes.md](references/midscene-official-notes.md)。
+
+## 启动与初始化
+
+进入 `/airxdb` 时运行：
+
+```bash
+python ../../scripts/airxdb_mode.py --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/gui-debug-log.md`
+- `AirPlan/state/airxdb/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirXDB 标记块。
+
+## 首次模型配置
+
+AirXDB 第一次进入项目时必须检查 Midscene 模型配置。`airxdb_mode.py` 会输出 `midscene_config`，如果出现 `midscene_config_required=true` 或 `midscene_config=missing:...`：
+
+- 暂停执行 `act`、`Tap`、`Input`、`KeyboardPress`、视觉定位等语义动作。
+- 用中文向用户索取配置：
+  - `MIDSCENE_MODEL_NAME`
+  - `MIDSCENE_MODEL_BASE_URL`
+  - `MIDSCENE_MODEL_API_KEY`
+  - `MIDSCENE_MODEL_FAMILY`
+  - 可选：`MCP_SERVER_REQUEST_TIMEOUT`
+- 告知用户可以只在当前会话设置环境变量，或写入 `AirPlan/state/airxdb/midscene.local.env` 方便后续复用。
+- `AirPlan/state/airxdb/midscene.local.env` 只保存本机密钥，默认由 `AirPlan/state/airxdb/.gitignore` 忽略；不要把真实 API key 写入 `AirPlan/AGENTS.md`、ADR、C4 或 debug log。
+- 如果用户暂时不提供模型配置，仍然可以做截图、MCP 连接、显示器枚举、环境探测等非语义取证操作；不能声称完成了 Midscene 视觉语义操作。
+- `MIDSCENE_MODEL_FAMILY` 是语义视觉动作必填项。`gpt-5.4` 这类 GPT-5.x 视觉模型使用 `gpt-5`。
+- 常见合法 family：`gpt-5`、`qwen2.5-vl`、`qwen3-vl`、`gemini`、`doubao-seed`、`vlm-ui-tars`。
+
+## 截图取证模式
+
+当用户需要给 `airdbg` 提供错误诊断信息、GUI 现场、弹窗、焦点状态、布局错位或多显示器证据时，优先使用截图取证模式：
+
+```bash
+python ../../scripts/airxdb_computer_mcp_smoke.py --project . --action screenshot
+```
+
+截图取证模式不要求 `MIDSCENE_MODEL_NAME`、`MIDSCENE_MODEL_BASE_URL`、`MIDSCENE_MODEL_API_KEY` 或 `MIDSCENE_MODEL_FAMILY`。它只验证 Computer MCP 桌面连接和截图能力，并将截图/JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`。
+
+截图后必须在 `AirPlan/docs/debug/gui-debug-log.md` 追加：
+
+- 截图目标和平台
+- 截图文件路径
+- 当前界面关键观察
+- 给 `airdbg` 的诊断线索
+- 是否还需要语义视觉动作或代码层修复
+
+如果截图可能包含密钥、聊天内容、账号、客户数据或隐私信息，在对外分享前提醒用户脱敏。
+
+## 远程设备截图模式
+
+当用户说明目标在远程设备、测试机、服务器、VM、SSH 主机，或当前桌面不是目标 GUI 所在机器时，不要先使用本机 Computer MCP。先运行远程设备 helper：
+
+```bash
+python ../../scripts/airxdb_remote_device.py --project . --action setup
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。首次运行会生成 `AirPlan/state/airxdb/remote-device.env.example`；把连接信息写入 `AirPlan/state/airxdb/remote-device.env` 或当前环境变量：
+
+- `AIRXDB_REMOTE_SSH_TARGET=user@host`
+- `AIRXDB_REMOTE_SSH_PORT=22`
+- `AIRXDB_REMOTE_SSH_OPTIONS=`
+- `AIRXDB_REMOTE_WORKDIR=`
+- `AIRXDB_REMOTE_SCREENSHOT_TOOL=auto`
+- `AIRXDB_REMOTE_DISPLAY=`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性和远程工作目录。
+- 探测 `gnome-screenshot`、`spectacle`、`scrot`、`grim`、`import`、`screencapture`。
+- 工具缺失时自动尝试用远端包管理器安装 `scrot`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
+- 将可复用配置写入 `AirPlan/state/airxdb/remote-device.env`，该文件由 `AirPlan/state/airxdb/.gitignore` 忽略。
+
+远程截图：
+
+```bash
+python ../../scripts/airxdb_remote_device.py --project . --action screenshot
+```
+
+远程截图和 JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`，并追加 `AirPlan/docs/debug/gui-debug-log.md`。远程截图只能证明远端截图链路和当前 GUI 现场；如果需要 Midscene 语义视觉动作，仍需单独确认远端或本机可用的 Midscene 接入方式。
+
+## Computer MCP 快速验证
+
+验证桌面 GUI 能力时优先运行 smoke test 脚本，而不是临时拼 MCP 客户端：
+
+```bash
+python ../../scripts/airxdb_computer_mcp_smoke.py --project . --action mousemove --prompt "Windows taskbar Start button"
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。
+
+脚本行为：
+
+- 加载 `AirPlan/state/airxdb/midscene.local.env`，但输出和 JSON 报告会屏蔽 API key；`--action screenshot` 不要求模型配置。
+- 启动 `@midscene/computer-mcp` HTTP 服务。
+- Windows 下自动检查并修复 `screenCapture_1.3.2.bat` / `app.manifest` 缺失问题；修复来源是 `screenshot-desktop@1.15.3` 官方 npm 包。
+- 执行 `computer_connect`、可选语义动作、`take_screenshot`、`computer_disconnect`。
+- 证据写入 `docs/debug/airxdb-artifacts/`，包括截图和 `airxdb-smoke.json` 报告。
+
+结果判断：
+
+- `airxdb_smoke=ok` 才能说明 Computer MCP 视觉链路通过。
+- 如果只完成截图，没有完成 `MouseMove` / `act` / `Tap` 等语义动作，只能说“截图/连接可用”，不能说“视觉语义操作已通过”。
+- 如果报 `MIDSCENE_MODEL_FAMILY is not set to a visual language model`，先补 family；`gpt-5.4` 用 `gpt-5`。
+- Windows 开始菜单 + 中文输入法场景下，输入查询词后可能需要双回车：第一次提交输入法，第二次执行启动。
+
+## Midscene 模式选择
+
+先判断目标界面和现有技术栈，再选 Midscene 模式：
+
+1. Web + 已有 Playwright：
+   - 优先使用 Midscene 的 Playwright 集成。
+   - 适合已有 E2E、页面复现、交互不稳定、视觉断言场景。
+2. Web + 需要复用本地 Chrome 状态：
+   - 使用 Chrome Bridge Mode。
+   - 适合需要复用 cookies、扩展、已登录会话、人工介入浏览器态的场景。
+3. 桌面应用 GUI：
+   - 使用 Midscene Computer / Playground。
+   - 适合 Electron、Qt、WPF、原生应用和跨应用流程。
+4. 远程设备 GUI：
+   - 先使用 AirXDB remote device helper 取证和自动配置远端截图工具。
+   - 适合 SSH 可达的测试机、VM、服务器桌面或远程 Linux/macOS GUI。
+5. 需要把 GUI 操作暴露给上层 Agent 或工具链：
+   - 使用 Midscene MCP。
+   - 浏览器优先 Web Bridge MCP，桌面优先 Computer MCP。
+
+不确定时，一次只问一个关键问题：
+
+- 这是浏览器页面还是桌面应用？
+- 项目里是否已有 Playwright？
+- 是否必须复用本机浏览器登录态？
+- 是要快速复现，还是要沉淀成长期自动化脚本？
+
+## GUI 调试流程
+
+1. 明确问题边界：
+   - 哪个界面、哪条交互链路、什么平台。
+   - 期望行为和实际行为。
+   - 是否涉及视觉错位、点击不到、浮层遮挡、Canvas、焦点问题、窗口切换、多显示器等。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看前端/桌面自动化相关代码、测试、构建配置。
+3. 选择 Midscene 模式并做最小复现：
+   - Playwright
+   - Chrome Bridge
+   - Computer / Playground
+   - MCP
+4. 生成可回放证据：
+   - Midscene HTML 报告
+   - 关键截图
+   - 复现命令
+   - 相关日志和报错
+5. 将证据和观察写入 `AirPlan/docs/debug/gui-debug-log.md`。
+6. 如果问题只是界面复现层，继续用 `airxdb` 深挖。
+7. 如果已定位到代码层根因，转入或并行配合 `airdbg` 做修复。
+8. 修复后再次用 Midscene 复跑关键 GUI 路径，确认问题关闭。
+
+## 与 AirDbg 的协作
+
+- `airxdb` 先做：
+  - GUI 复现
+  - 视觉定位
+  - 界面交互脚本/桥接/MCP 配置
+  - 报告与截图证据
+- `airdbg` 再做：
+  - 根因代码分析
+  - 修复实现
+  - 测试验证
+  - 风险收尾
+
+如果当前问题同时包含“界面复现难”和“代码根因不明”，先用 `airxdb` 稳定复现，再把复现结论和报告交给 `airdbg`。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的 GUI 调试命令、Playwright 命令、Midscene 运行方式。
+- 发现系统权限要求，例如桌面自动化权限、屏幕录制权限、多显示器限制。
+- 发现影响后续 GUI 调试的重要约束，如浏览器桥接、登录态、测试环境、显示缩放。
+- 发现远程设备 SSH 入口、远程截图工具、`AIRXDB_REMOTE_*` 配置方式或远端显示环境限制。
+- 引入了新的 GUI 自动化脚本、报告目录或运行前置条件。
+
+内容保持可执行、可复用，不写流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 决定长期采用某种 Midscene 接入方式，例如 Playwright 集成、Bridge Mode、Computer、MCP。
+- GUI 调试方案改变了测试边界、前端交互契约、浏览器控制方式、桌面自动化权限模型。
+- 为了稳定复现而新增长期保留的自动化脚本、报告流程或辅助基础设施。
+
+ADR 保持简洁：Context、Decision、Consequences、Alternatives。
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+当 GUI 调试或修复改变以下内容时，必须更新：
+
+- 前端模块边界
+- 自动化测试边界
+- 浏览器桥接/桌面控制边界
+- 报告和调试基础设施
+- UI 层和服务层之间的数据所有权或依赖
+
+## GUI Debug Log 维护
+
+文件：`AirPlan/docs/debug/gui-debug-log.md`。
+
+每次 AirXDB 会话至少追加：
+
+- 问题摘要
+- 目标平台和界面
+- Midscene 模式（Playwright / Bridge / Computer / MCP）
+- 是否使用远程设备 helper 以及远程目标、截图工具和限制
+- 复现步骤或命令
+- 报告文件路径
+- 截图或关键观察
+- 转交给 `airdbg` 的结论，或已完成的修复验证
+- 剩余风险
+
+## 输出格式
+
+本轮 GUI 调试结束时，用中文简洁汇报：
+
+- 选择了哪种 Midscene 模式，为什么。
+- 复现是否成功，证据在哪里。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / GUI debug log。
+- 是否需要切给 `airdbg` 继续做代码层修复。
--- a/AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/skills/airxdb/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/skills/airxdb/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airxdb
+short_description: Midscene GUI debug workflow with local and remote screenshot evidence
+default_prompt: "使用 AirXDB 配合 AirDbg 做图形界面调试；远程设备优先调用 remote device helper 并自动配置截图工具。"
--- a/AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/skills/airxdb/references/midscene-official-notes.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/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` 做修复。