@zhin.js/adapter-milky 3.0.1 → 4.0.1

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 (89) hide show
  1. package/CHANGELOG.md +443 -0
  2. package/README.md +36 -117
  3. package/adapters/milky.ts +68 -0
  4. package/lib/endpoint.d.ts +7 -0
  5. package/lib/endpoint.js +6 -0
  6. package/lib/index.d.ts +3 -20
  7. package/lib/index.js +3 -35
  8. package/lib/milky-agent-deps.d.ts +24 -0
  9. package/lib/milky-agent-deps.js +30 -0
  10. package/lib/milky-auth.d.ts +3 -0
  11. package/lib/milky-auth.js +30 -0
  12. package/lib/protocol.d.ts +162 -0
  13. package/lib/protocol.js +337 -0
  14. package/lib/sse-client.d.ts +20 -0
  15. package/lib/sse-client.js +85 -0
  16. package/lib/sse-endpoint.d.ts +50 -0
  17. package/lib/sse-endpoint.js +261 -0
  18. package/lib/webhook-endpoint.d.ts +40 -0
  19. package/lib/webhook-endpoint.js +212 -0
  20. package/lib/ws-endpoint.d.ts +42 -0
  21. package/lib/ws-endpoint.js +320 -0
  22. package/lib/ws-types.d.ts +11 -0
  23. package/lib/ws-types.js +1 -0
  24. package/lib/wss-endpoint.d.ts +40 -0
  25. package/lib/wss-endpoint.js +263 -0
  26. package/package.json +52 -19
  27. package/plugin.ts +8 -0
  28. package/schema.json +36 -0
  29. package/src/endpoint.ts +26 -0
  30. package/src/index.ts +59 -48
  31. package/src/milky-agent-deps.ts +53 -0
  32. package/src/milky-auth.ts +29 -0
  33. package/src/protocol.ts +491 -0
  34. package/src/sse-client.ts +106 -0
  35. package/src/sse-endpoint.ts +318 -0
  36. package/src/webhook-endpoint.ts +262 -0
  37. package/src/ws-endpoint.ts +373 -0
  38. package/src/ws-types.ts +12 -0
  39. package/src/wss-endpoint.ts +305 -0
  40. package/lib/adapter.d.ts +0 -37
  41. package/lib/adapter.d.ts.map +0 -1
  42. package/lib/adapter.js +0 -99
  43. package/lib/adapter.js.map +0 -1
  44. package/lib/api.d.ts +0 -10
  45. package/lib/api.d.ts.map +0 -1
  46. package/lib/api.js +0 -48
  47. package/lib/api.js.map +0 -1
  48. package/lib/endpoint-sse.d.ts +0 -31
  49. package/lib/endpoint-sse.d.ts.map +0 -1
  50. package/lib/endpoint-sse.js +0 -197
  51. package/lib/endpoint-sse.js.map +0 -1
  52. package/lib/endpoint-webhook.d.ts +0 -34
  53. package/lib/endpoint-webhook.d.ts.map +0 -1
  54. package/lib/endpoint-webhook.js +0 -189
  55. package/lib/endpoint-webhook.js.map +0 -1
  56. package/lib/endpoint-ws.d.ts +0 -35
  57. package/lib/endpoint-ws.d.ts.map +0 -1
  58. package/lib/endpoint-ws.js +0 -264
  59. package/lib/endpoint-ws.js.map +0 -1
  60. package/lib/endpoint-wss.d.ts +0 -34
  61. package/lib/endpoint-wss.d.ts.map +0 -1
  62. package/lib/endpoint-wss.js +0 -227
  63. package/lib/endpoint-wss.js.map +0 -1
  64. package/lib/index.d.ts.map +0 -1
  65. package/lib/index.js.map +0 -1
  66. package/lib/segment-mapper.d.ts +0 -2
  67. package/lib/segment-mapper.d.ts.map +0 -1
  68. package/lib/segment-mapper.js +0 -2
  69. package/lib/segment-mapper.js.map +0 -1
  70. package/lib/types.d.ts +0 -75
  71. package/lib/types.d.ts.map +0 -1
  72. package/lib/types.js +0 -5
  73. package/lib/types.js.map +0 -1
  74. package/lib/utils.d.ts +0 -35
  75. package/lib/utils.d.ts.map +0 -1
  76. package/lib/utils.js +0 -166
  77. package/lib/utils.js.map +0 -1
  78. package/plugin.yml +0 -3
  79. package/src/adapter.ts +0 -111
  80. package/src/api.ts +0 -63
  81. package/src/endpoint-sse.ts +0 -232
  82. package/src/endpoint-webhook.ts +0 -225
  83. package/src/endpoint-ws.ts +0 -300
  84. package/src/endpoint-wss.ts +0 -272
  85. package/src/segment-mapper.ts +0 -1
  86. package/src/types.ts +0 -73
  87. package/src/utils.ts +0 -182
  88. /package/{skills/milky → agent}/PERMITS.md +0 -0
  89. /package/{skills/milky/SKILL.md → agent/skills/milky.md} +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,443 @@
