net-connector 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f018d69d8d4cf234bd90fcdd4e56a60e4184ef5ddb4f4cf15f4ff49206d5631
-  data.tar.gz: f8e0afe1a9131435134e5580dc0f3ffdc9823e55b7fc5665d60b1768f3c223fc
+  metadata.gz: d1f1aa8bb2e1ce2a457e99cde7439206c7f4b1c44ccd590db5b6eb330386a39d
+  data.tar.gz: 4b29cb8d180a7428225badc8bedc90ac6887d574ad8eccbfd251159141f7bc2f
 SHA512:
-  metadata.gz: 620f62156a11192ae6648f48878ef61cb810830ee3c9dee8c7e8c6bc12b2b88e4c3f8ba420535bbb82b94a423328897c52844a4b7d76c4a404ae4e59b9f54c95
-  data.tar.gz: dc0ea681afb4a9a9cbeef79778d1cfebdf009004ee036a61dfcc8e9cb9f53579ad1967088a784bc2ed730874bdb1770207a57603b800caa55545dec8c8089915
+  metadata.gz: f4743a08bf81e10e58e6475c33c7537bc87bc68b6f418d9badd3502382e4a35395af00a923923d64349f8499862b50f3ebb85f8d963f421348028fd7c3d7c978
+  data.tar.gz: a23c96f292c6f69c56a2de6c0e62684f3d4d9b090d37e68d97315d8e9c3ecf22e7cc008776ca25fd74e0d284dd287031ed0b97431224c5e33e9dcba873c3edbf

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 更新记录
 
+## 0.14.0 - 2026-10-18
+
+- 不兼容调整：Netdisco 配置与策略入口整理为 `Config`、`Config::Initializer`、`Device::Policy`、`Topology::Options`，原常量和加载路径已移除，直接引用者需更新。
+- 示例入口统一为 `backup.rb`、`backup_tftp.rb` 和 `topology.rb`，单台 TFTP 使用 `backup_tftp.rb --host IP`，数据库示例配置改为 `inventory.yml`，原 `device_tftp.rb`、`review_tftp.rb` 和 `inventory_sql.yml` 已移除。
+- 备份示例支持默认配置、首次运行初始化、常用与完整帮助及清单预览，直接使用当前安装或 Bundler 选定的库。
+- 新增拓扑发现、描述审计和只读规划入口，只有显式 `--apply` 才下发，应用前重验邻居及原描述，修改后回读并保存，部分失败和中断保留已完成结果。
+- 清单支持 CIDR、地址范围、名称与厂商筛选、排除和重复参数，新增只读缓存模式，离线预览不连接设备或创建批次目录。
+- TFTP 支持逐设备服务器、源接口、源文件与 VRF 设置，核验目录按服务器绑定，修复仅配置服务器目录映射时将同服务器 PAN-OS 设备误判为文件名冲突的问题。
+- 示例的公开配置按 CLI、YAML、环境默认值依次取值，宿主可通过 `load_env: true` 启用相同规则，正式 CLI 保留原有优先级。
+- 运行时依赖解除版本约束，由宿主应用选择并锁定兼容版本。
+
 ## 0.13.0 - 2026-10-18
 
 - 不兼容调整：H3C 的 LLDP 列序变体合并为 `h3c/display_lldp_neighbor_information_list.textfsm`，显式引用旧模板路径的调用方需要更新。

data/README.md

@@ -41,7 +41,7 @@ net-backup --config config.yml --plan
 net-backup --config config.yml
 ```
 
-Start with [backup.yml](examples/backup.yml) or [inventory_sql.yml](examples/inventory_sql.yml). Configure inventory and device credentials in the environment; YAML contains non-sensitive settings. See the [Netdisco guide](docs/netdisco.md) for HTTP/PostgreSQL inventories, success policies, TFTP verification, and batch examples.
+Start with [backup.yml](examples/backup.yml) or [inventory.yml](examples/inventory.yml). Configure inventory and device credentials in the environment; YAML contains non-sensitive settings. See the [Netdisco guide](docs/netdisco.md) for HTTP/PostgreSQL inventories, success policies, TFTP verification, and batch examples.
 
 ## Documentation
 

data/README.zh-CN.md

@@ -41,7 +41,7 @@ net-backup --config config.yml --plan
 net-backup --config config.yml
 ```
 
-从 [backup.yml](examples/backup.yml) 或 [inventory_sql.yml](examples/inventory_sql.yml) 开始配置。清单与设备凭据放在环境变量中，YAML 只保存非敏感设置。HTTP/PostgreSQL 清单、成功策略、TFTP 核验和批量示例见 [Netdisco 指南](docs/netdisco.zh-CN.md)。
+从 [backup.yml](examples/backup.yml) 或 [inventory.yml](examples/inventory.yml) 开始配置。清单与设备凭据放在环境变量中，YAML 只保存非敏感设置。HTTP/PostgreSQL 清单、成功策略、TFTP 核验和批量示例见 [Netdisco 指南](docs/netdisco.zh-CN.md)。
 
 ## 文档
 

data/docs/VERIFICATION.md

