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

name, description

name

description

airdbg

Debug-first repair workflow. Use when the user invokes /airdbg or explicitly asks for AirDbg mode to debug, reproduce, diagnose, or fix software errors, including GUI, visual, screenshot, browser UI, desktop UI, remote GUI/device debugging, canvas, layout, focus, popup, graphical operation, network, packet capture, remote packet capture, pcap, DNS, TCP, UDP, TLS, HTTP connectivity, proxy, firewall, port, retransmit, reset, latency, cppcheck, static analysis, code quality, or security-relevant C/C++ defects. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; discuss symptoms and constraints with the user; reproduce the issue; require AirXDB local or remote device helpers or equivalent GUI/screen evidence for every local or remote GUI validation instead of treating process liveness as success; call AirNDB local or remote device helpers when tcpdump/WinDump packet capture, pcap analysis, BPF filters, or network-layer evidence is needed; call AirSDB local or remote device helpers when static-analysis capability, cppcheck evidence, or AirPlan/docs/staticanalysis.md documentation is needed; identify root cause; apply a focused fix; verify with tests or equivalent checks; and update AirPlan/AGENTS.md, ADR, and C4 module docs when project behavior, module boundaries, dependencies, GUI automation boundaries, network boundaries, static-analysis boundaries, remote-device boundaries, or architecture decisions change.

AirDbg

核心约束

• 全程使用中文与用户交流，代码、命令、日志、路径、异常名保持原文。
• /airdbg 是主要触发入口。用户进入 AirDbg 后，围绕调试和修复错误推进。
• 先加载项目上下文，再修复：AirPlan/AGENTS.md、AirPlan/docs/architecture/adr/、AirPlan/docs/architecture/c4/module.md。
• 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要记录真实模块边界，不只放空模板。
• 与用户交流症状、复现步骤、期望行为、实际行为、影响范围和修复约束。
• 默认做最小可验证修复，避免顺手重构。
• 每个修复都要验证。优先自动化测试，其次是可重复命令或明确的手工验证步骤。
• 只要验证或复现涉及本地或远程 GUI，就不能只以进程存在、窗口拉起、命令退出成功、端口监听或日志无异常判定通过；必须辅以图像/GUI 检验和测试。
• 调试中遇到图形对比、截图取证、GUI 操作、浏览器/桌面界面、Canvas、弹窗、焦点、布局、视觉回归或其他图形功能时，必须调用 airxdb 获取截图、探索界面、执行操作验证或收集视觉证据；如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并记录原因。
• 如果 GUI 问题发生在远程设备、测试机、VM、服务器或 SSH 主机上，调用 AirXDB remote device helper，而不是默认使用本机 Computer MCP。
• 调试中遇到抓包分析、pcap、tcpdump/WinDump、BPF、DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST 或延迟问题时，可以调用 airndb 获取网络层调试证据。
• 如果网络问题发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirNDB remote device helper，而不是默认使用本机抓包工具。
• 调试中遇到需要静态分析能力的检验、测试或定位场景，以及 C/C++ 静态分析、cppcheck、代码质量、安全性初筛、未初始化变量、空指针、越界、资源释放、危险转换或 CWE 线索需求时，可以调用 airsdb 获取 AirPlan/docs/staticanalysis.md、XML/JSON 报告等静态分析证据和辅助调试文档。
• 如果静态分析目标在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirSDB remote device helper，而不是默认使用本机 cppcheck。
• 一定要根据项目变化维护 AirPlan/AGENTS.md、ADR 和 C4 module。
• ADR 是给 AI 作为上下文的决策记录，短、准、可检索即可，不写冗长修饰。

启动与初始化

进入 /airdbg 时运行：

python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode enter --project .

如果当前环境没有 python，尝试 py 或 python3。脚本不可用时，手动确保以下结构存在：

• AirPlan/AGENTS.md
• AirPlan/docs/architecture/adr/
• AirPlan/docs/architecture/c4/module.md
• AirPlan/docs/debug/debug-log.md
• AirPlan/state/airdbg/state.json

初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirDbg 标记块。

图形调试与 AirXDB 协作

AirDbg 负责根因分析、代码层修复和验证收尾；AirXDB 负责图形界面的取证和操作层复现。遇到以下情况时，必须调用 AirXDB 或补充等效 GUI/屏幕证据：

