vxlan 0.4.1 → 0.5.0

data/lib/vxlan/cli/apply.rb

@@ -2,7 +2,9 @@
 
 require "optparse"
 require "ctx_cli/terminal"
+require "ctx_cli/input"
 require "json"
+require "ctx_runner/document"
 require "digest"
 require "ctx_runner/execution"
 require "ipaddr"
@@ -23,16 +25,16 @@ module Vxlan
       def read_configuration
         [ "terminal length 0", "terminal width 511" ].each { |command| write(command) }
         capture = CtxDriver::Reader.new(session: @native).read("show running-config")
-        raise IOError, "配置回读失败" unless capture.success?
+        raise IOError, "Configuration readback failed" unless capture.success?
         observation = Vxlan::Config.new.parse(capture.body, complete: true)
-        raise ArgumentError, "配置证据不完整" unless observation.complete? && observation.records.one?
-        JSON.parse(JSON.generate(observation.records.first))
+        raise ArgumentError, "Configuration evidence is incomplete" unless observation.complete? && observation.records.one?
+        CtxRunner::Document.call(observation.records.first)
       end
 
       # 每次只发一条命令；失败立即交还宿主，原始输出不进入终端和日志报告。
       def write(command)
         result = @native.execute_command(command.strip, output_sensitive: true)
-        raise IOError, "设备命令未确认" unless result.success? && result.steps.one?
+        raise IOError, "Device command is unconfirmed" unless result.success? && result.steps.one?
         true
       end
     end
@@ -50,44 +52,44 @@ module Vxlan
         @store, @execution = nil, nil
         options = { directory: File.join(Dir.pwd, "vxlan-executions"), port: 22 }
         parser = OptionParser.new do |p|
-          p.banner = "用法：vxlan apply --plan FILE --item ID [--env-file FILE]（必须真实终端明确确认）"
-          p.on("--plan FILE", "批次 plan.json，须有同目录 SHA256 校验文件") { |value| options[:plan] = value }
-          p.on("--item ID", "批次计划中明确选择一个增量，禁止批量执行") { |value| options[:item] = value }
-          p.on("--env-file FILE", "显式凭据文件，进程环境优先") { |value| options[:env_file] = value }
-          p.on("--directory DIR", "私有执行日志目录") { |value| options[:directory] = value }
-          p.on("--port N", Integer, "SSH 端口，默认 22") { |value| options[:port] = value }
-          p.on("-h", "--help", "查看帮助，不连接设备") { options[:help] = true }
+          p.banner = "Usage: vxlan apply --plan FILE --item ID [--env-file FILE] (requires explicit confirmation in an interactive terminal)"
+          p.on("--plan FILE", "Batch plan.json; requires a SHA256 checksum file in the same directory") { |value| options[:plan] = value }
+          p.on("--item ID", "Explicitly select one change from the batch plan; bulk execution is prohibited") { |value| options[:item] = value }
+          p.on("--env-file FILE", "Explicit credentials file; process environment takes precedence") { |value| options[:env_file] = value }
+          p.on("--directory DIR", "Private execution log directory") { |value| options[:directory] = value }
+          p.on("--port N", Integer, "SSH port, default 22") { |value| options[:port] = value }
+          p.on("-h", "--help", "Show help without connecting to devices") { options[:help] = true }
         end
         rest = parser.parse(argv.dup)
         return @out.puts(parser) || 0 if options[:help]
         terminal = CtxCli::Terminal.new(input: @input, out: @out)
         terminal.require_tty!(@error)
-        raise ArgumentError, "需要单个计划" unless rest.empty? && options[:plan] && options[:port].between?(1, 65_535)
-        body = File.read(options[:plan])
+        raise ArgumentError, "A single plan is required" unless rest.empty? && options[:plan] && options[:port].between?(1, 65_535)
+        body = CtxCli::Input.read(path: options[:plan])
         hash = Digest::SHA256.hexdigest(body)
         plan = CtxParser::Immutable.copy(select_plan(JSON.parse(body), options, hash))
         change = validate_plan(plan)
         host = plan.fetch("device").fetch("host")
