gns3-server/docs/gns3-copilot/implemented/packet-analysis-overview.md

GNS3-Copilot 实时数据包 AI 分析架构

核心流程

flowchart TB
    subgraph "① 分析触发与知识查询"
        A["用户提问\n如'分析OSPF邻居状态'"] --> B["LLM调用\nPacketAnalysisSkillsTool"]
        B --> C{"协议知识仓库\ngns3/gns3-skills"}
        C --> D["返回协议定义\nfields/base_filter/check_rules"]
        B --> E["LLM调用\nsearch_fields模式"]
        E --> F["tshark -G fields\n字段名搜索"]
        F --> G["返回有效字段名"]
    end

    subgraph "② 实时捕获与分析"
        D --> H["LLM构造tshark_args"]
        G --> H
        H --> I["PacketAnalysisTool\ncapture分析模式"]
        I --> J["GET /capture/file\n下载实时PCAP"]
        J --> K["预验证-e字段名"]
        K --> L["tshark -r pcap\n执行分析"]
        L --> M["返回分析结果"]
    end

工具总览

工具	源文件	作用	可用模式
PacketAnalysisTool	packet_analysis_tool.py	下载实时 PCAP + tshark 分析	teaching / lab_automation
PacketAnalysisSkillsTool	registry.py（skills 模块）	查询协议级分析知识（字段、过滤规则）	teaching / lab_automation

Agent 工作流（LangGraph）

sequenceDiagram
    participant U as User
    participant LLM as LLM Node
    participant Skills as PacketAnalysisSkillsTool
    participant Pcap as PacketAnalysisTool

    U->>LLM: OSPF邻居无法建立，分析一下
    LLM->>Skills: get protocol=ospf
    Skills-->>LLM: ospf字段、filter定义
    LLM->>Pcap: search_fields query=ospf.hello
    Pcap-->>LLM: 有效-e字段名
    LLM->>Pcap: 下载PCAP + tshark_args
    Pcap-->>LLM: tshark输出结果
    LLM->>LLM: 分析发现Dead间隔不匹配
    LLM-->>U: OSPF Dead间隔不一致

服务端 Capture API

端点	功能
POST /v3/projects/{pid}/links/{lid}/capture/start	启动链路上的数据包捕获
POST /v3/projects/{pid}/links/{lid}/capture/stop	停止捕获
GET /v3/projects/{pid}/links/{lid}/capture/file	下载 PCAP 文件（捕获进行中也可下载）
GET /v3/projects/{pid}/links/{lid}/capture/stream	流式传输 PCAP 数据
WS /v3/projects/{pid}/links/{lid}/capture/web-wireshark	Web Wireshark WebSocket 代理

关键设计要点

1. LLM 主导分析 — LLM 自行构造 tshark 参数，框架不做协议硬编码，只做安全验证
2. 实时 PCAP — 捕获运行时即可下载分析，无需停止抓包
3. 双重知识源 — 外部仓库提供协议预定义知识，本地 tshark field registry 提供精确字段名
4. 安全前置 — tshark 字段名预验证，避免无效字段导致执行失败