net-connector 0.16.1 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8afbc2a37dcb0b9b96be6fd1af171201cb5315803452632f4af2be0db4d5a297
-  data.tar.gz: f11815c48829959e83e89b2bfd37956c4ee9c8eded44c92c200445292fe458c0
+  metadata.gz: 33503c92ccbe8f7000652c0b47b967a8f2f40e6c9edd7081ba305c3246efe820
+  data.tar.gz: f2d4c434caab1b888d1b4cd9bf25a0def4e7e26eb63b2e6e5e93d8b56cc34c0d
 SHA512:
-  metadata.gz: 4de68d2427f07acaca0820aac064faeabad7d73a4be81e3286566affb3300a84511955a1f5b721751a488b38651cafe0226a2daecd1bed54d8521f7967b0bd48
-  data.tar.gz: c5d55197568da8f3a7945dd44697ad79d840ca7416408c57b9d605f1e2afb772d0a634eff72102e364e81fee6fdbb526a020300fa8085ac2018b58866cf96b96
+  metadata.gz: e8c126666632d1f4a708cbcc42c1df5ad434d37978a55fe2db363e3628f2c7e2779192d05ad7d8989933d389d92a6de520669a93a47c46209816a85d423abcca
+  data.tar.gz: ad704438b1ed05942371fe3f57a7ebf66f563261406682013b18f57c8cfbc8b01a190a41a685a2991f4d53ff3e2912d2cf8c8e272b593bc83e1a439c821ef349

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 更新记录
 
+## 0.17.1 - 2026-10-22
+
+- Delegate shared configuration, private initialization, option groups and terminal interaction to ctx_cli 0.1.0.
+
+## 0.17.0 - 2026-10-22
+
+- Centralize inventory selection and CLI filters in Net::Connector::Inventory; add vendor/model inclusion, exclusion and matching modes.
+
 ## 未发布
 
 ## 0.16.1 - 2026-10-21

data/README.md

@@ -62,3 +62,7 @@ script/ci
 The gate scans secrets, lints Ruby and workflows, runs tests and local PTY benchmarks, and verifies isolated gem installs. See [CONTRIBUTING](CONTRIBUTING.md), [security reporting](SECURITY.md), and the [changelog](CHANGELOG.md). Issues and pull requests may be written in English or Chinese.
 
 Licensed under [MIT](LICENSE).
+
+## ctx_cli 公共入口
+
+宿主配置文件读取、私有文件初始化、公共参数与终端交互由 ctx_cli 维护。原 `Net::Connector::Config`、配置路径、优先级和 backup/TFTP/topology 策略继续保留。源码联调使用 `CTX_CLI_PATH=../ctx_cli`；隔离安装可通过 `CTX_CLI_GEM=/absolute/path/ctx_cli-0.1.0.gem` 传入精确候选。

data/lib/net/connector/config.rb

@@ -1,366 +1,29 @@
 # frozen_string_literal: true
 
-require "yaml"
+require "ctx_cli/configuration"
 
 module Net
   module Connector
-    # Host-side configuration discovery. Requiring this file never loads device I/O.
-    class Config
+    # 保留原配置入口和路径政策；通用发现、来源与快照由 ctx_cli 维护。
+    class Config < CtxCli::Configuration
       NAMES = %w[vxlan wireless backup topology].freeze
       COMMON_KEYS = %w[netdisco inventory ssh].freeze
       CONFIG_ENV = { "vxlan" => "VXLAN_CONFIG", "wireless" => "WIRELESS_CONFIG",
                      "backup" => "NC_CONFIG", "topology" => "NC_CONFIG" }.freeze
 
