net-connector 0.5.0 → 0.7.0

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

@@ -13,7 +13,7 @@ module Net
 
         # 组装清单客户端、规则、凭据与结果存储。
         def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
-                       result_store: ResultStore::Text.new)
+                       result_store: ResultStore::Json.new)
           @settings = settings
           @client = client
           @rules = rules
@@ -35,46 +35,53 @@ module Net
         end
 
         # 规划 TFTP 配置备份的设备集合。
-        def plan_tftp_backup(limit_per_vendor: 5)
-          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp))
+        def plan_tftp_backup(limit_per_vendor: 5, allow_fixed_name_reuse: false)
+          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp),
+                     allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
         def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
                        limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
-                       success_policy: :strict)
-          reporting = Report.validate_policy!(success_policy)
-          policy = @settings.snapshot(mode: :backup)
-          directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
-          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
+                       success_policy: :strict, filename_style: :ip)
+          raise ArgumentError, "filename style must be ip or hostname_ip" unless %i[ip hostname_ip].include?(filename_style)
+
+          Report.validate_policy!(success_policy)
+          raise ArgumentError, "verified policy requires TFTP mode" if success_policy == :verified
+          settings_snapshot = @settings.snapshot(mode: :backup)
+          directory = settings_snapshot.backup_directory if directory.equal?(DEFAULT_SETTING)
+          concurrency = settings_snapshot.concurrency if concurrency.equal?(DEFAULT_SETTING)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
-          Worker.new(concurrency: concurrency)
+          Worker.validate_concurrency!(concurrency)
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
           validate_callback!(on_change, :on_change)
 
-          plan ||= build_plan(:backup, limit_per_vendor, policy)
+          plan ||= build_plan(:backup, limit_per_vendor, settings_snapshot)
           validate_plan!(plan, :backup)
           callbacks = [on_result]
-          callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
+          callbacks << ->(outcome) { on_change.call(outcome) if outcome.backup.is_a?(Backup) && outcome.backup.changed? } if on_change
           target_directory = File.expand_path(directory)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
-                    output_directory: target_directory, policy: policy, reporting: reporting,
+                    output_directory: target_directory, settings_snapshot: settings_snapshot, success_policy: success_policy,
                     on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory, policy)
+            backup_device(device, target_directory, log_directory, settings_snapshot, filename_style: filename_style)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
         def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: DEFAULT_SETTING, success_policy: :strict)
-          reporting = Report.validate_policy!(success_policy)
-          policy = @settings.snapshot(mode: :tftp)
-          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
-          report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
-          Worker.new(concurrency: concurrency)
+                            report_directory: DEFAULT_SETTING, success_policy: :strict, verification_root: nil,
+                            preserve_history: false)
+          Report.validate_policy!(success_policy)
+          raise ArgumentError, "verified policy requires a local TFTP directory" if success_policy == :verified && !verification_root
+          verification = TftpVerification.new(root: verification_root)
+          settings_snapshot = @settings.snapshot(mode: :tftp)
+          concurrency = settings_snapshot.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          report_directory = settings_snapshot.backup_directory if report_directory.equal?(DEFAULT_SETTING)
+          Worker.validate_concurrency!(concurrency)
           server = TftpTarget.new(host: server, path: "preflight.cfg").host
           raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
           source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
@@ -84,40 +91,53 @@ module Net
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
 
-          plan ||= build_plan(:tftp, limit_per_vendor, policy)
+          plan ||= build_plan(:tftp, limit_per_vendor, settings_snapshot,
+                              allow_fixed_name_reuse: preserve_history && !verification_root.nil?)
           validate_plan!(plan, :tftp)
+          if plan.allow_fixed_name_reuse && (!preserve_history || !verification_root)
+            raise ArgumentError, "fixed-name TFTP uploads require local history archival"
+          end
+          archive = TftpArchive.new(directory: report_directory, root: verification_root) if preserve_history
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    policy: policy, reporting: reporting, on_start: on_start, on_result: on_result) do |device, log_directory|
-            tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
+                    settings_snapshot: settings_snapshot, success_policy: success_policy, on_start: on_start, on_result: on_result,
+                    verification: preserve_history ? nil : verification) do |device, log_directory|
+            if archive
+              archive.upload_and_archive(device, started_at: Time.now.utc) do |remote_filename|
+                tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: remote_filename)
+              end
+            else
+              tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot)
+            end
           end
         end
 
         private
 
         # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
