net-connector 0.4.0

data/docs/architecture.md

@@ -0,0 +1,268 @@
+# Device operations model
+
+The public connector object represents one device session. It owns connection state,
+command execution, and the vendor profile. Callers continue to use
+`device.running_config`, `device.backup(path:)`, and `device.tftp_backup(...)`.
+Running configuration is a basic device capability: `device/` owns the facade,
+immutable profile, and shared collection flow. `Net::Connector::Operations`
+groups optional workflows over that device: backup, parsing, neighbor discovery,
+and interface description plans. Saved-file export is a local operation and
+does not open a device session.
+
+| Layer | Responsibility | Location |
+| --- | --- | --- |
+| Device session | Login, command dialogue, script execution, logging | `engine/` |
+| Device | Public facade, immutable profile, collection and interface naming helpers | `device/` |
+| Vendor assembly | Static CLI prompts, commands, interactions, strategy bindings and session hooks | `vendor/<name>.rb` |
+| Configuration collection | Shared execution, completeness checks and hook adaptation | `device/running_config.rb`, `device/running_config/strategy.rb` |
+| Vendor collection | Configuration cleanup, view transitions and response checks | `vendor/<name>/running_config.rb` |
+| Interface text | Name matching, optional abbreviations, description formatting and common interface-view commands | `device/interface_name.rb`, `device/interface_description.rb` |
+| TextFSM parsing | Select a template and parse command output or saved configuration into records | `operations/parse_output.rb`, `templates/` |
+| Topology and description plan | Read CDP/LLDP neighbors and current descriptions, prepare commands, recheck evidence before confirmed execution | `operations/topology.rb` |
+| Local backup | Collect, compare hashes, atomically save, report change | `operations/local_backup.rb` |
+| Saved configuration export | Find and export an existing local backup without inventory access | `operations/saved_config.rb` |
+| Private file write | Atomically replace local backup and export files with mode `0600` | `operations/private_file.rb` |
+| TFTP backup | Validate target, run export, check transfer evidence, report result | `operations/tftp_backup.rb` |
+| TFTP vendor strategy | Export command, prompts, source file, success evidence, remote name | `vendor/<name>/tftp_backup.rb` |
+| Topology vendor strategy | Discovery commands, parsing evidence, configuration views and command exceptions | `vendor/<name>/topology.rb` |
+| Inventory plan | Select ready devices, apply per-vendor limits, record skip reasons | `netdisco/planner.rb` |
+| Batch worker | Dispatch independent device jobs and isolate callback failures | `netdisco/worker.rb` |
+| Batch result | Summarize outcomes and preserve report failures | `netdisco/batch.rb` |
+| Fleet | Load inventory, run local or TFTP tasks, write reports | `netdisco/fleet.rb` |
+| Settings | Read environment and YAML overrides for CLI and fleet | `netdisco/settings.rb` |
+
+## Business contracts
+
+The connector facade owns one session. `Session` serializes login and scripts,
+closes the transport on failures, and never replays a device command. Each
+`Result` retains completed steps on failure. `RunningConfig` executes one
+collection script with one fresh strategy per call. Response checks, step
+selection and cleanup share that strategy. Selection and cleanup run through
+the existing facade hooks while the session lock is held; overridden methods
+can call `super`. The temporary binding is released even when cleanup fails,
+and is not available to other Fibers performing offline cleanup. Collection
+commands use the current session's complete prompt line, not a generic trailing
+`#`, `>` or `]`. PAN-OS view transitions preserve the authenticated prompt identity.
+A missing final prompt fails collection and leaves the previous backup untouched. Missing or blank configuration, including a response containing
+only a prompt or command echo, is `:incomplete_configuration`,
+not a successful empty backup. PAN-OS checks the candidate diff both before and
+after its `show` command.
+
+`LocalBackup` collects before replacing a private file and preserves the old
+file on failure. TFTP reports only device-side completion. Its strategies check
+explicit completion lines after removing command, reply and prompt echoes;
+filenames and future-tense progress do not establish success. Failure evidence
+from raw and rendered output takes precedence over completion messages. `Topology` reads
+neighbors and descriptions, freezes a plan, requires explicit confirmation,
+rechecks evidence, rebuilds the commands, and reads the configuration back.
+The complete recheck/write/readback sequence holds a session operation lease.
+Sequential scripts from its owning thread and Fiber may execute; other callers,
+close attempts and reentrant script callbacks receive `SessionBusy`. This lease
+is local to one connector instance, not a device-side or cross-process lock.
+`Fleet` keeps skipped, failed, successful, and saved-with-close-error outcomes
+distinct; callback and report errors remain visible without discarding device
+results. Neighbor table headers alone can establish an empty table, but unknown
+or partly parsed rows cannot establish a complete discovery result. Diagnostics
+are checked against both original output and terminal-rendered text so that
+color sequences cannot hide failures and carriage returns cannot erase them.
+Plan revalidation compares the complete discovered neighbor, including chassis
+ID when available, without changing the public evidence hash shape. PAN-OS
+configuration collection preserves multiline quoted values, but the interface
+description template supports single-line comments only; incomplete quoted
+comments raise `ParsingError` instead of becoming truncated plan evidence.
+
+## Expect semantics and Ruby boundaries
+
+The [Tcl Expect manual](https://core.tcl-lang.org/expect/doc/trunk/expect.man)
+defines ordered matching, `exp_continue -continue_timer`, buffer consumption,
+EOF, and separate close/wait responsibilities. Its
+[matching loop](https://github.com/tcltk-depot/expect/blob/main/expect.c)
+keeps the deadline when `EXP_CONTINUE_TIMER` is returned; its
+[process handling](https://github.com/tcltk-depot/expect/blob/main/exp_command.c)
+waits for the owned child and retries interrupted waits. These are useful
+reference semantics; `net-connector` is a device operations library, not a Tcl
+interpreter or a complete Expect API port.
+
+| Concern | Connector contract | Owner |
+| --- | --- | --- |
+| Matching | Connection failures precede interactions, then the final prompt; prompt matches must consume bytes | `ResponseReader` |
+| Time | One monotonic deadline includes command writes and prompt replies; progress and pagination never extend it | `Session`, `ResponseReader` |
+| Buffers | Preserve collected output up to `max_output_bytes`; retain 32 KiB of unmatched tail while streaming larger output | `Transports::Pty`, `ResponseReader` |
+| EOF | Return `ConnectionClosed`, preserve earlier completed steps, close the session | `ResponseReader`, `Execution`, `Session` |
+| Resources | Own the child through `expect-pty#hard_close`; release log files even after setup or flush errors | `Transports::Pty`, `Log` |
+| Interactive use | A manual interaction ends the automated session; subsequent work creates a fresh connection | `Session` |
+| Concurrency | One script or multi-script operation owns a device session; callbacks cannot reenter it; independent jobs use a bounded worker pool | `Session`, `Netdisco::Worker` |
+
+Patterns are Ruby regular expressions. Keep custom prompts and interaction
+markers short enough to fit the unmatched tail; a pattern requiring an
+arbitrarily long transcript is not supported by the streaming adapter. Output
+collection and the matching window have different limits. The terminal renderer
+handles common line-editing controls, not a full screen terminal emulator.
+`Profile#terminal_size` uses `[width, height]`; the PTY adapter converts it to
+Ruby's `[rows, columns]` convention.
+
+Ruby objects retain explicit resource ownership and keyword arguments.
+`Profile` provides finite declarations; strategies contain vendor behavior.
+Private guards use direct names such as `check_block!` and
+`check_change_support!`. Public methods, vendor hooks, result objects, and CLI
+JSON fields remain stable. There is no runtime method injection or workflow DSL.
+
+## Vendor capabilities
+
+`device.supports?(capability)` reads the profile and method-based collection
+commands without opening a transport or constructing a strategy. Accepted
+capabilities are `:running_config`, `:save_config`, `:backup`, `:tftp_backup`,
+`:neighbors`, `:interface_descriptions`, and
+`:interface_description_changes`; unknown names return `false`. This reports
+implementation support, not device authorization or firmware compatibility.
+
+| Vendor | Collect / local backup | Save | TFTP | Neighbors | Descriptions | Plan and apply descriptions |
+| --- | --- | --- | --- | --- | --- | --- |
+| H3C | Yes | Yes | Yes | Yes | Yes | Yes |
+| H3C wireless | Yes | Yes | Yes | Yes | Yes | Yes |
+| Cisco IOS / IOS XE | Yes | Yes | Yes | Yes | Yes | Yes |
+| Cisco NX-OS | Yes | Yes | Yes | Yes | Yes | Yes |
+| Radware Alteon | Yes | Yes | Yes | No | Yes | No |
+| PAN-OS | Yes | No | Yes | Yes | Yes | Yes |
+| Huawei | Yes | Yes | Yes | No | No | No |
+| Hillstone | Yes | Yes | Yes | Yes | Yes | Yes |
+
+The `Profile` DSL declares static command, prompt, interaction, and strategy
+bindings. Configuration, TFTP and topology rules live beside their vendor under
+`vendor/<name>/`. The shared collection flow and operations own validation,
+execution and result semantics. Identical rules are reused directly: NX-OS uses
+IOS topology rules, H3C wireless inherits H3C, and H3C/Huawei/Radware use the common
+rendered configuration strategy. A directory is not a reason to copy a rule. A subclass inherits and may replace these bindings.
+Setting a TFTP or topology binding to `nil` disables that capability. A `nil`
+collection binding uses the default strategy; an empty collection command list
+disables collection. For example, a model variant can replace its transfer flow:
+
+```ruby
+require "net/connector"
+require "net/connector/vendor/cisco_ios"
+
+class VariantTransfer < Net::Connector::CiscoIos::TftpBackup
+  # Override only the methods needed by this model; preserve the Strategy API.
+end
+
+class VariantRouter < Net::Connector.vendor_class(:cisco_ios)
+  profile do
+    tftp_strategy VariantTransfer
+  end
+end
+
+router = VariantRouter.new(host: "192.0.2.10", username: "operator")
+router.supports?(:tftp_backup) # => true, no connection attempted
+```
+
+For collection, bind `running_config_strategy` to a subclass of
+`Net::Connector::RunningConfig::Strategy`. The strategy defines cleaning, result-step
+selection, expected view transitions and per-response validation. PAN-OS candidate
+diff checks apply only to collection; a direct `execute("show config diff")` still
+returns the requested output. Static command lists stay in the profile. The
+facade's `collect_config`, `clean_config` and protected `config_result_step` hooks
+remain available for existing subclasses. `Base` runs generic scripts and locked
+callbacks; it does not decide whether a configuration is complete.
+
+For topology, bind a subclass of `Operations::Topology::Strategy` (or an
+existing vendor strategy) with `topology_strategy YourStrategy`. Its static
+`supports?` declares which of the three topology operations it implements;
+the instance methods provide commands, templates, output completeness, and
+interface spelling. A vendor using a custom inventory label must also provide
+a TextFSM template through `neighbor_template`, because the bundled index
+matches the existing vendor keys. Keep confirmation, evidence checks, and
+readback in `Topology`.
+
+Device operations are constructed for one connector and have a `call` method. TFTP
+strategies contain only device-specific transfer behavior; the operation owns
+the shared success and failure rules. Each vendor binds its strategies in its
+profile, so adding a backup operation does not add methods to every vendor
+connector. Generated TFTP filenames share `TftpTarget` validation and length
+limits. Scoped IPv6 addresses become safe ASCII filename tokens; an unusually
+long address uses a stable SHA-256 token. Existing valid filenames retain their
+spelling, and inventory labels are shortened only when the complete name would
+exceed the target limit.
+
+The facade keeps the existing device API while allowing batch workers and
+single-device callers to share the same operations. The TFTP result means the
+device reported upload completion; checking the server file remains the
+caller's responsibility.
+
+The acceptance gate is `script/ci` (also `bundle exec rake release:check`). It
+checks source, available Git history and gem contents for sensitive data; runs
+Ruby and workflow lint and the full test suite; and installs the gem into both
+an isolated gem home and a minimal Bundler application. A local PTY smoke checks
+vendor loading, configuration collection, packaged TextFSM templates and the CLI.
+RuboCop checks Ruby lint, security, whitespace, frozen string comments and the
+project's double-quoted string convention. No real device is contacted. Initial
+dependency and tool downloads require internet access; see
+[verification](VERIFICATION.md) and [release instructions](RELEASING.md).
+
+## Loading and compatibility
+
+`require "net/connector"` loads the device API and engine, without loading vendor
+rules or TextFSM. Each vendor entry point assembles only its own rules and shared
+parents. Parsing loads when a parsing or topology workflow is used. Lower-level
+callers can load `net/connector/engine/core` without device definitions, business
+operations or vendor rules. `engine/base`, `engine/profile`, and `engine` remain
+forwarding entry points for existing callers.
+
+Old `Operations::RunningConfig`, `Operations::RunningConfig::<Vendor>`,
+`Operations::Tftp::<Vendor>` and `Operations::Topology::<Vendor>` constants and
+require paths forward to the same classes, rather than maintaining duplicate
+implementations. Existing public result constants also remain available through
+autoload. New vendor code uses the vendor-owned classes directly.
+
+## Interface description policy
+
+Raw `Neighbor` fields and plan evidence retain the exact discovered values.
+`InterfaceName.key` matches local aliases to running configuration names;
+`InterfaceName.configuration` preserves the established CLI expansion rules.
+`InterfaceName.short` is exclusively a display policy for the remote port in a
+description. It never replaces the local interface used in commands.
+
+`InterfaceDescription.format(neighbor, abbreviate: true, lowercase: false)` is
+shared by every vendor's default plan. It retains the neighbor device name and
+produces `To <name> <port>`. Known families shorten as follows, preserving lower,
+upper or initial-capital case: Ethernet/Eth → Eth, GigabitEthernet/GE/Gi → Gi,
+Ten-GigabitEthernet/TenGigabitEthernet/XGE/Te → Te, FastEthernet/Fa → Fa, and
+port-channel/Po → Po. Port numbers and subinterface suffixes stay intact. Unknown
+forms such as `ge-0/0/1`, `100GE1/0/1` and `Port 12` stay unchanged by default;
+this is a finite mapping, not a claim to recognize all vendors or interface types.
+
+This changes the default proposal from `To peer Ethernet1/2` to
+`To peer Eth1/2`. Use `plan_interface_descriptions(abbreviate: false)` to keep the
+previous spelling, or `lowercase: true` to lowercase only the remote interface.
+An explicit formatter block receives the original neighbor and controls the
+complete description. All outputs still pass the same 80-byte and character
+validation, evidence recheck, confirmation and readback requirements.
+
+`InterfaceDescription.commands(interface:, description:, leave: "exit")` builds
+separate `interface`, `description` and exit commands for IOS/NX-OS and Hillstone;
+H3C supplies `leave: "quit"`. Entering configuration mode and saving remain
+vendor responsibilities. PAN-OS retains `set network interface ... comment`,
+`commit`, and its extended commit timeout. The common builder is pure: it does
+not send commands or bypass the reviewed topology plan.
+
+## Sensitive command lifetime
+
+One temporary redaction scope spans preparation, exchange, vendor postprocessing,
+user callbacks and error normalization. Follow-up queries share the enclosing
+scope; `ensure` removes temporary secrets afterward. Sensitive errors preserve
+type, code, phase and completed steps but hide arbitrary messages, output and
+underlying backtraces that could contain partial secrets. Explicit result data
+remains raw. Direct and streaming redaction prioritize actual secrets, including
+secrets containing the literal `[REDACTED]`, before preserving existing markers.
+
+## Local backup identity and legacy files
+
+Fleet backups use the normalized management IP alone (`<IP>.txt`, with IPv6 `:`
+replaced by `_`). Inventory names remain result metadata and TFTP labels.
+`SavedConfig` prefers this canonical file. If absent, it accepts exactly one
+legacy `<name>-<IP>.txt` file; multiple matches fail rather than choosing by mtime.
+The first successful canonical backup compares against the unique legacy digest,
+retains the legacy file, and reports `changed` or `unchanged` accordingly. Failed
+collection creates no canonical file. Symlinks and non-regular candidates are
+rejected before connecting. Existing ambiguous legacy sets need operator review:
+retain the originals and place the verified current configuration at the canonical
+path before resuming backup/export.

data/exe/net-connector-backup

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "net/connector/netdisco"
+
+exit Net::Connector::Netdisco::CLI.new.run

data/lib/net/connector/device/base.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+require "English"
+require "forwardable"
+require_relative "../engine/core"
+require_relative "profile"
+require_relative "running_config"
+require_relative "interface_description"
+require_relative "../operations"
+
+module Net
+  module Connector
+    # 设备连接门面；厂商子类提供语法和钩子，组合对象负责实际执行。
+    class Base
+      extend Forwardable
+
+      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(**)
+        begin
+          device.connect
+          yield device
+        ensure
+          active_error = $ERROR_INFO
+          begin
+            device.close
+          rescue StandardError
+            raise unless active_error
+          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(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
+
+      # 使用简短名称执行脚本。
+      alias run execute_script
+
+      # 读取运行配置并返回清理后的配置结果。
+      def running_config
+        RunningConfig.new(self).call
+      end
+
+      # 执行命令并按厂商、命令或显式 TextFSM 模板返回结构化记录。
+      def parse_command(command, template: nil, template_dir: nil)
+        parser = Operations::ParseOutput.new(template_dir: template_dir)
+        parser.call(execute(command).value!, template: template, vendor: vendor, command: command, host: host)
+      end
+
+      # 采集运行配置并使用指定 TextFSM 模板提取结构化记录。
+      def parse_config(template:, template_dir: nil)
+        parser = Operations::ParseOutput.new(template_dir: template_dir)
+        parser.call(running_config.value!, template: template, host: host)
+      end
+
+      # 执行 CDP 或 LLDP 查询并返回统一的链路邻居记录。
+      def neighbors = Operations::Topology.new(self).neighbors
+
+      # 读取运行配置中的接口描述或端口名称。
+      def interface_descriptions = Operations::Topology.new(self).descriptions
+
+      # 以邻居和现有配置为证据，生成待确认的接口描述变更计划。
+      def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        Operations::Topology.new(self).plan_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+      end
+
+      # 明确确认且现场证据未变化时执行接口描述计划。
+      def apply_interface_descriptions(plan, confirmed: false)
+        Operations::Topology.new(self).apply(plan, confirmed: confirmed)
+      end
+
+      # 多步骤业务操作独占当前会话，内部脚本仍禁止回调重入。
+      def with_operation(name, &block) = @session.with_operation(name, &block)
+
+      # 采集配置并以原子方式保存为私有文件。
+      # 采集失败时保留已有备份文件。
+      def backup(path:)
+        Operations::LocalBackup.new(self).call(path: path)
+      end
+
+      # 要求设备直接向 TFTP 服务器导出原生配置。
+      # 完成仅表示设备报告传输成功，未读取服务器端文件。
+      def tftp_backup(host:, path: nil, source_file: nil, vrf: nil)
+        Operations::TftpBackup.new(self).call(host: host, path: path, source_file: source_file, vrf: vrf)
+      end
+
+      # 配置采集是设备的基础能力，两个公共入口共享同一流程。
+      def collect_config = RunningConfig.new(self).call
+
+      # 业务层可扩展脚本准备、响应校验和最终结果，所有钩子均在会话锁内执行。
+      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 record_event(name, **details)
+        @session.log_event(name, **details)
+      end
+
+      # 执行厂商保存配置命令；不支持时返回显式失败结果。
+      def save_config
+        if save_commands.empty?
+          return Result.new(error: @session.error(UnsupportedOperation, "saving configuration is not supported",
+                                                  phase: :save))
+        end
+
+        execute_script(save_commands)
+      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 config_commands
+        commands = profile.config_commands
+        return commands if commands
+
+        raise NotImplementedError, "#{self.class} must define running configuration commands"
+      end
+
+      # 返回保存配置命令；空数组表示设备不支持保存。
+      def save_commands = profile.save_commands
+
+      # 清理运行配置文本；厂商可移除设备回显噪声。
+      def clean_config(text) = config_strategy.clean(text)
+
+      # 返回不包含凭据的连接状态摘要。
+      def inspect = "#<#{self.class} host=#{host.inspect} state=#{state}>"
+
+      protected
+
+      # 默认取最后一个已完成步骤；厂商可选择配置所在的业务步骤。
+      def config_result_step(result) = config_strategy.result_step(result)
+
+      # 匹配设备分页提示，供对话层自动发送翻页响应。
+      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_dialogues = profile.confirmation_interactions
+
+      # 返回登录期间需要自动应答的附加对话。
+      def login_dialogues = profile.login_interactions
+
+      # 返回旧版 SSH 恢复使用的协商参数。
+      def legacy_ssh_arguments = profile.legacy_ssh_arguments
+
+      # 返回进入特权模式的命令；nil 表示不支持。
+      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
+
+      # 采集器仅在持有会话锁的结果处理阶段绑定策略，让旧方法钩子的 super
+      # 复用响应校验状态。其他 Fiber 的离线清理仍使用自己的临时策略。
+      def with_config_strategy(strategy)
+        previous = @config_strategy_scope
+        @config_strategy_scope = [Fiber.current, strategy]
+        yield
+      ensure
+        @config_strategy_scope = previous
+      end
+
+      def config_strategy
+        scope = @config_strategy_scope
+        scope && scope.first.equal?(Fiber.current) ? scope.last : RunningConfig.strategy(self)
+      end
+
+      # 将厂商提示、失败模式和对话钩子组装成不可变对话语法。
+      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_dialogues,
+          command_interactions: [Interaction.new(pager_pattern, pager_response, capture: false),
+                                 *confirmation_dialogues]
+        )
+      end
+
+      # 在会话锁内运行脚本及业务回调，保留已完成步骤和统一错误边界。
+      def perform_script(script, operation: nil, prompt: nil, after_command: nil, privilege: true,
+                         finalize: nil, &on_step)
+        return Result.new if script.empty?
+
+        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
+        @session.perform(:script) do
+          before_batch(execution)
+          result = execution.execute(script, &on_step)
+          finalize ? finalize.call(result) : result
+        end
+      rescue Error => error
+        Result.new(steps: execution ? execution.steps : [], error: error)
+      end
+    end
+  end
+end