vxlan 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2efb2207fd79cd9e4ef9724ebca3a5da93aa10db56719c1a0b6f4ac3562ba444
-  data.tar.gz: 73730c534034650b6bf44e917675dab25e445f5dcb1967263f3610a2324f3830
+  metadata.gz: 1b045bbd7eb98d8771aac733587cf171bdf5c8c0da0f7ce3a4226317454da139
+  data.tar.gz: 06d4bddb07fa64f80ca0b2cb283c02321ad0bf54f56c94ec9c1538ebe052b447
 SHA512:
-  metadata.gz: 869198020e0207f4896732548a88cf2c3b0abef61dd143c025636021b49b513b54848645a10b26a18624961386eaf524cd9f2588da7d7b7843812e549d8ad0ff
-  data.tar.gz: fcf9a413bd76e02fcae70f8af7f52e5de9ebd5ddf836bd86d3e45c4f404368bb3bdcdb1a5491346b1220ddc8f2a5d250fd418ec6bbcde8255c6a4576ff4b2a57
+  metadata.gz: 6b5636dc50b48a4f0eed0c5c6b8babb2d650eae98f8a6ee78b1969b940327ba44e8f5b5bb16e12dd7b706cc0044756568aefae2fb9523e3034e72adbf132c2bc
+  data.tar.gz: 73d115544a200fab0ae647981720af491b05dca15f17b3f7a8ed021559221b101012842b2c7856dca0fa28edc7d9a4d2bb1d06ba439f78595b45aec3c5965c60

data/CHANGELOG.md

@@ -2,8 +2,20 @@
 
 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
 
+- 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

@@ -201,3 +201,15 @@ 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 字段。

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

@@ -3,6 +3,7 @@
 require "optparse"
 require "json"
 require "digest"
+require "ctx_runner/execution"
 require "ipaddr"
 require "vxlan"
 require_relative "report"
@@ -45,7 +46,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]（必须真实终端明确确认）"
@@ -75,43 +76,17 @@ module Vxlan
         return @out.puts("已取消，未连接设备。") || 1 unless @input.gets&.strip == token
         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 +133,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,7 @@
 # frozen_string_literal: true
 
 require "vxlan"
+require "ctx_runner/batch"
 require_relative "options"
 require_relative "report"
 require_relative "connector"
@@ -14,13 +15,12 @@ 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, @store, @progress, @devices, @batch = nil, nil, nil, [], nil
         @options = Options.new(argv, env: @env, out: @out, **@defaults)
         return 0 if @options.informational?
         @options.validate_interaction!(input: @input, error: @error)
@@ -52,32 +52,25 @@ module Vxlan
           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) }
+        @batch = CtxRunner::Batch.new(report: @store, progress: @progress, requested: devices)
+        outcome = @batch.run(present: ->(summary) { @out.puts JSON.pretty_generate(summary) if @options.flags[:json] }) do
+          @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)
         end
-        @store.review_collected_fabric(@options.fabric_policy)
-        summary = finish
-        return 2 unless summary
-        summary[:status] == :complete ? 0 : 1
+        completion(outcome)
       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
+        diagnostic "VXLAN 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
         2
       rescue StandardError => error
-        finish(execution_error: error) if @store
         diagnostic "VXLAN 清单或执行失败：#{CtxDriver::Failure.code(error, :collection_failed)}（#{error.class.name}）"
         2
       end
@@ -88,7 +81,7 @@ module Vxlan
       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.0；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
       end
 
       # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
@@ -106,14 +99,9 @@ module Vxlan
         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) }
+        selection = Net::Connector::Inventory::Filters.selection(values)
         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) }
+          selection.selected?(device.fetch("host"), "cisco_nxos", name: device["name"], model: device["model"])
         end
       end
 
@@ -140,46 +128,33 @@ module Vxlan
 
       # 单台失败保留其他设备和已获得维度；报告持久化失败交由批次终止处理。
       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
+        @batch.collect(device) do
           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: {} }
+          snapshot
         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)
