net-connector 0.7.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98616a3bf5a59d99a6b9060e1d87d4574ecc7802c8d465d074d1e0b45cda7d6e
-  data.tar.gz: 0232eac8ff46db4326e28910f8a17dc64f571866ab567505161a660baa681238
+  metadata.gz: c0d4b8cc4601018ae7e2f2838e59c57720cff0ca3bfda47cbbfb423c67f4620b
+  data.tar.gz: 6b8527cee1080118ff83574a80a9d71cedb01d47427b7e5c8d35621e2f206187
 SHA512:
-  metadata.gz: 525318622f7c1530155b49f1c8f8f196f52537aaf363f89e368e33072a68bf170a9203db49ec6e99f84100d45dbb63713a58e8c4f449b69ddeef5cad16386bdd
-  data.tar.gz: 7d6eb1adf97ce404c9c63839aee2ea76e406f4edbdd69059e9ea9f7db0983a7676522d06a69a7449a9d4c959c79a389650b94d9380a5941182d13d37444c411b
+  metadata.gz: c8070ed62134a1eac35ed652183fc608d276e12a35aef4bfefda3d3cb39c31d354386fe8ebdb49dec2cf9721f41caca047e671927b8f456e97de72ac0acfc897
+  data.tar.gz: b04fd3c47d8d09c68961db1c3eb320bca4b76c94f501b9fe107410b13169b747413cbb2c8fdc4d60dbe88f59f963319c4f0313bcb95571c7bb915eb76870e64f

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # 更新记录
 
-## 未发布
+## 0.8.0 - 2026-10-09
+
+- 破坏性变更：命令入口改为 `bin/net-backup`，gem 安装后使用 `net-backup`；移除 `TftpHistory`、`TftpArchive#path_for/#capture` 和 `ResultStore::Text` 兼容接口，调用方需更新路径与接口名称。
+- 引擎按职责拆出 `engine/redactor.rb` 与 `engine/response_reader.rb`；Netdisco 模块显式声明依赖，可独立加载并调用，聚合入口不再维护隐式加载顺序。
+- TFTP 归档与结果存储使用 `TftpArchive#upload_filename/#upload_and_archive` 与 `ResultStore::Json`。
+- 脚本日志收尾失败时保留已完成配置和原业务错误，完成事件不重复发送；登录、命令、TFTP 失败诊断及日志清理不再覆盖主错误或用户中断。
+- 进度终端写入或刷新失败后停止显示，批次继续保存设备结果、事件和报告；显示故障只记录一次安全回调诊断，末尾显示首次失败时补写诊断并更新最终退出状态。
+- PAN-OS 多行 set 配置增量跟踪引号状态，逻辑命令闭合后才进行完整语法校验，避免反复解析不断增长的证书等文本。
+- 每厂商有限采样使用 `Enumerable#min_by(n)`，减少大清单的全量排序开销，保留采样、冲突选择和清单输出顺序。
 
 ## 0.7.3 - 2026-10-07
 

data/README.md

@@ -262,7 +262,9 @@ end
 exit 1 unless batch.success?
 ```
 
-命令行程序 `net-connector-backup` 的 YAML 文件只允许非敏感设置；Netdisco 和设备凭据留在环境变量中。常用环境变量优先于 YAML，复杂参数只通过 YAML 或 CLI 设置。批量示例也支持 `NC_CONFIG`，可从 [完整配置示例](examples/backup.yml) 开始。只有传入 `--config FILE` 或设置 `NC_CONFIG` 时才加载文件：
+gem 安装后的命令为 `net-backup`；源码入口为 `bin/net-backup`，可在项目目录运行 `bundle exec bin/net-backup --help`。原命令 `net-connector-backup` 已改名。
+
+命令行程序 `net-backup` 的 YAML 文件只允许非敏感设置；Netdisco 和设备凭据留在环境变量中。常用环境变量优先于 YAML，复杂参数只通过 YAML 或 CLI 设置。批量示例也支持 `NC_CONFIG`，可从 [完整配置示例](examples/backup.yml) 开始。只有传入 `--config FILE` 或设置 `NC_CONFIG` 时才加载文件：
 
 ```yaml
 netdisco:
