思科拓扑工具 heqinjian/dsh-plugin-pkt

dsh-plugin-pkt — Cisco Packet Tracer 读写与自动化插件

给 DeepSeek Harness 用的 Packet Tracer 插件：读取、诊断、修复 .pkt / .pka / .pta 文件，从模板搭建新拓扑，并直接启动本机 Packet Tracer (Instructor) 打开文件。

纯 JavaScript，无第三方依赖：容器格式在本进程内编解码（Twofish-EAX + zlib）。

不装插件也能当命令行工具用，见第 5 节。

1. 工具一览

| 工具 | 作用 |
| pkt_read | 读取文件，按 section 返回不同视图 |
| pkt_fix | 检测并修复故障，写出新文件并自动复验 |
| pkt_new | 从模板新建拓扑：只保留指定设备，重建连线 |
| pkt_build | 在现有拓扑上克隆设备 + 加链路 |
| pkt_open | 用本机 Packet Tracer 打开文件 |

pkt_read 的 section

| section | 内容 |
| summary | 概览：设备、链路、画布标注（默认） |
| topology | 设备与链路清单 |
| addresses | IP 地址表 |
| issues | 检测到的配置故障 |
| routing | 各设备路由协议与 network 声明 |
| configs | running-config 文本（可配 device） |
| activity | Instructor 活动脚本与说明 |
| fixplan | 修复方案 + 可照抄的 CLI 命令（只读，不改文件） |
| xml | 解密后的原始 XML |

2. 能检出并自动修复什么

| 类别 | 判据 | 自动修复 |
| 线缆类型 | MDI/MDI-X 规则：Router/PC 之间要交叉线；Router↔Switch、Switch↔PC 要直通线 | 改 CABLE/TYPE |
| 接口关闭 | 接了链路却 shutdown | no shutdown，并按画布标注补 IP |
| 网关错误 | 填成本机地址 / 拓扑中不存在 / 不在本网段 | 改为同网段路由器接口地址 |
| 地址冲突 | 同一 IP 在多台设备上 | 把非首个持有者改到空闲地址 |
| 路由协议不一致 | 直连路由器跑不同协议 | 统一为配置更完整的一方（平局取 OSPF），按协议生成正确 network 语法 |
| 路由声明缺失 | router x 下无 network | 随上一条一并重写 |
| 掩码不一致 | 终端掩码与同网段路由器接口不同 | 仅提示，不自动改 |

3. 自动搭建拓扑

有两种方式，都基于同一个前提：Packet Tracer 的设备节点无法从零合成。设备块里包含模块树、端口表、文件管理器状态和一堆不透明的内存地址，凭空拼一个 PT 不会认。
所以要么克隆已有设备，要么从模板里挑选子集。

3.1 pkt_new — 从模板新建（推荐）

只保留模板里的指定设备，丢弃其余设备、全部连线和画布标注，再按需重建连线。
适合"我要一个干净的新实验"。

{
"template": "某份现成.pkt", "out": "新拓扑.pkt",
"keep": ["R1", "Switch0"],
"links": [
{ "from": "R1", "fromPort": "GigabitEthernet0/0",
"to": "Switch0", "toPort": "FastEthernet0/1",
"cable": "eStraightThrough" }
]
}

3.2 pkt_build — 在现有拓扑上追加

克隆已有设备为新节点，再接线。

{
"path": "lab.pkt",
"devices": [
{ "name": "PC3", "like": "PC1", "ip": "172.16.1.50",
"mask": "255.255.255.0", "gateway": "172.16.1.1" }
],
"links": [
{ "from": "PC3", "fromPort": "FastEthernet0",
"to": "Switch0", "toPort": "FastEthernet0/3",
"cable": "eStraightThrough" }
]
}

共同限制：两种方式都只能使用模板里已存在的设备形态。想加一台 2911 路由器，源文件里必须已经有一台 2911 可克隆。

4. 文件格式

Packet Tracer 6.x 及以后版本的 .pkt/.pka/.pta 是四段式封装：

| 阶段 | 处理 | 说明 |
| 1 | 按位置异或 + 字节反转 | out[i] = data[n-1-i] ^ ((n - in) & 0xFF) |
| 2 | Twofish-EAX 解密 | key = 0x89×16，nonce = 0x10×16；CMAC 认证 + CTR |
| 3 | 按位置异或 | buf[i] ^= (len - i) & 0xFF |
| 4 | zlib 解压 | 前 4 字节为大端原始长度 |

