agent-messenger 2.10.2 → 2.11.1

package/skills/agent-webex/references/authentication.md

@@ -28,10 +28,16 @@ agent-webex auth extract
 
 # With debug output
 agent-webex auth extract --debug
+
+# Scan custom Chromium profile/user-data dirs (repeatable or comma-separated)
+agent-webex auth extract --browser-profile ~/browser-data
+agent-webex auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"
 ```
 
 **Requirements**: You must be logged into web.webex.com in a supported Chromium browser. The browser does not need to be running — the CLI reads directly from on-disk LevelDB files.
 
+Use `--browser-profile <path>` for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles. The option can be repeated or given comma-separated paths.
+
 **Limitations**: Direct messages (`message dm`) require an existing conversation with the recipient. The extracted token cannot create new 1:1 conversations — start one from the Webex app first, then use the CLI.
 
 ### OAuth Device Grant

package/skills/agent-wechatbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-wechatbot
 description: Interact with WeChat Official Account using API credentials - send messages, manage templates, list followers
-version: 2.10.2
+version: 2.11.1
 allowed-tools: Bash(agent-wechatbot:*)
 metadata:
   openclaw:
@@ -255,6 +255,8 @@ agent-wechatbot template list --pretty
 
 ## Common Patterns
 
+See `references/common-patterns.md` for additional workflows.
+
 ### Send a customer service message within 48h window
 
 Customer service messages can be sent to users who have interacted with your account within the last 48 hours:
@@ -305,6 +307,14 @@ agent-wechatbot template send oABCD1234 deployment_alert \
   --data '{"version":{"value":"v2.1.0"},"environment":{"value":"production"},"status":{"value":"success"}}'
 ```
 
+## Templates
+
+See `templates/` directory for runnable examples:
+
+- `post-message.sh` - Send a customer service message with error handling and retries
+- `account-summary.sh` - Generate account, template, and follower summary
+- `send-template.sh` - Send a template message with parameters
+
 ## Error Handling
 
 All commands return consistent error format:
@@ -392,3 +402,8 @@ These indicate an expired or invalid access token. The CLI handles automatic tok
 ### Rate limiting (45009)
 
 WeChat enforces API call frequency limits. If you hit error `45009`, wait before retrying. For bulk operations, add delays between requests.
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)

package/skills/agent-wechatbot/references/authentication.md