@@ -291,12 +293,12 @@ tftp:
 ```
 
 ```sh
-net-connector-backup --config config.yml --show-config
-net-connector-backup --config config.yml --plan --host 192.0.2.7
-net-connector-backup --config config.yml --host 192.0.2.7
-net-connector-backup --config config.yml --tftp --plan
-net-connector-backup --config config.yml --tftp --all
-net-connector-backup --config config.yml --export 192.0.2.7 --output ./exports/device.cfg
+net-backup --config config.yml --show-config
+net-backup --config config.yml --plan --host 192.0.2.7
+net-backup --config config.yml --host 192.0.2.7
+net-backup --config config.yml --tftp --plan
+net-backup --config config.yml --tftp --all
+net-backup --config config.yml --export 192.0.2.7 --output ./exports/device.cfg
 ```
 
 ### PostgreSQL 联机查询
@@ -326,10 +328,10 @@ export NETDISCO_DB_PASS='replace-me'
 export NETDISCO_DB_SSLMODE=verify-full
 export NETDISCO_DB_SSLROOTCERT=/etc/net-connector/database-ca.crt
 
-net-connector-backup --config examples/inventory_sql.yml --show-config
-net-connector-backup --config examples/inventory_sql.yml --plan
+net-backup --config examples/inventory_sql.yml --show-config
+net-backup --config examples/inventory_sql.yml --plan
 # 覆盖查询参数；实际备份仍需设置 NC_DEVICE_* 凭据。
-net-connector-backup --config examples/inventory_sql.yml --plan --query-params '["Cisco"]'
+net-backup --config examples/inventory_sql.yml --plan --query-params '["Cisco"]'
 ```
 
 SQL、参数和来源也可分别通过 `--query SQL`、`--query-params JSON`、`--source postgres` 覆盖 YAML，不再从环境变量读取。SQL 和参数属于可公开配置，会出现在 `--show-config` 中；数据库密码只放在连接环境变量中。连接信息不进入策略快照、计划、报告或 `inspect`。已有 Fleet 每次重新查询时读取最新连接凭据；传入已有 `plan:` 执行时不会重新查询。
@@ -344,7 +346,7 @@ SQL、参数和来源也可分别通过 `--query SQL`、`--query-params JSON`、
 
 CLI 的计划与批次摘要使用 JSON。默认 `--success-policy strict` 使用严格规则：非空清单且全部成功、回调及报告正常时为 `0`；空清单或有跳过、部分成功、失败时为 `1`；清单或配置错误为 `2`。`--host` 未在清单中找到也返回 `2`。由于其他清单记录会标记为过滤，默认单主机备份成功时批次退出码仍可能是 `1`；应查看 JSON 中的 `succeeded`、`skipped` 和逐台 `status`。
 
-显式使用 `--success-policy selected` 后，CLI 按上述 selected 规则决定退出码，保留严格的 `status: incomplete` 与跳过计数，另列 `policy_success`。例如 `net-connector-backup --config config.yml --host 192.0.2.7 --success-policy selected`。成功策略由本次 CLI/API 参数指定，不改变已批准的清单选择，也不触发重试。
+显式使用 `--success-policy selected` 后，CLI 按上述 selected 规则决定退出码，保留严格的 `status: incomplete` 与跳过计数，另列 `policy_success`。例如 `net-backup --config config.yml --host 192.0.2.7 --success-policy selected`。成功策略由本次 CLI/API 参数指定，不改变已批准的清单选择，也不触发重试。
 
 本地批量示例和 TFTP 批量示例默认全量；显式 `--sample N`、`NC_SAMPLE_PER_VENDOR` 或 YAML `backup.limit_per_vendor` 才限制每厂商数量（示例允许 1 至 5）。优先级为命令行抽样 > 环境变量 > YAML。并发默认 4，可用 `NC_CONCURRENCY` 覆盖。两类示例在备份目录下创建唯一批次目录。TFTP 批量示例在可访问服务器目录时使用 hostname-ip 远端文件名并逐批归档；无法访问服务器目录时使用带批次标识的远端文件名，避免覆盖旧文件；上传完成与服务器文件验证是不同状态。
 