-      attr_reader :data, :specific, :process_environment, :file_environment, :environment,
-                  :config_files, :environment_files, :sources
-
-      def initialize(name:, env: ENV, script: $PROGRAM_NAME, cwd: Dir.pwd, home: Dir.home,
-                     directories: nil, config: nil, env_file: nil, config_env: nil,
-                     path_fields: [], env_path_keys: [], path_literals: {})
-        @name = name.to_s
-        raise ArgumentError, "unsupported configuration name: #{@name}" unless NAMES.include?(@name)
-
-        @cwd = File.expand_path(cwd)
-        @home = File.expand_path(home)
-        @config_env = config_env || CONFIG_ENV.fetch(@name)
-        @env_path_keys = (env_path_keys.map(&:to_s) + [@config_env]).uniq
-        @path_literals = self.class.freeze_tree(self.class.copy(path_literals.transform_keys(&:to_s)))
-        @process_environment = self.class.copy(env.to_h)
-        resolve_environment_paths!(@process_environment, @cwd)
-        self.class.freeze_tree(@process_environment)
-        @user_directory = File.join(user_config_home, "net-connector")
-        @directories = (directories || ["/etc/net-connector", "/usr/local/etc/net-connector", @user_directory,
-                                        File.dirname(File.expand_path(script, @cwd)), @cwd]).map do |path|
-          File.expand_path(path, @cwd)
-        end.uniq
-        @explicit_config = absolute(config, @cwd)
-        @explicit_env_file = absolute(env_file, @cwd)
-        @path_fields = path_fields.map { |path| path.to_s.split(".") }
-        @data = @specific = @file_environment = @environment = {}.freeze
-        @config_files = @environment_files = [].freeze
-        @sources = { "configuration_files" => @config_files, "environment_files" => @environment_files, "fields" => {}.freeze }.freeze
-      end
-
-      # Read environment files without mutating ENV or evaluating any YAML.
-      def load_environment(allow_missing: false)
-        return self if @environment_loaded
-
-        files = candidates(".env", @explicit_env_file)
-        values = {}
-        loaded = []
-        files.each do |path|
-          next unless readable_file?(path, explicit: path == @explicit_env_file, allow_missing: allow_missing)
-
-          parsed = parse_environment(path, values.merge(@process_environment))
-          resolve_environment_paths!(parsed, File.dirname(path))
-          values.merge!(parsed)
-          loaded << path
-        end
-        @file_environment = self.class.freeze_tree(values)
-        @environment = self.class.freeze_tree(values.merge(self.class.copy(@process_environment)))
-        @environment_files = self.class.freeze_tree(loaded)
-        # Empty selectors are absent, including an empty original process variable.
-        selector = present(@process_environment[@config_env]) || present(values[@config_env])
-        @selected_config = @explicit_config || absolute(selector, @cwd)
-        @environment_loaded = true
-        update_sources({})
-        self
-      end
-
-      # Freeze one batch snapshot; repeated calls do not re-read files.
-      def load(allow_missing: false)
-        return self if @loaded
-
-        load_environment(allow_missing: allow_missing)
-        merged = {}
-        specific = {}
-        fields = {}
-        loaded = []
-        @applicable = false
-        paths = @directories.flat_map { |directory| [File.join(directory, "net-connector.yml"), File.join(directory, "#{@name}.yml")] }
-        paths = final_candidates(paths, @selected_config)
-        paths.each do |path|
-          next unless readable_file?(path, explicit: path == @selected_config, allow_missing: allow_missing)
-
-          document = read_yaml(path)
-          if File.basename(path) == "net-connector.yml"
-            common, native, applicable = shared_sections(document, path)
-            merged = merge_layer(merged, common, path, fields)
-            @applicable ||= applicable
-          else
-            native = document
-            validate_string_keys!(native, path)
-            @applicable = true
-          end
-          merged = merge_layer(merged, native, path, fields)
-          specific = self.class.merge(specific, resolve_paths(native, path))
-          loaded << path
-        end
-        @data = self.class.freeze_tree(merged)
-        @specific = self.class.freeze_tree(specific)
-        @config_files = self.class.freeze_tree(loaded)
-        update_sources(fields)
-        @loaded = true
-        self
-      end
-
-      def config
-        @selected_config || @explicit_config || @config_files.last || init_config
-      end
-
-      def env_file
-        @explicit_env_file || @environment_files.last || init_env_file
-      end
-
-      def init_config
-        @selected_config || @explicit_config || File.join(@user_directory, "#{@name}.yml")
-      end
-
-      def init_env_file
-        @explicit_env_file || File.join(@user_directory, ".env")
-      end
-
-      def missing?
-        !@applicable
-      end
-
-      # Serialize native values using the same target-file schema as discovery.
-      def self.dump(document, name:, path:)
+      def initialize(name:, config_env: nil, **options)
         name = name.to_s
         raise ArgumentError, "unsupported configuration name: #{name}" unless NAMES.include?(name)
 
