@zhin.js/core 1.5.16 → 1.7.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 (334) hide show
  1. package/README.md +78 -195
  2. package/lib/ai-completion-contract.d.ts +135 -0
  3. package/lib/ai-completion-contract.js +69 -0
  4. package/lib/built/ai-access.d.ts +2 -21
  5. package/lib/built/ai-access.js +1 -46
  6. package/lib/built/ai-outbound/index.d.ts +0 -2
  7. package/lib/built/ai-outbound/index.js +0 -2
  8. package/lib/built/ai-outbound/prompt.d.ts +2 -0
  9. package/lib/built/ai-outbound/prompt.js +2 -0
  10. package/lib/built/ai-outbound/types.d.ts +1 -10
  11. package/lib/built/ai-trigger.d.ts +39 -78
  12. package/lib/built/ai-trigger.js +3 -254
  13. package/lib/built/common-adapter-tools.d.ts +21 -6
  14. package/lib/built/common-adapter-tools.js +28 -17
  15. package/lib/built/generic-segment-mapper.js +4 -1
  16. package/lib/built/html-segment-fallback.d.ts +6 -7
  17. package/lib/built/html-segment-fallback.js +1 -16
  18. package/lib/built/html-to-text.d.ts +0 -3
  19. package/lib/built/html-to-text.js +131 -40
  20. package/lib/built/interaction-messages.d.ts +1 -0
  21. package/lib/built/interaction-messages.js +30 -0
  22. package/lib/built/interactive-segments/action.d.ts +3 -4
  23. package/lib/built/interactive-segments/action.js +2 -5
  24. package/lib/built/interactive-segments/index.d.ts +0 -2
  25. package/lib/built/interactive-segments/index.js +0 -2
  26. package/lib/built/interactive-segments/keyboard-segment.d.ts +0 -1
  27. package/lib/built/interactive-segments/keyboard-segment.js +0 -1
  28. package/lib/built/interactive-segments/onebot-keyboard.d.ts +0 -1
  29. package/lib/built/interactive-segments/onebot-keyboard.js +0 -2
  30. package/lib/built/interactive-segments/resolve.d.ts +2 -3
  31. package/lib/built/interactive-segments/resolve.js +21 -14
  32. package/lib/built/interactive-segments/types.d.ts +2 -7
  33. package/lib/built/interactive-segments/types.js +22 -2
  34. package/lib/built/login-assist.d.ts +330 -25
  35. package/lib/built/login-assist.js +1156 -75
  36. package/lib/built/login-captcha.d.ts +62 -0
  37. package/lib/built/login-captcha.js +107 -0
  38. package/lib/built/message-enrich.d.ts +24 -27
  39. package/lib/built/message-enrich.js +53 -49
  40. package/lib/built/outbound-content-arrays.d.ts +4 -0
  41. package/lib/built/outbound-content-arrays.js +32 -0
  42. package/lib/built/outbound-media-trust.d.ts +46 -0
  43. package/lib/built/outbound-media-trust.js +245 -0
  44. package/lib/built/outbound-media-utils.d.ts +5 -3
  45. package/lib/built/outbound-media-utils.js +5 -3
  46. package/lib/built/readable-link.d.ts +4 -0
  47. package/lib/built/readable-link.js +32 -0
  48. package/lib/built/rich-segments/markdown-to-text.d.ts +1 -2
  49. package/lib/built/rich-segments/markdown-to-text.js +141 -17
  50. package/lib/built/roles.d.ts +141 -12
  51. package/lib/built/roles.js +253 -52
  52. package/lib/built/segment-contract/assert.js +8 -2
  53. package/lib/built/segment-contract/delivery.js +1 -0
  54. package/lib/built/segment-contract/index.d.ts +3 -3
  55. package/lib/built/segment-contract/index.js +2 -2
  56. package/lib/built/segment-contract/json-schema.d.ts +39 -5
  57. package/lib/built/segment-contract/json-schema.js +207 -24
  58. package/lib/built/segment-contract/preview.js +8 -1
  59. package/lib/built/segment-contract/text.js +1 -1
  60. package/lib/built/segment-contract/types.d.ts +2 -2
  61. package/lib/built/segment-contract/validate.d.ts +1553 -224
  62. package/lib/built/segment-contract/validate.js +39 -3
  63. package/lib/built/tool-access.d.ts +5 -0
  64. package/lib/built/tool-access.js +17 -0
  65. package/lib/built/user-interaction.d.ts +5 -4
  66. package/lib/built/user-interaction.js +64 -52
  67. package/lib/errors.d.ts +1 -18
  68. package/lib/errors.js +1 -26
  69. package/lib/feature/command-public-api.d.ts +5 -0
  70. package/lib/feature/command-public-api.js +5 -0
  71. package/lib/feature/command.d.ts +2 -0
  72. package/lib/feature/command.js +1 -0
  73. package/lib/feature/component.d.ts +1 -0
  74. package/lib/feature/component.js +1 -0
  75. package/lib/feature/handler.d.ts +13 -7
  76. package/lib/feature/handler.js +2 -1
  77. package/lib/feature/middleware-public-api.d.ts +6 -0
  78. package/lib/feature/middleware-public-api.js +6 -0
  79. package/lib/feature/middleware.d.ts +22 -2
  80. package/lib/feature/middleware.js +7 -2
  81. package/lib/im-scene.d.ts +4 -3
  82. package/lib/im-scene.js +9 -9
  83. package/lib/im-session-id.d.ts +20 -12
  84. package/lib/im-session-id.js +8 -8
  85. package/lib/index.d.ts +20 -48
  86. package/lib/index.js +15 -41
  87. package/lib/jsx/intrinsic-elements.d.ts +83 -0
  88. package/lib/jsx/message-renderer.d.ts +13 -0
  89. package/lib/jsx/message-renderer.js +128 -0
  90. package/lib/jsx/message-tags.d.ts +133 -0
  91. package/lib/jsx/message-tags.js +50 -0
  92. package/lib/jsx-dev-runtime.d.ts +2 -2
  93. package/lib/jsx-dev-runtime.js +1 -2
  94. package/lib/jsx-runtime.d.ts +2 -12
  95. package/lib/jsx-runtime.js +1 -10
  96. package/lib/jsx.d.ts +6 -30
  97. package/lib/jsx.js +3 -93
  98. package/lib/message.d.ts +0 -40
  99. package/lib/message.js +1 -27
  100. package/lib/models/system-log.d.ts +0 -2
  101. package/lib/models/system-log.js +1 -8
  102. package/lib/models/user.d.ts +0 -2
  103. package/lib/models/user.js +1 -7
  104. package/lib/notice.d.ts +38 -33
  105. package/lib/notice.js +23 -7
  106. package/lib/plugin-runtime/im/command-feedback.d.ts +59 -0
  107. package/lib/plugin-runtime/im/command-feedback.js +148 -0
  108. package/lib/plugin-runtime/im/contracts.d.ts +217 -32
  109. package/lib/plugin-runtime/im/contracts.js +141 -23
  110. package/lib/plugin-runtime/im/conversation-runtime.d.ts +42 -0
  111. package/lib/plugin-runtime/im/conversation-runtime.js +451 -0
  112. package/lib/plugin-runtime/im/endpoint-runtime.d.ts +112 -0
  113. package/lib/plugin-runtime/im/endpoint-runtime.js +434 -0
  114. package/lib/plugin-runtime/im/feature-gate.d.ts +21 -0
  115. package/lib/plugin-runtime/im/feature-gate.js +88 -0
  116. package/lib/plugin-runtime/im/host/component-host-installer.d.ts +2 -0
  117. package/lib/plugin-runtime/im/host/component-host-installer.js +14 -0
  118. package/lib/plugin-runtime/im/host/conversation-migration.d.ts +5 -0
  119. package/lib/plugin-runtime/im/host/conversation-migration.js +75 -0
  120. package/lib/plugin-runtime/im/host/database-config.d.ts +10 -0
  121. package/lib/plugin-runtime/im/host/database-config.js +152 -0
  122. package/lib/plugin-runtime/im/host/database-console-schema.d.ts +79 -0
  123. package/lib/plugin-runtime/im/host/database-console-schema.js +477 -0
  124. package/lib/plugin-runtime/im/host/database-console-sql.d.ts +66 -0
  125. package/lib/plugin-runtime/im/host/database-console-sql.js +459 -0
  126. package/lib/plugin-runtime/im/host/database-host-installer.d.ts +60 -0
  127. package/lib/plugin-runtime/im/host/database-host-installer.js +1166 -0
  128. package/lib/plugin-runtime/im/host/database-state.d.ts +9 -0
  129. package/lib/plugin-runtime/im/host/database-state.js +91 -0
  130. package/lib/plugin-runtime/im/host/index.d.ts +8 -0
  131. package/lib/plugin-runtime/im/host/index.js +8 -0
  132. package/lib/plugin-runtime/im/host/locale-host-installer.d.ts +3 -0
  133. package/lib/plugin-runtime/im/host/locale-host-installer.js +60 -0
  134. package/lib/plugin-runtime/im/host/outbound-host-installer.d.ts +8 -0
  135. package/lib/plugin-runtime/im/host/outbound-host-installer.js +153 -0
  136. package/lib/plugin-runtime/im/host/sender-enrichment.d.ts +34 -0
  137. package/lib/plugin-runtime/im/host/sender-enrichment.js +82 -0
  138. package/lib/plugin-runtime/im/im-runtime.d.ts +40 -111
  139. package/lib/plugin-runtime/im/im-runtime.js +235 -1059
  140. package/lib/plugin-runtime/im/inbound-dedup.d.ts +84 -0
  141. package/lib/plugin-runtime/im/inbound-dedup.js +322 -0
  142. package/lib/plugin-runtime/im/inbound-origin.d.ts +150 -0
  143. package/lib/plugin-runtime/im/inbound-origin.js +183 -0
  144. package/lib/plugin-runtime/im/inbound-runtime.d.ts +59 -0
  145. package/lib/plugin-runtime/im/inbound-runtime.js +478 -0
  146. package/lib/plugin-runtime/im/inbound-spine.d.ts +196 -0
  147. package/lib/plugin-runtime/im/inbound-spine.js +335 -0
  148. package/lib/plugin-runtime/im/index.d.ts +15 -4
  149. package/lib/plugin-runtime/im/index.js +11 -4
  150. package/lib/plugin-runtime/im/interaction-runtime.d.ts +50 -0
  151. package/lib/plugin-runtime/im/interaction-runtime.js +390 -0
  152. package/lib/plugin-runtime/im/interactive-router.d.ts +81 -0
  153. package/lib/plugin-runtime/im/interactive-router.js +382 -0
  154. package/lib/plugin-runtime/im/message-diagnostics.d.ts +70 -0
  155. package/lib/plugin-runtime/im/message-diagnostics.js +182 -0
  156. package/lib/plugin-runtime/im/message-dispatcher.d.ts +18 -4
  157. package/lib/plugin-runtime/im/message-dispatcher.js +138 -20
  158. package/lib/plugin-runtime/im/message-events.d.ts +85 -0
  159. package/lib/plugin-runtime/im/message-events.js +113 -0
  160. package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +39 -0
  161. package/lib/plugin-runtime/im/outbound-delivery-runtime.js +450 -0
  162. package/lib/plugin-runtime/im/outbound-renderer.d.ts +52 -3
  163. package/lib/plugin-runtime/im/outbound-renderer.js +188 -8
  164. package/lib/plugin-runtime/im/outbound-segments.d.ts +29 -5
  165. package/lib/plugin-runtime/im/outbound-segments.js +130 -36
  166. package/lib/plugin-runtime/im/progressive-reply.d.ts +58 -0
  167. package/lib/plugin-runtime/im/progressive-reply.js +501 -0
  168. package/lib/plugin-runtime/im/public-api.d.ts +1 -1
  169. package/lib/request.d.ts +27 -36
  170. package/lib/request.js +14 -6
  171. package/lib/side-event/base.d.ts +64 -44
  172. package/lib/side-event/base.js +72 -19
  173. package/lib/side-event/index.d.ts +1 -1
  174. package/lib/side-event/index.js +1 -1
  175. package/lib/side-event/normalize.d.ts +7 -38
  176. package/lib/side-event/normalize.js +4 -109
  177. package/lib/side-event/scene-events.d.ts +40 -0
  178. package/lib/side-event/scene-events.js +147 -0
  179. package/lib/side-event/types.d.ts +4 -13
  180. package/lib/side-event/types.js +1 -55
  181. package/lib/system-event.d.ts +17 -12
  182. package/lib/system-event.js +8 -6
  183. package/lib/types.d.ts +23 -167
  184. package/lib/utils.d.ts +50 -33
  185. package/lib/utils.js +12 -185
  186. package/lib/venue/contracts.d.ts +21 -0
  187. package/lib/venue/contracts.js +3 -0
  188. package/lib/venue/floor-controller.d.ts +11 -0
  189. package/lib/venue/floor-controller.js +63 -0
  190. package/lib/venue/index.d.ts +13 -0
  191. package/lib/venue/index.js +11 -0
  192. package/lib/venue/membership-port.d.ts +23 -0
  193. package/lib/venue/membership-port.js +141 -0
  194. package/lib/venue/projector.d.ts +38 -0
  195. package/lib/venue/projector.js +45 -0
  196. package/lib/venue/registry.d.ts +16 -0
  197. package/lib/venue/registry.js +63 -0
  198. package/lib/venue/router.d.ts +19 -0
  199. package/lib/venue/router.js +101 -0
  200. package/lib/venue/send-limiter.d.ts +17 -0
  201. package/lib/venue/send-limiter.js +73 -0
  202. package/lib/venue/validator.d.ts +6 -0
  203. package/lib/venue/validator.js +160 -0
  204. package/package.json +24 -50
  205. package/lib/adapter.d.ts +0 -145
  206. package/lib/adapter.js +0 -377
  207. package/lib/built/adapter-process.d.ts +0 -58
  208. package/lib/built/adapter-process.js +0 -128
  209. package/lib/built/agent-preset.d.ts +0 -64
  210. package/lib/built/agent-preset.js +0 -79
  211. package/lib/built/ai-outbound/adapter-access.d.ts +0 -3
  212. package/lib/built/ai-outbound/adapter-access.js +0 -9
  213. package/lib/built/ai-outbound/extensions/qq-message.d.ts +0 -3
  214. package/lib/built/ai-outbound/extensions/qq-message.js +0 -23
  215. package/lib/built/authorization.d.ts +0 -10
  216. package/lib/built/authorization.js +0 -76
  217. package/lib/built/command.d.ts +0 -72
  218. package/lib/built/command.js +0 -105
  219. package/lib/built/component.d.ts +0 -67
  220. package/lib/built/component.js +0 -97
  221. package/lib/built/config.d.ts +0 -98
  222. package/lib/built/config.js +0 -372
  223. package/lib/built/connect-endpoint-instance.d.ts +0 -17
  224. package/lib/built/connect-endpoint-instance.js +0 -42
  225. package/lib/built/database.d.ts +0 -68
  226. package/lib/built/database.js +0 -106
  227. package/lib/built/dispatcher.d.ts +0 -141
  228. package/lib/built/dispatcher.js +0 -383
  229. package/lib/built/endpoint-commands.d.ts +0 -3
  230. package/lib/built/endpoint-commands.js +0 -99
  231. package/lib/built/endpoint-lifecycle-service.d.ts +0 -28
  232. package/lib/built/endpoint-lifecycle-service.js +0 -242
  233. package/lib/built/endpoint-lifecycle.d.ts +0 -27
  234. package/lib/built/endpoint-lifecycle.js +0 -36
  235. package/lib/built/endpoint-manager.d.ts +0 -34
  236. package/lib/built/html-renderer-loader.d.ts +0 -13
  237. package/lib/built/html-renderer-loader.js +0 -33
  238. package/lib/built/inbound-pipeline.d.ts +0 -37
  239. package/lib/built/inbound-pipeline.js +0 -63
  240. package/lib/built/inbound-runner.d.ts +0 -22
  241. package/lib/built/inbound-runner.js +0 -34
  242. package/lib/built/interactive-segment-contract.d.ts +0 -6
  243. package/lib/built/interactive-segment-contract.js +0 -9
  244. package/lib/built/interactive-segments/fallback-store.d.ts +0 -29
  245. package/lib/built/interactive-segments/fallback-store.js +0 -63
  246. package/lib/built/interactive-segments/handlers.d.ts +0 -16
  247. package/lib/built/interactive-segments/handlers.js +0 -74
  248. package/lib/built/introspection-format.d.ts +0 -10
  249. package/lib/built/introspection-format.js +0 -28
  250. package/lib/built/management-command-guard.d.ts +0 -15
  251. package/lib/built/management-command-guard.js +0 -25
  252. package/lib/built/message-filter.d.ts +0 -176
  253. package/lib/built/message-filter.js +0 -239
  254. package/lib/built/optional-peer-import.d.ts +0 -3
  255. package/lib/built/optional-peer-import.js +0 -33
  256. package/lib/built/outbound-media-contract.d.ts +0 -22
  257. package/lib/built/outbound-media-contract.js +0 -10
  258. package/lib/built/permission.d.ts +0 -51
  259. package/lib/built/permission.js +0 -99
  260. package/lib/built/permit-check.d.ts +0 -7
  261. package/lib/built/permit-check.js +0 -35
  262. package/lib/built/permit-parse.d.ts +0 -16
  263. package/lib/built/permit-parse.js +0 -32
  264. package/lib/built/platform-permit.d.ts +0 -20
  265. package/lib/built/platform-permit.js +0 -91
  266. package/lib/built/queue-im-field-contract.d.ts +0 -32
  267. package/lib/built/queue-im-field-contract.js +0 -67
  268. package/lib/built/rich-segments/adapter-policies.d.ts +0 -9
  269. package/lib/built/rich-segments/adapter-policies.js +0 -27
  270. package/lib/built/rich-segments/base.d.ts +0 -11
  271. package/lib/built/rich-segments/base.js +0 -24
  272. package/lib/built/rich-segments/builtins.d.ts +0 -4
  273. package/lib/built/rich-segments/builtins.js +0 -40
  274. package/lib/built/rich-segments/capabilities.d.ts +0 -6
  275. package/lib/built/rich-segments/capabilities.js +0 -38
  276. package/lib/built/rich-segments/html-segment.d.ts +0 -15
  277. package/lib/built/rich-segments/html-segment.js +0 -62
  278. package/lib/built/rich-segments/index.d.ts +0 -13
  279. package/lib/built/rich-segments/index.js +0 -13
  280. package/lib/built/rich-segments/markdown-segment.d.ts +0 -14
  281. package/lib/built/rich-segments/markdown-segment.js +0 -58
  282. package/lib/built/rich-segments/qrcode-segment.d.ts +0 -18
  283. package/lib/built/rich-segments/qrcode-segment.js +0 -73
  284. package/lib/built/rich-segments/registry.d.ts +0 -16
  285. package/lib/built/rich-segments/registry.js +0 -52
  286. package/lib/built/rich-segments/resolve.d.ts +0 -5
  287. package/lib/built/rich-segments/resolve.js +0 -87
  288. package/lib/built/rich-segments/tts-segment.d.ts +0 -13
  289. package/lib/built/rich-segments/tts-segment.js +0 -51
  290. package/lib/built/rich-segments/types.d.ts +0 -79
  291. package/lib/built/rich-segments/types.js +0 -17
  292. package/lib/built/runtime-io.d.ts +0 -9
  293. package/lib/built/runtime-io.js +0 -67
  294. package/lib/built/schedule.d.ts +0 -54
  295. package/lib/built/schedule.js +0 -112
  296. package/lib/built/schema-endpoint-manager.d.ts +0 -17
  297. package/lib/built/schema-endpoint-manager.js +0 -73
  298. package/lib/built/schema-feature.d.ts +0 -77
  299. package/lib/built/schema-feature.js +0 -130
  300. package/lib/built/skill.d.ts +0 -120
  301. package/lib/built/skill.js +0 -151
  302. package/lib/built/speech-loader.d.ts +0 -14
  303. package/lib/built/speech-loader.js +0 -32
  304. package/lib/built/tool.d.ts +0 -151
  305. package/lib/built/tool.js +0 -388
  306. package/lib/command.d.ts +0 -50
  307. package/lib/command.js +0 -106
  308. package/lib/component.d.ts +0 -26
  309. package/lib/component.js +0 -583
  310. package/lib/endpoint-capabilities.d.ts +0 -46
  311. package/lib/endpoint-capabilities.js +0 -55
  312. package/lib/endpoint.d.ts +0 -19
  313. package/lib/endpoint.js +0 -3
  314. package/lib/host-plugin-registry.d.ts +0 -8
  315. package/lib/host-plugin-registry.js +0 -12
  316. package/lib/plugin-context.d.ts +0 -27
  317. package/lib/plugin-context.js +0 -64
  318. package/lib/plugin-runtime/im/interactive.d.ts +0 -26
  319. package/lib/plugin-runtime/im/interactive.js +0 -46
  320. package/lib/plugin-runtime/im/login-assist-host.d.ts +0 -6
  321. package/lib/plugin-runtime/im/login-assist-host.js +0 -6
  322. package/lib/plugin-runtime/im/message-bus.d.ts +0 -38
  323. package/lib/plugin-runtime/im/message-bus.js +0 -40
  324. package/lib/plugin-runtime/im/service-tokens.d.ts +0 -18
  325. package/lib/plugin-runtime/im/service-tokens.js +0 -13
  326. package/lib/plugin.d.ts +0 -268
  327. package/lib/plugin.js +0 -583
  328. package/lib/schema-interaction.d.ts +0 -117
  329. package/lib/schema-interaction.js +0 -247
  330. package/lib/side-event/dispatch.d.ts +0 -15
  331. package/lib/side-event/dispatch.js +0 -140
  332. package/lib/tool-zod.d.ts +0 -43
  333. package/lib/tool-zod.js +0 -184
  334. /package/lib/{built/endpoint-manager.js → jsx/intrinsic-elements.js} +0 -0