data/docs/architecture.md

@@ -5,6 +5,8 @@
 | 层次 | 职责 | 位置 |
 | --- | --- | --- |
 | 会话引擎 | 登录、传输、命令、脚本及资源所有权 | `engine/` |
+| 对话协议与响应读取 | 交互规则和响应值独立于有状态的读取、截止时间与输出预算 | `engine/dialogue.rb`、`engine/response_reader.rb` |
+| 错误与脱敏 | 错误类型和安全诊断；秘密作用域及 Expect 脱敏适配独立实现 | `engine/errors.rb`、`engine/redactor.rb` |
 | 日志 | 事件上下文与生命周期；安全事件、格式和字节流分别实现 | `engine/log.rb`、`engine/log/` |
 | 设备入口 | 能力组合、会话代理、通用脚本钩子 | `device/base.rb` |
 | 设备档案 | 不可变规则与策略接口校验；Builder 负责声明 DSL | `device/profile.rb`、`device/profile/` |
@@ -17,6 +19,7 @@
 | 解析 | TextFSM 模板选择、记录转换及异常映射 | `textfsm.rb`、`templates/` |
 | 终端文本 | 严格 UTF-8 字节验证和终端渲染 | `engine/terminal_text.rb`、`engine/terminal_renderer.rb` |
 | 清单与批量编排 | 清单预算、策略快照、计划校验、工作线程和报告 | `netdisco/` |
+| 命令行入口 | 转交给 CLI，参数处理与业务流程由库负责 | `bin/net-backup` |
 
 `Base` 引入 `RunningConfig::Capability`、`LocalBackup::Capability`、`Tftp::Capability`、`Topology::Capability`、`TextFSM::Capability` 及 `SaveConfig`。能力入口与实现共置，Base 不再重复业务包装。配置采集的临时策略绑定也由 RunningConfig 管理；备份与拓扑通过 `device.running_config` 复用同一流程。
 
@@ -54,6 +57,8 @@
 
 采集命令匹配当前会话的完整提示符行，不以末尾单个 `#`、`>` 或 `]` 判断完成。PAN-OS 切换视图时保留已认证的设备身份。缺少最终提示符会使采集失败，旧备份保持不变；只有提示符或命令回显的响应属于 `:incomplete_configuration`，不是成功的空配置。PAN-OS 在 `show` 前后都检查候选配置差异。
 
+PAN-OS 的 set 文本逐行增量跟踪单引号、双引号和转义状态，整条逻辑命令闭合后才由 Shellwords 校验；未闭合的多行内容仍拒绝。证书等长值不再每追加一行就重新解析完整前缀，校验仍在原会话租约内完成。
+
 IOS/NX-OS 清理器处理单条配置命令的响应，不把正文当成多命令会话记录。banner 内的命令、进度及完成提示均属于配置内容；易变时间注释仅从首个配置语句之前的响应头删除。终端渲染器成段处理普通文本，控制序列仍逐字节解释；光标覆盖、行尾空白、UTF-8 校验和逐行字节限额保持一致。
 
 `LocalBackup` 在采集前取得 `BackupLock`，持有到摘要比较、替换与结果构造结束。锁名由 realpath 父目录与归一化文件名决定；Unicode NFC、大小写折叠后的摘要同时覆盖尚未创建的目标。区分大小写的文件系统也保守合并这些锁，目标名称本身不变。锁文件用 NOFOLLOW/0600 打开，再验证普通文件、所有者、单硬链接和 inode；释放仅关闭 FD，不删除锁文件。默认 `flock(LOCK_EX | LOCK_NB)`，可选等待共用有限单调期限，超时均为 `BackupBusy`。
