net-connector 0.13.0 → 0.14.1

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "plan"
+require_relative "stages"
+
+module Net
+  module Connector
+    class Topology
+      # 逐接口区分可核实变更、未核实证据和只读平台；计划只包含明确获准的接口范围。
+      Audit = Data.define(:plan, :comparisons, :issues, :manual_required) do
+        def initialize(plan:, comparisons:, issues:, manual_required:)
+          raise ArgumentError, "audit plan must be a topology plan or nil" unless plan.nil? || plan.instance_of?(Plan)
+          unless [true, false].include?(manual_required) && comparisons.is_a?(Array) && issues.is_a?(Array)
+            raise ArgumentError, "invalid topology audit"
+          end
+          super(plan: plan, comparisons: copy_rows(comparisons), issues: copy_rows(issues), manual_required: manual_required)
+        end
+
+        def complete? = issues.empty?
+        def changes = comparisons.count { |entry| !%i[matches unverified].include?(entry[:status]) }
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
+        private
+
+        def copy_rows(rows)
+          rows.map do |row|
+            unless row.is_a?(Hash) && row.keys.all?(Symbol) && row.values.all? { |value| value.nil? || value.is_a?(String) || value.is_a?(Symbol) }
+              raise ArgumentError, "audit rows must contain scalar metadata"
+            end
+            row.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          end.freeze
+        end
+      end
+
+      # 纯计划构造器不连接设备；协议命令仍由策略及 Stages 生成。
+      class AuditBuilder
+        def initialize(host:, vendor:, strategy:, neighbors:, descriptions:, formatter:)
+          @host, @vendor, @strategy = host, vendor, strategy
+          @neighbors, @descriptions, @formatter = neighbors, descriptions, formatter
+          @comparisons, @issues, @evidence, @changes = [], [], {}, []
+        end
+
+        def call
+          groups = @neighbors.group_by { |neighbor| @strategy.interface_key(neighbor.local_interface) }
+          groups.each { |interface, peers| inspect_interface(interface, peers) }
+          writable = @strategy.supports?(:interface_description_changes)
+          plan = build_plan if writable
+          Audit.new(plan: plan, comparisons: @comparisons, issues: @issues,
+                    manual_required: !writable && @comparisons.any? { |entry| entry[:status] != :matches })
+        end
+
+        private
+
+        def inspect_interface(interface, peers)
+          peer = peers.first
+          current = @descriptions[interface]
+          row = { interface: peer.local_interface, neighbor: peer.neighbor_name, port: peer.neighbor_interface,
+                  current: current, expected: nil, status: :unverified }
+          @comparisons << row
+          if peers.size != 1 || peer.neighbor_name.empty? || peer.neighbor_interface.empty?
+            return reject_interface(row, :ambiguous_neighbor)
+          end
+          return reject_interface(row, :interface_missing) unless @descriptions.key?(interface)
+
+          proposed = @formatter.call(peer)
+          InterfaceDescription.validate!(proposed)
+          local = @strategy.configuration_interface(peer.local_interface)
+          InterfaceDescription.validate_interface!(local)
+          row.merge!(expected: proposed, status: compare_status(current, proposed))
+          @evidence[interface] = [peer.neighbor_name, peer.neighbor_interface, current]
+          return if current == proposed
+
+          @changes << Change.new(interface: local, old_description: current, new_description: proposed, neighbor: peer)
+        rescue ArgumentError
+          reject_interface(row, :unsafe_description)
+        end
+
+        def reject_interface(row, code)
+          row[:reason] = code
+          @issues << { interface: row[:interface], code: code }
+          nil
+        end
+
+        def compare_status(current, proposed)
+          return :matches if current == proposed
+          return :missing_description if current.empty?
+
+          :content_mismatch
+        end
+
+        def build_plan
+          commands = if @changes.empty?
+                       []
+                     else
+                       Stages.build(strategy: @strategy, host: @host, changes: @changes).values.flat_map { |script| script.map(&:text) }
+                     end
+          Plan.new(host: @host, vendor: @vendor, evidence: @evidence, changes: @changes, commands: commands, scope: :interfaces)
+        end
+      end
+      private_constant :AuditBuilder
+    end
+  end
+end

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