+      # Runner 决定批次结论；CLI 仅呈现安全诊断并映射退出码。
+      def completion(outcome)
+        if outcome.finalization_error
+          diagnostic "VXLAN 摘要报告错误：#{outcome.finalization_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
+        if outcome.recovery_failed
+          diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。"
+        end
+        if outcome.status == :interrupted
+          diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
+        elsif (failure = outcome.failure)
+          if failure[:kind] == :report
+            diagnostic "VXLAN 参数或报告错误：#{failure[:detail]}"
+          else
+            diagnostic "VXLAN 清单或执行失败：#{failure[:error_type]}；已采集结果见批次报告"
+          end
+        end
+        { complete: 0, incomplete: 1, failed: 2, interrupted: 130 }.fetch(outcome.status)
       end
 
       # 错误提示失败不能覆盖取消或执行退出码；已失效的进度流不再重试。

data/lib/vxlan/cli/options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
 require "fileutils"
@@ -10,7 +11,7 @@ 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
@@ -62,7 +63,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.0；读取 .env 还需要 dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
@@ -238,9 +239,12 @@ module Vxlan
           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 }
@@ -286,11 +290,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)

data/lib/vxlan/cli/report.rb

@@ -2,8 +2,7 @@
 
 require "json"
 require "time"
-require "tempfile"
-require "fileutils"
+require "ctx_runner/report"
 require_relative "review/report"
 require_relative "review/fabric"
 
@@ -14,46 +13,21 @@ module Vxlan
       include Review::Report
       include Review::Fabric
 
-      attr_reader :directory
+      # 私有证据发布由公共业务对象管理；本类只组织领域报告。
+      class Error < CtxRunner::Report::Error; end
 
-      # 采集和离线审查共用稳定名称，保留 IPv6 地址并避免设备名成为路径。
-      def self.device_basename(device)
-        "#{device.fetch('name').gsub(/[^A-Za-z0-9_.-]/, '_')[0, 100]}-#{device.fetch('host').gsub(/[^A-Za-z0-9_.-]/, '_')}"
+      def initialize(root, scripts: false)
+        @scripts = scripts
+        @report = CtxRunner::Report.new(root, error_class: Error)
       end
 
-      # 仅交付发布阶段，不保留底层异常正文或敏感报告内容。
-      class Error < IOError
-        attr_reader :relative, :phase
+      def directory = @report.directory
+      def recovery_failed? = @report.recovery_failed?
+      def write_execution(state) = @report.write_execution(state)
 
-        # 保留安全的发布阶段与提交状态，不携带底层异常正文。
-        def initialize(relative:, phase:, committed:)
-          @relative, @phase, @committed = relative.freeze, phase, committed
-          super("报告写入失败：#{relative}；阶段 #{phase}；#{committed ? '已替换，收尾未确认' : '尚未替换'}")
-        end
-
-        # 区分原子替换已完成与目录同步尚未确认。
-        def committed? = @committed
-      end
-
-      # 批次目录排他创建，重复时间戳不会覆盖上一批次。
-      def initialize(root, scripts: false)
-        @scripts = scripts
-        root = File.expand_path(root)
-        prepare_directory(root)
-        stat = File.lstat(root)
-        unless stat.directory? && (stat.mode & 0o077).zero?
-          raise ArgumentError, "报告根目录须为真实私有目录，权限0700；请设置独立目录并检查 chmod 0700"
-        end
-        stem = Time.now.utc.strftime("%Y-%m-%d_%H-%M-%S")
-        sequence = 0
-        begin
-          @directory = File.join(root, sequence.zero? ? stem : "#{stem}_#{sequence}")
-          Dir.mkdir(directory, 0o700)
-        rescue Errno::EEXIST
-          sequence += 1
-          retry
-        end
-        sync_directory(root)
+      # 采集和离线审查共用稳定名称，保留 IPv6 地址并避免设备名成为路径。
+      def self.device_basename(device)
+        "#{device.fetch('name').gsub(/[^A-Za-z0-9_.-]/, '_')[0, 100]}-#{device.fetch('host').gsub(/[^A-Za-z0-9_.-]/, '_')}"
       end
 
       # 每台完成后立即原子保存，即使批次随后取消仍可读取已完成证据。
