@zhin.js/adapter-onebot11 1.0.98 → 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.
Files changed (83) hide show
  1. package/CHANGELOG.md +650 -3
  2. package/README.md +58 -368
  3. package/adapters/onebot11.js +40 -0
  4. package/adapters/onebot11.ts +53 -0
  5. package/agent/PERMITS.md +14 -0
  6. package/{skills/onebot11/SKILL.md → agent/skills/onebot11.md} +4 -4
  7. package/agent/tools/set_title.ts +24 -0
  8. package/commands/endpoint/add/[id].js +3 -0
  9. package/commands/endpoint/add/[id].ts +3 -0
  10. package/commands/endpoint/list.js +3 -0
  11. package/commands/endpoint/list.ts +3 -0
  12. package/commands/endpoint/remove/[id].js +3 -0
  13. package/commands/endpoint/remove/[id].ts +3 -0
  14. package/lib/client.d.ts +20 -0
  15. package/lib/client.js +30 -0
  16. package/lib/content-port.d.ts +4 -0
  17. package/lib/content-port.js +63 -0
  18. package/lib/endpoint-management.d.ts +15 -0
  19. package/lib/endpoint-management.js +47 -0
  20. package/lib/index.d.ts +10 -16
  21. package/lib/index.js +7 -53
  22. package/lib/onebot11-endpoint-commands.d.ts +1 -0
  23. package/lib/onebot11-endpoint-commands.js +24 -0
  24. package/lib/onebot11-runtime-state.d.ts +1 -0
  25. package/lib/onebot11-runtime-state.js +6 -0
  26. package/lib/protocol.d.ts +160 -0
  27. package/lib/protocol.js +316 -0
  28. package/lib/side-event-dispatch.d.ts +7 -0
  29. package/lib/side-event-dispatch.js +36 -0
  30. package/lib/ws-endpoint.d.ts +22 -0
  31. package/lib/ws-endpoint.js +209 -0
  32. package/lib/ws-transport.d.ts +13 -0
  33. package/lib/ws-transport.js +71 -0
  34. package/lib/ws-types.d.ts +18 -0
  35. package/lib/ws-types.js +1 -0
  36. package/lib/wss-auth.d.ts +2 -0
  37. package/lib/wss-auth.js +16 -0
  38. package/lib/wss-endpoint.d.ts +25 -0
  39. package/lib/wss-endpoint.js +173 -0
  40. package/package.json +69 -22
  41. package/plugin.js +18 -0
  42. package/schema.json +97 -0
  43. package/src/client.ts +78 -0
  44. package/src/content-port.ts +66 -0
  45. package/src/endpoint-management.ts +72 -0
  46. package/src/index.ts +62 -65
  47. package/src/onebot11-endpoint-commands.ts +23 -0
  48. package/src/onebot11-runtime-state.ts +7 -0
  49. package/src/protocol.ts +459 -0
  50. package/src/side-event-dispatch.ts +48 -0
  51. package/src/ws-endpoint.ts +272 -0
  52. package/src/ws-transport.ts +100 -0
  53. package/src/ws-types.ts +21 -0
  54. package/src/wss-auth.ts +17 -0
  55. package/src/wss-endpoint.ts +228 -0
  56. package/lib/adapter.d.ts +0 -32
  57. package/lib/adapter.d.ts.map +0 -1
  58. package/lib/adapter.js +0 -92
  59. package/lib/adapter.js.map +0 -1
  60. package/lib/bot-ws-client.d.ts +0 -40
  61. package/lib/bot-ws-client.d.ts.map +0 -1
  62. package/lib/bot-ws-client.js +0 -397
  63. package/lib/bot-ws-client.js.map +0 -1
  64. package/lib/bot-ws-server.d.ts +0 -42
  65. package/lib/bot-ws-server.d.ts.map +0 -1
  66. package/lib/bot-ws-server.js +0 -344
  67. package/lib/bot-ws-server.js.map +0 -1
  68. package/lib/index.d.ts.map +0 -1
  69. package/lib/index.js.map +0 -1
  70. package/lib/onebot-get-msg.d.ts +0 -3
  71. package/lib/onebot-get-msg.d.ts.map +0 -1
  72. package/lib/onebot-get-msg.js +0 -27
  73. package/lib/onebot-get-msg.js.map +0 -1
  74. package/lib/types.d.ts +0 -54
  75. package/lib/types.d.ts.map +0 -1
  76. package/lib/types.js +0 -5
  77. package/lib/types.js.map +0 -1
  78. package/plugin.yml +0 -3
  79. package/src/adapter.ts +0 -104
  80. package/src/bot-ws-client.ts +0 -421
  81. package/src/bot-ws-server.ts +0 -382
  82. package/src/onebot-get-msg.ts +0 -33
  83. 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 v11 协议适配器,通过 WebSocket 连接各种支持 OneBot 协议的 QQ 机器人实现(如 go-cqhttp、Shamrock、LagrangeGo 等)。
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
- - 🔌 完整 OneBot v11 协议兼容
8
- - 📦 **单一适配器**:`context: onebot11`,通过 `connection` 选择连接方式
9
- - 🌐 **正向 WebSocket**(`connection: ws`):应用连 OneBot 实现的 WS
10
- - 🔄 **反向 WebSocket**(`connection: wss`):应用开 WS 服务端,实现连上来
11
- - 🔐 Access Token 认证支持
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 ws
16
+ pnpm add @zhin.js/adapter-onebot11
22
17
  ```
23
18
 
24
- 反向 WS 需同时启用 `@zhin.js/host-router`。
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
- ```yaml
42
- plugins:
43
- - "@zhin.js/adapter-onebot11"
26
+ 每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v11` 的 `OneBotV11Client`。业务代码直接调用
27
+ `$client.call(action, params)` 和 Client 的公开平台能力;双工 WS 的 `echo` 响应由 Endpoint
28
+ 先行分流,只有事件帧进入 Client 的 `ingest()` 和公开事件流。
44
29
 
45
- bots:
46
- - context: onebot11
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
- 所有 Bot 使用 **同一 context:`onebot11`**,通过 **`connection`** 区分连接方式。
35
+ 1. 启动兼容 OneBot 11 的实现,并选定正向或反向 WebSocket。
36
+ 2. 正向 WS 需 Zhin 可达实现端;反向 WS 需实现端可达 Zhin HTTP Host。
37
+ 3. 两端配置相同的 `access_token`,生产环境不要开放无鉴权连接。
56
38
 
57
- ### 正向 WebSocket(connection: ws)
39
+ ## 最小配置
58
40
 
59
41
  ```yaml
