Yuanbao

將 Hermes 連接到 Yuanbao，這是騰訊的企業 messaging 平臺。該適配器使用 WebSocket 網關進行實時消息傳遞，並支持單聊（C2C）和群聊。

信息

Yuanbao 是一個主要供騰訊內部和企業環境使用的企業即時通訊平臺。它使用 WebSocket 進行實時通信，採用基於 HMAC 的身份驗證，並支持包括圖片、文件和語音消息在內的富媒體內容。

前提條件

擁有創建機器人權限的 Yuanbao 賬號
Yuanbao APP_ID 和 APP_SECRET（從平臺管理員處獲取）
Python 包：websockets 和 httpx
如需媒體支持：aiofiles

安裝所需的依賴項：

pip install websockets httpx aiofiles

設置

1. 在 Yuanbao 中創建機器人

從 https://yuanbao.tencent.com/ 下載 Yuanbao 應用
在應用中，前往 PAI → 我的機器人 並創建一個新機器人
機器人創建完成後，複製 APP_ID 和 APP_SECRET

2. 運行設置嚮導

配置 Yuanbao 最簡單的方法是通過交互式設置：

hermes gateway setup

在提示時選擇 Yuanbao。嚮導將執行以下操作：

詢問您的 APP_ID
詢問您的 APP_SECRET
自動保存配置

提示

WebSocket URL 和 API 域名已內置合理的默認值。您只需提供 APP_ID 和 APP_SECRET 即可開始使用。

3. 配置環境變量

初始設置後，請驗證 ~/.hermes/.env 中的以下變量：

# 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. 啟動網關

hermes gateway

適配器將連接到 Yuanbao WebSocket 網關，使用 HMAC 簽名進行身份驗證，並開始處理消息。

功能特性

WebSocket 網關 — 實時雙向通信
HMAC 身份驗證 — 使用 APP_ID/APP_SECRET 進行安全的請求籤名
單聊消息（C2C） — 用戶與機器人之間的直接對話
群聊消息 — 群組聊天中的對話
媒體支持 — 通過 COS（雲對象存儲）支持圖片、文件和語音消息
Markdown 格式化 — 消息會自動分塊以適應 Yuanbao 的大小限制
消息去重 — 防止重複處理同一條消息
心跳/保活 — 維持 WebSocket 連接的穩定性
輸入指示器 — 當代理處理時顯示“正在輸入…”狀態
自動重連 — 使用指數退避處理 WebSocket 斷開連接
群組信息查詢 — 獲取群組詳情和成員列表
表情/Emoji 支持 — 在對話中發送 TIMFaceElem 表情貼紙和 emoji
自動設置主頻道（Auto-sethome） — 第一個向機器人發送消息的用戶會自動被設為主頻道所有者
慢響應通知 — 當代理響應時間超過預期時，發送等待消息

配置選項

聊天 ID 格式

Yuanbao 根據對話類型使用前綴標識符：

聊天類型	格式	示例
單聊 (C2C)	`direct:<account>`	`direct:user123`
群聊	`group:<group_code>`	`group:grp456`

媒體上傳

Yuanbao 適配器通過 COS（騰訊雲對象存儲）自動處理媒體上傳：

圖片：支持 JPEG、PNG、GIF、WebP
文件：支持所有常見文檔類型
語音：支持 WAV、MP3、OGG

媒體 URL 在上傳前會自動驗證並下載，以防止 SSRF 攻擊。

主頻道 (Home Channel)

在任何 Yuanbao 聊天（單聊或群聊）中使用 /sethome 命令將其指定為 主頻道。定時任務（cron jobs）會將結果發送到此頻道。

自動設置主頻道

如果未配置主頻道，第一個向機器人發送消息的用戶將自動被設為主頻道所有者。如果當前主頻道是群聊，第一條單聊消息會將其升級為單聊頻道。

您也可以在 ~/.hermes/.env 中手動設置：

YUANBAO_HOME_CHANNEL=direct:user_account_id
# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

示例：設置主頻道

在 Yuanbao 中與機器人開始對話
發送命令：/sethome
機器人回覆：“主頻道已設置為 [chat_name]，ID 為 [chat_id]。定時任務將發送到此位置。”
未來的定時任務和通知將發送到此頻道

示例：定時任務交付

創建一個定時任務：

/cron "0 9 * * *" Check server status

計劃輸出的內容將每天上午 9 點發送到您的 Yuanbao 主頻道。

使用技巧

開始對話

在 Yuanbao 中向機器人發送任何消息：

hello