@@ -288,7 +293,11 @@ TFTP 策略必须实现 `validate_options!(target, source_file:, vrf:)`、`recei
 
 ## 加载入口与厂商策略
 
-`require "net/connector"` 加载设备 API 和引擎，厂商通过 autoload 按需加载。TextFSM 能力模块可预先组合，但外部 `textfsm` gem 只在实际解析时加载。仅需会话引擎时使用 `require "net/connector/engine/core"`；离线文件操作使用 `net/connector/storage`，不加载厂商。
+`require "net/connector"` 加载设备 API 和引擎，厂商由 `vendor_class` 按需加载。TextFSM 能力模块可预先组合，但外部 `textfsm` gem 只在实际解析时加载。仅需会话引擎时使用 `require "net/connector/engine/core"`；离线文件操作使用 `net/connector/storage`，不加载厂商。
+
+`engine/dialogue` 只定义 Interaction、Dialogue 与 Response；读取循环位于 `engine/response_reader`。`engine/errors` 不加载脱敏运行时，`engine/redactor` 负责秘密作用域。Session 明确加载并持有读取器与脱敏器。
+
+Netdisco 的 Settings、Planner、Fleet、CLI 等文件各自声明实际依赖，单独 require 后即可调用，不依赖 `netdisco.rb` 的预设加载顺序。总入口只组合 CLI 和 BackupRun；Batch 通过 autoload 创建 Report，避免两者循环加载。私有 InventoryBudget 由 Client 加载。Progress 的终端显示、Fleet 的设备执行、Report 的结果解释和 Storage 的文件持久化保持独立职责。
 
 公共策略位于 `RunningConfig::Strategy` / `Rendered`、`Tftp::Strategy` / `FileUpload`、`Topology::Strategy` / `ImmediateStrategy`。厂商文件直接依赖公共策略，由 Profile 绑定；没有反向加载和厂商转发别名。
 
@@ -311,6 +320,10 @@ RunningConfig 的两处受控 `send` 保留，用于私有策略绑定与 protec
 
 | 原名称或入口 | 当前入口 |
 | --- | --- |
+| `exe/net-connector-backup` | `bin/net-backup`；安装后命令为 `net-backup` |
+| TFTP 策略 `interaction` | private `build_interaction`，构造交互规则；`device.interact` 仍表示立即进入人工终端交互 |
+| `TftpHistory`、`TftpArchive#path_for/#capture` | `TftpArchive#upload_filename/#upload_and_archive` |
+| `ResultStore::Text` | `ResultStore::Json`，与 `Report::Text` 的文本报告职责区分 |
 | `Base#login_dialogues` / `confirmation_dialogues` | protected `login_interactions` / `confirmation_interactions`；子类覆盖同步改名，继续支持 `super` |
 | `Fleet#backup_one` / `tftp_backup_one` / `run_one` | private `backup_device` / `tftp_backup_device` / `run_device`；公开批次入口不变 |
 | `engine`、`engine/base`、`engine/profile` | `net/connector`；底层分别为 `engine/core`、`device/base`、`device/profile` |
@@ -371,6 +384,8 @@ RunningConfig 的两处受控 `send` 保留，用于私有策略绑定与 protec
 
 操作后处理无论抛出异常还是返回失败 Result，都在敏感作用域退出前归一化错误，再记录完成事件；Result 的已完成步骤及配置内容保持原样。最终处理继承实际执行的命令及交互敏感性，包括准备钩子、替换命令和追加查询；只累计标记，不长期保留秘密，也不影响后续普通命令的日志。
 