@@ -155,7 +155,7 @@ SHA-256，首次使用时从官方 GitHub Release 下载，缓存到 `tmp/tools/
 
 运行依赖写在 `net-connector.gemspec`，包括直接使用的、可能从 Ruby 默认
 安装中拆出的标准库 gem。开发工具只写在 Gemfile，不进入运行依赖。
-共享脱敏要求 `expect-pty ~> 0.5.0`，使用已发布的公共 `Expect::Redactor`。
+共享脱敏使用 expect-pty 已发布的公共 `Expect::Redactor` 接口。
 开发及隔离安装检查使用正式依赖包，不再需要本地 expect 补丁或联调环境包装脚本。
 开发用 `parallel` 保持 1.x，以支持 Ruby 3.2。
 
@@ -163,9 +163,9 @@ SHA-256，首次使用时从官方 GitHub Release 下载，缓存到 `tmp/tools/
 分别解析兼容依赖。应用使用者应在自己的应用中提交 lockfile。测试和打包
 脚本通过隔离安装检查运行依赖，避免依赖开发环境里偶然存在的 gem。
 
-`gemfiles/minimum.gemfile` 固定关键业务依赖下限 expect-pty 0.5.0、textfsm 0.2.0；
+`gemfiles/minimum.gemfile` 固定较早的业务依赖 expect-pty 0.5.0、textfsm 0.2.0；
 标准库和开发工具仍按主 Gemfile 的兼容范围解析。普通矩阵检查允许版本的正常解析，
-另在 Ubuntu / Ruby 3.2、4.0 检查下限组合的全量测试与隔离安装。本地复现：
+另在 Ubuntu / Ruby 3.2、4.0 检查这组版本的全量测试与隔离安装。本地复现：
 
 ```sh
 BUNDLE_GEMFILE=gemfiles/minimum.gemfile bundle install
@@ -173,8 +173,8 @@ BUNDLE_GEMFILE=gemfiles/minimum.gemfile bundle exec rake test package:verify
 ```
 
 这不是所有传递依赖最旧版本的笛卡尔积，也不声称本地 macOS 运行证明远端矩阵通过。
-当前这两个关键依赖的正常解析与下限恰好相同，报告仍记录实际版本，供以后比较。
-开发锁文件均忽略；gemspec 保持兼容范围，基准、夹具、兼容 Gemfile 和审阅报告均不进 gem。
+报告记录实际解析版本，便于比较默认组合和旧版本组合。
+开发锁文件均忽略；gemspec 不限定依赖版本，基准、夹具、兼容 Gemfile 和审阅报告均不进 gem。
 
 gem 只收录库代码、TextFSM 模板、CLI、双语设备/Netdisco 指南、架构/验证/发布文档、双语 README、LICENSE、
 CHANGELOG、SECURITY 和 CONTRIBUTING。仅两个非敏感 YAML 示例随包分发；测试、示例脚本、发布工具、工作流、本地评审快照、本地配置和备份不进入包。

data/docs/architecture.md

@@ -326,7 +326,7 @@ TFTP 策略必须实现 `validate_options!(target, source_file:, vrf:)`、`recei
 
 `engine/interaction`、`engine/dialogue`、`engine/response` 分别定义交互规则、对话语法与响应值；读取循环位于 `engine/response_reader`。`engine/errors` 不加载脱敏运行时，`engine/redactor` 负责秘密作用域。Session 明确加载并持有读取器与脱敏器。
 
-Netdisco 的 Settings、Planner、Fleet、CLI 等文件各自声明实际依赖，单独 require 后即可调用，不依赖 `netdisco.rb` 的预设加载顺序。总入口只组合 CLI 和 CLI::Backup；Batch 通过 autoload 创建 Report，避免两者循环加载。内部清单预算 `Inventory::Budget` 由 Inventory 清单适配器加载。Progress 的终端显示、Fleet 的设备执行、Report 的结果解释和 Storage 的文件持久化保持独立职责。
+Netdisco 的 Settings、Planner、Fleet、CLI 等文件各自声明实际依赖，单独 require 后即可调用，不依赖 `netdisco.rb` 的预设加载顺序。总入口组合 CLI、CLI::Backup 和 CLI::Topology；Batch 通过 autoload 创建 Report，避免两者循环加载。内部清单预算 `Inventory::Budget` 由 Inventory 清单适配器加载。Progress 的终端显示、Fleet 的设备执行、Report 的结果解释和 Storage 的文件持久化保持独立职责。
 
 公共策略位于 `RunningConfig::Strategy` / `Rendered`、`Tftp::Strategy` / `FileUpload`、`Topology::Strategy` / `ImmediateStrategy`。厂商文件直接依赖公共策略，由 Profile 绑定；没有反向加载和厂商转发别名。
 
@@ -357,12 +357,15 @@ RunningConfig 的两处受控 `send` 保留，用于私有策略绑定与 protec
 | 命令结果 | `Command::Result`，位于 `engine/command/result.rb`；脚本汇总仍为 `Result` |
 | 安全诊断词表 | `Error::Metadata`，位于 `engine/error/metadata.rb` |
 | 清单预算与缓存 | `Netdisco::Inventory::Budget/Cache`，位于 `netdisco/inventory/` |
+| 配置解析与初始化 | `Netdisco::Config` 和 `Config::Initializer`，位于 `netdisco/config.rb` 和 `netdisco/config/initializer.rb` |
+| 逐设备策略 | `Netdisco::Device::Policy`，位于 `netdisco/device/policy.rb`，按厂商默认和设备地址选取参数 |
+| 拓扑批次参数 | `Netdisco::Topology::Options`，位于 `netdisco/topology/options.rb`；设备拓扑能力仍为 `Net::Connector::Topology` |
 | 配置操作结果 | `Netdisco::Operations::Batch/Outcome`，位于 `netdisco/operations/` |
 | 报告存储 | `Netdisco::Report::Store`，位于 `netdisco/report/store.rb`，通过 `report_store:` 注入 |
 | 服务器上传证据 | `Netdisco::Tftp::Verifier/Archive`，位于 `netdisco/tftp/` |
 | 厂商平台 | `Vendor::CiscoIos` 等平台类直接继承 Base 或协议家族类；策略位于平台类下 |
 | 文件边界 | `Storage::FileReader` 与 `Storage::AtomicFile`，分别负责受控读取与原子替换 |
-| 终端应用 | `Netdisco::CLI::Backup/Credentials/Options`，位于 `netdisco/cli/` |
+| 终端应用 | `Netdisco::CLI::Backup/Topology/Credentials/Options`，位于 `netdisco/cli/` |
 
 工厂方法用 `build_*` 表明返回新对象；抛错校验使用 `validate_*!`；块作用域使用明确的 `with_*`。单命令、脚本、命令文本构造和完成证据判断分别命名，避免从通用的 execute/check/complete 猜测行为。`legacy_ssh` 表示设备 SSH 协议协商选项，Netdisco QueryRequired 则是服务端 API 行为，两者均独立于本库旧版本接口。
 

data/docs/netdisco.md

@@ -76,7 +76,7 @@ The installed command is `net-backup`; source checkouts use `bundle exec bin/net
 
 Here `vendor` is the connector platform key, such as `cisco_ios` or `cisco_nxos`, rather than the manufacturer. Filtering and sampling use that key: a limit of five can select five IOS devices and five NX-OS devices. `source_vendor` retains the original inventory vendor label.
 
