net-connector 0.8.0 → 0.9.0

data/lib/net/connector/netdisco/fleet.rb

@@ -129,8 +129,8 @@ module Net
 
           rules = @rules || settings_snapshot.rules
           devices = rows.map { |row| Device.from_row(row, rules: rules) }
-          duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
-          devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
+          host_counts = devices.each_with_object(Hash.new(0)) { |device, counts| counts[device.host] += 1 if device.host }
+          devices.map { |device| host_counts[device.host] > 1 ? device.with(issue: :duplicate_host) : device }.freeze
         end
 
         def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false)

data/lib/net/connector/netdisco/plan.rb

@@ -25,6 +25,9 @@ module Net
         # 按清单顺序返回选中的设备。
         def selected = ready.map(&:last)
 
+        # 更新与新建共用容器复制边界，不能因 Ruby 版本差异共享可变任务槽位。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 在任何设备 I/O 前校验完整快照，外部构造或修改的计划也必须遵守相同约束。
         def validate!
           raise ArgumentError, "plan mode must be backup or tftp" unless %i[backup tftp].include?(mode)
@@ -72,10 +75,16 @@ module Net
 
         # 外部快照也遵守清单入口的地址唯一性；采样不能把重复设备重新变为可执行。
         def validate_duplicate_hosts!
-          groups = inventory.group_by { |device| device.host && IPAddr.new(device.host).to_s }
-          return unless groups.any? { |host, devices| host && devices.size > 1 && devices.any? { |device| device.issue != :duplicate_host } }
+          issues_by_host = {}
+          inventory.each do |device|
+            next unless device.host
 
-          raise ArgumentError, "plan duplicate hosts must be marked as duplicate_host"
+            host = IPAddr.new(device.host).to_s
+            if issues_by_host.key?(host) && (issues_by_host[host] != :duplicate_host || device.issue != :duplicate_host)
+              raise ArgumentError, "plan duplicate hosts must be marked as duplicate_host"
+            end
+            issues_by_host[host] = device.issue
+          end
         end
 
         # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。

data/lib/net/connector/netdisco/progress.rb

@@ -11,6 +11,7 @@ module Net
       class Progress
         attr_reader :output_error
 
+        # 调用方保留输出 IO 所有权；同一个互斥锁保护心跳、事件和任务计数。
         def initialize(io: $stderr, enabled: true, verbose: false)
           @io, @enabled, @verbose = io, enabled, verbose
           @tty = io.respond_to?(:tty?) && io.tty?
@@ -27,6 +28,7 @@ module Net
           write(nil, "正在读取 Netdisco 设备清单")
         end
 
+        # 以实际选中设备初始化进度，清单中被跳过的条目不计入执行任务总数。
         def plan(plan, concurrency:, limit_per_vendor: nil)
           @mutex.synchronize do
             @total = plan.ready.size
@@ -37,6 +39,7 @@ module Net
           end
         end
 
+        # 任务开始时记录单调时钟与登录阶段，不把开始通知当作连接成功。
         def start(device)
           @mutex.synchronize do
             @active += 1
@@ -75,6 +78,7 @@ module Net
           write(fields[:host], message) if message
         end
 
+        # 只消费最终任务结果，分别展示已保存、设备报告上传和服务器核验状态。
         def result(outcome)
           @mutex.synchronize do
             @completed += 1
@@ -104,6 +108,7 @@ module Net
           end
         end
 
+        # 使用报告的成功策略与受控失败分类，进度百分比不代替业务成功判定。
         def finish(report)
           return unless @enabled
 
@@ -148,6 +153,7 @@ module Net
           end
         end
 
+        # 心跳仅在持锁后刷新显示，不改变设备任务或完成计数。
         def tick
           @mutex.synchronize { refresh(force: true) }
         end
@@ -182,6 +188,7 @@ module Net
           format("%02d:%02d:%02d", total / 3600, total / 60 % 60, total % 60)
         end
 
+        # 吞吐与预计剩余时间使用单调时钟；异构设备的估算不能视为任务期限。
         def timing_line
           elapsed = [monotonic - (@run_started || @started_at), 0].max
           rate = elapsed.positive? ? @completed / elapsed : 0
@@ -200,6 +207,7 @@ module Net
           line
         end
 
