network-sketcher · 智能体框架与编排

一、项目背景与起源

Network Sketcher 是思科开源的 AI 网络拓扑设计工具，由思科旗下 cisco-open 组织开发和维护。2023年8月发布至今已更新至 Ver3.1.2 版本（2026年5月），累计获得 366 stars 和 18 forks，是目前网络工程领域少有的、将 AI 大模型（LLM）与图形化网络设计深度融合的开源项目。

这个工具诞生的背景很现实：传统的网络拓扑绘制依赖 Visio/YEd 等商业软件，工程师需要手动摆放设备图标、逐一标注 IP 地址和接口信息，效率低下且难以保持文档与真实配置的一致性。而 Network Sketcher 通过三种使用模式——Local MCP（AI原生）、Online（Web服务） 和 Offline（桌面GUI+CLI）——让用户既能享受 AI 的辅助设计能力，又能在纯本地环境中独立运行，覆盖了从 AI 开发者到网络运维工程师的广泛用户群体。

二、核心功能详解

2.1 三大版本对比

模式	界面	AI 集成	数据格式	适用场景
Local MCP	LLM 客户端（Cursor/Claude Code 等）	最直接，stdio 通信	`.nsm`	AI 开发者、自动化工作流
Online	Web 浏览器	通过 MCP server 调用	`.xlsx` / `.nsm`	多用户协作、跨平台
Offline	tkinter GUI / CLI	无	`.xlsx`	本地离线运维、单人使用

Local MCP 是最有特色的模式——通过 Anthropic 官方 MCP Python SDK（mcp>=1.0.0）将网络设计能力封装为标准 MCP 工具，LLM 客户端可直接调用 add_device、show_l3_diagram、export_config 等工具，无需打开浏览器或手动操作 GUI，实现了真正意义上"用自然语言驱动网络设计"的体验。

2.2 网络拓扑生成能力

项目的核心引擎位于 ns_engine/ 模块，约35个 Python 文件，分层实现：

L1 拓扑（物理层）：根据设备接口信息生成物理连接图（nsm_l1_master_create.py、nsm_l1_diagram_create.py）
L2 拓扑（二层网络）：生成 VLAN、广播域、Trunk 链路图（nsm_ddx_figure.py → SVG 渲染）
L3 拓扑（三层网络）：基于 IP 规划和路由信息生成网络层拓扑图（nsm_ddx_svg_l3.py）

所有图表均输出为 PowerPoint（.pptx） 和 Excel 配置表 两种格式，可直接用于项目文档或导入网络设备。Excel 文件同时作为主数据文件（Master File），所有设备信息、属性表、接口表均集中存储在 .xlsx 中，通过 python-pptx 生成配套图表。

2.3 AI 原生设计（Local MCP）

Local MCP 版本将 ns_engine 封装为 MCP server，对外暴露约50+工具命令，包括：

show area / show device / show l1_interface / show l2_broadcast_domain
add device / add area / add interface
rename device / rename area
delete device / delete link
export l3_diagram / export ai_context_file

LLM 通过 stdio 协议与 MCP server 通信，调用这些工具完成"创建网络拓扑 → 分配 IP 地址段 → 生成配置模板"的全流程自动化。例如，用户对 Cursor 说"帮我设计一个三数据中心网络，每个中心有2台核心交换机"，LLM 会自动调用 add_device 添加设备、show area 创建区域、export l3_diagram 导出拓扑图。

三、技术架构分析

3.1 代码规模与结构

项目纯 Python 实现，总代码量约 4.4M 字符（语言统计），主要分布在三个子目录：

network-sketcher_offline/ — 核心代码，33个文件，主逻辑（CLI、GUI、图表生成）
network-sketcher_online/ — Web 服务，基于 Flask（ns_web_start.py 约348KB），提供 HTTPS Web UI
network-sketcher_local_mcp/ — MCP 封装，约6万行核心引擎代码被复用

ns_engine/ 是三层版本共享的核心引擎，包含：

nsm_adapter.py — 引擎引导和 CLI 适配层
nsm_def.py — 数据模型定义
nsm_io.py — Excel 读写（依赖 openpyxl）
nsm_ddx_*.py — 各层图表 SVG/PPTX 生成

3.2 依赖栈

