@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.
- package/README.md +78 -195
- package/lib/ai-completion-contract.d.ts +135 -0
- package/lib/ai-completion-contract.js +69 -0
- package/lib/built/ai-access.d.ts +2 -21
- package/lib/built/ai-access.js +1 -46
- package/lib/built/ai-outbound/index.d.ts +0 -2
- package/lib/built/ai-outbound/index.js +0 -2
- package/lib/built/ai-outbound/prompt.d.ts +2 -0
- package/lib/built/ai-outbound/prompt.js +2 -0
- package/lib/built/ai-outbound/types.d.ts +1 -10
- package/lib/built/ai-trigger.d.ts +39 -78
- package/lib/built/ai-trigger.js +3 -254
- package/lib/built/common-adapter-tools.d.ts +21 -6
- package/lib/built/common-adapter-tools.js +28 -17
- package/lib/built/generic-segment-mapper.js +4 -1
- package/lib/built/html-segment-fallback.d.ts +6 -7
- package/lib/built/html-segment-fallback.js +1 -16
- package/lib/built/html-to-text.d.ts +0 -3
- package/lib/built/html-to-text.js +131 -40
- package/lib/built/interaction-messages.d.ts +1 -0
- package/lib/built/interaction-messages.js +30 -0
- package/lib/built/interactive-segments/action.d.ts +3 -4
- package/lib/built/interactive-segments/action.js +2 -5
- package/lib/built/interactive-segments/index.d.ts +0 -2
- package/lib/built/interactive-segments/index.js +0 -2
- package/lib/built/interactive-segments/keyboard-segment.d.ts +0 -1
- package/lib/built/interactive-segments/keyboard-segment.js +0 -1
- package/lib/built/interactive-segments/onebot-keyboard.d.ts +0 -1
- package/lib/built/interactive-segments/onebot-keyboard.js +0 -2
- package/lib/built/interactive-segments/resolve.d.ts +2 -3
- package/lib/built/interactive-segments/resolve.js +21 -14
- package/lib/built/interactive-segments/types.d.ts +2 -7
- package/lib/built/interactive-segments/types.js +22 -2
- package/lib/built/login-assist.d.ts +330 -25
- package/lib/built/login-assist.js +1156 -75
- package/lib/built/login-captcha.d.ts +62 -0
- package/lib/built/login-captcha.js +107 -0
- package/lib/built/message-enrich.d.ts +24 -27
- package/lib/built/message-enrich.js +53 -49
- package/lib/built/outbound-content-arrays.d.ts +4 -0
- package/lib/built/outbound-content-arrays.js +32 -0
- package/lib/built/outbound-media-trust.d.ts +46 -0
- package/lib/built/outbound-media-trust.js +245 -0
- package/lib/built/outbound-media-utils.d.ts +5 -3
- package/lib/built/outbound-media-utils.js +5 -3
- package/lib/built/readable-link.d.ts +4 -0
- package/lib/built/readable-link.js +32 -0
- package/lib/built/rich-segments/markdown-to-text.d.ts +1 -2
- package/lib/built/rich-segments/markdown-to-text.js +141 -17
- package/lib/built/roles.d.ts +141 -12
- package/lib/built/roles.js +253 -52
- package/lib/built/segment-contract/assert.js +8 -2
- package/lib/built/segment-contract/delivery.js +1 -0
- package/lib/built/segment-contract/index.d.ts +3 -3
- package/lib/built/segment-contract/index.js +2 -2
- package/lib/built/segment-contract/json-schema.d.ts +39 -5
- package/lib/built/segment-contract/json-schema.js +207 -24
- package/lib/built/segment-contract/preview.js +8 -1
- package/lib/built/segment-contract/text.js +1 -1
- package/lib/built/segment-contract/types.d.ts +2 -2
- package/lib/built/segment-contract/validate.d.ts +1553 -224
- package/lib/built/segment-contract/validate.js +39 -3
- package/lib/built/tool-access.d.ts +5 -0
- package/lib/built/tool-access.js +17 -0
- package/lib/built/user-interaction.d.ts +5 -4
- package/lib/built/user-interaction.js +64 -52
- package/lib/errors.d.ts +1 -18
- package/lib/errors.js +1 -26
- package/lib/feature/command-public-api.d.ts +5 -0
- package/lib/feature/command-public-api.js +5 -0
- package/lib/feature/command.d.ts +2 -0
- package/lib/feature/command.js +1 -0
- package/lib/feature/component.d.ts +1 -0
- package/lib/feature/component.js +1 -0
- package/lib/feature/handler.d.ts +13 -7
- package/lib/feature/handler.js +2 -1
- package/lib/feature/middleware-public-api.d.ts +6 -0
- package/lib/feature/middleware-public-api.js +6 -0
- package/lib/feature/middleware.d.ts +22 -2
- package/lib/feature/middleware.js +7 -2
- package/lib/im-scene.d.ts +4 -3
- package/lib/im-scene.js +9 -9
- package/lib/im-session-id.d.ts +20 -12
- package/lib/im-session-id.js +8 -8
- package/lib/index.d.ts +20 -48
- package/lib/index.js +15 -41
- package/lib/jsx/intrinsic-elements.d.ts +83 -0
- package/lib/jsx/message-renderer.d.ts +13 -0
- package/lib/jsx/message-renderer.js +128 -0
- package/lib/jsx/message-tags.d.ts +133 -0
- package/lib/jsx/message-tags.js +50 -0
- package/lib/jsx-dev-runtime.d.ts +2 -2
- package/lib/jsx-dev-runtime.js +1 -2
- package/lib/jsx-runtime.d.ts +2 -12
- package/lib/jsx-runtime.js +1 -10
- package/lib/jsx.d.ts +6 -30
- package/lib/jsx.js +3 -93
- package/lib/message.d.ts +0 -40
- package/lib/message.js +1 -27
- package/lib/models/system-log.d.ts +0 -2
- package/lib/models/system-log.js +1 -8
- package/lib/models/user.d.ts +0 -2
- package/lib/models/user.js +1 -7
- package/lib/notice.d.ts +38 -33
- package/lib/notice.js +23 -7
- package/lib/plugin-runtime/im/command-feedback.d.ts +59 -0
- package/lib/plugin-runtime/im/command-feedback.js +148 -0
- package/lib/plugin-runtime/im/contracts.d.ts +217 -32
- package/lib/plugin-runtime/im/contracts.js +141 -23
- package/lib/plugin-runtime/im/conversation-runtime.d.ts +42 -0
- package/lib/plugin-runtime/im/conversation-runtime.js +451 -0
- package/lib/plugin-runtime/im/endpoint-runtime.d.ts +112 -0
- package/lib/plugin-runtime/im/endpoint-runtime.js +434 -0
- package/lib/plugin-runtime/im/feature-gate.d.ts +21 -0
- package/lib/plugin-runtime/im/feature-gate.js +88 -0
- package/lib/plugin-runtime/im/host/component-host-installer.d.ts +2 -0
- package/lib/plugin-runtime/im/host/component-host-installer.js +14 -0
- package/lib/plugin-runtime/im/host/conversation-migration.d.ts +5 -0
- package/lib/plugin-runtime/im/host/conversation-migration.js +75 -0
- package/lib/plugin-runtime/im/host/database-config.d.ts +10 -0
- package/lib/plugin-runtime/im/host/database-config.js +152 -0
- package/lib/plugin-runtime/im/host/database-console-schema.d.ts +79 -0
- package/lib/plugin-runtime/im/host/database-console-schema.js +477 -0
- package/lib/plugin-runtime/im/host/database-console-sql.d.ts +66 -0
- package/lib/plugin-runtime/im/host/database-console-sql.js +459 -0
- package/lib/plugin-runtime/im/host/database-host-installer.d.ts +60 -0
- package/lib/plugin-runtime/im/host/database-host-installer.js +1166 -0
- package/lib/plugin-runtime/im/host/database-state.d.ts +9 -0
- package/lib/plugin-runtime/im/host/database-state.js +91 -0
- package/lib/plugin-runtime/im/host/index.d.ts +8 -0
- package/lib/plugin-runtime/im/host/index.js +8 -0
- package/lib/plugin-runtime/im/host/locale-host-installer.d.ts +3 -0
- package/lib/plugin-runtime/im/host/locale-host-installer.js +60 -0
- package/lib/plugin-runtime/im/host/outbound-host-installer.d.ts +8 -0
- package/lib/plugin-runtime/im/host/outbound-host-installer.js +153 -0
- package/lib/plugin-runtime/im/host/sender-enrichment.d.ts +34 -0
- package/lib/plugin-runtime/im/host/sender-enrichment.js +82 -0
- package/lib/plugin-runtime/im/im-runtime.d.ts +40 -111
- package/lib/plugin-runtime/im/im-runtime.js +235 -1059
- package/lib/plugin-runtime/im/inbound-dedup.d.ts +84 -0
- package/lib/plugin-runtime/im/inbound-dedup.js +322 -0
- package/lib/plugin-runtime/im/inbound-origin.d.ts +150 -0
- package/lib/plugin-runtime/im/inbound-origin.js +183 -0
- package/lib/plugin-runtime/im/inbound-runtime.d.ts +59 -0
- package/lib/plugin-runtime/im/inbound-runtime.js +478 -0
- package/lib/plugin-runtime/im/inbound-spine.d.ts +196 -0
- package/lib/plugin-runtime/im/inbound-spine.js +335 -0
- package/lib/plugin-runtime/im/index.d.ts +15 -4
- package/lib/plugin-runtime/im/index.js +11 -4
- package/lib/plugin-runtime/im/interaction-runtime.d.ts +50 -0
- package/lib/plugin-runtime/im/interaction-runtime.js +390 -0
- package/lib/plugin-runtime/im/interactive-router.d.ts +81 -0
- package/lib/plugin-runtime/im/interactive-router.js +382 -0
- package/lib/plugin-runtime/im/message-diagnostics.d.ts +70 -0
- package/lib/plugin-runtime/im/message-diagnostics.js +182 -0
- package/lib/plugin-runtime/im/message-dispatcher.d.ts +18 -4
- package/lib/plugin-runtime/im/message-dispatcher.js +138 -20
- package/lib/plugin-runtime/im/message-events.d.ts +85 -0
- package/lib/plugin-runtime/im/message-events.js +113 -0
- package/lib/plugin-runtime/im/outbound-delivery-runtime.d.ts +39 -0
- package/lib/plugin-runtime/im/outbound-delivery-runtime.js +450 -0
- package/lib/plugin-runtime/im/outbound-renderer.d.ts +52 -3
- package/lib/plugin-runtime/im/outbound-renderer.js +188 -8
- package/lib/plugin-runtime/im/outbound-segments.d.ts +29 -5
- package/lib/plugin-runtime/im/outbound-segments.js +130 -36
- package/lib/plugin-runtime/im/progressive-reply.d.ts +58 -0
- package/lib/plugin-runtime/im/progressive-reply.js +501 -0
- package/lib/plugin-runtime/im/public-api.d.ts +1 -1
- package/lib/request.d.ts +27 -36
- package/lib/request.js +14 -6
- package/lib/side-event/base.d.ts +64 -44
- package/lib/side-event/base.js +72 -19
- package/lib/side-event/index.d.ts +1 -1
- package/lib/side-event/index.js +1 -1
- package/lib/side-event/normalize.d.ts +7 -38
- package/lib/side-event/normalize.js +4 -109
- package/lib/side-event/scene-events.d.ts +40 -0
- package/lib/side-event/scene-events.js +147 -0
- package/lib/side-event/types.d.ts +4 -13
- package/lib/side-event/types.js +1 -55
- package/lib/system-event.d.ts +17 -12
- package/lib/system-event.js +8 -6
- package/lib/types.d.ts +23 -167
- package/lib/utils.d.ts +50 -33
- package/lib/utils.js +12 -185
- package/lib/venue/contracts.d.ts +21 -0
- package/lib/venue/contracts.js +3 -0
- package/lib/venue/floor-controller.d.ts +11 -0
- package/lib/venue/floor-controller.js +63 -0
- package/lib/venue/index.d.ts +13 -0
- package/lib/venue/index.js +11 -0
- package/lib/venue/membership-port.d.ts +23 -0
- package/lib/venue/membership-port.js +141 -0
- package/lib/venue/projector.d.ts +38 -0
- package/lib/venue/projector.js +45 -0
- package/lib/venue/registry.d.ts +16 -0
- package/lib/venue/registry.js +63 -0
- package/lib/venue/router.d.ts +19 -0
- package/lib/venue/router.js +101 -0
- package/lib/venue/send-limiter.d.ts +17 -0
- package/lib/venue/send-limiter.js +73 -0
- package/lib/venue/validator.d.ts +6 -0
- package/lib/venue/validator.js +160 -0
- package/package.json +24 -50
- package/lib/adapter.d.ts +0 -145
- package/lib/adapter.js +0 -377
- package/lib/built/adapter-process.d.ts +0 -58
- package/lib/built/adapter-process.js +0 -128
- package/lib/built/agent-preset.d.ts +0 -64
- package/lib/built/agent-preset.js +0 -79
- package/lib/built/ai-outbound/adapter-access.d.ts +0 -3
- package/lib/built/ai-outbound/adapter-access.js +0 -9
- package/lib/built/ai-outbound/extensions/qq-message.d.ts +0 -3
- package/lib/built/ai-outbound/extensions/qq-message.js +0 -23
- package/lib/built/authorization.d.ts +0 -10
- package/lib/built/authorization.js +0 -76
- package/lib/built/command.d.ts +0 -72
- package/lib/built/command.js +0 -105
- package/lib/built/component.d.ts +0 -67
- package/lib/built/component.js +0 -97
- package/lib/built/config.d.ts +0 -98
- package/lib/built/config.js +0 -372
- package/lib/built/connect-endpoint-instance.d.ts +0 -17
- package/lib/built/connect-endpoint-instance.js +0 -42
- package/lib/built/database.d.ts +0 -68
- package/lib/built/database.js +0 -106
- package/lib/built/dispatcher.d.ts +0 -141
- package/lib/built/dispatcher.js +0 -383
- package/lib/built/endpoint-commands.d.ts +0 -3
- package/lib/built/endpoint-commands.js +0 -99
- package/lib/built/endpoint-lifecycle-service.d.ts +0 -28
- package/lib/built/endpoint-lifecycle-service.js +0 -242
- package/lib/built/endpoint-lifecycle.d.ts +0 -27
- package/lib/built/endpoint-lifecycle.js +0 -36
- package/lib/built/endpoint-manager.d.ts +0 -34
- package/lib/built/html-renderer-loader.d.ts +0 -13
- package/lib/built/html-renderer-loader.js +0 -33
- package/lib/built/inbound-pipeline.d.ts +0 -37
- package/lib/built/inbound-pipeline.js +0 -63
- package/lib/built/inbound-runner.d.ts +0 -22
- package/lib/built/inbound-runner.js +0 -34
- package/lib/built/interactive-segment-contract.d.ts +0 -6
- package/lib/built/interactive-segment-contract.js +0 -9
- package/lib/built/interactive-segments/fallback-store.d.ts +0 -29
- package/lib/built/interactive-segments/fallback-store.js +0 -63
- package/lib/built/interactive-segments/handlers.d.ts +0 -16
- package/lib/built/interactive-segments/handlers.js +0 -74
- package/lib/built/introspection-format.d.ts +0 -10
- package/lib/built/introspection-format.js +0 -28
- package/lib/built/management-command-guard.d.ts +0 -15
- package/lib/built/management-command-guard.js +0 -25
- package/lib/built/message-filter.d.ts +0 -176
- package/lib/built/message-filter.js +0 -239
- package/lib/built/optional-peer-import.d.ts +0 -3
- package/lib/built/optional-peer-import.js +0 -33
- package/lib/built/outbound-media-contract.d.ts +0 -22
- package/lib/built/outbound-media-contract.js +0 -10
- package/lib/built/permission.d.ts +0 -51
- package/lib/built/permission.js +0 -99
- package/lib/built/permit-check.d.ts +0 -7
- package/lib/built/permit-check.js +0 -35
- package/lib/built/permit-parse.d.ts +0 -16
- package/lib/built/permit-parse.js +0 -32
- package/lib/built/platform-permit.d.ts +0 -20
- package/lib/built/platform-permit.js +0 -91
- package/lib/built/queue-im-field-contract.d.ts +0 -32
- package/lib/built/queue-im-field-contract.js +0 -67
- package/lib/built/rich-segments/adapter-policies.d.ts +0 -9
- package/lib/built/rich-segments/adapter-policies.js +0 -27
- package/lib/built/rich-segments/base.d.ts +0 -11
- package/lib/built/rich-segments/base.js +0 -24
- package/lib/built/rich-segments/builtins.d.ts +0 -4
- package/lib/built/rich-segments/builtins.js +0 -40
- package/lib/built/rich-segments/capabilities.d.ts +0 -6
- package/lib/built/rich-segments/capabilities.js +0 -38
- package/lib/built/rich-segments/html-segment.d.ts +0 -15
- package/lib/built/rich-segments/html-segment.js +0 -62
- package/lib/built/rich-segments/index.d.ts +0 -13
- package/lib/built/rich-segments/index.js +0 -13
- package/lib/built/rich-segments/markdown-segment.d.ts +0 -14
- package/lib/built/rich-segments/markdown-segment.js +0 -58
- package/lib/built/rich-segments/qrcode-segment.d.ts +0 -18
- package/lib/built/rich-segments/qrcode-segment.js +0 -73
- package/lib/built/rich-segments/registry.d.ts +0 -16
- package/lib/built/rich-segments/registry.js +0 -52
- package/lib/built/rich-segments/resolve.d.ts +0 -5
- package/lib/built/rich-segments/resolve.js +0 -87
- package/lib/built/rich-segments/tts-segment.d.ts +0 -13
- package/lib/built/rich-segments/tts-segment.js +0 -51
- package/lib/built/rich-segments/types.d.ts +0 -79
- package/lib/built/rich-segments/types.js +0 -17
- package/lib/built/runtime-io.d.ts +0 -9
- package/lib/built/runtime-io.js +0 -67
- package/lib/built/schedule.d.ts +0 -54
- package/lib/built/schedule.js +0 -112
- package/lib/built/schema-endpoint-manager.d.ts +0 -17
- package/lib/built/schema-endpoint-manager.js +0 -73
- package/lib/built/schema-feature.d.ts +0 -77
- package/lib/built/schema-feature.js +0 -130
- package/lib/built/skill.d.ts +0 -120
- package/lib/built/skill.js +0 -151
- package/lib/built/speech-loader.d.ts +0 -14
- package/lib/built/speech-loader.js +0 -32
- package/lib/built/tool.d.ts +0 -151
- package/lib/built/tool.js +0 -388
- package/lib/command.d.ts +0 -50
- package/lib/command.js +0 -106
- package/lib/component.d.ts +0 -26
- package/lib/component.js +0 -583
- package/lib/endpoint-capabilities.d.ts +0 -46
- package/lib/endpoint-capabilities.js +0 -55
- package/lib/endpoint.d.ts +0 -19
- package/lib/endpoint.js +0 -3
- package/lib/host-plugin-registry.d.ts +0 -8
- package/lib/host-plugin-registry.js +0 -12
- package/lib/plugin-context.d.ts +0 -27
- package/lib/plugin-context.js +0 -64
- package/lib/plugin-runtime/im/interactive.d.ts +0 -26
- package/lib/plugin-runtime/im/interactive.js +0 -46
- package/lib/plugin-runtime/im/login-assist-host.d.ts +0 -6
- package/lib/plugin-runtime/im/login-assist-host.js +0 -6
- package/lib/plugin-runtime/im/message-bus.d.ts +0 -38
- package/lib/plugin-runtime/im/message-bus.js +0 -40
- package/lib/plugin-runtime/im/service-tokens.d.ts +0 -18
- package/lib/plugin-runtime/im/service-tokens.js +0 -13
- package/lib/plugin.d.ts +0 -268
- package/lib/plugin.js +0 -583
- package/lib/schema-interaction.d.ts +0 -117
- package/lib/schema-interaction.js +0 -247
- package/lib/side-event/dispatch.d.ts +0 -15
- package/lib/side-event/dispatch.js +0 -140
- package/lib/tool-zod.d.ts +0 -43
- package/lib/tool-zod.js +0 -184
- /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
|
-
|
|
3
|
+
`@zhin.js/core` 负责组合 Zhin 的 IM 领域:规范化消息、入站分发、出站渲染、交互语义,以及 Plugin Runtime 的 IM Host。它消费独立 Feature 包产生的 generation snapshot,不拥有平台连接或能力注册表。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
架构与消息链路分别见:
|
|
6
6
|
|
|
7
|
-
-
|
|
7
|
+
- [分层架构](../../../docs/concepts/architecture.md)
|
|
8
|
+
- [消息流](../../../docs/concepts/message-flow.md)
|
|
9
|
+
- [公开 API 分级](../../../docs/contributing/public-api-surface.md)
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
`@zhin.js/middleware` 提供纯 definition、约定发现 provider 和 generation projection;
|
|
11
|
-
Core Runtime 只消费它们发布的 snapshot。
|
|
12
|
-
旧根入口的 `addCommand`、`addComponent`、`addMiddleware` 暂时作为作者兼容接口保留,后续
|
|
13
|
-
只向 RuntimeSnapshot 投影,不再维护第二套运行时权威。
|
|
11
|
+
## 边界
|
|
14
12
|
|
|
15
|
-
|
|
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
|
-
|
|
23
|
+
Core 不提供第二套 Adapter 基类、Endpoint 类型或进程级注册表。平台插件统一从 `zhin.js/adapter` 导入 `Adapter`、`defineAdapter`、结构 `Endpoint` 与 `endpointSpec`。
|
|
18
24
|
|
|
19
|
-
##
|
|
25
|
+
## Plugin Runtime
|
|
20
26
|
|
|
21
|
-
|
|
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 '
|
|
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(() => {
|
|
36
|
+
context.lifecycle.add(() => {
|
|
37
|
+
// release plugin-owned resources
|
|
38
|
+
})
|
|
34
39
|
},
|
|
35
40
|
})
|
|
36
41
|
```
|
|
37
42
|
|
|
38
43
|
```typescript
|
|
39
|
-
// commands/hello/
|
|
40
|
-
import { defineCommand } from '
|
|
44
|
+
// commands/hello/index.ts
|
|
45
|
+
import { defineCommand } from 'zhin.js/command'
|
|
41
46
|
|
|
42
47
|
export default defineCommand({
|
|
43
48
|
description: '打招呼',
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
},
|
|
47
|
-
execute({ params }) {
|
|
48
|
-
return `Hello, ${params.name}!`
|
|
49
|
+
execute() {
|
|
50
|
+
return 'Hello!'
|
|
49
51
|
},
|
|
50
52
|
})
|
|
51
53
|
```
|
|
52
54
|
|
|
53
|
-
|
|
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
|
-
|
|
57
|
+
## Adapter 与 Endpoint
|
|
81
58
|
|
|
82
|
-
|
|
59
|
+
Adapter 是账号配置、CAS 与连接 incarnation 的唯一 owner。Endpoint 继承真实 SDK 或实质协议 Client,并通过 `endpointSpec` / `createEndpointSpecification` 附加框架钩子;不覆盖 SDK 原生事件和 API。当前 generation 的 `AdapterIndex` 提供目录、租约路由和只读 connection 数据,不向普通查询暴露内部生命周期对象。
|
|
83
60
|
|
|
84
61
|
```typescript
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
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
|
-
|
|
76
|
+
平台管理、撤回、编辑、reaction 与 typing 通过 specification 的显式 capability/control 端口暴露。调用者通过 `AdapterIndex.management/control` 获取捕获真实 incarnation 的受租约保护端口,不能从只读 connection 数据取未受保护的操作。普通业务消息继续走统一出站链路。
|
|
108
77
|
|
|
109
|
-
|
|
110
|
-
- policy 为 `html: 'text'` 时等价于 **`coerceHtmlSegmentsToText`** / **`htmlToFallbackText`**。
|
|
111
|
-
- 日志预览:`[html-card]`、`[qrcode]`、`[markdown]` + 摘要(前 80 字)。
|
|
78
|
+
## 消息链路
|
|
112
79
|
|
|
113
|
-
|
|
80
|
+
入站由 Endpoint 发出结构化事件,Core Runtime 完成身份附加、消息规范化和 generation 准入,然后依次执行 Middleware、Command、Handler 与可选 Agent 路由。
|
|
114
81
|
|
|
115
|
-
|
|
82
|
+
出站统一经过:
|
|
116
83
|
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
-
|
|
144
|
-
|
|
145
|
-
### Adapter(适配器)
|
|
93
|
+
任何平台发送都必须经过这条链路。
|
|
146
94
|
|
|
147
|
-
|
|
95
|
+
## 语义消息段
|
|
148
96
|
|
|
149
|
-
|
|
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
|
-
|
|
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
|
-
|
|
109
|
+
这些 helper 只创建 canonical `{ type, data }` 消息段。Core 的统一出站规范化链路负责 HTML 渲染、Markdown 策略、交互降级和媒体协商;能力来自当前 generation 的资源与 Adapter definition,不存在第二套消息段类、registry 或 loader。
|
|
194
110
|
|
|
195
|
-
|
|
111
|
+
## 主要入口
|
|
196
112
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
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
|
-
|
|
117
|
+
插件作者通常从 `zhin.js` 及其 Feature 子路径导入;只有框架装配代码直接依赖 `@zhin.js/core/runtime`。
|
|
205
118
|
|
|
206
|
-
##
|
|
119
|
+
## 验证
|
|
207
120
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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
|
|
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
|
+
}
|
package/lib/built/ai-access.d.ts
CHANGED
|
@@ -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;
|
package/lib/built/ai-access.js
CHANGED
|
@@ -1,46 +1 @@
|
|
|
1
|
-
export
|
|
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[];
|