campus-auth 1.0.0__py3-none-any.whl

campus_auth/__init__.py

@@ -0,0 +1,6 @@
+"""campus-auth —— Dr.COM / eportal 校园网门户认证客户端。"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

campus_auth/__main__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

campus_auth/adapters/__init__.py

@@ -0,0 +1,58 @@
+"""适配层注册表。
+
+内置适配层在这里登记；也可以用 `--adapter module:attribute` 从任意
+Python 文件加载（写学校适配层时不必改本文件，方便 PR 之外的自用）。
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Final
+
+from ..errors import ConfigError
+from .base import Adapter, LoginResult, Param
+
+BUILTIN: Final[dict[str, str]] = {
+    "huuc": "campus_auth.adapters.huuc:ADAPTER",
+    "generic": "campus_auth.adapters.example_generic:ADAPTER",
+}
+
+_cache: dict[str, Adapter] = {}
+
+
+def _load_target(target: str) -> Adapter:
+    module_name, _, attr = target.partition(":")
+    attr = attr or "ADAPTER"
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise ConfigError(f"导出适配层失败（{target}）: {exc}") from exc
+    try:
+        adapter = getattr(module, attr)
+    except AttributeError as exc:
+        raise ConfigError(f"{module_name} 里没有 {attr!r}") from exc
+    if not isinstance(adapter, Adapter):
+        raise ConfigError(f"{target} 是 {type(adapter).__name__}，不是 Adapter 实例")
+    adapter.check()
+    return adapter
+
+
+def get_adapter(name: str) -> Adapter:
+    """按名字取适配层，`a:b` 形式走动态加载。"""
+    if not name:
+        raise ConfigError("没有指定适配层（adapter），跑 `campus-auth init` 会生成模板")
+    if name in _cache:
+        return _cache[name]
+    target = name if ":" in name else BUILTIN.get(name, "")
+    if not target:
+        raise ConfigError(f"没有适配层 {name!r}，内置的有: {', '.join(BUILTIN)}")
+    adapter = _load_target(target)
+    _cache[name] = adapter
+    return adapter
+
+
+def names() -> list[str]:
+    return sorted(BUILTIN)
+
+
+__all__ = ["Adapter", "LoginResult", "Param", "BUILTIN", "get_adapter", "names"]

campus_auth/adapters/base.py

