net-connector 0.4.1 → 0.5.0

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

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

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    # 日志与报告共用固定诊断词表；未知元数据可能来自配置正文，不能作为自由文本输出。
+    module ErrorMetadata
+      CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
+                           PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
+                           OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
+                           BackupPersistenceError TftpCompletionError].freeze
+      TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
+        %w[StandardError RuntimeError ArgumentError TypeError IOError EOFError SystemCallError ThreadError
+           RangeError KeyError IndexError NoMethodError NameError FrozenError NotImplementedError
+           Timeout::Error IO::TimeoutError Errno::EIO Errno::EACCES Errno::EPERM Errno::ENOSPC Errno::EROFS
+           Errno::ENOENT Errno::ENOTDIR Errno::EISDIR Errno::ELOOP Errno::EINVAL Errno::ENOSYS
+           Errno::ENOTSUP Errno::EOPNOTSUPP Errno::ETIMEDOUT Errno::ECONNREFUSED Errno::ECONNRESET
+           Net::Connector::Storage::PrivateFile::WriteError
+           Net::Connector::Storage::PrivateFile::PersistenceError
+           Net::Connector::Storage::PrivateFile::DirectorySyncUnsupported]).freeze
+      CODES = (CONNECTOR_TYPES.map { |name| name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym } +
+        %i[authentication_failed connection_failed connection_refused no_route connection_reset
+           connection_timeout host_key_changed host_key_untrusted rsa_too_small unsupported_cipher
+           ambiguous_description ambiguous_neighbor confirmation_required description_stages_unsupported
+           description_unconfirmed description_unsupported incomplete_configuration interface_missing
+           neighbor_discovery_unsupported parse_failed invalid_output_encoding persistence_unconfirmed stale_plan startup_config_missing
+           template_invalid template_missing template_unreadable transfer_failed transfer_finalize_failed
+           transfer_path_mismatch transfer_path_unconfirmed transfer_unconfirmed uncommitted_configuration
+           unrecognized_output unsupported_configuration_format verification_plan_changed candidate_isolation_unavailable
+           backup_durability_unsupported backup_finalize_failed backup_persistence_unconfirmed
+           file_finalize_failed file_persistence_unconfirmed file_write_failed directory_sync_unsupported]).freeze
+      PHASES = %i[connect login enable command script read write close logging backup collect discover parse
+                  plan apply verify persist save interact tftp_backup report callback].freeze
+      private_constant :CONNECTOR_TYPES, :TYPES, :CODES, :PHASES
+
+      module_function
+
+      def code(value) = CODES.include?(value) ? value : nil
+
+      def phase(value) = PHASES.include?(value) ? value : nil
+
+      def known_type?(name) = name.instance_of?(String) && TYPES.include?(name)
+
+      def type(name)
+        return if name.nil?
+
+        known_type?(name) ? name.dup.freeze : "StandardError"
+      end
+    end
+  end
+end

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

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
+require "expect/redactor"
+require_relative "error_metadata"
+
 module Net
   module Connector
-    # 操作错误携带已脱敏上下文；原始配置只存在于明确的结果或日志中。
+    # 操作错误携带已脱敏上下文；敏感配置正文只存在于明确返回的业务结果中。
     class Error < StandardError
       attr_reader :code, :host, :phase, :command, :output, :source, :line, :underlying
 
@@ -20,6 +23,19 @@ module Net
         @underlying = underlying
       end
 
+      # 内置错误保留业务回执，但不复制可能含秘密的原生 cause 和调用栈。
+      # 自定义子类重新构造，避免其 message 等方法继续读取未脱敏的私有字段。
+      def with_diagnostics(message:, **context)
+        context = { code: code, host: host, phase: phase, command: command, output: output,
+                    source: source, line: line, underlying: underlying }.merge(context)
+        return self.class.new(message, **context) unless ErrorMetadata.known_type?(self.class.name)
+
+        copy = self.class.allocate
+        instance_variables.each { |name| copy.instance_variable_set(name, instance_variable_get(name)) }
+        Error.instance_method(:initialize).bind_call(copy, message, **context)
+        copy
+      end
+
       # 返回不展开命令和输出的错误摘要。
       def inspect = "#<#{self.class} code=#{code.inspect} phase=#{phase.inspect} host=#{host.inspect}>"
     end
@@ -48,6 +64,8 @@ module Net
 
     class OutputLimitExceeded < Error; end
 
+    class ScriptOutputLimitExceeded < OutputLimitExceeded; end
+
     class SessionBusy < Error; end
 
     class UnsupportedOperation < Error; end
