vxlan 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2efb2207fd79cd9e4ef9724ebca3a5da93aa10db56719c1a0b6f4ac3562ba444
-  data.tar.gz: 73730c534034650b6bf44e917675dab25e445f5dcb1967263f3610a2324f3830
+  metadata.gz: 203d6c19eed76f37e033ba015e36a39953de0ba63dc5fd4130873a83f1e097c3
+  data.tar.gz: bb21ff1519721b7ee99cdedc5af2a3ac34c8542563c06ce9d3cd1328c31c4d6f
 SHA512:
-  metadata.gz: 869198020e0207f4896732548a88cf2c3b0abef61dd143c025636021b49b513b54848645a10b26a18624961386eaf524cd9f2588da7d7b7843812e549d8ad0ff
-  data.tar.gz: fcf9a413bd76e02fcae70f8af7f52e5de9ebd5ddf836bd86d3e45c4f404368bb3bdcdb1a5491346b1220ddc8f2a5d250fd418ec6bbcde8255c6a4576ff4b2a57
+  metadata.gz: aa2702cbc3fc196d77c7cb4ac24aca422f4e03eaf6ac4967d07b946e762ff774b9359d24deae4430ca9e7a8644992909e00b185c48d14b575d30bbeb037f381c
+  data.tar.gz: fea09bbf0ea945b4c33913f759aad4e4181bd4da4148593ade4e177a18939938ef7c0b327bbce9da0b3ac18e95d9bee9ebced5afd2014b4c35978bd9b80fb7c0

data/CHANGELOG.md

@@ -2,8 +2,25 @@
 
 Changes to the public contract are recorded here. Versions follow Semantic Versioning.
 
+## 0.4.0 (2026-10-22)
+
+- Delegate batch completion and cancellation/failure precedence to CtxRunner::Batch, keeping domain review and CLI presentation explicit.
+
+- Centralize inventory selection and CLI filters in Net::Connector::Inventory; add vendor/model inclusion, exclusion and matching modes.
+
+
+- Delegate shared collection, evidence and execution contracts to ctx_runner.
+- Preserve domain parsing, change policies, CLI layouts and connection ownership.
+
 ## Unreleased
 
+## 0.4.1 (2026-10-22)
+
+- Delegate command dispatch, common options, initialization, terminal interaction, offline IO and collection entrypoint orchestration to ctx_cli 0.1.0.
+- Keep domain policies, device capabilities and ctx_runner completion semantics in their existing layers.
+
+- Delegate batch completion and cancellation/failure precedence to CtxRunner::Batch, keeping domain review and CLI presentation explicit.
+
 ## 0.3.1 (2026-10-21)
 
 - Index Fabric address-group evidence by referenced object, preserving host order and missing dependencies without repeatedly searching every host's reference list.

data/bin/README.md

@@ -17,7 +17,7 @@ bundle exec ruby examples/offline.rb
 
 `bin/` 的公开内容是 `vxlan` 与本说明；现场 `vxlan.yml`、`.env`、`vxlans/` 由用户按需创建，不进入版本库或安装包。配置和凭据模板统一位于 `lib/vxlan/cli/templates/`，使用 `--init` 生成，不维护重复模板。
 
-离线解析和帮助不加载 net-connector。采集配置与联网入口可选依赖 `net-connector ~> 0.16.0`（已包含 `.env` 加载依赖 dotenv）。本仓库 Gemfile 的 `examples` 组已声明连接器，不进入 vxlan.gemspec 的运行依赖。只安装 vxlan gem 的宿主需要自行声明相应可选依赖。
+离线解析和帮助不加载 net-connector。采集配置与联网入口可选依赖 `net-connector ~> 0.17.1`（已包含 `.env` 加载依赖 dotenv）。本仓库 Gemfile 的 `examples` 组已声明连接器，不进入 vxlan.gemspec 的运行依赖。只安装 vxlan gem 的宿主需要自行声明相应可选依赖。
 
 ## 正式命令
 
