netstack 0.1.1 → 0.2.0

data/lib/netstack/connector/profile.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 描述设备命令行规则的不可变值对象；只承载声明式配置，不承载运行状态。
+    class Profile
+      DEFAULT_PAGER_PATTERN = /(?:\A|(?<=[\r\n]))[ \t]*(?:--More--|---- More ----)[ \t\x00\x08]*(?=\r|\n|\z)/i.freeze
+      DEFAULT_AUTHENTICATION_ERROR_PATTERNS = [
+        /(?:authentication failed|permission denied|access denied|login incorrect)/i
+      ].freeze
+      DEFAULT_PASSWORD_PROMPT = /password:\s*\z/i.freeze
+      DEFAULT_USERNAME_PROMPT = /(?:login|username|name):\s*\z/i.freeze
+      DEFAULT_PRIVILEGE_PROMPT = /#\s*\z/.freeze
+      DEFAULT_LEGACY_SSH_ARGUMENTS = ["-1"].freeze
+
+      attr_reader :config_commands, :save_commands,
+                  :login_prompt, :command_prompt, :username_prompt, :password_prompt,
+                  :privilege_prompt, :pager_pattern, :pager_response,
+                  :authentication_error_patterns, :command_error_patterns,
+                  :login_interactions, :confirmation_interactions, :legacy_ssh_arguments,
+                  :privilege_command, :command_timeout, :terminal_size, :tftp_strategy, :topology_strategy, :running_config_strategy
+
+      # 使用默认的公共规则创建空设备档案；登录和命令提示符仍由厂商声明。
+      def self.default
+        @default ||= new
+      end
+
+      # 在继承档案的基础上执行一次声明块，生成新的不可变设备档案。
+      def self.define(parent: nil, &definition)
+        raise ArgumentError, "profile requires a block" unless definition
+
+        builder = Builder.new(parent || default)
+        builder.instance_eval(&definition)
+        builder.build
+      end
+
+      # 校验并冻结设备命令、提示符、交互和连接参数。
+      def initialize(config_commands: nil, save_commands: [],
+                     login_prompt: nil, command_prompt: nil,
+                     username_prompt: DEFAULT_USERNAME_PROMPT, password_prompt: DEFAULT_PASSWORD_PROMPT,
+                     privilege_prompt: DEFAULT_PRIVILEGE_PROMPT,
+                     pager_pattern: DEFAULT_PAGER_PATTERN, pager_response: " ",
+                     authentication_error_patterns: DEFAULT_AUTHENTICATION_ERROR_PATTERNS,
+                     command_error_patterns: [], login_interactions: [], confirmation_interactions: [],
+                     legacy_ssh_arguments: DEFAULT_LEGACY_SSH_ARGUMENTS, privilege_command: nil,
+                     command_timeout: 25, terminal_size: nil, tftp_strategy: nil, topology_strategy: nil, running_config_strategy: nil)
+        @config_commands = command_list(config_commands, :config_commands, allow_nil: true)
+        @save_commands = command_list(save_commands, :save_commands)
+        @login_prompt = pattern(login_prompt, :login_prompt, allow_nil: true)
+        @command_prompt = pattern(command_prompt, :command_prompt, allow_nil: true)
+        @username_prompt = pattern(username_prompt, :username_prompt)
+        @password_prompt = pattern(password_prompt, :password_prompt)
+        @privilege_prompt = pattern(privilege_prompt, :privilege_prompt)
+        @pager_pattern = pattern(pager_pattern, :pager_pattern)
+        @pager_response = response_text(pager_response, :pager_response)
+        @authentication_error_patterns = patterns(authentication_error_patterns, :authentication_error_patterns)
+        @command_error_patterns = patterns(command_error_patterns, :command_error_patterns)
+        @login_interactions = interactions(login_interactions, :login_interactions)
+        @confirmation_interactions = interactions(confirmation_interactions, :confirmation_interactions)
+        @legacy_ssh_arguments = strings(legacy_ssh_arguments, :legacy_ssh_arguments)
+        @privilege_command = optional_text(privilege_command, :privilege_command)
+        @command_timeout = duration(command_timeout, :command_timeout)
+        @terminal_size = validate_terminal_size!(terminal_size)
+        @running_config_strategy = strategy_class(running_config_strategy, :running_config_strategy,
+                                                  %i[clean result_step prompt_text validate_response!])
+        @tftp_strategy = strategy_class(tftp_strategy, :tftp_strategy,
+                                        %i[resolve_source_file default_path remote_path script device_reported_complete? validate_options! receipt_metadata])
+        if @tftp_strategy && !@tftp_strategy.respond_to?(:filename)
+          raise ArgumentError, "tftp_strategy must expose filename"
+        end
+        @topology_strategy = strategy_class(topology_strategy, :topology_strategy,
+                                            %i[neighbor_command neighbor_template expected_neighbor_count empty_neighbor_output?
+                                               protocol description_template interface_key configuration_interface
+                                               decode_description validate_descriptions! change_error_code supports?
+                                               enter_configuration_command change_commands script_command
+                                               leave_configuration_commands verification_commands persistence_commands persistence_confirmed?])
+        if @topology_strategy && !@topology_strategy.respond_to?(:supports?)
+          raise ArgumentError, "topology_strategy must expose supports?"
+        end
+        freeze
+      end
+
+      # 返回一份供子类声明块继续编辑的关键字参数。
+      def to_h
+        {
+          config_commands: config_commands,
+          save_commands: save_commands,
+          login_prompt: login_prompt,
+          command_prompt: command_prompt,
+          username_prompt: username_prompt,
+          password_prompt: password_prompt,
+          privilege_prompt: privilege_prompt,
+          pager_pattern: pager_pattern,
+          pager_response: pager_response,
+          authentication_error_patterns: authentication_error_patterns,
+          command_error_patterns: command_error_patterns,
+          login_interactions: login_interactions,
+          confirmation_interactions: confirmation_interactions,
+          legacy_ssh_arguments: legacy_ssh_arguments,
+          privilege_command: privilege_command,
+          command_timeout: command_timeout,
+          terminal_size: terminal_size,
+          tftp_strategy: tftp_strategy,
+          topology_strategy: topology_strategy,
+          running_config_strategy: running_config_strategy
+        }
+      end
+
+      # 返回档案中最有用的设备规则摘要。
+      def inspect
+        "#<#{self.class} commands=#{config_commands&.size || 0} " \
+          "save_commands=#{save_commands.size}>"
+      end
+
+      private
+
+      # 校验静态接口，不构造策略实例或触发设备 I/O。
+      def strategy_class(value, name, required_methods)
+        return nil if value.nil?
+        unless value.is_a?(Class) && (required_methods - value.public_instance_methods).empty?
+          raise ArgumentError, "#{name} must be a strategy class implementing #{required_methods.join(", ")}"
+        end
+
+        value
+      end
+
+      # 校验单条命令数组并复制为深度不可变值。
+      def command_list(value, name, allow_nil: false)
+        return nil if allow_nil && value.nil?
+        unless value.is_a?(Array)
+          raise ArgumentError, "#{name} must be an Array of command strings"
+        end
+
+        value.map do |command|
+          unless command.is_a?(String) && !command.strip.empty? && !command.match?(/[\r\n\x00]/)
+            raise ArgumentError, "#{name} must contain nonempty single-line commands"
+          end
+
+          command.dup.freeze
+        end.freeze
+      end
+
+      # 校验提示模式并复制为不可变正则表达式。
+      def pattern(value, name, allow_nil: false)
+        return nil if allow_nil && value.nil?
+        unless value.is_a?(Regexp) && !value.match?("")
+          raise ArgumentError, "#{name} must be a nonempty Regexp"
+        end
+
+        value.dup.freeze
+      end
+
+      # 校验正则表达式列表并冻结每一项。
+      def patterns(values, name)
+        unless values.is_a?(Array)
+          raise ArgumentError, "#{name} must be an Array of Regexp objects"
+        end
+
+        values.map { |value| pattern(value, name) }.freeze
+      end
+
+      # 校验交互对象列表并冻结列表。
+      def interactions(values, name)
+        unless values.is_a?(Array) && values.all?(Interaction)
+          raise ArgumentError, "#{name} must be an Array of Interaction objects"
+        end
+
+        values.dup.freeze
+      end
+
+      # 校验并复制字符串数组。
+      def strings(values, name)
+        unless values.is_a?(Array) && values.all?(String)
+          raise ArgumentError, "#{name} must be an Array of strings"
+        end
+
+        values.map { |value| value.dup.freeze }.freeze
+      end
+
+      # 校验可选单行文本。
+      def optional_text(value, name)
+        return if value.nil?
+        text(value, name)
+      end
+
+      # 校验并复制单行文本。
+      def text(value, name)
+        unless value.is_a?(String) && !value.match?(/[\r\n\x00]/)
+          raise ArgumentError, "#{name} must be a single-line String"
+        end
+
+        value.dup.freeze
+      end
+
+      # 校验并复制分页或交互响应；响应可以包含换行。
+      def response_text(value, name)
+        raise ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+
+        value.dup.freeze
+      end
+
+      # 校验默认命令超时。
+      def duration(value, name)
+        result = Expect.duration(value)
+        raise ArgumentError, "#{name} must be finite" unless result
+
+        result
+      end
+
+      # 校验终端宽高并冻结数组。
+      def validate_terminal_size!(value)
+        return if value.nil?
+        unless value.is_a?(Array) && value.size == 2 && value.all? { |dimension| dimension.is_a?(Integer) && dimension.positive? }
+          raise ArgumentError, "terminal_size must contain two positive Integers"
+        end
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/netstack/connector/prompt_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 PromptError < Error; end
+  end
+end

