@zhin.js/adapter-onebot11

Zhin.js OneBot v11 协议适配器，通过 WebSocket 连接各种支持 OneBot 协议的 QQ 机器人实现（如 go-cqhttp、Shamrock、LagrangeGo 等）。

功能特性

- 🔌 完整 OneBot v11 协议兼容
- 🌐 WebSocket 客户端和服务器模式
- 🔐 Access Token 认证支持
- 🔄 自动重连机制
- 💓 心跳检测
- 📨 群聊和私聊消息处理
- 🛠️ 完整的 API 调用支持
- 📝 消息段（Message Segment）完整支持

安装

``bash
pnpm add @zhin.js/adapter-onebot11 ws
`

配置

$3

`typescript
// zhin.config.ts
import { defineConfig } from 'zhin.js'

export default defineConfig({
bots: [
{
context: 'onebot11',
type: 'ws', // WebSocket 客户端
name: 'my-bot',
url: 'ws://localhost:8080', // OneBot 服务地址
access_token: process.env.ONEBOT_TOKEN, // 访问令牌（可选）
reconnect_interval: 5000, // 重连间隔（毫秒）
heartbeat_interval: 30000 // 心跳间隔（毫秒）
}
],
plugins: [
'adapter-onebot11'
]
})
`

$3

`typescript
export default defineConfig({
bots: [
{
context: 'onebot11.wss', // WebSocket 服务器
type: 'ws_reverse',
name: 'my-bot',
path: '/onebot/ws', // WebSocket 路径
access_token: process.env.ONEBOT_TOKEN, // 访问令牌（可选）
heartbeat_interval: 30000
}
],
plugins: [
'http', // 需要 HTTP 服务
'adapter-onebot11'
]
})
`

支持的 OneBot 实现

$3

| 实现 | 协议支持 | 稳定性 | 推荐度 |
|------|---------|--------|--------|
| go-cqhttp | ✅ 完整 | ⭐⭐⭐⭐⭐ | 高 |
| LagrangeGo | ✅ 完整 | ⭐⭐⭐⭐ | 高 |
| Shamrock | ✅ 完整 | ⭐⭐⭐⭐ | 中 |
| NapCat | ✅ 完整 | ⭐⭐⭐⭐ | 中 |

$3

#### go-cqhttp

`yaml


config.yml


servers:
- ws:
host: 0.0.0.0
port: 8080
access-token: "your_token_here"
`

#### Shamrock

在 Shamrock 设置中：
1. 启用 WebSocket 服务
2. 设置端口（默认 5800）
3. 配置 Access Token（可选）

使用示例

$3

`typescript
import { addCommand, MessageCommand } from 'zhin.js'

addCommand(new MessageCommand('hello ')
.action(async (message, result) => {
return 你好，${result.params.name}！
})
)
`

$3

`typescript
import { onGroupMessage } from 'zhin.js'

onGroupMessage(async (message) => {
console.log(群 ${message.$channel.id} 收到消息)
await message.$reply('收到了！')
})
`

$3

`typescript
import { onPrivateMessage } from 'zhin.js'

onPrivateMessage(async (message) => {
await message.$reply('你好！')
})
`

$3

`typescript
addCommand(new MessageCommand('pic ')
.action(async (message, result) => {
return [
{ type: 'image', data: { file: result.params.url } }
]
})
)
`

$3

`typescript
addCommand(new MessageCommand('cq')
.action(async (message) => {
return [
{ type: 'face', data: { id: '123' } },
{ type: 'text', data: { text: '表情' } }
]
})
)
`

消息类型支持

$3

- ✅ 文本消息（text）
- ✅ 图片消息（image）
- ✅ 语音消息（record）
- ✅ 视频消息（video）
- ✅ @ 提及（at）
- ✅ 表情（face）
- ✅ 引用回复（reply）
- ✅ 戳一戳（poke）
- ✅ 分享（share）
- ✅ 位置（location）
- ✅ 音乐分享（music）
- ✅ JSON 卡片（json）
- ✅ XML 卡片（xml）

$3

- ✅ 文本消息
- ✅ 图片消息（支持 URL、Base64、本地文件）
- ✅ 语音消息
- ✅ 视频消息
- ✅ @ 提及
- ✅ 表情
- ✅ 引用回复
- ✅ 戳一戳
- ✅ 分享卡片
- ✅ 音乐分享
- ✅ JSON/XML 卡片

API 方法

$3

`typescript
const bot = app.adapters.get('onebot11')?.bots.get('my-bot')

