net-connector 0.13.0 → 0.14.0

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

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

@@ -3,7 +3,8 @@
 require "optparse"
 require_relative "../settings"
 require_relative "../planner"
-require_relative "../config_file"
+require_relative "../config"
+require_relative "help"
 
 module Net
   module Connector
@@ -12,9 +13,9 @@ module Net
         # 可注入参数与输入输出的备份选项，不退出宿主进程。
         class Options
           # 复制参数数组，返回选项或帮助标记；非法输入抛错，不退出宿主进程。
-          def self.parse(argv: ARGV, input: $stdin, output: $stdout, error: $stderr, program: $PROGRAM_NAME)
+          def self.parse(argv: ARGV, input: $stdin, output: $stdout, error: $stderr, program: $PROGRAM_NAME, mode: :backup, &additional)
             values = { environment: {}, json: false, verbose: false, stdin_credentials: false }
-            parser = parser_for(values, output: output, program: program)
+            parser = parser_for(values, output: output, program: program, mode: mode, &additional)
             remaining = parser.parse!(argv.dup)
             return values if values[:help]
             raise OptionParser::InvalidArgument unless remaining.empty?
@@ -30,29 +31,78 @@ module Net
             raise ArgumentError, "参数无效：并发数须为 1 至 50，抽样须为 1 至 5；使用 --help 查看参数", cause: nil
           end
 
-          def self.parser_for(values, output:, program:)
+          def self.parser_for(values, output:, program:, mode:, &additional)
+            raise ArgumentError, "unknown CLI mode" unless %i[backup tftp topology].include?(mode)
+
             OptionParser.new do |opts|
-              opts.banner = "用法：ruby #{File.basename(program)} [选项]（默认全量）"
+              default = mode == :topology ? "默认只读规划" : "默认沿用配置"
+              opts.banner = "用法：ruby #{File.basename(program)} [选项]（#{default}）\n命令行参数优先；未指定的项沿用配置及默认值。无筛选时选择全部就绪设备。"
               add_settings(opts, values)
-              add_execution(opts, values)
-              opts.on("--ask-password", "隐藏输入设备密码") { values[:ask_password] = true }
-              opts.on("--ask-netdisco-password", "隐藏输入 Netdisco 密码") { values[:ask_netdisco_password] = true }
-              opts.on("--no-progress", "关闭进度显示") { values[:no_progress] = true }
-              opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
-              opts.on("--json", "在 STDOUT 输出计划和结果 JSON") { values[:json] = true }
-              opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
-              opts.on("-h", "--help", "显示帮助") { output.puts opts; values[:help] = true }
+              add_execution(opts, values, mode: mode)
+              add_terminal_options(opts, values)
+              if mode == :topology
+                add_topology(opts, values)
+              else
+                opts.on("--plan", "--inventory-only", "预览过滤后的清单，不连接设备") { values[:inventory_only] = true }
+              end
+              additional&.call(opts, values)
+              opts.on("--examples", "查看常用命令范例，不执行任务") do
+                output.puts Help.examples(program: program, mode: mode)
+                values[:help] = true
+              end
+              opts.on("-h", "--help", "显示常用选项") do
+                output.puts(mode == :topology ? opts : Help.common(opts))
+                values[:help] = true
+              end
+              opts.on("--help-all", "显示完整选项（凭据、抽样、SSH、自动化等）") { output.puts opts; values[:help] = true }
             end
           end
 
+          def self.add_terminal_options(opts, values)
+            opts.on("--ask-password", "隐藏输入设备密码") { values[:ask_password] = true }
+            opts.on("--ask-netdisco-password", "隐藏输入 Netdisco 密码") { values[:ask_netdisco_password] = true }
+            opts.on("--quiet", "--no-progress", "关闭进度；可配合 --json") { values[:no_progress] = true }
+            opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
+            opts.on("--json", "在 stdout 输出 JSON；默认显示可读摘要") { values[:json] = true }
+            opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
+            opts.on("--interactive", "缺少配置时交互填写，已有配置保持原样") { values[:interactive] = true }
+            opts.on("--non-interactive", "缺少配置时使用默认值，不进行问答") { values[:interactive] = false }
+          end
+
+          def self.add_topology(opts, values)
+            { discover: "发现邻居并检查描述", plan: "生成配置计划", apply: "修正、读回并保存" }.each do |mode, description|
+              opts.on("--#{mode}", description) do
+                raise ArgumentError, "topology modes are mutually exclusive" if values[:topology_mode]
+
+                values[:topology_mode] = mode
+                values[:apply] = true if mode == :apply
+              end
+            end
+            opts.on("--inventory-only", "只读取并过滤清单，不连接设备") { values[:inventory_only] = true }
+            opts.on("--limit N", Integer, "最多选择 N 台可发现设备") do |value|
+              raise OptionParser::InvalidArgument unless value.positive?
+
+              values[:topology_limit] = value
+            end
+            opts.on("--description-format TEXT", "模板仅支持 %{neighbor}、%{port}") { |value| values[:environment]["NC_TOPOLOGY_DESCRIPTION_FORMAT"] = value }
+            opts.on("--full-port-names", "不缩写邻居端口") { values[:environment]["NC_TOPOLOGY_ABBREVIATE"] = "false" }
+            opts.on("--lowercase-ports", "邻居端口转换成小写") { values[:environment]["NC_TOPOLOGY_LOWERCASE"] = "true" }
+          end
+
           # 正式 CLI 与批次示例共用并发、抽样、核验和成功策略选项。
-          def self.add_execution(opts, values)
+          def self.add_execution(opts, values, mode: nil)
             opts.on("--refresh-inventory", "强制刷新清单；远端失败时回退已验证历史") { values[:force_refresh] = true }
