net-connector 0.4.1 → 0.5.0

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

@@ -2,9 +2,13 @@
 
 require "fileutils"
 require "logger"
+require "securerandom"
 require_relative "terminal_renderer"
-require_relative "log_messages"
+require_relative "log/event"
+require_relative "log/formatter"
+require_relative "log/stream"
 require_relative "errors"
+require_relative "error_metadata"
 
 module Net
   module Connector
@@ -12,39 +16,56 @@ module Net
     class Log
       LEVELS = { debug: ::Logger::DEBUG, info: ::Logger::INFO,
                  warn: ::Logger::WARN, error: ::Logger::ERROR }.freeze
+      CONTEXT_FIELDS = %w[host session_id operation command_id text source line].freeze
+      private_constant :CONTEXT_FIELDS
 
       # 保存日志配置和敏感信息脱敏器。
       def initialize(configuration, redactor:)
         @configuration = configuration
         @redactor = redactor
+        @context = {}.freeze
       end
 
       # 为会话打开日志文件或应用日志器。
       def open(transport)
         @transport = transport
+        @session_id = SecureRandom.hex(8).freeze
+        @command_sequence = 0
         @io = open_file(@configuration.log_file) if @configuration.log_file
-        @output = RedactingWriter.new(@io, @redactor) if @io
         if @configuration.log_format == :raw
-          @writer = @output
+          @writer = @output = RedactingWriter.new(@io, @redactor) if @io
         elsif @io || @configuration.logger
-          base = @configuration.logger || ::Logger.new(@io)
-          unless @configuration.logger
-            base.formatter = proc do |severity, time, _program, message|
-              "[#{time.getlocal.strftime("%Y-%m-%d %H:%M:%S %:z")}] #{severity} #{message}\n"
-            end
-          end
-          # 前缀直接写入消息，不克隆或修改调用方注入的日志器。
-          @logger = base
-          @event_level = [base.level, LEVELS.fetch(@configuration.log_level)].max
-          @tag = "[host=#{@configuration.host}] "
-          if @io && @configuration.log_level == :debug
-            @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
-          end
+          @logger = @configuration.logger || ::Logger.new(@io, formatter: Formatter.new)
+          open_transcript if @io && @configuration.log_level == :debug
         end
-        @line_open = false
       rescue => error
         close_preserving_error
-        raise failure("unable to open session log", error), cause: nil
+        raise build_error("unable to open session log", error), cause: nil
+      end
+
+      # 上下文只在持有会话锁期间使用；收尾必须先于恢复父上下文。
+      def with_context(**fields)
+        previous = @context
+        finish_output
+        @context = @context.merge(fields).freeze
+        yield
+      ensure
+        begin
+          finish_output
+        ensure
+          @context = previous
+        end
+      end
+
+      def with_operation_context(name, &block)
+        with_context(operation: name || @context[:operation] || :script, &block)
+      end
+
+      def with_command_context(command, &block)
+        @command_sequence += 1
+        with_context(command_id: @command_sequence, phase: :command,
+                     text: command.sensitive? ? "[REDACTED]" : command.text,
+                     source: command.source, line: command.line, &block)
       end
 
       # 将终端回显接入当前会话日志。
@@ -56,60 +77,75 @@ module Net
       end
 
       # 判断当前日志级别是否需要完整设备回显。
-      def detailed? = @configuration.log_level == :debug && !!(@writer || @logger)
+      def debug? = @configuration.log_level == :debug && (!!@writer || enabled?(:debug))
 
       # 按日志级别写入已脱敏的业务事件。
-      def event(name, level: :info, **fields)
+      def log_event(name, level: :info, **fields)
         return unless @logger
 
-        values = fields.transform_values do |value|
-          value.is_a?(String) ? @redactor.call(value).scrub.gsub(/[[:cntrl:]]+/, " ").strip : value
-        end
-        safe_name = @redactor.call(name.to_s).scrub.gsub(/[[:cntrl:]]+/, " ").strip
-        finish_line
-        @logger.public_send(level, "#{@tag}#{LogMessages.format(safe_name, values)}") if LEVELS.fetch(level) >= @event_level
+        finish_output
+        write_event(name, level: level, **fields)
       rescue Error
         raise
       rescue => error
