@zhin.js/adapter-onebot11 1.0.98 → 1.1.2

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 (88) hide show
  1. package/CHANGELOG.md +745 -3
  2. package/PERMITS.md +14 -0
  3. package/README.md +59 -367
  4. package/adapters/onebot11/index.js +40 -0
  5. package/adapters/onebot11/index.ts +53 -0
  6. package/agents/onebot11/agent.json +20 -0
  7. package/agents/onebot11/boundaries.md +3 -0
  8. package/agents/onebot11/conventions.md +3 -0
  9. package/agents/onebot11/skills/onebot11/SKILL.md +15 -0
  10. package/agents/onebot11/skills/onebot11/tools/set_title/index.js +25 -0
  11. package/agents/onebot11/skills/onebot11/tools/set_title/index.ts +24 -0
  12. package/agents/onebot11/system.md +3 -0
  13. package/commands/onebot11/endpoint/add/[id]/index.js +3 -0
  14. package/commands/onebot11/endpoint/add/[id]/index.ts +3 -0
  15. package/commands/onebot11/endpoint/definition.js +25 -0
  16. package/commands/onebot11/endpoint/definition.ts +23 -0
  17. package/commands/onebot11/endpoint/list/index.js +3 -0
  18. package/commands/onebot11/endpoint/list/index.ts +3 -0
  19. package/commands/onebot11/endpoint/remove/[id]/index.js +3 -0
  20. package/commands/onebot11/endpoint/remove/[id]/index.ts +3 -0
  21. package/lib/client.d.ts +20 -0
  22. package/lib/client.js +30 -0
  23. package/lib/content-port.d.ts +4 -0
  24. package/lib/content-port.js +63 -0
  25. package/lib/endpoint-management.d.ts +15 -0
  26. package/lib/endpoint-management.js +47 -0
  27. package/lib/index.d.ts +10 -16
  28. package/lib/index.js +7 -53
  29. package/lib/onebot11-runtime-state.d.ts +1 -0
  30. package/lib/onebot11-runtime-state.js +6 -0
  31. package/lib/protocol.d.ts +143 -0
  32. package/lib/protocol.js +327 -0
  33. package/lib/side-event-dispatch.d.ts +7 -0
  34. package/lib/side-event-dispatch.js +36 -0
  35. package/lib/ws-endpoint.d.ts +22 -0
  36. package/lib/ws-endpoint.js +209 -0
  37. package/lib/ws-transport.d.ts +12 -0
  38. package/lib/ws-transport.js +59 -0
  39. package/lib/ws-types.d.ts +18 -0
  40. package/lib/ws-types.js +1 -0
  41. package/lib/wss-auth.d.ts +2 -0
  42. package/lib/wss-auth.js +16 -0
  43. package/lib/wss-endpoint.d.ts +25 -0
  44. package/lib/wss-endpoint.js +186 -0
  45. package/package.json +82 -23
  46. package/plugin.js +18 -0
  47. package/schema.json +114 -0
  48. package/src/client.ts +78 -0
  49. package/src/content-port.ts +66 -0
  50. package/src/endpoint-management.ts +72 -0
  51. package/src/index.ts +60 -65
  52. package/src/onebot11-runtime-state.ts +7 -0
  53. package/src/protocol.ts +452 -0
  54. package/src/side-event-dispatch.ts +48 -0
  55. package/src/ws-endpoint.ts +272 -0
  56. package/src/ws-transport.ts +85 -0
  57. package/src/ws-types.ts +21 -0
  58. package/src/wss-auth.ts +17 -0
  59. package/src/wss-endpoint.ts +239 -0
  60. package/lib/adapter.d.ts +0 -32
  61. package/lib/adapter.d.ts.map +0 -1
  62. package/lib/adapter.js +0 -92
  63. package/lib/adapter.js.map +0 -1
  64. package/lib/bot-ws-client.d.ts +0 -40
  65. package/lib/bot-ws-client.d.ts.map +0 -1
  66. package/lib/bot-ws-client.js +0 -397
  67. package/lib/bot-ws-client.js.map +0 -1
  68. package/lib/bot-ws-server.d.ts +0 -42
  69. package/lib/bot-ws-server.d.ts.map +0 -1
  70. package/lib/bot-ws-server.js +0 -344
  71. package/lib/bot-ws-server.js.map +0 -1
  72. package/lib/index.d.ts.map +0 -1
  73. package/lib/index.js.map +0 -1
  74. package/lib/onebot-get-msg.d.ts +0 -3
  75. package/lib/onebot-get-msg.d.ts.map +0 -1
  76. package/lib/onebot-get-msg.js +0 -27
  77. package/lib/onebot-get-msg.js.map +0 -1
  78. package/lib/types.d.ts +0 -54
  79. package/lib/types.d.ts.map +0 -1
  80. package/lib/types.js +0 -5
  81. package/lib/types.js.map +0 -1
  82. package/plugin.yml +0 -3
  83. package/skills/onebot11/SKILL.md +0 -80
  84. package/src/adapter.ts +0 -104
  85. package/src/bot-ws-client.ts +0 -421
  86. package/src/bot-ws-server.ts +0 -382
  87. package/src/onebot-get-msg.ts +0 -33
  88. package/src/types.ts +0 -58