@@ -6,17 +6,17 @@ module Net
   module Connector
     class Topology
       # 审批树在领域边界固定；单设备与批量操作共享同一不可变计划。
-      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands) do
-        def initialize(host:, vendor:, evidence:, changes:, commands:)
+      Plan = Data.define(:host, :vendor, :evidence, :changes, :commands, :scope) do
+        def initialize(host:, vendor:, evidence:, changes:, commands:, scope: :device)
           unless host.is_a?(String) && vendor.is_a?(Symbol) && evidence.is_a?(Hash) &&
                  changes.is_a?(Array) && changes.all? { |change| change.instance_of?(Change) } &&
-                 commands.is_a?(Array) && commands.all?(String)
+                 commands.is_a?(Array) && commands.all?(String) && %i[device interfaces].include?(scope)
             raise ArgumentError, "description plan contains invalid fields"
           end
 
           super(host: host.frozen? ? host : host.dup.freeze, vendor: vendor,
                 evidence: copy_evidence(evidence), changes: changes.dup.freeze,
-                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze)
+                commands: commands.map { |command| command.frozen? ? command : command.dup.freeze }.freeze, scope: scope)
         end
 
         def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))

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

@@ -3,6 +3,7 @@
 require_relative "topology/strategy"
 require_relative "topology/stages"
 require_relative "topology/plan"
+require_relative "topology/audit"
 
 module Net
   module Connector
@@ -26,6 +27,11 @@ module Net
           Topology.new(self).plan_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
         end
 
+        # 核实各接口，保留缺失/冲突证据并为可确认的接口构造独立计划。
+        def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+          Topology.new(self).audit_interface_descriptions(abbreviate: abbreviate, lowercase: lowercase, &formatter)
+        end
+
         # 明确确认且现场证据未变化时执行接口描述计划。
         def apply_interface_descriptions(plan, confirmed: false)
           Topology.new(self).apply_interface_descriptions(plan, confirmed: confirmed)
@@ -151,6 +157,17 @@ module Net
         end
       end
 
+      def audit_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
+        unless [abbreviate, lowercase].all? { |value| value == true || value == false }
+          raise ArgumentError, "description formatting options must be boolean"
+        end
+        formatter ||= ->(peer) { InterfaceDescription.format(peer, abbreviate: abbreviate, lowercase: lowercase) }
+        @device.with_operation(:plan) do
+          AuditBuilder.new(host: @device.host, vendor: @device.vendor, strategy: @strategy,
+                           neighbors: neighbors, descriptions: interface_descriptions, formatter: formatter).call
+        end
+      end
+
       # 比对邻居和现有描述，生成包含确切命令的只读变更计划。
       def plan_interface_descriptions(abbreviate: true, lowercase: false, &formatter)
         validate_change_support!(:plan) if @strategy.supports?(:neighbors)
@@ -246,7 +263,12 @@ module Net
       # 重验失败仍在写入前直接抛异常，保持 stale_plan 的既有契约。
       def revalidate_plan!(plan)
         discovered = neighbors
-        evidence = evidence_for(discovered, interface_descriptions)
+        current = interface_descriptions
+        if plan.scope == :interfaces
+          discovered = discovered.select { |neighbor| plan.evidence.key?(@strategy.interface_key(neighbor.local_interface)) }
+          current = current.slice(*plan.evidence.keys)
+        end
+        evidence = evidence_for(discovered, current)
         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

data/lib/net/connector/engine/error/metadata.rb