42
+ # zhin.config.yml(Plugin Runtime)
60
43
  plugins:
61
- - "@zhin.js/adapter-onebot11"
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
- ### 反向 WebSocket(connection: wss)
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
- ```typescript
264
- // 踢出群成员
265
- await bot.callApi('set_group_kick', {
266
- group_id: 123456,
267
- user_id: 654321
268
- })
56
+ ## 连接方式
269
57
 
270
- // 禁言群成员
271
- await bot.callApi('set_group_ban', {
272
- group_id: 123456,
273
- user_id: 654321,
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
- ## 消息 ID 格式
68
+ ## 动作与事件
309
69
 
310
- OneBot11 适配器的消息 ID 格式:`{message_id}`
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
- 撤回消息时直接使用数字 ID。
73
+ ## AI 工具
313
74
 
314
- ## 注意事项
315
-
316
- ### Access Token
317
-
318
- 建议配置 Access Token 增强安全性:
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
- 适配器自动处理 CQ 码转换;发送时使用消息段格式即可:
81
+ ## 迁移说明(Plugin Runtime)
374
82
 
375
- ```typescript
376
- [
377
- { type: 'text', data: { text: '文本' } },
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
- ```bash
403
- pnpm build # 构建
404
- pnpm clean # 清理构建文件
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
+ });
@@ -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
- 只要 Bot 所在平台是 OneBot11 协议且涉及群管理操作,就应触发。
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
- - **group_admin** — 管理类:踢人、禁言、改名片、改群名
58
- - **group_owner** — 仅群主:设管理员、设专属头衔
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. **头衔只有群主能设**,管理员也不行。用户说「加个头衔」但 Bot 不是群主时,告知无法操作。
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
+ });
@@ -0,0 +1,3 @@
1
+ // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
+ import { onebot11EndpointCommands } from "../../../lib/onebot11-endpoint-commands.js";
3
+ export default onebot11EndpointCommands.add;
@@ -0,0 +1,3 @@
1
+ import { onebot11EndpointCommands } from '../../../src/onebot11-endpoint-commands.js';
2
+
3
+ export default onebot11EndpointCommands.add;
@@ -0,0 +1,3 @@
1
+ // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
+ import { onebot11EndpointCommands } from "../../lib/onebot11-endpoint-commands.js";
3
+ export default onebot11EndpointCommands.list;
@@ -0,0 +1,3 @@
1
+ import { onebot11EndpointCommands } from '../../src/onebot11-endpoint-commands.js';
2
+
3
+ export default onebot11EndpointCommands.list;
@@ -0,0 +1,3 @@
1
+ // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
+ import { onebot11EndpointCommands } from "../../../lib/onebot11-endpoint-commands.js";
3
+ export default onebot11EndpointCommands.remove;
@@ -0,0 +1,3 @@
1
+ import { onebot11EndpointCommands } from '../../../src/onebot11-endpoint-commands.js';
2
+
3
+ export default onebot11EndpointCommands.remove;
@@ -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>>;