v2rayn-mixed-proxy-split

name	v2rayn-mixed-proxy-split
description	Build, audit, or repair v2rayN-based smart split routing on macOS or Windows. Use when a user wants mixed proxy rules that separate domestic direct traffic, ordinary overseas proxy traffic, and high-risk overseas apps/sites that need a static residential IP, using the user's existing v2rayN nodes, sing-box/Xray cores, system proxy, TUN, or local mixed inbounds.

v2rayN Mixed Proxy Split

Use this skill to turn a user's existing v2rayN subscriptions and special nodes into a verified three-bucket routing setup:

1. Domestic or local traffic -> DIRECT.
2. Ordinary overseas traffic -> normal airport nodes.
3. High-risk overseas services -> static residential IP or another dedicated low-risk exit.

The default implementation target is v2rayN on macOS or Windows. Prefer v2rayN because it exposes local inbounds, profile data, Xray/sing-box cores, routing entries, and full-config support across both platforms. For other proxy tools, use this skill as a design checklist only; do not write tool-specific configs unless you first inspect that tool's real config format.

Required Workflow

1. Inspect the real machine before suggesting rules.

   • Find v2rayN config directory and runtime core.
   • Read local inbounds, selected profile, routing mode, TUN status, and system proxy state.
   • Read terminal proxy variables, GUI/session proxy variables, OS system proxy state, and live listener ports.
   • Read the failing app's exact error and intended local endpoint before changing rules.
   • Inventory profiles without exposing passwords, UUIDs, subscription URLs, or full server addresses.
   • Run the helper: python3 scripts/v2rayn_inventory.py --json.

2. If the user is offline or Codex/App connectivity is broken, recover first.

   • Prefer the currently live local listener that has a proven upstream path, even if it is only a temporary fallback.
   • A 401 Unauthorized from https://api.openai.com/v1/models through a proxy proves OpenAI network reachability when no API key is attached.
   • A local connection-refused error usually means the app is still pointed at a dead local endpoint. On macOS, check listeners, system proxy, app proxy settings, launch-session variables, and stale terminal variables before blaming the upstream site.
   • After recovery, return to the intended smart-split entrypoint and verify it. Do not leave the user permanently on a bypass/fallback port unless they explicitly accept it.

3. Classify exits, not websites first.

   • Identify a stable high-risk exit: residential/static IP, clean ISP, or user-designated account-safe node.
   • Identify ordinary nodes by region: US, HK/JP/TW, SG, EU if available.
   • Verify candidate nodes with real requests before assigning services to them.
   • Do not choose a region only because it is the lowest-latency node. Choose by target-service compatibility first, then latency.

4. Build the three-bucket decision model.

   • Domestic: .cn, China geosite/geoip, LAN/private ranges, known local services -> DIRECT.
   • Ordinary overseas: OpenAI/Codex/Gemini/Tabbit/AI SaaS -> usually US ordinary nodes; YouTube -> HK/JP/TW video nodes when available; GitHub/Telegram/normal SaaS -> ordinary global group.
   • High-risk overseas: Claude/Anthropic, TikTok, PayPal, Meta apps, Netflix, account/payment/commerce surfaces -> residential/static group.
   • Exchanges must be separate from both ordinary and high-risk traffic, usually SG or user-preferred jurisdiction.
   • Never merge AI/SaaS/global fallback into the exchange SG bucket unless live tests prove US/global ordinary nodes fail and the final report records that evidence.

5. Choose implementation mode.

   • If v2rayN GUI routing is enough: create or edit a routing item with direct/proxy/block rules.
   • If multiple outbounds or selector/urltest groups are required: generate a sing-box full config and run it as the main local proxy or import it as a v2rayN custom/full config.
   • On macOS, a LaunchAgent plus system proxy can be acceptable after validation.
   • On Windows, prefer v2rayN's own auto system proxy or service/startup controls; use Task Scheduler only if v2rayN cannot own the process cleanly.

6. Validate before and after writing anything.

   • sing-box check -c <config> or the equivalent core verifier must pass.
   • Confirm local listener ports with lsof on macOS or netstat/PowerShell on Windows.
   • Verify terminal environment, GUI/session environment, and system proxy separately.
   • Restart or explicitly refresh apps and shells that may have cached old proxy values.
   • Test representative URLs from all buckets.
   • Do not deploy if any required chain is unverified or contradictory.

7. Back up before deployment.

   • Back up every file/database that will be changed.
   • Record the exact restore path and rollback command.
   • If backup fails, stop; do not write a partial config.

8. Document the final mapping.

   • State the unified local entrypoint, for example 127.0.0.1:18080.
   • State each bucket, example apps/sites, and the actual selected node.
   • State whether any temporary recovery endpoint was used and whether it was cleaned up or intentionally retained.
   • State what must not be changed, such as "keep v2rayN selected on the residential profile if high-risk traffic is bridged through v2rayN's local inbound."

Read references/workflow.md for the full execution playbook and failure handling.

Hard Checkpoints

STOP before:

• Writing v2rayN database rows, full configs, system proxy settings, LaunchAgents, scheduled tasks, or TUN settings.
• Enabling TUN, because it changes more app traffic than system proxy mode.
• Promoting an emergency fallback port into the final design without a live reason and post-recovery verification.
• Printing or saving node secrets in workspace artifacts.
• Replacing the user's selected high-risk exit without a clear reason.
• Any deployment when preflight has not verified core config, live listener, terminal env, GUI/session env, system proxy, and one URL per routing bucket.
• Any deployment when current config/database backup paths have not been created and written down.

Do Not Do

• Do not assume port 10808 or 10809; inspect live listeners.
• Do not assume 18080 is alive just because it is the intended smart-split entrypoint. If it is down, recover through the proven live listener first, then repair 18080.
• Do not assume a v2rayN "SOCKS" profile is really SOCKS if its extra fields show Shadowsocks method data.
• Do not route all overseas sites to the residential IP. Keep residential exits for high-risk surfaces.
• Do not route all ordinary overseas sites to SG merely because SG is fast. Keep exchanges, AI/SaaS, video, and generic global traffic as distinct buckets unless evidence forces a merge.
• Do not call Cloudflare 403 challenge a network failure when the request reached the site.
• Do not call OpenAI API 401 Unauthorized a proxy failure when the request reached the API without credentials.
• Do not trust a browser screenshot alone; verify with real config, proxy state, and curl or equivalent probes.
• Do not leave the user with an unverified "draft" config. The endpoint, service, terminal, system proxy, and at least one URL per bucket must be checked.
• Do not silently ignore shell/GUI environment drift. Old terminals, launch sessions, and system proxy settings are separate surfaces.