yuanbao platform (#16298)

Co-authored-by: loongzhao <loongzhao@tencent.com>
2026-04-28 15:01:34 +08:00 · 2026-04-26 18:50:49 -07:00
parent 5eb6cd82b2
commit ab6879634e
28 changed files with 10997 additions and 12 deletions
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -1,12 +1,12 @@
 ---
 sidebar_position: 1
 title: "Messaging Gateway"
-description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Webhooks, or any OpenAI-compatible frontend via the API server — architecture and setup overview"
+description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Yuanbao, Webhooks, or any OpenAI-compatible frontend via the API server — architecture and setup overview"
 ---

 # Messaging Gateway

-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

 For the full voice feature set — including CLI microphone mode, spoken replies in messaging, and Discord voice-channel conversations — see [Voice Mode](/docs/user-guide/features/voice-mode) and [Use Voice Mode with Hermes](/docs/guides/use-voice-mode-with-hermes).

@@ -31,6 +31,7 @@ For the full voice feature set — including CLI microphone mode, spoken replies
 | Weixin | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |
 | BlueBubbles | — | ✅ | ✅ | — | ✅ | ✅ | — |
 | QQ | ✅ | ✅ | ✅ | — | — | ✅ | — |
+| Yuanbao | ✅ | ✅ | ✅ | — | — | ✅ | ✅ |

 **Voice** = TTS audio replies and/or voice message transcription. **Images** = send/receive images. **Files** = send/receive file attachments. **Threads** = threaded conversations. **Reactions** = emoji reactions on messages. **Typing** = typing indicator while processing. **Streaming** = progressive message updates via editing.

@@ -57,6 +58,7 @@ flowchart TB
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
+    yb[Yuanbao]
            api["API Server<br/>(OpenAI-compatible)"]
            wh[Webhooks]
        end
@@ -83,6 +85,7 @@ flowchart TB
    wx --> store
    bb --> store
    qq --> store
+    yb --> store
    api --> store
    wh --> store
    store --> agent
@@ -386,6 +389,7 @@ Each platform has its own toolset:
 | Weixin | `hermes-weixin` | Full tools including terminal |
 | BlueBubbles | `hermes-bluebubbles` | Full tools including terminal |
 | QQBot | `hermes-qqbot` | Full tools including terminal |
+| Yuanbao | `hermes-yuanbao` | Full tools including terminal |
 | API Server | `hermes` (default) | Full tools including terminal |
 | Webhooks | `hermes-webhook` | Full tools including terminal |

@@ -408,5 +412,6 @@ Each platform has its own toolset:
 - [Weixin Setup (WeChat)](weixin.md)
 - [BlueBubbles Setup (iMessage)](bluebubbles.md)
 - [QQBot Setup](qqbot.md)
+- [Yuanbao Setup](yuanbao.md)
 - [Open WebUI + API Server](open-webui.md)
- [Webhooks](webhooks.md)
+- [Webhooks](webhooks.md)
--- a/website/docs/user-guide/messaging/yuanbao.md
+++ b/website/docs/user-guide/messaging/yuanbao.md
@@ -0,0 +1,341 @@
+---
+sidebar_position: 16
+title: "Yuanbao"
+description: "Connect Hermes Agent to the Yuanbao enterprise messaging platform via WebSocket gateway"
+---
+
+# Yuanbao
+
+Connect Hermes to [Yuanbao](https://yuanbao.tencent.com/), Tencent's enterprise messaging platform. The adapter uses a WebSocket gateway for real-time message delivery and supports both direct (C2C) and group conversations.
+
+:::info
+Yuanbao is an enterprise messaging platform primarily used within Tencent and enterprise environments. It uses WebSocket for real-time communication, HMAC-based authentication, and supports rich media including images, files, and voice messages.
+:::
+
+## Prerequisites
+
+- A Yuanbao account with bot creation permissions
+- Yuanbao APP_ID and APP_SECRET (from platform admin)
+- Python packages: `websockets` and `httpx`
+- For media support: `aiofiles`
+
+Install the required dependencies:
+
+```bash
+pip install websockets httpx aiofiles
+```
+
+## Setup
+
+### 1. Create a Bot in Yuanbao
+
+1. Download the Yuanbao app from [https://yuanbao.tencent.com/](https://yuanbao.tencent.com/)
+2. In the app, go to **PAI → My Bot** and create a new bot
+3. After the bot is created, copy the **APP_ID** and **APP_SECRET**
+
+### 2. Run the Setup Wizard
+
+The easiest way to configure Yuanbao is through the interactive setup:
+
+```bash
+hermes gateway setup
+```
+
+Select **Yuanbao** when prompted. The wizard will:
+
+1. Ask for your APP_ID
+2. Ask for your APP_SECRET
+3. Save the configuration automatically
+
+:::tip
+The WebSocket URL and API Domain have sensible defaults built in. You only need to provide APP_ID and APP_SECRET to get started.
+:::
+
+### 3. Configure Environment Variables
+
+After initial setup, verify these variables in `~/.hermes/.env`:
+
+```bash
+# Required
+YUANBAO_APP_ID=your-app-id
+YUANBAO_APP_SECRET=your-app-secret
+YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
+YUANBAO_API_DOMAIN=https://api.yuanbao.example.com
+
+# Optional: bot account ID (normally obtained automatically from sign-token)
+# YUANBAO_BOT_ID=your-bot-id
+
+# Optional: internal routing environment (e.g. test/staging/production)
+# YUANBAO_ROUTE_ENV=production
+
+# Optional: home channel for cron/notifications (format: direct:<account> or group:<group_code>)
+YUANBAO_HOME_CHANNEL=direct:bot_account_id
+YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"
+
+# Optional: restrict access (legacy, see Access Control below for fine-grained policies)
+YUANBAO_ALLOWED_USERS=user_account_1,user_account_2
+```
+
+### 4. Start the Gateway
+
+```bash
+hermes gateway
+```
+
+The adapter will connect to the Yuanbao WebSocket gateway, authenticate using HMAC signatures, and begin processing messages.
+
+## Features
+
+- **WebSocket gateway** — real-time bidirectional communication
+- **HMAC authentication** — secure request signing with APP_ID/APP_SECRET
+- **C2C messaging** — direct user-to-bot conversations
+- **Group messaging** — conversations in group chats
+- **Media support** — images, files, and voice messages via COS (Cloud Object Storage)
+- **Markdown formatting** — messages are automatically chunked for Yuanbao's size limits
+- **Message deduplication** — prevents duplicate processing of the same message
+- **Heartbeat/keep-alive** — maintains WebSocket connection stability
+- **Typing indicators** — shows "typing…" status while the agent processes
+- **Automatic reconnection** — handles WebSocket disconnections with exponential backoff
+- **Group information queries** — retrieve group details and member lists
+- **Sticker/Emoji support** — send TIMFaceElem stickers and emoji in conversations
+- **Auto-sethome** — first user to message the bot is automatically set as the home channel owner
+- **Slow-response notification** — sends a waiting message when the agent takes longer than expected
+
+## Configuration Options
+
+### Chat ID Formats
+
+Yuanbao uses prefixed identifiers depending on conversation type:
+
+| Chat Type | Format | Example |
+|-----------|--------|---------|
+| Direct message (C2C) | `direct:<account>` | `direct:user123` |
+| Group message | `group:<group_code>` | `group:grp456` |
+
+### Media Uploads
+
+The Yuanbao adapter automatically handles media uploads via COS (Tencent Cloud Object Storage):
+
+- **Images**: Supports JPEG, PNG, GIF, WebP
+- **Files**: Supports all common document types
+- **Voice**: Supports WAV, MP3, OGG
+
+Media URLs are automatically validated and downloaded before upload to prevent SSRF attacks.
+
+## Home Channel
+
+Use the `/sethome` command in any Yuanbao chat (DM or group) to designate it as the **home channel**. Scheduled tasks (cron jobs) deliver their results to this channel.
+
+:::tip Auto-sethome
+If no home channel is configured, the first user to message the bot will be automatically set as the home channel owner. If the current home channel is a group chat, the first DM will upgrade it to a direct channel.
+:::
+
+You can also set it manually in `~/.hermes/.env`:
+
+```bash
+YUANBAO_HOME_CHANNEL=direct:user_account_id
+# or for a group:
+# YUANBAO_HOME_CHANNEL=group:group_code
+YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"
+```
+
+### Example: Set Home Channel
+
+1. Start a conversation with the bot in Yuanbao
+2. Send the command: `/sethome`
+3. The bot responds: "Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location."
+4. Future cron jobs and notifications will be sent to this channel
+
+### Example: Cron Job Delivery
+
+Create a cron job:
+
+```bash
+/cron "0 9 * * *" Check server status
+```
+
+The scheduled output will be delivered to your Yuanbao home channel every day at 9 AM.
+
+## Usage Tips
+
+### Starting a Conversation
+
+Send any message to the bot in Yuanbao:
+
+```
+hello
+```
+
+The bot responds in the same conversation thread.
+
+### Available Commands
+
+All standard Hermes commands work on Yuanbao:
+
+| Command | Description |
+|---------|-------------|
+| `/new` | Start a fresh conversation |
+| `/model [provider:model]` | Show or change the model |
+| `/sethome` | Set this chat as the home channel |
+| `/status` | Show session info |
+| `/help` | Show available commands |
+
+### Sending Files
+
+To send a file to the bot, simply attach it directly in the Yuanbao chat. The bot will automatically download and process the file attachment.
+
+You can also include a message with the attachment:
+
+```
+Please analyze this document
+```
+
+### Receiving Files
+
+When you ask the bot to create or export a file, it sends the file directly to your Yuanbao chat.
+
+## Troubleshooting
+
+### Bot is online but not responding to messages
+
+**Cause**: Authentication failed during WebSocket handshake.
+
+**Fix**:
+1. Verify APP_ID and APP_SECRET are correct
+2. Check that the WebSocket URL is accessible
+3. Ensure the bot account has proper permissions
+4. Review gateway logs: `tail -f ~/.hermes/logs/gateway.log`
+
+### "Connection refused" error
+
+**Cause**: WebSocket URL is unreachable or incorrect.
+
+**Fix**:
+1. Verify the WebSocket URL format (should start with `wss://`)
+2. Check network connectivity to the Yuanbao API domain
+3. Confirm firewall allows WebSocket connections
+4. Test URL with: `curl -I https://[YUANBAO_API_DOMAIN]`
+
+### Media uploads fail
+
+**Cause**: COS credentials are invalid or media server is unreachable.
+
+**Fix**:
+1. Verify API_DOMAIN is correct
+2. Check that media upload permissions are enabled for your bot
+3. Ensure the media file is accessible and not corrupted
+4. Check COS bucket configuration with platform admin
+
+### Messages not delivered to home channel
+
+**Cause**: Home channel ID format is incorrect or cron job hasn't triggered.
+
+**Fix**:
+1. Verify YUANBAO_HOME_CHANNEL is in correct format
+2. Test with `/sethome` command to auto-detect correct format
+3. Check cron job schedule with `/status`
+4. Verify bot has send permissions in the target chat
+
+### Frequent disconnections
+
+**Cause**: WebSocket connection is unstable or network is unreliable.
+
+**Fix**:
+1. Check gateway logs for error patterns
+2. Increase heartbeat timeout in connection settings
+3. Ensure stable network connection to Yuanbao API
+4. Consider enabling verbose logging: `HERMES_LOG_LEVEL=debug`
+
+## Access Control
+
+Yuanbao supports fine-grained access control for both DM and group conversations:
+
+```bash
+# DM policy: open (default) | allowlist | disabled
+YUANBAO_DM_POLICY=open
+# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
+YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2
+
+# Group policy: open (default) | allowlist | disabled
+YUANBAO_GROUP_POLICY=open
+# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
+YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2
+```
+
+These can also be set in `config.yaml`:
+
+```yaml
+platforms:
+  yuanbao:
+    extra:
+      dm_policy: allowlist
+      dm_allow_from: "user1,user2"
+      group_policy: open
+      group_allow_from: ""
+```
+
+## Advanced Configuration
+
+### Message Chunking
+
+Yuanbao has a maximum message size. Hermes automatically chunks large responses with Markdown-aware splitting (respects code fences, tables, and paragraph boundaries).
+
+### Connection Parameters
+
+The following connection parameters are built into the adapter with sensible defaults:
+
+| Parameter | Default Value | Description |
+|-----------|---------------|-------------|
+| WebSocket connect timeout | 15 seconds | Time to wait for WS handshake |
+| Heartbeat interval | 30 seconds | Ping frequency to keep connection alive |
+| Max reconnect attempts | 100 | Maximum number of reconnection tries |
+| Reconnect backoff | 1s → 60s (exponential) | Wait time between reconnect attempts |
+| Reply heartbeat interval | 2 seconds | RUNNING status send frequency |
+| Send timeout | 30 seconds | Timeout for outbound WS messages |
+
+:::note
+These values are currently not configurable via environment variables. They are optimized for typical Yuanbao deployments.
+:::
+
+### Verbose Logging
+
+Enable debug logging to troubleshoot connection issues:
+
+```bash
+HERMES_LOG_LEVEL=debug hermes gateway
+```
+
+## Integration with Other Features
+
+### Cron Jobs
+
+Schedule tasks that run on Yuanbao:
+
+```
+/cron "0 */4 * * *" Report system health
+```
+
+Results are delivered to your home channel.
+
+### Background Tasks
+
+Run long operations without blocking the conversation:
+
+```
+/background Analyze all files in the archive
+```
+
+### Cross-Platform Messages
+
+Send a message from CLI to Yuanbao:
+
+```bash
+hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"
+```
+
+## Related Documentation
+
+- [Messaging Gateway Overview](./index.md)
+- [Slash Commands Reference](/docs/reference/slash-commands.md)
+- [Cron Jobs](/docs/user-guide/features/cron-jobs.md)
+- [Background Tasks](/docs/guides/tips.md#background-tasks)