net-connector 0.17.2 → 0.18.1

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../tftp/archive"
+
+module Net
+  module Connector
+    module Netdisco
+      module SSH
+        module Archive
+          # 仅借用事务管道，维护控制帧与二进制正文的分界、缓冲和绝对期限。
+          class Protocol
+            READ_BYTES = 65_536
+            CONTROL_BYTES = 16_384
+            PAYLOAD_BYTES = 64 * 1024 * 1024
+            private_constant :READ_BYTES, :CONTROL_BYTES, :PAYLOAD_BYTES
+
+            # 每个事务独占自己的协议状态；管道关闭和进程回收仍由客户端负责。
+            def initialize(input, output, timeout: 280)
+              @input, @output = input, output
+              @timeout = timeout
+              @buffer = +"".b
+            end
+
+            # 发送有界单行控制帧，写入不完整不能当作命令已经交付。
+            def send_frame(**values)
+              frame = JSON.generate(values) + "\n"
+              raise Tftp::Archive::Failure if frame.bytesize > CONTROL_BYTES || @input.write(frame) != frame.bytesize
+
+              @input.flush
+            end
+
+            # 开始一个控制阶段；归档元数据取得的期限同时覆盖后续正文及交付确认。
+            def expect_phase(phase)
+              @deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+              read_phase(phase)
+            end
+
+            # 按声明长度分片交付二进制正文，随后在同一期限内确认服务器完成交付。
+            def read_payload(length)
+              unless @phase == "archived" && length.is_a?(Integer) && (1..PAYLOAD_BYTES).cover?(length)
+                raise Tftp::Archive::Failure
+              end
+
+              remaining = length
+              while remaining.positive?
+                remaining_time
+                @buffer << read_chunk if @buffer.empty?
+                chunk = @buffer.slice!(0, [remaining, READ_BYTES, @buffer.bytesize].min)
+                remaining -= chunk.bytesize
+                yield chunk
+              end
+              read_phase("delivered")
+            end
+
+            private
+
+            # 缓冲中可能同时含有控制帧和正文，只消费当前行并限制控制帧长度。
+            def read_phase(phase)
+              loop do
+                remaining_time
+                ending = @buffer.index("\n")
+                if ending
+                  raise Tftp::Archive::Failure if ending + 1 > CONTROL_BYTES
+
+                  value = JSON.parse(@buffer.slice!(0, ending + 1))
+                  unless value.is_a?(Hash) && value["ok"] == true && value["phase"] == phase
+                    raise Tftp::Archive::Failure
+                  end
+
+                  @phase = phase
+                  return value
+                end
+                raise Tftp::Archive::Failure if @buffer.bytesize >= CONTROL_BYTES
+
+                @buffer << read_chunk
+              end
+            rescue JSON::ParserError
+              raise Tftp::Archive::Failure, cause: nil
+            end
+
+            # 每次非阻塞读取使用剩余总预算，片段到达不能重新开始计时。
+            def read_chunk
+              loop do
+                raise Tftp::Archive::Failure unless @output.wait_readable(remaining_time)
+
+                chunk = @output.read_nonblock(READ_BYTES, exception: false)
+                next if chunk == :wait_readable
+                raise Tftp::Archive::Failure if chunk.nil?
+
+                return chunk
+              end
+            end
+
+            # 即使数据已经缓冲，也检查绝对期限，避免消费者或确认阶段偷偷延长预算。
+            def remaining_time
+              remaining = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              raise Tftp::Archive::Failure unless remaining.positive?
+
+              remaining
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/ssh/archive/worker.py

@@ -1,7 +1,6 @@
 # 服务器端单次归档事务：锁覆盖上传与核验，客户端断开后退出且不重放设备命令。
 """在一个目标锁内处理单次上传事务，客户端断开后退出且不重放设备操作。"""
 
-import base64
 from contextlib import ExitStack
 import fcntl
 import hashlib
@@ -14,6 +13,7 @@ import sys
 import time
 
 MAX_BYTES = 64 * 1024 * 1024
+CHUNK_BYTES = 64 * 1024
 DIRECTORY_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
 
 
@@ -107,7 +107,7 @@ def fingerprint(s):
 
 
 # 从固定目录安全读取有界普通文件，读前、读后和路径身份必须一致。