data/lib/netstack/connector/recovery.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 只选择一次连接级恢复；任何设备命令都不会重放。
+    class Recovery
+      # 只有明确允许的 SSH 拒绝才会建立一次 Telnet 连接。
+      class TelnetFallback
+        # 将连接被拒绝转换为 Telnet 传输，否则不提供恢复。
+        def recover(error, transport)
+          transport.as_telnet if error.code == :connection_refused && transport.respond_to?(:as_telnet)
+        end
+      end
+
+      # 主机密钥替换仅限调用方指定的 known_hosts 文件。
+      class HostKeyReplacement
+        # 删除旧密钥并返回原传输对象，其他错误不触发替换。
+        def recover(error, transport)
+          return unless error.code == :host_key_changed && transport.respond_to?(:replace_host_key)
+
+          transport.replace_host_key
+          transport
+        end
+      end
+
+      # 旧版协商参数来自厂商配置，不能由设备输出决定。
+      class LegacySsh
+        # 保存厂商提供的旧版参数。
+        def initialize(arguments)
+          @arguments = arguments
+        end
+
+        # 根据明确错误码创建一次旧版 SSH 传输。
+        def recover(error, transport)
+          return unless transport.respond_to?(:with_legacy)
+
+          arguments = { rsa_too_small: @arguments, unsupported_cipher: ["-c", "des"] }[error.code]
+          transport.with_legacy(arguments) if arguments
+        end
+      end
+
+      # 按配置顺序建立可用的连接级恢复规则。
+      def initialize(configuration, legacy_arguments:)
+        @rules = []
+        @rules << TelnetFallback.new if configuration.telnet_fallback?
+        @rules << HostKeyReplacement.new if configuration.host_key_policy == :replace
+        @rules << LegacySsh.new(legacy_arguments) if configuration.legacy_ssh?
+        @rules.freeze
+      end
+
+      # 依次尝试恢复规则，并只返回第一个新传输对象。
+      def recover(error, transport)
+        @rules.lazy.filter_map { |rule| rule.recover(error, transport) }.first
+      end
+    end
+  end
+end

