net-connector 0.4.2 → 0.5.0

data/lib/net/connector/device/topology/interface_description.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "interface_name"
+
+module Net
+  module Connector
+    class Topology
+      # 描述文本与常见接口视图命令的纯构造方法，不连接或修改设备。
+      module InterfaceDescription
+        # 将邻居名称和接口拼成默认描述；只缩写邻居接口，保留原始大小写。
+        def self.format(neighbor, abbreviate: true, lowercase: false)
+          port = if abbreviate
+                   InterfaceName.short(neighbor.neighbor_interface, lowercase: lowercase)
+                 else
+                   lowercase ? neighbor.neighbor_interface.downcase : neighbor.neighbor_interface
+                 end
+          validate!("To #{neighbor.neighbor_name} #{port}")
+        end
+
+        # 生成进入接口、设置描述和退出视图的命令，不执行设备操作。
+        def self.commands(interface:, description:, leave: "exit")
+          validate_interface!(interface)
+          validate!(description)
+          raise ArgumentError, "interface exit must be exit or quit" unless %w[exit quit].include?(leave)
+
+          ["interface #{interface}", "description #{description}", leave]
+        end
+
+        # 共享的输入约束同样适用于 PAN-OS 的独立命令语法。
+        def self.validate!(value)
+          return value if value.is_a?(String) && value.bytesize.between?(1, 80) &&
+                          value.match?(/\A[\p{Alnum}_.: \/-]+\z/u)
+
+          raise ArgumentError, "description must be 1-80 bytes of plain interface text"
+        end
+
+        # 拒绝可能把描述命令拆成多条命令的不安全接口名。
+        def self.validate_interface!(value)
+          return value if value.is_a?(String) && value.match?(/\A[A-Za-z][A-Za-z0-9.\/-]*\z/)
+
+          raise ArgumentError, "neighbor interface name is unsafe"
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/interface_name.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class Topology
+      # 接口身份匹配与描述展示共用名称规则；展示简称不能直接用作下发命令。
+      module InterfaceName
+        RULES = [
+          [/\A(?:xge|ten-gigabitethernet|tengigabitethernet|te)(?=\d)/i, "tengigabitethernet", "Te"],
+          [/\A(?:gigabitethernet|ge|gi)(?=\d)/i, "gigabitethernet", "Gi"],
+          [/\A(?:fastethernet|fa)(?=\d)/i, "fastethernet", "Fa"],
+          [/\A(?:ethernet|eth)(?=\d)/i, "ethernet", "Eth"],
+          [/\A(?:port-channel|po)(?=\d)/i, "port-channel", "Po"]
+        ].map(&:freeze).freeze
+
+        # 用于本机邻居表与配置的关联；保留已有证据键的拼写契约。
+        def self.key(name)
+          rule = RULES.find { |pattern, _key, _short| pattern.match?(name) }
+          rule ? name.sub(rule.first, rule[1]).downcase : name.downcase
+        end
+
+        # 仅缩短已识别的前缀，保留端口、子接口编号及未知命名。
+        # 默认延续输入的大写、小写或首字母大写形式；统一小写由调用方选择。
+        def self.short(name, lowercase: false)
+          rule = RULES.find { |pattern, _key, _short| pattern.match?(name) }
+          formatted = if rule
+                        name.sub(rule.first) do |prefix|
+                          abbreviation = rule.last
+                          if prefix == prefix.downcase
+                            abbreviation.downcase
+                          elsif prefix == prefix.upcase
+                            abbreviation.upcase
+                          elsif prefix.casecmp?(abbreviation)
+                            prefix
+                          else
+                            abbreviation
+                          end
+                        end
+                      else
+                        name.dup
+                      end
+          lowercase ? formatted.downcase : formatted
+        end
+
+        # 保留现有配置视图展开规则；厂商策略可覆盖不适用的名称。
+        def self.configuration(name)
+          name.sub(/\AXGE(?=\d)/i, "Ten-GigabitEthernet")
+              .sub(/\AGE(?=\d)/i, "GigabitEthernet")
+              .sub(/\AGi(?=\d)/i, "GigabitEthernet")
+              .sub(/\ATe(?=\d)/i, "TenGigabitEthernet")
+              .sub(/\AFa(?=\d)/i, "FastEthernet")
+              .sub(/\AEth(?=\d)/i, "Ethernet")
+              .sub(/\APo(?=\d)/i, "port-channel")
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/topology/strategy.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require_relative "interface_description"
+
+module Net
+  module Connector
+    class Topology
+      # 厂商拓扑规则；默认不提供任何设备能力。
+      class Strategy
+        # 保存设备供厂商规则查询档案和会话状态。
+        def initialize(device)
+          @device = device
+        end
+
+        # 声明策略类支持的拓扑能力，默认全部关闭。
+        def self.supports?(_capability) = false
+
+        # 将实例级能力查询交给策略类声明。
+        def supports?(capability) = self.class.supports?(capability)
+
+        # 返回读取邻居的命令，未定义时不支持发现。
+        def neighbor_command = nil
+
+        # 根据原始输出选择邻居解析模板。
+        def neighbor_template(_output) = nil
+
+        # 返回当前接口描述所用的解析模板。
+        def description_template = nil
+
+        # 返回输出中应解析出的邻居数量，供完整性校验使用。
+        def expected_neighbor_count(_output, _template) = 0
+
+        # 只有明确的空表证据才允许返回空邻居列表。
+        def empty_neighbor_output?(_output) = false
+
+        # 返回进入设备配置视图的命令。
+        def enter_configuration_command = nil
+
+        # 只读策略不提供变更阶段；可写策略必须分别声明退出、验证和保存命令。
+        def leave_configuration_commands = nil
+        def verification_commands = nil
+        def persistence_commands = nil
+        def persistence_confirmed?(_result) = false
+        def change_error_code = :description_unsupported
+
+        # 只读策略可以没有完整性扩展；立即生效的接口块模型会进一步校验解析数量。
+        def validate_descriptions!(_config, _rows) end
+
+        # 为一条接口描述变更生成厂商命令。
+        def change_commands(_change) = []
+
+        # 标明邻居发现使用的协议。
+        def protocol = :lldp
+
+        # 在下发前允许厂商调整命令对象及超时。
+        def script_command(command) = command
+
+        # 将发现接口名归一为查找当前配置所用的键。
+        def interface_key(name) = InterfaceName.key(name)
+
+        # 将发现协议常用的接口简称展开为配置视图可识别的名称。
+        def configuration_interface(name) = InterfaceName.configuration(name)
+
+        # 还原 PAN-OS set 配置或 Alteon dump 中的引号描述。
+        def decode_description(value)
+          value = value.strip
+          value.start_with?('"') ? Shellwords.split(value).join(" ") : value
+        rescue ArgumentError
+          value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "topology/strategy"
+
+module Net
+  module Connector
+    # 从 CDP/LLDP 回显生成链路邻居，并规划接口描述变更。
+    class Topology
+      # 设备入口与功能实现共置，Base 只组合能力，不重复业务流程。
+      module Capability
+        # 执行 CDP 或 LLDP 查询并返回统一的链路邻居记录。
+        def neighbors = Topology.new(self).neighbors
+
+        # 读取运行配置中的接口描述或端口名称。
+        def interface_descriptions = Topology.new(self).interface_descriptions
+
+        # 以邻居和现有配置为证据，生成待确认的接口描述变更计划。
+        def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
+        # 明确确认且现场证据未变化时执行接口描述计划。
+        def apply_interface_descriptions(plan, confirmed: false)
+          Topology.new(self).apply_interface_descriptions(plan, confirmed: confirmed)
+        end
+      end
+
+      Neighbor = Data.define(:local_interface, :neighbor_name, :neighbor_interface, :chassis_id, :protocol)
+      Change = Data.define(:interface, :old_description, :new_description, :neighbor)
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands)
+
+      # 保存设备及其独立的 TextFSM 解析入口。
+      def initialize(device, template_dir: nil)
+        require_relative "../textfsm"
+
+        @device = device
+        @parser = TextFSM.new(template_dir: template_dir)
+        @strategy = (device.profile.topology_strategy || Strategy).new(device)
+      end
+
+      # 执行厂商 CDP/LLDP 命令，返回统一的邻居记录。
+      def neighbors
+        command = @strategy.neighbor_command
+        unless @strategy.supports?(:neighbors) && command
+          raise UnsupportedOperation.new("this device cannot discover LLDP neighbors",
+                                         code: :neighbor_discovery_unsupported, host: @device.host, phase: :discover)
+        end
+
+        output = TerminalText.utf8(@device.execute_command(command).value!, host: @device.host)
+        template = @strategy.neighbor_template(output)
+        rows = @parser.call(output, template: template, vendor: @device.vendor, command: command, host: @device.host)
+        if rows.size != @strategy.expected_neighbor_count(output, template) || (rows.empty? && !@strategy.empty_neighbor_output?(output))
+          raise ParsingError.new("neighbor output was not recognized", code: :unrecognized_output,
+                                 host: @device.host, phase: :discover)
+        end
+
+        rows.map do |row|
+          Neighbor.new(local_interface: row.fetch("LOCAL_INTERFACE").strip.freeze,
+                       neighbor_name: row.fetch("NEIGHBOR_NAME", "").strip.freeze,
+                       neighbor_interface: row.fetch("NEIGHBOR_INTERFACE").strip.freeze,
+                       chassis_id: row.fetch("CHASSIS_ID", "").strip.freeze,
+                       protocol: @strategy.protocol).freeze
+        end
+      end
+
+      # 从运行配置读取已设置的接口描述或端口名称。
+      def interface_descriptions = read_interface_descriptions
+
+      # 内部读取先交付执行步骤，再处理解析；解析失败也不能抹去已经完成的采集命令。
+      def read_interface_descriptions
+        template = @strategy.description_template
+        unless @strategy.supports?(:interface_descriptions) && template
+          raise UnsupportedOperation.new("interface descriptions are unsupported for this vendor",
+                                         code: :description_unsupported, host: @device.host, phase: :discover)
+        end
+        result = @device.running_config
+        yield result if block_given?
+        config = result.value!
+        rows = @parser.call(config, template: template, host: @device.host)
+        @strategy.validate_descriptions!(config, rows)
+        rows.each_with_object({}) do |row, found|
+          interface = @strategy.interface_key(row.fetch("INTERFACE"))
+          description = @strategy.decode_description(row.fetch("DESCRIPTION", ""))
+          previous = found[interface]
+          if previous && !previous.empty? && !description.empty? && previous != description
+            raise ParsingError.new("interface has conflicting descriptions", code: :ambiguous_description,
+                                   host: @device.host, phase: :parse)
+          end
+          found[interface] = description unless description.empty? && previous
+        end
+      end
+
+      private :read_interface_descriptions
+
+      # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
+      def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        validate_change_support!(:plan) if @strategy.supports?(:neighbors)
+        discovered = neighbors
+        current = interface_descriptions
+        current.each_value(&:freeze)
+        evidence = evidence_for(discovered, current)
+        changes = discovered.filter_map do |neighbor|
+          old = current.fetch(@strategy.interface_key(neighbor.local_interface))
+          proposed = if formatter
+                       formatter.call(neighbor)
+                     else
+                       InterfaceDescription.format(neighbor, abbreviate: abbreviate, lowercase: lowercase)
+                     end
+          InterfaceDescription.validate!(proposed)
+          next if old == proposed
+
+          Change.new(interface: @strategy.configuration_interface(neighbor.local_interface).freeze, old_description: old.freeze,
+                     new_description: proposed.freeze, neighbor: neighbor).freeze
+        end.freeze
+        commands = if changes.empty?
+                     []
+                   else
+                     stage_scripts(changes).values.flat_map { |script| script.map(&:text) }
+                   end
+        commands.each(&:freeze)
+        Plan.new(host: @device.host.dup.freeze, vendor: @device.vendor, evidence: evidence,
+                 changes: changes, commands: commands.freeze).freeze
+      end
+
+      # 只有明确确认且邻居和旧描述未变化时，才下发计划中的命令。
+      def apply_interface_descriptions(plan, confirmed: false)
+        unless confirmed == true
+          raise UnsupportedOperation.new("description plan requires confirmation", code: :confirmation_required,
+                                         host: @device.host, phase: :apply)
+        end
+        raise ArgumentError, "plan must be a topology plan for this device" unless plan.is_a?(Plan) &&
+                                                                                   plan.host == @device.host &&
+                                                                                   plan.vendor == @device.vendor
+        if plan.changes.empty?
+          raise ArgumentError, "empty topology plan cannot contain commands" unless plan.commands.empty?
+
+          return Result.new
+        end
+
+        @strategy.supports?(:neighbors) ? validate_change_support!(:apply) : neighbors
+        @device.with_operation(:apply) { apply_plan(plan) }
+      end
+
+      private
+
+      # 同一租约覆盖重验、修改、读回与保存；有完成步骤后发生的错误必须带回这些步骤。
+      def apply_plan(plan)
+        stages = stage_scripts(plan.changes)
+        unless stages.values.flat_map { |script| script.map(&:text) } == plan.commands
+          raise ArgumentError, "plan commands were modified or use an older execution sequence; regenerate the plan"
+        end
+        revalidate_plan!(plan)
+        steps = []
+        result = execute_stage(stages.fetch(:change), steps)
+        return Result.new(steps: steps, error: result.error) if result.failure?
+
+        verify_descriptions!(plan.changes, stages.fetch(:verify), steps)
+        persisting = true
+        result = execute_stage(stages.fetch(:persist), steps)
+        if result.failure? || !@strategy.persistence_confirmed?(result)
+          return Result.new(steps: steps, error: build_persistence_error(result.error))
+        end
+        Result.new(steps: steps)
+      rescue Error => error
+        raise unless steps
+
+        Result.new(steps: steps, error: persisting ? build_persistence_error(error) : error)
+      end
+
+      # 读回命令与审批一致，并且每个目标描述均得到确认，才允许进入保存阶段。
+      def verify_descriptions!(changes, script, steps)
+        unless Script.new(@device.config_commands).map(&:text) == script.map(&:text)
+          raise DeviceError.new("configuration readback commands changed after approval",
+                                code: :verification_plan_changed, host: @device.host, phase: :verify)
+        end
+        updated = read_interface_descriptions do |readback|
+          steps.concat(readback.steps)
+          if readback.success? && readback.steps.map { |step| step.command.text } != script.map(&:text)
+            raise DeviceError.new("configuration readback did not execute the approved commands",
+                                  code: :verification_plan_changed, host: @device.host, phase: :verify)
+          end
+        end
+        unless changes.all? { |change| updated[@strategy.interface_key(change.interface)] == change.new_description }
+          raise DeviceError.new("interface descriptions were not confirmed by readback",
+                                code: :description_unconfirmed, host: @device.host, phase: :verify)
+        end
+      end
+
+      # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
+      def revalidate_plan!(plan)
+        discovered = neighbors
+        evidence = evidence_for(discovered, interface_descriptions)
+        current_neighbors = discovered.to_h { |neighbor| [@strategy.interface_key(neighbor.local_interface), neighbor] }
+        same_neighbors = plan.changes.all? do |change|
+          current_neighbors[@strategy.interface_key(change.interface)] == change.neighbor
+        end
+        unless evidence == plan.evidence && same_neighbors
+          raise DeviceError.new("neighbors or interface descriptions changed after planning",
+                                code: :stale_plan, host: @device.host, phase: :apply)
+        end
+
+        plan.changes.each do |change|
+          InterfaceDescription.validate!(change.new_description)
+          unless evidence.fetch(@strategy.interface_key(change.interface)) ==
+                 [change.neighbor.neighbor_name, change.neighbor.neighbor_interface, change.old_description]
+            raise ArgumentError, "plan changes do not match its discovery evidence"
+          end
+        end
+      end
+
+      # 审批列表保留真正执行的读回命令，使旧版“先保存后读回”计划无法静默复用。
+      def stage_scripts(changes)
+        phases = %i[leave_configuration_commands verification_commands persistence_commands].map do |method|
+          @strategy.public_send(method)
+        end
+        unless phases.all? { |commands| commands.is_a?(Array) && !commands.empty? }
+          raise UnsupportedOperation.new("topology strategy must declare separate readback and persistence stages",
+                                         code: :description_stages_unsupported, host: @device.host, phase: :plan)
+        end
+        leave, verify, persist = phases
+        sequences = {
+          change: [@strategy.enter_configuration_command] + changes.flat_map { |change| change_commands(change) } + leave,
+          verify: verify, persist: persist
+        }
+        sequences.transform_values do |commands|
+          Script.new(commands.map { |command| @strategy.script_command(command) }, name: "interface descriptions")
+        end
+      end
+
+      def execute_stage(script, steps)
+        result = @device.execute_script(script)
+        steps.concat(result.steps)
+        result
+      end
+
+      # 保存可能已执行，超时、失败或缺少完成行均不自动重放；诊断不附带回显正文。
+      def build_persistence_error(error = nil)
+        underlying = UnderlyingError.new(error, nil, sensitive: true) if error
+        DeviceError.new("interface descriptions were verified; persistence was not confirmed",
+                        code: :persistence_unconfirmed, host: @device.host, phase: :persist, underlying: underlying)
+      end
+
+      # 下发描述前确认厂商提供配置能力，避免把只读发现当成可写能力。
+      def validate_change_support!(phase)
+        return if @strategy.supports?(:interface_description_changes)
+
+        raise UnsupportedOperation.new("automatic interface description changes are unavailable; use a verified manual workflow",
+                                       code: @strategy.change_error_code, host: @device.host, phase: phase)
+      end
+
+      # 汇总邻居身份和当前描述，并要求每个目标接口都有配置证据。
+      def evidence_for(discovered, current)
+        interfaces = discovered.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+        if interfaces.any? { |_interface, peers| peers.size != 1 || peers.first.neighbor_name.empty? ||
+          peers.first.neighbor_interface.empty? }
+          raise ParsingError.new("neighbor identity is incomplete or ambiguous", code: :ambiguous_neighbor,
+                                 host: @device.host, phase: :plan)
+        end
+        unless interfaces.keys.all? { |interface| current.key?(interface) }
+          raise ParsingError.new("neighbor interface was not found in running configuration",
+                                 code: :interface_missing, host: @device.host, phase: :plan)
+        end
+
+        interfaces.transform_values do |peers|
+          peer = peers.fetch(0)
+          [peer.neighbor_name, peer.neighbor_interface, current.fetch(@strategy.interface_key(peer.local_interface))].freeze
+        end.freeze
+      end
+
+      # 设备标识来自解析证据，仍需在生成命令前验证其安全性。
+      def change_commands(change)
+        InterfaceDescription.validate_interface!(change.interface)
+        @strategy.change_commands(change)
+      end
+    end
+  end
+end

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