@@ -8,7 +8,7 @@ module Net
       # 日志与报告共用固定诊断词表；未知元数据可能来自配置正文，不能作为自由文本输出。
       module Metadata
         CONNECTOR_TYPES = %w[Error ConnectionError AuthenticationError LoginTimeout CommandTimeout WriteTimeout
-                             PromptError ConnectionClosed TransportError DeviceError ScriptError InternalError
+                             PromptError ConnectionClosed TransportError DeviceError ConfigurationError ScriptError InternalError
                              OutputLimitExceeded ScriptOutputLimitExceeded SessionBusy UnsupportedOperation LogError ParsingError BackupBusy
                              BackupPersistenceError BackupFinalizeError TftpCompletionError].freeze
         TYPES = (CONNECTOR_TYPES.map { |name| "Net::Connector::#{name}" } +
@@ -24,7 +24,7 @@ module Net
              Net::Connector::Netdisco::Tftp::Archive::Unavailable Net::Connector::Netdisco::Tftp::Archive::Failure]).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 known_hosts_busy rsa_too_small unsupported_cipher
+             connection_timeout host_key_changed host_key_untrusted known_hosts_busy known_hosts_unsafe 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
@@ -46,6 +46,14 @@ module Net
 
         def known_type?(name) = name.instance_of?(String) && TYPES.include?(name)
 
+        # 显示名白名单不授予复制私有字段的权限；外部子类可以重写 Class.name。
+        def trusted_error_class?(type)
+          name = type.name
+          known_type?(name) && Object.const_get(name).equal?(type)
+        rescue NameError
+          false
+        end
+
         def type(name)
           return if name.nil?
 

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

@@ -16,7 +16,7 @@ module Net
         @host = host
         @phase = phase
         @command = command
-        @output = output.freeze
+        @output = output.dup.freeze
         @source = source
         @line = line
         @underlying = underlying
@@ -27,7 +27,7 @@ module Net
       def with_diagnostics(message:, **context)
         context = { code: code, host: host, phase: phase, command: command, output: output,
                     source: source, line: line, underlying: underlying }.merge(context)
-        return self.class.new(message, **context) unless Error::Metadata.known_type?(self.class.name)
+        return self.class.new(message, **context) unless Error::Metadata.trusted_error_class?(self.class)
 
         copy = self.class.allocate
         instance_variables.each { |name| copy.instance_variable_set(name, instance_variable_get(name)) }
@@ -57,6 +57,8 @@ module Net
 
     class DeviceError < Error; end
 
+    class ConfigurationError < Error; end
+
     class ScriptError < Error; end
 
     class InternalError < Error; end

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

@@ -31,28 +31,28 @@ module Net
       end
 
       def commit
-        additions = File.binread(path).lines("\n") - @original.lines("\n")
-        return if additions.empty?
-
-        with_lock do
-          current = read_shared
-          Tempfile.create([".nc-known-hosts-merge-", ""], File.dirname(@destination)) do |file|
-            file.write(current)
-            file.flush
-            reject_changed_key!(file.path) unless @replace
-            remove_host(file.path) if @replace
-            contents = File.binread(file.path)
-            entries = contents.lines("\n")
-            additions.each { |line| entries << line unless entries.include?(line) }
-            File.open(file.path, "wb", 0o600) do |replacement|
-              replacement.write(entries.map { |line| line.end_with?("\n") ? line : line + "\n" }.join(""))
-              replacement.flush
-              replacement.fsync
+        # 纯会话引擎加载不触及文件业务；实际登记信任时才加载持久化协议。
+        require_relative "../storage/atomic_file"
+        begin
+          additions = File.binread(path).lines("\n") - @original.lines("\n")
+          return if additions.empty?
+
+          with_lock do
+            current = read_shared
+            Tempfile.create([".nc-known-hosts-merge-", ""], File.dirname(@destination)) do |file|
+              file.write(current)
+              file.flush
+              reject_changed_key!(file.path) unless @replace
+              remove_host(file.path) if @replace
+              contents = merge_entries(File.binread(file.path), additions)
+              Storage::AtomicFile.write(@destination, contents)
+            ensure
+              File.unlink(file.path + ".old") if file && File.exist?(file.path + ".old")
             end
-            File.rename(file.path, @destination)
-          ensure
-            File.unlink(file.path + ".old") if file && File.exist?(file.path + ".old")
           end
