vxlan 0.3.1 → 0.4.1

data/lib/vxlan/cli/parse.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require "optparse"
+require "ctx_cli/command"
+require "ctx_cli/options"
+require "ctx_cli/input"
+require "ctx_cli/output"
 require "json"
 require "time"
 require "vxlan"
@@ -12,45 +15,40 @@ module Vxlan
       # 注入标准流，便于在宿主测试中验证无需网络的行为。
       def initialize(out: $stdout, error: $stderr, input: $stdin, command: "vxlan parse")
         @out, @error, @input, @command = out, error, input, command
+        @output = CtxCli::Output.new(out: out, error: error)
       end
 
       # 参数错误与部分证据分开返回；默认只显示元数据，JSON 显式导出事实。
       def run(argv)
-        options = { dimension: :configuration, complete: false }
-        parser = OptionParser.new do |p|
-          p.banner = "用法：#{@command} [选项]（离线文件或 stdin）"
+        command = CtxCli::Command.new(banner: "用法：#{@command} [选项]（离线文件或 stdin）", defaults: { dimension: :configuration, complete: false }, out: @out) do |p, options|
           p.on("--file FILE", "读取文件，默认 stdin") { |v| options[:file] = v }
           p.on("--dimension NAME", "configuration 或运行维度") { |v| options[:dimension] = v.to_sym }
           p.on("--model NAME", "设备型号") { |v| options[:model] = v }
           p.on("--complete", "声明输入已完整采集，仍保留解析缺失诊断") { options[:complete] = true }
           p.on("--json", "输出事实 JSON，可能包含配置敏感信息") { options[:json] = true }
-          p.on("-h", "--help", "查看帮助") { options[:help] = true }
-          p.on("--help-all", "查看全部选项") { options[:help] = true }
-          p.on("--examples", "查看示例") { options[:examples] = true }
+          CtxCli::Options.information(p, options)
           p.separator "维度：#{Vxlan::Collector::COMMANDS.keys.join(', ')}"
         end
-        rest = parser.parse(argv.dup)
-        raise ArgumentError, "不接受位置参数" unless rest.empty?
-        return @out.puts(parser) || 0 if options[:help]
-        return @out.puts("#{@command} --file running.cfg --complete\ncat nve.txt | #{@command} --dimension nve_peers --complete --json") || 0 if options[:examples]
+        options = command.parse(argv)
+        return 0 if command.informational?(examples: "#{@command} --file running.cfg --complete\ncat nve.txt | #{@command} --dimension nve_peers --complete --json")
         raise ArgumentError, "未知维度" unless Vxlan::Collector::COMMANDS.key?(options[:dimension])
 
-        body = options[:file] ? File.read(options[:file]) : @input.read
+        body = CtxCli::Input.read(path: options[:file], input: @input)
         observation = if options[:dimension] == :configuration
           Vxlan::Config.new(model: options[:model]).parse(body, complete: options[:complete])
         else
           Vxlan::RuntimeParser.new(model: options[:model]).parse(options[:dimension], body, complete: options[:complete])
         end
         if options[:json]
-          @out.puts JSON.pretty_generate(observation.to_h)
+          @output.json(observation.to_h)
         else
           @out.puts "维度：#{observation.name}；证据：#{observation.status}；记录：#{observation.records.size}"
           @out.puts "诊断：#{observation.issues.map { |issue| issue[:code] }.uniq.join(', ')}" unless observation.issues.empty?
           @out.puts "证据完整性不代表 Fabric 健康。"
         end
         observation.complete? ? 0 : 1
-      rescue OptionParser::ParseError, ArgumentError, SystemCallError => error
-        @error.puts "离线解析参数或文件错误（#{error.class.name}）；使用 --help 查看参数"
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError, IOError => error
+        @output.diagnostic("离线解析参数或文件错误；使用 --help 查看参数", exception: error)
         2
       end
     end

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

@@ -1,41 +1,42 @@
 # frozen_string_literal: true
 
 require "vxlan/version"
+require "ctx_cli/application"
 
 module Vxlan
   # 命令入口按需加载采集或解析实现；核心库无需加载 CLI。
   module CLI
     # 由调用方拥有退出行为，库入口只返回退出码。
     def self.run(argv, env: ENV, out: $stdout, error: $stderr, input: $stdin, **collect_options)
-      arguments = argv.dup
-      command = arguments.shift
-      case command
-      when nil, "--help", "--help-all", "-h"
-        return usage(out) if arguments.empty?
-      when "--version", "-v"
-        return out.puts(Vxlan::VERSION) || 0 if arguments.empty?
-      when "collect"
-        require_relative "cli/collect"
-        return Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
-      when "apply"
-        require_relative "cli/apply"
-        return Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
-      when "review"
-        require_relative "cli/review"
-        return Review.new(out: out, error: error).run(arguments)
-      when "parse"
-        require_relative "cli/parse"
-        return Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
-      end
-      error.puts "未知命令或多余参数；使用 vxlan --help 查看用法"
-      2
+      commands = {
+        "collect" => ->(arguments) do
+          begin
+            require_relative "cli/collect"
+          rescue LoadError
+            error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
+            next 2
+          end
+          Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
+        end,
+        "apply" => ->(arguments) do
+          require_relative "cli/apply"
+          Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
+        end,
+        "review" => ->(arguments) do
+          require_relative "cli/review"
+          Review.new(out: out, error: error).run(arguments)
+        end,
+        "parse" => ->(arguments) do
+          require_relative "cli/parse"
+          Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
+        end
+      }
+      CtxCli::Application.new(name: "vxlan", version: Vxlan::VERSION, usage: USAGE,
+        commands: commands, out: out, error: error).run(argv)
     end
 
     # 全局帮助不读取配置、环境文件或设备清单。
-    def self.usage(out)
-      out.puts "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。"
-      0
-    end
-    private_class_method :usage
+    USAGE = "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。".freeze
+    private_constant :USAGE
   end
 end

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.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Gatework contributors
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: 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 +254,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