-        YAML.dump(File.basename(path) == "net-connector.yml" ? { name => document } : document)
-      end
-
-      # Recursive, non-destructive replacement: arrays, false and nil are values.
-      def self.merge(*hashes)
-        hashes.reduce({}) do |result, hash|
-          hash.each do |key, value|
-            result[copy(key)] = result[key].is_a?(Hash) && value.is_a?(Hash) ? merge(result[key], value) : copy(value)
-          end
-          result
-        end
-      end
-
-      def self.copy(value)
-        case value
-        when Hash then value.to_h { |key, entry| [copy(key), copy(entry)] }
-        when Array then value.map { |entry| copy(entry) }
-        when String then value.dup
-        else value
-        end
-      end
-
-      def self.freeze_tree(value)
-        case value
-        when Hash then value.each { |key, entry| freeze_tree(key); freeze_tree(entry) }
-        when Array then value.each { |entry| freeze_tree(entry) }
-        end
-        value.freeze
-      end
-
-      private
-
-      def present(value)
-        value unless value.nil? || value.to_s.strip.empty?
-      end
-
-      def absolute(path, directory)
-        File.expand_path(path.to_s, directory) if present(path)
-      end
-
-      def user_config_home
-        absolute(present(@process_environment["XDG_CONFIG_HOME"]), @cwd) || File.join(@home, ".config")
-      end
-
-      def candidates(filename, explicit)
-        final_candidates(@directories.map { |directory| File.join(directory, filename) }, explicit)
-      end
-
-      def final_candidates(paths, explicit)
-        paths = paths.reject { |path| path == explicit } + [explicit] if explicit
-        paths.uniq
-      end
-
-      def readable_file?(path, explicit:, allow_missing:)
-        unless File.exist?(path)
-          raise ArgumentError, "configuration file does not exist: #{path}" if explicit && !allow_missing
-
-          return false
-        end
-        return true if File.file?(path) && File.readable?(path)
-
-        raise ArgumentError, "configuration path is not a readable regular file: #{path}"
-      end
-
-      def read_yaml(path)
-        contents = File.read(path)
-        validate_yaml_structure!(contents, path)
-        document = YAML.safe_load(contents, permitted_classes: [], permitted_symbols: [], aliases: false)
-        document = {} if document.nil?
-        raise ArgumentError, "configuration must contain a mapping: #{path}" unless document.is_a?(Hash)
-
-        document
-      rescue Psych::Exception, SystemCallError, IOError => error
-        raise ArgumentError, "cannot read configuration file: #{path} (#{error.class})", cause: nil
-      end
-
-      # Overrides are explicit file layers; one file cannot hide duplicate keys
-      # or silently discard later documents before the tool validates its scope.
-      def validate_yaml_structure!(contents, path)
-        stream = YAML.parse_stream(contents)
-        raise ArgumentError, "configuration must contain a single YAML document: #{path}" if stream.children.size > 1
-
-        stream.each do |node|
-          next unless node.is_a?(Psych::Nodes::Mapping)
-
-          keys = {}
-          node.children.each_slice(2) do |key, _|
-            next unless key.is_a?(Psych::Nodes::Scalar)
-            if keys.key?(key.value)
-              raise ArgumentError, "duplicate configuration key at line #{key.start_line + 1}: #{path}"
-            end
-
-            keys[key.value] = true
-          end
-        end
-      end
-
-      def validate_string_keys!(value, path)
-        case value
-        when Hash
-          raise ArgumentError, "configuration keys must be strings: #{path}" unless value.keys.all?(String)
-
-          value.each_value { |entry| validate_string_keys!(entry, path) }
-        when Array
-          value.each { |entry| validate_string_keys!(entry, path) }
-        end
+        super(name: name, config_env: config_env || CONFIG_ENV.fetch(name), namespace: "net-connector",
+              names: NAMES, common_keys: COMMON_KEYS, **options)
       end
 
