@tencent-ai/agent-sdk 0.3.99 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/wecom-bot-setup.md

@@ -0,0 +1,274 @@
+# WeChat Work AI Bot Integration Guide
+
+Through the `/remote-control` command, you can quickly integrate CodeBuddy Code with WeChat Work AI Bot, enabling remote message-driven functionality. Using **WebSocket long polling** active connection mode, no public IP is required, making configuration the simplest option.
+
+## Prerequisites
+
+- Registered WeChat Work account
+- CodeBuddy Code installed: `codebuddy --version`
+- Completed login authentication: After running `codebuddy`, execute `/login`
+
+
+## 2. Configure Environment Variables
+
+Before starting CodeBuddy CLI, set the following environment variables:
+
+```bash
+export CODEBUDDY_WECOM_BOT_ID="<your Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<your Bot Secret>"
+```
+
+### Optional Configuration
+
+| Environment Variable | Description | Default Value |
+|---------------------|-------------|---------------|
+| `CODEBUDDY_WECOM_BOT_ID` | AI Bot ID (required) | — |
+| `CODEBUDDY_WECOM_BOT_SECRET` | AI Bot Secret (required) | — |
+| `CODEBUDDY_WECOM_BOT_WS_URL` | WebSocket server address (used for private deployment) | `wss://openws.work.weixin.qq.com` |
+
+### Persistent Configuration (Optional)
+
+Add environment variables to your shell startup file for automatic loading on each startup:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export CODEBUDDY_WECOM_BOT_ID="<your Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<your Bot Secret>"
+```
+
+---
+
+## 3. Start CodeBuddy and Connect
+
+### 3.1 Start Interactive Mode
+
+```bash
+codebuddy
+```
+
+### 3.2 Open Remote Control Panel
+
+```
+/remote-control
+```
+
+This command opens an interactive panel listing all available connection clients.
+
+### 3.3 Connect to wecom-bot
+
+Use arrow keys to select the `wecom-bot` entry and press `Enter` to initiate connection:
+
+```
+Remote Control Clients
+
+  1. • wecom-bot  [disconnected]  (Press Enter to connect)
+  2. • centrifugo [disconnected]
+  3. Cancel
+```
+
+The panel will automatically close after successful connection. If environment variables are not configured, the panel will stay and display error messages.
+
+### 3.4 Check Connection Status
+
+Run `/remote-control` again to check the connection status:
+
+```
+  1. • wecom-bot  [connected]  (Press Enter to disconnect)
+  2. Cancel
+```
+
+Status descriptions:
+- `disconnected` — Not connected, can initiate connection
+- `connecting` — Connecting, please wait
+- `connected` — Connected, can disconnect
+
+---
+
+## 4. Panel Operation Instructions
+
+| Operation | Description |
+|-----------|-------------|
+| `↑` / `↓` | Select client entry |
+| `j` / `k` | Vim-style navigation (equivalent to up/down arrow keys) |
+| `Enter` | Connect (in `disconnected` state) or disconnect (in `connected`/`connecting` state) |
+| `Esc` | Exit panel (not responsive during operations in progress) |
+
+---
+
+## 5. Verify Integration
+
+After establishing the connection, you can verify that the Bot is working properly through the following methods.
+
+### Method 1: Direct Conversation
+
+1. Open the WeChat Work client (desktop or mobile)
+2. Find the Bot you created in the message list
+3. Send a test message (such as "Hello") and confirm the Bot replies
+
+### Method 2: Group Chat
+
+1. Add the Bot to a group chat
+2. Send a message via @Bot name in the group
+3. The Bot will respond to @mentioned messages
+
+---
+
+## 6. Message Processing Flow and Status Indicators
+
+### Complete Message Processing Flow
+
+The processing flow after a user sends a message to the Bot:
+
+```
+User sends message on WeChat Work
+        ↓ WebSocket long polling real-time message push
+CodeBuddy CLI receives message
+        ↓ Reply within 5 seconds (meets WeChat Work callback timeout requirement)
+Send streaming message (stream finish=false): "Processing, please wait..."
+        ↓ WeChat Work client displays streaming message
+Agent processing... (processing time may be 1 second to 5+ minutes)
+        ↓
+Processing complete, send streaming message (stream finish=true): Final result
+        ↓ WeChat Work client replaces "Processing..." with final result
+WeChat Work user sees final reply (only the final result is kept in chat history)
+```
+
+### Streaming Status Indicator Mechanism
+
+Utilizing the full replacement feature of WeChat Work streaming messages (`aibot_respond_msg` stream type):
+
+1. **Immediate Reply**: After receiving a user message, immediately send a streaming message with `finish=false`, content: "Processing, please wait..."
+2. **In-place Replacement**: After the Agent finishes processing, send `finish=true` + final result using the same `stream.id`
+3. When the WeChat Work client receives `finish=true`, it replaces the previously displayed "Processing, please wait..." with the full content
+
+> Reference: [AI Bot Long Polling Documentation](https://developer.work.weixin.qq.com/document/path/101463) —— stream.content is full content, each send replaces the previous display.
+
+#### User Experience
+
+| Stage | Chat Window Display | Description |
+|-------|--------------------|-------------|
+| After message sent | "Processing, please wait..." | Streaming message placeholder, indicating Bot is processing |
+| After processing complete | Final reply content | "Processing..." replaced in-place by final result |
+
+#### Difference from Previous Solution
+
+| Aspect | Old Solution (Text Message ack) | New Solution (Streaming Message Replacement) |
+|--------|--------------------------------|---------------------------------------------|
+| "Processing, please wait..." | Permanently kept in chat history | Replaced in-place by final result |
+| Chat History | 2 messages (ack + result) | 1 message (final result only) |
+| Status Indicator | Yes | Yes |
+
+### Timeout Handling
+
+- **Streaming Message Timeout**: 6 minutes (timed from first stream send)
+- **Safety Timeout**: 5 minutes (1 minute buffer reserved)
+- **Timeout Fallback**: If Agent processing exceeds 5 minutes, automatically fallback to async push (`aibot_send_msg`, 24-hour validity)
+- **Callback Timeout**: Must send reply within 5 seconds after receiving message callback (streaming placeholder message meets this requirement)
+
+---
+
+## 7. How It Works
+
+```
+WeChat Work user sends message
+        ↓
+WeChat Work server (WebSocket connection pool)
+        ↓ WebSocket long polling real-time push
+CodeBuddy CLI (WecomBotClient)
+        ↓
+CodeBuddy Agent processes message, generates reply
+        ↓
+Reply message via the same WebSocket connection
+        ↓
+WeChat Work user receives Bot reply
+```
+
+### Key Features
+
+- **Connection Mode**: WebSocket long polling (client actively connects, no public IP required)
+- **Authentication Mechanism**: Send `aibot_subscribe` frame on startup, carrying `bot_id` + `secret` for authentication
+- **Message Reception**: WeChat Work server pushes user messages in real-time via `aibot_msg_callback` frame
+- **Message Reply**: Return Agent replies in streaming mode via `aibot_respond_msg` frame
+- **Heartbeat Keep-alive**: Send `ping` frame every 30 seconds to keep connection alive
+- **Auto Reconnect**: Automatically reconnect after connection drop with exponential backoff strategy, maximum delay 60 seconds
+
+---
+
+## 8. FAQ
+
+### Environment Variables Not Configured
+
+**Symptom**: Error displayed after selecting `wecom-bot` in `/remote-control` panel
+
+```
+Error: WeChat Work AI Bot is not configured.
+Missing environment variables: CODEBUDDY_WECOM_BOT_ID, CODEBUDDY_WECOM_BOT_SECRET
+```
+
+**Solution**:
+1. Confirm that `CODEBUDDY_WECOM_BOT_ID` and `CODEBUDDY_WECOM_BOT_SECRET` are set
+2. Execute `echo $CODEBUDDY_WECOM_BOT_ID` to verify environment variables are active
+3. Restart CodeBuddy CLI
+4. Execute `/remote-control` again to try connecting
+
+### Connection Failed
+
+**Possible Causes and Troubleshooting**:
+
+1. **Incorrect Bot ID or Secret**
+   - Confirm the values copied from WeChat Work admin console are exactly the same (note if there are trailing spaces)
+   - Confirm the AI Bot application status is normal and not disabled
+
+2. **Network Connection Issues**
+   - Check if you can access `wss://openws.work.weixin.qq.com`
+   - For private deployment, confirm `CODEBUDDY_WECOM_BOT_WS_URL` is set correctly
+   - Test network connection in browser: `curl -v wss://openws.work.weixin.qq.com`
+
+3. **CLI Log Viewing**
+   - Check error logs in terminal output
+   - After executing `codebuddy`, stay in the main interface and observe output during connection process
+
+### No Response After Connection
+
+**Troubleshooting Steps**:
+
+1. Execute `/remote-control` to confirm `wecom-bot` status is `connected`
+2. If status is `disconnected`, reconnect
+3. Check CLI terminal logs for error messages
+4. Confirm CodeBuddy CLI process is still running (not interrupted or exited)
+
+### CLI Restart Requires Reconnection
+
+The `/remote-control` connection status is temporary and not persisted. After each CodeBuddy CLI restart, you need to execute `/remote-control` again and select `wecom-bot` to establish connection.
+
+**Auto-Connect Solution** (if you need auto-connect on each startup):
+
+Add the following to your startup script or shell configuration file:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export CODEBUDDY_WECOM_BOT_ID="<your Bot ID>"
+export CODEBUDDY_WECOM_BOT_SECRET="<your Bot Secret>"
+
+# Optional: Create alias for quick startup with auto-connect
+alias cbc-wecom='codebuddy -c "/remote-control"'
+```
+
+> The `-c` parameter indicates automatically executing the specified command on startup.
+
+### App Shows "Token Expired" or "Invalid Secret"
+
+This usually means the Bot's Secret has expired or been regenerated. Solution:
+
+1. Log into WeChat Work admin console and go to Bot details page
+2. Regenerate Secret in the "API Configuration" area
+3. Update the environment variable `CODEBUDDY_WECOM_BOT_SECRET`
+4. Restart CodeBuddy CLI and reconnect
+
+---
+
+## Related Documentation
+
+- [Remote Control](./remote-control.md) - Learn about all Remote Control features and other clients
+- [Slash Commands](./slash-commands.md) - Master all built-in commands
+- [Settings](./settings.md) - Learn about CodeBuddy configuration options