package/README.md CHANGED
@@ -1,256 +1,139 @@
1
1
  # @zhin.js/core
2
2
 
3
- ## Plugin Runtime 子路径
3
+ `@zhin.js/core` 负责组合 Zhin 的 IM 领域:规范化消息、入站分发、出站渲染、交互语义,以及 Plugin Runtime 的 IM Host。它消费独立 Feature 包产生的 generation snapshot,不拥有平台连接或能力注册表。
4
4
 
5
- 新的 owner-aware IM 能力已经并入 Core,作为 Plugin Runtime 的正式领域接口:
5
+ 架构与消息链路分别见:
6
6
 
7
- - `@zhin.js/core/runtime`
7
+ - [分层架构](../../../docs/concepts/architecture.md)
8
+ - [消息流](../../../docs/concepts/message-flow.md)
9
+ - [公开 API 分级](../../../docs/contributing/public-api-surface.md)
8
10
 
9
- `@zhin.js/adapter`、`@zhin.js/command`、`@zhin.js/component` 与
10
- `@zhin.js/middleware` 提供纯 definition、约定发现 provider 和 generation projection;
11
- Core Runtime 只消费它们发布的 snapshot。
12
- 旧根入口的 `addCommand`、`addComponent`、`addMiddleware` 暂时作为作者兼容接口保留,后续
13
- 只向 RuntimeSnapshot 投影,不再维护第二套运行时权威。
11
+ ## 边界
14
12
 