package/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`。
package/README.md CHANGED
@@ -1,413 +1,105 @@
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 实现侧配置一致 |
21
+ - `@zhin.js/adapter` — 约定式 `adapters/onebot11/index.ts`(`defineAdapter`)
22
+ - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
23
+ - `zhin.js` — `plugin.ts`(`definePlugin`)
24
+ - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
34
25
 
35
- 必填字段见 `OneBot11BotConfig`:`context`、`name`、`connection`;`ws` 需 `url`,`wss` 需 `path`。
26
+ `AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并;协议层只接收一个已经展开的 endpoint 配置,不再读取嵌套 endpoint、旧 `type: ws_reverse` 别名或进程环境。
36
27
 
37
- ## 最小配置
38
-
39
- 正向 WebSocket(本地开发推荐):
40
-
41
- ```yaml
42
- plugins:
43
- - "@zhin.js/adapter-onebot11"
28
+ 每个 Endpoint 的 `$client` 是 `@imhelper/onebot-v11` 的 `OneBotV11Client`。业务代码直接调用
29
+ `$client.call(action, params)` 和 Client 的公开平台能力;双工 WS 的 `echo` 响应由 Endpoint
30
+ 先行分流,只有事件帧进入 Client 的 `ingest()` 和公开事件流。
44
31
 
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
- ```
32
+ 入站:`gateway.receive({ conversation, message, content, sender, metadata })`(`conversation.kind` 为 `private`/`group`,`id` 为 uid/gid)
33
+ 出站:`send({ conversation, payload })` → WS `send_private_msg` / `send_group_msg`(payload 已由 gateway/core 渲染;无 segment-mapper)
52
34
 
53
- ## 配置
35
+ ## 前置条件
54
36
 
55
- 所有 Bot 使用 **同一 context:`onebot11`**,通过 **`connection`** 区分连接方式。
37
+ 1. 启动兼容 OneBot 11 的实现,并选定正向或反向 WebSocket。
38
+ 2. 正向 WS 需 Zhin 可达实现端;反向 WS 需实现端可达 Zhin HTTP Host。
39
+ 3. 两端配置相同的 `access_token`,生产环境不要开放无鉴权连接。
56
40
 
57
- ### 正向 WebSocket(connection: ws)
41
+ ## 最小配置
58
42
 
59
43
  ```yaml
44
+ # zhin.config.yml(Plugin Runtime)
60
45
  plugins:
61
- - "@zhin.js/adapter-onebot11"
62
-
63
- bots:
64
- - context: onebot11
46
+ onebot11:
65
47
  connection: ws
66
- name: my-bot
67
- url: "ws://localhost:8080"
68
- access_token: "${ONEBOT_TOKEN}"
69
48
  reconnect_interval: 5000
70
49
  heartbeat_interval: 30000
50
+ endpoints:
51
+ - id: ob11-bot
52
+ url: "ws://127.0.0.1:6700"
53
+ access_token: "${ONEBOT11_ACCESS_TOKEN}"
71
54
  ```