Flask >= 3.1.0          # Online 版 Web 服务
python-pptx >= 0.6.21   # PowerPoint 图表生成
openpyxl <= 3.1.5       # Excel 主文件读写
ciscoconfparse >= 1.9.0 # 思科配置解析
networkx >= 3.4.2       # 网络图算法
numpy >= 1.24.2         # 数值计算
pandas >= 2.2.0         # 高性能数据处理
pyarrow >= 15.0.0       # .nsm 新格式（ZIP+Parquet）序列化
mcp >= 1.0.0            # Anthropic MCP SDK

关键洞察：项目未使用任何深度学习或 AI 模型推理框架（如 PyTorch、Transformers），而是将 AI 能力完全委托给外部 LLM（MCP 客户端）。这种架构让项目保持了轻量级，同时通过 MCP 协议解耦了 AI 能力，项目本身专注于网络工程领域的知识处理。

四、部署体验

4.1 部署难度：简单（2/5）

项目不提供 Docker 支持，需要手动安装 Python 依赖，但依赖关系清晰，技术栈均为标准库或主流 pip 包，没有复杂的编译依赖。

Online 版本部署步骤：

pip install -r requirements_online.txt（Flask + ns_engine 依赖）
python ns_web_start.py（启动 HTTPS 服务）
浏览器访问配置的 URL

Offline 版本：无需安装，直接下载 network-sketcher_offline/ 文件夹，在有 Python + tkinter 环境的机器上运行 ns_cli.py 或 network_sketcher.py。

Local MCP 版本：需先安装 Online 版，然后在 MCP 客户端（如 Claude Code）中配置 server 路径。

4.2 硬件需求

资源	需求
GPU	❌ 不需要
内存	2GB+
磁盘	1GB（包含示例数据）
操作系统	Windows / macOS / Linux

五、局限性与挑战

5.1 使用门槛较高

虽然项目自称"简单"，但对于非网络工程背景的用户（如 AI 开发者），理解 L1/L2/L3 网络拓扑模型、IP地址规划、Cisco 设备配置语法等概念，仍需要一定的学习成本。Local MCP 模式虽然降低了 AI 集成门槛，但前提是用户已配置好 Cursor/Claude Code + MCP 环境。

5.2 多版本并行维护

三个版本（Online / Offline / Local MCP）共享 ns_engine，但各有独立的入口文件和配置。这种"一体三面"的架构在保持同步更新时需要额外小心——特别是 Local MCP 版本的 ns_mcp_server.py 依赖 Online 版的目录结构，如果用户在独立部署时移动了目录，可能导致 sys.path 找不到 ns_engine。

5.3 无容器化

没有 Dockerfile 或 docker-compose，意味着无法享受容器化部署的隔离性和可重复性。对于需要在服务器环境长期运行 Online 版的用户，需要自己包装 Docker。

六、行业意义与增长趋势

366 stars 对于一个细分领域（网络工程 + AI）的工具来说，表现相当不错。项目从 2023年8月起步，经历了多次大版本迭代（Ver3.0 → Ver3.1），活跃的版本更新（最新推送 2026-06-10）说明项目仍在积极维护。

从趋势看，MCP（Model Context Protocol）在 2025-2026 年迅速成为 AI Agent 领域的标准接口协议，Network Sketcher 敏锐地抓住了这个技术窗口，提供了目前业界少有的网络设计 MCP 工具集。随着 AI 网络助手（如 Cursor、Claude Code）普及，这类工具的潜在用户群正在快速增长。

七、快速上手建议

推荐路径（AI 开发者）：

安装 Claude Code / Cursor
下载 Network Sketcher，定位到 network-sketcher_local_mcp/ 目录
安装 pip install -r requirements_mcp.txt
配置 MCP 客户端，指向 python ns_mcp_server.py
对 LLM 说："帮我设计一个简单的小型办公室网络，包含1台路由器、2台交换机和10台终端设备"

推荐路径（网络工程师）：

下载 network-sketcher_offline/ 文件夹
确保 Python 3.10+ 和 tkinter 已安装
双击 network_sketcher.py 打开 GUI，开始绘制拓扑

⚠️ 注意：项目不提供安装包或 Docker 镜像，需要 Python 运行环境。Windows 用户建议使用 Anaconda 创建独立环境，避免 tkinter 依赖问题。

一、项目背景与起源

二、核心功能详解

2.1 三大版本对比

模式	界面	AI 集成	数据格式	适用场景
Local MCP	LLM 客户端（Cursor/Claude Code 等）	最直接，stdio 通信	`.nsm`	AI 开发者、自动化工作流
Online	Web 浏览器	通过 MCP server 调用	`.xlsx` / `.nsm`	多用户协作、跨平台
Offline	tkinter GUI / CLI	无	`.xlsx`	本地离线运维、单人使用