+            opts.on("--cache-only", "仅使用已验证的清单缓存，不查询远端") { values[:environment]["ND_CACHE_MODE"] = "only" }
+            opts.on("--cache-mode MODE", %w[prefer only refresh], "清单缓存 prefer / only / refresh") do |value|
+              values[:environment]["ND_CACHE_MODE"] = value
+            end
             opts.on("-c", "--concurrency N", Integer, "并发设备数，1 至 50") do |count|
               raise OptionParser::InvalidArgument unless (1..Settings::MAX_CONCURRENCY).cover?(count)
 
               values[:environment]["NC_CONCURRENCY"] = count.to_s
             end
+            return if mode == :topology
+
             opts.on("--sample N", "--limit-per-vendor N", Integer, "每厂商抽样 1 至 5 台") do |count|
               Planner.validate_limit!(count)
               values[:limit] = count
@@ -65,18 +115,26 @@ module Net
           end
 
           # 公开 CLI 参数进入 overrides，凭据留在 environment；内部键不会重新开放已移除环境设置。
-          def self.settings(options, env: ENV)
+          def self.settings(options, env: ENV, load_env: false)
             raise ArgumentError, "--all 不能与抽样同时使用" if options[:all] && options[:limit]
+            if options[:host] && options.fetch(:environment).key?("NC_INCLUDE_HOSTS")
+              raise ArgumentError, "--host cannot be combined with --hosts"
+            end
 
             environment = environment(options, env: env)
             path = environment["NC_CONFIG"]
-            defaults = path && !path.empty? ? ConfigFile.load(path) : {}
-            keys = ConfigFile::FIELDS.values.flat_map { |fields| fields.values.map(&:first) }
+            defaults = path && !path.empty? ? Config.load(path) : {}
+            keys = Config::FIELDS.values.flat_map { |fields| fields.values.map(&:first) }
+            if load_env
+              # 显式启用时，公开环境值只填补 YAML；CLI 覆盖与凭据来源仍分开处理。
+              defaults = env.to_h.slice(*keys).merge(defaults)
+              environment = environment.reject { |key, _| keys.include?(key) }
+            end
             overrides = options.fetch(:environment).slice(*keys)
             environment = environment.reject { |key, _| overrides.key?(key) && !Settings::ENVIRONMENT_KEYS.include?(key) }
             { source: "ND_SOURCE", query: "ND_QUERY", query_params: "ND_QUERY_PARAMS",
               max_script_output_bytes: "NC_MAX_SCRIPT_OUTPUT_BYTES", host: "NC_INCLUDE_HOSTS",
-              limit: "NC_SAMPLE_PER_VENDOR" }.each do |option, key|
+              limit: "NC_SAMPLE_PER_VENDOR", tftp_root: "NC_TFTP_ROOT" }.each do |option, key|
               overrides[key] = options[option].to_s if options.key?(option)
             end
             overrides["NC_SAMPLE_PER_VENDOR"] = nil if options[:all]
@@ -85,6 +143,7 @@ module Net
 
           # 共用配置与凭据参数登记；具体入口决定后续预览、执行或导出。
           def self.add_settings(opts, values)
+            add_filters(opts, values)
             {
               "--username USER" => ["NC_DEVICE_USERNAME", "设备登录用户名"],
               "--password PASSWORD" => ["NC_DEVICE_PASSWORD", "设备登录密码（可改用 --ask-password）"],
@@ -109,6 +168,40 @@ module Net
             end
           end
 
+          # 同类 CLI 筛选替换 YAML；重复参数在本次调用内合并，绝不把范围展开为地址列表。
+          def self.add_filters(opts, values)
+            {
+              "--hosts PATTERNS" => ["NC_INCLUDE_HOSTS", "包含地址、网段或范围，逗号分隔"],
+              "--exclude-hosts PATTERNS" => ["NC_EXCLUDE_HOSTS", "排除地址、网段或范围"],
+              "--name PATTERNS" => ["NC_INCLUDE_NAMES", "包含设备名称，可重复或逗号分隔"],
+              "--exclude-name PATTERNS" => ["NC_EXCLUDE_NAMES", "排除设备名称，可重复或逗号分隔"],
+              "--vendor NAMES" => ["NC_INCLUDE_VENDORS", "包含连接器厂商名"],
+              "--exclude-vendor NAMES" => ["NC_EXCLUDE_VENDORS", "排除连接器厂商名"]
+            }.each do |flag, (key, description)|
+              opts.on(flag, description) do |value|
+                items = value.split(",", -1).map(&:strip)
+                raise OptionParser::InvalidArgument if items.empty? || items.any?(&:empty?)
+
+                previous = values[:environment][key]&.split(",") || []
+                values[:environment][key] = (previous + items).uniq.join(",")
+              end
+            end
+            opts.on("--name-match MODE", %w[contains prefix glob], "名称匹配方式：contains / prefix / glob") do |value|
+              values[:environment]["NC_NAME_MATCH"] = value
+            end
+            opts.on("--host IP", "选择单台设备，可重复") do |value|
+              raise OptionParser::InvalidArgument if value.empty? || value.match?(/[\/,]/)
+
+              begin
+                address = IPAddr.new(value).to_s
+              rescue IPAddr::Error
+                raise OptionParser::InvalidArgument
+              end
+              values[:host] = [*values[:host]&.split(","), address].uniq.join(",")
+            end
+          end
+          private_class_method :add_filters
+
           # 复制原环境并合并显式凭据，清除被通用凭据覆盖的厂商值及旧 API key。
           def self.environment(options, env: ENV)
             result = env.to_h.dup