-      def shared_sections(document, path)
-        unknown = document.keys - ["common", *NAMES]
-        raise ArgumentError, "unknown shared configuration namespaces in #{path}: #{unknown.join(", ")}" unless unknown.empty?
-
-        common = document.fetch("common", {})
-        native = document.fetch(@name, {})
-        unless common.is_a?(Hash) && native.is_a?(Hash)
-          raise ArgumentError, "common and #{@name} configuration must contain mappings: #{path}"
-        end
-        unknown_common = common.keys - COMMON_KEYS
-        unless unknown_common.empty?
-          raise ArgumentError, "unsupported common configuration fields in #{path}: #{unknown_common.join(", ")}"
-        end
-        validate_string_keys!(common, path)
-        validate_string_keys!(native, path)
-        [common, native, document.key?(@name)]
-      end
-
-      def resolve_paths(document, path)
-        result = self.class.copy(document)
-        @path_fields.each { |segments| resolve_path!(result, segments, File.dirname(path), segments.join(".")) }
-        result
-      end
-
-      def resolve_path!(value, segments, directory, field)
-        return unless value.is_a?(Hash) && !segments.empty?
-
-        key, *rest = segments
-        keys = key == "*" ? value.keys : [key]
-        keys.each do |entry|
-          next unless value.key?(entry)
-
-          if rest.empty?
-            value[entry] = declared_path(value[entry], directory, field) if value[entry].is_a?(String) && !value[entry].empty?
-          else
-            resolve_path!(value[entry], rest, directory, field)
-          end
-        end
-      end
-
-      # Declared paths may identify remote archive roots as well as local files.
-      def declared_path(value, directory, field)
-        raise ArgumentError if value.to_s.include?("\0")
-
-        return value if @path_literals.fetch(field, []).include?(value)
-
-        value.to_s.match?(%r{\A[A-Za-z][A-Za-z0-9+.-]*://}) ? value : absolute(value, directory)
-      rescue ArgumentError
-        raise ArgumentError, "invalid path #{field}", cause: nil
-      end
-
-      def resolve_environment_paths!(values, directory)
-        @env_path_keys.each do |key|
-          values[key] = declared_path(values[key], directory, key) if present(values[key])
-        end
-      end
-
-      def merge_layer(previous, document, path, fields)
-        resolved = resolve_paths(document, path)
-        record_fields(resolved, path, fields, previous: previous)
-        self.class.merge(previous, resolved)
-      end
-
-      def record_fields(document, source, fields, prefix = nil, previous: {})
-        document.each do |key, value|
-          name = [prefix, key].compact.join(".")
-          before = previous.is_a?(Hash) ? previous[key] : nil
-          next if value.is_a?(Hash) && value.empty? && before.is_a?(Hash) && !before.empty?
-
-          if value.is_a?(Hash) && !value.empty?
-            fields.delete(name)
-            record_fields(value, source, fields, name, previous: before)
-          else
-            fields.delete_if { |field, _| field == name || field.start_with?("#{name}.") }
-            fields[name] = source
-          end
-        end
-      end
-
-      def update_sources(fields)
-        @sources = self.class.freeze_tree({ "configuration_files" => @config_files,
-                                            "environment_files" => @environment_files, "fields" => fields })
-      end
-
-      # Dotenv's grammar is reused, but substitutions are deliberately isolated:
-      # its default implementation reads real ENV and executes shell commands.
-      def parse_environment(path, inherited)
-        require "dotenv"
-        process = @process_environment
-        variable_pattern = Dotenv::Substitutions::Variable.singleton_class.const_get(:VARIABLE)
-        parser_class = Class.new(Dotenv::Parser) do
-          define_singleton_method(:substitutions) do
-            [lambda do |value, local|
-              raise ArgumentError, "command substitution is unsupported" if value.include?("$(")
+      # 共享文件按工具分区；各专用 YAML 保持原有字段布局。
+      def self.dump(document, name:, path:)
+        raise ArgumentError, "unsupported configuration name: #{name}" unless NAMES.include?(name.to_s)
 
-              value.gsub(variable_pattern) do |variable|
-                match = Regexp.last_match
-                if match[1] == "\\"
-                  variable[1..]
-                elsif match[3]
-                  process.fetch(match[3]) { local.fetch(match[3]) { inherited.fetch(match[3], "") } }
-                else
-                  variable
-                end
-              end
-            end]
-          end
-          define_method(:expand_newlines) do |value|
-            if (@hash["DOTENV_LINEBREAK_MODE"] || inherited["DOTENV_LINEBREAK_MODE"]) == "legacy"
-              value.gsub('\\n', "\n").gsub('\\r', "\r")
-            else
-              value.gsub('\\n', "\\\\\\n").gsub('\\r', "\\\\\\r")
-            end
-          end
-          private :expand_newlines
-        end
-        contents = File.read(path)
-        remainder = contents.gsub(Dotenv::Parser::LINE, "")
-        unless remainder.lines.all? { |line| line.strip.empty? || line.lstrip.start_with?("#") }
-          raise ArgumentError, "invalid environment syntax"
-        end
-        parser_class.call(contents, overwrite: true)
-      rescue Dotenv::FormatError, ArgumentError, SystemCallError, IOError => error
-        raise ArgumentError, "cannot read environment file: #{path} (#{error.class})"
+        super(document, name: name, path: path, namespace: "net-connector")
       end
     end
   end

data/lib/net/connector/{netdisco → inventory}/address_set.rb

@@ -4,7 +4,7 @@ require "ipaddr"
 
 module Net
   module Connector
-    module Netdisco
+    module Inventory
       # 精确地址用索引，网段和范围只保存端点；绝不展开地址或发起扫描。
       class AddressSet
         # 规范化精确地址并合并同族网段区间，不展开大型地址范围。

data/lib/net/connector/inventory/filters.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "selection"
+
+module Net
+  module Connector
+    module Inventory
+      # 脚本共享筛选词汇和参数；配置来源及优先级仍由宿主决定。
+      module Filters
+        LISTS = {
+          "hosts" => :include_hosts, "exclude_hosts" => :exclude_hosts,
+          "names" => :include_names, "exclude_names" => :exclude_names,
+          "vendors" => :include_vendors, "exclude_vendors" => :exclude_vendors,
+          "models" => :include_models, "exclude_models" => :exclude_models
+        }.freeze
+        MODES = %w[name_match model_match].freeze
+        FIELDS = (LISTS.keys + MODES).freeze
+        FLAGS = {
+          "--hosts LIST" => "hosts", "--exclude-hosts LIST" => "exclude_hosts",
+          "--name LIST" => "names", "--exclude-name LIST" => "exclude_names",
+          "--vendor LIST" => "vendors", "--exclude-vendor LIST" => "exclude_vendors",
+          "--model LIST" => "models", "--exclude-model LIST" => "exclude_models"
+        }.freeze
+
+        def self.selection(values)
+          arguments = LISTS.to_h { |key, argument| [argument, values.fetch(key, [])] }
+          MODES.each { |key| arguments[key.to_sym] = values.fetch(key, :contains) }
+          Selection.new(**arguments)
+        end
+
+        # 每个回调只交付本次参数；追加或覆盖由配置适配器显式处理。
+        def self.add_options(parser, single_host: true, &accept)
+          flags = single_host ? {"--host IP" => "hosts"}.merge(FLAGS) : FLAGS
+          flags.each do |flag, key|
+            parser.on(flag, "筛选已有清单，同类条件取并集，排除优先") do |value|
+              items = value.split(",", -1).map(&:strip)
+              raise OptionParser::InvalidArgument, "filter list contains empty items" if items.empty? || items.any?(&:empty?)
+
+              accept.call(key, items)
+            end
+          end
+          MODES.each do |key|
+            parser.on("--#{key.tr("_", "-")} MODE", %w[contains prefix glob], "匹配方式 contains / prefix / glob") { |value| accept.call(key, value) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/inventory/selection.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "address_set"
+
+module Net
+  module Connector
+    module Inventory
+      # 只筛选已有设备，不识别厂商、不发现地址、不建立连接。
+      class Selection
+        Decision = Data.define(:reasons) do
+          def initialize(reasons:)
+            super(reasons: reasons.dup.freeze)
+          end
+
+          def selected? = reasons.empty?
+        end
+
+        def initialize(include_hosts: [], exclude_hosts: [], include_names: [], exclude_names: [],
+                       include_vendors: [], exclude_vendors: [], include_models: [], exclude_models: [],
+                       name_match: :contains, model_match: :contains)
+          @include_hosts, @exclude_hosts = AddressSet.new(include_hosts), AddressSet.new(exclude_hosts)
+          @names = [text_list(include_names), text_list(exclude_names), mode(name_match)].freeze
+          @models = [text_list(include_models), text_list(exclude_models), mode(model_match)].freeze
+          @vendors = [vendor_list(include_vendors), vendor_list(exclude_vendors)].freeze
+          freeze
+        end
+
+        # 同字段包含取并集，不同字段取交集；排除优先，原因不携带设备正文。
+        def evaluate(host:, vendor: nil, name: nil, model: nil)
+          reasons = []
+          if @exclude_hosts.include?(host)
+            reasons << :host_excluded
+          elsif !@include_hosts.empty? && !@include_hosts.include?(host)
+            reasons << :host_not_included
+          end
+          vendor = vendor.to_s
+          if @vendors.last.include?(vendor)
+            reasons << :vendor_excluded
+          elsif !@vendors.first.empty? && !@vendors.first.include?(vendor)
+            reasons << :vendor_not_included
+          end
+          reasons << text_reason(:name, name, @names)
+          reasons << text_reason(:model, model, @models)
+          Decision.new(reasons: reasons.compact)
+        end
+
+        def selected?(host, vendor = nil, name: nil, model: nil)
+          evaluate(host: host, vendor: vendor, name: name, model: model).selected?
+        end
+
+        def inspect = "#<#{self.class}>"
+        alias to_s inspect
+
+        private
+
+        def mode(value)
+          unless (value.is_a?(String) || value.is_a?(Symbol)) && %w[contains prefix glob].include?(value.to_s)
+            raise ArgumentError, "match mode must be contains, prefix or glob"
+          end
+          value.to_sym
+        end
+
+        def text_list(values)
+          unless values.is_a?(Array) && values.all? { |v| v.is_a?(String) && v.valid_encoding? && !v.strip.empty? && !/[\x00-\x1f\x7f]/.match?(v) }
+            raise ArgumentError, "filters must be arrays of nonempty text"
+          end
+          values.map { |v| v.downcase.freeze }.uniq.freeze
+        end
+
+        def vendor_list(values)
+          unless values.is_a?(Array) && values.all? { |v| v.is_a?(String) || v.is_a?(Symbol) }
+            raise ArgumentError, "vendors must be strings or symbols"
+          end
+          text_list(values.map(&:to_s))
+        end
+
+        def text_reason(field, value, rules)
+          includes, excludes, match = rules
+          value = value&.to_s&.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")&.downcase
+          return :"#{field}_excluded" if value && excludes.any? { |pattern| matches?(pattern, value, match) }
+          return :"#{field}_not_included" if !includes.empty? && (!value || includes.none? { |pattern| matches?(pattern, value, match) })
+
+          nil
+        end
+
+        def matches?(pattern, value, match)
+          case match
+          when :contains then value.include?(pattern)
+          when :prefix then value.start_with?(pattern)
+          when :glob then File.fnmatch?(pattern, value)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/options"
+require "ctx_cli/terminal"
 require_relative "../settings"
 require_relative "../planner"
 require_relative "../config"
 require_relative "../../config"
 require_relative "help"
+require_relative "../../inventory/filters"
 
 module Net
   module Connector
@@ -65,13 +68,9 @@ module Net
           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 }
+            CtxCli::Options.output(opts, values, quiet: :no_progress)
             opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
-            opts.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { values[:init] = true }
-            opts.on("--interactive", "缺少文件时询问是否创建，并可交互填写") { values[:interactive] = true }
-            opts.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { values[:interactive] = false }
+            CtxCli::Options.initialization(opts, values)
           end
 
           # 登记互斥的拓扑执行模式和格式化参数，应用模式必须显式选择。
@@ -208,25 +207,16 @@ module Net
 
           # 同类 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(",")
+            Net::Connector::Inventory::Filters.add_options(opts, single_host: false) do |key, value|
+              field = Net::Connector::Inventory::Filters::LISTS.fetch(key, key).to_s
+              environment_key = "NC_#{field.upcase}"
+              if value.is_a?(Array)
+                previous = values[:environment][environment_key]&.split(",") || []
+                values[:environment][environment_key] = (previous + value).uniq.join(",")
+              else
+                values[:environment][environment_key] = value
               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?(/[\/,]/)
 
@@ -265,15 +255,7 @@ module Net
             return unless values[flag]
 
             raise ArgumentError, "密码提示与显式密码不能同时使用" if values[:environment].key?(key)
-            raise ArgumentError, "密码提示需要交互终端；自动化任务可使用环境变量或 --stdin-credentials" unless input.tty?
-            require "io/console"
-            output.print "#{label}："
-            output.flush
-            password = input.noecho { |terminal| terminal.gets("\n") }&.chomp("\n")
-            output.puts
-            raise ArgumentError, "密码不能为空" if password.nil? || password.empty?
-
-            values[:environment][key] = password
+            values[:environment][key] = CtxCli::Terminal.new(input: input, out: output).password(label: label)
           end
           private_class_method :read_password, :parser_for
         end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "ctx_cli/terminal"
 require_relative "../config/initializer"
 require_relative "../config/defaults"
 
@@ -98,7 +99,7 @@ module Net
 
           # 标准输入凭据协议独占输入；只有真实终端才允许配置问答。
           def terminal?
-            !@options[:stdin_credentials] && @input.respond_to?(:tty?) && @input.tty? && @output.respond_to?(:tty?) && @output.tty?
+            !@options[:stdin_credentials] && CtxCli::Terminal.tty?(@input, @output)
           end
 
           # 创建和定制为独立选择；显式 --init 默认直接生成已识别值。

data/lib/net/connector/netdisco/config/defaults.rb

@@ -15,7 +15,8 @@ module Net
                               "cache_directory" => "./.cache/net-connector/inventory", "inventory_timeout" => 300,
                               "page_size" => 500, "allow_insecure_http" => false },
               "inventory" => { "include_hosts" => [], "exclude_hosts" => [], "include_names" => [], "exclude_names" => [],
-                               "include_vendors" => [], "exclude_vendors" => [], "name_match" => "contains" },
+                               "include_vendors" => [], "exclude_vendors" => [], "name_match" => "contains",
+                               "include_models" => [], "exclude_models" => [], "model_match" => "contains" },
               "ssh" => { "protocol" => "ssh", "host_key_policy" => "accept_new", "log_level" => "info" },
               "backup" => { "directory" => directory || "./backups", "parallel" => 4 }
             }