+业务执行与完成事件的异常范围分开：完成事件只尝试一次，观察者失败不能触发第二次相同通知。已有登录、命令或业务错误优先于失败日志的错误；脚本最终处理已生成的 Result.config 与 steps 不因日志收尾丢失。日志上下文刷新和传输接线恢复仍执行清理，但保留正在传播的主错误及 Interrupt。TFTP 的失败证据同样先决定错误码，再尝试记录失败事件。
+
 错误归一化通过 `Error#with_diagnostics` 保留内置错误的业务回执，并新建异常的原生状态，避免复制原 cause 或调用栈。自定义错误子类使用脱敏后的参数重新构造，不能复制可能参与消息呈现的原始私有字段。会话租约退出时若日志收尾失败，已返回的 Result 仍保留步骤、配置和原业务错误；仅在原操作成功时附加日志错误。
 
 单条命令的完整响应在输出日志和完成事件之前保存；即使这些日志处理失败，Session 仍在脱敏作用域退出前把响应交给 Execution，保留已完成步骤与输出预算。TFTP 可从失败结果的完成步骤构造设备回执，再报告日志错误；不会据此重放命令。
@@ -381,6 +396,8 @@ RunningConfig 的两处受控 `send` 保留，用于私有策略绑定与 protec
 
 注入的 logger 由调用方持有；连接器不修改级别、formatter、progname，也不关闭它。每次写入同时检查配置与 logger 当前级别。消息对象支持 to_s/inspect 和安全 to_h，应用可自行输出 JSON。自有文本日志使用毫秒时间及逐行事件；raw 文件只写经过敏感保护的字节。上下文退出前先收尾渲染与脱敏缓冲，避免上一命令尾部被标成下一条命令。
 
+人类进度显示由 Progress 单独管理：终端 write/flush 的 I/O 故障会停用后续显示，并只保留固定词表内的错误类型，不携带原始异常。心跳照常回收，设备任务、events.jsonl 与报告持久化继续进行；BackupRun 将显示故障合并为一次批次 callback_errors。若首次故障发生在报告保存后的最终显示阶段，仅补写一次报告诊断，最终 JSON 与退出码采用更新后的策略结果；已有报告错误保持优先，不重放设备备份或事件。
+
 `log_file` 使用 NOFOLLOW/NONBLOCK 打开，再对同一 FD 检查普通文件类型，随后才修改权限或写入。FIFO、设备文件和目录不能用作日志文件；应用拥有的输出流通过 `logger` 接入。日志打开先于登录，不能依赖登录超时为文件打开提供期限。
 
 ## 公开契约与 Rails 接入

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

@@ -249,17 +249,23 @@ module Net
 
         execution = build_execution(operation: operation, prompt: prompt, after_command: after_command, privilege: privilege)
         output_sensitive = script.any?(&:output_sensitive?)
+        result = nil
         @session.perform(:script) do
           @session.log_script(operation: operation, steps: execution.steps) do
             @session.with_sensitive_output(output_sensitive) { before_batch(execution) }
             result = execution.execute_script(script, &on_step)
             sensitive_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
             @session.with_sensitive_output(sensitive_result) do
-              finalize_script_result(result, finalize)
+              result = finalize_script_result(result, finalize)
             end
           end
         end
       rescue Error => error
+        # 脚本完成后的日志收尾仍可能失败，已经生成的配置与主错误保持权威。
+        if result.is_a?(Result)
+          return Result.new(steps: result.steps, config: result.config, error: result.error || error)
+        end
+
         Result.new(steps: execution ? execution.steps : [], error: error)
       end
 

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

@@ -84,18 +84,24 @@ module Net
       # 失败证据优先；步骤中的明确完成行可在随后清理失败时证明设备已经报告上传。
       def confirm_transfer!(strategy, target, result)
         if transfer_failed?(result)
-          @device.log_event("tftp_backup", level: :error, status: "transfer_failed", phase: :tftp_backup,
-                                code: :transfer_failed, server: target.host)
-          raise DeviceError.new("device reported TFTP backup failure",
-                                code: :transfer_failed, host: @device.host, phase: :tftp_backup)
+          reject_transfer!(target, :transfer_failed, "device reported TFTP backup failure")
         end
         return if strategy.device_reported_complete?(result)
 
         result.value! if result.failure?
