@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.
- package/CHANGELOG.md +745 -3
- package/PERMITS.md +14 -0
- package/README.md +59 -367
- package/adapters/onebot11/index.js +40 -0
- package/adapters/onebot11/index.ts +53 -0
- package/agents/onebot11/agent.json +20 -0
- package/agents/onebot11/boundaries.md +3 -0
- package/agents/onebot11/conventions.md +3 -0
- package/agents/onebot11/skills/onebot11/SKILL.md +15 -0
- package/agents/onebot11/skills/onebot11/tools/set_title/index.js +25 -0
- package/agents/onebot11/skills/onebot11/tools/set_title/index.ts +24 -0
- package/agents/onebot11/system.md +3 -0
- package/commands/onebot11/endpoint/add/[id]/index.js +3 -0
- package/commands/onebot11/endpoint/add/[id]/index.ts +3 -0
- package/commands/onebot11/endpoint/definition.js +25 -0
- package/commands/onebot11/endpoint/definition.ts +23 -0
- package/commands/onebot11/endpoint/list/index.js +3 -0
- package/commands/onebot11/endpoint/list/index.ts +3 -0
- package/commands/onebot11/endpoint/remove/[id]/index.js +3 -0
- package/commands/onebot11/endpoint/remove/[id]/index.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-runtime-state.d.ts +1 -0
- package/lib/onebot11-runtime-state.js +6 -0
- package/lib/protocol.d.ts +143 -0
- package/lib/protocol.js +327 -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 +12 -0
- package/lib/ws-transport.js +59 -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 +186 -0
- package/package.json +82 -23
- package/plugin.js +18 -0
- package/schema.json +114 -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 +60 -65
- package/src/onebot11-runtime-state.ts +7 -0
- package/src/protocol.ts +452 -0
- package/src/side-event-dispatch.ts +48 -0
- package/src/ws-endpoint.ts +272 -0
- package/src/ws-transport.ts +85 -0
- package/src/ws-types.ts +21 -0
- package/src/wss-auth.ts +17 -0
- package/src/wss-endpoint.ts +239 -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 -397
- 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/skills/onebot11/SKILL.md +0 -80
- package/src/adapter.ts +0 -104
- package/src/bot-ws-client.ts +0 -421
- package/src/bot-ws-server.ts +0 -382
- package/src/onebot-get-msg.ts +0 -33
- 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
|
|
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 实现侧配置一致 |
|
|
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
|
-
|
|
26
|
+
`AdapterIndex` 会把实例默认值与 `endpoints[]` 的逐项覆盖合并;协议层只接收一个已经展开的 endpoint 配置,不再读取嵌套 endpoint、旧 `type: ws_reverse` 别名或进程环境。
|
|
36
27
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
46
|
-
|
|
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
|
-
|
|
37
|
+
1. 启动兼容 OneBot 11 的实现,并选定正向或反向 WebSocket。
|
|
38
|
+
2. 正向 WS 需 Zhin 可达实现端;反向 WS 需实现端可达 Zhin HTTP Host。
|
|
39
|
+
3. 两端配置相同的 `access_token`,生产环境不要开放无鉴权连接。
|
|
56
40
|
|
|
57
|
-
|
|
41
|
+
## 最小配置
|
|
58
42
|
|
|
59
43
|
```yaml
|
|
44
|
+
# zhin.config.yml(Plugin Runtime)
|
|
60
45
|
plugins:
|
|
61
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
+
## 连接方式
|
|
116
59
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
127
|
-
import { addCommand, MessageCommand } from 'zhin.js'
|
|
70
|
+
## 动作与事件
|
|
128
71
|
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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
|
-
|
|
83
|
+
## 迁移说明(Plugin Runtime)
|
|
374
84
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
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
|
-
|
|
403
|
-
|
|
404
|
-
|
|
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,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
|
+
});
|