Chuyển tới nội dung chính

Nguyên bảo

Kết nối Hermes với Yuanbao, nền tảng nhắn tin doanh nghiệp của Tencent. Bộ điều hợp sử dụng cổng WebSocket để gửi tin nhắn theo thời gian thực và hỗ trợ cả hội thoại trực tiếp (C2C) và nhóm.

:::thông tin Yuanbao là một nền tảng nhắn tin doanh nghiệp chủ yếu được sử dụng trong môi trường Tencent và doanh nghiệp. Nó sử dụng WebSocket để liên lạc theo thời gian thực, xác thực dựa trên HMAC và hỗ trợ đa phương tiện bao gồm hình ảnh, tệp và tin nhắn thoại. :::

Điều kiện tiên quyết​

  • Tài khoản Yuanbao có quyền tạo bot
  • Yuanbao APP_ID và APP_SECRET (từ quản trị viên nền tảng)
  • Các gói Python: websockets và httpx
  • Để hỗ trợ truyền thông: aiofiles

Cài đặt các phụ thuộc cần thiết:

pip install websockets httpx aiofiles

Cài đặt​

1. Tạo Bot trong Yuanbao​

  1. Tải xuống ứng dụng Yuanbao từ https://yuanbao.tencent.com/
  2. Trong ứng dụng, hãy truy cập PAI → My Bot và tạo bot mới
  3. Sau khi bot được tạo, hãy sao chép APP_ID và APP_SECRET

2. Chạy Trình hướng dẫn cài đặt​

Cách dễ nhất để định cấu hình Yuanbao là thông qua thiết lập tương tác:

hermes gateway setup

Chọn Yuanbao khi được nhắc. Trình hướng dẫn sẽ:

  1. Yêu cầu APP_ID của bạn
  2. Yêu cầu APP_SECRET của bạn
  3. Tự động lưu cấu hình

:::mẹo URL WebSocket và Miền API được tích hợp sẵn các giá trị mặc định hợp lý. Bạn chỉ cần cung cấp APP_ID và APP_SECRET để bắt đầu. :::

3. Cấu hình biến môi trường​

Sau khi thiết lập lần đầu, hãy xác minh các biến này trong ~/.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"

# Tùy chọn: hạn chế quyền truy cập (cũ, xem Kiểm soát quyền truy cập bên dưới để biết các chính sách chi tiết)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. Khởi động Gateway​

hermes gateway

Bộ điều hợp sẽ kết nối với cổng Yuanbao WebSocket, xác thực bằng chữ ký HMAC và bắt đầu xử lý tin nhắn.

Đặc trưng​

  • Cổng WebSocket — giao tiếp hai chiều theo thời gian thực
  • Xác thực HMAC — ký yêu cầu an toàn bằng APP_ID/APP_SECRET
  • Nhắn tin C2C — cuộc trò chuyện trực tiếp giữa người dùng với bot
  • Nhắn tin nhóm — cuộc trò chuyện trong cuộc trò chuyện nhóm
  • Hỗ trợ phương tiện — hình ảnh, tệp và tin nhắn thoại qua COS (Lưu trữ đối tượng đám mây)
  • Định dạng đánh dấu — tin nhắn được tự động chia nhỏ theo giới hạn kích thước của Yuanbao
  • Loại bỏ tin nhắn — ngăn chặn việc xử lý trùng lặp cùng một tin nhắn
  • Heartbeat/keep-alive — duy trì sự ổn định của kết nối WebSocket
  • Chỉ báo đang gõ — hiển thị trạng thái "đang gõ..." trong khi tác nhân xử lý
  • Tự động kết nối lại — xử lý việc ngắt kết nối WebSocket với độ trễ theo cấp số nhân
  • Truy vấn thông tin nhóm — truy xuất thông tin chi tiết về nhóm và danh sách thành viên
  • Hỗ trợ Nhãn dán/Biểu tượng cảm xúc — gửi nhãn dán và biểu tượng cảm xúc TIMFaceElem trong cuộc trò chuyện
  • Auto-sethome — người dùng đầu tiên nhắn tin cho bot sẽ tự động được đặt làm chủ sở hữu kênh chính
  • Thông báo phản hồi chậm — gửi tin nhắn chờ khi tổng đài viên mất nhiều thời gian hơn dự kiến