-        @out.puts "目标：#{plan['device']['name']}（#{host}）；#{plan['scope']}；#{plan['title']}"
-        @out.puts "影响：#{plan['impact']}"
-        @out.puts Array(plan["prerequisites"]).map { |value| "条件：#{value}" }
-        @out.puts "计划 SHA256：#{hash}\n拟执行命令：\n#{change.commands.join("\n")}\n条件回退（不自动执行）：\n#{change.rollback.join("\n")}"
+        @out.puts "Target: #{plan['device']['name']}(#{host}); #{plan['scope']}; #{plan['title']}"
+        @out.puts "Impact: #{plan['impact']}"
+        @out.puts Array(plan["prerequisites"]).map { |value| "Prerequisite: #{value}" }
+        @out.puts "Plan SHA256: #{hash}\nProposed commands:\n#{change.commands.join("\n")}\nConditional rollback (not executed automatically):\n#{change.rollback.join("\n")}"
         token = "APPLY #{host} #{hash[0, 12]} #{options[:item]}"
-        confirmed = terminal.confirm(token: token, prompt: "确认业务策略及维护窗口后输入 #{token}；其他输入取消：")
-        return @out.puts("已取消，未连接设备。") || 1 unless confirmed
+        confirmed = terminal.confirm(token: token, prompt: "After confirming the service policy and maintenance window, enter #{token}; any other input cancels: ")
+        return @out.puts("Cancelled; no device connection opened.") || 1 unless confirmed
         settings = credentials(options)
         @store = Report.new(options[:directory])
         @execution = CtxRunner::Execution.new(plan: plan, change: change, journal: @store, plan_sha256: hash, item: options[:item])
         @execution.run { |operation| with_session(plan["device"], settings, &operation) }
-        @out.puts "配置回读已确认；仍需完成业务验收，未执行保存配置。日志：#{@store.directory}/execution.json"
+        @out.puts "Configuration readback confirmed; service acceptance is still required. Configuration was not saved to startup configuration. Log: #{@store.directory}/execution.json"
         0
       rescue Interrupt
         report_journal_failure
-        @error.puts "操作中断；#{@execution&.started? ? '设备效果可能不完整，请先回读核对，禁止重放。' : '尚未下发业务配置。'}"
+        @error.puts "Operation interrupted; #{@execution&.started? ? 'Device effects may be incomplete; read back and verify before proceeding. Do not replay commands.' : 'No service configuration was sent.'}"
         130
       rescue StandardError, LoadError => error
         report_journal_failure
-        @error.puts "下发停止（#{error.class.name}）；#{@execution&.started? ? '效果未完整确认，先回读，不自动重放或回退。' : '未下发业务配置；检查终端、计划、凭据及当前配置是否仍匹配。'}"
+        @error.puts "Apply stopped (#{error.class.name}); #{@execution&.started? ? 'Effects are not fully confirmed; read back first. No automatic replay or rollback.' : 'No service configuration was sent; check the terminal, plan, credentials and current configuration for consistency.'}"
         2
       end
 
@@ -98,20 +100,20 @@ module Vxlan
         id = options[:item]
         unless document.is_a?(Hash) && document["schema_version"] == 2 && document["platform"] == "cisco_nxos" && document["changes"].is_a?(Hash) &&
             id.is_a?(String) && id.match?(/\A[A-Za-z0-9_.-]+\z/) && document["changes"].key?(id)
-          raise ArgumentError, "需要批次计划及有效 --item"
+          raise ArgumentError, "A batch plan and valid --item are required"
         end
-        raise ArgumentError, "计划校验失败" unless File.read("#{options[:plan]}.sha256").strip == hash
+        raise ArgumentError, "Plan checksum verification failed" unless CtxCli::Input.read(path: "#{options[:plan]}.sha256", max_bytes: 128).strip == hash
         document["changes"].fetch(id)
       end
 
       # 不信任文件中的命令，重新从有限动作渲染并逐字核对，拒绝额外命令。
       def validate_plan(plan)