data/lib/net/connector/netdisco/config/initializer.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require "yaml"
-require "tempfile"
+require "ctx_cli/initialization"
+require "ctx_cli/terminal"
 require_relative "../settings"
 require_relative "../../config"
 
@@ -14,6 +15,7 @@ module Net
           # 绑定配置问答的输入输出，保留调用方对 IO 的所有权。
           def initialize(input: $stdin, output: $stderr)
             @input, @output = input, output
+            @writer = CtxCli::Initialization.new(prefix: ".net-connector-config-")
           end
 
           # 完成默认值校验与可选问答后独占发布新配置，不覆盖已存在文件。
@@ -26,7 +28,7 @@ module Net
 
             values = YAML.safe_load(YAML.dump(document), aliases: false)
             validate!(values)
-            interactive = @input.respond_to?(:tty?) && @input.tty? && @output.respond_to?(:tty?) && @output.tty? if interactive.nil?
+            interactive = CtxCli::Terminal.tty?(@input, @output) if interactive.nil?
             configure(values, mode: mode, inherited_parallel: inherited_parallel) if interactive && answer("进入交互配置？[y/N]", "n").casecmp?("y")
             validate!(values)
             name = mode == :topology ? "topology" : "backup"
@@ -43,14 +45,7 @@ module Net
           private
 
           # 判断已有配置是否为普通文件；符号链接或其他类型不作为可用配置。
