vxlan 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d262e92c5f60d01b4acfbe457e3c8b6466354f97414e14f9eff3e7cff2472519
-  data.tar.gz: 888b2ac2fac38db10ff2b0511861d46f007ccdf47ef98528c4b431734729439a
+  metadata.gz: 3711abc03628af1231bcd4698cff27e399db8b596a4d5e6ec46712bfc43f38fb
+  data.tar.gz: b57592e473ca59bfcf3c04a8abf6ed92a34bbd05a2d7d9e683be005437860f6d
 SHA512:
-  metadata.gz: 13cf4f4d999d82c923f0ae52143c271721ab23cdc24af24fef2bddfcac0f7f8b3517ad1686186b4961814cfbda65cd09e7ab50ceaee044fd4c71a6b8ccd17fa7
-  data.tar.gz: 7a63e8abd6569a3fc2de95089c42644f2a883d14fe4198f1c14eaa7a376ce14c213433da7950d7911e833a787f3fcda58f364c6ebdd68b9153088a62ba379d26
+  metadata.gz: '08f9a10991fb96ebaf09c2e30f4893a056576dcc48d1ad3471021b2c1c41efaab326e18873f008c42153036a545db3ba9be5f427b2e75aa778a6fa54f849795b'
+  data.tar.gz: 505286b2466afe7bbe7460680c4c3f791a476f6b5e5b3848ae4a2105c8f2003f92d4005cf16fbed1a581ebd1b711bb7882ed32ad4ff6db195fed2856243336e3

data/CHANGELOG.md

@@ -4,6 +4,12 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.5.0 (2026-10-23)
+
+- Consume immutable string-keyed Runner summary documents throughout reports and progress callbacks.
+- Use English diagnostics, CLI help, change plans and Fabric review reports.
+- Require Runner 0.2, net-connector 0.18 and the coordinated command receipt protocol.
+
 ## 0.4.2 (2026-10-23)
 
 - Migrate shared CLI entrypoints to ctx_cli 0.2.0 names without legacy aliases.

data/README-zh.md

@@ -59,7 +59,7 @@ observation.records.each { |record| p record }
 ```sh
 gem install vxlan
 # 联网采集与读取 .env 所需的可选依赖：
-gem install net-connector -v '~> 0.16.0'
+gem install net-connector -v '~> 0.18.0'
 vxlan --help
 vxlan collect --init --non-interactive
 vxlan collect --inventory-only

data/README.md

@@ -59,7 +59,7 @@ The gem installs `vxlan`; its implementation lives in `lib/vxlan/cli/`. The scri
 ```sh
 gem install vxlan
 # Optional dependencies for live collection and .env files:
-gem install net-connector -v '~> 0.17.1'
+gem install net-connector -v '~> 0.18.0'
 vxlan --help
 vxlan collect --init --non-interactive
 vxlan collect --inventory-only

data/bin/README.md

@@ -17,7 +17,7 @@ bundle exec ruby examples/offline.rb
 
 `bin/` 的公开内容是 `vxlan` 与本说明；现场 `vxlan.yml`、`.env`、`vxlans/` 由用户按需创建，不进入版本库或安装包。配置和凭据模板统一位于 `lib/vxlan/cli/templates/`，使用 `--init` 生成，不维护重复模板。
 
-离线解析和帮助不加载 net-connector。采集配置与联网入口可选依赖 `net-connector ~> 0.16.0`（已包含 `.env` 加载依赖 dotenv）。本仓库 Gemfile 的 `examples` 组已声明连接器，不进入 vxlan.gemspec 的运行依赖。只安装 vxlan gem 的宿主需要自行声明相应可选依赖。
+离线解析和帮助不加载 net-connector。采集配置与联网入口可选依赖 `net-connector ~> 0.18.0`（已包含 `.env` 加载依赖 dotenv）。本仓库 Gemfile 的 `examples` 组已声明连接器，不进入 vxlan.gemspec 的运行依赖。只安装 vxlan gem 的宿主需要自行声明相应可选依赖。
 
 ## 正式命令
 