-        def inventory(policy)
-          rows = (@client || @settings.client(policy: policy)).devices
+        def inventory(settings_snapshot)
+          rows = (@client || @settings.client(policy: settings_snapshot)).devices
           raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
 
-          rules = @rules || policy.rules
+          rules = @rules || settings_snapshot.rules
           devices = rows.map { |row| Device.from_row(row, rules: rules) }
           duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
           devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
         end
 
-        def build_plan(mode, limit, policy)
+        def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false)
           Planner.validate_limit!(limit)
-          Planner.new(inventory(policy)).call(mode: mode, limit_per_vendor: limit)
+          Planner.new(inventory(settings_snapshot)).call(mode: mode, limit_per_vendor: limit,
+                                               allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, policy:, reporting:, on_start:, on_result:, output_directory: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, settings_snapshot:, success_policy:, on_start:, on_result:, output_directory: nil, verification: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
           started = monotonic
           outcomes = plan.outcomes.dup
           FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
-          log_directory = policy.log_directory
+          log_directory = settings_snapshot.log_directory
           FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
           callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
                                        on_error: ->(device, error) { build_outcome(device, :failed, error: error) }) do |device|
@@ -126,8 +146,9 @@ module Net
           batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
-          batch = Report.new(batch, policy: reporting, duration_ms: ((monotonic - started) * 1000).round)
-          save_report(batch, directory: report_directory)
+          report = Report.new(batch, policy: success_policy, duration_ms: ((monotonic - started) * 1000).round, log_directory: log_directory)
+          report = verification.call(report) if verification
+          save_report(report, directory: report_directory)
         end
 
         def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -138,16 +159,16 @@ module Net
         end
 
         # 保存批量报告，记录写入失败而不覆盖设备结果。
-        def save_report(batch, directory:)
-          return batch unless @result_store
+        def save_report(report, directory:)
+          return report unless @result_store
 
-          batch.with(report_location: @result_store.write(batch, directory: directory))
+          report.with(report_location: @result_store.write(report, directory: directory))
         rescue Storage::PrivateFile::WriteError => error
           # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
           location = error.receipt.path if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
-          batch.with_report_error(error, location: location)
+          report.with_report_error(error, location: location)
         rescue StandardError => error
-          batch.with_report_error(error)
+          report.with_report_error(error)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -165,30 +186,30 @@ module Net
         end
 
         # 执行单台设备的 TFTP 导出。
-        def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
-          run_one(device, log_directory, policy, success_status: :reported_uploaded,
-                  close_error_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
+        def tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: device.tftp_filename)
+          run_device(device, log_directory, settings_snapshot, success_status: :reported_uploaded,
+                     partial_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
-            transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
+            transfer_settings = { host: server, path: path, source_file: source_file }
             transfer_settings[:vrf] = vrfs.fetch(device.vendor) if vrfs.key?(device.vendor)
             connector.tftp_backup(**transfer_settings)
           end
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory, policy)
-          destination = File.join(directory, device.backup_filename)
+        def backup_device(device, directory, log_directory, settings_snapshot, filename_style: :ip)
+          destination = File.join(directory, device.backup_filename(style: filename_style))
           Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
             Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