• 需要截图或图形对比来理解错误现场、视觉回归、布局错位、颜色/尺寸/遮挡差异。
• 需要操作浏览器 UI、桌面 UI、Electron/Qt/WPF 等应用、Canvas、菜单、弹窗、托盘、任务栏或多显示器界面。
• 需要 /airxdb screenshot 保存错误现场，再把截图交给 AirDbg 做代码层诊断。
• 目标 GUI 在远程设备、测试机、VM、服务器或 SSH 主机上，需要 /airxdb remote-screenshot 或 airxdb_remote_device.py 保存远程错误现场。
• 需要用 AirXDB 执行最小 GUI 操作，确认按钮、表单、导航、窗口切换、焦点或图形流程是否真的失败。
• 需要把 GUI 证据沉淀到 AirPlan/docs/debug/gui-debug-log.md、AirPlan/docs/debug/airxdb-artifacts/ 或 AirDbg 的 AirPlan/docs/debug/debug-log.md。

协作规则：

• 先用 AirXDB 收集最小必要证据，再回到 AirDbg 分析代码根因；不要把视觉症状直接当作根因。
• 任何本地或远程 GUI 测试/验证都不能仅以进程存活、窗口创建成功、命令返回成功或日志无异常视为通过；默认至少保留 1 份截图/图像证据，并完成 1 次关键 GUI 操作或状态检查。
• 如果是嵌入式屏幕、显示控制器、外接面板链路等截图无诊断价值的场景，可改用外部采集视频、framebuffer dump、串口/日志配合按键或触控操作记录、状态灯/OSD 观察记录等等效证据，但必须在 debug-log.md 记录为什么不截图以及替代证据是什么。
• 截图模式可在没有 Midscene 语义模型配置时使用；语义视觉动作按 AirXDB 规则先检查模型配置。
• 本机 GUI 证据使用 /airxdb screenshot 或 airxdb_computer_mcp_smoke.py；远程 GUI 证据使用 airxdb_remote_device.py --action setup|screenshot，由它探测 SSH、远端截图工具并在缺失时自动尝试配置。
• 远程 helper 缺少 AIRXDB_REMOTE_SSH_TARGET 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
• AirDbg 的 debug-log.md 必须记录 AirXDB 命令、截图/报告路径、关键观察、与根因的关系、复验结果和剩余风险。
• 如果 GUI 自动化、截图取证、视觉验收、浏览器桥接或桌面控制成为长期调试/测试边界，更新 C4 module 并创建或修订 ADR。
• 如果发现稳定可复用的 GUI 调试命令、截图方式、远程设备配置或视觉验收步骤，更新 AGENTS.md。
• 截图可能包含账号、密钥、客户数据或聊天内容时，先提醒用户脱敏，再外部分享或长期保留。

抓包调试与 AirNDB 协作

AirDbg 负责把网络证据和代码行为联系起来，定位根因并修复；AirNDB 负责 tcpdump/WinDump 抓包、pcap 摘要、BPF 过滤器和网络层证据。遇到以下情况时，调用 AirNDB：

• 需要抓包判断请求是否发出、响应是否回来、连接是否被 RST/ICMP/防火墙/代理中断。
• 需要分析 DNS 查询、TCP 三次握手、TLS 握手、HTTP 连接、UDP 流量、端口可达性、重传、丢包或延迟。
• 需要读取已有 .pcap 或生成新的短时有界 pcap 给调试使用。
• 需要确定问题在应用代码、系统网络栈、容器/WSL/VM/宿主机边界、代理、防火墙还是远端服务。
• 目标流量发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 /airndb remote-interfaces、/airndb remote-capture 或 airndb_remote_device.py 获取远程网络证据。

协作规则：

• 先让 AirNDB 明确授权范围、接口、BPF 过滤器、抓包窗口和 pcap 输出路径；不要进行无界抓包。
• 本机网络证据使用 airndb_capture.py；远程网络证据使用 airndb_remote_device.py --action setup|interfaces|command|capture，由它探测 SSH、远端 tcpdump / dumpcap 并在缺失时自动尝试配置。
• 远程 helper 缺少 AIRNDB_REMOTE_SSH_TARGET 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
• AirDbg 的 debug-log.md 必须记录 AirNDB 命令、pcap/summary/report 路径、关键包或时间线观察、与根因的关系、复验结果和剩余风险。
• 如果抓包发现新的长期网络边界、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机约束或观测方式，更新 C4 module 并创建或修订 ADR。
• 如果发现稳定可复用的抓包命令、接口选择规则、BPF、远程设备配置或 pcap 读取方式，更新 AGENTS.md。
• pcap 可能包含 token、cookie、payload、内网地址、主机名或个人信息；对外分享前必须提醒用户脱敏。

