GNS3/gns3-skills

# GNS3-Skills GNS3 领域知识库 —— 包含全面的网络故障注入场景、协议分析规则和设备命令参考，专为集成到 GNS3 server 的 AI 驱动网络实验室助手而设计。 本仓库目前包含 **50 个 YAML 格式的 skill 定义**，涵盖 **815 个故障注入场景**，涉及 60 多种网络协议和技术 —— 从 PPP 串行链路到 SRv6 和 EVPN。 ## 目录 - [目录结构](#directory-structure) - [架构](#architecture) - [Skill 格式](#skill-format) - [注入 Skills](#injection-skills) - [设备 Skills](#device-skills) - [严重性与难度等级](#severity--difficulty-levels) - [在 GNS3 Copilot 中的使用](#usage-with-gns3-copilot) - [CI/CD 验证](#cicd-validation) - [贡献](#contributing) - [许可证](#license) ## 目录结构 ``` GNS3-Skills/ ├── injection/ # 50 fault injection skill files (YAML) │ ├── bgp_issues.yaml │ ├── ospf_issues.yaml │ ├── srv6_issues.yaml │ └── ... ├── device/ # Device interface definitions (YAML) │ └── vpcs.yaml # VPCS virtual PC commands ├── feature/ # Network planning and design functionalities (YAML) │ └── topology_planner.yaml # Topology design automation ├── prompts/ # LLM system prompts for agent modes │ ├── troubleshooting_injection.md │ ├── lab_automation_assistant.md │ ├── teaching_assistant.md │ └── title.md ├── packet_analysis/ # Packet capture analysis rules (tshark field extraction) │ ├── arp.yaml │ ├── bgp.yaml │ ├── ospf.yaml │ ├── icmp.yaml │ ├── tcp.yaml │ └── tshark_fields.yaml (field query reference) ├── config/ # Runtime configuration │ └── forbidden_commands.txt ├── .github/ # CI/CD and validation │ ├── workflows/yaml-validation.yml │ ├── scripts/validate_yaml.py │ ├── scripts/validate_skills.py │ └── scripts/validate_tshark_fields.py ├── .githooks/ # Pre-commit hooks │ └── pre-commit └── SKILLS_SUMMARY.md # Full statistics and breakdown ``` ## 架构 本仓库构成了 GNS3 Copilot 的 **知识层**。这里定义的 skills 并非独立的可执行单元 —— 它们是结构化的领域知识，由注册在 `gns3_copilot` agent 模块中的 LangChain 工具所调用。 ``` graph TB subgraph GNS3_Copilot["GNS3 Copilot (LangGraph Agent)"] LLM["LLM (with System Prompt)
prompts/troubleshooting_injection.md
prompts/lab_automation_assistant.md"] subgraph Skills_Tools["LangChain Skills Tools"] Injection_Tools["injection_skills (Tool)"] Device_Tools["device_skills (Tool)"] Packet_Tools["packet_analysis_skills (Tool)"] end subgraph GNS3_Tools["GNS3 Operation Tools"] GNS3_Ops["GNS3CreateNode, GNS3StartNode
PacketAnalysis, etc."] end LLM --> Skills_Tools LLM --> GNS3_Tools end subgraph Skills_Repo["GNS3-Skills Repository"] Injection_Files["injection/
ospf_issues.yaml
bgp_issues.yaml
... (50 files)"] Device_Files["device/
vpcs.yaml"] Feature_Files["feature/
topology_planner.yaml"] Packet_Files["packet_analysis/
ospf.yaml
bgp.yaml
arp.yaml
... (60 files)"] end Injection_Tools --> Injection_Files Device_Tools --> Device_Files Device_Tools --> Feature_Files Packet_Tools --> Packet_Files classDef llmStyle fill:#f9f,stroke:#333,stroke-width:2px classDef toolsStyle fill:#bbf,stroke:#333,stroke-width:1px classDef repoStyle fill:#bfb,stroke:#333,stroke-width:1px class LLM llmStyle class Injection_Tools,Device_Tools,Packet_Tools,GNS3_Ops toolsStyle class Injection_Files,Device_Files,Feature_Files,Packet_Files repoStyle ``` **数据流：** 1. GNS3 Copilot 启动 → `SkillsManager` 克隆/拉取本仓库 → `SkillsLoader` 解析 YAML 文件 2. 解析后的数据填充到三个内存注册表中：`INJECTION_SKILLS_REGISTRY`、`SKILLS_REGISTRY`、`PACKET_ANALYSIS_REGISTRY` 3. 三个 LangChain 工具（`InjectionSkillsTool`、`DeviceSkillsTool`、`PacketAnalysisSkillsTool`）通过工具调用将这些注册表暴露给 LLM 4. 独立的可执行工具（例如，`PacketAnalysisTool` → tshark，`ExecuteMultipleDeviceConfigCommands` → 网络设备）执行实际操作 5. Agent prompt（`prompts/*.md`）被直接加载到 LLM 的系统消息中，以定义角色和工作流程 用 Claude Code 的话来说，这种架构类似于在独立的仓库中分别拥有 **references/** 数据和 **scripts/** 可执行文件，它们通过自定义的 agent 框架而不是 Claude Code 运行时连接在一起。 ## Skill 格式 Skills 根据其类型以两种格式定义： ### 注入 Skills 用于故障注入场景（`injection/` 中的大多数文件）： ``` name: "Skill Name" description: "Skill description" category: "injection" # optional protocols: # optional, list of related protocols - ospf - ospfv3 issues: issue_key: # unique identifier (snake_case) name: "Issue Name" # required description: "..." # required severity: "low|medium|high|critical" # optional difficulty: "beginner|intermediate|advanced" # optional protocols: # optional - ospf symptoms: # optional - "Symptom 1" troubleshooting_hints: # optional - "Hint 1" applicability: "..." # optional ``` ### 设备 Skills 用于定义设备命令和接口（例如，`device/vpcs.yaml`）： ``` name: "Device Name" description: "Device description" device_type: "gns3_vpcs_telnet" # required, used as the skill key category: "device" config_commands: # configuration syntax definitions ip_config: syntax: "ip

