Documentation
¶
Overview ¶
proto.go — 元宝 WebSocket 协议编解码。
协议对齐 参考实现-agent gateway/platforms/yuanbao_proto.py(手写 protobuf wire-format,encoding/binary 级别实现,不引入第三方 protobuf 库)。
每个 WebSocket 帧 = 一条 ConnMsg protobuf(标准 protobuf;magic+len 二进制 格式只用于 quic/tcp):
ConnMsg { Head head=1; bytes data=2 }
Head { uint32 cmd_type=1; string cmd=2; uint32 seq_no=3; string msg_id=4;
string module=5; bool need_ack=6; int32 status=10 }
data 为业务 payload(InboundMessagePush / SendC2CMessageReq / SendGroupMessageReq / ...,服务名前缀见 bizPkg 常量)。
sign.go — sign-token 鉴权(对齐 参考实现-agent yuanbao.py SignManager)。
POST {domain}/api/v5/robotLogic/sign-token,payload {app_key, nonce, timestamp, signature},其中 signature = HMAC-SHA256( nonce+timestamp+app_key+app_secret, key=app_secret) hexdigest; timestamp 为北京时区 ISO-8601(无毫秒)。响应 {code, data:{token, bot_id, source, duration, product}},token 缓存至过期(提前 60s 视为过期)。
ws.go — WebSocket 传输层(gobwas/ws)。
真实协议为 WebSocket 长连接 wss://bot-wss.yuanbao.tencent.com/wss/connection, 每帧为一条二进制 ConnMsg protobuf(见 proto.go)。
Package yuanbao implements a Tencent Yuanbao (腾讯元宝) platform adapter.
协议对齐 参考实现-agent gateway/platforms/yuanbao*.py(Python 参考实现):
- 鉴权:POST {domain}/api/v5/robotLogic/sign-token,payload {app_key, nonce, timestamp, signature},其中 signature = HMAC-SHA256(nonce+timestamp+app_key+app_secret, key=app_secret);响应 {token, bot_id, source, duration} 缓存至过期。 (对应 REST 侧请求头 X-ID/X-Token/X-Source 的三元组经 WS AUTH_BIND 帧下发。)
- 传输:WebSocket 长连接 wss://bot-wss.yuanbao.tencent.com/wss/connection, 每帧为一条手写 protobuf 的 ConnMsg(见 proto.go)。
- 连接握手:AUTH_BIND(biz_id=ybBot, uid=bot_id, source, token, device_info.instance_id)→ BIND_ACK;之后 30s ping/pong 心跳 (连续 2 次超时触发重连)、Push 帧 need_ack 时回 PushAck。
- 入站 InboundMessagePush(protobuf / JSON 双格式解码)→ OnMessage 回调; 出站 SendC2CMessageReq / SendGroupMessageReq(TIM 格式消息体, 文本用 TIMTextElem)。
- 断线重连指数退避(1s, 2s, 4s, … 上限 60s);ctx 取消干净退出。
环境变量(与 参考实现 配置的对应关系):
YUANBAO_APP_ID app_key(参考实现: app_id)——主配置
YUANBAO_APP_SECRET app_secret(参考实现: app_secret)——主配置
签名需要 app_key + app_secret 成对使用。
YUANBAO_API_KEY 旧配置名,保留兼容:未设置 YUANBAO_APP_ID 时视为
app_key。注意旧实现将其作为 REST bearer token
(POST {base}/bot/{botID}/messages + Bearer),该
web 端点约定已被证实与真实协议完全不符;sign-token
签名实际需要的是 app_key(参考实现 app_id),而非
bearer token。
YUANBAO_BOT_ID 可选;sign-token 返回的 bot_id 会覆盖/补齐
(参考实现: bot_id 可选,由 sign-token 返回)。
YUANBAO_WS_URL WS 网关地址,默认
wss://bot-wss.yuanbao.tencent.com/wss/connection
YUANBAO_API_DOMAIN sign-token API 域名,默认 https://bot.yuanbao.tencent.com
YUANBAO_ROUTE_ENV 可选路由环境(X-Route-Env 头 / AUTH_BIND env_name)
channelID 约定:群聊为 "group:<group_code>",单聊为对端用户 id(发送时也 接受 "direct:<account>" 前缀,对齐 参考实现 的 chat_id 路由)。入站回调中 UserID 与单聊 channelID 均为对端账号(from_account)。
Index ¶
- Constants
- type Adapter
- func (a *Adapter) Category() plugin.Category
- func (a *Adapter) GetCategory() plugin.Category
- func (a *Adapter) GetID() string
- func (a *Adapter) GetName() string
- func (a *Adapter) ID() string
- func (a *Adapter) Name() string
- func (a *Adapter) OnMessage(callback func(plugin.IncomingMessage))
- func (a *Adapter) Platform() plugin.PlatformProvider
- func (a *Adapter) Send(ctx context.Context, channelID string, text string) error
- func (a *Adapter) SendMessage(ctx context.Context, channelID string, msg plugin.OutgoingMessage) error
- func (a *Adapter) Start(ctx context.Context) error
- func (a *Adapter) Stop() error
- func (a *Adapter) Validate() error
Constants ¶
const (
PlatformName = "yuanbao"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter 是元宝平台适配器(WS 长连接模式)。
func (*Adapter) GetCategory ¶
func (*Adapter) OnMessage ¶
func (a *Adapter) OnMessage(callback func(plugin.IncomingMessage))
func (*Adapter) Platform ¶
func (a *Adapter) Platform() plugin.PlatformProvider
func (*Adapter) SendMessage ¶
func (a *Adapter) SendMessage(ctx context.Context, channelID string, msg plugin.OutgoingMessage) error
SendMessage 通过 WS 发送消息:channelID 为 "group:<code>"(群聊, SendGroupMessageReq)或用户 id / "direct:<account>"(C2C, SendC2CMessageReq)。文本以 TIMTextElem 封装。