@@ -25,7 +25,7 @@ bundle exec ruby examples/offline.rb
 
 ```sh
 gem install vxlan
-gem install net-connector -v '~> 0.16.0'
+gem install net-connector -v '~> 0.18.0'
 vxlan --help
 vxlan collect --init --non-interactive
 vxlan collect --inventory-only

data/lib/vxlan/change_plan/svi_acl.rb

@@ -12,14 +12,14 @@ module Vxlan
       def validate_parameters!
         super
         name, direction = @change.values_at("acl", "direction")
-        raise ArgumentError, "ACL 参数无效" unless name.is_a?(String) && name.match?(/\A[A-Za-z0-9_.-]{1,63}\z/) && %w[in out].include?(direction)
-        raise ArgumentError, "ACL 创建状态无效" unless [ true, false ].include?(@change["create_acl"])
-        raise ArgumentError, "不能覆盖既有绑定" unless [ nil, name ].include?(@change["previous_binding"])
+        raise ArgumentError, "Invalid ACL parameters" unless name.is_a?(String) && name.match?(/\A[A-Za-z0-9_.-]{1,63}\z/) && %w[in out].include?(direction)
+        raise ArgumentError, "Invalid ACL creation state" unless [ true, false ].include?(@change["create_acl"])
+        raise ArgumentError, "Cannot overwrite an existing binding" unless [ nil, name ].include?(@change["previous_binding"])
         groups = @change.fetch("address_groups", {})
-        raise ArgumentError, "ACL 依赖未验证" unless groups.is_a?(Hash)
+        raise ArgumentError, "ACL dependencies are unverified" unless groups.is_a?(Hash)
         @policy = AclPolicy.resolve({ "address_groups" => groups }, @change["entries"])
-        raise ArgumentError, "ACL 规则或依赖未验证" unless @policy && @policy.address_groups == groups
-        raise ArgumentError, "无有效 ACL 规则" if @policy.rules.empty?
+        raise ArgumentError, "ACL rules or dependencies are unverified" unless @policy && @policy.address_groups == groups
+        raise ArgumentError, "No valid ACL rules" if @policy.rules.empty?
         @rule_commands = rule_commands
       end
 
@@ -29,7 +29,7 @@ module Vxlan
           next if entry["action"] == "remark"
           action, expression = entry.values_at("action", "expression")
           unless %w[permit deny].include?(action) && expression.is_a?(String) && expression.match?(/\A(?:ip|tcp|udp|icmp|igmp|gre|esp|ah|ospf) [A-Za-z0-9_.:\/ -]+\z/)
-            raise ArgumentError, "ACL 规则语法未验证"
+            raise ArgumentError, "ACL rule syntax is unverified"
           end
           "  #{entry['sequence']} #{action} #{expression}"
         end

data/lib/vxlan/change_plan.rb

@@ -15,12 +15,12 @@ module Vxlan
 
     # 类型判别只发生在输入边界，不接受任意脚本或未声明字段。
     def self.build(change)
-      raise ArgumentError, "增量须为映射" unless change.is_a?(Hash)
+      raise ArgumentError, "Change must be a mapping" unless change.is_a?(Hash)
       case change["kind"]
       when "vlan_vni_add" then VlanVni.new(change)
       when "svi_gateway_add" then SviGateway.new(change)
       when "svi_acl" then SviAcl.new(change)
-      else raise ArgumentError, "不支持的增量类型"
+      else raise ArgumentError, "Unsupported change type"
       end
     end
 
@@ -34,9 +34,9 @@ module Vxlan
 
     # 构造时一次校验和渲染，随后调用者不能改变已确认的参数或命令。
     def initialize(change)
-      raise ArgumentError, "请使用 ChangePlan.build 构造业务增量" if instance_of?(ChangePlan)
+      raise ArgumentError, "Use ChangePlan.build to construct a domain change" if instance_of?(ChangePlan)
       unless change.is_a?(Hash) && change.keys.all?(String) && (change.keys - self.class::FIELDS).empty? && change["kind"] == self.class::KIND
-        raise ArgumentError, "增量字段无效"
+        raise ArgumentError, "Invalid change fields"
       end
       @change = CtxParser::Immutable.copy(change)
       validate_parameters!
@@ -66,8 +66,8 @@ module Vxlan
 
     # 三种动作均定位已有 L2 业务，VLAN/VNI 不从字符串或名称猜测。
     def validate_parameters!
-      raise ArgumentError, "VLAN 无效" unless @change["vlan"].is_a?(Integer) && @change["vlan"].between?(1, 4094)
-      raise ArgumentError, "VNI 无效" unless @change["vni"].is_a?(Integer) && @change["vni"].between?(1, 16_777_215)
+      raise ArgumentError, "Invalid VLAN" unless @change["vlan"].is_a?(Integer) && @change["vlan"].between?(1, 4094)
+      raise ArgumentError, "Invalid VNI" unless @change["vni"].is_a?(Integer) && @change["vni"].between?(1, 16_777_215)
     end
 
     # 网关相关增量必须携带明确租户及单个已验证 IPv4 前缀。
@@ -75,7 +75,7 @@ module Vxlan
       address = @change["address"]
       unless @change["vrf"].is_a?(String) && !@change["vrf"].empty? && address.is_a?(String) &&
           address.match?(/\A\d{1,3}(?:\.\d{1,3}){3}\/\d{1,2}\z/) && IPAddr.new(address).ipv4?
-        raise ArgumentError, "缺少已验证的业务网关"
+        raise ArgumentError, "Verified service gateway is missing"
       end
     end
 

data/lib/vxlan/cli/apply.rb

@@ -25,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?
+        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
@@ -52,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)
+        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
 
@@ -100,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 CtxCli::Input.read(path: "#{options[:plan]}.sha256", max_bytes: 128).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
 
@@ -122,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
@@ -139,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

@@ -34,7 +34,7 @@ module Vxlan
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "联网采集需要 net-connector >= 0.16.0；请在宿主 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 来源二选一；所有重复地址在连接前拒绝。
@@ -71,7 +71,7 @@ module Vxlan
           begin
             Net::Connector::Resources.prepare!(parallel: [ devices.size, options.values.fetch("parallel") ].min)
           rescue ArgumentError
-            raise CtxCli::Collection::Error, "本机文件描述符额度不足；请提高终端 ulimit -n 或降低 --parallel。已停止，未连接设备。", cause: nil
+            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
@@ -80,14 +80,14 @@ module Vxlan
       def report(options)
         Report.new(options.values.fetch("directory"), scripts: options.flags[:scripts] == true)
       rescue ArgumentError
-        raise CtxCli::Collection::Error, "报告目录无效；请使用真实私有目录、权限0700，并检查目录路径。", cause: nil
+        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 CtxCli::Collection::Error, "请设置 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

@@ -6,6 +6,7 @@ require "optparse"
 require "ctx_cli/options"
 require "ctx_cli/terminal"
 require "ctx_cli/initializer"
+gem "net-connector", "~> 0.18.0"
 require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
@@ -28,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
 
       # 帮助和范例只打印文本，不读取文件或加载可选网络依赖。
@@ -36,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
@@ -51,7 +52,7 @@ module Vxlan
       # 自动化拒绝强制问答；帮助分支无需检查终端或消费输入。
       def validate_interaction!(input:, error:)
         if flags[:interactive] && !CtxCli::Terminal.tty?(input, error)
-          raise CtxCli::Collection::Error, "--interactive 需要交互终端；自动化请使用 --init --non-interactive"
+          raise CtxCli::Collection::Error, "--interactive requires an interactive terminal; use --init --non-interactive for automation"
         end
       end
 
@@ -66,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 最后覆盖；数组不追加设备。
@@ -74,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")
@@ -92,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)
+          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
 
       # 对外只列来源路径和字段归属，不携带环境文件的值。
@@ -157,9 +158,9 @@ module Vxlan
           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::Initializer.new(prefix: ".vxlan-init-").create(path: path, contents: body)
-          @out.puts "#{status == :created ? '已创建' : '已保留'}：#{path}"
+          @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。
@@ -169,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
 
@@ -211,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)
@@ -232,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)
@@ -243,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
 
@@ -258,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