-        raise failure("unable to write session event", error), cause: nil
+        raise build_error("unable to write session event", error), cause: nil
       end
 
-      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
-      def authentication_output(bytes)
-        return unless detailed?
+      # 异常正文由会话先脱敏；类型、错误码和阶段只允许共享词表中的值进入日志。
+      def log_failure(name, failure, phase: nil, **fields)
+        log_event(name, level: :error, **fields,
+                  error: ErrorMetadata.type(failure.class.name) || "StandardError",
+                  code: ErrorMetadata.code(failure.code),
+                  phase: ErrorMetadata.phase(failure.phase) || ErrorMetadata.phase(phase),
+                  message: failure.message)
+      end
 
-        event("login_output", level: :debug)
-        if @writer
-          write(@redactor.call(bytes))
-          flush
+      # 用户钩子可能把未登记的配置片段放进事件名、字段名或值；敏感范围统一隐藏。
+      def log_custom_event(name, level: :info, **fields)
+        if @redactor.sensitive?
+          log_event("custom", level: level, details: "[REDACTED]")
         else
-          response_output(bytes)
+          log_event(name, level: level, **fields)
+        end
+      end
+
+      # 登录完成并收集动态口令后，再记录已脱敏的认证回显。
+      def log_authentication_output(bytes)
+        return unless debug?
+
+        with_context(phase: :login) do
+          log_event("login_output", level: :debug)
+          if @writer
+            write(@redactor.call(bytes))
+            flush
+          else
+            log_response_output(bytes)
+          end
         end
       end
 
-      # 应用注入的日志器没有终端写入器，改由日志器记录完整回显。
-      def response_output(bytes)
-        return unless detailed? && !@writer
+      # 注入日志器与文件回显共用事件格式；两次脱敏覆盖终端控制符拼接。
+      def log_response_output(bytes)
+        return unless debug? && !@writer && !@redactor.output_sensitive?
 
         @redactor.call(TerminalRenderer.render(@redactor.call(bytes))).each_line do |line|
-          @logger.debug("#{@tag}  #{line.chomp}") if ::Logger::DEBUG >= @event_level
+          write_event("device_output", level: :debug, output: line.chomp)
         end
       rescue Error
         raise
       rescue => error
-        raise failure("unable to write device output", error), cause: nil
+        raise build_error("unable to write device output", error), cause: nil
       end
 
       # 向终端日志写入已处理的回显字节。
       def write(bytes)
-        return unless @writer
+        return unless @writer && !@redactor.output_sensitive?
 
         @writer.write(bytes)
-        @line_open = !bytes.end_with?("\n") unless bytes.empty?
       rescue Error
         raise
       rescue => error
-        raise failure("unable to write session log", error), cause: nil
+        raise build_error("unable to write session log", error), cause: nil
       end
 
       # 刷新日志缓冲区。
@@ -119,7 +155,7 @@ module Net
       rescue Error
         raise
       rescue => error
-        raise failure("unable to flush session log", error), cause: nil
+        raise build_error("unable to flush session log", error), cause: nil
       end
 
       # 执行代码块期间暂停自动记录传输回显。
@@ -140,62 +176,48 @@ module Net
           begin
             @io&.close
           ensure
-            @writer = @output = @logger = @io = @transport = @tag = @event_level = nil
+            @writer = @output = @transcript = @logger = @io = @transport = @session_id = nil
             @attached = false
           end
         end
       rescue Error
         raise
       rescue => error
-        raise failure("unable to close session log", error), cause: nil
+        raise build_error("unable to close session log", error), cause: nil
       end
 
       private
 
-      # 结束未换行的回显，保持事件独占一行。
-      def finish_line
-        return unless @writer
+      # 每次读取调用方的当前阈值，不缓存级别、不改写共享 Logger。
+      def enabled?(level)
+        @logger && LEVELS.fetch(level) >= [@logger.level, LEVELS.fetch(@configuration.log_level)].max
+      end
+
+      def write_event(name, level:, **fields)
+        return unless enabled?(level)
 