// 发送群消息
await bot.callApi('send_group_msg', {
group_id: 123456,
message: '消息内容'
})

// 发送私聊消息
await bot.callApi('send_private_msg', {
user_id: 123456,
message: '消息内容'
})

// 撤回消息
await bot.callApi('delete_msg', {
message_id: 123456
})
`

$3

`typescript
// 获取登录信息
const loginInfo = await bot.callApi('get_login_info')

// 获取用户信息
const userInfo = await bot.callApi('get_stranger_info', {
user_id: 123456
})

// 获取群信息
const groupInfo = await bot.callApi('get_group_info', {
group_id: 123456
})

// 获取群成员列表
const memberList = await bot.callApi('get_group_member_list', {
group_id: 123456
})
`

$3

`typescript
// 踢出群成员
await bot.callApi('set_group_kick', {
group_id: 123456,
user_id: 654321
})

// 禁言群成员
await bot.callApi('set_group_ban', {
group_id: 123456,
user_id: 654321,
duration: 600 // 秒
})

// 设置群名片
await bot.callApi('set_group_card', {
group_id: 123456,
user_id: 654321,
card: '新名片'
})
`

连接模式对比

$3

优点：
- ✅ 配置简单
- ✅ 主动连接，无需开放端口
- ✅ 适合本地开发

缺点：
- ❌ 需要 OneBot 实现提供 WebSocket 服务

$3

优点：
- ✅ OneBot 实现主动连接
- ✅ 支持多个客户端连接
- ✅ 适合生产环境

缺点：
- ❌ 需要开放端口或使用内网穿透
- ❌ 配置相对复杂

消息 ID 格式

OneBot11 适配器的消息 ID 格式：{message_id}

撤回消息时直接使用数字 ID。

注意事项

$3

建议配置 Access Token 增强安全性：
`typescript
{
access_token: process.env.ONEBOT_TOKEN
}
`

OneBot 实现需要配置相同的 Token。

$3

适配器会自动重连，可配置重连间隔：
`typescript
{
reconnect_interval: 5000 // 5秒后重连
}
`

$3

心跳机制确保连接活跃：
`typescript
{
heartbeat_interval: 30000 // 30秒发送一次心跳
}
`

$3

API 调用默认 30 秒超时，可在代码中调整。

常见问题

$3

A: 检查：
1. OneBot 服务是否启动
2. WebSocket 地址是否正确
3. Access Token 是否匹配
4. 防火墙是否阻止连接

$3

A: 可能原因：
1. 未登录或登录失败
2. 被风控限制
3. 群/好友不存在
4. 消息格式错误

$3

A: 确认：
1. HTTP 服务已启动
2. WebSocket 路径配置正确
3. OneBot 配置的反向 WS 地址正确
4. 端口已开放

$3

A: OneBot11 适配器自动处理 CQ 码转换，使用消息段格式即可：
`typescript
[
{ type: 'text', data: { text: '文本' } },
{ type: 'image', data: { file: 'url' } }
]
`

相关链接

- OneBot 标准
- go-cqhttp
- LagrangeGo
- Shamrock
- Zhin.js 官方文档

依赖项

- ws - WebSocket 客户端/服务器库
- zhin.js - Zhin 核心框架

开发

`bash
pnpm build # 构建
pnpm clean # 清理构建文件
``

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！