-def read_file(parent, name, missing=False):
+def read_file(parent, name, missing=False, consume=None):
     try:
         fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=parent)
     except FileNotFoundError:
@@ -118,13 +118,24 @@ def read_file(parent, name, missing=False):
         before = os.fstat(f.fileno())
         if not stat.S_ISREG(before.st_mode) or before.st_size > MAX_BYTES:
             raise ValueError("unsafe or oversized file")
-        data = f.read(MAX_BYTES + 1)
+        digest = hashlib.sha256()
+        size = 0
+        while True:
+            chunk = f.read(CHUNK_BYTES)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > MAX_BYTES:
+                raise ValueError("oversized file")
+            digest.update(chunk)
+            if consume is not None and consume(chunk) != len(chunk):
+                raise IOError("incomplete file write")
         after = os.fstat(f.fileno())
-        if len(data) > MAX_BYTES or fingerprint(before) != fingerprint(after):
+        if size != after.st_size or fingerprint(before) != fingerprint(after):
             raise ValueError("file changed while reading")
         if fingerprint(after) != fingerprint(os.stat(name, dir_fd=parent, follow_symlinks=False)):
             raise ValueError("file replaced while reading")
-        return data, fingerprint(after)
+        return digest.hexdigest(), fingerprint(after)
 
 
 # 在固定目录中以随机名称独占创建私有临时文件，碰撞时重新选择名称。
@@ -139,11 +150,13 @@ def temporary(parent, prefix):
 
 
 # 先写全并同步临时文件，再独占链接到归档名并同步目录，已有归档不会被覆盖。
-def persist(parent, name, data):
+def persist(parent, name, source_parent, source_name, expected, digest):
     fd, pending = temporary(parent, ".net-connector-")
     try:
         with os.fdopen(fd, "wb") as f:
-            f.write(data)
+            copied, current = read_file(source_parent, source_name, consume=f.write)
+            if current != expected or copied != digest:
+                raise ValueError("source changed before archive commit")
             f.flush()
             os.fsync(f.fileno())
         # 临时名与最终名均相对固定目录解析，父路径改名也不能将写入重定向。
@@ -218,9 +231,9 @@ def run():
         # 上传前先保留同名历史文件；只有服务器确认就绪后，客户端才允许设备导出。
         verify_boundary()
         old, previous = read_file(root_fd, name, missing=True)
-        if old is not None:
+        if previous is not None:
             previous_fd = directories.private(batch_fd, "previous")
-            persist(previous_fd, archive_name, old)
+            persist(previous_fd, archive_name, root_fd, name, previous, old)
         fd, marker = temporary(root_fd, ".net-connector-upload-")
         try:
             started = os.fstat(fd).st_mtime_ns
@@ -233,26 +246,29 @@ def run():
             return
         verify_boundary()
         # 新文件必须非空、区别于旧基线且不早于本次上传边界，旧文件不能冒充新结果。
-        data, current = read_file(root_fd, name)
-        if not data or current == previous or current[3] < started:
+        digest, current = read_file(root_fd, name)
+        if not current[2] or current == previous or current[3] < started:
             raise ValueError("no new nonempty upload")
-        digest = hashlib.sha256(data).hexdigest()
-        persist(batch_fd, archive_name, data)
-        archived, _ = read_file(batch_fd, archive_name)
-        if hashlib.sha256(archived).hexdigest() != digest:
+        persist(batch_fd, archive_name, root_fd, name, current, digest)
+        archived, saved = read_file(batch_fd, archive_name)
+        if archived != digest or saved[2] != current[2]:
             raise ValueError("archive verification failed")
         verify_boundary()
         destination = os.path.join(root, "archive", batch, archive_name)
-        send(phase="archived", bytes=len(data), sha256=digest, archive_path=destination,
-             data=base64.b64encode(data).decode("ascii"))
+        send(phase="archived", bytes=current[2], sha256=digest, archive_path=destination)
+        delivered, check = read_file(batch_fd, archive_name, consume=sys.stdout.buffer.write)
+        if delivered != digest or check != saved:
+            raise ValueError("archive changed during delivery")
+        verify_boundary()
+        send(phase="delivered")
         # 远端归档及正文已交付客户端；只有收到客户端核验后的明确清理指令才删除 staging。
         action = receive()
         if action.get("action") == "cleanup":
             if action.get("sha256") != digest:
                 raise ValueError("cleanup digest mismatch")
             verify_boundary()
