openclacky 0.9.7 → 0.9.9

data/lib/clacky/default_skills/browser-setup/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: browser-setup
+description: |
+  Configure the browser tool for Clacky. Guides the user through Chrome setup,
+  verifies the connection, and writes ~/.clacky/browser.yml.
+  Trigger on: "browser setup", "setup browser", "配置浏览器", "browser config",
+  "browser doctor".
+  Subcommands: setup, doctor.
+argument-hint: "setup | doctor"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - browser
+---
+
+# Browser Setup Skill
+
+Configure the browser tool for Clacky. Config is stored at `~/.clacky/browser.yml`.
+
+## Command Parsing
+
+| User says | Subcommand |
+|---|---|
+| `browser setup`, `配置浏览器`, `setup browser` | setup |
+| `browser doctor` | doctor |
+
+If no subcommand is clear, default to `setup`.
+
+---
+
+## `setup`
+
+### Step 1 — Check Node.js & install chrome-devtools-mcp
+
+Run:
+```bash
+node --version
+```
+
+If Node.js is missing or version < 20, tell the user and stop:
+
+> ❌ The browser tool requires Node.js 20+.
+> Please install it first: https://nodejs.org/
+> Let me know when done and I'll retry.
+
+Then install/update `chrome-devtools-mcp`:
+```bash
+npm install -g chrome-devtools-mcp@latest
+```
+
+If this fails, stop and tell the user:
+
+> ❌ Failed to install chrome-devtools-mcp. Please run manually:
+> ```
+> npm install -g chrome-devtools-mcp@latest
+> ```
+> Let me know when done.
+
+### Step 2 — Try to connect to Chrome
+
+Immediately attempt to connect — do **not** ask the user anything first:
+
+```
+browser(action="act", kind="evaluate", js="navigator.userAgentData?.brands?.find(b => b.brand === 'Google Chrome')?.version || navigator.userAgent.match(/Chrome\\/([\\d]+)/)?.[1] || 'unknown'")
+```
+
+**If connection succeeds** → parse the Chrome version and jump to Step 3.
+
+**If connection fails** → inspect the error message from the evaluate result to diagnose:
+
+**Case A — error contains `"timed out"`**: The MCP daemon failed to start — Chrome is not running or remote debugging is not enabled. Try to open the page for the user:
+
+```bash
+open "chrome://inspect/#remote-debugging"
+```
+
+Tell the user:
+
+> I've opened `chrome://inspect/#remote-debugging` in Chrome.
+> Please click **"Allow remote debugging for this browser instance"** and let me know when done.
+
+If `open` fails, fall back to:
+
+> Please open this URL in Chrome:
+> `chrome://inspect/#remote-debugging`
+> Then click **"Allow remote debugging for this browser instance"** and let me know when done.
+
+Wait for the user to confirm, then retry the connection once. If still failing, stop:
+
+> ❌ Could not connect to Chrome. Please make sure Chrome is open and remote debugging is enabled, then run `/browser-setup` again.
+
+**Case B — error contains `"Chrome MCP error:"`**: The MCP daemon is alive but Chrome's CDP connection is broken — this is a known Chrome issue after long sessions. Tell the user:
+
+> Chrome's remote debugging connection is unstable.
+> Please restart Chrome and let me know when done.
+
+Wait for the user to confirm, then retry once. If still failing, stop with the same error message as Case A.
+
+### Step 3 — Check Chrome version
+
+Parse the version number from Step 2:
+- version >= 146 → proceed
+- version 144–145 → warn but proceed:
+  > ⚠️ Your Chrome version is vXXX. Version 146+ is recommended. Continuing anyway...
+- version < 144 or unknown → stop:
+  > ❌ Chrome vXXX is too old. Please upgrade to Chrome 146+: https://www.google.com/chrome/
+  > Let me know when you've upgraded and I'll retry.
+
+### Step 4 — Save config and start daemon
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/configure \
+  -H "Content-Type: application/json" \
+  -d '{"chrome_version":"<VERSION>"}'
+```
+
+This writes `~/.clacky/browser.yml` and hot-reloads the daemon in one step.
+If this fails (server not running), skip silently — the daemon will start lazily on next use.
+
+### Step 5 — Done
+
+> ✅ Browser configured.
+>
+> Chrome v<VERSION> is connected and ready to use.
+
+---
+
+## `doctor`
+
+Run a diagnostic check and report each item:
+
+```
+Browser Doctor
+──────────────
+[✅/❌] Config file              (~/.clacky/browser.yml)
+[✅/❌] Node.js 20+              (node --version)
+[✅/❌] chrome-devtools-mcp      (chrome-devtools-mcp --version)
+[✅/❌] Chrome connection        (browser status)
+[✅/❌] Chrome version           (≥146 best, ≥144 OK)
+```
+
+For any ❌ item, show the fix inline.
+
+Steps:
+1. Check `~/.clacky/browser.yml`:
+   - File missing → ❌ Not configured. Stop and suggest running `/browser-setup`.
+   - File exists, `enabled: false` → ⏸ Configured but disabled. Suggest running `/browser-setup` to re-enable.
+   - File exists, `enabled: true` → ✅ Continue.
+2. Run `node --version` via Bash.
+3. Run `chrome-devtools-mcp --version` via Bash; if missing, suggest `npm install -g chrome-devtools-mcp`.
+4. Run `browser(action="status")`:
+   - If failed, inspect the error message to distinguish the cause:
+     - error contains `"timed out"` → MCP daemon failed to start; Chrome not running or remote debugging not enabled. Fix: open `chrome://inspect/#remote-debugging`, click **"Allow remote debugging for this browser instance"**.
+     - error contains `"Chrome MCP error:"` → daemon alive but CDP connection broken after long session. Fix: restart Chrome.
+5. If step 4 succeeded, run evaluate to get Chrome version.
+
+Report all results together at the end.

