vxlan 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b045bbd7eb98d8771aac733587cf171bdf5c8c0da0f7ce3a4226317454da139
-  data.tar.gz: 06d4bddb07fa64f80ca0b2cb283c02321ad0bf54f56c94ec9c1538ebe052b447
+  metadata.gz: 203d6c19eed76f37e033ba015e36a39953de0ba63dc5fd4130873a83f1e097c3
+  data.tar.gz: bb21ff1519721b7ee99cdedc5af2a3ac34c8542563c06ce9d3cd1328c31c4d6f
 SHA512:
-  metadata.gz: 6b5636dc50b48a4f0eed0c5c6b8babb2d650eae98f8a6ee78b1969b940327ba44e8f5b5bb16e12dd7b706cc0044756568aefae2fb9523e3034e72adbf132c2bc
-  data.tar.gz: 73d115544a200fab0ae647981720af491b05dca15f17b3f7a8ed021559221b101012842b2c7856dca0fa28edc7d9a4d2bb1d06ba439f78595b45aec3c5965c60
+  metadata.gz: aa2702cbc3fc196d77c7cb4ac24aca422f4e03eaf6ac4967d07b946e762ff774b9359d24deae4430ca9e7a8644992909e00b185c48d14b575d30bbeb037f381c
+  data.tar.gz: fea09bbf0ea945b4c33913f759aad4e4181bd4da4148593ade4e177a18939938ef7c0b327bbce9da0b3ac18e95d9bee9ebced5afd2014b4c35978bd9b80fb7c0

data/CHANGELOG.md

@@ -14,6 +14,11 @@ Changes to the public contract are recorded here. Versions follow Semantic Versi
 
 ## Unreleased
 
+## 0.4.1 (2026-10-22)
+
+- Delegate command dispatch, common options, initialization, terminal interaction, offline IO and collection entrypoint orchestration to ctx_cli 0.1.0.
+- Keep domain policies, device capabilities and ctx_runner completion semantics in their existing layers.
+
 - Delegate batch completion and cancellation/failure precedence to CtxRunner::Batch, keeping domain review and CLI presentation explicit.
 
 ## 0.3.1 (2026-10-21)

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.17.1`（已包含 `.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.17.1'
 vxlan --help
 vxlan collect --init --non-interactive
 vxlan collect --inventory-only
@@ -213,3 +213,7 @@ vxlan collect --hosts 192.0.2.0/24 --name edge --exclude-name spare --model 'S68
 IP 支持单地址、CIDR、范围；名称及型号支持 contains（默认）、prefix、glob，不区分大小写。`--vendor`/`--exclude-vendor` 使用连接器平台标识（如 cisco_nxos、h3c、h3c_wireless、huawei），不是原始厂商标签。同字段条件为 OR，跨字段为 AND，排除优先。缺失型号不命中包含规则。`--model`/`--exclude-model`、`--name-match`/`--model-match` 可组合；筛选只选择已有清单，不扫描地址、不扩大平台支持范围。
 
 YAML 顶层对应 hosts/exclude_hosts、names/exclude_names、vendors/exclude_vendors、models/exclude_models、name_match/model_match。Netdisco inventory 段使用 include_hosts/include_names/include_vendors/include_models 及对应 exclude 字段。
+
+## ctx_cli 公共入口
+
+分发、公共选项、配置初始化、离线输入输出、终端确认和采集入口由 ctx_cli 组合提供；领域规则与 ctx_runner 业务状态保持各自职责。`CTX_CLI_PATH=../ctx_cli bundle exec rake` 用于源码联调；普通入口先安装 ctx_cli 候选包。

data/lib/vxlan/cli/apply.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/terminal"
 require "json"
 require "digest"
 require "ctx_runner/execution"
@@ -59,7 +60,8 @@ module Vxlan
         end
         rest = parser.parse(argv.dup)
         return @out.puts(parser) || 0 if options[:help]
-        raise ArgumentError, "必须使用真实交互终端" unless @input.tty? && @out.tty? && @error.tty?
+        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])
         hash = Digest::SHA256.hexdigest(body)