機器人將在同一對話線程中回覆。

可用命令

所有標準的 Hermes 命令均可在 Yuanbao 上使用：

命令	描述
`/new`	開始新的對話
`/model [provider:model]`	顯示或更改模型
`/sethome`	將此聊天設為主頻道
`/status`	顯示會話信息
`/help`	顯示可用命令

發送文件

要向機器人發送文件，只需在 Yuanbao 聊天中直接附加文件即可。機器人將自動下載並處理文件附件。

你也可以在附件中包含一條消息：

Please analyze this document

接收文件

當你要求機器人創建或導出文件時，它會將文件直接發送到你的元寶聊天中。

故障排除

機器人在線但無響應

原因：WebSocket 握手期間身份驗證失敗。

修復：

驗證 APP_ID 和 APP_SECRET 是否正確
檢查 WebSocket URL 是否可訪問
確保機器人賬戶具有適當的權限
查看網關日誌：tail -f ~/.hermes/logs/gateway.log

“Connection refused”（連接被拒絕）錯誤

原因：WebSocket URL 不可達或不正確。

修復：

驗證 WebSocket URL 格式（應以 wss:// 開頭）
檢查到元寶 API 域名的網絡連接
確認防火牆允許 WebSocket 連接
使用以下命令測試 URL：curl -I https://[YUANBAO_API_DOMAIN]

媒體上傳失敗

原因：COS 憑據無效或媒體服務器不可達。

修復：

驗證 API_DOMAIN 是否正確
檢查是否為你的機器人啟用了媒體上傳權限
確保媒體文件可訪問且未損壞
與平臺管理員檢查 COS 存儲桶配置

消息未送達主頁頻道

原因：主頁頻道 ID 格式不正確或 cron 作業未觸發。

修復：

驗證 YUANBAO_HOME_CHANNEL 是否為正確格式
使用 /sethome 命令測試以自動檢測正確格式
使用 /status 檢查 cron 作業計劃
驗證機器人在目標聊天中是否具有發送權限

頻繁斷開連接

原因：WebSocket 連接不穩定或網絡不可靠。

修復：

檢查網關日誌中的錯誤模式
在連接設置中增加心跳超時時間
確保到元寶 API 的網絡連接穩定
考慮啟用詳細日誌記錄：HERMES_LOG_LEVEL=debug

訪問控制

元寶支持對私聊（DM）和群聊進行細粒度的訪問控制：

# 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

這些也可以在 config.yaml 中設置：

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

高級配置

消息分塊

元寶有最大消息大小限制。Hermes 會自動對大型響應進行分塊，採用感知 Markdown 的分割方式（尊重代碼圍欄、表格和段落邊界）。

連接參數

以下連接參數已內置於適配器中，並設有合理的默認值：

參數	默認值	描述
WebSocket 連接超時	15 秒	等待 WS 握手的時間
心跳間隔	30 秒	保持連接活躍的 Ping 頻率
最大重連嘗試次數	100	最大重連嘗試次數
重連退避	1s → 60s（指數級）	重連嘗試之間的等待時間
回覆心跳間隔	2 秒	RUNNING 狀態發送頻率
發送超時	30 秒	出站 WS 消息的超時時間

備註

這些值目前無法通過環境變量進行配置。它們針對典型的元寶部署進行了優化。

詳細日誌記錄

啟用調試日誌以排查連接問題：

HERMES_LOG_LEVEL=debug hermes gateway

與其他功能集成

Cron 作業

計劃在元寶上運行的任務：

/cron "0 */4 * * *" Report system health

結果將交付到你的主頁頻道。

後臺任務

運行長時間操作而不阻塞對話：

/background Analyze all files in the archive

跨平臺消息

從 CLI 向元寶發送消息：

hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

前提條件​

設置​

1. 在 Yuanbao 中創建機器人​

2. 運行設置嚮導​

3. 配置環境變量​

4. 啟動網關​

功能特性​

配置選項​

聊天 ID 格式​

媒體上傳​

主頻道 (Home Channel)​

示例：設置主頻道​

示例：定時任務交付​

使用技巧​

開始對話​

可用命令​

發送文件​

接收文件​

故障排除​

機器人在線但無響應​

“Connection refused”（連接被拒絕）錯誤​

媒體上傳失敗​

消息未送達主頁頻道​

頻繁斷開連接​

訪問控制​

高級配置​

消息分塊​

連接參數​

詳細日誌記錄​

與其他功能集成​

Cron 作業​

後臺任務​

跨平臺消息​

相關文檔​