<!-- Source: https://hermesbible.com/docs/user-guide/messaging/yuanbao -->

章節：訊息平台 · URL: https://hermesbible.com/docs/user-guide/messaging/yuanbao

將 Hermes 連接到 Yuanbao，Tencent 的企業訊息平台。此適配器使用 WebSocket 閘道器進行即時訊息傳遞，並支援直接（C2C）和群組對話。

INFO

Yuanbao 是一個企業訊息平台，主要用於 Tencent 和企業環境中。它使用 WebSocket 進行即時通訊、基於 HMAC 的認證，並支援豐富的媒體類型，包括圖片、檔案和語音訊息。

先決條件

• 具備機器人建立權限的 Yuanbao 帳戶
• Yuanbao APP_ID 和 APP_SECRET（來自平台管理員）
• Python 套件：websockets 和 httpx
• 用於媒體支援：aiofiles

安裝所需的依賴項：

pip install websockets httpx aiofiles

設定

1. 在 Yuanbao 中建立機器人

1. 從 https://yuanbao.tencent.com/ 下載 Yuanbao 應用程式
2. 在應用程式中，前往 PAI → 我的機器人 並建立新機器人
3. 機器人建立後，複製 APP_ID 和 APP_SECRET

2. 執行設定精靈

設定 Yuanbao 最簡單的方式是透過互動式設定：

hermes gateway setup

在提示時選擇 Yuanbao。精靈將會：

1. 詢問您的 APP_ID
2. 詢問您的 APP_SECRET
3. 自動儲存設定

TIP

WebSocket URL 和 API Domain 已內建合理的預設值。您只需提供 APP_ID 和 APP_SECRET 即可開始使用。

3. 設定環境變數

初始設定後，在 ~/.hermes/.env 中驗證這些變數：

# 必要
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

# 選擇性：機器人帳戶 ID（通常從 sign-token 自動取得）
# YUANBAO_BOT_ID=your-bot-id

# 選擇性：內部路由環境（例如 test/staging/production）
# YUANBAO_ROUTE_ENV=production

# 選擇性：用於 cron/通知的主頻道（格式：direct:<account> 或 group:<group_code>）
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# 選擇性：限制存取（舊版，請參閱下方「存取控制」以取得更精細的策略）
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 斷線
• 群組資訊查詢 — 取得群組詳細資訊和成員列表
• 貼圖/表情符號支援 — 在對話中傳送 TIMFaceElem 貼圖和表情符號
• 自動設定主頻道 — 第一個傳訊息給機器人的用戶會自動設定為主頻道擁有者
• 慢回應通知 — 當機器人處理時間超過預期時傳送等待訊息

設定選項

聊天 ID 格式

Yuanbao 根據對話類型使用帶有前綴的識別碼：

媒體上傳

Yuanbao 適配器透過 COS（Tencent 雲端物件儲存）自動處理媒體上傳：

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

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

主頻道

在任何 Yuanbao 聊天（私訊或群組）中使用 /sethome 命令將其指定為主頻道。排程任務（cron 作業）會將結果傳送到此頻道。

TIP — 自動設定主頻道

如果未設定主頻道，第一個傳訊息給機器人的用戶將自動設定為主頻道擁有者。如果目前的主頻道是群組聊天，第一個私訊將升級為直接頻道。

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

YUANBAO_HOME_CHANNEL=direct:user_account_id
# 或者對於群組：
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

範例：設定主頻道

1. 在 Yuanbao 中與機器人開始對話
2. 傳送命令：/sethome
3. 機器人回應：「主頻道已設定為 [chat_name]，ID 為 [chat_id]。Cron 作業將傳送到此位置。」
4. 未來的 cron 作業和通知將傳送到此頻道

範例：Cron 作業傳遞

建立 cron 作業：

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

排程輸出將每天早上 9 點傳送到您的 Yuanbao 主頻道。

使用提示

開始對話

在 Yuanbao 中傳送任何訊息給機器人：

hello

機器人會在相同的對話執行緒中回應。

可用命令

所有標準 Hermes 命令都適用於 Yuanbao：

傳送檔案

要將檔案傳給機器人，只需在 Yuanbao 聊天中直接附加檔案。機器人會自動下載和處理檔案附件。

您也可以在附件中包含訊息：

Please analyze this document

接收檔案

當您要求機器人建立或匯出檔案時，它會將檔案直接傳送到您的 Yuanbao 聊天。

疑難排解

機器人在線上但沒有回應訊息

原因：在 WebSocket 握手期間認證失敗。

修正：

1. 驗證 APP_ID 和 APP_SECRET 是否正確
2. 檢查 WebSocket URL 是否可存取
3. 確保機器人帳戶具有適當權限
4. 檢視閘道器日誌：tail -f ~/.hermes/logs/gateway.log

「Connection refused」錯誤

原因：WebSocket URL 無法存取或不正確。

修正：

1. 驗證 WebSocket URL 格式（應以 wss:// 開頭）
2. 檢查與 Yuanbao API 網域的網路連線
3. 確認防火牆允許 WebSocket 連線
4. 使用以下命令測試 URL：curl -I https://[YUANBAO_API_DOMAIN]

媒體上傳失敗

原因：COS 憑證無效或媒體伺服器無法存取。

修正：

1. 驗證 API_DOMAIN 是否正確
2. 檢查您的機器人是否啟用了媒體上傳權限
3. 確保媒體檔案可存取且未損壞
4. 與平台管理員確認 COS 桶設定

訊息未傳送到主頻道

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

修正：

1. 驗證 YUANBAO_HOME_CHANNEL 格式是否正確
2. 使用 /sethome 命令測試以自動偵測正確格式
3. 使用 /status 檢查 cron 作業排程
4. 確認機器人在目標聊天中具有傳送權限

頻繁斷線

原因：WebSocket 連線不穩定或網路不可靠。

修正：

1. 檢查閘道器日誌以找出錯誤模式
2. 在連線設定中增加心跳逾時時間
3. 確保與 Yuanbao API 的穩定網路連線
4. 考慮啟用詳細日誌記錄：HERMES_LOG_LEVEL=debug

存取控制

Yuanbao 支援對私訊和群組對話進行精細的存取控制：

# 私訊策略：open（預設）| allowlist | disabled
YUANBAO_DM_POLICY=open
# 允許私訊機器人的用戶 ID 以逗號分隔（僅在 DM_POLICY=allowlist 時使用）
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# 群組策略：open（預設）| allowlist | disabled
YUANBAO_GROUP_POLICY=open
# 允許的群組代碼以逗號分隔（僅在 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: ""

進階設定

訊息分塊

Yuanbao 有最大訊息大小限制。Hermes 會自動將大型回應分塊，並使用 Markdown 感知的分割（尊重代碼圍欄、表格和段落邊界）。

連線參數

以下連線參數已內建於適配器中，並具有合理的預設值：

NOTE

這些值目前無法透過環境變數進行設定。它們針對典型的 Yuanbao 部署進行了最佳化。

詳細日誌記錄

啟用除錯日誌以疑難排解連線問題：

HERMES_LOG_LEVEL=debug hermes gateway

與其他功能整合

Cron 作業

排程在 Yuanbao 上執行的任務：

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

結果將傳送到您的主頻道。

背景任務

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

/background Analyze all files in the archive

跨平台訊息

從 CLI 傳送訊息到 Yuanbao：

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

相關文件

• 訊息閘道器概覽
• 斜線命令參考
• Cron 作業
• 背景會話

---

---

Bitwarden Secrets Manager