net-connector 0.15.0 → 0.16.0

data/lib/net/connector/config.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Net
+  module Connector
+    # Host-side configuration discovery. Requiring this file never loads device I/O.
+    class Config
+      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:)
+        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
+      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?("$(")
+
+              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})"
+      end
+    end
+  end
+end

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

@@ -43,7 +43,7 @@ module Net
         def initialize(host:, vendor:, strategy:, neighbors:, descriptions:, formatter:, description_matcher: nil)
           @host, @vendor, @strategy = host, vendor, strategy
           @neighbors, @descriptions, @formatter = neighbors, descriptions, formatter
-          @description_matcher = description_matcher || ->(current, proposed, _peer) { InterfaceDescription.equivalent?(current, proposed) }
+          @description_matcher = description_matcher || ->(current, proposed, _peer) { Description.equivalent?(current, proposed) }
           @comparisons, @issues, @evidence, @changes = [], [], {}, []
         end
 
@@ -74,9 +74,9 @@ module Net
           return reject_interface(row, :interface_missing) unless @descriptions.key?(interface)
 
           proposed = @formatter.call(peer)
-          InterfaceDescription.validate!(proposed)
+          Description.validate!(proposed)
           local = @strategy.configuration_interface(peer.local_interface)
-          InterfaceDescription.validate_interface!(local)
+          Description.validate_interface!(local)
           row.merge!(expected: proposed, status: compare_status(current, proposed, peer))
           @evidence[interface] = [peer.neighbor_name, peer.neighbor_interface, current]
           return if row[:status] == :matches

data/lib/net/connector/device/interfaces/{interface_blocks.rb → blocks.rb}

@@ -4,7 +4,7 @@ module Net
   module Connector
     class Interfaces
       # interface 块方言共用完整性校验；解析器不能静默遗漏未知接口头。
-      module InterfaceBlocks
+      module Blocks
         # 比较原配置接口头与解析记录，拒绝静默遗漏接口的解析结果。
         def validate_descriptions!(config, rows)
           expected = config.scan(/^interface[ \t]+([^\r\n]*)/).flatten.map(&:strip)

data/lib/net/connector/device/interfaces/{interface_description.rb → description.rb}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-require_relative "interface_name"
+require_relative "name"
 
 module Net
   module Connector
     class Interfaces
       # 描述文本与常见接口视图命令的纯构造方法，不连接或修改设备。
-      module InterfaceDescription
+      module Description
         # 将邻居名称和接口拼成默认描述；统一邻居接口简称，原始发现记录保持不变。
         def self.format(neighbor, abbreviate: true, lowercase: false)
           port = if abbreviate
-                   InterfaceName.short(neighbor.neighbor_interface, lowercase: lowercase)
+                   Name.short(neighbor.neighbor_interface, lowercase: lowercase)
                  else
                    lowercase ? neighbor.neighbor_interface.downcase : neighbor.neighbor_interface
                  end
@@ -25,10 +25,10 @@ module Net
           old_prefix, separator, old_port = current.rpartition("_")
           new_prefix, new_separator, new_port = expected.rpartition("_")
           return false if separator.empty? || new_separator.empty? || !old_prefix.casecmp?(new_prefix)
-          return false unless InterfaceName::RULES.any? { |pattern,| pattern.match?(old_port) } &&
-                              InterfaceName::RULES.any? { |pattern,| pattern.match?(new_port) }
+          return false unless Name::RULES.any? { |pattern,| pattern.match?(old_port) } &&
+                              Name::RULES.any? { |pattern,| pattern.match?(new_port) }
 
-          InterfaceName.key(old_port) == InterfaceName.key(new_port)
+          Name.key(old_port) == Name.key(new_port)
         end
 
         # 生成进入接口、设置描述和退出视图的命令，不执行设备操作。

data/lib/net/connector/device/interfaces/immediate_strategy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "strategy"
-require_relative "interface_blocks"
+require_relative "blocks"
 require_relative "../../engine/terminal/renderer"
 
 module Net
@@ -9,7 +9,7 @@ module Net
     class Interfaces
       # 接口描述立即生效的设备：退出视图、读回、保存是不同阶段，不能在 finish 中提前保存。
       class ImmediateStrategy < Strategy