-        finish_output
-        @io.write("\n") if @line_open
-        @line_open = false
+        values = @context.compact.merge(fields.reject { |key, _| CONTEXT_FIELDS.include?(key.to_s) })
+        values = values.merge(host: @configuration.host, session_id: @session_id)
+        @logger.public_send(level, Event.new(name, values, redactor: @redactor))
       end
 
-      # 先完成终端渲染，再写出脱敏流的最后几个字节。
+      def open_transcript
+        @transcript = Transcript.new { |line| write_event("device_output", level: :debug, output: line) }
+        @output = RedactingWriter.new(@transcript, @redactor)
+        @writer = TerminalRenderer.new(@output, max_line_bytes: @configuration.max_output_bytes)
+      end
+
+      # 先渲染，再结束过滤流，最后发出半行事件；顺序不能反转。
       def finish_output
         @writer.finish if @writer.respond_to?(:finish)
         @output&.finish unless @output.equal?(@writer)
+        @transcript&.finish
+      rescue Error
+        raise
+      rescue => error
+        raise build_error("unable to finish session output", error), cause: nil
       end
 
-      # 文件写入边界保留短尾部，避免分片或终端控制符拼出明文凭据。
-      class RedactingWriter
-        # 保存目标流、脱敏器和等待下一分片的尾部。
-        def initialize(target, redactor)
-          @target = target
-          @redactor = redactor
-          @pending = "".b
-        end
-
-        # 写入已确认安全的前缀，暂存可能与下一分片组成秘密的尾部。
-        def write(bytes)
-          @pending << bytes.b
-          safe, @pending = @redactor.stream_chunk(@pending)
-          @target.write(safe)
-          bytes.bytesize
-        end
-
-        # 刷新目标流，仍不提前写出待判断的尾部。
-        def flush = @target.flush
-
-        # 在日志结束时脱敏并写出剩余尾部。
-        def finish
-          safe, @pending = @redactor.stream_chunk(@pending, final: true)
-          @target.write(safe)
-          flush
-        end
-      end
-      private_constant :RedactingWriter
-
       # 以私有权限打开设备日志文件。
       def open_file(path)
         FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
@@ -223,8 +245,9 @@ module Net
       end
 
       # 将日志异常包装成统一错误并保留脱敏原因。
-      def failure(message, error)
-        LogError.new(message, phase: :logging, underlying: UnderlyingError.new(error, @redactor))
+      def build_error(message, error)
+        LogError.new(message, phase: :logging,
+                     underlying: UnderlyingError.new(error, @redactor, sensitive: @redactor.sensitive?))
       end
     end
   end

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

@@ -10,6 +10,8 @@ module Net
   module Connector
     # 连接状态、传输层和日志的唯一所有者；同一时刻只允许一个操作占用会话。
     class Session
+      MAX_ERROR_OUTPUT_BYTES = 4096
+
       attr_reader :configuration, :transport, :reader, :redactor, :state, :prompt
 
       # 创建认证、响应读取、脱敏和日志对象，并把会话置于关闭状态。
@@ -38,7 +40,22 @@ module Net
       def mark_privileged! = @privileged = true
 
       # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
-      def log_event(name, **fields) = @log.event(name, **fields)
+      def log_event(name, **fields) = @log.log_custom_event(name, **fields)
+
+      # 业务名称贯穿脚本及其钩子，底层命令另外分配独立序号。
+      def log_script(operation:, steps:)
+        @log.with_operation_context(operation) do
+          started = Expect.monotonic
+          @log.log_event("operation_start", level: :debug, phase: :script)
+          result = yield
+          log_operation_completion(started, result.is_a?(Result) ? result.error : nil, steps: steps.size)
+          result
+        rescue => error
+          failure = normalize_error(error, phase: :script)
+          log_operation_completion(started, failure, steps: steps.size)
+          raise failure, cause: nil
+        end
+      end
 
       # 在会话锁内建立连接。
       def connect
@@ -51,7 +68,7 @@ module Net
           return perform_locked(phase) { yield }
         end
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
 
         begin
@@ -64,17 +81,31 @@ module Net
       # 业务操作在多次脚本之间持有租约；只有同一线程和 Fiber 可顺序使用。
       def with_operation(phase)
         unless @lock.try_lock