@@ -73,151 +47,33 @@ module Vxlan
 
       # 摘要不嵌入配置事实，只汇总状态与诊断，供终端和自动化共用。
       def finish(results, interrupted: false, requested: [], report_error: nil, execution_error: nil, output_error: nil)
-        @recovery_failed = false
-        # 按地址索引一次，避免大批次逐个扫描所有已完成结果。
-        completed_hosts = results.to_h { |result| [ result.fetch(:device).fetch("host"), true ] }
-        pending = requested.reject { |device| completed_hosts.key?(device.fetch("host")) }
-        complete = !report_error && !execution_error && !output_error && pending.empty? && results.any? && results.all? { |r| r[:status] == :complete && r[:report_saved] != false }
-        summary = { status: interrupted ? :interrupted : (complete ? :complete : :incomplete),
-          total: [ requested.size, results.size ].max, completed: results.size, pending: pending, counts: results.map { |r| r[:status] }.tally, devices: results,
-          directory: directory, evidence_only: true }
-        summary[:review] = @review_summary if @review_summary
-        summary[:report_error] = report_error if report_error
-        summary[:execution_error] = execution_error if execution_error
-        summary[:output_error] = output_error if output_error
-        # 先保存未完成检查点；文本发布或最终提交失败都不能留下成功摘要。
-        checkpoint = summary.merge(status: interrupted ? :interrupted : :incomplete,
-          report_error: report_error || :report_finalization_unconfirmed)
-        checkpoint_body = JSON.pretty_generate(serializable(checkpoint)) + "\n"
-        begin
-          publish("summary.json", checkpoint_body)
-        rescue Error, Interrupt
-          invalidate_completed_summary
-          raise
-        end
-        text = [ "VXLAN 证据：#{summary.fetch(:status)}；完成 #{results.size} 台", "分类：#{summary.fetch(:counts)}", "证据完整性不代表 Fabric 健康。" ]
-        text << "逐设备诊断：devices/；候选脚本：scripts/；所有候选配置未执行。"
-        text << @review_text if @review_text
-        text << "批次报告状态：参见 summary.json；文本中的证据状态不确认报告发布完成。"
-        text << "报告错误：#{report_error}" if report_error
-        text << "执行错误：#{execution_error}" if execution_error
-        text << "进度输出错误：#{output_error[:error_type]}；设备结果已保留" if output_error
-        results.each do |r|
-          saved = r[:report_saved] == true ? "已保存" : "保存未确认"
-          text << "#{r[:device]['host']}\t#{r[:device]['name']}\t#{r[:status]}\t#{saved}\t#{r[:error]}"
-        end
-        pending.each { |device| text << "#{device['host']}\t#{device['name']}\t未采集" }
-        publish("summary.txt", text.join("\n") + "\n")
-        begin
-          publish("summary.json", JSON.pretty_generate(serializable(summary)) + "\n")
-        rescue Error => error
-          # 未替换时原检查点仍安全，不做可能破坏它的多余恢复写入。
-          restore_checkpoint(checkpoint_body) if error.committed?
-          raise
-        rescue Interrupt
-          checkpoint[:status] = :interrupted
-          restore_checkpoint(JSON.pretty_generate(serializable(checkpoint)) + "\n")
-          raise
-        end
-        summary
-      end
-
-      # 每次发送配置前后发布检查点；失败由执行器停止后续写入。
-      def write_execution(state)
-        publish("execution.json", JSON.pretty_generate(state) + "\n")
-      end
-
-      # 恢复写入或删除受阻时，调用方须把退出码及此状态作为未确认诊断。
-      def recovery_failed? = @recovery_failed == true
-
-      private
-
-      # 新建目录的名字属于父目录；文件 fsync 不能替代这条持久化链。
-      def prepare_directory(path)
-        missing, parent = [], path
-        until File.directory?(parent)
-          missing << parent
-          parent = File.dirname(parent)
-        end
-        FileUtils.mkdir_p(path, mode: 0o700)
-        missing.reverse_each do |created|
-          parent = File.dirname(created)
-          sync_directory(File.symlink?(parent) ? File.realpath(parent) : parent)
-        end
-      end
-
-      # 批次创建与文件发布共享目录同步边界，失败直接交还宿主停止执行。
-      def sync_directory(path)
-        File.open(path, File::RDONLY | File::NOFOLLOW) { |parent| parent.fsync }
-      end
-
-      # 新一次收尾失败时，旧成功摘要不再代表当前状态；安全检查点继续保留。
-      def invalidate_completed_summary
-        Thread.handle_interrupt(Exception => :never) do
-          saved = JSON.parse(File.read(File.join(directory, "summary.json")))
-          discard_summary if saved["status"] == "complete"
-        end
-      rescue Errno::ENOENT
-        nil
-      rescue SystemCallError, JSON::ParserError, Interrupt
-        @recovery_failed = true
-      end
-
-      # 屏蔽恢复中的次级取消，始终把最先观察到的发布失败或取消交还调用方。
-      def restore_checkpoint(body, relative: "summary.json")
-        Thread.handle_interrupt(Exception => :never) do
-          begin
-            publish(relative, body)
-          rescue Error, Interrupt => error
-            @recovery_failed = true
-            discard_summary(relative: relative) unless error.is_a?(Error) && error.committed?
+        @report.finish(results, interrupted: interrupted, requested: requested, report_error: report_error,
+          execution_error: execution_error, output_error: output_error, review: @review_summary) do |summary|
+          pending = summary.fetch(:pending)
+          text = [ "VXLAN 证据：#{summary.fetch(:status)}；完成 #{results.size} 台", "分类：#{summary.fetch(:counts)}", "证据完整性不代表 Fabric 健康。" ]
+          text << "逐设备诊断：devices/；候选脚本：scripts/；所有候选配置未执行。"
+          text << @review_text if @review_text
+          text << "批次报告状态：参见 summary.json；文本中的证据状态不确认报告发布完成。"
+          text << "报告错误：#{report_error}" if report_error
+          text << "执行错误：#{execution_error}" if execution_error
+          text << "进度输出错误：#{output_error[:error_type]}；设备结果已保留" if output_error
+          results.each do |r|
+            saved = r[:report_saved] == true ? "已保存" : "保存未确认"
+            text << "#{r[:device]['host']}\t#{r[:device]['name']}\t#{r[:status]}\t#{saved}\t#{r[:error]}"
           end
