net-connector 0.17.2 → 0.18.1

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

@@ -59,14 +59,14 @@ module Net
           @error.puts "net-backup: #{message}"
           2
         rescue OptionParser::ParseError
-          @error.puts "net-backup: 参数无效；使用 --help 查看参数"
+          @error.puts "net-backup: invalid arguments; use --help for options"
           2
         rescue ArgumentError, KeyError, Errno::ENOENT,
           Psych::Exception, JSON::ParserError, Inventory::Error => exception
           @error.puts "net-backup: #{exception.message}"
           2
         rescue StandardError => exception
-          @error.puts "net-backup 失败（#{exception.class}）"
+          @error.puts "net-backup failed (#{exception.class})"
           2
         end
 
@@ -111,7 +111,7 @@ module Net
                    fleet.plan_backup(limit_per_vendor: limit, **refresh)
                  end
           options[:host]&.split(",")&.each do |host|
-            raise ArgumentError, "清单中未找到设备 #{host}" unless plan.inventory.any? { |device| device.host == host }
+            raise ArgumentError, "Device not found in inventory: #{host}" unless plan.inventory.any? { |device| device.host == host }
           end
           plan
         end
@@ -120,9 +120,9 @@ module Net
         def inventory_warning(fleet)
           status = fleet.inventory_status if fleet.respond_to?(:inventory_status)
           if status && status[:source] == :stale_cache
-            @error.puts "net-backup: 清单刷新失败，使用历史缓存（#{status[:refresh_error_code]}）"
+            @error.puts "net-backup: inventory refresh failed; using the previous cache (#{status[:refresh_error_code]})"
           end
-          @error.puts "net-backup: 清单缓存写入失败（#{status[:write_error_type]}）" if status && status[:write_error_type]
+          @error.puts "net-backup: inventory cache write failed (#{status[:write_error_type]})" if status && status[:write_error_type]
         end
 
         # 仅执行已经校验的计划，保留本地与 TFTP 两种结果语义。
@@ -143,25 +143,25 @@ module Net
         def parse_options
           options = { environment: {} }
           parser = OptionParser.new do |args|
-            args.banner = "用法：net-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
+            args.banner = "Usage: net-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
             Options.add_settings(args, options)
             Options.add_execution(args, options)
-            args.on("--init", "创建用户目录中的缺失配置和环境模板后退出") { options[:init] = true }
-            args.on("--interactive", "通过终端问答创建缺失配置") { options[:interactive] = true }
-            args.on("--non-interactive", "禁用配置问答") { options[:interactive] = false }
-            args.on("--source SOURCE", %w[http postgres], "清单来源：http（默认）或 postgres") { |value| options[:source] = value }
-            args.on("--query SQL", "PostgreSQL 清单查询，使用 $1、$2 绑定参数") { |value| options[:query] = value }
-            args.on("--query-params JSON", "查询参数的 JSON 数组") { |value| options[:query_params] = value }
-            args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
-            args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
-            args.on("--export IP", "导出已保存的本地配置") { |value| options[:export] = value }
-            args.on("--output FILE", "将导出配置写入私有文件") { |value| options[:output] = value }
-            args.on("--max-script-output-bytes N", Integer, "每个脚本的累计响应字节上限") { |value| options[:max_script_output_bytes] = value }
-            args.on("-v", "--version", "显示版本") do
+            args.on("--init", "Create missing configuration and environment templates in the user directory, then exit") { options[:init] = true }
+            args.on("--interactive", "Create missing configuration through terminal prompts") { options[:interactive] = true }
+            args.on("--non-interactive", "Disable configuration prompts") { options[:interactive] = false }
+            args.on("--source SOURCE", %w[http postgres], "Inventory source: http (default) or postgres") { |value| options[:source] = value }
+            args.on("--query SQL", "PostgreSQL inventory query using $1 and $2 bound parameters") { |value| options[:query] = value }
+            args.on("--query-params JSON", "JSON array of query parameters") { |value| options[:query_params] = value }
+            args.on("--plan", "Preview device inventory without connecting to devices") { options[:plan] = true }
+            args.on("--tftp", "Have devices initiate TFTP backups") { options[:tftp] = true }
+            args.on("--export IP", "Export a saved local configuration") { |value| options[:export] = value }
+            args.on("--output FILE", "Write exported configuration to a private file") { |value| options[:output] = value }
+            args.on("--max-script-output-bytes N", Integer, "Cumulative response byte limit per script") { |value| options[:max_script_output_bytes] = value }
+            args.on("-v", "--version", "Show version") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
             end