@@ -61,7 +61,7 @@ module Net
       def login_interactions
         host_key = Interaction.new(SSH_CONFIRMATION, lambda { |_prompt|
           if @config.host_key_policy == :strict
-            raise @session.error(ConnectionError, "host key confirmation rejected",
+            raise @session.build_error(ConnectionError, "host key confirmation rejected",
                                  phase: :login, code: :host_key_untrusted), cause: nil
           end
           "yes\n"

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

@@ -37,7 +37,7 @@ module Net
         @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?(:formatter) || !logger.respond_to?(:level))
+          !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

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

@@ -134,7 +134,7 @@ module Net
           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)
+          validate_event!(event, bytes, raw, phase, command)
 
           if event.index == patterns.size
             raw << event.match
@@ -142,7 +142,7 @@ module Net
           elsif event.index == patterns.size - 1
             return finish_response(event.match, raw, output, phase, command)
           elsif event.index < failures.size
-            raise connection_error(failures.values.fetch(event.index), phase, command), cause: nil
+            raise build_connection_error(failures.values.fetch(event.index), phase, command), cause: nil
           else
             reply = interactions.fetch(event.index - failures.size)
             raw << event.match
@@ -151,7 +151,7 @@ module Net
           end
           next if Expect.monotonic < deadline
 
-          raise read_error(nil, phase, command, raw.join), cause: nil
+          raise build_read_error(nil, phase, command, raw.join), cause: nil
         end
       end
 
@@ -163,24 +163,24 @@ module Net
       end
 
       # 连接失败模式携带稳定错误码，供连接级恢复规则选择处理方式。
-      def connection_error(failure, phase, command)
+      def build_connection_error(failure, phase, command)
         klass, code = failure
-        @session.error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
+        @session.build_error(klass, "device connection failed (#{code})", phase: phase, code: code, command: command)
       end
 
       # 先限制原始字节数，再处理传输失败，避免错误输出绕过总量限制。
-      def validate_event(event, bytes, raw, phase, command)
+      def validate_event!(event, bytes, raw, phase, command)
         if bytes > @session.configuration.max_output_bytes
-          raise @session.error(OutputLimitExceeded, "device output exceeded 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 read_error(event, phase, command, raw.join), cause: nil unless event.matched?
+        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.error(PromptError, "prompt pattern did not consume any output",
+          raise @session.build_error(PromptError, "prompt pattern did not consume any output",
                                phase: phase, command: command, output: raw.join), cause: nil
         end
 
@@ -194,11 +194,11 @@ module Net
       def respond(reply, prompt, counts, deadline, phase, command)
         counts[reply] += 1
         if prompt.empty? || (reply.limit && counts[reply] > reply.limit)
-          raise interaction_error("response rejected or repeated", phase, command), cause: nil
+          raise build_interaction_error("response rejected or repeated", phase, command), cause: nil
         end
 
         value = interaction_response(reply, prompt, phase, command)
-        raise interaction_error("response unavailable", phase, command), cause: nil unless value.is_a?(String)
+        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)
@@ -209,7 +209,7 @@ module Net
       def interaction_response(reply, prompt, phase, command)
         return reply.response(prompt) unless reply.sensitive?
 
-        @session.redactor.scope(reuse: true) do
+        @session.redactor.with_scope(reuse: true) do
           @session.redactor.sensitive!
           reply.response(prompt)
         rescue => error
@@ -218,17 +218,17 @@ module Net
       end
 
       # 将交互拒绝或响应缺失转换为认证或脚本错误。
-      def interaction_error(message, phase, command)
+      def build_interaction_error(message, phase, command)
         authenticating = %i[login enable].include?(phase)
         klass = authenticating ? AuthenticationError : ScriptError
         label = authenticating ? "authentication" : "command interaction"
-        @session.error(klass, "#{label} #{message}", phase: phase, command: command)
+        @session.build_error(klass, "#{label} #{message}", phase: phase, command: command)
       end
 
       # 根据 EOF、提示符、阶段和底层异常选择具体读取错误类型。
-      def read_error(event, phase, command, output)
+      def build_read_error(event, phase, command, output)
         if event&.error.is_a?(Exception)
-          return @session.error(TransportError, "transport read failed", phase: phase, command: command,
+          return @session.build_error(TransportError, "transport read failed", phase: phase, command: command,
                                 underlying: event.error, output: output)
         end
         klass = if event&.error == :eof
@@ -240,7 +240,7 @@ module Net
                 else
                   CommandTimeout
                 end
-        @session.error(klass, "device response #{event&.error || :timeout}", phase: phase,
+        @session.build_error(klass, "device response #{event&.error || :timeout}", phase: phase,
                        command: command, output: output)
       end
     end

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

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