data/lib/netstack/connector/redactor.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    # 管理连接器的秘密作用域和输出敏感性；字节过滤统一委托给 expect-pty。
+    class Redactor
+      MASK = "[REDACTED]".b.freeze
+
+      # 保存初始凭据，并建立第一版脱敏词表。
+      def initialize(*secrets)
+        unless Expect.constants(false).include?(:Redactor) && Expect::Redactor.respond_to?(:redact)
+          raise LoadError, "netstack requires expect-pty with the public Expect::Redactor API"
+        end
+
+        @configured = secrets.compact.map(&:b).map(&:freeze).freeze
+        reset
+      end
+
+      # 重置动态词表，同时保留配置中的固定凭据。
+      def reset
+        @secrets = []
+        @patterns = nil
+        @scoped = false
+        @sensitive = false
+        @output_sensitive = false
+        @configured.each { |secret| remember(secret) }
+      end
+
+      # 临时命令响应在错误归一化期间保留，离开作用域后不进入长期会话。
+      def with_scope(reuse: false)
+        return yield if reuse && @scoped
+
+        previous = @secrets
+        previous_patterns = @patterns
+        previous_scoped = @scoped
+        previous_sensitive = @sensitive
+        previous_output_sensitive = @output_sensitive
+        @secrets = previous.dup
+        @scoped = true
+        begin
+          yield
+        ensure
+          @secrets = previous
+          @patterns = previous_patterns
+          @scoped = previous_scoped
+          @sensitive = previous_sensitive
+          @output_sensitive = previous_output_sensitive
+        end
+      end
+
+      # 敏感命令和交互的异常可能只引用秘密的一部分，不能只依赖完整词匹配。
+      def sensitive! = @sensitive = true
+
+      # 判断当前脱敏范围是否包含敏感交互。
+      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?
+
+        bytes = secret.b
+        return if @secrets.include?(bytes)
+
+        @secrets << bytes.freeze
+        @patterns = nil
+      end
+
+      # 一次性诊断不共享流状态；原标记作为不透明区间，避免再次展开它。
+      def call(text)
+        Expect::Redactor.redact(text.to_s.b, patterns, replacement: MASK)
+      end
+
+      # 每个日志目标独占过滤流，跨分片尾部和重叠掩码由依赖库维护。
+      def stream
+        Expect::Redactor.new(patterns, replacement: MASK)
+      end
+
+      # 临时范围恢复时，日志流可以同步恢复注册词表，不缓存配置正文。
+      def patterns
+        @patterns ||= (@secrets.empty? ? [] : (@secrets + [MASK]).uniq).freeze
+      end
+
+      # 返回脱敏器类型摘要。
+      def inspect = "#<#{self.class}>"
+    end
+  end
+end

