netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/backup.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    Backup = Data.define(:path, :bytes, :sha256, :collected_at, :change, :previous_sha256) do
+      # 保存配置备份的路径、摘要和变更状态。
+      def initialize(path:, bytes:, sha256:, collected_at:, change: nil, previous_sha256: nil)
+        super
+      end
+
+      # 判断本次采集是否产生新的配置内容。
+      def changed? = [:created, :changed].include?(change)
+    end
+  end
+end

data/lib/netstack/connector/backup_busy.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    class BackupBusy < Error; end
+  end
+end

data/lib/netstack/connector/backup_persistence_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "digest"
+
+module Netstack
+  module Connector
+    # 只携带库自身的提交回执和配置元数据，不携带正文或原始文件系统异常。
+    class BackupPersistenceError < Error
+      attr_reader :backup, :receipt, :underlying_type
+
+      def initialize(backup:, write_error:, host: nil)
+        unless backup.instance_of?(Backup) && Storage::PrivateFile.receipt_error?(write_error) &&
+               write_error.receipt.committed? && write_error.receipt.path == backup.path
+          raise ArgumentError, "backup persistence error requires a matching committed backup receipt"
+        end
+
+        @backup, @receipt = backup, write_error.receipt
+        @underlying_type = write_error.underlying_type
+        code = if write_error.instance_of?(Storage::PrivateFile::DirectorySyncUnsupported)
+                 :backup_durability_unsupported
+               elsif receipt.durable?
+                 :backup_finalize_failed
+               else
+                 :backup_persistence_unconfirmed
+               end
+        super(write_error.message, code: code, host: host, phase: :backup)
+      end
+    end
+  end
+end

data/lib/netstack/connector/command.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 一条设备命令行，可附带独立截止时间和交互规则。
+    class Command
+      attr_reader :text, :timeout, :interactions, :prompt, :source, :line
+
+      # 在任何输入输出前校验命令、提示、交互和敏感标记，并冻结命令。
+      def initialize(text, timeout: nil, interactions: [], prompt: nil, sensitive: false, output_sensitive: false,
+                     source: nil, line: nil)
+        unless text.is_a?(String) && !text.strip.empty? && !text.match?(/[\r\n\x00]/)
+          raise ScriptError.new("a command must contain exactly one nonempty CLI line", phase: :parse,
+                                source: source, line: line)
+        end
+        unless interactions.is_a?(Array) && interactions.all?(Interaction)
+          raise ArgumentError, "interactions must be an Array of Interaction objects"
+        end
+        valid_prompt = prompt.nil? || (prompt.is_a?(Regexp) && !prompt.match?(""))
+        unless valid_prompt
+          raise ArgumentError, "prompt must be a nonempty Regexp or nil"
+        end
+        raise ArgumentError, "sensitive must be true or false" unless [true, false].include?(sensitive)
+        raise ArgumentError, "output_sensitive must be true or false" unless [true, false].include?(output_sensitive)
+
+        @text = text.dup.freeze
+        @timeout = Expect.duration(timeout)
+        @interactions = interactions.dup.freeze
+        @prompt = prompt
+        @sensitive = sensitive
+        @output_sensitive = output_sensitive
+        @source = source&.dup&.freeze
+        @line = line
+        freeze
+      end
+
+      # 判断命令文本是否需要脱敏。
+      def sensitive? = @sensitive
+
+      # 响应正文可能包含尚未登记的秘密，与命令文本是否敏感无关。
+      def output_sensitive? = @output_sensitive
+
+      # 复制命令元数据，只替换命令文本。
+      def with_text(text)
+        self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
+                       sensitive: sensitive?, output_sensitive: output_sensitive?, source: source, line: line)
+      end
+
+      # 配置采集保留调用方的全部命令元数据，只收紧输出的诊断边界。
+      def with_output_sensitive
+        self.class.new(text, timeout: timeout, interactions: interactions, prompt: prompt,
+                       sensitive: sensitive?, output_sensitive: true, source: source, line: line)
+      end
+
+      # 返回命令来源摘要，不展开命令内容。
+      def inspect = "#<#{self.class} source=#{source.inspect} line=#{line.inspect}>"
+    end
+  end
+end

