@zhin.js/core 1.1.38 → 1.1.39

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 (43) hide show
  1. package/lib/built/ai-access.d.ts +2 -2
  2. package/lib/built/ai-access.js +4 -4
  3. package/lib/built/ai-outbound/types.d.ts +1 -1
  4. package/lib/built/ai-trigger.d.ts +1 -1
  5. package/lib/built/ai-trigger.js +17 -10
  6. package/lib/built/interactive-segments/action.d.ts +3 -3
  7. package/lib/built/interactive-segments/action.js +1 -1
  8. package/lib/built/message-enrich.d.ts +19 -22
  9. package/lib/built/message-enrich.js +47 -42
  10. package/lib/built/tool-access.d.ts +2 -2
  11. package/lib/built/tool-access.js +2 -2
  12. package/lib/im-scene.d.ts +4 -3
  13. package/lib/im-scene.js +9 -9
  14. package/lib/im-session-id.d.ts +20 -12
  15. package/lib/im-session-id.js +8 -8
  16. package/lib/index.d.ts +2 -1
  17. package/lib/index.js +1 -1
  18. package/lib/message.d.ts +1 -29
  19. package/lib/message.js +1 -27
  20. package/lib/notice.d.ts +34 -32
  21. package/lib/notice.js +21 -7
  22. package/lib/plugin-runtime/im/contracts.d.ts +23 -1
  23. package/lib/plugin-runtime/im/contracts.js +4 -1
  24. package/lib/plugin-runtime/im/conversation-runtime.js +22 -31
  25. package/lib/plugin-runtime/im/inbound-runtime.d.ts +2 -2
  26. package/lib/plugin-runtime/im/inbound-runtime.js +58 -29
  27. package/lib/plugin-runtime/im/index.d.ts +3 -0
  28. package/lib/plugin-runtime/im/index.js +3 -0
  29. package/lib/plugin-runtime/im/public-api.d.ts +1 -1
  30. package/lib/request.d.ts +27 -35
  31. package/lib/request.js +14 -6
  32. package/lib/side-event/base.d.ts +64 -43
  33. package/lib/side-event/base.js +66 -19
  34. package/lib/side-event/dispatch.js +40 -38
  35. package/lib/side-event/normalize.d.ts +9 -8
  36. package/lib/side-event/normalize.js +9 -8
  37. package/lib/side-event/types.d.ts +3 -6
  38. package/lib/side-event/types.js +0 -5
  39. package/lib/system-event.d.ts +17 -11
  40. package/lib/system-event.js +8 -6
  41. package/lib/types.d.ts +3 -2
  42. package/lib/utils.d.ts +1 -1
  43. package/package.json +4 -4