@@ -71,9 +73,8 @@ module Vxlan
         @out.puts Array(plan["prerequisites"]).map { |value| "条件：#{value}" }
         @out.puts "计划 SHA256：#{hash}\n拟执行命令：\n#{change.commands.join("\n")}\n条件回退（不自动执行）：\n#{change.rollback.join("\n")}"
         token = "APPLY #{host} #{hash[0, 12]} #{options[:item]}"
-        @out.print "确认业务策略及维护窗口后输入 #{token}；其他输入取消："
-        @out.flush
-        return @out.puts("已取消，未连接设备。") || 1 unless @input.gets&.strip == token
+        confirmed = terminal.confirm(token: token, prompt: "确认业务策略及维护窗口后输入 #{token}；其他输入取消：")
+        return @out.puts("已取消，未连接设备。") || 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])

data/lib/vxlan/cli/collect.rb

@@ -2,6 +2,7 @@
 
 require "vxlan"
 require "ctx_runner/batch"
+require "ctx_cli/collection"
 require_relative "options"
 require_relative "report"
 require_relative "connector"
@@ -17,79 +18,31 @@ module Vxlan
         @defaults = options
       end
 
-      # 先预检全部输入和凭据，再创建报告和连接；失败分类不打印原始异常正文。
+      # 公共入口编排顺序与失败收尾；以下方法是显式领域适配协议。
       def run(argv)
-        # 每次运行独立持有批次状态；预检失败不能改写上一次报告。
-        @options, @store, @progress, @devices, @batch = nil, nil, nil, [], nil
-        @options = Options.new(argv, env: @env, out: @out, **@defaults)
-        return 0 if @options.informational?
-        @options.validate_interaction!(input: @input, error: @error)
-        @options.load_environment
-        if @options.flags[:init]
-          @options.initialize_files
-          return 0
+        progress = ->(options) do
+          require "net/connector/collect/progress"
+          Net::Connector::Collect::Progress.new(io: @error, enabled: !options.flags[:quiet], verbose: options.flags[:verbose])
         end
-        return 0 if @options.missing?(input: @input, error: @error)
-        @options.load
-        require "net/connector/collect/progress"
-        @progress = Net::Connector::Collect::Progress.new(io: @error, enabled: !@options.flags[:quiet], verbose: @options.flags[:verbose])
-        @progress.notice("配置：#{@options.config}")
-        return output(@options.public_values.merge("sources" => @options.sources)) if @options.flags[:show_config]
-        @devices = devices = inventory
-        return output(devices) if @options.flags[:inventory_only]
-        if devices.empty?
-          @progress.notice("没有匹配设备，未建立连接")
-          @out.puts JSON.generate(status: :no_devices, total: 0) if @options.flags[:json]
-          return 1
-        end
-        credentials = credentials!
-        load_network unless @connector_factory && @executor
-        unless @connector_factory
-          devices.each { |device| Net::Connector::Configuration.new(host: device.fetch("host"), **credentials).validate_endpoint! }
-        end
-        unless @executor
-          require "net/connector/resources"
-          Net::Connector::Resources.prepare!(parallel: [ devices.size, @options.values.fetch("parallel") ].min)
-        end
-        @store = Report.new(@options.values.fetch("directory"), scripts: @options.flags[:scripts] == true)
-        @batch = CtxRunner::Batch.new(report: @store, progress: @progress, requested: devices)
-        outcome = @batch.run(present: ->(summary) { @out.puts JSON.pretty_generate(summary) if @options.flags[:json] }) do
-          @progress.plan(devices: devices, total: @inventory_total, parallel: @options.values.fetch("parallel"), label: "VXLAN 只读采集")
-          @progress.with_updates do
-            execute(devices) { |device| collect(device, credentials) }
-          end
-          @store.review_collected_fabric(@options.fabric_policy)
-        end
-        completion(outcome)
-      rescue Interrupt
-        diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
-        130
-      rescue SystemCallError, IOError => error
-        diagnostic "VXLAN 参数或报告错误：#{report_diagnostic(error)}"
-        2
-      rescue OptionParser::ParseError, ArgumentError, LoadError => error
-        diagnostic "VXLAN 参数、依赖或报告错误：#{error.message}；使用 --help 查看参数"
-        2
-      rescue StandardError => error
-        diagnostic "VXLAN 清单或执行失败：#{CtxDriver::Failure.code(error, :collection_failed)}（#{error.class.name}）"
-        2
+        CtxCli::Collection.new(adapter: self, options: ->(arguments) { Options.new(arguments, env: @env, out: @out, **@defaults) },
+          progress: progress, batch: CtxRunner::Batch, label: "VXLAN", report_error: Report::Error,
+          failure_code: ->(error) { CtxDriver::Failure.code(error, :collection_failed) },
+          out: @out, error: @error, input: @input).run(argv)
       end
 
