network-infra-utility 0.6.0 → 1.0.0

data/bin/gen-get

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# gen-get — network-infra-utility 的互联网 IP 归属查询工具 (geo 系列)
+#
+# 调用免费互联网接口查询 IP 归属, 默认 ip-api.com 及其参数
+# (lang=zh-CN, fields=status,message,country,regionName,city,isp,as,query),
+# 内置 45 req/min 限速与本地 JSON 缓存。
+#
+# 用法:
+#   gen-get 8.8.8.8                    # 单 IP, 文字格式
+#   gen-get 8.8.8.8 -j                 # JSON 格式
+#   gen-get 1.1.1.1 8.8.8.8 ...       # 多 IP (自动限速)
+#   cat ips.txt | gen-get -j           # 从 stdin 逐行读 IP
+#   gen-get 8.8.8.8 --refresh         # 忽略缓存强刷
+#   gen-get --cache-stats              # 查看缓存统计
+#
+# 选项:
+#   -t, --text         文字格式输出 (默认)
+#   -j, --json         JSON 格式输出 (多 IP 时输出数组)
+#   --refresh          忽略缓存强制重查
+#   --no-cache         查询结果不写入缓存
+#   --api URL          覆盖默认接口 ({ip} 占位符)
+#   --timeout SEC      HTTP 超时秒数, 默认 10
+#   --cache-stats      查看缓存统计后退出
+#   -h, --help         显示帮助
+#   -v, --version      显示版本
+#
+# 退出码: 0 = 查询完成 (含确认无归属); 1 = IP 不合法; 2 = 互联网查询不可达
+#
+# 结果状态 (state):
+#   ok           互联网查询成功
+#   empty        互联网确认无归属 (如私有/保留地址)
+#   unreachable  互联网查询不可达 (网络不通/超时/限速), 返回空结果状态
+#   invalid      IP 不合法
+
+require "optparse"
+require "json"
+require_relative "../service/geoquery/geoquery"
+
+options = { format: :text, refresh: false, no_cache: false, timeout: 10, api: nil }
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    gen-get — 互联网 IP 归属查询工具 (network-infra-utility)
+
+    默认接口: ip-api.com 免费接口 (限 45 req/min, 无需 Key)
+    用法:
+      gen-get <IP> [options]
+      gen-get 8.8.8.8 -j
+      cat ips.txt | gen-get -j
+
+    选项:
+  BAN
+  opts.on("-t", "--text", "文字格式输出 (默认)")      { options[:format] = :text }
+  opts.on("-j", "--json", "JSON 格式输出")            { options[:format] = :json }
+  opts.on("--refresh", "忽略缓存强制重查")             { options[:refresh] = true }
+  opts.on("--no-cache", "查询结果不写入缓存")          { options[:no_cache] = true }
+  opts.on("--api URL", "覆盖默认互联网接口 ({ip} 占位符)") { |v| options[:api] = v }
+  opts.on("--timeout SEC", Integer, "HTTP 超时秒数 (默认 10)") { |v| options[:timeout] = v }
+  opts.on("--cache-stats", "查看缓存统计") do
+    cache = GeoQuery::Cache.new(File.join(GeoQuery::Cache.default_dir, "gen-cache.json"))
+    stats = cache.stats
+    puts "缓存文件: #{stats['file']}"
+    puts "缓存条目: #{stats['total']}    大小: #{stats['size_kb']} KB"
+    unless stats["states"].empty?
+      puts "状态分布: " + stats["states"].map { |k, v| "#{k}=#{v}" }.join("  ")
+    end
+    exit 0
+  end
+  opts.on("-v", "--version", "显示版本") do
+    require_relative "../version"
+    puts "gen-get #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    exit 0
+  end
+end
+parser.parse!
+
+# IP 来源: 命令行参数, 无参数且 stdin 非 TTY 时逐行读
+ips = ARGV.reject { |a| a.start_with?("-") }.map(&:strip).reject(&:empty?)
+if ips.empty? && !$stdin.tty?
+  ips = $stdin.each_line.map(&:strip).reject(&:empty?)
+end
+if ips.empty?
+  warn "用法: gen-get <IP> [options]  (或管道输入 IP 列表, 详见 --help)"
+  exit 1
+end
+
+cache = GeoQuery::Cache.new(File.join(GeoQuery::Cache.default_dir, "gen-cache.json"))
+client = GeoQuery::OnlineClient.new(api: options[:api], timeout: options[:timeout])
+
+results = ips.map do |ip|
+  result = nil
+  unless options[:refresh]
+    cached = cache.get(ip)
+    if cached
+      cached["source"] = "gen-get(cache)"
+      result = cached
+    end
+  end
+  result ||= client.lookup(ip)
+  cache.put(ip, result) unless options[:no_cache]
+  result
+end
+
+cache.save unless options[:no_cache]
+
+# ---- 输出 -------------------------------------------------------------------
+case options[:format]
+when :json
+  puts JSON.pretty_generate(results.size == 1 ? results.first : results)
+when :text
+  results.each do |r|
+    puts "查询 IP: #{r['ip']}    接口: ip-api.com (免费, 限 45 req/min)"
+    puts "-" * 64
+    case r["state"]
+    when "ok"
+      cached = r["cached"] ? "缓存命中" : "实时查询"
+      puts "国家: #{r['country']}    省份: #{r['province']}    城市: #{r['city']}"
+      puts "运营商: #{r['isp']}    用途: #{r['usage']}"
+      puts "ASN: #{r['asn'].empty? ? '未知' : "AS#{r['asn']}"} #{r['asn_org']}"
+      puts "状态: ok    来源: #{r['source']}    #{cached}"
+    when "empty"
+      puts "互联网确认无该 IP 归属数据 (#{r['message']})"
+      puts "状态: empty    来源: #{r['source']}"
+    when "unreachable"
+      puts "✗ 互联网查询不可达: #{r['message']}"
+      puts "状态: unreachable —— 无法连接互联网查询接口, 返回空结果"
+    when "invalid"
+      puts "✗ #{r['message']}"
+      puts "状态: invalid"
+    end
+    puts
+  end
+end
+
+# 退出码取最严重: unreachable(2) > invalid(1) > 其他(0)
+exit 2 if results.any? { |r| r["state"] == "unreachable" }
+exit 1 if results.any? { |r| r["state"] == "invalid" }
+exit 0