1
+ # @zhin.js/adapter-milky
2
+
3
+ ## 4.0.1
4
+
5
+ ### Patch Changes
6
+
7
+ - cc5c94d: 约定式插件运行时迁移(breaking):插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录(`adapters/`、`commands/`、`components/`、`tools/` 等)。
8
+
9
+ - 新增约定式运行时包:`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`(首版 1.0.0 走 init-publish,不在本 changeset 内 bump)。
10
+ - 全部 20 个平台适配器改为约定式 `defineAdapter`,旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除;onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
11
+ - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
12
+ - CLI 增加 plugin-runtime host installer(http/database/outbound/schedule/console 等)。
13
+
14
+ 后续加固(同批):
15
+
16
+ - CLI:`zhin runtime start --daemon`(pidfile/崩溃拉起/风暴保护),orphan watchdog 防僵尸进程;legacy `zhin dev` / `zhin start` 已移除(含 `zhin restart`),`zhin stop` 兼容新 daemon。
17
+ - 安全:builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`(声明式策略表,deny 优先);审计日志 close flush + 背压队列;`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
18
+ - 日志:Logger 双堆栈修复、本地时区、`getLogger` 挂树(`setLevel` 递归生效)、第三方库(log4js/discord)桥接、启动人读总结。
19
+ - 结构:`plugins/games/shared` 迁为 `packages/game-kit`(`@zhin.js/game-kit`);死目录 `plugins/adapters/common` 删除。
20
+ - 脚手架:`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态(minimal-bot 同构,新配置格式)。
21
+ - Console:endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
22
+
23
+ 注:按仓库发布惯例(见 1bb345dd2),本次 breaking 迁移统一使用 patch,避免 zhin.js 5.0 级联。
24
+
25
+ - 447f3e2: 迁移缺口修复(legacy 功能对齐):
26
+
27
+ - html 段出站规范化:经 `@zhin.js/html-renderer` 渲染为 image 段(sandbox 豁免、无渲染器时降级文本),修复真实平台 `[object Object]`。
28
+ - 群聊 @ 触发 AI:适配器入站标注 `metadata.mentioned`(icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori),`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords(默认值与 legacy 对齐)。
29
+ - im_transcripts 全量流水恢复写入(chat_history 工具可用);群聊旁听上下文回迁。
30
+ - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效;masters/trusted 角色解析对齐 legacy。
31
+ - `Message.sender` 统一为用户 ID(onebot11/12、napcat、milky 原误传显示名);quote_id 经 metadata 接入 AI 引用上下文。
32
+
33
+ - Updated dependencies [16ec4e8]
34
+ - Updated dependencies [cc5c94d]
35
+ - Updated dependencies [447f3e2]
36
+ - @zhin.js/core@1.3.5
37
+ - @zhin.js/agent@1.0.4
38
+ - @zhin.js/host-http@1.0.1
39
+ - zhin.js@4.1.3
40
+ - @zhin.js/logger@1.0.75
41
+ - @zhin.js/plugin-runtime@1.0.1
42
+ - @zhin.js/adapter@1.0.1
43
+
44
+ ## 3.0.2
45
+
46
+ ### Patch Changes
47
+
48
+ - 872c583: fix: 代码格式优化
49
+ - Updated dependencies [872c583]
50
+ - Updated dependencies [872c583]
51
+ - @zhin.js/agent@1.0.3
52
+ - @zhin.js/host-router@2.0.3
53
+ - zhin.js@4.1.2
54
+
55
+ ## 3.0.1
56
+
57
+ ### Patch Changes
58
+
59
+ - 5cc9c03: fix: ai 优化
60
+ - b9b3881: fix: 增加游戏引擎以及部分游戏
61
+ - Updated dependencies [5cc9c03]
62
+ - Updated dependencies [7700903]
63
+ - @zhin.js/host-router@2.0.2
64
+ - zhin.js@4.1.1
65
+
66
+ ## 3.0.0
67
+
68
+ ### Patch Changes
69
+
70
+ - c4575c9: fix: 输入输出优化,文档优化
71
+ - Updated dependencies [c4575c9]
72
+ - Updated dependencies [c4575c9]
73
+ - @zhin.js/host-router@2.0.1
74
+ - zhin.js@4.1.0
75
+
76
+ ## 2.0.1
77
+
78
+ ### Patch Changes
79
+
80
+ - Updated dependencies [ae5239c]
81
+ - zhin.js@4.0.1
82
+ - @zhin.js/host-router@2.0.0
83
+
84
+ ## 2.0.0
85
+
86
+ ### Patch Changes
87
+
88
+ - zhin.js@3.0.0
89
+ - @zhin.js/host-router@2.0.0
90
+
91
+ ## 1.0.1
92
+
93
+ ### Patch Changes
94
+
95
+ - d8def69: fix: 性能优化
96
+ - 2ef4896: fix: 更新概念 Bot=>Endpoint,已适配后续更多的业务场景;统一角色权限
97
+ - Updated dependencies [d8def69]
98
+ - Updated dependencies [2ef4896]
99
+ - @zhin.js/host-router@1.0.1
100
+ - zhin.js@2.0.1
101
+
102
+ ## 1.0.0
103
+
104
+ ### Patch Changes
105
+
106
+ - zhin.js@2.0.0
107
+ - @zhin.js/host-router@1.0.0
108
+
109
+ ## 0.0.42
110
+
111
+ ### Patch Changes
112
+
113
+ - Updated dependencies [d8547d2]
114
+ - zhin.js@1.0.92
115
+ - @zhin.js/host-router@0.0.3
116
+
117
+ ## 0.0.41
118
+
119
+ ### Patch Changes
120
+
121
+ - Updated dependencies [3735e96]
122
+ - zhin.js@1.0.91
123
+ - @zhin.js/host-router@0.0.3
124
+
125
+ ## 0.0.40
126
+
127
+ ### Patch Changes
128
+
129
+ - c8f8207: fix: 修复内存泄露问题
130
+ - Updated dependencies [c8f8207]
131
+ - @zhin.js/host-router@0.0.3
132
+ - zhin.js@1.0.90
133
+
134
+ ## 0.0.39
135
+
136
+ ### Patch Changes
137
+
138
+ - Updated dependencies [c78d2cd]
139
+ - @zhin.js/host-router@0.0.2
140
+ - zhin.js@1.0.89
141
+
142
+ ## 0.0.38
143
+
144
+ ### Patch Changes
145
+
146
+ - Updated dependencies [ccb6e24]
147
+ - zhin.js@1.0.88
148
+
149
+ ## 0.0.37
150
+
151
+ ### Patch Changes
152
+
153
+ - 90d9efd: fix: 处理包名
154
+ - zhin.js@1.0.87
155
+ - @zhin.js/host-router@0.0.1
156
+
157
+ ## 0.0.36
158
+
159
+ ### Patch Changes
160
+
161
+ - 7e14f8d: fix: 统一发个版,优化一些列安全问题
162
+ - Updated dependencies [7e14f8d]
163
+ - zhin.js@1.0.86
164
+ - @zhin.js/host-router@1.0.79
165
+
166
+ ## 0.0.35
167
+
168
+ ### Patch Changes
169
+
170
+ - zhin.js@1.0.85
171
+ - @zhin.js/host-router@1.0.78
172
+
173
+ ## 0.0.34
174
+
175
+ ### Patch Changes
176
+
177
+ - 0db9fed: fix: deno deploy
178
+ - f19d2e0: fix: remove multiple runtime support
179
+ - Updated dependencies [0db9fed]
180
+ - Updated dependencies [f19d2e0]
181
+ - zhin.js@1.0.84
182
+ - @zhin.js/host-router@1.0.77
183
+
184
+ ## 0.0.33
185
+
186
+ ### Patch Changes
187
+
188
+ - 775427e: fix: edge 支持
189
+ - Updated dependencies [775427e]
190
+ - @zhin.js/host-router@1.0.76
191
+ - zhin.js@1.0.83
192
+
193
+ ## 0.0.32
194
+
195
+ ### Patch Changes
196
+
197
+ - 32049f5: fix: init publish
198
+ - Updated dependencies [32049f5]
199
+ - @zhin.js/host-router@1.0.75
200
+ - zhin.js@1.0.82
201
+
202
+ ## 0.0.31
203
+
204
+ ### Patch Changes
205
+
206
+ - Updated dependencies [8086ccb]
207
+ - zhin.js@1.0.81
208
+ - @zhin.js/host-router@1.0.74
209
+
210
+ ## 0.0.30
211
+
212
+ ### Patch Changes
213
+
214
+ - zhin.js@1.0.80
215
+ - @zhin.js/host-router@1.0.73
216
+
217
+ ## 0.0.29
218
+
219
+ ### Patch Changes
220
+
221
+ - zhin.js@1.0.79
222
+ - @zhin.js/host-router@1.0.72
223
+
224
+ ## 0.0.28
225
+
226
+ ### Patch Changes
227
+
228
+ - zhin.js@1.0.78
229
+ - @zhin.js/host-router@1.0.71
230
+
231
+ ## 0.0.27
232
+
233
+ ### Patch Changes
234
+
235
+ - zhin.js@1.0.77
236
+ - @zhin.js/host-router@1.0.70
237
+
238
+ ## 0.0.26
239
+
240
+ ### Patch Changes
241
+
242
+ - Updated dependencies [cb9fbf1]
243
+ - zhin.js@1.0.76
244
+ - @zhin.js/host-router@1.0.69
245
+
246
+ ## 0.0.25
247
+
248
+ ### Patch Changes
249
+
250
+ - zhin.js@1.0.75
251
+ - @zhin.js/host-router@1.0.68
252
+
253
+ ## 0.0.24
254
+
255
+ ### Patch Changes
256
+
257
+ - Updated dependencies [c9dec38]
258
+ - zhin.js@1.0.74
259
+ - @zhin.js/host-router@1.0.67
260
+
261
+ ## 0.0.23
262
+
263
+ ### Patch Changes
264
+
265
+ - f1e9a76: fix: 提高 skill 质量
266
+ - zhin.js@1.0.73
267
+ - @zhin.js/host-router@1.0.66
268
+
269
+ ## 0.0.22
270
+
271
+ ### Patch Changes
272
+
273
+ - abc75a4: fix: 优化,客户端构建优化
274
+
275
+ ## 0.0.21
276
+
277
+ ### Patch Changes
278
+
279
+ - e28fd7c: fix: 重新发版
280
+ - Updated dependencies [e28fd7c]
281
+ - zhin.js@1.0.72
282
+ - @zhin.js/host-router@1.0.65
283
+
284
+ ## 0.0.20
285
+
286
+ ### Patch Changes
287
+
288
+ - 4304825: fix: 重新发版
289
+ - Updated dependencies [4304825]
290
+ - zhin.js@1.0.71
291
+ - @zhin.js/host-router@1.0.64
292
+
293
+ ## 0.0.19
294
+
295
+ ### Patch Changes
296
+
297
+ - zhin.js@1.0.68
298
+ - @zhin.js/host-router@1.0.63
299
+
300
+ ## 0.0.18
301
+
302
+ ### Patch Changes
303
+
304
+ - Updated dependencies [0eba6d6]
305
+ - @zhin.js/host-router@1.0.62
306
+ - zhin.js@1.0.67
307
+
308
+ ## 0.0.17
309
+
310
+ ### Patch Changes
311
+
312
+ - zhin.js@1.0.66
313
+ - @zhin.js/host-router@1.0.61
314
+
315
+ ## 0.0.16
316
+
317
+ ### Patch Changes
318
+
319
+ - zhin.js@1.0.65
320
+ - @zhin.js/host-router@1.0.60
321
+
322
+ ## 0.0.15
323
+
324
+ ### Patch Changes
325
+
326
+ - 9577eba: fix: tool 收集 bug,升级 ts 到 6.0.2
327
+ - Updated dependencies [9577eba]
328
+ - zhin.js@1.0.64
329
+ - @zhin.js/host-router@1.0.59
330
+
331
+ ## 0.0.14
332
+
333
+ ### Patch Changes
334
+
335
+ - Updated dependencies [ba30934]
336
+ - @zhin.js/host-router@1.0.58
337
+ - zhin.js@1.0.63
338
+
339
+ ## 0.0.13
340
+
341
+ ### Patch Changes
342
+
343
+ - zhin.js@1.0.62
344
+ - @zhin.js/host-router@1.0.57
345
+
346
+ ## 0.0.12
347
+
348
+ ### Patch Changes
349
+
350
+ - zhin.js@1.0.61
351
+ - @zhin.js/host-router@1.0.56
352
+
353
+ ## 0.0.11
354
+
355
+ ### Patch Changes
356
+
357
+ - 5073d4c: chore: chore: update TypeScript version to ^5.9.3 across all plugins and packages
358
+ feat: enhance ai-text-as-image output registration with off handler for cleanup
359
+ fix: remove unnecessary logging in ensureBuiltinFontsCached function
360
+ refactor: simplify action handlers in html-renderer tools
361
+ chore: add README files for queue-sandbox-poc and event-delivery packages
362
+ chore: adjust pnpm workspace configuration to exclude games directory
363
+ chore: update tsconfig to include plugins directory for TypeScript compilation
364
+ - Updated dependencies [5073d4c]
365
+ - zhin.js@1.0.60
366
+ - @zhin.js/host-router@1.0.55
367
+
368
+ ## 0.0.10
369
+
370
+ ### Patch Changes
371
+
372
+ - c212bf7: fix: 适配器优化
373
+ - Updated dependencies [c212bf7]
374
+ - zhin.js@1.0.59
375
+ - @zhin.js/host-router@1.0.54
376
+
377
+ ## 0.0.9
378
+
379
+ ### Patch Changes
380
+
381
+ - zhin.js@1.0.58
382
+ - @zhin.js/host-router@1.0.53
383
+
384
+ ## 0.0.8
385
+
386
+ ### Patch Changes
387
+
388
+ - zhin.js@1.0.57
389
+ - @zhin.js/host-router@1.0.52
390
+
391
+ ## 0.0.7
392
+
393
+ ### Patch Changes
394
+
395
+ - zhin.js@1.0.56
396
+ - @zhin.js/host-router@1.0.51
397
+
398
+ ## 0.0.6
399
+
400
+ ### Patch Changes
401
+
402
+ - zhin.js@1.0.55
403
+ - @zhin.js/host-router@1.0.50
404
+
405
+ ## 0.0.5
406
+
407
+ ### Patch Changes
408
+
409
+ - 16c8f92: fix: 统一发一次版
410
+ - Updated dependencies [16c8f92]
411
+ - zhin.js@1.0.54
412
+ - @zhin.js/host-router@1.0.49
413
+
414
+ ## 0.0.4
415
+
416
+ ### Patch Changes
417
+
418
+ - zhin.js@1.0.53
419
+ - @zhin.js/host-router@1.0.48
420
+
421
+ ## 0.0.3
422
+
423
+ ### Patch Changes
424
+
425
+ - a3511a0: 各包内 Agent 技能说明已固定为随包发布的 `skills/*/SKILL.md`(替代已移除的运行时 `declareSkill`)。本批为 registry / 分发侧对齐的 **patch** 版本递增。
426
+ - Updated dependencies [a3511a0]
427
+ - @zhin.js/host-router@1.0.47
428
+
429
+ ## 0.0.2
430
+
431
+ ### Patch Changes
432
+
433
+ - Updated dependencies [bb6bfa8]
434
+ - Updated dependencies [bb6bfa8]
435
+ - zhin.js@1.0.52
436
+ - @zhin.js/host-router@1.0.46
437
+
438
+ ## 0.0.1
439
+
440
+ ### Patch Changes
441
+
442
+ - zhin.js@1.0.51
443
+ - @zhin.js/host-router@1.0.45
package/README.md CHANGED
@@ -1,44 +1,37 @@
1
1
  # @zhin.js/adapter-milky