+          pending.each { |device| text << "#{device['host']}\t#{device['name']}\t未采集" }
+          text.join("\n") + "\n"
         end
-      rescue Interrupt
-        @recovery_failed = true
-      end
-
-      # 存储拒绝恢复时尽力移除不可信摘要，不删除已获得的设备事实。
-      def discard_summary(relative: "summary.json")
-        File.unlink(File.join(directory, relative))
-      rescue Errno::ENOENT
-        nil
-      rescue SystemCallError
-        @recovery_failed = true
       end
 
-      # Time 使用 ISO-8601，递归转换 Data 只发生在显式持久化边界。
-      def serializable(value)
-        case value
-        when Time then value.iso8601(6)
-        when Data then serializable(value.to_h)
-        when Hash then value.transform_values { |item| serializable(item) }
-        when Array then value.map { |item| serializable(item) }
-        else value
-        end
-      end
+      private
 
-      # 临时文件与目标在同一目录，写入失败不发布半份报告。
-      def publish(relative, body)
-        target = File.join(directory, relative)
-        phase, committed = :temporary_file, false
-        Tempfile.create([ ".vxlan-", ".tmp" ], File.dirname(target)) do |file|
-          file.chmod(0o600)
-          phase = :write
-          file.write(body)
-          phase = :file_sync
-          file.flush
-          file.fsync
-          phase = :rename
-          File.rename(file.path, target)
-          committed = true
-          phase = :directory_sync
-          sync_directory(File.dirname(target))
-          phase = :cleanup
-        end
-      rescue SystemCallError, IOError, NotImplementedError
-        raise Error.new(relative: relative, phase: phase, committed: committed), cause: nil
-      end
+      # 保持领域呈现接口，事务与恢复状态仅在公共报告中实现。
+      def prepare_directory(path) = @report.prepare_directory(path)
+      def publish(relative, body) = @report.publish(relative, body)
+      def serializable(value) = @report.serializable(value)
+      def checkpoint(relative, value) = @report.checkpoint(relative, value)
+      def finalize(relative, summary, checkpoint:) = @report.finalize(relative, summary, checkpoint: checkpoint)
     end
   end
 end