-        include InterfaceBlocks
+        include Blocks
 
         # 使用配置采集命令读回即时生效的接口描述。
         def verification_commands = @device.config_commands

data/lib/net/connector/device/interfaces/{interface_name.rb → name.rb}

@@ -4,7 +4,7 @@ module Net
   module Connector
     class Interfaces
       # 接口身份匹配与描述展示共用名称规则；展示简称不能直接用作下发命令。
-      module InterfaceName
+      module Name
         RULES = [
           [/\A(?:bridge-aggregation|bagg)(?=\d)/i, "bridge-aggregation", "BAGG"],
           [/\A(?:route-aggregation|ragg)(?=\d)/i, "route-aggregation", "RAGG"],

data/lib/net/connector/device/interfaces/stages.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../engine/script"
-require_relative "interface_description"
+require_relative "description"
 
 module Net
   module Connector
@@ -37,7 +37,7 @@ module Net
 
           interfaces = {}
           changes.each do |change|
-            InterfaceDescription.validate_interface!(change.interface)
+            Description.validate_interface!(change.interface)
             key = strategy.interface_key(change.interface)
             raise ArgumentError, "topology changes must identify unique interfaces" if interfaces.key?(key)
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "shellwords"
-require_relative "interface_description"
+require_relative "description"
 require_relative "quoted_text"
 
 module Net
@@ -65,10 +65,10 @@ module Net
         def description_key(row) = interface_key(row.fetch("INTERFACE"))
 
         # 将发现接口名归一为查找当前配置所用的键。
-        def interface_key(name) = InterfaceName.key(name)
+        def interface_key(name) = Name.key(name)
 
         # 将发现协议常用的接口简称展开为配置视图可识别的名称。
-        def configuration_interface(name) = InterfaceName.configuration(name)
+        def configuration_interface(name) = Name.configuration(name)
 
         # 还原 PAN-OS set 配置或 Alteon dump 中的引号描述。
         def decode_description(value)

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

@@ -137,7 +137,7 @@ module Net
       # 在同一会话内采集邻居和描述，返回逐接口证据与候选修正计划。
       def audit(abbreviate: true, lowercase: false, description_matcher: nil, &formatter)
         validate_format_options!(abbreviate, lowercase)
-        formatter ||= ->(peer) { InterfaceDescription.format(peer, abbreviate: abbreviate, lowercase: lowercase) }
+        formatter ||= ->(peer) { Description.format(peer, abbreviate: abbreviate, lowercase: lowercase) }
         @device.with_operation(:plan) do
           AuditBuilder.new(host: @device.host, vendor: @device.vendor, strategy: @strategy,
                            neighbors: neighbors, descriptions: descriptions, formatter: formatter, description_matcher: description_matcher).call
@@ -191,10 +191,10 @@ module Net
           proposed = if formatter
                        formatter.call(neighbor)
                      else
-                       InterfaceDescription.format(neighbor, abbreviate: abbreviate, lowercase: lowercase)
+                       Description.format(neighbor, abbreviate: abbreviate, lowercase: lowercase)
                      end
-          InterfaceDescription.validate!(proposed)
-          next if InterfaceDescription.equivalent?(old, proposed)
+          Description.validate!(proposed)
+          next if Description.equivalent?(old, proposed)
 
           Change.new(interface: @strategy.configuration_interface(neighbor.local_interface), old_description: old,
                      new_description: proposed, neighbor: neighbor)
@@ -270,7 +270,7 @@ module Net
         end
 
         plan.changes.each do |change|
-          InterfaceDescription.validate!(change.new_description)
+          Description.validate!(change.new_description)
           unless evidence.fetch(@strategy.interface_key(change.interface)) ==
                  [change.neighbor.neighbor_name, change.neighbor.neighbor_interface, change.old_description]
             raise ArgumentError, "plan changes do not match its discovery evidence"

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

@@ -36,8 +36,8 @@ module Net
         copy
       end
 
-      # 返回不展开命令和输出的错误摘要。
-      def inspect = "#<#{self.class} code=#{code.inspect} phase=#{phase.inspect} host=#{host.inspect}>"
+      # 摘要复用日志诊断词表；扩展钩子可提供原始元数据，但不能借摘要输出配置正文。
+      def inspect = "#<#{self.class} code=#{Metadata.code(code).inspect} phase=#{Metadata.phase(phase).inspect}>"
     end
 
     class ConnectionError < Error; end
@@ -89,8 +89,8 @@ module Net
         freeze
       end
 
-      # 返回底层异常类型摘要。
-      def inspect = "#<#{self.class} type=#{type}>"
+      # 类型名称可能由外部异常类提供，摘要只展示共享词表接受的名称。
+      def inspect = "#<#{self.class} type=#{Error::Metadata.type(type)}>"
     end
   end
 end

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

@@ -52,8 +52,8 @@ module Net
         config || output
       end
 
-      # 返回结果成功状态、步骤数量和错误码摘要。
-      def inspect = "#<#{self.class} success=#{success?} steps=#{steps.size} code=#{error&.code.inspect}>"
+      # 摘要只展示受控错误码，不展开扩展钩子提供的原始元数据。
+      def inspect = "#<#{self.class} success=#{success?} steps=#{steps.size} code=#{Error::Metadata.code(error&.code).inspect}>"
     end
   end
 end

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

@@ -18,12 +18,13 @@ module Net
         class Backup
           # 保存批次模式与调用方 IO，构造阶段不读取清单、不创建目录。
           def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr,
-                         default_config: nil, default_directory: nil, default_env: nil, load_env: false)
+                         default_config: nil, default_directory: nil, default_env: nil, configuration_options: {})
             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, @default_env = load_env, default_env
