procproxy 0.1.0__py3-none-any.whl

proxycore/backend/windivert/pkt.py

@@ -0,0 +1,424 @@
+"""路线 A · IPv4/IPv6 报文解析与改写 + 校验和重算。
+
+为什么必须有这个模块：WinDivert 改写目的地址/端口后，IP 头校验和与
+TCP/UDP 伪头校验和都会失效，漏算的表现就是"连接卡死在 SYN_SENT"
+。pydivert 的 `recalculate_checksums()` 能做这件事，
+但：
+* 我们要在没有驱动、没有管理员权限的环境里也能验证（单测用字节样本）；
+* 需要明确的"改了什么、重算了什么"语义，便于排错。
+
+因此本模块只做纯字节运算，不依赖 pydivert/驱动。
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+import struct
+from dataclasses import dataclass, field
+
+IPPROTO_TCP = 6
+IPPROTO_UDP = 17
+
+IPV4_MIN_HEADER = 20
+IPV6_HEADER = 40
+TCP_MIN_HEADER = 20
+UDP_HEADER = 8
+
+FIN = 0x01
+SYN = 0x02
+RST = 0x04
+PSH = 0x08
+ACK = 0x10
+
+
+class PacketError(ValueError):
+    """报文无法解析（长度不足/版本不支持/扩展头不支持）。"""
+
+
+# ============================================================ 校验和 =======
+def ones_complement_sum(data: bytes, initial: int = 0) -> int:
+    """RFC 1071 的 16 位反码和。"""
+    total = initial
+    length = len(data)
+    if length & 1:
+        total += data[-1] << 8
+        length -= 1
+    # 用 4 字节步进减少 Python 循环次数
+    if length:
+        total += sum(struct.unpack(f"!{length // 2}H", data[:length]))
+    while total >> 16:
+        total = (total & 0xFFFF) + (total >> 16)
+    return total
+
+
+def finish_checksum(total: int) -> int:
+    """反码和 → 校验和（取反）。"""
+    return (~total) & 0xFFFF
+
+
+def checksum(data: bytes, initial: int = 0) -> int:
+    return finish_checksum(ones_complement_sum(data, initial))
+
+
+def pseudo_header_v4(src: str, dst: str, proto: int, length: int) -> bytes:
+    return (
+        socket.inet_aton(src)
+        + socket.inet_aton(dst)
+        + bytes([0, proto])
+        + struct.pack("!H", length)
+    )
+
+
+def pseudo_header_v6(src: str, dst: str, proto: int, length: int) -> bytes:
+    return (
+        socket.inet_pton(socket.AF_INET6, src)
+        + socket.inet_pton(socket.AF_INET6, dst)
+        + struct.pack("!I", length)  # 32 位长度
+        + b"\x00\x00\x00"  # 3 字节零
+        + bytes([proto])
+    )
+
+
+def verify_v4_header_checksum(packet: bytes) -> bool:
+    """校验 IPv4 头校验和（重算后应与之相等）。"""
+    if len(packet) < IPV4_MIN_HEADER:
+        raise PacketError(f"IPv4 报文过短：{len(packet)}")
+    ihl = (packet[0] & 0x0F) * 4
+    return ones_complement_sum(packet[:ihl]) == 0xFFFF
+
+
+def verify_transport_checksum(packet: bytes) -> bool:
+    """校验 IPv4 + TCP/UDP 的传输层校验和（含伪头）。"""
+    parsed = ParsedPacket.parse(packet)
+    return parsed.transport_checksum_valid
+
+
+# ============================================================ 报文结构 =====
+@dataclass(slots=True)
+class ParsedPacket:
+    """一条 IPv4/IPv6 报文的结构化视图（支持原地改写后再序列化）。"""
+
+    raw: bytearray
+    is_v6: bool
+    ip_header_len: int
+    proto: int
+    src_addr: str
+    dst_addr: str
+    src_port: int
+    dst_port: int
+    tcp_flags: int = 0
+    tcp_seq: int = 0
+    tcp_ack: int = 0
+    # 供排错/统计
+    total_length: int = 0
+    payload_len: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+    # ------------------------------------------------------------ 解析 -----
+    @classmethod
+    def parse(cls, packet: bytes | bytearray) -> ParsedPacket:
+        raw = bytearray(packet)
+        if not raw:
+            raise PacketError("空报文")
+        version = raw[0] >> 4
+        if version == 4:
+            return cls._parse_v4(raw)
+        if version == 6:
+            return cls._parse_v6(raw)
+        raise PacketError(f"不支持的 IP 版本：{version}")
+
+    @classmethod
+    def _parse_v4(cls, raw: bytearray) -> ParsedPacket:
+        if len(raw) < IPV4_MIN_HEADER:
+            raise PacketError(f"IPv4 报文过短：{len(raw)}")
+        ihl = (raw[0] & 0x0F) * 4
+        if ihl < IPV4_MIN_HEADER or len(raw) < ihl:
+            raise PacketError(f"IPv4 头长度非法：{ihl}")
+        total_length = struct.unpack_from("!H", raw, 2)[0] or len(raw)
+        proto = raw[9]
+        src = socket.inet_ntoa(bytes(raw[12:16]))
+        dst = socket.inet_ntoa(bytes(raw[16:20]))
+        parsed = cls(
+            raw=raw,
+            is_v6=False,
+            ip_header_len=ihl,
+            proto=proto,
+            src_addr=src,
+            dst_addr=dst,
+            src_port=0,
+            dst_port=0,
+            total_length=total_length,
+        )
+        parsed._parse_transport()
+        return parsed
+
+    @classmethod
+    def _parse_v6(cls, raw: bytearray) -> ParsedPacket:
+        if len(raw) < IPV6_HEADER:
+            raise PacketError(f"IPv6 报文过短：{len(raw)}")
+        payload_len = struct.unpack_from("!H", raw, 4)[0]
+        next_header = raw[6]
+        src = socket.inet_ntop(socket.AF_INET6, bytes(raw[8:24]))
+        dst = socket.inet_ntop(socket.AF_INET6, bytes(raw[24:40]))
+        parsed = cls(
+            raw=raw,
+            is_v6=True,
+            ip_header_len=IPV6_HEADER,
+            proto=next_header,
+            src_addr=src,
+            dst_addr=dst,
+            src_port=0,
+            dst_port=0,
+            total_length=IPV6_HEADER + payload_len if payload_len else len(raw),
+        )
+        if next_header in (0, 43, 44, 60):
+            # 扩展头：本实现不解析
+            parsed.proto = 0
+            parsed.warnings.append(f"IPv6 扩展头未处理（NextHeader={next_header}）")
+            parsed.payload_len = payload_len
+            return parsed
+        parsed._parse_transport()
+        return parsed
+
+    def _parse_transport(self) -> None:
+        offset = self.ip_header_len
+        available = len(self.raw) - offset
+        if self.proto == IPPROTO_TCP:
+            if available < TCP_MIN_HEADER:
+                raise PacketError(f"TCP 头长度不足：{available}")
+            self.src_port, self.dst_port = struct.unpack_from("!HH", self.raw, offset)
+            self.tcp_seq = struct.unpack_from("!I", self.raw, offset + 4)[0]
+            self.tcp_ack = struct.unpack_from("!I", self.raw, offset + 8)[0]
+            self.tcp_flags = self.raw[offset + 13]
+            data_offset = (self.raw[offset + 12] >> 4) * 4
+            if data_offset < TCP_MIN_HEADER or offset + data_offset > len(self.raw):
+                raise PacketError(f"TCP 数据偏移非法：{data_offset}")
+            self.payload_len = max(0, available - data_offset)
+        elif self.proto == IPPROTO_UDP:
+            if available < UDP_HEADER:
+                raise PacketError(f"UDP 头长度不足：{available}")
+            self.src_port, self.dst_port = struct.unpack_from("!HH", self.raw, offset)
+            self.payload_len = max(0, struct.unpack_from("!H", self.raw, offset + 4)[0] - UDP_HEADER)
+        else:
+            # ICMP 等：只填端口 0，交由上层按 proto 处理
+            self.payload_len = max(0, available)
+
+    # ------------------------------------------------------------ 属性 -----
+    @property
+    def is_syn_only(self) -> bool:
+        """新连接的首包：SYN 置位且 ACK 未置位。"""
+        return self.proto == IPPROTO_TCP and bool(self.tcp_flags & SYN) and not (self.tcp_flags & ACK)
+
+    @property
+    def is_tcp(self) -> bool:
+        return self.proto == IPPROTO_TCP
+
+    @property
+    def is_udp(self) -> bool:
+        return self.proto == IPPROTO_UDP
+
+    def transport_length(self) -> int:
+        """传输层段长度（含头，用于伪头长度字段）。"""
+        return max(0, self.total_length - self.ip_header_len)
+
+    # ------------------------------------------------------------ 改写 -----
+    def set_dst(self, addr: str, port: int) -> None:
+        """改写目的地址与端口（不重算校验和：由 `recalculate_checksums()` 负责）。"""
+        ip = ipaddress.ip_address(addr)
+        if self.is_v6 != (ip.version == 6):
+            raise PacketError(f"地址版本不匹配：报文 is_v6={self.is_v6}，地址 {addr}")
+        if self.is_v6:
+            self.raw[24:40] = ip.packed
+        else:
+            self.raw[16:20] = ip.packed
+        struct.pack_into("!H", self.raw, self.ip_header_len + 2, port)
+        self.dst_addr = addr
+        self.dst_port = port
+
+    def set_src(self, addr: str, port: int) -> None:
+        """改写源地址与端口（用于构造回包， UDP 注入需要）。"""
+        ip = ipaddress.ip_address(addr)
+        if self.is_v6 != (ip.version == 6):
+            raise PacketError(f"地址版本不匹配：报文 is_v6={self.is_v6}，地址 {addr}")
+        if self.is_v6:
+            self.raw[8:24] = ip.packed
+        else:
+            self.raw[12:16] = ip.packed
+        struct.pack_into("!H", self.raw, self.ip_header_len, port)
+        self.src_addr = addr
+        self.src_port = port
+
+    def recalculate_checksums(self) -> None:
+        """重算 IP 头校验和 + TCP/UDP 校验和（python-can 风格的原地改写后必调）。"""
+        if self.is_v6:
+            self._recalc_v6()
+        else:
+            self._recalc_v4()
+
+    def _recalc_v4(self) -> None:
+        # ① IP 头校验和：先清零再算
+        struct.pack_into("!H", self.raw, 10, 0)
+        ihl = self.ip_header_len
+        struct.pack_into("!H", self.raw, 10, checksum(bytes(self.raw[:ihl])))
+        # ② 传输层校验和（含伪头）
+        if self.proto not in (IPPROTO_TCP, IPPROTO_UDP):
+            return
+        seg_len = min(self.transport_length(), len(self.raw) - ihl)
+        offset = ihl
+        # UDP 校验和为 0 表示"不校验"（IPv4 允许），但既然在改包就统算一遍
+        struct.pack_into("!H", self.raw, offset + (16 if self.proto == IPPROTO_TCP else 6), 0)
+        segment = bytes(self.raw[offset : offset + seg_len])
+        pseudo = pseudo_header_v4(self.src_addr, self.dst_addr, self.proto, seg_len)
+        value = checksum(segment, ones_complement_sum(pseudo))
+        struct.pack_into("!H", self.raw, offset + (16 if self.proto == IPPROTO_TCP else 6), value)
+
+    def _recalc_v6(self) -> None:
+        if self.proto not in (IPPROTO_TCP, IPPROTO_UDP):
+            return
+        ihl = self.ip_header_len
+        seg_len = min(self.transport_length(), len(self.raw) - ihl)
+        offset = ihl
+        csum_at = offset + (16 if self.proto == IPPROTO_TCP else 6)
+        if self.proto == IPPROTO_UDP:
+            # IPv6 下 UDP 校验和是强制的，0 视为非法 → 统一重算
+            struct.pack_into("!H", self.raw, csum_at, 0)
+        else:
+            struct.pack_into("!H", self.raw, csum_at, 0)
+        segment = bytes(self.raw[offset : offset + seg_len])
+        pseudo = pseudo_header_v6(self.src_addr, self.dst_addr, self.proto, seg_len)
+        value = checksum(segment, ones_complement_sum(pseudo))
+        if self.proto == IPPROTO_UDP and value == 0:
+            value = 0xFFFF  # RFC 768：算出来是 0 时用 0xFFFF 表示
+        struct.pack_into("!H", self.raw, csum_at, value)
+
+    # ------------------------------------------------------ 校验和验证 -----
+    @property
+    def ip_checksum_valid(self) -> bool:
+        if self.is_v6:
+            return True  # IPv6 没有头校验和
+        return ones_complement_sum(bytes(self.raw[: self.ip_header_len])) == 0xFFFF
+
+    @property
+    def transport_checksum_valid(self) -> bool:
+        """把校验和字段一起算进去，正确时反码和应为 0xFFFF。"""
+        if self.proto not in (IPPROTO_TCP, IPPROTO_UDP):
+            return True
+        ihl = self.ip_header_len
+        seg_len = min(self.transport_length(), len(self.raw) - ihl)
+        if seg_len <= 0:
+            return True
+        pseudo = (
+            pseudo_header_v6(self.src_addr, self.dst_addr, self.proto, seg_len)
+            if self.is_v6
+            else pseudo_header_v4(self.src_addr, self.dst_addr, self.proto, seg_len)
+        )
+        total = ones_complement_sum(bytes(self.raw[ihl : ihl + seg_len]), ones_complement_sum(pseudo))
+        return total == 0xFFFF
+
+    def to_bytes(self) -> bytes:
+        return bytes(self.raw)
+
+
+# ============================================================ 构造辅助 =====
+def build_tcp_syn(src: str, sport: int, dst: str, dport: int, *, seq: int = 1000) -> bytes:
+    """构造一个 IPv4 TCP SYN 报文（供单测/工具用，校验和正确）。"""
+    tcp = struct.pack("!HHIIBBHHH", sport, dport, seq, 0, 5 << 4, SYN, 64240, 0, 0)
+    total_len = IPV4_MIN_HEADER + len(tcp)
+    src_raw = socket.inet_aton(src)
+    dst_raw = socket.inet_aton(dst)
+    ip_header = struct.pack("!BBHHHBBH", 0x45, 0, total_len, 0x1234, 0x4000, 64, IPPROTO_TCP, 0) + src_raw + dst_raw
+    packet = bytearray(ip_header + tcp)
+    struct.pack_into("!H", packet, 10, checksum(bytes(packet[:IPV4_MIN_HEADER])))
+    pseudo = pseudo_header_v4(src, dst, IPPROTO_TCP, len(tcp))
+    struct.pack_into(
+        "!H", packet, IPV4_MIN_HEADER + 16, checksum(tcp, ones_complement_sum(pseudo))
+    )
+    return bytes(packet)
+
+
+def build_udp(src: str, sport: int, dst: str, dport: int, payload: bytes = b"") -> bytes:
+    """构造一个 IPv4 UDP 报文（校验和正确）。"""
+    udp_len = UDP_HEADER + len(payload)
+    udp = struct.pack("!HHHH", sport, dport, udp_len, 0) + payload
+    total_len = IPV4_MIN_HEADER + udp_len
+    ip_header = (
+        struct.pack("!BBHHHBBH", 0x45, 0, total_len, 0x4321, 0x4000, 64, IPPROTO_UDP, 0)
+        + socket.inet_aton(src)
+        + socket.inet_aton(dst)
+    )
+    packet = bytearray(ip_header + udp)
+    struct.pack_into("!H", packet, 10, checksum(bytes(packet[:IPV4_MIN_HEADER])))
+    pseudo = pseudo_header_v4(src, dst, IPPROTO_UDP, udp_len)
+    struct.pack_into("!H", packet, IPV4_MIN_HEADER + 6, checksum(udp, ones_complement_sum(pseudo)))
+    return bytes(packet)
+
+
+def build_tcp_syn_v6(src: str, sport: int, dst: str, dport: int, *, seq: int = 2000) -> bytes:
+    """构造一个 IPv6 TCP SYN 报文（Next Header = 6，无扩展头）。"""
+    tcp = struct.pack("!HHIIBBHHH", sport, dport, seq, 0, 5 << 4, SYN, 64240, 0, 0)
+    header = (
+        struct.pack("!IHBB", 0x60000000, len(tcp), IPPROTO_TCP, 64)
+        + socket.inet_pton(socket.AF_INET6, src)
+        + socket.inet_pton(socket.AF_INET6, dst)
+    )
+    packet = bytearray(header + tcp)
+    pseudo = pseudo_header_v6(src, dst, IPPROTO_TCP, len(tcp))
+    struct.pack_into("!H", packet, IPV6_HEADER + 16, checksum(tcp, ones_complement_sum(pseudo)))
+    return bytes(packet)
+
+
+def redirect_packet(packet: bytes | bytearray, sink_addr: str, sink_port: int) -> bytes:
+    """一步到位：解析 → 改写目的 → 重算校验和。"""
+    parsed = ParsedPacket.parse(packet)
+    parsed.set_dst(sink_addr, sink_port)
+    parsed.recalculate_checksums()
+    return parsed.to_bytes()
+
+
+def reflect_packet(
+    packet: bytes | bytearray,
+    *,
+    src_addr: str,
+    src_port: int,
+    dst_addr: str,
+    dst_port: int,
+) -> bytes:
+    """把报文改写成"从别处发来"，供反向路径使用（对应 WinDivert streamdump 的 reflect）。
+
+    两个方向都要用：
+
+    * 客户端 → 目标：改写成 `客户端:端口 → sink`，让 sink 收到这条连接；
+    * sink → 客户端：改写成 `原始目标:端口 → 客户端`，让客户端的 socket 认这条应答。
+
+    注意：本函数只改地址与端口，不改方向标志。
+    调用方还必须把报文标记为"入向"（`packet.direction = INBOUND`）
+    只改地址不翻方向的话，内核不会把它投递给本地 socket，握手永远完不成。
+    """
+    parsed = ParsedPacket.parse(packet)
+    parsed.set_src(src_addr, src_port)
+    parsed.set_dst(dst_addr, dst_port)
+    parsed.recalculate_checksums()
+    return parsed.to_bytes()
+
+
+__all__ = [
+    "ACK",
+    "FIN",
+    "IPPROTO_TCP",
+    "IPPROTO_UDP",
+    "RST",
+    "SYN",
+    "PacketError",
+    "ParsedPacket",
+    "build_tcp_syn",
+    "build_tcp_syn_v6",
+    "build_udp",
+    "checksum",
+    "finish_checksum",
+    "ones_complement_sum",
+    "redirect_packet",
+    "reflect_packet",
+    "verify_transport_checksum",
+    "verify_v4_header_checksum",
+]

proxycore/canproxy.py

@@ -0,0 +1,229 @@
+"""一句话回答"我现在能不能转发进程流量"。
+
+它会检查三件事并给出结论：
+  1. 是否管理员（WinDivert 与服务都需要）
+  2. WinDivert 驱动是否可用（pydivert 自带已签名的 WinDivert64.sys）
+  3. 配置里的 sink 端口是否可用、上游是否可达
+
+用法:
+    python -m proxycore can-proxy                                  # 用 dev.yaml 检查
+    python -m proxycore can-proxy --config samples/profiles/dev.yaml
+    python -m proxycore can-proxy --backend windivert              # 指定要检查的后端
+    python -m proxycore can-proxy --json                           # 机器可读输出
+
+退出码：0 = 可以转发进程流量；1 = 还不能（会打印缺什么、怎么补）
+"""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import json
+import os
+import pathlib
+import socket
+import sys
+
+from proxycore.config import Config, ConfigError
+from proxycore.proc import IS_WINDOWS
+
+
+def is_admin() -> bool:
+    if not IS_WINDOWS:
+        # os.geteuid 只在 POSIX 上存在；Windows 的 os 模块里根本没有这个名字，
+        # 所以走 getattr 而不是直接属性访问（否则 Windows 上静态检查与运行期都不好看）。
+        geteuid = getattr(os, "geteuid", None)
+        return bool(geteuid is not None and geteuid() == 0)
+    try:
+        return bool(ctypes.windll.shell32.IsUserAnAdmin())
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def windivert_driver() -> tuple[bool, str]:
+    """pydivert 自带 WinDivert64.sys（第三方已签名）；能否加载取决于权限与 EDR。"""
+    try:
+        import pydivert
+    except ImportError:
+        return False, "未安装 pydivert（pip install pydivert psutil）"
+    package_dir = pathlib.Path(pydivert.__file__).parent
+    drivers = list(package_dir.rglob("WinDivert*.sys"))
+    if not drivers:
+        return False, "pydivert 里找不到 WinDivert*.sys"
+    driver = drivers[0]
+    try:
+        handle = pydivert.WinDivert("outbound and tcp and tcp.Syn and tcp.DstPort == 1")
+        handle.open()
+        handle.close()
+        return True, f"可打开（{driver.name}, {driver.stat().st_size} 字节）"
+    except Exception as exc:  # noqa: BLE001 - pydivert 抛的异常类型随版本变
+        return False, f"打不开（{type(exc).__name__}: {exc}）"
+
+
+def port_state(host: str, port: int) -> tuple[bool, str]:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1) if hasattr(
+            socket, "SO_EXCLUSIVEADDRUSE"
+        ) else None
+        sock.bind((host, port))
+        return True, "空闲（可以监听）"
+    except OSError as exc:
+        return False, f"被占用或不可用（{exc}）"
+    finally:
+        sock.close()
+
+
+def upstream_state(host: str, port: int) -> tuple[bool, str]:
+    try:
+        with socket.create_connection((host, port), timeout=1.5):
+            return True, "可达"
+    except OSError as exc:
+        return False, f"不可达（{exc}）"
+
+
+
+def _repo_root_str() -> str:
+    """仓库根（已安装场景下退回当前目录）。路径解析复用 `cli` 里的实现。"""
+    from .cli import repo_root
+
+    root = repo_root()
+    return str(root) if root is not None else os.getcwd()
+
+
+def resolve_config_path(raw: str) -> pathlib.Path:
+    from .cli import resolve_config_path as _resolve
+
+    return _resolve(raw)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="procproxy can-proxy", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--config", default="samples/profiles/dev.yaml")
+    ap.add_argument("--backend", default="", choices=["", "null", "windivert"])
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    admin = is_admin()
+    wd_ok, wd_detail = windivert_driver()
+
+    config: Config | None = None
+    config_error = ""
+    try:
+        config = Config.load(resolve_config_path(args.config))
+    except (ConfigError, OSError) as exc:
+        config_error = str(exc)
+
+    backend = args.backend or (config.service.backend if config else "windivert")
+    sink_host = config.service.sink.host if config else "127.0.0.1"
+    sink_port = config.service.sink.port if config else 19080
+    sink_free, sink_detail = port_state(sink_host, sink_port)
+
+    upstreams = []
+    if config is not None:
+        for alias, upstream in config.profile.upstreams.items():
+            ok, detail = upstream_state(upstream.host, upstream.port)
+            upstreams.append({"alias": alias, "endpoint": f"{upstream.host}:{upstream.port}",
+                              "reachable": ok, "detail": detail})
+
+    # ---- 结论 ----
+    if backend == "null":
+        can_proxy = False
+        verdict = "backend=null：只做联调，不抓包、不改道 → 不能转发真实进程流量"
+        howto = [
+            "把 backend 换成 windivert 并以管理员运行",
+            "python -m proxycore run --config samples/profiles/dev.yaml --backend windivert",
+        ]
+    elif backend == "windivert":
+        if not IS_WINDOWS:
+            can_proxy, verdict, howto = False, "WinDivert 仅 Windows 可用", ["在 Windows 上跑"]
+        elif not admin:
+            can_proxy = False
+            verdict = "WinDivert 已就绪，但当前不是管理员 → 打不开驱动，无法改道"
+            howto = [
+                "以管理员打开 PowerShell / 终端（右键 → 以管理员身份运行），然后：",
+                "  cd /d " + _repo_root_str(),
+                "  python -m proxycore doctor --backend windivert",
+                "  python -m proxycore run --config samples/profiles/dev.yaml --backend windivert --log-level DEBUG",
+                "另一个窗口：curl.exe https://example.invalid/ -o NUL",
+            ]
+        elif not wd_ok:
+            can_proxy = False
+            verdict = f"管理员 OK，但 WinDivert 打不开：{wd_detail}"
+            howto = ["常见原因：EDR/杀软拦截 WinDivert 驱动；或已有别的 WinDivert 实例",
+                     "诊断：sc query WinDivert"]
+        else:
+            can_proxy = True
+            verdict = "WinDivert 路线 A 已就绪（驱动与权限）"
+            howto = [
+                "python -m proxycore run --config samples/profiles/dev.yaml --backend windivert --log-level DEBUG",
+                "另一窗口验证：curl.exe https://example.invalid/ -o NUL",
+                "python -m proxycore check-route --target-pid curl.exe --expect proxied --live-required",
+            ]
+
+    # 能力检查之外还要确认"现在真的能跑"：配置可用、sink 能绑、上游可达。
+    # 只报 can_proxy=True 却让 proxy 规则在启动/拨号时全部失败，等于误导。
+    if config is None:
+        can_proxy = False
+        verdict += f"；但配置不可用：{config_error or '未知错误'}"
+    elif not sink_free:
+        can_proxy = False
+        verdict += f"；但 sink 端口 {sink_host}:{sink_port} {sink_detail}"
+    elif not upstreams:
+        can_proxy = False
+        verdict += "；但配置里没有上游，命中 proxy 规则也没有代理可用"
+    elif not any(item["reachable"] for item in upstreams):
+        can_proxy = False
+        verdict += "；但配置中的所有上游都不可达，命中 proxy 的连接会失败（不会直连）"
+
+    if can_proxy:
+        verdict += "，可以转发进程流量"
+
+    report = {
+        "platform": sys.platform,
+        "is_admin": admin,
+        "backend": backend,
+        "windivert_driver": {"ok": wd_ok, "detail": wd_detail},
+        "config": {"ok": config is not None, "error": config_error},
+        "sink": {"endpoint": f"{sink_host}:{sink_port}", "free": sink_free, "detail": sink_detail},
+        "upstreams": upstreams,
+        "can_proxy_process_traffic": can_proxy,
+        "verdict": verdict,
+        "how_to": howto,
+    }
+
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+        return 0 if can_proxy else 1
+
+    print()
+    print("=" * 70)
+    print(" 能不能转发进程流量？")
+    print("=" * 70)
+    rows = [
+        ("平台", sys.platform, IS_WINDOWS),
+        ("管理员权限", "是" if admin else "否（关键！）", admin),
+        ("WinDivert 驱动", wd_detail, wd_ok),
+        (f"sink 端口 {sink_host}:{sink_port}", sink_detail, sink_free),
+    ]
+    for name, value, ok in rows:
+        print(f"  [{'OK  ' if ok else 'NO  '}] {name:<24} {value}")
+    for item in upstreams:
+        print(f"  [{'OK  ' if item['reachable'] else 'NO  '}] 上游 {item['alias']:<17} "
+              f"{item['endpoint']} {item['detail']}")
+    if config_error:
+        print(f"  [NO  ] 配置 {args.config}: {config_error}")
+
+    print()
+    print(f"使用后端：{backend}")
+    print(f"结论：{'✅ ' if can_proxy else '❌ '}{verdict}")
+    print()
+    if howto:
+        print("怎么才能跑起来：")
+        for line in howto:
+            print(f"  {line}")
+    print()
+    return 0 if can_proxy else 1
+
+if __name__ == "__main__":  # pragma: no cover - 也支持以模块方式直接运行
+    raise SystemExit(main())