+        rescue Storage::AtomicFile::WriteError => error
+          # 已替换但目录未同步时报告完成边界，不能把新信任误当作尚未写入。
+          raise ConnectionError.new(error.message, code: error.code, host: @host, phase: :login), cause: nil
         end
       end
 
@@ -71,6 +71,19 @@ module Net
 
       private
 
+      # 保留已有条目和顺序；新增条目只登记一次，避免每条新增密钥扫描整份清单。
+      def merge_entries(contents, additions)
+        entries = contents.lines("\n")
+        present = entries.each_with_object({}) { |line, index| index[line.freeze] = true }
+        additions.each do |line|
+          next if present.key?(line)
+
+          entries << line
+          present[line.freeze] = true
+        end
+        entries.map { |line| line.end_with?("\n") ? line : line + "\n" }.join("")
+      end
+
       # 临时文件返回后先登记所有权，阻塞构造期间仍允许取消。
       def create_snapshot
         failure = nil
@@ -110,12 +123,18 @@ module Net
 
       def read_shared
         File.open(@destination, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
-          raise IOError, "known_hosts must be a regular file" unless file.stat.file?
+          raise unsafe_file_error, cause: nil unless file.stat.file?
 
           file.read
         end
       rescue Errno::ENOENT
         ""
+      rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+        raise unsafe_file_error, cause: nil
+      end
+
+      def unsafe_file_error
+        ConnectionError.new("known_hosts must be a managed regular file", code: :known_hosts_unsafe, host: @host, phase: :login)
       end
 
       def reject_changed_key!(current_path)

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Net
+  module Connector
+    module Netdisco
+      # 精确地址用索引，网段和范围只保存端点；绝不展开地址或发起扫描。
+      class AddressFilter
+        def initialize(values)
+          raise ArgumentError, "host lists must be Arrays" unless values.is_a?(Array)
+
+          exact = {}
+          ranges = {}
+          values.each do |value|
+            raise ArgumentError, "host entries must be nonempty strings" unless value.is_a?(String) && !value.empty?
+
+            if value.include?("/") || value.split("%", 2).first.include?("-")
+              first, last = endpoints(value)
+              (ranges[first.family] ||= []) << [first.to_i, last.to_i]
+            else
+              exact[IPAddr.new(value).to_s.freeze] = true
+            end
+          end
+          @exact = exact.freeze
+          @ranges = ranges.transform_values { |items| merge_ranges(items) }.freeze
+          freeze
+        rescue IPAddr::Error
+          raise ArgumentError, "host entries must be IP addresses, networks or ordered ranges", cause: nil
+        end
+
+        def empty? = @exact.empty? && @ranges.empty?
+
+        def include?(host)
+          return false if empty?
+          return true if @exact.key?(host)
+          return false unless host.is_a?(String) && !host.empty?
+
+          address = IPAddr.new(host)
+          return true if @exact.key?(address.to_s)
+
+          intervals = @ranges[address.family]
+          return false unless intervals
+
+          value = address.to_i
+          interval = intervals.bsearch { |_, last| last >= value }
+          interval && interval.first <= value ? true : false
+        rescue IPAddr::Error
+          false
+        end
+
+        private
+
+        def endpoints(value)
+          if value.include?("/")
+            range = IPAddr.new(value).to_range
+            return [range.begin, range.end]
+          end
+          first, last = value.split("-", 2)
+          first = IPAddr.new(first)
+          if first.ipv4? && last&.match?(/\A\d+\z/)
+            last = first.to_s.rpartition(".").first + ".#{last}"
+          end
+          last = IPAddr.new(last)
+          unless first.family == last.family && first.to_i <= last.to_i && !(first.ipv6? && (first.zone_id || last.zone_id))
+            raise ArgumentError, "host ranges require ordered endpoints of the same address family", cause: nil
+          end
+          [first, last]
+        end
+
+        # 合并重叠范围，使每台设备匹配的成本不随网段大小增长。
+        def merge_ranges(items)
+          merged = []
+          items.sort.each do |first, last|
+            if !merged.empty? && first <= merged.last.last + 1
+              merged.last[1] = [merged.last.last, last].max
+            else
+              merged << [first, last]
+            end
+          end
+          merged.each(&:freeze).freeze
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/cli/backup.rb

@@ -5,6 +5,7 @@ require "socket"
 require_relative "options"
 require_relative "credentials"
 require_relative "../fleet"
+require_relative "../config/initializer"
 require_relative "../progress"
 require_relative "../report/files"
 require_relative "../../storage/batch_directory"
@@ -16,42 +17,41 @@ module Net
         # 终端备份入口：固定配置、预览、执行、保存报告，最后决定输出与退出码。
         class Backup
           # 保存批次模式与调用方 IO，构造阶段不读取清单、不创建目录。
-          def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr)
+          def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr,
+                         default_config: nil, default_directory: nil, load_env: false)
             raise ArgumentError, "mode must be backup or tftp" unless %i[backup tftp].include?(mode)
 
             @mode, @argv, @env, @input, @output, @error = mode, argv, env, input, output, error
