@zhin.js/core 1.1.53 → 1.1.54
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 +13 -26
- package/lib/built/login-assist.d.ts +12 -3
- package/lib/built/login-assist.js +32 -26
- package/lib/feature/handler.d.ts +12 -2
- package/lib/feature/handler.js +2 -1
- package/lib/index.d.ts +3 -1
- package/lib/index.js +2 -0
- package/lib/plugin-runtime/im/captured-endpoint-operation.d.ts +30 -0
- package/lib/plugin-runtime/im/captured-endpoint-operation.js +1 -0
- package/lib/plugin-runtime/im/command-menu-navigation.d.ts +8 -1
- package/lib/plugin-runtime/im/command-menu-navigation.js +3 -3
- package/lib/plugin-runtime/im/contracts.d.ts +69 -48
- package/lib/plugin-runtime/im/contracts.js +65 -58
- package/lib/plugin-runtime/im/endpoint-runtime.d.ts +9 -14
- package/lib/plugin-runtime/im/endpoint-runtime.js +156 -40
- package/lib/plugin-runtime/im/group-rule-violation.d.ts +5 -0
- package/lib/plugin-runtime/im/im-runtime.d.ts +3 -0
- package/lib/plugin-runtime/im/im-runtime.js +29 -4
- package/lib/plugin-runtime/im/inbound-runtime.d.ts +2 -0
- package/lib/plugin-runtime/im/inbound-runtime.js +138 -33
- package/lib/plugin-runtime/im/index.d.ts +1 -1
- package/lib/plugin-runtime/im/interaction-operation.d.ts +5 -1
- package/lib/plugin-runtime/im/interaction-runtime.d.ts +12 -2
- package/lib/plugin-runtime/im/interaction-runtime.js +50 -35
- package/lib/plugin-runtime/im/message-dispatcher.js +2 -2
- package/lib/plugin-runtime/im/operation-endpoint.d.ts +6 -0
- package/lib/plugin-runtime/im/operation-endpoint.js +2 -0
- package/lib/plugin-runtime/im/outbound-delivery-runtime.js +40 -9
- package/lib/plugin-runtime/im/outbound-renderer.d.ts +12 -3
- package/lib/plugin-runtime/im/outbound-renderer.js +20 -13
- package/package.json +13 -13
package/README.md
CHANGED
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
| Agent 编排、工具安全与 MCP | `@zhin.js/agent` |
|
|
21
21
|
| 进程装配 | `@zhin.js/cli` |
|
|
22
22
|
|
|
23
|
-
Core 不提供第二套 Adapter 基类、Endpoint 类型或进程级注册表。平台插件统一从 `zhin.js/adapter` 导入 `defineAdapter` 与 `
|
|
23
|
+
Core 不提供第二套 Adapter 基类、Endpoint 类型或进程级注册表。平台插件统一从 `zhin.js/adapter` 导入 `Adapter`、`defineAdapter`、结构 `Endpoint` 与 `endpointSpec`。
|
|
24
24
|
|
|
25
25
|
## Plugin Runtime
|
|
26
26
|
|
|
@@ -56,37 +56,24 @@ export default defineCommand({
|
|
|
56
56
|
|
|
57
57
|
## Adapter 与 Endpoint
|
|
58
58
|
|
|
59
|
-
Adapter
|
|
59
|
+
Adapter 是账号配置、CAS 与连接 incarnation 的唯一 owner。Endpoint 继承真实 SDK 或实质协议 Client,并通过 `endpointSpec` / `createEndpointSpecification` 附加框架钩子;不覆盖 SDK 原生事件和 API。当前 generation 的 `AdapterIndex` 提供目录、租约路由和只读 connection 数据,不向普通查询暴露内部生命周期对象。
|
|
60
60
|
|
|
61
61
|
```typescript
|
|
62
|
-
// adapters/
|
|
63
|
-
import {
|
|
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'
|
|
64
66
|
|
|
65
|
-
|
|
66
|
-
readonly client = new ExampleClient()
|
|
67
|
-
|
|
68
|
-
async start(signal: AbortSignal) {
|
|
69
|
-
// connect transport; bind cancellation to signal
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
async stop() {
|
|
73
|
-
// idempotent cleanup
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
async send(request) {
|
|
77
|
-
return this.client.send(request.conversation.id, request.payload)
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
export default defineAdapter({
|
|
67
|
+
export default defineAdapter<NapCatEndpointConfig>({
|
|
82
68
|
capabilities: ['inbound', 'outbound'],
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
},
|
|
69
|
+
operations: ['recall'],
|
|
70
|
+
createAdapter: context => new NapcatAdapter(context),
|
|
86
71
|
})
|
|
87
72
|
```
|
|
88
73
|
|
|
89
|
-
|
|
74
|
+
`createAdapter` 是唯一工厂。公开 `Endpoint` 没有可继承基类,实际 Native Client 规范示例见 [适配器开发](../../../docs/authoring/adapters.md)。同一个公开 `AdapterRegistry` 推断 Command、Handler、Middleware 和 Tool 的实际 Client 与事件类型,不另建 Client token 或目录。
|
|
75
|
+
|
|
76
|
+
平台管理、撤回、编辑、reaction 与 typing 通过 specification 的显式 capability/control 端口暴露。调用者通过 `AdapterIndex.management/control` 获取捕获真实 incarnation 的受租约保护端口,不能从只读 connection 数据取未受保护的操作。普通业务消息继续走统一出站链路。
|
|
90
77
|
|
|
91
78
|
## 消息链路
|
|
92
79
|
|
|
@@ -100,7 +87,7 @@ Message.$reply / OutboundMessageService
|
|
|
100
87
|
→ canonical segment normalization
|
|
101
88
|
→ before.sendMessage middleware
|
|
102
89
|
→ AdapterIndex.send
|
|
103
|
-
→ Endpoint
|
|
90
|
+
→ Endpoint specification send hook
|
|
104
91
|
```
|
|
105
92
|
|
|
106
93
|
任何平台发送都必须经过这条链路。
|
|
@@ -22,10 +22,17 @@ export interface PendingLoginTaskPayload {
|
|
|
22
22
|
/** 其它扩展字段 */
|
|
23
23
|
[key: string]: unknown;
|
|
24
24
|
}
|
|
25
|
+
export interface LoginAssistEndpointIdentity {
|
|
26
|
+
readonly canonicalId: string;
|
|
27
|
+
readonly instanceId: string;
|
|
28
|
+
readonly epoch: number;
|
|
29
|
+
readonly incarnationId: string;
|
|
30
|
+
}
|
|
25
31
|
export interface PendingLoginTask {
|
|
26
32
|
id: string;
|
|
27
33
|
adapter: string;
|
|
28
34
|
endpointKey: string;
|
|
35
|
+
endpointIdentity?: LoginAssistEndpointIdentity;
|
|
29
36
|
type: LoginAssistType;
|
|
30
37
|
payload: PendingLoginTaskPayload;
|
|
31
38
|
createdAt: number;
|
|
@@ -35,6 +42,9 @@ export interface PendingLoginTask {
|
|
|
35
42
|
export interface WaitForInputOptions {
|
|
36
43
|
/** Endpoint-instance owner. Only this owner may cancel the task during rollback/retirement. */
|
|
37
44
|
owner: object;
|
|
45
|
+
/** Captured Endpoint incarnation; abort retires this exact challenge immediately. */
|
|
46
|
+
signal?: AbortSignal;
|
|
47
|
+
endpointIdentity?: LoginAssistEndpointIdentity;
|
|
38
48
|
/**
|
|
39
49
|
* 超时毫秒。默认 {@link DEFAULT_LOGIN_ASSIST_TIMEOUT_MS}。
|
|
40
50
|
* 传 `0` / `Infinity` / 负数表示不超时(仅测试或显式长驻场景)。
|
|
@@ -51,7 +61,6 @@ export declare class LoginAssist {
|
|
|
51
61
|
private readonly bus;
|
|
52
62
|
private readonly pending;
|
|
53
63
|
private readonly local;
|
|
54
|
-
private idSeq;
|
|
55
64
|
/** 构造时默认超时;可被 waitForInput options 覆盖 */
|
|
56
65
|
private readonly defaultTimeoutMs;
|
|
57
66
|
constructor(bus?: LoginAssistBus | null, options?: {
|
|
@@ -70,11 +79,11 @@ export declare class LoginAssist {
|
|
|
70
79
|
/**
|
|
71
80
|
* 消费者:提交结果,对应 waitForInput 的 Promise 会 resolve。
|
|
72
81
|
*/
|
|
73
|
-
submit(id: string, value: string | Record<string, unknown
|
|
82
|
+
submit(id: string, value: string | Record<string, unknown>, endpointIdentity?: LoginAssistEndpointIdentity): boolean;
|
|
74
83
|
/**
|
|
75
84
|
* 消费者:取消某条待办,对应 Promise 会 reject。
|
|
76
85
|
*/
|
|
77
|
-
cancel(id: string, reason?: string): boolean;
|
|
86
|
+
cancel(id: string, reason?: string, endpointIdentity?: LoginAssistEndpointIdentity): boolean;
|
|
78
87
|
/**
|
|
79
88
|
* Cancel pending tasks created by one exact Endpoint instance.
|
|
80
89
|
*/
|
|
@@ -1,14 +1,4 @@
|
|
|
1
|
-
|
|
2
|
-
* LoginAssist — 登录辅助生产者-消费者
|
|
3
|
-
*
|
|
4
|
-
* 适配器在需要人为辅助登录时(扫码、短信、滑块等)作为生产者投递待办;
|
|
5
|
-
* Web 控制台、命令行等作为消费者拉取待办并提交结果。
|
|
6
|
-
* 待办未消费前会一直保留,刷新页面后仍可继续消费。
|
|
7
|
-
*
|
|
8
|
-
* 事件:
|
|
9
|
-
* endpoint.login.pending — 有新待办时触发,payload: PendingLoginTask
|
|
10
|
-
* endpoint.login.expired — 超时自动取消时触发,payload: PendingLoginTask
|
|
11
|
-
*/
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
12
2
|
/** 默认 5 分钟;扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
|
|
13
3
|
export const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS = 5 * 60 * 1000;
|
|
14
4
|
// ============================================================================
|
|
@@ -18,7 +8,6 @@ export class LoginAssist {
|
|
|
18
8
|
bus;
|
|
19
9
|
pending = new Map();
|
|
20
10
|
local = new Map();
|
|
21
|
-
idSeq = 0;
|
|
22
11
|
/** 构造时默认超时;可被 waitForInput options 覆盖 */
|
|
23
12
|
defaultTimeoutMs;
|
|
24
13
|
constructor(bus, options) {
|
|
@@ -45,13 +34,15 @@ export class LoginAssist {
|
|
|
45
34
|
* 超时后 reject 并 emit `endpoint.login.expired`。
|
|
46
35
|
*/
|
|
47
36
|
waitForInput(adapter, endpointKey, type, payload, options) {
|
|
48
|
-
|
|
37
|
+
options.signal?.throwIfAborted();
|
|
38
|
+
const id = `login-${randomUUID()}`;
|
|
49
39
|
const timeoutMs = resolveTimeoutMs(options?.timeoutMs, this.defaultTimeoutMs);
|
|
50
40
|
const createdAt = Date.now();
|
|
51
41
|
const task = {
|
|
52
42
|
id,
|
|
53
43
|
adapter,
|
|
54
44
|
endpointKey,
|
|
45
|
+
...(options.endpointIdentity ? { endpointIdentity: Object.freeze({ ...options.endpointIdentity }) } : {}),
|
|
55
46
|
type,
|
|
56
47
|
payload: { message: payload.message ?? '', ...payload },
|
|
57
48
|
createdAt,
|
|
@@ -64,6 +55,7 @@ export class LoginAssist {
|
|
|
64
55
|
if (!this.pending.has(id))
|
|
65
56
|
return;
|
|
66
57
|
this.pending.delete(id);
|
|
58
|
+
this.#detach(entry);
|
|
67
59
|
try {
|
|
68
60
|
this.#notify('endpoint.login.expired', task);
|
|
69
61
|
}
|
|
@@ -76,20 +68,28 @@ export class LoginAssist {
|
|
|
76
68
|
entry.timer.unref?.();
|
|
77
69
|
}
|
|
78
70
|
this.pending.set(id, entry);
|
|
79
|
-
|
|
71
|
+
if (options.signal) {
|
|
72
|
+
const signal = options.signal;
|
|
73
|
+
const abort = () => { this.cancel(id, 'endpoint_retired'); };
|
|
74
|
+
signal.addEventListener('abort', abort, { once: true });
|
|
75
|
+
entry.detachAbort = () => signal.removeEventListener('abort', abort);
|
|
76
|
+
if (signal.aborted)
|
|
77
|
+
abort();
|
|
78
|
+
}
|
|
79
|
+
if (this.pending.has(id))
|
|
80
|
+
this.#notify('endpoint.login.pending', task);
|
|
80
81
|
});
|
|
81
82
|
return promise;
|
|
82
83
|
}
|
|
83
84
|
/**
|
|
84
85
|
* 消费者:提交结果,对应 waitForInput 的 Promise 会 resolve。
|
|
85
86
|
*/
|
|
86
|
-
submit(id, value) {
|
|
87
|
+
submit(id, value, endpointIdentity) {
|
|
87
88
|
const entry = this.pending.get(id);
|
|
88
|
-
if (!entry)
|
|
89
|
+
if (!entry || !matchesIdentity(entry.task.endpointIdentity, endpointIdentity))
|
|
89
90
|
return false;
|
|
90
91
|
this.pending.delete(id);
|
|
91
|
-
|
|
92
|
-
clearTimeout(entry.timer);
|
|
92
|
+
this.#detach(entry);
|
|
93
93
|
entry.resolve(value);
|
|
94
94
|
this.#notify('endpoint.login.resolved', entry.task);
|
|
95
95
|
return true;
|
|
@@ -97,13 +97,12 @@ export class LoginAssist {
|
|
|
97
97
|
/**
|
|
98
98
|
* 消费者:取消某条待办,对应 Promise 会 reject。
|
|
99
99
|
*/
|
|
100
|
-
cancel(id, reason = 'cancelled') {
|
|
100
|
+
cancel(id, reason = 'cancelled', endpointIdentity) {
|
|
101
101
|
const entry = this.pending.get(id);
|
|
102
|
-
if (!entry)
|
|
102
|
+
if (!entry || !matchesIdentity(entry.task.endpointIdentity, endpointIdentity))
|
|
103
103
|
return false;
|
|
104
104
|
this.pending.delete(id);
|
|
105
|
-
|
|
106
|
-
clearTimeout(entry.timer);
|
|
105
|
+
this.#detach(entry);
|
|
107
106
|
entry.reject(new Error(reason));
|
|
108
107
|
this.#notify('endpoint.login.resolved', entry.task);
|
|
109
108
|
return true;
|
|
@@ -117,8 +116,7 @@ export class LoginAssist {
|
|
|
117
116
|
if (entry.owner !== owner)
|
|
118
117
|
continue;
|
|
119
118
|
this.pending.delete(id);
|
|
120
|
-
|
|
121
|
-
clearTimeout(entry.timer);
|
|
119
|
+
this.#detach(entry);
|
|
122
120
|
entry.reject(new Error(reason));
|
|
123
121
|
this.#notify('endpoint.login.resolved', entry.task);
|
|
124
122
|
count += 1;
|
|
@@ -145,13 +143,17 @@ export class LoginAssist {
|
|
|
145
143
|
}
|
|
146
144
|
dispose() {
|
|
147
145
|
for (const [, entry] of this.pending) {
|
|
148
|
-
|
|
149
|
-
clearTimeout(entry.timer);
|
|
146
|
+
this.#detach(entry);
|
|
150
147
|
entry.reject(new Error('LoginAssist disposed'));
|
|
151
148
|
}
|
|
152
149
|
this.pending.clear();
|
|
153
150
|
this.local.clear();
|
|
154
151
|
}
|
|
152
|
+
#detach(entry) {
|
|
153
|
+
if (entry.timer)
|
|
154
|
+
clearTimeout(entry.timer);
|
|
155
|
+
entry.detachAbort?.();
|
|
156
|
+
}
|
|
155
157
|
#notify(name, task) {
|
|
156
158
|
try {
|
|
157
159
|
this.bus?.emit(name, task);
|
|
@@ -175,3 +177,7 @@ function resolveTimeoutMs(explicit, fallback) {
|
|
|
175
177
|
return undefined;
|
|
176
178
|
return raw;
|
|
177
179
|
}
|
|
180
|
+
function matchesIdentity(actual, expected) {
|
|
181
|
+
return expected === undefined || (actual !== undefined && actual.canonicalId === expected.canonicalId
|
|
182
|
+
&& actual.instanceId === expected.instanceId && actual.epoch === expected.epoch && actual.incarnationId === expected.incarnationId);
|
|
183
|
+
}
|
package/lib/feature/handler.d.ts
CHANGED
|
@@ -26,7 +26,7 @@ export interface ClientHandlerEvent<TAdapter extends RegisteredAdapterName, TNam
|
|
|
26
26
|
export interface ClientHandlerOptions<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>> {
|
|
27
27
|
readonly adapter: TAdapter;
|
|
28
28
|
readonly event: TName;
|
|
29
|
-
handle(this: HandlerContext, event: ClientHandlerEvent<TAdapter, TName>): void | Promise<void>;
|
|
29
|
+
handle(this: HandlerContext<unknown, TAdapter>, event: ClientHandlerEvent<TAdapter, TName>): void | Promise<void>;
|
|
30
30
|
}
|
|
31
31
|
export interface ClientHandlerWildcardEvent<TAdapter extends RegisteredAdapterName> {
|
|
32
32
|
readonly name: string;
|
|
@@ -37,8 +37,18 @@ export interface ClientHandlerWildcardEvent<TAdapter extends RegisteredAdapterNa
|
|
|
37
37
|
export interface ClientHandlerWildcardOptions<TAdapter extends RegisteredAdapterName> {
|
|
38
38
|
readonly adapter: TAdapter;
|
|
39
39
|
readonly event: '*';
|
|
40
|
-
handle(this: HandlerContext, event: ClientHandlerWildcardEvent<TAdapter>): void | Promise<void>;
|
|
40
|
+
handle(this: HandlerContext<unknown, TAdapter>, event: ClientHandlerWildcardEvent<TAdapter>): void | Promise<void>;
|
|
41
41
|
}
|
|
42
|
+
type CanonicalHandlerEvent = 'message.receive' | 'notice.receive' | 'request.receive' | 'system.receive' | 'platform.receive';
|
|
43
|
+
type BoundCanonicalHandler<K extends CanonicalHandlerEvent> = {
|
|
44
|
+
[A in RegisteredAdapterName]: {
|
|
45
|
+
readonly adapter: A;
|
|
46
|
+
readonly event: K;
|
|
47
|
+
handle(this: HandlerContext<unknown, A>, ...args: HandlerEventMap[K]): void | Promise<void>;
|
|
48
|
+
};
|
|
49
|
+
}[RegisteredAdapterName];
|
|
50
|
+
/** Canonical messages share the captured operation Session; native callbacks retain their original payload. */
|
|
51
|
+
export declare function defineHandler<K extends CanonicalHandlerEvent>(options: BoundCanonicalHandler<K>): Readonly<HandlerDefinition<K>>;
|
|
42
52
|
export declare function defineHandler<TAdapter extends RegisteredAdapterName, TName extends NativeEventName<TAdapter>>(options: ClientHandlerOptions<TAdapter, TName>): Readonly<HandlerDefinition<'platform.receive'>>;
|
|
43
53
|
/** Handle every native event from one Client without pretending unknown payloads are typed. */
|
|
44
54
|
export declare function defineHandler<TAdapter extends RegisteredAdapterName>(options: ClientHandlerWildcardOptions<TAdapter>): Readonly<HandlerDefinition<'platform.receive'>>;
|
package/lib/feature/handler.js
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
export { parseHandlerDefinition, HandlerIndex, isHandlerIndex, handlerFeatureId, handlerFeature, handlerEventFromLocalName, resolveHandlerEvent, } from '@zhin.js/handler';
|
|
3
3
|
import { defineHandler as defineHandlerFeature, } from '@zhin.js/handler';
|
|
4
4
|
export function defineHandler(options) {
|
|
5
|
-
if (!('adapter' in options) || typeof options.adapter !== 'string'
|
|
5
|
+
if (!('adapter' in options) || typeof options.adapter !== 'string'
|
|
6
|
+
|| ['message.receive', 'notice.receive', 'request.receive', 'system.receive', 'platform.receive'].includes(options.event ?? '')) {
|
|
6
7
|
return defineHandlerFeature(options);
|
|
7
8
|
}
|
|
8
9
|
const adapter = options.adapter;
|
package/lib/index.d.ts
CHANGED
|
@@ -44,4 +44,6 @@ export { Schema } from '@zhin.js/schema';
|
|
|
44
44
|
export { ScheduleEngine, Scheduler, } from '@zhin.js/kernel';
|
|
45
45
|
export type { Schedule, JobPayload, JobState, ScheduledJob, JobStore, JobCallback, AddJobOptions, IScheduler, SchedulerOptions, ScheduleFireCallback, MemoryScheduleRegistration, ScheduleEngineOptions, JobContext, ResolvedJob, ScheduleKind, } from '@zhin.js/kernel';
|
|
46
46
|
export type { ConversationRef, DeliveryReceipt } from '@zhin.js/im-contract';
|
|
47
|
-
export
|
|
47
|
+
export { conversationRefKey } from '@zhin.js/im-contract';
|
|
48
|
+
export { readOperationSession } from '@zhin.js/feature-kit';
|
|
49
|
+
export type { CapabilityContext, OperationClientPort, OperationSession, OperationScene, OperationSender, OperationMessage, OperationMessageRef } from '@zhin.js/feature-kit';
|
package/lib/index.js
CHANGED
|
@@ -42,3 +42,5 @@ export * from '@zhin.js/database';
|
|
|
42
42
|
export * from '@zhin.js/logger';
|
|
43
43
|
export { Schema } from '@zhin.js/schema';
|
|
44
44
|
export { ScheduleEngine, Scheduler, } from '@zhin.js/kernel';
|
|
45
|
+
export { conversationRefKey } from '@zhin.js/im-contract';
|
|
46
|
+
export { readOperationSession } from '@zhin.js/feature-kit';
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { EndpointControl, EndpointManagement } from '@zhin.js/adapter';
|
|
2
|
+
import type { ConversationRef, DeliveryReceipt } from '@zhin.js/im-contract';
|
|
3
|
+
import type { Locale, PluginId } from '@zhin.js/plugin-runtime';
|
|
4
|
+
import type { SendContent } from './contracts.js';
|
|
5
|
+
/** Capture while the source Message/event is active, before handing work to an asynchronous owner. */
|
|
6
|
+
export interface CaptureEndpointOperationInput {
|
|
7
|
+
/** Canonical complete source address; never an account alias. */
|
|
8
|
+
readonly target: ConversationRef;
|
|
9
|
+
/** Actual source Client, checked against the selected account incarnation. */
|
|
10
|
+
readonly client: unknown;
|
|
11
|
+
/** Lifetime of the work that is retaining the source operation. */
|
|
12
|
+
readonly signal?: AbortSignal;
|
|
13
|
+
/** Author supplied by trusted composition or the owner-bound Host facade. */
|
|
14
|
+
readonly requester?: PluginId;
|
|
15
|
+
}
|
|
16
|
+
/** Retained execution authority for one concrete Client; consumers must release it in finally. */
|
|
17
|
+
export interface CapturedEndpointOperation {
|
|
18
|
+
readonly target: ConversationRef;
|
|
19
|
+
readonly signal: AbortSignal;
|
|
20
|
+
/** The same guarded semantic ports as ordinary calls, pinned to the retained Client. */
|
|
21
|
+
readonly control?: EndpointControl;
|
|
22
|
+
readonly management?: EndpointManagement;
|
|
23
|
+
/** Uses the ordinary renderer/middleware/delivery pipeline with the captured author. */
|
|
24
|
+
send(content: SendContent, options?: Readonly<{
|
|
25
|
+
locale?: Locale;
|
|
26
|
+
signal?: AbortSignal;
|
|
27
|
+
}>): Promise<DeliveryReceipt>;
|
|
28
|
+
/** Stops new calls and releases source/Root leases after accepted calls drain; never stops the account. */
|
|
29
|
+
release(): void;
|
|
30
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -2,5 +2,12 @@ import type { CommandDispatchResult, CommandIndex } from '@zhin.js/command';
|
|
|
2
2
|
import type { ConversationRef } from '@zhin.js/im-contract';
|
|
3
3
|
import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
|
|
4
4
|
import type { SendContent } from './contracts.js';
|
|
5
|
+
/** Rendering dependencies for one menu response; callbacks retain the same generation. */
|
|
6
|
+
export interface CommandMenuReplyContext {
|
|
7
|
+
readonly commands: CommandIndex;
|
|
8
|
+
readonly snapshot: RuntimeSnapshot;
|
|
9
|
+
readonly conversation: ConversationRef;
|
|
10
|
+
readonly prefix: string;
|
|
11
|
+
}
|
|
5
12
|
/** IM-only presentation: Command remains independent of JSX, adapters and callback registries. */
|
|
6
|
-
export declare function commandMenuReply(result: CommandDispatchResult, commands
|
|
13
|
+
export declare function commandMenuReply(result: CommandDispatchResult, { commands, snapshot, conversation, prefix }: CommandMenuReplyContext): Promise<SendContent>;
|
|
@@ -8,7 +8,7 @@ const menuMessages = createMessages({
|
|
|
8
8
|
next: { 'zh-CN': '下一页', en: 'Next' },
|
|
9
9
|
});
|
|
10
10
|
/** IM-only presentation: Command remains independent of JSX, adapters and callback registries. */
|
|
11
|
-
export async function commandMenuReply(result, commands, snapshot, conversation, prefix) {
|
|
11
|
+
export async function commandMenuReply(result, { commands, snapshot, conversation, prefix }) {
|
|
12
12
|
// Only validated menus carry this metadata; other command return values stay opaque.
|
|
13
13
|
const menu = result.menu;
|
|
14
14
|
if (!menu)
|
|
@@ -28,8 +28,8 @@ export async function commandMenuReply(result, commands, snapshot, conversation,
|
|
|
28
28
|
if (disabled)
|
|
29
29
|
return [];
|
|
30
30
|
const input = `${menu.keyword}${menu.pluginKey ? ` ${menu.pluginKey}` : ''} --page ${page}`;
|
|
31
|
-
const next = await commands.dispatch(input, message,
|
|
32
|
-
return commandMenuReply(next, commands, snapshot, message.conversation, prefix);
|
|
31
|
+
const next = await commands.dispatch({ input: input, source: message, commandPrefix: prefix, snapshot: snapshot, locale: menu.locale });
|
|
32
|
+
return commandMenuReply(next, { commands: commands, snapshot: snapshot, conversation: message.conversation, prefix: prefix });
|
|
33
33
|
},
|
|
34
34
|
});
|
|
35
35
|
return [content,
|
|
@@ -1,10 +1,11 @@
|
|
|
1
|
+
import type { CapturedEndpointOperation } from './captured-endpoint-operation.js';
|
|
1
2
|
import type { JSXElement } from '@zhin.js/jsx';
|
|
2
3
|
import { type CommandMenuPage } from '@zhin.js/command';
|
|
3
|
-
import type
|
|
4
|
-
import { type
|
|
5
|
-
import { operationInputBinding, operationInputSignal } from '@zhin.js/feature-kit';
|
|
4
|
+
import { type PluginId, type RuntimeSnapshot, type Locale } from '@zhin.js/plugin-runtime';
|
|
5
|
+
import { operationInputBinding, operationInputSignal, operationSession, type OperationSession } from '@zhin.js/feature-kit';
|
|
6
6
|
import type { ConversationRef, DeliveryReceipt, MessageRef } from '@zhin.js/im-contract';
|
|
7
7
|
import type { MessageOrigin } from './inbound-origin.js';
|
|
8
|
+
import type { OperationEndpointSource } from './operation-endpoint.js';
|
|
8
9
|
import type { MediaRef, Segment } from '../../built/segment-contract/types.js';
|
|
9
10
|
import { interactionOperationScope, type InteractionOperationScope } from './interaction-operation.js';
|
|
10
11
|
export type { MediaRef, Segment };
|
|
@@ -36,6 +37,9 @@ export interface MessageSenderRef {
|
|
|
36
37
|
readonly roles?: readonly string[];
|
|
37
38
|
}
|
|
38
39
|
export interface IncomingMessage {
|
|
40
|
+
/** Original SDK message callback object; operation-only, not a persistence field. */
|
|
41
|
+
readonly event?: unknown;
|
|
42
|
+
readonly platformSentAt?: number;
|
|
39
43
|
readonly conversation: ConversationRef;
|
|
40
44
|
readonly message?: MessageRef;
|
|
41
45
|
readonly content: string;
|
|
@@ -70,7 +74,7 @@ export interface IncomingContext {
|
|
|
70
74
|
/** 消息是否 @了机器人。 */
|
|
71
75
|
readonly mentioned?: boolean;
|
|
72
76
|
}
|
|
73
|
-
export interface SendRequest {
|
|
77
|
+
export interface SendRequest extends OperationEndpointSource {
|
|
74
78
|
/** Language captured by the sending operation; absent for explicit sends without a user. */
|
|
75
79
|
readonly locale?: Locale;
|
|
76
80
|
readonly conversation: ConversationRef;
|
|
@@ -120,7 +124,7 @@ export interface MessageDispatchResult {
|
|
|
120
124
|
readonly menu?: CommandMenuPage;
|
|
121
125
|
}
|
|
122
126
|
/** Canonical message value delivered to inbound middleware and handlers. */
|
|
123
|
-
export interface MessageBase extends IncomingMessage {
|
|
127
|
+
export interface MessageBase extends Omit<IncomingMessage, 'event' | 'platformSentAt'> {
|
|
124
128
|
/** Language resolved from the sender and project when this operation began. */
|
|
125
129
|
readonly locale: Locale;
|
|
126
130
|
/** Effective chat command environment; undefined means no resolved environment. */
|
|
@@ -148,63 +152,80 @@ export interface MessageBase extends IncomingMessage {
|
|
|
148
152
|
readonly $replyToGroup: (groupId: string, content: SendContent) => Promise<DeliveryReceipt>;
|
|
149
153
|
readonly $replyToChannel: (channelId: string, guildId: string, content: SendContent, threadId?: string) => Promise<DeliveryReceipt>;
|
|
150
154
|
}
|
|
155
|
+
/** Captured once from the actual inbound Endpoint operation, never from message metadata. */
|
|
156
|
+
export type RuntimeMessageSessionBinding = Omit<OperationSession<string>, 'reply'>;
|
|
157
|
+
/** Immutable facts shared by every author-bound view of one received message. */
|
|
158
|
+
export interface RuntimeMessageFacts {
|
|
159
|
+
readonly conversation: ConversationRef;
|
|
160
|
+
readonly content: string;
|
|
161
|
+
readonly sender?: MessageSenderRef;
|
|
162
|
+
readonly metadata?: Readonly<Record<string, unknown>>;
|
|
163
|
+
readonly segments?: readonly Segment[];
|
|
164
|
+
readonly message?: MessageRef;
|
|
165
|
+
readonly endpointId?: string;
|
|
166
|
+
readonly mentioned?: boolean;
|
|
167
|
+
readonly replyTo?: {
|
|
168
|
+
readonly id: string;
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
/** Presentation resolved for an author view without changing its transport identity. */
|
|
172
|
+
export interface RuntimeMessagePresentation {
|
|
173
|
+
readonly locale?: Locale;
|
|
174
|
+
readonly commands?: Readonly<{
|
|
175
|
+
prefix: string;
|
|
176
|
+
menu?: string;
|
|
177
|
+
}>;
|
|
178
|
+
readonly resolveCommands?: (message: RuntimeMessage) => Readonly<{
|
|
179
|
+
prefix: string;
|
|
180
|
+
menu?: string;
|
|
181
|
+
}>;
|
|
182
|
+
}
|
|
183
|
+
/** Captured execution authority; its callbacks delegate to Core's existing operation lease. */
|
|
184
|
+
export interface RuntimeMessageOperation {
|
|
185
|
+
readonly generation: number;
|
|
186
|
+
readonly reply: (content: SendContent, requester?: PluginId, targetConversation?: ConversationAddress) => Promise<DeliveryReceipt>;
|
|
187
|
+
readonly client?: () => unknown;
|
|
188
|
+
readonly clientAdapter?: string;
|
|
189
|
+
readonly requester?: PluginId;
|
|
190
|
+
readonly snapshot?: RuntimeSnapshot;
|
|
191
|
+
readonly assertActive?: () => void;
|
|
192
|
+
readonly origin?: MessageOrigin;
|
|
193
|
+
/** Explicit Root stop, source-account and caller lifetime, never generation replacement alone. */
|
|
194
|
+
readonly signal?: AbortSignal;
|
|
195
|
+
readonly captureInteraction?: (owner: PluginId) => CapturedEndpointOperation;
|
|
196
|
+
readonly session?: RuntimeMessageSessionBinding;
|
|
197
|
+
readonly registerOperationView?: (view: object, owner: PluginId) => void;
|
|
198
|
+
readonly presentation?: RuntimeMessagePresentation;
|
|
199
|
+
}
|
|
151
200
|
/** Canonical runtime message with optional plugin-owned extensions. */
|
|
152
201
|
export type Message<T extends object = {}> = MessageBase & T;
|
|
153
202
|
/** @internal Generation-scoped implementation of the public Message contract. */
|
|
154
203
|
export declare class RuntimeMessage implements MessageBase {
|
|
155
204
|
#private;
|
|
205
|
+
readonly locale: Locale;
|
|
206
|
+
readonly commandPrefix?: string;
|
|
207
|
+
readonly commandMenu?: string;
|
|
156
208
|
readonly conversation: ConversationRef;
|
|
157
209
|
readonly content: string;
|
|
158
210
|
readonly generation: number;
|
|
159
|
-
readonly sender?: MessageSenderRef
|
|
211
|
+
readonly sender?: MessageSenderRef;
|
|
160
212
|
readonly metadata: Readonly<Record<string, unknown>>;
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
readonly segments?: readonly Segment[] | undefined;
|
|
166
|
-
/** 结构化入站消息身份(平台原生 message id 经 MessageRef 传递)。 */
|
|
167
|
-
readonly message?: MessageRef | undefined;
|
|
168
|
-
readonly endpointId?: string | undefined;
|
|
169
|
-
readonly mentioned?: boolean | undefined;
|
|
213
|
+
readonly segments?: readonly Segment[];
|
|
214
|
+
readonly message?: MessageRef;
|
|
215
|
+
readonly endpointId?: string;
|
|
216
|
+
readonly mentioned?: boolean;
|
|
170
217
|
readonly replyTo?: {
|
|
171
218
|
readonly id: string;
|
|
172
|
-
}
|
|
173
|
-
readonly clientAdapter?: string
|
|
174
|
-
readonly locale: Locale;
|
|
175
|
-
readonly commandPrefix?: string;
|
|
176
|
-
readonly commandMenu?: string;
|
|
219
|
+
};
|
|
220
|
+
readonly clientAdapter?: string;
|
|
177
221
|
readonly origin?: MessageOrigin;
|
|
178
|
-
/**
|
|
179
|
-
constructor(
|
|
180
|
-
/**
|
|
181
|
-
|
|
182
|
-
* Command dispatcher 优先使用此字段,以支持 mention、image 等结构化参数。
|
|
183
|
-
*/
|
|
184
|
-
segments?: readonly Segment[] | undefined,
|
|
185
|
-
/** 结构化入站消息身份(平台原生 message id 经 MessageRef 传递)。 */
|
|
186
|
-
message?: MessageRef | undefined, endpointId?: string | undefined, mentioned?: boolean | undefined, replyTo?: {
|
|
187
|
-
readonly id: string;
|
|
188
|
-
} | undefined, client?: () => unknown, clientAdapter?: string | undefined, binding?: Readonly<{
|
|
189
|
-
locale?: Locale;
|
|
190
|
-
commands?: Readonly<{
|
|
191
|
-
prefix: string;
|
|
192
|
-
menu?: string;
|
|
193
|
-
}>;
|
|
194
|
-
resolveCommands?: (message: RuntimeMessage) => Readonly<{
|
|
195
|
-
prefix: string;
|
|
196
|
-
menu?: string;
|
|
197
|
-
}>;
|
|
198
|
-
requester?: PluginId;
|
|
199
|
-
snapshot?: RuntimeSnapshot;
|
|
200
|
-
assertActive?: () => void;
|
|
201
|
-
origin?: MessageOrigin;
|
|
202
|
-
retirementSignal?: AbortSignal;
|
|
203
|
-
registerOperationView?: (view: object, owner: PluginId) => void;
|
|
204
|
-
}>);
|
|
222
|
+
/** Core owns these immutable facts; author rebinding shares them and the captured operation. */
|
|
223
|
+
constructor(facts: RuntimeMessageFacts, operation: RuntimeMessageOperation);
|
|
224
|
+
/** The same captured data, with reply authority rebound by operationInputBinding. */
|
|
225
|
+
[operationSession](): OperationSession<string> | undefined;
|
|
205
226
|
/** @internal A frozen view whose sends retain the current author's exact operation. */
|
|
206
227
|
[operationInputBinding](owner: PluginId, snapshot: RuntimeSnapshot): RuntimeMessage;
|
|
207
|
-
/** @internal
|
|
228
|
+
/** @internal Explicit operation cancellation; replacement alone does not end accepted work. */
|
|
208
229
|
[operationInputSignal](): AbortSignal | undefined;
|
|
209
230
|
/** @internal The command/handler author's actual leased operation. */
|
|
210
231
|
[interactionOperationScope](): InteractionOperationScope | undefined;
|