72
55
 
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
- ```
56
+ 根插件 `zhin.plugins`(或项目图)需引用 `@zhin.js/adapter-onebot11`(`instanceKey: onebot11`)。
114
57
 
115
- #### Shamrock
58
+ ## 连接方式
116
59
 
117
- 在 Shamrock 设置中:
118
- 1. 启用 WebSocket 服务
119
- 2. 设置端口(默认 5800)
120
- 3. 配置 Access Token(可选)
60
+ | connection | 状态 |
61
+ |------------|----------------|
62
+ | `ws` | 已实现(推荐) |
63
+ | `wss` | 已实现:反向 WS(`httpHostToken`) |
121
64
 
122
- ## 使用示例
65
+ ## 鉴权
123
66
 
124
- ### 基础消息处理
67
+ - **Bearer**:`Authorization: Bearer <access_token>`
68
+ - 正向 WS 在 Upgrade 时附带请求头,并在 URL query 写入 `access_token`
125
69
 
126
- ```typescript
127
- import { addCommand, MessageCommand } from 'zhin.js'
70
+ ## 动作与事件
128
71
 
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
- ```
72
+ - 事件:`post_type`(message/notice/request/meta_event)、`message_type`、`message` 等
73
+ - 动作:`send_private_msg`、`send_group_msg`、`delete_msg`、`set_group_special_title` 等
238
74
 
239
- ### 信息获取
75
+ ## AI 工具
240
76
 
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
- ### 群管理
262
-
263
- ```typescript
264
- // 踢出群成员
265
- await bot.callApi('set_group_kick', {
266
- group_id: 123456,
267
- user_id: 654321
268
- })
269
-
270
- // 禁言群成员
271
- await bot.callApi('set_group_ban', {
272
- group_id: 123456,
273
- user_id: 654321,
274
- duration: 600 // 秒
275
- })
276
-
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
- - ✅ 适合生产环境
303
-
304
- **缺点:**
305
- - ❌ 需要开放端口或使用内网穿透
306
- - ❌ 配置相对复杂
307
-
308
- ## 消息 ID 格式
309
-
310
- OneBot11 适配器的消息 ID 格式:`{message_id}`
311
-
312
- 撤回消息时直接使用数字 ID。
313
-
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 码与消息段
77
+ | 类别 | 路径 |
78
+ |------|------|
79
+ | Permit 词汇 | `PERMITS.md` |
80
+ | 平台工具 | `tools/set_title/index.ts` → `onebot11_set_title` |
81
+ | 技能说明 | `agents/onebot11/skills/onebot11/SKILL.md` |
372
82
 
373
- 适配器自动处理 CQ 码转换;发送时使用消息段格式即可:
83
+ ## 迁移说明(Plugin Runtime)
374
84
 
375
- ```typescript
376
- [
377
- { type: 'text', data: { text: '文本' } },
378
- { type: 'image', data: { file: 'url' } }
379
- ]
380
- ```
85
+ - **notice / request / meta 侧事件**:经 the unified `Endpoint.emit(...)` ingress 归一后分发到 `handlers`;消息仍走 `outboundMessageToken`。
86
+ - **群管工具暂未迁移**:旧 Adapter 经 `createSceneManagementTools` 注册踢人 / 禁言 / 群名片等成套 agent 工具;迁移后仅保留 `onebot11_set_title`,其余群管能力可通过 `$client.call()`(如 `set_group_kick`、`set_group_ban`)作为逃生舱调用。
87
+ - **平台权限门禁**:`plugin.ts` setup 通过 generation-owned `permissionHostToken` 调用 `host.registerPlatform('onebot11', createSceneRolePlatformChecker())`,`scene_admin` / `scene_owner` 依据入站 metadata 中的 sender `role`(owner / admin)判定。
381
88
 
382
89
  ## 文档链接
383
90
 