-            data, check = read_file(root_fd, name)
-            if check != current or hashlib.sha256(data).hexdigest() != digest:
+            uploaded, check = read_file(root_fd, name)
+            if check != current or uploaded != digest:
                 raise ValueError("upload changed before cleanup")
             verify_boundary()
             os.unlink(name, dir_fd=root_fd)

data/lib/net/connector/netdisco/ssh/authentication.rb

@@ -14,17 +14,15 @@ module Net
 
           # 在同一认证期限内等待一次密码提示及连接结束；主连接可用性由调用方另行核对。
           def self.respond(arguments, password:)
-            session = Expect::Session.new(buffer_limit: 65_536, write_timeout: 5)
-            session.spawn(*arguments, raw: true)
-            deadline = Expect.monotonic + 15
-            challenge = session.expect(PASSWORD, REJECTED, timeout: [deadline - Expect.monotonic, 0].max)
-            return false unless challenge.number == 1
+            Expect.spawn(*arguments, raw: true, buffer_limit: 65_536, write_timeout: 5) do |session|
+              deadline = Expect.monotonic + 15
+              challenge = session.expect(PASSWORD, REJECTED, timeout: [deadline - Expect.monotonic, 0].max)
+              next false unless challenge.number == 1
 
-            session.write(password + "\n")
-            completion = session.expect(PASSWORD, REJECTED, timeout: [deadline - Expect.monotonic, 0].max)
-            completion.error == :eof
-          ensure
-            session&.close
+              session.write(password + "\n")
+              completion = session.expect(PASSWORD, REJECTED, timeout: [deadline - Expect.monotonic, 0].max)
+              completion.error == :eof
+            end
           end
         end
       end

data/lib/net/connector/netdisco/topology/files.rb

@@ -35,16 +35,16 @@ module Net
             path = outcome[:device_report]
             return unless path
 
-            lines = ["设备：#{text(outcome[:name])}（#{text(outcome[:host])}）", "厂商：#{text(outcome[:vendor])}",
-                     "状态：#{Presentation.status(outcome[:status], changes: outcome.fetch(:changes, 0))}；候选变更：#{outcome.fetch(:changes, 0)}",
-                     outcome[:script_file] ? "命令文件：#{outcome[:script_file]}" : "命令文件：未生成（没有已核实的配置变更）"]
-            lines << "命令校验 SHA-256：#{outcome[:script_sha256]}" if outcome[:script_sha256]
-            lines << "诊断：#{text(outcome.dig(:diagnostic, :error_code))}" if outcome[:diagnostic]
-            lines << "配置命令来自本次计划；文件生成不表示已经下发，执行结果以状态和设备回执为准。"
+            lines = ["Device: #{text(outcome[:name])} (#{text(outcome[:host])})", "Vendor: #{text(outcome[:vendor])}",
+                     "Status: #{Presentation.status(outcome[:status], changes: outcome.fetch(:changes, 0))}; candidate changes: #{outcome.fetch(:changes, 0)}",
+                     outcome[:script_file] ? "Command file: #{outcome[:script_file]}" : "Command file: not generated (no verified configuration changes)"]
+            lines << "Command SHA-256: #{outcome[:script_sha256]}" if outcome[:script_sha256]
+            lines << "Diagnostics: #{text(outcome.dig(:diagnostic, :error_code))}" if outcome[:diagnostic]
+            lines << "Configuration commands come from this plan; generating a file does not mean commands were sent. Check status and device receipts for execution results."
             lines.concat(outcome.fetch(:neighbors, []).map do |row|
-              "#{text(row[:interface])} #{text(row[:status])} 现有=#{row[:current].inspect} 目标=#{row[:expected].inspect}"
+              "#{text(row[:interface])} #{text(row[:status])} current=#{row[:current].inspect} target=#{row[:expected].inspect}"
             end)
-            lines.concat(outcome.fetch(:issues, []).map { |issue| "未核实：#{text(issue[:interface])} #{text(Presentation.reason(issue[:code]))}" })
+            lines.concat(outcome.fetch(:issues, []).map { |issue| "Unverified: #{text(issue[:interface])} #{text(Presentation.reason(issue[:code]))}" })
             FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
             Storage::AtomicFile.write(path, lines.join("\n") + "\n")
           end