+            @default_config, @default_directory = default_config, default_directory
+            @load_env = load_env
           end
 
           # 先固定并校验策略，再预览、执行和保存报告；成功判定使用最终报告。
           def run
-            options = CLI::Options.parse(argv: @argv, input: @input, output: @output, error: @error)
+            options = CLI::Options.parse(argv: @argv, input: @input, output: @output, error: @error, mode: @mode)
             return 0 if options[:help]
+            apply_defaults(options)
+            return 0 if initialize_config?(options)
 
             settings, success_policy, server_root, batch_directory = prepare(options)
             inventory, credentials = Credentials.resolve(settings, stdin_credentials: options[:stdin_credentials], input: @input)
             progress = Progress.new(io: @error, enabled: !options[:no_progress], verbose: options[:verbose])
             resolver = ->(device) { credentials.call(device)&.merge(on_event: progress.method(:event)) }
             fleet = Fleet.new(inventory: inventory, settings: settings, credentials: resolver, report_store: nil)
-            progress.reading_inventory
-            limit = settings.limit_per_vendor
-            refresh = options[:force_refresh] ? { force_refresh: true } : {}
-            plan = if @mode == :backup
-                     fleet.plan_backup(limit_per_vendor: limit, **refresh)
-                   else
-                     fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?, **refresh)
-                   end
-            inventory_warning(fleet)
-            progress.plan(plan, concurrency: settings.concurrency, limit_per_vendor: limit)
-            preview = plan_summary(plan)
-            @output.puts JSON.generate(plan: preview) if options[:json]
-            @output.flush
+            plan = read_plan(fleet, settings, options, progress, server_root)
+            return preview_status(plan, options) if options[:plan] || options[:inventory_only]
             return 1 if options[:stdin_credentials] && @input.gets("\n")&.strip != "RUN"
 
-            Storage::AtomicFile.write(File.join(batch_directory, "plan.json"), JSON.pretty_generate(preview))
+            Storage::AtomicFile.write(File.join(batch_directory, "plan.json"), JSON.pretty_generate(plan_summary(plan)))
             report = execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
             report = record_progress_error(report, progress)
             report = Report::Files.write(report, directory: batch_directory, plan: plan, concurrency: settings.concurrency)
             finish(report, progress, options, batch_directory, plan, settings.concurrency)
+          rescue Interrupt
+            130
+          rescue EOFError
+            @error.puts "配置输入未完成，未创建文件。"
+            2
           rescue ArgumentError, Inventory::Error => exception
             @error.puts "备份参数或清单错误：#{exception.message}"
             2
@@ -62,6 +62,53 @@ module Net
 
           private
 
