1实现原理 · 为什么它能做到
它把「Tailscale 与代理/VPN 共存」的冲突按网络栈层级拆成 5 层，每层标注「什么坏了 / 什么还好 / 根因」，用「谁还在工作」反推故障层——这是整个 skill 的诊断骨架。
tunnel-doctor/SKILL.md
| Layer | What breaks | What still works | Root cause | |-------|-------------|------------------|------------| | 1. Route table | Everything (SSH, curl, browser) | `tailscale ping` | `tun-excluded-routes` adds `en0` route overriding Tailscale utun |
配套的关键判据：'SSH does NOT use `http_proxy`/`NO_PROXY` env vars. If SSH works but HTTP doesn't → Layer 2.' 与 '`curl` uses `http_proxy` env var, NOT the system proxy.'
它的核心方法论是「先验证组件自己的健康端点，别从旁证下结论」——因为多层可以产生重叠症状，先跳到最具体的验证可以避免钻进错误的一层。
tunnel-doctor/SKILL.md
When symptoms point at a component (proxy, VPN, route table, DNS), **don't commit to a hypothesis from circumstantial evidence — verify with that component's own health endpoint first.**
同节的因果说明：'A symptom that matches the description of Step 2X does not, by itself, prove component X is the problem.' 并给出组件→健康检查对照表（proxy 用 curl -x、Tailscale 用 tailscale status、DNS 用 dig @ns）。
针对 TUN 全局模式下「探针会撒谎」这一现象，它给出可判定的证伪标准：0.00s 的跨洋连接、亚毫秒 ping 在物理上不可能，因此测到的是本地 TUN 而非网络。
tunnel-doctor/SKILL.md
**Counter-move**: before citing any latency / reachability number while a TUN is up, ask *"would this number be physically possible if the packet really traversed to the destination?"* A `0.00s` connect or a `0.2ms` ping to another continent is the tell that you measured the TUN, not the network.
它同时列出「在 TUN 下可以信的东西」：curl 的 time_appconnect/time_starttransfer、境内 IP-geo 源、以及从磁盘解出的代理配置 + 工具自身 GUI。
对同一句错误信息给出两套互斥解释并要求先做区分实验：198.18.x.x 只证明有 TUN，不证明 fake-IP 导致了失败；(A) 协议误判与 (B) 转发路径间歇性抖动需要相反的修法。
tunnel-doctor/SKILL.md
**First, a warning about this symptom**: the `198.18.x.x` in the error message is **not evidence that fake-IP caused the failure**. Under TUN, *every* hostname resolves to a fake IP, so that address appears in the error whether the connection failed for this reason or any other.
区分手段是「同一代理路径跑 40 次普通 HTTPS 统计失败率」的循环，并给了量化数据点：'ssh -T [email protected]` succeeded 20/20 in a good window and failed roughly 15–20% of attempts in a bad one'。
它把「端口探测在 TUN 下全不可信」变成了一条必须先做的校准实验：探一个目标肯定不服务的端口，若也报开，则该机器上所有端口探测零信息量。
tunnel-doctor/SKILL.md
**First: stop trusting `nc -z`.** Under a TUN the local stack completes the TCP handshake on the destination's behalf, so `nc -z` succeeds for **every** port, including ports the destination has closed.
校准命令原文：nc -z -G 5 -w 5 <destination-ip> 65001 与对照组 203.0.113.199（RFC 5737 TEST-NET-3）。
「隧道还是对端防火墙」这个在客户端无法区分的问题，被要求走带外通道（云厂商 guest-agent）进入目标机取证，并给出「journalctl 而非 auth.log」的实测反例。
tunnel-doctor/SKILL.md
**Then ask the destination out-of-band.** The only way to settle "did my packets arrive?" is a channel that does not traverse the failing data path. On a cloud VM that is the provider's guest-agent control plane
配套实测警告：'On Ubuntu 24.04 the file still exists and still receives `CRON` and `sudo` lines, but `rsyslog` is not installed by default and **`sshd` writes nothing to it** — measured on a live 24.04 host: 90 lines in `auth.log`, 0 of them from `sshd`'
自带的快速诊断脚本把最常见的四类 macOS 冲突（env 代理、系统代理例外、直连/代理路径分裂、本地 TLS 信任）压成一条命令，并给出可判读的三行结论。
tunnel-doctor/SKILL.md
python3 scripts/quick_diagnose.py --host local.example.com --url https://local.example.com/health
判读规则原文：'- `direct=PASS` + `forced_proxy=FAIL` = host must bypass proxy (`skip-proxy` + `NO_PROXY`).' 与 '- `strict_tls=FAIL` + `direct=PASS` = path is reachable; trust issue only'。
对「破坏性网络变更」设了前置门：动 VPN/路由/服务之前必须先读 recovery 参考、先验证前置条件、先布好有界恢复手段，并明确「停成功/进程脱离/脚本末尾重启」都不算恢复证据。
tunnel-doctor/SKILL.md
Before any authorized VPN disconnect, app termination, route cutover, or service restart, read [network_change_recovery.md](references/network_change_recovery.md). Validate prerequisites before interruption, arm bounded recovery before the first disruptive action, and verify both the repaired path and the user's original network use. A successful stop command, a detached process, or a restart placed at the end of a script is not recovery evidence.
该 reference 的三段结构为 Before interruption / Execute and recover / Verify and finish。
2核心能力
01路由层冲突诊断与修复（proxy 抢占 Tailscale CGNAT 网段）
02NO_PROXY / skip-proxy 环境变量与系统代理例外修复（含 Go net/http 不支持 CIDR 的坑）
03TUN DIRECT split-brain 诊断（域名连接死、真实 IP + 正确 SNI 通）
04DNS getaddrinfo 链停滞的逐 nameserver 二分定位（nslookup 快但系统解析挂 60s）
05VM/容器代理传播修复（OrbStack/Docker Desktop 透明代理与 TUN 冲突、buildkit 直连、v2rayN 端口分裂）
06SSH 双隧道与 git over SSH 间歇失败处理（含只重试 key exchange 前失败的 wrapper 契约）
07Tailscale SSH 在 WSL 上的静默拦截修复（kex_exchange_identification + tcpdump 0 包判据）
08代理节点/出口/链路的容量诊断（单跳与多跳链，串行对比、真实客户端复测、原始工作负载重放）
09Windows 主机 TUN 级联故障（WSL + 其 Tailscale 一起掉）与事件日志时间线取证
10Tailscale 远程开发 SOP（proxy 安全的 Makefile、SSH 隧道目标、多端口转发、non-login shell 环境）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | tailscale（status / ssh / up / version） |
| cli | macOS 网络诊断工具族（ifconfig / netstat / route / scutil / lsof / dscacheutil） |
| cli | curl（含 -x 显式代理、--noproxy '*'、-w 计时模板） |
| cli | dig / nslookup（逐 nameserver 二分 DNS） |
| cli | nc / tcpdump / ss（端口探测与到达性取证，含 sudo tcpdump） |
| cli | ssh / ssh -vvv / ssh -T（连通性与 git over SSH 诊断） |
| cli | docker / docker build / docker run（VM 与容器代理传播诊断） |
| cli | pnpm（SOP 示例，含 npmmirror 镜像参数） |
| cli | 阿里云 CLI（aliyun ecs …，带外命令执行取证） |
| cli | journalctl / grep（目标机日志取证；经带外通道执行） |
| api | Shadowrocket 配置编辑器 API（读/写整份代理配置，LAN 内 HTTP） |
| network | 通用可达性目标（Google generate_204、api.github.com、alpine CDN）用于路径健康与容量测量 |
| network | Tailscale 官方站点（ACL 管理页与独立版安装包） |
| network | 本地/内网服务与 vanity 域名（文档中的占位目标，非固定端点） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: python3 scripts/quick_diagnose.py --host … --url … [--tailscale-ip …]（仓库自带，
- 网络端点: 声明外部网络访问: curl 经本地/局域网代理端口（127.0.0.1:1082、host.internal:1082 等）与直连访问外部站点做路径健康与容量测量（ap
- 本地工作目录: 文件读写与工件输出: Shadowrocket 配置写回：POST /api/save --data-binary @config.txt 替换编辑器缓冲区（referen
审计说明： 。判橙的三条硬依据：①【凭据接触】references/proxy_conflict_reference.md 教用户/agent 从局域网明文 HTTP 读取整份 Shadowrocket 配置（含代理节点与凭据）并写回该配置；这是对代理凭据的直接读取路径。②【系统级改动】skill 的核心动作就是改路由表、改系统代理例外、重启/重装 Tailscale（含 sudo route delete、sudo killall -HUP mDNSResponder、sudo snap remove tailscale、sudo tailscale up --ssh），属于会改变用户网络状态的高影响操作。③【跨机取证】会 SSH 到 Tailscale 内主机、并经云厂商 guest-agent 通道在目标云主机上执行 shell（aliyun ecs RunCommand）。为什么不是红：没有安全降级作为主路径（Step 6 出现一处 StrictHostKeyChecking=no，但那是连通性验证命令而非数据通道，且文档在 2H 节明确反对为省事而放宽该检查），没有反爬/绕过/批量采集意图，所有外发目标都是诊断必需的通用可达性站点与用户自己的代理/云控制台。为什么不是黄：涉及凭据读取、系统配置变更与他机操作的组合面，影响半径明显超过「常规 API 调用」。使用建议：只在你自己（或有明确授权）的机器上运行；涉及 VPN 断开/路由切换前先按 network_change_recovery.md 布置恢复；读取代理配置时避免把整份配置内容回显到会话或日志里。
5第二遍独立确认
- [discrepancy] 每条外部依赖的调用点是否真实存在（13 个 CLI/API/network 条目） — 【本项在第二遍自查时曾误判为 ok，后经磁盘级校验工具抓出并已修正】。逐条回查后确认：tailscale 调用点见 Step 2D 的 `tailscale status` 与诊断纪律表的 `| Tailscale daemon | \`tailscale status\` returns peer list (not connection error) |`、Step 5 的 `sudo tailscale up --ssh` / `--ssh=false` / `tailscale ssh` / `tailscale version`；其余依赖亦各有真实调用点（env/ifconfig/route/scutil 见 2A/2B、curl 见 2A/2C/2E 与容量参考、dig 见 2I/2J/2K、nc/tcpdump/ss 见 2K 与 Step 6、ssh 见 Step 6 与 SSH 双隧道、docker 见 2G、pnpm 见 SOP 第 5 节、aliyun ecs 与 journalctl 见 2K、Shadowrocket config API 见 proxy_conflict_reference.md、google/github/alpine CDN 见 2H/2K/2G、Tailscale 官方站点见 Step 4/5B、localhost/local.<domain> 见 Step 1 症状清单）。**纠正的具体错误**：首稿有两条 evidence 的 quote 被误取自同批另一份源码（windows-remote-desktop-connection-doctor/SKILL.md）——`tailscale status` / `tailscale netcheck` 与 `ifconfig | grep -E "^[a-z]|inet |utun"` / `netstat -rn | head -40` / `scutil --proxy` 均属该文件而非本 skill；本 skill 内 tailscale 的实际命令是 `tailscale status`、`tailscale ssh`、`sudo tailscale up --ssh`、`tailscale version`（**不含 netcheck**），macOS 工具的实际命令是 `ifconfig | grep -A2 'inet 100\.'`。两条 quote 已按 pin 源码逐字替换，`netcheck` 相关表述已从 name/scripts_executed 中清除。教训记录：跨文件批量取证时，同批并行读取的相邻源码极易被错误归属，evidence 必须在写入前逐条回到目标文件复核。
- [ok] 自带脚本是否与文档声明一致（是否只做诊断、不写盘、无 shell 注入） — quick_diagnose.py 的 docstring 自述只做五类冲突检测（env+NO_PROXY、系统代理例外、代理路径 vs 直连、本地 TLS 信任、可选路由归属）；其 subprocess.run 全部传参数列表（无 shell=True）；os.environ.copy() 后仅 pop 代理变量以做对照请求；无文件写入、无 subprocess 之外的网络栈。结论成立。
- [ok] 是否漏记外发目标（把每个域名回查调用点） — 全目录域名提取：api.github.com、www.google.com、dl-cdn.alpinelinux.org、registry.npmmirror.com、login.tailscale.com、pkgs.tailscale.com、docs.python.org、docs.ansible.com、tailscale.com、local.example.com、localhost（多端口）、127.0.0.1:1082、host.internal:1082、192.168.31.110:8080（Shadowrocket IP 占位）、100.101.102.103:8002、203.0.113.199（RFC 5737 对照）、198.18.x.x（fake-IP 段）。均已归入 external_deps 或注入面说明；无未记载的隐蔽外发。
- [discrepancy] 『安全降级』检索是否有命中 — 命中并构成文档内部张力：Step 6 的端到端验证命令为 `ssh -o ConnectTimeout=10 -o StrictHostKeyChecking=no <user>@<tailscale-ip> 'echo SSH_OK && hostname && whoami'`，即关闭主机密钥校验；而 Step 2H 在讨论『不要硬编码 GitHub IP』时明确把『pressure you into loosening `StrictHostKeyChecking`』列为真实成本，并称「That is a real cost paid for an uncertain benefit.」。同一文档一处反对放宽该检查、另一处把它写进推荐验证命令，属于未消解的表述张力（实际影响有限：该命令只执行 echo/hostname/whoami，无数据外发）。按分级范式这不足以把本 skill 判红，但应作为使用提醒记录下来。
- [ok] 『读取代理配置』这一凭据接触面是否被文档自己披露 — 披露且被谨慎处理：proxy_conflict_reference.md 明确要求不要硬编码设备 IP（'The device IP changes with DHCP. Do not hardcode it.'）、给出端口 8080 可能被别的服务占用的 lsof 检查、并用粗体警告 -d 会 URL 编码从而『destroys the entire configuration』。即作者意识到了该接口的高风险性。此事以「凭据读取 + 配置写入」双重性质记入 security，不构成隐蔽行为。
- [ok] 是否存在混淆或隐蔽脚本 — 全目录扫描 >200 字符无空格长行零命中；无 base64 大块（仅 2K 节的 aliyun --ContentEncoding Base64 说明与 RFC 引述）；唯一可执行文件 quick_diagnose.py 全文可读、无动态代码加载。
- [ok] 文档内部是否另有自相矛盾（除 StrictHostKeyChecking 外） — 抽查了 nc -z 的表述：Step 1 的关键区分里曾以 nc -z 成功作为判据，Step 2K 则明确『This supersedes the plain `nc -z` reading in the bullet above whenever a TUN — not just Tailscale — is in the path』——即作者主动标注了覆盖关系而非留矛盾，属已消解的张力。其余抽查（utun MTU 判据、TUN 可信探针清单）内部一致。
- [ok] pin commit 与 skill.path 是否与任务书表格一致 — git rev-parse HEAD = d5c4678cb5d4fd6acc9c922690df035dbd33d247，与任务书表格『库内 HEAD』一致；目录位于仓库根，相对路径 tunnel-doctor；本目录最后一次提交 829d9758（2026-09-08 22:22）。GitHub API 复核 MIT / stars 1392 / pushed 2026-09-15T09:30:04Z。
6结论
适合： 适合：在用 Tailscale/VPN/代理工具并与本地网络冲突缠斗的 macOS 开发者与运维（尤其中国大陆网络环境：Shadowrocket/Clash/Surge + 国内 DIRECT 规则 + 需要 SSH 到 WSL 或云主机）；也适合遇到「SSH 不通但 ping 通」「浏览器 503 但 curl 通」「nslookup 快但 ssh 卡 60 秒」「docker pull 慢/失败」这类具体症状、想要一份可执行判据而非泛泛建议的人。
不适合： 不适合：根因未知或属应用/协议层（SSE/CDN/HTTP2 行为）的排错——文档明确要求回退到 debugging-network-issues；不适合不愿在本机改路由/代理配置的人；不适合只是想知道「网络是不是断了」的轻量场景（成本远高于直接看状态）。在他人机器或生产网络设备上使用前，需先取得明确且范围限定的授权。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload tunnel-doctor.tar.gz
sha256:
Option B · Copy Guide for Agenta9f26e4f66655f0e…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.