openclacky 1.0.4 → 1.1.0

data/lib/clacky/default_skills/{channel-setup → channel-manager}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: channel-setup
+name: channel-manager
 description: |
-  Configure IM platform channels (Feishu, WeCom, Weixin) for openclacky.
+  Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram, DingTalk) for openclacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
-  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "channel config",
-  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
-  "send message to weixin", "send message to feishu", "send message to wecom".
+  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup telegram", "setup dingtalk",
+  "channel config", "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
+  "send message to weixin", "send message to feishu", "send message to wecom", "send message to discord", "send message to telegram", "send message to dingtalk".
   Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
 argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
 allowed-tools:
@@ -28,13 +28,13 @@ Configure IM platform channels for openclacky.
 
 | User says | Subcommand |
 |---|---|
-| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat` | setup |
+| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat`, `setup discord`, `setup telegram`, `setup dingtalk` | setup |
 | `channel status` | status |
-| `channel enable feishu/wecom/weixin` | enable |
-| `channel disable feishu/wecom/weixin` | disable |
+| `channel enable feishu/wecom/weixin/discord/telegram/dingtalk` | enable |
+| `channel disable feishu/wecom/weixin/discord/telegram/dingtalk` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
-| `send <message> to weixin/feishu/wecom` | send |
+| `send <message> to weixin/feishu/wecom/discord/telegram/dingtalk` | send |
 
 ---
 
@@ -51,7 +51,9 @@ Response shape (example):
 {"channels":[
   {"platform":"feishu","enabled":true,"running":true,"has_config":true,"app_id":"cli_xxx","domain":"https://open.feishu.cn","allowed_users":[]},
   {"platform":"wecom","enabled":false,"running":false,"has_config":false,"bot_id":""},
-  {"platform":"weixin","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://ilinkai.weixin.qq.com","allowed_users":[]}
+  {"platform":"weixin","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://ilinkai.weixin.qq.com","allowed_users":[]},
+  {"platform":"discord","enabled":true,"running":true,"has_config":true,"has_token":true,"allowed_users":[]}
+  {"platform":"telegram","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://api.telegram.org","parse_mode":"Markdown","allowed_users":[]}
 ]}
 ```
 
@@ -64,14 +66,20 @@ Platform   Enabled   Running   Details
 feishu     ✅ yes    ✅ yes    app_id: cli_xxx...
 wecom      ❌ no     ❌ no     (not configured)
 weixin     ✅ yes    ✅ yes    has_token: true
+discord    ✅ yes    ✅ yes    has_token: true
+telegram   ✅ yes    ✅ yes    has_token: true
+dingtalk   ✅ yes    ✅ yes    client_id: ding_xxx...
 ─────────────────────────────────────────────────────
 ```
 
 - Feishu: show `app_id` (truncated to 12 chars)
 - WeCom: show `bot_id` if present
 - Weixin: show `has_token: true/false` (token value is never displayed)
+- Discord: show `has_token: true/false` (token value is never displayed)
+- Telegram: show `has_token: true/false` (bot token is never displayed)
+- DingTalk: show `client_id` (truncated to 12 chars)
 
-If the API is unreachable or returns an empty list: "No channels configured yet. Run `/channel-setup setup` to get started."
+If the API is unreachable or returns an empty list: "No channels configured yet. Run `/channel-manager setup` to get started."
 
 ---
 
@@ -83,6 +91,9 @@ Ask:
 > 1. Feishu
 > 2. WeCom (Enterprise WeChat)
 > 3. Weixin (Personal WeChat via iLink QR login)
+> 4. Discord
+> 5. Telegram (Bot API)
+> 6. DingTalk
 
 ---
 
@@ -216,7 +227,7 @@ Call `request_user_feedback`:
 zh:
 ```json
 {
-  "question": "是否要安装「飞书 CLI」？装好之后 AI 可以帮你操作飞书云文档、电子表格、多维表格、知识库、日历、任务等几乎全部飞书能力，不只是聊天，而是能\"做事\"。不装也 OK。",
+  \"question\": \"是否要安装「飞书 CLI」？装好之后 AI 可以帮你操作飞书云文档等能力。不装也 OK。\",
   "options": ["启用", "跳过"]
 }
 ```
