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 字段名预验证，避免无效字段导致执行失败