AirCoding/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/SKILL.md

name, description

name

description

airxdb

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 调试，先调用 $HOME/plugins/airxdb/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。

启动与初始化

进入 /airxdb 时运行：

python "$HOME/plugins/airxdb/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 现场、弹窗、焦点状态、布局错位或多显示器证据时，优先使用截图取证模式：

python "$HOME/plugins/airxdb/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：

python "$HOME/plugins/airxdb/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 忽略。

远程截图：

python "$HOME/plugins/airxdb/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 客户端：

python "$HOME/plugins/airxdb/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 继续做代码层修复。