dsh-autoconfig

dsh-autoconfig

给 DSH（DeepSeek Harness）用的网络设备自动配置终端插件。基于 [dsh-ssh-ops](https://github.com/caoyiwei850/dsh-ssh-ops) 的「主对话驱动 + 右侧终端」架构重新实现，面向路由器、交换机、防火墙等设备的日常配置与排障。

> 安全提示（重要）：SSH 主机密钥校验默认关闭（hostVerifier: () => true），存在中间人攻击风险。请仅在可信管理网络使用；需要校验时，修改 src/transport-ssh.js 中的 hostVerifier，接入 ~/.ssh/known_hosts 或设备指纹白名单。详见文末[安全说明](#安全说明)。

>

> 批准模型与写权限边界（重要）：本插件的配置计划审批属于流程性防护，不构成强制访问控制。默认流程为：plan_create 展示计划 → 操作者在对话中明确同意 → Agent 调用 plan_approve 记录批准哈希 → plan_execute 校验后分步执行。由于 plan_approve 仍由 Agent 发起，在提示词注入、模型策略偏差或工具编排错误的情况下，存在 Agent 未经操作者真实批准即写入配置 的可能。若需将写权限收紧为更强的门禁，可在 ~/.dsh/autoconfig-rag.json 中设置 "requirePanelApproval": true：此时宿主会拒绝 plan_approve，只有右侧「计划」抽屉中由操作者点击才能写入批准哈希。更严格的做法是移除或禁用 Agent 的 plan_execute 工具，由前端完成执行；最终仍应以设备侧 AAA / 命令授权作为安全边界。详见[安全说明](#安全说明)。

>

> 原生依赖：串口功能依赖 serialport 原生绑定。pnpm/DSH 安装器通常会写入 allowBuilds 并重试，但若本机没有预编译包且缺少编译工具链，安装可能失败。Windows 需要 Visual Studio Build Tools 的“使用 C++ 的桌面开发”和 Python 3；Linux 需要 build-essential 与 python3。不使用串口时，SSH/Telnet/SFTP 不受影响。

1.0.0 能做什么

一句话：把「查手册 → 认设备 → 出计划 → 人批准 → 逐步下发 → 出错自愈 → 留痕」串成一个可审计的闭环。

典型工作流

1. 建库：在右侧「知识库」上传 PDF / CHM / MD 手册，填写厂家、系列、型号、适用版本；后台建立 TGM + BM25 + 本地向量索引。

2. 接设备：通过 SSH / Telnet / Console 连接交换机、路由器或防火墙；插件自动采集 display version、序列号、hostname 等只读信息。

3. 核验：把设备厂家/型号/版本与手册匹配；有精确匹配时只用精确手册，否则明确提示风险。

4. 提需求：在对话里说“给 Vlan-interface1000 配 11.1.1.1/24，并加一条 121.1.1.0/24 指向 11.1.1.2 的静态路由”。

5. 审计划：plan_create 返回完整计划——每条命令的中文解释、验证命令、回滚命令、风险等级、手册页码；视图检测会自动去掉/补充 system-view。

6. 批准：默认在对话中确认后由 plan_approve 记录批准；严格模式只允许右侧「计划」抽屉的按钮批准。

7. 分步执行：命令逐条写入右侧终端，终端留下 [plan] 命令 — 解释 与 [plan verify] 标记；任一步失败立即暂停。

8. 验证与回滚：执行后自动跑验证命令；不通过或需要撤销时，按计划里的回滚命令恢复。

9. 出错自愈：识别 ^ 错误位置，用 ? 逐词探测（不回车、不执行），修订计划后重新批准；失败样本进入本地案例库，后续计划自动提示相似坑。

10. 审计：会话日志、设备档案、计划 JSON、错误案例全部落盘，可导出、可复核。

具体能干什么

| 场景 | 能力 |

|---|---|

| 手册问答 | 问“怎么配日志服务器/Telnet/VLAN/静态路由”，返回手册章节、页码/行号与原文片段 |

| 设备识别 | 自动识别 H3C/Huawei/Maipu/Ruijie/Cisco 的提示符、型号、版本、序列号 |

| 配置生成 | 基于检索到的命令生成带解释、验证、回滚的计划，不再靠模型凭空猜命令 |

| 计划审批 | 一次批准整份计划；计划改动一个字即失效，需重新确认 |

| 终端执行 | 按步骤写入右侧终端，命令与解释同步显示，失败即停 |

| 错误修复 | 解析 % ... at '^' position，? 探测候选关键字，修订后重批重跑 |

| 多厂商 | Comware / VRP / Maipu / IOS 的视图切换、保存、错误提示差异 |

| 知识库管理 | CHM/PDF/MD 上传、重建索引、预览、删除；CHM 构建中断可恢复 |

| 设备档案 | 按序列号保存档案，导出/导入，供后续配置复用 |

| 审计留痕 | 会话 .log + .json、计划 JSON、错误案例 JSONL |

一个完整例子

你：给 192.168.0.200 的 Vlan-interface1000 配 11.1.1.1/24，
    再加一条 121.1.1.0/24 指向 11.1.1.2 的静态路由。

插件：device_profile → H3C S5820V2-54QS-GE / 7.1.075 / SN DPPMWWB76
      kb_search → H3C 手册 70-BGP… 3.4.1 / 43-Portal… 4.5.1
      plan_create → 计划（含解释、验证、回滚、风险）
你：批准
插件：plan_approve → plan_execute → 终端逐条执行 → display 验证

边界（它不做什么）

• 不替代设备侧 AAA、命令授权、ACL 和变更审计；插件批准不是密码学安全边界。
• 不保证扫描版 PDF、纯图片 CHM 的识别效果；这类文档需要先 OCR 或提供文字版。
• 不做自动配置备份、合规扫描、拓扑发现；这些需要额外工具或脚本。
• 不自动执行高风险命令；save、reboot、undo 管理面等仍逐条展示并由操作者批准。
• 不替用户保存设备密码到日志或模型上下文；密码只进入 DSH 凭据库/连接表单。

功能

• 右侧终端面板：在官方右侧边栏注册「自动配置终端」标签页。AI 的每一次连接、输入、读取和 SFTP 操作都会显示在同一个终端里，操作者可以全程审计。
• 四种接入方式
• ssh：ssh2 交互式 shell（PTY），支持密码 / 私钥 / keyboard-interactive，支持旧设备 SHA-1 group14 KEX 回退。
• telnet：原始 TCP + RFC 854 选项协商（ECHO/SGA/TTYPE/NAWS），可自动回答 login: / Password:。
• console：串口（COMx / /dev/ttyUSBx），默认 9600 8N1，可自动登录。
• sftp：SSH 认证后只打开 SFTP 子系统；SSH 连接也可以随时切到「文件」页做 SFTP 操作。
• 自动会话日志：连接建立即开始记录，文件名形如

SW-Core_10.1.1.1_20261027-231530.log

（__.log）。设备提示符中识别到真实 hostname 后会自动重命名日志；未填写设备名时先用 device 占位（如 device_10.1.1.1_...log），识别后再重命名。同目录下有同名 .json 元数据。

• AI 工具：device_connect / device_list / device_send / device_read / device_close / device_sftp / device_logs，以及 1.0.0 的 kb_search / kb_docs / device_profile / plan_*。device_send 会在右侧终端留下 [agent ...] 标记并写入日志的 INPUT (agent) 记录。
• 左侧会话栏：像 MobaXterm / SecureCRT 一样保存连接过的设备。双击有锁标记（已保存密码）的会话直接重连；没有密码的会话会预填地址，只补密码即可。密码写入 DSH 凭据库，autoconfig-profiles.json 只保存地址、用户名和端口。
• 关键字高亮：内置 colorful-network.ini 的 22 条规则（no/down/error 红、up/connected 绿、协议/端口蓝、路由/ACL 品红、接口/IP/百分比橙），大小写不敏感，按最长匹配避免重叠，且只在整词边界命中（不会把 Usage 里的 ge、Canonical 里的 no 染色）。工具栏「高亮」可随时关闭；已带 ANSI 颜色的设备输出原样保留。
• 终端外观：终端页面默认纯黑背景；工具栏可一键切黑/深蓝黑/浅色，或用取色器选任意颜色。背景与高亮开关保存在浏览器 localStorage（dsh-autoconfig.terminal-background / dsh-autoconfig.keyword-highlight）。
• 日志查看：面板「日志」按钮可预览、下载、删除日志；日志目录默认 ~/.dsh/autoconfig-logs。
• 手册知识库（1.0.0）：右侧「知识库」抽屉上传 PDF / CHM / MD 技术手册，填写厂家/系列/型号/适用版本；后台建立 TGM（章节树 + 实体图 + 映射）+ BM25 + 本地向量（bge-m3）混合索引，可选 bge-reranker 重排。
• 配置计划与审批（1.0.0）：AI 先 device_profile 采集厂商/型号/版本/序列号并与手册核验，再 kb_search 取手册依据；plan_create 生成的计划包含每条命令的中文解释、验证命令和回滚命令，并完整展示在对话中。默认由操作者在对话里确认后，AI 调用 plan_approve 记录“对话批准”，再 plan_execute 分步写入终端；右侧「计划」抽屉保留手动批准入口。设置 requirePanelApproval: true 后，对话批准被宿主拒绝，只有面板按钮能完成批准。批准与命令哈希绑定，改一个字即失效，执行中失败立即暂停。
• 错误识别与 ? 自愈（0.2.0）：识别 Comware / VRP / IOS 的 ^ 错误位置与 % ... found at '^' position 提示，用 ? 逐词探测（不回车、不执行），修正后计划回到 draft 由操作者重新批准；失败样本写入本地案例库并注入后续计划。
• 视图自适应（0.2.1）：plan_create 读取终端当前提示符（` 用户视图 / [H3C] 系统视图 / [H3C-xxx] 子视图），已在系统视图时自动移除重复的 system-view，在用户视图时自动补充 system-view，子视图会给出警告；执行时再次检测，重复的视图切换命令直接跳过并留下 [plan skip]` 标记。

手册知识库与配置计划（1.0.0）

这一版把 BookRAG 的检索能力内置为本地 sidecar（Python），插件只通过 127.0.0.1 的随机端口和一次性 token 访问它；浏览器不直连 sidecar。

• 数据目录：默认 ~/.dsh/autoconfig-kb，可用 ~/.dsh/autoconfig-rag.json 覆盖：

{
  "dataDir": "E:\\dsh-autoconfig-data",
  "python": "E:\\dsh-autoconfig-data\\.venv\\Scripts\\python.exe",
  "modelPath": "E:\\dsh-autoconfig-data\\models\\bge-m3",
  "device": "cuda",