2.2 网络拓扑生成能力

项目的核心引擎位于 ns_engine/ 模块，约35个 Python 文件，分层实现：

L1 拓扑（物理层）：根据设备接口信息生成物理连接图（nsm_l1_master_create.py、nsm_l1_diagram_create.py）
L2 拓扑（二层网络）：生成 VLAN、广播域、Trunk 链路图（nsm_ddx_figure.py → SVG 渲染）
L3 拓扑（三层网络）：基于 IP 规划和路由信息生成网络层拓扑图（nsm_ddx_svg_l3.py）

2.3 AI 原生设计（Local MCP）

Local MCP 版本将 ns_engine 封装为 MCP server，对外暴露约50+工具命令，包括：

show area / show device / show l1_interface / show l2_broadcast_domain
add device / add area / add interface
rename device / rename area
delete device / delete link
export l3_diagram / export ai_context_file

三、技术架构分析

3.1 代码规模与结构

项目纯 Python 实现，总代码量约 4.4M 字符（语言统计），主要分布在三个子目录：

network-sketcher_offline/ — 核心代码，33个文件，主逻辑（CLI、GUI、图表生成）
network-sketcher_online/ — Web 服务，基于 Flask（ns_web_start.py 约348KB），提供 HTTPS Web UI
network-sketcher_local_mcp/ — MCP 封装，约6万行核心引擎代码被复用

ns_engine/ 是三层版本共享的核心引擎，包含：

nsm_adapter.py — 引擎引导和 CLI 适配层
nsm_def.py — 数据模型定义
nsm_io.py — Excel 读写（依赖 openpyxl）
nsm_ddx_*.py — 各层图表 SVG/PPTX 生成

3.2 依赖栈

Flask >= 3.1.0          # Online 版 Web 服务
python-pptx >= 0.6.21   # PowerPoint 图表生成
openpyxl <= 3.1.5       # Excel 主文件读写
ciscoconfparse >= 1.9.0 # 思科配置解析
networkx >= 3.4.2       # 网络图算法
numpy >= 1.24.2         # 数值计算
pandas >= 2.2.0         # 高性能数据处理
pyarrow >= 15.0.0       # .nsm 新格式（ZIP+Parquet）序列化
mcp >= 1.0.0            # Anthropic MCP SDK

四、部署体验

4.1 部署难度：简单（2/5）

项目不提供 Docker 支持，需要手动安装 Python 依赖，但依赖关系清晰，技术栈均为标准库或主流 pip 包，没有复杂的编译依赖。

Online 版本部署步骤：

pip install -r requirements_online.txt（Flask + ns_engine 依赖）
python ns_web_start.py（启动 HTTPS 服务）
浏览器访问配置的 URL

Offline 版本：无需安装，直接下载 network-sketcher_offline/ 文件夹，在有 Python + tkinter 环境的机器上运行 ns_cli.py 或 network_sketcher.py。

Local MCP 版本：需先安装 Online 版，然后在 MCP 客户端（如 Claude Code）中配置 server 路径。

4.2 硬件需求

资源	需求
GPU	❌ 不需要
内存	2GB+
磁盘	1GB（包含示例数据）
操作系统	Windows / macOS / Linux

五、局限性与挑战

5.1 使用门槛较高

5.2 多版本并行维护

5.3 无容器化

没有 Dockerfile 或 docker-compose，意味着无法享受容器化部署的隔离性和可重复性。对于需要在服务器环境长期运行 Online 版的用户，需要自己包装 Docker。

六、行业意义与增长趋势

七、快速上手建议

推荐路径（AI 开发者）：

安装 Claude Code / Cursor
下载 Network Sketcher，定位到 network-sketcher_local_mcp/ 目录
安装 pip install -r requirements_mcp.txt
配置 MCP 客户端，指向 python ns_mcp_server.py
对 LLM 说："帮我设计一个简单的小型办公室网络，包含1台路由器、2台交换机和10台终端设备"

推荐路径（网络工程师）：

下载 network-sketcher_offline/ 文件夹
确保 Python 3.10+ 和 tkinter 已安装
双击 network_sketcher.py 打开 GUI，开始绘制拓扑

⚠️ 注意：项目不提供安装包或 Docker 镜像，需要 Python 运行环境。Windows 用户建议使用 Anaconda 创建独立环境，避免 tkinter 依赖问题。