network-infra-utility 0.2.0 → 0.5.0

data/bin/geo-doc

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# geo-doc — network-infra-utility 的 GeoLite2 JSON → 大表导出工具
+#
+# 把 geo-load 生成的 JSON 数据文件（city-IPv4/IPv6、country-IPv4/IPv6、
+# asn、geo-city、geo-country）拼接成一张完整大表，按 IPv4 / IPv6 分别
+# 输出为 CSV 和/或 TXT 文件。
+#
+# 用法:
+#   geo-doc                                  # 从 ./geodb/ 读取, 输出到 ./geodb/
+#   geo-doc -d /data/geodb                   # 指定数据目录
+#   geo-doc -d /data/geodb -o /output        # 指定数据目录 + 输出目录
+#   geo-doc -d /data/geodb --format csv      # 仅输出 CSV
+#   geo-doc -d /data/geodb --format txt      # 仅输出 TXT
+#   geo-doc -d /data/geodb -o /out -f csv    # 指定输出目录 + 仅 CSV
+#
+# 参数规则:
+#   -d, --data-dir DIR     数据文件目录（含 JSON），默认 ./geodb/
+#   -o, --output-dir DIR   输出目录，默认与数据目录相同
+#   -f, --format FORMAT    输出格式: csv / txt / both（默认 both）
+#   -h, --help             显示帮助
+#   -v, --version          显示版本
+
+require "optparse"
+
+# ---- 命令行解析 -------------------------------------------------------------
+options = { data_dir: nil, output_dir: nil, format: :both }
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    geo-doc — GeoLite2 JSON → 大表导出工具 (network-infra-utility)
+
+    将 geo-load 生成的 JSON 拼接为完整 IP 归属大表，按 IPv4/IPv6 分别输出。
+
+    用法:
+      geo-doc                              # 从 ./geodb/ 读取并输出
+      geo-doc -d /data/geodb               # 指定数据目录
+      geo-doc -d /data/geodb -o /output    # 指定数据目录 + 输出目录
+      geo-doc -d /data/geodb -f csv        # 仅输出 CSV
+      geo-doc -d /data/geodb -f txt        # 仅输出 TXT
+
+    参数:
+      -d, --data-dir DIR     数据文件目录 (含 JSON)，默认 ./geodb/
+      -o, --output-dir DIR   输出目录，默认与数据目录相同
+      -f, --format FORMAT    输出格式: csv / txt / both (默认 both)
+
+    选项:
+  BAN
+  opts.on("-d", "--data-dir DIR", "数据文件目录，默认 ./geodb/") { |v| options[:data_dir] = v }
+  opts.on("-o", "--output-dir DIR", "输出目录，默认与数据目录相同") { |v| options[:output_dir] = v }
+  opts.on("-f", "--format FORMAT", %w[csv txt both], "输出格式: csv / txt / both (默认 both)") { |v| options[:format] = v.to_sym }
+  opts.on("-v", "--version", "显示版本") do
+    require_relative "../version"
+    puts "geo-doc #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    exit 0
+  end
+end
+parser.parse!
+
+# ---- 确定数据目录 -----------------------------------------------------------
+data_dir = options[:data_dir] || ENV["GEODB_DATA_DIR"] || "geodb"
+data_dir = File.expand_path(data_dir)
+
+unless File.directory?(data_dir)
+  warn "✗ 数据目录不存在: #{data_dir}"
+  warn "  请用 -d/--data-dir 指定包含 JSON 数据文件的目录。"
+  warn "  期望目录下含: asn.json / city-IPv4.json / city-IPv6.json /"
+  warn "               country-IPv4.json / country-IPv6.json /"
+  warn "               geo-city.json / geo-country.json"
+  exit 1
+end
+
+required = %w[asn.json geo-city.json geo-country.json]
+missing = required.reject { |f| File.exist?(File.join(data_dir, f)) }
+unless missing.empty?
+  warn "✗ 数据目录 #{data_dir} 缺少必要文件: #{missing.join(', ')}"
+  warn "  请先运行 geo-load 生成 JSON 数据文件。"
+  exit 1
+end
+
+# ---- 确定输出目录 -----------------------------------------------------------
+if options[:output_dir]
+  output_dir = File.expand_path(options[:output_dir])
+  unless File.directory?(output_dir)
+    begin
+      require "fileutils"
+      FileUtils.mkdir_p(output_dir)
+    rescue SystemCallError => e
+      abort "✗ 无法创建输出目录 #{output_dir}: #{e.message}"
+    end
+  end
+else
+  output_dir = nil  # nil → 与数据目录相同
+end
+
+# ---- 解析 format 参数 -------------------------------------------------------
+case options[:format]
+when :csv  then format = [:csv]
+when :txt  then format = [:txt]
+when :both then format = [:csv, :txt]
+else
+  abort "✗ 不支持的格式: #{options[:format]} (可选: csv / txt / both)"
+end
+
+# ---- 加载 GeoDB 模块 --------------------------------------------------------
+ROOT = File.expand_path("..", __dir__)
+$LOAD_PATH.unshift File.join(ROOT, "service", "geodb")
+
+require "cc"
+require "network"
+CC.use "file", "enum", "shell-tools"
+require "geodb"
+
+# ---- 执行导出 ---------------------------------------------------------------
+require_relative "../version"
+puts "╭─ geo-doc #{NetworkInfraUtility::VERSION} ───────────────────────────────"
+puts "│ 数据目录: #{data_dir}"
+puts "│ 输出目录: #{output_dir || data_dir}"
+puts "│ 输出格式: #{format.join(' + ')}"
+puts "╰─ 开始导出 ─────────────────────────────────────"
+$stdout.flush
+
+GeoDB.output(data_dir + "/", format: format, output_path: output_dir ? output_dir + "/" : nil)
+
+puts "╭─ 完成 ───────────────────────────────────────"
+out_target = output_dir || data_dir
+puts "│ 大表文件已生成到: #{out_target}"
+puts "│ 文件列表:"
+Dir.glob(File.join(out_target, "output-*.{csv,txt}")).each { |f| puts "│   #{File.basename(f)}" }
+puts "╰─ 可用 geo-get 查询单个 IP 归属信息 ──────────"

