net-connector 0.6.0 → 0.7.0

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

@@ -30,13 +30,10 @@ module Net
         @lock = Mutex.new
       end
 
-      # 判断会话状态和传输层是否都表明连接仍然有效。
       def connected? = state != :closed && !transport.closed?
 
-      # 返回当前是否已经进入特权模式。
       def privileged? = @privileged
 
-      # 标记当前会话已进入特权模式。
       def mark_privileged! = @privileged = true
 
       # 记录脚本之外的业务结果，例如设备报告的 TFTP 上传状态。
@@ -63,16 +60,16 @@ module Net
       end
 
       # 锁覆盖完整操作而不是单次写入，保证批处理命令不会交错。
-      def perform(phase)
+      def perform(phase, &)
         if @operation_owner == [Thread.current, Fiber.current] && !@performing
-          return perform_locked(phase) { yield }
+          return perform_locked(phase, &)
         end
         unless @lock.try_lock
           raise build_error(SessionBusy, "session already belongs to another operation", phase: phase), cause: nil
         end
 
         begin
-          perform_locked(phase) { yield }
+          perform_locked(phase, &)
         ensure
           @lock.unlock
         end
@@ -106,37 +103,6 @@ module Net
         raise build_error(SessionBusy, "backup path ownership must be acquired before a session operation", phase: phase), cause: nil
       end
 
-      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
-      def perform_locked(phase)
-        @performing = true
-        completed = false
-        begin
-          unless connected?
-            close_resources unless state == :closed
-            connect_session
-          end
-          @state = (phase == :connect) ? :ready : :executing
-          result = yield
-          completed = true
-          result
-        rescue => error
-          failure = normalize_error(error, phase: phase)
-          close_preserving_failure
-          raise failure, cause: nil
-        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
-          close_preserving_failure
-          raise
-        ensure
-          # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
-          # 半途的设备提示符误当成下一条命令的响应。
-          close_preserving_failure unless completed || !connected?
-          @state = :ready if connected?
-          @performing = false
-        end
-      end
-
-      private :perform_locked
-
       # 独占关闭会话；已有操作占用时返回会话繁忙错误。
       def close
         unless @lock.try_lock
@@ -195,6 +161,99 @@ module Net
         end
       end
 
