QQ Bot
Kết nối Hermes với QQ thông qua API Bot QQ chính thức (v2) — hỗ trợ tin nhắn riêng (C2C), đề cập nhóm (@), guild và tin nhắn trực tiếp kèm chuyển đổi giọng nói.
Tổng quan
Bộ điều hợp QQ Bot sử dụng API Bot QQ chính thức để:
- Nhận tin nhắn qua kết nối WebSocket liên tục đến QQ Gateway
- Gửi phản hồi văn bản và markdown qua REST API
Các loại tin nhắn được hỗ trợ
| Loại | Sự kiện | Ghi chú |
|---|---|---|
| Tin nhắn riêng (C2C) | C2C_MESSAGE_CREATE | Trò chuyện 1-1 với bot |
| Đề cập nhóm | GROUP_AT_MESSAGE_CREATE | @bot trong nhóm |
| Kênh Guild | AT_MESSAGE_CREATE | @bot trong kênh guild |
| DM Guild | DIRECT_MESSAGE_CREATE | DM qua guild |
Thiết lập
1. Tạo QQ Bot
- Truy cập QQ Bot Platform và tạo một bot mới
- Ghi lại App ID và App Secret của bạn
2. Cấu hình biến môi trường
Thêm vào ~/.hermes/.env:
QQ_APP_ID=your_app_id
QQ_CLIENT_SECRET=your_app_secret
3. Khởi động Hermes với QQ
hermes --messaging qq
Cấu hình
| Biến | Mô tả | Mặc định |
|---|---|---|
QQ_APP_ID | App ID của QQ Bot (bắt buộc) | — |
QQ_CLIENT_SECRET | App Secret của QQ Bot (bắt buộc) | — |
QQ_HOME_CHANNEL | OpenID cho gửi cron/thông báo | — |
QQ_HOME_CHANNEL_NAME | Tên hiển thị cho kênh chính | Home |
QQ_ALLOWED_USERS | Danh sách OpenID người dùng được phép DM, cách nhau bằng dấu phẩy | mở (tất cả người dùng) |
QQ_ALLOW_ALL_USERS | Đặt true để cho phép tất cả DM | false |
QQ_MARKDOWN_SUPPORT | Bật markdown QQ (msg_type 2) | true |
QQ_STT_API_KEY | API key cho nhà cung cấp chuyển giọng nói thành văn bản | — |
QQ_STT_BASE_URL | URL cơ sở cho nhà cung cấp STT | https://open.bigmodel.cn/api/coding/paas/v4 |
Phiên làm việc
Bộ điều hợp QQ sử dụng mô hình phiên theo loại tin nhắn:
- C2C: Mỗi người dùng nhận được phiên riêng
- Nhóm: Mỗi nhóm chia sẻ một phiên duy nhất
- Guild: Mỗi kênh nhận được phiên riêng
- DM Guild: Mỗi cặp DM nhận được phiên riêng
Chuyển đổi giọng nói
QQ Bot hỗ trợ tin nhắn giọng nói thông qua tích hợp STT (Speech-to-Text):
- Cấu hình
QQ_STT_API_KEYvàQQ_STT_BASE_URL(tùy chọn) - Khi người dùng gửi tin nhắn giọng nói, Hermes tự động chuyển đổi thành văn bản
- Văn bản đã chuyển đổi được xử lý như tin nhắn văn bản thông thường
Hạn chế đã biết
- API QQ Bot yêu cầu bot phải phản hồi trong vòng 5 giây hoặc sử dụng cơ chế callback
- Hỗ trợ markdown phụ thuộc vào phiên bản ứng dụng QQ của người dùng
- Tin nhắn đa phương tiện (hình ảnh, file) hiện có hỗ trợ hạn chế