data/bin/geo-get

@@ -82,7 +82,7 @@ def fetch(base, path, params)
   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 E:/workspace/momentum/twinklite/data/geodb"
+  abort "✗ 无法连接 #{base} —— geo-api 服务未启动。\n  启动命令: geo-api -d ./geodb"
 rescue => e
   abort "✗ 请求失败: #{e.class}: #{e.message}"
 end

data/document/ASNum/346/250/241/345/235/227/345/212/237/350/203/275/350/257/264/346/230/216.md

@@ -0,0 +1,242 @@
+
+# ASNum 模块功能说明
+
+> 源码位置：`support/basic/as_num.rb`
+> 加载方式：`require 'network'` 自动加载，或单独 `require_relative 'support/basic/as_num'`
+
+## AS 号背景
+
+AS（自治系统）号是 BGP 路由中标识独立路由域的编号，分 16 位传统号和 32 位扩展号两个区间，每个区间内再分公有、私有、保留三类。
+
+### 号段一览
+
+| 位宽     | 类型   | 范围                              | 说明                     |
+| -------- | ------ | --------------------------------- | ------------------------ |
+| 16 位    | 公有   | 1 – 64511                         | 全球可路由，需向 RIR 申请 |
+| 16 位    | 私有   | 64512 – 65534                     | 内部网络，不可通告公网   |
+| 16 位    | 保留   | 0, 23456, 65535                   | AS 0 / AS_TRANS / 文档   |
+| 32 位    | 公有   | 65536 – 4,199,999,999             | 全球可路由               |
+| 32 位    | 私有   | 4,200,000,000 – 4,294,967,294     | 内部使用                 |
+| 32 位    | 保留   | 4,294,967,295                     | 32 位全 1                |
+
+> AS_TRANS（23456）用于 16 位与 32 位 BGP 互通过渡，归类为保留，不归公有。
+
+### 两种记法
+
+| 记法       | 示例        | 说明                            |
+| ---------- | ----------- | ------------------------------- |
+| **asplain** | `65546`     | 纯十进制整数                    |
+| **asdot**   | `1.10`      | 高 16 位 . 低 16 位，各 0–65535 |
+
+转换关系：`plain = high * 65536 + low`
+
+---
+
+## 创建
+
+`ASNum.new` 接受 String（asplain 或 asdot）或 Integer：
+
+```ruby
+require 'network'
+
+ASNum.new("65546")      # asplain 字符串
+ASNum.new("1.10")       # asdot 字符串
+ASNum.new(65546)        # Integer
+ASNum.new("  65546  ")  # 自动去除前后空白
+```
+
+非法输入抛 `ArgumentError`：
+
+```ruby
+ASNum.new("abc")          # → ArgumentError (Invalid AS number)
+ASNum.new("70000.1")      # → ArgumentError (asdot 段超 65535)
+ASNum.new(4294967296)     # → ArgumentError (超 32 位范围)
+ASNum.new(-1)             # → ArgumentError (负数)
+```
+
+---
+
+## 属性
+
+```ruby
+as = ASNum.new("1.10")
+
+as.number  # => 65546       32 位整数
+as.high    # => 1           高 16 位
+as.low     # => 10          低 16 位
+```
+
+---
+
+## 输出格式
+
+```ruby
+as = ASNum.new("1.10")
+
+as.to_i      # => 65546        十进制整数
+as.to_plain  # => "65546"      asplain 字符串
+as.to_dot    # => "1.10"       asdot 字符串（16 位范围内无点）
+as.to_s      # => "1.10"       同 to_dot
+as.inspect   # => "1.10"       同 to_dot
+```
+
+16 位号 `to_dot` 回退为纯数字：
+
+```ruby
+ASNum.new("100").to_dot    # => "100"
+ASNum.new("65535").to_dot  # => "65535"
+ASNum.new("65536").to_dot  # => "1.0"
+```
+
+### asplain ↔ asdot 互换
+
+```ruby
+ASNum.new("1.10").to_plain        # => "65546"
+ASNum.new("65546").to_dot         # => "1.10"
+ASNum.new("65000.20001").to_plain # => "4259860001"
+ASNum.new("4259860001").to_dot    # => "65000.20001"
+```
+
+---
+
+## 类型判定
+
+```ruby
+# 公有
+ASNum.new("100").public?          # => true   (1 – 64511)
+ASNum.new("65536").public?        # => true   (65536 – 4199999999)
+
+# 私有
+ASNum.new("64512").private?       # => true   (64512 – 65534)
+ASNum.new("4200000000").private?  # => true   (4200000000 – 4294967294)
+
+# 保留
+ASNum.new("0").reserved?          # => true   AS 0
+ASNum.new("23456").reserved?      # => true   AS_TRANS
+ASNum.new("65535").reserved?      # => true   16 位文档保留
+ASNum.new("4294967295").reserved? # => true   32 位全 1
+
+# 一次性获取类型符号
+ASNum.new("100").type          # => :public
+ASNum.new("64512").type        # => :private
+ASNum.new("23456").type        # => :reserved
+```
+
+> 三类互斥：同一 AS 号只属于一类。AS_TRANS(23456) 虽落在 1–64511 范围内，但因属保留号，`public?` 返回 false。
+
+### 兼容原接口别名
+
+```ruby
+as = ASNum.new("100")
+as.is_public_as?    # => true   等价 public?
+as.is_private_as?   # => false  等价 private?
+as.is_reserved_as?  # => false  等价 reserved?
+```
+
+---
+
+## 位宽判定
+
+```ruby
+ASNum.new("100").as2?    # => true   16 位传统号 (0 – 65535)
+ASNum.new("65536").as4?  # => true   32 位扩展号 (≥ 65536)
+
+ASNum.new("65535").as4?  # => false
+ASNum.new("65536").as2?  # => false
+```
+
+---
+
+## 排序比较
+
+`ASNum` 包含 `Comparable`，按 32 位整数排序：
+
+```ruby
+ASNum.new("100") < ASNum.new("200")    # => true
+ASNum.new("1.10") == ASNum.new("65546") # => true（不同记法等价）
+ASNum.new("1.10") == ASNum.new(65546)   # => true
+
+arr = [ASNum.new("300"), ASNum.new("100"), ASNum.new("200")]
+arr.sort.map(&:to_i)   # => [100, 200, 300]
+arr.min.to_i           # => 100
+```
+
+### 作为 Hash key
+
+```ruby
+h = { ASNum.new("100") => "AS100", ASNum.new("200") => "AS200" }
+h[ASNum.new("100")]    # => "AS100"
+
+# 不同记法、相同值 → hash 一致
+ASNum.new("1.10").hash == ASNum.new("65546").hash  # => true
+```
+
+---
+
+## 典型业务场景
+
+### 1. 批量判断 AS 号归属
+
+```ruby
+as_list = ["100", "64512", "23456", "4294967295", "65536"]
+as_list.each do |s|
+  as = ASNum.new(s)
+  puts "#{s} → #{as.type}"
+end
+# 100 → public
+# 64512 → private
+# 23456 → reserved
+# 4294967295 → reserved
+# 65536 → public
+```
+
+### 2. BGP 路由表 AS 号去重排序
+
+```ruby
+# 从 BGP 表中收集的 AS 号（asdot 与 asplain 混用）
+raw = ["1.10", "65546", "100", "65000.20001", "100"]
+
+unique_sorted = raw.map { |s| ASNum.new(s) }.uniq.sort
+unique_sorted.map(&:to_plain)
+# => ["100", "65546", "4259860001"]
+```
+
+### 3. asdot ↔ asplain 批量转换
+
+```ruby
+# Cisco 设备导出 asdot，需转为 asplain 做入库
+["1.10", "65000.20001", "0.100"].map { |s| ASNum.new(s).to_plain }
+# => ["65546", "4259860001", "100"]
+
+# 反过来，asplain 转 asdot
+["65546", "4259860001", "100"].map { |s| ASNum.new(s).to_dot }
+# => ["1.10", "65000.20001", "100"]
+```
+
+### 4. 过滤私有和保留 AS 号
+
+```ruby
+as_paths = [100, 64512, 23456, 65536, 65000, 0]
+
+announcable = as_paths.reject { |n| ASNum.new(n).private? || ASNum.new(n).reserved? }
+# => [100, 65536]
+```
+
+---
+
+## 内部常量
+
+| 常量          | 值              | 说明            |
+| ------------- | --------------- | --------------- |
+| `AS2_MAX`     | 65535           | 16 位上限       |
+| `AS4_MAX`     | 4294967295      | 32 位上限       |
+| `PUB_16_MIN`  | 1               | 16 位公有下限   |
+| `PUB_16_MAX`  | 64511           | 16 位公台上限   |
+| `PRIV_16_MIN` | 64512           | 16 位私有下限   |
+| `PRIV_16_MAX` | 65534           | 16 位私台上限   |
+| `PUB_32_MIN`  | 65536           | 32 位公有下限   |
+| `PUB_32_MAX`  | 4199999999      | 32 位公台上限   |
+| `PRIV_32_MIN` | 4200000000      | 32 位私有下限   |
+| `PRIV_32_MAX` | 4294967294      | 32 位私台上限   |
+| `RESERVED_16` | [0, 23456, 65535] | 16 位保留号列表 |
+| `RESERVED_32` | 4294967295      | 32 位保留号     |