-        raise ArgumentError, "计划类型不匹配" unless plan.is_a?(Hash) && plan["schema_version"] == 1 && plan["platform"] == "cisco_nxos"
+        raise ArgumentError, "Plan type mismatch" unless plan.is_a?(Hash) && plan["schema_version"] == 1 && plan["platform"] == "cisco_nxos"
         host = plan.fetch("device").fetch("host")
-        raise ArgumentError, "目标地址无效" unless host.is_a?(String) && !host.include?("/") && IPAddr.new(host).to_s == host
-        raise ArgumentError, "配置指纹无效" unless plan["expected_config_sha256"].is_a?(String) && plan["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
+        raise ArgumentError, "Invalid target address" unless host.is_a?(String) && !host.include?("/") && IPAddr.new(host).to_s == host
+        raise ArgumentError, "Invalid configuration fingerprint" unless plan["expected_config_sha256"].is_a?(String) && plan["expected_config_sha256"].match?(/\A[0-9a-f]{64}\z/)
         change = ChangePlan.build(plan.fetch("change"))
-        raise ArgumentError, "计划命令被修改" unless change.commands == plan["commands"] && change.rollback == plan["rollback"]
+        raise ArgumentError, "Plan commands were modified" unless change.commands == plan["commands"] && change.rollback == plan["rollback"]
         change
       end
 
@@ -120,7 +122,7 @@ module Vxlan
         require "net/connector/config"
         env = Net::Connector::Config.new(name: "vxlan", env: @env, env_file: options[:env_file], **@discovery).load_environment.environment
         username = env["NC_CISCO_NXOS_USERNAME"] || env["NC_DEVICE_USERNAME"]
-        raise ArgumentError, "缺少设备用户名" unless username.is_a?(String) && !username.strip.empty?
+        raise ArgumentError, "Device username is missing" unless username.is_a?(String) && !username.strip.empty?
         { username: username, password: env["NC_CISCO_NXOS_PASSWORD"] || env["NC_DEVICE_PASSWORD"], enable_password: env["NC_ENABLE_PASSWORD"],
           port: options[:port], host_key_policy: "strict", command_timeout: 60, login_timeout: 15 }
       end
@@ -137,7 +139,7 @@ module Vxlan
       # 公共执行器保存失败状态；CLI 只呈现持久性尚未确认的诊断。
       def report_journal_failure
         return unless @execution&.journal_failed?
-        @error.puts "执行日志收尾未确认；保留已有检查点，禁止据此重放配置。"
+        @error.puts "Execution log finalization is unconfirmed; existing checkpoints retained. Do not replay configuration based on this state."
       rescue StandardError, Interrupt
         nil
       end

data/lib/vxlan/cli/collect.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
+require "ctx_cli/collection"
 require "vxlan"
 require "ctx_runner/batch"
-require "ctx_cli/collection"
 require_relative "options"
 require_relative "report"
 require_relative "connector"
@@ -34,7 +34,7 @@ module Vxlan
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "联网采集需要 net-connector >= 0.17.1；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
+        raise LoadError, "Online collection requires net-connector >= 0.18.0; add it to the host Gemfile or run gem install net-connector", cause: nil
       end
 
       # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
@@ -68,18 +68,26 @@ module Vxlan
         end
         unless @executor
           require "net/connector/resources"
-          Net::Connector::Resources.prepare!(parallel: [ devices.size, options.values.fetch("parallel") ].min)
+          begin
+            Net::Connector::Resources.prepare!(parallel: [ devices.size, options.values.fetch("parallel") ].min)
+          rescue ArgumentError
+            raise CtxCli::Collection::Error, "Insufficient local file descriptor limit; raise the terminal ulimit -n or lower --parallel. Stopped without connecting to devices.", cause: nil
+          end
         end
         credentials
       end
 
-      def report(options) = Report.new(options.values.fetch("directory"), scripts: options.flags[:scripts] == true)
+      def report(options)
+        Report.new(options.values.fetch("directory"), scripts: options.flags[:scripts] == true)
+      rescue ArgumentError
+        raise CtxCli::Collection::Error, "Invalid report directory; use a real private directory with mode 0700 and check its path.", cause: nil
+      end
       def after_collect(report, options) = report.review_collected_fabric(options.fabric_policy)
 
       # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
       def credentials!(options)
         username = secret(options, "NC_CISCO_NXOS_USERNAME") || secret(options, "NC_DEVICE_USERNAME")
-        raise ArgumentError, "请设置 NC_DEVICE_USERNAME 或 NC_CISCO_NXOS_USERNAME；密码可通过环境或 SSH key/agent 提供" unless username
+        raise CtxCli::Collection::Error, "Set NC_DEVICE_USERNAME or NC_CISCO_NXOS_USERNAME; provide a password through the environment or use an SSH key/agent" unless username
         options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
           password: secret(options, "NC_CISCO_NXOS_PASSWORD") || secret(options, "NC_DEVICE_PASSWORD"), enable_password: secret(options, "NC_ENABLE_PASSWORD"))
       end