data/lib/net/connector/netdisco/topology/presentation.rb

@@ -6,18 +6,18 @@ module Net
       module Topology
         # JSON 状态码保持稳定；终端、汇总和设备说明共用中文含义及分类统计。
         module Presentation
-          STATUSES = { planned: "已生成计划", partial_planned: "已生成部分计划", unverified: "含待核实接口",
-                       discovered: "发现完成", applied: "应用完成", partial_applied: "部分应用完成", manual_required: "需人工处理",
-                       unsupported_operation: "不支持，已跳过", failed: "执行失败", partial: "执行部分失败",
-                       missing_credentials: "缺少凭据", interrupted: "已中断", not_started: "未开始", offline_review: "离线重审" }.freeze
-          REASONS = { unknown_neighbor_name: "邻居未提供名称", unknown_neighbor_interface: "邻居未提供端口",
-                      ambiguous_neighbor: "同一接口存在多个邻居", interface_missing: "配置中未找到本地接口",
-                      unsafe_description: "目标描述不符合安全约束" }.freeze
+          STATUSES = { planned: "plan generated", partial_planned: "partial plan generated", unverified: "contains unverified interfaces",
+                       discovered: "discovery complete", applied: "apply complete", partial_applied: "partial apply complete", manual_required: "manual action required",
+                       unsupported_operation: "unsupported; skipped", failed: "execution failed", partial: "execution partially failed",
+                       missing_credentials: "missing credentials", interrupted: "interrupted", not_started: "not started", offline_review: "offline review" }.freeze
+          REASONS = { unknown_neighbor_name: "neighbor name missing", unknown_neighbor_interface: "neighbor port missing",
+                      ambiguous_neighbor: "multiple neighbors on one interface", interface_missing: "local interface not found in configuration",
+                      unsafe_description: "target description violates safety constraints" }.freeze
           FAILURES = %i[failed partial missing_credentials interrupted not_started].freeze
 
           # 已规划但没有变更时明确显示无需修改，避免读者将 planned 理解为已经执行。
           def self.status(value, changes: nil)
-            return "无需修改" if value.to_sym == :planned && changes == 0
+            return "no changes needed" if value.to_sym == :planned && changes == 0
 
             STATUSES.fetch(value.to_sym, value.to_s)
           end
@@ -27,7 +27,7 @@ module Net
 
           # 汇总逐接口的问题数量，不把身份不足与设备连接或命令失败混为一谈。
           def self.issues(rows)
-            rows.map { |row| row[:code] }.tally.map { |code, count| "#{reason(code)} #{count} 个接口" }.join("；")
+            rows.map { |row| row[:code] }.tally.map { |code, count| "#{reason(code)} #{count} interfaces" }.join("; ")
           end
 
           # 设备与接口分别统计；含待核实项的设备也可能拥有可执行的局部计划。
@@ -43,14 +43,14 @@ module Net
 
           # 只读计划中有差异或未知证据表示待处理，不能把生成计划描述为配置下发完成。
           def self.result(summary)
-            return "未完成" if summary[:orchestration_error_type] || summary[:interrupted] || summary[:progress_error]
-            return "完成" if summary[:success]
-            return "执行存在失败" if summary.fetch(:statistics).fetch(:failed).positive?
+            return "incomplete" if summary[:orchestration_error_type] || summary[:interrupted] || summary[:progress_error]
+            return "complete" if summary[:success]
+            return "execution contains failures" if summary.fetch(:statistics).fetch(:failed).positive?
 
-            return "没有可处理设备" if summary[:devices].empty?
+            return "no eligible devices" if summary[:devices].empty?
 
-            { plan: "已生成计划，存在待修正或待核实项", discover: "发现结束，仍有待核实接口",
-              apply: "应用结束，仍有待处理项" }.fetch(summary[:mode], "存在待处理项")
+            { plan: "plan generated; corrections or verification still required", discover: "discovery finished; unverified interfaces remain",
+              apply: "apply finished; pending items remain" }.fetch(summary[:mode], "pending items remain")
           end
         end
       end

data/lib/net/connector/progress.rb

@@ -27,26 +27,26 @@ module Net
 
       # 输出当前开始读取清单的进度提示。
       def reading_inventory(config: nil)