-      private
-
       # 只在需要库存或网络执行时加载可选依赖，帮助和静态预览保持独立。
       def load_network
         require "net/connector"
       rescue LoadError
-        raise LoadError, "联网采集需要 net-connector >= 0.17.0；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
+        raise LoadError, "联网采集需要 net-connector >= 0.17.1；请在宿主 Gemfile 添加或 gem install net-connector", cause: nil
       end
 
       # YAML 静态设备或显式 Netdisco 来源二选一；所有重复地址在连接前拒绝。
-      def inventory
-        values = @options.values
-        rows = if @options.dynamic_inventory?
-          @progress.reading_inventory
-          settings = @options.netdisco_settings
+      def inventory(options, progress:)
+        values = options.values
+        rows = if options.dynamic_inventory?
+          progress.reading_inventory
+          settings = options.netdisco_settings
           Net::Connector::Netdisco::Fleet.new(settings: settings).devices.filter_map do |device|
             next unless device.ready? && device.vendor == :cisco_nxos
             { "host" => device.host, "name" => device.name || device.host, "model" => device.model }
@@ -97,89 +50,63 @@ module Vxlan
         else
           values.fetch("devices")
         end
-        targets = @options.normalize_devices(rows)
-        @inventory_total = targets.size
+        targets = options.normalize_devices(rows)
+        total = targets.size
         selection = Net::Connector::Inventory::Filters.selection(values)
-        targets.select do |device|
+        selected = targets.select do |device|
           selection.selected?(device.fetch("host"), "cisco_nxos", name: device["name"], model: device["model"])
         end
+        [ selected, total ]
       end
 
+      # 所有设备先完成凭据、端点与资源预检，再允许创建报告和连接。
+      def prepare(devices, options)
+        credentials = credentials!(options)
+        load_network unless @connector_factory && @executor
+        unless @connector_factory
+          devices.each { |device| Net::Connector::Configuration.new(host: device.fetch("host"), **credentials).validate_endpoint! }
+        end
+        unless @executor
+          require "net/connector/resources"
+          Net::Connector::Resources.prepare!(parallel: [ devices.size, options.values.fetch("parallel") ].min)
+        end
+        credentials
+      end
+
+      def report(options) = Report.new(options.values.fetch("directory"), scripts: options.flags[:scripts] == true)
+      def after_collect(report, options) = report.review_collected_fabric(options.fabric_policy)
+
       # 缺失用户名时不尝试连接；密码允许省略以支持明确的 SSH key/agent。
-      def credentials!
-        username = secret("NC_CISCO_NXOS_USERNAME") || secret("NC_DEVICE_USERNAME")
+      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
-        @options.values.fetch("ssh").transform_keys(&:to_sym).merge(username: username,
-          password: secret("NC_CISCO_NXOS_PASSWORD") || secret("NC_DEVICE_PASSWORD"), enable_password: secret("NC_ENABLE_PASSWORD"))
+        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
 
       # 空白环境值视为缺失，不修改或回显凭据。