data/lib/vxlan/cli/options.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require "ctx_cli/collection"
+require "ctx_cli/input"
 require "optparse"
 require "ctx_cli/options"
 require "ctx_cli/terminal"
-require "ctx_cli/initialization"
+require "ctx_cli/initializer"
+gem "net-connector", "~> 0.18.0"
 require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
@@ -26,7 +29,7 @@ module Vxlan
         @explicit_config, @explicit_env_file = config, env_file
         @overrides, @flags = {}, {}
         @parser = parser
-        @parser.parse!(argv.dup).tap { |rest| raise ArgumentError, "不接受位置参数" unless rest.empty? }
+        @parser.parse!(argv.dup).tap { |rest| raise ArgumentError, "Positional arguments are not accepted" unless rest.empty? }
       end
 
       # 帮助和范例只打印文本，不读取文件或加载可选网络依赖。
@@ -34,12 +37,12 @@ module Vxlan
         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}"
+            @out.puts "Environment defaults: VXLAN_CONFIG, VXLAN_FABRIC, VXLAN_PARALLEL (or NC_PARALLEL), VXLAN_DIRECTORY."
+            @out.puts "Credentials: NC_DEVICE_USERNAME / NC_DEVICE_PASSWORD, or NC_CISCO_NXOS_USERNAME / NC_CISCO_NXOS_PASSWORD; optional NC_ENABLE_PASSWORD."
+            @out.puts "Precedence: CLI > process environment > YAML > .env > built-in defaults. YAML/.env paths are relative to their source directory; CLI paths are relative to the startup directory. Default reports: #{@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"
+          @out.puts "Common examples (replace addresses with actual inventory addresses):\n  Initialize missing files and exit:\n    #{@command} --init --non-interactive\n  Preview filtered inventory:\n    #{@command} --host 192.0.2.10 --plan\n  Select devices by name:\n    #{@command} --name leaf --exclude-name spare -p 4\n  Automated collection summary:\n    #{@command} --dimensions configuration,nve_peers --json --no-progress"
         else
           return false
         end
@@ -49,7 +52,7 @@ module Vxlan
       # 自动化拒绝强制问答；帮助分支无需检查终端或消费输入。
       def validate_interaction!(input:, error:)
         if flags[:interactive] && !CtxCli::Terminal.tty?(input, error)
-          raise ArgumentError, "--interactive 需要交互终端；自动化请使用 --init --non-interactive"
+          raise CtxCli::Collection::Error, "--interactive requires an interactive terminal; use --init --non-interactive for automation"
         end
       end
 
@@ -64,7 +67,7 @@ module Vxlan
         @environment = @files.environment
         @config, @env_file = @files.config, @files.env_file
       rescue LoadError
-        raise LoadError, "采集配置需要 net-connector >= 0.17.1；读取 .env 还需要 dotenv", cause: nil
+        raise LoadError, "Collection configuration requires net-connector >= 0.18.0; reading .env also requires dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
@@ -72,7 +75,7 @@ module Vxlan
         @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?
+        raise ArgumentError, "YAML accepts only public configuration fields" 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")
@@ -90,14 +93,14 @@ module Vxlan
         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)