-Interactive batch examples use `CLI::Backup`; `CLI::Credentials.resolve` supplies the inventory source and per-device credential resolver, while `CLI::Options` parses arguments and configuration overrides. These components live under `netdisco/cli/`.
+Interactive batch examples use `CLI::Backup` and `CLI::Topology`; `CLI::Credentials.resolve` supplies the inventory source and per-device credential resolver, while `CLI::Options` parses arguments and configuration overrides. These components live under `netdisco/cli/`. The examples explicitly pass `load_env: true` to make public environment values defaults below YAML and CLI options. The formal CLI retains its existing environment precedence.
 
 `--export IP` reads an existing canonical `<IP>.txt` file offline. It writes original bytes to stdout, or atomically writes a private file with `--output`. It does not require inventory or device credentials. Hostname-prefixed batch-example files are not searched by this command.
 
@@ -146,7 +146,7 @@ For other independent tasks, load `net/connector/concurrency/pool` and use `Net:
 
 ## PostgreSQL inventory
 
-Set `netdisco.source: postgres` and provide your own SELECT query. Table names and business filters are not built into the library. See [inventory_sql.yml](../examples/inventory_sql.yml):
+Set `netdisco.source: postgres` and provide your own SELECT query. Table names and business filters are not built into the library. See [inventory.yml](../examples/inventory.yml):
 
 ```yaml
 netdisco:
@@ -170,7 +170,7 @@ export ND_DB_HOST=database.example
 export ND_DB_NAME=netdisco
 export ND_DB_USER=inventory-reader
 export ND_DB_PASS='replace-me'
-net-backup --config examples/inventory_sql.yml --plan
+net-backup --config examples/inventory.yml --plan
 ```
 
 Host, database, user, and password are required. Source, query, and parameters may be overridden by `--source`, `--query`, and `--query-params`. They are public configuration and may appear in `--show-config`; passwords belong only in connection variables. HTTP credentials and device credentials are not prerequisites for a database-only plan.

data/docs/netdisco.zh-CN.md

@@ -89,7 +89,7 @@ net-backup --config config.yml --export 192.0.2.7 --output ./exports/device.cfg
 
 ### PostgreSQL 联机查询
 
-设置 `netdisco.source: postgres` 可以直接从数据库查询清单，继续使用同一套 Fleet、规则、计划和备份流程。库不内置表名、SQL 或业务筛选条件；必须提供查询，可直接修改 [YAML 示例](../examples/inventory_sql.yml)：
+设置 `netdisco.source: postgres` 可以直接从数据库查询清单，继续使用同一套 Fleet、规则、计划和备份流程。库不内置表名、SQL 或业务筛选条件；必须提供查询，可直接修改 [YAML 示例](../examples/inventory.yml)：
 
 ```yaml
 netdisco:
@@ -116,10 +116,10 @@ export ND_DB_NAME=netdisco
 export ND_DB_USER=inventory-reader
 export ND_DB_PASS='replace-me'
 
-net-backup --config examples/inventory_sql.yml --show-config
-net-backup --config examples/inventory_sql.yml --plan
+net-backup --config examples/inventory.yml --show-config
+net-backup --config examples/inventory.yml --plan
 # 覆盖查询参数；实际备份仍需设置 NC_DEVICE_* 凭据。