-          def existing?(path)
-            stat = File.lstat(path)
-            raise ArgumentError, "config path must be a regular file" unless stat.file?
-
-            true
-          rescue Errno::ENOENT
-            false
-          end
+          def existing?(path) = @writer.existing?(path)
 
           # 通过完整策略快照校验候选文档，拒绝生成不可执行的配置。
           def validate!(document)
@@ -102,10 +97,11 @@ module Net
             if document.dig("netdisco", "source") == "http"
               field(document, "netdisco", "url", "清单 URL", mode.nil? ? "https://netdisco.example.invalid" : nil)
             end
-            %w[include_hosts exclude_hosts include_names exclude_names].each do |key|
+            %w[include_hosts exclude_hosts include_names exclude_names include_models exclude_models].each do |key|
               field(document, "inventory", key, key, [], list: true)
             end
             field(document, "inventory", "name_match", "名称匹配 contains/prefix/glob", "contains")
+            field(document, "inventory", "model_match", "型号匹配 contains/prefix/glob", "contains")
             %w[include_vendors exclude_vendors].each { |key| field(document, "inventory", key, key, [], list: true) }
             if document.key?("topology")
               field(document, "topology", "parallel", "拓扑并发数 1..500", inherited_parallel)
@@ -117,51 +113,8 @@ module Net
             end
           end
 
