From 305eb58b1c0f330e76e86934a1dfa94deec6143e Mon Sep 17 00:00:00 2001 From: YueGuobin Date: Thu, 28 May 2026 14:18:24 +0800 Subject: [PATCH] docs: add overview docs for packet analysis, fault injection, and AI assistant --- .../implemented/ai-assistant-overview.en.md | 161 ++++++++++++++++++ .../implemented/ai-assistant-overview.md | 161 ++++++++++++++++++ .../fault-injection-overview.en.md | 104 +++++++++++ .../implemented/fault-injection-overview.md | 104 +++++++++++ .../packet-analysis-overview.en.md | 74 ++++++++ .../implemented/packet-analysis-overview.md | 75 ++++++++ 6 files changed, 679 insertions(+) create mode 100644 docs/gns3-copilot/implemented/ai-assistant-overview.en.md create mode 100644 docs/gns3-copilot/implemented/ai-assistant-overview.md create mode 100644 docs/gns3-copilot/implemented/fault-injection-overview.en.md create mode 100644 docs/gns3-copilot/implemented/fault-injection-overview.md create mode 100644 docs/gns3-copilot/implemented/packet-analysis-overview.en.md create mode 100644 docs/gns3-copilot/implemented/packet-analysis-overview.md diff --git a/docs/gns3-copilot/implemented/ai-assistant-overview.en.md b/docs/gns3-copilot/implemented/ai-assistant-overview.en.md new file mode 100644 index 000000000..b01c1d20f --- /dev/null +++ b/docs/gns3-copilot/implemented/ai-assistant-overview.en.md @@ -0,0 +1,161 @@ + + +# GNS3-Copilot AI Assistant Overview + +## Overall Architecture + +```mermaid +flowchart TB + subgraph "Client" + A["Web UI"] --> B["SSE Streaming"] + end + + subgraph "FastAPI Route Layer" + B --> C["POST /chat/stream\nPOST /chat/inject"] + C --> D["Auth + LLM Config Loading\nSet ContextVars"] + end + + subgraph "AgentService (Project-level)" + D --> E["LangGraph Agent\nStateGraph"] + E --> F["SQLite Checkpointer\ncopilot_checkpoints.db"] + end + + subgraph "LangGraph Workflow" + E --> G["llm_call node\nmodel invocation"] + E --> H["tool_node\ntool execution"] + E --> I["title_generator_node\nauto title"] + E --> J["abort_handler_node\ninterrupt handling"] + end + + subgraph "Three Copilot Modes" + G --> K["teaching_assistant\ndiagnostic read-only"] + G --> L["lab_automation_assistant\nfull control"] + G --> M["troubleshooting_injection\nfault injection"] + end + + subgraph "LLM Config System" + D --> N["User configs\nGroup config inheritance\nAPI key encryption"] + end +``` + +## API Endpoints + +| Endpoint | Function | +|---|---| +| `POST /v3/projects/{pid}/chat/stream` | Streaming conversation (SSE), supports three copilot modes | +| `POST /v3/projects/{pid}/chat/inject` | Fault injection entry, auto-switches to `troubleshooting_injection` mode | +| `GET /v3/projects/{pid}/chat/sessions` | List sessions (supports filtering, pagination) | +| `DELETE /v3/projects/{pid}/chat/sessions/{sid}` | Delete session | +| `PATCH /v3/projects/{pid}/chat/sessions/{sid}` | Update session (rename, pin) | +| `POST /v3/projects/{pid}/chat/sessions/{sid}/abort` | Abort an active session | + +## LangGraph Agent Workflow + +```mermaid +sequenceDiagram + participant U as User + participant API as FastAPI + participant AS as AgentService + participant LLM as LLM Node + participant Tool as Tool Node + participant TGen as Title Node + + U->>API: send message + API->>AS: stream_chat() + AS->>AS: set ContextVars
(jwt_token, llm_config) + + Note over AS,LLM: llm_call node + AS->>LLM: invoke pre-compiled model + LLM->>LLM: pre_model_hook
inject topology + trim context + LLM-->>AS: AI reply (may include tool_calls) + + opt has tool calls + AS->>Tool: execute tools + Tool-->>AS: tool results + AS->>LLM: continue LLM call + end + + opt first turn and no title + AS->>TGen: auto-generate title + TGen-->>AS: session title + end + + AS-->>API: SSE streaming response + API-->>U: stream output +``` + +## Three Copilot Modes + +### Mode Comparison + +| Mode | Tool Scope | Use Case | +|---|---|---| +| `teaching_assistant` (default) | Diagnostic read-only + packet analysis + node management | Teaching demos, troubleshooting guidance | +| `lab_automation_assistant` | All tools (including config changes) | Lab automation, device configuration | +| `troubleshooting_injection` | Fault injection tool set | Troubleshooting practice, fault simulation | + +### Tool Binding Details + +| Tool | teaching_assistant | lab_automation_assistant | troubleshooting_injection | +|---|---|---|---| +| `GNS3TemplateTool` get templates | ✓ | ✓ | | +| `GNS3CreateNodeTool` create nodes | ✓ | ✓ | | +| `GNS3LinkTool` create links | ✓ | ✓ | | +| `GNS3StartNodeTool` start nodes | ✓ | ✓ | | +| `GNS3UpdateNodeNameTool` rename | ✓ | ✓ | | +| `GNS3StopNodeTool` stop nodes | | ✓ | | +| `GNS3SuspendNodeTool` suspend nodes | | ✓ | | +| `ExecuteMultipleDeviceCommands` read-only commands | ✓ | ✓ | ✓ | +| `ExecuteMultipleDeviceConfigCommands` config commands | | ✓ | ✓ | +| `VPCSCommands` VPCS commands | | ✓ | | +| `PacketAnalysisTool` live packet analysis | ✓ | ✓ | | +| `PacketAnalysisSkillsTool` protocol knowledge | ✓ | ✓ | | +| `DeviceSkillsTool` device skills | ✓ | ✓ | | +| `GNS3PacketFilterTool` link filters | | | ✓ | +| `InjectionSkillsTool` fault injection skills | | | ✓ | +| `GNS3TopologyTool` topology info | | | ✓ | + +The mode is selected in the `llm_call` node via `copilot_mode`, which picks the corresponding tool list and binds it to the LLM model instance through `create_base_model_with_tools(mode_tools, llm_config)`. + +## Context Window Management + +```mermaid +flowchart LR + A["LLM call triggered"] --> B["pre_model_hook"] + B --> C["Inject topology\ninto System Prompt"] + B --> D["Estimate tool definition\ntoken cost"] + B --> E["trim_messages\nby strategy"] + E --> F["conservative 60%\nbalanced 75%\naggressive 85%"] + F --> G["Invoke LLM"] +``` + +- Accurate token counting via tiktoken (`cl100k_base`) +- Three trimming strategies: conservative / balanced / aggressive +- Auto-injects `{{topology_info}}` into System Prompt + +## Session Management + +- Per-project independent SQLite database (`gns3-copilot/copilot_checkpoints.db`) +- Supports pin, rename, delete, history query +- Auto-records token usage, message count, LLM call count + +## LLM Config System + +| Feature | Description | +|---|---| +| User-level configs | Each user can independently configure provider / model / api_key | +| Group inheritance | Users auto-inherit group config when no personal config is set | +| API key encryption | Auto-encrypted at database storage | +| Optimistic locking | `version` field prevents concurrent modification conflicts | + +## Key Design Points + +1. **Project-level Isolation** — Each GNS3 project has its own Agent instance and SQLite storage +2. **ContextVars Safe Passing** — JWT token, API key exist only in memory, auto-cleared when request ends +3. **LangGraph StateGraph** — Custom nodes + conditional edges, supports ReAct loop and recursion limits +4. **SSE Streaming** — Real-time push of content / tool_call / tool_start / tool_end / error / done events +5. **Hot Reload** — System Prompt, Skills, Protocols all support runtime reload +6. **Mode-based Tool Sets** — Three copilot modes bind different tools, safely isolated by scenario diff --git a/docs/gns3-copilot/implemented/ai-assistant-overview.md b/docs/gns3-copilot/implemented/ai-assistant-overview.md new file mode 100644 index 000000000..cbb30d781 --- /dev/null +++ b/docs/gns3-copilot/implemented/ai-assistant-overview.md @@ -0,0 +1,161 @@ + + +# GNS3-Copilot AI 助手概览 + +## 整体架构 + +```mermaid +flowchart TB + subgraph "客户端" + A["Web UI"] --> B["SSE 流式响应"] + end + + subgraph "FastAPI 路由层" + B --> C["POST /chat/stream\nPOST /chat/inject"] + C --> D["认证 + LLM配置加载\n设置ContextVars"] + end + + subgraph "AgentService（项目级）" + D --> E["LangGraph Agent\nStateGraph"] + E --> F["SQLite Checkpointer\ncopilot_checkpoints.db"] + end + + subgraph "LangGraph 工作流" + E --> G["llm_call 节点\n模型调用"] + E --> H["tool_node\n工具执行"] + E --> I["title_generator_node\n自动生成标题"] + E --> J["abort_handler_node\n终止处理"] + end + + subgraph "三种 Copilot 模式" + G --> K["teaching_assistant\n诊断只读"] + G --> L["lab_automation_assistant\n完全控制"] + G --> M["troubleshooting_injection\n故障注入"] + end + + subgraph "LLM 配置系统" + D --> N["用户自有配置\n用户组配置继承\nAPI密钥加密存储"] + end +``` + +## API 端点 + +| 端点 | 功能 | +|---|---| +| `POST /v3/projects/{pid}/chat/stream` | 流式对话（SSE），支持三种 copilot 模式 | +| `POST /v3/projects/{pid}/chat/inject` | 故障注入入口，自动切换为 `troubleshooting_injection` 模式 | +| `GET /v3/projects/{pid}/chat/sessions` | 列出会话（支持过滤、分页） | +| `DELETE /v3/projects/{pid}/chat/sessions/{sid}` | 删除会话 | +| `PATCH /v3/projects/{pid}/chat/sessions/{sid}` | 更新会话（重命名、置顶） | +| `POST /v3/projects/{pid}/chat/sessions/{sid}/abort` | 终止正在进行的会话 | + +## LangGraph Agent 工作流 + +```mermaid +sequenceDiagram + participant U as User + participant API as FastAPI + participant AS as AgentService + participant LLM as LLM Node + participant Tool as Tool Node + participant TGen as Title Node + + U->>API: 发送消息 + API->>AS: stream_chat() + AS->>AS: 设置ContextVars
(jwt_token, llm_config) + + Note over AS,LLM: llm_call 节点 + AS->>LLM: invoke预编译模型 + LLM->>LLM: pre_model_hook
注入拓扑+裁剪上下文 + LLM-->>AS: AI回复(含可能tool_calls) + + alt 有工具调用 + AS->>Tool: 执行工具 + Tool-->>AS: 工具结果 + AS->>LLM: 继续LLM调用 + end + + opt 第一轮且无标题 + AS->>TGen: 自动生成标题 + TGen-->>AS: 会话标题 + end + + AS-->>API: SSE流式返回 + API-->>U: 流式输出 +``` + +## 三种 Copilot 模式 + +### 模式对照 + +| 模式 | 工具范围 | 适用场景 | +|---|---|---| +| `teaching_assistant`（默认） | 诊断只读 + 数据包分析 + 节点管理 | 教学演示、故障排查指导 | +| `lab_automation_assistant` | 全部工具（含配置变更） | 实验自动化、设备配置 | +| `troubleshooting_injection` | 故障注入工具集 | 排错练习、故障模拟 | + +### 工具绑定明细 + +| 工具 | teaching_assistant | lab_automation_assistant | troubleshooting_injection | +|---|---|---|---| +| `GNS3TemplateTool` 获取模板 | ✓ | ✓ | | +| `GNS3CreateNodeTool` 创建节点 | ✓ | ✓ | | +| `GNS3LinkTool` 创建链路 | ✓ | ✓ | | +| `GNS3StartNodeTool` 启动节点 | ✓ | ✓ | | +| `GNS3UpdateNodeNameTool` 更新名称 | ✓ | ✓ | | +| `GNS3StopNodeTool` 停止节点 | | ✓ | | +| `GNS3SuspendNodeTool` 挂起节点 | | ✓ | | +| `ExecuteMultipleDeviceCommands` 只读命令 | ✓ | ✓ | ✓ | +| `ExecuteMultipleDeviceConfigCommands` 配置命令 | | ✓ | ✓ | +| `VPCSCommands` VPCS命令 | | ✓ | | +| `PacketAnalysisTool` 实时抓包分析 | ✓ | ✓ | | +| `PacketAnalysisSkillsTool` 协议知识查询 | ✓ | ✓ | | +| `DeviceSkillsTool` 设备技能查询 | ✓ | ✓ | | +| `GNS3PacketFilterTool` 链路滤波器 | | | ✓ | +| `InjectionSkillsTool` 故障注入技能 | | | ✓ | +| `GNS3TopologyTool` 拓扑信息 | | | ✓ | + +模式通过 `llm_call` 节点中的 `copilot_mode` 选择对应工具列表，调用 `create_base_model_with_tools(mode_tools, llm_config)` 将工具绑定到 LLM 模型实例。 + +## 上下文窗口管理 + +```mermaid +flowchart LR + A["LLM调用触发"] --> B["pre_model_hook"] + B --> C["注入拓扑信息\n到System Prompt"] + B --> D["估算工具定义\ntoken消耗"] + B --> E["trim_messages\n按策略裁剪"] + E --> F["conservative 60%\nbalanced 75%\naggressive 85%"] + F --> G["调用LLM"] +``` + +- 使用 tiktoken（`cl100k_base`）精确计数 +- 三层裁剪策略：conservative / balanced / aggressive +- 自动注入 `{{topology_info}}` 到 System Prompt + +## 会话管理 + +- 每个项目独立的 SQLite 数据库（`gns3-copilot/copilot_checkpoints.db`） +- 支持置顶、重命名、删除、历史查询 +- 自动记录 token 用量、消息数、LLM 调用次数 + +## LLM 配置系统 + +| 特性 | 说明 | +|---|---| +| 用户级配置 | 每个用户可独立配置 provider / model / api_key | +| 用户组继承 | 用户未配置时自动继承所属组配置 | +| API 密钥加密 | 数据库存储时自动加密 | +| 乐观锁 | version 字段防止并发修改冲突 | + +## 关键设计要点 + +1. **项目级隔离** — 每个 GNS3 项目拥有独立的 Agent 实例和 SQLite 存储 +2. **ContextVars 安全传递** — JWT token、API key 仅存于内存，随请求结束自动清除 +3. **LangGraph StateGraph** — 自定义节点 + 条件边，支持 ReAct 循环和递归限制 +4. **流式 SSE** — 实时推送 content / tool_call / tool_start / tool_end / error / done 事件 +5. **热重载** — System Prompt、Skills、Protocols 均支持运行时重载 +6. **模式化工具集** — 三种 copilot 模式绑定不同工具组合，按场景安全隔离 diff --git a/docs/gns3-copilot/implemented/fault-injection-overview.en.md b/docs/gns3-copilot/implemented/fault-injection-overview.en.md new file mode 100644 index 000000000..00a0acfac --- /dev/null +++ b/docs/gns3-copilot/implemented/fault-injection-overview.en.md @@ -0,0 +1,104 @@ + + +# GNS3-Copilot Fault Injection Overview + +## Core Flow + +```mermaid +flowchart TB + subgraph "① API Trigger & Mode Switch" + A["POST /chat/inject\nUser requests fault injection"] --> B["Verify project is opened"] + B --> C["Set copilot_mode =\ntroubleshooting_injection"] + C --> D["Start Agent\nwith fault injection tool set"] + end + + subgraph "② Topology Analysis & Fault Selection" + D --> E["GNS3TopologyTool\nget topology info"] + E --> F["ExecuteMultipleDeviceCommands\nget device configs"] + F --> G["InjectionSkillsTool\nquery available fault types"] + G --> H{"Injection Skills Repository\ngns3/gns3-skills"} + H --> I["Return matching fault definitions\nwith config injection commands"] + end + + subgraph "③ Fault Injection" + I --> J["Choose injection method"] + J --> K["ExecuteMultipleDeviceConfigCommands\ninject config changes"] + J --> L["GNS3PacketFilterTool\ninject link-layer faults"] + end + + subgraph "④ Result Confirmation" + K --> M["Verify fault is active"] + L --> M + M --> N["Document fault details\nincluding restore commands"] + end +``` + +## Tool Overview + +| Tool | Source File | Purpose | Available Modes | +|---|---|---|---| +| `InjectionSkillsTool` | `registry.py` (skills module) | Query protocol-level fault definitions (config change commands) | troubleshooting_injection | +| `GNS3PacketFilterTool` | `gns3_packet_filter.py` | Link-layer fault injection (delay, loss, corruption, BPF) | troubleshooting_injection | +| `ExecuteMultipleDeviceConfigCommands` | `config_tools_nornir.py` | Batch device config changes | troubleshooting_injection | +| `ExecuteMultipleDeviceCommands` | `display_tools_nornir.py` | Read device configurations (read-only) | troubleshooting_injection | +| `GNS3TopologyTool` | `gns3_client` | Get project topology information | troubleshooting_injection | + +## Fault Injection API + +| Endpoint | Function | +|---|---| +| `POST /v3/projects/{pid}/chat/inject` | Trigger fault injection, sets `troubleshooting_injection` mode then starts Agent | + +**Prerequisite**: Project must be in `opened` status, otherwise returns 403. + +## GNS3PacketFilterTool Link Filters + +| Filter Type | Function | Parameters | +|---|---|---| +| `delay` | Latency + jitter | `[latency(0-32767), jitter(0-32767)]` | +| `packet_loss` | Packet loss percentage | `[chance(0-100)]` | +| `corrupt` | Packet corruption percentage | `[chance(0-100)]` | +| `frequency_drop` | Drop every Nth packet | `[frequency(-1~32767)]` | +| `bpf` | Berkeley Packet Filter | expression text | + +## Agent Workflow (LangGraph) + +```mermaid +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: Inject an OSPF fault + API->>LLM: set mode=troubleshooting_injection + LLM->>Topo: get topology + Topo-->>LLM: topology info + LLM->>DC: read device configs + DC-->>LLM: running configs + LLM->>Skill: list context=["ospf"] + Skill-->>LLM: matching fault types + LLM->>Skill: get device_type=injection_ospf + Skill-->>LLM: fault definition + injection commands + LLM->>CC: execute config injection + CC-->>LLM: injection result + LLM->>Filter: set filters={delay:[200,50]} + Filter-->>LLM: link delay injected successfully + LLM-->>U: Fault injected, restore commands included +``` + +## Key Design Points + +1. **Dedicated API Endpoint** — `POST /chat/inject` is the dedicated entry point, automatically switching to `troubleshooting_injection` mode +2. **LLM-driven Fault Selection** — The LLM analyzes the topology then queries matching faults via `InjectionSkillsTool`; no hardcoded fault scenarios +3. **Dual-Layer Injection** — Device-level config changes + link-level network impairment, covering complete troubleshooting scenarios +4. **Fully Reversible** — Every injection includes restore commands; link filters can be cleared with `action: clear` +5. **Safety First** — BPF syntax is pre-validated via tshark; config commands are restricted by `command_filter` +6. **Context Filtering** — `InjectionSkillsTool` requires a `context` parameter, returning only faults matching the topology protocols diff --git a/docs/gns3-copilot/implemented/fault-injection-overview.md b/docs/gns3-copilot/implemented/fault-injection-overview.md new file mode 100644 index 000000000..b77acc028 --- /dev/null +++ b/docs/gns3-copilot/implemented/fault-injection-overview.md @@ -0,0 +1,104 @@ + + +# GNS3-Copilot 故障注入概览 + +## 核心流程 + +```mermaid +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） + +```mermaid +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` 参数，只返回与拓扑协议匹配的故障 diff --git a/docs/gns3-copilot/implemented/packet-analysis-overview.en.md b/docs/gns3-copilot/implemented/packet-analysis-overview.en.md new file mode 100644 index 000000000..ba11a7aa3 --- /dev/null +++ b/docs/gns3-copilot/implemented/packet-analysis-overview.en.md @@ -0,0 +1,74 @@ + + +# GNS3-Copilot Real-time Packet AI Analysis Overview + +## Core Flow + +```mermaid +flowchart TB + subgraph "① Analysis Trigger & Knowledge Query" + A["User asks\n'e.g. Analyze OSPF neighbor state'"] --> B["LLM calls\nPacketAnalysisSkillsTool"] + B --> C{"Protocol Knowledge Repository\ngns3/gns3-skills"} + C --> D["Returns protocol definition\nfields/base_filter/check_rules"] + B --> E["LLM calls\nsearch_fields mode"] + E --> F["tshark -G fields\nfield name search"] + F --> G["Returns valid field names"] + end + + subgraph "② Live Capture & Analysis" + D --> H["LLM constructs tshark_args"] + G --> H + H --> I["PacketAnalysisTool\ncapture analysis mode"] + I --> J["GET /capture/file\ndownload live PCAP"] + J --> K["Pre-validate -e field names"] + K --> L["tshark -r pcap\nrun analysis"] + L --> M["Return analysis results"] + end +``` + +## Tool Overview + +| Tool | Source File | Purpose | Available Modes | +|---|---|---|---| +| `PacketAnalysisTool` | `packet_analysis_tool.py` | Download live PCAP + tshark analysis | teaching / lab_automation | +| `PacketAnalysisSkillsTool` | `registry.py` (skills module) | Query protocol-level analysis knowledge (fields, filters) | teaching / lab_automation | + +## Agent Workflow (LangGraph) + +```mermaid +sequenceDiagram + participant U as User + participant LLM as LLM Node + participant Skills as PacketAnalysisSkillsTool + participant Pcap as PacketAnalysisTool + + U->>LLM: OSPF neighbors can't establish, analyze + LLM->>Skills: get protocol=ospf + Skills-->>LLM: OSPF fields, filter definitions + LLM->>Pcap: search_fields query=ospf.hello + Pcap-->>LLM: valid -e field names + LLM->>Pcap: download PCAP + tshark_args + Pcap-->>LLM: tshark output results + LLM->>LLM: analysis reveals Dead interval mismatch + LLM-->>U: OSPF Dead interval mismatch detected +``` + +## Server Capture API + +| Endpoint | Function | +|---|---| +| `POST /v3/projects/{pid}/links/{lid}/capture/start` | Start packet capture on a link | +| `POST /v3/projects/{pid}/links/{lid}/capture/stop` | Stop packet capture | +| `GET /v3/projects/{pid}/links/{lid}/capture/file` | Download PCAP file (available even while capture is active) | +| `GET /v3/projects/{pid}/links/{lid}/capture/stream` | Stream PCAP data | +| `WS /v3/projects/{pid}/links/{lid}/capture/web-wireshark` | Web Wireshark WebSocket proxy | + +## Key Design Points + +1. **LLM-driven Analysis** — The LLM constructs tshark parameters itself; the framework does not hardcode protocol logic, only performs safety validation +2. **Live PCAP** — Captures can be downloaded and analyzed while running, no need to stop capturing +3. **Dual Knowledge Sources** — External repository provides protocol-specific knowledge; local tshark field registry provides exact field names +4. **Safety First** — Pre-validation of tshark field names prevents execution failures from invalid fields diff --git a/docs/gns3-copilot/implemented/packet-analysis-overview.md b/docs/gns3-copilot/implemented/packet-analysis-overview.md new file mode 100644 index 000000000..a45f294f4 --- /dev/null +++ b/docs/gns3-copilot/implemented/packet-analysis-overview.md @@ -0,0 +1,75 @@ + + +# GNS3-Copilot 实时数据包 AI 分析架构 + +## 核心流程 + +```mermaid +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） + +```mermaid +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 字段名预验证，避免无效字段导致执行失败