airxdb/commands/airxdb.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Enter, exit, inspect, screenshot, remote-screenshot, or smoke-test AirXDB GUI debug mode	enter|exit|status|screenshot|remote-setup|remote-status|remote-screenshot|smoke	Read Glob Grep Bash Write Edit

/airxdb

控制当前工作区的 AirXDB 图形界面调试模式。

用户传入参数：$ARGUMENTS

• enter 或空参数：进入 AirXDB 模式并初始化 GUI 调试上下文。
• status：检查 AirXDB 状态和关键文件是否存在。
• screenshot：连接 Computer MCP 并截图，为 airdbg 提供 GUI 错误诊断证据；不要求 Midscene 模型配置。
• remote-setup：检查远程设备 SSH 和截图工具；缺失时自动尝试配置远程截图工具。
• remote-status：只检查远程设备配置和工具状态，不自动安装。
• remote-screenshot：通过 SSH 在远程设备截图，并把截图/JSON 报告拉回当前项目。
• smoke：启动 Computer MCP smoke test，默认视觉定位 Windows taskbar Start button 并移动鼠标。
• exit：退出 AirXDB 模式。

执行步骤

1. 解析 $ARGUMENTS，默认动作为 enter。
2. 在当前项目根目录运行：

python "$HOME/plugins/airxdb/scripts/airxdb_mode.py" --mode <enter|exit|status> --project .

如果 python 不存在，尝试 py 或 python3。

3. enter 后必须：

• 加载或初始化 AirPlan/AGENTS.md、ADR、C4 module、AirPlan/docs/debug/gui-debug-log.md
  • 检查输出中的 midscene_config
  • 如果出现 midscene_config_required=true、midscene_config=missing:... 或 midscene_semantic_config=missing:...，先向用户索取 Midscene 模型配置，再执行视觉语义动作
  • 判断是浏览器 GUI 还是桌面 GUI
  • 判断是否已有 Playwright
  • 选择 Midscene 模式：Playwright / Bridge / Computer / MCP
  • 与用户确认是否要和 airdbg 配合推进

4. 如果 $ARGUMENTS 包含 remote、ssh、远程，或用户已经说明目标 GUI 在远程设备、测试机、服务器、VM、SSH 主机上，优先运行远程设备 helper：

python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action <setup|status|screenshot>

首次缺少远程配置时，helper 会生成 AirPlan/state/airxdb/remote-device.env.example 并提示设置 AIRXDB_REMOTE_SSH_TARGET。有 SSH 目标后，helper 会探测远端截图工具；缺失时自动尝试安装 scrot，只使用非交互式 sudo -n，无法自动配置时停止并提示用户。

5. screenshot 且目标是本机桌面时运行：

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

截图结果写入 AirPlan/docs/debug/airxdb-artifacts/，并应追加到 AirPlan/docs/debug/gui-debug-log.md，作为给 airdbg 的诊断证据。

6. smoke 时运行：

python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"

如果 python 不存在，尝试 py、python3 或用户提供的 Python 绝对路径。smoke 会加载 AirPlan/state/airxdb/midscene.local.env，启动 @midscene/computer-mcp，必要时修复 Windows 截图脚本缺失，并把截图/JSON 报告写入 AirPlan/docs/debug/airxdb-artifacts/。

7. GUI 调试过程中必须维护：
   • AGENTS.md
   • docs/architecture/adr/
   • docs/architecture/c4/module.md

• AirPlan/docs/debug/gui-debug-log.md

输出文案

进入模式：

AirXDB 模式已开启：已初始化或检查 AGENTS.md、ADR、C4 module 和 GUI debug log。若 Midscene 模型配置缺失，请先提供 MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_FAMILY；之后请说明目标界面、复现步骤，以及你希望使用 Playwright、Bridge、Desktop 还是 MCP 路线。

smoke 成功：

AirXDB smoke test 通过：Computer MCP 已连接桌面，语义视觉动作完成，截图和 JSON 报告已写入 docs/debug/airxdb-artifacts/。

screenshot 成功：

AirXDB 截图取证完成：Computer MCP 已连接桌面并保存截图/JSON 报告，可交给 airdbg 做错误诊断。

remote-screenshot 成功：

AirXDB 远程截图取证完成：已通过 SSH 获取远程设备截图/JSON 报告，并写入 docs/debug/airxdb-artifacts/，可交给 airdbg 做错误诊断。

退出模式：

AirXDB 模式已退出：已返回标准 Codex 流程。

状态检查：

AirXDB 状态：<enabled|disabled>
关键文件：逐项列出 ok/missing。