-      def secret(name)
-        value = @options.environment[name]
+      def secret(options, name)
+        value = options.environment[name]
         value unless value.nil? || value.strip.empty?
       end
 
       # 每个任务使用独立 Collector 和会话；公共执行器负责有界并发和线程回收。
-      def execute(devices, &block)
-        parallel = @options.values.fetch("parallel")
+      def execute(devices, options, &block)
+        parallel = options.values.fetch("parallel")
         return @executor.call(devices, parallel, &block) if @executor
         Net::Connector::Parallel::Pool.new(parallel: parallel).map(devices, &block)
       end
 
       # 单台失败保留其他设备和已获得维度；报告持久化失败交由批次终止处理。
-      def collect(device, credentials)
-        credentials = credentials.merge(on_event: @progress.method(:event))
-        @batch.collect(device) do
-          connector = @connector_factory ? @connector_factory.call(device, credentials) : Connector.new(device, credentials)
-          snapshot = Vxlan::Collector.new.collect(connector: connector, target: device, fabric_key: @options.values.fetch("fabric"),
-            model: device["model"], dimensions: @options.values.fetch("dimensions").map(&:to_sym))
-          snapshot
-        end
+      def collect(device, options, context:, progress:)
+        credentials = context.merge(on_event: progress.method(:event))
+        connector = @connector_factory ? @connector_factory.call(device, credentials) : Connector.new(device, credentials)
+        snapshot = Vxlan::Collector.new.collect(connector: connector, target: device, fabric_key: options.values.fetch("fabric"),
+          model: device["model"], dimensions: options.values.fetch("dimensions").map(&:to_sym))
+        snapshot
       end
 
-      # Runner 决定批次结论；CLI 仅呈现安全诊断并映射退出码。
-      def completion(outcome)
-        if outcome.finalization_error
-          diagnostic "VXLAN 摘要报告错误：#{outcome.finalization_error}"
-        end
-        if outcome.recovery_failed
-          diagnostic "摘要恢复未确认；请依据退出码及报告目录检查，不能将旧摘要视为本次成功。"
-        end
-        if outcome.status == :interrupted
-          diagnostic "采集已取消，已保存的设备报告保留；未保存结果见报告状态"
-        elsif (failure = outcome.failure)
-          if failure[:kind] == :report
-            diagnostic "VXLAN 参数或报告错误：#{failure[:detail]}"
-          else
-            diagnostic "VXLAN 清单或执行失败：#{failure[:error_type]}；已采集结果见批次报告"
-          end
-        end
-        { complete: 0, incomplete: 1, failed: 2, interrupted: 130 }.fetch(outcome.status)
-      end
-
-      # 错误提示失败不能覆盖取消或执行退出码；已失效的进度流不再重试。
-      def diagnostic(message)
-        return if @progress&.output_error
-        @error.puts(message)
-      rescue StandardError
-        nil
-      end
-
-      # 自有发布错误消息不含正文；外部文件异常只显示类型，不打印 message/cause。
-      def report_diagnostic(error)
-        error.instance_of?(Report::Error) ? error.message : error.class.name
-      end
-
-      # 预览默认显示逐设备身份；公开配置由显式开关展示。
-      def output(value)
-        if @options.flags[:json] || value.is_a?(Hash)
-          @out.puts JSON.pretty_generate(value)
-        else
-          value.each { |device| @out.puts "#{device.fetch('host')}\t#{device.fetch('name')}\t#{device['model']}" }
-          @out.puts "设备：#{value.size} 台；未建立设备连接"
-        end
-        value.is_a?(Array) && value.empty? ? 1 : 0
-      end
+      private :load_network, :credentials!, :secret
     end
   end
 end

data/lib/vxlan/cli/options.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require "optparse"
+require "ctx_cli/options"
+require "ctx_cli/terminal"
+require "ctx_cli/initialization"
 require "net/connector/inventory/filters"
 require "yaml"
 require "ipaddr"
-require "fileutils"
-require "tempfile"
 
 module Vxlan
   module CLI
