vxlan 0.2.2 → 0.3.0

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../../fabric/review"
+
+module Vxlan
+  module CLI
+    class Review
+      # Fabric 文本只呈现已有发现，不重新计算基线或混入下发决策。
+      module Fabric
+        # 相同事实合并展示；规则版本保持匹配顺序，完整证据由聚合计划保存。
+        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 为删除依据。", "" ]
+          inventory = audit[:inventory]
+          if inventory
+            lines << "覆盖：已纳入 #{inventory[:assigned].size} 台；未纳入 #{inventory[:unassigned].size} 台；缺证据 #{inventory[:missing].size} 台。"
+            inventory[:groups].each do |fabric, roles|
+              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('、')}" }
+              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]}"
+          end
+          audit[:findings].each_with_index do |finding, index|
+            lines.concat([ "", "[#{index + 1}] #{finding[:fabric]} / #{finding[:role] || '全 Fabric'} / #{finding[:vni] || '公共策略'} — #{finding[:title]}", "规则：#{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('、')}"
+              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}" ])
+              end
+              next
+            end
+            unless evidence.is_a?(Array) && evidence.all? { |row| row.is_a?(Hash) }
+              lines << JSON.pretty_generate(evidence)
+              next
+            end
+            grouped = evidence.group_by do |row|
+              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}"
+              end
+              [ row[:vlan] || row[:interface] || "公共", 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('、')}" ])
+            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.concat(rules.map { |rule| "    #{rule['action']} #{rule['expression']}" })
+              end
+            end
+          end
+          lines.join("\n") + "\n"
+        end
+
+        # 机器字段转换为运维读法，显式保留缺失和未知。
+        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]}"
+          elsif value.is_a?(Array)
+            value.empty? ? "未配置地址" : value.join("、")
+          elsif value.nil?
+            "未提供"
+          elsif value.is_a?(Hash)
+            JSON.generate(value)
+          else
+            value.to_s
+          end
+        end
+
+        # 实时收尾读取已经保存的事实；审查摘要交给采集摘要一起发布，避免相互覆盖。
+        def review_collected_fabric(policy)
+          sources = Dir[File.join(directory, "evidence", "*.json")].sort.map do |path|
+            body = File.read(path)
+            [ File.expand_path(path), body, JSON.parse(body) ]
+          end
+          build_review(sources, policy: policy, standalone: false) unless sources.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../../recommendations"
+require_relative "../../change_plan"
+
+module Vxlan
+  module CLI
+    class Review
+      # 与 topology 同序编排：先合并诊断，再发布设备报告、脚本、聚合计划和摘要。
+      module Report
+        # 所有比较先完成；每台设备只发布一次最终建议，不再写后回填 Fabric 差异。
+        def build_review(sources, policy: nil, standalone: true)
+          documents = sources.map { |entry| entry[2] }
+          @fabric_audit = policy && Vxlan::Fabric::Review.new(documents, policy).call
+          @fabric_text = @fabric_audit && fabric_text(@fabric_audit, documents)
+          entries = sources.map do |path, body, document, initial|
+            advice = initial || Recommendations.new(document).call
+            additions = @fabric_audit && @fabric_audit[:device_items][document["device"]["host"]]
+            advice = Recommendations.combine(advice, additions)
+            device = document.fetch("device")
+            basename = CLI::Report.device_basename(device)
+            write_review(document, basename: basename, source: path, source_sha256: Digest::SHA256.hexdigest(body), advice: advice)
+          end
+          finish_review(entries, source_batch: File.dirname(File.dirname(sources.first[0])), standalone: standalone)
+        end
+
+        # 配置和回退集中于每设备一份 cfg；有限类型动作汇总到批次计划，不接受 cfg 直接执行。
+        def write_review(document, basename:, source:, source_sha256:, advice: nil)
+          raise ArgumentError, "非法报告名称" 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,
+            source_sha256: source_sha256, script: nil, script_sha256: nil, plans: [], changes: {}, advice: advice }
+          config = Config::Evidence.complete_record(document)
+          config_sha256 = nil
+          advice[:items].each do |item|
+            next unless @scripts && config && item[:status] == "candidate" && item[:change]
+            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)
+            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] }
+            item[:plan_id] = id
+            entry[:plans] << id
+          end
+          candidates = advice[:items].select { |item| item[:status] == "candidate" && item[:commands].any? }
+          if @scripts && candidates.any?
+            script = script_text(candidates)
+            entry[:script] = "scripts/#{basename}.cfg"
+            entry[:script_sha256] = Digest::SHA256.hexdigest(script)
+            prepare_directory(File.join(directory, "scripts"))
+            publish(entry[:script], script)
+          end
+          prepare_directory(File.join(directory, "devices"))
+          publish(entry[:report], device_text(entry, document))
+          entry
+        end
+
+        # JSON 状态最后提交；中途失败保留未完成检查点和已经发布的事实。
+        def finish_review(entries, source_batch:, standalone: true)
+          counts = entries.each_with_object(Hash.new(0)) { |entry, total| entry[:counts].each { |key, count| total[key] += count } }
+          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
+          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"
+          summary[:plan_sha256] = Digest::SHA256.hexdigest(body)
+          publish("plan.json", body)
+          publish("plan.json.sha256", summary[:plan_sha256] + "\n")
+          events = public_entries.map { |entry| JSON.generate(event: "device_reviewed", reviewed_at: Time.now.utc.iso8601(6), host: entry[:device]["host"], source_sha256: entry[:source_sha256], counts: entry[:counts], report: entry[:report], script: entry[:script], executed: false) }
+          publish("events.jsonl", events.join("\n") + (events.empty? ? "" : "\n"))
+          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
+          end
+          @review_summary, @review_text = summary.merge(status: "complete"), text
+          @review_summary
+        end
+
+        private
+
+        # 默认只输出诊断和核查步骤；命令和动作只在 --scripts 时保留。
+        def report_advice(advice)
+          return advice if @scripts
+          advice.merge(items: advice[:items].map { |item| item.reject { |key, _| %i[change template].include?(key) }.merge(commands: [], rollback: []) })
+        end
+
+        # 每项包含作用域、条件、命令及注释化回退，不将多项当成原子变更。
+        def script_text(items)
+          lines = [ "! 候选配置，未执行；先审阅同名 devices/*.txt；禁止整批直接粘贴。", "! apply 只读取 plan.json 中明确选择的单项，不执行本 cfg。" ]
+          items.each do |item|
+            lines.concat([ "", "! #{item[:scope]} / #{item[:title]}", "! 计划项：#{item[:plan_id] || '仅审阅草稿，不支持交互执行'}" ])
+            lines.concat(item[:prerequisites].map { |condition| "! 条件：#{condition}" })
+            lines.concat(item[:commands])
+            lines << "! 条件回退（不自动执行）："
+            lines.concat(item[:rollback].map { |command| "! #{command}" })
+            lines << "! 核查：#{item[:verify].join(' ; ')}"
+          end
+          lines.join("\n") + "\n"
+        end
+
+        # 文本按设备、证据、问题、动作顺序组织，完整跨设备证据位于聚合计划。
+        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"]
+          configuration_time = document.dig("snapshot", "dimensions", "configuration", "evidence", 0, "observed_at")
+          lines << "配置证据时间：#{configuration_time}" if configuration_time
+          lines << "当前规则未命中；不代表网络健康。" 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]}" ])
+            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"
+            if item[:plan_id]
+              lines << "交互计划项：#{item[:plan_id]}"
+              lines << "在批次目录运行：vxlan apply --plan plan.json --item #{item[:plan_id]}"
+            end
+            { prerequisites: "适用条件", blockers: "待决信息", commands: "候选配置（未执行）", rollback: "条件回退", verify: "只读核查", template: "待补模板（不可执行）" }.each do |key, title|
+              values = item[key] || []
+              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?
+          end
+          lines.join("\n") + "\n"
+        end
+
+        # 总览先给计数和入口，再给跨设备差异，详细命令只在设备报告/脚本中展示。
+        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 选择单项、交互确认、重读配置并核对指纹；无自动批量执行。", "" ]
+          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} 项" ])
+          end
+          lines.concat([ "", @fabric_text ]) if @fabric_text
+          lines.join("\n") + "\n"
+        end
+      end
+    end
+  end
+end