data/lib/netstack/connector/response.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 在厂商清理前保留原始字节，供诊断和日志使用。
+    class Response
+      attr_reader :raw, :output, :prompt
+
+      # 保存原始响应、清理后输出和命令结束提示，并冻结三者。
+      def initialize(raw:, output:, prompt:)
+        @raw = raw.freeze
+        @output = output.freeze
+        @prompt = prompt.freeze
+        freeze
+      end
+
+      # 返回响应大小摘要，不展开原始内容。
+      def inspect = "#<#{self.class} bytes=#{raw.bytesize}>"
+    end
+  end
+end

data/lib/netstack/connector/response_reader.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/pty"
+
+module Netstack
+  module Connector
+    # 在传输层上执行有界对话；收到字节或分页标记不会重置截止时间。
+    class ResponseReader
+      # 保存会话引用，以便读取器使用传输、配置和脱敏上下文。
+      def initialize(session)
+        @session = session
+      end
+
+      # 读取到结束提示、失败模式或超时，并处理交互响应和输出上限。
+      def read(prompt:, interactions:, phase:, timeout: nil, deadline: nil, command: nil, failures: {})
+        deadline ||= Expect.monotonic + timeout
+        patterns = [*failures.keys, *interactions.map(&:pattern), prompt]
+        raw = []
+        output = []
+        counts = Hash.new(0)
+        bytes = 0
+        loop do
+          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
+          validate_event!(event, bytes, raw, phase, command)
+
+          if event.index == patterns.size
+            raw << event.match
+            output << event.match
+          elsif event.index == patterns.size - 1
+            return finish_response(event.match, raw, output, phase, command)
+          elsif event.index < failures.size
+            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?
+            respond(reply, event.match, counts, deadline, phase, command)
+          end
+          next if Expect.monotonic < deadline
+
+          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.with_scope(reuse: true) do
+          @session.redactor.sensitive!
+          reply.response(prompt)
+        rescue => error
+          raise @session.normalize_error(error, phase: phase, command: command), cause: nil
+        end
+      end
+
+      # 将交互拒绝或响应缺失转换为认证或脚本错误。
+      def build_interaction_error(message, phase, command)
+        authenticating = %i[login enable].include?(phase)
+        klass = authenticating ? AuthenticationError : ScriptError
+        label = authenticating ? "authentication" : "command interaction"
+        @session.build_error(klass, "#{label} #{message}", phase: phase, command: command)
+      end
+
+      # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
+      def build_read_error(event, phase, command, output)
+        if event&.error.is_a?(Exception)
+          return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
+                                      underlying: event.error, output: output)
+        end
+        klass = if event&.error == :eof
+                  ConnectionClosed
+                elsif command&.prompt
+                  PromptError
+                elsif %i[login enable].include?(phase)
+                  LoginTimeout
+                else
+                  CommandTimeout
+                end
+        @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
+                             command: command, output: output)
+      end
+    end
+  end
+end