data/lib/vxlan/cli/review/report.rb

@@ -66,7 +66,7 @@ module Vxlan
           public_entries = entries.map { |entry| entry.reject { |key, _| %i[advice changes].include?(key) } }
           summary = { layout_version: 3, mode: "review", status: "incomplete", review_only: true, devices: entries.size, counts: counts, source_batch: source_batch,
             reports: public_entries, plan: "plan.json", plan_sha256: nil, fabric_findings: @fabric_audit ? @fabric_audit[:findings].size : 0 }
-          publish("summary.json", JSON.pretty_generate(summary) + "\n") if standalone
+          checkpoint("summary.json", summary) if standalone
           plan = { schema_version: 2, platform: "cisco_nxos", mode: "review", devices: public_entries, audits: entries.map { |entry| entry[:advice] },
             changes: entries.each_with_object({}) { |entry, all| all.merge!(entry[:changes]) }, fabric: @fabric_audit && @fabric_audit.reject { |key, _| key == :device_items } }
           body = JSON.pretty_generate(plan) + "\n"
@@ -78,15 +78,7 @@ module Vxlan
           text = summary_text(summary)
           if standalone
             publish("summary.txt", text)
-            begin
-              publish("summary.json", JSON.pretty_generate(summary.merge(status: "complete")) + "\n")
-            rescue CLI::Report::Error => error
-              restore_checkpoint(JSON.pretty_generate(summary) + "\n") if error.committed?
-              raise
-            rescue Interrupt
-              restore_checkpoint(JSON.pretty_generate(summary.merge(status: "interrupted")) + "\n")
-              raise
-            end
+            finalize("summary.json", summary.merge(status: "complete"), checkpoint: summary)
           end
           @review_summary, @review_text = summary.merge(status: "complete"), text
           @review_summary

data/lib/vxlan/cli.rb

@@ -15,7 +15,12 @@ module Vxlan
       when "--version", "-v"
         return out.puts(Vxlan::VERSION) || 0 if arguments.empty?
       when "collect"
-        require_relative "cli/collect"
+        begin
+          require_relative "cli/collect"
+        rescue LoadError
+          error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
+          return 2
+        end
         return Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
       when "apply"
         require_relative "cli/apply"

data/lib/vxlan/collection_plan.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "observation"
+
+module Vxlan
+  # 配置证据约束运行查询：明确未启用的功能才允许空回显或省略查询。
+  class CollectionPlan
+    def initialize(profile:, configuration: nil)
+      @profile, @configuration = profile, configuration
+    end
+
+    def parse_many(names, body, complete:, command:)
+      if names.one? && body.strip.empty? && unconfigured?(names.first)
+        name = names.first
+        code = name == :port_channels ? :port_channels_not_configured : :nve_not_configured
+        return { name => CtxParser::Result.new(status: :complete, issues: [ { code: code } ]) }
+      end
+      @profile.parse_many(names, body, complete: complete, command: command)
+    end
+
+    # 仅当同一会话的完整配置证明功能未启用时，才接受空运行回显。
+    def unconfigured?(name)
+      return false unless @configuration&.complete? && @configuration.records.one?
+
+      settings = @configuration.records.first
+      case name
+      when :vpc then !settings[:vpc_domain] && !settings.fetch(:features).include?("vpc")
+      when :nve_peers, :nve_vnis then !settings.fetch(:nve)[:interface]
+      when :port_channels
+        settings.fetch(:interfaces).none? { |interface, values| /\Aport-channel\d+\z/i.match?(interface) || values[:channel_group] }
+      else false
+      end
+    end
+  end
+end

