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

name, description

name

description

airndb

Network-debug packet capture workflow. Use when the user invokes /airndb or asks to debug networking, packet loss, DNS, TCP, UDP, TLS handshakes, HTTP connectivity, ports, retransmits, resets, latency, firewall, proxy, service reachability, pcap files, tcpdump, WinDump, remote packet capture over SSH, or BPF filters. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, AirPlan/docs/architecture/c4/module.md, AirPlan/docs/network/airndb-log.md, and AirPlan/docs/network/airndb-captures/; on first startup detect tcpdump/WinDump and on Windows auto-download official WinDump.exe when no capture tool is available; when remote debugging, call the AirNDB remote device helper and auto-configure remote tcpdump/dumpcap when missing; build safe bounded tcpdump/WinDump commands; capture or read pcap artifacts; summarize packet evidence; and maintain AirPlan/AGENTS.md, ADR, C4 module docs, and network debug logs when capture tooling, network boundaries, or debugging decisions change.

AirNDB

核心约束

• 全程使用中文与用户交流，命令、接口名、BPF、日志、路径和协议名保持原文。
• /airndb 专用于网络抓包、pcap 分析和网络层调试证据收集。
• 只抓取用户授权的本机、项目、测试环境或明确允许的网络流量。
• 默认不做无界抓包；必须使用包数、超时、时长或轮转上限。
• 默认先列接口，再确认接口、目标 host/port/protocol/filter、抓包窗口和输出路径。
• 初次启动必须检测 tcpdump / windump / WinDump.exe 是否可用；Windows 下如果不可用，自动从 WinDump 官方下载页获取 WinDump.exe，校验 SHA1 后写入 AirPlan/state/airndb/tool.env。
• 远程设备、测试机、VM 或 SSH 主机上的网络调试，先调用 $HOME/plugins/airndb/scripts/airndb_remote_device.py；缺少远程 tcpdump / dumpcap 时允许脚本自动配置，无法无密码 sudo 或无包管理器时停止并提示用户。
• 自动获取只下载 WinDump 用户态程序，不静默安装 WinPcap/Npcap 抓包驱动；如果接口列举失败，提示用户安装 Npcap 或 WinPcap 并用管理员权限重试。
• 默认使用 -nn 避免 DNS/service-name 解析，使用 -s 0 写入完整 pcap。
• pcap 可能包含凭据、cookie、token、payload、内网地址、主机名或个人信息；对外分享前必须提醒脱敏。
• 网络证据要写入 AirPlan/docs/network/airndb-log.md，pcap/摘要/JSON 报告写入 AirPlan/docs/network/airndb-captures/。
• 根据项目变化维护 AirPlan/AGENTS.md、ADR 和 C4 module。
• 如果需要 WinDump/tcpdump 选项和 BPF 简表，读取 references/windump-tcpdump-notes.md。

启动与初始化

进入 /airndb 时运行：

python "$HOME/plugins/airndb/scripts/airndb_mode.py" --mode enter --project .

如果当前环境没有 python，尝试 py、python3 或用户提供的 Python 绝对路径。脚本不可用时，手动确保以下结构存在：

• AirPlan/AGENTS.md
• AirPlan/docs/architecture/adr/
• AirPlan/docs/architecture/c4/module.md
• AirPlan/docs/network/airndb-log.md
• AirPlan/docs/network/airndb-captures/
• AirPlan/state/airndb/state.json

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

首次工具配置

airndb_mode.py --mode enter 会执行工具自检：

1. 查找显式配置、项目 AirPlan/state/airndb/tool.env、环境变量 AIRNDB_TCPDUMP、项目 AirPlan/state/airndb/tools/WinDump.exe、PATH 中的 windump / WinDump.exe / tcpdump。
2. 如果找到可用工具，写入或刷新 AirPlan/state/airndb/tool.env，后续 airndb_capture.py 自动读取。
3. 如果 Windows 上找不到工具，自动从 WinDump 官方下载地址获取 WinDump.exe，校验 SHA1 d59bc54721951dec855cbb4bbc000f9a71ea4d95，保存到 AirPlan/state/airndb/tools/WinDump.exe，然后写入 AirPlan/state/airndb/tool.env。
4. 如果下载失败或校验失败，停止并提示用户手动安装 tcpdump / WinDump.exe 或设置 AIRNDB_TCPDUMP。

AirPlan/state/airndb/tool.env 是本机路径配置，由 AirPlan/state/airndb/.gitignore 忽略，不应提交。

注意：WinDump 仍需要抓包驱动。官方 WinDump 安装页要求先安装 WinPcap 3.1 或更新版本；WinPcap 主页提示项目已停止维护并建议 Windows 10 用户使用 Npcap。AirNDB 不静默安装驱动，只负责检测、下载 WinDump.exe 和配置本机路径。

远程设备工具配置

当用户说明目标流量发生在远程设备、测试机、服务器、VM、容器宿主机、SSH 主机，或本机抓包看不到目标流量时，不要先使用本机 airndb_capture.py。先运行远程设备 helper：

python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup

如果当前环境没有 python，尝试 py、python3 或用户提供的 Python 绝对路径。首次运行会生成 AirPlan/state/airndb/remote-device.env.example；把连接信息写入 AirPlan/state/airndb/remote-device.env 或当前环境变量：

• AIRNDB_REMOTE_SSH_TARGET=user@host
• AIRNDB_REMOTE_SSH_PORT=22
• AIRNDB_REMOTE_SSH_OPTIONS=
• AIRNDB_REMOTE_WORKDIR=
• AIRNDB_REMOTE_TCPDUMP=auto
• AIRNDB_REMOTE_CAPTURE_PREFIX=sudo -n