+        # TTY 原地刷新最多每秒五次；详细事件和重定向输出采用独立显示路径。
         def refresh(force: false)
           return unless @enabled && @tty && !@verbose
 
@@ -230,6 +238,7 @@ module Net
           line
         end
 
+        # 擦除前一次实际显示的行数，避免短文本或窄终端留下旧状态。
         def clear_refresh
           return unless @refreshing
 

data/lib/net/connector/netdisco/report/files.rb

@@ -9,6 +9,7 @@ module Net
       class Report
         # 示例与批次入口共享唯一摘要结构；保存结果先于终端成功提示。
         class Files
+          # 文本和 JSON 分别提交；失败时尝试保存诊断，并保留已提交的 JSON 位置。
           def self.write(report, directory:, plan:, concurrency:)
             destination = File.join(directory, "summary.json")
             finalized = report.with(report_location: destination)

data/lib/net/connector/netdisco/result_store.rb

@@ -8,6 +8,7 @@ require_relative "../storage/private_file"
 module Net
   module Connector
     module Netdisco
+      # 调用方选择结果持久化方式；所有写入器接收同一份 Report，不再次执行设备任务。
       module ResultStore
         # 每批保存一份私有 JSON 报告，通过重命名防止半写文件。
         class Json

data/lib/net/connector/netdisco/rules.rb

@@ -94,11 +94,13 @@ module Net
 
         # 根据地址、显式规则和厂商信息识别连接器。
         def resolve(row)
-          begin
-            address = IPAddr.new(row["ip"]).to_s
-            return @host_overrides.fetch(address) if @host_overrides.key?(address)
-          rescue IPAddr::Error, TypeError
-            # 无效的管理地址交由 Device.from_row 标记。
+          unless @host_overrides.empty?
+            begin
+              address = IPAddr.new(row["ip"]).to_s
+              return @host_overrides.fetch(address) if @host_overrides.key?(address)
+            rescue IPAddr::Error, TypeError
+              # 无效的管理地址交由 Device.from_row 标记。
+            end
           end
           label = normalize(row["vendor"])
           os = normalize(row["os"])

data/lib/net/connector/netdisco/settings.rb

@@ -16,21 +16,24 @@ module Net
         DEFAULT_BACKUP_DIRECTORY = "backups"
         DEFAULT_CONCURRENCY = 4
         MAX_CONCURRENCY = 50
-        ENVIRONMENT_KEYS = %w[NETDISCO_URL NC_BACKUP_DIRECTORY NC_CONCURRENCY NC_SAMPLE_PER_VENDOR
-                              NC_PROTOCOL NC_KNOWN_HOSTS NC_HOST_KEY_POLICY NC_LOG_DIRECTORY NC_LOG_LEVEL TFTP_HOST].freeze
+        # 这里只列可从环境读取的公开策略；凭据单独动态读取，其他内部键只供 YAML/CLI 使用。
+        ENVIRONMENT_KEYS = %w[ND_URL].freeze
         DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
         UNSET = Object.new.freeze
         private_constant :UNSET
 
+        # 加载无凭据 YAML 作为默认策略，保留传入环境作为动态凭据来源。
         def self.from_file(path, env: ENV)
           new(env: env, defaults: ConfigFile.load(path))
         end
 
+        # 只有 NC_CONFIG 显式指定时才读取文件，不隐式加载 .env。
         def self.from_env(env: ENV)
           path = env["NC_CONFIG"]
           path && !path.empty? ? from_file(path, env: env) : new(env: env)
         end
 
+        # 分开保存默认策略、显式覆盖与凭据来源；fixed 实例只承载已复制的公开快照。
         def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
           @env, @defaults, @overrides = env, defaults, overrides
           @policy, @fixed = policy, fixed
@@ -38,7 +41,14 @@ module Net
 
         # 调用入口补充运行目录等非敏感覆盖，凭据仍从同一来源读取。
         def with_overrides(values)