data/lib/vxlan/collector.rb

@@ -2,6 +2,9 @@
 
 require_relative "parser_registry"
 require "ctx_driver"
+require "ctx_runner/collection"
+require "ctx_runner/query"
+require_relative "collection_plan"
 require_relative "observation"
 require_relative "snapshot"
 
@@ -21,29 +24,12 @@ module Vxlan
       target, fabric_key, dimensions, profile = request(target, fabric_key, dimensions, connector.platform, model)
 
       observations = {}
-      session_started = session_finished = false
-      begin
-        connector.open do |session|
-          if session_started
-            dimensions.each { |name| observations[name] ||= failure(name, :session_reentered) }
-            observations[:collection] = failure(:collection, :session_reentered)
-            next
-          end
-          session_started = true
-          observations.merge!(read_dimensions(session, dimensions, profile))
-          session_finished = true
-        end
-      rescue StandardError => error
-        raise unless CtxDriver::Failure.connection_error?(error, connector)
-
-        code = CtxDriver::Failure.code(error, :connection_failed)
+      collection = CtxRunner::Collection.new
+      collection.open(connector) { |session| observations.merge!(read_dimensions(session, dimensions, profile)) }
+      if collection.failure
+        code = collection.failure.fetch(:code)
         dimensions.each { |name| observations[name] ||= failure(name, code) }
-        observations[:collection] = failure(:collection, session_finished ? :session_close_failed : code)
-      end
-      # 连接器正常返回也不等于已提供会话；缺少回调必须保留全部请求的失败事实。
-      unless session_finished || observations.key?(:collection)
-        dimensions.each { |name| observations[name] = failure(name, :session_not_opened) }
-        observations[:collection] = failure(:collection, :session_not_opened)
+        observations[:collection] = failure(:collection, code)
       end
       snapshot(target, fabric_key, observations)
     end
@@ -79,11 +65,11 @@ module Vxlan
       end
       ordered = dimensions.include?(:configuration) ? [ :configuration, *dimensions.reject { |name| name == :configuration } ] : dimensions
       ordered.each do |name|
-        config = observations[:configuration]
-        observations[name] = if name == :vpc && !reader.failure && unconfigured?(name, config)
+        plan = CollectionPlan.new(profile: profile, configuration: observations[:configuration])
+        observations[name] = if name == :vpc && !reader.failure && plan.unconfigured?(name)
           Observation.new(name: name, status: :complete, completed_at: @clock.call, issues: [ { code: :vpc_not_configured } ])
         else
-          collect_observation(reader, name, config, profile)
+          collect_observation(reader, name, plan, profile)
         end
       end
       dimensions.to_h { |name| [ name, observations.fetch(name) ] }
@@ -112,45 +98,18 @@ module Vxlan
     end
 
     # 解析失败限定在单条查询内；Reader 负责传输与回执校验。
-    def collect_observation(reader, name, configuration, profile)
+    def collect_observation(reader, name, plan, profile)
       command = profile.command(name)