@@ -224,7 +235,7 @@ zh:
 en:
 ```json
 {
-  "question": "Install Feishu CLI? With it, the AI can operate Feishu Docs, Sheets, Bitable, Wiki, Calendar, Tasks and almost every Feishu capability — not just chat, but actually get things done. Skipping is fine.",
+  "question": "Install Feishu CLI? With it, the AI can help you work with Feishu Docs and more. Skipping is fine.",
   "options": ["Enable", "Skip"]
 }
 ```
@@ -236,8 +247,7 @@ If the user picks Enable, run:
 ```bash
 lark-cli --version > /dev/null 2>&1 || npm install -g @larksuite/cli
 echo -n "<APP_SECRET>" | lark-cli config init --app-id <APP_ID> --app-secret-stdin --brand feishu
-npx -y skills add larksuite/cli -y -g
-ruby "SKILL_DIR/import_lark_skills.rb"
+ruby "SKILL_DIR/install_feishu_skills.rb"
 lark-cli auth login --recommend
 ```
 
@@ -344,6 +354,110 @@ Tell the user while waiting:
 
 ---
 
+### Discord setup
+
+Discord requires manual portal interaction (hCaptcha gates Application creation). The browser just navigates the user to the portal; the user clicks through and pastes the bot token + app id back.
+
+#### Step 1 — Open the developer portal
+
+Get the portal URL from the script and open it in the browser:
+
+```bash
+PORTAL_URL=$(ruby "SKILL_DIR/discord_setup.rb" --portal-url)
+```
+
+Open it: `browser(action="navigate", url="<PORTAL_URL>")`. If the browser tool is not configured, invoke `browser-setup` first, then retry.
+
+#### Step 2 — Guide the user through the portal (one round-trip)
+
+Tell the user **all** of the following in a single message, then call `request_user_feedback` to collect the values in one reply:
+
+> In the Discord Developer Portal I just opened:
+>
+> 1. Click **New Application** (top-right). Name it whatever you like (e.g. "Open Clacky"), check the ToS box, click **Create**.
+> 2. In the left nav click **Bot**.
+> 3. Scroll down to **Privileged Gateway Intents** and turn on **MESSAGE CONTENT INTENT**, then click **Save Changes**.
+> 4. Scroll up, click **Reset Token** → **Yes, do it!**. Click **Copy** to copy the bot token. (This is the only time the token is shown — don't navigate away before copying.)
+> 5. In the left nav click **General Information**. Copy the **Application ID**.
+>
+> Paste both values back here in this format (one line):
+>
+> `token=YOUR_BOT_TOKEN app_id=YOUR_APPLICATION_ID`
+
+If the user is chatting in a non-English language, append the localized label in parens after each bolded English button name (e.g. `**Bot**（机器人）`). The English label stays primary — it's what they physically click in the portal.
+
+Use `request_user_feedback` to collect the reply. Parse with tolerant regex (`token=\S+`, `app_id=\d+`).
+
+If the reply is malformed (missing either field), apologise briefly and ask again with the exact same format reminder. Up to 3 retries; after that, surface the original message and stop.
+
+#### Step 3 — Validate, save, invite, wait
+
+1. Validate the token and save credentials:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --validate "<BOT_TOKEN>"
+   ```
+   On success the script prints `{"bot_id":"...","username":"..."}` and the adapter starts.
+
+2. Generate the invite URL using the application id from Step 2:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --invite-url "<APP_ID>"
+   ```
+   Open it: `browser(action="navigate", url="<INVITE_URL>")`. Tell the user:
+   > Pick your server from the dropdown → **Continue** → **Authorize**. I'll detect when the bot joins.
+   >
+   > If the dropdown is empty, you don't have a server yet — open <https://discord.com/channels/@me>, click **Add a Server** (the **+** button on the left sidebar) → **Create My Own** → **For me and my friends** → name it → **Create**, then re-open the invite link.
+
+3. Wait for the bot to join a guild (long-poll, 10 min timeout). Run with `timeout: 620`:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --watch-guild
+   ```
+   On exit 0: "✅ Discord channel configured! Bot is in `<guild_name>`. Mention it or DM it from any channel."
+   On timeout: offer to re-open the invite URL — the bot token stays valid.
+
+### Telegram setup (Bot API)
+
+Telegram setup is by far the simplest — no browser automation, no QR. The user creates a bot via @BotFather and pastes the token here.
+
+#### Step 1 — Create a bot via @BotFather
+
+Tell the user:
+
+> Open Telegram and start a chat with **@BotFather** (https://t.me/BotFather). Send `/newbot`, choose a display name and a username ending in `bot`. BotFather will reply with an HTTP API token that looks like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`. Paste the token here.
+>
+> Optional: if your network blocks `api.telegram.org`, also tell me the base URL of your self-hosted Bot API server (e.g. `https://my-tg-proxy.example.com`). Otherwise leave it blank.
+
+Wait for the user's reply. Parse the token (matches `^\d+:[\w-]{30,}$`).
+
+#### Step 2 — Save credentials and validate
+
+Call the server API. It calls `getMe` against the Bot API to validate the token before persisting:
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/telegram \
+  -H "Content-Type: application/json" \
+  -d '{"bot_token":"<TOKEN>","base_url":"<BASE_URL_OR_OMIT>"}'
+```
+
+- `200 { "ok": true }` — token validated and saved. The adapter starts long-polling immediately.
+- `422 { "ok": false, "error": "..." }` — show the error (commonly "Unauthorized" → wrong token) and offer to retry.
+
+On success:
+
+> ✅ Telegram channel configured. Open your bot in Telegram and send any message to start chatting.
+> 
+> **For group chats**: You must disable Privacy Mode in @BotFather first (`/mybots → Bot Settings → Group Privacy → Turn off`), then remove and re-add the bot to the group. Otherwise the bot cannot receive any messages — including @-mentions.
+
+#### Notes
+
+- **Group chats — Privacy Mode (IMPORTANT)**: By default Telegram enables Privacy Mode for all bots, which means the bot **cannot receive any group messages, including @-mentions**. To use the bot in a group you MUST disable Privacy Mode first:
+  1. Open @BotFather → `/mybots` → select your bot → `Bot Settings` → `Group Privacy` → **Turn off**
+  2. **Remove the bot from the group and re-add it** — the permission change does not apply to groups the bot is already in.
+  After that, the bot will respond whenever it is @-mentioned or directly replied to.
+- **Self-hosted Bot API**: set `base_url` when `api.telegram.org` is unreachable. See https://github.com/tdlib/telegram-bot-api for the official self-hosted server.
+- **`allowed_users`**: restrict which Telegram user IDs the bot will respond to. Find a user's numeric ID by messaging @userinfobot.
+
+---
+
 ## `enable`
 
 Call the server API to re-enable the platform (this reads from disk, sets enabled, saves, and hot-reloads):
@@ -372,6 +486,32 @@ Say: "❌ `<platform>` channel disabled."
 
 ---
 
+### DingTalk setup
+
+#### Step 1 — Get QR code
+
+```bash
+ruby "SKILL_DIR/dingtalk_setup.rb" --print-qr
+```
+
+Parse the last line starting with `{` to get `qr_url` and `device_code`. On non-0 exit, show the error and abort.
+
+#### Step 2 — Show QR and wait
+
+Show `qr_url` to the user, ask them to scan with the DingTalk mobile app and tap "Create New Robot", then call `request_user_feedback`.
+
+#### Step 3 — Poll for authorization
+
+```bash
+ruby "SKILL_DIR/dingtalk_setup.rb" --poll "<device_code>"
+```
+
+- **0** → "✅ DingTalk channel configured! Find your robot in DingTalk and send it a message." Stop.
+- **2** → not scanned yet. Ask user to confirm, then re-poll. If output contains `WAITING_TIMEOUT` or `expired`, restart from Step 1.
+- **1** → show the error and abort.
+
+---
+
 ## `reconfigure`
 
 1. Show current config via `GET /api/channels` (mask secrets — show last 4 chars only).
@@ -391,15 +531,37 @@ Check each item, report ✅ / ❌ with remediation:
    - Feishu: `app_id`, `app_secret` present and non-empty
    - WeCom: `bot_id`, `secret` present and non-empty
    - Weixin: `token` present and non-empty in `channels.yml`
+   - Discord: `bot_token` present and non-empty in `channels.yml`
+   - Telegram: `bot_token` present and non-empty
 3. **Feishu credentials** (if enabled) — run the token API call, check `code=0`.
 4. **Weixin token** (if enabled) — call `GET /api/channels` and check `has_token: true` for the weixin entry.
-5. **WeCom credentials** (if enabled) — search today's log:
+5. **Telegram credentials** (if enabled) — call `getMe` against the Bot API:
+   ```bash
+   BOT_TOKEN=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["bot_token"] rescue "")')
+   BASE_URL=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["base_url"] || "https://api.telegram.org" rescue "https://api.telegram.org")')
+   curl -s "$BASE_URL/bot$BOT_TOKEN/getMe" | grep -q '"ok":true' && echo "✅ Telegram OK" || echo "❌ Telegram credentials rejected by getMe"
+   ```
+6. **WeCom credentials** (if enabled) — search today's log:
    ```bash
    grep -iE "wecom adapter loop started|WeCom authentication failed|WeCom WS error response|WecomAdapter" \
      ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
    ```
    - `WeCom authentication failed` or non-zero errcode → ❌ "WeCom credentials incorrect"
    - `adapter loop started` with no auth error → ✅
+6. **Discord credentials** (if enabled) — call `GET /api/channels` and check `has_token: true`. Search today's log:
+   ```bash
+   grep -iE "DiscordAdapter|discord-gateway|/users/@me failed" \
+     ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
+   ```
+   - `/users/@me failed` → ❌ "Discord token invalid or revoked — re-run setup"
+   - `authenticated as` with no error → ✅
+7. **DingTalk credentials** (if enabled) — search today's log:
+   ```bash
+   grep -iE "dingtalk-ws|DingTalk.*error|stream.*error" \
+     ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
+   ```
+   - `WebSocket connected` → ✅
+   - `Stream endpoint error` or `token error` → ❌ "DingTalk credentials invalid — re-run setup"
 
 ---
 
@@ -410,7 +572,7 @@ Proactively send a message to a user via an IM channel adapter.
 ### Parse the request
 
 Extract two things from the user's instruction:
-- **platform** — one of `weixin`, `feishu`, `wecom`
+- **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`, `dingtalk`
 - **message** — the text content to send
 
 If the platform cannot be inferred, ask the user to clarify.