15
- Zhin.js **IM/多通道运行时**包:Plugin、Adapter、**Endpoint**、MessageDispatcher 与统一出站链。**AI 编排(ZhinAgent、工具安全、MCP)在 [`@zhin.js/agent`](../agent/README.md)**;本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
13
+ | 职责 | 所属包 |
14
+ |------|--------|
15
+ | Adapter 声明、Endpoint 生命周期与 `AdapterIndex` | `@zhin.js/adapter` |
16
+ | Command 声明与 `CommandIndex` | `@zhin.js/command` |
17
+ | Middleware / Component / Handler 声明 | 对应 Feature 包 |
18
+ | generation、snapshot、资源与插件生命周期 | `@zhin.js/plugin-runtime` |
19
+ | 消息规范化、渲染、分发与 IM Runtime | `@zhin.js/core` |
20
+ | Agent 编排、工具安全与 MCP | `@zhin.js/agent` |
21
+ | 进程装配 | `@zhin.js/cli` |
16
22
 
17
- 领域词汇见 [CONTEXT.md](./CONTEXT.md);入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。
23
+ Core 不提供第二套 Adapter 基类、Endpoint 类型或进程级注册表。平台插件统一从 `zhin.js/adapter` 导入 `Adapter`、`defineAdapter`、结构 `Endpoint` 与 `endpointSpec`。
18
24
 
