net-connector 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83213050dfe70e3f81b22303e33a960c1d50880a6f8455f993568661a0464203
-  data.tar.gz: 4e1780c49d1fb686db3e0e955ae78384e1abb11583863b54680535aab6be15ef
+  metadata.gz: 1d0c8bdb5d1bb484683d8bc2b5da59f3c75f506479b4911776ca7b1ce9a82bc1
+  data.tar.gz: 8ee5fc708d89da6778af7aa5742775969e81cd1b1cea55ff9adc031aea2bb433
 SHA512:
-  metadata.gz: a0c786d8d8dc12880cdbd44bfd0fc6ed440b01b5245cb20a090428accdaf9a159f133c7f442eb8397feab65e5dbec9431bd6618197bce1819b229708fd832ee7
-  data.tar.gz: 21e51022f1e7161026776fc637dfbcfdc484f46edd250d61eadcc505b59731e00e4836dda483fcb27035f858fdc31c514dbd8a1b6678cf5df41b1fd482469766
+  metadata.gz: 04f5fa015e849927a3fda6b858f41b06bc352167e698962a62817d716b7267cd54feb5a0c219e2c48f976e200527ad72a95268a4cb40c70ef1b241f1965398b8
+  data.tar.gz: 21395d46e9fad39a3e8dd45ddfa512031576d4e89121d9d911ce3973e384becc51474d5035d2b6efdb9771f854a4a893976655409ab1012e5fcec9764f131bcf

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 未发布
 
+## 0.7.2 - 2026-10-06
+
+- 修复 IOS/NX-OS 配置清理误删 banner 内命令示例、进度文本及其后正文的问题，避免用截断配置覆盖旧备份。
+- 命令完成后即使日志或事件回调出错，失败结果仍保留已完成步骤，TFTP 错误仍携带设备确认的上传回执，不自动重放命令。
+- 修复固定文件名 TFTP 上传把前一设备残留文件误认为本次上传的问题，按服务器文件系统的时间核验，仍支持向预创建文件重新上传相同内容。
+- `log_file` 只接受普通文件，拒绝 FIFO 等特殊文件，避免连接前阻塞；其他输出流可通过 `logger` 注入。
+- 加快终端渲染、配置采集、debug 日志及大规模设备地址过滤，保留控制符处理、UTF-8 校验和输出限额。
+- 修复 ANSI 行首擦除后破坏中文等 UTF-8 文本的问题，非法字节仍按日志或严格解析策略处理。
+
+## 0.7.1 - 2026-10-05
+
+- 兼容 expect-pty 0.7 的 Session、expect 与 transcript 接口，保留旧版和输出限额语义。
+
+- 版本标签触发 RubyGems OIDC 可信发布，不再依赖静态 `RUBYGEMS_API_KEY` Secret；保留完整 CI 矩阵、原始产物发布、敏感信息扫描和 GitHub/RubyGems SHA256 回读校验。
+
 ## 0.7.0 - 2026-09-28
 
 - 统一内部参数、预算和声明校验的 `validate_*!` 命名；区分脚本发送前与响应后的预算检查，复用并发预检，简化状态计数并补充值对象复制边界测试。保持本轮增量重构的公开接口、错误及完成证据语义。

data/README.md

