@zhin.js/adapter-onebot11 1.0.97 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +654 -0
- package/README.md +58 -368
- package/adapters/onebot11.js +40 -0
- package/adapters/onebot11.ts +53 -0
- package/agent/PERMITS.md +14 -0
- package/{skills/onebot11/SKILL.md → agent/skills/onebot11.md} +4 -4
- package/agent/tools/set_title.ts +24 -0
- package/commands/endpoint/add/[id].js +3 -0
- package/commands/endpoint/add/[id].ts +3 -0
- package/commands/endpoint/list.js +3 -0
- package/commands/endpoint/list.ts +3 -0
- package/commands/endpoint/remove/[id].js +3 -0
- package/commands/endpoint/remove/[id].ts +3 -0
- package/lib/client.d.ts +20 -0
- package/lib/client.js +30 -0
- package/lib/content-port.d.ts +4 -0
- package/lib/content-port.js +63 -0
- package/lib/endpoint-management.d.ts +15 -0
- package/lib/endpoint-management.js +47 -0
- package/lib/index.d.ts +10 -16
- package/lib/index.js +7 -53
- package/lib/onebot11-endpoint-commands.d.ts +1 -0
- package/lib/onebot11-endpoint-commands.js +24 -0
- package/lib/onebot11-runtime-state.d.ts +1 -0
- package/lib/onebot11-runtime-state.js +6 -0
- package/lib/protocol.d.ts +160 -0
- package/lib/protocol.js +316 -0
- package/lib/side-event-dispatch.d.ts +7 -0
- package/lib/side-event-dispatch.js +36 -0
- package/lib/ws-endpoint.d.ts +22 -0
- package/lib/ws-endpoint.js +209 -0
- package/lib/ws-transport.d.ts +13 -0
- package/lib/ws-transport.js +71 -0
- package/lib/ws-types.d.ts +18 -0
- package/lib/ws-types.js +1 -0
- package/lib/wss-auth.d.ts +2 -0
- package/lib/wss-auth.js +16 -0
- package/lib/wss-endpoint.d.ts +25 -0
- package/lib/wss-endpoint.js +173 -0
- package/package.json +69 -22
- package/plugin.js +18 -0
- package/schema.json +97 -0
- package/src/client.ts +78 -0
- package/src/content-port.ts +66 -0
- package/src/endpoint-management.ts +72 -0
- package/src/index.ts +62 -65
- package/src/onebot11-endpoint-commands.ts +23 -0
- package/src/onebot11-runtime-state.ts +7 -0
- package/src/protocol.ts +459 -0
- package/src/side-event-dispatch.ts +48 -0
- package/src/ws-endpoint.ts +272 -0
- package/src/ws-transport.ts +100 -0
- package/src/ws-types.ts +21 -0
- package/src/wss-auth.ts +17 -0
- package/src/wss-endpoint.ts +228 -0
- package/lib/adapter.d.ts +0 -32
- package/lib/adapter.d.ts.map +0 -1
- package/lib/adapter.js +0 -92
- package/lib/adapter.js.map +0 -1
- package/lib/bot-ws-client.d.ts +0 -40
- package/lib/bot-ws-client.d.ts.map +0 -1
- package/lib/bot-ws-client.js +0 -395
- package/lib/bot-ws-client.js.map +0 -1
- package/lib/bot-ws-server.d.ts +0 -42
- package/lib/bot-ws-server.d.ts.map +0 -1
- package/lib/bot-ws-server.js +0 -344
- package/lib/bot-ws-server.js.map +0 -1
- package/lib/index.d.ts.map +0 -1
- package/lib/index.js.map +0 -1
- package/lib/onebot-get-msg.d.ts +0 -3
- package/lib/onebot-get-msg.d.ts.map +0 -1
- package/lib/onebot-get-msg.js +0 -27
- package/lib/onebot-get-msg.js.map +0 -1
- package/lib/types.d.ts +0 -54
- package/lib/types.d.ts.map +0 -1
- package/lib/types.js +0 -5
- package/lib/types.js.map +0 -1
- package/plugin.yml +0 -3
- package/src/adapter.ts +0 -104
- package/src/bot-ws-client.ts +0 -420
- package/src/bot-ws-server.ts +0 -382
- package/src/onebot-get-msg.ts +0 -33
- package/src/types.ts +0 -58
package/README.md
CHANGED
|
@@ -1,413 +1,103 @@
|
|
|
1
1
|
# @zhin.js/adapter-onebot11
|
|
2
2
|
|
|
3
|
-
Zhin.js OneBot
|
|
3
|
+
Zhin.js [OneBot 11](https://github.com/botuniverse/onebot-11) 适配器(Plugin Runtime)。生产路径为正向 WebSocket 客户端(`connection: ws`);亦支持反向 WS(`connection: wss`,经 `httpHostToken`)。
|
|
4
4
|
|
|
5
5
|
## 功能特性
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
- 🔄 自动重连机制
|
|
13
|
-
- 💓 心跳检测
|
|
14
|
-
- 📨 群聊和私聊消息处理
|
|
15
|
-
- 🛠️ 完整的 API 调用支持
|
|
16
|
-
- 📝 消息段(Message Segment)完整支持
|
|
7
|
+
- [OneBot 11 标准](https://github.com/botuniverse/onebot-11) 兼容(事件 + 动作)
|
|
8
|
+
- 约定式 `defineAdapter` / `definePlugin`(无需 `usePlugin`)
|
|
9
|
+
- **正向 WebSocket**(`connection: ws`):应用连 OneBot 实现的 WS 服务器
|
|
10
|
+
- `access_token` 鉴权(Bearer + query)
|
|
11
|
+
- 入站经 `Endpoint.emit(...)`;出站 `send({ conversation, payload })`
|
|
17
12
|
|
|
18
13
|
## 安装
|
|
19
14
|
|
|
20
15
|
```bash
|
|
21
|
-
pnpm add @zhin.js/adapter-onebot11
|
|
16
|
+
pnpm add @zhin.js/adapter-onebot11
|
|
22
17
|
```
|
|
23
18
|
|
|
24
|
-
|
|
19
|
+
## Plugin Runtime
|
|
25
20
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
| **OneBot 实现** | 已运行 go-cqhttp、Lagrange、Shamrock 等,并开启 WS 服务 |
|
|
31
|
-
| **正向 WS(`connection: ws`)** | 配置 OneBot 实现的 WS 地址;应用主动连接 |
|
|
32
|
-
| **反向 WS(`connection: wss`)** | 需 `@zhin.js/host-router`;OneBot 实现连到本 Bot 的 `path` |
|
|
33
|
-
| **access_token** | 可选;须与 OneBot 实现侧配置一致 |
|
|
34
|
-
|
|
35
|
-
必填字段见 `OneBot11BotConfig`:`context`、`name`、`connection`;`ws` 需 `url`,`wss` 需 `path`。
|
|
36
|
-
|
|
37
|
-
## 最小配置
|
|
38
|
-
|
|
39
|
-
正向 WebSocket(本地开发推荐):
|
|
21
|
+
- `@zhin.js/adapter` — 约定式 `adapters/onebot11.ts`(`defineAdapter`)
|
|
22
|
+
- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
|
|
23
|
+
- `zhin.js` — `plugin.ts`(`definePlugin`)
|
|
24
|
+
- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
|
|
40
25
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
26
|
+
每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v11` 的 `OneBotV11Client`。业务代码直接调用
|
|
27
|
+
`$client.call(action, params)` 和 Client 的公开平台能力;双工 WS 的 `echo` 响应由 Endpoint
|
|
28
|
+
先行分流,只有事件帧进入 Client 的 `ingest()` 和公开事件流。
|
|
44
29
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
connection: ws
|
|
48
|
-
name: my-bot
|
|
49
|
-
url: "ws://127.0.0.1:6700"
|
|
50
|
-
access_token: "${ONEBOT11_ACCESS_TOKEN}"
|
|
51
|
-
```
|
|
30
|
+
入站:`gateway.receive({ conversation, message, content, sender, metadata })`(`conversation.kind` 为 `private`/`group`,`id` 为 uid/gid)
|
|
31
|
+
出站:`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`(payload 已由 gateway/core 渲染;无 segment-mapper)
|
|
52
32
|
|
|
53
|
-
##
|
|
33
|
+
## 前置条件
|
|
54
34
|
|
|
55
|
-
|
|
35
|
+
1. 启动兼容 OneBot 11 的实现,并选定正向或反向 WebSocket。
|
|
36
|
+
2. 正向 WS 需 Zhin 可达实现端;反向 WS 需实现端可达 Zhin HTTP Host。
|
|
37
|
+
3. 两端配置相同的 `access_token`,生产环境不要开放无鉴权连接。
|
|
56
38
|
|
|
57
|
-
|
|
39
|
+
## 最小配置
|
|
58
40
|
|
|
59
41
|
```yaml
|
|
42
|
+
# zhin.config.yml(Plugin Runtime)
|
|
60
43
|
plugins:
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
bots:
|
|
64
|
-
- context: onebot11
|
|
44
|
+
onebot11:
|
|
65
45
|
connection: ws
|
|
66
|
-
name: my-bot
|
|
67
|
-
url: "ws://localhost:8080"
|
|
68
|
-
access_token: "${ONEBOT_TOKEN}"
|
|
69
46
|
reconnect_interval: 5000
|
|
70
47
|
heartbeat_interval: 30000
|
|
48
|
+
endpoints:
|
|
49
|
+
- name: ob11-bot
|
|
50
|
+
url: "ws://127.0.0.1:6700"
|
|
51
|
+
access_token: "${ONEBOT11_ACCESS_TOKEN}"
|
|
71
52
|
```
|
|
72
53
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
```yaml
|
|
76
|
-
plugins:
|
|
77
|
-
- "@zhin.js/host-router"
|
|
78
|
-
- "@zhin.js/adapter-onebot11"
|
|
79
|
-
|
|
80
|
-
bots:
|
|
81
|
-
- context: onebot11
|
|
82
|
-
connection: wss
|
|
83
|
-
name: my-bot
|
|
84
|
-
path: "/onebot/ws"
|
|
85
|
-
access_token: "${ONEBOT_TOKEN}"
|
|
86
|
-
heartbeat_interval: 30000
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
兼容旧配置:若使用 `type: 'ws'` / `type: 'ws_reverse'` 而未写 `connection`,适配器会自动映射为 `ws` / `wss`。
|
|
90
|
-
|
|
91
|
-
## 支持的 OneBot 实现
|
|
92
|
-
|
|
93
|
-
### 推荐实现
|
|
94
|
-
|
|
95
|
-
| 实现 | 协议支持 | 稳定性 | 推荐度 |
|
|
96
|
-
|------|---------|--------|--------|
|
|
97
|
-
| [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) | ✅ 完整 | ⭐⭐⭐⭐⭐ | 高 |
|
|
98
|
-
| [LagrangeGo](https://github.com/LagrangeDev/Lagrange.Core) | ✅ 完整 | ⭐⭐⭐⭐ | 高 |
|
|
99
|
-
| [Shamrock](https://github.com/whitechi73/OpenShamrock) | ✅ 完整 | ⭐⭐⭐⭐ | 中 |
|
|
100
|
-
| [NapCat](https://github.com/NapNeko/NapCatQQ) | ✅ 完整 | ⭐⭐⭐⭐ | 中 |
|
|
101
|
-
|
|
102
|
-
### 配置示例
|
|
103
|
-
|
|
104
|
-
#### go-cqhttp
|
|
105
|
-
|
|
106
|
-
```yaml
|
|
107
|
-
# config.yml
|
|
108
|
-
servers:
|
|
109
|
-
- ws:
|
|
110
|
-
host: 0.0.0.0
|
|
111
|
-
port: 8080
|
|
112
|
-
access-token: "your_token_here"
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
#### Shamrock
|
|
116
|
-
|
|
117
|
-
在 Shamrock 设置中:
|
|
118
|
-
1. 启用 WebSocket 服务
|
|
119
|
-
2. 设置端口(默认 5800)
|
|
120
|
-
3. 配置 Access Token(可选)
|
|
121
|
-
|
|
122
|
-
## 使用示例
|
|
123
|
-
|
|
124
|
-
### 基础消息处理
|
|
125
|
-
|
|
126
|
-
```typescript
|
|
127
|
-
import { addCommand, MessageCommand } from 'zhin.js'
|
|
128
|
-
|
|
129
|
-
addCommand(new MessageCommand('hello <name:text>')
|
|
130
|
-
.action(async (message, result) => {
|
|
131
|
-
return `你好,${result.params.name}!`
|
|
132
|
-
})
|
|
133
|
-
)
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
### 群聊消息
|
|
137
|
-
|
|
138
|
-
```typescript
|
|
139
|
-
import { onGroupMessage } from 'zhin.js'
|
|
140
|
-
|
|
141
|
-
onGroupMessage(async (message) => {
|
|
142
|
-
console.log(`群 ${message.$channel.id} 收到消息`)
|
|
143
|
-
await message.$reply('收到了!')
|
|
144
|
-
})
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
### 私聊消息
|
|
148
|
-
|
|
149
|
-
```typescript
|
|
150
|
-
import { onPrivateMessage } from 'zhin.js'
|
|
151
|
-
|
|
152
|
-
onPrivateMessage(async (message) => {
|
|
153
|
-
await message.$reply('你好!')
|
|
154
|
-
})
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
### 发送图片
|
|
158
|
-
|
|
159
|
-
```typescript
|
|
160
|
-
addCommand(new MessageCommand('pic <url:text>')
|
|
161
|
-
.action(async (message, result) => {
|
|
162
|
-
return [
|
|
163
|
-
{ type: 'image', data: { file: result.params.url } }
|
|
164
|
-
]
|
|
165
|
-
})
|
|
166
|
-
)
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
### 使用 CQ 码
|
|
170
|
-
|
|
171
|
-
```typescript
|
|
172
|
-
addCommand(new MessageCommand('cq')
|
|
173
|
-
.action(async (message) => {
|
|
174
|
-
return [
|
|
175
|
-
{ type: 'face', data: { id: '123' } },
|
|
176
|
-
{ type: 'text', data: { text: '表情' } }
|
|
177
|
-
]
|
|
178
|
-
})
|
|
179
|
-
)
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
## 消息类型支持
|
|
183
|
-
|
|
184
|
-
### 接收消息类型
|
|
185
|
-
|
|
186
|
-
- ✅ 文本消息(text)
|
|
187
|
-
- ✅ 图片消息(image)
|
|
188
|
-
- ✅ 语音消息(record)
|
|
189
|
-
- ✅ 视频消息(video)
|
|
190
|
-
- ✅ @ 提及(at)
|
|
191
|
-
- ✅ 表情(face)
|
|
192
|
-
- ✅ 引用回复(reply)
|
|
193
|
-
- ✅ 戳一戳(poke)
|
|
194
|
-
- ✅ 分享(share)
|
|
195
|
-
- ✅ 位置(location)
|
|
196
|
-
- ✅ 音乐分享(music)
|
|
197
|
-
- ✅ JSON 卡片(json)
|
|
198
|
-
- ✅ XML 卡片(xml)
|
|
199
|
-
|
|
200
|
-
### 发送消息类型
|
|
201
|
-
|
|
202
|
-
- ✅ 文本消息
|
|
203
|
-
- ✅ 图片消息(支持 URL、Base64、本地文件)
|
|
204
|
-
- ✅ 语音消息
|
|
205
|
-
- ✅ 视频消息
|
|
206
|
-
- ✅ @ 提及
|
|
207
|
-
- ✅ 表情
|
|
208
|
-
- ✅ 引用回复
|
|
209
|
-
- ✅ 戳一戳
|
|
210
|
-
- ✅ 分享卡片
|
|
211
|
-
- ✅ 音乐分享
|
|
212
|
-
- ✅ JSON/XML 卡片
|
|
213
|
-
|
|
214
|
-
## API 方法
|
|
215
|
-
|
|
216
|
-
### 消息相关
|
|
217
|
-
|
|
218
|
-
```typescript
|
|
219
|
-
const bot = app.adapters.get('onebot11')?.bots.get('my-bot')
|
|
220
|
-
|
|
221
|
-
// 发送群消息
|
|
222
|
-
await bot.callApi('send_group_msg', {
|
|
223
|
-
group_id: 123456,
|
|
224
|
-
message: '消息内容'
|
|
225
|
-
})
|
|
226
|
-
|
|
227
|
-
// 发送私聊消息
|
|
228
|
-
await bot.callApi('send_private_msg', {
|
|
229
|
-
user_id: 123456,
|
|
230
|
-
message: '消息内容'
|
|
231
|
-
})
|
|
232
|
-
|
|
233
|
-
// 撤回消息
|
|
234
|
-
await bot.callApi('delete_msg', {
|
|
235
|
-
message_id: 123456
|
|
236
|
-
})
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
### 信息获取
|
|
240
|
-
|
|
241
|
-
```typescript
|
|
242
|
-
// 获取登录信息
|
|
243
|
-
const loginInfo = await bot.callApi('get_login_info')
|
|
244
|
-
|
|
245
|
-
// 获取用户信息
|
|
246
|
-
const userInfo = await bot.callApi('get_stranger_info', {
|
|
247
|
-
user_id: 123456
|
|
248
|
-
})
|
|
249
|
-
|
|
250
|
-
// 获取群信息
|
|
251
|
-
const groupInfo = await bot.callApi('get_group_info', {
|
|
252
|
-
group_id: 123456
|
|
253
|
-
})
|
|
254
|
-
|
|
255
|
-
// 获取群成员列表
|
|
256
|
-
const memberList = await bot.callApi('get_group_member_list', {
|
|
257
|
-
group_id: 123456
|
|
258
|
-
})
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
### 群管理
|
|
54
|
+
根插件 `zhin.plugins`(或项目图)需引用 `@zhin.js/adapter-onebot11`(`instanceKey: onebot11`)。
|
|
262
55
|
|
|
263
|
-
|
|
264
|
-
// 踢出群成员
|
|
265
|
-
await bot.callApi('set_group_kick', {
|
|
266
|
-
group_id: 123456,
|
|
267
|
-
user_id: 654321
|
|
268
|
-
})
|
|
56
|
+
## 连接方式
|
|
269
57
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
duration: 600 // 秒
|
|
275
|
-
})
|
|
58
|
+
| connection | 状态 |
|
|
59
|
+
|------------|----------------|
|
|
60
|
+
| `ws` | 已实现(推荐) |
|
|
61
|
+
| `wss` | 已实现:反向 WS(`httpHostToken`) |
|
|
276
62
|
|
|
277
|
-
|
|
278
|
-
await bot.callApi('set_group_card', {
|
|
279
|
-
group_id: 123456,
|
|
280
|
-
user_id: 654321,
|
|
281
|
-
card: '新名片'
|
|
282
|
-
})
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
## 连接模式对比
|
|
286
|
-
|
|
287
|
-
### 正向 WebSocket(客户端模式)
|
|
288
|
-
|
|
289
|
-
**优点:**
|
|
290
|
-
- ✅ 配置简单
|
|
291
|
-
- ✅ 主动连接,无需开放端口
|
|
292
|
-
- ✅ 适合本地开发
|
|
293
|
-
|
|
294
|
-
**缺点:**
|
|
295
|
-
- ❌ 需要 OneBot 实现提供 WebSocket 服务
|
|
296
|
-
|
|
297
|
-
### 反向 WebSocket(服务器模式)
|
|
298
|
-
|
|
299
|
-
**优点:**
|
|
300
|
-
- ✅ OneBot 实现主动连接
|
|
301
|
-
- ✅ 支持多个客户端连接
|
|
302
|
-
- ✅ 适合生产环境
|
|
63
|
+
## 鉴权
|
|
303
64
|
|
|
304
|
-
|
|
305
|
-
-
|
|
306
|
-
- ❌ 配置相对复杂
|
|
65
|
+
- **Bearer**:`Authorization: Bearer <access_token>`
|
|
66
|
+
- 正向 WS 在 Upgrade 时附带请求头,并在 URL query 写入 `access_token`
|
|
307
67
|
|
|
308
|
-
##
|
|
68
|
+
## 动作与事件
|
|
309
69
|
|
|
310
|
-
|
|
70
|
+
- 事件:`post_type`(message/notice/request/meta_event)、`message_type`、`message` 等
|
|
71
|
+
- 动作:`send_private_msg`、`send_group_msg`、`delete_msg`、`set_group_special_title` 等
|
|
311
72
|
|
|
312
|
-
|
|
73
|
+
## AI 工具
|
|
313
74
|
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
```typescript
|
|
320
|
-
{
|
|
321
|
-
access_token: process.env.ONEBOT_TOKEN
|
|
322
|
-
}
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
OneBot 实现需要配置相同的 Token。
|
|
326
|
-
|
|
327
|
-
### 重连机制
|
|
328
|
-
|
|
329
|
-
适配器会自动重连,可配置重连间隔:
|
|
330
|
-
```typescript
|
|
331
|
-
{
|
|
332
|
-
reconnect_interval: 5000 // 5秒后重连
|
|
333
|
-
}
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
### 心跳检测
|
|
337
|
-
|
|
338
|
-
心跳机制确保连接活跃:
|
|
339
|
-
```typescript
|
|
340
|
-
{
|
|
341
|
-
heartbeat_interval: 30000 // 30秒发送一次心跳
|
|
342
|
-
}
|
|
343
|
-
```
|
|
344
|
-
|
|
345
|
-
### API 超时
|
|
346
|
-
|
|
347
|
-
API 调用默认 30 秒超时,可在代码中调整。
|
|
348
|
-
|
|
349
|
-
## 故障排查
|
|
350
|
-
|
|
351
|
-
### 连接不上 OneBot 服务
|
|
352
|
-
|
|
353
|
-
1. OneBot 服务是否已启动
|
|
354
|
-
2. WebSocket 地址(`url`)或反向路径(`path`)是否正确
|
|
355
|
-
3. `access_token` 是否与实现侧一致
|
|
356
|
-
4. 防火墙是否阻止连接
|
|
357
|
-
|
|
358
|
-
### 消息发送失败
|
|
359
|
-
|
|
360
|
-
1. QQ 未登录或登录失效
|
|
361
|
-
2. 账号风控限制
|
|
362
|
-
3. 群/好友不存在
|
|
363
|
-
4. 消息段格式错误
|
|
364
|
-
|
|
365
|
-
### 反向 WS 无法连接
|
|
366
|
-
|
|
367
|
-
1. `@zhin.js/host-router` 已启用且 HTTP 服务正常
|
|
368
|
-
2. `path` 与 OneBot 实现配置的反向 WS 地址一致
|
|
369
|
-
3. 端口已从公网或内网可达
|
|
370
|
-
|
|
371
|
-
### CQ 码与消息段
|
|
75
|
+
| 类别 | 路径 |
|
|
76
|
+
|------|------|
|
|
77
|
+
| Permit 词汇 | `agent/PERMITS.md` |
|
|
78
|
+
| 平台工具 | `agent/tools/set_title.ts` → `onebot11_set_title` |
|
|
79
|
+
| 技能说明 | `agent/skills/onebot11.md` |
|
|
372
80
|
|
|
373
|
-
|
|
81
|
+
## 迁移说明(Plugin Runtime)
|
|
374
82
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
{ type: 'image', data: { file: 'url' } }
|
|
379
|
-
]
|
|
380
|
-
```
|
|
83
|
+
- **notice / request / meta 侧事件**:经 the unified `Endpoint.emit(...)` ingress 归一后分发到 `handlers`;消息仍走 `outboundMessageToken`。
|
|
84
|
+
- **群管工具暂未迁移**:旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具;迁移后仅保留 `onebot11_set_title`,其余群管能力可通过 `$client.call()`(如 `set_group_kick`、`set_group_ban`)作为逃生舱调用。
|
|
85
|
+
- **平台权限门禁**:`plugin.ts` setup 已注册 `registerDefaultScenePlatformPermitChecker('onebot11')`,`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`(owner / admin)判定。
|
|
381
86
|
|
|
382
87
|
## 文档链接
|
|
383
88
|
|
|
384
|
-
- [OneBot v11 适配器文档](https://zhin.js.org/adapters/onebot11)
|
|
385
|
-
- [适配器概览](https://zhin.js.org/essentials/adapters)
|
|
386
89
|
- [OneBot 11 标准](https://github.com/botuniverse/onebot-11)
|
|
90
|
+
- [适配器概览](https://zhin.js.org/essentials/adapters)
|
|
387
91
|
|
|
388
|
-
##
|
|
389
|
-
|
|
390
|
-
- [OneBot 标准](https://github.com/botuniverse/onebot-11)
|
|
391
|
-
- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp)
|
|
392
|
-
- [LagrangeGo](https://github.com/LagrangeDev/Lagrange.Core)
|
|
393
|
-
- [Shamrock](https://github.com/whitechi73/OpenShamrock)
|
|
394
|
-
|
|
395
|
-
## 依赖项
|
|
396
|
-
|
|
397
|
-
- `ws` - WebSocket 客户端/服务器库
|
|
398
|
-
- `zhin.js` - Zhin 核心框架
|
|
399
|
-
|
|
400
|
-
## 开发
|
|
92
|
+
## 故障排查
|
|
401
93
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
94
|
+
| 现象 | 排查 |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| WS 无法建立 | 核对连接方向、URL、端口与实现端 WS 服务 |
|
|
97
|
+
| 401 或握手关闭 | 确认 Header/query token 与实现端一致 |
|
|
98
|
+
| 能收不能发 | 检查发送动作支持与账号风控状态 |
|
|
99
|
+
| notice/request 不出现 | 确认实现端上报对应 post type,并查看 Endpoint 请求/通知 |
|
|
406
100
|
|
|
407
101
|
## 许可证
|
|
408
102
|
|
|
409
103
|
MIT License
|
|
410
|
-
|
|
411
|
-
## 贡献
|
|
412
|
-
|
|
413
|
-
欢迎提交 Issue 和 Pull Request!
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// Generated by build-plugin-runtime-entries.mjs. Do not edit.
|
|
2
|
+
/**
|
|
3
|
+
* Convention entry: discover `adapters/onebot11.ts` → defineAdapter.
|
|
4
|
+
*/
|
|
5
|
+
import { defineAdapter } from 'zhin.js/adapter';
|
|
6
|
+
import { httpHostToken } from '@zhin.js/host-http';
|
|
7
|
+
import { OneBot11WsEndpoint } from "../lib/ws-endpoint.js";
|
|
8
|
+
import { OneBot11WssEndpoint } from "../lib/wss-endpoint.js";
|
|
9
|
+
import { resolveOneBot11Config, } from "../lib/protocol.js";
|
|
10
|
+
import { onebot11RuntimeStateToken } from "../lib/onebot11-runtime-state.js";
|
|
11
|
+
export { OneBot11WsEndpoint } from "../lib/ws-endpoint.js";
|
|
12
|
+
export { OneBot11WssEndpoint } from "../lib/wss-endpoint.js";
|
|
13
|
+
export default defineAdapter({
|
|
14
|
+
capabilities: ['inbound', 'outbound'],
|
|
15
|
+
operations: ['recall'],
|
|
16
|
+
// OneBot file 参数原生消费 url / base64:// 媒体;无卡片交互面,交互段降级纯文本。
|
|
17
|
+
segments: {
|
|
18
|
+
outboundMedia: ['url', 'base64'],
|
|
19
|
+
interactive: 'text',
|
|
20
|
+
},
|
|
21
|
+
create(context) {
|
|
22
|
+
const config = resolveOneBot11Config(context.config);
|
|
23
|
+
// 注册到插件运行时状态(onebot11.endpoint list 的"运行中"数据源)
|
|
24
|
+
context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
|
|
25
|
+
id: config.id,
|
|
26
|
+
mode: config.connection,
|
|
27
|
+
});
|
|
28
|
+
if (config.connection === 'wss') {
|
|
29
|
+
return new OneBot11WssEndpoint({
|
|
30
|
+
id: context.id,
|
|
31
|
+
http: context.use(httpHostToken),
|
|
32
|
+
config,
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
return new OneBot11WsEndpoint({
|
|
36
|
+
id: context.id,
|
|
37
|
+
config,
|
|
38
|
+
});
|
|
39
|
+
},
|
|
40
|
+
});
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Convention entry: discover `adapters/onebot11.ts` → defineAdapter.
|
|
3
|
+
*/
|
|
4
|
+
import { defineAdapter } from 'zhin.js/adapter';
|
|
5
|
+
import { httpHostToken } from '@zhin.js/host-http';
|
|
6
|
+
import { OneBot11WsEndpoint } from '../src/ws-endpoint.js';
|
|
7
|
+
import { OneBot11WssEndpoint } from '../src/wss-endpoint.js';
|
|
8
|
+
import {
|
|
9
|
+
resolveOneBot11Config,
|
|
10
|
+
type OneBot11AdapterConfig,
|
|
11
|
+
} from '../src/protocol.js';
|
|
12
|
+
import { onebot11RuntimeStateToken } from '../src/onebot11-runtime-state.js';
|
|
13
|
+
|
|
14
|
+
export { OneBot11WsEndpoint } from '../src/ws-endpoint.js';
|
|
15
|
+
export type { OneBot11WsEndpointOptions } from '../src/ws-endpoint.js';
|
|
16
|
+
export { OneBot11WssEndpoint } from '../src/wss-endpoint.js';
|
|
17
|
+
export type { OneBot11WssEndpointOptions } from '../src/wss-endpoint.js';
|
|
18
|
+
export type { OneBot11WsSocket, OneBot11WsCreateOptions } from '../src/ws-types.js';
|
|
19
|
+
|
|
20
|
+
declare module '@zhin.js/core' {
|
|
21
|
+
interface AdapterEndpoints {
|
|
22
|
+
onebot11: import('../src/ws-endpoint.js').OneBot11WsEndpoint;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export default defineAdapter<OneBot11AdapterConfig>({
|
|
27
|
+
capabilities: ['inbound', 'outbound'],
|
|
28
|
+
operations: ['recall'],
|
|
29
|
+
// OneBot file 参数原生消费 url / base64:// 媒体;无卡片交互面,交互段降级纯文本。
|
|
30
|
+
segments: {
|
|
31
|
+
outboundMedia: ['url', 'base64'],
|
|
32
|
+
interactive: 'text',
|
|
33
|
+
},
|
|
34
|
+
create(context) {
|
|
35
|
+
const config = resolveOneBot11Config(context.config);
|
|
36
|
+
// 注册到插件运行时状态(onebot11.endpoint list 的"运行中"数据源)
|
|
37
|
+
context.use(onebot11RuntimeStateToken).endpoints.set(config.id, {
|
|
38
|
+
id: config.id,
|
|
39
|
+
mode: config.connection,
|
|
40
|
+
});
|
|
41
|
+
if (config.connection === 'wss') {
|
|
42
|
+
return new OneBot11WssEndpoint({
|
|
43
|
+
id: context.id,
|
|
44
|
+
http: context.use(httpHostToken),
|
|
45
|
+
config,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
return new OneBot11WsEndpoint({
|
|
49
|
+
id: context.id,
|
|
50
|
+
config,
|
|
51
|
+
});
|
|
52
|
+
},
|
|
53
|
+
});
|
package/agent/PERMITS.md
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# OneBot v11 Platform Permits(QQ 群)
|
|
2
|
+
|
|
3
|
+
## 入站字段
|
|
4
|
+
|
|
5
|
+
`sender.role` 来自 OneBot 事件,经 `applyQqSenderRoleToMessageSender` 写入 `$sender.role`。
|
|
6
|
+
|
|
7
|
+
## Permit 词汇表
|
|
8
|
+
|
|
9
|
+
| `platform(onebot11,…)` | 含义 |
|
|
10
|
+
|------------------------|------|
|
|
11
|
+
| `scene_owner` | 群主 |
|
|
12
|
+
| `scene_admin` | 群管理员(含群主) |
|
|
13
|
+
|
|
14
|
+
工厂工具默认 `scene_admin` / `scene_owner`;扩展工具如 `onebot11_set_title` 使用 `scene_owner`。
|
|
@@ -5,7 +5,7 @@ platforms:
|
|
|
5
5
|
description: >-
|
|
6
6
|
OneBot11 协议群管理能力。当用户在 QQ 群中请求踢人、禁言、设管理员、改群名片、
|
|
7
7
|
设专属头衔、查成员列表或群信息时使用此技能。即使用户没有提到 OneBot,
|
|
8
|
-
只要
|
|
8
|
+
只要 Endpoint 所在平台是 OneBot11 协议且涉及群管理操作,就应触发。
|
|
9
9
|
仅有昵称时必须先查成员列表获取 user_id。
|
|
10
10
|
keywords:
|
|
11
11
|
- onebot
|
|
@@ -54,8 +54,8 @@ OneBot11 是 QQ 生态中广泛使用的标准协议。此技能覆盖基础群
|
|
|
54
54
|
### 权限层级
|
|
55
55
|
|
|
56
56
|
- **user** — 查询类:`list_members`, `get_group_info`
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
57
|
+
- **scene_admin** — 管理类:踢人、禁言、改名片、改群名
|
|
58
|
+
- **scene_owner** — 仅群主:设管理员、设专属头衔
|
|
59
59
|
|
|
60
60
|
Bot 权限不足时 API 会报错,应向用户说明而非重试。
|
|
61
61
|
|
|
@@ -76,5 +76,5 @@ Bot 权限不足时 API 会报错,应向用户说明而非重试。
|
|
|
76
76
|
## 易错点
|
|
77
77
|
|
|
78
78
|
1. **禁言 duration=0 是解禁**,不是永久禁言。最长可设 2592000(30 天)。
|
|
79
|
-
2. **头衔只有群主能设**,管理员也不行。用户说「加个头衔」但
|
|
79
|
+
2. **头衔只有群主能设**,管理员也不行。用户说「加个头衔」但 Endpoint 不是群主时,告知无法操作。
|
|
80
80
|
3. **OneBot11 与 NapCat/ICQQ 功能范围不同**:标准 OneBot11 不支持合并转发、精华消息、群文件等扩展功能,这些属于 NapCat 或 ICQQ 的增强。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { defineAgentTool } from '@zhin.js/agent/tools';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
export default defineAgentTool<{ group_id: number; user_id: number; title: string }>({
|
|
4
|
+
description: '设置 QQ 群成员的专属头衔。只有群主才能设置。',
|
|
5
|
+
inputSchema: z.object({
|
|
6
|
+
group_id: z.number().describe('目标群号'),
|
|
7
|
+
user_id: z.number().describe('目标成员 QQ号'),
|
|
8
|
+
title: z.string().describe('头衔文字'),
|
|
9
|
+
}),
|
|
10
|
+
adapter: 'onebot11',
|
|
11
|
+
tags: ['onebot11'],
|
|
12
|
+
permissions: ['platform(onebot11,scene_owner)'],
|
|
13
|
+
async execute({ group_id, user_id, title }: { group_id: number; user_id: number; title: string }, context) {
|
|
14
|
+
const client = context.$client;
|
|
15
|
+
const response = await client.call('set_group_special_title', {
|
|
16
|
+
group_id,
|
|
17
|
+
user_id,
|
|
18
|
+
special_title: title,
|
|
19
|
+
duration: -1,
|
|
20
|
+
});
|
|
21
|
+
const success = response.status === 'ok';
|
|
22
|
+
return { success, message: success ? `已将 ${user_id} 的头衔设为 "${title}"` : '设置失败' };
|
|
23
|
+
},
|
|
24
|
+
});
|
package/lib/client.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { OneBotV11Client, type OneBotV11Event as ImHelperOneBot11Event, type OneBotV11Response } from '@imhelper/onebot-v11';
|
|
2
|
+
import { type EventMap, type ImHelperEventMap } from 'imhelper';
|
|
3
|
+
import { type ClientEventPayloads } from 'zhin.js/adapter';
|
|
4
|
+
import type { ResolvedOneBot11Config } from './protocol.js';
|
|
5
|
+
export { OneBotV11Client as Onebot11Client } from '@imhelper/onebot-v11';
|
|
6
|
+
export type Onebot11ApiCall = (action: string, params?: Record<string, unknown>) => Promise<OneBotV11Response>;
|
|
7
|
+
type Onebot11ClientEvents = ImHelperEventMap<number, ImHelperOneBot11Event, EventMap<number>>;
|
|
8
|
+
export type Onebot11ClientEventMap = ClientEventPayloads<Onebot11ClientEvents>;
|
|
9
|
+
export declare function createOnebot11EndpointClient(config: ResolvedOneBot11Config, request: Onebot11ApiCall): OneBotV11Client;
|
|
10
|
+
export declare function callOnebot11Client<T = unknown>(client: OneBotV11Client, action: string, params?: Record<string, unknown>): Promise<T | undefined>;
|
|
11
|
+
export declare function forwardOnebot11ClientEvents(client: OneBotV11Client, receive: (name: string, payload: unknown) => void): () => void;
|
|
12
|
+
declare module '@zhin.js/feature-kit' {
|
|
13
|
+
interface AdapterClientRegistry {
|
|
14
|
+
readonly onebot11: {
|
|
15
|
+
readonly client: OneBotV11Client;
|
|
16
|
+
readonly events: Onebot11ClientEventMap;
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
export declare const onebot11Client: import("@zhin.js/adapter").EndpointClientToken<OneBotV11Client, ClientEventPayloads<Onebot11ClientEvents>>;
|