@@ -72,10 +90,16 @@ module Net
       def inspect = "#<#{self.class} type=#{type}>"
     end
 
-    # 每个会话独立保存脱敏词，包括配置凭据和动态认证响应。
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
     class Redactor
+      MASK = "[REDACTED]".b.freeze
+
       # 保存初始凭据，并建立第一版脱敏词表。
       def initialize(*secrets)
+        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
+          raise LoadError, "net-connector requires expect-pty with the public Expect::Redactor API"
+        end
+
         @configured = secrets.compact.map(&:b).map(&:freeze).freeze
         reset
       end
@@ -83,29 +107,32 @@ module Net
       # 重置动态词表，同时保留配置中的固定凭据。
       def reset
         @secrets = []
-        @pattern = nil
+        @patterns = nil
         @scoped = false
         @sensitive = false
+        @output_sensitive = false
         @configured.each { |secret| remember(secret) }
       end
 
       # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
-      def scope(reuse: false)
+      def with_scope(reuse: false)
         return yield if reuse && @scoped
 
         previous = @secrets
-        previous_pattern = @pattern
+        previous_patterns = @patterns
         previous_scoped = @scoped
         previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
         @secrets = previous.dup
         @scoped = true
         begin
           yield
         ensure
           @secrets = previous
-          @pattern = previous_pattern
+          @patterns = previous_patterns
           @scoped = previous_scoped
           @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
         end
       end
 
@@ -115,7 +142,16 @@ module Net
       # 判断当前脱敏范围是否包含敏感交互。
       def sensitive? = @sensitive
 
-      # 记住新的敏感字节，并按长度排序避免短词先匹配。
+      # 输出敏感时不把正文加入词表；只在当前范围内屏蔽日志和任意错误正文。
+      def output_sensitive!
+        @output_sensitive = true
+        sensitive!
+      end
+
+      # 后续查询继承输出边界，即使查询命令本身没有敏感标记。
+      def output_sensitive? = @output_sensitive
+
+      # 只维护当前作用域的注册词；匹配次序和重叠区间交给共享过滤器。
       def remember(secret)
         return if secret.nil? || secret.empty?
 
@@ -123,63 +159,26 @@ module Net
         return if @secrets.include?(bytes)
 
         @secrets << bytes.freeze
-        @secrets.sort_by! { |value| -value.bytesize }
-        @pattern = nil
-      end
-
-      # 保留可能跨下一分片的尾部；完整匹配始终作为整体脱敏。
-      def stream_chunk(bytes, final: false)
-        return [call(bytes), "".b] if final || @secrets.empty?
-
-        retained = [@secrets.first.bytesize, "[REDACTED]".bytesize].max - 1
-        boundary = [bytes.bytesize - retained, 0].max
-        matches(bytes).each do |start, finish|
-          if start < boundary && finish > boundary
-            boundary = start
-            break
-          end
-        end
-        [call(bytes.byteslice(0, boundary)), bytes.byteslice(boundary..)]
+        @patterns = nil
       end
 
-      # 单次扫描替换所有敏感词，并保留已有脱敏标记。
+      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
       def call(text)
-        text = text.to_s.b
-        return text if @secrets.empty?
-
-        output = +"".b
-        offset = 0
-        matches(text).each do |start, finish|
-          output << text.byteslice(offset, start - offset) << "[REDACTED]"
-          offset = finish
-        end
-        output << text.byteslice(offset..)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
       end
 