19
- ## 核心概念
25
+ ## Plugin Runtime
20
26
 
21
- ### Plugin(插件)— Plugin Runtime
22
-
23
- 唯一启动路径:`zhin runtime start`。`plugin.ts` 必须 default-export `definePlugin()`;能力按约定目录发现。
27
+ 应用入口使用 `definePlugin()`,能力入口放在约定目录中。只有 `$` 开头的文件会被发现,其他文件可作为同目录 helper 安全复用。
24
28
 
25
29
  ```typescript
26
30
  // plugin.ts
27
- import { definePlugin } from '@zhin.js/plugin-runtime'
31
+ import { definePlugin } from 'zhin.js'
28
32
 
29
33
  export default definePlugin({
30
34
  name: 'hello-bot',
31
- metadata: { displayName: 'Hello Bot' },
32
35
  setup(context) {
33
- context.lifecycle.add(() => { /* cleanup */ })
36
+ context.lifecycle.add(() => {
37
+ // release plugin-owned resources
38
+ })
34
39
  },
35
40
  })
36
41
  ```
37
42
 
38
43
  ```typescript
39
- // commands/hello/[name].ts
40
- import { defineCommand } from '@zhin.js/command'
44
+ // commands/hello/index.ts
45
+ import { defineCommand } from 'zhin.js/command'
41
46
 
42
47
  export default defineCommand({
43
48
  description: '打招呼',
44
- params: {
45
- name: { type: 'string' },
46
- },
47
- execute({ params }) {
48
- return `Hello, ${params.name}!`
49
+ execute() {
50
+ return 'Hello!'
49
51
  },
50
52
  })
51
53
  ```
52
54
 
53
- > **已移除**:`usePlugin()` / `getPlugin()` / `bootstrapNode`(`zhin.js/node`)调用即 throw;唯一入口为 `definePlugin` + `zhin runtime start`。`MessageCommand` / `Plugin.addCommand` 仍 deprecated。见 [public-api-surface](../../docs/contributing/public-api-surface.md)。
54
-
55
- 本包仍提供 IM 运行时契约(Message / Adapter / Endpoint);创作面在 Feature 包与 `@zhin.js/plugin-runtime`。
56
-
57
- ### Feature(特性抽象)
58
-
59
- 约定式 Feature(Command / Middleware / Component / Adapter…)由独立包提供 definition + 约定发现;Core Runtime 消费 snapshot。
60
-
61
- 经典 `CommandFeature` / `addCommand` 等仍挂在 `Plugin.prototype`,**已 deprecated**,仅兼容 Agent init / game-kit:
62
-
63
- ```
64
- Feature (抽象基类) — legacy 注册表仍在
65
- ├── CommandFeature — MessageCommand(→ defineCommand)
66
- ├── ToolFeature — AI 工具(→ defineAgentTool)
67
- ├── …
68
- ```
69
-
70
- ```typescript
71
- const toolFeature = plugin.inject('tool')
72
- const off = toolFeature.on('add', (tool, pluginName) => {
73
- console.log(`工具 ${tool.name} 已注册 (来自 ${pluginName})`)
74
- })
75
- toolFeature.on('remove', (tool) => {
76
- console.log(`工具 ${tool.name} 已移除`)
77
- })
78
- ```
55
+ 运行时入口是 `zhin start`(管理网关拉起 `zhin.js/instance`)。Core 的 `@zhin.js/core/runtime` 子路径供实例装配根(`zhin.js/instance`)装配 IM Host,不是插件侧 service locator。
79
56
 
80
- ### 出站消息段:`segment.html`
57
+ ## Adapter 与 Endpoint
81
58
 
82
- 业务插件可返回 **`html` 消息段**,由出站链统一处理转图或文本回退:
59
+ Adapter 是账号配置、CAS 与连接 incarnation 的唯一 owner。Endpoint 继承真实 SDK 或实质协议 Client,并通过 `endpointSpec` / `createEndpointSpecification` 附加框架钩子;不覆盖 SDK 原生事件和 API。当前 generation 的 `AdapterIndex` 提供目录、租约路由和只读 connection 数据,不向普通查询暴露内部生命周期对象。
83
60
 
84
61
  ```typescript
85
- import { segment } from '@zhin.js/core'
86
-
87
- return segment.html({
88
- html: '<div>…</div>', // 必填:Satori 可渲染的 HTML
89
- text: undefined, // 可选:显式回退文本(覆盖自动剥离)
90
- width: 540,
91
- backgroundColor: '#d8dce3',
92
- fileName: 'card.png',
62
+ // adapters/napcat/index.ts
63
+ import { defineAdapter } from 'zhin.js/adapter'
64
+ import { NapcatAdapter } from '../../src/adapter.js'
65
+ import type { NapCatEndpointConfig } from '../../src/protocol.js'
66
+
67
+ export default defineAdapter<NapCatEndpointConfig>({
68
+ capabilities: ['inbound', 'outbound'],
69
+ operations: ['recall'],
70
+ createAdapter: context => new NapcatAdapter(context),
93
71
  })
94
-
95
- // Markdown 段(QQ 等平台 policy 为 origin 时透传)
96
- return segment.markdown('# Title\n\nBody')
97
72
  ```