@@ -450,7 +612,7 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/
 ### Constraints & notes
 
 - **Weixin (iLink protocol)**: Every outbound message requires a `context_token` that is obtained from the most recent inbound message from that user. The token is cached in memory and reset on server restart. If the server was restarted since the user last wrote, the token is gone and the send will fail — the user must message the bot again.
-- **Feishu / WeCom**: No token required. As long as the adapter is running and the `user_id` / `chat_id` is valid, the message will be delivered.
+- **Feishu / WeCom / Discord / Telegram**: No per-message token required. As long as the adapter is running and the `user_id` / `chat_id` (or Discord channel/user id) is valid, the message will be delivered. For Telegram specifically, the `user_id` must be a Telegram chat_id that the bot can write to — the user must have sent at least one message to the bot first.
 - This feature is intended for **proactive notifications** (e.g. task completion, reminders). It is not a replacement for the normal reply flow triggered by inbound messages.
 
 ---

data/lib/clacky/default_skills/channel-manager/dingtalk_setup.rb

@@ -0,0 +1,191 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# dingtalk_setup.rb — DingTalk channel setup via Device Flow (QR scan).
+#
+# Modes:
+#   --print-qr            Phase 1+2: call init/begin, print QR URL as JSON, exit immediately.
+#   --poll <device_code>  Phase 3+4+5: poll until SUCCESS, save credentials, wait for WS.
+#
+# Environment:
+#   CLACKY_SERVER_PORT, CLACKY_SERVER_HOST — clacky server coordinates
+
+require "json"
+require "net/http"
+require "net/https"
+require "uri"
+
+DINGTALK_REG_BASE  = "https://oapi.dingtalk.com"
+# Registration source ID assigned by DingTalk (not a brand string — do not rebrand).
+DINGTALK_REG_SOURCE = "DING_DWS_CLAW"
+POLL_INTERVAL = 3
+POLL_TIMEOUT  = 300
+
+CLACKY_SERVER_URL = begin
+  url = "http://#{ENV.fetch("CLACKY_SERVER_HOST")}:#{ENV.fetch("CLACKY_SERVER_PORT")}"
+  uri = URI.parse(url)
+  raise "Invalid CLACKY_SERVER_URL: #{url}" unless uri.is_a?(URI::HTTP) && uri.host && uri.port
+  url
+end
+
+def step(msg);  puts("[dingtalk-setup] #{msg}"); end
+def ok(msg);    puts("[dingtalk-setup] ✅ #{msg}"); end
+def warn(msg);  puts("[dingtalk-setup] ⚠️  #{msg}"); end
+def fail!(msg)
+  puts("[dingtalk-setup] ❌ #{msg}")
+  exit 1
+end
+
+def post_json(url, payload)
+  uri  = URI.parse(url)
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.use_ssl = uri.scheme == "https"
+  req = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
+  req.body = JSON.generate(payload)
+  resp = http.request(req)
+  data = JSON.parse(resp.body)
+  fail! "API error (#{resp.code}): #{data["errmsg"] || resp.body}" if data["errcode"] && data["errcode"] != 0
+  data
+rescue JSON::ParserError => e
+  fail! "JSON parse error from #{url}: #{e.message}"
+end
+
+def server_post(path, body)
+  uri = URI(CLACKY_SERVER_URL)
+  Net::HTTP.start(uri.host, uri.port, open_timeout: 3, read_timeout: 10) do |h|
+    req = Net::HTTP::Post.new(path, "Content-Type" => "application/json")
+    req.body = JSON.generate(body)
+    h.request(req)
+  end
+end
+
+def server_get(path)
+  uri = URI(CLACKY_SERVER_URL)
+  Net::HTTP.start(uri.host, uri.port, open_timeout: 3, read_timeout: 10) do |h|
+    h.request(Net::HTTP::Get.new(path))
+  end
+end
+
+# ── Mode: --print-qr ─────────────────────────────────────────────────────────
+# Call init + begin, print JSON with qr_url / device_code / expires_in, exit 0.
+def mode_print_qr
+  step "Phase 1 — Starting DingTalk Device Flow registration..."
+
+  init_data = post_json("#{DINGTALK_REG_BASE}/app/registration/init",
+                        { source: DINGTALK_REG_SOURCE })
+  nonce = init_data["nonce"].to_s.strip
+  fail! "Missing nonce in init response" if nonce.empty?
+
+  begin_data   = post_json("#{DINGTALK_REG_BASE}/app/registration/begin", { nonce: nonce })
+  device_code  = begin_data["device_code"].to_s.strip
+  qr_url       = begin_data["verification_uri_complete"].to_s.strip
+  expires_in   = (begin_data["expires_in"] || POLL_TIMEOUT).to_i
+
+  fail! "Missing device_code in begin response"  if device_code.empty?
+  fail! "Missing verification_uri_complete"       if qr_url.empty?
+
+  ok "Device Flow started. QR expires in #{expires_in}s."
+  puts JSON.generate({ qr_url: qr_url, device_code: device_code, expires_in: expires_in })
+end
+
+# ── Mode: --poll <device_code> ────────────────────────────────────────────────
+# Poll until SUCCESS or a terminal state. Exits with:
+#   0  — SUCCESS: credentials saved and adapter started
+#   2  — WAITING: user hasn't scanned yet (Agent should ask user to scan and retry)
+#   1  — terminal failure (expired, fail, or server error)
+def mode_poll(device_code, expires_in: POLL_TIMEOUT, interval: POLL_INTERVAL)
+  step "Phase 3 — Checking DingTalk authorization..."
+
+  client_id     = nil
+  client_secret = nil
+  deadline      = Time.now + expires_in
+
+  loop do
+    if Time.now > deadline
+      puts "[dingtalk-setup] WAITING_TIMEOUT"
+      exit 2
+    end
+
+    poll_data = post_json("#{DINGTALK_REG_BASE}/app/registration/poll",
+                          { device_code: device_code })
+    status = poll_data["status"].to_s.upcase
+
+    case status
+    when "WAITING"
+      puts "[dingtalk-setup] WAITING"
+      exit 2
+    when "SUCCESS"
+      client_id     = poll_data["client_id"].to_s.strip
+      client_secret = poll_data["client_secret"].to_s.strip
+      fail! "Authorization succeeded but missing client credentials" if client_id.empty? || client_secret.empty?
+      ok "Authorization complete! client_id=#{client_id}"
+      break
+    when "EXPIRED"
+      fail! "Authorization QR code expired. Please re-run."
+    when "FAIL"
+      fail! "Authorization failed: #{poll_data["fail_reason"] || "unknown reason"}"
+    else
+      warn "Unknown status=#{status}, retrying..."
+      sleep interval
+    end
+  end
+
+  # ── Phase 4: Save credentials to clacky server ─────────────────────────────
+  step "Phase 4 — Saving credentials to clacky server..."
+
+  begin
+    res = server_post("/api/channels/dingtalk",
+                      { client_id: client_id, client_secret: client_secret, enabled: true })
+    if res.code.to_i == 200
+      ok "Credentials saved, DingTalk Stream adapter starting..."
+    else
+      body = JSON.parse(res.body) rescue { "error" => res.body }
+      fail! "Server rejected credentials: #{body["error"] || res.body}"
+    end
+  rescue StandardError => e
+    fail! "Could not reach clacky server: #{e.message}"
+  end
+
+  # ── Phase 5: Wait for Stream Mode WebSocket to connect ─────────────────────
+  step "Phase 5 — Waiting for DingTalk Stream connection..."
+
+  ws_ready    = false
+  ws_deadline = Time.now + 30
+
+  loop do
+    break if Time.now > ws_deadline
+    begin
+      res      = server_get("/api/channels")
+      channels = JSON.parse(res.body)["channels"] || []
+      dingtalk = channels.find { |c| c["platform"] == "dingtalk" }
+      if dingtalk&.fetch("running", false)
+        ws_ready = true
+        break
+      end
+    rescue StandardError => e
+      warn "Channel status check failed: #{e.message}"
+    end
+    sleep 2
+  end
+
+  if ws_ready
+    ok "DingTalk Stream WebSocket connected."
+  else
+    warn "Stream connection not confirmed within 30s — it may still be starting."
+  end
+
+  ok "🎉 DingTalk channel setup complete! Search for your robot in DingTalk to start chatting."
+  ok "   client_id: #{client_id}"
+end
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+case ARGV[0]
+when "--print-qr"
+  mode_print_qr
+when "--poll"
+  device_code = ARGV[1].to_s.strip
+  fail! "Usage: dingtalk_setup.rb --poll <device_code>" if device_code.empty?
+  mode_poll(device_code)
+else
+  fail! "Usage: dingtalk_setup.rb --print-qr | --poll <device_code>"
+end