+          raise ArgumentError, "fabric_policy must be a path" unless values["fabric_policy"].is_a?(String)
+          policy = YAML.safe_load(CtxCli::Input.read(path: 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
+        raise ArgumentError, "Invalid YAML or disallowed types", cause: nil
       end
 
       # 对外只列来源路径和字段归属，不携带环境文件的值。
@@ -154,10 +157,10 @@ module Vxlan
         template = template.lines("\n").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|
-          status = CtxCli::Initialization.new(prefix: ".vxlan-init-").create(path: path, contents: body)
-          @out.puts "#{status == :created ? '已创建' : '已保留'}：#{path}"
+          status = CtxCli::Initializer.new(prefix: ".vxlan-init-").create(path: path, contents: body)
+          @out.puts "#{status == :created ? 'created' : 'preserved'}: #{path}"
         end
-        @out.puts "请检查配置及凭据后再次运行；本次未读取清单、未连接设备。"
+        @out.puts "Check configuration and credentials, then run again; inventory was not read and no devices were connected."
       end
 
       # 默认仅在真实终端提供初始化选择；自动化从不消费 stdin。
@@ -167,20 +170,20 @@ module Vxlan
         return false unless @files.missing?
         terminal = CtxCli::Terminal.new(input: input, out: error)
         if terminal.tty? && flags[:interactive] != false
-          answer = terminal.question("配置不存在：#{config}；是否创建配置与环境模板？[y/N] ")
+          answer = terminal.question("Configuration does not exist: #{config}; create configuration and environment templates? [y/N] ")
           if answer&.match?(/\Ay(?:es)?\z/i)
             initialize_files
             return true
           end
         end
-        raise ArgumentError, "配置不存在：#{config}；请执行 --init 后填写设备，或使用 --config 指定配置"
+        raise ArgumentError, "Configuration does not exist: #{config}; run --init and fill in devices, or select configuration with --config"
       end
 
       # 公开配置输出与实际清单复用身份预检，不读取远端清单。
       def normalize_devices(rows)
-        raise ArgumentError, "devices 须为数组" unless rows.is_a?(Array)
+        raise ArgumentError, "devices must be an array" 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
+        raise ArgumentError, "Device inventory contains duplicate management addresses" unless targets.map { |row| row.fetch("host") }.uniq.size == targets.size
         targets
       end
 
@@ -209,20 +212,20 @@ module Vxlan
       # 设备身份只接受公开字段，拒绝隐藏在 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"
+          raise ArgumentError, "devices accepts only host, name and model; host must be a single IP address"
         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?) }
+        %w[name model].each { |key| raise ArgumentError, "Device #{key} must be a nonempty string" 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
+        raise ArgumentError, "Invalid device host", cause: nil
       end
 
       # 显式声明短参数与长参数；不提供难以发现的兼容缩写。
       def parser
         OptionParser.new do |p|
-          p.banner = "用法：#{@command} [选项]（只读 VXLAN 采集）"
-          CtxCli::Options.configuration(p, parallel_help: "设备并发 1～500；继承 NC_PARALLEL，未配置时 4") do |key, value|
+          p.banner = "Usage: #{@command} [options] (read-only VXLAN collection)"
+          CtxCli::Options.configuration(p, parallel_help: "Device concurrency 1 to 500; inherits NC_PARALLEL, defaults to 4") do |key, value|
             case key
             when :config then @explicit_config = File.expand_path(value, Dir.pwd)
             when :env_file then @explicit_env_file = File.expand_path(value, Dir.pwd)
@@ -230,9 +233,9 @@ module Vxlan
             when :parallel then @overrides["parallel"] = value
             end
           end
-          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) }
+          p.on("--fabric-policy FILE", "Explicit Fabric/Leaf/Border/Spine inventory YAML") { |v| @overrides["fabric_policy"] = File.expand_path(v) }
+          p.on("--fabric NAME", "Fabric identity for this collection") { |v| @overrides["fabric"] = v }
+          p.on("--dimensions LIST", "Comma-separated dimensions; see --help for supported values") { |v| @overrides["dimensions"] = list(v) }
           Net::Connector::Inventory::Filters.add_options(p) do |key, value|
             if value.is_a?(Array)
               (@overrides[key] ||= []).concat(value)