@@ -1,51 +1,72 @@
1
- import type { MessageSender } from '../types.js';
2
- /**
3
- * Side Event 共享基础结构(Notice 与 Request 共用)。
4
- * 字段统一为 `$foo_bar` 命名。
5
- *
6
- * 完整事件名:`${$type}.${$scene_type}.${$sub_type}`(见 `formatSideEventName`)。
7
- */
8
- export interface SideEventBase {
9
- /** 平台侧去重键 / flag(非 DB 行 id) */
10
- $id: string;
11
- $adapter: string;
12
- $endpoint: string;
13
- /** 命名空间:`notice` 或 `request` */
14
- $type: string;
15
- /** 平台场景 ID(群号、用户号、频道 ID 等) */
16
- $scene_id: string;
17
- /** 场景域(如 group、friend、channel、endpoint) */
18
- $scene_type?: string;
19
- /** 动作子类型(如 member_increase、add、poke) */
20
- $sub_type?: string;
21
- /** 主参与者(原 Notice.$operator / Request.$sender) */
22
- $actor?: MessageSender;
23
- /** 被操作对象 */
24
- $target?: MessageSender;
25
- /** 毫秒时间戳 */
26
- $timestamp: number;
27
- /** Canonical relation fields populated by the Adapter boundary. */
28
- $message_id?: string;
29
- $reaction?: string;
30
- $operation?: 'added' | 'removed';
31
- $duration_seconds?: number;
32
- $role?: string;
33
- $enabled?: boolean;
1
+ import type { ConversationRef, EndpointRef } from '@zhin.js/im-contract';
2
+ import type { ConversationAddress, MessageSenderRef } from '../plugin-runtime/im/contracts.js';
3
+ /** Shared Endpoint event data, with no assumption about chat or participants. */
4
+ export interface IncomingEndpointEvent {
5
+ readonly id: string;
6
+ readonly type: 'notice' | 'request' | 'system';
7
+ readonly name: string;
8
+ readonly endpointId?: string;
9
+ readonly clientAdapter?: string;
10
+ readonly timestamp: number;
11
+ readonly metadata: Readonly<Record<string, unknown>>;
34
12
  }
35
- /** 组合 Side Event 完整类型名 */
36
- export declare function composeSideEventName(type: string, sceneType: string | undefined, subType: string | undefined): string;
37
- /** 从 Side Event 字段生成完整类型名 */
38
- export declare function formatSideEventName(event: Pick<SideEventBase, '$type' | '$scene_type' | '$sub_type'>): string;
39
- /** 判断 Side Event 是否匹配完整类型名(如 `notice.group.member_increase`) */
40
- export declare function matchesSideEventName(event: Pick<SideEventBase, '$type' | '$scene_type' | '$sub_type'>, fullName: string): boolean;
41
- /** 解析完整类型名为三段 */
13
+ /** Identity and lifetime shared by all canonical Endpoint event views. */
14
+ export interface EndpointEventBase extends IncomingEndpointEvent {
15
+ readonly endpoint: EndpointRef;
16
+ readonly generation: number;
17
+ readonly $client: unknown;
18
+ }
19
+ /** Adapter-normalized Notice/Request data. System events do not inherit this contract. */
20
+ export interface IncomingSideEvent extends IncomingEndpointEvent {
21
+ readonly type: 'notice' | 'request';
22
+ readonly conversation?: ConversationAddress;
23
+ readonly actor?: MessageSenderRef;
24
+ readonly target?: MessageSenderRef;
25
+ }
26
+ export interface SideEventBase extends IncomingSideEvent, Omit<EndpointEventBase, 'type'> {
27
+ readonly conversation?: ConversationRef;
28
+ }
29
+ /** @internal Context captured by one generation-owned ingress operation. */
30
+ export interface EndpointEventContext {
31
+ readonly endpoint: EndpointRef;
32
+ readonly generation: number;
33
+ readonly client: () => unknown;
34
+ }
35
+ /** @internal Endpoint identity/lifetime only; SystemEvent has no chat fields. */
36
+ export declare class RuntimeEndpointEvent implements EndpointEventBase {
37
+ #private;
38
+ readonly id: string;
39
+ readonly type: IncomingEndpointEvent['type'];
40
+ readonly name: string;
41
+ readonly endpoint: EndpointRef;
42
+ readonly endpointId?: string;
43
+ readonly clientAdapter?: string;
44
+ readonly timestamp: number;
45
+ readonly metadata: Readonly<Record<string, unknown>>;
46
+ readonly generation: number;
47
+ constructor(input: IncomingEndpointEvent, context: EndpointEventContext);
48
+ get $client(): unknown;
49
+ }
50
+ /** @internal Shared Notice/Request data view. */
51
+ export declare class RuntimeSideEvent extends RuntimeEndpointEvent implements SideEventBase {
52
+ readonly type: IncomingSideEvent['type'];
53
+ readonly conversation?: ConversationRef;
54
+ readonly actor?: MessageSenderRef;
55
+ readonly target?: MessageSenderRef;
56
+ constructor(input: IncomingSideEvent, context: EndpointEventContext);
57
+ }
58
+ export declare function composeSideEventName(type: string, sceneType?: string, subType?: string): string;
59
+ /** The full semantic event name is the only event-name authority. */
60
+ export declare function formatSideEventName(event: Pick<IncomingEndpointEvent, 'name'>): string;
61
+ export declare function matchesSideEventName(event: Pick<IncomingEndpointEvent, 'name'>, fullName: string): boolean;
42
62
  export declare function parseSideEventName(fullName: string): {
43
63
  type: string;
44
64
  scene_type?: string;
45
65
  sub_type?: string;
46
66
  };
47
- /** 将 Side Event 场景映射为 IM 发送通道(group-suite 等消费者用) */
48
- export declare function sideEventSendChannel(event: Pick<SideEventBase, '$scene_type' | '$scene_id'>): {
67
+ /** Map known platform scene domains; non-conversation events have no send target. */
68
+ export declare function sideEventConversation(sceneType: string | undefined, id: string): ConversationAddress | undefined;
69
+ export declare function sideEventSendChannel(event: Pick<IncomingSideEvent, 'conversation'>): {
49
70
  id: string;
50
71
  type: 'group' | 'private' | 'channel';
51
- };
72
+ } | undefined;
@@ -1,30 +1,77 @@
1
- /** 组合 Side Event 完整类型名 */
1
+ /** @internal Endpoint identity/lifetime only; SystemEvent has no chat fields. */
2
+ export class RuntimeEndpointEvent {
3
+ id;
4
+ type;
5
+ name;
6
+ endpoint;
7
+ endpointId;
8
+ clientAdapter;
9
+ timestamp;
10
+ metadata;
11
+ generation;
12
+ #client;
13
+ constructor(input, context) {
14
+ if (!input.name.startsWith(`${input.type}.`)) {
15
+ throw new TypeError('Event name must belong to its event type');
16
+ }
17
+ this.id = input.id;
18
+ this.type = input.type;
19
+ this.name = input.name;
20
+ this.endpoint = Object.freeze({ ...context.endpoint });
21
+ this.endpointId = input.endpointId;
22
+ this.clientAdapter = input.clientAdapter ?? context.endpoint.adapter;
23
+ this.timestamp = input.timestamp;
24
+ this.metadata = Object.freeze({ ...input.metadata });
25
+ this.generation = context.generation;
26
+ this.#client = context.client;
27
+ }
28
+ get $client() { return this.#client(); }
29
+ }
30
+ /** @internal Shared Notice/Request data view. */
31
+ export class RuntimeSideEvent extends RuntimeEndpointEvent {
32
+ conversation;
33
+ actor;
34
+ target;
35
+ constructor(input, context) {
36
+ super(input, context);
37
+ this.conversation = input.conversation ? Object.freeze({
38
+ ...input.conversation,
39
+ ...(input.conversation.parent ? { parent: Object.freeze({ ...input.conversation.parent }) } : {}),
40
+ endpoint: this.endpoint,
41
+ }) : undefined;
42
+ this.actor = freezeSender(input.actor);
43
+ this.target = freezeSender(input.target);
44
+ }
45
+ }
46
+ function freezeSender(sender) {
47
+ return sender ? Object.freeze({
48
+ ...sender,
49
+ ...(sender.roles ? { roles: Object.freeze([...sender.roles]) } : {}),
50
+ }) : undefined;
51
+ }
2
52
  export function composeSideEventName(type, sceneType, subType) {
3
- return [type, sceneType, subType].filter((p) => !!p).join('.');
53
+ return [type, sceneType, subType].filter(Boolean).join('.');
4
54
  }
5
- /** 从 Side Event 字段生成完整类型名 */
55
+ /** The full semantic event name is the only event-name authority. */
6
56
  export function formatSideEventName(event) {
7
- return composeSideEventName(event.$type, event.$scene_type, event.$sub_type);
57
+ return event.name;
8
58
  }
9
- /** 判断 Side Event 是否匹配完整类型名(如 `notice.group.member_increase`) */
10
59
  export function matchesSideEventName(event, fullName) {
11
- return formatSideEventName(event) === fullName;
60
+ return event.name === fullName;
12
61
  }
13
- /** 解析完整类型名为三段 */
14
62
  export function parseSideEventName(fullName) {
15
63
  const parts = fullName.split('.');
16
- return {
17
- type: parts[0] ?? '',
18
- scene_type: parts[1],
19
- sub_type: parts.slice(2).join('.') || undefined,
20
- };
64
+ return { type: parts[0] ?? '', scene_type: parts[1], sub_type: parts.slice(2).join('.') || undefined };
65
+ }
66
+ /** Map known platform scene domains; non-conversation events have no send target. */
67
+ export function sideEventConversation(sceneType, id) {
68
+ if (!id)
69
+ return undefined;
70
+ const kind = sceneType === 'friend' ? 'private' : sceneType;
71
+ return kind === 'private' || kind === 'group' || kind === 'channel'
72
+ ? Object.freeze({ kind, id })
73
+ : undefined;
21
74
  }
22
- /** 将 Side Event 场景映射为 IM 发送通道(group-suite 等消费者用) */
23
75
  export function sideEventSendChannel(event) {
24
- const domain = event.$scene_type ?? 'private';
25
- if (domain === 'group')
26
- return { id: event.$scene_id, type: 'group' };
27
- if (domain === 'channel')
28
- return { id: event.$scene_id, type: 'channel' };
29
- return { id: event.$scene_id, type: 'private' };
76
+ return event.conversation ? { id: event.conversation.id, type: event.conversation.kind } : undefined;
30
77
  }
@@ -1,3 +1,4 @@
1
+ import { composeSideEventName, sideEventConversation } from './base.js';
1
2
  import { buildNotice, buildRequest, buildSystem, mapNoticeParts, mapRequestParts, resolveSideEventDedupeKey, senderFromId, } from './normalize.js';
2
3
  /**
3
4
  * Normalize OneBot / icqq-style notice|request|meta payloads and feed Endpoint.emit().
@@ -25,26 +26,25 @@ export async function receiveOneBotLikeSideEvent(emit, input) {
25
26
  ? raw.user_id
26
27
  : undefined;
27
28
  const notice = buildNotice(raw, {
28
- $id: id,
29
- $adapter: input.adapter,
30
- $endpoint: input.endpointKey,
31
- $type: 'notice',
32
- $scene_id: String(raw.group_id ?? raw.user_id ?? input.endpointKey),
33
- $scene_type: parts.scene_type,
34
- $sub_type: parts.sub_type,
35
- $actor: senderFromId(actorId),
36
- $target: senderFromId(targetId),
37
- $timestamp: toMillis(raw.time),
38
- ...(raw.message_id != null ? { $message_id: String(raw.message_id) } : {}),
29
+ id,
30
+ clientAdapter: input.adapter,
31
+ endpointId: input.endpointKey,
32
+ type: 'notice',
33
+ conversation: oneBotConversation(parts.scene_type, raw),
34
+ name: composeSideEventName('notice', parts.scene_type, parts.sub_type),
35
+ actor: senderFromId(actorId),
36
+ target: senderFromId(targetId),
37
+ timestamp: toMillis(raw.time),
38
+ ...(raw.message_id != null ? { messageId: String(raw.message_id) } : {}),
39
39
  ...(raw.emoji_id != null || raw.code != null
40
- ? { $reaction: String(raw.emoji_id ?? raw.code) }
40
+ ? { reaction: String(raw.emoji_id ?? raw.code) }
41
41
  : {}),
42
42
  ...(parts.sub_type === 'emoji_reaction'
43
- ? { $operation: /delete|remove/i.test(String(raw.sub_type ?? noticeType)) ? 'removed' : 'added' }
43
+ ? { operation: /delete|remove/i.test(String(raw.sub_type ?? noticeType)) ? 'removed' : 'added' }
44
44
  : {}),
45
- ...(raw.duration != null ? { $duration_seconds: Math.max(0, Number(raw.duration) || 0) } : {}),
45
+ ...(raw.duration != null ? { durationSeconds: Math.max(0, Number(raw.duration) || 0) } : {}),
46
46
  ...(parts.sub_type === 'admin_change'
47
- ? { $role: 'admin', $enabled: String(raw.sub_type ?? '') === 'set' }
47
+ ? { role: 'admin', enabled: String(raw.sub_type ?? '') === 'set' }
48
48
  : {}),
49
49
  });
50
50
  await emit('notice.receive', notice);
@@ -74,16 +74,15 @@ export async function receiveOneBotLikeSideEvent(emit, input) {
74
74
  return operation;
75
75
  };
76
76
  const request = buildRequest(raw, {
77
- $id: id,
78
- $adapter: input.adapter,
79
- $endpoint: input.endpointKey,
80
- $type: 'request',
81
- $scene_id: String(raw.group_id ?? raw.user_id ?? input.endpointKey),
82
- $scene_type: parts.scene_type,
83
- $sub_type: parts.sub_type,
84
- $actor: actor,
85
- $comment: raw.comment != null ? String(raw.comment) : undefined,
86
- $timestamp: toMillis(raw.time),
77
+ id,
78
+ clientAdapter: input.adapter,
79
+ endpointId: input.endpointKey,
80
+ type: 'request',
81
+ conversation: oneBotConversation(parts.scene_type, raw),
82
+ name: composeSideEventName('request', parts.scene_type, parts.sub_type),
83
+ actor,
84
+ comment: raw.comment != null ? String(raw.comment) : undefined,
85
+ timestamp: toMillis(raw.time),
87
86
  async $approve(remark) {
88
87
  if (!approve || !flag)
89
88
  throw new Error('Request approve is not available');
@@ -112,26 +111,29 @@ export async function receiveOneBotLikeSideEvent(emit, input) {
112
111
  ?? raw.detail_type
113
112
  ?? (postType.replace(/^(meta_event|meta|system)\.?/, '') || 'unknown'));
114
113
  const subType = raw.sub_type != null ? String(raw.sub_type) : undefined;
115
- const sceneType = postType.startsWith('system.')
116
- ? (postType.split('.')[1] ?? 'system')
117
- : metaType === 'lifecycle' || metaType === 'heartbeat'
118
- ? metaType
119
- : 'meta';
114
+ const name = postType.startsWith('system.')
115
+ ? (postType.split('.').length === 2 ? composeSideEventName(postType, subType) : postType)
116
+ : composeSideEventName('system', metaType, subType);
120
117
  const system = buildSystem(raw, {
121
- $id: `system:${toMillis(raw.time)}_${metaType}_${subType ?? ''}`,
122
- $adapter: input.adapter,
123
- $endpoint: input.endpointKey,
124
- $type: 'system',
125
- $scene_id: String(raw.self_id ?? input.endpointKey),
126
- $scene_type: sceneType,
127
- $sub_type: subType ?? metaType,
128
- $timestamp: toMillis(raw.time),
118
+ id: `system:${toMillis(raw.time)}_${metaType}_${subType ?? ''}`,
119
+ clientAdapter: input.adapter,
120
+ endpointId: input.endpointKey,
121
+ type: 'system',
122
+ name,
123
+ timestamp: toMillis(raw.time),
129
124
  });
130
125
  await emit('system.receive', system);
131
126
  return 'system';
132
127
  }
133
128
  return null;
134
129
  }
130
+ function oneBotConversation(sceneType, raw) {
131
+ const id = sceneType === 'group' ? raw.group_id
132
+ : sceneType === 'channel' ? raw.channel_id
133
+ : sceneType === 'private' || sceneType === 'friend' ? raw.user_id
134
+ : undefined;
135
+ return sideEventConversation(sceneType, id == null ? '' : String(id));
136
+ }
135
137
  function toMillis(time) {
136
138
  const seconds = Number(time);
137
139
  return Number.isFinite(seconds) && seconds > 0
@@ -1,6 +1,6 @@
1
- import { Notice, type NoticeBase } from '../notice.js';
2
- import { Request, type RequestBase } from '../request.js';
3
- import { SystemEvent, type SystemEventBase } from '../system-event.js';
1
+ import type { IncomingNotice } from '../notice.js';
2
+ import type { IncomingRequest } from '../request.js';
3
+ import type { IncomingSystemEvent } from '../system-event.js';
4
4
  import { type SideEventParts } from './types.js';
5
5
  export type SideEventPlatform = 'onebot' | 'icqq' | 'napcat' | 'kook' | (string & {});
6
6
  export interface OneBotLikeRawEvent {
@@ -18,7 +18,7 @@ export interface OneBotLikeRawEvent {
18
18
  /** 去重用:notice / request 无稳定 id 时组合键 */
19
19
  export declare function resolveSideEventDedupeKey(data: OneBotLikeRawEvent, kind: 'notice' | 'request'): string;
20
20
  /**
21
- * 将平台原始 notice_type 映射为标准 `$scene_type` + `$sub_type`。
21
+ * 将平台原始 notice_type 映射为标准 `scene_type` + `sub_type`。
22
22
  */
23
23
  export declare function mapNoticeParts(platform: SideEventPlatform, raw: string, options?: {
24
24
  sub_type?: string;
@@ -26,13 +26,14 @@ export declare function mapNoticeParts(platform: SideEventPlatform, raw: string,
26
26
  notify_handler?: (subType: string | undefined, isGroup: boolean) => SideEventParts;
27
27
  }): SideEventParts;
28
28
  /**
29
- * 将平台原始 request_type 映射为标准 `$scene_type` + `$sub_type`。
29
+ * 将平台原始 request_type 映射为标准 `scene_type` + `sub_type`。
30
30
  */
31
31
  export declare function mapRequestParts(_platform: SideEventPlatform, raw: string, subType?: string): SideEventParts;
32
32
  export declare function senderFromId(id: unknown, name?: string): {
33
33
  id: string;
34
34
  name: string;
35
35
  } | undefined;
36
- export declare function buildNotice<T extends object>(input: T, format: NoticeBase): Notice<T>;
37
- export declare function buildRequest<T extends object>(input: T, format: RequestBase): Request<T>;
38
- export declare function buildSystem<T extends object>(input: T, format: SystemEventBase): SystemEvent<T>;
36
+ /** Keep native fields under metadata; never mutate or flatten the platform event. */
37
+ export declare function buildNotice<T extends object>(input: T, format: Omit<IncomingNotice, 'metadata'>): IncomingNotice;
38
+ export declare function buildRequest<T extends object>(input: T, format: Omit<IncomingRequest, 'metadata'>): IncomingRequest;
39
+ export declare function buildSystem<T extends object>(input: T, format: Omit<IncomingSystemEvent, 'metadata'>): IncomingSystemEvent;
@@ -1,6 +1,3 @@
1
- import { Notice } from '../notice.js';
2
- import { Request } from '../request.js';
3
- import { SystemEvent } from '../system-event.js';
4
1
  import { parseSideEventName } from './base.js';
5
2
  import { KOOK_NOTICE_PARTS_MAP, ONEBOT_NOTICE_PARTS_MAP, SLACK_NOTICE_PARTS_MAP } from './types.js';
6
3
  /** 去重用:notice / request 无稳定 id 时组合键 */
@@ -34,7 +31,7 @@ function resolveEssenceNoticeParts(subType) {
34
31
  : { scene_type: 'group', sub_type: 'essence_delete' };
35
32
  }
36
33
  /**
37
- * 将平台原始 notice_type 映射为标准 `$scene_type` + `$sub_type`。
34
+ * 将平台原始 notice_type 映射为标准 `scene_type` + `sub_type`。
38
35
  */
39
36
  export function mapNoticeParts(platform, raw, options) {
40
37
  const subType = options?.sub_type;
@@ -52,6 +49,9 @@ export function mapNoticeParts(platform, raw, options) {
52
49
  if (raw === 'essence') {
53
50
  return resolveEssenceNoticeParts(subType);
54
51
  }
52
+ if (platform === 'icqq' && (raw === 'group' || raw === 'friend') && subType) {
53
+ return ONEBOT_NOTICE_PARTS_MAP[`${raw}.${subType}`] ?? { scene_type: raw, sub_type: subType };
54
+ }
55
55
  if (ONEBOT_NOTICE_PARTS_MAP[raw]) {
56
56
  return ONEBOT_NOTICE_PARTS_MAP[raw];
57
57
  }
@@ -76,7 +76,7 @@ export function mapNoticeParts(platform, raw, options) {
76
76
  return { scene_type: platform, sub_type: raw };
77
77
  }
78
78
  /**
79
- * 将平台原始 request_type 映射为标准 `$scene_type` + `$sub_type`。
79
+ * 将平台原始 request_type 映射为标准 `scene_type` + `sub_type`。
80
80
  */
81
81
  export function mapRequestParts(_platform, raw, subType) {
82
82
  if (raw === 'friend' || raw.startsWith('friend')) {
@@ -100,12 +100,13 @@ export function senderFromId(id, name) {
100
100
  const s = String(id);
101
101
  return { id: s, name: name ?? s };
102
102
  }
103
+ /** Keep native fields under metadata; never mutate or flatten the platform event. */
103
104
  export function buildNotice(input, format) {
104
- return Notice.from(input, format);
105
+ return Object.freeze({ ...format, metadata: Object.freeze({ ...input }) });
105
106
  }
106
107
  export function buildRequest(input, format) {
107
- return Request.from(input, format);
108
+ return Object.freeze({ ...format, metadata: Object.freeze({ ...input }) });
108
109
  }
109
110
  export function buildSystem(input, format) {
110
- return SystemEvent.from(input, format);
111
+ return Object.freeze({ ...format, metadata: Object.freeze({ ...input }) });
111
112
  }
@@ -1,9 +1,6 @@
1
- /**
2
- * Side Event 标准类型。
3
- * 运行时 `$type` 仅存命名空间(`notice` / `request` / `system`);
4
- * 完整名由 `${$type}.${$scene_type}.${$sub_type}` 组合。
5
- */
6
- export type SideEventKind = 'notice' | 'request' | 'system';
1
+ /** Semantic names for independent Notice, Request and SystemEvent contracts. */
2
+ export type SideEventKind = 'notice' | 'request';
3
+ export type EndpointEventKind = SideEventKind | 'system';
7
4
  export type NoticeKind = 'notice';
8
5
  export type RequestKind = 'request';
9
6
  export type SystemKind = 'system';
@@ -1,8 +1,3 @@
1
- /**
2
- * Side Event 标准类型。
3
- * 运行时 `$type` 仅存命名空间(`notice` / `request` / `system`);
4
- * 完整名由 `${$type}.${$scene_type}.${$sub_type}` 组合。
5
- */
6
1
  /** OneBot / icqq 等平台 notice_type 原始值 → 标准 scene_type + sub_type */
7
2
  export const ONEBOT_NOTICE_PARTS_MAP = {
8
3
  group_increase: { scene_type: 'group', sub_type: 'member_increase' },
@@ -1,14 +1,20 @@
1
- import type { SideEventBase } from './side-event/base.js';
2
- /**
3
- * 系统/登录侧事件(扫码、滑块、掉线等)。
4
- * `$scene_type`:`login` / `offline` / `online` 等;
5
- * `$sub_type`:`qrcode` / `slider` / `device` / `kickoff` / `network` 等。
6
- */
7
- export interface SystemEventBase extends SideEventBase {
8
- $adapter: string;
9
- $type: 'system';
1
+ import type { ComposedSystemName } from './side-event/types.js';
2
+ import { RuntimeEndpointEvent, type IncomingEndpointEvent, type EndpointEventBase, type EndpointEventContext } from './side-event/base.js';
3
+ export type { ComposedSystemName, SystemKind } from './side-event/types.js';
4
+ export type { IncomingEndpointEvent, EndpointEventBase } from './side-event/base.js';
5
+ export interface IncomingSystemEvent extends IncomingEndpointEvent {
6
+ readonly type: 'system';
7
+ readonly name: ComposedSystemName;
8
+ }
9
+ export interface SystemEventBase extends EndpointEventBase {
10
+ readonly type: 'system';
11
+ readonly name: ComposedSystemName;
10
12
  }
11
13
  export type SystemEvent<T extends object = {}> = SystemEventBase & T;
12
- export declare namespace SystemEvent {
13
- function from<T extends object>(input: T, format: SystemEventBase): SystemEvent<T>;
14
+ /** @internal Endpoint lifecycle signals do not imply a conversation. */
15
+ export declare class RuntimeSystemEvent extends RuntimeEndpointEvent implements SystemEventBase {
16
+ readonly type: 'system';
17
+ readonly name: ComposedSystemName;
18
+ constructor(input: IncomingSystemEvent, context: EndpointEventContext);
14
19
  }
20
+ export declare const SystemEvent: typeof RuntimeSystemEvent;
@@ -1,7 +1,9 @@
1
- export var SystemEvent;
2
- (function (SystemEvent) {
3
- function from(input, format) {
4
- return Object.assign(input, format);
1
+ import { RuntimeEndpointEvent } from './side-event/base.js';
2
+ /** @internal Endpoint lifecycle signals do not imply a conversation. */
3
+ export class RuntimeSystemEvent extends RuntimeEndpointEvent {
4
+ constructor(input, context) {
5
+ super(input, context);
6
+ Object.freeze(this);
5
7
  }
6
- SystemEvent.from = from;
7
- })(SystemEvent || (SystemEvent = {}));
8
+ }
9
+ export const SystemEvent = RuntimeSystemEvent;
package/lib/types.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { MessageChannel, Message, MessageComponent } from './message.js';
1
+ import type { MessageChannel, MessageComponent } from './message.js';
2
+ import type { Message } from './plugin-runtime/im/contracts.js';
2
3
  import { SystemLog } from './models/system-log.js';
3
4
  import { User } from './models/user.js';
4
5
  export type { SenderRole } from "./built/roles.js";
@@ -237,7 +238,7 @@ export interface Tool<TArgs extends Record<string, any> = Record<string, any>> {
237
238
  * @param message 通讯上下文(入站 Message 或合成 Message)
238
239
  * @returns 执行结果
239
240
  */
240
- execute: (args: TArgs, message?: Message<any>) => MaybePromise<ToolResult>;
241
+ execute: (args: TArgs, message?: Message) => MaybePromise<ToolResult>;
241
242
  /** 工具来源标识(自动填充:adapter:xxx / plugin:xxx) */
242
243
  source?: string;
243
244
  /** 工具标签(用于分类和过滤) */
package/lib/utils.d.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  */
7
7
  export { evaluate, execute, getValueWithRuntime, compiler, remove, isEmpty, Time, supportedPluginExtensions, resolveEntry, sleep, } from '@zhin.js/kernel';
8
8
  import { MessageMiddleware, SendContent } from "./types.js";
9
- import { Message } from "./message.js";
9
+ import type { Message } from "./plugin-runtime/im/contracts.js";
10
10
  import { KeyboardSegment } from "./built/interactive-segments/keyboard-segment.js";
11
11
  import { ButtonSpec, type KeyboardRowInput } from "./built/interactive-segments/button-spec.js";
12
12
  import type { ButtonData, KeyboardFallback } from "./built/interactive-segments/types.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zhin.js/core",
3
- "version": "1.1.38",
3
+ "version": "1.1.39",
4
4
  "description": "Zhin机器人核心框架",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -69,6 +69,7 @@
69
69
  "qrcode": "^1.5.4",
70
70
  "segment-matcher": "^1.0.5",
71
71
  "@zhin.js/adapter": "1.1.15",
72
+ "@zhin.js/command": "1.1.3",
72
73
  "@zhin.js/component": "1.1.2",
73
74
  "@zhin.js/database": "1.1.2",
74
75
  "@zhin.js/handler": "1.1.2",
@@ -77,11 +78,10 @@
77
78
  "@zhin.js/kernel": "1.1.1",
78
79
  "@zhin.js/logger": "1.1.1",
79
80
  "@zhin.js/middleware": "1.1.2",
80
- "@zhin.js/permission": "1.1.2",
81
- "@zhin.js/command": "1.1.2",
81
+ "@zhin.js/permission": "1.1.3",
82
82
  "@zhin.js/plugin-runtime": "1.1.11",
83
83
  "@zhin.js/schedule-feature": "1.1.2",
84
- "@zhin.js/schema": "1.1.0"
84
+ "@zhin.js/schema": "1.1.1"
85
85
  },
86
86
  "devDependencies": {
87
87
  "@types/node": "^26.1.2",