-            run_one(device, log_directory, policy, success_status: :backed_up,
-                    close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+            run_device(device, log_directory, settings_snapshot, success_status: :backed_up,
+                       partial_status: :saved_with_error, backup_class: Backup) do |connector|
               path_lock.with_delegated_lock { connector.backup(path: destination) }
             end
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
+        def run_device(device, log_directory, settings_snapshot, success_status:, partial_status:, backup_class:)
           connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
           return build_outcome(device, :missing_credentials) if connection_settings.nil?
           unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
@@ -197,7 +218,7 @@ module Net
             raise ArgumentError, "credential resolver must return settings with username and without host"
           end
 
-          connection_settings = policy.connection_options(device.vendor).merge(connection_settings)
+          connection_settings = settings_snapshot.connection_options(device.vendor).merge(connection_settings)
           log_name = device.host.tr(":", "_")
           if log_directory
             connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
@@ -206,7 +227,7 @@ module Net
           backup, failure = perform_one(connector, backup_class) { yield connector }
           return build_outcome(device, success_status, backup: backup) unless failure
 
-          build_outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+          build_outcome(device, backup ? partial_status : :failed, backup: backup, error: failure)
         rescue StandardError => error
           build_outcome(device, :failed, error: error)
         end

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

@@ -23,21 +23,21 @@ module Net
         # 在追加正文前计数；不能靠 Content-Length 或 JSON 解析后的大小限制内存。
         def consume_bytes(size, response_bytes:)
           remaining
-          check_limit!(:max_response_bytes, response_bytes + size)
-          check_limit!(:max_inventory_bytes, @bytes + size)
+          validate_limit!(:max_response_bytes, response_bytes + size)
+          validate_limit!(:max_inventory_bytes, @bytes + size)
           @bytes += size
         end
 
         # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
         def consume_devices(size)
           remaining
-          check_limit!(:max_devices, @devices + size)
+          validate_limit!(:max_devices, @devices + size)
           @devices += size
         end
 
         private
 
-        def check_limit!(name, value)
+        def validate_limit!(name, value)
           return if value <= @options.fetch(name)
 
           raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil

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

@@ -4,15 +4,18 @@ module Net
   module Connector
     module Netdisco
       # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
-      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes, :allow_fixed_name_reuse) do
         # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
-        def initialize(mode:, inventory:, ready:, outcomes:)
+        def initialize(mode:, inventory:, ready:, outcomes:, allow_fixed_name_reuse: false)
           unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
             raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
           end
 
           tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
-          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+          raise ArgumentError, "allow_fixed_name_reuse must be boolean" unless [true, false].include?(allow_fixed_name_reuse)
+
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze,
+                allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 按清单顺序返回选中的设备。
@@ -26,7 +29,7 @@ module Net
           end
 
           selected_indices = {}
-          filenames = {}
+          selected_filenames = {}
           previous_index = -1
           ready.each do |task|
             unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
@@ -39,9 +42,11 @@ module Net
             end
             if mode == :tftp
               filename = device.tftp_filename
-              raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename" if filenames.key?(filename)
+              if selected_filenames.key?(filename) && !(allow_fixed_name_reuse && device.vendor == :palo_alto)
+                raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename"
+              end
 
-              filenames[filename] = true
+              selected_filenames[filename] = true
             end
             selected_indices[index] = true
             previous_index = index
@@ -51,7 +56,7 @@ module Net
             result = outcomes[index]
             next if selected_indices[index] && result.nil?
 
-            unless !selected_indices[index] && valid_skipped_outcome?(result, device, filenames)
+            unless !selected_indices[index] && valid_skipped_outcome?(result, device, selected_filenames)
               raise ArgumentError, "plan outcome does not match its inventory slot"
             end
           end
@@ -61,7 +66,7 @@ module Net
         private
 
         # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。
-        def valid_skipped_outcome?(result, device, filenames)
+        def valid_skipped_outcome?(result, device, selected_filenames)
           return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
                               result.error_code.nil? && result.error_type.nil? &&
                               result.started_at.nil? && result.finished_at.nil?
@@ -69,7 +74,7 @@ module Net
           return result.status == device.issue unless device.ready?
 
           result.status == :sample_limit ||
-            (mode == :tftp && result.status == :remote_filename_collision && filenames.key?(device.tftp_filename))
+            (mode == :tftp && result.status == :remote_filename_collision && selected_filenames.key?(device.tftp_filename))
         end
       end
     end

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

@@ -13,21 +13,23 @@ module Net
         end
 
         # 生成本地或 TFTP 备份计划，明确记录每台未执行设备的原因。
-        def call(mode:, limit_per_vendor:)
+        def call(mode:, limit_per_vendor:, allow_fixed_name_reuse: false)
           self.class.validate_limit!(limit_per_vendor)