98
73
 
99
- 出站富媒体段(`qrcode` / `html` / `markdown`)在 **`Adapter.renderSendMessage` 首步** 按各 Adapter 的 **`outboundRichSegmentPolicy`** 统一渲染为 `image` / `text` / `origin`:
100
-
101
- | 渲染模式 | 含义 |
102
- |---------|------|
103
- | `image` | 转为 `image` 段(qrcode 生成 PNG;html/markdown 经 `@zhin.js/html-renderer` 动态转图,未安装则降级 text) |
104
- | `text` | 剥离为纯文本段 |
105
- | `origin` | 原样透传,由 Endpoint 解释(如 QQ markdown、process 终端二维码) |
74
+ `createAdapter` 是唯一工厂。公开 `Endpoint` 没有可继承基类,实际 Native Client 规范示例见 [适配器开发](../../../docs/authoring/adapters.md)。同一个公开 `AdapterRegistry` 推断 Command、Handler、Middleware 和 Tool 的实际 Client 与事件类型,不另建 Client token 或目录。
106
75
 
107
- 默认策略:`qrcode: image`,`html: text`,`markdown: text`。QQ / KOOK 等适配器 override static policy。
76
+ 平台管理、撤回、编辑、reaction 与 typing 通过 specification 的显式 capability/control 端口暴露。调用者通过 `AdapterIndex.management/control` 获取捕获真实 incarnation 的受租约保护端口,不能从只读 connection 数据取未受保护的操作。普通业务消息继续走统一出站链路。
108
77
 
109
- - 安装 **`@zhin.js/html-renderer`** 且 policy 为 `html: 'image'` 时,core 在首步动态 import 并转 PNG。
110
- - policy 为 `html: 'text'` 时等价于 **`coerceHtmlSegmentsToText`** / **`htmlToFallbackText`**。
111
- - 日志预览:`[html-card]`、`[qrcode]`、`[markdown]` + 摘要(前 80 字)。
78
+ ## 消息链路
112
79
 
113
- #### 扩展新 Rich Segment(长期方案)
80
+ 入站由 Endpoint 发出结构化事件,Core Runtime 完成身份附加、消息规范化和 generation 准入,然后依次执行 Middleware、Command、Handler 与可选 Agent 路由。
114
81
 
115
- 内置 kind 通过 **`richSegmentRegistry`** 注册;optional 能力通过 **`registerRichSegmentCapabilityLoader`** 注入(与 `@zhin.js/html-renderer` 同模式)。
82
+ 出站统一经过:
116
83
 
117
- ```typescript
118
- import {
119
- RichSegment,
120
- registerRichSegmentKind,
121
- registerRichSegmentCapabilityLoader,
122
- RICH_SEGMENT_MODE,
123
- segment,
124
- } from '@zhin.js/core';
125
-
126
- // 1. 内置 capability:speech(@zhin.js/speech)已注册,tts kind 已内置
127
- // 可选:注册 ffmpeg 等
128
- registerRichSegmentCapabilityLoader('media-pipeline', async (opts) => {
129
- const { createMediaPipeline } = await import('@zhin.js/media-pipeline');
130
- return createMediaPipeline(opts.getConfig?.());
131
- });
132
-
133
- // 2. 使用内置 segment.tts(Adapter policy 决定 audio/text/origin)
134
- // segment.tts({ text: '你好' })
135
- class MyAdapter extends Adapter {
136
- static override outboundRichSegmentPolicy = {
137
- tts: 'audio',
138
- qrcode: 'image', // 其余 kind 用 registry 默认值
139
- };
140
- }
84
+ ```text
85
+ Message.$reply / OutboundMessageService
86
+ → component render
87
+ → canonical segment normalization
88
+ → before.sendMessage middleware
89
+ → AdapterIndex.send
90
+ → Endpoint specification send hook
141
91
  ```
142
92
 
143
- **分工**:Rich Segment 负责「语义段 → 标准 IM 段」;Endpoint `materializeOutboundMedia` 负责「已有 audio/video/file → 平台上传」。
144
-
145
- ### Adapter(适配器)
93
+ 任何平台发送都必须经过这条链路。
146
94
 
147
- 适配器将不同聊天平台接入 Zhin.js,统一消息收发接口。
95
+ ## 语义消息段
148
96
 
149
- ```typescript
150
- // 适配器通过 Adapter.register 静态注册
151
- Adapter.register('my-platform', MyAdapter)
152
- ```
153
-
154
- 每个适配器可以通过 `addTool()` 注册平台特有工具,标准群管操作通过覆写 `ISceneManagement` 方法自动注册。
155
-
156
- **群管理能力自动检测:** 适配器基类声明了 `ISceneManagement` 接口中的可选方法(`kickMember`、`muteMember`、`banMember` 等),子类只需覆写自己平台支持的方法,`start()` 会自动检测哪些方法已实现,生成对应的 Tool 并注册为"群聊管理"Skill。目前所有 9 个 IM 适配器(ICQQ、OneBot11、QQ 官方、Telegram、Discord、KOOK、Slack、钉钉、飞书)均已采用此模式:
97
+ 业务代码可以返回 `segment.html()`、`segment.markdown()`、`segment.qrcode()` 等语义段。Adapter 定义通过 `segments` 声明交互模式和媒体能力;Core 按当前 Endpoint 能力渲染,平台 Endpoint 只处理最终 payload。
157
98
 
158
99
  ```typescript
159
- class IcqqAdapter extends Adapter<IcqqEndpoint> {
160
- // 覆写标准群管方法
161
- async kickMember(endpointId: string, sceneId: string, userId: string) {
162
- const endpoint = this.endpoints.get(endpointId)
163
- if (!endpoint) throw new Error(`Endpoint ${endpointId} 不存在`)
164
- return endpoint.kickMember(Number(sceneId), Number(userId), false)
165
- }
166
- async muteMember(endpointId: string, sceneId: string, userId: string, duration = 600) { /* ... */ }
167
- async setAdmin(endpointId: string, sceneId: string, userId: string, enable = true) { /* ... */ }
168
- // ...共覆写 7 个标准方法
169
-
170
- async start() {
171
- this.registerIcqqPlatformTools() // 头衔、公告、戳一戳等平台特有工具
172
- await super.start() // 自动检测 → 生成标准 Tool → 与平台工具一起注册 Skill
173
- }
174
- }
175
- ```
176
-
177
- ### MessageDispatcher(消息路由)
178
-
179
- 三阶段消息处理管线:
100
+ import { segment } from '@zhin.js/core'
180
101
 
102
+ return segment.html({
103
+ html: '<div>status</div>',
104
+ text: 'status',
105
+ width: 540,
106
+ })
181
107
  ```
