110 lines
4.6 KiB
Markdown
110 lines
4.6 KiB
Markdown
---
|
||
description: Enter, exit, inspect, screenshot, remote-screenshot, or smoke-test AirXDB GUI debug mode
|
||
argument-hint: [enter|exit|status|screenshot|remote-setup|remote-status|remote-screenshot|smoke]
|
||
allowed-tools: [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. 在当前项目根目录运行：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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` 且目标是本机桌面时运行：
|
||
|
||
```bash
|
||
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` 时运行：
|
||
|
||
```bash
|
||
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`
|
||
|
||
## 输出文案
|
||
|
||
进入模式：
|
||
|
||
```text
|
||
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 成功：
|
||
|
||
```text
|
||
AirXDB smoke test 通过：Computer MCP 已连接桌面，语义视觉动作完成，截图和 JSON 报告已写入 docs/debug/airxdb-artifacts/。
|
||
```
|
||
|
||
screenshot 成功：
|
||
|
||
```text
|
||
AirXDB 截图取证完成：Computer MCP 已连接桌面并保存截图/JSON 报告，可交给 airdbg 做错误诊断。
|
||
```
|
||
|
||
remote-screenshot 成功：
|
||
|
||
```text
|
||
AirXDB 远程截图取证完成：已通过 SSH 获取远程设备截图/JSON 报告，并写入 docs/debug/airxdb-artifacts/，可交给 airdbg 做错误诊断。
|
||
```
|
||
|
||
退出模式：
|
||
|
||
```text
|
||
AirXDB 模式已退出：已返回标准 Codex 流程。
|
||
```
|
||
|
||
状态检查：
|
||
|
||
```text
|
||
AirXDB 状态：<enabled|disabled>
|
||
关键文件：逐项列出 ok/missing。
|
||
```
|