sysx-cli 1.0.0__tar.gz → 1.1.0__tar.gz

{sysx_cli-1.0.0/sysx_cli.egg-info → sysx_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysx-cli
-Version: 1.0.0
+Version: 1.1.0
 Summary: 轻量级系统信息与开发辅助 CLI 工具，纯标准库实现，零第三方依赖
 Author-email: maoxian3824 <maoxian3824@users.noreply.github.com>
 License-Expression: MIT
@@ -35,6 +35,8 @@ Dynamic: license-file
 
 # sysx
 
+> English version: [README.en.md](README.en.md)
+
 > 轻量级系统信息与开发辅助 CLI 工具 — 纯 Python 标准库实现，零第三方依赖。
 
 [![Tests](https://github.com/maoxian3824/sysx/actions/workflows/test.yml/badge.svg)](https://github.com/maoxian3824/sysx/actions/workflows/test.yml)
@@ -85,8 +87,8 @@ python3 sysx.py info
 ### 方式四：从 GitHub Release 安装
 
 ```bash
-curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.0.0-py3-none-any.whl
-pip install sysx_cli-1.0.0-py3-none-any.whl
+curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.1.0-py3-none-any.whl
+pip install sysx_cli-1.1.0-py3-none-any.whl
 ```
 
 ## 使用
@@ -104,7 +106,7 @@ sysx <命令> [选项]
 | `disk` | 磁盘挂载点与使用率（按使用率排序） |
 | `proc` | 占用最高的进程，可按 CPU / 内存排序 |
 | `net` | 网络接口、MAC、链路状态、本机 IP、DNS |
-| `ports` | 监听中的 TCP 端口 |
+| `ports` | 监听中的 TCP 与绑定的 UDP 端口 |
 | `env` | 相关环境变量（Shell、语言工具链、容器等） |
 | `uptime` | 运行时长与 1/5/15 分钟负载 |
 | `doctor` | 开发环境体检：工具链、网络、磁盘余量 |
@@ -216,7 +218,7 @@ sysx ports -j | jq -r '.[].port'
 | 磁盘挂载 | `/proc/mounts` + `shutil.disk_usage` |
 | 网络接口 | `/sys/class/net/*` |
 | DNS | `/etc/resolv.conf` |
-| 监听端口 | `/proc/net/tcp`、`/proc/net/tcp6` |
+| 监听/绑定端口 | `/proc/net/tcp`、`/proc/net/tcp6`、`/proc/net/udp`、`/proc/net/udp6` |
 
 **关于 CPU 占用率**：直接读 `/proc/<pid>/stat` 只能拿到进程的累计 CPU 时间，
 除以总和会得出错误结果（长运行进程会被严重高估）。`sysx` 采用两次采样（间隔 250ms）

{sysx_cli-1.0.0 → sysx_cli-1.1.0}/README.md

@@ -1,5 +1,7 @@
 # sysx
 
+> English version: [README.en.md](README.en.md)
+
 > 轻量级系统信息与开发辅助 CLI 工具 — 纯 Python 标准库实现，零第三方依赖。
 
 [![Tests](https://github.com/maoxian3824/sysx/actions/workflows/test.yml/badge.svg)](https://github.com/maoxian3824/sysx/actions/workflows/test.yml)
@@ -50,8 +52,8 @@ python3 sysx.py info
 ### 方式四：从 GitHub Release 安装
 
 ```bash
-curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.0.0-py3-none-any.whl
-pip install sysx_cli-1.0.0-py3-none-any.whl
+curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.1.0-py3-none-any.whl
+pip install sysx_cli-1.1.0-py3-none-any.whl
 ```
 
 ## 使用
@@ -69,7 +71,7 @@ sysx <命令> [选项]
 | `disk` | 磁盘挂载点与使用率（按使用率排序） |
 | `proc` | 占用最高的进程，可按 CPU / 内存排序 |
 | `net` | 网络接口、MAC、链路状态、本机 IP、DNS |
-| `ports` | 监听中的 TCP 端口 |
+| `ports` | 监听中的 TCP 与绑定的 UDP 端口 |
 | `env` | 相关环境变量（Shell、语言工具链、容器等） |
 | `uptime` | 运行时长与 1/5/15 分钟负载 |
 | `doctor` | 开发环境体检：工具链、网络、磁盘余量 |
@@ -181,7 +183,7 @@ sysx ports -j | jq -r '.[].port'
 | 磁盘挂载 | `/proc/mounts` + `shutil.disk_usage` |
 | 网络接口 | `/sys/class/net/*` |
 | DNS | `/etc/resolv.conf` |
-| 监听端口 | `/proc/net/tcp`、`/proc/net/tcp6` |
+| 监听/绑定端口 | `/proc/net/tcp`、`/proc/net/tcp6`、`/proc/net/udp`、`/proc/net/udp6` |
 
 **关于 CPU 占用率**：直接读 `/proc/<pid>/stat` 只能拿到进程的累计 CPU 时间，
 除以总和会得出错误结果（长运行进程会被严重高估）。`sysx` 采用两次采样（间隔 250ms）

{sysx_cli-1.0.0 → sysx_cli-1.1.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 # PyPI 上的发行包名。运行命令仍是 sysx（见 [project.scripts]）。
 # 注意：PyPI 上 sysx / systools / systool 均已被占用，故使用 sysx-cli。
 name = "sysx-cli"
-version = "1.0.0"
+version = "1.1.0"
 description = "轻量级系统信息与开发辅助 CLI 工具，纯标准库实现，零第三方依赖"
 readme = "README.md"
 requires-python = ">=3.8"

{sysx_cli-1.0.0 → sysx_cli-1.1.0}/sysx.py

@@ -6,17 +6,20 @@ sysx - 轻量级系统信息与开发辅助 CLI 工具
 """
 
 import argparse
+import ipaddress
 import json
 import os
 import platform
+import re
 import shutil
 import socket
 import subprocess
 import sys
 import time
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timedelta
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 # 系统级常量，用于 /proc 解析
 try:
@@ -29,11 +32,15 @@ try:
 except (ValueError, OSError, AttributeError):
     PAGE_SIZE = 4096
 
+# 是否存在 /proc 文件系统（用于跨平台降级提示）
+HAS_PROC = os.path.isdir("/proc")
+
 # ---------------------------------------------------------------- ANSI 颜色
 
 class C:
-    """ANSI 颜色。当输出不是 TTY 或设置了 NO_COLOR 时自动禁用。"""
-    _enabled = sys.stdout.isatty() and not os.environ.get("NO_COLOR")
+    """ANSI 颜色。是否启用在运行时由 main() 按当前 stdout 判定，
+    而非导入时求值，以兼容 stdout 被重定向/替换的场景。"""
+    _enabled = True  # 默认启用；main() 启动时会按实际 stdout 重新判定
 
     RESET = "\033[0m"
     BOLD = "\033[1m"
@@ -62,8 +69,10 @@ def _paint(text, color):
 # ---------------------------------------------------------------- 工具函数
 
 def human_bytes(n):
-    """把字节数格式化为人类可读形式。"""
+    """把字节数格式化为人类可读形式。负数按 0 处理。"""
     size = float(n)
+    if size < 0:
+        size = 0.0
     for unit in ("B", "KB", "MB", "GB", "TB", "PB"):
         if size < 1024 or unit == "PB":
             if unit == "B":
@@ -74,8 +83,10 @@ def human_bytes(n):
 
 
 def human_duration(seconds):
-    """把秒数格式化为人类可读形式。"""
+    """把秒数格式化为人类可读形式。负值（如时钟回拨）按 0 处理。"""
     seconds = int(seconds)
+    if seconds < 0:
+        seconds = 0
     days, rem = divmod(seconds, 86400)
     hours, rem = divmod(rem, 3600)
     minutes, secs = divmod(rem, 60)
@@ -95,27 +106,29 @@ def read_text(path):
     try:
         with open(path, "r", encoding="utf-8", errors="replace") as fh:
             return fh.read()
-    except (OSError, IOError):
+    except OSError:
         return None
 
 
+def _disp_width(text):
+    """按显示宽度统计：CJK 等宽字符按 2 计，其余按 1。"""
+    return sum(2 if ord(ch) > 0x2E80 else 1 for ch in str(text))
+
+
 def render_table(headers, rows):
-    """渲染对齐的文本表格。"""
+    """渲染对齐的文本表格（表头与数据行使用同一套宽度统计）。"""
     if not rows:
         return ""
     cols = len(headers)
-    widths = [len(str(h)) for h in headers]
+    widths = [_disp_width(h) for h in headers]
     for row in rows:
         for i in range(cols):
             cell = str(row[i]) if i < len(row) else ""
-            # 中文等宽字符粗略按 2 个宽度计算
-            width = sum(2 if ord(ch) > 0x2E80 else 1 for ch in cell)
-            widths[i] = max(widths[i], width)
+            widths[i] = max(widths[i], _disp_width(cell))
 
     def pad(text, width):
         text = str(text)
-        cur = sum(2 if ord(ch) > 0x2E80 else 1 for ch in text)
-        return text + " " * max(0, width - cur)
+        return text + " " * max(0, width - _disp_width(text))
 
     out = []
     out.append(_paint("  ".join(pad(h, widths[i]) for i, h in enumerate(headers)),
@@ -128,11 +141,12 @@ def render_table(headers, rows):
 
 
 def emit(data, as_json, renderer):
-    """统一输出分发：JSON 模式下打印 JSON，否则调用渲染函数。"""
+    """统一输出分发：JSON 模式打印 JSON，否则调用渲染函数并补一个空行。"""
     if as_json:
         print(json.dumps(data, indent=2, ensure_ascii=False))
     else:
         renderer(data)
+        print()
 
 
 def section(title):
@@ -143,17 +157,32 @@ def section(title):
 
 # ---------------------------------------------------------------- info 子命令
 
+def _read_boot_time():
+    """从 /proc/stat 的 btime 字段读取真实启动时间（epoch 转 datetime）。"""
+    content = read_text("/proc/stat")
+    if content:
+        for line in content.splitlines():
+            if line.startswith("btime "):
+                try:
+                    return datetime.fromtimestamp(int(line.split()[1]))
+                except (ValueError, OSError, OverflowError):
+                    return None
+    return None
+
+
 def collect_info(args=None):
     uname = platform.uname()
-    boot_time = None
+    boot_time = _read_boot_time()
     uptime_seconds = None
 
-    # Linux: 从 /proc/uptime 取更精确的运行时长
+    # Linux: 从 /proc/uptime 取更精确的运行时长；启动时间优先用 btime，
+    # 取不到时才用 now - uptime 兜底（后者会受系统时间被修改影响）。
     uptime_raw = read_text("/proc/uptime")
     if uptime_raw:
         try:
             uptime_seconds = float(uptime_raw.split()[0])
-            boot_time = datetime.now() - timedelta(seconds=uptime_seconds)
+            if boot_time is None:
+                boot_time = datetime.now() - timedelta(seconds=uptime_seconds)
         except (ValueError, IndexError):
             pass
 
@@ -199,11 +228,31 @@ def _read_distro():
     content = read_text("/etc/os-release")
     if not content:
         return None
+    # 合并以反斜杠续行的行（os-release 规范允许）
+    merged = []
+    pending = ""
+    for raw in content.splitlines():
+        if raw.endswith("\\"):
+            pending += raw[:-1]
+        else:
+            merged.append(pending + raw)
+            pending = ""
+    if pending:
+        merged.append(pending)
+
     info = {}
-    for line in content.splitlines():
-        if "=" in line:
-            key, _, value = line.partition("=")
-            info[key.strip()] = value.strip().strip('"')
+    for line in merged:
+        if "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        # 仅在首尾成对出现时剥离一层引号，避免误伤值内嵌的引号
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        # 还原值内的换义符（\n / \t）
+        value = value.replace("\\n", "\n").replace("\\t", "\t")
+        info[key] = value
     return info.get("PRETTY_NAME") or info.get("NAME")
 
 
@@ -291,7 +340,10 @@ def collect_mem(args=None):
 
 
 def render_bar(percent, width=30):
-    """渲染进度条，按用量着色。"""
+    """渲染进度条，按用量着色。percent 会被 clamp 到 [0, 100]，None 视为 0。"""
+    if percent is None:
+        percent = 0.0
+    percent = min(max(float(percent), 0.0), 100.0)
     filled = int(width * percent / 100)
     bar = "█" * filled + "░" * (width - filled)
     if percent >= 90:
@@ -326,17 +378,29 @@ def render_mem(data):
 
 # ---------------------------------------------------------------- disk 子命令
 
+def _mount_rank(mountpoint):
+    """挂载点优先级，用于同一设备多个 bind mount 时择优：
+    / 最优先，其次路径越浅越优先，最后按字典序保证稳定。"""
+    if mountpoint == "/":
+        return (0, 0, "")
+    return (1, mountpoint.count("/"), mountpoint)
+
+
 def collect_disk(args=None):
+    # 容器环境中同一设备常被 bind mount 到多个路径。为每个设备挑选
+    # 最"根级"的挂载点（优先 /，其次最浅路径），避免保留 /etc/hosts
+    # 这类噪音路径而漏掉真正的根分区。
+    best = {}
+    for part in parse_proc_mounts():
+        dev = part["device"]
+        if dev not in best or _mount_rank(part["mountpoint"]) < _mount_rank(best[dev]["mountpoint"]):
+            best[dev] = part
+
     mounts = []
-    seen_devices = set()
-    for part in psutil_like_partitions():
-        # 容器环境中同一块设备常被 bind mount 到多个路径，按设备去重
-        if part["device"] in seen_devices:
-            continue
-        seen_devices.add(part["device"])
+    for part in best.values():
         try:
             usage = shutil.disk_usage(part["mountpoint"])
-        except (OSError, IOError):
+        except OSError:
             continue
         percent = (usage.used / usage.total * 100) if usage.total else 0
         mounts.append({
@@ -352,7 +416,7 @@ def collect_disk(args=None):
     return mounts
 
 
-def psutil_like_partitions():
+def parse_proc_mounts():
     """从 /proc/mounts 解析挂载点，只保留真实块设备。"""
     content = read_text("/proc/mounts")
     if not content:
@@ -382,17 +446,22 @@ def psutil_like_partitions():
         if mountpoint in seen:
             continue
         seen.add(mountpoint)
-        # 反转义 /proc/mounts 中的八进制转义
-        mountpoint = (mountpoint.replace("\\040", " ")
-                                .replace("\\011", "\t")
-                                .replace("\\012", "\n"))
+        mountpoint = _unescape_mount(mountpoint)
         result.append({"device": device, "mountpoint": mountpoint, "fstype": fstype})
     return result
 
 
+def _unescape_mount(s):
+    """解码 /proc/mounts 中的八进制转义（\\040=空格, \\011=Tab, \\134=反斜杠）。"""
+    return re.sub(r"\\(\d{3})", lambda m: chr(int(m.group(1), 8)), s)
+
+
 def render_disk(data):
     if not data:
-        print("未找到可用的块设备挂载点")
+        if HAS_PROC:
+            print("未找到可用的块设备挂载点")
+        else:
+            print("当前平台不支持磁盘信息（需要 Linux /proc/mounts）")
         return
     rows = []
     for m in data:
@@ -511,7 +580,8 @@ def collect_proc(limit=10, sort_by="cpu", interval=0.25):
             "state": cur["state"],
             "cpu_percent": round(cpu_percent, 1),
             "rss": cur["rss"],
-            "mem_percent": round(cur["rss"] / total_mem * 100, 2) if total_mem else 0,
+            # 读不到 MemTotal 时标记为 None，避免把"无数据"误显示成 0%
+            "mem_percent": round(cur["rss"] / total_mem * 100, 2) if total_mem else None,
         })
 
     key = "rss" if sort_by == "mem" else "cpu_percent"
@@ -521,7 +591,10 @@ def collect_proc(limit=10, sort_by="cpu", interval=0.25):
 
 def render_proc(data):
     if not data:
-        print("未读到进程信息（需要 Linux /proc 文件系统）")
+        if HAS_PROC:
+            print("未读到进程信息")
+        else:
+            print("当前平台不支持进程信息（需要 Linux /proc 文件系统）")
         return
     rows = []
     for p in data:
@@ -531,7 +604,7 @@ def render_proc(data):
             p["state"],
             f"{p['cpu_percent']}%",
             human_bytes(p["rss"]),
-            f"{p['mem_percent']}%",
+            f"{p['mem_percent']}%" if p["mem_percent"] is not None else "-",
         ])
     print(render_table(["PID", "名称", "状态", "CPU", "内存", "内存占比"], rows))
 
@@ -556,10 +629,10 @@ def collect_net(args=None):
             if state:
                 iface["state"] = state.strip()
             try:
-                with open(f"/sys/class/net/{name}/speed") as fh:
+                with open(f"/sys/class/net/{name}/speed", encoding="utf-8") as fh:
                     speed = int(fh.read().strip())
-                    # 网卡未连接或虚拟网卡时内核返回负数
-                    iface["speed"] = speed if speed > 0 else None
+                    # 未连接/虚拟网卡返回负数；内核用 0xFFFFFFFF 表示速率未知
+                    iface["speed"] = speed if 0 < speed < 0xFFFFFFFF else None
             except (OSError, ValueError):
                 pass
             info["interfaces"].append(iface)
@@ -591,7 +664,7 @@ def collect_net(args=None):
 def render_net(data):
     print(_paint(f"  主机名  {data['hostname']}", C.BOLD))
     if data.get("local_ip"):
-        print(f"  本机 IP  {_paint(data['local_ip'], C.GREEN)}")
+        print(f"  默认出口 IP  {_paint(data['local_ip'], C.GREEN)}")
     if data.get("dns"):
         print(f"  DNS     {', '.join(data['dns'])}")
 
@@ -643,10 +716,31 @@ def render_env(data):
 
 # ---------------------------------------------------------------- ports 子命令
 
+def _decode_ipv6(addr_hex):
+    """把 /proc/net/*6 的 32 位十六进制 IPv6 地址解码为标准字符串。
+    内核按 4 个 u32 存储、每个 u32 内小端，故每组 4 字节需反转。"""
+    try:
+        raw = bytes.fromhex(addr_hex)
+    except ValueError:
+        return "?"
+    if len(raw) != 16:
+        return "?"
+    ordered = bytes(b for i in range(0, 16, 4) for b in raw[i:i + 4][::-1])
+    return ipaddress.IPv6Address(ordered).compressed
+
+
 def collect_ports(args=None):
-    """从 /proc/net/tcp 解析监听端口。"""
+    """解析监听/绑定的端口：
+    TCP / TCP6 取 LISTEN（状态 0A）；UDP / UDP6 取已绑定的未连接
+    socket（状态 07，即 UDP 的"监听"）。"""
     ports = []
-    for proto, path in (("tcp", "/proc/net/tcp"), ("tcp6", "/proc/net/tcp6")):
+    specs = (
+        ("tcp", "/proc/net/tcp", "0A"),
+        ("tcp6", "/proc/net/tcp6", "0A"),
+        ("udp", "/proc/net/udp", "07"),
+        ("udp6", "/proc/net/udp6", "07"),
+    )
+    for proto, path, listen_state in specs:
         content = read_text(path)
         if not content:
             continue
@@ -657,7 +751,7 @@ def collect_ports(args=None):
                 continue
             local = fields[1]
             state = fields[3]
-            if state != "0A":  # 0A = LISTEN
+            if state != listen_state:
                 continue
             try:
                 addr_hex, port_hex = local.rsplit(":", 1)
@@ -665,13 +759,11 @@ def collect_ports(args=None):
             except ValueError:
                 continue
             try:
-                if proto == "tcp":
+                if proto.endswith("6"):
+                    ip = _decode_ipv6(addr_hex)
+                else:
                     ip = ".".join(str(int(addr_hex[i:i + 2], 16))
                                   for i in (6, 4, 2, 0))
-                else:
-                    ip = "::"
-                    if addr_hex == "0" * 32:
-                        ip = "[::]"
             except ValueError:
                 ip = "?"
 
@@ -682,16 +774,19 @@ def collect_ports(args=None):
                 "inode": fields[9] if len(fields) > 9 else None,
             })
 
-    # 去重并按端口排序
+    # 去重并按协议+端口排序
     uniq = {}
     for p in ports:
         uniq[(p["proto"], p["port"])] = p
-    return sorted(uniq.values(), key=lambda p: p["port"])
+    return sorted(uniq.values(), key=lambda p: (p["proto"], p["port"]))
 
 
 def render_ports(data):
     if not data:
-        print("未发现监听中的 TCP 端口")
+        if HAS_PROC:
+            print("未发现监听/绑定的端口")
+        else:
+            print("当前平台不支持端口信息（需要 Linux /proc/net）")
         return
     rows = [[p["proto"], p["address"], p["port"]] for p in data]
     print(render_table(["协议", "监听地址", "端口"], rows))
@@ -739,24 +834,44 @@ def _check_dns():
     return False, "所有域名解析均失败"
 
 
-def _check_network():
-    """多目标 TCP 探测，任一可达即认为外网连通。"""
+def _probe_tcp(target, timeout=3):
+    """探测单个 TCP 目标，返回 (ok, detail)。"""
+    host, port = target
+    try:
+        # 用 with 确保异常路径下 socket 也会被关闭
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.settimeout(timeout)
+            sock.connect((host, port))
+        return True, f"可访问 {host}:{port}"
+    except (OSError, socket.error) as exc:
+        return False, str(exc)
+
+
+def _check_network(timeout=3):
+    """多目标 TCP 并发探测，任一可达即认为外网连通。
+    并发后断网最坏耗时约 timeout，而非 timeout × 目标数。"""
     targets = [("1.1.1.1", 443), ("8.8.8.8", 53), ("223.5.5.5", 443)]
-    errors = []
-    for host, port in targets:
-        try:
-            # 用 with 确保异常路径下 socket 也会被关闭
-            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
-                sock.settimeout(3)
-                sock.connect((host, port))
-            return True, f"可访问 {host}:{port}"
-        except (OSError, socket.error) as exc:
-            errors.append(str(exc))
-            continue
-    detail = errors[0] if errors else "连接失败"
+    with ThreadPoolExecutor(max_workers=len(targets)) as pool:
+        results = [f.result() for f in (pool.submit(_probe_tcp, t, timeout)
+                                        for t in targets)]
+    for ok, detail in results:
+        if ok:
+            return True, detail
+    detail = next((d for ok, d in results if d), "连接失败")
     return False, detail[:60]
 
 
+def _is_root():
+    """是否 root；平台不支持（如 Windows 无 geteuid）时返回 None。"""
+    geteuid = getattr(os, "geteuid", None)
+    if geteuid is None:
+        return None
+    try:
+        return geteuid() == 0
+    except OSError:
+        return None
+
+
 def collect_doctor(args=None):
     """开发环境体检。"""
     checks = []
@@ -774,15 +889,20 @@ def collect_doctor(args=None):
         path = shutil.which(tool)
         check(tool, path is not None, path or "未安装")
 
-    # 权限
-    check("root 权限", os.geteuid() == 0,
-          "当前是 root" if os.geteuid() == 0 else "普通用户")
-
-    # 网络探测
-    dns_ok, dns_detail = _check_dns()
+    # 权限（Windows 无 geteuid，跳过而非误报失败）
+    root = _is_root()
+    if root is None:
+        check("root 权限", True, "当前平台不支持该检查")
+    else:
+        check("root 权限", root, "当前是 root" if root else "普通用户")
+
+    # 网络探测：DNS 与外网连通并发执行，缩短断网环境下的等待
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        dns_future = pool.submit(_check_dns)
+        net_future = pool.submit(_check_network)
+        dns_ok, dns_detail = dns_future.result()
+        net_ok, net_detail = net_future.result()
     check("DNS 解析", dns_ok, dns_detail)
-
-    net_ok, net_detail = _check_network()
     check("外网连通", net_ok, net_detail)
 
     # 磁盘余量
@@ -835,20 +955,22 @@ def build_parser():
     )
     parser.add_argument("-V", "--version", action="version",
                         version=f"sysx {__version__}")
+    parser.add_argument("--debug", action="store_true",
+                        help="发生错误时打印完整堆栈信息")
 
     sub = parser.add_subparsers(dest="command", metavar="<命令>")
 
-    def add(name, help_text, func, collector, renderer, extra=None):
+    def add(name, help_text, collector, renderer, extra=None):
         p = sub.add_parser(name, help=help_text, description=help_text)
         p.add_argument("-j", "--json", action="store_true",
                        help="以 JSON 格式输出")
         if extra:
             extra(p)
-        p.set_defaults(func=func, collector=collector, renderer=renderer)
+        p.set_defaults(collector=collector, renderer=renderer)
 
-    add("info", "显示系统概览信息", None, collect_info, render_info)
-    add("mem", "显示内存与交换分区使用情况", None, collect_mem, render_mem)
-    add("disk", "显示磁盘挂载点与使用率", None, collect_disk, render_disk)
+    add("info", "显示系统概览信息", collect_info, render_info)
+    add("mem", "显示内存与交换分区使用情况", collect_mem, render_mem)
+    add("disk", "显示磁盘挂载点与使用率", collect_disk, render_disk)
 
     def proc_extra(p):
         p.add_argument("-n", "--limit", type=int, default=10,
@@ -859,14 +981,14 @@ def build_parser():
     def proc_collect(args):
         return collect_proc(limit=args.limit, sort_by=args.sort)
 
-    add("proc", "显示占用最高的进程", None, proc_collect, render_proc,
+    add("proc", "显示占用最高的进程", proc_collect, render_proc,
         extra=proc_extra)
 
-    add("net", "显示网络接口与 DNS 信息", None, collect_net, render_net)
-    add("env", "显示相关环境变量", None, collect_env, render_env)
-    add("ports", "显示监听中的 TCP 端口", None, collect_ports, render_ports)
-    add("uptime", "显示系统运行时长与负载", None, collect_uptime, render_uptime)
-    add("doctor", "检查开发环境完整性", None, collect_doctor, render_doctor)
+    add("net", "显示网络接口与 DNS 信息", collect_net, render_net)
+    add("env", "显示相关环境变量", collect_env, render_env)
+    add("ports", "显示监听/绑定的 TCP 与 UDP 端口", collect_ports, render_ports)
+    add("uptime", "显示系统运行时长与负载", collect_uptime, render_uptime)
+    add("doctor", "检查开发环境完整性", collect_doctor, render_doctor)
 
     return parser
 
@@ -879,19 +1001,36 @@ def main(argv=None):
         parser.print_help()
         return 0
 
-    if getattr(args, "json", False) and not sys.stdout.isatty():
-        C.disable()
-
-    data = args.collector(args)
+    # 颜色状态在运行时按当前 stdout 判定（而非导入时），兼容 stdout
+    # 被重定向/替换的场景；NO_COLOR 约定依旧生效。
+    C._enabled = bool(sys.stdout.isatty()) and not os.environ.get("NO_COLOR")
 
-    if args.json:
-        print(json.dumps(data, indent=2, ensure_ascii=False))
-    else:
-        args.renderer(data)
-        print()
+    try:
+        data = args.collector(args)
+        emit(data, args.json, args.renderer)
+    except BrokenPipeError:
+        # 下游管道提前关闭（如 `sysx info | head`）：静默优雅退出，
+        # 并把 stdout 重定向到 devnull，避免解释器退出时再次 flush 报错。
+        try:
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        except OSError:
+            pass
+        return 0
+    except KeyboardInterrupt:
+        print("\n已取消", file=sys.stderr)
+        return 130
+    except Exception as exc:  # 单项失败给友好提示，不暴露 traceback
+        if getattr(args, "debug", False):
+            raise
+        print(f"sysx: {type(exc).__name__}: {exc}", file=sys.stderr)
+        print("（加 --debug 可查看完整堆栈）", file=sys.stderr)
+        return 1
 
     return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    try:
+        sys.exit(main())
+    except BrokenPipeError:
+        os._exit(0)

{sysx_cli-1.0.0 → sysx_cli-1.1.0/sysx_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysx-cli
-Version: 1.0.0
+Version: 1.1.0
 Summary: 轻量级系统信息与开发辅助 CLI 工具，纯标准库实现，零第三方依赖
 Author-email: maoxian3824 <maoxian3824@users.noreply.github.com>
 License-Expression: MIT
@@ -35,6 +35,8 @@ Dynamic: license-file
 
 # sysx
 
+> English version: [README.en.md](README.en.md)
+
 > 轻量级系统信息与开发辅助 CLI 工具 — 纯 Python 标准库实现，零第三方依赖。
 
 [![Tests](https://github.com/maoxian3824/sysx/actions/workflows/test.yml/badge.svg)](https://github.com/maoxian3824/sysx/actions/workflows/test.yml)
@@ -85,8 +87,8 @@ python3 sysx.py info
 ### 方式四：从 GitHub Release 安装
 
 ```bash
-curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.0.0-py3-none-any.whl
-pip install sysx_cli-1.0.0-py3-none-any.whl
+curl -LO https://github.com/maoxian3824/sysx/releases/latest/download/sysx_cli-1.1.0-py3-none-any.whl
+pip install sysx_cli-1.1.0-py3-none-any.whl
 ```
 
 ## 使用
@@ -104,7 +106,7 @@ sysx <命令> [选项]
 | `disk` | 磁盘挂载点与使用率（按使用率排序） |
 | `proc` | 占用最高的进程，可按 CPU / 内存排序 |
 | `net` | 网络接口、MAC、链路状态、本机 IP、DNS |
-| `ports` | 监听中的 TCP 端口 |
+| `ports` | 监听中的 TCP 与绑定的 UDP 端口 |
 | `env` | 相关环境变量（Shell、语言工具链、容器等） |
 | `uptime` | 运行时长与 1/5/15 分钟负载 |
 | `doctor` | 开发环境体检：工具链、网络、磁盘余量 |
@@ -216,7 +218,7 @@ sysx ports -j | jq -r '.[].port'
 | 磁盘挂载 | `/proc/mounts` + `shutil.disk_usage` |
 | 网络接口 | `/sys/class/net/*` |
 | DNS | `/etc/resolv.conf` |
-| 监听端口 | `/proc/net/tcp`、`/proc/net/tcp6` |
+| 监听/绑定端口 | `/proc/net/tcp`、`/proc/net/tcp6`、`/proc/net/udp`、`/proc/net/udp6` |
 
 **关于 CPU 占用率**：直接读 `/proc/<pid>/stat` 只能拿到进程的累计 CPU 时间，
 除以总和会得出错误结果（长运行进程会被严重高估）。`sysx` 采用两次采样（间隔 250ms）

{sysx_cli-1.0.0 → sysx_cli-1.1.0}/tests/test_sysx.py

@@ -9,13 +9,15 @@ sysx 自动化测试套件
     python3 tests/test_sysx.py
 """
 
+import argparse
+import datetime
 import io
 import json
 import os
 import subprocess
 import sys
 import unittest
-from contextlib import redirect_stdout
+from contextlib import redirect_stderr, redirect_stdout
 from unittest import mock
 
 # 让测试可以直接 import sysx.py
@@ -123,6 +125,46 @@ class TestHelpers(unittest.TestCase):
         self.assertEqual(sysx.render_bar(0, 10).count("█"), 0)
         self.assertEqual(sysx.render_bar(100, 10).count("█"), 10)
 
+    def test_render_bar_out_of_range_clamped(self):
+        # percent 超出 [0,100] 时必须被 clamp，进度条长度恒等于 width
+        sysx.C.disable()
+        for bad in (-10, 150, 999):
+            with self.subTest(percent=bad):
+                bar = sysx.render_bar(bad, width=20)
+                self.assertEqual(len(bar), 20)
+        # >100 时填满，<0 时为空
+        self.assertEqual(sysx.render_bar(150, 10).count("█"), 10)
+        self.assertEqual(sysx.render_bar(-5, 10).count("█"), 0)
+
+    def test_human_duration_negative_clamped(self):
+        # 负值（时钟回拨等异常）不应产生 "-1d -1h..." 这类输出
+        for raw in (-1, -3600, -999999):
+            with self.subTest(raw=raw):
+                out = sysx.human_duration(raw)
+                self.assertEqual(out, "0s")
+                self.assertNotIn("-", out)
+
+    def test_disp_width(self):
+        self.assertEqual(sysx._disp_width("abc"), 3)
+        self.assertEqual(sysx._disp_width("名称"), 4)   # CJK 双宽
+        self.assertEqual(sysx._disp_width("中a"), 3)
+
+    def test_render_table_cjk_header_width(self):
+        # 表头中文应按双宽计算，分隔行该列为 4 个 '-'
+        sysx.C.disable()
+        out = sysx.render_table(["项目"], [["os"]])
+        self.assertEqual(out.splitlines()[1], "----")
+
+    def test_human_bytes_negative_is_zero(self):
+        self.assertEqual(sysx.human_bytes(-1), "0 B")
+        self.assertEqual(sysx.human_bytes(-(1024 ** 3)), "0 B")
+
+    def test_render_bar_none(self):
+        sysx.C.disable()
+        bar = sysx.render_bar(None, width=10)
+        self.assertEqual(len(bar), 10)
+        self.assertEqual(bar.count("█"), 0)
+
 
 class TestColorControl(unittest.TestCase):
     """颜色控制与 NO_COLOR 约定。"""
@@ -247,7 +289,7 @@ class TestCollectors(unittest.TestCase):
         for item in data:
             self.assertIn("proto", item)
             self.assertIn("port", item)
-            self.assertIn(item["proto"], ("tcp", "tcp6"))
+            self.assertIn(item["proto"], ("tcp", "tcp6", "udp", "udp6"))
             self.assertGreater(item["port"], 0)
             self.assertLessEqual(item["port"], 65535)
 
@@ -439,5 +481,190 @@ class TestPackaging(unittest.TestCase):
         self.assertIn("Repository", urls)
 
 
+class TestPortParsing(unittest.TestCase):
+    """/proc/net/{tcp,udp} 端口解析的纯逻辑（用 mock 喂假数据）。"""
+
+    # 注意：IPv4 地址是小端十六进制。0100007F -> 127.0.0.1；00000000 -> 0.0.0.0
+    TCP = (
+        "  sl  local_address rem_address   st ...\n"
+        "   0: 0100007F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 111 1\n"
+        "   1: 00000000:0050 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 222 1\n"
+        "   2: 0100007F:9999 0100007F:1F90 01 00000000:00000000 00:00000000 00000000 1000 0 333 1\n"
+    )
+    UDP = (
+        "  sl  local_address rem_address   st ...\n"
+        "   0: 00000000:0035 00000000:0000 07 00000000:00000000 00:00000000 00000000 0 0 444 1\n"
+        "   1: 0100007F:1234 0100007F:9999 01 00000000:00000000 00:00000000 00000000 1000 0 555 1\n"
+    )
+
+    def run_collect(self, tcp, tcp6=None, udp=None, udp6=None):
+        mapping = {
+            "/proc/net/tcp": tcp,
+            "/proc/net/tcp6": tcp6,
+            "/proc/net/udp": udp,
+            "/proc/net/udp6": udp6,
+        }
+        with mock.patch.object(sysx, "read_text",
+                               side_effect=lambda p: mapping.get(p)):
+            return sysx.collect_ports(None)
+
+    def test_tcp_listen_parsed(self):
+        data = self.run_collect(tcp=self.TCP)
+        ports = {(p["proto"], p["port"]) for p in data}
+        self.assertIn(("tcp", 8080), ports)    # 0x1F90
+        self.assertIn(("tcp", 80), ports)      # 0x0050
+        # 状态非 LISTEN(0A) 的 9999(0x9999=39321) 不应出现
+        self.assertNotIn(("tcp", 39321), ports)
+
+    def test_ipv4_address_decoded(self):
+        data = self.run_collect(tcp=self.TCP)
+        by_port = {p["port"]: p for p in data}
+        self.assertEqual(by_port[8080]["address"], "127.0.0.1")
+        self.assertEqual(by_port[80]["address"], "0.0.0.0")
+
+    def test_udp_bound_parsed(self):
+        data = self.run_collect(tcp="", udp=self.UDP)
+        ports = {(p["proto"], p["port"]) for p in data}
+        self.assertIn(("udp", 53), ports)      # 0x0035
+        # 状态非 07 的 UDP(0x1234=4660) 不应出现
+        self.assertNotIn(("udp", 4660), ports)
+
+    def test_missing_files_skipped(self):
+        # 只喂 tcp，其余为 None，不应崩溃，且只产出 tcp
+        data = self.run_collect(tcp=self.TCP)
+        self.assertTrue(data)
+        self.assertTrue(all(p["proto"] == "tcp" for p in data))
+
+    def test_dedup_same_proto_port(self):
+        dup = self.TCP + (
+            "   3: 0100007F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 666 1\n"
+        )
+        data = self.run_collect(tcp=dup)
+        tcp_8080 = [p for p in data if p["proto"] == "tcp" and p["port"] == 8080]
+        self.assertEqual(len(tcp_8080), 1)
+
+    def test_invalid_port_hex_skipped(self):
+        broken = (
+            "  sl  local_address rem_address   st ...\n"
+            "   0: 0100007F:ZZZZ 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 1 1\n"
+            "   1: 0100007F:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 2 1\n"
+        )
+        data = self.run_collect(tcp=broken)
+        self.assertEqual([p["port"] for p in data if p["proto"] == "tcp"], [8080])
+
+    def test_invalid_ip_hex_yields_question_mark(self):
+        broken = (
+            "  sl  local_address rem_address   st ...\n"
+            "   0: ZZZZZZZZ:1F90 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 1 1\n"
+        )
+        data = self.run_collect(tcp=broken)
+        self.assertEqual(len(data), 1)
+        self.assertEqual(data[0]["port"], 8080)
+        self.assertEqual(data[0]["address"], "?")
+
+    def test_decode_ipv6(self):
+        self.assertEqual(sysx._decode_ipv6("0" * 32), "::")
+        # 内核小端表示的 loopback ::1
+        self.assertEqual(sysx._decode_ipv6("00000000000000000000000001000000"), "::1")
+        # 长度不足或非法均返回 "?"
+        self.assertEqual(sysx._decode_ipv6("00" * 15), "?")
+        self.assertEqual(sysx._decode_ipv6("xyz"), "?")
+
+    def test_unescape_mount(self):
+        self.assertEqual(sysx._unescape_mount("/mnt/my\\040disk"), "/mnt/my disk")
+        self.assertEqual(sysx._unescape_mount("/a\\134b"), "/a\\b")  # \134 = 反斜杠
+        self.assertEqual(sysx._unescape_mount("/plain/path"), "/plain/path")
+
+
+class TestDistroParsing(unittest.TestCase):
+    """/etc/os-release 解析：引号剥离与续行合并。"""
+
+    def _read(self, content):
+        with mock.patch.object(sysx, "read_text", return_value=content):
+            return sysx._read_distro()
+
+    def test_quotes_stripped_once(self):
+        content = 'NAME="Ubuntu"\nPRETTY_NAME="Ubuntu 24.04.3 LTS"\n'
+        self.assertEqual(self._read(content), "Ubuntu 24.04.3 LTS")
+
+    def test_unmatched_quote_preserved(self):
+        # 仅一端有引号时不应剥离（旧 .strip('"') 会误剥首引号）
+        content = 'PRETTY_NAME="Ubuntu\n'
+        self.assertEqual(self._read(content), '"Ubuntu')
+
+    def test_inner_quote_not_stripped(self):
+        # 首尾不成对（尾非引号）时，旧 .strip('"') 会误伤首引号
+        content = 'PRETTY_NAME="a"b\n'
+        self.assertEqual(self._read(content), '"a"b')
+
+    def test_single_quotes(self):
+        content = "PRETTY_NAME='Arch Linux'\n"
+        self.assertEqual(self._read(content), "Arch Linux")
+
+    def test_line_continuation(self):
+        # 反斜杠续行应被合并
+        content = 'NAME="Debian\\\n GNU/Linux"\n'
+        self.assertEqual(self._read(content), "Debian GNU/Linux")
+
+    def test_pretty_name_preferred(self):
+        content = 'NAME="Ubuntu"\nPRETTY_NAME="Ubuntu 24.04"\n'
+        self.assertEqual(self._read(content), "Ubuntu 24.04")
+
+    def test_fallback_to_name(self):
+        content = 'NAME="Alpine"\nID=alpine\n'
+        self.assertEqual(self._read(content), "Alpine")
+
+    def test_empty_returns_none(self):
+        self.assertIsNone(self._read(""))
+        self.assertIsNone(self._read(None))
+
+    def test_newline_unescape(self):
+        # 值内的 \n 应还原为真实换行
+        content = 'PRETTY_NAME="Line1\\nLine2"\n'
+        self.assertEqual(self._read(content), "Line1\nLine2")
+
+
+class TestRobustness(unittest.TestCase):
+    """平台判断、启动时间、debug 模式等健壮性逻辑。"""
+
+    def test_is_root_returns_bool_or_none(self):
+        r = sysx._is_root()
+        # Linux 返回 bool；无 geteuid 的平台返回 None
+        self.assertTrue(r is None or isinstance(r, bool))
+
+    def test_read_boot_time_parses_btime(self):
+        fake = "cpu  1 2 3\nbtime 1700000000\nprocesses 10\n"
+        with mock.patch.object(sysx, "read_text", return_value=fake):
+            bt = sysx._read_boot_time()
+        self.assertEqual(bt, datetime.datetime.fromtimestamp(1700000000))
+
+    def test_read_boot_time_missing(self):
+        with mock.patch.object(sysx, "read_text", return_value=None):
+            self.assertIsNone(sysx._read_boot_time())
+
+    def test_debug_reraises_exception(self):
+        def boom(args):
+            raise ValueError("boom")
+        args = argparse.Namespace(command="info", json=False, debug=True,
+                                  collector=boom, renderer=lambda d: None)
+        with mock.patch.object(sysx, "build_parser") as bp:
+            bp.return_value.parse_args.return_value = args
+            with self.assertRaises(ValueError):
+                sysx.main([])
+
+    def test_no_debug_returns_one_on_error(self):
+        def boom(args):
+            raise ValueError("boom")
+        args = argparse.Namespace(command="info", json=False, debug=False,
+                                  collector=boom, renderer=lambda d: None)
+        with mock.patch.object(sysx, "build_parser") as bp:
+            bp.return_value.parse_args.return_value = args
+            buf = io.StringIO()
+            with redirect_stderr(buf):
+                rc = sysx.main([])
+        self.assertEqual(rc, 1)
+        self.assertIn("ValueError", buf.getvalue())
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)