@@ -25,7 +25,7 @@ bundle exec ruby examples/offline.rb
 
 ```sh
 gem install vxlan
-gem install net-connector -v '~> 0.16.0'
+gem install net-connector -v '~> 0.17.1'
 vxlan --help
 vxlan collect --init --non-interactive
 vxlan collect --inventory-only
@@ -201,3 +201,19 @@ Fabric 的 ACL 比较包含有序规则和引用地址组的成员。对象缺
 `fabric-policy.yml` 显式声明各 Fabric 的 `leaves`、`borders`、`spines`。Leaf 与 Border 按各自已部署的共同 VNI 比较；Spine 检查角色冲突。业务目录联合 VLAN/NVE/EVPN 识别不完整部署，总览显示覆盖范围、未纳入设备和缺证据成员。只有完整一致的对端与本机唯一业务接口相互印证、且全 Fabric 无跨 VNI 网段冲突时，才建议补齐已有 VLAN 的 VNI 关联；不会推导全量铺开 VLAN，也不按命名猜测角色。
 
 每次采集独立合并进程环境与指定 `.env`，不改写调用者环境；凭据、清单与参数使用同一份本次有效环境。Fabric 策略在连接前加载、校验并固定，采集中途修改策略文件只影响下一批。下发只接受带校验文件的 `plan.json` 与 `--item ID`，不接受旧版独立单项计划。
+
+## 统一设备筛选
+
+collect 的筛选与备份/拓扑共用 net-connector 的 Inventory::Selection。需要安装包含 `net/connector/inventory/filters` 的当前候选连接器；collect 帮助也从该组件读取参数定义，离线 parse/review 不加载它。
+
+```sh
+vxlan collect --hosts 192.0.2.0/24 --name edge --exclude-name spare --model 'S68*' --model-match glob --plan
+```
+
+IP 支持单地址、CIDR、范围；名称及型号支持 contains（默认）、prefix、glob，不区分大小写。`--vendor`/`--exclude-vendor` 使用连接器平台标识（如 cisco_nxos、h3c、h3c_wireless、huawei），不是原始厂商标签。同字段条件为 OR，跨字段为 AND，排除优先。缺失型号不命中包含规则。`--model`/`--exclude-model`、`--name-match`/`--model-match` 可组合；筛选只选择已有清单，不扫描地址、不扩大平台支持范围。
+
+YAML 顶层对应 hosts/exclude_hosts、names/exclude_names、vendors/exclude_vendors、models/exclude_models、name_match/model_match。Netdisco inventory 段使用 include_hosts/include_names/include_vendors/include_models 及对应 exclude 字段。
+
+## ctx_cli 公共入口
+
+分发、公共选项、配置初始化、离线输入输出、终端确认和采集入口由 ctx_cli 组合提供；领域规则与 ctx_runner 业务状态保持各自职责。`CTX_CLI_PATH=../ctx_cli bundle exec rake` 用于源码联调；普通入口先安装 ctx_cli 候选包。

data/lib/vxlan/change_plan.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
+require "ctx_runner/fingerprint"
 require "json"
 require "ipaddr"
 require "ctx_parser/immutable"
@@ -34,16 +34,10 @@ module Vxlan
     end
 
     # 字符串键规范化后计算语义指纹；Hash 顺序不影响结果，数组保留业务顺序。
-    def self.fingerprint(value) = Digest::SHA256.hexdigest(JSON.generate(canonical(value)))
-
-    # 规范化同时提供独立容器，用于屏蔽唯一允许变化的字段。
-    def self.canonical(value)
-      case value
-      when Hash then value.transform_keys(&:to_s).sort.to_h.transform_values { |entry| canonical(entry) }
-      when Array then value.map { |entry| canonical(entry) }
-      else value
-      end
-    end
+    def self.fingerprint(value) = CtxRunner::Fingerprint.call(value)
+
+    # 兼容既有领域入口，配置身份协议仅由 Runner 实现。
+    def self.canonical(value) = CtxRunner::Fingerprint.canonical(value)
 
     # 构造时一次校验和渲染，随后调用者不能改变已确认的参数或命令。
     def initialize(change)

data/lib/vxlan/cli/apply.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/terminal"
 require "json"
 require "digest"
+require "ctx_runner/execution"
 require "ipaddr"
 require "vxlan"
 require_relative "report"
@@ -45,7 +47,7 @@ module Vxlan
 
       # 没有 --yes 或自动回退；零退出码只确认配置回读，不声称业务已验收。
       def run(argv)
-        @store, @state, @started = nil, nil, false
+        @store, @execution = nil, nil
         options = { directory: File.join(Dir.pwd, "vxlan-executions"), port: 22 }
         parser = OptionParser.new do |p|
           p.banner = "用法：vxlan apply --plan FILE --item ID [--env-file FILE]（必须真实终端明确确认）"
@@ -58,7 +60,8 @@ module Vxlan
         end
         rest = parser.parse(argv.dup)
         return @out.puts(parser) || 0 if options[:help]
-        raise ArgumentError, "必须使用真实交互终端" unless @input.tty? && @out.tty? && @error.tty?
+        terminal = CtxCli::Terminal.new(input: @input, out: @out)
+        terminal.require_tty!(@error)
         raise ArgumentError, "需要单个计划" unless rest.empty? && options[:plan] && options[:port].between?(1, 65_535)
         body = File.read(options[:plan])
         hash = Digest::SHA256.hexdigest(body)
@@ -70,48 +73,21 @@ module Vxlan
         @out.puts Array(plan["prerequisites"]).map { |value| "条件：#{value}" }
         @out.puts "计划 SHA256：#{hash}\n拟执行命令：\n#{change.commands.join("\n")}\n条件回退（不自动执行）：\n#{change.rollback.join("\n")}"
         token = "APPLY #{host} #{hash[0, 12]} #{options[:item]}"
-        @out.print "确认业务策略及维护窗口后输入 #{token}；其他输入取消："
-        @out.flush
-        return @out.puts("已取消，未连接设备。") || 1 unless @input.gets&.strip == token
+        confirmed = terminal.confirm(token: token, prompt: "确认业务策略及维护窗口后输入 #{token}；其他输入取消：")
+        return @out.puts("已取消，未连接设备。") || 1 unless confirmed
         settings = credentials(options)
         @store = Report.new(options[:directory])
-        @state = { "status" => "confirmed", "device" => plan["device"], "plan_sha256" => hash, "plan_item" => options[:item], "expected_config_sha256" => plan["expected_config_sha256"], "commands" => plan["commands"], "steps" => [] }
-        @store.write_execution(@state)
-        session_opened, verified = false, false
-        with_session(plan["device"], settings) do |session|
-          raise IOError, "会话回调重复，禁止重放" if session_opened
-          session_opened = true
-          before = CtxParser::Immutable.copy(session.read_configuration)
-          unless ChangePlan.fingerprint(before) == plan["expected_config_sha256"] && change.eligible?(before)
-            raise ArgumentError, "配置已变化或增量前提不满足"
-          end
-          change.commands.each_with_index do |command, index|
-            @state["status"] = "executing"
-            @state["pending_command"] = index
-            @store.write_execution(@state)
-            @started = true
-            raise IOError, "设备命令未确认" unless session.write(command) == true
-            @state["steps"] << { "index" => index, "status" => "acknowledged" }
-            @state.delete("pending_command")
-            @store.write_execution(@state)
-          end
-          after = CtxParser::Immutable.copy(session.read_configuration)
-          raise IOError, "配置验收未通过" unless change.satisfied?(after, before: before)
-          @state["observed_config_sha256"] = ChangePlan.fingerprint(after)
-          verified = true
-        end
-        raise IOError, "会话未完成配置验证" unless verified
-        @state["status"] = "configuration_verified"
-        @store.write_execution(@state)
+        @execution = CtxRunner::Execution.new(plan: plan, change: change, journal: @store, plan_sha256: hash, item: options[:item])
+        @execution.run { |operation| with_session(plan["device"], settings, &operation) }
         @out.puts "配置回读已确认；仍需完成业务验收，未执行保存配置。日志：#{@store.directory}/execution.json"
         0
       rescue Interrupt
-        record_failure("interrupted")
-        @error.puts "操作中断；#{@started ? '设备效果可能不完整，请先回读核对，禁止重放。' : '尚未下发业务配置。'}"
+        report_journal_failure
+        @error.puts "操作中断；#{@execution&.started? ? '设备效果可能不完整，请先回读核对，禁止重放。' : '尚未下发业务配置。'}"
         130
       rescue StandardError, LoadError => error
-        record_failure(error.class.name)
-        @error.puts "下发停止（#{error.class.name}）；#{@started ? '效果未完整确认，先回读，不自动重放或回退。' : '未下发业务配置；检查终端、计划、凭据及当前配置是否仍匹配。'}"
+        report_journal_failure
+        @error.puts "下发停止（#{error.class.name}）；#{@execution&.started? ? '效果未完整确认，先回读，不自动重放或回退。' : '未下发业务配置；检查终端、计划、凭据及当前配置是否仍匹配。'}"
         2
       end
 
@@ -158,14 +134,12 @@ module Vxlan
         end
       end
 
-      # 失败记录尽力持久化；记录失败也不允许继续发送任何命令。
-      def record_failure(code)
-        return unless @store && @state
-        @state["status"] = @started ? "uncertain" : "failed"
-        @state["error"] = code
-        @store.write_execution(@state)
-      rescue StandardError, Interrupt
+      # 公共执行器保存失败状态；CLI 只呈现持久性尚未确认的诊断。
+      def report_journal_failure
+        return unless @execution&.journal_failed?
         @error.puts "执行日志收尾未确认；保留已有检查点，禁止据此重放配置。"
+      rescue StandardError, Interrupt
+        nil
       end
     end
   end

data/lib/vxlan/cli/collect.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "vxlan"
+require "ctx_runner/batch"
+require "ctx_cli/collection"
 require_relative "options"
 require_relative "report"
 require_relative "connector"
@@ -14,89 +16,33 @@ module Vxlan
         @env, @out, @error, @input = env, out, error, input
         @connector_factory, @executor = connector_factory, executor
         @defaults = options
-        @lock = Mutex.new
       end
 
-      # 先预检全部输入和凭据，再创建报告和连接；失败分类不打印原始异常正文。
+      # 公共入口编排顺序与失败收尾；以下方法是显式领域适配协议。
       def run(argv)
-        # 每次运行独立持有批次状态；预检失败不能改写上一次报告。
-        @options, @store, @progress, @devices, @results = nil, nil, nil, [], []
-        @options = Options.new(argv, env: @env, out: @out, **@defaults)
-        return 0 if @options.informational?
-        @options.validate_interaction!(input: @input, error: @error)
-        @options.load_environment
-        if @options.flags[:init]
-          @options.initialize_files
-          return 0
+        progress = ->(options) do
+          require "net/connector/collect/progress"
+          Net::Connector::Collect::Progress.new(io: @error, enabled: !options.flags[:quiet], verbose: options.flags[:verbose])
         end
-        return 0 if @options.missing?(input: @input, error: @error)
-        @options.load
-        require "net/connector/collect/progress"
-        @progress = Net::Connector::Collect::Progress.new(io: @error, enabled: !@options.flags[:quiet], verbose: @options.flags[:verbose])
-        @progress.notice("配置：#{@options.config}")
-        return output(@options.public_values.merge("sources" => @options.sources)) if @options.flags[:show_config]
-        @devices = devices = inventory
-        return output(devices) if @options.flags[:inventory_only]
-        if devices.empty?
-          @progress.notice("没有匹配设备，未建立连接")
-          @out.puts JSON.generate(status: :no_devices, total: 0) if @options.flags[:json]
-          return 1
-        end
-        credentials = credentials!
-        load_network unless @connector_factory && @executor
-        unless @connector_factory
-          devices.each { |device| Net::Connector::Configuration.new(host: device.fetch("host"), **credentials).validate_endpoint! }
-        end
-        unless @executor
-          require "net/connector/resources"
-          Net::Connector::Resources.prepare!(parallel: [ devices.size, @options.values.fetch("parallel") ].min)
-        end
-        @store = Report.new(@options.values.fetch("directory"), scripts: @options.flags[:scripts] == true)
-        @progress.plan(devices: devices, total: @inventory_total, parallel: @options.values.fetch("parallel"), label: "VXLAN 只读采集")
-        @progress.with_updates do
-          execute(devices) { |device| collect(device, credentials) }
-        end
-        @store.review_collected_fabric(@options.fabric_policy)
-        summary = finish
-        return 2 unless summary
-        summary[:status] == :complete ? 0 : 1
-      rescue Interrupt
-        finish(interrupted: true) if @store
-        diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
-        130
-      rescue SystemCallError, IOError => error
-        finish(report_error: error) if @store
-        diagnostic "VXLAN 参数或报告错误：#{report_diagnostic(error)}"
-        2
-      rescue OptionParser::ParseError, ArgumentError, LoadError => error
-        if @store
-          finish(execution_error: error)
-          diagnostic "VXLAN 执行失败：#{error.class.name}；已采集结果见批次报告"
-        else
-          diagnostic "VXLAN 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
-        end
-        2
-      rescue StandardError => error
-        finish(execution_error: error) if @store
-        diagnostic "VXLAN 清单或执行失败：#{CtxDriver::Failure.code(error, :collection_failed)}（#{error.class.name}）"
-        2
+        CtxCli::Collection.new(adapter: self, options: ->(arguments) { Options.new(arguments, env: @env, out: @out, **@defaults) },
+          progress: progress, batch: CtxRunner::Batch, label: "VXLAN", report_error: Report::Error,
+          failure_code: ->(error) { CtxDriver::Failure.code(error, :collection_failed) },
+          out: @out, error: @error, input: @input).run(argv)
       end
 
-      private
-
       # 只在需要库存或网络执行时加载可选依赖，帮助和静态预览保持独立。
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "联网采集需要 net-connector >= 0.16.0；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
+        raise LoadError, "联网采集需要 net-connector >= 0.17.1；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
       end
 
       # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
-      def inventory
-        values = @options.values
-        rows = if @options.dynamic_inventory?
-          @progress.reading_inventory
-          settings = @options.netdisco_settings
+      def inventory(options, progress:)
+        values = options.values
+        rows = if options.dynamic_inventory?
+          progress.reading_inventory
+          settings = options.netdisco_settings
           Net::Connector::Netdisco::Fleet.new(settings: settings).devices.filter_map do |device|
             next unless device.ready? && device.vendor == :cisco_nxos
             { "host" => device.host, "name" => device.name || device.host, "model" => device.model }
@@ -104,107 +50,63 @@ module Vxlan
         else
           values.fetch("devices")
         end
-        targets = @options.normalize_devices(rows)
-        @inventory_total = targets.size
-        includes = values.fetch("hosts").map { |v| IPAddr.new(v) }
-        excludes = values.fetch("exclude_hosts").map { |v| IPAddr.new(v) }
-        targets.select do |device|
-          host, name = device.values_at("host", "name")
-          (includes.empty? || includes.any? { |network| network.include?(host) }) &&
-            excludes.none? { |network| network.include?(host) } &&
-            (values.fetch("names").empty? || values.fetch("names").any? { |v| name.downcase.include?(v.downcase) }) &&
-            values.fetch("exclude_names").none? { |v| name.downcase.include?(v.downcase) }
+        targets = options.normalize_devices(rows)
+        total = targets.size
+        selection = Net::Connector::Inventory::Filters.selection(values)
+        selected = targets.select do |device|
+          selection.selected?(device.fetch("host"), "cisco_nxos", name: device["name"], model: device["model"])
         end
+        [ selected, total ]
       end
 
+      # 所有设备先完成凭据、端点与资源预检，再允许创建报告和连接。
+      def prepare(devices, options)
+        credentials = credentials!(options)
+        load_network unless @connector_factory && @executor
+        unless @connector_factory
+          devices.each { |device| Net::Connector::Configuration.new(host: device.fetch("host"), **credentials).validate_endpoint! }
+        end
+        unless @executor
+          require "net/connector/resources"
+          Net::Connector::Resources.prepare!(parallel: [ devices.size, options.values.fetch("parallel") ].min)
+        end
+        credentials
+      end
+
+      def report(options) = Report.new(options.values.fetch("directory"), scripts: options.flags[:scripts] == true)
+      def after_collect(report, options) = report.review_collected_fabric(options.fabric_policy)
+
       # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
-      def credentials!
-        username = secret("NC_CISCO_NXOS_USERNAME") || secret("NC_DEVICE_USERNAME")
+      def credentials!(options)
+        username = secret(options, "NC_CISCO_NXOS_USERNAME") || secret(options, "NC_DEVICE_USERNAME")
         raise ArgumentError, "请设置 NC_DEVICE_USERNAME 或 NC_CISCO_NXOS_USERNAME；密码可通过环境或 SSH key/agent 提供" unless username
-        @options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
-          password: secret("NC_CISCO_NXOS_PASSWORD") || secret("NC_DEVICE_PASSWORD"), enable_password: secret("NC_ENABLE_PASSWORD"))
+        options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
+          password: secret(options, "NC_CISCO_NXOS_PASSWORD") || secret(options, "NC_DEVICE_PASSWORD"), enable_password: secret(options, "NC_ENABLE_PASSWORD"))
       end
 
       # 空白环境值视为缺失，不修改或回显凭据。
-      def secret(name)
-        value = @options.environment[name]
+      def secret(options, name)
+        value = options.environment[name]
         value unless value.nil? || value.strip.empty?
       end
 
       # 每个任务使用独立 Collector 和会话；公共执行器负责有界并发和线程回收。
-      def execute(devices, &block)
-        parallel = @options.values.fetch("parallel")
+      def execute(devices, options, &block)
+        parallel = options.values.fetch("parallel")
         return @executor.call(devices, parallel, &block) if @executor
         Net::Connector::Parallel::Pool.new(parallel: parallel).map(devices, &block)
       end
 
       # 单台失败保留其他设备和已获得维度；报告持久化失败交由批次终止处理。
-      def collect(device, credentials)
-        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        snapshot = nil
-        @progress.start(device)
-        credentials = credentials.merge(on_event: @progress.method(:event))
-        begin
-          connector = @connector_factory ? @connector_factory.call(device, credentials) : Connector.new(device, credentials)
-          snapshot = Vxlan::Collector.new.collect(connector: connector, target: device, fabric_key: @options.values.fetch("fabric"),
-            model: device["model"], dimensions: @options.values.fetch("dimensions").map(&:to_sym))
-          dimensions = snapshot.dimensions.transform_values { |v| { status: v.status, records: v.records.size, issues: v.issues.map { |issue| issue[:code] }.uniq } }
-          status = snapshot.dimensions.fetch(:collection).status
-          result = { device: device, status: status, dimensions: dimensions }
-        rescue StandardError => error
-          result = { device: device, status: :failed, error: CtxDriver::Failure.code(error, :collection_failed), dimensions: {} }
-        end
-        result[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
-        result[:report_saved] = false
-        @lock.synchronize { @results << result }
-        @store.write(result, snapshot: snapshot)
-        @lock.synchronize { result[:report_saved] = true }
-        @progress.result(result)
-        result
-      end
-
-      # 调度器已回收线程；摘要失败只交付安全诊断，不覆盖先前的取消事实。
-      def finish(interrupted: false, report_error: nil, execution_error: nil)
-        results = @results.sort_by { |result| result[:device]["host"] }
-        options = { interrupted: interrupted, requested: @devices,
-          report_error: report_error && report_diagnostic(report_error), execution_error: execution_error&.class&.name }
-        summary = @store.finish(results, **options, output_error: @progress.output_error)
-        @progress.finish(summary)
-        # 末尾提示也可能首次失败；只补写输出诊断，不重复设备任务。
-        if @progress.output_error && !summary[:output_error]
-          summary = @store.finish(results, **options, output_error: @progress.output_error)
-        end
-        @out.puts JSON.pretty_generate(summary) if @options.flags[:json]
-        summary
-      rescue SystemCallError, IOError => error
-        diagnostic "VXLAN 摘要报告错误：#{report_diagnostic(error)}"
-        diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。" if @store.recovery_failed?
-        nil
-      end
-
-      # 错误提示失败不能覆盖取消或执行退出码；已失效的进度流不再重试。
-      def diagnostic(message)
-        return if @progress&.output_error
-        @error.puts(message)
-      rescue StandardError
-        nil
-      end
-
-      # 自有发布错误消息不含正文；外部文件异常只显示类型，不打印 message/cause。
-      def report_diagnostic(error)
-        error.instance_of?(Report::Error) ? error.message : error.class.name
+      def collect(device, options, context:, progress:)
+        credentials = context.merge(on_event: progress.method(:event))
+        connector = @connector_factory ? @connector_factory.call(device, credentials) : Connector.new(device, credentials)
+        snapshot = Vxlan::Collector.new.collect(connector: connector, target: device, fabric_key: options.values.fetch("fabric"),
+          model: device["model"], dimensions: options.values.fetch("dimensions").map(&:to_sym))
+        snapshot
       end
 
-      # 预览默认显示逐设备身份；公开配置由显式开关展示。
-      def output(value)
-        if @options.flags[:json] || value.is_a?(Hash)
-          @out.puts JSON.pretty_generate(value)
-        else
-          value.each { |device| @out.puts "#{device.fetch('host')}\t#{device.fetch('name')}\t#{device['model']}" }
-          @out.puts "设备：#{value.size} 台；未建立设备连接"
-        end
-        value.is_a?(Array) && value.empty? ? 1 : 0
-      end
+      private :load_network, :credentials!, :secret
     end
   end
 end

data/lib/vxlan/cli/options.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/options"
+require "ctx_cli/terminal"
+require "ctx_cli/initialization"
+require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
-require "fileutils"
-require "tempfile"
 
 module Vxlan
   module CLI
     # 采集入口的公开参数；凭据始终留在环境中，不传入解析库或 YAML。
     class Options
-      FIELDS = %w[fabric fabric_policy devices netdisco inventory netdisco_config parallel directory dimensions ssh hosts exclude_hosts names exclude_names].freeze
+      FIELDS = (%w[fabric fabric_policy devices netdisco inventory netdisco_config parallel directory dimensions ssh] + Net::Connector::Inventory::Filters::FIELDS).freeze
       SSH_FIELDS = %w[port command_timeout login_timeout host_key_policy known_hosts].freeze
       SSH_DEFAULTS = { "host_key_policy" => "strict", "command_timeout" => 60, "login_timeout" => 15 }.freeze
       attr_reader :values, :config, :env_file, :flags, :fabric_policy, :environment
@@ -46,7 +48,7 @@ module Vxlan
 
       # 自动化拒绝强制问答；帮助分支无需检查终端或消费输入。
       def validate_interaction!(input:, error:)
-        if flags[:interactive] && !(input.tty? && error.tty?)
+        if flags[:interactive] && !CtxCli::Terminal.tty?(input, error)
           raise ArgumentError, "--interactive 需要交互终端；自动化请使用 --init --non-interactive"
         end
       end
@@ -62,7 +64,7 @@ module Vxlan
         @environment = @files.environment
         @config, @env_file = @files.config, @files.env_file
       rescue LoadError
-        raise LoadError, "采集配置需要 net-connector >= 0.16.0；读取 .env 还需要 dotenv", cause: nil
+        raise LoadError, "采集配置需要 net-connector >= 0.17.1；读取 .env 还需要 dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
@@ -149,22 +151,11 @@ module Vxlan
         end
         overrides_parallel = @overrides.key?("parallel") || parallel_source&.fetch("VXLAN_PARALLEL", nil)
         document = overrides_parallel ? values : values.reject { |key, _| key == "parallel" }
-        template = template.lines.select { |line| line.start_with?("#") }.join +
+        template = template.lines("\n").select { |line| line.start_with?("#") }.join("") +
           Net::Connector::Config.dump(document, name: "vxlan", path: config)
         { config => template, env_file => File.read(File.join(__dir__, "templates/env.example")) }.each do |path, body|
-          FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-          begin
-            Tempfile.create([ ".vxlan-init-", ".tmp" ], File.dirname(path)) do |file|
-              file.chmod(0o600)
-              file.write(body)
-              file.flush
-              file.fsync
-              File.link(file.path, path)
-            end
-            @out.puts "已创建：#{path}"
-          rescue Errno::EEXIST
-            @out.puts "已保留：#{path}"
-          end
+          status = CtxCli::Initialization.new(prefix: ".vxlan-init-").create(path: path, contents: body)
+          @out.puts "#{status == :created ? '已创建' : '已保留'}：#{path}"
         end
         @out.puts "请检查配置及凭据后再次运行；本次未读取清单、未连接设备。"
       end
@@ -174,10 +165,10 @@ module Vxlan
         @files.load
         @config, @env_file = @files.config, @files.env_file
         return false unless @files.missing?
-        if input.tty? && error.tty? && flags[:interactive] != false
-          error.print "配置不存在：#{config}；是否创建配置与环境模板？[y/N] "
-          error.flush
-          if input.gets&.strip&.match?(/\Ay(?:es)?\z/i)
+        terminal = CtxCli::Terminal.new(input: input, out: error)
+        if terminal.tty? && flags[:interactive] != false
+          answer = terminal.question("配置不存在：#{config}；是否创建配置与环境模板？[y/N] ")
+          if answer&.match?(/\Ay(?:es)?\z/i)
             initialize_files
             return true
           end
@@ -231,40 +222,37 @@ module Vxlan
       def parser
         OptionParser.new do |p|
           p.banner = "用法：#{@command} [选项]（只读 VXLAN 采集）"
-          p.on("--config FILE", "最高优先级 YAML，叠加系统/用户/脚本/工作目录配置") { |v| @explicit_config = File.expand_path(v) }
-          p.on("--env-file FILE", "最高优先级环境文件；进程环境仍优先") { |v| @explicit_env_file = File.expand_path(v) }
-          p.on("-p", "--parallel N", Integer, "设备并发 1～500；继承 NC_PARALLEL，未配置时 4") { |v| @overrides["parallel"] = v }
-          p.on("--directory DIR", "按设备保存报告的目录") { |v| @overrides["directory"] = File.expand_path(v) }
+          CtxCli::Options.configuration(p, parallel_help: "设备并发 1～500；继承 NC_PARALLEL，未配置时 4") do |key, value|
+            case key
+            when :config then @explicit_config = File.expand_path(value, Dir.pwd)
+            when :env_file then @explicit_env_file = File.expand_path(value, Dir.pwd)
+            when :directory then @overrides["directory"] = File.expand_path(value, Dir.pwd)
+            when :parallel then @overrides["parallel"] = value
+            end
+          end
           p.on("--fabric-policy FILE", "显式 Fabric/Leaf/Border/Spine 清单 YAML") { |v| @overrides["fabric_policy"] = File.expand_path(v) }
           p.on("--fabric NAME", "采集所属 Fabric 身份") { |v| @overrides["fabric"] = v }
           p.on("--dimensions LIST", "逗号分隔维度；--help 查看支持项") { |v| @overrides["dimensions"] = list(v) }
-          { "--host IP" => "hosts", "--hosts LIST" => "hosts", "--exclude-hosts LIST" => "exclude_hosts",
-            "--name LIST" => "names", "--exclude-name LIST" => "exclude_names" }.each do |option, key|
-            p.on(option, "筛选已有清单，同类条件取并集，排除优先") { |v| (@overrides[key] ||= []).concat(list(v)) }
+          Net::Connector::Inventory::Filters.add_options(p) do |key, value|
+            if value.is_a?(Array)
+              (@overrides[key] ||= []).concat(value)
+            else
+              @overrides[key] = value
+            end
           end
-          p.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { flags[:init] = true }
-          p.on("--interactive", "缺少配置时询问是否创建；要求真实终端") { flags[:interactive] = true }
-          p.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { flags[:interactive] = false }
+          CtxCli::Options.initialization(p, flags)
           p.on("--plan", "--inventory-only", "预览筛选清单，不连接设备") { flags[:inventory_only] = true }
           p.on("--show-config", "查看公开有效配置") { flags[:show_config] = true }
-          p.on("--json", "stdout 输出 JSON；默认显示可读摘要") { flags[:json] = true }
-          p.on("--quiet", "--no-progress", "关闭 stderr 进度，可配合 --json") { flags[:quiet] = true }
+          CtxCli::Options.output(p, flags)
           p.on("--[no-]scripts", "可选导出配置建议，默认仅诊断") { |value| flags[:scripts] = value }
-          p.on("--verbose", "显示逐台结果及安全命令事件") { flags[:verbose] = true }
-          p.on("-h", "--help", "查看选项帮助") { flags[:help] = true }
-          p.on("--help-all", "查看全部选项、路径与环境约定") { flags[:help_all] = true }
-          p.on("--examples", "查看常用命令范例，不执行任务") { flags[:examples] = true }
+          CtxCli::Options.information(p, flags)
           p.separator "维度：#{Vxlan::Collector::COMMANDS.keys.join(', ')}"
           p.separator "优先级：CLI > 进程环境 > YAML > .env > 内置默认值。退出码：0 完整/预览；1 未完成/无目标；2 参数/持久化错误；130 取消。"
         end
       end
 
       # 列表中的空项属于输入错误，不能被静默删掉。
-      def list(value)
-        values = value.split(",", -1).map(&:strip)
-        raise ArgumentError, "列表不能有空项" if values.any?(&:empty?)
-        values
-      end
+      def list(value) = CtxCli::Options.list(value)
 
       # 先验证整批策略，避免在前面设备连接后才发现后面的非法配置。
       def validate!
@@ -286,11 +274,8 @@ module Vxlan
           raise ArgumentError, "netdisco_config 须为配置路径，且不能同时声明 devices" unless values["netdisco_config"].is_a?(String) && !values["netdisco_config"].empty? && values["devices"].empty?
           values["netdisco_config"] = File.expand_path(values["netdisco_config"], Dir.pwd)
         end
-        %w[hosts exclude_hosts names exclude_names].each do |key|
-          items = values[key] = values.fetch(key, [])
-          raise ArgumentError, "#{key} 须为非空字符串数组" unless items.is_a?(Array) && items.all? { |v| v.is_a?(String) && !v.strip.empty? }
-        end
-        %w[hosts exclude_hosts].each { |key| values[key].each { |v| IPAddr.new(v) } }
+        Net::Connector::Inventory::Filters::LISTS.each_key { |key| values[key] = values.fetch(key, []) }
+        Net::Connector::Inventory::Filters.selection(values)
         ssh = values["ssh"]
         raise ArgumentError, "ssh 包含未知或敏感字段" unless ssh.is_a?(Hash) && (ssh.keys - SSH_FIELDS).empty?
         ssh = SSH_DEFAULTS.merge(ssh)