@@ -0,0 +1,219 @@
+# Authentication Guide
+
+## Overview
+
+agent-wechatbot uses the WeChat Official Account API with App ID + App Secret authentication. Credentials come from the WeChat Official Account admin panel. No desktop app extraction or pairing codes needed.
+
+## API Credential Setup
+
+### How It Works
+
+1. You log in to the WeChat Official Account admin panel
+2. Open **Development > Basic Configuration**
+3. Copy your **App ID** and **App Secret**
+4. Add your server's IP to the **IP Whitelist**
+5. Store both credentials in the CLI with `auth set`
+
+The CLI validates credentials against the WeChat Official Account API before saving.
+
+### Setting Credentials
+
+```bash
+agent-wechatbot auth set <app-id> <app-secret>
+```
+
+Response on success:
+
+```json
+{ "success": true, "app_id": "wx1234567890", "account_name": "wx1234567890" }
+```
+
+Response on failure:
+
+```json
+{
+  "error": "Invalid credentials. Check your App ID and App Secret."
+}
+```
+
+### Getting Credentials from the WeChat Admin Panel
+
+1. Log in to the [WeChat Official Account admin panel](https://mp.weixin.qq.com/)
+2. Navigate to **Development > Basic Configuration**
+3. **App ID**: shown directly under "Developer ID (AppID)"
+4. **App Secret**: under "Developer Password (AppSecret)" — click **View** or **Reset** to retrieve. The secret is shown only once on creation; keep it safe.
+5. **IP Whitelist**: in the same screen, add the IP address(es) of any server that will run the CLI. WeChat returns error `40164` if the calling IP is not whitelisted.
+6. Run `agent-wechatbot auth set <app-id> <app-secret>`
+
+### Access Token Lifecycle
+
+WeChat issues a short-lived access token internally on every API call. The CLI handles token caching and refresh automatically:
+
+- **Access tokens** expire after 7200 seconds (2 hours)
+- The CLI fetches a new token on demand and caches it in memory for the duration of the process
+- You do **not** store the access token yourself — only the App ID + App Secret
+
+## Multi-Account Management
+
+Multiple WeChat Official Accounts can be stored simultaneously.
+
+### List Accounts
+
+```bash
+agent-wechatbot auth list
+```
+
+```json
+[
+  {
+    "account_id": "wx1234567890",
+    "app_id": "wx1234567890",
+    "account_name": "Acme Notifications",
+    "current": true
+  },
+  {
+    "account_id": "wx0987654321",
+    "app_id": "wx0987654321",
+    "account_name": "Acme Marketing",
+    "current": false
+  }
+]
+```
+
+### Switch Account
+
+```bash
+agent-wechatbot auth use wx0987654321
+```
+
+### Per-Command Account
+
+Commands accept `--account <id>` to use a specific account without switching:
+
+```bash
+agent-wechatbot message send oABCD1234 "Hello" --account wx0987654321
+agent-wechatbot template list --account wx0987654321
+```
+
+### Remove Account
+
+```bash
+agent-wechatbot auth remove <account-id>
+```
+
+## Credential Storage
+
+### Location
+
+```
+~/.config/agent-messenger/wechatbot-credentials.json
+```
+
+### Format
+
+```json
+{
+  "current": { "account_id": "wx1234567890" },
+  "accounts": {
+    "wx1234567890": {
+      "app_id": "wx1234567890",
+      "app_secret": "...",
+      "account_name": "wx1234567890"
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- App secrets are stored in plaintext
+- Keep this file secure. The App Secret grants full messaging access to your Official Account
+- Never commit to version control
+
+## Authentication Status
+
+Check current auth state:
+
+```bash
+agent-wechatbot auth status
+```
+
+Output when authenticated:
+
+```json
+{
+  "authenticated": true,
+  "account_id": "wx1234567890",
+  "app_id": "wx1234567890",
+  "account_name": "Acme Notifications"
+}
+```
+
+Output when not authenticated:
+
+```json
+{
+  "error": "No credentials. Run \"auth set <app-id> <app-secret>\" first."
+}
+```
+
+Check a specific account:
+
+```bash
+agent-wechatbot auth status --account wx0987654321
+```
+
+## Clear Credentials
+
+Remove all stored credentials:
+
+```bash
+agent-wechatbot auth clear
+```
+
+## Re-authentication
+
+If commands start failing with auth errors:
+
+```bash
+# Check current status
+agent-wechatbot auth status
+
+# Re-set credentials (e.g., after rotating the App Secret)
+agent-wechatbot auth set <app-id> <new-app-secret>
+
+# Verify it worked
+agent-wechatbot auth status
+```
+
+## Common Auth Errors
+
+| WeChat errcode | Meaning                                         | Fix                                                                                       |
+| -------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `40001`        | Invalid access token                            | Token rotation race; retry. Persistent errors mean the App Secret is wrong.               |
+| `40013`        | Invalid App ID                                  | Verify the App ID matches your account in the admin panel                                 |
+| `40125`        | Invalid App Secret                              | The App Secret is incorrect. Reset it in the admin panel and re-run `auth set`.           |
+| `40164`        | Calling IP not in IP whitelist                  | Add your server's public IP to the IP Whitelist in **Development > Basic Configuration**. |
+| `42001`        | Access token expired                            | The CLI will refresh automatically. Persistent errors indicate a network issue.           |
+| `45009`        | API call frequency limit exceeded               | Slow down. Add delays between calls in batch operations.                                  |
+
+## Security Considerations
+
+### What agent-wechatbot Can Access
+
+With stored credentials, agent-wechatbot can:
+
+- Send customer service messages (text, image, news) to followers within the 48h window
+- Send pre-approved template messages to followers at any time
+- List and inspect message templates
+- List followers and retrieve follower info (OpenID, language, subscribe time)
+
+### What agent-wechatbot Cannot Do
+
+- Read or list received messages (webhook-only for inbound)
+- Access group chats (Official Accounts are 1:1 with followers)
+- Make voice or video calls
+- Manage Official Account settings
+- Upload media (images must be uploaded to WeChat's media platform separately and referenced by media ID)
+- Edit or delete sent messages

package/skills/agent-wechatbot/references/common-patterns.md

@@ -0,0 +1,358 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with WeChat Official Account API using agent-wechatbot.
+
+## Pattern 1: Send a Customer Service Message
+
+**Use case**: Reply to a follower within the 48-hour customer service window
+
+```bash
+#!/bin/bash
+
+OPENID="oABCD1234"
+
+# Direct approach
+agent-wechatbot message send "$OPENID" "Thanks for reaching out!"
+
+# With error handling
+RESULT=$(agent-wechatbot message send "$OPENID" "Hello")
+if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
+  exit 1
+fi
+echo "Message sent"
+```
+
+**When to use**: Replying to a follower who interacted with the Official Account in the last 48 hours.
+
+**Note**: Free-form text only works within the 48-hour customer service window. Outside that window, use template messages.
+
+## Pattern 2: Send a Template Notification
+
+**Use case**: Send a pre-approved template message at any time
+
+```bash
+#!/bin/bash
+
+OPENID="oABCD1234"
+TEMPLATE_ID="TM00001"
+
+# First, list available templates
+agent-wechatbot template list --pretty
+
+# Send the template with data
+agent-wechatbot template send "$OPENID" "$TEMPLATE_ID" \
+  --data '{"order_id":{"value":"ORD-9876"},"customer_name":{"value":"Alice"}}' \
+  --url "https://example.com/orders/9876"
+```
+
+**When to use**: Order confirmations, shipping updates, appointment reminders, system notifications outside the 48h window.
+
+**Important**: Templates must be created and approved in the WeChat admin panel before use.
+
+## Pattern 3: Discover Templates
+
+**Use case**: Find the right template and its required parameters
+
+```bash
+#!/bin/bash
+
+# List all templates
+TEMPLATES=$(agent-wechatbot template list)
+
+# Extract required parameters for each template
+echo "$TEMPLATES" | jq '.template_list[] | {template_id, title, content, example}'
+```
+
+**When to use**: First time sending templates, or when you need to verify parameter structure.
+
+## Pattern 4: Send a News/Article Message
+
+**Use case**: Share a rich content card with a follower
+
+```bash
+#!/bin/bash
+
+OPENID="oABCD1234"
+
+agent-wechatbot message send-news "$OPENID" \
+  --title "Your Order Update" \
+  --description "Your order #12345 has shipped and will arrive in 3 days" \
+  --url "https://example.com/orders/12345" \
+  --picurl "https://example.com/images/shipping.jpg"
+```
+
+**When to use**: Sending order updates, blog posts, marketing content with a clickable card. Within 48h window only.
+
+## Pattern 5: Send an Image Message
+
+**Use case**: Share an image with a follower (requires pre-uploaded media ID)
+
+```bash
+#!/bin/bash
+
+OPENID="oABCD1234"
+MEDIA_ID="MEDIA_ID_FROM_UPLOAD_API"  # Obtain via WeChat's media upload API separately
+
+agent-wechatbot message send-image "$OPENID" "$MEDIA_ID"
+```
+
+**When to use**: Product photos, QR codes, support screenshots. Within 48h window only.
+
+**Note**: Images must be uploaded to WeChat's media platform first using the [media upload API](https://developers.weixin.qq.com/doc/offiaccount/Asset_Management/New_temporary_materials.html). The CLI does not handle media upload; it expects an existing `media_id`.
+
+## Pattern 6: List and Inspect Followers
+
+**Use case**: Discover follower OpenIDs and basic info
+
+```bash
+#!/bin/bash
+
+# Get first page of followers (up to 10,000)
+FOLLOWERS=$(agent-wechatbot user list)
+
+# Extract OpenIDs
+echo "$FOLLOWERS" | jq -r '.data.openid[]'
+
+# Paginate (next page)
+NEXT=$(echo "$FOLLOWERS" | jq -r '.next_openid')
+if [ -n "$NEXT" ] && [ "$NEXT" != "null" ]; then
+  agent-wechatbot user list --next-openid "$NEXT"
+fi
+
+# Get details for a specific follower
+agent-wechatbot user get oABCD1234 --pretty
+```
+
+**When to use**: Building a follower list for broadcasts, discovering OpenIDs to message.
+
+## Pattern 7: Multi-Recipient Template Notification
+
+**Use case**: Send the same template to multiple followers
+
+```bash
+#!/bin/bash
+
+TEMPLATE_ID="TM00001"
+OPENIDS=("oABCD1234" "oEFGH5678" "oIJKL9012")
+
+for openid in "${OPENIDS[@]}"; do
+  echo "Sending to $openid..."
+  RESULT=$(agent-wechatbot template send "$openid" "$TEMPLATE_ID" \
+    --data '{"order_id":{"value":"ORD-001"},"status":{"value":"shipped"}}')
+
+  if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    echo "  Failed: $(echo "$RESULT" | jq -r '.error')"
+  else
+    echo "  Sent"
+  fi
+
+  # Respect rate limits
+  sleep 1
+done
+```
+
+**When to use**: Broadcasting order updates, scheduled reminders, bulk notifications.
+
+## Pattern 8: Multi-Account Workflow
+
+**Use case**: Send from different Official Accounts
+
+```bash
+#!/bin/bash
+
+# Send from notifications account
+agent-wechatbot template send oABCD1234 TM00001 \
+  --data '{"order_id":{"value":"ORD-001"}}' \
+  --account wx1234567890
+
+# Send from marketing account
+agent-wechatbot message send oABCD1234 "Check out our new products!" \
+  --account wx0987654321
+```
+
+**When to use**: Managing multiple Official Accounts (notifications, marketing, support).
+
+## Pattern 9: CI/CD Deployment Notification
+
+**Use case**: Notify a team via template after deployment
+
+```bash
+#!/bin/bash
+
+VERSION="v2.1.0"
+ENVIRONMENT="production"
+STATUS="success"
+ON_CALL_OPENID="oABCD1234"
+
+agent-wechatbot template send "$ON_CALL_OPENID" deployment_alert \
+  --data "{\"version\":{\"value\":\"$VERSION\"},\"environment\":{\"value\":\"$ENVIRONMENT\"},\"status\":{\"value\":\"$STATUS\"}}" \
+  --url "https://ci.example.com/builds/$VERSION"
+```
+
+**When to use**: Automated deployment notifications, build status alerts.
+
+## Pattern 10: Error Handling and Retry
+
+**Use case**: Robust message sending with retries
+
+```bash
+#!/bin/bash
+
+send_with_retry() {
+  local openid=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    echo "Attempt $attempt/$max_attempts..."
+
+    RESULT=$(agent-wechatbot message send "$openid" "$message" 2>&1)
+
+    if ! echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+      echo "Message sent!"
+      return 0
+    fi
+
+    ERROR=$(echo "$RESULT" | jq -r '.error')
+    echo "Failed: $ERROR"
+
+    # Don't retry auth errors
+    if echo "$ERROR" | grep -q "No credentials"; then
+      echo "Not authenticated. Run: agent-wechatbot auth set <app-id> <app-secret>"
+      return 1
+    fi
+
+    # Don't retry IP whitelist errors
+    if echo "$ERROR" | grep -q "40164"; then
+      echo "IP not whitelisted. Add server IP in WeChat admin panel."
+      return 1
+    fi
+
+    # Don't retry if outside 48h window
+    if echo "$ERROR" | grep -q "48h\|48-hour"; then
+      echo "Use template messages instead: agent-wechatbot template send ..."
+      return 1
+    fi
+
+    if [ $attempt -lt $max_attempts ]; then
+      SLEEP_TIME=$((attempt * 3))
+      echo "Retrying in ${SLEEP_TIME}s..."
+      sleep $SLEEP_TIME
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  echo "Failed after $max_attempts attempts"
+  return 1
+}
+
+# Usage
+send_with_retry "oABCD1234" "Important update!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Best Practices
+
+### 1. Cache Template Info
+
+```bash
+# Good: discover once, reuse
+TEMPLATES=$(agent-wechatbot template list)
+# ... use template info for multiple sends
+
+# Bad: fetch templates before every send
+agent-wechatbot template list  # Wasteful
+agent-wechatbot template send ...
+agent-wechatbot template list  # Wasteful
+agent-wechatbot template send ...
+```
+
+### 2. Use Memory for Known Templates
+
+Store frequently used template IDs and their parameters in `~/.config/agent-messenger/MEMORY.md` to skip `template list` calls in future sessions.
+
+### 3. Respect Rate Limits
+
+```bash
+# Good: pause between operations
+for openid in "${OPENIDS[@]}"; do
+  agent-wechatbot template send "$openid" "$TEMPLATE_ID" ...
+  sleep 1
+done
+
+# Bad: rapid-fire (will hit errcode 45009)
+for openid in "${OPENIDS[@]}"; do
+  agent-wechatbot template send "$openid" "$TEMPLATE_ID" ...
+done
+```
+
+### 4. Check Auth Before Multi-Step Workflows
+
+```bash
+# Good: verify auth upfront
+STATUS=$(agent-wechatbot auth status)
+if echo "$STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Not authenticated"
+  exit 1
+fi
+
+# Proceed with workflow
+agent-wechatbot template list
+agent-wechatbot template send ...
+```
+
+### 5. Use Templates for Proactive Messages
+
+```bash
+# Bad: will fail outside 48h window
+agent-wechatbot message send oABCD1234 "Your order shipped!"
+
+# Good: works anytime
+agent-wechatbot template send oABCD1234 shipping_update \
+  --data '{"order_id":{"value":"ORD-001"}}'
+```
+
+## Anti-Patterns
+
+### Don't Send Customer Service Messages Outside the 48h Window
+
+```bash
+# Bad: will fail if follower hasn't interacted recently
+agent-wechatbot message send oABCD1234 "Reminder: your appointment is tomorrow"
+
+# Good: use a template
+agent-wechatbot template send oABCD1234 appointment_reminder \
+  --data '{"date":{"value":"2024-01-15"},"time":{"value":"14:00"}}'
+```
+
+### Don't Hardcode Template Data Structure
+
+```bash
+# Bad: fragile if template parameters change
+agent-wechatbot template send oABCD1234 order_confirmation \
+  --data '{"name":{"value":"Alice"}}'
+
+# Good: verify template structure first
+TEMPLATE=$(agent-wechatbot template list | jq '.template_list[] | select(.template_id=="TM00001")')
+# Inspect required parameters, then build data dynamically
+```
+
+### Don't Forget the IP Whitelist
+
+```bash
+# Bad: deploying to a new server without updating the WeChat admin panel
+# Result: errcode 40164 — IP not in whitelist
+
+# Good: add the server IP to the WeChat admin panel BEFORE deploying
+# Development > Basic Configuration > IP Whitelist
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up API credentials