data/lib/netstack/connector/result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 不可变执行结果；构造结果不会复制已经累计的命令输出前缀。
+    class Result
+      include Enumerable
+
+      attr_reader :steps, :error, :config
+
+      # 校验步骤、错误和配置文本，并冻结结果容器。
+      def initialize(steps: [], error: nil, config: nil)
+        raise ArgumentError, "error must be a Connector::Error or nil" unless error.nil? || error.is_a?(Error)
+        unless steps.is_a?(Array) && steps.all?(CommandResult)
+          raise ArgumentError, "steps must be an Array of CommandResult objects"
+        end
+        raise ArgumentError, "config must be a String or nil" unless config.nil? || config.is_a?(String)
+
+        @steps = steps.dup.freeze
+        @error = error
+        @config = config&.dup&.freeze
+        freeze
+      end
+
+      # 判断执行是否成功。
+      def success? = error.nil?
+
+      # 判断执行是否失败。
+      def failure? = !success?
+
+      # 遍历已完成命令步骤。
+      def each(&) = steps.each(&)
+
+      # 拼接所有已完成步骤的输出字节。
+      def output = steps.map(&:output).join.b
+
+      # 成功时返回配置或输出，失败时重新抛出领域错误。
+      def value!
+        raise error, cause: nil if failure?
+
+        config || output
+      end
+
+      # 返回结果成功状态、步骤数量和错误码摘要。
+      def inspect = "#<#{self.class} success=#{success?} steps=#{steps.size} code=#{ErrorMetadata.code(error&.code).inspect}>"
+    end
+  end
+end

data/lib/netstack/connector/running_config/rendered.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class RunningConfig
+
+      # 使用终端行编辑规则渲染 H3C、Huawei 和 Radware 配置。
+      class Rendered < Strategy
+        # 应用终端行编辑规则，还原设备最终显示的配置文本。
+        def clean(text) = TerminalRenderer.render(text)
+      end
+    end
+  end
+end

data/lib/netstack/connector/running_config/strategy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    class RunningConfig
+      class Strategy
+        # 保存策略所属设备，供提示符和厂商校验使用。
+        def initialize(device) = @device = device
+
+        # 默认保留设备响应原文。
+        def clean(text) = text
+
+        # 默认取脚本最后一个完成步骤作为运行配置。
+        def result_step(result) = result.steps.last
+
+        # 普通采集命令保持视图不变；需要切换视图的采集策略显式调整。
+        def prompt_text(_command)
+          TerminalRenderer.render(@device.current_prompt.to_s).lines.last.to_s.strip
+        end
+
+        # 公共策略不增加逐命令响应检查。
+        def validate_response!(_command, _response, _execution) end
+      end
+    end
+  end
+end