-          candidates = @inventory.each_with_index.select { |device, _index| device.ready? }
-          selected = if limit_per_vendor
-                       candidates.group_by { |device, _index| device.vendor }.values.flat_map do |entries|
-                         entries.sort_by { |device, _index| device.host }.first(limit_per_vendor)
-                       end
-                     else
-                       candidates
-                     end
-          selected_indices = selected.to_h { |_device, index| [index, true] }
-          filenames = {}
+          ready_tasks = @inventory.each_with_index.filter_map do |device, index|
+            [index, device] if device.ready?
+          end
+          selected_tasks = if limit_per_vendor
+                             ready_tasks.group_by { |_index, device| device.vendor }.values.flat_map do |tasks|
+                               tasks.sort_by { |_index, device| device.host }.first(limit_per_vendor)
+                             end
+                           else
+                             ready_tasks
+                           end
+          selected_indices = selected_tasks.to_h { |index, _device| [index, true] }
+          first_index_by_filename = {}
           if mode == :tftp
             # 先按采样顺序保留每个目标的首台设备，再按清单顺序输出结果。
-            selected.each { |device, index| filenames[device.tftp_filename] ||= index }
+            selected_tasks.each { |index, device| first_index_by_filename[device.tftp_filename] ||= index }
           end
           outcomes = Array.new(@inventory.size)
           ready = @inventory.each_with_index.filter_map do |device, index|
@@ -37,14 +39,16 @@ module Net
             elsif !selected_indices.key?(index)
               outcomes[index] = skipped(device, :sample_limit)
               nil
-            elsif mode == :tftp && filenames.fetch(device.tftp_filename) != index
+            elsif mode == :tftp && first_index_by_filename.fetch(device.tftp_filename) != index &&
+                  !(allow_fixed_name_reuse && device.vendor == :palo_alto)
               outcomes[index] = skipped(device, :remote_filename_collision)
               nil
             else
               [index, device].freeze
             end
           end
