net-connector 0.8.0 → 0.9.0

data/docs/usage.md

@@ -0,0 +1,124 @@
+# Device guide
+
+[简体中文](usage.zh-CN.md) | [Home](../README.md) | [Netdisco and fleet backups](netdisco.md)
+
+## Supported devices
+
+Use these vendor keys with `Net::Connector.open` or `Net::Connector.build`:
+
+| Vendor key | Devices | Configuration command | Save command |
+| --- | --- | --- | --- |
+| `:h3c` | H3C Comware | `dis cur` | `save force` |
+| `:h3c_wireless` | H3C wireless controllers | `dis cur` | `save force` |
+| `:cisco_ios` | Cisco IOS / IOS XE | `show running-config` | `copy running-config startup-config` |
+| `:cisco_nxos` | Cisco NX-OS | `show running-config` | `copy run start` |
+| `:huawei` | Huawei | `dis cur` | `save force` |
+| `:hillstone` | Hillstone StoneOS | `show configuration running` | `save all` |
+| `:radware` | Radware Alteon | `/cfg/dump` | `/cfg/save` |
+| `:palo_alto` | Palo Alto PAN-OS | Set-format export from configuration view | Unsupported |
+
+`device.supports?(:tftp_backup)` checks implemented capabilities without connecting. It does not establish firmware compatibility or account permissions. See the [capability matrix](architecture.md#厂商能力) (Chinese).
+
+## Sessions and local backups
+
+```ruby
+require "net/connector"
+
+Net::Connector.open(:cisco_ios,
+  host: "192.0.2.10", username: ENV.fetch("NC_DEVICE_USERNAME"),
+  password: ENV.fetch("NC_DEVICE_PASSWORD"),
+  known_hosts: "/etc/net-connector/known_hosts", host_key_policy: :strict) do |device|
+  backup = device.backup(path: "/var/backups/network/router.cfg", lock_timeout: 2)
+  puts "#{backup.change}: #{backup.sha256}"
+end
+```
+
+Create and protect the parent directory first. `open` closes the session on return, exception, or interruption. One connector owns one session; competing operations fail with `SessionBusy`.
+
+`backup` locks the path before collecting, compares SHA-256, and reports `:created`, `:changed`, or `:unchanged`. Unchanged safe files retain their mtime. Default lock acquisition is immediate; contention raises `BackupBusy`. `lock_timeout:` allows a bounded wait. Call backup outside an existing session operation so path ownership precedes session ownership.
+
+Writes use mode `0600`, file synchronization, atomic replacement, and parent-directory synchronization. A collection failure leaves the old file intact. Failure after replacement raises `BackupPersistenceError`; `error.backup` retains metadata and `error.receipt` distinguishes `:committed` from `:durable`. Unsupported directory synchronization is reported as `:backup_durability_unsupported`. Do not repeat the device operation to recover file finalization.
+
+Private `.net-connector-<digest>.lock` files remain in the directory. All writers must follow the same locking protocol; ancestor directories remain the caller's responsibility.
+
+For an in-memory configuration, use `device.running_config.value!`. The `Result` retains completed steps on failure. Collection suppresses configuration content in logs and error diagnostics, including debug/raw and application loggers; returned output and backup files remain sensitive.
+
+## Device-initiated TFTP
+
+```ruby
+receipt = device.tftp_backup(host: "192.0.2.30", source_file: "flash:/startup.cfg",
+                             path: "site/switch.cfg") # Huawei or H3C
+```
+
+H3C discovers its saved source with `display startup` when omitted; Huawei requires `source_file:`. IOS uses interactive `copy running-config tftp:`. NX-OS defaults to VRF `management`; Hillstone defaults to `mgt-vr`. These two vendors accept `vrf:`. Radware exports `.tgz`, Hillstone exports startup `.dat`, and PAN-OS always uploads `running-config.xml`.
+
+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).
+
+## TextFSM parsing
+
+```ruby
+interfaces = device.parse_command("show ip interface brief") # Cisco IOS
+rows = device.parse_config(template: "cisco_ios_running_config_interfaces.textfsm")
+
+saved = Net::Connector::Storage::SavedConfig.new(directory: "/var/backups/network")
+rows = saved.parse(host: "192.0.2.10", template: "/path/to/template.textfsm")
+```
+
+Parsers return arrays of hashes with template field names. `parse_command` uses vendor/command lookup; `parse_config` requires a template. Pass `template:` or `template_dir:` to select external templates. No matches return `[]`; missing or invalid templates raise `ParsingError`, and device failures retain their connector error.
+
+Parsing validates UTF-8 before and after terminal rendering. Invalid bytes raise `:invalid_output_encoding`; no encoding is guessed. Raw results, backups, and exports retain their bytes. Each parse has its own parser, and TextFSM loads only when parsing is requested.
+
+## Topology and interface descriptions
+
+```ruby
+neighbors = device.neighbors
+plan = device.plan_interface_descriptions
+puts plan.commands.join("\n")
+# Review the plan and approve the exact commands before applying it.
+device.apply_interface_descriptions(plan, confirmed: true).value!
+```
+
+IOS/NX-OS use CDP; H3C, H3C wireless, Hillstone, and PAN-OS use LLDP. Neighbor records contain local interface, peer name/interface, chassis ID, and protocol. Unknown or partial output raises an error rather than becoming an empty table. Radware can read port names but cannot discover neighbors or apply descriptions.
+
+The default description is `To <peer name> <peer interface abbreviation>`. Abbreviations preserve case. Use `abbreviate: false`, `lowercase: true`, or a formatter block to customize them. Raw identities and evidence are unchanged.
+
+Apply requires `confirmed: true` and rechecks neighbor and description evidence. Changed evidence raises `:stale_plan` before writing. Supported immediate-change devices follow change, exit configuration, read back, then save. Failed/incomplete readback prevents save; unconfirmed persistence returns `:persistence_unconfirmed` with completed steps. Changes may already be active, so commands are never replayed or rolled back automatically.
+
+PAN-OS supports read-only discovery and descriptions. Automatic changes are disabled with `:candidate_isolation_unavailable`; collection checks candidate differences before and after export and requires set format. See [topology contracts](architecture.md#业务约束) (Chinese) before extending these flows.
+
+## Scripts and interactions
+
+```ruby
+script = Net::Connector::Script.parse(<<~CLI, name: "change-123")
+  configure terminal
+  interface GigabitEthernet1/0/1
+  description uplink
+  end
+CLI
+result = device.execute_script(script)
+warn "#{result.error.code}: #{result.steps.size} completed commands" if result.failure?
+```
+
+`execute_command` runs one command; `execute_script` accepts a `Script` or command array. `Script.load(path)` reads a file. Commands are validated before I/O; completed steps survive later failures. `save_config` explicitly sends save commands; ordinary scripts do not save automatically.
+
+Set `max_script_output_bytes:` to bound cumulative raw responses, including additional queries. Default is `nil`. Exceeding it returns `ScriptOutputLimitExceeded` (`:script_output_limit_exceeded`) and stops subsequent commands; the current command may already have executed. `max_output_bytes` separately limits each response. Neither setting is a process-memory limit.
+
+Per-command prompts use `interactions: [Net::Connector::Interaction.new(/Token:\z/, ->(_) { "value\n" }, sensitive: true)]`. Mark commands containing secrets `sensitive: true`. For safe command text with sensitive output, use `output_sensitive: true`; `running_config` enables this automatically.
+
+## Connections, host keys, and logging
+
+`Configuration` accepts `protocol: :ssh` or `:telnet`, ports, timeouts, output limits, `known_hosts`, `log_file`, `logger`, `log_format`, and `log_level`. Host-key policy defaults to `:strict`. `:accept_new` registers first-use keys and rejects changed keys; `:replace` requires an explicit dedicated `known_hosts` file and replaces only the affected host on a recognized key-change failure. Never delete the persistent trust file to resolve an error.
+
+`telnet_fallback` and `legacy_ssh` are disabled by default and apply only to recognized connection failures. Network login does not hold the shared trust-file lock. Authenticated merging has a separate `login_timeout` wait budget; `:known_hosts_busy` closes the session and preserves the shared file.
+
+`log_file` requires a regular file, rejecting symlinks and special files. Text logs use Ruby Logger; `:info` records lifecycle events, `:debug` adds permitted output, and `:raw` writes protected device bytes. Injected `logger: Rails.logger` or a standard Logger keeps its ownership, formatting, and current threshold; the stricter of its level and `log_level` applies.
+
+`on_event: ->(event) { ... }` receives frozen, redacted `Log::Event` values synchronously. Keep callbacks short; failures are surfaced as logging failures. Events include session/command IDs, operation, phase, duration, byte counts, and controlled diagnostics. `response_received` confirms a response, not device persistence or TFTP server verification. Custom events use `device.log_event("audit", level: :info, count: 2)`; sensitive scopes hide arbitrary custom payloads.
+
+## 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.
+
+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

@@ -0,0 +1,190 @@
+# 设备操作指南
+
+[English](usage.md) | [返回首页](../README.zh-CN.md) | [Netdisco 批量备份](netdisco.zh-CN.md)
+
+支持 Ruby 3.2 及以上版本和 POSIX 系统。SSH 调用本机 OpenSSH，Telnet 需要本机安装 `telnet` 并显式选择。主要依赖为 [`expect-pty`](https://rubygems.org/gems/expect-pty) 0.5.0 及以上和 [`textfsm`](https://rubygems.org/gems/textfsm) 0.2.0 及以上。
+
+脱敏直接复用 expect-pty 从 0.5.0 起公开的 `Expect::Redactor` 接口；连接器只管理秘密作用域和配置输出的隐私策略。
+
+运行时依赖只声明所需最低版本，不设置缺少兼容性依据的上限；宿主应用通过自己的 Gemfile/锁文件选择版本。正式发布依赖的安装验证使用 JSON 2。RubyGems 上 textfsm 0.2.0 仍约束 json ~> 2.0；JSON 3 使用固定 TextFSM 源码和显式依赖声明补丁单独验证，不代表公开依赖已经支持 JSON 3。开发工具及兼容测试矩阵的版本约束不影响 gem 使用者。
+
+示例脚本通过开发依赖 `dotenv` 自动读取项目根目录 `.env`（先执行 `bundle install`），已有进程环境变量优先；库和 CLI 本身不会隐式读取 `.env`。
+
+## 支持的设备
+
+`device.supports?(:tftp_backup)` 等能力查询不会连接设备，只表示该连接器实现了对应操作，不代表设备权限或固件一定支持。完整能力矩阵和扩展示例见[厂商能力](architecture.md#厂商能力)。
+
+| 厂商标识 | 设备系列 | 运行配置命令 | 保存配置命令 |
+| --- | --- | --- | --- |
+| `:h3c` | H3C Comware | `dis cur` | `save force` |
+| `:h3c_wireless` | H3C 无线控制器 | `dis cur` | `save force` |
+| `:cisco_ios` | Cisco IOS / IOS XE | `show running-config` | `copy running-config startup-config` |
+| `:cisco_nxos` | Cisco NX-OS | `show running-config` | `copy run start` |
+| `:radware` | Radware Alteon | `/cfg/dump` | `/cfg/save` |
+| `:palo_alto` | Palo Alto PAN-OS | 候选视图中的 set 格式导出 | 不支持 |
+| `:huawei` | 华为 | `dis cur` | `save force` |
+| `:hillstone` | 山石 StoneOS | `show configuration running` | `save all` |
+
+厂商标识仅使用上表的规范名称。厂商连接器位于 `Net::Connector` 下，例如 `Net::Connector::H3cWireless::Connector`。
+
+## 登录与本地备份
+
+```ruby
+Net::Connector.open(:cisco_ios,
+  host: "192.0.2.10", username: "admin", password: ENV.fetch("NC_DEVICE_PASSWORD"),
+  known_hosts: "/etc/net-connector/known_hosts", host_key_policy: :strict,
+  log_file: "/var/log/net-connector/router.log") do |device|
+  backup = device.backup(path: "/var/backups/router-running.cfg")
+  puts "#{backup.bytes} 字节，SHA-256 #{backup.sha256}"
+end
+```
+
+`open` 会在代码块结束或出错时关闭会话。`backup` 在采集前取得目标路径锁，持有到比较、保存和生成原有 `Backup` 元数据对象完成；采集失败不会覆盖旧备份。同路径争用默认立即抛出 `BackupBusy`（`code: :backup_busy`），需要有限等待可传 `lock_timeout: 2`，单位为秒。直接调用 `backup`；不要在已有 `with_operation` 会话租约内调用，否则会因锁顺序返回 `SessionBusy`。
+
+写入使用 `0600` 临时文件、文件同步、原子替换及父目录同步。替换后同步或收尾失败会抛出 `BackupPersistenceError`，`error.backup` 保留已写文件的元数据，`error.receipt` 区分 `:committed`（持久性未确认）和 `:durable`（同步已完成）。目录同步不受支持对应 `:backup_durability_unsupported`，不会静默报告持久化成功，也不会自动重做设备采集。
+
+调用方应创建并保护备份目录，运行配置可能含有设备凭据。同目录下的 `.net-connector-<摘要>.lock` 是私有的长期锁文件，正常释放不删除它。所有写入者须使用本库的锁协议；`NOFOLLOW` 不保护被外部替换的祖先目录。锁名保守合并大小写及 Unicode 等价写法，实际备份文件名不变；在区分大小写的文件系统上，这些名称也会串行。
+
+## 设备发起的 TFTP 备份
+
+`tftp_backup` 让设备把原生配置直接上传到 TFTP 服务器，命令和提示交互由厂商策略提供。H3C 和华为从设备文件读取源配置，例如：
+
+```ruby
+Net::Connector.open(:huawei, host: "192.0.2.20", username: ENV.fetch("NC_DEVICE_USERNAME"),
+                    password: ENV.fetch("NC_DEVICE_PASSWORD")) do |device|
+  transfer = device.tftp_backup(host: "192.0.2.30", source_file: "flash:/startup.cfg")
+  puts "已上传 #{transfer.path} 到 #{transfer.server}"
+end
+```
+
+示例会下发 `tftp 192.0.2.30 put flash:/startup.cfg`；可传入 `path: "site/switch.cfg"` 指定目标文件名。H3C 默认通过 `display startup` 查找保存配置；华为因型号差异需要显式指定 `source_file:`。Cisco IOS 使用交互式 `copy running-config tftp:`；Nexus 9000 默认使用 `vrf management`，可用 `vrf:` 覆盖。山石导出已保存的启动配置，Radware Alteon 生成 `.tgz` 并处理私钥及 `mansync` 提示，PAN-OS 使用固定的 `running-config.xml` 文件名。其他厂商默认使用 `<管理地址>.cfg`。
+
+只有设备回显确认传输完成，`tftp_backup` 才返回不可变的 `TftpReceipt`。回执直接包含 `server`、实际目标 `path`、`completed_at`、`configuration_kind`、`source_file`、`format`、`requested_path`、`verification` 和 `server_sha256`。明确失败对应 `:transfer_failed`，缺少成功证据对应 `:transfer_unconfirmed`。本方法不读取服务器上的文件。TFTP 不加密配置数据，应限制在合适的管理网络中使用。
+
+回执的当前验证等级为 `:device_reported`，服务器摘要为 `nil`。H3C 自动探测结果标为 `:startup`；H3C/华为显式文件标为 `:saved_file`，格式为 `:unknown`，不凭扩展名推断内容。山石未指定文件名时 `requested_path` 为 `nil`，`path` 保留设备生成名称。
+
+策略先校验参数组合，再在同一次会话租约中完成源探测、上传、证据检查和收尾。上传已确认但日志或清理失败时抛出 `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` 指定传输选项。
+
+只需在内存中采集配置时，调用 `device.running_config`；它返回 `Result`，`result.value!` 返回清理后的文本，失败时抛出对应错误。
+
+配置采集统一由 `device/running_config` 提供，厂商差异位于 `vendor/<厂商>/running_config`。
+旧 `operations/running_config`、TFTP / 拓扑厂商转发路径及 `engine/base` 等设备转发入口已移除；
+自定义扩展请按[加载入口与迁移表](architecture.md#加载入口与厂商策略)使用当前路径和常量。
+
+子类可覆盖 protected 的 `login_interactions`、`confirmation_interactions`，通过 `super` 取得档案中的交互数组再追加规则。原 `login_dialogues`、`confirmation_dialogues` 已改名，不保留别名；这两个钩子仍不属于应用层公开调用入口。
+
+配置采集默认屏蔽日志和错误诊断中的配置正文，包括 debug/raw 日志和外部 logger；返回的配置、步骤输出和备份内容保持完整。调用方应按敏感数据保管这些业务结果。
+
+## TextFSM 解析
+
+`parse_command` 执行一条命令，再按厂商和命令选择 TextFSM 模板。内置索引覆盖 Cisco IOS 的 `show ip interface brief`，以及拓扑发现使用的 CDP/LLDP 命令：
+
+```ruby
+Net::Connector.open(:cisco_ios, host: "192.0.2.10", username: "admin",
+                    password: ENV.fetch("NC_DEVICE_PASSWORD")) do |device|
+  interfaces = device.parse_command("show ip interface brief")
+  puts interfaces.first.fetch("INTERFACE")
+end
+```
+
+`parse_config` 采集运行配置，要求显式指定模板。内置 Cisco IOS 模板只提取接口名称和描述，并非完整配置模型：
+
+```ruby
+interfaces = device.parse_config(template: "cisco_ios_running_config_interfaces.textfsm")
+```
+
+两种方法都返回由模板字段名组成的哈希数组；匹配不到记录时返回 `[]`。模板缺失或无效会抛出 `ParsingError`，设备命令失败则保留原始连接器错误。可用 `template:` 指定外部模板，或用 `template_dir:` 指定含 `index` 的模板目录。每次解析使用独立解析器，批量任务之间不共享状态。已有本地备份也可离线解析：
+
+```ruby
+saved = Net::Connector::Storage::SavedConfig.new(directory: "/var/backups")
+rows = saved.parse(host: "192.0.2.10", template: "/path/to/template.textfsm")
+```
+
+解析默认严格检查 UTF-8 字节，包括终端控制符处理前的原文和处理后的文本；非法字节会抛出 `ParsingError`（`code: :invalid_output_encoding`），不会转成替换文本继续生成记录或拓扑计划。库不猜测或自动转换其他编码，原始结果、备份和离线导出保持原字节。Netdisco 入口及纯文件导出不加载 TextFSM，实际解析时才加载。
+
+## 邻居发现与接口描述
+
+`neighbors` 在 Cisco IOS/NX-OS 上查询 CDP，在 H3C、H3C 无线、山石和 PAN-OS 上查询 LLDP。记录包含 `local_interface`、`neighbor_name`、`neighbor_interface`、`chassis_id` 和 `protocol`。H3C 会按表头选择不同列顺序的模板；未知输出会抛出 `ParsingError`，不会误判为空表。`interface_descriptions` 从运行配置读取当前描述，Radware 则从配置转储读取端口名称。
+
+```ruby
+Net::Connector.open(:h3c, host: "192.0.2.10", username: ENV.fetch("NC_DEVICE_USERNAME"),
+                    password: ENV.fetch("NC_DEVICE_PASSWORD")) do |device|
+  plan = device.plan_interface_descriptions
+  plan.changes.each { |change| puts "#{change.interface}: #{change.old_description.inspect} -> #{change.new_description.inspect}" }
+  puts plan.commands.join("\n")
+  # 核对将要下发的命令，并完成操作审批。
+  result = device.apply_interface_descriptions(plan, confirmed: true)
+  result.value!
+end
+```
+
+默认描述为 `To <邻居名称> <邻居接口简称>`。接口缩写默认开启并保留大小写：`ethernet1/1` 变为 `eth1/1`，`Ethernet1/1` 变为 `Eth1/1`，`GigabitEthernet1/0/1` 变为 `Gi1/0/1`；未知形式保持原样。原始邻居记录、计划证据和本机下发接口名不会被缩写。`abbreviate: false` 关闭缩写，`lowercase: true` 才会转为小写；也可传入代码块自行生成完整描述。公共纯函数是 `Net::Connector::Topology::InterfaceDescription.format`。
+
+规划会拒绝歧义邻居、缺少对端身份、不安全文本和无法识别的输出。下发必须传 `confirmed: true`，操作会再次读取邻居和旧描述；证据变化在写入前抛出 `DeviceError`，其 `code` 为 `:stale_plan`。IOS/NX-OS、H3C 和山石采用“修改 → 退出配置视图 → 读回 → 保存”的顺序；读回不匹配返回 `:description_unconfirmed`，解析不完整或查询命令不符合审批时也不会保存。
+
+`plan.commands` 现在包括读回命令，旧版计划必须重新生成、审核；执行仍返回 `Result`，保留修改、读回及保存阶段已经完成的步骤。只有设备提供明确保存完成行才成功，保存超时、失败或只有提示符会返回 `:persistence_unconfirmed`，此时描述可能已生效，不能自动重放或回滚。现场下发前仍应按设备固件核对命令与回显。
+
+PAN-OS 的自动描述计划及改写暂不提供，`supports?(:interface_description_changes)` 为 false，入口在设备 I/O 前抛出 `:candidate_isolation_unavailable`。候选配置的归属、验证及提交需要经目标固件实验确认的独立流程；目前可继续只读查询邻居和描述。Radware 支持读取端口名称，但不提供邻居发现或自动改写，其 `neighbors` 返回 `:neighbor_discovery_unsupported`。
+
+PAN-OS 在导出前后检查候选配置差异，并拒绝 XML 或非 set 格式输出，避免将未提交配置误作运行配置。
+
+## 命令脚本与自动交互
+
+```ruby
+script = Net::Connector::Script.parse(<<~CLI, name: "change-123")
+  # 独立成行的注释会被忽略。
+  configure terminal
+  interface GigabitEthernet1/0/1
+  description uplink
+  end
+CLI
+
+result = device.execute_script(script) do |step|
+  puts "#{step.command.text}: #{step.duration.round(2)} 秒"
+end
+
+if result.failure?
+  warn "#{result.error.code}，阶段 #{result.error.phase}"
+  warn "失败前已完成 #{result.steps.size} 条命令"
+end
+```
+
+`execute_command` 执行一条命令；`execute_script` 接收 `Script` 或命令数组；`Script.load(path)` 读取脚本文件。所有命令在设备 I/O 前校验，后续步骤失败时仍保留已完成结果，库不会自动重放命令。`save_config` 显式执行厂商保存命令，普通脚本不会自动保存。
+
+创建连接器时可设置 `max_script_output_bytes: 8 * 1024 * 1024`，限制每个脚本及其追加查询累计收到的原始响应字节；默认 `nil` 保持原有完整输出行为。达到上限后不再发送下一命令，当前响应超过上限时保留刚完成的步骤并返回 `ScriptOutputLimitExceeded`（`code: :script_output_limit_exceeded`）。命令可能已经执行，不会自动重试。原有 `max_output_bytes` 继续限制单次读取响应；累计预算不是进程内存上限，详细计数规则见架构文档。
+
+厂商档案处理分页和常见确认提示。特定命令可给 `execute_command` 传入 `interactions: [Net::Connector::Interaction.new(/Token:\z/, ->(_) { "value\n" }, sensitive: true)]`。敏感命令及交互会暂停回显日志并在错误中脱敏；若普通命令文本包含秘密，必须显式标记 `sensitive: true`。
+
+命令文本安全、输出可能包含秘密时，使用 `device.execute_command("show running-config", output_sensitive: true)`。该标记保护响应及其准备、后处理、回调异常，保留安全命令文字；不会改写 `Result` 的业务输出。`running_config` 自动启用此保护，手写脚本的默认值仍为 `false`。
+
+## 连接与日志设置
+
+连接参数 `on_event: ->(event) { ... }` 接收不可变、已脱敏的 `Log::Event`，可与日志文件或应用 logger 共用；按 `log_level` 过滤，独立于应用 logger 的阈值。回调同步执行，应保持简短；异常按日志故障处理，不会静默吞掉。它不提供未脱敏的配置正文。
+
+`Configuration` 支持 `protocol: :ssh`（默认）或 `:telnet`，以及端口、超时、输出大小、`log_file`、`logger`、`log_format`、`log_level` 和 `known_hosts` 等参数。文本日志使用 Ruby 标准库 `Logger`，记录毫秒时间、级别、设备、中文说明和完整事件字段。`:info` 包括连接、登录、命令响应、脚本处理和 TFTP 结果；`:debug` 增加逐行脱敏回显；`:warn`、`:error` 只保留相应级别。`:raw` 文件只写经过现有敏感保护的设备字节，不添加事件字段。
+
+`log_file` 只接受普通文件，拒绝符号链接、FIFO 和设备文件；应用管理的输出流可通过 `logger` 注入。命令已经完成后若日志或事件回调失败，失败结果仍保留完成步骤，TFTP 错误仍携带已确认的设备回执；调用方不能据此自动重放命令。
+
+每次连接生成 `session_id`，每条实际发送的命令分配 `command_id`；日志还包含 `operation`、`phase`、脚本 `source` / `line`、`duration_ms`、`response_bytes` 和失败 `code`。`command_complete` 的 `response_received` 只表示收到了提示符；`operation_complete` 覆盖脚本准备、执行及后处理，不替代 TFTP 服务端核验或设备持久化证据。普通自定义事件使用 `device.log_event("audit", level: :info, count: 2)`。
+
+可注入 `logger: Rails.logger` 或普通 `Logger`。有效级别取 `log_level` 与调用方**当前**级别中较严格的一项；连接器不修改它的级别、formatter 或 progname，也不关闭它。消息是已脱敏且冻结的 `Net::Connector::Log::Event`，`to_s` 供文本显示，`to_h` 供应用 formatter 输出 JSON：
+
+```ruby
+require "net/connector"
+require "json"
+require "logger"
+require "time"
+
+logger = Logger.new($stdout)
+logger.formatter = lambda do |severity, time, program, message|
+  fields = message.is_a?(Net::Connector::Log::Event) ? message.to_h : { message: message.to_s }
+  "#{JSON.generate(time: time.iso8601(3), severity: severity, program: program, **fields)}\n"
+end
+# 将 logger: logger 传给 Net::Connector.build / open。
+```
+
+事件字段接受字符串、符号、整数、有限浮点数、布尔和 nil；复杂对象统一隐藏，不展开对象内容。事件名、字段名和值经过校验/脱敏，会话与命令标识不可由自定义字段覆盖。敏感命令或配置处理期间，自定义事件的名称和载荷整体隐藏，避免钩子把未登记的配置秘密写进日志。更多边界见[架构文档](architecture.md)。
+
+主机密钥策略默认为 `:strict`；`:accept_new` 接受首次连接的密钥；`:replace` 需要显式 `known_hosts` 文件。`telnet_fallback` 和 `legacy_ssh` 默认关闭，只在已识别的连接失败时使用。外部命令以参数数组执行，不经 shell。Telnet 不提供 SSH 加密，只应在可信管理网络启用。设备授权和变更审批由调用方负责。

data/examples/backup.yml

@@ -1,9 +1,9 @@
-# Non-secret settings only. Credentials belong in environment variables.
-# Common NC_* environment variables override their YAML counterparts.
+# 仅保存非敏感策略，凭据使用环境变量。
+# ND_URL 可覆盖 netdisco.url；其他公开策略由 YAML 或 CLI 设置。
 backup:
   directory: ./examples/backups
   concurrency: 4
-  # limit_per_vendor: 3 # Omit for full inventory.
+  # limit_per_vendor: 3 # 省略时使用全量清单。
 netdisco:
   source: http
   page_size: 500
@@ -27,13 +27,14 @@ inventory:
 ssh:
   protocol: ssh
   vendor_protocols: {}
-  host_key_policy: accept_new # Persist first-seen keys; reject changed keys.
+  host_key_policy: accept_new # 保存首次见到的密钥，拒绝已有密钥变化。
   log_level: info
   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

data/examples/inventory_sql.yml

@@ -1,6 +1,10 @@
-# 数据库连接只从 NETDISCO_DB_* 环境变量读取；此文件可直接编辑并纳入版本控制。
+# 数据库身份从 ND_DB_HOST/NAME/USER/PASS 读取；非敏感连接策略在此设置。
 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

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "English"
 require "forwardable"
 require_relative "../engine/core"
 require_relative "profile"
@@ -67,12 +66,14 @@ module Net
         begin
           device.connect
           yield device
+        rescue Exception # rubocop:disable Lint/RescueException -- 本次连接或块失败时仍关闭设备，并保留原始故障或中断。
+          failed = true
+          raise
         ensure
-          active_error = $ERROR_INFO
           begin
             device.close
-          rescue StandardError
-            raise unless active_error
+          rescue Exception # rubocop:disable Lint/RescueException -- 只保留本次作用域的原始异常，不受外层已处理异常影响。
+            raise unless failed
           end
         end
       end

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

@@ -39,6 +39,7 @@ module Net
       end
     end
 
+    # 先取得路径锁再采集和原子写入；提交后的收尾错误仍保留备份元数据。
     class LocalBackup
       # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
       module Capability
@@ -77,12 +78,14 @@ module Net
         backup = Backup.new(path: destination, bytes: contents.bytesize,
                             sha256: digest, collected_at: Time.now.utc, change: change,
                             previous_sha256: previous_digest)
+        # 内容未变也须核对权限与目录项身份；只在两者仍有效时保留原文件和 mtime。
         if change != :unchanged || previous.mode != 0o600 || !Storage::SafeFile.same_entry?(destination, previous)
           write_backup(backup, contents)
         end
         backup
       end
 
+      # 替换后失败仍交付已提交的备份回执，不能让调用方误判为没有产物。
       def write_backup(backup, contents)
         Storage::PrivateFile.write(backup.path, contents)
       rescue Storage::PrivateFile::WriteError => error

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

@@ -5,6 +5,7 @@ require_relative "../../engine/terminal_renderer"
 module Net
   module Connector
     class RunningConfig
+      # 采集策略决定业务步骤、视图提示符和响应校验；默认不改写配置正文。
       class Strategy
         # 保存策略所属设备，供提示符和厂商校验使用。
         def initialize(device) = @device = device
@@ -24,7 +25,7 @@ module Net
         def validate_response!(_command, _response, _execution) end
       end
 
-      # 使用终端行编辑规则渲染 H3C、Huawei 和 Radware 配置。
+      # 按终端行编辑规则还原配置画面，厂商子类只清理已识别的响应头。
       class Rendered < Strategy
         # 应用终端行编辑规则，还原设备最终显示的配置文本。
         def clean(text) = TerminalRenderer.render(text)

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

@@ -6,6 +6,7 @@ require_relative "running_config/strategy"
 
 module Net
   module Connector
+    # 单次运行配置采集的协调器；策略状态仅在当前会话租约与 Fiber 内可见。
     class RunningConfig
       # 设备只引入此能力；采集入口和策略作用域与采集流程一起维护。
       module Capability
@@ -40,6 +41,7 @@ module Net
           @config_strategy_scope = previous
         end
 
+        # 离线清理使用新策略；只有当前 Fiber 可复用正在采集的策略状态。
         def config_strategy
           scope = @config_strategy_scope
           scope && scope.first.equal?(Fiber.current) ? scope.last : RunningConfig.strategy(self)

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

@@ -15,6 +15,7 @@ module Net
       FORMATS = %i[cfg xml dat tgz unknown].freeze
       private_constant :KINDS, :FORMATS
 
+      # 校验目标、配置种类和核验状态，只有服务器核验成功才允许携带文件摘要与归档路径。
       def initialize(server:, path:, completed_at:, configuration_kind: :unknown, source_file: nil,
                      format: :unknown, requested_path: nil, verification: :device_reported, server_sha256: nil,
                      server_bytes: nil, local_path: nil, archive_path: nil)

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

@@ -5,8 +5,9 @@ require_relative "target"
 module Net
   module Connector
     class Tftp
+      # 厂商声明命名、交互与完成证据；公共层统一过滤精确回显和保留失败历史。
       class Strategy
-        # 厂商只声明格式差异，清单规划与设备直连共用同一命名规则。
+        # 声明默认配置扩展名，清单规划与设备直连共用同一命名规则。
         def self.file_extension = "cfg"
 
         # 不创建会话即可生成目标名，供批量计划检查文件覆盖风险。
@@ -15,10 +16,7 @@ module Net
         end
 
         # 保存 TFTP 厂商策略使用的设备对象。
-        def initialize(device)
-          @device = device
-          @responses = []
-        end
+        def initialize(device) = @device = device
 
         # 返回调用方指定的配置源文件。
         def resolve_source_file(value) = value
@@ -29,11 +27,21 @@ module Net
         # 返回目标中指定的远端文件名。
         def remote_path(target, _result) = target.path
 
+        # 原文、历史和终端画面共同保存失败证据；仅过滤精确输入回显与提示符。
+        def failure_outputs(result)
+          return enum_for(__method__, result) unless block_given?
+
+          result.steps.each do |step|
+            yield evidence_lines(step, step.output).join("\n")
+            yield evidence_lines(step, TerminalRenderer.render(step.output.gsub(/\r(?!\n)/, "\n"))).join("\n")
+            yield evidence_lines(step, TerminalRenderer.render(step.output)).join("\n")
+          end
+        end
+
         private
 
-        # 记录脚本的静态响应，避免文件名或 VRF 回显成为传输完成证据。
+        # 静态交互不进入业务输出，证据过滤从完成步骤读取原始声明。
         def interaction(pattern, response)
-          @responses << response.chomp
           Interaction.new(pattern, response, capture: false)
         end
 
@@ -45,8 +53,19 @@ module Net
           output = TerminalRenderer.render(step.output)
           prompt = TerminalRenderer.render(step.prompt.to_s)
           output = output.delete_suffix(prompt) unless prompt.empty?
-          echoes = [step.command.text, "#{prompt.strip}#{step.command.text}", *@responses]
-          output.each_line.map(&:strip).reject { |line| line.empty? || echoes.include?(line) }
+          evidence_lines(step, output)
+        end
+
+        # 移除精确命令、静态响应和提示符，保留回车重绘前后的设备消息。
+        def evidence_lines(step, output)
+          prompt = TerminalRenderer.render(step.prompt.to_s).strip
+          responses = step.command.interactions.filter_map { |reply| reply.static_response&.chomp }
+          echoes = [step.command.text, "#{prompt}#{step.command.text}", *responses]
+          # 原文中的每次回车分开核对，避免重绘回显误报，也保留被覆盖的诊断。
+          output.each_line.flat_map { |line| line.split(/\r(?!\n)/) }.map do |line|
+            # 样式不改变字符历史；光标移动和擦除不能拿来删掉原始失败消息。
+            line.gsub(/\e\[[0-9;:]*m/, "").strip
+          end.reject { |line| line.empty? || line == prompt || echoes.include?(line) }
         end
 
         # 只接受字节数非零、已发送量与总量相同的 curl 完成进度行。

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

@@ -5,6 +5,7 @@ require_relative "tftp/receipt"
 
 module Net
   module Connector
+    # 协调原生上传与设备证据核对；设备报告完成和服务器文件核验分别处理。
     class Tftp
       # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
       module Capability
@@ -66,6 +67,7 @@ module Net
 
       private
 
+      # 只接受厂商声明的固定元数据字段，沿用已确认的上传与路径回执。
       def build_receipt(strategy, target, source_file, explicit_source, receipt)
         metadata = strategy.receipt_metadata(target, source_file: source_file, explicit_source: explicit_source)
         unless metadata.is_a?(Hash) && (metadata.keys - %i[configuration_kind source_file format requested_path]).empty?
@@ -74,6 +76,7 @@ module Net
         receipt.with(**{ source_file: source_file, requested_path: target.path }.merge(metadata))
       end
 
+      # 实际目标必须重新校验；解析失败保留上传事实，但不推测远端路径。
       def remote_path(strategy, target, result, receipt)
         TftpTarget.validate_path!(strategy.remote_path(target, result))
       rescue StandardError => error
@@ -83,7 +86,7 @@ module Net
 
       # 失败证据优先；步骤中的明确完成行可在随后清理失败时证明设备已经报告上传。
       def confirm_transfer!(strategy, target, result)
-        if transfer_failed?(result)
+        if transfer_failed?(strategy, result)
           reject_transfer!(target, :transfer_failed, "device reported TFTP backup failure")
         end
         return if strategy.device_reported_complete?(result)
@@ -104,18 +107,16 @@ module Net
         raise failure, cause: nil
       end
 
-      # 识别设备回显中的传输失败信息。
-      def transfer_failed?(result)
-        result.steps.any? do |step|
+      # 已有厂商策略可提供证据枚举；其他策略复用公共证据过滤，不重跑交互回调。
+      def transfer_failed?(strategy, result)
+        evidence = strategy.respond_to?(:failure_outputs) ? strategy : Strategy.new(@device)
+        evidence.failure_outputs(result).any? do |output|
           # 文件名中的 failed.cfg、error-backup 等不属于诊断词；句末标点仍是词边界。
           pattern = %r{(?<![\w./-])
             (?:error|failed|failure|aborted|denied|timed\ out|timeout|not\ found|no\ such\ file|
                unable\ to|network\ is\ unreachable|can't\ open)
             (?![\w/-]|\.[\w])}ix
-          # 原始诊断不能被回车抹除，颜色控制符也不能掩盖失败词。
-          history = step.output.gsub(/\r(?!\n)/, "\n")
-          step.output.match?(pattern) || TerminalRenderer.render(history).match?(pattern) ||
-            TerminalRenderer.render(step.output).match?(pattern)
+          output.match?(pattern)
         end
       end
     end

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

@@ -24,9 +24,10 @@ module Net
         def persistence_confirmed?(result)
           !result.steps.empty? && result.steps.all? do |step|
             raw = step.output.delete_suffix(step.prompt.to_s)
+            history = raw.gsub(/\e\[[0-9;:]*m/, "").gsub(/\r(?!\n)/, "\n")
             rendered = TerminalRenderer.render(raw)
             failure = /\b(?:error|failed|failure|denied|cannot|unable|unsuccessful|aborted)\b/i
-            next false if raw.match?(failure) || rendered.match?(failure)
+            next false if history.match?(failure) || TerminalRenderer.render(history).match?(failure) || rendered.match?(failure)
 
             rendered.lines.any? { |line| line.strip.match?(persistence_pattern) }
           end

data/lib/net/connector/engine/core.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# 组合设备会话需要的引擎组件；厂商策略和清单客户端由各自入口按需加载。
 require_relative "configuration"
 require_relative "dialogue"
 require_relative "session"

data/lib/net/connector/engine/dialogue.rb

@@ -36,6 +36,9 @@ module Net
       # 根据当前提示计算响应文本或调用动态响应函数。
       def response(prompt) = @response.respond_to?(:call) ? @response.call(prompt) : @response
 
+      # 证据核对只能读取声明的静态响应，不能重新执行动态挑战回调。
+      def static_response = (@response if @response.is_a?(String))
+
       # 判断响应是否需要从日志和错误上下文中脱敏。
       def sensitive? = @sensitive
 
@@ -78,8 +81,8 @@ module Net
       def diagnostic(output)
         return if command_errors.empty?
 
-        # 先保留被回车覆写的失败，再识别颜色或退格处理后的可见诊断。
-        raw = output.gsub(/\r(?!\n)/, "\n")
+        # 样式不改变诊断历史；先拼回被颜色拆开的词，再保留重绘之前的失败。
+        raw = output.gsub(/\e\[[0-9;:]*m/, "").gsub(/\r(?!\n)/, "\n")
         diagnostic_line(raw) || (diagnostic_line(TerminalRenderer.render(output)) if output.match?(/[\e\b]/))
       end