第 2 段是 EAX 不是 CBC。CTR 是流模式，密文长度不必是 16 的倍数；EAX 的认证标签同时校验完整性。

写回时只做文本级精确替换，不重新序列化 XML，因此 PT 需要的所有结构细节原样保留。

⚠️ 前 4 字节是「字节数」，不是「字符数」

长度前缀必须是 UTF-8 字节数。误用 JS 字符串的 .length（UTF-16 码元数）时，只要文档里有中文（画布标注、设备描述等），前缀就会偏小 2 × 汉字数 字节，而 PT 只读前缀声明的字节数，会静默截断文档尾部——表现为最后一台设备的部分元素丢失，例如接口 IP 还在、DNS_SERVER 却不见了。
因此 encryptPkt() 会先把字符串或 Buffer 统一归一化为 Buffer，再写前缀；decryptPkt() 额外返回 sizeMismatch 标志，pkt_fix/pkt_build/pkt_new 写完后断言它为 false。

5. 命令行（不装插件也能用）

node bin/pkt.mjs <file.pkt> [--device NAME] [--out FILE]

读写
node bin/pkt.mjs lab.pkt summary
node bin/pkt.mjs lab.pkt issues
node bin/pkt.mjs lab.pkt configs --device R1
node bin/pkt.mjs lab.pkt xml --out lab.xml

修复
node bin/pkt.mjs lab.pkt fix --out lab-fixed.pkt

搭建
node bin/pkt.mjs lab.pkt build --spec spec.json --out lab-built.pkt

从模板新建（keep + links 写在 spec 里）
node bin/pkt.mjs template.pkt new --spec spec.json --out lab-new.pkt

6. 安装

6.1 从 GitHub 安装（推荐）

git clone https://github.com/heqinjian/dsh-plugin-pkt.git
cd dsh-plugin-pkt
powershell -ExecutionPolicy Bypass -File install.ps1

脚本会把包复制到 <profile>\node_modules\dsh-plugin-pkt，并在 cordis.patch.yml 里追加加载条目（先备份原文件）。

指定其他配置档：

powershell -ExecutionPolicy Bypass -File install.ps1 -ProfileDir "C:\Users\me\.dsh\profiles\desktop"

6.2 用 DSH 插件管理器

plugin_manager install_bundle target="github:heqinjian/dsh-plugin-pkt"

6.3 只想要命令行

不需要装插件，直接 clone 后运行 node bin/pkt.mjs（见第 5 节）。要求 Node.js ≥ 18。

6.4 更新已安装的插件

插件是纯 JavaScript、无第三方依赖、无构建步骤，所以「更新」本质上只有两件事：替换 <profile>\node_modules\dsh-plugin-pkt 里的文件 + 重启 DSH。

先确认当前装的是哪个版本：

(Get-Content "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-pkt\package.json" |
ConvertFrom-Json).version

A. 用 git clone + install.ps1 装的（推荐）

cd dsh-plugin-pkt
git pull
powershell -ExecutionPolicy Bypass -File install.ps1

install.ps1 对更新是安全的，可以反复执行：

- 会先 Remove-Item -Recurse -Force 删掉目标目录再整份复制，不会残留旧文件；
- cordis.patch.yml 里检测到 id: pkt-reader 就跳过，不会重复插入 loader 条目（重复插入会导致 tool "pkt_read" is already registered）。

B. 用 plugin_manager 装的

plugin_manager remove_bundle target="dsh-plugin-pkt"
plugin_manager install_bundle target="github:heqinjian/dsh-plugin-pkt"

⚠️ 如果 remove_bundle 后立刻 install_bundle，新的 loader 条目可能卡在 failed（见下文「装完必须重启 DSH」）。稳妥顺序是：移除 → 重启 DSH → 安装 → 重启 DSH。

C. 只想升级命令行

git pull

bin/pkt.mjs 不依赖配置档，clone 目录更新完即可用。

更新后验证

1. 必须重启 DSH——loader 不会热加载插件，不重启就还是旧代码在跑；
2. 重启后确认 pkt_read / pkt_fix / pkt_new / pkt_build / pkt_open 五个工具都在；
3. 跑自检：