2
2
 
3
- Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器,**一个适配器**支持 WebSocket 正向/反向、SSE、Webhook 四种连接方式,由配置项 `connection` 区分;支持 HTTP API 调用与 `access_token` 鉴权。
3
+ Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器(Plugin Runtime)。默认 **正向 WebSocket 客户端**(`connection: ws`);亦支持 **Webhook**、**反向 WS**(经 `httpHostToken`)与 **SSE**(HTTP GET `/event`,fetch 解析 `text/event-stream`)。
4
4
 
5
5
  ## 功能特性
6
6
 
7
- - 🔌 Milky 协议兼容([通信说明](https://milky.ntqqrev.org/guide/communication))
8
- - 📦 **单一适配器**:`context: milky`,通过 `connection` 选择连接方式
9
- - 🌐 **WebSocket 正向**(`connection: ws`):应用连协议端 `ws(s)://baseUrl/event`
10
- - 📡 **SSE**(`connection: sse`):应用 GET 协议端 `/event`
11
- - 📮 **Webhook**(`connection: webhook`):应用提供 POST 端点收事件
12
- - 🔄 **WebSocket 反向**(`connection: wss`):应用开 WS 服务端,协议端来连
13
- - 🔐 `access_token` 鉴权(Header 或 query)
14
- - 📨 群聊 / 私聊消息收发与消息段映射
15
- - 🛠️ HTTP API 封装,供发消息、撤回、群管等复用
7
+ - [Milky 协议](https://milky.ntqqrev.org/guide/communication) 兼容(事件 + HTTP API
8
+ - 约定式 `defineAdapter` / `definePlugin`(无需 `usePlugin`)
9
+ - **正向 WebSocket**(`connection: ws`):应用连协议端 `ws(s)://baseUrl/event`
10
+ - `access_token` 鉴权(Bearer + query)
11
+ - 入站经 `messageGatewayToken`;出站 `send({ target, payload })` → HTTP `send_*_message`
16
12
 
17
13
  ## 安装
18
14
 
19
15
  ```bash
20
- pnpm add @zhin.js/adapter-milky ws eventsource
16
+ pnpm add @zhin.js/adapter-milky
21
17
  ```
22
18
 
23
- 适配器依赖 `@zhin.js/host-router` 提供的 `router` 才能注册(Webhook/反向 WS 需挂路由),请同时启用 HTTP 服务:
19
+ ## Plugin Runtime
24
20
 
25
- ```bash
26
- pnpm add @zhin.js/host-router
27
- ```
28
-
29
- ## 配置
21
+ - `@zhin.js/adapter` — 约定式 `adapters/milky.ts`(`defineAdapter`)
22
+ - `@zhin.js/core` — `messageGatewayToken` 入站/出站
23
+ - `@zhin.js/plugin-runtime` — `plugin.ts`(`definePlugin`)
24
+ - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
30
25
 
31
- 所有 Endpoint 使用 **同一 context:`milky`**,通过 **`connection`** 区分连接方式。
26
+ 入站:`gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata })`
27
+ 出站:`send({ target, payload })` → HTTP `send_private_message` / `send_group_message`(payload 已由 gateway/core 渲染;无 segment-mapper)
32
28
 
33
- ### WebSocket 正向
29
+ ## 最小配置
34
30
 
35
31
  ```yaml
32
+ # zhin.config.yml(Plugin Runtime)
36
33
  plugins:
37
- - "@zhin.js/host-router"
38
- - "@zhin.js/adapter-milky"
39
-
40
- endpoints:
41
- - context: milky
34
+ milky:
42
35
  connection: ws
43
36
  name: milky-bot
44
37
  baseUrl: "http://127.0.0.1:8080"
@@ -47,112 +40,38 @@ endpoints:
47
40
  heartbeat_interval: 30000
48
41
  ```
49
42
 
50
- ### SSE
51
-
52
- ```yaml
53
- endpoints:
54
- - context: milky
55
- connection: sse
56
- name: milky-sse-bot
57
- baseUrl: "http://127.0.0.1:8080"
58
- access_token: "${MILKY_ACCESS_TOKEN}"
59
- ```
43
+ 根插件 `zhin.plugins`(或项目图)需引用 `@zhin.js/adapter-milky`(`instanceKey: milky`)。
60
44
 
61
- ### Webhook
45
+ ## 连接方式
62
46
 
63
- ```yaml
64
- endpoints:
65
- - context: milky
66
- connection: webhook
67
- name: milky-webhook-bot
68
- baseUrl: "http://协议端地址"
69
- path: "/milky/webhook" # 应用接收事件的 POST 路径
70
- access_token: "${MILKY_ACCESS_TOKEN}"
71
- ```
72
-
73
- ### WebSocket 反向
74
-
75
- ```yaml
76
- endpoints:
77
- - context: milky
78
- connection: wss
79
- name: milky-wss-bot
80
- baseUrl: "http://协议端地址"
81
- path: "/milky/event" # 应用 WS 服务端路径
82
- access_token: "${MILKY_ACCESS_TOKEN}"
83
- heartbeat_interval: 30000
84
- ```
47
+ | connection | 状态 |
48
+ |------------|------|
49
+ | `ws` | 已实现(推荐) |
50
+ | `sse` | HTTP GET `/event`(`Accept: text/event-stream`) || `webhook` | 已实现:POST 入站 + baseUrl HTTP API 出站 |
51
+ | `wss` | 已实现:反向 WS(httpHostToken) |
85
52
 
86
53
  ## 鉴权
87
54
 
88
- 所有连接方式统一支持:
89
-
90
- - **Header**:`Authorization: Bearer {access_token}`
91
- - **Query**:`access_token=xxx`
92
-
93
- 建议配置 `access_token`,并与协议端一致。
94
-
95
- ## 连接方式对比
96
-
97
- | connection | 说明 |
98
- |------------|--------------------------------|
99
- | `ws` | 应用主动连协议端 `/event` |
100
- | `sse` | 应用 GET `/event` 拉取事件流 |
101
- | `webhook` | 协议端 POST 到应用配置的 path |
102
- | `wss` | 协议端连应用提供的 WS path |
55
+ - **Bearer**:`Authorization: Bearer <access_token>`
56
+ - 正向 WS 在 Upgrade 时附带请求头,并在 URL query 写入 `access_token`
57
+ - HTTP API 同样使用 Header / query 鉴权
103
58
 
104
- ## 使用示例
59
+ ## 消息 ID
105
60
 
106
- ### 消息处理
61
+ `{message_scene}:{peer_id}:{message_seq}`(如 `group:123456:10001`)。
107
62
 
108
- ```typescript
109
- import { addCommand, MessageCommand } from 'zhin.js'
110
-
111
- addCommand(new MessageCommand('hello <name:text>')
112
- .action(async (message, result) => {
113
- return `你好,${result.params.name}!`
114
- })
115
- )
116
- ```
117
-
118
- ### 发送消息段
119
-
120
- ```typescript
121
- addCommand(new MessageCommand('pic')
122
- .action(async () => {
123
- return [
124
- { type: 'text', data: { text: '图片:' } },
125
- { type: 'image', data: { url: 'https://example.com/img.png' } }
126
- ]
127
- })
128
- )
129
- ```
63
+ ## AI 工具
130
64
 
131
- 发消息、撤回、群管等通过适配器封装的 HTTP API 完成。群管能力通过 `ISceneManagement` 自动注册为工具,详见 [工具与技能](/advanced/tools-skills)。
65
+ | 类别 | 路径 |
66
+ |------|------|
67
+ | Permit 词汇 | `agent/PERMITS.md` |
68
+ | 技能说明 | `agent/skills/milky.md` |
132
69
 
133
- ## 消息 ID 格式
134
-
135
- `{message_scene}:{peer_id}:{message_seq}`(如 `group:123456:10001`)。撤回时使用该 ID。
136
-
137
- ## 协议与 API 参考
70
+ ## 文档链接
138
71
 
139
72
  - [Milky 快速开始](https://milky.ntqqrev.org/)
140
73
  - [Milky 通信](https://milky.ntqqrev.org/guide/communication)
141
- - [事件结构](https://milky.ntqqrev.org/struct/Event)、[接收消息](https://milky.ntqqrev.org/struct/IncomingMessage)、[消息 API](https://milky.ntqqrev.org/api/message)、[群聊 API](https://milky.ntqqrev.org/api/group)
142
-
143
- ## 依赖项
144
-
145
- - `ws` - WebSocket 客户端/服务端
146
- - `eventsource` - SSE 客户端
147
- - `zhin.js` - Zhin 核心
148
- - `@zhin.js/host-router` - 提供 router,适配器注册依赖
149
-
150
- ## 开发
151
-
152
- ```bash
153
- pnpm build # 构建
154
- pnpm clean # 清理
155
- ```
74
+ - [适配器概览](https://zhin.js.org/essentials/adapters)
156
75
 
157
76
  ## 许可证
158
77
 
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Convention entry: discover `adapters/milky.ts` → defineAdapter.
3
+ */
4
+ import { defineAdapter } from '@zhin.js/adapter';
5
+ import { messageGatewayToken } from '@zhin.js/core/runtime';
6
+ import { httpHostToken } from '@zhin.js/host-http';
7
+ import {
8
+ MilkySseEndpoint,
9
+ MilkyWebhookEndpoint,
10
+ MilkyWssEndpoint,
11
+ MilkyWsEndpoint,
12
+ } from '../src/endpoint.js';
13
+ import {
14
+ resolveMilkyConfig,
15
+ type MilkyAdapterConfig,
16
+ } from '../src/protocol.js';
17
+
18
+ export {
19
+ MilkySseEndpoint,
20
+ MilkyWebhookEndpoint,
21
+ MilkyWssEndpoint,
22
+ MilkyWsEndpoint,
23
+ } from '../src/endpoint.js';
24
+ export type {
25
+ CreateMilkySseStream,
26
+ MilkySseEndpointOptions,
27
+ MilkyWebhookEndpointOptions,
28
+ MilkyWssEndpointOptions,
29
+ MilkyWsEndpointOptions,
30
+ MilkyWsCreateOptions,
31
+ MilkyWsSocket,
32
+ } from '../src/endpoint.js';
33
+
34
+ export default defineAdapter<MilkyAdapterConfig>({
35
+ capabilities: ['inbound', 'outbound'],
36
+ create(context) {
37
+ const config = resolveMilkyConfig(context.config);
38
+ const gateway = context.use(messageGatewayToken);
39
+ if (config.connection === 'webhook') {
40
+ return new MilkyWebhookEndpoint({
41
+ id: context.id,
42
+ gateway,
43
+ http: context.use(httpHostToken),
44
+ config,
45
+ });
46
+ }
47
+ if (config.connection === 'wss') {
48
+ return new MilkyWssEndpoint({
49
+ id: context.id,
50
+ gateway,
51
+ http: context.use(httpHostToken),
52
+ config,
53
+ });
54
+ }
55
+ if (config.connection === 'sse') {
56
+ return new MilkySseEndpoint({
57
+ id: context.id,
58
+ gateway,
59
+ config,
60
+ });
61
+ }
62
+ return new MilkyWsEndpoint({
63
+ id: context.id,
64
+ gateway,
65
+ config,
66
+ });
67
+ },
68
+ });
@@ -0,0 +1,7 @@
1
+ export { MilkyWsEndpoint, type MilkyWsEndpointOptions, } from './ws-endpoint.js';
2
+ export { MilkyWebhookEndpoint, type MilkyWebhookEndpointOptions, } from './webhook-endpoint.js';
3
+ export { MilkyWssEndpoint, type MilkyWssEndpointOptions, } from './wss-endpoint.js';
4
+ export { MilkySseEndpoint, type MilkySseEndpointOptions, type CreateMilkySseStream, } from './sse-endpoint.js';
5
+ export type { MilkyWsSocket, MilkyWsCreateOptions } from './ws-types.js';
6
+ export { verifyMilkyAccessToken, readRequestBody } from './milky-auth.js';
7
+ export { openSseStream, consumeSseBuffer } from './sse-client.js';