vxlan 0.4.1 → 0.5.0

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

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "yaml"
+require "ctx_cli/input"
+require "ctx_runner/fingerprint"
 require_relative "../../fabric/review"
 
 module Vxlan
@@ -11,35 +13,35 @@ module Vxlan
         # 相同事实合并展示；规则版本保持匹配顺序，完整证据由聚合计划保存。
         def fabric_text(audit, documents)
           by_host = documents.to_h { |document| [ document.fetch("device").fetch("host"), document ] }
-          lines = [ "Fabric 共同业务一致性", "范围：按显式 Fabric 和角色比较共同 VNI；Leaf、Border 分开比较，Spine 检查业务承载配置。", "部署事实联合 VLAN/NVE/EVPN 识别；不完整部署不等于未部署。保留部署范围差异。", "ACL 比较包含有序规则与依赖对象；不以多数无 ACL 为删除依据。", "" ]
+          lines = [ "Fabric shared-service consistency", "Scope: compare shared VNIs within explicit Fabrics and roles; compare Leaf and Border separately, and check Spine for service-bearing configuration.", "Deployment facts combine VLAN/NVE/EVPN evidence; incomplete deployment does not mean absence. Deployment scope differences are retained.", "ACL comparison includes ordered rules and dependencies; a majority without an ACL is not grounds for removal.", "" ]
           inventory = audit[:inventory]
           if inventory
-            lines << "覆盖：已纳入 #{inventory[:assigned].size} 台；未纳入 #{inventory[:unassigned].size} 台；缺证据 #{inventory[:missing].size} 台。"
+            lines << "Coverage: included #{inventory[:assigned].size} devices; excluded #{inventory[:unassigned].size} devices; missing evidence #{inventory[:missing].size} devices."
             inventory[:groups].each do |fabric, roles|
-              lines << "#{fabric}：Leaf #{roles['leaves'].size} / Border #{roles['borders'].size} / Spine #{roles['spines'].size}"
+              lines << "#{fabric}: Leaf #{roles['leaves'].size} / Border #{roles['borders'].size} / Spine #{roles['spines'].size}"
               %w[leaves borders].each do |role|
                 services = audit[:coverage].select { |entry| entry[:fabric] == fabric && entry[:role] == role }
                 partial = services.select { |entry| entry[:incomplete].any? }
-                lines << "  #{role}：已部署业务 #{services.size}，多设备共同业务 #{services.count { |entry| entry[:deployed].size >= 2 }}，关联不完整 #{partial.size}。"
-                partial.each { |entry| lines << "    VNI #{entry[:vni]} 待补齐：#{entry[:incomplete].map { |host| by_host.dig(host, 'device', 'name') || host }.join('、')}" }
+                lines << "  #{role}: deployed services #{services.size}, services shared across devices #{services.count { |entry| entry[:deployed].size >= 2 }}, incomplete associations #{partial.size}."
+                partial.each { |entry| lines << "    VNI #{entry[:vni]} missing: #{entry[:incomplete].map { |host| by_host.dig(host, 'device', 'name') || host }.join(', ')}" }
               end
             end
             lines << ""
           end
           audit[:findings].each_with_index do |finding, index|
-            lines << "#{index + 1}. #{finding[:fabric]} / #{finding[:role] || '全 Fabric'} / #{finding[:vni] ? "VNI #{finding[:vni]}" : '公共策略'}：#{finding[:title]}"
+            lines << "#{index + 1}. #{finding[:fabric]} / #{finding[:role] || 'entire Fabric'} / #{finding[:vni] ? "VNI #{finding[:vni]}" : 'shared policy'}: #{finding[:title]}"
           end
           audit[:findings].each_with_index do |finding, index|