-          self.class.new(env: @env, defaults: @defaults, overrides: @overrides.merge(values))
+          if @fixed
+            public_values = @env.merge(@overrides).merge(values).slice(*non_secret_keys)
+                                .transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+            return self.class.new(env: public_values, fixed: true).freeze
+          end
+
+          policy = @policy.with_overrides(values) if @policy
+          self.class.new(env: @env, defaults: @defaults, overrides: @overrides.merge(values), policy: policy)
         end
 
         # 快照自身不保留 ENV、凭据 resolver 或原 Settings 的引用，不能携带秘密进入摘要。
@@ -61,6 +71,7 @@ module Net
           self.class.new(env: @env, defaults: @defaults, overrides: @overrides, policy: snapshot(mode: mode))
         end
 
+        # 按业务模式预检所有策略；离线导出仅验证目录，不读取清单或设备凭据。
         def validate!(mode:)
           unless %i[backup tftp inventory show_config export].include?(mode)
             raise ArgumentError, "unknown settings validation mode"
@@ -73,7 +84,9 @@ module Net
           concurrency
           limit_per_vendor
           log_directory
+          tftp_root
           connection_options
+          database_options
           Net::Connector.vendors.each { |vendor| connection_options(vendor) }
           tftp_source_files.each_value { |source| TftpTarget.validate_source_file!(source) }
           tftp_vrfs
@@ -81,6 +94,7 @@ module Net
           self
         end
 
+        # 用固定策略创建清单客户端，但每次读取最新身份凭据；显式认证覆盖默认认证来源。
         def client(policy: snapshot(mode: :inventory), credentials: nil)
           if credentials && (!credentials.is_a?(Hash) || credentials.keys.sort != %i[password username] ||
             !credentials.values.all? { |value| present?(value) })
@@ -88,28 +102,29 @@ module Net
           end
           options = policy.client_options
           if policy.inventory_source == :postgres
-            connection = DatabaseClient::CONNECTION_ENV.each_with_object({}) do |(key, name), values|
+            connection = DatabaseClient::CONNECTION_ENV.each_with_object(policy.database_options.dup) do |(key, name), values|
               item = secret_value(name)
               values[key] = item if item
             end
             connection.merge!(user: credentials[:username], password: credentials[:password]) if credentials
             return DatabaseClient.new(connection_options: connection, **options)
           end
-          raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
+          raise ArgumentError, "ND_URL is required" unless options.fetch(:url)
 
           authentication = if credentials
                              credentials
-                           elsif (token = secret_value("NETDISCO_API_KEY"))
+                           elsif (token = secret_value("ND_API_KEY"))
                              { api_key: token }
                            else
-                             { username: required_secret("NETDISCO_USERNAME"), password: required_secret("NETDISCO_PASSWORD") }
+                             { username: required_secret("ND_USERNAME"), password: required_secret("ND_PASSWORD") }
                            end
           Client.new(**options, **authentication)
         end
 
+        # 清单来源来自 YAML/CLI，HTTP 与 PostgreSQL 共用后续计划和执行接口。
         def inventory_source
-          source = value("NETDISCO_SOURCE") || "http"
-          raise ArgumentError, "NETDISCO_SOURCE must be http or postgres" unless %w[http postgres].include?(source)
+          source = value("ND_SOURCE") || "http"
+          raise ArgumentError, "ND_SOURCE must be http or postgres" unless %w[http postgres].include?(source)
 
           source.to_sym
         end
@@ -121,6 +136,7 @@ module Net
           inventory_source == :postgres ? postgres_options(options) : http_options(options)
         end
 
+        # 将筛选和映射策略交给 Rules 校验，未识别设备由清单结果单独标记。
         def rules
           Rules.new(include_hosts: list("NC_INCLUDE_HOSTS"),
                     exclude_hosts: list("NC_EXCLUDE_HOSTS"),
@@ -130,6 +146,7 @@ module Net
                     mappings: json("NC_DEVICE_RULES", []))
         end
 
