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 作业​

后台任务​

跨平台消息​

相关文档​