-        write(nil, "正在读取 Netdisco 设备清单#{config ? "（配置：#{config}）" : ""}")
+        write(nil, "Reading Netdisco device inventory#{config ? "(configuration: #{config})" : ""}")
       end
 
       # 以实际选中设备初始化进度，跳过的条目不计入执行任务总数。
-      def plan(total:, selected:, parallel:, label: "全量")
+      def plan(total:, selected:, parallel:, label: "all devices")
         @mutex.synchronize do
           @total = selected
           @completed = @active = 0
           @run_started = monotonic
-          emit(nil, "#{label} | 清单 #{total} 台；本次 #{@total} 台；跳过 #{total - @total} 台；并发 #{parallel}")
+          emit(nil, "#{label} | Inventory #{total} devices; selected #{@total}; skipped #{total - @total} devices; concurrency #{parallel}")
         end
       end
 
       # 任务开始只表示进入登录阶段，不代表设备已连接。
-      def start(host:, label: "采集")
+      def start(host:, label: "collecting")
         @mutex.synchronize do
           @active += 1
-          @stages[host] = "登录"
+          @stages[host] = "logging in"
           @task_started[host] = monotonic
-          @verbose ? emit(host, "开始#{label}") : refresh
+          @verbose ? emit(host, "starting#{label}") : refresh
         end
       end
 
@@ -59,9 +59,9 @@ module Net
           @task_started.delete(host)
           success ? @succeeded += 1 : @failed += 1
           hint = failure_hint(error_code)
-          message = "#{message}；#{hint}" if hint
+          message = "#{message}; #{hint}" if hint
           if @verbose || !success
-            emit(host, "#{message}；耗时 #{duration_ms} ms")
+            emit(host, "#{message}; elapsed #{duration_ms} ms")
           elsif !@tty && ((@completed % 25).zero? || @completed == @total)
             emit(nil, status_line)
           end
@@ -72,9 +72,9 @@ module Net
       # 完成百分比只表示任务结束，最终结果始终由已保存的业务报告决定。
       def finish(success:, succeeded:, partial:, failed:, skipped:, failures: {})
         unless failures.empty?
-          write(nil, "未完成分类：#{failures.sort_by { |code, count| [-count, code.to_s] }.map { |code, count| "#{code}=#{count}" }.join("，")}")
+          write(nil, "Incomplete categories: #{failures.sort_by { |code, count| [-count, code.to_s] }.map { |code, count| "#{code}=#{count}" }.join(", ")}")
         end
-        write(nil, "批次结束：成功 #{succeeded}，部分成功 #{partial}，失败 #{failed}，跳过 #{skipped}；耗时 #{(monotonic - @started_at).round(1)} 秒；结果 #{success ? "完成" : "未完成"}")
+        write(nil, "Batch finished: succeeded #{succeeded}, partial #{partial}, failed #{failed}, skipped #{skipped}; elapsed #{(monotonic - @started_at).round(1)} seconds; result #{success ? "complete" : "incomplete"}")
       end
 
       # 普通批次提示也复用锁、脱敏和输出故障处理。
@@ -89,7 +89,7 @@ module Net
         unless @verbose
           @mutex.synchronize do
             host = event.fields[:host]
-            @stages[host] = "采集" if @stages.key?(host) && event.name == "login_complete" && event.fields[:status] == "ok"
+            @stages[host] = "collecting" if @stages.key?(host) && event.name == "login_complete" && event.fields[:status] == "ok"
             refresh
           end
           return
@@ -97,16 +97,16 @@ module Net
 
         fields = event.fields
         message = case event.name
-                  when "connect" then "正在连接并登录（#{fields[:protocol]}）"
+                  when "connect" then "Connecting and logging in (#{fields[:protocol]})"
                   when "login_complete"
-                    fields[:status] == "ok" ? "登录成功" : "登录失败（#{fields[:code]}）"
-                  when "connect_failed" then "连接失败（#{fields[:code]}）"
-                  when "command_start" then "执行命令：#{fields[:text]}；等待响应"
+                    fields[:status] == "ok" ? "Login succeeded" : "Login failed (#{fields[:code]})"
+                  when "connect_failed" then "Connection failed (#{fields[:code]})"
+                  when "command_start" then "Executing command: #{fields[:text]}; waiting for response"
                   when "command_complete"
-                    fields[:status] == "response_received" ? "命令响应完成（#{fields[:duration_ms]} ms）" :
-                      "命令失败（#{fields[:code]}）"
+                    fields[:status] == "response_received" ? "Command response complete (#{fields[:duration_ms]} ms)" :
+                      "Command failed (#{fields[:code]})"
                   when "operation_complete"
-                    fields[:status] == "completed" ? "脚本处理完成" : "脚本处理失败（#{fields[:code]}）"
+                    fields[:status] == "completed" ? "Script complete" : "Script failed (#{fields[:code]})"
                   end
         write(fields[:host], message) if message
       end
@@ -151,8 +151,8 @@ module Net
       end
 
       # 显示已保存报告的位置与可读标签。
-      def location(path, label: "报告")
-        write(nil, "#{label}：#{path}")
+      def location(path, label: "report")
+        write(nil, "#{label}: #{path}")
       end
 
       private
@@ -160,15 +160,15 @@ module Net
       # 根据已知错误码返回简短排查建议，不展示任意异常正文。
       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 "设备拒绝命令，请核对厂商映射和账号权限"
-        when :missing_completeness_evidence then "缺少完整性证据，未完成维度见设备报告"
-        when :report_not_saved then "设备报告保存未确认"
+        when :authentication_failed then "Device rejected authentication; check username, password or AAA policy"
+        when :authentication_error then "Authentication dialogue incomplete; check authentication method or device AAA logs"
+        when :host_key_untrusted then "Host key is not yet trusted; verify and register its fingerprint"
+        when :host_key_changed then "Registered host key changed; verify device identity"
+        when :login_timeout then "Login prompt not received before the deadline; check SSH handshake and login dialogue"
+        when :connection_timeout then "SSH connection or handshake timed out; check service and network"
+        when :device_error then "Device rejected the command; check vendor mapping and account permissions"
+        when :missing_completeness_evidence then "Completeness evidence missing; see the device report for incomplete dimensions"
+        when :report_not_saved then "Device report persistence unconfirmed"
         end
       end
 
@@ -176,11 +176,11 @@ module Net
       def status_line
         percent = @total.positive? ? @completed * 100 / @total : 0
         counts = progress_counts
-        "#{@completed}/#{@total} #{percent}% | #{counts} | 登录 #{@stages.values.count("登录")} 采集 #{@stages.values.count("采集")} 排队 #{[@total - @completed - @active, 0].max}"
+        "#{@completed}/#{@total} #{percent}% | #{counts} | Logging in #{@stages.values.count("logging in")} collecting #{@stages.values.count("collecting")} queued #{[@total - @completed - @active, 0].max}"
       end
 
       # 默认统计设备任务，领域适配器可提供自己的计数文案。
-      def progress_counts = "成功 #{@succeeded} 未完成 #{@failed}"
+      def progress_counts = "succeeded #{@succeeded} incomplete #{@failed}"
 
       # 读取单调时钟秒数，避免系统校时影响期限与耗时计算。
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -198,14 +198,14 @@ module Net
         eta = if @completed == @total && @total.positive?
                 "00:00:00"
               elsif @completed >= 5 && rate.positive?
-                "约 #{duration((@total - @completed) / rate)}"
+                "about #{duration((@total - @completed) / rate)}"
               else
-                "估算中"
+                "estimating"
               end
-        line = "耗时 #{duration(elapsed)} | #{format("%.1f", rate)} 台/秒 | 剩余 #{eta}"
+        line = "elapsed #{duration(elapsed)} | #{format("%.1f", rate)} devices/s | remaining #{eta}"
         host, started = @task_started.min_by { |_key, value| value }
         if started && monotonic - started >= 10
-          line += " | 最久 #{host} #{@stages[host]} #{(monotonic - started).floor}s"
+          line += " | longest #{host} #{@stages[host]} #{(monotonic - started).floor}s"
         end
         line
       end
@@ -260,7 +260,7 @@ module Net
 
         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")}] [#{@completed}/#{@total}#{percent} running #{@active}] [#{host || "batch"}] #{message}"
         line = "[#{Time.now.strftime("%H:%M:%S")}] #{host ? "#{host}  " : ""}#{message}" unless @verbose
         write_output(line.gsub(/[[:cntrl:]]/, " ") + "\n")
       end

data/lib/net/connector/resources.rb

@@ -32,7 +32,7 @@ module Net
           Process.setrlimit(:NOFILE, required, hard)
         end
       rescue SystemCallError, ArgumentError, NotImplementedError
-        raise ArgumentError, "本机文件描述符额度不足：#{parallel} 并发至少预留 #{required} 个文件描述符；请提高终端 ulimit -n 或降低 --parallel。已停止，未连接设备。", cause: nil
+        raise ArgumentError, "Insufficient local file descriptor limit: #{parallel} concurrent devices require at least #{required} file descriptors; raise the terminal ulimit -n or lower --parallel. Stopped without connecting to devices.", cause: nil
       end
       private_class_method :reserve!
     end

data/lib/net/connector/storage/atomic_file.rb

@@ -79,24 +79,30 @@ module Net
 
         # 统一返回写入回执；失败时从异常 receipt 判断目录项是否已经替换。
         def self.write(path, contents)
+          write_stream(path) { |file| file.write(contents) }
+        end
+
+        # 借出私有临时文件供分片写入，生产者正常返回后才同步并替换目标。
+        def self.write_stream(path)
           raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+          raise ArgumentError, "a streaming writer block is required" unless block_given?
 
           receipt = Receipt.new(path: File.expand_path(path), state: :not_committed, phase: :resolve_parent)
           directory = File.realpath(File.dirname(receipt.path))
           destination = File.join(directory, File.basename(receipt.path))
           receipt = receipt.with(phase: :temporary_file)
-          Tempfile.create([".net-connector-", ".tmp"], directory) do |file|
+          with_owned_file(-> { Tempfile.create([".net-connector-", ".tmp"], directory) }, temporary: true) do |file|
             file.binmode
             file.chmod(0o600)
             receipt = receipt.with(phase: :write)
-            file.write(contents)
+            yield file
             receipt = receipt.with(phase: :file_sync)
             file.flush
             file.fsync
             receipt = receipt.with(phase: :rename)
             File.rename(file.path, destination)
             receipt = receipt.with(state: :committed, phase: :directory_open)
-            File.open(directory, File::RDONLY | File::NOFOLLOW) do |parent|
+            with_owned_file(-> { File.open(directory, File::RDONLY | File::NOFOLLOW) }) do |parent|
               raise IOError, "parent is not a directory" unless parent.stat.directory?
 
               receipt = receipt.with(phase: :directory_sync)
@@ -118,6 +124,57 @@ module Net
                   end
           raise klass.new(receipt: receipt, underlying_type: error.class.name.to_s), cause: nil
         end
+
+        # 唯一持有本次写入的文件句柄；临时目录项身份在取消递送前登记，退出时保留主控制流。
+        def self.with_owned_file(acquire, temporary: false)
+          file = path = identity = nil
+          completed = false
+          Thread.handle_interrupt(Exception => :never) do
+            file = acquire.call
+            if temporary
+              path = file.path
+              identity = file.stat
+            end
+          end
+          result = yield file
+          completed = true
+          result
+        rescue Exception # rubocop:disable Lint/RescueException -- 正常返回标记之后递送的取消也必须先于清理故障。
+          completed = false
+          raise
+        ensure
+          begin
+            cleanup_file(file, path, identity) if file
+          rescue StandardError, NotImplementedError
+            raise if completed
+          end
+        end
+
+        # 关闭失败仍尝试删除属于本次写入的临时目录项，已替换的同名文件不归本作用域所有。
+        def self.cleanup_file(file, path, identity)
+          Thread.handle_interrupt(Exception => :never) do
+            failure = nil
+            begin
+              file.close unless file.closed?
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 关闭故障不能跳过临时目录项清理。
+              failure = error
+            end
+            begin
+              if path && identity
+                current = File.lstat(path)
+                File.unlink(path) if current.dev == identity.dev && current.ino == identity.ino
+              end
+            rescue Errno::ENOENT
+              # 原子替换已经移走临时目录项，或其他清理已将其删除。
+              nil
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 保留最先发生的清理故障。
+              failure ||= error
+            end
+            raise failure if failure
+          end
+        end
+
+        private_class_method :with_owned_file, :cleanup_file
       end
     end
   end

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.17.2"
+    VERSION = "0.18.1"
   end
 end