vxlan 0.2.2 → 0.3.0

data/lib/vxlan/cli/options.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "yaml"
+require "ipaddr"
+require "fileutils"
+require "tempfile"
+
+module Vxlan
+  module CLI
+    # 采集入口的公开参数；凭据始终留在环境中，不传入解析库或 YAML。
+    class Options
+      FIELDS = %w[fabric fabric_policy devices netdisco inventory netdisco_config parallel directory dimensions ssh hosts exclude_hosts names exclude_names].freeze
+      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
+
+      PATH_FIELDS = %w[directory fabric_policy netdisco_config ssh.known_hosts netdisco.cache_directory netdisco.db_sslrootcert].freeze
+
+      # 文件发现由共享加载器负责；这里只保存调用入口和领域参数。
+      def initialize(argv, env:, out:, config: nil, env_file: nil, directory: File.join(Dir.pwd, "vxlans"), discovery: {}, command: "vxlan collect")
+        @process_environment, @out = env.to_h.dup, out
+        @directory, @command, @discovery = directory, command, discovery
+        @explicit_config, @explicit_env_file = config, env_file
+        @overrides, @flags = {}, {}
+        @parser = parser
+        @parser.parse!(argv.dup).tap { |rest| raise ArgumentError, "不接受位置参数" unless rest.empty? }
+      end
+
+      # 帮助和范例只打印文本，不读取文件或加载可选网络依赖。
+      def informational?
+        if flags[:help] || flags[:help_all]
+          @out.puts @parser
+          if flags[:help_all]
+            @out.puts "环境默认：VXLAN_CONFIG、VXLAN_FABRIC、VXLAN_PARALLEL（或 NC_PARALLEL）、VXLAN_DIRECTORY。"
+            @out.puts "凭据：NC_DEVICE_USERNAME / NC_DEVICE_PASSWORD，或 NC_CISCO_NXOS_USERNAME / NC_CISCO_NXOS_PASSWORD；可选 NC_ENABLE_PASSWORD。"
+            @out.puts "优先级：CLI > 进程环境 > YAML > .env > 内置默认值。YAML/.env 路径基于来源目录；CLI 路径基于启动目录。默认报告：#{@directory}"
+          end
+        elsif flags[:examples]
+          @out.puts "常用示例（地址须替换为实际清单地址）：\n  初始化缺失文件后退出：\n    #{@command} --init --non-interactive\n  预览筛选清单：\n    #{@command} --host 192.0.2.10 --plan\n  按名称选择设备：\n    #{@command} --name leaf --exclude-name spare -p 4\n  自动化采集摘要：\n    #{@command} --dimensions configuration,nve_peers --json --no-progress"
+        else
+          return false
+        end
+        true
+      end
+
+      # 自动化拒绝强制问答；帮助分支无需检查终端或消费输入。
+      def validate_interaction!(input:, error:)
+        if flags[:interactive] && !(input.tty? && error.tty?)
+          raise ArgumentError, "--interactive 需要交互终端；自动化请使用 --init --non-interactive"
+        end
+      end
+
+      # 只在采集/初始化时加载共享文件服务，不改写进程环境。
+      def load_environment
+        require "net/connector/config"
+        @files = Net::Connector::Config.new(name: "vxlan", env: @process_environment,
+          config: @explicit_config, env_file: @explicit_env_file, path_fields: PATH_FIELDS,
+          env_path_keys: %w[VXLAN_DIRECTORY NC_KNOWN_HOSTS ND_CACHE_DIRECTORY ND_DB_SSLROOTCERT],
+          path_literals: { "netdisco.db_sslrootcert" => [ "system" ], "ND_DB_SSLROOTCERT" => [ "system" ] }, **@discovery)
+        @files.load_environment(allow_missing: flags[:init])
+        @environment = @files.environment
+        @config, @env_file = @files.config, @files.env_file
+      rescue LoadError
+        raise LoadError, "采集配置需要 net-connector >= 0.16.0；读取 .env 还需要 dotenv", cause: nil
+      end
+
+      # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
+      def load
+        @files.load
+        @config, @env_file = @files.config, @files.env_file
+        data = Net::Connector::Config.merge(@files.data)
+        raise ArgumentError, "YAML 只接受公开配置字段" unless (data.keys - FIELDS).empty?
+        specific = @files.specific
+        if specific["devices"].is_a?(Array) && specific["devices"].any? && (specific.keys & %w[netdisco inventory netdisco_config]).empty?
+          data = data.except("netdisco", "inventory")
+        elsif specific["netdisco_config"] && (specific.keys & %w[netdisco inventory]).empty?
+          data = data.except("netdisco", "inventory")
+        end
+        defaults = { "fabric" => "default", "devices" => [], "parallel" => 4, "directory" => @directory,
+          "dimensions" => Vxlan::Collector::COMMANDS.keys.map(&:to_s), "ssh" => SSH_DEFAULTS }
+        dynamic = (data.keys & %w[netdisco inventory]).any?
+        process = environment_values(@files.process_environment, dynamic: dynamic)
+        file_defaults = environment_values(@files.file_environment, dynamic: dynamic,
+          higher: Net::Connector::Config.merge(data, process, @overrides))
+        @values = Net::Connector::Config.merge(defaults, file_defaults, data, process, @overrides)
+        validate!
+        netdisco_settings if dynamic_inventory?
+        @fabric_policy = nil
+        if values["fabric_policy"]
+          raise ArgumentError, "fabric_policy 须为路径" unless values["fabric_policy"].is_a?(String)
+          policy = YAML.safe_load(File.read(values["fabric_policy"]), aliases: false)
+          Vxlan::Fabric::Scope.new(policy)
+          @fabric_policy = CtxParser::Immutable.copy(policy)
+        end
+        self
+      rescue Psych::Exception
+        raise ArgumentError, "YAML 无效或包含不允许的类型", cause: nil
+      end
+
+      # 对外只列来源路径和字段归属，不携带环境文件的值。
+      def sources = @files.sources
+
+      # 来源选择与默认参数分开；共同 Netdisco 配置不会改写显式静态清单。
+      def dynamic_inventory? = values["netdisco_config"] || values.key?("netdisco") || values.key?("inventory")
+
+      # 凭据使用本批有效环境，公共环境值按相同优先级交给原生 Settings。
+      def netdisco_settings
+        return @netdisco_settings if @netdisco_settings
+        require "net/connector/netdisco"
+        schema = Net::Connector::Netdisco::Config
+        sections = %w[netdisco inventory]
+        data = values["netdisco_config"] ? external_inventory_data : values.slice(*sections)
+        document = schema.parse_sections(data, sections: sections)
+        keys = schema.environment_keys
+        inventory_keys = schema.environment_keys(sections: sections)
+        defaults = @files.file_environment.slice(*inventory_keys).merge(document)
+        process = @files.process_environment.slice(*inventory_keys)
+        secrets = environment.reject { |key, _| keys.include?(key) || key == "NC_CONFIG" }
+        @inventory_public = schema.from_environment(defaults.merge(process), sections: sections)
+        @netdisco_settings = Net::Connector::Netdisco::Settings.new(env: secrets, defaults: defaults, overrides: process).for_run(mode: :inventory)
+      end
+
+      # 外部清单同样按文件来源解析路径，并在预检时固定本批配置。
+      def external_inventory_data
+        Net::Connector::Config.new(name: "backup", env: {}, directories: [], config: values.fetch("netdisco_config"),
+          path_fields: %w[netdisco.cache_directory netdisco.db_sslrootcert],
+          path_literals: { "netdisco.db_sslrootcert" => [ "system" ] }).load.data
+      end
+      private :external_inventory_data
+
+      # 展示外部清单的有效公开字段，预览与执行共用本批快照。
+      def public_values
+        return values unless values["netdisco_config"]
+        netdisco_settings
+        values.merge("inventory_configuration" => @inventory_public)
+      end
+
+      # 只初始化缺失文件，排他创建防止覆盖现场配置；不读取设备清单。
+      def initialize_files
+        template = File.read(File.join(__dir__, "templates/vxlan.yml"))
+        @config, @env_file = @files.init_config, @files.init_env_file
+        @values = Net::Connector::Config.merge(YAML.safe_load(template), { "directory" => @directory, "parallel" => 4 },
+          environment_values(@files.file_environment), environment_values(@files.process_environment), @overrides)
+        validate!
+        # 公共 NC_PARALLEL 保持继承；只有本工具显式覆盖才写入 YAML。
+        parallel_source = [ @files.process_environment, @files.file_environment ].find do |source|
+          source["VXLAN_PARALLEL"] || source["NC_PARALLEL"]
+        end
+        overrides_parallel = @overrides.key?("parallel") || parallel_source&.fetch("VXLAN_PARALLEL", nil)
+        document = overrides_parallel ? values : values.reject { |key, _| key == "parallel" }
+        template = template.lines.select { |line| line.start_with?("#") }.join +
+          Net::Connector::Config.dump(document, name: "vxlan", path: config)
+        { config => template, env_file => File.read(File.join(__dir__, "templates/env.example")) }.each do |path, body|
+          FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+          begin
+            Tempfile.create([ ".vxlan-init-", ".tmp" ], File.dirname(path)) do |file|
+              file.chmod(0o600)
+              file.write(body)
+              file.flush
+              file.fsync
+              File.link(file.path, path)
+            end
+            @out.puts "已创建：#{path}"
+          rescue Errno::EEXIST
+            @out.puts "已保留：#{path}"
+          end
+        end
+        @out.puts "请检查配置及凭据后再次运行；本次未读取清单、未连接设备。"
+      end
+
+      # 默认仅在真实终端提供初始化选择；自动化从不消费 stdin。
+      def missing?(input:, error:)
+        @files.load
+        @config, @env_file = @files.config, @files.env_file
+        return false unless @files.missing?
+        if input.tty? && error.tty? && flags[:interactive] != false
+          error.print "配置不存在：#{config}；是否创建配置与环境模板？[y/N] "
+          error.flush
+          if input.gets&.strip&.match?(/\Ay(?:es)?\z/i)
+            initialize_files
+            return true
+          end
+        end
+        raise ArgumentError, "配置不存在：#{config}；请执行 --init 后填写设备，或使用 --config 指定配置"
+      end
+
+      # 公开配置输出与实际清单复用身份预检，不读取远端清单。
+      def normalize_devices(rows)
+        raise ArgumentError, "devices 须为数组" unless rows.is_a?(Array)
+        targets = rows.map { |row| normalize_device(row) }
+        raise ArgumentError, "设备清单包含重复管理地址" unless targets.map { |row| row.fetch("host") }.uniq.size == targets.size
+        targets
+      end
+
+      private
+
+      # 环境值只映射公开字段；非法低优先级值可以被更高层覆盖，最终统一校验。
+      def environment_values(source, dynamic: false, higher: {})
+        result = {}
+        { "VXLAN_FABRIC" => "fabric", "VXLAN_DIRECTORY" => "directory" }.each do |key, field|
+          result[field] = source[key] if source.key?(key)
+        end
+        parallel = source["VXLAN_PARALLEL"] || source["NC_PARALLEL"]
+        result["parallel"] = Integer(parallel, exception: false) || parallel if parallel
+        ssh = {}
+        { "NC_HOST_KEY_POLICY" => "host_key_policy", "NC_KNOWN_HOSTS" => "known_hosts" }.each do |key, field|
+          ssh[field] = source[key] if source.key?(key)
+        end
+        result["ssh"] = ssh if ssh.any?
+        if dynamic
+          require "net/connector/netdisco/config"
+          result.merge!(Net::Connector::Netdisco::Config.from_environment(source, sections: %w[netdisco inventory], higher: higher))
+        end
+        result
+      end
+
+      # 设备身份只接受公开字段，拒绝隐藏在 YAML 中的密码或连接参数。
+      def normalize_device(row)
+        unless row.is_a?(Hash) && (row.keys - %w[host name model]).empty? && row["host"].is_a?(String) && !row["host"].include?("/")
+          raise ArgumentError, "devices 仅接受 host、name、model，host 须为单个 IP"
+        end
+        host = IPAddr.new(row.fetch("host")).to_s
+        %w[name model].each { |key| raise ArgumentError, "设备 #{key} 须为非空字符串" if row.key?(key) && !row[key].nil? && (!row[key].is_a?(String) || row[key].strip.empty?) }
+        { "host" => host, "name" => row["name"] || host, "model" => row["model"] }.freeze
+      rescue IPAddr::Error
+        raise ArgumentError, "设备 host 无效", cause: nil
+      end
+
+      # 显式声明短参数与长参数；不提供难以发现的兼容缩写。
+      def parser
+        OptionParser.new do |p|
+          p.banner = "用法：#{@command} [选项]（只读 VXLAN 采集）"
+          p.on("--config FILE", "最高优先级 YAML，叠加系统/用户/脚本/工作目录配置") { |v| @explicit_config = File.expand_path(v) }
+          p.on("--env-file FILE", "最高优先级环境文件；进程环境仍优先") { |v| @explicit_env_file = File.expand_path(v) }
+          p.on("-p", "--parallel N", Integer, "设备并发 1～500；继承 NC_PARALLEL，未配置时 4") { |v| @overrides["parallel"] = v }
+          p.on("--directory DIR", "按设备保存报告的目录") { |v| @overrides["directory"] = File.expand_path(v) }
+          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)) }
+          end
+          p.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { flags[:init] = true }
+          p.on("--interactive", "缺少配置时询问是否创建；要求真实终端") { flags[:interactive] = true }
+          p.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { flags[:interactive] = false }
+          p.on("--plan", "--inventory-only", "预览筛选清单，不连接设备") { flags[:inventory_only] = true }
+          p.on("--show-config", "查看公开有效配置") { flags[:show_config] = true }
+          p.on("--json", "stdout 输出 JSON；默认显示可读摘要") { flags[:json] = true }
+          p.on("--quiet", "--no-progress", "关闭 stderr 进度，可配合 --json") { flags[:quiet] = true }
+          p.on("--[no-]scripts", "可选导出配置建议，默认仅诊断") { |value| flags[:scripts] = value }
+          p.on("--verbose", "显示逐台结果及安全命令事件") { flags[:verbose] = true }
+          p.on("-h", "--help", "查看选项帮助") { flags[:help] = true }
+          p.on("--help-all", "查看全部选项、路径与环境约定") { flags[:help_all] = true }
+          p.on("--examples", "查看常用命令范例，不执行任务") { flags[:examples] = true }
+          p.separator "维度：#{Vxlan::Collector::COMMANDS.keys.join(', ')}"
+          p.separator "优先级：CLI > 进程环境 > YAML > .env > 内置默认值。退出码：0 完整/预览；1 未完成/无目标；2 参数/持久化错误；130 取消。"
+        end
+      end
+
+      # 列表中的空项属于输入错误，不能被静默删掉。
+      def list(value)
+        values = value.split(",", -1).map(&:strip)
+        raise ArgumentError, "列表不能有空项" if values.any?(&:empty?)
+        values
+      end
+
+      # 先验证整批策略，避免在前面设备连接后才发现后面的非法配置。
+      def validate!
+        raise ArgumentError, "parallel 须为 1～500" unless values["parallel"].is_a?(Integer) && (1..500).cover?(values["parallel"])
+        %w[fabric directory].each { |key| raise ArgumentError, "#{key} 须为非空字符串" unless values[key].is_a?(String) && !values[key].strip.empty? }
+        dimensions = values["dimensions"]
+        unless dimensions.is_a?(Array) && dimensions.any? && dimensions.all?(String) && dimensions.uniq == dimensions && (dimensions - Vxlan::Collector::COMMANDS.keys.map(&:to_s)).empty?
+          raise ArgumentError, "dimensions 包含未知、重复或空维度"
+        end
+        values["devices"] = normalize_devices(values["devices"])
+        inline = %w[netdisco inventory].any? { |key| values.key?(key) }
+        %w[netdisco inventory].each do |key|
+          raise ArgumentError, "#{key} 须为映射" if values.key?(key) && !values[key].is_a?(Hash)
+        end
+        if inline && (!values["devices"].empty? || values["netdisco_config"])
+          raise ArgumentError, "静态 devices、内嵌 Netdisco 和外部 netdisco_config 不能同时声明"
+        end
+        if values["netdisco_config"]
+          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) } }
+        ssh = values["ssh"]
+        raise ArgumentError, "ssh 包含未知或敏感字段" unless ssh.is_a?(Hash) && (ssh.keys - SSH_FIELDS).empty?
+        ssh = SSH_DEFAULTS.merge(ssh)
+        raise ArgumentError, "host_key_policy 须为 strict 或 accept_new" unless %w[strict accept_new].include?(ssh["host_key_policy"])
+        %w[command_timeout login_timeout].each { |key| raise ArgumentError, "#{key} 须为正数" unless ssh[key].is_a?(Numeric) && ssh[key].finite? && ssh[key].positive? }
+        raise ArgumentError, "port 须为 1～65535" if ssh.key?("port") && (!ssh["port"].is_a?(Integer) || !(1..65535).cover?(ssh["port"]))
+        if ssh.key?("known_hosts")
+          raise ArgumentError, "known_hosts 须为路径" unless ssh["known_hosts"].is_a?(String) && !ssh["known_hosts"].empty?
+          ssh["known_hosts"] = File.expand_path(ssh["known_hosts"], Dir.pwd)
+        end
+        values["ssh"] = ssh
+        values["directory"] = File.expand_path(values["directory"], Dir.pwd)
+      rescue IPAddr::Error
+        raise ArgumentError, "hosts 须为 IP 或 CIDR，不展开地址、不扫描网段", cause: nil
+      end
+    end
+  end
+end

