yuanbao

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: AGPL-3.0 Imports: 26 Imported by: 0

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

View Source
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 New

func New() *Adapter

func (*Adapter) Category

func (a *Adapter) Category() plugin.Category

func (*Adapter) GetCategory

func (a *Adapter) GetCategory() plugin.Category

func (*Adapter) GetID

func (a *Adapter) GetID() string

func (*Adapter) GetName

func (a *Adapter) GetName() string

func (*Adapter) ID

func (a *Adapter) ID() string

func (*Adapter) Name

func (a *Adapter) Name() string

func (*Adapter) OnMessage

func (a *Adapter) OnMessage(callback func(plugin.IncomingMessage))

func (*Adapter) Platform

func (a *Adapter) Platform() plugin.PlatformProvider

func (*Adapter) Send

func (a *Adapter) Send(ctx context.Context, channelID string, text string) error

Send 发送纯文本。

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 封装。

func (*Adapter) Start

func (a *Adapter) Start(ctx context.Context) error

Start 校验配置并启动后台连接循环(sign-token → WS → AUTH_BIND → 心跳 → 收发),立即返回。断线后按指数退避重连,ctx 取消时干净退出。

func (*Adapter) Stop

func (a *Adapter) Stop() error

Stop 取消连接循环并等待退出。

func (*Adapter) Validate

func (a *Adapter) Validate() error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址