--- 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` 继续做代码层修复。