@@ -47,7 +48,7 @@ module Vxlan
 
       # 自动化拒绝强制问答；帮助分支无需检查终端或消费输入。
       def validate_interaction!(input:, error:)
-        if flags[:interactive] && !(input.tty? && error.tty?)
+        if flags[:interactive] && !CtxCli::Terminal.tty?(input, error)
           raise ArgumentError, "--interactive 需要交互终端；自动化请使用 --init --non-interactive"
         end
       end
@@ -63,7 +64,7 @@ module Vxlan
         @environment = @files.environment
         @config, @env_file = @files.config, @files.env_file
       rescue LoadError
-        raise LoadError, "采集配置需要 net-connector >= 0.17.0；读取 .env 还需要 dotenv", cause: nil
+        raise LoadError, "采集配置需要 net-connector >= 0.17.1；读取 .env 还需要 dotenv", cause: nil
       end
 
       # 公共与专用文件先合并，进程值和 CLI 最后覆盖；数组不追加设备。
@@ -150,22 +151,11 @@ module Vxlan
         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 +
+        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|
-          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
+          status = CtxCli::Initialization.new(prefix: ".vxlan-init-").create(path: path, contents: body)
+          @out.puts "#{status == :created ? '已创建' : '已保留'}：#{path}"
         end
         @out.puts "请检查配置及凭据后再次运行；本次未读取清单、未连接设备。"
       end
@@ -175,10 +165,10 @@ module Vxlan
         @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)
+        terminal = CtxCli::Terminal.new(input: input, out: error)
+        if terminal.tty? && flags[:interactive] != false
+          answer = terminal.question("配置不存在：#{config}；是否创建配置与环境模板？[y/N] ")
+          if answer&.match?(/\Ay(?:es)?\z/i)
             initialize_files
             return true
           end
@@ -232,10 +222,14 @@ module Vxlan
       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) }
+          CtxCli::Options.configuration(p, parallel_help: "设备并发 1～500；继承 NC_PARALLEL，未配置时 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)
+            when :directory then @overrides["directory"] = File.expand_path(value, Dir.pwd)
+            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) }
@@ -246,29 +240,19 @@ module Vxlan
               @overrides[key] = value
             end
           end
-          p.on("--init", "创建缺失配置和环境模板后退出；已有文件不覆盖") { flags[:init] = true }
-          p.on("--interactive", "缺少配置时询问是否创建；要求真实终端") { flags[:interactive] = true }
-          p.on("--non-interactive", "禁用问答；创建文件须同时指定 --init") { flags[:interactive] = false }
+          CtxCli::Options.initialization(p, flags)
           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 }
+          CtxCli::Options.output(p, flags)
           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 }
+          CtxCli::Options.information(p, flags)
           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 list(value) = CtxCli::Options.list(value)
 
       # 先验证整批策略，避免在前面设备连接后才发现后面的非法配置。
       def validate!

data/lib/vxlan/cli/parse.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require "optparse"
+require "ctx_cli/command"
+require "ctx_cli/options"
+require "ctx_cli/input"
+require "ctx_cli/output"
 require "json"
 require "time"
 require "vxlan"
@@ -12,45 +15,40 @@ module Vxlan
       # 注入标准流，便于在宿主测试中验证无需网络的行为。
       def initialize(out: $stdout, error: $stderr, input: $stdin, command: "vxlan parse")
         @out, @error, @input, @command = out, error, input, command
+        @output = CtxCli::Output.new(out: out, error: error)
       end
 
       # 参数错误与部分证据分开返回；默认只显示元数据，JSON 显式导出事实。
       def run(argv)
-        options = { dimension: :configuration, complete: false }
-        parser = OptionParser.new do |p|
-          p.banner = "用法：#{@command} [选项]（离线文件或 stdin）"
+        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 }
-          p.on("-h", "--help", "查看帮助") { options[:help] = true }
-          p.on("--help-all", "查看全部选项") { options[:help] = true }
-          p.on("--examples", "查看示例") { options[:examples] = true }
+          CtxCli::Options.information(p, options)
           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]