data/lib/clacky/default_skills/channel-setup/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: channel-setup
 description: |
-  Configure IM platform channels (Feishu, WeCom) for open-clacky.
+  Configure IM platform channels (Feishu, WeCom, Weixin) for open-clacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
-  Trigger on: "channel setup", "setup feishu", "setup wecom", "channel config",
+  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "channel config",
   "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor".
   Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor.
 argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor"
@@ -21,14 +21,16 @@ allowed-tools:
 
 Configure IM platform channels for open-clacky. Config is stored at `~/.clacky/channels.yml`.
 
+---
+
 ## Command Parsing
 
 | User says | Subcommand |
 |---|---|
-| `channel setup`, `setup feishu`, `setup wecom` | setup |
+| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat` | setup |
 | `channel status` | status |
-| `channel enable feishu/wecom` | enable |
-| `channel disable feishu/wecom` | disable |
+| `channel enable feishu/wecom/weixin` | enable |
+| `channel disable feishu/wecom/weixin` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
 
@@ -44,9 +46,12 @@ Channel Status
 Platform   Enabled   Details
 feishu     ✅ yes    app_id: cli_xxx...  domain: feishu.cn
 wecom      ❌ no     (not configured)
+weixin     ✅ yes    2 account(s) logged in
 ─────────────────────────────────────────────────────
 ```
 
+For Weixin, show `has_token: true/false` from the channels.yml entry (token is never displayed).
+
 If the file doesn't exist: "No channels configured yet. Run `/channel-setup setup` to get started."
 
 ---
@@ -58,34 +63,59 @@ Ask:
 >
 > 1. Feishu
 > 2. WeCom (Enterprise WeChat)
+> 3. Weixin (Personal WeChat via iLink QR login)
 
 ---
 
 ### Feishu setup
 