@@ -0,0 +1,272 @@
+"""适配层基类。
+
+一个适配层只描述"某所学校门户的差异"，不实现 HTTP、重试、CLI。
+差异面被压缩成四件事：
+
+1. 请求怎么发：路径、方法、查询串、表单体（`Request`）
+2. 参数怎么编码（`key_style` + `encoder`）
+3. 账号怎么拼（前缀、运营商后缀）
+4. 响应怎么解读（`interpret_login` / `interpret_sessions`）
+
+默认行为（GET + JSONP + `list` 数组 + `result`/`ret_code`）覆盖 Dr.COM 系；
+某所学校需要变的东西，只覆盖对应方法，不重写 core。
+新增一所学校 = 抄一份 `example_generic.py` 改常量，别动 core。
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ..crypto import xor_hex, xor_key
+
+__all__ = ["Adapter", "LoginResult", "Param", "PortalLike", "Request"]
+
+
+class Param(tuple):
+    """一个查询参数: (键, 明文值, 是否参与编码)。"""
+
+    def __new__(cls, key: str, value: str, encode: bool = True) -> Param:
+        return super().__new__(cls, (key, value, encode))
+
+    key = property(lambda self: self[0])
+    value = property(lambda self: self[1])
+    encode = property(lambda self: self[2])
+
+
+@dataclass(frozen=True)
+class Request:
+    """一次门户请求。`path` 可相对 `base_url`，也可给完整 URL（跨主机发现时用）。"""
+
+    path: str
+    method: str = "GET"
+    params: list[Param] = field(default_factory=list)
+    body: dict[str, str] = field(default_factory=dict)
+    headers: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def is_absolute(self) -> bool:
+        return self.path.startswith(("http://", "https://"))
+
+
+class PortalLike(Protocol):
+    """适配层眼里的 `Portal`：只承诺下面这些属性和动作。
+
+    真 `Portal` 结构性满足它；测试里的假门户类型不参与运行时检查，照旧能塞。
+    """
+
+    base_url: str
+    ip: str
+    mac: str
+    account: str
+    password: str
+    operator: str
+    ctx: dict[str, object]
+
+    def raw(self, url: str, *, timeout: float | None = None) -> tuple[int, str]: ...
+
+    def request(self, request: Request) -> dict[str, object]: ...
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    ok: bool
+    msg: str
+    ret_code: int | None = None
+    hint: str = ""
+
+
+Encoder = Callable[[str], str]
+
+
+@dataclass(frozen=True)
+class Adapter:
+    name: str
+    school: str
+    base_url: str
+    key_style: str = "ip-xor"
+    account_prefix: str = ""
+    operator_suffixes: Mapping[str, str] = field(default_factory=dict)
+    js_version: str = ""
+    login_path: str = "/eportal/portal/login"
+    logout_path: str = "/eportal/portal/logout"
+    unbind_path: str = "/eportal/portal/mac/unbind"
+    online_path: str = "/eportal/portal/online_list"
+    callback_prefix: str = "dr"
+    timeout: float = 20.0
+    verify_tls: bool = False
+    status: str = "已验证"
+    notes: str = ""
+
+    # ---------- 编码 ----------
+
+    def encoder(self, ip: str) -> Encoder:
+        """返回一个把明文变密文的函数。"""
+        if self.key_style == "plain":
+            return lambda text: text
+        if self.key_style == "ip-xor":
+            key = xor_key(ip)
+            return lambda text: xor_hex(text, key)
+        raise ValueError(f"未知 key_style: {self.key_style!r}")
+
+    # ---------- 账号 ----------
+
+    def format_account(self, account: str, operator: str = "none") -> str:
+        suffix = self.operator_suffixes.get(operator, "") if operator else ""
+        return f"{self.account_prefix}{account}{suffix}"
+
+    def operator_names(self) -> list[str]:
+        return ["none", *self.operator_suffixes]
+
+    # ---------- 参数 ----------
+
+    def callback(self, action: str) -> str:
+        return f"{self.callback_prefix}{action}"
+
+    def account_params(self, account: str, password: str, operator: str) -> list[Param]:
+        return [
+            Param("user_account", self.format_account(account, operator)),
+            Param("user_password", password),
+        ]
+
+    def identity_params(self, ip: str, mac: str) -> list[Param]:
+        """每个请求都带的身份参数；`wlan_ac_ip` 等手段留空。"""
+        params = [
+            Param("wlan_user_ip", ip),
+            Param("wlan_user_ipv6", "", encode=False),
+            Param("wlan_user_mac", mac),
+            Param("wlan_ac_ip", "", encode=False),
+            Param("wlan_ac_name", "", encode=False),
+        ]
+        if self.js_version:
+            params.append(Param("jsVersion", self.js_version))
+        params += [
+            Param("captcha", "", encode=False),
+            Param("terminal_type", "1"),
+            Param("lang", "zh"),
+            Param("encrypt", "1", encode=False),
+            Param("v", self.nonce(), encode=False),
+            Param("lang", "zh", encode=False),  # 前端确实发了两次 lang
+        ]
+        return params
+
+    @staticmethod
+    def nonce() -> str:
+        return f"0.{random.randint(10**15, 10**16 - 1)}"
+
+    # ---------- 发现（锐捷要门户地址，深澜要 challenge） ----------
+
+    def discover(self, portal: PortalLike, account: str) -> dict[str, object]:
+        """登录前的准备请求；默认什么都不做。结果放进 `portal.ctx`。"""
+        return {}
+
+    # ---------- 请求构造 ----------
+
+    def login_request(self, portal: PortalLike) -> Request:
+        ip, mac = portal.ip, portal.mac
+        cb = self.callback("1003")
+        return Request(
+            path=self.login_path,
+            params=[
+                Param("callback", cb),
+                Param("login_method", "1"),
+                *self.account_params(
+                    portal.account,
+                    portal.password,
+                    portal.operator,
+                ),
+                *self.identity_params(ip, mac),
+            ],
+        )
+
+    def logout_request(self, portal: PortalLike) -> Request:
+        ip, mac = portal.ip, portal.mac
+        cb = self.callback("1004")
+        return Request(
+            path=self.logout_path,
+            params=[
+                Param("callback", cb),
+                Param("login_method", "1"),
+                Param("user_account", "drcom"),
+                Param("user_password", "123"),
+                Param("ac_logout", "1"),
+                Param("register_mode", "1"),
+                Param("wlan_vlan_id", "0"),
+                *self.identity_params(ip, mac),
+            ],
+        )
+
+    def unbind_request(self, portal: PortalLike) -> Request:
+        ip, mac = portal.ip, portal.mac
+        params = [
+            Param("callback", self.callback("1005")),
+            Param("user_account", portal.account),
+            Param("wlan_user_mac", mac),
+            Param("wlan_user_ip", ip),
+        ]
+        if self.js_version:
+            params.append(Param("jsVersion", self.js_version))
+        params += [
+            Param("encrypt", "1", encode=False),
+            Param("v", self.nonce(), encode=False),
+            Param("lang", "zh"),
+            Param("lang", "zh", encode=False),
+        ]
+        return Request(path=self.unbind_path, params=params)
+
+    def sessions_request(self, portal: PortalLike) -> Request:
+        return Request(path=self.online_path, params=self.online_params())
+
+    def online_params(self) -> list[Param]:
+        return [Param("callback", "cb", encode=False), Param("lang", "zh", encode=False)]
+
+    # ---------- 响应解读 ----------
+
+    def interpret_login(self, resp: Mapping[str, object]) -> LoginResult:
+        code = resp.get("ret_code")
+        ret_code = (
+            int(code) if isinstance(code, int | str) and str(code).lstrip("-").isdigit() else None
+        )
+        msg = str(resp.get("msg") or "")
+        ok = resp.get("result") in (1, "1", True) and ret_code in (0, None)
+        return LoginResult(ok=ok, msg=msg, ret_code=ret_code, hint=self.hint_for(ret_code, msg))
+
+    def hint_for(self, ret_code: int | None, msg: str) -> str:
+        """把服务端的含糊报错翻译成人话；子类按需覆盖。"""
+        if ret_code in (0, None):
+            return ""
+        return f"服务端返回 ret_code={ret_code}，原文: {msg or '(空)'}"
+
+    def interpret_sessions(self, payload: Mapping[str, object]) -> list[Mapping[str, object]]:
+        """从会话接口的响应里取出会话行；默认认 `list` 数组。"""
+        rows = payload.get("list") or []
+        return [row for row in rows if isinstance(row, dict)]  # type: ignore[misc]
+
+    def row_is_mine(self, row: Mapping[str, object], ip: str, mac: str, account: str = "") -> bool:
+        """IP 对上、且（给了账号时）账号也对上 —— 别人占着这个 IP 不算你的会话。"""
+        if str(row.get("online_ip") or "") != ip:
+            return False
+        if not account:
+            return True
+        actual = str(row.get("user_account") or row.get("user_name") or "")
+        return not actual or account in actual
+
+    def online_check(self, portal: PortalLike) -> bool | None:
+        """在线判定。返回 None 表示"走会话列表"，返回 True/False 表示自己判定。"""
+        return None
+
+    def after_login(self, portal: PortalLike, payload: Mapping[str, object]) -> None:
+        """登录成功后收尾（比如存下 userIndex）；默认什么都不做。"""
+
+    def zone_hint(self, ip: str, ssid: str | None) -> str:
+        return ""
+
+    # ---------- 自检 ----------
+
+    def check(self) -> None:
+        if self.key_style not in {"plain", "ip-xor"}:
+            raise ValueError(f"{self.name}: 未知 key_style {self.key_style!r}")
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ValueError(f"{self.name}: base_url 必须以 http(s):// 开头")

campus_auth/adapters/example_generic.py

@@ -0,0 +1,37 @@
+"""通用 eportal 适配层模板 —— 抄这份改成你的学校。
+
+**先跑 `campus-auth probe --url <门户地址>` 确认是 Dr.COM**，判成别的就别往下写。
+
+改的时候按这个顺序核对（F12 → Network，作为普通用户点一次登录）：
+
+1. 参数名不同 → 覆盖 `account_params()` / `identity_params()` 或整个 `login_request()`。
+2. 参数值是 `%xx` 十六进制 → `key_style="ip-xor"`，并把密钥算法写进 `encoder()` 的
+   返回函数（常见是 MAC 或固定盐，密钥一致才有用）。
+3. 响应不是 JSON → 覆盖 `interpret_login()` 和 `hint_for()`。
+4. 路径不同 → 改 `login_path` / `logout_path` 这些字段。
+
+改完在 `adapters/__init__.py` 的 `BUILTIN` 登记，再跑
+`campus-auth status --adapter <代号>` 和一次真机 `login`。
+"""
+
+from __future__ import annotations
+
+from .base import Adapter
+
+
+class GenericAdapter(Adapter):
+    def __init__(self) -> None:
+        super().__init__(
+            name="generic",
+            school="未具名学校（模板）",
+            base_url="http://10.0.0.1:8080",
+            key_style="plain",
+            account_prefix=",0,",
+            operator_suffixes={},
+            js_version="4.2.1",
+            status="模板",
+            notes="改 base_url 和各路径后先跑 `campus-auth status` 验证能不能连通。",
+        )
+
+
+ADAPTER = GenericAdapter()

campus_auth/adapters/huuc.py

@@ -0,0 +1,92 @@
+"""河南城建学院（HUUC）适配层 —— UCLINK / UCSIG 门户。
+
+协议来自门户前端 `a41.js` 的 `getkey` / `enc_pwd` 以及抓包核对：
+
+* 密钥 = `wlan_user_ip` 各字符 ASCII 逐位异或
+* 账号要带 `,0,` 前缀；宿舍（UCSIG）还要挂运营商后缀
+* `wlan_user_mac` 服务端不校验，可填全 0
+* 成功与否一律以 `online_list` 里出现自己的 IP 为准，别信 `msg`
+
+宿舍联通/电信多数账号还没在运营商侧开通，现象是 `unbind isp uid` /
+`AC认证失败` —— 那是运营商的问题，不是密码错。
+"""
+
+from __future__ import annotations
+
+from ..adapters.base import Adapter, LoginResult
+from ..crypto import xor_key
+
+PORTAL_IP = "10.210.213.208"
+
+# (区域说明, SSID, 建议后缀)
+SSID_ZONES = {
+    "UCLINK": ("教学楼/图书馆", "UCLINK", "none"),
+    "UCSIG": ("宿舍", "UCSIG", "cmcc"),
+}
+SUBNET_ZONES = {
+    "10.152.": ("教学楼/图书馆", "UCLINK", "none"),
+    "10.138.": ("宿舍", "UCSIG", "cmcc"),
+}
+
+HINTS = {
+    "unbind isp uid": "运营商侧还没绑定这个账号：宿舍请确认已开通宽带，或换 -w cmcc。",
+    "AC认证失败": "AC 认证失败，多因运营商侧未开通或该 SSID 只收特定运营商。",
+    "账号或密码错误": "账号或密码不对；账号是纯数字学号，不要带 @ 后缀（后缀由 -w 拼）。",
+    "用户已在线": "已经在线了，直接跑 status 看看。",
+    "没有可解析的 JSON": "门户回的是页面不是 JSON：确认 base_url 指到 eportal 入口，不是门户首页。",
+}
+
+
+class HuucAdapter(Adapter):
+    def __init__(self) -> None:
+        super().__init__(
+            name="huuc",
+            school="河南城建学院",
+            base_url="https://netauth.huuc.edu.cn:802",
+            key_style="ip-xor",
+            account_prefix=",0,",
+            operator_suffixes={"cmcc": "@cmcc", "unicom": "@unicom", "dx": "@dx"},
+            js_version="4.2.1",
+            notes=f"门户 IP {PORTAL_IP}；netauth.huuc.edu.cn:802。",
+        )
+
+    def zone_of(self, ip: str, ssid: str | None) -> tuple[str, str | None, str | None, str]:
+        """(区域, SSID, 应选后缀, 依据)。依据是 ssid / subnet / none。"""
+        if ssid and ssid in SSID_ZONES:
+            return (*SSID_ZONES[ssid], "ssid")
+        for prefix, info in SUBNET_ZONES.items():
+            if ip.startswith(prefix):
+                return (*info, "subnet")
+        return ("未知", ssid, None, "none")
+
+    def zone_hint(self, ip: str, ssid: str | None) -> str:
+        area, seen, want, source = self.zone_of(ip, ssid)
+        if want is None:
+            return f"没认出所在区域（SSID {seen or '未知'}），如果在宿舍要手动加 -w cmcc。"
+        if want == "none":
+            return ""
+        if want == "cmcc":
+            return f"看着像{area}（{source}），宿舍一般要加 -w cmcc，否则多半 AC 认证失败。"
+        return ""
+
+    def hint_for(self, ret_code: int | None, msg: str) -> str:
+        for needle, hint in HINTS.items():
+            if needle in msg:
+                return hint
+        if "AC认证失败" in msg or "isp uid" in msg:
+            return HINTS["AC认证失败"]
+        return super().hint_for(ret_code, msg)
+
+    def interpret_login(self, resp):
+        result = super().interpret_login(resp)
+        if not result.ok and not result.hint:
+            result = LoginResult(False, result.msg, result.ret_code, "服务端拒绝但没给可读原因。")
+        return result
+
+
+ADAPTER = HuucAdapter()
+
+
+def key_for(ip: str) -> int:
+    """便于排查：直接看某个 IP 派生出的密钥。"""
+    return xor_key(ip)

campus_auth/cli.py

@@ -0,0 +1,165 @@
+"""命令行入口：只有 parser、分之调度和退出码。
+
+各子命令的实现都在 `commands.py`。
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import sys
+import traceback
+
+from . import __version__, adapters
+from .commands import (
+    _dump,
+    _err,
+    cmd_adapters,
+    cmd_check,
+    cmd_init,
+    cmd_install,
+    cmd_login,
+    cmd_logout,
+    cmd_password,
+    cmd_probe,
+    cmd_status,
+    cmd_unbind,
+    cmd_uninstall,
+    cmd_urls,
+    cmd_watch,
+)
+from .errors import (
+    EXIT_CONFIG,
+    EXIT_ENV,
+    EXIT_OK,
+    CampusAuthError,
+    ConfigError,
+    EnvironmentError_,
+)
+
+__all__ = ["main"]
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="campus-auth",
+        description="Dr.COM / eportal 校园网门户认证客户端",
+        epilog="适配层用 --adapter 选，内置: " + ", ".join(adapters.names()),
+    )
+    parser.add_argument("--version", action="version", version=f"campus-auth {__version__}")
+    parser.add_argument(
+        "--show-secrets", action="store_true", help="报错里的密码不打码（默认打码）"
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--config", help="配置文件路径")
+    common.add_argument("--adapter", help="适配层名，或 module:attr")
+    common.add_argument("-a", "--account", help="学号（纯数字，不带 @ 后缀）")
+    common.add_argument("-w", "--operator", help="运营商 none/cmcc/unicom/dx")
+    common.add_argument("-p", "--password", help="密码（不推荐，会留在历史里）")
+    common.add_argument("--password-stdin", action="store_true", help="从标准输入读密码")
+    common.add_argument("--mac", help="覆盖 MAC（12 位十六进制）")
+    common.add_argument("--ip", help="覆盖本机 IP（离线生成 URL 时用）")
+    common.add_argument("--url", help="覆盖门户地址")
+    common.add_argument("--timeout", type=float, help="单次请求超时秒数")
+    common.add_argument("--retries", type=int, help="传输重试次数")
+    common.add_argument("--verify-tls", action="store_true", help="校验证书")
+    common.add_argument("--json", action="store_true", help="输出 JSON")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init", parents=[common], help="生成配置模板")
+    init.add_argument("-o", "--output", help="写到哪个文件")
+    init.add_argument("-f", "--force", action="store_true", help="覆盖已有文件")
+    init.set_defaults(func=cmd_init)
+
+    sub.add_parser("adapters", parents=[common], help="列出内置适配层").set_defaults(
+        func=cmd_adapters
+    )
+    login_p = sub.add_parser("login", parents=[common], help="登录")
+    login_p.add_argument("--remember", action="store_true", help="成功后把密码存进系统钥匙串")
+    login_p.set_defaults(func=cmd_login)
+    sub.add_parser("logout", parents=[common], help="注销").set_defaults(func=cmd_logout)
+    sub.add_parser("unbind", parents=[common], help="解除 MAC 绑定").set_defaults(func=cmd_unbind)
+    sub.add_parser("status", parents=[common], help="查看在线会话").set_defaults(func=cmd_status)
+
+    check = sub.add_parser("check", parents=[common], help="只查在线状态，用退出码表达")
+    check.add_argument("-q", "--quiet", action="store_true")
+    check.set_defaults(func=cmd_check)
+
+    probe_p = sub.add_parser(
+        "probe", parents=[common], help="探测门户是不是 Dr.COM（--url 给地址）"
+    )
+    probe_p.set_defaults(func=cmd_probe)
+
+    urls = sub.add_parser("urls", parents=[common], help="为当前 IP 生成快捷方式")
+    urls.add_argument("-o", "--output", help="输出目录")
+    urls.set_defaults(func=cmd_urls)
+
+    watch_p = sub.add_parser("watch", parents=[common], help="断线自动重连")
+    watch_p.add_argument("--once", action="store_true", help="只跑一轮")
+    watch_p.add_argument("--cycles", type=int, help="跑多少轮后退出")
+    watch_p.add_argument("--interval", type=float, help="两轮间隔秒数")
+    watch_p.add_argument("--log", help="同时写进这个文件（按 1 MiB 轮转，留一份 .1）")
+    watch_p.set_defaults(func=cmd_watch)
+
+    password_p = sub.add_parser("password", parents=[common], help="把密码存进/删出系统钥匙串")
+    password_p.add_argument("--forget", action="store_true", help="删掉存着的密码")
+    password_p.add_argument("--show", action="store_true", help="只看有没有存，不写入")
+    password_p.set_defaults(func=cmd_password)
+
+    install_p = sub.add_parser(
+        "install", parents=[common], help="把 watch 装成登录自启（计划任务 / systemd / launchd）"
+    )
+    install_p.add_argument("--dry-run", action="store_true", help="只打印要写什么、跑什么")
+    install_p.set_defaults(func=cmd_install)
+
+    uninstall_p = sub.add_parser("uninstall", parents=[common], help="卸掉 install 装的自启")
+    uninstall_p.add_argument("--dry-run", action="store_true", help="只打印要跑什么")
+    uninstall_p.set_defaults(func=cmd_uninstall)
+    return parser
+
+
+def _force_utf8() -> None:
+    """重定向到文件/管道时也保证输出是 UTF-8，别变成 GBK 乱码。"""
+    for stream in (sys.stdout, sys.stderr):
+        with contextlib.suppress(AttributeError, ValueError, OSError):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8()
+    args = _parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except ConfigError as exc:
+        _err(f"配置: {exc}")
+        return EXIT_CONFIG
+    except EnvironmentError_ as exc:
+        _err(f"环境: {exc}")
+        return EXIT_ENV
+    except CampusAuthError as exc:
+        _err(str(exc))
+        if args.json:
+            _dump({"ok": False, "error": str(exc)})
+        return exc.exit_code
+    except KeyboardInterrupt:
+        _err("已中断")
+        return 130
+    except (BrokenPipeError, OSError) as exc:
+        # `campus-auth ... | head` 会在这里断掉；Windows 上是 errno 22，POSIX 是 32
+        if isinstance(exc, BrokenPipeError) or getattr(exc, "errno", None) in {22, 32}:
+            with contextlib.suppress(OSError, ValueError):
+                sys.stdout = open(os.devnull, "w")  # noqa: SIM115
+            return EXIT_OK
+        _err(f"意外错误: {exc!r}")
+        traceback.print_exc()
+        return 70
+    except Exception as exc:  # 未预期的错误给 traceback，别静默
+        _err(f"意外错误: {exc!r}")
+        traceback.print_exc()
+        return 70
+
+
+if __name__ == "__main__":
+    sys.exit(main())