-          raise error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
+          raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
         @operation_owner = [Thread.current, Fiber.current]
+        result = nil
         begin
-          yield
+          @log.with_operation_context(phase) { result = yield }
+        rescue Error => error
+          raise unless result.is_a?(Result)
+
+          # 日志收尾失败不能抹去已完成的设备步骤，也不能覆盖原业务错误。
+          Result.new(steps: result.steps, config: result.config,
+                     error: result.error || normalize_error(error, phase: phase))
         ensure
           @operation_owner = nil
           @lock.unlock
         end
       end
 
+      # 文件业务必须先取得路径锁，再调用会话；不能持有会话租约去等待另一个备份者。
+      def assert_path_lock_order!(phase)
+        return unless @lock.locked?
+
+        raise build_error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
+      end
+
       # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
       def perform_locked(phase)
         @performing = true
@@ -109,7 +140,7 @@ module Net
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
         unless @lock.try_lock
-          raise error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
+          raise build_error(SessionBusy, "cannot close a session owned by another operation", phase: :close), cause: nil
         end
 
         begin
@@ -122,7 +153,7 @@ module Net
       # 执行特权认证，并更新提示符及特权状态。
       def enable(command, prompt)
         unless command
-          raise error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
+          raise build_error(UnsupportedOperation, "privilege authentication is not supported", phase: :enable), cause: nil
         end
 
         @privileged = false
@@ -133,38 +164,71 @@ module Net
       end
 
       # 命令准备、交换、后处理及回调共用一份临时词表，退出时一并清除。
-      def command_scope(command)
-        redactor.scope do
+      def with_command_redaction(command)
+        redactor.with_scope do
           protect_command(command)
           yield
         end
       end
 
+      # 批次准备和最终清理也可能读取配置；在作用域退出前归一化其异常，
+      # 防止清理钩子的消息或回溯将已完成步骤中的正文带回诊断通道。
+      def with_sensitive_output(enabled)
+        return yield unless enabled
+
+        redactor.with_scope do
+          redactor.output_sensitive!
+          yield
+        rescue => error
+          raise normalize_error(error, phase: :script), cause: nil
+        end
+      end
+
       # 复用完整命令的脱敏范围；厂商后续查询产生的秘密保留到外层回调结束。
-      def exchange(command, timeout:, prompt: nil)
-        redactor.scope(reuse: true) do
+      def execute_command(command, timeout:, prompt: nil)
+        redactor.with_scope(reuse: true) do
           protect_command(command)
-          started = Expect.monotonic
-          @log.event("command_start", text: command.sensitive? ? "[REDACTED]" : command.text)
-          sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
-          @log.event("device_output", level: :debug) if @log.detailed? && !command.sensitive? && !sensitive_dialogue
-          response = exchange_command(command, timeout: timeout, prompt: prompt)
-          @log.response_output(response.raw) unless command.sensitive? || sensitive_dialogue
-          @log.event("command_complete", status: "response_received")
-          @log.event("command_detail", level: :debug,
-                     duration_ms: ((Expect.monotonic - started) * 1000).round,
-                     response_bytes: response.raw.bytesize)
-          response
-        rescue => error
-          failure = normalize_error(error, phase: :command, command: command)
-          @log.event("command_complete", level: :error, status: "failed",
-                     error: failure.class.name, message: failure.message)
-          raise failure, cause: nil
+          @log.with_command_context(command) { execute_command_with_logging(command, timeout: timeout, prompt: prompt) }
+        ensure
+          # 失败的敏感探测也可能被钩子捕获后继续；离开作用域前始终通知执行器。
+          yield if block_given?
         end
       end
 