-      capture = reader.read(command)
-      metadata = { started_at: capture.started_at, completed_at: capture.completed_at, evidence: capture.evidence }
-      unless capture.success?
-        return failed_capture(name, capture, command).with(**metadata)
-      end
-      begin
-        body = capture.body
-        parsed = if body.strip.empty? && unconfigured?(name, configuration)
-          code = name == :port_channels ? :port_channels_not_configured : :nve_not_configured
-          Observation.new(name: name, status: :complete, issues: [ { code: code } ])
-        else
-          Observation.new(name: name, **profile.parse(name, body, complete: true).to_h)
-        end
-        parsed.with(**metadata)
-      rescue StandardError => error
-        details = CtxDriver::Failure.details(error, fallback: :command_processing_failed, stage: :parse)
-        failure(name, details.fetch(:code), **details.except(:code), command: command).with(**metadata)
-      end
-    end
-
-    # 保留传输首次不可用原因，并标记从未发送的命令。
-    def failed_capture(name, capture, command)
-      failure(name, capture.failure.fetch(:code), **capture.failure.except(:code), command: command, skipped: capture.skipped?)
-    end
-
-    # 仅当同一会话的完整配置证明功能未启用时，才接受空运行回显。
-    def unconfigured?(name, configuration)
-      return false unless configuration&.complete? && configuration.records.one?
-
-      settings = configuration.records.first
-      case name
-      when :vpc then !settings[:vpc_domain] && !settings.fetch(:features).include?("vpc")
-      when :nve_peers, :nve_vnis then !settings.fetch(:nve)[:interface]
-      when :port_channels
-        settings.fetch(:interfaces).none? { |interface, values| /\Aport-channel\d+\z/i.match?(interface) || values[:channel_group] }
-      else false
+      unavailable = ->(view, capture, details) do
+        issue = details.merge(command: command)
+        issue[:skipped] = capture.skipped? unless capture.success?
+        failure(view, issue.fetch(:code), **issue.except(:code)).with(
+          started_at: capture.started_at, completed_at: capture.completed_at, evidence: capture.evidence)
       end
+      CtxRunner::Query.new(reader: reader, parser: plan).read(command, names: [ name ], unavailable: unavailable) do |view, result, capture|
+        Observation.new(name: view, **result.to_h, started_at: capture.started_at,
+          completed_at: capture.completed_at, evidence: capture.evidence)
+      end.fetch(name)
     end
 
     # 构建失败观测，不丢弃已成功的同级维度。

data/lib/vxlan/observation.rb

@@ -1,29 +1,8 @@
 # frozen_string_literal: true
 
-require "ctx_parser/immutable"
+require "ctx_runner/observation"
 
 module Vxlan
-  # 保留命令事实与完整性；默认检查不输出原始配置或凭据。
-  Observation = Data.define(:name, :status, :records, :issues, :evidence, :started_at, :completed_at) do
-    # 冻结单个维度的记录、状态及诊断元数据。
-    def initialize(name:, status:, records: [], issues: [], evidence: [], started_at: nil, completed_at: nil)
-      raise ArgumentError, "Observation name must be a symbol" unless name.is_a?(Symbol)
-      raise ArgumentError, "Invalid observation status" unless %i[complete partial failed unsupported not_requested].include?(status)
-      raise ArgumentError, "Records must be hashes" unless records.is_a?(Array) && records.all? { |row| row.is_a?(Hash) }
-
-      super(name: name, status: status, records: CtxParser::Immutable.copy(records),
-        issues: CtxParser::Immutable.copy(issues), evidence: CtxParser::Immutable.copy(evidence),
-        started_at: started_at&.dup&.freeze, completed_at: completed_at&.dup&.freeze)
-    end
-
-    # 判断所有已选事实是否都有完整证据支持。
-    def complete? = status == :complete
-
-    # 展示对象身份与状态，避免泄露原始回显或凭据。
-    def inspect = "#<#{self.class.name} name=#{name} status=#{status} records=#{records.size}>"
-    alias to_s inspect
-
-    # PP 默认展开 Data 成员，显式沿用脱敏展示。
-    def pretty_print(printer) = printer.text(inspect)
-  end
+  # 复用公共事实契约；领域保留公开类型与后续的专属约束。
+  class Observation < CtxRunner::Observation; end
 end

data/lib/vxlan/version.rb

@@ -2,5 +2,5 @@
 
 module Vxlan
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Gatework contributors
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_runner
+  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: ctx_parser
   requirement: !ruby/object:Gem::Requirement
@@ -226,6 +240,7 @@ files:
 - lib/vxlan/cli/review/report.rb
 - lib/vxlan/cli/templates/env.example
 - lib/vxlan/cli/templates/vxlan.yml
+- lib/vxlan/collection_plan.rb
 - lib/vxlan/collector.rb
 - lib/vxlan/config.rb
 - lib/vxlan/config/evidence.rb