静态分析与 AirSDB 协作

AirDbg 负责把静态分析线索和代码根因联系起来；AirSDB 负责 cppcheck 检测/安装、本机或远程扫描、XML/JSON 产物和 AirPlan/docs/staticanalysis.md 简短报告。遇到以下情况时，可以调用 AirSDB：

• 需要用 cppcheck 辅助定位 C/C++ bug、内存/资源/越界/空指针/未初始化变量/危险转换/CWE 线索。
• 需要在修复前后比较静态分析结果。
• 需要给 AirDbg 的根因分析提供短报告而不是长 XML。
• 检验、测试或调试判断需要静态分析能力、质量门信息或可引用文档时，需要读取 AirPlan/docs/staticanalysis.md 或 AirSDB XML/JSON 报告辅助分析。
• 目标代码在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 /airsdb remote-scan 或 airsdb_remote_device.py 获取远端静态分析证据。

协作规则：

• 本机静态分析使用 airsdb_cppcheck.py --action scan；远程静态分析使用 airsdb_remote_device.py --action setup|scan，由它探测 SSH、远端 cppcheck 并在缺失时自动尝试配置。
• AirDbg 的 AirPlan/docs/debug/debug-log.md 必须记录 AirSDB 命令、AirPlan/docs/staticanalysis.md、XML/JSON 报告路径、关键 findings、与根因的关系、复验结果和剩余风险。
• 如果静态分析发现新的长期质量门槛、suppressions、远程设备配置或 cppcheck 命令，更新 AGENTS.md。
• 如果静态分析成为长期测试/调试边界，更新 C4 module 并创建或修订 ADR。

调试流程

1. 确认问题边界：
   • 用户看到的错误是什么。
   • 期望行为和实际行为是什么。
   • 复现步骤、输入数据、环境、版本、最近变更是什么。
   • 有哪些不能破坏的兼容性或性能要求。
2. 加载上下文：
   • 读取 AGENTS.md。
   • 读取 ADR 列表和相关 ADR。
   • 读取 docs/architecture/c4/module.md。
   • 查看测试、入口、依赖、配置和最近相关文件。
3. 复现问题：
   • 优先运行已有失败测试或用户给出的命令。
   • 没有复现命令时，先构造最小复现或定位性测试。
   • 如果复现依赖 GUI、截图或图形操作，必须调用 AirXDB 获取截图、执行最小界面操作或保存 GUI 报告；远程目标走 AirXDB remote device helper；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
   • 如果复现依赖网络路径或抓包证据，调用 AirNDB 获取短时 pcap、摘要或网络层时间线；远程目标走 AirNDB remote device helper。

• 如果复现或定位需要 C/C++ 静态分析，或当前检验需要静态分析能力辅助判断，调用 AirSDB 运行本机或远程 cppcheck，并读取 AirPlan/docs/staticanalysis.md。
  • 记录复现命令和关键输出到 docs/debug/debug-log.md。

4. 定位根因：
   • 从错误栈、日志、测试断言、数据流和模块边界推断。
   • 对 GUI 问题，结合 AirXDB 本机或远程截图/报告判断视觉症状、交互失败和代码根因之间的关系。
   • 对网络问题，结合 AirNDB 本机或远程 pcap/摘要判断请求是否出站、响应是否入站、失败发生在 DNS/TCP/TLS/应用层哪一段。
   • 对静态分析问题，结合 AirSDB findings 判断哪些是当前 bug 线索、哪些是既有质量债或误报。
   • 必要时加临时日志或小范围探针，完成后清理。
   • 区分根因、诱因和表面症状。
5. 修复：
   • 优先选择影响面小、能解释根因的修复。
   • 不做无关格式化、批量重构或架构迁移。
   • 如果修复会改变模块边界、依赖、接口、数据所有权或关键行为，先更新 C4/ADR。