-        @device.log_event("tftp_backup", level: :error, status: "transfer_unconfirmed", phase: :tftp_backup,
-                              code: :transfer_unconfirmed, server: target.host)
-        raise DeviceError.new("device did not confirm TFTP backup completion",
-                              code: :transfer_unconfirmed, host: @device.host, phase: :tftp_backup)
+        reject_transfer!(target, :transfer_unconfirmed, "device did not confirm TFTP backup completion")
+      end
+
+      # 设备证据先决定业务失败；事件记录失败不能把明确的上传状态替换为日志故障。
+      def reject_transfer!(target, code, message)
+        failure = DeviceError.new(message, code: code, host: @device.host, phase: :tftp_backup)
+        begin
+          @device.log_event("tftp_backup", level: :error, status: code.to_s, phase: :tftp_backup,
+                            code: code, server: target.host)
+        rescue Error
+          # 主错误仍在下方抛出，不重试事件或设备命令。
+        end
+        raise failure, cause: nil
       end
 
       # 识别设备回显中的传输失败信息。

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "expect/pty"
 require_relative "dialogue"
 
 module Net

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

@@ -2,7 +2,6 @@
 
 require_relative "errors"
 require_relative "terminal_renderer"
-require "expect/pty"
 
 module Net
   module Connector
@@ -113,136 +112,5 @@ module Net
       # 返回响应大小摘要，不展开原始内容。
       def inspect = "#<#{self.class} bytes=#{raw.bytesize}>"
     end
-
-    # 在传输层上执行有界对话；收到字节或分页标记不会重置截止时间。
-    class ResponseReader
-      # 保存会话引用，以便读取器使用传输、配置和脱敏上下文。
-      def initialize(session)
-        @session = session
-      end
-
-      # 读取到结束提示、失败模式或超时，并处理交互响应和输出上限。
-      def read(prompt:, interactions:, phase:, timeout: nil, deadline: nil, command: nil, failures: {})
-        deadline ||= Expect.monotonic + timeout
-        patterns = [*failures.keys, *interactions.map(&:pattern), prompt]
-        raw = []
-        output = []
-        counts = Hash.new(0)
-        bytes = 0
-        loop do
-          event = read_event(patterns, deadline)
-          raw << event.before unless event.before.empty?
-          output << event.before unless event.before.empty?
-          bytes += event.before.bytesize + event.match.bytesize
-          validate_event!(event, bytes, raw, phase, command)
-
-          if event.index == patterns.size
-            raw << event.match
-            output << event.match
-          elsif event.index == patterns.size - 1
-            return finish_response(event.match, raw, output, phase, command)
-          elsif event.index < failures.size
-            raise build_connection_error(failures.values.fetch(event.index), phase, command), cause: nil
-          else
-            reply = interactions.fetch(event.index - failures.size)
-            raw << event.match
-            output << event.match if reply.capture?
-            respond(reply, event.match, counts, deadline, phase, command)
-          end
-          next if Expect.monotonic < deadline
-
-          raise build_read_error(nil, phase, command, raw.join), cause: nil
-        end
-      end
-
-      private
-
-      # 分页和流式输出只消耗剩余时间，不为下一次读取重新计时。
-      def read_event(patterns, deadline)
-        @session.transport.read(patterns, timeout: [deadline - Expect.monotonic, 0].max)
-      end
-
-      # 连接失败模式携带稳定错误码，供连接级恢复规则选择处理方式。
-      def build_connection_error(failure, phase, command)
-        klass, code = failure
-        @session.build_error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
-      end
-
-      # 先限制原始字节数，再处理传输失败，避免错误输出绕过总量限制。
-      def validate_event!(event, bytes, raw, phase, command)
-        if bytes > @session.configuration.max_output_bytes
-          raise @session.build_error(OutputLimitExceeded, "device output exceeded max_output_bytes",
-                                     phase: phase, command: command, output: (raw + [event.match]).join), cause: nil
-        end
-        raise build_read_error(event, phase, command, raw.join), cause: nil unless event.matched?
-      end
-
-      # 完整提示符必须消费字节；交互标记可从业务输出排除，但原始响应始终保留。
-      def finish_response(prompt, raw, output, phase, command)
-        if prompt.empty?
-          raise @session.build_error(PromptError, "prompt pattern did not consume any output",
-                                     phase: phase, command: command, output: raw.join), cause: nil
-        end
-
-        raw << prompt
-        output << prompt
-        raw_text = raw.join
-        Response.new(raw: raw_text, output: (output == raw) ? raw_text : output.join, prompt: prompt)
-      end
-
-      # 重复提示和缺失应答必须在写入前失败；所有应答共用读取操作的截止时间。
-      def respond(reply, prompt, counts, deadline, phase, command)
-        counts[reply] += 1
-        if prompt.empty? || (reply.limit && counts[reply] > reply.limit)
-          raise build_interaction_error("response rejected or repeated", phase, command), cause: nil
-        end
-
-        value = interaction_response(reply, prompt, phase, command)
-        raise build_interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
-
-        @session.redactor.remember(value.chomp) if reply.sensitive?
-        @session.write(value, deadline: deadline, phase: phase, command: command)
-      end
-
-      # 动态口令尚未返回时无法加入词表，须在敏感范围内先归一化回调异常。
-      # 成功后由调用方登记响应，临时敏感标记不会影响后续普通命令的诊断。
-      def interaction_response(reply, prompt, phase, command)
-        return reply.response(prompt) unless reply.sensitive?
-
-        @session.redactor.with_scope(reuse: true) do
-          @session.redactor.sensitive!
-          reply.response(prompt)
-        rescue => error
-          raise @session.normalize_error(error, phase: phase, command: command), cause: nil
-        end
-      end
-
-      # 将交互拒绝或响应缺失转换为认证或脚本错误。
-      def build_interaction_error(message, phase, command)
-        authenticating = %i[login enable].include?(phase)
-        klass = authenticating ? AuthenticationError : ScriptError
-        label = authenticating ? "authentication" : "command interaction"
-        @session.build_error(klass, "#{label} #{message}", phase: phase, command: command)
-      end
-
-      # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
-      def build_read_error(event, phase, command, output)
-        if event&.error.is_a?(Exception)
-          return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
-                                      underlying: event.error, output: output)
-        end
-        klass = if event&.error == :eof
-                  ConnectionClosed
-                elsif command&.prompt
-                  PromptError
-                elsif %i[login enable].include?(phase)
-                  LoginTimeout
-                else
-                  CommandTimeout
-                end
-        @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
-                             command: command, output: output)
-      end
-    end
   end
 end

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "expect/redactor"
 require_relative "error_metadata"
 
 module Net