data/bin/geo-api

@@ -11,6 +11,7 @@
 # 用法:
 #   geo-api                              # 默认 ./geodb/ + 0.0.0.0:9292
 #   geo-api -d /data/ipdb                # 指定数据文件目录
+#   geo-api -d /data/ipdb -a ./GEO_CACHE # 外带 GEO_CACHE 缓存目录
 #   geo-api -p 8080                      # 指定端口
 #   geo-api -b 127.0.0.1 -p 9292 -d ./ipdb
 #   geo-api --server puma                # 指定 Rack 服务器
@@ -18,6 +19,9 @@
 #
 # 选项:
 #   -d, --data-dir DIR   IP 数据文件目录，默认 ./geodb/
+#   -a, --cache-dir DIR  GEO_CACHE 外带缓存目录 (geocacheYYYYMMDD.json,
+#                        ngeo-get -c 产出; addr 查询兑底)
+#   --priority ORDER     查询顺位 local,cache 的排列 (默认 local,cache)
 #   -b, --host HOST      监听地址，默认 0.0.0.0
 #   -p, --port PORT      监听端口，默认 9292
 #   -s, --server NAME    Rack 服务器，默认 puma
@@ -29,6 +33,13 @@
 #   country-IPv4.json / country-IPv6.json / city-IPv6.json / geo-city.json /
 #   geo-country.json)。目录不存在或没有任何 *.json 文件将直接报错退出。
 #   查询时若具体文件缺失，对应接口容错返回 404 无结果，不影响其他接口。
+#
+# 缓存目录说明:
+#   -a 指定的 GEO_CACHE 目录内存放 geocacheYYYYMMDD.json (客户端 ngeo-get
+#   查询产出)。addr 查询按 --priority 顺位 (默认 local,cache) 编排:
+#   先查本地 GeoLite2 库，查不到时用缓存定位信息兑底。目录不存在仅警告
+#   不退出 (首次使用可能尚无产出文件，后续创建自动感知); 目录内文件
+#   增删改自动感知，无需重启。缓存命中响应附 "cached": true 标记。
 
 require "optparse"
 require "rackup"