182
- 消息到达 → Guardrail(守卫) → Route(路由) → Handle(处理)
183
- │ │ │
184
- 权限/频率检查 命令 or AI? 执行命令 / AI Agent
185
- ```
186
-
187
- - **Guardrail** — 鉴权、速率限制、黑名单等前置检查
188
- - **Route** — 判断消息是命令还是 AI 对话
189
- - **Handle** — CommandFeature 处理命令;AI 对话由 `@zhin.js/agent` 的 ZhinAgent / AIService 处理(经 Dispatcher 注册)
190
-
191
- ### AI 与 @zhin.js/agent
192
108
 
193
- Core **不包含** ZhinAgent 实现。IM 侧的 AI 对话、工具收集、执行策略、MCP 客户端与 `ctx.ai` / `ctx.agent` 挂载均在 **`@zhin.js/agent`**(主包 `zhin.js` 会 `initAgentModule()` 并 re-export)。
109
+ 这些 helper 只创建 canonical `{ type, data }` 消息段。Core 的统一出站规范化链路负责 HTML 渲染、Markdown 策略、交互降级和媒体协商;能力来自当前 generation 的资源与 Adapter definition,不存在第二套消息段类、registry 或 loader。
194
110
 
195
- 本包从 `@zhin.js/ai` selective re-export 以下内容,供插件或适配器在不依赖 agent 层时使用:
111
+ ## 主要入口
196
112
 
197
- | 类别 | 示例导出 |
198
- |------|----------|
199
- | Provider | `AIProvider` 接口、`createSdkProviderAdapter`(AI SDK 传输) |
200
- | Agent 原语 | `ModelRegistry`、`agentLoop` |
201
- | 会话 / 上下文 | `ConversationEventStore`(IM 事实)与 Agent 的 `ContextRepository`(模型会话) |
202
- | 压缩 / 限流 / 输出 | `compactSession`、`RateLimiter`、`parseOutput`、`CostTracker` |
113
+ - `@zhin.js/core`:Message、场景、消息段、渲染与通用 IM 契约。
114
+ - `@zhin.js/core/runtime`:IM Runtime 的 composition ports 与实现。
115
+ - `@zhin.js/core/jsx-runtime`:消息 JSX runtime。
203
116
 
204
- 完整 Agent 能力与配置见 [`@zhin.js/agent`](../agent/README.md) 与 [AI 模块](https://zhin.js.org/advanced/ai)。
117
+ 插件作者通常从 `zhin.js` 及其 Feature 子路径导入;只有框架装配代码直接依赖 `@zhin.js/core/runtime`。
205
118
 
206
- ## 主要导出
119
+ ## 验证
207
120
 
208
- 入口为 [`src/index.ts`](./src/index.ts)。摘要如下(非完整列表):
209
-
210
- ```typescript
211
- // 插件系统
212
- export { Plugin, usePlugin, getPlugin, definePlugin } from './plugin.js' // usePlugin/getPlugin 为 throwing stub
213
-
214
- // Feature 体系(Cron / Scheduler 来自 @zhin.js/kernel)
215
- export { Feature, Cron, Scheduler } from '@zhin.js/kernel'
216
- export { CommandFeature, ToolFeature, SkillFeature, ScheduleFeature, DatabaseFeature, ... } from './built/*.js'
217
-
218
- // 消息路由
219
- export { createMessageDispatcher } from './built/dispatcher.js'
220
-
221
- // 适配器与消息(MessageCommand 已 deprecated)
222
- export { Adapter, Message, MessageCommand, Endpoint, segment, ... } from './'
223
-
224
- // 富媒体出站段
225
- export {
226
- resolveRichSegments,
227
- DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY,
228
- QrcodeSegment,
229
- HtmlSegment,
230
- MarkdownSegment,
231
- } from './built/rich-segments/index.js'
232
- export type { RichSegmentKind, RichRenderMode, OutboundRichSegmentPolicy } from './built/rich-segments/types.js'
233
-
234
- // HTML 出站回退(legacy;policy html:'text' 时等价)
235
- export { htmlToFallbackText, coerceHtmlSegmentsToText, registerHtmlSegmentFallback } from './built/*.js'
236
-
237
- // AI 原语(来自 @zhin.js/ai,非 ZhinAgent)
238
- export {
239
- AIProvider, createSdkProviderAdapter, ModelRegistry,
240
- ContextRepository, ContextManager, compactSession, ...
241
- } from '@zhin.js/ai'
242
- ```
243
-
244
- > ZhinAgent、`initAgentModule`、`AIService`、ExecPolicy、编排 Registry 等请从 **`zhin.js`** 或 **`@zhin.js/agent`** 引入。
245
-
246
- ## 安装
121
+ 命令可通过 `execution` 显式开启冷却、并发预算与一次进度反馈,详见
122
+ [`@zhin.js/command`](../command/README.md#可选执行预算)。Core 在真实入站 operation 上绑定身份,
123
+ Root Resource 保存跨 generation 的预算;外层 finally 在所有已启动发送排空后释放。
124
+ retirement signal 只停止尚未启动的提示,不释放仍在执行的占用,也不取消普通旧 lease 的发送。
125
+ 诊断 `dispatchStatus: 'limited'` 与 `limit` 表示准入拒绝,不是权限授权或平台投递失败。
247
126
 
248
127
  ```bash