-      # 返回脱敏器类型摘要。
-      def inspect = "#<#{self.class}>"
-
-      private
-
-      # 前瞻保留重叠匹配；跨标记边界的真实秘密不能被已有标记遮蔽。
-      def pattern
-        @pattern ||= /(?=(#{Regexp.union((@secrets + ["[REDACTED]"]).uniq.sort_by { |secret| -secret.bytesize })}))/n
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
       end
 
-      # 合并重叠的秘密匹配区间，防止替换顺序露出部分凭据。
-      def matches(text)
-        ranges = []
-        text.to_enum(:scan, pattern).each do
-          match = Regexp.last_match
-          start, finish = match.begin(1), match.end(1)
-          if ranges.last && start < ranges.last.last
-            ranges.last[1] = [ranges.last.last, finish].max
-          else
-            ranges << [start, finish]
-          end
-        end
-        ranges
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
       end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
     end
   end
 end

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

@@ -18,36 +18,59 @@ module Net
         @prompt = prompt
         @context = {}
         @steps = []
+        @output_bytes = 0
+        @output_limit = session.configuration.max_script_output_bytes
+        @sensitive = false
       end
 
+      # 汇总实际执行的命令及交互，包括批次准备和厂商追加查询。
+      def sensitive? = @sensitive
+
       # 依次准备、执行和记录脚本命令；失败时保留已完成步骤并统一抛错。
-      def execute(script)
+      def execute_script(script)
         script.each do |original|
-          @session.command_scope(original) do
+          @session.with_command_redaction(original) do
             @current_command = original
             command = @prepare_command.call(original, self)
             next unless command
 
             @current_command = command
             started = Expect.monotonic
-            response = query(command)
-            step = CommandResult.new(command: command, output: response.output, prompt: response.prompt,
-                                     duration: Expect.monotonic - started)
-            steps << step
+            step = nil
+            response = execute_command(command) do |received|
+              step = CommandResult.new(command: command, output: received.output, prompt: received.prompt,
+                                       duration: Expect.monotonic - started)
+              steps << step
+            end
             # 设备已经完成命令；后处理失败也不能从部分结果中抹去其副作用。
             @after_command.call(command, response, self)
             yield step if block_given?
+            check_output_budget!(@last_query_command, completed: true)
           rescue => error
             raise @session.normalize_error(error, phase: :script, command: @current_command), cause: nil
           end
         end
+        check_output_budget!(@last_query_command, completed: true)
         Result.new(steps: steps)
       end
 
       # 厂商后续查询复用同一信道和错误处理，不开启新的批处理。
-      def query(command)
+      def execute_command(command)
         command = Command.new(command) unless command.is_a?(Command)
-        @session.exchange(command, timeout: @command_timeout, prompt: @prompt&.call(command))
+        check_output_budget!(command, completed: false)
+        prompt = @prompt&.call(command)
+        # 提示符回调也可能追加查询，实际发送前重新检查它消耗的预算。
+        check_output_budget!(command, completed: false) if @prompt
+        response = @session.execute_command(command, timeout: @command_timeout, prompt: prompt) do
+          # 必须在 Session 恢复命令词表前读取；最终处理只能继承敏感性，不长期保留秘密。
+          @sensitive ||= @session.redactor.sensitive?
+        end
+        @last_query_command = command
+        @output_bytes += response.raw.bytesize
+        # 主命令先记录完整步骤，再检查超额；追加查询同样计入预算，但不改变原 steps 结构。
+        yield response if block_given?
+        check_output_budget!(command, completed: true)
+        response
       end
 
       # 只有当前会话未特权时才执行特权认证。
@@ -56,8 +79,19 @@ module Net
       end
 
       # 根据当前命令建立脚本阶段错误。
-      def failure(message)
-        @session.error(ScriptError, message, phase: :script, command: @current_command)
+      def build_error(message)
+        @session.build_error(ScriptError, message, phase: :script, command: @current_command)
+      end
+
+      private
+
+      # 单响应上限仍约束正在读取的命令；累计预算阻止继续发送，不承诺设备尚未执行。
+      def check_output_budget!(command, completed:)
+        return unless @output_limit && (completed ? @output_bytes > @output_limit : @output_bytes >= @output_limit)
+
+        raise @session.build_error(ScriptOutputLimitExceeded,
+                             "script output reached max_script_output_bytes; commands already sent may have executed",
+                             phase: :script, command: command), cause: nil
       end
     end
   end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../terminal_renderer"
+require_relative "messages"
+
+module Net
+  module Connector
+    class Log
+      # 在敏感作用域结束前冻结安全副本；应用 formatter 可直接读取字段。
+      class Event
+        attr_reader :name, :fields
+
+        def initialize(name, fields, redactor:)
+          @name = safe_text(name.is_a?(String) || name.is_a?(Symbol) ? name.to_s : "custom", redactor).freeze
+          @fields = fields.each_with_object({}) do |(key, value), result|
+            next unless (key.is_a?(Symbol) || key.is_a?(String)) && key.to_s.match?(/\A[a-z][a-z0-9_]{0,63}\z/)
+            next unless redactor.call(key.to_s) == key.to_s
+            next if key.to_s == "event"
+
+            result[key.to_sym] = safe_value(value, redactor)
+          end.freeze
+          freeze
+        end
+
+        # 与文本呈现共用同一安全记录，调用方不能借 formatter 取得原始秘密。
+        def to_h = { event: name, **fields }.freeze
+
+        def to_s
+          details = to_h.reject { |key, _| key == :host }.map { |key, value| "#{key}=#{token(value)}" }.join(" ")
+          "[host=#{token(fields[:host])}] #{Messages.format(name, fields)} | #{details}"
+        end
+
+        # Ruby Logger 的默认 formatter 对非 String 消息调用 inspect。
+        alias inspect to_s
+
+        private
+
+        def safe_value(value, redactor)
+          case value
+          when String, Symbol
+            safe_text(value.to_s, redactor).freeze
+          when Float
+            value.finite? && redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          when Integer, TrueClass, FalseClass, NilClass
+            redactor.call(value.to_s) == value.to_s ? value : "[REDACTED]"
+          else
+            # 不调用任意对象的 inspect/to_s，避免展开异常、配置对象或容器中的秘密。
+            "[REDACTED]"
+          end
+        end
+
+        def safe_text(text, redactor)
+          rendered = TerminalRenderer.render(redactor.call(text))
+          redactor.call(rendered).force_encoding(Encoding::UTF_8).scrub.gsub(/[[:cntrl:]]+/, " ").strip
+        end
+
+        def token(value)
+          return "nil" if value.nil?
+
+          text = value.to_s
+          text.match?(/\A[A-Za-z0-9_.:\/-]+\z/) ? text : text.inspect
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Net
+  module Connector
+    class Log
+      # 只安装在连接器自有的 Logger 上；注入的日志器保留应用自己的格式。
+      class Formatter < ::Logger::Formatter
+        def call(severity, time, _program, message)
+          "[#{time.getlocal.strftime("%Y-%m-%d %H:%M:%S.%L %:z")}] #{severity} #{message}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Log
+      # 独立于日志目标的人类可读事件文案。
+      module Messages
+        module_function
+
+        # 将结构化会话事件转换为便于人工阅读的中文日志。
+        def format(name, fields)
+          case name
+          when "connect"
+            "开始连接 #{fields[:host]}（#{fields[:protocol].to_s.upcase}，账号 #{fields[:username]}）"
+          when "connect_failed"
+            "连接失败：#{fields[:message]}（#{fields[:error]}）"
+          when "login_start"
+            "等待设备登录提示"
+          when "login_output"
+            "登录过程回显（已脱敏）："
+          when "login_complete"
+            fields[:status] == "ok" ? "登录成功，设备提示符：#{fields[:prompt]}" :
+              "登录失败：#{fields[:message]}（#{fields[:error]}）"
+          when "command_start"
+            "下发命令：#{fields[:text]}"
+          when "device_output"
+            "设备回显："
+          when "command_complete"
+            fields[:status] == "response_received" ? "命令回显结束，已收到设备提示符" :
+              "命令执行失败：#{fields[:message]}（#{fields[:error]}）"
+          when "operation_start"
+            "开始处理设备脚本"
+          when "operation_complete"
+            fields[:status] == "completed" ? "设备脚本处理完成" :
+              "设备脚本处理失败：#{fields[:message]}（#{fields[:error]}）"
+          when "tftp_backup"
+            case fields[:status]
+            when "reported_uploaded"
+              "TFTP 备份：设备报告上传成功，目标 #{fields[:server]}/#{fields[:path]}；服务器文件尚未核验"
+            when "transfer_failed"
+              "TFTP 备份失败：设备报告传输失败，服务器 #{fields[:server]}"
+            else
+              "TFTP 备份未确认：设备未报告上传成功，服务器 #{fields[:server]}"
+            end
+          else
+            name.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Log
+      # 每个目标独占 expect-pty 的过滤流；此层只适配 IO，不实现匹配算法。
+      class RedactingWriter
+        def initialize(target, redactor)
+          @target = target
+          @redactor = redactor
+          @filter = redactor.stream
+        end
+
+        def write(bytes)
+          @filter.patterns = @redactor.patterns
+          @target.write(@filter.append(bytes.b))
+          bytes.bytesize
+        end
+
+        def flush = @target.flush
+
+        def finish
+          @filter.patterns = @redactor.patterns
+          # 配置正文由 Session 的敏感范围隔离；保留完整词匹配的收尾契约。
+          @target.write(@filter.finish(partial: false))
+          flush
+        end
+      end
+
+      # 已渲染、已脱敏的字节按行变成事件，半行在上下文切换前收尾。
+      class Transcript
+        def initialize(&on_line)
+          @on_line = on_line
+          @buffer = +"".b
+        end
+
+        def write(bytes)
+          @buffer << bytes
+          while (ending = @buffer.index("\n"))
+            @on_line.call(@buffer.slice!(0, ending + 1).chomp)
+          end
+          bytes.bytesize
+        end
+
+        def flush; end
+
+        def finish
+          @on_line.call(@buffer) unless @buffer.empty?
+          @buffer = +"".b
+        end
+      end
+
+      private_constant :RedactingWriter, :Transcript
+    end
+  end
+end