Summary

Adds a QR code scan authorization flow to the DingTalk setup wizard (hermes gateway setup), eliminating the need for users to manually navigate the DingTalk Developer Console to obtain Client ID and Client Secret. This dramatically simplifies DingTalk onboarding — from a multi-step developer console workflow to a single QR scan.

Motivation

Currently, configuring DingTalk requires users to:

1. Log in to the DingTalk Developer Console (open.dingtalk.com)
2. Create an application manually
3. Enable the Robot capability
4. Copy the Client ID and Client Secret
5. Paste them into the setup wizard

This is error-prone (wrong credentials, missing robot capability) and intimidating for non-developer users. Other DingTalk ecosystem tools (e.g., dingtalk-openclaw-connector) already support device-flow registration — this PR brings parity.

How It Works

The implementation follows the DingTalk device-flow registration protocol (same as OAuth device flow):

┌─────────────────────────────────────────────────────────┐
│  1. POST /app/registration/init                         │
│     → nonce                                             │
│                                                         │
│  2. POST /app/registration/begin                        │
│     → device_code + verification_uri_complete           │
│                                                         │
│  3. Render QR code in terminal                          │
│     User scans with DingTalk app → authorizes           │
│                                                         │
│  4. POST /app/registration/poll (loop)                  │
│     → WAITING... WAITING... SUCCESS                     │
│     → client_id + client_secret                         │
│                                                         │
│  5. Auto-save to .env:                                  │
│     DINGTALK_CLIENT_ID=xxx                              │
│     DINGTALK_CLIENT_SECRET=xxx                          │
│     DINGTALK_ALLOW_ALL_USERS=true                       │
└─────────────────────────────────────────────────────────┘

User Experience

When running hermes gateway setup and selecting DingTalk:

  ─── 🔔 DingTalk Setup ───

  Choose setup method
  [0] QR Code Scan (Recommended, auto-obtain Client ID and Client Secret)
  [1] Manual Input (Client ID and Client Secret)
  > 0

  Initializing DingTalk device authorization...

  Please scan the QR code below with DingTalk to authorize:

    ▄▄▄▄▄▄▄ ▄▄▄▄▄ ▄▄▄▄▄▄▄
    █ ▄▄▄ █ █▀▄▀█ █ ▄▄▄ █
    █ ███ █ ▄▀█▀▄ █ ███ █
    ...

  Or open this link manually: https://oapi.dingtalk.com/...

  Waiting for QR scan authorization... (timeout: 2 hours)
  ......
  ✓ QR scan authorization successful!
  ✓ Client ID:     dingxxxxxxxx
  ✓ Client Secret: xxxxxxxx********

Changes

Design Decisions

1. QR library auto-install: If qrcode is not installed, the module tries uv pip install then pip install automatically. Falls back to showing the plain URL if install fails.
2. Graceful degradation: If the QR auth module fails to import or the flow fails at any step, the wizard falls back to manual input — no dead ends.
3. 2-hour timeout with polling: Matches the DingTalk API expires_in default. Polling interval respects the server-suggested value (minimum 2s).
4. Transient error retry window: Network blips during polling get a 120s retry window before giving up — handles mobile network flakiness during QR scan.
5. DINGTALK_ALLOW_ALL_USERS=true by default: Both QR and manual paths set this for convenience, since most users want all org members to be able to interact with the bot.

Commits

Test Plan

• QR scan flow: init → begin → render QR → scan with DingTalk → poll succeeds → credentials saved to .env
• Manual input fallback: selecting option [1] behaves identically to the previous flow
• QR auth failure: network error during init → prints error, falls back to manual
• QR auth timeout: waited past expiry → clean error message, falls back to manual
• qrcode library missing: auto-installs via uv pip, renders QR successfully
• qrcode install fails: shows plain URL link, user can open in browser
• Reconfiguration: existing DINGTALK_CLIENT_ID detected → prompts "Reconfigure?" → respects choice
• gateway/config.py env var detection: DINGTALK_CLIENT_ID + DINGTALK_CLIENT_SECRET in env → platform auto-enabled
• DINGTALK_HOME_CHANNEL env var → HomeChannel correctly configured

Risk Assessment

Low risk — purely additive feature:

• Existing manual setup flow is untouched (option [1] calls _setup_standard_platform as before)
• New module dingtalk_auth.py is only imported when user selects QR scan
• gateway/config.py change adds env var detection that was previously missing (all other platforms already had this)
• No new required dependencies (qrcode is optional, auto-installed only when needed)
• No changes to the DingTalk runtime adapter — this only affects the one-time setup wizard

Dependencies: This feature is independent of the stream adapter fix PRs and can be merged in any order.