@@ -190,6 +190,8 @@ ruby examples/backup.rb --concurrency 10 --username backup-user --ask-password
 
 `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：

data/docs/RELEASING.md

@@ -56,16 +56,19 @@ ruby script/release.rb --artifact /path/to/verified/net-connector-X.Y.Z.gem
 
 ## GitHub Actions 发布
 
-仓库中配置 `RUBYGEMS_API_KEY` Actions Secret，并赋予发布此 gem 所需的权限。
-Runner 不继承本机 RubyGems 登录。GitHub 操作使用工作流自带的 token。
+Actions 使用 RubyGems Trusted Publishing，通过 GitHub OIDC 交换短期发布凭据，不再需要仓库的 `RUBYGEMS_API_KEY` Secret。
 
-提交和推送版本修改后，创建并推送对应的 `vX.Y.Z` 标签，在该标签上手动运行
-`Release` 工作流。只允许标签与 gem 版本一致且说明已归档的发布。
-工作流先复用完整 CI 矩阵，全部通过后下载 Ubuntu / Ruby 4.0 验证的同一个
-gem，再执行 `--artifact`；发布阶段不重新构建。
+首次在 [net-connector 的 Trusted publishers 页面](https://rubygems.org/gems/net-connector/trusted_publishers)
+创建 GitHub Actions 发布者：Repository owner 为 `gatework`，Repository name 为 `net-connector`，Workflow filename 为
+`release.yml`。可将 Environment 限定为 `release`；工作流始终使用该环境。需要审批时，在 GitHub 仓库 Settings → Environments 中配置。
 
-普通 push、PR 和标签推送只触发 CI。Release 工作流仅手动触发，避免本地
-发布创建标签时又自动开始第二次发布。
+提交和推送版本修改后，推送对应的 `vX.Y.Z` 标签会自动触发 Release。也可在 Actions → Release → Run workflow 选择同一版本标签恢复失败任务。
+只允许标签与 Gem 版本一致且说明已归档的发布。避免本地与 Actions 同时上传同一版本，优先使用标签工作流。
+
+工作流先复用完整 CI 矩阵，全部通过后下载 Ubuntu / Ruby 4.0 验证的同一个 Gem，配置 OIDC 凭据并执行 `--artifact`；
+发布阶段不重新构建，源码、历史、包的敏感信息扫描及 SHA256 回读继续生效。
+
+没有匹配的可信发布者时，OIDC 交换会失败；先补齐 RubyGems 配置再恢复原包发布。本地脚本仍使用既有 Gem 登录和 MFA。
 
 ## 失败后重试
 

data/docs/architecture.md

@@ -54,6 +54,8 @@
 
 采集命令匹配当前会话的完整提示符行，不以末尾单个 `#`、`>` 或 `]` 判断完成。PAN-OS 切换视图时保留已认证的设备身份。缺少最终提示符会使采集失败，旧备份保持不变；只有提示符或命令回显的响应属于 `:incomplete_configuration`，不是成功的空配置。PAN-OS 在 `show` 前后都检查候选配置差异。
 
+IOS/NX-OS 清理器处理单条配置命令的响应，不把正文当成多命令会话记录。banner 内的命令、进度及完成提示均属于配置内容；易变时间注释仅从首个配置语句之前的响应头删除。终端渲染器成段处理普通文本，控制序列仍逐字节解释；光标覆盖、行尾空白、UTF-8 校验和逐行字节限额保持一致。
+
 `LocalBackup` 在采集前取得 `BackupLock`，持有到摘要比较、替换与结果构造结束。锁名由 realpath 父目录与归一化文件名决定；Unicode NFC、大小写折叠后的摘要同时覆盖尚未创建的目标。区分大小写的文件系统也保守合并这些锁，目标名称本身不变。锁文件用 NOFOLLOW/0600 打开，再验证普通文件、所有者、单硬链接和 inode；释放仅关闭 FD，不删除锁文件。默认 `flock(LOCK_EX | LOCK_NB)`，可选等待共用有限单调期限，超时均为 `BackupBusy`。
 
 Fleet 在规范目标校验、凭据解析及连接器构造之前加同一把锁，再向下层备份授权一次同进程、同 Fiber 的借用。借用在采集前消费，回调递归备份不能重复使用；没有全局路径缓存。路径锁在外、会话锁在内，`Base#backup` 拒绝已有会话操作中的嵌套调用。独立进程必须采用同一 flock 协议；调用方保护目录及祖先，锁不约束不合作的写入者。
@@ -136,10 +138,10 @@ Diagnostic 只保存固定词表中的码、类型、阶段和受控产物状态
 任务 ensure 和 Session 超时仍保留；任意用户回调应自行保证返回，不能承诺非合作
 回调的硬期限。清单获取 deadline 只约束 Client.devices，不覆盖整个 Fleet 任务。
 