data/lib/netstack/connector/command_result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 一条已完成命令的结果；后续命令失败时仍保留已完成步骤。
+    class CommandResult
+      attr_reader :command, :output, :prompt, :duration
+
+      # 保存命令输出、提示符和耗时，并冻结结果。
+      def initialize(command:, output:, prompt:, duration:)
+        @command = command
+        @output = output.frozen? ? output : output.dup.freeze
+        @prompt = prompt&.dup&.freeze
+        @duration = duration
+        freeze
+      end
+
+      # 返回输出字节数和耗时摘要。
+      def inspect = "#<#{self.class} bytes=#{output.bytesize} duration=#{duration.round(6)}>"
+    end
+  end
+end

data/lib/netstack/connector/command_timeout.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class CommandTimeout < Error; end
+  end
+end

data/lib/netstack/connector/configuration.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 显式且不可变的连接设置；环境变量读取由调用库的可执行程序负责。
+    class Configuration
+      attr_reader :host, :username, :password, :enable_password, :protocol, :port, :login_timeout,
+                  :command_timeout, :write_timeout, :max_output_bytes, :max_script_output_bytes, :log_file, :log_format, :log_level,
+                  :known_hosts, :host_key_policy, :challenges, :logger, :on_event
+
+      # 校验端点、凭据、超时、日志、主机密钥和挑战配置，然后冻结设置。
+      def initialize(host: nil, username: nil, password: nil, enable_password: nil, protocol: :ssh, port: nil,
+                     login_timeout: 10, command_timeout: nil, write_timeout: 10,
+                     max_output_bytes: 32 * 1024 * 1024, max_script_output_bytes: nil, log_file: nil, logger: nil,
+                     log_format: :text, log_level: :info, on_event: nil,
+                     known_hosts: nil, host_key_policy: :strict, telnet_fallback: false, legacy_ssh: false,
+                     challenges: [])
+        @host = frozen_string(host)
+        @username = frozen_string(username)
+        @password = single_line_credential(password)
+        @enable_password = single_line_credential(enable_password)
+        @protocol = enum_value(protocol, %i[ssh telnet], :protocol)
+        @port = port
+        valid_port = port.nil? || (port.is_a?(Integer) && (1..65_535).cover?(port))
+        unless valid_port
+          raise ArgumentError, "port must be in 1..65535"
+        end
+
+        @login_timeout = timeout_seconds(login_timeout, :login_timeout)
+        @command_timeout = command_timeout.nil? ? nil : timeout_seconds(command_timeout, :command_timeout)
+        @write_timeout = timeout_seconds(write_timeout, :write_timeout)
+        @max_output_bytes = positive_integer(max_output_bytes, :max_output_bytes)
+        @max_script_output_bytes = positive_integer(max_script_output_bytes, :max_script_output_bytes) unless max_script_output_bytes.nil?
+        @log_file = absolute_path(log_file)
+        if logger && (!logger.respond_to?(:debug) || !logger.respond_to?(:info) ||
+          !logger.respond_to?(:warn) || !logger.respond_to?(:error) ||
+          !logger.respond_to?(:level))
+          raise ArgumentError, "logger must be Logger-compatible"
+        end
+        raise ArgumentError, "logger and log_file cannot be combined" if logger && @log_file
+        @log_format = enum_value(log_format, %i[raw text], :log_format)
+        raise ArgumentError, "logger cannot be combined with raw logging" if logger && @log_format == :raw
+
+        @logger = logger
+        raise ArgumentError, "on_event must respond to call" if on_event && !on_event.respond_to?(:call)
+
+        @on_event = on_event
+        @log_level = enum_value(log_level, %i[debug info warn error], :log_level)
+        @known_hosts = absolute_path(known_hosts)
+        @host_key_policy = enum_value(host_key_policy, %i[strict accept_new replace], :host_key_policy)
+        if @host_key_policy == :replace && !@known_hosts
+          raise ArgumentError, "host_key_policy :replace requires an explicit known_hosts file"
+        end
+
+        @telnet_fallback = boolean_value(telnet_fallback)
+        @legacy_ssh = boolean_value(legacy_ssh)
+        unless challenges.is_a?(Array) && challenges.all?(Interaction)
+          raise ArgumentError, "challenges must be an Array of Interaction objects"
+        end
+
+        @challenges = challenges.dup.freeze
+        freeze
+      end
+
+      # 判断是否允许 SSH 失败后回退到 Telnet。
+      def telnet_fallback? = @telnet_fallback
+
+      # 判断是否允许使用旧版 SSH 协商参数恢复。
+      def legacy_ssh? = @legacy_ssh
+
+      # 校验最终连接主机和用户名能安全进入外部命令参数。
+      def validate_endpoint!
+        unless host.is_a?(String) && /\A[A-Za-z0-9:][A-Za-z0-9.:%_-]*\z/.match?(host)
+          raise ArgumentError, "host must be a device address or hostname"
+        end
+        return if username.is_a?(String) && /\A[A-Za-z0-9_][A-Za-z0-9_.@$\\-]*\z/.match?(username)
+
+        raise ArgumentError, "username is empty or contains unsupported characters"
+      end
+
+      # 返回不包含凭据的连接配置摘要。
+      def inspect = "#<#{self.class} host=#{host.inspect} protocol=#{protocol.inspect}>"
+
+      private
+
+      def positive_integer(value, name)
+        raise ArgumentError, "#{name} must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
+      # 将可选值校验为字符串副本。
+      def frozen_string(value)
+        return nil if value.nil?
+        raise ArgumentError, "expected a String or nil" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      # 校验凭据是单行文本。
+      def single_line_credential(value)
+        value = frozen_string(value)
+        raise ArgumentError, "credentials must be a single line" if value&.match?(/[\r\n\x00]/)
+
+        value
+      end
+
+      # 将路径转换为绝对冻结文本。
+      def absolute_path(value) = value.nil? ? nil : File.expand_path(frozen_string(value)).freeze
+
+      # 将超时转换为有限秒数。
+      def timeout_seconds(value, name)
+        result = Expect.duration(value)
+        raise ArgumentError, "#{name} must be finite" unless result
+
+        result
+      end
+
+      # 校验布尔设置只能是 true 或 false。
+      def boolean_value(value)
+        raise ArgumentError, "expected true or false" unless [true, false].include?(value)
+
+        value
+      end
+
+      # 将枚举输入转换为允许的符号。
+      def enum_value(value, choices, name)
+        return value.to_sym if value.respond_to?(:to_sym) && choices.include?(value.to_sym)
+
+        raise ArgumentError, "#{name} must be one of #{choices.join(", ")}"
+      end
+    end
+  end
+end