+          def read_plan(fleet, settings, options, progress, server_root)
+            progress.reading_inventory
+            limit = settings.limit_per_vendor
+            refresh = options[:force_refresh] ? { force_refresh: true } : {}
+            plan = if @mode == :backup || options[:inventory_only]
+                     fleet.plan_backup(limit_per_vendor: limit, **refresh)
+                   else
+                     fleet.plan_tftp_backup(limit_per_vendor: limit,
+                                            allow_fixed_name_reuse: !server_root.nil? || !settings.tftp_verification_roots.empty?, **refresh)
+                   end
+            inventory_warning(fleet)
+            progress.plan(plan, concurrency: settings.concurrency, limit_per_vendor: limit)
+            preview = plan_summary(plan)
+            @output.puts JSON.generate(plan: preview) if options[:json]
+            @output.flush
+            plan
+          end
+
+          def preview_status(plan, options)
+            @output.puts(plan.selected.map { |device| "#{device.host}\t#{device.name}\t#{device.vendor}" }) unless options[:json]
+            plan.selected.empty? || plan.outcomes.compact.any? { |item| !%i[filtered sample_limit].include?(item.status) } ? 1 : 0
+          end
+
+          def apply_defaults(options)
+            values = options.fetch(:environment)
+            values["NC_CONFIG"] = @default_config if @default_config && !values.key?("NC_CONFIG") && !@env.key?("NC_CONFIG")
+            return unless @default_directory && !values.key?("NC_BACKUP_DIRECTORY")
+
+            path = values["NC_CONFIG"] || @env["NC_CONFIG"]
+            document = path && File.file?(path) ? Config.load(path) : {}
+            values["NC_BACKUP_DIRECTORY"] = @default_directory unless document.key?("NC_BACKUP_DIRECTORY")
+          end
+
+          def initialize_config?(options)
+            path = options.fetch(:environment)["NC_CONFIG"] || @env["NC_CONFIG"]
+            return false unless path && !File.exist?(path) && !File.symlink?(path)
+
+            document = { "backup" => { "directory" => @default_directory || "./backups", "concurrency" => 4 },
+                         "netdisco" => { "source" => "http", "cache_mode" => "prefer" },
+                         "inventory" => { "include_hosts" => [], "exclude_hosts" => [], "include_names" => [],
+                                          "exclude_names" => [], "include_vendors" => [], "exclude_vendors" => [], "name_match" => "contains" },
+                         "ssh" => { "protocol" => "ssh", "host_key_policy" => "accept_new" } }
+            Config::Initializer.new(input: @input, output: @error).create(path: path, document: document, interactive: options[:interactive])
+            @error.puts "已初始化配置：#{path}；检查配置后再次运行。"
+            true
+          end
+
           # 清单离线回退和本地保存故障单独提示，不覆盖设备操作结果。
           def inventory_warning(fleet)
             if fleet.inventory_status && fleet.inventory_status[:source] == :stale_cache
@@ -74,15 +121,18 @@ module Net
 
           # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
           def prepare(options)
-            settings = CLI::Options.settings(options, env: @env).for_run(mode: @mode)
+            settings = CLI::Options.settings(options, env: @env, load_env: @load_env).for_run(mode: @mode)
             success_policy = options.fetch(:success_policy, :selected)
             raise ArgumentError, "verified policy requires TFTP mode" if success_policy == :verified && @mode != :tftp
             raise ArgumentError, "--tftp-root requires TFTP mode" if options[:tftp_root] && @mode != :tftp
-            server_root = tftp_root(settings, options) if @mode == :tftp
-            raise ArgumentError, "verified policy requires a local TFTP directory" if success_policy == :verified && !server_root
+            server_root = tftp_root(settings, options) if @mode == :tftp && !options[:inventory_only]
+            if success_policy == :verified && !server_root && settings.tftp_verification_roots.empty?
+              raise ArgumentError, "verified policy requires a local TFTP directory"
+            end
             Tftp::Verifier.new(root: server_root) if server_root
-            batch_directory = Storage::BatchDirectory.create(settings.backup_directory)
-            if @mode == :tftp && !settings.log_directory
+            settings = settings.with_overrides("NC_TFTP_ROOT" => server_root) if server_root
+            batch_directory = Storage::BatchDirectory.create(settings.backup_directory) unless options[:plan] || options[:inventory_only]
+            if batch_directory && @mode == :tftp && !settings.log_directory
               settings = settings.with_overrides("NC_LOG_DIRECTORY" => File.join(batch_directory, "logs"))
             end
             [settings, success_policy, server_root, batch_directory]