@@ -89,96 +88,5 @@ module Net
       # 返回底层异常类型摘要。
       def inspect = "#<#{self.class} type=#{type}>"
     end
-
-    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
-    class Redactor
-      MASK = "[REDACTED]".b.freeze
-
-      # 保存初始凭据，并建立第一版脱敏词表。
-      def initialize(*secrets)
-        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
-          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
-        end
-
-        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
-        reset
-      end
-
-      # 重置动态词表，同时保留配置中的固定凭据。
-      def reset
-        @secrets = []
-        @patterns = nil
-        @scoped = false
-        @sensitive = false
-        @output_sensitive = false
-        @configured.each { |secret| remember(secret) }
-      end
-
-      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
-      def with_scope(reuse: false)
-        return yield if reuse && @scoped
-
-        previous = @secrets
-        previous_patterns = @patterns
-        previous_scoped = @scoped
-        previous_sensitive = @sensitive
-        previous_output_sensitive = @output_sensitive
-        @secrets = previous.dup
-        @scoped = true
-        begin
-          yield
-        ensure
-          @secrets = previous
-          @patterns = previous_patterns
-          @scoped = previous_scoped
-          @sensitive = previous_sensitive
-          @output_sensitive = previous_output_sensitive
-        end
-      end
-
-      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
-      def sensitive! = @sensitive = true
-
-      # 判断当前脱敏范围是否包含敏感交互。
-      def sensitive? = @sensitive
-
-      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
-      def output_sensitive!
-        @output_sensitive = true
-        sensitive!
-      end
-
-      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
-      def output_sensitive? = @output_sensitive
-
-      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
-      def remember(secret)
-        return if secret.nil? || secret.empty?
-
-        bytes = secret.b
-        return if @secrets.include?(bytes)
-
-        @secrets << bytes.freeze
-        @patterns = nil
-      end
-
-      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
-      def call(text)
-        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
-      end
-
-      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
-      def stream
-        Expect::Redactor.new(patterns, replacement: MASK)
-      end
-
-      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
-      def patterns
-        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
-      end
-
-      # 返回脱敏器类型摘要。
-      def inspect = "#<#{self.class}>"
-    end
   end
 end

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