@@ -40,6 +51,8 @@ $LOAD_PATH.unshift File.join(ROOT, "service", "geodb")
 # 命令行默认值
 options = {
   data_dir: nil,
+  cache_dir: nil,
+  priority: nil,
   host: "0.0.0.0",
   port: 9292,
   server: "puma"
@@ -56,6 +69,8 @@ parser = OptionParser.new do |opts|
     选项:
   BAN
   opts.on("-d", "--data-dir DIR", "IP 数据文件目录，默认 ./geodb/") { |v| options[:data_dir] = v }
+  opts.on("-a", "--cache-dir DIR", "GEO_CACHE 外带缓存目录 (geocache*.json, 查询兑底)") { |v| options[:cache_dir] = v }
+  opts.on("--priority ORDER", "查询顺位 local,cache 排列 (默认 local,cache)") { |v| options[:priority] = v }
   opts.on("-b", "--host HOST", "监听地址，默认 0.0.0.0") { |v| options[:host] = v }
   opts.on("-p", "--port PORT", Integer, "监听端口，默认 9292") { |v| options[:port] = v }
   opts.on("-s", "--server NAME", "Rack 服务器，默认 puma") { |v| options[:server] = v }
@@ -94,10 +109,34 @@ if json_files.empty?
   exit 1
 end
 
+# ---- 缓存目录与顺位 ---------------------------------------------------------
+cache_order = options[:priority] || "local,cache"
+parts = cache_order.split(/[,\s]+/).map(&:strip).reject(&:empty?)
+unless !parts.empty? && parts.all? { |p| %w[local cache].include?(p) } && parts.uniq.size == parts.size
+  warn "✗ 无效顺位: #{cache_order} (geo-api 仅支持 local / cache 的排列)"
+  warn "  示例: --priority local,cache   (默认, 先本地库再缓存)"
+  exit 1
+end
+ENV["GEODB_CACHE_ORDER"] = parts.join(",")
+
+cache_dir = nil
+if options[:cache_dir]
+  cache_dir = File.expand_path(options[:cache_dir])
+  # 目录不存在仅警告: 首次使用可能尚无产出文件, 后续创建自动感知
+  unless File.directory?(cache_dir)
+    warn "⚠ 缓存目录不存在: #{cache_dir} (将继续启动, 目录创建后自动感知)"
+  end
+  ENV["GEODB_CACHE_DIR"] = cache_dir
+end
+
 require_relative "../version"
-puts "╭─ geo-api #{NetworkInfraUtility::VERSION} ───────────────────────────────"
+puts "╭─ geo-api #{NetworkInfraUtility::VERSION} ─────────────────────────────"
 puts "│ 数据目录: #{data_dir} "
 puts "│ #{json_files.length}个数据文件：#{json_files.map { |f| File.basename(f) }.join(' ')}"
+if cache_dir
+  n_cache = Dir.glob(File.join(cache_dir, "geocache*.json")).select { |f| /\Ageocache\d{8}\.json\z/ =~ File.basename(f) }.size
+  puts "│ 缓存目录: #{cache_dir} (#{n_cache}个缓存文件, 兑底顺位: #{parts.join(',')})"
+end
 puts "│ 监听: http://#{options[:host]}:#{options[:port]}"
 puts "│ 服务: #{options[:server]}"
 puts "╰─ Ctrl+C 退出 ─────────────────────────────────────"

data/bin/geo-get

@@ -7,6 +7,10 @@
 # 向运行中的 geo-api 服务发起查询，一次输入 IP，同时拉取 country / city /
 # asn 三类归属信息并汇总输出。默认展示文字，加 -j 则打印 JSON。
 #
+# 本命令为 GeoQuery::LocalClient (service/geoquery/local.rb) 的瘦封装：
+# 三接口拉取与汇总逻辑统一收口在 LocalClient，与 ngeo-get / gen-get
+# 共享同一套客户端实现，消除双实现。
+#
 # 用法:
 #   geo-get 1.181.240.251              # 默认三接口齐查, 文字格式
 #   geo-get 8.8.8.8 -j                 # JSON 格式输出
@@ -24,16 +28,14 @@
 #   -v, --version      显示版本
 #
 # 默认连 http://127.0.0.1:9292 (geo-api 默认监听)。
+# 可用环境变量 GEO_API_BASE 覆盖服务地址。
 # 服务未运行时给出明确提示与启动命令。
 
 require "optparse"
-require "net/http"
 require "json"
-require "uri"
+require_relative "../service/geoquery/geoquery"
 
-HOST = "127.0.0.1"
-PORT = 9292
-BASE = "http://#{HOST}:#{PORT}"
+BASE = ENV["GEO_API_BASE"] || GeoQuery::LocalClient::DEFAULT_BASE
 
 # ---- 命令行解析 -------------------------------------------------------------
 options = { format: :text, only: nil }
@@ -70,59 +72,39 @@ parser.parse!
 ip = ARGV.find { |a| !a.start_with?("-") } || "1.181.240.251"
 
 only = options[:only]
-do_country = only.nil? || only == :country
-do_city    = only.nil? || only == :city
-do_asn     = only.nil? || only == :asn
+endpoints = only ? [only] : GeoQuery::LocalClient::ENDPOINTS
 
-# ---- HTTP 取数 --------------------------------------------------------------
-# 发起一次 GET, 返回 {code:, body:}
-def fetch(base, path, params)
-  uri = URI("#{base}#{path}")
-  uri.query = URI.encode_www_form(params) unless params.empty?
-  res = Net::HTTP.get_response(uri)
-  { code: res.code.to_i, body: (JSON.parse(res.body) rescue res.body) }
-rescue Errno::ECONNREFUSED
-  abort "✗ 无法连接 #{base} —— geo-api 服务未启动。\n  启动命令: geo-api -d ./geodb"
-rescue => e
-  abort "✗ 请求失败: #{e.class}: #{e.message}"
-end
+# ---- 查询 (LocalClient 底座) ------------------------------------------------
+client = GeoQuery::LocalClient.new(base: BASE)
+raw = client.fetch_raw(ip, endpoints: endpoints)
 
-# ---- 按接口拉取 + 收集 ------------------------------------------------------
-results = {}
-results[:country] = fetch(BASE, "/geo/country", addr: ip) if do_country
-results[:city]    = fetch(BASE, "/geo/city",    addr: ip) if do_city
-results[:asn]     = fetch(BASE, "/geo/asn",     addr: ip) if do_asn
+if raw == :unreachable
+  abort "✗ 无法连接 #{BASE} —— geo-api 服务未启动。\n  启动命令: geo-api -d ./geodb"
+end
 
 # ---- 输出: --json / --text 两路分发 -----------------------------------------
 case options[:format]
 when :json
   # JSON 格式: 把每个接口的响应原样放进一个对象打印。
   # 命中的接口放解析后的 body; 404/无结果放 null, 不逐条刷错误。
-  payload = {}
-  results.each do |key, r|
-    payload[key] = (r[:code] == 200 ? r[:body] : nil)
-  end
-  puts JSON.pretty_generate(payload)
+  puts JSON.pretty_generate(raw.transform_keys(&:to_s))
 when :text
   puts "查询 IP: #{ip}    范围: #{only ? "仅 #{only}" : 'country / city / asn 三接口齐查'}    服务: #{BASE}"
   puts "-" * 60
 
   hits = []
-  if do_country && (r = results[:country]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:country])
     g = d["geoname"]; rc = d["registered_country"]
     country = (g && g["country_name"]) || (rc && rc["country_name"]) || "未知"
     hits << "[国家] #{country} (#{(g && g["country_iso_code"]) || (rc && rc["country_iso_code"])})  网段 #{d["network"]}"
   end