384
- - [OneBot v11 适配器文档](https://zhin.js.org/adapters/onebot11)
385
- - [适配器概览](https://zhin.js.org/essentials/adapters)
386
91
  - [OneBot 11 标准](https://github.com/botuniverse/onebot-11)
92
+ - [适配器概览](https://zhin.js.org/essentials/adapters)
387
93
 
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
- ## 开发
94
+ ## 故障排查
401
95
 
402
- ```bash
403
- pnpm build # 构建
404
- pnpm clean # 清理构建文件
405
- ```
96
+ | 现象 | 排查 |
97
+ | --- | --- |
98
+ | WS 无法建立 | 核对连接方向、URL、端口与实现端 WS 服务 |
99
+ | 401 或握手关闭 | 确认 Header/query token 与实现端一致 |
100
+ | 能收不能发 | 检查发送动作支持与账号风控状态 |
101
+ | notice/request 不出现 | 确认实现端上报对应 post type,并查看 Endpoint 请求/通知 |
406
102
 
407
103
  ## 许可证
408
104
 
409
105
  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/index.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/index.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 OneBot11EndpointConfig,
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<OneBot11EndpointConfig>({
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,20 @@
1
+ {
2
+ "name": "ONEBOT11 Platform Agent",
3
+ "version": "1.0.0",
4
+ "description": "Handles onebot11 platform-specific operations and progressively loads only the required platform Skill.",
5
+ "trigger_rules": {
6
+ "file_patterns": [],
7
+ "keywords": [
8
+ "onebot11",
9
+ "adapter:onebot11"
10
+ ]
11
+ },
12
+ "entry_points": [
13
+ "system.md",
14
+ "boundaries.md",
15
+ "conventions.md"
16
+ ],
17
+ "platforms": [
18
+ "onebot11"
19
+ ]
20
+ }
@@ -0,0 +1,3 @@
1
+ # Boundaries
2
+
3
+ Operate only on the active onebot11 endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.
@@ -0,0 +1,3 @@
1
+ # Conventions
2
+
3
+ Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: onebot11
3
+ platforms: [onebot11]
4
+ description: OneBot 11 消息通道与群专属头衔设置能力。
5
+ keywords: [onebot11, qq, title, 头衔]
6
+ tags: [adapter, messaging]
7
+ tools:
8
+ - set_title
9
+ ---
10
+
11
+ # OneBot 11
12
+
13
+ `set_title` 用于设置群成员专属头衔。执行前确认群、目标用户和头衔文本,并遵守 Tool 自身审批与平台权限。
14
+
15
+ 当前 Agent Tool 不提供踢人、禁言、管理员、群名片、成员列表或群信息操作。
@@ -0,0 +1,25 @@
1
+ // Generated by build-plugin-runtime-entries.mjs. Do not edit.
2
+ import { defineAgentTool } from '@zhin.js/tool';
3
+ import { z } from 'zod';
4
+ export default defineAgentTool({
5
+ description: '设置 QQ 群成员的专属头衔。只有群主才能设置。',
6
+ inputSchema: z.object({
7
+ group_id: z.number().describe('目标群号'),
8
+ user_id: z.number().describe('目标成员 QQ号'),
9
+ title: z.string().describe('头衔文字'),
10
+ }),
11
+ adapter: 'onebot11',
12
+ tags: ['onebot11'],
13
+ permissions: ['platform(onebot11,scene_owner)'],
14
+ async execute({ group_id, user_id, title }, context) {
15
+ const client = context.$client;
16
+ const response = await client.call('set_group_special_title', {
17
+ group_id,
18
+ user_id,
19
+ special_title: title,
20
+ duration: -1,
21
+ });
22
+ const success = response.status === 'ok';
23
+ return { success, message: success ? `已将 ${user_id} 的头衔设为 "${title}"` : '设置失败' };
24
+ },
25
+ });
@@ -0,0 +1,24 @@
1
+ import { defineAgentTool } from '@zhin.js/tool';
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
+ # ONEBOT11 Platform Agent
2
+
3
+ You are the onebot11 platform specialist. Interpret requests in the current onebot11 conversation and load only the narrowest private Skill needed for the task.