-NC-07C（TFTP 服务端验证适配器）同为可选扩展，本轮 **deferred**：尚无调用方存储、
-时间/版本关联和目标隔离协议，当前业务执行不生成 server_verified。只检查文件
-存在或只把固定名上传串行化均不足以实现验证，因此 PAN-OS 同名冲突拒绝规则不变。
-后续适配器必须关联设备、实际目标、时间/版本、摘要及本次任务；验证失败也不能重传。
+NC-07C 的本地服务器目录核验已接入 `TftpVerification`；单设备 API 仍只报告设备回执。
+Fleet 可把回执与本地普通文件的时间、稳定性、摘要及目录项身份关联，生成 server_verified。
+启用历史归档并提供服务器目录时，PAN-OS 固定名可在路径锁内顺序上传、核验和归档；
+其他场景仍拒绝同批固定名碰撞。验证失败不能重传设备命令。
 
 本地租约不阻止其他设备会话/管理员写入；flock 不隔离未合作的进程，也不能使祖先目录
 或网络文件系统成为可信事务。目录同步不等于断电恢复认证，TFTP 的同批检查不解决外部
@@ -260,7 +262,7 @@ TFTP 策略的类方法 `filename(host, label: nil)` 是必需的无 I/O 命名
 
 TFTP 策略必须实现 `validate_options!(target, source_file:, vrf:)`、`receipt_metadata(target, source_file:, explicit_source:)`、`resolve_source_file`、`default_path`、`remote_path`、`script` 和 `device_reported_complete?`。可继承 `Tftp::Strategy` 的公共默认值；重写上传流程时必须一并审视继承的参数约束和来源声明。预检不得访问设备，元数据只允许 configuration_kind/source_file/format/requested_path。接口缺失在 Profile 构造时失败，不再动态回退到另一套行为。
 
-服务器核验适配器尚未接入；TFTP API 不会自动生成 server_verified 结果。PAN-OS 固定名仍按现有计划拒绝同批碰撞，串行运行不改变该限制，也不保证跨进程或跨批次隔离。
+单设备 TFTP API 返回 device_reported；Fleet 的本地目录核验可提升为 server_verified。`TftpArchive` 在持有目标路径锁后保存旧文件，并记录其 dev、ino、size、mtime、ctime。上传时间取同一服务器目录内临时文件的 mtime，随即清理临时文件，避免文件系统时钟精度低于 Time.now 时误拒绝新上传。核验要求非空文件的新鲜时间及稳定读取；已有文件还必须发生状态变化。重新写入相同内容可以通过，未变化的旧文件即使 mtime 在未来也不能冒充新上传。预创建的服务器目标文件在上传前保持可用，成功归档后按原规则清理；未合作的外部写入者仍不受路径锁约束。
 
 验收入口是 `script/ci`，也可用 `bundle exec rake release:check`。它检查源码、可用 Git 历史和 gem 内容中的敏感数据，执行 Ruby 与工作流 lint、完整测试，并在隔离 gem 目录及最小 Bundler 应用中安装。真实本地 PTY 烟测覆盖厂商加载、配置采集、打包模板和 CLI，不接触网络设备。初次下载依赖和工具需要联网，详见[验证文档](VERIFICATION.md)及[发布文档](RELEASING.md)。
 
@@ -367,12 +369,16 @@ RunningConfig 的两处受控 `send` 保留，用于私有策略绑定与 protec
 
 错误归一化通过 `Error#with_diagnostics` 保留内置错误的业务回执，并新建异常的原生状态，避免复制原 cause 或调用栈。自定义错误子类使用脱敏后的参数重新构造，不能复制可能参与消息呈现的原始私有字段。会话租约退出时若日志收尾失败，已返回的 Result 仍保留步骤、配置和原业务错误；仅在原操作成功时附加日志错误。
 