6. 验证：
   • 运行失败用例、相关单元测试、集成测试、lint/typecheck。
   • 如果修复涉及 GUI 或视觉行为，必须调用 AirXDB 截图、图形对比或操作验证关键路径；远程目标用远程 helper 复验；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
   • 如果修复涉及网络行为，调用 AirNDB 复验关键网络路径或读取 pcap 摘要；远程目标用远程 helper 复验。

• 如果修复涉及 C/C++ 风险、静态分析 findings，或验证需要静态分析能力辅助判断，调用 AirSDB 复跑 cppcheck 并更新 AirPlan/docs/staticanalysis.md。
  • 如果不能运行，说明原因，并给出可复验的替代验证。
  • 记录验证证据到 debug log。

7. 收尾：
   • 更新 AGENTS.md 中与调试、测试、运行方式相关的项目上下文。
   • 更新或新增 ADR。
   • 更新 C4 module。
   • 向用户汇报根因、改动、验证结果、剩余风险。

AGENTS.md 维护

在以下情况更新 AGENTS.md：

• 发现新的运行、测试、构建、调试命令。
• 发现新的 AirXDB 截图、GUI 操作验证、图形对比、远程设备配置或视觉验收命令。
• 发现新的 AirNDB 抓包命令、BPF 过滤器、接口选择规则、远程设备配置、pcap 读取方式或网络复验步骤。
• 发现新的 AirSDB cppcheck 命令、suppressions、质量门槛、远程设备配置或静态分析复验步骤。
• 发现影响后续 AI 会话的重要项目约束。
• 修复改变了模块职责、关键流程或错误处理策略。
• 发现常见坑、环境要求或验证方式。

保持内容可执行、可复用，不写调试过程流水账。

ADR 维护

目录：docs/architecture/adr/。

需要 ADR 的情况：

• 修复选择了一个会影响长期架构或行为兼容性的方案。
• 改变错误处理、重试、事务、缓存、一致性、安全边界。
• 改变模块依赖、数据所有权、接口契约。
• 将 GUI 自动化、截图取证、远程设备 GUI 取证、视觉验收或图形调试流程纳入长期测试/调试边界。
• 将抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS 或网络拓扑纳入长期调试/测试边界。
• 将 cppcheck、staticanalysis.md、静态分析质量门槛或远程静态分析纳入长期调试/测试边界。
• 拒绝了明显可选方案，需要给后续 AI 留下原因。

ADR 模板：

# ADR-000X: short-title

- Status: Accepted
- Date: YYYY-MM-DD

## Context
简述错误、约束和为什么需要决策。

## Decision
简述采用的修复或架构选择。

## Consequences
- 正面影响
- 代价或风险

## Alternatives
- 方案 A：放弃原因

C4 Module 维护

文件：docs/architecture/c4/module.md。

必须记录：

• 模块名。
• 职责。
• 对外接口。
• 依赖。
• 数据所有权。
• 与本次错误或修复相关的质量属性。

新增模块、拆分模块、改变依赖、改变接口、改变数据边界、改变错误处理流时必须更新。

引入或改变 GUI 自动化、浏览器桥接、桌面控制、截图取证、远程设备 GUI 取证、视觉验收或图形调试基础设施时，也必须更新。

引入或改变 tcpdump/WinDump 抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机网络边界时，也必须更新。

引入或改变 cppcheck、staticanalysis.md、静态分析质量门槛、suppressions 或远程静态分析边界时，也必须更新。

debug-log 维护

文件：docs/debug/debug-log.md。

每次 AirDbg 修复至少追加：

• 问题摘要。
• 复现命令或复现步骤。
• 根因。
• 修复摘要。
• 验证命令和结果。
• AirXDB 本机或远程截图/报告/操作验证证据及其结论（如适用）。
• AirNDB 本机或远程 pcap/summary/report/抓包分析证据及其结论（如适用）。
• AirSDB 本机或远程 staticanalysis.md/XML/JSON 静态分析证据及其结论（如适用）。
• 相关 ADR/C4 更新。
• 剩余风险。

输出格式

调试完成后用中文简洁汇报：

• 根因。
• 修复了什么。
• 更新了哪些 AGENTS.md / ADR / C4 / debug log 上下文。
• 运行了哪些验证；是否调用 AirXDB/AirNDB/AirSDB，截图、pcap、staticanalysis、报告或操作证据在哪里。
• 仍然存在的风险或未验证项。