@@ -148,9 +198,12 @@ module Net
 
           # 优先使用显式核验根目录；仅服务器是本机地址时探测本机惯用 TFTP 目录。
           def tftp_root(settings, options)
-            server = settings.tftp_server || (raise ArgumentError, "YAML tftp.server is required")
+            server = settings.tftp_server
+            if !server && settings.tftp_servers.empty?
+              raise ArgumentError, "YAML tftp.server or tftp.servers is required"
+            end
             return options[:tftp_root] || settings.tftp_root if options[:tftp_root] || settings.tftp_root
-            return unless Socket.ip_address_list.any? { |address| address.ip_address == server }
+            return unless server && Socket.ip_address_list.any? { |address| address.ip_address == server }
 
             candidate = File.join(Dir.home, "Documents", "TFTP")
             candidate if File.directory?(candidate)
@@ -162,8 +215,10 @@ module Net
               vendors: plan.inventory.group_by { |device| device.vendor || :unmapped }.transform_values(&:size),
               issues: plan.inventory.reject(&:ready?).group_by(&:issue).transform_values(&:size),
               selected: plan.selected.map do |device|
-                filename = @mode == :backup ? device.backup_filename(style: :hostname_ip) : device.tftp_filename
-                { host: device.host, name: device.name, vendor: device.vendor, backup_filename: filename }
+                filename = plan.mode == :backup ? device.backup_filename(style: :hostname_ip) : device.tftp_filename
+                entry = { host: device.host, name: device.name, vendor: device.vendor, backup_filename: filename }
+                entry[:transfer] = plan.transfers.fetch(device.host).to_h if plan.mode == :tftp && plan.transfers.key?(device.host)
+                entry
               end }
           end
         end

data/lib/net/connector/netdisco/cli/help.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Netdisco
+      class CLI
+        # 简要帮助从实际解析器筛选；范例按执行模式生成完整命令。
+        module Help
+          COMMON = %w[config directory interactive non-interactive host hosts name exclude-name vendor
+                      plan inventory-only concurrency refresh-inventory json quiet no-progress help help-all examples].freeze
+
+          def self.common(parser)
+            keep = true
+            parser.to_s.lines.select do |line|
+              flag = line[/--([a-z-]+)/, 1]
+              keep = COMMON.include?(flag) if flag
+              keep
+            end.join
+          end
+
+          def self.examples(program:, mode:)
+            command = "ruby #{File.basename(program)}"
+            cases = if mode == :topology
+                      [["预览过滤后的清单", "--inventory-only --name edge --cache-only"],
+                       ["发现邻居", "--discover --hosts 192.0.2.10-20"],
+                       ["生成只读计划", "--plan --host 192.0.2.10"],
+                       ["明确应用并读回保存", "--apply --host 192.0.2.10"]]
+                    elsif mode == :tftp
+                      [["预览待上传设备", "--plan --hosts 192.0.2.10-20"],
+                       ["单台上传，服务器沿用配置", "--host 192.0.2.10"],
+                       ["连续 IP 范围并发上传", "--hosts 192.0.2.10-20 --concurrency 8"],
+                       ["上传并核验服务器文件", "--host 192.0.2.10 --tftp-root /srv/tftp --success-policy verified"]]
+                    else
+                      [["沿用配置执行备份", ""], ["预览连续 IP 范围", "--plan --hosts 192.0.2.10-20"],
+                       ["单台设备配置备份", "--host 192.0.2.10"],
+                       ["按名称筛选并排除设备", "--name szx10 --exclude-name csw,asw,wlc --concurrency 8"],
+                       ["使用数据库清单预览", "--config examples/inventory.yml --plan"]]
+                    end
+            ["常用示例（IP 请替换为实际清单地址）：",
+             *cases.map { |label, arguments| "  #{label}：\n    #{command} #{arguments}" },
+             "包含条件取交集，排除优先；同类参数可逗号分隔或重复传参。"].join("\n")
+          end
+        end
+      end
+    end
+  end
+end