data/document/DNSQuery/345/267/245/345/205/267/344/275/277/347/224/250/346/226/271/346/263/225.md

@@ -0,0 +1,248 @@
+
+# DNS Query 命令工具使用方法
+
+> 命令文件：`bin/dns-query`
+> 运行方式：`ruby bin/dns-query`
+
+跨平台统一域名查询工具：自动检测当前系统所有可用的 DNS 查询工具（dig / nslookup / host / Resolve-DnsName / ping -a 等），默认使用优先级最高的工具执行查询。用户无需关心底层工具差异，也不需要记住各家工具的参数差异。
+
+---
+
+## 一、命令行用法
+
+**用法：**
+
+```
+ruby bin/dns-query <目标> [选项]
+```
+
+**位置参数：**
+
+| 参数 | 说明 |
+|------|------|
+| `<目标>` | 域名（正查）或 IP 地址（反查 PTR）。目标为 IP 地址时自动切换为 PTR 反查 |
+
+**选项：**
+
+| 选项 | 说明 |
+|------|------|
+| `-t, --type TYPE` | DNS 记录类型，默认 `A`。支持 `A` / `AAAA` / `CNAME` / `MX` / `NS` / `PTR` / `SOA` / `TXT` / `SRV` / `ANY` |
+| `-s, --server SERVER` | 指定 DNS 服务器（IP 或域名），默认用系统 DNS |
+| `-a, --all` | 使用当前平台所有可用工具交叉查询 |
+| `--tools` | 列出当前平台可用工具及优先级 |
+| `--matrix` | 显示 10 个查询工具的全平台支持矩阵 |
+| `--no-color` | 禁用 ANSI 颜色输出（适合重定向到文件或管道） |
+| `-v, --version` | 显示版本号 |
+| `-h, --help` | 显示帮助 |
+
+**示例：**
+
+```bash
+# 正查 A 记录（默认）
+ruby bin/dns-query www.baidu.com
+
+# 反查 PTR 记录（自动识别 IP）
+ruby bin/dns-query 8.8.8.8
+
+# 指定记录类型
+ruby bin/dns-query www.baidu.com -t MX
+ruby bin/dns-query baidu.com -t NS
+
+# 指定 DNS 服务器
+ruby bin/dns-query www.baidu.com -s 8.8.8.8
+ruby bin/dns-query www.baidu.com -s 114.114.114.114 -t AAAA
+
+# 用所有可用工具交叉查询
+ruby bin/dns-query www.baidu.com -a
+
+# 查看当前平台可用工具
+ruby bin/dns-query --tools
+
+# 查看全平台工具矩阵
+ruby bin/dns-query --matrix
+
+# 无颜色输出（重定向到文件时不带 ANSI 转义码）
+ruby bin/dns-query www.baidu.com --no-color > result.txt
+```
+
+**退出码：**
+
+| 退出码 | 含义 |
+|--------|------|
+| `0` | 查询成功 |
+| `1` | 参数错误 / 当前平台无可用工具 / 查询全部失败 |
+
+---
+
+## 二、自动行为说明
+
+### 1. 工具自动选择
+
+每次查询前会做运行时检测（命令是否存在），按优先级自动选择：
+
+- **Linux**：`dig` → `host` → `nslookup` → `drill` → `kdig` → `dog` → `getent` → `resolvectl`
+- **Windows**：`dig`（若安装）→ `nslookup` → `Resolve-DnsName` → `ping -a`
+
+可通过 `--tools` 查看当前平台实际可用工具。
+
+### 2. IP 自动反查 PTR
+
+目标为合法 IPv4 / IPv6 地址时，若未显式指定 `-t`，自动把记录类型切换为 `PTR`，并统一转换成反向域名（`in-addr.arpa` / `ip6.arpa`）再查询，保证 dig / drill / kdig 等工具行为一致。
+
+```bash
+ruby bin/dns-query 8.8.8.8
+# 等效于: ruby bin/dns-query 8.8.8.8 -t PTR
+# 实际查询: nslookup -type=PTR 8.8.8.8.in-addr.arpa
+```
+
+### 3. 记录类型与工具能力对照
+
+各工具支持能力不同（可用 `--matrix` 查看完整矩阵），摘要如下：
+
+| 记录类型 | dig | nslookup | host | drill | kdig | dog | Resolve-DnsName |
+|----------|-----|----------|------|-------|------|-----|-----------------|
+| A / AAAA / CNAME / MX / NS / PTR / SOA / TXT / SRV | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| ANY | ✅ | – | – | – | – | – | – |
+| AXFR / DNSSEC / trace | ✅ | – | – | ✅ | ✅ | – | – |
+| DoH / DoT | – | – | – | – | ✅ | – | – |
+
+部分工具（如 `getent hosts`）只支持 A / AAAA，`ping -a` 仅支持 PTR。`--all` 模式下查询失败的工具会显示 `[查询失败或不可用]`，不影响其他工具结果。
+
+---
+
+## 三、全平台工具矩阵（--matrix）
+
+`--matrix` 输出 10 个 DNS 工具的跨平台支持情况：
+
+- **dig**（DNS 查询瑞士军刀）：Linux 各发行版可用；Windows 需手动安装 ISC BIND
+- **nslookup**（经典工具）：全平台内置（Linux 需 bind 工具包）
+- **host**：仅 Linux（bind 工具包）
+- **drill**（ldns，支持 DNSSEC）：Linux 各发行版；Windows 需手动安装
+- **kdig**（Knot DNS，支持 DNSSEC / DoH / DoT）：Linux 各发行版
+- **dog**（Rust 彩色工具）：Linux 各发行版（部分需 cargo 安装）
+- **Resolve-DnsName**（PowerShell）：仅 Windows（PS 4.0+）
+- **ping -a**（反查主机名）：仅 Windows，仅支持 PTR
+- **getent hosts**：仅 Linux
+- **resolvectl query**：仅 Linux（systemd-resolved，Alpine 无）
+
+**缺失工具的安装命令**（Linux）：
+
+| 工具 | Ubuntu / Debian | Alpine | RHEL/CentOS |
+|------|-----------------|--------|-------------|
+| dig / host / nslookup | `sudo apt install -y dnsutils` | `sudo apk add bind-tools` | `sudo yum install -y bind-utils` |
+| drill | `sudo apt install -y ldnsutils` | `sudo apk add drill` | `sudo yum install -y ldns` |
+| kdig | `sudo apt install -y knot-dnsutils` | `sudo apk add knot` | `sudo yum install -y knot-utils` |
+
+---
+
+## 四、典型使用场景
+
+### 1. 正查域名 A 记录
+
+```bash
+$ ruby bin/dns-query www.baidu.com
+=== 使用 nslookup 查询 www.baidu.com (A) ===
+
+非权威应答:
+
+服务器:  UnKnown
+Address:  10.140.209.68
+
+名称:    www.a.shifen.com
+Addresses:  39.156.70.46
+	39.156.70.239
+Aliases:  www.baidu.com
+```
+
+### 2. 反查 IP 归属域名
+
+```bash
+$ ruby bin/dns-query 8.8.8.8
+=== 使用 nslookup 查询 8.8.8.8 (PTR) ===
+
+非权威应答:
+
+服务器:  UnKnown
+Address:  10.140.209.68
+
+8.8.8.8.in-addr.arpa	name = dns.google
+```
+
+### 3. 指定公网 DNS 服务器校验解析结果
+
+```bash
+# 对比系统 DNS 与公共 DNS 的解析差异（排查 DNS 污染/劫持）
+ruby bin/dns-query www.baidu.com
+ruby bin/dns-query www.baidu.com -s 8.8.8.8
+ruby bin/dns-query www.baidu.com -s 114.114.114.114
+```
+
+### 4. 多工具交叉验证（--all）
+
+```bash
+$ ruby bin/dns-query www.baidu.com -a
+=== 使用所有可用工具查询 www.baidu.com (A) ===
+
+--- nslookup ---
+非权威应答: ...
+--- Resolve-DnsName ---
+Name      : www.baidu.com
+QueryType : A
+...
+--- ping -a ---
+正在 Ping www.a.shifen.com [2409:8c00:...] 具有 32 字节的数据:
+...
+```
+
+### 5. 检查邮件服务器（MX）
+
+```bash
+$ ruby bin/dns-query qq.com -t MX
+=== 使用 nslookup 查询 qq.com (MX) ===
+非权威应答:
+qq.com	MX preference = 30, mail exchanger = mx3.qq.com
+...
+```
+
+---
+
+## 五、代码级用法
+
+脚本同时提供可复用的模块能力（`load` 后不自动执行 CLI；文件无 `.rb` 扩展名，需用 `load` 而非 `require`）：
+
+```ruby
+load File.expand_path("bin/dns-query", __dir__)
+
+# 查询对象：自动判断 IP / 域名，IP 自动反查 PTR
+query = DnsQuery::Query.new("www.baidu.com", qtype: "A", server: "8.8.8.8")
+
+# 默认最佳工具查询 → [stdout, exit_code]
+stdout, code = query.execute
+
+# 全部工具交叉查询 → [汇总状态, exit_code]
+DnsQuery::Query.new("8.8.8.8").execute_all
+
+# 平台与工具检测
+DnsQuery::Platform.os            # => :windows / :linux
+DnsQuery::Platform.wsl?          # => true / false
+DnsQuery::ToolDetector.detect    # => [{key:, name:, priority:}, ...]
+```
+
+**模块结构：**
+
+| 模块 | 职责 |
+|------|------|
+| `DnsQuery::Platform` | 操作系统 / 发行版 / Windows 版本 / PowerShell 版本检测 |
+| `DnsQuery::ToolDetector` | 运行时检测当前平台可用工具（`which`/`where` 按平台分流） |
+| `DnsQuery::Executor` | 10 个工具的调用逻辑统一入口，PTR 自动转反向域名，Windows 输出自动转 UTF-8 |
+| `DnsQuery::Query` | 查询编排：最佳工具单查 / 全部工具交叉查 |
+| `DnsQuery::CLI` | 参数解析、校验、分发，返回进程退出码 |
+
+---
+
+## 六、注意事项
+
+- Windows 下 `ver` / PowerShell 命令输出为 GBK 编码，脚本已统一转换为 UTF-8，无需手动设置代码页
+- 指定 `-s` 服务器时接受 IP 或域名；非法格式会在查询前报错
+- `ping -a` 会实际发起一次 ICMP 探测，离线环境 `--all` 模式会超时，可单独用 `--tools` 确认后避免使用该工具
+- 输出重定向到文件时建议加 `--no-color`，避免 ANSI 转义码进入文件