-#### Phase 1 — Open Feishu Open Platform
+#### Step 1 — Try automated setup (script)
+
+Run the setup script (full path is available in the supporting files list above):
+```bash
+ruby "SKILL_DIR/feishu_setup.rb"
+```
+
+**If exit code is 0:**
+- The script completed successfully.
+- Config is already written to `~/.clacky/channels.yml`.
+- Tell the user: "✅ Feishu channel configured automatically! The channel is ready."
+- **Stop here — do not proceed to manual steps.**
+
+**If exit code is non-0 (or script not found):**
+- Note the failure reason from stdout (the last `❌` line).
+- Tell the user: "Automated setup encountered an issue: `<reason>`. Switching to guided setup..."
+- Continue to Step 2 (manual flow) below.
+
+---
+
+#### Step 2 — Manual guided setup (fallback)
+
+Only reach here if the automated script failed.
+
+##### Phase 1 — Open Feishu Open Platform
 
 1. Navigate: `open https://open.feishu.cn/app`. Pass `isolated: true`.
 2. If a login page or QR code is shown, tell the user to log in and wait for "done".
 3. Confirm the app list is visible.
 
-#### Phase 2 — Create a new app
+##### Phase 2 — Create a new app
 
-6. **Always create a new app** — do NOT reuse existing apps. Guide the user: "Click 'Create Enterprise Self-Built App', fill in name (e.g. Open Clacky) and description (e.g. AI assistant powered by open-clacky), then submit. Reply done." Wait for "done".
+4. **Always create a new app** — do NOT reuse existing apps. Guide the user: "Click 'Create Enterprise Self-Built App', fill in name (e.g. Open Clacky) and description (e.g. AI assistant powered by open-clacky), then submit. Reply done." Wait for "done".
 
-#### Phase 3 — Enable Bot capability
+##### Phase 3 — Enable Bot capability
 
-7. Feishu opens Add App Capabilities by default after creating an app. Guide the user: "Find the Bot capability card and click the Add button next to it, then reply done." Wait for "done".
+5. Feishu opens Add App Capabilities by default after creating an app. Guide the user: "Find the Bot capability card and click the Add button next to it, then reply done." Wait for "done".
 
-#### Phase 4 — Get credentials
+##### Phase 4 — Get credentials
 
-8. Navigate to Credentials & Basic Info in the left menu.
-9. Guide the user: "Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" Wait for "done".
+6. Navigate to Credentials & Basic Info in the left menu.
+7. Guide the user: "Copy App ID and App Secret, then paste here. Reply with: App ID: xxx, App Secret: xxx" Wait for the reply. Parse `app_id` and `app_secret`.
 
-#### Phase 5 — Add message permissions
+##### Phase 5 — Add message permissions
 
-10. Navigate to Permission Management and open the bulk import dialog.
-11. Guide the user: "In the bulk import dialog, clear the existing example first (select all, delete), then paste the following JSON. Reply done." Wait for "done". Do NOT try to clear or edit via browser — user does it.
+8. Navigate to Permission Management and open the bulk import dialog.
+9. Guide the user: "In the bulk import dialog, clear the existing example first (select all, delete), then paste the following JSON. Reply done." Wait for "done". Do NOT try to clear or edit via browser — user does it.
 
 ```json
 {
@@ -100,31 +130,38 @@ Ask:
 }
 ```
 
-#### Phase 6 — Configure event subscription (Long Connection)
-
-**CRITICAL**: Feishu requires the long connection to be established *before* you can save the event config. The platform shows "No application connection detected, ensure long connection is established before saving" until `clacky server` is running and connected. Do NOT try to save until the connection is established.
+##### Phase 6 — Configure event subscription (Long Connection)
 
-12. **Apply config and establish connection** — Run `curl -X POST http://localhost:7070/api/channels/feishu -H "Content-Type: application/json" -d '{"app_id":"...","app_secret":"...","domain":"..."}'`. The server hot-reloads the Feishu adapter and establishes the WebSocket.
-13. **Wait for connection** — Wait until the log shows `[feishu-ws] WebSocket connected ✅`.
-14. **Navigate to Events & Callbacks** — Then guide the user: "Select 'Long Connection' mode. Click Save. Then click Add Event, type `im.message.receive_v1` in the search box, select it, click Add. Reply done." Wait for "done".
+**CRITICAL**: Feishu requires the long connection to be established *before* you can save the event config. The platform shows "No application connection detected" until `clacky server` is running and connected.
 
