gns3-server/docs/gns3-copilot/implemented/fault-injection-overview.md

GNS3-Copilot 故障注入概览

核心流程

flowchart TB
    subgraph "① 接口触发与模式切换"
        A["POST /chat/inject\n用户请求注入故障"] --> B["验证项目已打开"]
        B --> C["设置copilot_mode =\ntroubleshooting_injection"]
        C --> D["启动Agent\n携带故障注入工具集"]
    end

    subgraph "② 拓扑分析与故障选型"
        D --> E["GNS3TopologyTool\n获取拓扑信息"]
        E --> F["ExecuteMultipleDeviceCommands\n获取设备配置"]
        F --> G["InjectionSkillsTool\n查询可用故障类型"]
        G --> H{"注入技能仓库\ngns3/gns3-skills"}
        H --> I["返回匹配的故障定义\n含配置注入命令"]
    end

    subgraph "③ 故障注入"
        I --> J["选择注入方式"]
        J --> K["ExecuteMultipleDeviceConfigCommands\n注入配置变更"]
        J --> L["GNS3PacketFilterTool\n注入链路层故障"]
    end

    subgraph "④ 结果确认"
        K --> M["验证故障生效"]
        L --> M
        M --> N["记录故障详情\n含恢复命令"]
    end

工具总览

工具	源文件	作用	可用模式
InjectionSkillsTool	registry.py（skills 模块）	查询协议级故障定义（配置变更命令）	troubleshooting_injection
GNS3PacketFilterTool	gns3_packet_filter.py	链路层故障注入（延迟、丢包、损坏、BPF）	troubleshooting_injection
ExecuteMultipleDeviceConfigCommands	config_tools_nornir.py	批量执行设备配置变更	troubleshooting_injection
ExecuteMultipleDeviceCommands	display_tools_nornir.py	读取设备配置（只读）	troubleshooting_injection
GNS3TopologyTool	gns3_client	获取项目拓扑信息	troubleshooting_injection

故障注入 API

端点	功能
POST /v3/projects/{pid}/chat/inject	触发故障注入，设置 troubleshooting_injection 模式后启动 Agent

前置条件：项目必须为 opened 状态，否则返回 403。

GNS3PacketFilterTool 链路滤波器

滤波器类型	功能	参数
delay	延迟 + 抖动	[latency(0-32767), jitter(0-32767)]
packet_loss	丢包率	[chance(0-100)]
corrupt	包损坏率	[chance(0-100)]
frequency_drop	每 N 包丢弃一个	[frequency(-1~32767)]
bpf	Berkeley Packet Filter	表达式文本

Agent 工作流（LangGraph）

sequenceDiagram
    participant U as User
    participant API as POST /chat/inject
    participant LLM as LLM Node
    participant Topo as GNS3TopologyTool
    participant DC as ExecuteMultipleDeviceCommands
    participant CC as ExecuteMultipleDeviceConfigCommands
    participant Skill as InjectionSkillsTool
    participant Filter as GNS3PacketFilterTool

    U->>API: 注入一个OSPF故障
    API->>LLM: 设置mode=troubleshooting_injection
    LLM->>Topo: 获取拓扑
    Topo-->>LLM: 拓扑信息
    LLM->>DC: 查看设备配置
    DC-->>LLM: Running配置
    LLM->>Skill: list context=["ospf"]
    Skill-->>LLM: 匹配的故障类型
    LLM->>Skill: get device_type=injection_ospf
    Skill-->>LLM: 故障定义+注入命令
    LLM->>CC: 执行配置注入
    CC-->>LLM: 注入结果
    LLM->>Filter: set filters={delay:[200,50]}
    Filter-->>LLM: 链路延迟注入成功
    LLM-->>U: 故障已注入，含恢复命令

关键设计要点

1. 专用 API 入口 — POST /chat/inject 端点专门用于故障注入，自动切换为 troubleshooting_injection 模式
2. LLM 主导故障选型 — LLM 分析拓扑后通过 InjectionSkillsTool 查询匹配协议栈的故障，不硬编码故障场景
3. 双层注入 — 设备级配置变更 + 链路级网络损伤，覆盖完整排错场景
4. 故障可逆 — 每条注入均附带恢复命令，链路滤波器可通过 action: clear 一键清除
5. 安全前置 — BPF 语法通过 tshark 预验证，配置命令受 command_filter 限制
6. 上下文过滤 — InjectionSkillsTool 强制要求传入 context 参数，只返回与拓扑协议匹配的故障