MagicCommander

批量生成网络设备配置 | Network Device Configuration Automation

运维团队管理着 50 台、200 台甚至 500 台网络设备。每次上新设备、变更 VLAN、调整接口描述，都要逐台登录、逐行敲命令。配置格式不统一，参数容易写错，一个项目下来，光配置交换机就要花掉一整天。

设备标签呢？手写、贴纸、Excel 打印……标签丢失、信息不全、格式混乱，运维交接时面对一堆"无名设备"无从下手。

MagicCommander 就是为解决这个问题而生的。

MagicCommander 将你的网络设备参数（Excel 表格）和设备配置模板（Jinja2 语法）结合起来，一键生成所有设备的标准化配置文件，同时自动生成可打印的设备标签。

工作原理：左侧项目浏览器管理模板和 Excel 参数，右侧 AI 对话面板通过自然语言驱动渲染、分析、优化等操作。你用 Jinja2 模板定义配置格式，在 Excel 中维护设备参数，MagicCommander 自动完成拼接和渲染，输出可直接使用的设备配置文件。

用 Jinja2 语法编写一次配置模板，后续所有项目、所有设备都基于同一套模板生成配置。模板改了，重新渲染即可，不必逐台修改。

interface {{ info['接口名'] }}
 description {{ info['终端名称'] }}
 switchport mode access
 switchport access vlan {{ info['接入VLAN'] }}
 no shutdown

设备参数天然适合用表格管理。MagicCommander 内建 Excel 编辑器，直接在软件里编辑 connection、hostname、ipaddress、parameter 等参数表，无需来回切换工具。

选好模板和参数，点击渲染，MagicCommander 逐项目生成配置文件和 YAML 中间文件。渲染进度实时可见，日志清晰记录每一步处理结果。渲染带输入指纹缓存——参数与模板未变化时，再次渲染直接复用上次结果，秒级完成。

• dry-run 预演：预览生成结果但不写入文件，确认无误再正式渲染
• Jinja2 语法校验：渲染前解析模板，提前发现语法错误
• Excel 数据校验：检查必要 sheet、列、空值、类型异常
• diff 对比：预演结果与已有输出一键对比，变更一目了然

从 hostname 表格自动提取设备名、SN、型号、机柜位置、管理 IP 等信息，生成 Word/Markdown 格式的标签文档，支持 A4/A5 纸张、横纵向打印、自定义每页标签数量，可导出 PDF。