+        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])
 
-        body = options[:file] ? File.read(options[:file]) : @input.read
+        body = CtxCli::Input.read(path: options[:file], input: @input)
         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)
+          @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 健康。"
         end
         observation.complete? ? 0 : 1
-      rescue OptionParser::ParseError, ArgumentError, SystemCallError => error
-        @error.puts "离线解析参数或文件错误（#{error.class.name}）；使用 --help 查看参数"
+      rescue OptionParser::ParseError, ArgumentError, SystemCallError, IOError => error
+        @output.diagnostic("离线解析参数或文件错误；使用 --help 查看参数", exception: error)
         2
       end
     end

data/lib/vxlan/cli.rb

@@ -1,46 +1,42 @@
 # frozen_string_literal: true
 
 require "vxlan/version"
+require "ctx_cli/application"
 
 module Vxlan
   # 命令入口按需加载采集或解析实现；核心库无需加载 CLI。
   module CLI
     # 由调用方拥有退出行为，库入口只返回退出码。
     def self.run(argv, env: ENV, out: $stdout, error: $stderr, input: $stdin, **collect_options)
-      arguments = argv.dup
-      command = arguments.shift
-      case command
-      when nil, "--help", "--help-all", "-h"
-        return usage(out) if arguments.empty?
-      when "--version", "-v"
-        return out.puts(Vxlan::VERSION) || 0 if arguments.empty?
-      when "collect"
-        begin
-          require_relative "cli/collect"
-        rescue LoadError
-          error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
-          return 2
+      commands = {
+        "collect" => ->(arguments) do
+          begin
+            require_relative "cli/collect"
+          rescue LoadError
+            error.puts "collect 需要含共享清单筛选的当前 net-connector；请安装项目依赖。"
+            next 2
+          end
+          Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
+        end,
+        "apply" => ->(arguments) do
+          require_relative "cli/apply"
+          Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
+        end,
+        "review" => ->(arguments) do
+          require_relative "cli/review"
+          Review.new(out: out, error: error).run(arguments)
+        end,
+        "parse" => ->(arguments) do
+          require_relative "cli/parse"
+          Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
         end
-        return Collect.new(env: env, out: out, error: error, input: input, **collect_options).run(arguments)
-      when "apply"
-        require_relative "cli/apply"
-        return Apply.new(env: env, out: out, error: error, input: input, connector_factory: collect_options[:connector_factory], discovery: collect_options.fetch(:discovery, {})).run(arguments)
-      when "review"
-        require_relative "cli/review"
-        return Review.new(out: out, error: error).run(arguments)
-      when "parse"
-        require_relative "cli/parse"
-        return Parse.new(out: out, error: error, input: input, command: collect_options.fetch(:command, "vxlan parse")).run(arguments)
-      end
-      error.puts "未知命令或多余参数；使用 vxlan --help 查看用法"
-      2
+      }
+      CtxCli::Application.new(name: "vxlan", version: Vxlan::VERSION, usage: USAGE,
+        commands: commands, out: out, error: error).run(argv)
     end
 
     # 全局帮助不读取配置、环境文件或设备清单。
-    def self.usage(out)
-      out.puts "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。"
-      0
-    end
-    private_class_method :usage
+    USAGE = "用法：vxlan collect [选项]  只读采集与报告\n      vxlan parse [选项]    离线文件或 stdin 解析\n      vxlan review --batch DIR  离线修复建议\n      vxlan apply --plan FILE --item ID  交互确认后下发\n      vxlan --version\n使用 vxlan collect --help 、vxlan parse --help 或 vxlan review --help 查看参数；--help-all 查看完整约定，--examples 查看范例。".freeze
+    private_constant :USAGE
   end
 end

data/lib/vxlan/version.rb

@@ -2,5 +2,5 @@
 
 module Vxlan
   # 公开包版本，供 RubyGems 元数据和运行时调用方共用。
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vxlan
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Gatework contributors
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ctx_cli
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: ctx_runner
   requirement: !ruby/object:Gem::Requirement