@@ -241,13 +244,13 @@ module Vxlan
             end
           end
           CtxCli::Options.initialization(p, flags)
-          p.on("--plan", "--inventory-only", "预览筛选清单，不连接设备") { flags[:inventory_only] = true }
-          p.on("--show-config", "查看公开有效配置") { flags[:show_config] = true }
+          p.on("--plan", "--inventory-only", "Preview filtered inventory without connecting to devices") { flags[:inventory_only] = true }
+          p.on("--show-config", "Show effective public configuration") { flags[:show_config] = true }
           CtxCli::Options.output(p, flags)
-          p.on("--[no-]scripts", "可选导出配置建议，默认仅诊断") { |value| flags[:scripts] = value }
+          p.on("--[no-]scripts", "Optionally export configuration suggestions; diagnostics only by default") { |value| flags[:scripts] = value }
           CtxCli::Options.information(p, flags)
-          p.separator "维度：#{Vxlan::Collector::COMMANDS.keys.join(', ')}"
-          p.separator "优先级：CLI > 进程环境 > YAML > .env > 内置默认值。退出码：0 完整/预览；1 未完成/无目标；2 参数/持久化错误；130 取消。"
+          p.separator "Dimensions: #{Vxlan::Collector::COMMANDS.keys.join(', ')}"
+          p.separator "Precedence: CLI > process environment > YAML > .env > built-in defaults. Exit codes: 0 complete/preview; 1 incomplete/no targets; 2 argument/persistence error; 130 cancelled."
         end
       end
 
@@ -256,40 +259,40 @@ module Vxlan
 
       # 先验证整批策略，避免在前面设备连接后才发现后面的非法配置。
       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? }
+        raise ArgumentError, "parallel must be 1 to 500" unless values["parallel"].is_a?(Integer) && (1..500).cover?(values["parallel"])
+        %w[fabric directory].each { |key| raise ArgumentError, "#{key} must be a nonempty string" 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 包含未知、重复或空维度"
+          raise ArgumentError, "dimensions contains unknown, duplicate or empty 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)
+          raise ArgumentError, "#{key} must be a mapping" if values.key?(key) && !values[key].is_a?(Hash)
         end
         if inline && (!values["devices"].empty? || values["netdisco_config"])
-          raise ArgumentError, "静态 devices、内嵌 Netdisco 和外部 netdisco_config 不能同时声明"
+          raise ArgumentError, "Static devices, inline Netdisco and external netdisco_config are mutually exclusive"
         end
         if values["netdisco_config"]
-          raise ArgumentError, "netdisco_config 须为配置路径，且不能同时声明 devices" unless values["netdisco_config"].is_a?(String) && !values["netdisco_config"].empty? && values["devices"].empty?
+          raise ArgumentError, "netdisco_config must be a configuration path and cannot be combined with 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
         Net::Connector::Inventory::Filters::LISTS.each_key { |key| values[key] = values.fetch(key, []) }
         Net::Connector::Inventory::Filters.selection(values)
         ssh = values["ssh"]
-        raise ArgumentError, "ssh 包含未知或敏感字段" unless ssh.is_a?(Hash) && (ssh.keys - SSH_FIELDS).empty?
+        raise ArgumentError, "ssh contains unknown or sensitive fields" 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"]))
+        raise ArgumentError, "host_key_policy must be strict or accept_new" unless %w[strict accept_new].include?(ssh["host_key_policy"])
+        %w[command_timeout login_timeout].each { |key| raise ArgumentError, "#{key} must be positive" unless ssh[key].is_a?(Numeric) && ssh[key].finite? && ssh[key].positive? }
+        raise ArgumentError, "port must be 1 to 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?
+          raise ArgumentError, "known_hosts must be a path" 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
+        raise ArgumentError, "hosts must contain IPs or CIDRs; addresses are not expanded and subnets are not scanned", cause: nil
       end
     end
   end

data/lib/vxlan/cli/parse.rb

@@ -20,18 +20,18 @@ module Vxlan
 
       # 参数错误与部分证据分开返回；默认只显示元数据，JSON 显式导出事实。
       def run(argv)
-        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 }
+        command = CtxCli::Command.new(banner: "Usage: #{@command} [options] (offline file or stdin)", defaults: { dimension: :configuration, complete: false }, out: @out) do |p, options|
+          p.on("--file FILE", "Read a file; defaults to stdin") { |v| options[:file] = v }
+          p.on("--dimension NAME", "configuration or a runtime dimension") { |v| options[:dimension] = v.to_sym }
+          p.on("--model NAME", "Device model") { |v| options[:model] = v }
+          p.on("--complete", "Declare input fully collected; missing parse evidence is still reported") { options[:complete] = true }
+          p.on("--json", "Output facts as JSON; may contain sensitive configuration") { options[:json] = true }
           CtxCli::Options.information(p, options)