/ " example: "ip 10.0.0.1/24 10.0.0.254" description: "..." display_commands: # diagnostic commands ping: syntax: "ping " description: "..." notes: # important operational notes - "Warning: VPCS is not a router" troubleshooting: # common issue guide ping_failed: - "Use show ip to verify IP configuration" command_aliases: # LLM command mapping test_connectivity: "ping " ``` ## 严重性与难度等级 ### 严重性 | 等级 | 描述 | |-------|-------------| | **low** | 影响极小，易于识别 | | **medium** | 影响明显，需要一定排查 | | **high** | 影响严重，影响多个服务 | | **critical** | 全网影响，属于紧急级别 | ### 难度 | 等级 | 描述 | |-------|-------------| | **beginner** | 需要基础故障排查技能 | | **intermediate** | 需要扎实的网络知识 | | **advanced** | 需要深厚的协议专业知识 | ## 在 GNS3 Copilot 中的使用 Skills 会被 GNS3 Copilot agent 从本仓库自动加载到三个内存注册表中： | 注册表 | 源目录 | 暴露方式 | 用途 | |---|---|---|---| | `INJECTION_SKILLS_REGISTRY` | `injection/` | `injection_skills` 工具 | 故障注入场景 | | `SKILLS_REGISTRY` | `device/`、`feature/` | `device_skills` 工具 | 设备接口定义，网络规划功能 | | `PACKET_ANALYSIS_REGISTRY` | `packet_analysis/` | `packet_analysis_skills` 工具 | 协议 tshark 字段定义 | LLM 在运行时通过工具调用查询这些注册表，然后使用独立的可执行工具（例如，用于运行 tshark 的 `PacketAnalysisTool`，用于配置设备的 `ExecuteMultipleDeviceConfigCommands`）对返回的知识进行操作。 ### 配置 在 `gns3server/agent/gns3_copilot/configs/skills_config.py` 中： ``` SKILLS_CONFIG = { "repo_url": "https://github.com/GNS3/gns3-skills.git", "branch": "main", "auto_update": True, "enabled": True, } ``` 这些值可以通过 `gns3_server.conf → [Server]` 设置覆盖：`skills_repo_url`、`skills_repo_branch`、`skills_auto_update`。 ### 手动更新 使用 GNS3 Web UI → Settings → Skills → [Update Skills] 按钮 或通过 API： ``` curl -X POST http://localhost:3080/api/skills/update ``` ### 加载行为 在启动时，`SkillsManager` 会克隆或拉取本仓库，然后 `SkillsLoader` 会将 YAML 文件解析到注册表中： - `injection/ospf_issues.yaml` → `INJECTION_SKILLS_REGISTRY["injection_ospf"]` - `device/vpcs.yaml` → `SKILLS_REGISTRY["gns3_vpcs_telnet"]`（键来自 `device_type` 字段） - `feature/topology_planner.yaml` → `SKILLS_REGISTRY["topology_planner"]`（键来自 `device_type` 字段） - `packet_analysis/ospf.yaml` → `PACKET_ANALYSIS_REGISTRY["ospf"]`（键来自 `protocol_key` 字段） `prompts/` 中的 prompt 会通过 `prompt_loader.py` 单独加载到 agent 的系统消息中。 注册表支持热重载（`POST /api/skills/update`），无需重启服务器。 ## CI/CD 验证 本项目使用 GitHub Actions 在每次推送和拉取请求时验证 YAML 文件。 ### 自动检查 - **YAML 语法验证**：确保所有 YAML 文件具有有效的语法 - **Skill 格式验证**：根据 `gns3server/agent/gns3_copilot/skills/loader.py` 中定义的 schema 验证 skill 文件 - 必填字段：`name`、`description`、`issues` - 必填的 issue 字段：`name`、`description` - 已验证的枚举：`severity` (low/medium/high/critical)、`difficulty` (beginner/intermediate/advanced) - **TShark 字段验证**：根据已安装的 tshark 版本验证 `packet_analysis/*.yaml` 中的所有 `tshark_field` 值 ### 本地验证（推荐） 安装 pre-commit 钩子以便在提交前验证文件： ``` git config core.hooksPath .githooks ``` 或手动运行验证： ``` # 验证 YAML 语法 python3 .github/scripts/validate_yaml.py # 验证 skill 格式 python3 .github/scripts/validate_skills.py # 验证 tshark fields（需要已安装 tshark） python3 .github/scripts/validate_tshark_fields.py ``` 有关 CI/CD 的详细文档，请参阅 [`.github/scripts/README.md`](.github/scripts/README.md)。 ## 许可证 GPL-3.0-or-later ## 版权 Copyright (C) 2025 GNS3 Contributors ## 作者 由 Yue Guobin (@yueguobin) 开发

标签：GNS3, 故障注入, 网络仿真, 网络协议分析, 网络工程, 逆向工具