+        # 将备份目录解析为绝对路径；这里只校验配置，不创建目录。
         def backup_directory
           path = raw("NC_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
           raise ArgumentError, "NC_BACKUP_DIRECTORY must be nonempty" unless present?(path)
@@ -137,6 +154,7 @@ module Net
           File.expand_path(path)
         end
 
+        # 与 Worker 共用并发上限，非法值在任务与目录创建前失败。
         def concurrency
           count = integer("NC_CONCURRENCY", DEFAULT_CONCURRENCY)
           raise ArgumentError, "NC_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
@@ -144,6 +162,7 @@ module Net
           count
         end
 
+        # 显式 nil 表示全量；tftp: true 且未设置时采用五台上限，示例入口另外选择全量。
         def limit_per_vendor(tftp: false)
           count = if configured?("NC_SAMPLE_PER_VENDOR")
                     integer("NC_SAMPLE_PER_VENDOR", 5) unless raw("NC_SAMPLE_PER_VENDOR").nil?
@@ -154,6 +173,7 @@ module Net
           count
         end
 
+        # 华为批次默认上传 startup.cfg；H3C 省略源文件时由设备策略探测。
         def tftp_source_files
           files = { huawei: raw("NC_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
           %i[h3c h3c_wireless].each do |vendor|
@@ -163,6 +183,7 @@ module Net
           files
         end
 
+        # 按厂商读取 VRF 映射，不能把不支持 VRF 的厂商静默忽略。
         def tftp_vrfs
           mapping = json("NC_TFTP_VRFS", {})
           raise ArgumentError, "NC_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
@@ -170,6 +191,7 @@ module Net
           self.class.validate_vrfs!(mapping.transform_keys(&:to_sym))
         end
 
+        # 只允许 NX-OS、山石的安全单一 VRF 名称，禁止命令拼接字符。
         def self.validate_vrfs!(vrfs)
           unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, name|
             %i[cisco_nxos hillstone].include?(vendor) && name.is_a?(String) &&
@@ -180,8 +202,32 @@ module Net
           vrfs
         end
 
-        def tftp_server = value("TFTP_HOST")
+        # 服务器地址只来自 YAML/CLI 的公开策略，不从 NC_TFTP_HOST 环境变量读取。
+        def tftp_server = value("NC_TFTP_HOST")
+
+        # 本机核验根目录属于策略快照，解析路径不证明文件已经上传。
+        def tftp_root
+          path = value("NC_TFTP_ROOT")
+          File.expand_path(path) if path
+        end
+
+        # 端口、TLS 与连接超时进入固定策略；主机、数据库名和登录凭据仍从环境读取。
+        def database_options
+          options = {}
+          %i[port connect_timeout].each do |name|
+            key = "ND_DB_#{name.to_s.upcase}"
+            next unless configured?(key)
 
+            options[name] = integer(key, nil)
+          end
+          %i[sslmode sslrootcert].each do |name|
+            item = value("ND_DB_#{name.to_s.upcase}")
+            options[name] = item if item
+          end
+          DatabaseClient.connection_policy(**options)
+        end
+
+        # 经 Configuration 复用连接校验；厂商协议覆盖通用协议，不包含设备凭据。
         def connection_options(vendor = nil)
           configuration = Configuration.new(
             protocol: vendor_protocols[vendor.to_s] || value("NC_PROTOCOL") || "ssh",
@@ -194,6 +240,7 @@ module Net
           options.freeze
         end
 
+        # 厂商协议必须使用已登记的厂商键和 ssh/telnet，不接受未知映射。
         def vendor_protocols
           values = json("NC_VENDOR_PROTOCOLS", {})
           unless values.is_a?(Hash) && values.all? { |vendor, protocol| Net::Connector.vendors.map(&:to_s).include?(vendor) && %w[ssh telnet].include?(protocol) }
@@ -202,6 +249,7 @@ module Net
           values
         end
 
+        # 每台任务读取最新厂商凭据，缺失字段回退到通用凭据；无用户名时跳过设备。
         def device_credentials_for(device)
           prefix = "NC_#{device.vendor.to_s.upcase}_"
           username = secret_value(prefix + "USERNAME") || secret_value("NC_DEVICE_USERNAME")
@@ -212,11 +260,13 @@ module Net
             enable_password: secret_value(prefix + "ENABLE_PASSWORD") || secret_value("NC_ENABLE_PASSWORD") }
         end
 
+        # 会话日志目录属于公开策略；调用方和批次入口负责实际创建。
         def log_directory
           path = value("NC_LOG_DIRECTORY")
           File.expand_path(path) if path
         end
 
+        # 生成已验证的无凭据配置摘要，不展开原环境或 resolver。
         def public_config
           snapshot(mode: :show_config).config_hash
         end
@@ -225,9 +275,10 @@ module Net
 
         protected
 
+        # 只输出公开策略；数据库身份和设备凭据不得通过配置摘要进入报告。
         def config_hash
           {
-            netdisco: client_options.merge(source: inventory_source),
+            netdisco: client_options.merge(source: inventory_source, database: database_options),
             backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
             inventory: { include_hosts: list("NC_INCLUDE_HOSTS"),
                          exclude_hosts: list("NC_EXCLUDE_HOSTS"),
@@ -239,10 +290,11 @@ module Net
               log_directory: log_directory,
               vendor_protocols: vendor_protocols
             ),
-            tftp: { server: tftp_server, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
+            tftp: { server: tftp_server, verification_root: tftp_root, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
           }
         end
 
+        # 优先读取固定策略或显式覆盖；内部键的名称不表示该键可由进程环境配置。
         def raw(key, default = nil)
           return @policy.raw(key, default) if @policy
           return @overrides.fetch(key) if @overrides.key?(key)
@@ -260,7 +312,7 @@ module Net
 
         def client_budget_options(defaults)
           defaults.to_h do |name, default|
-            key = "NETDISCO_#{name.to_s.upcase}"
+            key = "ND_#{name.to_s.upcase}"
             parsed = case name
                      when :inventory_timeout then number(key, default)
                      when :allow_insecure_http then boolean(key, default)
@@ -271,16 +323,16 @@ module Net
         end
 
         def postgres_options(options)
-          query = value("NETDISCO_QUERY") || (raise ArgumentError, "NETDISCO_QUERY is required for postgres")
-          DatabaseClient.options(query: query, query_params: json("NETDISCO_QUERY_PARAMS", []), **options)
+          query = value("ND_QUERY") || (raise ArgumentError, "ND_QUERY is required for postgres")
+          DatabaseClient.options(query: query, query_params: json("ND_QUERY_PARAMS", []), **options)
         end
 
         def http_options(options)
-          if value("NETDISCO_QUERY") || value("NETDISCO_QUERY_PARAMS")
-            raise ArgumentError, "SQL query settings require NETDISCO_SOURCE=postgres"
+          if value("ND_QUERY") || value("ND_QUERY_PARAMS")
+            raise ArgumentError, "SQL query settings require ND_SOURCE=postgres"
           end
           options = Client.options(**options)
-          url = value("NETDISCO_URL")
+          url = value("ND_URL")
           Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
           options.merge(url: url).freeze
         end
@@ -289,11 +341,16 @@ module Net
           ConfigFile::FIELDS.values.flat_map { |section| section.values.map(&:first) }
         end
 
+        # 旧前缀和已移除策略明确报错；错误只包含变量名，不泄露变量值。
         def validate_environment!
           legacy = @env.keys.find { |key| key.start_with?("NET_CONNECTOR_") }
-          raise ArgumentError, "#{legacy} has been renamed to #{legacy.sub("NET_CONNECTOR_", "NC_")}" if legacy
+          raise ArgumentError, "#{legacy} is unsupported; use NC_ credentials or YAML via NC_CONFIG" if legacy
+
+          legacy = @env.keys.find { |key| key.start_with?("NETDISCO_", "TFTP_") }
+          raise ArgumentError, "#{legacy} is unsupported; use ND_ credentials or YAML via NC_CONFIG" if legacy
 
           removed = non_secret_keys - ENVIRONMENT_KEYS
+          removed << "NC_PROGRESS"
           removed += Net::Connector.vendors.map { |vendor| "NC_#{vendor.to_s.upcase}_PROTOCOL" }
           key = removed.find { |name| @env.key?(name) }
           raise ArgumentError, "#{key} is no longer an environment setting; use YAML via NC_CONFIG or CLI options" if key
@@ -349,6 +406,7 @@ module Net
           result if present?(result)
         end
 
+        # 凭据只从活的环境映射读取并复制，不允许 defaults/overrides 充当秘密来源。
         def secret_value(key)
           result = @env[key]
           raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)

data/lib/net/connector/netdisco/tftp_archive.rb

@@ -17,6 +17,7 @@ module Net
         BATCH_DIRECTORY_NAME = /\A\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:_\d{2})?\z/
         private_constant :BATCH_DIRECTORY_NAME
 
+        # 固定名上传无法保留历史时，在设备上传之前拒绝执行。
         class Unavailable < Net::Connector::Error
           def initialize(host: nil)
             super("a local TFTP root is required to retain a fixed-name upload", code: :tftp_history_unavailable,
@@ -24,6 +25,7 @@ module Net
           end
         end
 
+        # 设备可能已经上传，归档失败不能撤销或重新执行设备命令。
         class ArchiveFailed < Net::Connector::Error
           def initialize(host: nil)
             super("the uploaded file could not be retained in the batch", code: :tftp_archive_failed,
@@ -40,6 +42,7 @@ module Net
           @verifier = TftpVerification.new(root: @server_root)
         end
 
+        # 有本机根目录时保留原名并归档；远端服务器使用批次后缀避免重复覆盖。
         def upload_filename(device)
           name = device.tftp_filename
           return name if @server_root || device.vendor == :palo_alto
@@ -50,6 +53,7 @@ module Net
           TftpTarget.validate_path!("#{stem.byteslice(0, TftpTarget::MAX_PATH_BYTES - suffix.bytesize)}#{suffix}")
         end
 
+        # 上传与归档在同一目标锁内完成，后续失败仍保留可确认的上传回执和提交路径。
         def upload_and_archive(device, started_at:)
           raise Unavailable.new(host: device.host) if device.vendor == :palo_alto && !@server_root
 

data/lib/net/connector/netdisco/worker.rb

@@ -60,7 +60,7 @@ module Net
               threads.each do |thread|
                 begin
                   thread.join
-                rescue Exception # rubocop:disable Lint/RescueException -- Preserve the original interruption after all workers stop.
+                rescue Exception # rubocop:disable Lint/RescueException -- 等待全部工作线程停止，不让收尾异常覆盖原中断。
                   nil
                 end
               end

data/lib/net/connector/storage/private_file.rb

@@ -18,8 +18,12 @@ module Net
 
           def committed? = state != :not_committed
           def durable? = state == :durable
+
+          # 阶段更新仍校验状态并冻结路径，Ruby 3.2 也不能绕过初始化约束。
+          def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
         end
 
+        # 写入失败仍携带阶段与提交回执，调用方据此区分未替换和已替换文件。
         class WriteError < IOError
           attr_reader :receipt, :code, :underlying_type
 
@@ -41,8 +45,10 @@ module Net
           def inspect = "#<#{self.class} state=#{receipt.state} phase=#{receipt.phase}>"
         end
 
+        # 替换已经提交后的持久化或收尾失败，不能按尚未写入处理。
         class PersistenceError < WriteError; end
 
+        # 目录同步能力缺失只表示持久性未确认，已替换的目标文件仍然保留。
         class DirectorySyncUnsupported < WriteError
           def initialize(**options)
             super

data/lib/net/connector/vendor/cisco_ios/running_config.rb

@@ -5,6 +5,7 @@ require_relative "../../device/running_config/strategy"
 module Net
   module Connector
     module CiscoIos
+      # 清理 IOS 响应头，保留 banner 和配置正文内的命令、时间等原始内容。
       class RunningConfig < Net::Connector::RunningConfig::Rendered
         # 每条命令已有独立响应；正文中的命令示例属于配置，不能按会话回显删除。
         # 只清理首个配置语句之前的时间注释，避免改写 banner 等多行文本。

data/lib/net/connector/vendor/cisco_ios/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module CiscoIos
+      # 通过交互复制运行配置，以设备的复制完成行确认上传。
       class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, vrf: nil)
@@ -12,6 +13,7 @@ module Net
           raise ArgumentError, "Cisco IOS TFTP backup does not use vrf" unless vrf.nil?
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
 
         # 构造当前厂商的 TFTP 导出交互脚本。

data/lib/net/connector/vendor/cisco_ios/topology.rb

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module CiscoIos
+      # 基于 CDP 证据规划接口描述，变更后读回确认，再执行独立保存阶段。
       class Topology < Topology::ImmediateStrategy
         # IOS 提供 CDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
@@ -26,6 +27,7 @@ module Net
         # 先回到执行视图读回，随后才执行档案中的保存命令。
         def leave_configuration_commands = ["end"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\A(?:\[OK\]|Copy complete\.)\z/i
 
         # 每个 Device ID 表示一条应由模板解析的邻居记录。

data/lib/net/connector/vendor/cisco_nxos/tftp_backup.rb

@@ -5,12 +5,14 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module CiscoNxos
+      # 在指定 VRF 上传 NX-OS 运行配置，默认使用 management。
       class TftpBackup < Tftp::Strategy
         # 在连接前拒绝当前厂商不支持的参数组合。
         def validate_options!(_target, source_file:, **)
           raise ArgumentError, "Cisco NX-OS does not use source_file" unless source_file.nil?
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(_target, **) = { configuration_kind: :running, format: :cfg }
 
         # 构造当前厂商的 TFTP 导出交互脚本。

data/lib/net/connector/vendor/h3c/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/file_upload"
 module Net
   module Connector
     module H3c
+      # 未指定源文件时探测 H3C 启动配置，显式文件不推断配置种类。
       class TftpBackup < Tftp::FileUpload
         # 自动探测选择的是启动配置；显式文件仍不能推断为运行或启动配置。
         def receipt_metadata(target, source_file:, explicit_source:)

data/lib/net/connector/vendor/h3c/topology.rb

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module H3c
+      # 适配 H3C LLDP 表头与接口视图，数量核对失败时禁止继续规划变更。
       class Topology < Topology::ImmediateStrategy
         TABLE_HEADER = /^\s*(?:System Name\s+Local Interface\b|(?:Local Interface|LocalIf)\s+)/i
         # H3C 提供 LLDP 邻居、配置描述读取和描述变更。
@@ -24,6 +25,7 @@ module Net
         # 返回用户视图读回；保存交给后续独立阶段。
         def leave_configuration_commands = ["return"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\ASaved the current configuration to mainboard device successfully\.\z/i
 
         # H3C 不同版本的列顺序不同，按表头选对应模板。

data/lib/net/connector/vendor/hillstone/running_config.rb

@@ -5,6 +5,7 @@ require_relative "../../device/running_config/strategy"
 module Net
   module Connector
     module Hillstone
+      # 山石配置保持原始文本，仅删除已识别的退格分页痕迹。
       class RunningConfig < Net::Connector::RunningConfig::Strategy
         # 去掉山石 CLI 用退格控制符绘制的分页痕迹。
         def clean(text) = text.gsub(/\x00?\x08+[ \t]+\x08+/, "")

data/lib/net/connector/vendor/hillstone/tftp_backup.rb

@@ -5,6 +5,7 @@ require_relative "../../device/tftp/strategy"
 module Net
   module Connector
     module Hillstone
+      # 导出山石启动配置，并从完成行确认设备实际使用的 dat 文件名。
       class TftpBackup < Tftp::Strategy
         # 山石原生导出的配置文件使用 dat 扩展名。
         def self.file_extension = "dat"
@@ -17,6 +18,7 @@ module Net
           raise ArgumentError, "Hillstone TFTP filename cannot contain a directory"
         end
 
+        # 声明本厂商实际导出的配置种类与格式，不推断服务器文件已核验。
         def receipt_metadata(target, **)
           { configuration_kind: :startup, format: :dat, requested_path: target.explicit_path? ? target.path : nil }
         end

data/lib/net/connector/vendor/hillstone/topology.rb

@@ -5,6 +5,7 @@ require_relative "../../device/topology/immediate_strategy"
 module Net
   module Connector
     module Hillstone
+      # 核对山石 LLDP 数据与总数，接口描述读回一致后才保存配置。
       class Topology < Topology::ImmediateStrategy
         # 山石提供 LLDP 邻居、配置描述读取和描述变更。
         def self.supports?(capability)
@@ -23,6 +24,7 @@ module Net
         # 退出配置视图后先读回，保存动作随后单独执行。
         def leave_configuration_commands = ["exit"]
 
+        # 只认可本厂商明确的保存完成行，设备提示符返回本身不能证明持久化。
         def persistence_pattern = /\ASaving configuration is finished\.?\z/i
 
         # 用数据行和设备报告的总数交叉核对，避免遗漏邻居。