-  if do_city && (r = results[:city]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:city])
     g = d["geoname"]
     city = (g && (g["city_namezh"] || g["city_name"])) || "未知"
     coord = g && g["latitude"] && g["longitude"] ? "#{g["latitude"]}, #{g["longitude"]}" : "无"
     hits << "[城市] #{city}    坐标 #{coord}    网段 #{d["network"]}"
   end
-  if do_asn && (r = results[:asn]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:asn])
     hits << "[ASN]  AS#{d["autonomous_system_number"]} #{d["autonomous_system_organization"]}    网段 #{d["network"]}"
   end
 

data/bin/ngeo-get

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# ngeo-get — network-infra-utility 的 IP 归属综合查询工具 (geo 系列)
+#
+# 按 -p 顺位编排三个数据源, 满意即停, 字段叠加:
+#   cache    GEO_CACHE 外带缓存目录 (geocacheYYYYMMDD.json, -a 指定)
+#   local    本地 geo-api 服务 (GeoLite2)
+#   internet 互联网 ip-api.com (限速 + 熔断保护)
+#
+# 结果状态可信度: unreachable < local-partial < cache-partial < empty
+#                < cache < local < online < merged
+#   unreachable   各源均无结果且有不联通 (空结果状态)
+#   local-partial 本地部分结果, 无更多补充
+#   cache-partial 缓存部分结果, 无更多补充
+#   empty         各源均确认无归属 (如私有地址)
+#   cache         缓存命中且满意
+#   local         本地结果满意 (省/市/ASN 齐全)
+#   online        纯互联网结果
+#   merged        多源叠加综合
+#
+# 用法:
+#   ngeo-get 111.8.44.6                     # 默认顺位 cache,local,internet
+#   ngeo-get 111.8.44.6 -a ./GEO_CACHE      # 指定外带缓存目录
+#   ngeo-get 111.8.44.6 -p local,internet,cache   # 本地优先, 缓存兜底
+#   ngeo-get 111.8.44.6 -nc                 # 查询但不产出缓存文件
+#   ngeo-get 1.1.1.1 8.8.8.8 -j             # 多 IP (在线部分自动限速)
+#   cat ips.txt | ngeo-get -j                # 从 stdin 逐行读 IP
+#   ngeo-get -m ./GEO_CACHE                 # 合并缓存目录全部 geocache*.json
+#   ngeo-get --cache-stats                   # 查看会话缓存统计
+#
+# 选项:
+#   -t, --text          文字格式输出 (默认)
+#   -j, --json          JSON 格式输出 (多 IP 时输出数组)
+#   -a, --cache-dir DIR GEO_CACHE 外带缓存目录 (geocache*.json 文件集)
+#   -p, --priority O    查询顺位, cache/local/internet 的排列
+#                       (默认 cache,local,internet: 优先缓存, 再本地, 再互联网)
+#   -c, --cache-out     查询结果保存为 geocacheYYYYMMDD.json (默认开启)
+#   -nc, --no-cache-out 不保存查询产出
+#   -m, --merge DIR     合并 DIR 下全部 geocache*.json 为新文件后退出
+#   --refresh           忽略缓存强制重查 (会话缓存与 GEO_CACHE 均跳过)
+#   --no-local          跳过本地 geo-api
+#   --api URL           覆盖默认互联网接口 ({ip} 占位符)
+#   --geoapi URL        覆盖本地 geo-api 地址 (默认 http://127.0.0.1:9292)
+#   --timeout SEC       互联网 HTTP 超时秒数, 默认 10
+#   --cache-stats       查看缓存统计后退出
+#   -h, --help          显示帮助
+#   -v, --version       显示版本
+#
+# 产出说明:
+#   每次查询的结果 (默认) 保存到缓存目录 (未指定 -a 时为当前目录,
+#   可用环境变量 GEO_CACHE_DIR 覆盖), 命名为 geocacheYYYYMMDD.json,
+#   同一天多次查询自动归并到同一文件, 同 IP 以新结果覆盖。
+#   产出文件即后续 -a 查询 / -m 合并 / geo-api -a 服务端兜底的数据源。
+#
+# 退出码: 0 = 查询完成 (含 empty/local-partial/cache-partial);
+#         1 = IP 不合法或参数错误; 2 = 互联网不可达且其余源无结果
+
+require "optparse"
+require "json"
+require_relative "../service/geoquery/geoquery"
+
+options = { format: :text, refresh: false, no_local: false, timeout: 10,
+            api: nil, geoapi: nil, geo_cache_dir: nil, order: nil,
+            cache_out: true, merge_dir: nil }
+
+# "-nc" 为 "-c" 的反义短参组合, OptionParser 无法注册, 手动预提取
+if (idx = ARGV.index("-nc"))
+  ARGV.delete_at(idx)
+  options[:cache_out] = false
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    ngeo-get — IP 归属综合查询工具 (GEO_CACHE 缓存 + 本地 geo-get + 互联网 gen-get)
+
+    策略: 按顺位逐源查询 (-p, 默认 cache,local,internet), 满意即停, 字段叠加
+    用法:
+      ngeo-get <IP> [options]
+      ngeo-get 111.8.44.6 -a ./GEO_CACHE -j
+      ngeo-get -m ./GEO_CACHE
+      cat ips.txt | ngeo-get -j
+
+    选项:
+  BAN
+  opts.on("-t", "--text", "文字格式输出 (默认)")        { options[:format] = :text }
+  opts.on("-j", "--json", "JSON 格式输出")              { options[:format] = :json }
+  opts.on("-a", "--cache-dir DIR", "GEO_CACHE 外带缓存目录") { |v| options[:geo_cache_dir] = v }
+  opts.on("-p", "--priority ORDER", "查询顺位 cache/local/internet 排列 (默认 cache,local,internet)") { |v| options[:order] = v }
+  opts.on("-c", "--cache-out", "查询结果保存为 geocacheYYYYMMDD.json (默认开启)") { options[:cache_out] = true }
+  opts.on("--no-cache-out", "不保存查询产出 (同 -nc)")    { options[:cache_out] = false }
+  opts.on("-m", "--merge DIR", "合并 DIR 下全部 geocache*.json 为新文件后退出") { |v| options[:merge_dir] = v }
+  opts.on("--refresh", "忽略缓存强制重查")               { options[:refresh] = true }
+  opts.on("--no-local", "跳过本地 geo-api")              { options[:no_local] = true }
+  opts.on("--api URL", "覆盖默认互联网接口 ({ip} 占位符)") { |v| options[:api] = v }
+  opts.on("--geoapi URL", "覆盖本地 geo-api 地址")        { |v| options[:geoapi] = v }
+  opts.on("--timeout SEC", Integer, "互联网 HTTP 超时秒数 (默认 10)") { |v| options[:timeout] = v }
+  opts.on("--cache-stats", "查看缓存统计") do
+    cache = GeoQuery::Cache.new(File.join(GeoQuery::Cache.default_dir, "ngeo-cache.json"))
+    stats = cache.stats
+    puts "会话缓存: #{stats['file']}"
+    puts "缓存条目: #{stats['total']}    大小: #{stats['size_kb']} KB"
+    unless stats["states"].empty?
+      puts "状态分布: " + stats["states"].map { |k, v| "#{k}=#{v}" }.join("  ")
+    end
+    if options[:geo_cache_dir]
+      gstats = GeoQuery::GeoCache.new(options[:geo_cache_dir]).stats
+      puts
+      puts "GEO_CACHE: #{gstats['dir']}"
+      puts "缓存文件: #{gstats['files']}    条目: #{gstats['entries']}"
+      unless gstats["states"].empty?
+        puts "状态分布: " + gstats["states"].map { |k, v| "#{k}=#{v}" }.join("  ")
+      end
+    end
+    exit 0
+  end
+  opts.on("-v", "--version", "显示版本") do
+    require_relative "../version"
+    puts "ngeo-get #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    puts <<~NOTE
+
+      顺位示例:
+        -p cache,local,internet   优先缓存 → 本地库 → 互联网 (默认)
+        -p local,internet,cache   本地优先, 本地查不到才找互联网, 互联网查不到或不通再查缓存
+        -p internet,local         纯互联网优先, 不通再查本地
+
+      产出: 默认保存查询结果为 geocacheYYYYMMDD.json (缓存目录或当前目录), -nc 关闭
+    NOTE
+    exit 0
+  end
+end
+parser.parse!
+
+# ---- -m 整理模式: 合并缓存目录后退出 (优先级最高) ---------------------------
+if options[:merge_dir]
+  gc = GeoQuery::GeoCache.new(options[:merge_dir])
+  unless File.directory?(gc.dir)
+    warn "✗ 缓存目录不存在: #{gc.dir}"
+    exit 1
+  end
+  stats = gc.merge!
+  puts "合并完成: #{stats['files']} 个缓存文件 → #{stats['entries']} 条记录"
+  puts "输出文件: #{stats['output']}"
+  exit 0
+end
+
+# ---- 顺位参数校验 -----------------------------------------------------------
+order = GeoQuery::NGeo::DEFAULT_ORDER
+if options[:order]
+  order = GeoQuery::GeoCache.parse_order(options[:order])
+  if order.nil?
+    warn "✗ 无效顺位: #{options[:order]}"
+    warn "  合法源: cache / local / internet, 逗号分隔, 不重复"
+    warn "  示例: -p cache,local,internet   (默认)"
+    exit 1
+  end
+end
+
+# IP 来源: 命令行参数, 无参数且 stdin 非 TTY 时逐行读
+ips = ARGV.reject { |a| a.start_with?("-") }.map(&:strip).reject(&:empty?)
+if ips.empty? && !$stdin.tty?
+  ips = $stdin.each_line.map(&:strip).reject(&:empty?)
+end
+if ips.empty?
+  warn "用法: ngeo-get <IP> [options]  (或管道输入 IP 列表, 详见 --help)"
+  exit 1
+end
+
+ngeo = GeoQuery::NGeo.new(api: options[:api], geoapi_base: options[:geoapi],
+                          timeout: options[:timeout],
+                          geo_cache_dir: options[:geo_cache_dir], order: order)
+
+results = ips.map do |ip|
+  ngeo.lookup(ip, refresh: options[:refresh], no_local: options[:no_local])
+end
+
+ngeo.save_cache
+
+# ---- 产出: 查询结果保存为 geocacheYYYYMMDD.json -----------------------------
+# 保存目录: -a 指定目录 > ENV["GEO_CACHE_DIR"] > 当前目录; -nc 关闭
+if options[:cache_out] && !results.empty?
+  out_dir = options[:geo_cache_dir] || GeoQuery::GeoCache.default_dir
+  out = GeoQuery::GeoCache.new(out_dir).put_batch(results)
+  # 提示走 stderr, 不污染 JSON 输出
+  warn "产出: #{out['entries']} 条查询结果 → #{out['file']}" if out
+end
+
+# ---- 输出 -------------------------------------------------------------------
+STATE_LABEL = {
+  "merged" => "多源叠加综合", "online" => "纯互联网",
+  "local" => "本地满意", "local-partial" => "本地部分 (无更多补充)",
+  "cache" => "缓存命中", "cache-partial" => "缓存部分 (无更多补充)",
+  "empty" => "各源均无归属", "unreachable" => "查询不可达",
+  "invalid" => "IP 不合法",
+}.freeze
+
+SRC_DISPLAY = {
+  "cache" => "GEO_CACHE 缓存", "local" => "本地 geo-get", "online" => "互联网 gen-get",
+}.freeze
+
+ORDER_TEXT = order.join(",").freeze
+
+case options[:format]
+when :json
+  puts JSON.pretty_generate(results.size == 1 ? results.first : results)
+when :text
+  results.each do |r|
+    puts "查询 IP: #{r['ip']}    顺位: #{ORDER_TEXT} (满意即停, 字段叠加)"
+    puts "-" * 64
+    case r["state"]
+    when "unreachable"
+      puts "✗ #{r['message']}"
+      puts "状态: unreachable (#{STATE_LABEL['unreachable']}) —— 各源均无结果, 且有不联通"
+    when "invalid"
+      puts "✗ #{r['message']}"
+      puts "状态: invalid"
+    else
+      country = r["country"].empty? ? "未知" : r["country"]
+      province = r["province"].empty? ? "未知" : r["province"]
+      city = r["city"].empty? ? "未知" : r["city"]
+      puts "国家: #{country}    省份: #{province}    城市: #{city}"
+      puts "运营商: #{r['isp'].empty? ? '未知' : r['isp']}    用途: #{r['usage'].empty? ? '未知' : r['usage']}"
+      asn = r["asn"].empty? ? "未知" : "AS#{r['asn']}"
+      net = r["network"].empty? ? "" : "    网段: #{r['network']}"
+      puts "ASN: #{asn} #{r['asn_org']}#{net}"
+      cached = r["cached"] ? "缓存命中" : "实时查询"
+      puts "状态: #{r['state']} (#{STATE_LABEL[r['state']]})    来源: #{r['source']}    #{cached}"
+      unless r["message"].to_s.empty?
+        puts "提示: #{r['message']}"
+      end
+      if r["sources"].is_a?(Hash)
+        r["sources"].each do |name, info|
+          next unless info.is_a?(Hash)
+          label = SRC_DISPLAY[name] || name
+          verdict = info["verdict"] ? ", #{info['verdict']}" : ""
+          msg = info["message"].to_s.empty? ? "" : " (#{info['message']})"
+          puts "  · #{label}: #{info['state']}#{verdict}#{msg}"
+        end
+      end
+    end
+    puts
+  end
+end
+
+# 退出码取最严重: unreachable(2) > invalid(1) > 其他(0)
+exit 2 if results.any? { |r| r["state"] == "unreachable" }
+exit 1 if results.any? { |r| r["state"] == "invalid" }
+exit 0