node test/selftest.mjs # 加密内核 + 容器往返
node test/plugin.test.mjs # 工具注册

自检要在 git clone 目录里跑，不要在配置档目录里跑——install.ps1 只复制 src/bin/package.json/cordis.patch.yml/README.md/LICENSE，不含 test/ 和 examples/，在配置档里执行会报找不到文件。

更新后工具行为没变？

按这个顺序查：

1. 没重启 DSH —— 最常见，占九成；
2. 改了不止一处拷贝 —— 手工装过一份、插件管理器又装了一份。检查： Get-ChildItem "$env:USERPROFILE\.dsh\profiles\desktop\node_modules" -Filter "pkt" -Directory

只应存在一个 dsh-plugin-pkt；
3. 版本号没变 —— 用上面的 package.json 命令确认，别只靠 git log。

⚠️ 装完必须重启 DSH

DSH loader 在运行期新增的插件条目一律 fiberPhase: failed，与代码无关——把同一份代码装进宿主启动时就存在的条目则正常。因此：

1. 装好后重启 DSH，五个工具才会出现；
2. 后续更新代码也要重启才生效；
3. 如果条目卡在 failed，换个 id 重新插入即可（同名不会重试）。

安装常见问题

「未找到插件」

包确实不在 profile 里。检查：

Test-Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-pkt"

返回 False 说明没装上——删除插件后 UI 可能还留着旧行，直接重装即可。

装的时候报 tool "pkt_read" is already registered

说明还有另一份拷贝在用同一个工具名注册。常见于手工装过一份、又用插件管理器装了一份。
查一下有没有残留：

Get-ChildItem "$env:USERPROFILE\.dsh\profiles\desktop\node_modules" -Filter "pkt*" -Directory

把多余的删掉（连同 cordis.patch.yml 里对应的 - insert: 条目），再重装。

装完状态一直是 failed

同一 id 的条目不会重试。删掉插件、重启 DSH、再装一次，就会拿到全新的 entry。

推荐的干净流程：

删除插件 → 重启 DSH → 安装 → 重启 DSH（若未自动激活）

7. 目录结构

dsh-plugin-pkt/
├── bin/pkt.mjs 命令行入口 ├── src/ │ ├── index.js 插件入口（注册 5 个工具） │ ├── twofish-eax.js Twofish + EAX + 容器编解码 │ ├── xml.js 无依赖 XML 解析 │ ├── model.js 建模、故障检测、报告渲染 │ ├── plan.js 故障 → 编辑操作 │ ├── edit.js XML 精确改写 │ └── build.js 设备克隆、链路添加、模板子集抽取 ├── test/ │ ├── selftest.mjs 加密内核自检（无需样本文件） │ └── plugin.test.mjs 工具注册冒烟测试 ├── examples/ │ ├── 01-new-topology.mjs 从模板新建拓扑 │ ├── 02-two-lan-lab.mjs 双交换机双 PC 实验 │ └── 03-fix-faults.mjs 批量修复故障 ├── install.ps1 └── package.json

自检

node test/selftest.mjs # Twofish KAT + 容器往返
node test/plugin.test.mjs # 工具注册
node test/plugin.test.mjs 你的文件.pkt # 再跑一次 pkt_read

8. 限制

- 仅 128 位 Twofish（PT 只用这一种）；5.x 及更早的两段式格式未实现。
- 不能替代人工在 PT 里点按钮：PT 没有公开自动化 API。本插件通过改写 .pkt 文件 达成配置，效果等价于手工配置，但需要 PT 重新打开文件才可见。
- pkt_new / pkt_build 只能复用模板里已有的设备形态，不能凭空造出文件里不存在的型号。
- 路由协议统一是启发式的（选配置更完整的一方），复杂场景需人工判断。
- 克隆设备的 MAC 地址沿用模板，同一文件内可能出现重复 MAC，严格场景建议手工改。
- PT 打开文件后 STP 收敛约需 15 秒，此前交换机端显示橙色，属正常现象。

9. 许可

MIT。见 LICENSE。

本项目不包含任何 Cisco 的代码或资源；Packet Tracer 是 Cisco 的商标。
文件格式的实现来自公开的逆向工程资料。