-          # 尝试关闭目录与临时文件全部句柄，清理失败不覆盖原始异常。
-          def close_files(file, parent, primary)
-            Thread.handle_interrupt(Exception => :never) do
-              error = nil
-              [-> { parent&.close }, -> { file&.close! }].each do |close|
-                begin
-                  close.call
-                rescue Exception => failure # rubocop:disable Lint/RescueException -- 两个资源均尝试关闭，保留首个故障。
-                  error ||= failure
-                end
-              end
-              raise error if error && !primary
-            end
-          end
-
-          # 先写入并同步私有临时文件，再以独占硬链接发布完整配置并同步目录。
-          # 最终路径只在内容写全并同步后出现；已有目标由独占链接保护，取消也不能留下半份配置。
-          def write(path, contents)
-            directory = File.realpath(File.dirname(File.expand_path(path)))
-            destination = File.join(directory, File.basename(path))
-            file = parent = nil
-            begin
-              Thread.handle_interrupt(Exception => :never) { file = Tempfile.new([".net-connector-config-", ".tmp"], directory) }
-              file.binmode
-              file.chmod(0o600)
-              file.write(contents)
-              file.flush
-              file.fsync
-              begin
-                File.link(file.path, destination)
-              rescue Errno::EEXIST
-                return :exists if existing?(destination)
-
-                raise
-              end
-              Thread.handle_interrupt(Exception => :never) { parent = File.open(directory, File::RDONLY | File::NOFOLLOW) }
-              parent.fsync
-              :created
-            rescue Exception => failure # rubocop:disable Lint/RescueException -- 清理不能覆盖输入取消或发布故障。
-              primary = failure
-              raise
-            ensure
-              close_files(file, parent, primary)
-            end
-          end
+          # 公开文档已校验；排他发布、同步与清理由公共初始化器负责。
+          def write(path, contents) = @writer.create(path: path, contents: contents)
         end
       end
     end

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

@@ -45,6 +45,9 @@ module Net
                            "include_names" => ["NC_INCLUDE_NAMES", :list],
                            "exclude_names" => ["NC_EXCLUDE_NAMES", :list],
                            "name_match" => ["NC_NAME_MATCH", :string],
+                           "include_models" => ["NC_INCLUDE_MODELS", :list],
+                           "exclude_models" => ["NC_EXCLUDE_MODELS", :list],
+                           "model_match" => ["NC_MODEL_MATCH", :string],
                            "exclude_vendors" => ["NC_EXCLUDE_VENDORS", :list],
                            "include_vendors" => ["NC_INCLUDE_VENDORS", :list],
                            "vendor_overrides" => ["NC_VENDOR_OVERRIDES", :json],

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

@@ -38,7 +38,7 @@ module Net
           end
           vendor = rules.resolve(row)
           name = [row["name"], row["dns"]].find { |value| value && !value.strip.empty? }
-          issue ||= :filtered unless rules.selected?(host, vendor, name: name&.strip)
+          issue ||= :filtered unless rules.selected?(host, vendor, name: name&.strip, model: row["model"])
           issue ||= :unsupported_vendor unless vendor
           new(host: host, source_ip: source_ip, name: name&.strip, vendor: vendor,
               source_vendor: row["vendor"], model: row["model"], os: row["os"],

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

@@ -2,7 +2,7 @@
 
 require "ipaddr"
 require_relative "../../connector"
-require_relative "address_set"
+require_relative "../inventory/selection"
 
 module Net
   module Connector
@@ -12,17 +12,11 @@ module Net
         # 校验并保存清单过滤和厂商映射规则。
         def initialize(include_hosts: [], exclude_hosts: [], include_vendors: [], vendor_overrides: {},
                        host_overrides: {}, mappings: [], include_names: [], exclude_names: [],
-                       name_match: :contains, exclude_vendors: [])
-          @include_hosts = AddressSet.new(include_hosts)
-          @exclude_hosts = AddressSet.new(exclude_hosts)
-          @include_vendors = vendor_list(include_vendors)
-          @exclude_vendors = vendor_list(exclude_vendors)
-          @include_names = name_list(include_names)
-          @exclude_names = name_list(exclude_names)
-          unless (name_match.is_a?(String) || name_match.is_a?(Symbol)) && %w[contains prefix glob].include?(name_match.to_s)
-            raise ArgumentError, "name_match must be contains, prefix or glob"
-          end
-          @name_match = name_match.to_sym
+                       name_match: :contains, exclude_vendors: [], include_models: [], exclude_models: [], model_match: :contains)
+          @selection = Net::Connector::Inventory::Selection.new(include_hosts: include_hosts, exclude_hosts: exclude_hosts,
+            include_names: include_names, exclude_names: exclude_names, name_match: name_match,
+            include_vendors: vendor_list(include_vendors), exclude_vendors: vendor_list(exclude_vendors),
+            include_models: include_models, exclude_models: exclude_models, model_match: model_match)
           @vendor_overrides = vendor_mapping(vendor_overrides)
           @host_overrides = host_mapping(host_overrides)
           @mappings = device_mappings(mappings)
