name: wsl-singbox-tun description: Deploy or fix a WSL2 + sing-box 1.13 + VLESS Reality Vision TUN proxy so only WSL-internal traffic (git/curl/docker/npm/claude-code/AI agents) is proxied while the Windows host stays direct. Use this whenever the user pastes a vless:// link and asks to set up, deploy, or configure a proxy/VPN/sing-box/TUN on WSL — even if they just say "帮我配一下这个节点" or "把这个链接部署一下". Also use it whenever the user reports that some internal/company address, git remote, or LAN service times out or hangs in WSL but works fine right after sudo systemctl stop sing-box — that symptom means an internal CIDR is being routed through the proxy instead of direct, and this skill's troubleshoot script diagnoses and fixes it. Do NOT use for general VPN/proxy questions unrelated to this specific WSL2 + sing-box + TUN setup, or for non-WSL (native Linux/macOS) proxy configuration.

WSL2 sing-box TUN 部署与排障

自动化 references/WSL2_singbox_TUN_2026.md 里验证过的部署流程：一条 vless 链接 → 生成配置 → 装服务 → 起 TUN，以及事后排障（内网地址被误路由进代理）。 这份 md 文档是唯一真实来源（source of truth）——遇到任何和这里不一致的地方， 以文档为准，不要凭记忆或"应该是这样"去发挥其他做法。文档本身也应保持更新， 如果部署/排障过程中发现文档过时或有出入，顺手把文档一起改了。

这个 skill 会修改系统状态，先说清楚再动手

deploy.sh 会执行 sudo apt install、覆盖 /etc/sing-box/config.json、写 /etc/systemd/system/sing-box.service、重启 sing-box 服务。这些是运行在用户 真实机器上的操作，且如果用户已经有一套在用的代理配置，覆盖它会打断当前连接。 调用脚本前，用一两句话告诉用户接下来会做什么（装什么、改哪个文件、会不会覆盖 已有配置），必要时确认后再跑。已有配置会自动备份成 config.json.bak.<日期>，但仍然要让用户知情。

场景一：部署新节点

用户给一条 vless://... 链接，要求配置/部署代理。

bash scripts/deploy.sh 'vless://uuid@host:port?...#remark'

脚本按文档顺序做六件事，任何一步失败会停在那一步并打印原因：

1. 前置检查：/etc/wsl.conf 是否开了 systemd=true、/dev/net/tun 是否存在。 这两个只要有一个没满足，脚本会打印需要在 Windows 侧执行的命令 （wsl --shutdown / wsl --update）然后退出——这一步没法从 WSL 内部 自动化，必须让用户去 Windows 那边操作一下再回来重跑。
2. 安装 sing-box + nftables/iproute2/iptables（已装则跳过，幂等）。
3. 用 scripts/parse_vless.py 解析链接，scripts/render_config.py 生成 config.json，覆盖前自动备份旧文件。
4. sing-box check 校验配置语法。
5. 写 systemd unit，daemon-reload，enable --now。
6. 验证：service 状态、tun0 地址、ip rule、curl https://ipinfo.io（应显示 代理服务器出口 IP）。

跑完之后，把第 6 步的输出摘要给用户看一眼（服务是否 active、tun0 有没有起来、 出口 IP 对不对），而不是简单说"部署完成"。

内网直连网段（route_exclude_address）

render_config.py 默认只排除 127.0.0.0/8（本机回环），其余流量默认全部 经代理（route.final = "proxy"）。这意味着任何公司/家庭内网、局域网服务 默认都会被送进代理隧道——代理服务器到不了这些内网地址，所以第一次部署时 如果用户提到"我们内网还有 XXX 服务"，一定要主动问清楚这些内网网段，用参数 追加进去，不要留到出问题了再补：

bash scripts/deploy.sh 'vless://...' --extra-exclude 10.0.0.0/8,192.168.0.0/16
bash scripts/deploy.sh 'vless://...' --exclude 127.0.0.0/8,10.0.0.0/8   # 完全替换默认列表

只支持的协议组合

parse_vless.py 只接受 encryption=none & security=reality & type=tcp & flow=xtls-rprx-vision——这是文档里唯一验证过、render_config.py 模板对应 的组合。如果用户的链接是别的传输方式（ws/grpc/非 reality 的 tls、或者 根本不是 vless 协议），脚本会明确报错退出，不要绕开报错去手写一份没验证过 的配置糊弄过去；如实告诉用户这个组合超出了本 skill 的覆盖范围，需要人工扩展 render_config.py 的模板。

场景二：排障——内网地址连不上，停了 sing-box 就好了

这是文档第八节总结的典型症状：git pull 或访问某个内网服务卡死/超时， sudo systemctl stop sing-box 后立刻恢复。根因几乎总是同一个：目标 IP 所在网段没被排除，被强制送进了代理隧道，而代理服务器到不了这个内网。