@@ -49,9 +49,14 @@ module Net
         finish_output
         @context = @context.merge(fields).freeze
         yield
+      rescue Exception # rubocop:disable Lint/RescueException -- Preserve only failures propagating from this scope, including interrupts.
+        failed = true
+        raise
       ensure
         begin
           finish_output
+        rescue Error
+          raise unless failed
         ensure
           @context = previous
         end
@@ -98,6 +103,9 @@ module Net
                   code: ErrorMetadata.code(failure.code),
                   phase: ErrorMetadata.phase(failure.phase) || ErrorMetadata.phase(phase),
                   message: failure.message)
+      rescue Error
+        # 原始失败已由调用者保留；诊断通道故障不能替换登录、命令或业务错误。
+        nil
       end
 
       # 用户钩子可能把未登记的配置片段放进事件名、字段名或值；敏感范围统一隐藏。
@@ -163,8 +171,16 @@ module Net
         finish_output
         @transport.log_output = nil if @transport
         yield
+      rescue Exception # rubocop:disable Lint/RescueException -- Restore attachment without replacing this scope's failure or interruption.
+        failed = true
+        raise
       ensure
-        @transport.log_output = self if @transport && @writer && @attached
+        begin
+          @transport.log_output = self if @transport && @writer && @attached
+        rescue StandardError
+          # 恢复接线仍须尝试，但不能盖掉设备失败或用户中断。
+          raise unless failed
+        end
       end
 
       # 断开回显记录并关闭日志资源。

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "expect/redactor"
+
+module Net
+  module Connector
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
+    class Redactor
+      MASK = "[REDACTED]".b.freeze
+
+      # 保存初始凭据，并建立第一版脱敏词表。
+      def initialize(*secrets)
+        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
+          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
+        end
+
+        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
+        reset
+      end
+
+      # 重置动态词表，同时保留配置中的固定凭据。
+      def reset
+        @secrets = []
+        @patterns = nil
+        @scoped = false
+        @sensitive = false
+        @output_sensitive = false
+        @configured.each { |secret| remember(secret) }
+      end
+
+      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
+      def with_scope(reuse: false)
+        return yield if reuse && @scoped
+
+        previous = @secrets
+        previous_patterns = @patterns
+        previous_scoped = @scoped
+        previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
+        @secrets = previous.dup
+        @scoped = true
+        begin
+          yield
+        ensure
+          @secrets = previous
+          @patterns = previous_patterns
+          @scoped = previous_scoped
+          @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
+        end
+      end
+
+      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
+      def sensitive! = @sensitive = true
+
+      # 判断当前脱敏范围是否包含敏感交互。
+      def sensitive? = @sensitive
+
+      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
+      def output_sensitive!
+        @output_sensitive = true
+        sensitive!
+      end
+
+      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
+      def output_sensitive? = @output_sensitive
+
+      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
+      def remember(secret)
+        return if secret.nil? || secret.empty?
+
+        bytes = secret.b
+        return if @secrets.include?(bytes)
+
+        @secrets << bytes.freeze
+        @patterns = nil
+      end
+
+      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
+      def call(text)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
+      end
+
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
+      end
+
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
+      end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
+    end
+  end
+end