嵌入式网络调试时，用统一脚本完成接口发现、抓包、pcap…

需要发现网络接口、抓包/分析 pcap、测试连通性、扫描端口或统计流量时使用。

适用场景

解决思路

1. 使用 `<skill-dir>/scripts/` 下的脚本执行网络调试；环境级配置放在 `<skill-dir>/config.json`，仅配置工具路径；工程级网络参数放在 `<workspace>/.embeddedskills/config.json`；需要端口/协议映射时读取 `<skill-dir>/references/common_protocols.json`。
2. 确认依赖：`tshark`（随 Wireshark 安装并加入 PATH）、`dumpcap`（随 Wireshark 安装）；可选 `capinfos`；Windows 自带 `ipconfig`、`ping`、`tracert`、`netstat`、`arp`、`nslookup`；Python 3.x 仅标准库；抓包需要 Npcap 驱动，部分环境需要管理员权限。
3. 检查 `tshark` 是否可用；若不可用，提示用户安装 Wireshark（含 tshark）并确认已加入 PATH；若需要抓包，还要提示安装 Npcap 驱动；依赖缺失时终止执行并输出 `status: error` 及安装指引。
4. 按优先级解析参数：CLI 参数（如 `--interface`、`--target` 等）> 工程级配置 `.embeddedskills/config.json` 中的 `net` 部分 > 状态文件 `.embeddedskills/state.json` 中的历史记录 > 默认值；脚本通过 CLI 参数接收覆盖值，多个来源冲突时以更高优先级为准，并在输出 summary 中注明被覆盖的来源。
5. 若无子命令，默认执行 `iface`（列出网络接口）。
6. 成功执行后，将确认的参数写回 `.embeddedskills/config.json` 工程配置。
7. 运行对应脚本并输出统一结构化 JSON 结果。
8. 失败时优先提示权限、Npcap、过滤器、接口选择等问题。
9. 交互时优先用解析后的参数直接执行，不额外询问；连接失败时再询问用户并引导修改配置。
10. 未给扫描范围时默认收敛到单主机、小范围端口。
11. 结果中明确回显目标范围、过滤器和持续时间。
12. 抓包结果优先总结异常协议、重传、RST 等。
13. 抓包失败优先提示权限和 Npcap 问题。
14. 执行 `iface`：`python <skill-dir>/scripts/net_iface.py [--filter <关键词>] [--tshark] [--json]`；`--tshark` 同时显示 tshark 抓包接口索引映射，`--filter` 按关键词筛选接口，无副作用可直接执行。
15. 执行 `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`、`--display-filter` 覆盖配置；`--output` 保存抓包文件；`--json` 输出 JSON Lines（基于 `tshark -T ek`）；`--decode-as` 自定义解码规则；默认格式 `pcapng`，参数完整后直接执行。
16. 执行 `analyze`：`python <skill-dir>/scripts/net_analyze.py <pcap_file> [--mode <summary|protocols|conversations|endpoints|io|anomalies|all>] [--filter <显示过滤器>] [--top <数量>] [--decode-as <规则>] [--export-fields <字段列表>] [--output <CSV路径>] [--json]`；基于 `tshark` 和 `capinfos` 进行离线分析；`--mode all` 输出全部分析维度；无副作用可直接执行。
17. 执行 `ping`：`python <skill-dir>/scripts/net_ping.py [--target <目标>] [--tcp <端口>] [--count <次数>] [--traceroute] [--concurrent <线程数>] [--timeout <毫秒>] [--json]`；目标按优先级解析；`--target` 覆盖配置；`--tcp` 做 TCP 连通性测试；`--traceroute` 执行路由追踪；`--timeout` 覆盖超时；参数完整后直接执行。
18. 执行 `scan`：`python <skill-dir>/scripts/net_scan.py [--target <目标>] [--ports <端口范围>] [--timeout <毫秒>] [--banner] [--concurrent <线程数>] [--json]`；目标和端口范围按优先级解析；`--target` 覆盖目标；`--ports` 如 `'80,443,8000-8100'` 覆盖端口范围；`--banner` 尝试获取服务 Banner；默认收敛到嵌入式常用端口集；参数完整后直接执行。
19. 执行 `stats`：`python <skill-dir>/scripts/net_stats.py [--interface <接口>] [--duration <秒>] [--display-filter <过滤器>] [--interval <秒>] [--mode <overview|protocol|endpoint|port>] [--json]`；接口和时长按优先级解析；`--interface`、`--duration`、`--display-filter` 覆盖配置；默认输出按时段汇总的 JSON；无副作用可直接执行。
20. 统一输出格式：成功对象包含 `status: ok`、`action`、`summary`、`details`；错误对象包含 `status: error`、`action`、`error.code`、`error.message`；`capture --json` 输出 JSON Lines，进度信息写入 stderr。
21. 配置写入：环境级 `<skill-dir>/config.json` 使用 `tshark_exe`、`capinfos_exe`；工程级 `.embeddedskills/config.json` 的 `net` 部分使用 `interface`、`target`、`capture_filter`、`display_filter`、`duration`、`timeout_ms`、`scan_ports`、`capture_format`、`log_dir`。
22. 需要查询嵌入式常用端口和协议映射时，读取 `references/common_protocols.json`。

适用边界 · 注意事项

• 未安装 Wireshark/tshark/dumpcap 或未加入 PATH 时，无法执行抓包和分析。
• 抓包需要 Npcap 驱动且部分环境需管理员权限；缺少驱动或权限时避免抓包。
• 不适用于非网络调试、无需 pcap/连通性/端口扫描/流量统计的场景。