Tùy chọn cấu hình​

Định dạng ID trò chuyện​

Yuanbao sử dụng số nhận dạng tiền tố tùy thuộc vào loại cuộc hội thoại:

Chat TypeFormatExample
Direct message (C2C)direct:<account>direct:user123
Group messagegroup:<group_code>group:grp456

Tải lên phương tiện​

Bộ điều hợp Yuanbao tự động xử lý việc tải lên phương tiện thông qua COS (Bộ lưu trữ đối tượng đám mây của Tencent):

  • Hình ảnh: Hỗ trợ JPEG, PNG, GIF, WebP
  • Tệp: Hỗ trợ tất cả các loại tài liệu phổ biến
  • Giọng nói: Hỗ trợ WAV, MP3, OGG

URL phương tiện được tự động xác thực và tải xuống trước khi tải lên để ngăn chặn các cuộc tấn công SSRF.

Kênh chủ​

Sử dụng lệnh /sethome trong bất kỳ cuộc trò chuyện Yuanbao (DM hoặc nhóm) nào để chỉ định kênh đó là kênh chính. Các tác vụ đã lên lịch (cron jobs) phân phối kết quả của chúng tới kênh này.

Tự động đặt nhà

Nếu không có kênh chính nào được định cấu hình, người dùng đầu tiên nhắn tin cho bot sẽ tự động được đặt làm chủ sở hữu kênh chính. Nếu kênh trang chủ hiện tại là kênh trò chuyện nhóm thì DM đầu tiên sẽ nâng cấp kênh đó lên kênh trực tiếp.

Bạn cũng có thể đặt thủ công trong ~/.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"

Ví dụ: Đặt kênh Home​

  1. Bắt đầu cuộc trò chuyện với bot trong Yuanbao
  2. Gửi lệnh: /sethome
  3. Bot trả lời: "Kênh chủ được đặt thành [chat_name] với ID [chat_id]. Công việc định kỳ sẽ được gửi đến vị trí này."
  4. Các công việc định kỳ và thông báo trong tương lai sẽ được gửi đến kênh này

Ví dụ: Phân phối công việc định kỳ​

Tạo một công việc định kỳ:

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

Đầu ra theo lịch trình sẽ được gửi đến kênh nhà Yuanbao của bạn vào lúc 9 giờ sáng hàng ngày.

Mẹo sử dụng​

Bắt đầu cuộc trò chuyện​

Gửi bất kỳ tin nhắn nào tới bot trong Yuanbao:

hello

Bot phản hồi trong cùng một chuỗi hội thoại.

Các lệnh có sẵn​

Tất cả các lệnh Hermes tiêu chuẩn đều hoạt động trên Yuanbao:

CommandDescription
/newStart a fresh conversation
/model [provider:model]Show or change the model
/sethomeSet this chat as the home channel
/statusShow session info
/helpShow available commands

Gửi tập tin​

Để gửi tệp tới bot, chỉ cần đính kèm tệp trực tiếp vào cuộc trò chuyện Yuanbao. Bot sẽ tự động tải xuống và xử lý tệp đính kèm.

Bạn cũng có thể bao gồm một tin nhắn với tệp đính kèm:

Please analyze this document

Đang nhận tập tin​

Khi bạn yêu cầu bot tạo hoặc xuất tệp, nó sẽ gửi tệp trực tiếp đến cuộc trò chuyện Yuanbao của bạn.

Khắc phục sự cố​

Bot đang online nhưng không trả lời tin nhắn​

Lý do: Xác thực không thành công trong quá trình bắt tay WebSocket.

Khắc phục:

  1. Xác minh APP_ID và APP_SECRET là chính xác
  2. Kiểm tra xem URL WebSocket có thể truy cập được không
  3. Đảm bảo tài khoản bot có quyền thích hợp
  4. Xem lại nhật ký cổng: tail -f ~/.hermes/logs/gateway.log