-            lines.concat([ "", "[#{index + 1}] #{finding[:fabric]} / #{finding[:role] || '全 Fabric'} / #{finding[:vni] || '公共策略'} — #{finding[:title]}", "规则：#{finding[:code]}" ])
+            lines.concat([ "", "[#{index + 1}] #{finding[:fabric]} / #{finding[:role] || 'entire Fabric'} / #{finding[:vni] || 'shared policy'} — #{finding[:title]}", "Rule: #{finding[:code]}" ])
             evidence = finding[:evidence]
             if finding[:code] == "fabric_address_group"
               defined = evidence.filter_map { |row| row[:value] }
               common = defined.reduce { |all, members| all & members } || []
-              lines << "  已定义版本的共同成员（不代表批准基线）：#{common.empty? ? '无' : common.join('、')}"
+              lines << "  Members common to defined versions (not an approved baseline): #{common.empty? ? 'none' : common.join(', ')}"
               evidence.group_by { |row| row[:value] }.each do |members, rows|
                 names = rows.map { |row| by_host.dig(row[:host], "device", "name") || row[:host] }
-                value = members ? "#{members.size} 个成员；共同成员之外：#{(members - common).empty? ? '无' : (members - common).join('、')}" : "未提供定义或未采集对象证据"
-                lines.concat([ "  #{names.join('、')}", "    #{value}" ])
+                value = members ? "#{members.size} members; outside the common set: #{(members - common).empty? ? 'none' : (members - common).join(', ')}" : "No definition provided or object evidence not collected"
+                lines.concat([ "  #{names.join(', ')}", "    #{value}" ])
               end
               next
             end
@@ -51,18 +53,18 @@ module Vxlan
               value = row.key?(:value) ? row[:value] : row.reject { |key, _| %i[host name vlan entries semantics].include?(key) }
               value = value.reject { |key, _| key == :entries } if value.is_a?(Hash)
               if row[:semantics]
-                policy = row[:policy] ? "规则与依赖版本 #{ChangePlan.fingerprint(row[:policy])[0, 12]}" : "依赖对象未验证"
-                value = "#{row[:entries].size} 条规则，#{policy}"
+                policy = row[:policy] ? "Rule and dependency version #{CtxRunner::Fingerprint.call(row[:policy])[0, 12]}" : "Dependencies unverified"
+                value = "#{row[:entries].size} rules, #{policy}"
               end
-              [ row[:vlan] || row[:interface] || "公共", display_fabric_value(value) ]
+              [ row[:vlan] || row[:interface] || "shared", display_fabric_value(value) ]
             end
             grouped.each do |(vlan, value), members|
               names = members.map { |row| row[:name] || by_host.dig(row[:host], "device", "name") || row[:host] }
-              lines.concat([ "  VLAN/接口 #{vlan}：#{value}", "    #{names.join('、')}" ])
+              lines.concat([ "  VLAN/interface #{vlan}: #{value}", "    #{names.join(', ')}" ])
             end
             if evidence.any? { |row| row[:semantics] }
               evidence.group_by { |row| row[:semantics] }.each_with_index do |(rules, members), variant|
-                lines << "  规则版本 #{variant + 1}：#{members.map { |row| by_host.dig(row[:host], 'device', 'name') || row[:host] }.join('、')}"
+                lines << "  Rule version #{variant + 1}: #{members.map { |row| by_host.dig(row[:host], 'device', 'name') || row[:host] }.join(', ')}"
                 lines.concat(rules.map { |rule| "    #{rule['action']} #{rule['expression']}" })
               end
             end
@@ -73,14 +75,14 @@ module Vxlan
         # 机器字段转换为运维读法，显式保留缺失和未知。
         def display_fabric_value(value)
           if value.is_a?(Hash) && value.key?(:acl)
-            return "未挂载 ACL" unless value[:acl]
-            return "#{value[:acl]}；本机缺少定义" unless value[:defined]
-            return "#{value[:acl]}；已定义，但依赖对象未验证" unless value[:policy_verified]
-            "#{value[:acl]}；已定义，版本 #{value[:digest].to_s[0, 12]}"
+            return "No ACL attached" unless value[:acl]
+            return "#{value[:acl]}; local definition missing" unless value[:defined]
+            return "#{value[:acl]}; defined, but dependencies unverified" unless value[:policy_verified]
+            "#{value[:acl]}; defined, version #{value[:digest].to_s[0, 12]}"
           elsif value.is_a?(Array)