@@ -153,19 +147,8 @@ module Net
         end
 
         # 判断设备是否通过地址和厂商过滤。
-        def selected?(host, vendor, name: nil)
-          return false if @exclude_hosts.include?(host)
-          return false if !@include_hosts.empty? && !@include_hosts.include?(host)
-          return false if @exclude_vendors.include?(vendor)
-          return false if !@include_vendors.empty? && !@include_vendors.include?(vendor)
-
-          return true if @include_names.empty? && @exclude_names.empty?
-
-          value = name.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "").downcase
-          return false if @exclude_names.any? { |pattern| name_matches?(pattern, value) }
-          return false if !@include_names.empty? && @include_names.none? { |pattern| name_matches?(pattern, value) }
-
-          true
+        def selected?(host, vendor, name: nil, model: nil)
+          @selection.selected?(host, vendor, name: name, model: model)
         end
 
         private
@@ -176,23 +159,6 @@ module Net
           wireless ? :h3c_wireless : :h3c
         end
 
-        # 校验名称过滤项为有效非空文本，统一小写并去重冻结。
-        def name_list(values)
-          unless values.is_a?(Array) && values.all? { |value| value.is_a?(String) && !value.strip.empty? && value.valid_encoding? }
-            raise ArgumentError, "name filters must be arrays of nonempty strings"
-          end
-          values.map { |value| value.downcase.freeze }.uniq.freeze
-        end
-
-        # 按包含、前缀或通配符模式匹配已规范化的设备名称。
-        def name_matches?(pattern, value)
-          case @name_match
-          when :contains then value.include?(pattern)
-          when :prefix then value.start_with?(pattern)
-          when :glob then File.fnmatch?(pattern, value)
-          end
-        end
-
         # 将设备标签转为便于匹配的小写词串。
         def normalize(value) = value.to_s.downcase.gsub(/[^a-z0-9]+/, " ").strip
       end

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

@@ -190,6 +190,8 @@ module Net
                     exclude_vendors: list("NC_EXCLUDE_VENDORS"),
                     include_names: list("NC_INCLUDE_NAMES"), exclude_names: list("NC_EXCLUDE_NAMES"),
                     name_match: raw("NC_NAME_MATCH", "contains"),
+                    include_models: list("NC_INCLUDE_MODELS"), exclude_models: list("NC_EXCLUDE_MODELS"),
+                    model_match: raw("NC_MODEL_MATCH", "contains"),
                     vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
                     host_overrides: json("NC_HOST_OVERRIDES", {}),
                     mappings: json("NC_DEVICE_RULES", []))
@@ -381,6 +383,8 @@ module Net
                          exclude_vendors: list("NC_EXCLUDE_VENDORS"),
                          include_names: list("NC_INCLUDE_NAMES"), exclude_names: list("NC_EXCLUDE_NAMES"),
                          name_match: raw("NC_NAME_MATCH", "contains"),
+                         include_models: list("NC_INCLUDE_MODELS"), exclude_models: list("NC_EXCLUDE_MODELS"),
+                         model_match: raw("NC_MODEL_MATCH", "contains"),
                          vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
                          host_overrides: json("NC_HOST_OVERRIDES", {}),
                          device_rules: json("NC_DEVICE_RULES", []) },

data/lib/net/connector/version.rb

@@ -3,6 +3,6 @@
 module Net
   module Connector
     # gemspec、CLI 与发布工具共用此版本，运行时读取不触发设备依赖加载。
-    VERSION = "0.16.1"
+    VERSION = "0.17.1"
   end
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: net-connector
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.1
 platform: ruby
 authors:
 - net-connector contributors
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: expect-pty
   requirement: !ruby/object:Gem::Requirement
@@ -417,8 +431,10 @@ files:
 - lib/net/connector/engine/terminal/renderer.rb
 - lib/net/connector/engine/terminal/text.rb
 - lib/net/connector/engine/transports.rb
+- lib/net/connector/inventory/address_set.rb
+- lib/net/connector/inventory/filters.rb
+- lib/net/connector/inventory/selection.rb
 - lib/net/connector/netdisco.rb
-- lib/net/connector/netdisco/address_set.rb
 - lib/net/connector/netdisco/batch.rb
 - lib/net/connector/netdisco/cli.rb
 - lib/net/connector/netdisco/cli/backup.rb