airdbg/commands/airdbg.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Enter, exit, or inspect AirDbg mode for debugging and repair, with mandatory GUI evidence plus AirNDB and AirSDB evidence handoff	enter|exit|status	Read Glob Grep Bash Write Edit

/airdbg

控制当前工作区的 AirDbg 调试修复模式。

用户传入参数：$ARGUMENTS

• enter 或空参数：进入 AirDbg 模式并初始化调试上下文。
• status：检查 AirDbg 状态和关键文件是否存在。
• exit：退出 AirDbg 模式。

执行步骤

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

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

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

3. enter 后开始调试对话：

   • 确认错误症状、期望行为、实际行为。
   • 确认复现步骤、环境、最近变更和修复限制。
   • 读取或初始化 AGENTS.md、ADR 和 C4 module。
   • 复现、定位根因、最小修复、验证。

4. 调试中遇到图形相关需求时，必须调用 airxdb 或补充等效 GUI/屏幕证据：

   • 图形对比、截图取证、视觉回归、布局错位、弹窗、焦点、Canvas、浏览器/桌面 GUI：用 AirXDB 获取截图或报告。
   • 如果目标 GUI 在远程设备、测试机、服务器、VM 或 SSH 主机上，使用 AirXDB 远程设备路径：

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

• 远程 helper 缺少 AIRXDB_REMOTE_SSH_TARGET 时，先让用户提供 SSH 目标；有目标后它会自动探测远端截图工具，缺失时自动尝试配置。
• 需要确认用户界面操作是否可用：用 AirXDB 执行最小 GUI 操作验证。
• 本地或远程 GUI 测试/验证不得只以进程存在、窗口拉起、命令退出成功或日志无异常视为通过。
• 如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并在 debug log 记录原因。
• AirDbg 继续负责根因分析、修复和最终验证，并把 AirXDB 证据写入 debug log。

5. 调试中遇到抓包或网络层证据需求时，可调用 airndb：
   • DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST、延迟：用 AirNDB 设计 BPF 并抓取/读取 pcap。
   • 需要判断请求是否发出、响应是否回来或失败发生在哪个网络阶段：用 AirNDB 生成 pcap、summary 和 JSON 报告。
   • 如果目标流量在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirNDB 远程设备路径：

python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup
python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action interfaces
python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action capture --iface <iface> --filter "<bpf>" --count 200 --timeout 30

• 远程 helper 缺少 AIRNDB_REMOTE_SSH_TARGET 时，先让用户提供 SSH 目标；有目标后它会自动探测远端 tcpdump / dumpcap，缺失时自动尝试配置。
• AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirNDB 证据写入 debug log。

6. 调试中遇到 C/C++ 静态分析或 cppcheck 证据需求时，可调用 airsdb：

• 未初始化变量、空指针、越界、资源释放、危险转换、CWE、代码质量或安全性初筛：用 AirSDB 运行 cppcheck 并维护 AirPlan/docs/staticanalysis.md。
• 当检验、测试或调试判断需要静态分析能力时，用 AirSDB 获取 AirPlan/docs/staticanalysis.md、XML/JSON 报告等静态分析信息和文档辅助调试。
  • 如果目标代码在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirSDB 远程设备路径：

python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action setup
python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action scan

• AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirSDB 证据写入 debug log。

7. 修复过程中必须维护：
   • AGENTS.md
   • docs/architecture/adr/
   • docs/architecture/c4/module.md
   • docs/debug/debug-log.md

输出文案

进入模式：

AirDbg 模式已开启：已初始化或检查 AGENTS.md、ADR、C4 module 和 debug log。请描述错误症状、复现步骤、期望行为和实际行为；如果涉及本机或远程 GUI 测试/验证，必须使用 AirXDB 或等效 GUI/屏幕证据做复验，不能只看进程是否存活；如果涉及抓包或网络层分析，可调用 AirNDB 获取本机或远程 pcap/summary 证据；如果涉及 C/C++ 静态分析或检验需要静态分析能力，可调用 AirSDB 获取本机或远程 cppcheck/staticanalysis 证据。

退出模式：

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

状态检查：

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