-#### Phase 7 — Publish the app
+10. **Apply config and establish connection** — Run:
+    ```bash
+    curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/feishu \
+      -H "Content-Type: application/json" \
+      -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>","domain":"https://open.feishu.cn"}'
+    ```
+11. **Wait for connection** — Poll until log shows `[feishu-ws] WebSocket connected ✅`:
+    ```bash
+    for i in $(seq 1 20); do
+      grep -q "\[feishu-ws\] WebSocket connected" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log 2>/dev/null && echo "CONNECTED" && break
+      sleep 1
+    done
+    ```
+12. **Configure events** — Guide the user: "In Events & Callbacks, select 'Long Connection' mode. Click Save. Then click Add Event, search `im.message.receive_v1`, select it, click Add. Reply done." Wait for "done".
 
-15. Navigate to Version Management & Release. Then guide the user: "Create a new version, fill in version (e.g. 1.0.0) and update description (e.g. Initial release for Open Clacky), then publish. Reply done." Wait for "done".
+##### Phase 7 — Publish the app
 
-#### Phase 8 — Finalize config and validate
+13. Navigate to Version Management & Release. Guide the user: "Create a new version (e.g. 1.0.0, note: Initial release for Open Clacky) and publish it. Reply done." Wait for "done".
 
-Config was applied in step 12 (via API).
+##### Phase 8 — Validate
 
-Validate:
 ```bash
-curl -s -X POST "${DOMAIN}/open-apis/auth/v3/tenant_access_token/internal" \
+curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
   -H "Content-Type: application/json" \
-  -d "{\"app_id\":\"${APP_ID}\",\"app_secret\":\"${APP_SECRET}\"}"
+  -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'
 ```
-Check for `"code":0`. If it fails, explain and offer to retry.
 
-On success: "✅ Feishu channel configured. The channel is already active."
+Check for `"code":0`. On success: "✅ Feishu channel configured."
 
 ---
 
@@ -132,13 +169,70 @@ On success: "✅ Feishu channel configured. The channel is already active."
 
 1. Navigate: `open https://work.weixin.qq.com/wework_admin/frame#/aiHelper/create`. Pass `isolated: true`.
 2. If a login page or QR code is shown, tell the user to log in and wait for "done".