远程 helper 行为：

• 检查本机 ssh、远程连通性和远程工作目录。
• 探测 tcpdump、dumpcap、windump、WinDump.exe。
• 工具缺失时自动尝试用远端包管理器安装 tcpdump，只使用非交互式 sudo -n；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
• 将可复用配置写入 AirPlan/state/airndb/remote-device.env，该文件由 AirPlan/state/airndb/.gitignore 忽略。
• 抓包产物拉回 AirPlan/docs/network/airndb-captures/，并追加 AirPlan/docs/network/airndb-log.md。

常用远程命令：

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

远程抓包仍必须有明确授权、接口、BPF、包数或超时上限。AIRNDB_REMOTE_CAPTURE_PREFIX 默认是 sudo -n；如果远端已配置免 sudo 的 capture capability，可改为空或指定更合适的前缀。

工作流

1. 明确网络问题：
   • 现象：连不上、超时、重置、DNS 异常、TLS 握手失败、丢包、延迟、端口不可达、代理/防火墙疑似问题。
   • 目标：源/目的 host、端口、协议、服务名、容器/VM/WSL/宿主机边界。
   • 抓包窗口：包数、超时、复现步骤和是否允许保存 payload。
2. 发现接口：
   • 本机调试运行 airndb_capture.py --action interfaces。
   • 远程调试运行 airndb_remote_device.py --action interfaces。
   • Windows 优先使用 windump -D 或 WinDump.exe -D；Linux/macOS 优先 tcpdump -D。
3. 设计过滤器：
   • 使用最窄可行 BPF：host、src host、dst host、port、tcp、udp、icmp、net。
   • 不确定时先短时宽过滤，再根据结果收窄。
4. 执行有界抓包：
   • 使用 airndb_capture.py --action capture --iface <iface> --filter "<bpf>" --count <n> --timeout <seconds>。
   • 产物写入 AirPlan/docs/network/airndb-captures/。
5. 读取和分析：
   • 使用 airndb_capture.py --action read --read-file <pcap> --filter "<bpf>" 生成文本摘要。
   • 结合时间线、TCP flags、重传、RST、DNS 响应、ICMP、TLS ClientHello/ServerHello 迹象判断网络层事实。
6. 记录证据：
   • exact command
   • interface
   • BPF filter
   • packet count or timeout
   • pcap path
   • summary/report path
   • 观察结论、限制和剩余风险

与 AirDbg 协作

• AirNDB 负责抓包、pcap 摘要、网络层证据和过滤器。
• AirDbg 负责代码层根因分析、修复和验证收尾。
• AirDbg 调试中遇到 DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传或 pcap 证据需求时，可以调用 AirNDB。
• AirNDB 收集到的证据必须能被 AirDbg 直接引用：命令、pcap 路径、摘要、关键包、时间线和结论要写清楚。

常用命令

列接口：

python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action interfaces

检查或初始化工具路径：

python "$HOME/plugins/airndb/scripts/airndb_mode.py" --project . --mode enter

只生成命令：

python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action command --iface 1 --filter "tcp and port 443" --count 200

短时抓包：

python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action capture --iface 1 --filter "tcp and port 443" --count 200 --timeout 30

读取 pcap：

python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action read --read-file AirPlan/docs/network/airndb-captures/example.pcap

AGENTS.md 维护

在以下情况更新 AGENTS.md：

• 发现稳定可复用的 tcpdump/WinDump 命令、接口选择规则、BPF 过滤器或 pcap 读取方式。
• 发现影响后续 AI 调试的网络边界：容器、WSL、VM、代理、防火墙、VPN、DNS、TLS、NAT、端口映射。
• 发现抓包权限、驱动、管理员权限或平台差异。
• 发现本机 tcpdump/WinDump 路径或 AirPlan/state/airndb/tool.env 配置方式。
• 发现远程设备 SSH 入口、远程抓包工具、AIRNDB_REMOTE_* 配置方式或远端抓包权限限制。

ADR 维护

目录：docs/architecture/adr/。

需要 ADR 的情况：

• 长期采用 tcpdump/WinDump 作为项目网络诊断方式。
• 抓包流程改变了测试边界、网络观测边界、运行权限、数据留存或安全策略。
• 发现需要保留的网络架构决策，例如代理、DNS、TLS、端口、服务发现或跨容器/宿主机边界。

ADR 保持简洁：Context、Decision、Consequences、Alternatives。

C4 Module 维护

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

当网络调试发现或改变以下内容时，必须更新：

• 模块间网络依赖。
• 服务端口、协议、DNS、代理、TLS、队列、网关、容器/宿主机/WSL/VM 边界。
• 抓包或观测基础设施成为长期模块或运行边界。
• 网络错误处理、重试、超时、连接池或安全边界。

network log 维护

文件：AirPlan/docs/network/airndb-log.md。

每次 AirNDB 会话至少追加：

• 问题摘要。
• 授权范围和目标流量。
• 接口、BPF、抓包窗口。
• 是否使用远程设备 helper 以及远程目标、抓包工具和权限限制。
• pcap/summary/report 路径。
• 关键包或时间线观察。
• 结论、限制和给 AirDbg 的线索。
• ADR/C4/AGENTS 更新。

完成输出

本轮网络调试结束时，用中文简洁汇报：

• 使用了哪个接口和过滤器。
• 抓包是否成功，证据在哪里。
• 关键观察和网络层结论。
• 更新了哪些 AGENTS.md / ADR / C4 / network log。
• 是否需要切给 AirDbg 做代码层修复。