+      def execute_command_with_logging(command, timeout:, prompt:)
+        started = Expect.monotonic
+        @log.log_event("command_start")
+        sensitive_dialogue = [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
+        private_output = command.sensitive? || redactor.output_sensitive? || sensitive_dialogue
+        @log.log_event("device_output", level: :debug) if @log.debug? && !private_output
+        response = exchange_command(command, timeout: timeout, prompt: prompt)
+        @log.log_response_output(response.raw) unless private_output
+        details = { duration_ms: elapsed_ms(started), response_bytes: response.raw.bytesize }
+        @log.log_event("command_complete", status: "response_received", **details)
+        response
+      rescue => error
+        failure = normalize_error(error, phase: :command, command: command)
+        @log.log_failure("command_complete", failure, status: "failed", duration_ms: elapsed_ms(started), phase: :command)
+        raise failure, cause: nil
+      end
+
+      def elapsed_ms(started) = ((Expect.monotonic - started) * 1000).round
+
+      def log_operation_completion(started, failure, steps: nil)
+        fields = { status: failure ? "failed" : "completed", duration_ms: elapsed_ms(started), steps: steps,
+                   phase: :script }
+        if failure
+          @log.log_failure("operation_complete", failure, **fields, failed_command: failure.command)
+        else
+          @log.log_event("operation_complete", **fields)
+        end
+      end
+
+      private :execute_command_with_logging, :elapsed_ms, :log_operation_completion
+
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
+        redactor.output_sensitive! if command.output_sensitive?
         if command.sensitive? || [*command.interactions, *@dialogue.command_interactions].any?(&:sensitive?)
           redactor.sensitive!
         end
@@ -184,12 +248,12 @@ module Net
                                  deadline: deadline, phase: :command, command: command)
           @prompt = response.prompt
           if (diagnostic = @dialogue.diagnostic(response.raw))
-            raise error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
+            raise build_error(DeviceError, diagnostic, phase: :command, command: command, output: response.raw), cause: nil
           end
 
           response
         end
-        if command.sensitive? || interactions.any?(&:sensitive?)
+        if command.sensitive? || redactor.output_sensitive? || interactions.any?(&:sensitive?)
           @log.pause(&operation)
         else
           operation.call
@@ -219,33 +283,33 @@ module Net
       end
 
       # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