-net-backup --config examples/inventory_sql.yml --plan --query-params '["Cisco"]'
+net-backup --config examples/inventory.yml --plan --query-params '["Cisco"]'
 ```
 
 SQL、参数和来源也可分别通过 `--query SQL`、`--query-params JSON`、`--source postgres` 覆盖 YAML，不再从环境变量读取。SQL 和参数属于可公开配置，会出现在 `--show-config` 中；数据库密码只放在连接环境变量中。身份凭据不进入策略快照、计划、报告或 `inspect`；端口、TLS 和超时属于公开策略，进入快照与配置摘要。已有 Fleet 每次重新查询时读取最新连接凭据；传入已有 `plan:` 执行时不会重新查询。
@@ -140,7 +140,7 @@ CLI 的计划与批次摘要使用 JSON。默认 `--success-policy strict` 使
 
 本地批量示例和 TFTP 批量示例默认全量；显式 `--sample N` 或 YAML `backup.limit_per_vendor` 才限制每厂商数量（示例允许 1 至 5）。优先级为 CLI > YAML。并发默认 4，可用 `--concurrency N`、环境变量 `NC_CONCURRENCY` 或 YAML `backup.concurrency` 覆盖，优先级依次降低。两类示例在备份目录下创建唯一批次目录。TFTP 批量示例在可访问服务器目录时使用 hostname-ip 远端文件名并逐批归档；无法访问服务器目录时使用带批次标识的远端文件名，避免覆盖旧文件；上传完成与服务器文件验证是不同状态。
 
-全量 TFTP 计划保存为 `plan.json`。目标文件名通常为 `<设备名>-<IP>.cfg`，Radware 用 `.tgz`，山石用 `.dat`。可访问本机 TFTP 服务器目录时，批量示例直接使用 `<设备名>-<IP>.<扩展名>` 上传，并在服务器的 `archive/<批次>/` 与本地 `<批次目录>/tftp/` 各保留一份；上传前已有的同名文件先保存到新归档目录的 `previous/`。无法访问服务器目录时，远端文件名增加东八区批次标识及同秒序号，避免覆盖旧文件；实际文件名见 `summary.json` 的 `remote_path`。计划仍检查同批目标名冲突。PAN-OS 固定使用 `running-config.xml`，还要求 `Sent ... bytes` 完成行；为避免下次上传覆盖它，运行批量示例时必须能访问本机 TFTP 服务器目录，否则该设备会明确失败且不会发起上传。H3C 从 `display startup` 发现源文件，可用 YAML `tftp.h3c_source_file` 覆盖；华为默认 `flash:/startup.cfg`。Nexus 9000 默认 VRF 为 `management`，山石为 `mgt-vr`；YAML `tftp.vrfs` 接受按厂商键配置的映射。山石命令在 `vrouter` 参数后追加唯一的 `.dat` 文件名；直接调用山石连接器且不指定 `path:` 时，由设备生成文件名并在结果中返回。通过 `--tftp-root DIR` 或 YAML `tftp.verification_root` 指定本机或已挂载的服务器目录时，批量示例在每台设备完成后核验实际回执路径、非空文件、修改时间和 SHA-256，并立即保存两份历史文件；报告的 `local_file` 和 `server_archive_file` 分别指向本地批次副本和服务器归档副本。核验或归档失败不会报告成功。未提供本机目录时，可命名设备仍使用不覆盖旧文件的远端文件名，回执保留为 `device_reported`，本地批次不包含配置副本。默认示例使用 `selected` 策略；要求服务器文件核验时使用 `--success-policy verified`，并提供本机服务器目录。可运行 `ruby examples/review_tftp.rb <批次目录>`，根据会话日志复核剩余失败，而不改写原始结果。日志、`events.jsonl` 和逐台结果均以私有权限保存。
+全量 TFTP 计划保存为 `plan.json`。目标文件名通常为 `<设备名>-<IP>.cfg`，Radware 用 `.tgz`，山石用 `.dat`。可访问本机 TFTP 服务器目录时，批量示例直接使用 `<设备名>-<IP>.<扩展名>` 上传，并在服务器的 `archive/<批次>/` 与本地 `<批次目录>/tftp/` 各保留一份；上传前已有的同名文件先保存到新归档目录的 `previous/`。无法访问服务器目录时，远端文件名增加东八区批次标识及同秒序号，避免覆盖旧文件；实际文件名见 `summary.json` 的 `remote_path`。计划仍检查同批目标名冲突。PAN-OS 固定使用 `running-config.xml`，还要求 `Sent ... bytes` 完成行；为避免下次上传覆盖它，运行批量示例时必须能访问本机 TFTP 服务器目录，否则该设备会明确失败且不会发起上传。H3C 从 `display startup` 发现源文件，可用 YAML `tftp.h3c_source_file` 覆盖；华为默认 `flash:/startup.cfg`。Nexus 9000 默认 VRF 为 `management`，山石为 `mgt-vr`；YAML `tftp.vrfs` 接受按厂商键配置的映射。山石命令在 `vrouter` 参数后追加唯一的 `.dat` 文件名；直接调用山石连接器且不指定 `path:` 时，由设备生成文件名并在结果中返回。通过 `--tftp-root DIR` 或 YAML `tftp.verification_root` 指定本机或已挂载的服务器目录时，批量示例在每台设备完成后核验实际回执路径、非空文件、修改时间和 SHA-256，并立即保存两份历史文件；报告的 `local_file` 和 `server_archive_file` 分别指向本地批次副本和服务器归档副本。核验或归档失败不会报告成功。未提供本机目录时，可命名设备仍使用不覆盖旧文件的远端文件名，回执保留为 `device_reported`，本地批次不包含配置副本。默认示例使用 `selected` 策略；要求服务器文件核验时使用 `--success-policy verified`，并提供本机服务器目录。日志、`events.jsonl` 和逐台结果均以私有权限保存。
 
 批量 TFTP 源文件通过 YAML `tftp.h3c_source_file`、`tftp.h3c_wireless_source_file`、`tftp.huawei_source_file` 设置。源文件是设备上的路径，需符合连接器校验规则。
 
@@ -243,9 +243,9 @@ directory = Net::Connector::Storage::BatchDirectory.create("./backups")
 
 批量示例由 `Netdisco::CLI::Backup` 统一编排，`CLI::Options.settings` 为示例和正式 CLI 共用配置覆盖入口。
 
-终端入口按职责放在 `cli/`：`CLI::Backup` 编排批量备份，`CLI::Credentials.resolve` 解析凭据来源，`CLI::Options` 解析参数和配置覆盖。
+终端入口按职责放在 `cli/`：`CLI::Backup` 编排批量备份，`CLI::Topology` 编排发现、规划与显式应用，`CLI::Credentials.resolve` 解析凭据来源，`CLI::Options` 解析参数和配置覆盖。示例显式传入 `load_env: true`，将公开环境变量作为 YAML 和 CLI 之下的默认值；正式 CLI 保留既有的环境覆盖规则。
 示例默认 `selected`，正式 CLI 保留 `strict` 默认；两者均支持显式 `--success-policy`，退出码与报告的 `policy_success` 一致。
-新示例 `summary.json` 使用标准 schema 2 的 `devices`，不再另造 `outcomes`；旧报告可继续用 `review_tftp.rb` 读取。
+示例 `summary.json` 使用标准 schema 2 的 `devices`，逐台结果与诊断统一保存在批次报告中。
 TFTP 的 `verification` 汇总与设备条目的 `server_file_verified` 区分上传回执和服务器文件核验，核验成功还包含 `local_file`、`server_archive_file`、`bytes`、`sha256`。
 报告通过私有原子写入保存；报告保存失败会阻止成功退出，终端最终结果在报告保存之后输出。
 

data/docs/usage.md

@@ -61,7 +61,7 @@ H3C discovers its saved source with `display startup` when omitted; Huawei requi
 
 The immutable `TftpReceipt` records `server`, actual `path`, `completed_at`, `configuration_kind`, `source_file`, `format`, `requested_path`, and verification fields. Direct calls return `:device_reported` with no server digest: they confirm device output, not the server file. Explicit source files are not assumed to contain running configuration. TFTP carries configuration without encryption; restrict its network access appropriately.
 
-Explicit failure raises `:transfer_failed`; missing completion evidence raises `:transfer_unconfirmed`. A failure after confirmed upload raises `TftpCompletionError` with `error.receipt`. A mismatched explicit path is `:transfer_path_mismatch`; an unconfirmed actual path is `:transfer_path_unconfirmed` with receipt path `nil`. No automatic retransmission occurs. See the [single-device example](../examples/device_tftp.rb) and [server verification](netdisco.md#tftp-history-and-verification).
+Explicit failure raises `:transfer_failed`; missing completion evidence raises `:transfer_unconfirmed`. A failure after confirmed upload raises `TftpCompletionError` with `error.receipt`. A mismatched explicit path is `:transfer_path_mismatch`; an unconfirmed actual path is `:transfer_path_unconfirmed` with receipt path `nil`. No automatic retransmission occurs. For a single inventory device, run `bundle exec ruby examples/backup_tftp.rb --host 192.0.2.20` with the server and transfer options in [backup.yml](../examples/backup.yml). See [server verification](netdisco.md#tftp-history-and-verification).
 
 ## TextFSM parsing
 
@@ -145,6 +145,6 @@ Per-command prompts use `interactions: [Net::Connector::Interaction.new(/Token:\
 
 ## Dependencies and extensions
 
-Load device APIs with `require "net/connector"`; Netdisco has a separate entrypoint. Vendor implementations and TextFSM load on demand. Runtime dependencies declare minimum versions; the host application's lockfile selects compatible versions. Published TextFSM 0.2.0 constrains JSON to 2.x. The explicit JSON 3 source-patch matrix does not establish compatibility of the published dependency.
+Load device APIs with `require "net/connector"`; Netdisco has a separate entrypoint. Vendor implementations and TextFSM load on demand. Runtime dependencies have no version constraints; the host application's lockfile selects compatible versions. Published TextFSM 0.2.0 constrains JSON to 2.x. The explicit JSON 3 source-patch matrix does not establish compatibility of the published dependency.
 
 Examples use the development dependency `dotenv` to read the project `.env`; the library and CLI do not. Follow the [loading and migration reference](architecture.md#加载入口与厂商策略) (Chinese) for custom profiles, strategies, and protected hooks.

data/docs/usage.zh-CN.md

@@ -6,7 +6,7 @@
 
 脱敏直接复用 expect-pty 从 0.5.0 起公开的 `Expect::Redactor` 接口；连接器只管理秘密作用域和配置输出的隐私策略。
 
-运行时依赖只声明所需最低版本，不设置缺少兼容性依据的上限；宿主应用通过自己的 Gemfile/锁文件选择版本。正式发布依赖的安装验证使用 JSON 2。RubyGems 上 textfsm 0.2.0 仍约束 json ~> 2.0；JSON 3 使用固定 TextFSM 源码和显式依赖声明补丁单独验证，不代表公开依赖已经支持 JSON 3。开发工具及兼容测试矩阵的版本约束不影响 gem 使用者。
+运行时依赖不设置版本约束，宿主应用通过自己的 Gemfile 和锁文件选择兼容版本。正式发布依赖的安装验证使用 JSON 2。RubyGems 上 textfsm 0.2.0 仍约束 json ~> 2.0；JSON 3 使用固定 TextFSM 源码和显式依赖声明补丁单独验证，不代表公开依赖已经支持 JSON 3。开发工具及兼容测试矩阵的版本约束不影响 gem 使用者。
 
 示例脚本通过开发依赖 `dotenv` 自动读取项目根目录 `.env`（先执行 `bundle install`），已有进程环境变量优先；库和 CLI 本身不会隐式读取 `.env`。
 
@@ -72,7 +72,7 @@ end
 
 策略先校验参数组合，再在同一次会话租约中完成源探测、上传、证据检查和收尾。上传已确认但日志或清理失败时抛出 `TftpCompletionError`，通过 `error.receipt` 保留完成事实。显式请求与实际路径不同返回 `:transfer_path_mismatch`；实际路径无法安全确认返回 `:transfer_path_unconfirmed`，此时回执的 `path` 为 `nil`。这些错误不会自动重传；Fleet 保留上传事实并标为 `reported_with_error`。
 
-可运行[单设备示例](../examples/device_tftp.rb)：`ruby examples/device_tftp.rb --vendor huawei --host 192.0.2.20 --server 192.0.2.30 --source-file flash:/startup.cfg --path site/router.cfg`。凭据使用 `NC_DEVICE_USERNAME`、`NC_DEVICE_PASSWORD`；`--source-file`、`--path`、`--vrf` 指定传输选项。
+清单内的单台设备使用统一[批量入口](../examples/backup_tftp.rb)：`bundle exec ruby examples/backup_tftp.rb --host 192.0.2.20`。服务器、源文件和 VRF 在 [backup.yml](../examples/backup.yml) 中配置；凭据使用 `NC_DEVICE_USERNAME`、`NC_DEVICE_PASSWORD`。需要指定自定义远端路径时，使用上面的 `device.tftp_backup` API。
 
 只需在内存中采集配置时，调用 `device.running_config`；它返回 `Result`，`result.value!` 返回清理后的文本，失败时抛出对应错误。
 

data/examples/backup.yml

@@ -1,11 +1,15 @@
 # 仅保存非敏感策略，凭据使用环境变量。
-# ND_URL、ND_CACHE_TTL、NC_CONCURRENCY 可覆盖对应策略；其余由 YAML 或 CLI 设置。
+# 示例层优先级：CLI > YAML > 环境默认值；进程环境优先于 .env。
 backup:
   directory: ./examples/backups
   concurrency: 4
   # limit_per_vendor: 3 # 省略时使用全量清单。
 netdisco:
   source: http
+  cache_enabled: true
+  cache_mode: prefer # prefer / only / refresh；CLI 可覆盖。
+  cache_ttl: 259200
+  cache_directory: ./.cache/net-connector/inventory
   page_size: 500
   max_pages: 10000
   max_response_bytes: 16777216
@@ -16,6 +20,10 @@ netdisco:
 inventory:
   include_hosts: []
   exclude_hosts: []
+  include_names: []
+  exclude_names: []
+  name_match: contains # contains / prefix / glob；不区分大小写，排除优先。
+  exclude_vendors: []
   include_vendors: []
   vendor_overrides: {}
   host_overrides: {}
@@ -32,10 +40,41 @@ ssh:
   max_script_output_bytes: null
 tftp:
   vrfs:
-    cisco_nxos: management
-    hillstone: mgt-vr
-  # verification_root: /srv/tftp
-  # server: 192.0.2.10
-  # h3c_source_file: flash:/startup.cfg
-  # h3c_wireless_source_file: flash:/startup.cfg
-  # huawei_source_file: flash:/startup.cfg
+    cisco_nxos:
+      default: management
+      hosts:
+        "192.0.2.21": production # 设备值覆盖 default；null 回到设备协议缺省。
+    hillstone:
+      default: mgt-vr
+      hosts:
+        "192.0.2.22": trust-vr
+  source_interfaces:
+    h3c:
+      default: management # 单次 source ip，使用本设备连接 IPv4 地址。
+      hosts:
+        "192.0.2.23": Vlan-interface10
+        "192.0.2.24": null # 清除 management，让设备使用协议缺省源。
+    radware:
+      default: management # 单次 -mgmt；data 对应 -data。
+      hosts:
+        "192.0.2.25": data
+  # 以下地址均为文档保留地址，运行前替换为设备可达的实际服务器。
+  server: 192.0.2.10
+  servers:
+    "192.0.2.26": "192.0.2.20" # 仅此设备改用另一个服务器。
+  verification_roots: {} # 精确服务器到本机目录；设备切换服务器后不会沿用默认目录。
+  # 启用核验时将上面的 {} 替换为实际可写目录映射，例如：
+  # verification_roots:
+  #   "192.0.2.10": /srv/tftp/main
+  #   "192.0.2.20": /srv/tftp/alternate
+  source_files:
+    h3c:
+      default: null # 未指定时从设备发现；也可配置 flash:/startup.cfg。
+      hosts:
+        "192.0.2.23": flash:/startup.cfg
+    h3c_wireless:
+      default: null
+      hosts: {}
+    huawei:
+      default: flash:/startup.cfg
+      hosts: {}

data/examples/inventory.yml

@@ -0,0 +1,39 @@
+# PostgreSQL 完整批量示例；凭据使用 ND_DB_HOST/NAME/USER/PASS。
+# 只读参数化查询，不把数据库密码写入 YAML。
+netdisco:
+  source: postgres
+  db_port: 5432
+  db_sslmode: verify-full
+  # db_sslrootcert: /etc/net-connector/database-ca.crt
+  # db_connect_timeout: 10
+  query: |
+    SELECT host(ip) AS ip, name, dns, vendor, os, model, os_ver, serial
+    FROM device
+    WHERE vendor = $1
+    ORDER BY ip
+  query_params: [H3C]
+  page_size: 500
+  max_devices: 100000
+  inventory_timeout: 300
+  cache_enabled: true
+  cache_mode: prefer
+  cache_ttl: 259200
+  cache_directory: ./.cache/net-connector/inventory
+inventory:
+  include_hosts: []
+  exclude_hosts: []
+  include_names: []
+  exclude_names: []
+  name_match: contains
+  include_vendors: []
+  exclude_vendors: []
+  vendor_overrides: {}
+  host_overrides: {}
+  device_rules: []
+backup:
+  directory: ./examples/backups
+  concurrency: 4
+ssh:
+  protocol: ssh
+  host_key_policy: accept_new
+  log_level: info

data/lib/net/connector/device/tftp/strategy.rb

@@ -28,9 +28,10 @@ module Net
         def remote_path(target, _result) = target.path
 
         # 单次上传共用预检、命令预算和应答封装；厂商只提供协议命令与交互差异。
-        def script(target, source_file:, vrf: nil)
+        def script(target, source_file:, vrf: nil, source_interface: nil)
+          validate_source_interface!(target, source_interface: source_interface)
           validate_options!(target, source_file: source_file, vrf: vrf)
-          command = transfer_command(target, source_file: source_file, vrf: vrf)
+          command = transfer_command(target, source_file: source_file, vrf: vrf, source_interface: source_interface)
           interactions = transfer_interactions(target, source_file: source_file, vrf: vrf)
           Script.new([Command.new(command, timeout: 180, interactions: interactions)])
         end
@@ -46,6 +47,10 @@ module Net
           end
         end
 
+        def validate_source_interface!(_target, source_interface:)
+          raise ArgumentError, "source_interface is not supported by this TFTP strategy" unless source_interface.nil?
+        end
+
         private
 
         def transfer_command(_target, **)

data/lib/net/connector/device/tftp.rb

@@ -11,8 +11,8 @@ module Net
       module Capability
         # 要求设备直接向 TFTP 服务器导出原生配置。
         # 完成仅表示设备报告传输成功，未读取服务器端文件。
-        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil)
-          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
+        def tftp_backup(host:, path: nil, source_file: nil, vrf: nil, source_interface: nil)
+          Tftp.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf, source_interface: source_interface)
         end
       end
 
@@ -20,7 +20,7 @@ module Net
       def initialize(device) = @device = device
 
       # 参数先纯校验；源探测、上传、证据核对及收尾共用一次会话租约。
-      def call(host:, path: nil, source_file: nil, vrf: nil)
+      def call(host:, path: nil, source_file: nil, vrf: nil, source_interface: nil)
         receipt = nil
         strategy_class = @device.profile.tftp_strategy
         unless strategy_class
@@ -34,12 +34,21 @@ module Net
         source_file = TftpTarget.validate_source_file!(source_file).dup.freeze unless source_file.nil?
         vrf = vrf&.dup&.freeze
         target = TftpTarget.new(host: host, path: path.nil? ? "preflight.cfg" : path, explicit_path: !path.nil?)
+        source_interface = source_interface.dup.freeze if source_interface.is_a?(String)
+        unless source_interface.nil?
+          unless strategy.respond_to?(:validate_source_interface!)
+            raise ArgumentError, "source_interface is not supported by this TFTP strategy"
+          end
+          strategy.validate_source_interface!(target, source_interface: source_interface)
+        end
         strategy.validate_options!(target, source_file: source_file, vrf: vrf)
         @device.with_operation(:tftp_backup) do
           source = strategy.resolve_source_file(source_file)
           source = TftpTarget.validate_source_file!(source).dup.freeze unless source.nil?
           target = TftpTarget.new(host: target.host, path: strategy.default_path(source), explicit_path: false) if path.nil?
-          result = @device.execute_operation(strategy.script(target, source_file: source, vrf: vrf),
+          transfer_options = { source_file: source, vrf: vrf }
+          transfer_options[:source_interface] = source_interface unless source_interface.nil?
+          result = @device.execute_operation(strategy.script(target, **transfer_options),
                                              name: :tftp_backup, privilege: false)
           confirm_transfer!(strategy, target, result)
           # 一旦看到明确完成证据就保存回执；路径解析或用户钩子失败也不能抹去上传事实。

data/lib/net/connector/device/topology/audit.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "plan"
+require_relative "stages"
+
+module Net
+  module Connector
+    class Topology
+      # 逐接口区分可核实变更、未核实证据和只读平台；计划只包含明确获准的接口范围。
+      Audit = Data.define(:plan, :comparisons, :issues, :manual_required) do
+        def initialize(plan:, comparisons:, issues:, manual_required:)
+          raise ArgumentError, "audit plan must be a topology plan or nil" unless plan.nil? || plan.instance_of?(Plan)
+          unless [true, false].include?(manual_required) && comparisons.is_a?(Array) && issues.is_a?(Array)
+            raise ArgumentError, "invalid topology audit"
+          end
+          super(plan: plan, comparisons: copy_rows(comparisons), issues: copy_rows(issues), manual_required: manual_required)
+        end
+
+        def complete? = issues.empty?
+        def changes = comparisons.count { |entry| !%i[matches unverified].include?(entry[:status]) }
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        private
+
+        def copy_rows(rows)
+          rows.map do |row|
+            unless row.is_a?(Hash) && row.keys.all?(Symbol) && row.values.all? { |value| value.nil? || value.is_a?(String) || value.is_a?(Symbol) }
+              raise ArgumentError, "audit rows must contain scalar metadata"
+            end
+            row.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          end.freeze
+        end
+      end
+
+      # 纯计划构造器不连接设备；协议命令仍由策略及 Stages 生成。
+      class AuditBuilder
+        def initialize(host:, vendor:, strategy:, neighbors:, descriptions:, formatter:)
+          @host, @vendor, @strategy = host, vendor, strategy
+          @neighbors, @descriptions, @formatter = neighbors, descriptions, formatter
+          @comparisons, @issues, @evidence, @changes = [], [], {}, []
+        end
+
+        def call
+          groups = @neighbors.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+          groups.each { |interface, peers| inspect_interface(interface, peers) }
+          writable = @strategy.supports?(:interface_description_changes)
+          plan = build_plan if writable
+          Audit.new(plan: plan, comparisons: @comparisons, issues: @issues,
+                    manual_required: !writable && @comparisons.any? { |entry| entry[:status] != :matches })
+        end
+
+        private
+
+        def inspect_interface(interface, peers)
+          peer = peers.first
+          current = @descriptions[interface]
+          row = { interface: peer.local_interface, neighbor: peer.neighbor_name, port: peer.neighbor_interface,
+                  current: current, expected: nil, status: :unverified }
+          @comparisons << row
+          if peers.size != 1 || peer.neighbor_name.empty? || peer.neighbor_interface.empty?
+            return reject_interface(row, :ambiguous_neighbor)
+          end
+          return reject_interface(row, :interface_missing) unless @descriptions.key?(interface)
+
+          proposed = @formatter.call(peer)
+          InterfaceDescription.validate!(proposed)
+          local = @strategy.configuration_interface(peer.local_interface)
+          InterfaceDescription.validate_interface!(local)
+          row.merge!(expected: proposed, status: compare_status(current, proposed))
+          @evidence[interface] = [peer.neighbor_name, peer.neighbor_interface, current]
+          return if current == proposed
+
+          @changes << Change.new(interface: local, old_description: current, new_description: proposed, neighbor: peer)
+        rescue ArgumentError
+          reject_interface(row, :unsafe_description)
+        end
+
+        def reject_interface(row, code)
+          row[:reason] = code
+          @issues << { interface: row[:interface], code: code }
+          nil
+        end
+
+        def compare_status(current, proposed)
+          return :matches if current == proposed
+          return :missing_description if current.empty?
+
+          :content_mismatch
+        end
+
+        def build_plan
+          commands = if @changes.empty?
+                       []
+                     else
+                       Stages.build(strategy: @strategy, host: @host, changes: @changes).values.flat_map { |script| script.map(&:text) }
+                     end
+          Plan.new(host: @host, vendor: @vendor, evidence: @evidence, changes: @changes, commands: commands, scope: :interfaces)
+        end
+      end
+      private_constant :AuditBuilder
+    end
+  end
+end

data/lib/net/connector/device/topology/plan.rb

@@ -6,17 +6,17 @@ module Net
   module Connector
     class Topology
       # 审批树在领域边界固定；单设备与批量操作共享同一不可变计划。
-      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands) do
-        def initialize(host:, vendor:, evidence:, changes:, commands:)
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands, :scope) do
+        def initialize(host:, vendor:, evidence:, changes:, commands:, scope: :device)
           unless host.is_a?(String) && vendor.is_a?(Symbol) && evidence.is_a?(Hash) &&
                  changes.is_a?(Array) && changes.all? { |change| change.instance_of?(Change) } &&