data/lib/netstack/connector/connection_closed.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class ConnectionClosed < ConnectionError; end
+  end
+end

data/lib/netstack/connector/connection_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class ConnectionError < Error; end
+  end
+end

data/lib/netstack/connector/device.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "forwardable"
+
+module Netstack
+  module Connector
+    # 设备连接门面；厂商子类提供语法和钩子，组合对象负责实际执行。
+    class Device
+      extend Forwardable
+      include RunningConfig::Capability
+      include SaveConfig
+      include LocalBackup::Capability
+      include Tftp::Capability
+      include Topology::Capability
+      include TextFSM::Capability
+
+      attr_reader :configuration, :command_timeout
+
+      def_delegators :@session, :connected?, :privileged?, :state
+      def_delegators :@configuration, :host, :username, :log_file
+
+      class << self
+        def vendor(key = nil)
+          return @vendor = key if key
+
+          @vendor || (superclass.vendor if superclass.respond_to?(:vendor))
+        end
+
+        # 在子类中声明设备规则；没有块时返回当前类继承到的档案。
+        def profile(&definition)
+          return inherited_profile unless definition
+
+          @profile = Profile.define(parent: inherited_profile, &definition)
+        end
+
+        # 让子类共享不可变父档案，子类声明时再生成自己的副本。
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@profile, profile)
+        end
+
+        private
+
+        # 查找当前类或最近父类的设备档案。
+        def inherited_profile
+          return @profile if instance_variable_defined?(:@profile)
+
+          parent = superclass
+          parent.respond_to?(:profile) ? parent.profile : nil
+        end
+      end
+
+      # 连接设备并执行代码块；无论正常返回、break、异常还是中断，都会释放会话资源。
+      def self.open(**)
+        raise ArgumentError, "open requires a block" unless block_given?
+
+        device = new(**)
+        failed = false
+        begin
+          device.connect
+          yield device
+        rescue Exception # rubocop:disable Lint/RescueException -- Preserve failures from this block, including interrupts, through cleanup.
+          failed = true
+          raise
+        ensure
+          begin
+            device.close
+          rescue StandardError
+            raise unless failed
+          end
+        end
+      end
+
+      # 校验连接配置，创建对话语法、传输层、恢复器和会话对象。
+      def initialize(configuration: nil, transport: nil, **settings)
+        if configuration
+          raise ArgumentError, "configuration cannot be combined with settings" unless settings.empty?
+          raise ArgumentError, "configuration must be a Configuration" unless configuration.is_a?(Configuration)
+        end
+        @configuration = configuration || Configuration.new(**settings)
+        @command_timeout = @configuration.command_timeout || default_command_timeout
+        @dialogue = build_dialogue
+        transport ||= Transports.build(@configuration, terminal_size: terminal_size)
+        @session = Session.new(configuration: @configuration, dialogue: @dialogue, transport: transport,
+                               recovery: Recovery.new(@configuration, legacy_arguments: legacy_ssh_arguments),
+                               after_login: method(:after_login))
+      end
+
+      # 返回当前连接器使用的不可变设备档案，便于检查厂商声明。
+      def profile = self.class.profile || Profile.default
+
+      def vendor = self.class.vendor
+
+      # 只查询实现能力，不连接设备；不代表现场权限或固件验证成功。
+      def supports?(capability)
+        capability = capability.to_sym if capability.is_a?(String)
+        case capability
+        when :running_config, :backup
+          !config_commands.empty?
+        when :save_config
+          !save_commands.empty?
+        when :tftp_backup
+          !profile.tftp_strategy.nil?
+        when :neighbors, :interface_descriptions, :interface_description_changes
+          !!profile.topology_strategy&.supports?(capability)
+        else
+          false
+        end
+      rescue NotImplementedError
+        false
+      end
+
+      # 建立会话并返回当前设备对象。
+      def connect
+        @session.connect
+        self
+      end
+
+      # 关闭会话及其传输资源。
+      def close = @session.close
+
+      # 将一条文本命令包装成脚本并执行。
+      def execute_command(text, **, &)
+        execute_script(Script.new([Command.new(text, **)]), &)
+      end
+
+      # 接收脚本或命令数组，统一交给单次会话执行。
+      def execute_script(script, &)
+        script = Script.new(script) unless script.is_a?(Script)
+        perform_script(script, &)
+      end
+
+      # 多步骤业务操作独占当前会话，内部脚本仍禁止回调重入。
+      def with_operation(name, &) = @session.with_operation(name, &)
+
+      # 业务层可扩展脚本准备、响应校验和最终结果，所有钩子均在会话锁内执行。
+      def execute_operation(script, name:, prompt: nil, after_command: nil, privilege: true, &finalize)
+        perform_script(script, operation: name, prompt: prompt, after_command: after_command,
+                       privilege: privilege, finalize: finalize)
+      end
+
+      # 返回已确认的提示，供业务层为只读采集绑定准确的结束条件。
+      def current_prompt = @session.prompt
+
+      # 将业务事件写入当前设备会话日志。
+      def log_event(name, **details)
+        @session.log_event(name, **details)
+      end
+
+      # 进入特权模式，并把当前提示符记录到会话。
+      def enable
+        @session.perform(:enable) { @session.enable(enable_command, enable_prompt) }
+        self
+      end
+
+      # 将会话交给人工交互；交互结束后会话按终端语义关闭。
+      def interact(input: $stdin, output: $stdout, escape: "\x1d".b, timeout: nil)
+        @session.interact(input: input, output: output, escape: escape, timeout: timeout)
+      end
+
+      def inspect = "#<#{self.class} host=#{host.inspect} state=#{state}>"
+
+      protected
+
+      def pager_pattern = profile.pager_pattern
+
+      def pager_response = profile.pager_response
+
+      def password_prompt = profile.password_prompt
+
+      def username_prompt = profile.username_prompt
+
+      def authentication_error_patterns = profile.authentication_error_patterns
+
+      def command_error_patterns = profile.command_error_patterns
+
+      # 返回命令期间需要自动应答的确认对话。
+      def confirmation_interactions = profile.confirmation_interactions
+
+      # 返回登录期间需要自动应答的附加对话。
+      def login_interactions = profile.login_interactions
+
+      def legacy_ssh_arguments = profile.legacy_ssh_arguments
+
+      def enable_command = profile.privilege_command
+
+      def enable_prompt = profile.privilege_prompt
+
+      def default_command_timeout = profile.command_timeout
+
+      def terminal_size = profile.terminal_size
+
+      # 返回登录完成提示；厂商必须实现。
+      def login_prompt
+        prompt = profile.login_prompt
+        return prompt if prompt
+
+        raise NotImplementedError, "#{self.class} must define login_prompt"
+      end
+
+      # 返回普通命令提示；厂商必须实现。
+      def command_prompt
+        prompt = profile.command_prompt
+        return prompt if prompt
+
+        raise NotImplementedError, "#{self.class} must define command_prompt"
+      end
+
+      # 登录成功后执行厂商初始化钩子。
+      def after_login(_session, _response) end
+
+      # 脚本开始前执行厂商批处理准备钩子。
+      def before_batch(execution)
+        return unless enable_command && execution.context.fetch(:privilege, true)
+
+        execution.enable(enable_command, enable_prompt)
+      end
+
+      # 调整单条命令或返回 nil 跳过该命令。
+      def prepare_command(command, _execution) = command
+
+      # 单条命令完成后执行厂商后处理钩子。
+      def after_command(_command, _response, _execution) end
+
+      private
+
+      # 将厂商提示、失败模式和对话钩子组装成不可变对话语法。
+      def build_dialogue
+        Dialogue.new(
+          login_prompt: login_prompt, command_prompt: command_prompt,
+          password_prompt: password_prompt, username_prompt: username_prompt, enable_prompt: enable_prompt,
+          authentication_errors: authentication_error_patterns, command_errors: command_error_patterns,
+          login_interactions: login_interactions,
+          command_interactions: [Interaction.new(pager_pattern, pager_response, capture: false),
+                                 *confirmation_interactions]
+        )
+      end
+
+      # 在会话锁内运行脚本及业务回调，保留已完成步骤和统一错误边界。
+      def perform_script(script, operation: nil, prompt: nil, after_command: nil, privilege: true,
+                         finalize: nil, &on_step)
+        return Result.new if script.empty?
+
+        execution = build_execution(operation: operation, prompt: prompt, after_command: after_command, privilege: privilege)
+        output_sensitive = script.any?(&:output_sensitive?)
+        @session.perform(:script) do
+          @session.log_script(operation: operation, steps: execution.steps) do
+            @session.with_sensitive_output(output_sensitive) { before_batch(execution) }
+            result = execution.execute_script(script, &on_step)
+            sensitive_result = output_sensitive || script.any?(&:sensitive?) || execution.sensitive?
+            @session.with_sensitive_output(sensitive_result) do
+              finalize_script_result(result, finalize)
+            end
+          end
+        end
+      rescue Error => error
+        Result.new(steps: execution ? execution.steps : [], error: error)
+      end
+
+      def build_execution(operation:, prompt:, after_command:, privilege:)
+        finish_step = lambda do |command, response, context|
+          self.after_command(command, response, context)
+          after_command&.call(command, response, context)
+        end
+        execution = Execution.new(session: @session, timeout: command_timeout,
+                                  prepare: method(:prepare_command), after_command: finish_step, prompt: prompt)
+        execution.context[:operation] = operation if operation
+        execution.context[:privilege] = privilege
+        execution
+      end
+
+      # 回调也可直接返回失败；与抛错共用脱敏边界，保留已完成步骤及业务配置。
+      def finalize_script_result(result, finalize)
+        result = finalize ? finalize.call(result) : result
+        return result unless result.is_a?(Result) && result.failure?
+
+        Result.new(steps: result.steps, config: result.config,
+                   error: @session.normalize_error(result.error, phase: :script))
+      end
+    end
+  end
+end