249
- pnpm add @zhin.js/core
128
+ pnpm --filter @zhin.js/core build
129
+ pnpm exec vitest run packages/im/core/tests packages/im/adapter/tests
130
+ pnpm check:architecture
250
131
  ```
251
132
 
252
- > 通常不需要直接安装此包。使用 `zhin.js` 主入口包即可自动引入。
253
-
254
133
  ## 许可证
255
134
 
256
135
  MIT License
136
+
137
+ ## 定制内置展示
138
+
139
+ 应用 Root 可从 `zhin.js/command` 选择 `commandFeedbackToken`、`commandMenuPresentationToken`,从 `zhin.js/middleware` 选择 `outboundPresentationToken`。保留默认反馈、分页、权限与平台能力;不绑定或返回 `undefined` 继续使用内置展示。具体上下文、JSX 作者和失败边界见[定制内置展示](../../../docs/authoring/behavior-customization.md)。
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Plugin-facing contract for tool-free text completion (#804, #877).
3
+ *
4
+ * Lives in core so plugins can import it from the `zhin.js` main entry without installing the
5
+ * optional `@zhin.js/agent`. The agent provides {@link aiCompletionToken} only when an AI host is
6
+ * configured; check with {@link hasResource} (or `context.has?.(token)`) before `use()`.
7
+ */
8
+ import { type Token } from '@zhin.js/plugin-runtime';
9
+ /** Who a completion is billed to (`onBehalfOf`). `groupId` is `${platform}:${endpoint}:${sceneId}` in group / channel chats. */
10
+ export interface UsageSubject {
11
+ readonly userId: string;
12
+ /** Stable group key (platform + endpoint + group id); undefined in private chats. */
13
+ readonly groupId?: string;
14
+ readonly owner: boolean;
15
+ }
16
+ /** Original input used to estimate one participant's share of a completion. */
17
+ export interface AiCompletionUsageShare {
18
+ readonly subject: UsageSubject;
19
+ readonly text: string;
20
+ }
21
+ export interface AiCompletionUntrustedInput {
22
+ /** Where the text came from, e.g. `group-chat`; shown to the model as the block's source. */
23
+ readonly source: string;
24
+ readonly text: string;
25
+ }
26
+ export interface AiCompletionInput {
27
+ /** Required label for logs and usage attribution, e.g. `summarize-chat`. */
28
+ readonly purpose: string;
29
+ /** Trusted instructions written by the plugin. */
30
+ readonly system?: string;
31
+ /** Trusted input written by the plugin. */
32
+ readonly prompt: string;
33
+ /** Untrusted content (group chat, web pages, files); always rendered as data, never as instructions. */
34
+ readonly untrusted?: readonly AiCompletionUntrustedInput[];
35
+ /** Agent binding whose provider / model is used; defaults to `zhin`. */
36
+ readonly agent?: string;
37
+ /** Model id on the binding's provider; defaults to the binding's model. */
38
+ readonly model?: string;
39
+ readonly maxTokens?: number;
40
+ readonly temperature?: number;
41
+ /** Per-request timeout in ms; defaults to the provider resilience setting. */
42
+ readonly timeoutMs?: number;
43
+ readonly signal?: AbortSignal;
44
+ /** The IM user (and group) this call is made for; counts against their usage quota. */
45
+ readonly onBehalfOf?: UsageSubject;
46
+ /** Shared attribution, mutually exclusive with onBehalfOf. Denied users must be removed from the prompt before retrying. */
47
+ readonly usageShares?: readonly AiCompletionUsageShare[];
48
+ }
49
+ /** Token cost breakdown; structurally identical to `@zhin.js/ai` `TokenCost`. */
50
+ export interface AiCompletionTokenCost {
51
+ input: number;
52
+ output: number;
53
+ cacheRead: number;
54
+ cacheWrite: number;
55
+ total: number;
56
+ }
57
+ /** Token usage; structurally identical to `@zhin.js/ai` `TokenUsage` (asserted by agent type tests). */
58
+ export interface AiCompletionTokenUsage {
59
+ /** Availability metadata mirrors TokenUsage without importing the optional AI package. */
60
+ reported?: Partial<Record<'input' | 'output' | 'totalTokens' | 'cacheRead' | 'cacheWrite' | 'reasoning', boolean>>;
61
+ input: number;
62
+ output: number;
63
+ cacheRead: number;
64
+ cacheWrite: number;
65
+ totalTokens: number;
66
+ reasoning?: number;
67
+ cost: AiCompletionTokenCost;
68
+ }
69
+ export interface AiCompletionResult {
70
+ readonly text: string;
71
+ /** Model that actually answered (may be a fallback). */
72
+ readonly model: string;
73
+ readonly durationMs: number;
74
+ readonly usage?: AiCompletionTokenUsage;
75
+ }
76
+ export interface AiCompletion {
77
+ /** Older/custom hosts may omit this; callers must not send shared attribution to such hosts. */
78
+ readonly supportsUsageShares?: true;
79
+ completeText(input: AiCompletionInput): Promise<AiCompletionResult>;
80
+ }
81
+ /**
82
+ * Generation-owned plain text completion for plugins, provided by `@zhin.js/agent` when an AI host
83
+ * is configured; absent otherwise. Importing it never loads the agent.
84
+ */
85
+ export declare const aiCompletionToken: Token<AiCompletion>;
86
+ /** Shape of the agent's `AiCompletionQuotaError`, recognisable without importing `@zhin.js/agent`. */
87
+ export interface AiCompletionQuotaErrorLike extends Error {
88
+ readonly name: 'AiCompletionQuotaError';
89
+ readonly scope: 'user' | 'group';
90
+ readonly retryAfterSeconds: number;
91
+ /** Batch preflight rejected these users without starting a provider request or reserving quota. */
92
+ readonly deniedUserIds?: readonly string[];
93
+ }
94
+ /** True for the agent's quota error (`message` is user-facing); works without importing `@zhin.js/agent`. */
95
+ export declare function isAiCompletionQuotaError(error: unknown): error is AiCompletionQuotaErrorLike;
96
+ /** Usage quota group key shared by Agent turns and plugin completions. */
97
+ export declare function usageGroupId(platform: string, endpoint: string, sceneId: string): string;
98
+ /** Minimal structural input: core `Message`, `CommandMessage` and `@zhin.js/testing` fakes all fit. */
99
+ export interface UsageSubjectSource {
100
+ readonly conversation: Readonly<{
101
+ endpoint: Readonly<{
102
+ adapter: string;
103
+ id: string;
104
+ }>;
105
+ kind: string;
106
+ id: string;
107
+ }>;
108
+ readonly sender?: Readonly<{
109
+ id?: string;
110
+ chatRole?: 'owner' | 'admin' | 'trusted';
111
+ chatRoleLevels?: unknown;
112
+ }>;
113
+ readonly clientAdapter?: string;
114
+ readonly endpointId?: string;
115
+ }
116
+ /**
117
+ * The {@link UsageSubject} for a call made on behalf of a message's sender, with the same rules as
118
+ * Agent turns (so both count against one quota bucket): platform = `clientAdapter` or the endpoint
119
+ * adapter, endpoint = `endpointId` or the endpoint id, `groupId` only in group / channel chats,
120
+ * `owner` when the sender is a global chat-role `owner` (same host-wide rule as Agent turns, ADR 0056 §2).
121
+ *
122
+ * Returns `undefined` when the message has no sender (e.g. system events); omit `onBehalfOf` then.
123
+ * Throws `TypeError` for a malformed conversation (missing platform / endpoint / id, unknown kind).
124
+ */
125
+ export declare function usageSubjectFromMessage(message: UsageSubjectSource): UsageSubject | undefined;
126
+ /** Any context that resolves resources: setup `resources` (Scope), capability / construction contexts. */
127
+ export interface ResourceReader {
128
+ use<T>(token: Token<T>): T;
129
+ has?(token: Token<unknown>): boolean;
130
+ }
131
+ /**
132
+ * True when `context.use(token)` would succeed. Uses `context.has` when the context provides it and
133
+ * otherwise probes `use()`, so it also works with older or hand-written contexts.
134
+ */
135
+ export declare function hasResource(context: ResourceReader, token: Token<unknown>): boolean;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Plugin-facing contract for tool-free text completion (#804, #877).
3
+ *
4
+ * Lives in core so plugins can import it from the `zhin.js` main entry without installing the
5
+ * optional `@zhin.js/agent`. The agent provides {@link aiCompletionToken} only when an AI host is
6
+ * configured; check with {@link hasResource} (or `context.has?.(token)`) before `use()`.
7
+ */
8
+ import { createToken } from '@zhin.js/plugin-runtime';
9
+ import { hostChatRole } from '@zhin.js/im-contract';
10
+ /**
11
+ * Generation-owned plain text completion for plugins, provided by `@zhin.js/agent` when an AI host
12
+ * is configured; absent otherwise. Importing it never loads the agent.
13
+ */
14
+ export const aiCompletionToken = createToken('zhin.agent.ai-completion', 'Tool-free text completion with retry and fallback, for plugins');
15
+ /** True for the agent's quota error (`message` is user-facing); works without importing `@zhin.js/agent`. */
16
+ export function isAiCompletionQuotaError(error) {
17
+ return error instanceof Error && error.name === 'AiCompletionQuotaError'
18
+ && (error.scope === 'user' || error.scope === 'group')
19
+ && typeof error.retryAfterSeconds === 'number';
20
+ }
21
+ /** Usage quota group key shared by Agent turns and plugin completions. */
22
+ export function usageGroupId(platform, endpoint, sceneId) {
23
+ return `${platform}:${endpoint}:${sceneId}`;
24
+ }
25
+ /**
26
+ * The {@link UsageSubject} for a call made on behalf of a message's sender, with the same rules as
27
+ * Agent turns (so both count against one quota bucket): platform = `clientAdapter` or the endpoint
28
+ * adapter, endpoint = `endpointId` or the endpoint id, `groupId` only in group / channel chats,
29
+ * `owner` when the sender is a global chat-role `owner` (same host-wide rule as Agent turns, ADR 0056 §2).
30
+ *
31
+ * Returns `undefined` when the message has no sender (e.g. system events); omit `onBehalfOf` then.
32
+ * Throws `TypeError` for a malformed conversation (missing platform / endpoint / id, unknown kind).
33
+ */
34
+ export function usageSubjectFromMessage(message) {
35
+ const userId = String(message.sender?.id ?? '').trim();
36
+ if (!userId)
37
+ return undefined;
38
+ const { conversation } = message;
39
+ const kind = conversation.kind;
40
+ if (kind !== 'private' && kind !== 'group' && kind !== 'channel') {
41
+ throw new TypeError(`usageSubjectFromMessage: unsupported conversation kind ${String(kind)}`);
42
+ }
43
+ const platform = String(message.clientAdapter ?? conversation.endpoint.adapter ?? '').trim();
44
+ const endpoint = String(message.endpointId ?? conversation.endpoint.id ?? '').trim();
45
+ const sceneId = String(conversation.id ?? '').trim();
46
+ if (!platform || !endpoint || !sceneId) {
47
+ throw new TypeError('usageSubjectFromMessage: conversation platform, endpoint and id are required');
48
+ }
49
+ return Object.freeze({
50
+ userId,
51
+ ...(kind === 'private' ? {} : { groupId: usageGroupId(platform, endpoint, sceneId) }),
52
+ owner: hostChatRole(message.sender) === 'owner',
53
+ });
54
+ }
55
+ /**
56
+ * True when `context.use(token)` would succeed. Uses `context.has` when the context provides it and
57
+ * otherwise probes `use()`, so it also works with older or hand-written contexts.
58
+ */
59
+ export function hasResource(context, token) {
60
+ if (typeof context.has === 'function')
61
+ return context.has(token);
62
+ try {
63
+ context.use(token);
64
+ return true;
65
+ }
66
+ catch {
67
+ return false;
68
+ }
69
+ }
@@ -1,7 +1,7 @@
1
1
  /**
2
- * AI Access Gate — 控制 LLM 回复路径是否对当前会话开放(平台 AIGC 合规等)
2
+ * AI Access Gate config — 控制 LLM 回复路径是否对当前会话开放(平台 AIGC 合规等)。
3
+ * The gate itself lives in `@zhin.js/agent`; core only owns the config shape.
3
4
  */
4
- import type { Message } from '../message.js';
5
5
  export type AIAccessMode = 'open' | 'closed' | 'whitelist';
6
6
  /** Endpoint 或全局 ai.access 配置块 */
7
7
  export interface AIAccessScopeConfig {
@@ -15,22 +15,3 @@ export interface AIAccessScopeConfig {
15
15
  }
16
16
  /** 全局 ai.access 配置(与 AIAccessScopeConfig 同形) */
17
17
  export type AIAccessConfig = AIAccessScopeConfig;
18
- export interface ResolvedAIAccessConfig {
19
- mode: AIAccessMode;
20
- users: string[];
21
- groups: string[];
22
- denyMessage: string;
23
- }
24
- export interface AIAccessResult {
25
- allowed: boolean;
26
- reason: string;
27
- /** 私聊拒绝时返回;群/频道拒绝为 undefined(静默) */
28
- replyMessage?: string;
29
- }
30
- export declare const DEFAULT_AI_ACCESS_DENY_MESSAGE = "\u5F53\u524D\u4F1A\u8BDD\u672A\u5F00\u653E AI \u529F\u80FD\u3002";
31
- export declare function resolveAIAccessConfig(global: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): ResolvedAIAccessConfig;
32
- /**
33
- * 判定当前消息是否允许进入 AI Handler(LLM 回复路径)。
34
- * 不影响命令、游戏等其它 Dispatcher 分支。
35
- */
36
- export declare function checkAIAccess(message: Message<any>, globalConfig: AIAccessConfig | undefined, endpointScope?: AIAccessScopeConfig): AIAccessResult;
@@ -1,46 +1 @@
1
- export const DEFAULT_AI_ACCESS_DENY_MESSAGE = '当前会话未开放 AI 功能。';
2
- const DEFAULT_MODE = 'open';
3
- export function resolveAIAccessConfig(global, endpointScope) {
4
- const base = global ?? {};
5
- const endpoint = endpointScope ?? {};
6
- return {
7
- mode: endpoint.mode ?? base.mode ?? DEFAULT_MODE,
8
- users: endpoint.users ?? base.users ?? [],
9
- groups: endpoint.groups ?? base.groups ?? [],
10
- denyMessage: endpoint.denyMessage ?? base.denyMessage ?? DEFAULT_AI_ACCESS_DENY_MESSAGE,
11
- };
12
- }
13
- function isWhitelisted(message, config) {
14
- const userId = String(message.$sender?.id ?? '');
15
- if (userId && config.users.includes(userId))
16
- return true;
17
- const scope = message.$channel?.type;
18
- if (scope === 'group' || scope === 'channel') {
19
- const channelId = String(message.$channel?.id ?? '');
20
- if (channelId && config.groups.includes(channelId))
21
- return true;
22
- }
23
- return false;
24
- }
25
- function denyResult(message, config, reason) {
26
- const scope = message.$channel?.type;
27
- const replyMessage = scope === 'private' ? config.denyMessage : undefined;
28
- return { allowed: false, reason, replyMessage };
29
- }
30
- /**
31
- * 判定当前消息是否允许进入 AI Handler(LLM 回复路径)。
32
- * 不影响命令、游戏等其它 Dispatcher 分支。
33
- */
34
- export function checkAIAccess(message, globalConfig, endpointScope) {
35
- const config = resolveAIAccessConfig(globalConfig, endpointScope);
36
- if (config.mode === 'open') {
37
- return { allowed: true, reason: 'mode: open' };
38
- }
39
- if (config.mode === 'closed') {
40
- return denyResult(message, config, 'mode: closed');
41
- }
42
- if (isWhitelisted(message, config)) {
43
- return { allowed: true, reason: 'whitelist: matched' };
44
- }
45
- return denyResult(message, config, 'whitelist: not matched');
46
- }
1
+ export {};
@@ -4,6 +4,4 @@ export * from './plain-mention-rewrite.js';
4
4
  export * from './resolve.js';
5
5
  export * from './prompt.js';
6
6
  export * from './structured-detect.js';
7
- export * from './adapter-access.js';
8
7
  export * from './extensions/onebot-keyboard.js';
9
- export * from './extensions/qq-message.js';
@@ -4,6 +4,4 @@ export * from './plain-mention-rewrite.js';
4
4
  export * from './resolve.js';
5
5
  export * from './prompt.js';
6
6
  export * from './structured-detect.js';
7
- export * from './adapter-access.js';
8
7
  export * from './extensions/onebot-keyboard.js';
9
- export * from './extensions/qq-message.js';
@@ -1,6 +1,8 @@
1
1
  import type { AiOutboundCapabilities, AiOutboundExtensionDefinition } from './types.js';
2
2
  export declare const AI_OUTBOUND_JSON_EXAMPLE = "{\"mentions\":[\"researcher\",\"210723495\"],\"text\":\"\u6B63\u6587\"}";
3
+ /** @deprecated Legacy `{mentions,text}` format; Agent replies use the canonical `{segments}` contract (`buildAiOutboundJsonSchema`). */
3
4
  export declare function buildCoreAiOutboundPromptHint(capabilities?: AiOutboundCapabilities): string;
5
+ /** @deprecated Legacy `{mentions,text}` format; Agent replies use the canonical `{segments}` contract (`buildAiOutboundJsonSchema`). */
4
6
  export declare function buildAiOutboundPromptHint(input: {
5
7
  capabilities?: AiOutboundCapabilities;
6
8
  extensions?: readonly AiOutboundExtensionDefinition[];