data/lib/vxlan/cli/review.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "digest"
+require_relative "report"
+
+module Vxlan
+  module CLI
+    # 只读打开已有批次，生成独立建议批次；不加载凭据或建立设备连接。
+    class Review
+      # 注入输出流，离线批次可通过 CLI 或宿主调用。
+      def initialize(out: $stdout, error: $stderr)
+        @out, @error = out, error
+      end
+
+      # 返回零只代表建议生成完成，不代表问题已修复或候选配置已获批准。
+      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 }
+        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 ]
+        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)
+        Vxlan::Fabric::Scope.new(policy) if policy
+        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
+      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
+      end
+
+      # 在输出目录创建前验证所有会参与建议生成的嵌套字段。
+      def validate_record(record, dimension)
+        return unless dimension == "configuration"
+        array_of_hashes(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|
+          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, "接口结构错误"
+          end
+          addresses.each { |address| IPAddr.new(address) }
+        end
+        acls = record.fetch("acls", {})
+        raise ArgumentError, "ACL 结构错误" unless acls.is_a?(Hash)
+        acls.each_value do |entries|
+          array_of_hashes(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 规则结构错误"
+            end
+          end
+        end
+        groups = record.fetch("address_groups", {})
+        raise ArgumentError, "地址组结构错误" 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, "地址组成员错误"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vxlan/cli/templates/env.example

@@ -0,0 +1,12 @@
+# 已有进程环境优先；密码中的 #、$ 请用单引号包裹。
+# NC_DEVICE_USERNAME=operator
+# NC_DEVICE_PASSWORD='replace-me'
+# NC_ENABLE_PASSWORD='replace-me'
+# 可用 SSH key/agent 时不要求密码；用户名必须明确。
+# NC_CISCO_NXOS_USERNAME=operator
+# NC_CISCO_NXOS_PASSWORD='replace-me'
+# VXLAN_CONFIG=vxlan.yml
+# VXLAN_FABRIC=default
+# VXLAN_PARALLEL=4
+# VXLAN_DIRECTORY=vxlans
+# 使用 Netdisco 时，其凭据遵循 net-connector 的 ND_* 环境约定。

data/lib/vxlan/cli/templates/vxlan.yml

@@ -0,0 +1,32 @@
+# 公开配置；凭据仅在环境中。CLI > 进程环境 > YAML > .env > 默认。
+fabric: default
+# 并发默认继承公共 NC_PARALLEL；仅需独立覆盖时设置 parallel。
+# parallel: 4
+directory: vxlans
+# 默认采集全部维度；大表可以按需启用，单设备命令始终顺序执行。
+dimensions:
+  - configuration
+  - cdp_neighbors
+  - nve_peers
+  - nve_vnis
+  - bgp_neighbors
+  - ospf_neighbors
+  - vpc
+  - interfaces
+  - port_channels
+  - mac_addresses
+  - l2route_macs
+  - l2route_mac_ips
+ssh:
+  host_key_policy: strict
+  command_timeout: 60
+  login_timeout: 15
+# 只操作此处明确列出的设备，不扫描。替换为实际设备后取消注释。
+devices: []
+#  - host: 192.0.2.10
+#    name: LEAF-01
+#    model: N9K-C93180YC-FX
+#  - host: 192.0.2.11
+#    name: LEAF-02
+# 可选：复用 net-connector 的 Netdisco YAML；与非空 devices 互斥。
+# netdisco_config: /path/to/net-connector/examples/backup.yml

data/lib/vxlan/cli.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "vxlan/version"
+
+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
+    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
+  end
+end

data/lib/vxlan/collector.rb

@@ -18,36 +18,19 @@ module Vxlan
 
     # 通过调用方持有的连接器顺序采集请求维度。
     def collect(connector:, target:, fabric_key:, model: nil, dimensions: COMMANDS.keys)
-      raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
-
-      unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions && (dimensions - COMMANDS.keys).empty?
-        raise ArgumentError, "Unknown or duplicate VXLAN dimensions"
-      end
-      target = CtxParser::Immutable.copy(target)
-      fabric_key = CtxParser::Immutable.copy(fabric_key)
-      dimensions = dimensions.dup.freeze
-      raise ArgumentError, "VXLAN requires Cisco NX-OS" unless connector.platform.to_s == "cisco_nxos"
-      profile = ParserRegistry.fetch(connector.platform, model: model)
+      target, fabric_key, dimensions, profile = request(target, fabric_key, dimensions, connector.platform, model)
 
       observations = {}
-      session_finished = false
+      session_started = session_finished = false
       begin
         connector.open do |session|
-          reader = CtxDriver::Reader.new(session: session, clock: @clock)
-          if (code = prepare_terminal(reader))
-            dimensions.each { |name| observations[name] = failure(name, code) }
-            observations[:collection] = failure(:collection, code)
+          if session_started
+            dimensions.each { |name| observations[name] ||= failure(name, :session_reentered) }
+            observations[:collection] = failure(:collection, :session_reentered)
             next
           end
-          dimensions.each do |name|
-            config = observations[:configuration]
-            if name == :vpc && !reader.failure && unconfigured?(name, config)
-              observations[name] = Observation.new(name: name, status: :complete, completed_at: @clock.call,
-                issues: [ { code: :vpc_not_configured } ])
-            else
-              observations[name] = collect_observation(reader, name, config, profile)
-            end
-          end
+          session_started = true
+          observations.merge!(read_dimensions(session, dimensions, profile))
           session_finished = true
         end
       rescue StandardError => error
@@ -57,6 +40,57 @@ module Vxlan
         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)
+      end
+      snapshot(target, fabric_key, observations)
+    end
+
+    # 借用已打开的会话；调用方负责连接和关闭，本方法不重连、不提权。
+    def collect_session(session:, target:, fabric_key:, platform: :cisco_nxos, model: nil, dimensions: COMMANDS.keys)
+      target, fabric_key, dimensions, profile = request(target, fabric_key, dimensions, platform, model)
+      snapshot(target, fabric_key, read_dimensions(session, dimensions, profile))
+    end
+
+    private
+
+    # 连接前固定请求数据，生命周期入口和借用会话入口共用相同校验。
+    def request(target, fabric_key, dimensions, platform, model)
+      raise ArgumentError, "Target must be a hash" unless target.is_a?(Hash)
+      unless dimensions.is_a?(Array) && dimensions.any? && dimensions.uniq == dimensions && (dimensions - COMMANDS.keys).empty?
+        raise ArgumentError, "Unknown or duplicate VXLAN dimensions"
+      end
+      raise ArgumentError, "VXLAN requires Cisco NX-OS" unless platform.to_s == "cisco_nxos"
+
+      [ CtxParser::Immutable.copy(target), CtxParser::Immutable.copy(fabric_key), dimensions.dup.freeze,
+        ParserRegistry.fetch(platform, model: model) ]
+    end
+
+    # 配置先于依赖它的运行查询读取；结果维度仍保持请求顺序。
+    def read_dimensions(session, dimensions, profile)
+      observations = {}
+      reader = CtxDriver::Reader.new(session: session, clock: @clock)
+      if (code = prepare_terminal(reader))
+        dimensions.each { |name| observations[name] = failure(name, code) }
+        observations[:collection] = failure(:collection, code)
+        return observations
+      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)
+          Observation.new(name: name, status: :complete, completed_at: @clock.call, issues: [ { code: :vpc_not_configured } ])
+        else
+          collect_observation(reader, name, config, profile)
+        end
+      end
+      dimensions.to_h { |name| [ name, observations.fetch(name) ] }
+    end
+
+    # 汇总证据完整性，不将查询成功解释为 Fabric 健康。
+    def snapshot(target, fabric_key, observations)
       status = if observations.values.all?(&:complete?)
         :complete
       elsif observations.values.any? { |value| %i[complete partial].include?(value.status) }
@@ -65,12 +99,9 @@ module Vxlan
         :failed
       end
       observations[:collection] ||= Observation.new(name: :collection, status: status, completed_at: @clock.call)
-      Snapshot.new(target: target,
-        fabric_key: fabric_key, dimensions: observations, observed_at: @clock.call)
+      Snapshot.new(target: target, fabric_key: fabric_key, dimensions: observations, observed_at: @clock.call)
     end
 
-    private
-
     # 采集设备回显前，禁用分页并归一化终端宽度。
     def prepare_terminal(reader)
       PREPARATION_COMMANDS.each do |command|

data/lib/vxlan/config/evidence.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Vxlan
+  class Config
+    # 设备快照只有唯一且完成配置审查的记录，才能用于缺失推导或变更计划。
+    module Evidence
+      # 外层采集成功不能覆盖记录层的部分解析或多份配置歧义。
+      def self.complete_record(document)
+        observation = document&.dig("snapshot", "dimensions", "configuration")
+        return unless observation && observation["status"] == "complete"
+        records = observation["records"]
+        return unless records.is_a?(Array) && records.one?
+        record = records.first
+        record if record.is_a?(Hash) && record["review_status"] == "complete"
+      end
+    end
+  end
+end