-      def error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
-        sensitive = redactor.sensitive? || command&.sensitive?
+      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
         message = safe_error_text(message, sensitive: sensitive)
         output = safe_error_text(output, sensitive: sensitive)
         klass.new(message, host: configuration.host, phase: phase,
                   command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
                   source: command&.source, line: command&.line,
-                  output: output.byteslice(-4096, 4096) || output,
+                  output: truncate_output(output),
                   underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
       end
 
       # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
       def normalize_error(exception, phase:, command: nil)
         if exception.is_a?(Error)
-          sensitive = redactor.sensitive? || command&.sensitive?
+          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
           failed_command = exception.command || command&.text
           if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
             failed_command = "[REDACTED]"
           end
           message = safe_error_text(exception.message, sensitive: sensitive)
           output = safe_error_text(exception.output, sensitive: sensitive)
-          return exception.class.new(
-            message, code: exception.code,
+          return exception.with_diagnostics(
+            message: message,
             host: exception.host || configuration.host, phase: exception.phase || phase,
             command: failed_command && redactor.call(failed_command),
             source: exception.source || command&.source, line: exception.line || command&.line,
-            output: output.byteslice(-4096, 4096) || output,
+            output: truncate_output(output),
             underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
           )
         end
@@ -255,7 +319,7 @@ module Net
                 when IOError, SystemCallError, Expect::SpawnError then TransportError
                 else InternalError
                 end
-        error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
       end
 
       # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
@@ -265,6 +329,13 @@ module Net
 
       private :safe_error_text
 
+      # 必须先脱敏再截取尾部，避免截断凭据后逃过完整词匹配。
+      def truncate_output(text)
+        text.byteslice(-MAX_ERROR_OUTPUT_BYTES, MAX_ERROR_OUTPUT_BYTES) || text
+      end
+
+      private :truncate_output
+
       # 返回不包含凭据的会话状态摘要。
       def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
 
@@ -275,27 +346,28 @@ module Net
         attempted_recovery = false
         begin
           @state = :connecting
+          started = Expect.monotonic
           redactor.reset
           @log.open(transport)
-          @log.event("connect", host: configuration.host, username: configuration.username,
-                     protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+          @log.log_event("connect", host: configuration.host, username: configuration.username,
+                     phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
           transport.open
           @state = :authenticating
-          @log.event("login_start", level: :debug)
+          @log.log_event("login_start", level: :debug, phase: :login)
           response = @authentication.login
           safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
                                        prompt: response.prompt)
           @prompt = response.prompt
           @after_login.call(self, safe_response)
-          @log.authentication_output(response.raw)
-          @log.event("login_complete", status: "ok", prompt: response.prompt)
+          @log.log_authentication_output(response.raw)
+          @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
           @log.attach
           @state = :ready
         rescue => error
           phase = (@state == :connecting) ? :connect : :login
           failure = normalize_error(error, phase: phase)
-          @log.event(phase == :connect ? "connect_failed" : "login_complete", level: :error,
-                     status: "failed", error: failure.class.name, message: failure.message, phase: phase)
+          @log.log_failure(phase == :connect ? "connect_failed" : "login_complete", failure,
+                           status: "failed", phase: phase, duration_ms: elapsed_ms(started))
           close_preserving_failure
           replacement = attempted_recovery ? nil : @recovery.recover(failure, transport)
           if replacement

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

@@ -8,20 +8,21 @@ module Net
     # 把终端编辑控制符渲染成可读、兼容 UTF-8 和二进制的逐行日志。
     class TerminalRenderer
       # 将字节流完整渲染为字符串，供测试和一次性转换使用。
-      def self.render(input)
+      def self.render(input, strict_utf8: false)
         output = StringIO.new("".b)
-        renderer = new(output)
+        renderer = new(output, strict_utf8: strict_utf8)
         renderer.write(input)
         renderer.finish
         output.string
       end
 
       # 初始化当前行、光标和转义序列状态。
-      def initialize(target, max_line_bytes: 32 * 1024 * 1024)
+      def initialize(target, max_line_bytes: 32 * 1024 * 1024, strict_utf8: false)
         raise ArgumentError, "target must respond to write" unless target.respond_to?(:write)
         unless max_line_bytes.is_a?(Integer) && max_line_bytes.positive?
           raise ArgumentError, "max_line_bytes must be positive"
         end
+        raise ArgumentError, "strict_utf8 must be true or false" unless [true, false].include?(strict_utf8)
 
         @target = target
         @line = "".b
@@ -29,6 +30,7 @@ module Net
         @escape_state = nil
         @csi_parameters = "".b
         @max_line_bytes = max_line_bytes
+        @strict_utf8 = strict_utf8
       end
 
       # 逐字节消费终端输出，并返回输入字节数。
@@ -146,10 +148,11 @@ module Net
         @cursor = 0
       end
 
-      # 尽量保持有效 UTF-8；非法字节转义为可读的十六进制文本。
+      # 日志把非法字节转义；解析必须拒绝终端编辑产生的损坏字节，不能制造可写业务证据。
       def utf8_safe(line)
         text = line.dup.force_encoding(Encoding::UTF_8)
         return text.b if text.valid_encoding?
+        raise Encoding::InvalidByteSequenceError, "terminal editing produced invalid UTF-8" if @strict_utf8
 
         text.scrub { |invalid| invalid.bytes.map { |byte| format("\\x%02X", byte) }.join }.b
       end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "terminal_renderer"
+require_relative "errors"
+
+module Net
+  module Connector
+    # 设备/文件提供的是字节，不受 Ruby 源文件编码控制。解析边界只接受 UTF-8，
+    # 不猜测编码、不改写原文，也不让终端编辑把非法字节抹掉后变成可信证据。
+    module TerminalText
+      def self.utf8(bytes, host: nil)
+        raise ArgumentError, "text must be a String" unless bytes.is_a?(String)
+
+        text = bytes.b.force_encoding(Encoding::UTF_8)
+        invalid_encoding!(host) unless text.valid_encoding?
+        text
+      end
+
+      def self.render(bytes, host: nil)
+        TerminalRenderer.render(utf8(bytes, host: host), strict_utf8: true).force_encoding(Encoding::UTF_8)
+      rescue Encoding::InvalidByteSequenceError
+        invalid_encoding!(host)
+      end
+
+      def self.invalid_encoding!(host)
+        raise ParsingError.new("device output is not valid UTF-8", code: :invalid_output_encoding,
+                               host: host, phase: :parse), cause: nil
+      end
+
+      private_class_method :invalid_encoding!
+    end
+  end
+end