bash scripts/troubleshoot.sh internal-git.example.com
# 或直接传 IP
bash scripts/troubleshoot.sh 10.20.5.10

脚本会解析域名、检查目标 IP 是否命中 sing-box 的策略路由表（table 2022）， 并打印诊断结论：

• 命中：说明确实是这个已知问题。脚本会给出修复命令模板，但不会自己写回 config.json——由你（Claude）确认命中的网段合理（一般取命中网段的整数段， 比如 /16，没必要为了精确到 /32 列一大堆），跟用户说清楚要加哪个网段， 再用 add_exclude_cidr.py 生成新配置、校验、写回、重启：

  sudo python3 scripts/add_exclude_cidr.py /etc/sing-box/config.json 10.20.0.0/16 \
    > /tmp/config.json.new
  sudo sing-box check -c /tmp/config.json.new && sudo cp /tmp/config.json.new /etc/sing-box/config.json
  sudo systemctl restart sing-box
  ip route show table 2022 | grep 10.20.0.0/16   # 应无输出，确认已排除
  

• 未命中：说明不是路由劫持问题，脚本会打印几个别的排查方向（服务状态、 DNS 劫持、端口连通性、日志），换个思路排查，不要死磕"加排除网段"这一个方向。

目录结构

scripts/
  parse_vless.py       解析 vless:// 链接 -> JSON
  render_config.py      JSON 字段 -> sing-box config.json（默认只排除 127.0.0.0/8）
  add_exclude_cidr.py   给已有 config.json 追加直连网段（排障用）
  check_route_hit.py    判断某个 IP 是否命中 table 2022（排障用）
  deploy.sh              串联以上脚本 + apt/systemctl，完成从零部署
  troubleshoot.sh        排障入口，只诊断不动手改配置
references/
  WSL2_singbox_TUN_2026.md   原始文档，唯一真实来源

wsl-singbox-tun

在 WSL2 上一键部署/排障 sing-box 1.13 + VLESS Reality Vision + TUN 代理：只让 WSL 内部流量（git / curl / docker / npm / claude-code / AI Agent...）走代理， Windows 宿主机完全不受影响。

能做什么

• 部署：传入一条 vless:// 节点链接，自动完成安装 sing-box、生成 /etc/sing-box/config.json、建 systemd 服务、启动并验证的全流程。
• 排障：当某个内网地址/域名在 WSL 里连不上、但停掉 sing-box 就恢复正常时， 自动判断是不是该网段被误路由进了代理隧道，并给出修复方式。

依赖环境

• WSL2，已在 /etc/wsl.conf 启用 systemd=true
• /dev/net/tun 可用（较新版本 WSL 内核默认支持）
• sudo 权限（安装软件、写 /etc/sing-box/、/etc/systemd/system/）
• 只支持 vless + reality + xtls-rprx-vision + tcp 这一种组合，其他协议/传输 方式（ws、grpc、trojan、shadowsocks 等）暂不支持

用法

# 部署
bash scripts/deploy.sh 'vless://uuid@host:port?encryption=none&flow=xtls-rprx-vision&security=reality&sni=...&fp=...&pbk=...&sid=...&type=tcp&headerType=none#remark'

# 追加/替换需要直连（不走代理）的内网网段
bash scripts/deploy.sh 'vless://...' --extra-exclude 10.20.0.0/16
bash scripts/deploy.sh 'vless://...' --exclude 127.0.0.0/8,10.20.0.0/16

# 排障：内网地址连不上
bash scripts/troubleshoot.sh code.example.com
bash scripts/troubleshoot.sh 10.20.5.10

在 Claude Code 里直接把 vless 链接发给 Claude 并说"帮我部署这个代理"或"这个 内网地址连不上"即可自动触发，细节见 SKILL.md。

目录结构

scripts/
  parse_vless.py       解析 vless:// 链接 -> JSON
  render_config.py      JSON 字段 -> sing-box config.json（默认只排除 127.0.0.0/8）
  add_exclude_cidr.py   给已有 config.json 追加直连网段（排障用）
  check_route_hit.py    判断某个 IP 是否命中策略路由表（排障用）
  deploy.sh              串联以上脚本 + apt/systemctl，完成从零部署
  troubleshoot.sh        排障入口，只诊断不动手改配置
references/
  WSL2_singbox_TUN_2026.md   完整部署文档（唯一真实来源），示例用占位信息

注意事项

• deploy.sh 会真实执行 sudo apt install、覆盖 /etc/sing-box/config.json、 重启 sing-box 服务；已有配置会自动备份成 config.json.bak.<日期>，但仍 建议先确认再执行，尤其是机器上已有一套在用的代理配置时。
• route_exclude_address 默认只有 127.0.0.0/8（本机回环）。任何公司/家庭 内网、局域网服务默认都会被送进代理隧道，第一次部署时记得用 --extra-exclude 把自己的内网网段加进去，别等出问题了再补。