Lỗi "Kết nối bị từ chối"​

Lý do: URL WebSocket không thể truy cập được hoặc không chính xác.

Khắc phục:

  1. Xác minh định dạng URL WebSocket (nên bắt đầu bằng wss://)
  2. Kiểm tra kết nối mạng với miền API Yuanbao
  3. Xác nhận tường lửa cho phép kết nối WebSocket
  4. Kiểm tra URL với: curl -I https://[YUANBAO_API_DOMAIN]

Tải lên phương tiện không thành công​

Lý do: Thông tin xác thực COS không hợp lệ hoặc máy chủ phương tiện không thể truy cập được.

Khắc phục:

  1. Xác minh API_DOMAIN là chính xác
  2. Kiểm tra xem quyền tải lên phương tiện đã được bật cho bot của bạn chưa
  3. Đảm bảo tệp phương tiện có thể truy cập được và không bị hỏng
  4. Kiểm tra cấu hình nhóm COS với quản trị viên nền tảng

Tin nhắn chưa được gửi tới kênh chủ​

Nguyên nhân: Định dạng ID kênh chính không chính xác hoặc công việc định kỳ chưa được kích hoạt.

Khắc phục:

  1. Xác minh YUANBAO_HOME_CHANNEL có đúng định dạng
  2. Kiểm tra bằng lệnh /sethome để tự động phát hiện định dạng đúng
  3. Kiểm tra lịch công việc định kỳ bằng /status
  4. Xác minh bot có quyền gửi trong cuộc trò chuyện mục tiêu

Ngắt kết nối thường xuyên​

Lý do: Kết nối WebSocket không ổn định hoặc mạng không đáng tin cậy.

Khắc phục:

  1. Kiểm tra nhật ký cổng để tìm các mẫu lỗi
  2. Tăng thời gian chờ của nhịp tim trong cài đặt kết nối
  3. Đảm bảo kết nối mạng ổn định với API Yuanbao
  4. Cân nhắc việc bật ghi nhật ký chi tiết: HERMES_LOG_LEVEL=debug

Kiểm soát truy cập​

Yuanbao hỗ trợ kiểm soát truy cập chi tiết cho cả cuộc trò chuyện trực tiếp và nhóm:

# 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

Những thứ này cũng có thể được đặt trong config.yaml:

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

Cấu hình nâng cao​

Phân đoạn tin nhắn​

Yuanbao có kích thước tin nhắn tối đa. Hermes tự động phân chia các phản hồi lớn bằng tính năng phân tách nhận biết Markdown (tôn trọng hàng rào mã, bảng và ranh giới đoạn văn).

Thông số kết nối​

Các tham số kết nối sau được tích hợp vào bộ chuyển đổi với các giá trị mặc định hợp lý:

ParameterDefault ValueDescription
WebSocket connect timeout15 secondsTime to wait for WS handshake
Heartbeat interval30 secondsPing frequency to keep connection alive
Max reconnect attempts100Maximum number of reconnection tries
Reconnect backoff1s → 60s (exponential)Wait time between reconnect attempts
Reply heartbeat interval2 secondsRUNNING status send frequency
Send timeout30 secondsTimeout for outbound WS messages

:::lưu ý Các giá trị này hiện không thể cấu hình được thông qua các biến môi trường. Chúng được tối ưu hóa cho việc triển khai Yuanbao điển hình. :::

Ghi nhật ký dài dòng​

Bật tính năng ghi nhật ký gỡ lỗi để khắc phục sự cố kết nối:

HERMES_LOG_LEVEL=debug hermes gateway

Tích hợp với các tính năng khác​

Công việc định kỳ​

Lên lịch các tác vụ chạy trên Yuanbao:

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

Kết quả được gửi đến kênh chủ của bạn.

Tác vụ nền​

Chạy các thao tác dài mà không chặn cuộc trò chuyện:

/background Analyze all files in the archive

Tin nhắn đa nền tảng​

Gửi tin nhắn từ CLI tới Yuanbao:

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

Tài liệu liên quan​