-                 commands.is_a?(Array) && commands.all?(String)
+                 commands.is_a?(Array) && commands.all?(String) && %i[device interfaces].include?(scope)
             raise ArgumentError, "description plan contains invalid fields"
           end
 
           super(host: host.frozen? ? host : host.dup.freeze, vendor: vendor,
                 evidence: copy_evidence(evidence), changes: changes.dup.freeze,
-                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze)
+                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze, scope: scope)
         end
 
         def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))

data/lib/net/connector/device/topology.rb

@@ -3,6 +3,7 @@
 require_relative "topology/strategy"
 require_relative "topology/stages"
 require_relative "topology/plan"
+require_relative "topology/audit"
 
 module Net
   module Connector
@@ -26,6 +27,11 @@ module Net
           Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
         end
 
+        # 核实各接口，保留缺失/冲突证据并为可确认的接口构造独立计划。
+        def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).audit_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
         # 明确确认且现场证据未变化时执行接口描述计划。
         def apply_interface_descriptions(plan, confirmed: false)
           Topology.new(self).apply_interface_descriptions(plan, confirmed: confirmed)
@@ -151,6 +157,17 @@ module Net
         end
       end
 
+      def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+          raise ArgumentError, "description formatting options must be boolean"
+        end
+        formatter ||= ->(peer) { InterfaceDescription.format(peer, abbreviate: abbreviate, lowercase: lowercase) }
+        @device.with_operation(:plan) do
+          AuditBuilder.new(host: @device.host, vendor: @device.vendor, strategy: @strategy,
+                           neighbors: neighbors, descriptions: interface_descriptions, formatter: formatter).call
+        end
+      end
+
       # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
       def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
@@ -246,7 +263,12 @@ module Net
       # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
       def revalidate_plan!(plan)
         discovered = neighbors
-        evidence = evidence_for(discovered, interface_descriptions)
+        current = interface_descriptions
+        if plan.scope == :interfaces
+          discovered = discovered.select { |neighbor| plan.evidence.key?(@strategy.interface_key(neighbor.local_interface)) }
+          current = current.slice(*plan.evidence.keys)
+        end
+        evidence = evidence_for(discovered, current)
         current_neighbors = discovered.to_h { |neighbor| [@strategy.interface_key(neighbor.local_interface), neighbor] }
         same_neighbors = plan.changes.all? do |change|
           current_neighbors[@strategy.interface_key(change.interface)] == change.neighbor