data/lib/netstack/connector/device_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class DeviceError < Error; end
+  end
+end

data/lib/netstack/connector/dialogue.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 每台设备一份不可变对话语法，由厂商方法组装而不是合并默认值。
+    class Dialogue
+      attr_reader :login_prompt, :command_prompt, :password_prompt, :username_prompt, :enable_prompt,
+                  :authentication_errors, :command_errors, :login_interactions, :command_interactions
+
+      # 校验提示和交互列表，并冻结整套设备对话语法。
+      def initialize(login_prompt:, command_prompt:, password_prompt:, username_prompt:, enable_prompt:,
+                     authentication_errors:, command_errors:, login_interactions:, command_interactions:)
+        @login_prompt = login_prompt
+        @command_prompt = command_prompt
+        @password_prompt = password_prompt
+        @username_prompt = username_prompt
+        @enable_prompt = enable_prompt
+        [login_prompt, command_prompt, password_prompt, username_prompt, enable_prompt].each do |pattern|
+          raise ArgumentError, "prompt must be a nonempty Regexp" unless pattern.is_a?(Regexp) && !pattern.match?("")
+        end
+        @authentication_errors = authentication_errors.freeze
+        @command_errors = command_errors.freeze
+        @login_interactions = login_interactions.freeze
+        @command_interactions = command_interactions.freeze
+        freeze
+      end
+
+      # 从命令输出中返回包含错误模式的诊断行，而不是光标或此前全部输出。
+      def diagnostic(output)
+        return if command_errors.empty?
+
+        # 先保留被回车覆写的失败，再识别颜色或退格处理后的可见诊断。
+        raw = output.gsub(/\r(?!\n)/, "\n")
+        diagnostic_line(raw) || (diagnostic_line(TerminalRenderer.render(output)) if output.match?(/[\e\b]/))
+      end
+
+      private
+
+      # 只截取命中错误模式的当前行，避免把整段设备配置写进诊断信息。
+      def diagnostic_line(output)
+        match = command_errors.lazy.filter_map { |pattern| pattern.match(output) }.first
+        return unless match
+
+        start = match.begin(0).positive? ? output.rindex(/[\r\n]/, match.begin(0) - 1) : nil
+        start = start ? start + 1 : 0
+        finish = output.index(/[\r\n]/, match.end(0)) || output.bytesize
+        output.byteslice(start, finish - start).strip
+      end
+    end
+  end
+end