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>

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airxdb/commands/airxdb.md

@@ -0,0 +1,109 @@
+---
+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。
+```