data/lib/vxlan/cli/parse.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "time"
+require "vxlan"
+
+module Vxlan
+  module CLI
+    # 离线解析显式提供的文件或 stdin，不自行假定传输完整。
+    class Parse
+      # 注入标准流，便于在宿主测试中验证无需网络的行为。
+      def initialize(out: $stdout, error: $stderr, input: $stdin, command: "vxlan parse")
+        @out, @error, @input, @command = out, error, input, command
+      end
+
+      # 参数错误与部分证据分开返回；默认只显示元数据，JSON 显式导出事实。
+      def run(argv)
+        options = { dimension: :configuration, complete: false }
+        parser = OptionParser.new do |p|
+          p.banner = "用法：#{@command} [选项]（离线文件或 stdin）"
+          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 }
+          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]
+        raise ArgumentError, "未知维度" unless Vxlan::Collector::COMMANDS.key?(options[:dimension])
+
+        body = options[:file] ? File.read(options[:file]) : @input.read
+        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)
+        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 查看参数"
+        2
+      end
+    end
+  end
+end

data/lib/vxlan/cli/report.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "tempfile"
+require "fileutils"
+require_relative "review/report"
+require_relative "review/fabric"
+
+module Vxlan
+  module CLI
+    # 宿主按批次保存事实；配置事实可能敏感，目录 0700、文件 0600。
+    class Report
+      include Review::Report
+      include Review::Fabric
+
+      attr_reader :directory
+
+      # 采集和离线审查共用稳定名称，保留 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
+
+      # 仅交付发布阶段，不保留底层异常正文或敏感报告内容。
+      class Error < IOError
+        attr_reader :relative, :phase
+
+        # 保留安全的发布阶段与提交状态，不携带底层异常正文。
+        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)
+      end
+
+      # 每台完成后立即原子保存，即使批次随后取消仍可读取已完成证据。
+      def write(result, snapshot: nil)
+        device = result.fetch(:device)
+        name = self.class.device_basename(device)
+        # 保存状态属于批次宿主；不能让正在发布的文件预先声明自身已保存。
+        body = result.reject { |key, _| key == :report_saved }.merge(snapshot: snapshot && snapshot.to_h)
+        document = JSON.parse(JSON.generate(serializable(body)))
+        advice = report_advice(Recommendations.new(document).call)
+        document["recommendations"] = advice
+        json = JSON.pretty_generate(document) + "\n"
+        prepare_directory(File.join(directory, "evidence"))
+        publish("evidence/#{name}.json", json)
+        write_review(document, basename: name, source: File.join(directory, "evidence", "#{name}.json"), source_sha256: Digest::SHA256.hexdigest(json), advice: advice)
+      end
+
+      # 摘要不嵌入配置事实，只汇总状态与诊断，供终端和自动化共用。
+      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?
+          end
+        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
+
+      # 临时文件与目标在同一目录，写入失败不发布半份报告。
+      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
+    end
+  end
+end