-3. Steps 3–7: Do NOT take snapshots. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation'. Reply done." Wait for "done".
-4. Guide the user: "Click 'Add' next to 'Visible Range'. In the scope dialog, select the top-level company node (or specific users/departments). Click Confirm. Reply done." Wait for "done".
-5. Guide the user: "If Secret is not visible, click 'Get Secret'. Copy Bot ID and Secret **before** clicking Save — do NOT click 'Get Secret' again after copying (it invalidates the previous secret). Paste here. Reply with: Bot ID: xxx, Secret: xxx" Wait for "done".
-6. Guide the user: "Click Save. In the dialog, enter name (e.g. Open Clacky) and description (e.g. AI assistant powered by open-clacky). Click Confirm. Click Save again. Reply done." Wait for "done".
-7. **Apply config and hot-reload** — Parse credentials from step 5. Trim leading/trailing whitespace from bot_id and secret. Run `curl -X POST http://localhost:7070/api/channels/wecom -H "Content-Type: application/json" -d '{"bot_id":"...","secret":"..."}'`. Ensure bot_id (starts with `aib`) and secret (longer string) are not swapped.
+3. Guide the user: "Scroll to the bottom of the right panel and click 'API mode creation'. Reply done." Wait for "done".
+4. Guide the user: "Click 'Add' next to 'Visible Range'. Select the top-level company node. Click Confirm. Reply done." Wait for "done".
+5. Guide the user: "If Secret is not visible, click 'Get Secret'. Copy Bot ID and Secret **before** clicking Save. Paste here. Reply with: Bot ID: xxx, Secret: xxx" Wait for "done".
+6. Guide the user: "Click Save. Enter name (e.g. Open Clacky) and description. Click Confirm. Click Save again. Reply done." Wait for "done".
+7. Parse credentials. Trim whitespace. Ensure bot_id (starts with `aib`) and secret are not swapped. Run:
+   ```bash
+   curl -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/wecom \
+     -H "Content-Type: application/json" \
+     -d '{"bot_id":"<BOT_ID>","secret":"<SECRET>"}'
+   ```
+
+On success: "✅ WeCom channel configured. WeCom client → Contacts → Smart Bot to find it."
+
+---
+
+### Weixin setup (Personal WeChat via iLink QR login)
+
+Weixin uses a QR code login — no app_id/app_secret needed. The token from the QR scan is saved directly in `channels.yml`.
+
+#### Step 1 — Fetch QR code and open in browser
+
+Run the script in `--fetch-qr` mode to get the QR URL without blocking:
+
+```bash
+QR_JSON=$(ruby "SKILL_DIR/weixin_setup.rb" --fetch-qr 2>/dev/null)
+echo "$QR_JSON"
+```
+
+Parse the JSON output:
+- `qrcode_url` — the URL to open in browser (this IS the QR code content)
+- `qrcode_id`  — the session ID needed for polling
+
+If the output contains `"error"`, show it and stop.
+
+Tell the user:
+> Opening the WeChat QR code in your browser. Please scan it with WeChat, then confirm in the app.
+
+**Open the QR code page in browser** — build a local URL and navigate to it:
+
+```
+http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/weixin-qr.html?url=<URL-encoded qrcode_url>
+```
+
+Use the browser tool to open this URL. The page renders a proper scannable QR code image using qrcode.js.
+Do NOT open the raw `qrcode_url` directly — that page shows "请使用微信扫码打开" with no actual QR image.
+
+#### Step 3 — Wait for scan and save credentials
+
+Once the browser shows the QR page, immediately run the polling script in the background:
+
+```bash
+ruby "SKILL_DIR/weixin_setup.rb" --qrcode-id "$QRCODE_ID"
+```
+
+Where `$QRCODE_ID` is the `qrcode_id` from Step 2's JSON output.
+
+This command blocks until the user scans and confirms in WeChat (up to 5 minutes), then automatically saves the token via `POST /api/channels/weixin`.
+
+Tell the user while waiting:
+> Waiting for you to scan the QR code and confirm in WeChat... (this may take a moment)
+
+**If exit code is 0:** "✅ Weixin channel configured! You can now message your bot on WeChat."
 
-On success: "✅ WeCom channel configured. To use the bot: WeCom client → Contacts → select Smart Bot to see the newly created bot.".
+**If exit code is non-0 or times out:** Show the error and offer to retry from Step 2.
 
 ---
 
@@ -164,7 +258,7 @@ Say: "❌ `<platform>` channel disabled. Restart `clacky server` to deactivate."
 
 1. Show current config (mask secrets).
 2. Ask: update credentials / change allowed users / add a new platform / enable or disable a platform.
-3. For credential updates, re-run the relevant setup flow (Admin Console or Client flow for WeCom).
+3. For credential updates, re-run the relevant setup flow.
 4. Write atomically: write to `~/.clacky/channels.yml.tmp` then rename to `~/.clacky/channels.yml`.
 5. Say: "Restart `clacky server` to apply changes."
 
@@ -178,13 +272,16 @@ Check each item, report ✅ / ❌ with remediation:
 2. **Required keys** — for each enabled platform:
    - 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`
 3. **Feishu credentials** (if enabled) — run the token API call, check `code=0`.
-4. **WeCom credentials** (if enabled) — search today's log for auth-related lines:
+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:
    ```bash
-   grep -iE "wecom adapter loop started|WeCom authentication failed|WeCom WS error response|WecomAdapter" ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
+   grep -iE "wecom adapter loop started|WeCom authentication failed|WeCom WS error response|WecomAdapter" \
+     ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
    ```
-   - If output contains `WeCom authentication failed` or `WeCom WS error response` with non-zero errcode: ❌ "WeCom Bot ID or Secret is incorrect — re-run `/channel-setup reconfigure`"
-   - If output contains `[ChannelManager] :wecom adapter loop started` with no auth error after it: ✅
+   - `WeCom authentication failed` or non-zero errcode → ❌ "WeCom credentials incorrect"
+   - `adapter loop started` with no auth error → ✅
 
 ---