+单条命令的完整响应在输出日志和完成事件之前保存；即使这些日志处理失败，Session 仍在脱敏作用域退出前把响应交给 Execution，保留已完成步骤与输出预算。TFTP 可从失败结果的完成步骤构造设备回执，再报告日志错误；不会据此重放命令。
+
 每次连接有独立 session_id，每次发送命令分配 command_id；operation、phase、source、line 贯穿命令开始、回显、完成和错误。command_complete 在 info 级别记录 duration_ms、response_bytes，status: response_received 只表示响应已完成。operation_complete 在脚本准备、执行、回调及最终处理之后记录成功或失败，不代替文件持久性或 TFTP 服务端核验。
 
 `device.log_event(name, level: :info, **fields)` 是唯一自定义事件入口。会话身份和命令上下文由引擎提供，不能从 fields 覆盖。事件名和字段值经终端渲染与脱敏后冻结；非法字段名丢弃，复杂对象和非有限浮点数隐藏，不调用任意对象的 inspect/to_s。敏感范围内自定义事件整体隐藏，包括事件名和任意字段，防止配置钩子输出未登记的秘密。
 
 注入的 logger 由调用方持有；连接器不修改级别、formatter、progname，也不关闭它。每次写入同时检查配置与 logger 当前级别。消息对象支持 to_s/inspect 和安全 to_h，应用可自行输出 JSON。自有文本日志使用毫秒时间及逐行事件；raw 文件只写经过敏感保护的字节。上下文退出前先收尾渲染与脱敏缓冲，避免上一命令尾部被标成下一条命令。
 
+`log_file` 使用 NOFOLLOW/NONBLOCK 打开，再对同一 FD 检查普通文件类型，随后才修改权限或写入。FIFO、设备文件和目录不能用作日志文件；应用拥有的输出流通过 `logger` 接入。日志打开先于登录，不能依赖登录超时为文件打开提供期限。
+
 ## 公开契约与 Rails 接入
 
 应用代码优先使用 `Net::Connector.open/build`、`Base` 的公开设备方法、`Command`、`Script`、结果对象，以及 `Netdisco::Fleet`。厂商扩展使用 `Profile` DSL 和文档中列出的策略接口；`Profile::Builder`、`Session` 的状态字段、工作线程调度及解析辅助方法属于内部实现。扩展直接加载当前设备模块或厂商目录下的类。项目仍处于 0.x，公开契约的变更会在更新记录中说明。

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

@@ -61,14 +61,17 @@ module Net
         prompt = @prompt_resolver&.call(command)
         # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
         validate_send_budget!(command) if @prompt_resolver
-        response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do
+        response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do |received|
           # 必须在 Session 恢复命令词表前读取；最终处理只能继承敏感性，不长期保留秘密。
           @sensitive ||= @session.redactor.sensitive?
+          if received
+            @last_executed_command = command
+            @output_bytes += received.raw.bytesize
+            # 完成事实先进入结果；日志失败不能抹去已执行命令，也不能触发重放。
+            yield received if block_given?
+          end
         end
-        @last_executed_command = command
-        @output_bytes += response.raw.bytesize
         # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
-        yield response if block_given?
         validate_response_budget!(command)
         response
       end

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

@@ -224,8 +224,11 @@ module Net
       # 以私有权限打开设备日志文件。
       def open_file(path)
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW, 0o600)
+        file = File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW | File::NONBLOCK, 0o600)
         begin
+          # FIFO 的打开不受登录截止时间约束；验证同一个 FD 后才能修改权限或写入。
+          raise ArgumentError, "session log must be a regular file" unless file.stat.file?
+
           file.chmod(0o600)
           file.binmode
           file.write("\n") if file.size.positive? && @configuration.log_format == :text

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

@@ -152,12 +152,15 @@ module Net
 
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
       def execute_command(command, timeout:, prompt: nil)
+        response = nil
         redactor.with_scope(reuse: true) do
           protect_command(command)
-          @log.with_command_context(command) { execute_command_with_logging(command, timeout: timeout, prompt: prompt) }
+          @log.with_command_context(command) do
+            execute_command_with_logging(command, timeout: timeout, prompt: prompt) { |received| response = received }
+          end
         ensure
-          # 失败的敏感探测也可能被钩子捕获后继续；离开作用域前始终通知执行器。
-          yield if block_given?
+          # 日志失败也要交付已完成响应；失败的敏感探测同样必须在恢复词表前通知执行器。
+          yield response if block_given?
         end
       end
 
@@ -254,13 +257,13 @@ module Net
         end
       end
 
-      def execute_command_with_logging(command, timeout:, prompt:)
+      def execute_command_with_logging(command, timeout:, prompt:, &)
         started = Expect.monotonic
         @log.log_event("command_start")
         sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
         private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
         @log.log_event("device_output", level: :debug) if @log.debug? && !private_output
