Pi-Yuanbao

通过腾讯元宝官方 Bot API，将元宝作为聊天渠道远程控制 Pi Agent。

用手机上的元宝 App 给 Bot 发消息，Pi 自动接收并处理，响应实时回传到手机。

功能

• 使用元宝官方 WebSocket + Protobuf 协议，稳定可靠
• sign-token 自动获取和缓存刷新
• WebSocket 心跳 + Reply 心跳（处理中状态推送）
• 断线指数退避重连，自动刷新 token
• 每轮 Turn 实时推送到手机，不漏回复
• 图片、文件自动下载后转发给 Pi 处理
• 支持多用户同时与 Bot 对话
• 注册 send_to_yuanbao 工具 + /yuanbao 命令

安装

pi install npm:pi-yuanbao

配置

获取凭证

在腾讯元宝开放平台申请 Bot，获取 App Key 和 App Secret。

配置方式

支持三种配置方式，优先级从高到低：

1. CLI 标志

pi --yuanbao-app-id=YOUR_KEY --yuanbao-app-secret=YOUR_SECRET

2. 环境变量

export YUANBAO_APP_ID="your_app_key"
export YUANBAO_APP_SECRET="your_app_secret"

3. Pi settings.json（推荐）

在 .pi/settings.json（项目级）或 ~/.pi/agent/settings.json（全局）中添加：

{
  "yuanbao": {
    "appId": "your_app_key",
    "appSecret": "your_app_secret",
    "botId": "optional_bot_id",
    "wsUrl": "optional_ws_url",
    "apiDomain": "optional_api_domain",
    "routeEnv": "optional_route_env"
  }
}

字段名支持 camelCase（appId）和 snake_case（app_id）两种写法。项目级配置覆盖全局配置。

配置项说明

| 字段 | 环境变量 | CLI 标志 | 必需 | |------|----------|----------|------| | App Key | YUANBAO_APP_ID | --yuanbao-app-id | 是 | | App Secret | YUANBAO_APP_SECRET | --yuanbao-app-secret | 是 | | Bot ID | YUANBAO_BOT_ID | --yuanbao-bot-id | 否，自动获取 | | WebSocket 地址 | YUANBAO_WS_URL | --yuanbao-ws-url | 否 | | API 域名 | YUANBAO_API_DOMAIN | --yuanbao-api-domain | 否 | | 路由环境 | YUANBAO_ROUTE_ENV | --yuanbao-route-env | 否 |

启动

pi

Pi 启动时会自动加载 pi-yuanbao 扩展并连接元宝 Bot。在元宝 App 中给 Bot 发消息即可开始使用。

管理命令

在 Pi 中使用 /yuanbao 命令管理连接：

| 命令 | 说明 | |------|------| | /yuanbao start | 启动元宝 Bot 连接 | | /yuanbao stop | 断开连接 | | /yuanbao status | 查看连接状态 | | /yuanbao config | 查看当前配置 | | /yuanbao help | 显示帮助 |

架构

┌─────────────────────┐    WebSocket (Protobuf)    ┌──────────────────┐
│   腾讯元宝 Bot 网关  │ ◄────────────────────────► │  Pi Extension    │
│   bot-wss.yuanbao   │    AUTH_BIND / Heartbeat   │  (yuanbao-client)│
└─────────────────────┘                            └────────┬─────────┘
                                                            │
                                                            │ sendUserMessage()
                                                            │ on("turn_end")
                                                            ▼
                                                   ┌──────────────────┐
                                                   │  Pi Agent Core   │
                                                   │  (LLM + Tools)   │
                                                   └──────────────────┘

协议流程

1. 认证: sign-token API → WebSocket AUTH_BIND → BIND_ACK
2. 心跳: 每 30s 发送 ping，收到 pong 确认
3. 收消息: InboundMessagePush → 解码 (JSON/Protobuf 双格式) → 提取文本 → sendUserMessage()
4. 发消息: turn_end 事件 → 分块 → 编码 SendC2CMessageReq → WebSocket 发送
5. Reply 心跳: 处理中每 2s 发送 RUNNING 状态，完成后发送 FINISH

消息类型支持

| 消息类型 | 协议类型 | 状态 | |----------|----------|------| | 文本 | TIMTextElem | 支持 | | 图片 | TIMImageElem | 支持 | | 文件 | TIMFileElem | 支持 | | 表情 | TIMFaceElem | 支持 | | 语音 | TIMSoundElem | 支持 | | 自定义 | TIMCustomElem | 支持 |

协议实现

协议编解码参考 hermes-agent 的 Python 实现，纯 TypeScript 手写 Protobuf wire format，零第三方依赖。

项目结构

pi-yuanbao/
├── src/
│   ├── index.ts              # Pi 扩展主入口
│   ├── yuanbao-client.ts     # 元宝 WebSocket 客户端
│   ├── yuanbao-proto.ts      # Protobuf 协议编解码
│   ├── yuanbao-sign.ts       # Sign Token 管理器
│   └── types.ts              # 类型定义
├── package.json
└── README.md

开发

npm install
npm run typecheck
npm run test
pi -e ./src/index.ts --yuanbao-app-id=KEY --yuanbao-app-secret=SECRET

注意事项

1. App Secret 请妥善保管，不要提交到版本控制
2. sign-token 有有效期，扩展会自动刷新
3. 单条消息最大 4000 字符（元宝限制），长消息自动分块
4. 需要能访问 bot-wss.yuanbao.tencent.com 和 bot.yuanbao.tencent.com

License

MIT