-            args.on("-h", "--help", "显示帮助") do
+            args.on("-h", "--help", "Show help") do
               @output.puts args
               options[:done] = true
             end
@@ -179,15 +179,15 @@ module Net
           Planner.validate_limit!(options[:limit])
           raise ArgumentError, "--tftp-root requires --tftp" if options[:tftp_root] && !options[:tftp]
           modes = [:show_config, :plan, :export].count { |key| options[key] }
-          raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
-          raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
-          raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
+          raise ArgumentError, "Select only one of --show-config, --plan and --export" if modes > 1
+          raise ArgumentError, "--output requires --export" if options[:output] && !options[:export]
+          raise ArgumentError, "--all cannot be combined with --limit-per-vendor" if options[:all] && options[:limit]
           if options[:export] && (options[:source] || options[:query] || options[:query_params])
-            raise ArgumentError, "--export 不能与清单查询选项同时使用"
+            raise ArgumentError, "--export cannot be combined with inventory query options"
           end
           if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:environment].key?("NC_PARALLEL") || options[:host] ||
             options[:success_policy] || options[:tftp_root] || options[:max_script_output_bytes] || options[:force_refresh])
-            raise ArgumentError, "--export 不能与备份选项同时使用"
+            raise ArgumentError, "--export cannot be combined with backup options"
           end
         end
 

data/lib/net/connector/netdisco/config/defaults.rb

@@ -48,7 +48,7 @@ module Net
             else value
             end
           rescue ArgumentError, TypeError, JSON::ParserError
-            raise ArgumentError, "初始化参数 #{key} 格式无效", cause: nil
+            raise ArgumentError, "Initialization parameter #{key} has an invalid format", cause: nil
           end
 
           # 同一字段声明同时约束加载与生成，不持久化密码或未知环境变量。

data/lib/net/connector/netdisco/config/initializer.rb

@@ -29,7 +29,7 @@ module Net
             values = YAML.safe_load(YAML.dump(document), aliases: false)
             validate!(values)
             interactive = CtxCli::Terminal.tty?(@input, @output) if interactive.nil?
-            configure(values, mode: mode, inherited_parallel: inherited_parallel) if interactive && answer("进入交互配置？[y/N]", "n").casecmp?("y")
+            configure(values, mode: mode, inherited_parallel: inherited_parallel) if interactive && answer("Start interactive configuration? [y/N]", "n").casecmp?("y")
             validate!(values)
             name = mode == :topology ? "topology" : "backup"
             write(path, Net::Connector::Config.dump(values, name: name, path: path))
@@ -54,7 +54,7 @@ module Net
 
           # 显示有效默认值；空输入可由字段选择沿用或保留继承，输入结束则中止生成。
           def answer(label, default, blank: default)