-            value.empty? ? "未配置地址" : value.join("、")
+            value.empty? ? "No address configured" : value.join(", ")
           elsif value.nil?
-            "未提供"
+            "not provided"
           elsif value.is_a?(Hash)
             JSON.generate(value)
           else
@@ -91,7 +93,7 @@ module Vxlan
         # 实时收尾读取已经保存的事实；审查摘要交给采集摘要一起发布，避免相互覆盖。
         def review_collected_fabric(policy)
           sources = Dir[File.join(directory, "evidence", "*.json")].sort.map do |path|
-            body = File.read(path)
+            body = CtxCli::Input.read(path: path)
             [ File.expand_path(path), body, JSON.parse(body) ]
           end
           build_review(sources, policy: policy, standalone: false) unless sources.empty?

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "digest"
+require "ctx_runner/fingerprint"
 require_relative "../../recommendations"
 require_relative "../../change_plan"
 
@@ -27,7 +28,7 @@ module Vxlan
 
         # 配置和回退集中于每设备一份 cfg；有限类型动作汇总到批次计划，不接受 cfg 直接执行。
         def write_review(document, basename:, source:, source_sha256:, advice: nil)
-          raise ArgumentError, "非法报告名称" unless basename.match?(/\A[A-Za-z0-9_.-]+\z/)
+          raise ArgumentError, "Invalid report name" unless basename.match?(/\A[A-Za-z0-9_.-]+\z/)
           advice = report_advice(advice || Recommendations.new(document).call).merge(source: source, source_sha256: source_sha256)
           advice[:items] = advice[:items].map(&:dup)
           entry = { device: advice[:device], counts: advice[:counts], basename: basename, report: "devices/#{basename}.txt", source: source,
@@ -39,8 +40,8 @@ module Vxlan
             plan = ChangePlan.candidate(item[:change], config: config)
             next unless plan
             change = plan.to_h
-            id = [ basename, change["kind"], "vlan#{change['vlan']}", change["direction"], ChangePlan.fingerprint(change)[0, 12] ].compact.join("--")
-            config_sha256 ||= ChangePlan.fingerprint(config)
+            id = [ basename, change["kind"], "vlan#{change['vlan']}", change["direction"], CtxRunner::Fingerprint.call(change)[0, 12] ].compact.join("--")
+            config_sha256 ||= CtxRunner::Fingerprint.call(config)
             entry[:changes][id] = { schema_version: 1, platform: "cisco_nxos", device: document.fetch("device"), expected_config_sha256: config_sha256,
               source: source, source_sha256: source_sha256, change: change, commands: plan.commands, rollback: plan.rollback,
               scope: item[:scope], title: item[:title], prerequisites: item[:prerequisites], impact: item[:impact], verify: item[:verify] }
@@ -94,14 +95,14 @@ module Vxlan
 
         # 每项包含作用域、条件、命令及注释化回退，不将多项当成原子变更。
         def script_text(items)
-          lines = [ "! 候选配置，未执行；先审阅同名 devices/*.txt；禁止整批直接粘贴。", "! apply 只读取 plan.json 中明确选择的单项，不执行本 cfg。" ]
+          lines = [ "! Candidate configuration, not executed; review the matching devices/*.txt first. Do not paste the entire batch.", "! apply reads only the explicitly selected item from plan.json; it does not execute this cfg file." ]
           items.each do |item|
-            lines.concat([ "", "! #{item[:scope]} / #{item[:title]}", "! 计划项：#{item[:plan_id] || '仅审阅草稿，不支持交互执行'}" ])
-            lines.concat(item[:prerequisites].map { |condition| "! 条件：#{condition}" })
+            lines.concat([ "", "! #{item[:scope]} / #{item[:title]}", "! Plan item: #{item[:plan_id] || 'Review draft only; interactive execution unsupported'}" ])
+            lines.concat(item[:prerequisites].map { |condition| "! Prerequisite: #{condition}" })
             lines.concat(item[:commands])
-            lines << "! 条件回退（不自动执行）："
+            lines << "! Conditional rollback (not executed automatically): "
             lines.concat(item[:rollback].map { |command| "! #{command}" })
-            lines << "! 核查：#{item[:verify].join(' ; ')}"
+            lines << "! Verification: #{item[:verify].join(' ; ')}"
           end
           lines.join("\n") + "\n"
         end
@@ -109,27 +110,27 @@ module Vxlan
         # 文本按设备、证据、问题、动作顺序组织，完整跨设备证据位于聚合计划。
         def device_text(entry, document)
           advice, device = entry.values_at(:advice, :device)
-          lines = [ "设备：#{device['name']}（#{device['host']}）", "模式：诊断与计划，未执行设备配置", "证据时间：#{advice[:observed_at] || '未知'}", "来源：#{entry[:source]}", "源文件 SHA256：#{entry[:source_sha256]}",
-            "建议：#{entry[:counts]}", "命令文件：#{entry[:script] || '未生成'}", "命令 SHA256：#{entry[:script_sha256] || '无'}", "计划文件：plan.json；交互计划项 #{entry[:plans].size} 个", "" ]
-          lines << "采集状态：#{document['status']}" if document["status"]
+          lines = [ "Device: #{device['name']} (#{device['host']})", "Mode: diagnostics and planning; no device configuration executed", "Evidence time: #{advice[:observed_at] || 'unknown'}", "Source: #{entry[:source]}", "Source file SHA256: #{entry[:source_sha256]}",
+            "Recommendations: #{entry[:counts]}", "Command file: #{entry[:script] || 'not generated'}", "Command SHA256: #{entry[:script_sha256] || 'none'}", "Plan file: plan.json; interactive plan items: #{entry[:plans].size} items", "" ]
+          lines << "Collection status: #{document['status']}" if document["status"]
           configuration_time = document.dig("snapshot", "dimensions", "configuration", "evidence", 0, "observed_at")
-          lines << "配置证据时间：#{configuration_time}" if configuration_time
-          lines << "当前规则未命中；不代表网络健康。" if advice[:items].empty?
+          lines << "Configuration evidence time: #{configuration_time}" if configuration_time
+          lines << "No current rules matched; this does not establish network health." if advice[:items].empty?
           advice[:items].each_with_index do |item, index|
-            lines.concat([ "", "#{index + 1}. #{item[:scope]} — #{item[:title]}", "状态：#{item[:status]}；规则：#{item[:code]}", "影响：#{item[:impact]}" ])
+            lines.concat([ "", "#{index + 1}. #{item[:scope]} — #{item[:title]}", "Status: #{item[:status]}; rule: #{item[:code]}", "Impact: #{item[:impact]}" ])
             evidence = item[:category] == "fabric" ? Array(item[:evidence]).select { |row| row[:host] == device["host"] } : item[:evidence]
-            lines.concat([ "本机依据：", JSON.pretty_generate(evidence) ])
-            lines << "跨设备对比：summary.txt；完整原始对比：plan.json 的 audits / fabric。" if item[:category] == "fabric"
+            lines.concat([ "Local evidence: ", JSON.pretty_generate(evidence) ])
+            lines << "Cross-device comparison: summary.txt; full raw comparison: audits / fabric in plan.json." if item[:category] == "fabric"
             if item[:plan_id]
-              lines << "交互计划项：#{item[:plan_id]}"
-              lines << "在批次目录运行：vxlan apply --plan plan.json --item #{item[:plan_id]}"
+              lines << "Interactive plan item: #{item[:plan_id]}"
+              lines << "Run in the batch directory: vxlan apply --plan plan.json --item #{item[:plan_id]}"
             end
-            { prerequisites: "适用条件", blockers: "待决信息", commands: "候选配置（未执行）", rollback: "条件回退", verify: "只读核查", template: "待补模板（不可执行）" }.each do |key, title|
+            { prerequisites: "Prerequisites", blockers: "Unresolved information", commands: "Candidate configuration (not executed)", rollback: "Conditional rollback", verify: "Read-only verification", template: "Incomplete template (not executable)" }.each do |key, title|
               values = item[key] || []
-              lines.concat([ "#{title}：", *values.map { |value| "  #{value}" } ]) if values.any?
+              lines.concat([ "#{title}: ", *values.map { |value| "  #{value}" } ]) if values.any?
             end
-            lines << "验收：#{item[:expected]}" if item[:expected]
-            lines << "命令参考：#{item[:references].join(' ')}" if item[:references]&.any?
+            lines << "Acceptance: #{item[:expected]}" if item[:expected]
+            lines << "Command reference: #{item[:references].join(' ')}" if item[:references]&.any?
           end
           lines.join("\n") + "\n"
         end
@@ -138,15 +139,15 @@ module Vxlan
         def summary_text(summary)
           entries, counts = summary.values_at(:reports, :counts)
           active = entries.count { |entry| entry[:counts].values.sum.positive? }
-          lines = [ "VXLAN 诊断与配置建议；模式：review；未执行设备变更。", "报告完成状态以 summary.json 为准。", "设备：#{entries.size} 台；有建议 #{active} 台；未命中规则 #{entries.size - active} 台（不代表健康）。",
-            "建议：待决 #{counts['blocked']}，候选 #{counts['candidate']}，排查 #{counts['investigate']}；Fabric 聚合差异 #{summary[:fabric_findings]} 项。",
-            "计划：#{entries.sum { |entry| entry[:plans].size }} 项可交互执行增量；#{entries.count { |entry| entry[:script] }} 份候选脚本。候选数与可执行计划数不同。",
-            "阅读顺序：summary.txt → devices/<设备>.txt → scripts/<设备>.cfg → plan.json 中的指定计划项。",
-            "evidence/ 保存程序使用的采集证据，日常阅读无需打开；devices/ 只包含可读诊断。",
-            "plan.json.sha256 校验聚合计划；events.jsonl 记录本次离线审查，不代表设备会话或下发回执。", "下发必须 --item 选择单项、交互确认、重读配置并核对指纹；无自动批量执行。", "" ]
+          lines = [ "VXLAN diagnostics and configuration recommendations; mode: review; no device changes executed.", "Report completion status is authoritative in summary.json.", "Devices: #{entries.size} devices; with recommendations #{active} devices; no rules matched #{entries.size - active} devices (does not establish health).",
+            "Recommendations: unresolved #{counts['blocked']}, candidates #{counts['candidate']}, investigations #{counts['investigate']}; aggregated Fabric differences #{summary[:fabric_findings]} items.",
+            "Plan: #{entries.sum { |entry| entry[:plans].size }} changes available for interactive execution; #{entries.count { |entry| entry[:script] }} candidate scripts. Candidate counts differ from executable plan counts.",
+            "Read in order: summary.txt -> devices/<device>.txt -> scripts/<device>.cfg -> the selected plan item in plan.json.",
+            "evidence/ stores collection evidence used by the program; routine review does not require opening it. devices/ contains readable diagnostics only.",
+            "plan.json.sha256 verifies the aggregate plan; events.jsonl records this offline review, not device sessions or execution receipts.", "Applying requires selecting one --item, interactive confirmation, configuration readback and fingerprint verification; there is no automatic bulk execution.", "" ]
           entries.sort_by { |entry| [ entry[:counts].values.sum.positive? ? 0 : 1, entry[:device]["name"].to_s ] }.each do |entry|
-            lines.concat([ "#{entry[:device]['host']} #{entry[:device]['name']} 待决=#{entry[:counts].fetch('blocked', 0)} 候选=#{entry[:counts].fetch('candidate', 0)} 排查=#{entry[:counts].fetch('investigate', 0)}",
-              "  设备报告：#{entry[:report]}", "  命令文件：#{entry[:script] || '未生成'}；可执行计划：#{entry[:plans].size} 项" ])
+            lines.concat([ "#{entry[:device]['host']} #{entry[:device]['name']} unresolved=#{entry[:counts].fetch('blocked', 0)} candidates=#{entry[:counts].fetch('candidate', 0)} investigations=#{entry[:counts].fetch('investigate', 0)}",
+              "  Device report: #{entry[:report]}", "  Command file: #{entry[:script] || 'not generated'}; executable plans: #{entry[:plans].size} items" ])
           end
           lines.concat([ "", @fabric_text ]) if @fabric_text
           lines.join("\n") + "\n"

data/lib/vxlan/cli/review.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
-require "optparse"
-require "json"
-require "digest"
+require "ctx_cli/command"
+require "ctx_cli/review"
+require "yaml"
+require "ipaddr"
+require "ctx_runner/evidence"
 require_relative "report"
 
 module Vxlan
@@ -16,107 +18,74 @@ module Vxlan
 
       # 返回零只代表建议生成完成，不代表问题已修复或候选配置已获批准。
       def run(argv)
-        options = {}
-        parser = OptionParser.new do |p|
-          p.banner = "用法：vxlan review --batch DIR [--output DIR]（离线生成建议，不执行配置）"
-          p.on("--fabric-policy FILE", "显式 Fabric/Leaf/Border/Spine 清单 YAML") { |value| options[:fabric_policy] = value }
-          p.on("--batch DIR", "已采集批次，含 evidence/*.json") { |value| options[:batch] = value }
-          p.on("--[no-]scripts", "可选导出配置建议，默认仅诊断") { |value| options[:scripts] = value }
-          p.on("--output DIR", "私有输出根目录，默认批次内 reviews") { |value| options[:output] = value }
-          p.on("-h", "--help", "查看帮助") { options[:help] = true }
+        command = CtxCli::Command.new(banner: "Usage: vxlan review --batch DIR [--output DIR] (generate recommendations offline without executing configuration)", out: @out) do |p, options|
+          p.on("--fabric-policy FILE", "Explicit Fabric/Leaf/Border/Spine inventory YAML") { |value| options[:fabric_policy] = value }
+          p.on("--batch DIR", "Collected batch containing evidence/*.json") { |value| options[:batch] = value }
+          p.on("--[no-]scripts", "Optionally export configuration suggestions; diagnostics only by default") { |value| options[:scripts] = value }
+          p.on("--output DIR", "Private output root; defaults to reviews inside the batch") { |value| options[:output] = value }
+          p.on("-h", "--help", "Show help") { options[:help] = true }
         end
-        rest = parser.parse(argv.dup)
-        return @out.puts(parser) || 0 if options[:help]
-        raise ArgumentError, "需要批次目录" unless rest.empty? && options[:batch]
-        batch = File.expand_path(options[:batch])
-        paths = Dir[File.join(batch, "evidence", "*.json")].sort
-        raise ArgumentError, "无设备报告" if paths.empty?
-        # 先校验所有输入，损坏文件不会留下看似完成的部分建议批次。
-        documents = paths.map do |path|
-          body = File.read(path)
-          document = JSON.parse(body)
-          validate(document)
-          [ path, body, document, Recommendations.new(document).call ]
+        CtxCli::Review.new(command: command, directory: "evidence", adapter: self, out: @out, error: @error).run(argv)
+      end
+
+      # 领域结构、建议和身份冲突必须在创建输出目录前全部校验。
+      def prepare(documents, options)
+        documents.each do |entry|
+          validate(entry[2])
+          entry << Recommendations.new(entry[2]).call
         end
         hosts = documents.map { |entry| entry[2]["device"]["host"] }
         names = documents.map { |entry| CLI::Report.device_basename(entry[2].fetch("device")) }
-        raise ArgumentError, "设备身份或输出名称重复" unless hosts.uniq == hosts && names.uniq == names
-        policy = options[:fabric_policy] && YAML.safe_load(File.read(options[:fabric_policy]), aliases: false)
+        raise ArgumentError, "Duplicate device identity or output name" unless hosts.uniq == hosts && names.uniq == names
+        policy = options[:fabric_policy] && YAML.safe_load(CtxCli::Input.read(path: options[:fabric_policy]), aliases: false)
         Vxlan::Fabric::Scope.new(policy) if policy
+        policy
+      end
+
+      # 公共入口完成预检后才调用发布；领域报告格式保持独立。
+      def publish(documents, options, batch:, context:)
         report = CLI::Report.new(options[:output] || File.join(batch, "reviews"), scripts: options[:scripts] == true)
-        report.build_review(documents, policy: policy)
-        @out.puts "建议已生成：#{report.directory}/summary.txt；#{documents.size} 台；未执行设备变更。"
-        0
-      rescue Psych::Exception, OptionParser::ParseError, ArgumentError, TypeError, KeyError, JSON::ParserError, SystemCallError, IOError => error
-        @error.puts "建议生成失败（#{error.class.name}）；请检查输入结构、目录权限和 --help；未执行设备变更。"
-        2
+        report.build_review(documents, policy: context)
+        "Recommendations generated: #{report.directory}/summary.txt; #{documents.size} devices; no device changes executed."
       end
 
       private
 
-      # 仅接受宿主保存的设备快照边界；缺少快照的失败采集仍可生成补采任务。
+      # 先校验公共证据外壳，再验证领域记录。
       def validate(document)
-        raise ArgumentError, "无设备身份" unless document.is_a?(Hash) && document["device"].is_a?(Hash) && %w[name host].all? { |key| document["device"][key].is_a?(String) }
-        host = document["device"]["host"]
-        raise ArgumentError, "目标地址须为规范主机地址" unless !host.include?("/") && IPAddr.new(host).to_s == host
-        snapshot = document["snapshot"]
-        raise ArgumentError, "无快照字段" unless document.key?("snapshot")
-        return if snapshot.nil?
-        raise ArgumentError, "快照结构错误" unless snapshot.is_a?(Hash) && snapshot["dimensions"].is_a?(Hash)
-        if snapshot.key?("target") && (!snapshot["target"].is_a?(Hash) || snapshot["target"]["host"] != host)
-          raise ArgumentError, "设备身份与采集目标不一致"
-        end
-        snapshot["dimensions"].each do |dimension, observation|
-          unless observation.is_a?(Hash) && %w[complete partial failed unsupported not_requested].include?(observation["status"]) && observation["records"].is_a?(Array) && observation["records"].all? { |record| record.is_a?(Hash) }
-            raise ArgumentError, "观测结构错误"
-          end
-          array_of_hashes(observation.fetch("issues", []))
-          observation["records"].each { |record| validate_record(record, dimension) }
-        end
-      end
-
-      # 校验规则读取的容器类型，错误消息不包含配置正文。
-      def array_of_hashes(value)
-        raise ArgumentError, "列表结构错误" unless value.is_a?(Array) && value.all? { |entry| entry.is_a?(Hash) }
-        value
-      end
-
-      # 映射值必须仍是记录，不能将损坏结构解释成空事实。
-      def hash_of_hashes(value)
-        raise ArgumentError, "映射结构错误" unless value.is_a?(Hash) && value.values.all? { |entry| entry.is_a?(Hash) }
-        value
+        CtxRunner::Evidence.validate(document) { |record, dimension| validate_record(record, dimension) }
       end
 
       # 在输出目录创建前验证所有会参与建议生成的嵌套字段。
       def validate_record(record, dimension)
         return unless dimension == "configuration"
-        array_of_hashes(record.fetch("review_findings", []))
+        CtxRunner::Evidence.array(record.fetch("review_findings", []))
         nve = record.fetch("nve", {})
-        raise ArgumentError, "NVE/VLAN 结构错误" unless nve.is_a?(Hash) && record.fetch("vlan_vnis", {}).is_a?(Hash)
-        hash_of_hashes(nve.fetch("members", {}))
-        hash_of_hashes(record.fetch("vrfs", {}))
-        hash_of_hashes(record.fetch("evpn", {})).each_value { |entry| array_of_hashes(entry.fetch("route_targets", [])) }
-        hash_of_hashes(record.fetch("interfaces", {})).each_value do |interface|
+        raise ArgumentError, "Invalid NVE/VLAN structure" unless nve.is_a?(Hash) && record.fetch("vlan_vnis", {}).is_a?(Hash)
+        CtxRunner::Evidence.map(nve.fetch("members", {}))
+        CtxRunner::Evidence.map(record.fetch("vrfs", {}))
+        CtxRunner::Evidence.map(record.fetch("evpn", {})).each_value { |entry| CtxRunner::Evidence.array(entry.fetch("route_targets", [])) }
+        CtxRunner::Evidence.map(record.fetch("interfaces", {})).each_value do |interface|
           addresses, bindings = interface.fetch("addresses", []), interface.fetch("acl_bindings", {})
           unless addresses.is_a?(Array) && addresses.all? { |address| address.is_a?(String) && address.include?("/") } && bindings.is_a?(Hash) && bindings.all? { |direction, name| %w[in out].include?(direction) && name.is_a?(String) }
-            raise ArgumentError, "接口结构错误"
+            raise ArgumentError, "Invalid interface structure"
           end
           addresses.each { |address| IPAddr.new(address) }
         end
         acls = record.fetch("acls", {})
-        raise ArgumentError, "ACL 结构错误" unless acls.is_a?(Hash)
+        raise ArgumentError, "Invalid ACL structure" unless acls.is_a?(Hash)
         acls.each_value do |entries|
-          array_of_hashes(entries).each do |entry|
+          CtxRunner::Evidence.array(entries).each do |entry|
             unless entry["sequence"].is_a?(Integer) && %w[permit deny remark].include?(entry["action"]) && entry["expression"].is_a?(String)
-              raise ArgumentError, "ACL 规则结构错误"
+              raise ArgumentError, "Invalid ACL rule structure"
             end
           end
         end
         groups = record.fetch("address_groups", {})
-        raise ArgumentError, "地址组结构错误" unless groups.is_a?(Hash)
+        raise ArgumentError, "Invalid address group structure" unless groups.is_a?(Hash)
         groups.each_value do |members|
           unless members.is_a?(Array) && members.all? { |member| member.is_a?(String) && member.include?("/") && IPAddr.new(member).ipv4? }
-            raise ArgumentError, "地址组成员错误"
+            raise ArgumentError, "Invalid address group members"
           end
         end
       end

data/lib/vxlan/cli.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "vxlan/version"
-require "ctx_cli/application"
+require "ctx_cli/router"
 
 module Vxlan
   # 命令入口按需加载采集或解析实现；核心库无需加载 CLI。
@@ -13,7 +13,7 @@ module Vxlan
           begin
             require_relative "cli/collect"
           rescue LoadError
-            error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
+            error.puts "collect requires a current net-connector with shared inventory filters; install the project dependencies."
             next 2
           end
           Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
@@ -31,12 +31,12 @@ module Vxlan
           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,
+      CtxCli::Router.new(name: "vxlan", version: Vxlan::VERSION, usage: USAGE,
         commands: commands, out: out, error: error).run(argv)
     end
 
     # 全局帮助不读取配置、环境文件或设备清单。
-    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
+    USAGE = "Usage: vxlan collect [options]  Read-only collection and reports\n       vxlan parse [options]    Parse offline files or stdin\n       vxlan review --batch DIR  Offline remediation recommendations\n       vxlan apply --plan FILE --item ID  Apply after interactive confirmation\n       vxlan --version\nUse vxlan collect --help, vxlan parse --help or vxlan review --help for options; --help-all for full conventions, --examples for examples.".freeze
     private_constant :USAGE
   end
 end

data/lib/vxlan/collection_plan.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "observation"
+require "ctx_parser/result"
 
 module Vxlan
   # 配置证据约束运行查询：明确未启用的功能才允许空回显或省略查询。