+      # 按截止时间限制传输写入，并统一包装底层错误。
+      def write(bytes, deadline:, phase:, command: nil)
+        remaining = [deadline - Expect.monotonic, 0].max
+        transport.write(bytes, timeout: [remaining, configuration.write_timeout].min)
+      rescue => error
+        raise normalize_error(error, phase: phase, command: command), cause: nil
+      end
+
+      # 人工交互会结束当前连接，未完成的输入行不能在之后重放。
+      def interact(**options)
+        perform(:interact) do
+          @state = :interacting
+          begin
+            transport.interact(**options)
+          ensure
+            $ERROR_INFO ? close_preserving_failure : close_resources
+          end
+        end
+      end
+
+      # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
+      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
+        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
+        message = safe_error_text(message, sensitive: sensitive)
+        output = safe_error_text(output, sensitive: sensitive)
+        klass.new(message, host: configuration.host, phase: phase,
+                  command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
+                  source: command&.source, line: command&.line,
+                  output: truncate_output(output),
+                  underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
+      end
+
+      # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
+      def normalize_error(exception, phase:, command: nil)
+        if exception.is_a?(Error)
+          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
+          failed_command = exception.command || command&.text
+          if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
+            failed_command = "[REDACTED]"
+          end
+          message = safe_error_text(exception.message, sensitive: sensitive)
+          output = safe_error_text(exception.output, sensitive: sensitive)
+          return exception.with_diagnostics(
+            message: message,
+            host: exception.host || configuration.host, phase: exception.phase || phase,
+            command: failed_command && redactor.call(failed_command),
+            source: exception.source || command&.source, line: exception.line || command&.line,
+            output: truncate_output(output),
+            underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
+          )
+        end
+
+        klass = case exception
+                when Expect::WriteTimeout then WriteTimeout
+                when IOError, SystemCallError, Expect::SpawnError then TransportError
+                else InternalError
+                end
+        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
+      end
+
+      def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
+
+      private
+
+      # 一次操作从连接到结果处理始终持锁；异常或 throw 中断都关闭未完成会话。
+      def perform_locked(phase)
+        @performing = true
+        completed = false
+        begin
+          unless connected?
+            close_resources unless state == :closed
+            connect_session
+          end
+          @state = (phase == :connect) ? :ready : :executing
+          result = yield
+          completed = true
+          result
+        rescue => error
+          failure = normalize_error(error, phase: phase)
+          close_preserving_failure
+          raise failure, cause: nil
+        rescue Exception # rubocop:disable Lint/RescueException -- Interrupts release the transport, then propagate.
+          close_preserving_failure
+          raise
+        ensure
+          # throw/catch 也会离开此块；对话未完成时必须关闭连接，不能把
+          # 半途的设备提示符误当成下一条命令的响应。
+          close_preserving_failure unless completed || !connected?
+          @state = :ready if connected?
+          @performing = false
+        end
+      end
+
       def execute_command_with_logging(command, timeout:, prompt:)
         started = Expect.monotonic
         @log.log_event("command_start")
@@ -224,8 +283,6 @@ module Net
         end
       end
 
-      private :execute_command_with_logging, :elapsed_ms, :log_operation_completion
-
       # 在用户钩子运行前标记敏感上下文，动态交互尚未返回时也能保护其异常。
       def protect_command(command)
         redactor.output_sensitive! if command.output_sensitive?
@@ -235,8 +292,6 @@ module Net
         redactor.remember(command.text) if command.sensitive?
       end
 
-      private :protect_command
-
       # 写入命令、读取对话、识别设备诊断，并返回响应对象。
       def exchange_command(command, timeout:, prompt: nil)
         deadline = Expect.monotonic + (command.timeout || timeout)
@@ -260,109 +315,23 @@ module Net
         end
       end
 
-      private :exchange_command
-
-      # 按截止时间限制传输写入，并统一包装底层错误。
-      def write(bytes, deadline:, phase:, command: nil)
-        remaining = [deadline - Expect.monotonic, 0].max
-        transport.write(bytes, timeout: [remaining, configuration.write_timeout].min)
-      rescue => error
-        raise normalize_error(error, phase: phase, command: command), cause: nil
-      end
-
-      # 人工交互会结束当前连接，未完成的输入行不能在之后重放。
-      def interact(**options)
-        perform(:interact) do
-          @state = :interacting
-          begin
-            transport.interact(**options)
-          ensure
-            $ERROR_INFO ? close_preserving_failure : close_resources
-          end
-        end
-      end
-
-      # 创建带脱敏上下文、阶段、命令和输出尾部的领域错误。
-      def build_error(klass, message, phase:, command: nil, output: "".b, underlying: nil, **context)
-        sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
-        message = safe_error_text(message, sensitive: sensitive)
-        output = safe_error_text(output, sensitive: sensitive)
-        klass.new(message, host: configuration.host, phase: phase,
-                  command: command && (command.sensitive? ? "[REDACTED]" : redactor.call(command.text)),
-                  source: command&.source, line: command&.line,
-                  output: truncate_output(output),
-                  underlying: underlying && UnderlyingError.new(underlying, redactor, sensitive: sensitive), **context)
-      end
-
-      # 将底层异常映射为连接、传输、超时或内部错误，并保留安全上下文。
-      def normalize_error(exception, phase:, command: nil)
-        if exception.is_a?(Error)
-          sensitive = redactor.sensitive? || command&.sensitive? || command&.output_sensitive?
-          failed_command = exception.command || command&.text
-          if command&.sensitive? || (sensitive && exception.command && exception.command != command&.text)
-            failed_command = "[REDACTED]"
-          end
-          message = safe_error_text(exception.message, sensitive: sensitive)
-          output = safe_error_text(exception.output, sensitive: sensitive)
-          return exception.with_diagnostics(
-            message: message,
-            host: exception.host || configuration.host, phase: exception.phase || phase,
-            command: failed_command && redactor.call(failed_command),
-            source: exception.source || command&.source, line: exception.line || command&.line,
-            output: truncate_output(output),
-            underlying: exception.underlying && UnderlyingError.new(exception.underlying, redactor, sensitive: sensitive)
-          )
-        end
-
-        klass = case exception
-                when Expect::WriteTimeout then WriteTimeout
-                when IOError, SystemCallError, Expect::SpawnError then TransportError
-                else InternalError
-                end
-        build_error(klass, "#{phase} failed: #{exception.class}", phase: phase, command: command, underlying: exception)
-      end
-
       # 敏感上下文的任意异常和设备输出可能只包含局部秘密，保留类型和错误码诊断。
       def safe_error_text(text, sensitive:)
         sensitive && !text.to_s.empty? ? "[REDACTED]".b : redactor.call(text)
       end
 
-      private :safe_error_text
-
       # 必须先脱敏再截取尾部，避免截断凭据后逃过完整词匹配。
       def truncate_output(text)
         text.byteslice(-MAX_ERROR_OUTPUT_BYTES, MAX_ERROR_OUTPUT_BYTES) || text
       end
 
-      private :truncate_output
-
-      # 返回不包含凭据的会话状态摘要。
-      def inspect = "#<#{self.class} state=#{state} host=#{configuration.host.inspect}>"
-
-      private
-
       # 建立传输并登录；失败时最多执行一次连接级恢复，然后重试登录。
       def connect_session
         attempted_recovery = false
         begin
           @state = :connecting
           started = Expect.monotonic
-          redactor.reset
-          @log.open(transport)
-          @log.log_event("connect", host: configuration.host, username: configuration.username,
-                         phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
-          transport.open
-          @state = :authenticating
-          @log.log_event("login_start", level: :debug, phase: :login)
-          response = @authentication.login
-          safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
-                                       prompt: response.prompt)
-          @prompt = response.prompt
-          @after_login.call(self, safe_response)
-          @log.log_authentication_output(response.raw)
-          @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
-          @log.attach
-          @state = :ready
+          login_once(started)
         rescue => error
           phase = (@state == :connecting) ? :connect : :login
           failure = normalize_error(error, phase: phase)
@@ -379,6 +348,26 @@ module Net
         end
       end
 
+      def login_once(started)
+        redactor.reset
+        @log.open(transport)
+        @log.log_event("connect", host: configuration.host, username: configuration.username,
+                       phase: :connect, protocol: transport.respond_to?(:protocol) ? transport.protocol : configuration.protocol)
+        transport.open
+        @state = :authenticating
+        @log.log_event("login_start", level: :debug, phase: :login)
+        response = @authentication.login
+        transport.authenticated if transport.respond_to?(:authenticated)
+        safe_response = Response.new(raw: redactor.call(response.raw), output: redactor.call(response.output),
+                                     prompt: response.prompt)
+        @prompt = response.prompt
+        @after_login.call(self, safe_response)
+        @log.log_authentication_output(response.raw)
+        @log.log_event("login_complete", status: "ok", prompt: response.prompt, phase: :login, duration_ms: elapsed_ms(started))
+        @log.attach
+        @state = :ready
+      end
+
       # 清除会话状态并关闭传输和日志资源。
       def close_resources
         @state = :closed

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

@@ -2,6 +2,7 @@
 
 require "open3"
 require "expect/pty"
+require_relative "known_hosts"
 
 module Net
   module Connector
@@ -125,6 +126,29 @@ module Net
           @legacy_arguments = legacy_arguments.dup.freeze
         end
 
+        def open
+          configuration.validate_endpoint!
+          unless configuration.host_key_policy == :strict
+            @known_hosts = KnownHosts.new(configuration, replace: @replace_host_key)
+          end
+          super
+        rescue Exception # rubocop:disable Lint/RescueException -- Release a staged trust file on failed startup.
+          close
+          raise
+        end
+
+        def authenticated
+          @known_hosts&.commit
+          @replace_host_key = false
+        end
+
+        def close
+          super
+        ensure
+          @known_hosts&.close
+          @known_hosts = nil
+        end
+
         # 返回 SSH 协议标识。
         def protocol = :ssh
 
@@ -133,9 +157,10 @@ module Net
           configuration.validate_endpoint!
           checking = (configuration.host_key_policy == :strict) ? "yes" : "accept-new"
           arguments = ["ssh", *legacy_arguments, "-tt", "-o", "StrictHostKeyChecking=#{checking}",
-                       "-o", "NumberOfPasswordPrompts=1",
+                       "-o", "NumberOfPasswordPrompts=1", "-o", "UpdateHostKeys=no",
                        "-o", "ConnectTimeout=#{[configuration.login_timeout.ceil, 1].max}"]
-          arguments += ["-o", "UserKnownHostsFile=#{configuration.known_hosts}"] if configuration.known_hosts
+          known_hosts = @known_hosts&.path || configuration.known_hosts
+          arguments += ["-o", "UserKnownHostsFile=#{known_hosts}"] if known_hosts
           arguments += ["-p", configuration.port.to_s] if configuration.port
           arguments + ["-l", configuration.username, configuration.host]
         end
@@ -151,13 +176,13 @@ module Net
           Telnet.new(configuration, channel_factory: @channel_factory, terminal_size: @terminal_size)
         end
 
-        # 从指定 known_hosts 文件中删除当前设备的旧主机密钥。
+        # 恢复只标记下一次会话副本；共享信任文件在认证成功后才更新。
         def replace_host_key
-          host = configuration.host
-          host = "[#{host}]:#{configuration.port}" if configuration.port && configuration.port != 22
-          _output, status = Open3.capture2e("ssh-keygen", "-f", configuration.known_hosts, "-R", host)
-          raise IOError, "removing device host key failed" unless status.success?
+          raise IOError, "host key replacement is not enabled" unless configuration.host_key_policy == :replace
+
+          @replace_host_key = true
         end
+
       end
 
       # Telnet 只能显式启用；SSH 专用端口不能带入回退连接。

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+module Net
+  module Connector
+    module Netdisco
+      # 人类批次入口：固定配置、预览、执行、保存报告，最后决定输出与退出码。
+      class BackupRun
+        def initialize(mode: :backup, argv: ARGV, env: ENV, input: $stdin, output: $stdout, error: $stderr)
+          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
+        end
+
+        def run
+          options = CLI::Options.parse(argv: @argv, input: @input, output: @output, error: @error)
+          return 0 if options[:help]
+
+          settings, success_policy, server_root, batch_directory = prepare(options)
+          client, credentials = Connection.build(settings, stdin_credentials: options[:stdin_credentials], input: @input)
+          progress = Progress.new(io: @error, enabled: @env.fetch("NC_PROGRESS", "1") != "0", verbose: options[:verbose])
+          resolver = ->(device) { credentials.call(device)&.merge(on_event: progress.method(:event)) }
+          fleet = Fleet.new(client: client, settings: settings, credentials: resolver, result_store: nil)
+          progress.reading_inventory
+          limit = settings.limit_per_vendor
+          plan = if @mode == :backup
+                   fleet.plan_backup(limit_per_vendor: limit)
+                 else
+                   fleet.plan_tftp_backup(limit_per_vendor: limit, allow_fixed_name_reuse: !server_root.nil?)
+                 end
+          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
+          return 1 if options[:stdin_credentials] && @input.gets&.strip != "RUN"
+
+          Storage::PrivateFile.write(File.join(batch_directory, "plan.json"), JSON.pretty_generate(preview))
+          report = execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
+          report = Report::Files.write(report, directory: batch_directory, plan: plan, concurrency: settings.concurrency)
+          finish(report, progress, options, batch_directory)
+        rescue ArgumentError, Client::Error => exception
+          @error.puts "备份参数或清单错误：#{exception.message}"
+          2
+        rescue StandardError => exception
+          @error.puts "备份未完成（#{exception.class}）"
+          2
+        end
+
+        private
+
+        def prepare(options)
+          settings = CLI::Options.settings(options, env: @env)
+          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
+          TftpVerification.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_LOG_DIRECTORY" => File.join(batch_directory, "logs"))
+          end
+          settings = settings.for_run(mode: @mode)
+          [settings, success_policy, server_root, batch_directory]
+        end
+
+        def execute(fleet, settings, plan, batch_directory, progress, success_policy, server_root)
+          File.open(File.join(batch_directory, "events.jsonl"), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |events|
+            options = { plan: plan, concurrency: settings.concurrency, success_policy: success_policy,
+                        on_start: progress.method(:start), on_result: result_callback(progress, events) }
+            progress.with_updates do
+              if @mode == :backup
+                fleet.backup_all(directory: batch_directory, filename_style: :hostname_ip, **options)
+              else
+                fleet.tftp_backup_all(server: settings.tftp_server, source_files: settings.tftp_source_files,
+                                      vrfs: settings.tftp_vrfs, report_directory: batch_directory,
+                                      verification_root: server_root, preserve_history: true, **options)
+              end
+            end
+          end
+        end
+
+        def result_callback(progress, events)
+          lock = Mutex.new
+          lambda do |outcome|
+            progress.result(outcome)
+            lock.synchronize do
+              events.puts JSON.generate(host: outcome.device.host, vendor: outcome.device.vendor,
+                                         status: outcome.status, error_code: outcome.diagnostic&.error_code,
+                                         error_type: outcome.diagnostic&.error_type, duration_ms: outcome.duration_ms)
+              events.flush
+            end
+          end
+        end
+
+        def finish(report, progress, options, batch_directory)
+          progress.finish(report)
+          progress.location(report.report_location) if report.report_location
+          @error.puts "文本报告：#{File.join(batch_directory, "summary.txt")}" if @env.fetch("NC_PROGRESS", "1") != "0" && File.file?(File.join(batch_directory, "summary.txt"))
+          if options[:json]
+            @output.puts JSON.generate(directory: batch_directory, counts: report.counts,
+                                       tasks_succeeded: report.policy_success?, success: report.policy_success?,
+                                       policy: report.policy, policy_success: report.policy_success?,
+                                       report_location: report.report_location, report_error: report.report_error)
+          end
+          report.policy_success? ? 0 : 1
+        end
+
+        def tftp_root(settings, options)
+          server = settings.tftp_server || (raise ArgumentError, "TFTP_HOST or YAML tftp.server is required")
+          return options[:tftp_root] || @env["TFTP_ROOT"] if options[:tftp_root] || @env["TFTP_ROOT"]
+          return unless Socket.ip_address_list.any? { |address| address.ip_address == server }
+
+          candidate = File.join(Dir.home, "Documents", "TFTP")
+          candidate if File.directory?(candidate)
+        end
+
+        def plan_summary(plan)
+          { total: plan.inventory.size, ready: plan.inventory.count(&:ready?),
+            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 }
+            end }
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,7 @@ module Net
       Batch = Data.define(:mode, :outcomes, :started_at, :finished_at, :callback_errors,
                           :report_location, :report_error) do
         # 按设备最终状态统计数量。
-        def counts = outcomes.group_by(&:status).transform_values(&:size)
+        def counts = outcomes.map(&:status).tally
 
         # 仅在所有设备成功且回调、报告均正常时判定整批成功。
         def success? = !outcomes.empty? && outcomes.all?(&:success?) && callback_errors.empty? && report_error.nil?

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Net
+  module Connector
+    module Netdisco
+      class CLI
+        # 可注入参数与输入输出的备份选项，不退出宿主进程。
+        class Options
+          def self.parse(argv: ARGV, input: $stdin, output: $stdout, error: $stderr, program: $PROGRAM_NAME)
+            values = { environment: {}, json: false, verbose: false, stdin_credentials: false }
+            parser = parser_for(values, output: output, program: program)
+            remaining = parser.parse!(argv.dup)
+            return values if values[:help]
+            raise OptionParser::InvalidArgument unless remaining.empty?
+            credentials = values[:environment].keys.any? { |key| key.match?(/USERNAME|PASSWORD/) }
+            if values[:stdin_credentials] && (credentials || values[:ask_password] || values[:ask_netdisco_password])
+              raise ArgumentError, "--stdin-credentials 不能与命令行凭据或密码提示同时使用"
+            end
+            read_password(values, :ask_password, "NC_DEVICE_PASSWORD", "设备密码", input: input, output: error)
+            read_password(values, :ask_netdisco_password, "NETDISCO_PASSWORD", "Netdisco 密码", input: input, output: error)
+
+            values
+          rescue OptionParser::ParseError
+            raise ArgumentError, "参数无效：并发数须为 1 至 50，抽样须为 1 至 5；使用 --help 查看参数", cause: nil
+          end
+
+          def self.parser_for(values, output:, program:)
+            OptionParser.new do |opts|
+              opts.banner = "用法：ruby #{File.basename(program)} [选项]（默认全量）"
+              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("--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 }
+            end
+          end
+
+          def self.add_execution(opts, values)
+            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
+            opts.on("--sample N", "--limit-per-vendor N", Integer, "每厂商抽样 1 至 5 台") do |count|
+              Planner.validate_limit!(count)
+              values[:limit] = count
+            end
+            opts.on("--tftp-root DIR", "本机 TFTP 服务器文件目录") { |path| values[:tftp_root] = path }
+            opts.on("--all", "选择全部就绪设备") { values[:all] = true }
+            opts.on("--success-policy POLICY", %w[strict selected verified], "成功判定：strict / selected / verified（TFTP 文件核验）") do |policy|
+              values[:success_policy] = policy.to_sym
+            end
+          end
+
+          def self.settings(options, env: ENV)
+            raise ArgumentError, "--all 不能与抽样同时使用" if options[:all] && options[:limit]
+
+            environment = environment(options, env: env)
+            path = environment["NC_CONFIG"]
+            defaults = path && !path.empty? ? ConfigFile.load(path) : {}
+            overrides = {}
+            { source: "NETDISCO_SOURCE", query: "NETDISCO_QUERY", query_params: "NETDISCO_QUERY_PARAMS",
+              max_script_output_bytes: "NC_MAX_SCRIPT_OUTPUT_BYTES", host: "NC_INCLUDE_HOSTS",
+              limit: "NC_SAMPLE_PER_VENDOR" }.each do |option, key|
+              overrides[key] = options[option].to_s if options.key?(option)
+            end
+            overrides["NC_SAMPLE_PER_VENDOR"] = nil if options[:all]
+            Settings.new(env: environment, defaults: defaults, overrides: overrides)
+          end
+
+          def self.add_settings(opts, values)
+            {
+              "--username USER" => ["NC_DEVICE_USERNAME", "设备登录用户名"],
+              "--password PASSWORD" => ["NC_DEVICE_PASSWORD", "设备登录密码（可改用 --ask-password）"],
+              "--enable-password PASSWORD" => ["NC_ENABLE_PASSWORD", "设备提权密码"],
+              "--netdisco-url URL" => ["NETDISCO_URL", "Netdisco 地址"],
+              "--netdisco-username USER" => ["NETDISCO_USERNAME", "Netdisco 用户名"],
+              "--netdisco-password PASSWORD" => ["NETDISCO_PASSWORD", "Netdisco 密码"],
+              "--directory DIR" => ["NC_BACKUP_DIRECTORY", "备份目录，相对项目根目录"],
+              "--config FILE" => ["NC_CONFIG", "YAML 配置，相对项目根目录"]
+            }.each do |flag, (key, description)|
+              opts.on(flag, description) do |value|
+                raise OptionParser::InvalidArgument if value.empty?
+
+                values[:environment][key] = value
+              end
+            end
+            opts.on("--host-key-policy POLICY", %w[strict accept_new replace], "主机密钥策略：strict / accept_new / replace（变化时自动替换）") do |policy|
+              values[:environment]["NC_HOST_KEY_POLICY"] = policy
+            end
+            opts.on("--known-hosts FILE", "持久保存主机密钥的文件") do |path|
+              values[:environment]["NC_KNOWN_HOSTS"] = path
+            end
+          end
+
+          def self.environment(options, env: ENV)
+            result = env.to_h.dup
+            overrides = options.fetch(:environment)
+            # 显式设备参数覆盖对应厂商默认值；未指定的字段继续按原凭据规则解析。
+            { "NC_DEVICE_USERNAME" => "USERNAME", "NC_DEVICE_PASSWORD" => "PASSWORD",
+              "NC_ENABLE_PASSWORD" => "ENABLE_PASSWORD" }.each do |key, suffix|
+              next unless overrides.key?(key)
+
+              result.delete_if do |name, _|
+                name.start_with?("NC_") && name.end_with?("_#{suffix}") &&
+                  (suffix != "PASSWORD" || !name.end_with?("_ENABLE_PASSWORD"))
+              end
+            end
+            if overrides.key?("NETDISCO_USERNAME") || overrides.key?("NETDISCO_PASSWORD")
+              result.delete("NETDISCO_API_KEY")
+            end
+            result.merge(overrides)
+          end
+
+          def self.read_password(values, flag, key, label, input:, output:)
+            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(&:gets)&.chomp
+            output.puts
+            raise ArgumentError, "密码不能为空" if password.nil? || password.empty?
+
+            values[:environment][key] = password
+          end
+          private_class_method :read_password, :parser_for
+        end
+      end
+    end
+  end
+end