-            @output.print "#{label}#{default.nil? ? "" : " [#{default}]"}："
+            @output.print "#{label}#{default.nil? ? "" : " [#{default}]"}: "
             @output.flush
             line = @input.gets("\n")
             raise EOFError, "configuration input ended before completion" unless line
@@ -67,7 +67,7 @@ module Net
           def field(document, section, key, label, default, list: false)
             values = (document[section] ||= {})
             previous = values.fetch(key, default)
-            label = "#{label}（留空继承）" if key == "parallel" && !values.key?(key)
+            label = "#{label}(leave blank to inherit)" if key == "parallel" && !values.key?(key)
             loop do
               displayed = previous.is_a?(Array) ? previous.join(",") : previous&.to_s
               text = answer(label, displayed, blank: key == "parallel" ? nil : displayed)
@@ -86,30 +86,30 @@ module Net
                 values[key] = value
                 return
               rescue ArgumentError
-                @output.puts "值无效，请重新输入。"
+                @output.puts "Invalid value; enter it again."
               end
             end
           end
 
           # 按清单来源和业务模式逐项填写非敏感配置。
           def configure(document, mode: nil, inherited_parallel:)
-            field(document, "netdisco", "source", "清单来源 http/postgres", "http")
+            field(document, "netdisco", "source", "Inventory source http/postgres", "http")
             if document.dig("netdisco", "source") == "http"
-              field(document, "netdisco", "url", "清单 URL", mode.nil? ? "https://netdisco.example.invalid" : nil)
+              field(document, "netdisco", "url", "Inventory URL", mode.nil? ? "https://netdisco.example.invalid" : nil)
             end
             %w[include_hosts exclude_hosts include_names exclude_names include_models exclude_models].each do |key|
               field(document, "inventory", key, key, [], list: true)
             end
-            field(document, "inventory", "name_match", "名称匹配 contains/prefix/glob", "contains")
-            field(document, "inventory", "model_match", "型号匹配 contains/prefix/glob", "contains")
+            field(document, "inventory", "name_match", "Name matching contains/prefix/glob", "contains")
+            field(document, "inventory", "model_match", "Model matching contains/prefix/glob", "contains")
             %w[include_vendors exclude_vendors].each { |key| field(document, "inventory", key, key, [], list: true) }
             if document.key?("topology")
-              field(document, "topology", "parallel", "拓扑并发数 1..500", inherited_parallel)
-              field(document, "topology", "directory", "拓扑报告目录", "./topologys")
+              field(document, "topology", "parallel", "Topology concurrency 1..500", inherited_parallel)
+              field(document, "topology", "directory", "Topology report directory", "./topologys")
             else
-              field(document, "backup", "parallel", "并发数 1..500", inherited_parallel)
-              field(document, "backup", "directory", "备份目录", "./backups")
-              field(document, "tftp", "server", "TFTP 服务器", nil) if mode.nil? || mode == :tftp
+              field(document, "backup", "parallel", "Concurrency 1..500", inherited_parallel)
+              field(document, "backup", "directory", "Backup directory", "./backups")
+              field(document, "tftp", "server", "TFTP server", nil) if mode.nil? || mode == :tftp
             end
           end
 

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

@@ -12,26 +12,26 @@ module Net
         # 备份入口保留清单对象接口，显示由公共批次组件处理。
         def plan(plan, parallel:, limit_per_vendor: nil)
           @operation_mode = false
-          mode = limit_per_vendor ? "抽样（每厂商最多 #{limit_per_vendor} 台）" : "全量"
+          mode = limit_per_vendor ? "sample (at most #{limit_per_vendor} devices per vendor)" : "all devices"
           super(total: plan.inventory.size, selected: plan.ready.size, parallel: parallel, label: mode)
         end
 
         # 设备对象只在领域入口转换为显示身份。
-        def start(device, label: "备份")
-          super(host: device.host, label: "#{label}（#{device.vendor}）")
+        def start(device, label: "Backup")
+          super(host: device.host, label: "#{label}(#{device.vendor})")
         end
 
         # 分别展示已保存、设备报告上传和服务器核验状态。
         def result(outcome)
           error_code = diagnostic_code(outcome)
           message = case outcome.status
-                    when :backed_up then "备份已保存（#{outcome.backup.bytes} 字节）"
+                    when :backed_up then "Backup saved (#{outcome.backup.bytes} bytes)"
                     when :reported_uploaded
-                      outcome.backup&.verification == :server_verified ? "配置已归档（#{outcome.backup.server_bytes} 字节）" :
-                        "设备报告上传完成；服务器文件尚未核验"
-                    when :saved_with_error then "备份有产物但未完全成功（#{error_code || outcome.status}）"
-                    when :reported_with_error then "设备报告上传但收尾异常（#{error_code || outcome.status}）"
-                    else "未完成（#{error_code || outcome.status}）"
+                      outcome.backup&.verification == :server_verified ? "Configuration archived (#{outcome.backup.server_bytes} bytes)" :
+                        "Device reported a completed upload; server file has not been verified"
+                    when :saved_with_error then "Backup artifact exists but the operation did not fully succeed (#{error_code || outcome.status})"
+                    when :reported_with_error then "Device reported an upload but finalization failed (#{error_code || outcome.status})"
+                    else "Incomplete (#{error_code || outcome.status})"
                     end
           super(host: outcome.device.host, success: outcome.success?, duration_ms: outcome.duration_ms, message: message, error_code: error_code)
         end
@@ -45,10 +45,10 @@ module Net
                            .group_by { |item| diagnostic_code(item) || item.status }.transform_values(&:size)
           super(success: report.policy_success?, **summary.slice(:succeeded, :partial, :failed, :skipped), failures: failures)
           unverified = summary[:verification]&.fetch(:unverified, 0) || 0
-          write(nil, "其中 #{unverified} 台仅设备报告上传完成，服务器文件尚未核验") if unverified.positive?
+          write(nil, "Of these, #{unverified} devices only reported a completed upload; server files have not been verified") if unverified.positive?
           return unless !report.callback_errors.empty? || report.report_error
 
-          write(nil, "回调异常 #{report.callback_errors.size}，报告错误 #{summary[:report_error] || "无"}")
+          write(nil, "Callback errors #{report.callback_errors.size}, report error #{summary[:report_error] || "none"}")
         end
 
         # 清空上一阶段计数，初始化本次拓扑操作的任务规模与计时。
@@ -61,7 +61,7 @@ module Net
             @stages.clear
             @task_started.clear
             @run_started = monotonic
-            emit(nil, "#{label} | 本次 #{@total} 台；并发 #{parallel}")
+            emit(nil, "#{label} | Selected #{@total} devices; concurrency #{parallel}")
           end
         end
 
@@ -89,8 +89,8 @@ module Net
             @failures[error_code || status] += 1 unless succeeded || skipped
             if @verbose || failed
               label = Topology::Presentation.status(status, changes: changes)
-              reasons = issues.empty? ? "" : "；#{Topology::Presentation.issues(issues)}"
-              emit(device.host, "#{label}；耗时 #{duration_ms} ms#{error_code ? "（#{error_code}）" : ""}#{reasons}")
+              reasons = issues.empty? ? "" : "; #{Topology::Presentation.issues(issues)}"
+              emit(device.host, "#{label}; elapsed #{duration_ms} ms#{error_code ? "(#{error_code})" : ""}#{reasons}")
             elsif !@tty && ((@completed % 25).zero? || @completed == @total)
               emit(nil, status_line)
             end
@@ -101,15 +101,15 @@ module Net
         # 输出拓扑批次的最终状态计数和完成判断。
         def finish_operations(success:, counts:)
           failed = counts.any? { |status, count| Topology::Presentation::FAILURES.include?(status) && count.positive? }
-          result = success ? "完成" : (failed ? "未完成" : "存在待处理项")
-          write(nil, "拓扑批次结束：#{counts.map { |status, count| "#{Topology::Presentation.status(status)} #{count} 台" }.join("，")}；结果 #{result}")
+          result = success ? "complete" : (failed ? "incomplete" : "pending items remain")
+          write(nil, "Topology batch finished: #{counts.map { |status, count| "#{Topology::Presentation.status(status)} #{count} devices" }.join(", ")}; result #{result}")
         end
 
         private
 
         # 拓扑进度保留待核实项计数，备份使用通用成功与失败计数。
         def progress_counts
-          @operation_mode ? "完成 #{@completed} 待核实 #{@operation_pending} 失败 #{@failed}" : super
+          @operation_mode ? "complete #{@completed} unverified #{@operation_pending} failed #{@failed}" : super
         end
 
         # 与持久化摘要采用同一诊断白名单，保留领域结果自身的原始错误字段。

data/lib/net/connector/netdisco/report/text.rb

@@ -14,24 +14,24 @@ module Net
             summary = report.statistics
             failed = report.outcomes.reject { |item| item.success? || %i[filtered sample_limit].include?(item.status) }
             groups = failed.group_by { |item| diagnostic_code(item) || item.status }
-            lines = ["网络设备备份报告", "=" * 72,
-                     "开始时间：#{report.started_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
-                     "结束时间：#{report.finished_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
-                     "清单：#{plan.inventory.size} 台；本次：#{plan.ready.size} 台；并发：#{parallel}",
-                     "成功：#{summary[:succeeded]}；部分成功：#{summary[:partial]}；失败：#{summary[:failed]}；跳过：#{summary[:skipped]}",
-                     "耗时：#{(report.duration_ms.to_f / 1000).round(1)} 秒；批次状态：#{summary[:status]}",
-                     "成功策略：#{report.policy}；策略通过：#{report.policy_success?}",
-                     "回调异常：#{report.callback_errors.size}；报告错误：#{summary[:report_error] || "无"}",
-                     "状态计数：#{report.counts.map { |key, value| "#{key}=#{value}" }.join("，")}",
-                     "未完成分类：#{groups.empty? ? "无" : groups.map { |key, items| "#{key}=#{items.size}" }.join("，")}",
-                     "-" * 72, "未完成设备："]
+            lines = ["Network device backup report", "=" * 72,
+                     "Started: #{report.started_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
+                     "Finished: #{report.finished_at.getlocal("+08:00").strftime("%Y-%m-%d %H:%M:%S %:z")}",
+                     "Inventory: #{plan.inventory.size} devices; selected: #{plan.ready.size} devices; concurrency: #{parallel}",
+                     "Succeeded: #{summary[:succeeded]}; partial: #{summary[:partial]}; failed: #{summary[:failed]}; skipped: #{summary[:skipped]}",
+                     "Elapsed: #{(report.duration_ms.to_f / 1000).round(1)} seconds; batch status: #{summary[:status]}",
+                     "Success policy: #{report.policy}; policy passed: #{report.policy_success?}",
+                     "Callback errors: #{report.callback_errors.size}; report error: #{summary[:report_error] || "none"}",
+                     "Status counts: #{report.counts.map { |key, value| "#{key}=#{value}" }.join(", ")}",
+                     "Incomplete categories: #{groups.empty? ? "none" : groups.map { |key, items| "#{key}=#{items.size}" }.join(", ")}",
+                     "-" * 72, "Incomplete devices: "]
             lines.concat(failure_lines(failed))
-            lines << "无" if failed.empty?
+            lines << "none" if failed.empty?
             if report.mode == :tftp
               verification = summary.fetch(:verification)
-              lines << "TFTP 服务器文件：已核验 #{verification[:verified]}，未核验 #{verification[:unverified]}。"
+              lines << "TFTP server files: verified #{verification[:verified]}, unverified #{verification[:unverified]}."
             end
-            lines += ["=" * 72, "备份目录：#{directory}", "完整明细：#{File.join(directory, "summary.json")}"]
+            lines += ["=" * 72, "Backup directory: #{directory}", "Full details: #{File.join(directory, "summary.json")}"]
             Net::Connector::Storage::AtomicFile.write(File.join(directory, "summary.txt"), lines.join("\n") + "\n")
           end
 
@@ -39,7 +39,7 @@ module Net
           def self.failure_lines(failed)
             failed.map do |item|
               label = item.device.name.to_s.gsub(/[[:cntrl:]]/, " ")
-              "#{item.device.host} | #{label} | #{item.status} | #{diagnostic_code(item) || "无错误码"} | #{item.duration_ms} ms"
+              "#{item.device.host} | #{label} | #{item.status} | #{diagnostic_code(item) || "no error code"} | #{item.duration_ms} ms"
             end
           end
           private_class_method :failure_lines

data/lib/net/connector/netdisco/ssh/archive/client.rb

@@ -3,7 +3,6 @@
 require_relative "../../../storage/directory"
 
 require "digest"
-require "json"
 require "open3"
 require "securerandom"
 require "shellwords"
@@ -11,6 +10,7 @@ require "tmpdir"
 require_relative "../../tftp/root"
 require_relative "../authentication"
 require_relative "../../tftp/archive"
+require_relative "protocol"
 
 module Net
   module Connector
@@ -25,11 +25,11 @@ module Net
               # 构造不含凭据值的认证不可用提示，在设备任务开始前拒绝执行。
               def initialize(password_configured: false)
                 detail = if password_configured
-                           "已读取 NC_TFTP_SSH_PASSWORD，但 SSH 认证或主连接建立失败；请检查账号、密码、主机密钥及网络。密码含 # 或 $ 时请在 .env 中用单引号包裹"
+                           "NC_TFTP_SSH_PASSWORD was read, but SSH authentication or master connection setup failed; check username, password, host key and network. Wrap passwords containing # or $ in single quotes in .env"
                          else
-                           "请在项目根目录 .env 设置 NC_TFTP_SSH_PASSWORD，或配置可用的 SSH 密钥/agent"
+                           "Set NC_TFTP_SSH_PASSWORD in the project root .env, or configure a working SSH key/agent"
                          end
-                super("SSH 归档认证不可用：#{detail}。已停止，未连接设备。")
+                super("SSH archive authentication unavailable: #{detail}. Stopped without connecting to devices.")
               end
             end
 
@@ -37,16 +37,15 @@ module Net
             class PreparationUnavailable < ArgumentError
               # 提示检查远端运行时及私有目录，不携带 SSH 输出或设备配置。
               def initialize
-                super("SSH 归档目录预检失败：请检查服务器 python3、TFTP 根目录及写权限；archive、批次目录和 .net-connector-locks 须由 SSH 账号拥有且权限为 0700。已停止，未连接设备。")
+                super("SSH archive directory preflight failed: check server python3, the TFTP root and write permissions; archive, batch directories and .net-connector-locks must be owned by the SSH user with mode 0700. Stopped without connecting to devices.")
               end
             end
 
-            MAX_FRAME_BYTES = 90 * 1024 * 1024
             SESSION_LIMIT = 4
             WORKER = File.expand_path("worker.py", __dir__)
             ACTIVE_CLIENTS = {}
             ACTIVE_CLIENTS_MUTEX = Mutex.new
-            private_constant :MAX_FRAME_BYTES, :WORKER, :ACTIVE_CLIENTS, :ACTIVE_CLIENTS_MUTEX
+            private_constant :WORKER, :ACTIVE_CLIENTS, :ACTIVE_CLIENTS_MUTEX
 
             # 退出处理只持有仍需清理的连接；已关闭的批次与凭据可由 GC 回收。
             at_exit do
@@ -94,30 +93,26 @@ module Net
               acquired = @slots.pop
               filename = TftpTarget.validate_path!(upload_filename(device))
               archive_name = "#{device.backup_filename(style: :hostname_ip).delete_suffix(".txt")}#{File.extname(filename)}"
-              @launcher.call do |input, output, error, process|
-                begin
-                  write_frame(input, root: @root, filename: filename, archive_name: archive_name, batch: @batch)
-                  expect_phase(output, "ready")
-                  outcome = yield filename
-                  receipt = outcome.backup
-                  unless receipt.is_a?(TftpReceipt) && receipt.path == filename
-                    write_frame(input, action: "abort")
-                    next outcome
-                  end
-                  outcome = outcome.with(started_at: started_at)
-                  write_frame(input, action: "verify")
-                  proof = expect_phase(output, "archived")
-                  outcome = retain_upload(outcome, proof, archive_name)
-                  if outcome.success?
-                    write_frame(input, action: "cleanup", sha256: outcome.backup.server_sha256)
-                    expect_phase(output, "complete")
-                  else
-                    write_frame(input, action: "abort")
-                  end
-                  outcome
-                ensure
-                  stop_process(input, output, error, process)
+              with_process do |protocol|
+                protocol.send_frame(root: @root, filename: filename, archive_name: archive_name, batch: @batch)
+                protocol.expect_phase("ready")
+                outcome = yield filename
+                receipt = outcome.backup
+                unless receipt.is_a?(TftpReceipt) && receipt.path == filename
+                  protocol.send_frame(action: "abort")
+                  next outcome
+                end
+                outcome = outcome.with(started_at: started_at)
+                protocol.send_frame(action: "verify")
+                proof = protocol.expect_phase("archived")
+                outcome = retain_upload(outcome, protocol, proof, archive_name)
+                if outcome.success?
+                  protocol.send_frame(action: "cleanup", sha256: outcome.backup.server_sha256)
+                  protocol.expect_phase("complete")
+                else
+                  protocol.send_frame(action: "abort")
                 end
+                outcome
               end
             rescue StandardError
               raise Tftp::Archive::Failure.new(host: device.host), cause: nil unless outcome
@@ -158,33 +153,26 @@ module Net
 
             # 用实际事务进程预检目录与写入边界，不读取或上传任何设备文件。
             def prepare_archive
-              @launcher.call do |input, output, error, process|
-                begin
-                  write_frame(input, root: @root, filename: "preflight.cfg", archive_name: "preflight.cfg", batch: @batch, action: "preflight")
-                  expect_phase(output, "ready")
-                ensure
-                  stop_process(input, output, error, process)
-                end
+              with_process do |protocol|
+                protocol.send_frame(root: @root, filename: "preflight.cfg", archive_name: "preflight.cfg", batch: @batch, action: "preflight")
+                protocol.expect_phase("ready")
               end
             rescue StandardError
               raise PreparationUnavailable, cause: nil
             end
 
             # 先核对服务器正文与摘要，再保留远端归档路径；后续本地写入失败仍保留已有证据。
-            def retain_upload(outcome, proof, archive_name)
-              bytes = proof.fetch("data").unpack1("m0")
-              digest = Digest::SHA256.hexdigest(bytes)
-              unless bytes.bytesize.positive? && bytes.bytesize == proof.fetch("bytes") && digest == proof.fetch("sha256")
-                raise Tftp::Archive::Failure
-              end
-              receipt = outcome.backup.with(verification: :server_verified, server_sha256: digest, server_bytes: bytes.bytesize,
+            def retain_upload(outcome, protocol, proof, archive_name)
+              receipt = outcome.backup.with(verification: :server_verified, server_sha256: proof.fetch("sha256"), server_bytes: proof.fetch("bytes"),
                                           archive_path: remote_path(proof.fetch("archive_path")))
-              outcome = outcome.with(backup: receipt)
               path = File.join(@report_directory, "tftp", archive_name)
-              Storage::Directory.prepare(File.dirname(path))
-              Storage::AtomicFile.write(path, bytes)
+              persist_upload(path) do |file|
+                failure = receive_upload(protocol, receipt, file)
+                outcome = outcome.with(backup: receipt)
+                raise failure if failure
+              end
               outcome = outcome.with(backup: receipt.with(local_path: path))
-              raise Tftp::Archive::Failure unless Storage::FileReader.fingerprint(path).sha256 == digest
+              raise Tftp::Archive::Failure unless Storage::FileReader.fingerprint(path).sha256 == receipt.server_sha256
 
               outcome
             rescue StandardError => error
@@ -194,6 +182,38 @@ module Net
               outcome.success? ? archive_failure(outcome) : outcome
             end
 
+            # 本地准备失败仍接收并核验服务器正文；已经开始接收的失败事务不能重读或重写。
+            def persist_upload(path)
+              received = false
+              Storage::Directory.prepare(File.dirname(path))
+              Storage::AtomicFile.write_stream(path) do |file|
+                received = true
+                yield file
+              end
+            rescue StandardError
+              yield nil unless received
+              raise
+            end
+
+            # 逐块核对摘要，首次写盘错误后只继续读取；完整交付确认后才返回写盘故障。
+            def receive_upload(protocol, receipt, file)
+              digest = Digest::SHA256.new
+              failure = nil
+              protocol.read_payload(receipt.server_bytes) do |chunk|
+                digest << chunk
+                next unless file && !failure
+
+                begin
+                  raise IOError, "incomplete archive write" unless file.write(chunk) == chunk.bytesize
+                rescue StandardError => error
+                  failure = error
+                end
+              end
+              raise Tftp::Archive::Failure unless digest.hexdigest == receipt.server_sha256
+
+              failure
+            end
+
             # 保留设备和服务器回执，将归档收尾异常转换为可诊断的部分成功。
             def archive_failure(outcome)
               failure = Tftp::Archive::Failure.new(host: outcome.device.host)
@@ -251,11 +271,10 @@ module Net
               false
             end
 
-            # 复用主连接启动一次归档事务进程，会话槽位限制由调用作用域管理。
-            def open_ssh(&)
-              prepare_master
+            # 返回事务管道和等待线程，由调用作用域唯一负责关闭、终止及回收。
+            def open_ssh
               command = "python3 -u -c #{Shellwords.escape(File.read(WORKER))}"
-              Open3.popen3(*ssh_arguments, @uri.host, command, &)
+              Open3.popen3(*ssh_arguments, @uri.host, command)
             end
 
             # 将已校验端点组装为独立 SSH 参数，固定严格主机密钥检查与连接超时。
@@ -265,32 +284,24 @@ module Net
                "-p", (@uri.port || 22).to_s, "-l", @uri.user]
             end
 
-            # 将路径或事务动作编码为单行 JSON 并刷新，协议帧不携带认证凭据。
-            def write_frame(input, **values)
-              input.write(JSON.generate(values) + "\n")
-              input.flush
-            end
-
-            # 在总期限和帧大小上限内读取完整响应，拒绝断连、错误阶段及无效协议数据。
-            def expect_phase(output, phase)
-              deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 280
-              frame = +"".b
-              loop do
-                remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-                raise Tftp::Archive::Failure unless remaining.positive? && output.wait_readable(remaining)
-
-                chunk = output.read_nonblock(65_536, exception: false)
-                next if chunk == :wait_readable
-                raise Tftp::Archive::Failure if chunk.nil?
-
-                frame << chunk
-                raise Tftp::Archive::Failure if frame.bytesize > MAX_FRAME_BYTES
-                next unless frame.end_with?("\n")
-
-                value = JSON.parse(frame)
-                raise Tftp::Archive::Failure unless value["ok"] == true && value["phase"] == phase
-
-                return value
+            # 每次事务独占进程与协议状态，主故障或非局部退出不能被普通清理错误覆盖。
+            def with_process
+              handles = nil
+              prepare_master unless @custom_launcher
+              completed = false
+              # 取得资源与登记所有权之间暂缓取消；事务本身仍可立即中断。
+              Thread.handle_interrupt(Exception => :never) { handles = @launcher.call }
+              result = yield Protocol.new(handles[0], handles[1])
+              completed = true
+              result
+            rescue Exception # rubocop:disable Lint/RescueException -- 返回前递送的取消仍属于事务主控制流。
+              completed = false
+              raise
+            ensure
+              begin
+                stop_process(*handles) if handles
+              rescue Exception # rubocop:disable Lint/RescueException -- 取消和非局部退出均保留原始控制流。
+                raise if completed
               end
             end
 
@@ -303,7 +314,26 @@ module Net
 
             # 先关闭事务管道并等待子进程退出，超时后分级终止，促使服务器释放锁。
             def stop_process(input, output, error, process)
-              [input, output, error].each { |io| io.close unless io.closed? }
+              Thread.handle_interrupt(Exception => :never) do
+                failure = nil
+                [input, output, error].each do |io|
+                  begin
+                    io.close unless io.closed?
+                  rescue Exception => caught # rubocop:disable Lint/RescueException -- 单个关闭失败仍须回收其余管道和进程。
+                    failure ||= caught
+                  end
+                end
+                begin
+                  reap_process(process)
+                rescue Exception => caught # rubocop:disable Lint/RescueException -- 保留先发生的清理故障。
+                  failure ||= caught
+                end
+                raise failure if failure
+              end
+            end
+
+            # 为正常退出保留短暂宽限，随后终止仍未退出的事务进程并回收等待线程。
+            def reap_process(process)
               return if process.join(2)
 
               Process.kill("TERM", process.pid)