-          p.separator "维度：#{Vxlan::Collector::COMMANDS.keys.join(', ')}"
+          p.separator "Dimensions: #{Vxlan::Collector::COMMANDS.keys.join(', ')}"
         end
         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])
+        raise ArgumentError, "Unknown dimension" unless Vxlan::Collector::COMMANDS.key?(options[:dimension])
 
         body = CtxCli::Input.read(path: options[:file], input: @input)
         observation = if options[:dimension] == :configuration
@@ -42,13 +42,13 @@ module Vxlan
         if options[:json]
           @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 健康。"
+          @out.puts "Dimensions: #{observation.name}; evidence: #{observation.status}; records: #{observation.records.size}"
+          @out.puts "Diagnostics: #{observation.issues.map { |issue| issue[:code] }.uniq.join(', ')}" unless observation.issues.empty?
+          @out.puts "Complete evidence does not establish Fabric health."
         end
         observation.complete? ? 0 : 1
       rescue OptionParser::ParseError, ArgumentError, SystemCallError, IOError => error
-        @output.diagnostic("离线解析参数或文件错误；使用 --help 查看参数", exception: error)
+        @output.diagnostic("Offline parsing argument or file error; use --help for options", exception: error)
         2
       end
     end

data/lib/vxlan/cli/report.rb

@@ -3,6 +3,7 @@
 require "json"
 require "time"
 require "ctx_runner/report"
+require "ctx_runner/document"
 require_relative "review/report"
 require_relative "review/fabric"
 
@@ -36,9 +37,9 @@ module Vxlan
         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)))
+        document = CtxRunner::Document.call(body)
         advice = report_advice(Recommendations.new(document).call)
-        document["recommendations"] = advice
+        document = document.merge("recommendations" => advice)
         json = JSON.pretty_generate(document) + "\n"
         prepare_directory(File.join(directory, "evidence"))
         publish("evidence/#{name}.json", json)
@@ -49,19 +50,19 @@ module Vxlan
       def finish(results, interrupted: false, requested: [], report_error: nil, execution_error: nil, output_error: nil)
         @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/；所有候选配置未执行。"
+          pending = summary.fetch("pending")
+          text = [ "VXLAN evidence: #{summary.fetch('status')}; completed #{summary.fetch('completed')} devices", "Categories: #{summary.fetch('counts')}", "Complete evidence does not establish Fabric health." ]
+          text << "Per-device diagnostics: devices/; candidate scripts: scripts/; no candidate configuration was executed."
           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]}"
+          text << "Batch report status: see summary.json; evidence status in text does not confirm report publication."
+          text << "Report error: #{summary['report_error']}" if summary["report_error"]
+          text << "Execution error: #{summary['execution_error']}" if summary["execution_error"]
+          text << "Progress output error: #{summary['output_error']['error_type']}; device results retained" if summary["output_error"]
+          summary.fetch("devices").each do |r|
+            saved = r["report_saved"] == true ? "saved" : "persistence unconfirmed"
+            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未采集" }
+          pending.each { |device| text << "#{device['host']}\t#{device['name']}\tnot collected" }
           text.join("\n") + "\n"
         end
       end
@@ -71,7 +72,6 @@ module Vxlan
       # 保持领域呈现接口，事务与恢复状态仅在公共报告中实现。
       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