+            @default_env = default_env
+            @configuration_options = configuration_options
           end
 
           # 先固定并校验策略，再预览、执行和保存报告；成功判定使用最终报告。
@@ -33,6 +34,12 @@ module Net
             apply_defaults(options)
             return 0 if initialize_config?(options)
 
+            if options[:show_config]
+              settings = CLI::Options.settings(options, env: @env, configuration: @configuration,
+                                               defaults: @default_directory ? { "NC_BACKUP_DIRECTORY" => @default_directory } : {})
+              @output.puts JSON.pretty_generate(settings.public_config.merge(sources: CLI::Options.sources(@configuration, options)))
+              return 0
+            end
             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])
@@ -88,21 +95,17 @@ module Net
             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") && !@env.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")
+            options.fetch(:environment)["NC_CONFIG"] ||= @default_config if @default_config && !@env["NC_CONFIG"]
+            options[:env_file] ||= @default_env if @default_env
+            @configuration = CLI::Options.configuration(options, env: @env, mode: @mode, **@configuration_options)
           end
 
           # 配置不存在时生成并验证初始文件；本次运行到此结束，不继续连接设备。
           def initialize_config?(options)
-            Setup.new(mode: @mode, options: options, env: @env, input: @input, output: @error,
-                      env_path: @default_env, directory: @default_directory, load_env: @load_env).initialize_files?
+            Setup.new(mode: @mode, options: options, input: @input, output: @error,
+                      directory: @default_directory || File.expand_path("backups"), configuration: @configuration).initialize_files?
           end
 
           # 清单离线回退和本地保存故障单独提示，不覆盖设备操作结果。
@@ -117,7 +120,8 @@ module Net
 
           # 预检完成后才创建批次目录；补充日志路径时保持原策略快照与动态凭据来源。
           def prepare(options)
-            settings = CLI::Options.settings(options, env: @env, load_env: @load_env).for_run(mode: @mode)
+            settings = CLI::Options.settings(options, env: @env, configuration: @configuration,
+                                             defaults: @default_directory ? { "NC_BACKUP_DIRECTORY" => @default_directory } : {}).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

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

@@ -6,7 +6,7 @@ module Net
       class CLI
         # 简要帮助从实际解析器筛选；范例按执行模式生成完整命令。
         module Help
-          COMMON = %w[init config directory interactive non-interactive host hosts name exclude-name vendor
+          COMMON = %w[init config env-file show-config directory interactive non-interactive host hosts name exclude-name vendor
                       plan inventory-only parallel refresh-inventory json quiet no-progress help help-all examples].freeze
 
           # 从完整解析器帮助中筛选常用选项，避免维护重复的帮助文本。