-          Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze)
+          Plan.new(mode: mode, inventory: @inventory, ready: ready.freeze, outcomes: outcomes.freeze,
+                   allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 限制单厂商采样数，空值表示选择所有就绪设备。

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

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Net
+  module Connector
+    module Netdisco
+      # 共享一个实例接收并发会话事件和任务回调；人类进度不混入 JSON 输出。
+      class Progress
+        def initialize(io: $stderr, enabled: true, verbose: false)
+          @io, @enabled, @verbose = io, enabled, verbose
+          @tty = io.respond_to?(:tty?) && io.tty?
+          @stages = {}
+          @task_started = {}
+          @failures = Hash.new(0)
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @succeeded = @failed = @unverified = 0
+          @mutex = Mutex.new
+          @total = @completed = @active = 0
+        end
+
+        def reading_inventory
+          write(nil, "正在读取 Netdisco 设备清单")
+        end
+
+        def plan(plan, concurrency:, limit_per_vendor: nil)
+          @mutex.synchronize do
+            @total = plan.ready.size
+            @completed = @active = 0
+            @run_started = monotonic
+            mode = limit_per_vendor ? "抽样（每厂商最多 #{limit_per_vendor} 台）" : "全量"
+            emit(nil, "#{mode} | 清单 #{plan.inventory.size} 台；本次 #{@total} 台；跳过 #{plan.inventory.size - @total} 台；并发 #{concurrency}")
+          end
+        end
+
+        def start(device)
+          @mutex.synchronize do
+            @active += 1
+            @stages[device.host] = "登录"
+            @task_started[device.host] = monotonic
+            @verbose ? emit(device.host, "开始备份（#{device.vendor}）") : refresh
+          end
+        end
+
+        # 只显示已脱敏事件中的阶段和安全命令，不显示设备回显或异常原文。
+        def event(event)
+          return unless event.is_a?(Log::Event)
+
+          unless @verbose
+            @mutex.synchronize do
+              host = event.fields[:host]
+              @stages[host] = "采集" if @stages.key?(host) && event.name == "login_complete" && event.fields[:status] == "ok"
+              refresh
+            end
+            return
+          end
+
+          fields = event.fields
+          message = case event.name
+                    when "connect" then "正在连接并登录（#{fields[:protocol]}）"
+                    when "login_complete"
+                      fields[:status] == "ok" ? "登录成功" : "登录失败（#{fields[:code]}）"
+                    when "connect_failed" then "连接失败（#{fields[:code]}）"
+                    when "command_start" then "执行命令：#{fields[:text]}；等待响应"
+                    when "command_complete"
+                      fields[:status] == "response_received" ? "命令响应完成（#{fields[:duration_ms]} ms）" :
+                        "命令失败（#{fields[:code]}）"
+                    when "operation_complete"
+                      fields[:status] == "completed" ? "脚本处理完成" : "脚本处理失败（#{fields[:code]}）"
+                    end
+          write(fields[:host], message) if message
+        end
+
+        def result(outcome)
+          @mutex.synchronize do
+            @completed += 1
+            @active -= 1
+            @stages.delete(outcome.device.host)
+            @task_started.delete(outcome.device.host)
+            @failures[outcome.error_code || outcome.status] += 1 unless outcome.success?
+            outcome.success? ? @succeeded += 1 : @failed += 1
+            @unverified += 1 if outcome.status == :reported_uploaded && outcome.backup&.verification != :server_verified
+            message = case outcome.status
+                      when :backed_up then "备份已保存（#{outcome.backup.bytes} 字节）"
+                      when :reported_uploaded
+                        outcome.backup&.verification == :server_verified ? "配置已归档（#{outcome.backup.server_bytes} 字节）" :
+                          "设备报告上传完成；服务器文件尚未核验"
+                      when :saved_with_error then "备份有产物但未完全成功（#{outcome.error_code}）"
+                      when :reported_with_error then "设备报告上传但收尾异常（#{outcome.error_code}）"
+                      else "未完成（#{outcome.error_code || outcome.status}）"
+                      end
+            hint = failure_hint(outcome.error_code)
+            message = "#{message}；#{hint}" if hint
+            if @verbose || !outcome.success?
+              emit(outcome.device.host, "#{message}；耗时 #{outcome.duration_ms} ms")
+            elsif !@tty && ((@completed % 25).zero? || @completed == @total)
+              emit(nil, status_line)
+            end
+            refresh
+          end
+        end
+
+        def finish(report)
+          summary = report.summary
+          failures = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
+                           .group_by { |item| item.error_code || item.status }.transform_values(&:size)
+          unless failures.empty?
+            write(nil, "未完成分类：#{failures.sort_by { |code, count| [-count, code.to_s] }.map { |code, count| "#{code}=#{count}" }.join("，")}")
+          end
+          write(nil, "批次结束：成功 #{summary[:succeeded]}，部分成功 #{summary[:partial]}，失败 #{summary[:failed]}，跳过 #{summary[:skipped]}；耗时 #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at).round(1)} 秒；结果 #{report.policy_success? ? "完成" : "未完成"}")
+          unverified = summary[:verification]&.fetch(:unverified, 0) || 0
+          write(nil, "其中 #{unverified} 台仅设备报告上传完成，服务器文件尚未核验") if unverified.positive?
+          return unless !report.callback_errors.empty? || report.report_error
+
+          write(nil, "回调异常 #{report.callback_errors.size}，报告错误 #{report.report_error || "无"}")
+        end
+
+        # 心跳只负责显示；退出、异常或中断时先唤醒并回收线程。
+        def with_updates
+          return yield unless @enabled && @tty && !@verbose
+
+          lock = Mutex.new
+          signal = ConditionVariable.new
+          stopped = false
+          worker = Thread.new do
+            loop do
+              stop = lock.synchronize do
+                signal.wait(lock, 1) unless stopped
+                stopped
+              end
+              break if stop
+
+              tick
+            end
+          end
+          yield
+        ensure
+          if worker
+            lock.synchronize { stopped = true; signal.broadcast }
+            worker.value
+            @mutex.synchronize { clear_refresh }
+          end
+        end
+
+        def tick
+          @mutex.synchronize { refresh(force: true) }
+        end
+
+        def location(path)
+          write(nil, "报告：#{path}")
+        end
+
+        private
+
+        def failure_hint(code)
+          case code
+          when :authentication_failed then "设备拒绝认证，请核对账号、密码或 AAA 策略"
+          when :authentication_error then "认证交互未完成，请核对认证方式或设备 AAA 日志"
+          when :host_key_untrusted then "主机密钥尚未信任，请确认指纹并登记"
+          when :host_key_changed then "已登记主机密钥发生变化，请核实设备身份"
+          when :login_timeout then "未在期限内获得登录提示，请检查 SSH 握手与登录交互"
+          when :connection_timeout then "SSH 连接或握手超时，请检查服务与网络"
+          when :device_error then "设备拒绝命令，请核对厂商映射和账号权限"
+          end
+        end
+
+        def status_line
+          percent = @total.positive? ? @completed * 100 / @total : 0
+          "#{@completed}/#{@total} #{percent}% | 成功 #{@succeeded} 未完成 #{@failed} | 登录 #{@stages.values.count("登录")} 采集 #{@stages.values.count("采集")} 排队 #{[@total - @completed - @active, 0].max}"
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def duration(seconds)
+          total = seconds.round
+          format("%02d:%02d:%02d", total / 3600, total / 60 % 60, total % 60)
+        end
+
+        def timing_line
+          elapsed = [monotonic - (@run_started || @started_at), 0].max
+          rate = elapsed.positive? ? @completed / elapsed : 0
+          eta = if @completed == @total && @total.positive?
+                  "00:00:00"
+                elsif @completed >= 5 && rate.positive?
+                  "约 #{duration((@total - @completed) / rate)}"
+                else
+                  "估算中"
+                end
+          line = "耗时 #{duration(elapsed)} | #{format("%.1f", rate)} 台/秒 | 剩余 #{eta}"
+          host, started = @task_started.min_by { |_key, value| value }
+          if started && monotonic - started >= 10
+            line += " | 最久 #{host} #{@stages[host]} #{(monotonic - started).floor}s"
+          end
+          line
+        end
+
+        def refresh(force: false)
+          return unless @enabled && @tty && !@verbose
+
+          now = monotonic
+          return if !force && @refreshing && @completed < @total && @last_refresh && now - @last_refresh < 0.2
+
+          @last_refresh = now
+          divider = fit_terminal("-" * 100)
+          lines = [divider, fit_terminal(status_line), fit_terminal(timing_line), divider]
+          return if @refreshing && @last_status == lines
+
+          clear_refresh
+          @last_status = lines
+          @io.write(lines.join("\n"))
+          @io.flush
+          @refreshing = true
+        end
+
+        # 留一列避免终端自动换行，窄窗口也不会留下旧进度行。
+        def fit_terminal(line)
+          columns = @io.respond_to?(:winsize) ? @io.winsize.last : 120
+          columns = 120 unless columns.positive?
+          width = 0
+          text = line.gsub(/[[:cntrl:]]/, " ")
+          text.each_char.take_while do |character|
+            width += character.ord > 255 ? 2 : 1
+            width < columns
+          end.join
+        rescue IOError, SystemCallError
+          line
+        end
+
+        def clear_refresh
+          return unless @refreshing
+
+          @io.write("\r\e[2K" + ("\e[1A\r\e[2K" * (@last_status.length - 1)))
+          @refreshing = false
+        end
+
+        def write(host, message)
+          @mutex.synchronize { emit(host, message) }
+        end
+
+        def emit(host, message)
+          return unless @enabled
+
+          percent = @total.positive? ? " #{(@completed * 100.0 / @total).floor}%" : ""
+          clear_refresh
+          line = "[#{Time.now.strftime("%H:%M:%S")}] [#{@completed}/#{@total}#{percent} 执行中 #{@active}] [#{host || "批次"}] #{message}"
+          line = "[#{Time.now.strftime("%H:%M:%S")}] #{host ? "#{host}  " : ""}#{message}" unless @verbose
+          @io.write(line.gsub(/[[:cntrl:]]/, " ") + "\n")
+          @io.flush
+        end
+      end
+    end
+  end
+end