-        response = exchange_command(command, timeout: timeout, prompt: prompt)
+        response = exchange_command(command, timeout: timeout, prompt: prompt, &)
         @log.log_response_output(response.raw) unless private_output
         details = { duration_ms: elapsed_ms(started), response_bytes: response.raw.bytesize }
         @log.log_event("command_complete", status: "response_received", **details)
@@ -306,6 +309,8 @@ module Net
             raise build_error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
           end
 
+          # 恢复敏感命令的日志接线也可能失败；在离开暂停范围前保存完成事实。
+          yield response
           response
         end
         if command.sensitive? || redactor.output_sensitive? || interactions.any?(&:sensitive?)

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

@@ -7,8 +7,17 @@ module Net
   module Connector
     # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
     class TerminalRenderer
+      DEFAULT_MAX_LINE_BYTES = 32 * 1024 * 1024
+      private_constant :DEFAULT_MAX_LINE_BYTES
+
       # 将字节流完整渲染为字符串，供测试和一次性转换使用。
       def self.render(input, strict_utf8: false)
+        # 日志元数据通常是无控制符的 ASCII 单行；直接返回独立副本，仍受默认行限额约束。
+        if [true, false].include?(strict_utf8) && input.instance_of?(String) && input.bytesize <= DEFAULT_MAX_LINE_BYTES &&
+           input.ascii_only? && input.match?(/\A[\x20-\x7f]*\z/n)
+          return input.b.rstrip
+        end
+
         output = StringIO.new("".b)
         renderer = new(output, strict_utf8: strict_utf8)
         renderer.write(input)
@@ -17,7 +26,7 @@ module Net
       end
 
       # 初始化当前行、光标和转义序列状态。
-      def initialize(target, max_line_bytes: 32 * 1024 * 1024, strict_utf8: false)
+      def initialize(target, max_line_bytes: DEFAULT_MAX_LINE_BYTES, strict_utf8: false)
         raise ArgumentError, "target must respond to write" unless target.respond_to?(:write)
         unless max_line_bytes.is_a?(Integer) && max_line_bytes.positive?
           raise ArgumentError, "max_line_bytes must be positive"
@@ -33,10 +42,23 @@ module Net
         @strict_utf8 = strict_utf8
       end
 
-      # 逐字节消费终端输出，并返回输入字节数。
+      # 普通文本按片段写入；只有控制序列逐字节解释，避免大配置和逐行日志的 Ruby 调用开销。
       def write(input)
         bytes = input.to_s.b
-        bytes.each_byte { |byte| consume(byte) }
+        offset = 0
+        while offset < bytes.bytesize
+          if @escape_state
+            consume_escape(bytes.getbyte(offset))
+            offset += 1
+            next
+          end
+
+          control = bytes.index(/[\x00-\x08\x0a-\x1f]/n, offset)
+          ending = control || bytes.bytesize
+          write_text(bytes.byteslice(offset, ending - offset)) if ending > offset
+          consume_control(bytes.getbyte(control)) if control
+          offset = ending + 1
+        end
         bytes.bytesize
       end
 
@@ -54,16 +76,13 @@ module Net
       private
 
       # 处理普通控制字符、换行、回车和转义序列起始符。
-      def consume(byte)
-        return consume_escape(byte) if @escape_state
-
+      def consume_control(byte)
         case byte
         when 7 then nil
         when 8 then @cursor = [@cursor - 1, 0].max
         when 10 then emit_line(newline: true)
         when 13 then @cursor = 0
         when 27 then @escape_state = :escape
-        else write_byte(byte) if byte == 9 || byte >= 32
         end
       end
 
@@ -124,20 +143,23 @@ module Net
         case mode
         when 0 then @line = @line.byteslice(0, @cursor)
         when 1
-          @line = (" " * [@cursor + 1, @line.bytesize].min) + @line.byteslice((@cursor + 1)..).to_s
+          @line = (" ".b * [@cursor + 1, @line.bytesize].min) + @line.byteslice((@cursor + 1)..).to_s
         when 2
           @line.clear
           @cursor = 0
         end
       end
 
