net

Net Debug Skill

嵌入式网络通信调试工具，统一封装接口发现、抓包、离线分析、连通性测试、端口扫描和流量统计能力。

脚本与配置路径

• 脚本目录: <skill-dir>/scripts/
• 环境级配置: <skill-dir>/config.json（仅工具路径）
• 工程级配置: <workspace>/.embeddedskills/config.json（网络参数）
• 协议参考: <skill-dir>/references/common_protocols.json

依赖

• tshark (随 Wireshark 安装，需加入 PATH)
• dumpcap (随 Wireshark 安装)
• 可选: capinfos
• Windows 自带: ipconfig、ping、tracert、netstat、arp、nslookup
• Python 3.x (仅标准库)
• 抓包需要 Npcap 驱动，部分环境需管理员权限

配置

环境级配置 (skill/config.json)

仅保留工具路径相关的环境级配置：

{
  "tshark_exe": "tshark",
  "capinfos_exe": "capinfos"
}

工程级配置 (.embeddedskills/config.json)

工作区下的 .embeddedskills/config.json 存放工程级网络配置：

{
  "net": {
    "interface": "",
    "target": "",
    "capture_filter": "",
    "display_filter": "",
    "duration": 30,
    "timeout_ms": 1000,
    "scan_ports": "",
    "capture_format": "pcapng",
    "log_dir": ".embeddedskills/logs/net"
  }
}

参数解析优先级

1. CLI 参数 (--interface, --target 等) - 最高优先级
2. 工程级配置 (.embeddedskills/config.json 中的 net 部分)
3. 状态文件 (.embeddedskills/state.json 中的历史记录)
4. 默认值 - 最低优先级

连接和采集参数按优先级解析，脚本通过 CLI 参数接收覆盖值。若配置缺少必要项或连接失败，询问用户并引导修改配置。

执行流程

1. 检查 tshark 是否可用；若不可用，提示用户安装 Wireshark（含 tshark）并确认已加入 PATH；若需要抓包，还需提示安装 Npcap 驱动；依赖缺失时终止执行并输出 status: error 及安装指引
2. 按优先级解析参数：CLI > 工程级配置 > 状态文件 > 默认值；若多个来源对同一参数均有值，以更高优先级来源为准，并在输出 summary 中注明被覆盖的来源
3. 若无子命令，默认执行 iface（列出网络接口）
4. 成功执行后，将确认的参数写回工程配置
5. 运行对应脚本并输出结构化 JSON 结果
6. 失败时优先提示权限、Npcap、过滤器、接口选择等问题

子命令

iface — 列出网络接口

python <skill-dir>/scripts/net_iface.py [--filter <关键词>] [--tshark] [--json]

• --tshark: 同时显示 tshark 抓包接口索引映射
• --filter: 按关键词筛选接口
• 无副作用，可直接执行

capture — 抓包

python <skill-dir>/scripts/net_capture.py [--interface <接口>] [--duration <秒>] [--capture-filter <过滤器>] [--display-filter <过滤器>] [--output <文件路径>] [--format <pcapng|pcap>] [--decode-as <规则>] [--json]

• 接口、过滤器、时长按优先级解析
• --interface: 抓包接口（覆盖配置）
• --duration: 抓包时长（覆盖配置）
• --capture-filter: BPF 抓包过滤器（覆盖配置）
• --display-filter: Wireshark 显示过滤器（覆盖配置）
• --output: 保存抓包文件路径
• --json: 输出 JSON Lines 格式（基于 tshark -T ek）
• --decode-as: 自定义解码规则
• 默认格式 pcapng，参数完整后直接执行