内建 Monaco Editor（VS Code 同款编辑器），支持 Jinja2 语法高亮、代码补全、多标签页管理。智能补全会从项目 Excel 参数表自动提取字段名，输入 info[' 即可获得字段提示；切换标签页不再丢失编辑器的撤销历史。

搜索面板支持单项目与全部项目两种范围，可按文件名或文件内容搜索，文件类型可过滤（模板/Excel/输出/文本等），结果可一键跳转编辑。

内置示例模板（交换机 ASW/PSW/DOA 配置，以及 4 个 AIDC 示例项目 64/128 台 H100 · IB/RoCE）一键创建新项目；支持将现有项目保存为模板供团队复用；每个模板自动进行质量评级（A/B/C/D），基于变量复杂度、Excel 数据质量与交叉引用打分，帮助快速判断模板质量。5.0.10 起示例库扩充至 7 个（新增 H100-256台/512台-RoCE 规模化、国产-昇腾-256 多厂商场景），覆盖从 64 台到 512 台的完整规模谱系。

MagicCommander 内建 AI Hub，支持 DeepSeek、OpenAI、Claude、Gemini、Qwen、GLM、Grok、Ollama 等 9 种大模型。通过自然语言对话即可完成项目管理、配置渲染、模板分析、优化建议等操作。

AI 对话式工作流示例：

你: "帮我看看 test1 项目有哪些模板，分析一下质量"
AI: [调用 list_projects → 找到 test1]
    [调用 analyze_project → 分析 3 个模板 + 5 个 Excel]
    "test1 项目包含 3 个模板(ASW/DOA/PSW)和 5 个 Excel 文件。
     DOA.j2 复杂度较高(15 个变量)，建议拆分为子模板；
     devices.xlsx 第 3 行有空值，建议补全。"

你: "渲染 test1 项目"
AI: [调用 render_config → 生成 22 台设备配置]
    "已生成 22 台设备配置，输出目录: output/。
     需要我 dry-run 预览一下吗？"

支持 智能路由——根据任务类型（编码/分析/问答/推理）自动选择最优模型。AI 可调用 53 个内置工具，包括项目创建、配置渲染、Excel 分析、模板复杂度评估、dry-run 预演、diff 对比、标签生成、配置反向生成、技能自学习、知识库检索等。

AI Agent 工作流深化（5.0.3+）：多步自主任务编排（Plan→Execute→Verify 状态机，full_auto 自主 / advisor 每步确认 / semi_auto 关键步确认）；技能自学习闭环（反馈持久化 → 成功率评估 → 自动修订）；MCP 工具接入（可调用外部 MCP server 能力）；AI 引擎三选一（自有=默认 / Hermes / 自动）。

知识库与文档工作台（5.0.5+）：知识库（KnowledgeEngine 中文 2-gram/英文分词加权检索，Top-K 召回，AI 对话自动注入上下文）；文档工作台（评审包 / 评审 PDF / Markdown / 用户指南 / 知识库聚合一处）。

导入 AIDC 项目后，可一键切换 3D 视图：机房全景（WebGL，机柜按矩阵落位、冷热通道对向排布）+ 单柜 SVG 等距视图（U 位设备分布）。热力图按机柜功率使用率着色（绿→黄→红，与 AutoLink 对齐），点击机柜联动 2D↔3D 一致高亮，支持 PNG/SVG 导出。

• 性能基准对比基线（bench_perf.py --json/--compare）：跨版本逐场景 delta 对比，量化规模化渲染成本
• 批量渲染并发 2→3 + 按内存动态收敛（防 OOM）；Monaco 编辑器懒加载（降低首屏 bundle 与启动内存）
• 实测基准：批量渲染 100 项目 ≤90s（实测 31s）；单项目全量渲染 ≤30s（实测 0.57s）；万行参数表 ≤30s（实测 1.14s）

覆盖率棘轮只升不降（前端 ≥36% / 后端 ≥64%）；设备库联网校对（400G 端口形态对齐厂商手册）；CI e2e 加固（retry + 超时兜底）；平台依赖漏洞清零（PyJWT 迁移 + pip-audit）。

升级体验可靠化：安装包下载断点续传 + SHA-512 强校验 + 版本回滚 + 灰度通道（stable/beta）；企业部署基座（内网 updateUrl 镜像 / 代理下载 / 版本锁定，配置开关默认隐藏）；云交付（分享预览页「下载方案包」）。

MagicCommander 支持连接自建 MagicCommander Platform（基于 Gitea + FastAPI）实现团队协作：

• 模板市场：浏览、搜索、安装云端模板，支持按分类筛选
• 项目同步：本地项目一键推送至云端，云端项目拉取到本地，自动检测同步状态
• QR 扫码登录：支持飞书 / QQ / 微信扫码登录，JWT Token 自动刷新
• 通知中心：实时接收平台公告和版本更新提醒
• 用户资料：云端用户档案管理，支持平台账号绑定

MagicCommander 5.1 起把自身封装为标准 MCP Server，Claude Desktop / Codex CLI / Trae Work / VS Code 等外部 Agent 可直接查询项目、读写模板、渲染配置、生成标签，无需你手工点界面。

• 双场景模式
  • --mode compiled（编译态，默认）：只读 + 受控写入，不触碰软件本体；高危工具（删除/清库/裸 CLI/读源码）强制隐藏
  • --mode source（源码态，npm run dev:all）：追加 run_cli 白名单透传与沙箱内文件系统读写，写操作放宽为 NOTIFY
• 权限门禁（5.2.2 真实化）：gate_mode（enforce / shadow / off）配置化生效，gate_hits / block_audit 记录拦截明细；启动时执行「屏蔽规则对账」断言——规则未命中任何注册工具即拒绝启动，杜绝静默失效
• 确定性语义层：一次调用返回单层 {success, isError …} 结构 + 扁平化 payload，工具结果机器可读
• 异步长任务：渲染等长耗时工具自动异步化（task_submit / task_query / task_wait / task_cancel），MCP 调用立即返回 task_id
• 操作审计：--audit <path> 落 JSONL，audit_query 工具可按会话查询脱敏摘要
• 自检：GET /api/chat/agent-connect/selfcheck 逐项体检（SDK / 开关 / 工具注册 / 屏蔽对账 / 门禁 / 审计）

接入配置样例见 docs/agent-connect/README.md。

支持简体中文、繁體中文、English、日本語、한국어、Français 共 6 种语言（含 RTL 适配），多语言运维团队无缝协作。

MagicCommander 是本地桌面软件（Electron + React + TypeScript），所有数据存放在你的电脑上，无需联网，不上传云端，企业数据安全有保障。

• 内建渲染缓存、单实例锁、渲染进程崩溃自动恢复
• Jinja2 模板沙箱执行，杜绝模板恶意代码执行
• 路径白名单 + 输入校验，杜绝越权读写
• API Key 本地加密存储，云平台管理接口鉴权

从 GitHub Releases 下载对应平台的安装包，双击运行安装向导即可。Windows 版本已内嵌 Python 运行时，无需单独安装。

如果想从源码运行：

git clone https://github.com/bangbang8000-cell/MagicCommander.git
cd MagicCommander
npm install
pip install -r backend/requirements.txt
npm run dev:all

打开 MagicCommander，点击左侧活动栏的项目浏览器图标（或使用顶部文件 → 新建项目菜单；文件 → 最近项目可一键打开历史项目），新建一个项目。项目会自动生成 templates / excel / output / yaml 四个目录。也可以从 模板中心 的内置示例模板一键创建。

在 templates 目录下创建 .j2 模板文件（带智能补全），在 excel 目录下填写设备参数，切换到工作台面板——工作台按三步分组：①配置与就绪（项目/参数就绪度）→ ②渲染材料与操作（dry-run、校验、diff）→ ③校对与输出（渲染与结果分页）。核对就绪状态后点击"开始渲染"，配置文件即刻生成到 output 目录。

项目名称/
├── templates/       # Jinja2 模板 (.j2)
├── excel/           # 设备参数表 (.xlsx)
├── output/          # 生成的配置文件 (.txt)  [按时间戳分目录]
├── yaml/            # 生成的 YAML 中间文件
└── output-label/    # 生成的设备标签 (.docx / .md / .pdf)
    └── 2026_08_11_01_02_03/   # 按时间戳组织
        ├── xxx_label.docx
        ├── xxx_label.md
        └── xxx_label.pdf

Electron 28 · React 18 · TypeScript 5 · Vite 5 · TailwindCSS 3 · Zustand 4 · Monaco Editor · Python 3.12 · Jinja2 · FastAPI · Gitea · JWT · i18next (6 语言) · Vitest

MagicCommander/
├── src/                  # 前端 (Electron + React)
│   ├── components/       # UI 组件 (chat, cloud, layout, sidebar, dialogs)
│   ├── stores/           # Zustand 状态管理 (ui, platform, cloud, chat, project)
│   ├── i18n/             # 6 语言国际化
│   ├── api/              # 云端 API 客户端 (platform.ts)
│   └── types/            # TypeScript 类型定义
├── backend/              # Python 渲染引擎 (Excel→参数→Jinja2→配置)
│   ├── main.py           # 统一命令行入口
│   ├── pre_processing.py # 渲染管线（含输入指纹缓存）
│   ├── analyzer.py       # 项目/模板质量分析引擎
│   └── requirements.txt  # Python 依赖
├── ai_hub/               # AI Hub 服务 (FastAPI Agent)
│   ├── agent/            # Agent 框架 (53 Tools + 工具权限分级 + 多步任务)
│   ├── llm/              # 9 Provider 适配 (OpenAI 兼容接口)
│   ├── mcp/              # MCP Client（外部 MCP server 工具接入）
│   ├── skills/           # 技能自学习引擎
│   ├── knowledge/        # 知识库检索引擎
│   └── prompts/          # LLM 系统提示词与工具规范
├── electron/             # Electron 主进程 (IPC / 安全 / 更新)
├── public/               # 静态资源 (图标/文档/使用指南)
├── resources/            # 嵌入式 Python 运行时
└── docs/                 # 开发文档与计划

Q: 渲染失败怎么办？

检查 Python 是否已安装（python --version），确认已执行 pip install -r backend/requirements.txt 安装依赖，再检查 Excel 参数表格式和模板语法是否正确。Windows 发布版已内嵌 Python，通常无需手动安装。

Q: Excel 文件打不开？

确认文件格式为 .xlsx 或 .xls，且未被其他程序（如 Microsoft Excel）占用。

Q: 如何恢复项目数据？

所有项目数据存储在本地 workspace/ 目录下，备份该目录即可。删除项目前会有二次确认弹窗，避免误操作。渲染输出支持撤销（渲染前自动备份最近 5 份）。

Q: 如何配置 AI 助手？

打开设置面板 → AI 标签 → 选择 Provider → 填写 API Key（Ollama 本地部署无需 Key）→ 测试连接。详见使用指南「AI 智能助手」章节。

文档中的数字（Agent 工具 53 / 设备库 / 模板数）由 scripts/check_doc_numbers.py 以代码为唯一真值源反向校验，CI 门禁拦截漂移。

欢迎提交 Issue 和 Pull Request。请遵守工程门禁：npm run lint（0 warning）、npm run typecheck、npm run format:check、npm run check-version、npm test、后端与 AI Hub pytest 全部通过后再提交，CI 会自动校验。

当前测试规模：前端 Vitest 802 用例（渲染 645 + Electron 157）+ 后端 pytest 843 用例（backend/tests 378 + ai_hub/tests 465）。

搜索引擎关键词：网络设备配置批量生成、交换机配置自动生成、Jinja2 网络配置工具、网络运维自动化、设备标签打印、批量生成设备配置

MIT License