-      # 在光标位置写入字节，并限制单行缓冲大小。
-      def write_byte(byte)
-        raise OutputLimitExceeded, "terminal line exceeded max_line_bytes" if @cursor >= @max_line_bytes
+      # 覆盖光标后的同等字节数并保留余下后缀；超限时仍保留已经消费的有效前缀。
+      def write_text(bytes)
+        available = @max_line_bytes - @cursor
+        length = bytes.bytesize > available ? available : bytes.bytesize
+        raise OutputLimitExceeded, "terminal line exceeded max_line_bytes" unless length.positive?
 
         @line << (" " * (@cursor - @line.bytesize)) if @cursor > @line.bytesize
-        (@cursor < @line.bytesize) ? @line.setbyte(@cursor, byte) : @line << byte
-        @cursor += 1
+        @line[@cursor, length] = length == bytes.bytesize ? bytes : bytes.byteslice(0, length)
+        @cursor += length
+        raise OutputLimitExceeded, "terminal line exceeded max_line_bytes" if length < bytes.bytesize
       end
 
       # 删除行尾空白，写出当前行并重置光标。

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

@@ -41,14 +41,29 @@ module Net
           @channel = if @channel_factory
                        @channel_factory.call
                      else
-                       Expect.new(raw_pty: true, reset_timeout_on_read: false, buffer_limit: nil,
+                       if defined?(Expect::Session)
+                         Expect::Session.new(buffer_limit: nil, write_timeout: configuration.write_timeout)
+                       else
+                         Expect.new(raw_pty: true, reset_timeout_on_read: false, buffer_limit: nil,
                                   preserve_buffer: false, log_stdout: false, log_listeners: false,
                                   debug_level: 0, write_timeout: configuration.write_timeout)
+                       end
                      end
           # Profile 使用宽、高；PTY 使用行数、列数。
           @channel.slave.winsize = @terminal_size.reverse if @terminal_size
-          @channel.log_output = method(:write_log_output)
-          @channel.spawn(*argv)
+          if @channel.respond_to?(:transcript=)
+            writer = Object.new
+            callback = method(:write_log_output)
+            writer.define_singleton_method(:write) do |bytes|
+              callback.call(bytes)
+              bytes.bytesize
+            end
+            @channel.transcript = writer
+            @channel.spawn(*argv, raw: true)
+          else
+            @channel.log_output = method(:write_log_output)
+            @channel.spawn(*argv)
+          end
           self
         rescue Exception # rubocop:disable Lint/RescueException -- A half-open PTY must be released on interrupts.
           begin
@@ -61,7 +76,8 @@ module Net
 
         # 从信道读取下一事件，并把字符串字段转换为字节字符串。
         def read(patterns, timeout:)
-          result = @channel.expect_result(*patterns, STREAM, timeout: timeout)
+          reader = @channel.respond_to?(:expect_result) ? :expect_result : :expect
+          result = @channel.public_send(reader, *patterns, STREAM, timeout: timeout)
           Event.new(index: result.number && (result.number - 1), before: result.before.to_s.b,
                     match: result.match.to_s.b, error: result.error)
         end

data/lib/net/connector/netdisco/rules.rb

@@ -10,8 +10,8 @@ module Net
         # 校验并保存清单过滤和厂商映射规则。
         def initialize(include_hosts: [], exclude_hosts: [], include_vendors: [], vendor_overrides: {},
                        host_overrides: {}, mappings: [])
-          @include_hosts = string_list(include_hosts)
-          @exclude_hosts = string_list(exclude_hosts)
+          @include_hosts = host_index(include_hosts)
+          @exclude_hosts = host_index(exclude_hosts)
           @include_vendors = vendor_list(include_vendors)
           @vendor_overrides = vendor_mapping(vendor_overrides)
           @host_overrides = host_mapping(host_overrides)
@@ -126,8 +126,8 @@ module Net
 
         # 判断设备是否通过地址和厂商过滤。
         def selected?(host, vendor)
-          return false if @exclude_hosts.include?(host)
-          return false if !@include_hosts.empty? && !@include_hosts.include?(host)
+          return false if @exclude_hosts.key?(host)
+          return false if !@include_hosts.empty? && !@include_hosts.key?(host)
           return false if !@include_vendors.empty? && !@include_vendors.include?(vendor)
 
           true
@@ -140,15 +140,15 @@ module Net
           wireless ? :h3c_wireless : :h3c
         end
 
-        # 校验并标准化管理地址列表。
-        def string_list(values)
+        # 外部仍接受地址数组；内部仅做成员匹配，建索引避免逐台扫描整个清单。
+        def host_index(values)
           raise ArgumentError, "host lists must be Arrays" unless values.is_a?(Array)
 
-          values.map do |value|
+          values.to_h do |value|
             raise ArgumentError, "host list entries must be Strings" unless value.is_a?(String) && !value.empty?
             raise ArgumentError, "host list entries must be IP addresses" if value.include?("/")
 
-            IPAddr.new(value).to_s.freeze
+            [IPAddr.new(value).to_s.freeze, true]
           rescue IPAddr::Error
             raise ArgumentError, "host list entries must be IP addresses"
           end.freeze

data/lib/net/connector/netdisco/tftp_archive.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "tempfile"
 require_relative "../storage/backup_lock"
 require_relative "../storage/private_file"
 require_relative "../storage/safe_file"
@@ -52,14 +53,15 @@ module Net
           remote_filename = upload_filename(device)
           return yield remote_filename unless @server_root
 
-          # The lock spans the upload and copy, including a fixed-name PAN-OS upload.
+          # 固定文件名的基线与上传时间都在锁内采集；排队期间前一设备的文件不属于本次上传。
           Storage::BackupLock.synchronize(File.join(@server_root, remote_filename), host: device.host, timeout: 240) do
-            archive_existing_file(device, remote_filename)
+            previous = archive_existing_file(device, remote_filename)
+            upload_started_at = server_timestamp
             outcome = yield remote_filename
             receipt = outcome.backup
             return outcome unless receipt.is_a?(TftpReceipt) && receipt.path
 
-            verified = @verifier.verify_outcome(outcome.with(started_at: started_at))
+            verified = @verifier.verify_outcome(outcome.with(started_at: started_at), started_at: upload_started_at, previous: previous)
             return outcome.success? ? archive_failure(outcome) : outcome unless verified.backup.verification == :server_verified
 
             archive_uploaded_file(verified)
@@ -71,16 +73,22 @@ module Net
 
         private
 
+        # 文件系统的 mtime 可能落后于 Time.now；用同一服务器目录的时间建立上传边界。
+        def server_timestamp
+          Tempfile.create(".net-connector-upload-", @server_root) { |file| file.stat.mtime }
+        end
+
         # 首次采用固定远端名时，先保留服务器上原有文件，再允许设备覆盖。
         def archive_existing_file(device, remote_filename)
           existing_path = File.join(@server_root, remote_filename)
-          bytes = Storage::SafeFile.open(existing_path, missing: true) { |file, _stat| file.read }
+          bytes, previous = Storage::SafeFile.open(existing_path, missing: true) { |file, stat| [file.read, stat] }
           return unless bytes
 
           previous_directory = File.join(@server_archive_directory, "previous")
           FileUtils.mkdir_p(previous_directory, mode: 0o700)
           archive_path = File.join(previous_directory, archive_filename(device, File.extname(remote_filename)))
           Storage::PrivateFile.write(archive_path, bytes)
+          previous
         rescue StandardError
           raise ArchiveFailed.new(host: device.host), cause: nil
         end

data/lib/net/connector/netdisco/tftp_verification.rb

@@ -23,22 +23,23 @@ module Net
           report.with(outcomes: outcomes.freeze)
         end
 
-        def verify_outcome(outcome)
-          return outcome unless @root && outcome.started_at && outcome.backup.is_a?(TftpReceipt) && outcome.backup.path
+        def verify_outcome(outcome, started_at: outcome.started_at, previous: nil)
+          return outcome unless @root && started_at && outcome.backup.is_a?(TftpReceipt) && outcome.backup.path
 
-          verify(outcome, outcome.backup)
+          verify(outcome, outcome.backup, started_at: started_at, previous: previous)
         end
 
         private
 
-        def verify(outcome, receipt)
+        def verify(outcome, receipt, started_at: outcome.started_at, previous: nil)
           path = File.join(@root, receipt.path)
           parent = File.realpath(File.dirname(path))
           return outcome unless parent == @root || parent.start_with?(@root + File::SEPARATOR)
 
           size = nil
           fingerprint = Storage::SafeFile.open(path, missing: true) do |file, stat|
-            next unless stat.size.positive? && stat.mtime >= outcome.started_at
+            next unless stat.size.positive? && stat.mtime >= started_at
+            next if previous && same_file_state?(previous, stat)
 
             size = stat.size
             value = Storage::SafeFile.fingerprint_io(path, file, stat)
@@ -52,6 +53,12 @@ module Net
           # 核验失败不抹去设备上传回执；要求服务器证据的策略仍判为未完成。
           outcome
         end
+
+        # 内容相同的重新上传仍有效；但未变化的旧文件不能仅凭未来 mtime 冒充新上传。
+        def same_file_state?(before, after)
+          [before.dev, before.ino, before.size, before.mtime, before.ctime] ==
+            [after.dev, after.ino, after.size, after.mtime, after.ctime]
+        end
       end
     end
   end

data/lib/net/connector/vendor/cisco_ios/running_config.rb

@@ -6,13 +6,14 @@ module Net
   module Connector
     module CiscoIos
       class RunningConfig < Net::Connector::RunningConfig::Rendered
-        # 去掉终端长度设置、保存命令回显和易变化的配置时间注释。
+        # 每条命令已有独立响应；正文中的命令示例属于配置，不能按会话回显删除。
+        # 只清理首个配置语句之前的时间注释，避免改写 banner 等多行文本。
         def clean(text)
           config = super
-          config.gsub!(/^[^\n]*#\s*terminal\s+length\s+0\s*\n/i, "")
-          config.sub!(/^[^\n]*#\s*copy\s+run(?:ning-config)?\s+(?:start|startup-config)\s*\n.*\z/im, "")
-          config.gsub!(/^!.*(?:Last\s+configuration\s+change|NVRAM\s+config).*\n/i, "")
-          config
+          config.sub(/\A(?:[ \t]*\n|![^\n]*\n|(?:\S+[#])?show[ \t]+running-config[^\n]*\n|
+                        Building[ \t]+configuration[^\n]*\n|Current[ \t]+configuration[^\n]*\n)*/ix) do |header|
+            header.gsub(/^!.*(?:Last\s+configuration\s+change|NVRAM\s+config).*\n/i, "")
+          end
         end
       end
     end

data/lib/net/connector/vendor/cisco_nxos/running_config.rb

@@ -5,18 +5,8 @@ require_relative "../cisco_ios/running_config"
 module Net
   module Connector
     module CiscoNxos
+      # 分页交互由引擎处理；响应正文中的进度或命令示例必须原样保留。
       class RunningConfig < CiscoIos::RunningConfig
-        # 先清除 NX-OS 分页与进度回显，再复用 IOS 的配置清理规则。
-        def clean(text)
-          without_pager = text.to_s.gsub(
-            /[ \t]*(?:\x1b\[[0-9;]*[A-Za-z])*--More--
-              (?:\x1b\[[0-9;]*[A-Za-z])*(?:[\r\x00\x08 ]|\x1b\[[0-9;]*[A-Za-z])*/ix, ""
-          )
-          config = super(without_pager)
-          config.sub!(/\A.*?^(?=[^\n]*#\s*show\s+running-config\s*$)/im, "")
-          config.gsub(/^[ \t]*(?:\[[# ]*\]|\])[ \t]*\d+%[ \t]*\n?/i, "")
-                .gsub(/^[ \t]*Copy\s+complete\b[^\n]*\n?/i, "")
-        end
       end
     end
   end

data/lib/net/connector/version.rb

@@ -2,6 +2,6 @@
 
 module Net
   module Connector
-    VERSION = "0.7.0"
+    VERSION = "0.7.2"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - net-connector contributors
 bindir: exe
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expect-pty