feat(uploader): expose --cdp-url for xiaohongshu/tencent/youtube login + WSL guide

[DerekEXS]

Problem

WSL2 users running SAU from WSL bash want to use their desktop Chrome (already logged into the platform) for scan-QR login instead of letting Playwright launch a fresh bundled Chromium. The mechanism is the Chrome DevTools Protocol (CDP) — Playwright connect_over_cdp() attaches to an already-running browser instead of spawning one.

Doublin / Kuaishou already had --cdp-url (wired in earlier work). The other three Playwright-based platforms — xiaohongshu, tencent, youtube — were missing it, leaving WSL users on those platforms no choice but to either:

• Use bundled chromium + scan QR through WSLg (broken on most setups: WebGL/IME/render issues), or
• Patch the source to add cdp_url themselves.

Bilibili uses biliup CLI (subprocess), so --cdp-url is not applicable there.

Fix

1. uploader/xiaohongshu_uploader/main.py — add cdp_url to xiaohongshu_setup and xiaohongshu_cookie_gen. Inside cookie_gen, when cdp_url is set, use playwright.chromium.connect_over_cdp() instead of launch(), reuse existing context if present. Guard browser.close() with should_close_browser flag (CDP browser must NOT be closed).

2. uploader/tencent_uploader/main.py — same pattern for tencent_setup, tencent_cookie_gen, get_tencent_cookie.

3. uploader/youtube_uploader/main.py — same pattern for youtube_setup, youtube_cookie_gen.

4. sau_cli.py — add cdp_url parameter to login_xiaohongshu_account, login_tencent_account, login_youtube_account. Add --cdp-url argparse to xiaohongshu, tencent, youtube login parsers (mirroring douyin/kuaishou). Wire cdp_url=args.cdp_url at dispatch sites.

5. docs/WSL-USER-GUIDE.md — new file covering the full WSL2 / Linux-server workflow:

   • Why --headed is the default for douyin (anti-bot detection)
   • Chrome 111+ IPv6 binding problem + Python IPv4→IPv6 TCP proxy solution
   • WSL2 .bat must be ASCII (UTF-8 echo trap in cmd GBK)
   • --user-data-dir preservation
   • Complete end-to-end workflow example

Why --cdp-url matters for WSL

A typical WSL2 user setup:

• Desktop Chrome (Windows): logged into all platforms, has UI window
• WSL2 bash: runs SAU CLI
• WSL cannot reach Windows 127.0.0.1 (WSL has its own loopback)
• WSL can reach Windows 172.19.224.1 (vEthernet (WSL) bridge IP)

So WSL users run a Python TCP proxy on Windows that forwards 0.0.0.0:9222 → [::1]:9222 (Chrome's actual bind address on Windows after Chrome 111+ removed --remote-debugging-address). Then SAU attaches via --cdp-url http://172.19.224.1:9222.

Without this fix, SAU would launch a new headless Chromium (no UI, can't scan QR) or fail outright if no browser is available.

Usage

# Desktop Chrome already running on Windows with --remote-debugging-port=9222
sau xiaohongshu login --account myaccount --headed --cdp-url http://172.19.224.1:9222
sau tencent login --account myaccount --headed --cdp-url http://172.19.224.1:9222
sau youtube login --account myaccount --headed --cdp-url http://172.19.224.1:9222

Testing

• All 4 platforms parse --cdp-url correctly:

  douyin: cdp_url=http://172.19.224.1:9222 ✓
  xiaohongshu: cdp_url=http://172.19.224.1:9222 ✓
  tencent: cdp_url=http://172.19.224.1:9222 ✓
  youtube: cdp_url=http://172.19.224.1:9222 ✓
  

• Existing test suite: 31 passed, 2 deselected (pre-existing failures on main, unrelated to this PR).
• All 3 modified uploader modules import cleanly.

Affected files

 docs/WSL-USER-GUIDE.md                | 219 ++++++++++++++++++++++++++++++++++
 sau_cli.py                            |  99 ++++++++++++---
 uploader/tencent_uploader/main.py     |  22 +++-
 uploader/xiaohongshu_uploader/main.py |  18 ++-
 uploader/youtube_uploader/main.py     |  22 ++--
 5 files changed, 349 insertions(+), 31 deletions(-)

Related

• PR fix(uploader): default browser channel to chromium, add SAU_BROWSER_CHANNEL override #246 (channel default chromium + SAU_BROWSER_CHANNEL override) — the first half of the WSL story.
• OpenClaw issue #108262 — unrelated agent fallback bug, but commonly encountered in the same WSL workflow.