@zhin.js/core 1.3.3 → 1.3.5

package/lib/request.d.ts

@@ -1,84 +1,41 @@
-import { Adapters } from './adapter.js';
-import type { MessageSender, MaybePromise } from './types.js';
+import type { MaybePromise } from './types.js';
+import type { Adapters } from './adapter.js';
+import type { RequestKind } from './side-event/types.js';
+import type { SideEventBase } from './side-event/base.js';
+export type { RequestKind, ComposedRequestName, RequestType } from './side-event/types.js';
 /**
- * 请求类型枚举
- *
- * 常见 IM 请求事件分类：
- * - friend_add:  好友添加请求
- * - group_add:   主动申请入群
- * - group_invite: 邀请入群请求
- *
- * 适配器可自行扩展更多子类型
- */
-export type RequestType = 'friend_add' | 'group_add' | 'group_invite' | (string & {});
-/**
- * 请求频道信息
- */
-export interface RequestChannel {
-    id: string;
-    type: 'group' | 'private' | 'channel';
-}
-/**
- * 请求基础结构
- *
- * 与 MessageBase / NoticeBase 同构设计。
- * 核心区别：Request 提供 `$approve()` 和 `$reject()` 方法，用于快速处理请求。
+ * 请求基础结构 — 继承 SideEventBase，附加审批方法。
  *
  * @example
  * ```typescript
- * // 适配器中格式化请求
  * const request = Request.from(rawEvent, {
  *   $id: rawEvent.flag,
  *   $adapter: 'icqq',
  *   $endpoint: endpointId,
- *   $type: 'group_invite',
- *   $channel: { id: groupId, type: 'group' },
- *   $sender: { id: userId, name: '邀请者' },
+ *   $type: 'request',
+ *   $scene_id: groupId,
+ *   $scene_type: 'group',
+ *   $sub_type: 'invite',
+ *   $actor: { id: userId, name: '邀请者' },
  *   $comment: '请求加群消息',
  *   $timestamp: Date.now(),
  *   $approve: async (remark?) => { await api.approve(flag, remark); },
  *   $reject: async (reason?) => { await api.reject(flag, reason); },
  * });
+ * // formatSideEventName(request) === 'request.group.invite'
  * this.adapter.emit('request.receive', request);
  * ```
  */
-export interface RequestBase {
-    /** 请求唯一 ID / flag（平台提供的请求标识，用于后续处理） */
-    $id: string;
-    /** 适配器名称 */
+export interface RequestBase extends SideEventBase {
     $adapter: keyof Adapters;
-    /** Endpoint 名称 */
-    $endpoint: string;
-    /** 请求类型 */
-    $type: RequestType;
-    /** 请求子类型 */
-    $subType?: string;
-    /** 请求发生的频道/群/会话 */
-    $channel: RequestChannel;
-    /** 请求发送者 */
-    $sender: MessageSender;
-    /** 请求附言/验证消息 */
+    $type: RequestKind;
+    /** 主参与者（必填） */
+    $actor: NonNullable<SideEventBase['$actor']>;
     $comment?: string;
-    /** 请求时间戳 */
-    $timestamp: number;
-    /**
-     * 同意请求
-     * @param remark 备注信息（如好友备注）
-     */
     $approve(remark?: string): MaybePromise<void>;
-    /**
-     * 拒绝请求
-     * @param reason 拒绝原因
-     */
     $reject(reason?: string): MaybePromise<void>;
 }
-/**
- * 完整请求类型，支持平台原始数据扩展
- */
 export type Request<T extends object = {}> = RequestBase & T;
 export declare namespace Request {
-    /**
-     * 工具方法：合并自定义字段与基础请求结构
-     */
     function from<T extends object>(input: T, format: RequestBase): Request<T>;
 }

package/lib/request.js

@@ -1,8 +1,5 @@
 export var Request;
 (function (Request) {
-    /**
-     * 工具方法：合并自定义字段与基础请求结构
-     */
     function from(input, format) {
         return Object.assign(input, format);
     }

package/lib/side-event/base.d.ts

@@ -0,0 +1,45 @@
+import type { Adapters } from '../adapter.js';
+import type { MessageSender } from '../types.js';
+/**
+ * Side Event 共享基础结构（Notice 与 Request 共用）。
+ * 字段统一为 `$foo_bar` 命名。
+ *
+ * 完整事件名：`${$type}.${$scene_type}.${$sub_type}`（见 `formatSideEventName`）。
+ */
+export interface SideEventBase {
+    /** 平台侧去重键 / flag（非 DB 行 id） */
+    $id: string;
+    $adapter: keyof Adapters;
+    $endpoint: string;
+    /** 命名空间：`notice` 或 `request` */
+    $type: string;
+    /** 平台场景 ID（群号、用户号、频道 ID 等） */
+    $scene_id: string;
+    /** 场景域（如 group、friend、channel、endpoint） */
+    $scene_type?: string;
+    /** 动作子类型（如 member_increase、add、poke） */
+    $sub_type?: string;
+    /** 主参与者（原 Notice.$operator / Request.$sender） */
+    $actor?: MessageSender;
+    /** 被操作对象 */
+    $target?: MessageSender;
+    /** 毫秒时间戳 */
+    $timestamp: number;
+}
+/** 组合 Side Event 完整类型名 */
+export declare function composeSideEventName(type: string, sceneType: string | undefined, subType: string | undefined): string;
+/** 从 Side Event 字段生成完整类型名 */
+export declare function formatSideEventName(event: Pick<SideEventBase, '$type' | '$scene_type' | '$sub_type'>): string;
+/** 判断 Side Event 是否匹配完整类型名（如 `notice.group.member_increase`） */
+export declare function matchesSideEventName(event: Pick<SideEventBase, '$type' | '$scene_type' | '$sub_type'>, fullName: string): boolean;
+/** 解析完整类型名为三段 */
+export declare function parseSideEventName(fullName: string): {
+    type: string;
+    scene_type?: string;
+    sub_type?: string;
+};
+/** 将 Side Event 场景映射为 IM 发送通道（group-suite 等消费者用） */
+export declare function sideEventSendChannel(event: Pick<SideEventBase, '$scene_type' | '$scene_id'>): {
+    id: string;
+    type: 'group' | 'private' | 'channel';
+};

package/lib/side-event/base.js

@@ -0,0 +1,30 @@
+/** 组合 Side Event 完整类型名 */
+export function composeSideEventName(type, sceneType, subType) {
+    return [type, sceneType, subType].filter((p) => !!p).join('.');
+}
+/** 从 Side Event 字段生成完整类型名 */
+export function formatSideEventName(event) {
+    return composeSideEventName(event.$type, event.$scene_type, event.$sub_type);
+}
+/** 判断 Side Event 是否匹配完整类型名（如 `notice.group.member_increase`） */
+export function matchesSideEventName(event, fullName) {
+    return formatSideEventName(event) === fullName;
+}
+/** 解析完整类型名为三段 */
+export function parseSideEventName(fullName) {
+    const parts = fullName.split('.');
+    return {
+        type: parts[0] ?? '',
+        scene_type: parts[1],
+        sub_type: parts.slice(2).join('.') || undefined,
+    };
+}
+/** 将 Side Event 场景映射为 IM 发送通道（group-suite 等消费者用） */
+export function sideEventSendChannel(event) {
+    const domain = event.$scene_type ?? 'private';
+    if (domain === 'group')
+        return { id: event.$scene_id, type: 'group' };
+    if (domain === 'channel')
+        return { id: event.$scene_id, type: 'channel' };
+    return { id: event.$scene_id, type: 'private' };
+}

package/lib/side-event/index.d.ts

@@ -0,0 +1,3 @@
+export * from './base.js';
+export * from './types.js';
+export * from './normalize.js';

package/lib/side-event/index.js

@@ -0,0 +1,3 @@
+export * from './base.js';
+export * from './types.js';
+export * from './normalize.js';

package/lib/side-event/normalize.d.ts

@@ -0,0 +1,40 @@
+import { Notice, type NoticeBase } from '../notice.js';
+import { Request, type RequestBase } from '../request.js';
+import { type ComposedNoticeName, type ComposedRequestName, type SideEventParts } from './types.js';
+export type SideEventPlatform = 'onebot' | 'icqq' | 'napcat' | 'kook' | (string & {});
+export interface OneBotLikeRawEvent {
+    notice_type?: string;
+    request_type?: string;
+    sub_type?: string;
+    group_id?: number | string;
+    user_id?: number | string;
+    operator_id?: number | string;
+    flag?: string;
+    time?: number;
+    self_id?: number | string;
+    [key: string]: unknown;
+}
+/** 去重用：notice / request 无稳定 id 时组合键 */
+export declare function resolveSideEventDedupeKey(data: OneBotLikeRawEvent, kind: 'notice' | 'request'): string;
+/**
+ * 将平台原始 notice_type 映射为标准 `$scene_type` + `$sub_type`。
+ */
+export declare function mapNoticeParts(platform: SideEventPlatform, raw: string, options?: {
+    sub_type?: string;
+    is_group?: boolean;
+    notify_handler?: (subType: string | undefined, isGroup: boolean) => SideEventParts;
+}): SideEventParts;
+/**
+ * 将平台原始 request_type 映射为标准 `$scene_type` + `$sub_type`。
+ */
+export declare function mapRequestParts(_platform: SideEventPlatform, raw: string, subType?: string): SideEventParts;
+/** 组合完整 Notice 类型名（兼容旧 API） */
+export declare function mapNoticeType(platform: SideEventPlatform, raw: string, options?: Parameters<typeof mapNoticeParts>[2]): ComposedNoticeName;
+/** 组合完整 Request 类型名（兼容旧 API） */
+export declare function mapRequestType(platform: SideEventPlatform, raw: string, subType?: string): ComposedRequestName;
+export declare function senderFromId(id: unknown, name?: string): {
+    id: string;
+    name: string;
+} | undefined;
+export declare function buildNotice<T extends object>(input: T, format: NoticeBase): Notice<T>;
+export declare function buildRequest<T extends object>(input: T, format: RequestBase): Request<T>;

package/lib/side-event/normalize.js

@@ -0,0 +1,117 @@
+import { Notice } from '../notice.js';
+import { Request } from '../request.js';
+import { composeSideEventName, parseSideEventName, } from './base.js';
+import { KOOK_NOTICE_PARTS_MAP, ONEBOT_NOTICE_PARTS_MAP, SLACK_NOTICE_PARTS_MAP } from './types.js';
+/** 去重用：notice / request 无稳定 id 时组合键 */
+export function resolveSideEventDedupeKey(data, kind) {
+    if (data.flag != null && String(data.flag) !== '') {
+        return `${kind}:${data.flag}`;
+    }
+    const time = data.time ?? 0;
+    const type = data.notice_type ?? data.request_type ?? kind;
+    const scope = data.group_id ?? data.user_id ?? '';
+    const sub = data.sub_type ?? '';
+    return `${kind}:${time}_${type}_${scope}_${sub}`;
+}
+function resolveNotifyNoticeParts(subType, isGroup) {
+    if (subType === 'poke') {
+        return isGroup
+            ? { scene_type: 'group', sub_type: 'poke' }
+            : { scene_type: 'friend', sub_type: 'poke' };
+    }
+    if (subType === 'input_status')
+        return { scene_type: 'notify', sub_type: 'input_status' };
+    if (subType === 'title')
+        return { scene_type: 'notify', sub_type: 'title_change' };
+    if (subType === 'profile_like')
+        return { scene_type: 'notify', sub_type: 'profile_like' };
+    return { scene_type: 'notify', sub_type: subType ?? 'unknown' };
+}
+function resolveEssenceNoticeParts(subType) {
+    return subType === 'add'
+        ? { scene_type: 'group', sub_type: 'essence_add' }
+        : { scene_type: 'group', sub_type: 'essence_delete' };
+}
+/**
+ * 将平台原始 notice_type 映射为标准 `$scene_type` + `$sub_type`。
+ */
+export function mapNoticeParts(platform, raw, options) {
+    const subType = options?.sub_type;
+    const isGroup = options?.is_group ?? false;
+    if (platform === 'kook') {
+        return KOOK_NOTICE_PARTS_MAP[raw] ?? { scene_type: 'kook', sub_type: raw };
+    }
+    if (platform === 'slack') {
+        return SLACK_NOTICE_PARTS_MAP[raw] ?? { scene_type: 'slack', sub_type: raw };
+    }
+    if (raw === 'notify') {
+        const handler = options?.notify_handler ?? resolveNotifyNoticeParts;
+        return handler(subType, isGroup);
+    }
+    if (raw === 'essence') {
+        return resolveEssenceNoticeParts(subType);
+    }
+    if (ONEBOT_NOTICE_PARTS_MAP[raw]) {
+        return ONEBOT_NOTICE_PARTS_MAP[raw];
+    }
+    if (raw.startsWith('notice.')) {
+        const parsed = parseSideEventName(raw);
+        if (parsed.scene_type && parsed.sub_type) {
+            return { scene_type: parsed.scene_type, sub_type: parsed.sub_type };
+        }
+        const suffix = raw.slice('notice.'.length).replace(/\./g, '_');
+        if (ONEBOT_NOTICE_PARTS_MAP[suffix])
+            return ONEBOT_NOTICE_PARTS_MAP[suffix];
+        return { scene_type: parsed.scene_type ?? 'unknown', sub_type: parsed.sub_type ?? suffix };
+    }
+    if (platform === 'icqq' || platform === 'onebot' || platform === 'napcat') {
+        const dotted = raw.replace(/_/g, '.');
+        const parsed = parseSideEventName(`notice.${dotted}`);
+        return {
+            scene_type: parsed.scene_type ?? dotted.split('.')[0] ?? 'unknown',
+            sub_type: parsed.sub_type ?? (dotted.split('.').slice(1).join('.') || raw),
+        };
+    }
+    return { scene_type: platform, sub_type: raw };
+}
+/**
+ * 将平台原始 request_type 映射为标准 `$scene_type` + `$sub_type`。
+ */
+export function mapRequestParts(_platform, raw, subType) {
+    if (raw === 'friend' || raw.startsWith('friend')) {
+        return { scene_type: 'friend', sub_type: 'add' };
+    }
+    if (raw === 'group' || raw.startsWith('group')) {
+        return { scene_type: 'group', sub_type: subType === 'invite' ? 'invite' : 'add' };
+    }
+    if (raw.startsWith('request.')) {
+        const parsed = parseSideEventName(raw);
+        return {
+            scene_type: parsed.scene_type ?? 'unknown',
+            sub_type: parsed.sub_type ?? 'unknown',
+        };
+    }
+    return { scene_type: raw, sub_type: subType ?? 'unknown' };
+}
+/** 组合完整 Notice 类型名（兼容旧 API） */
+export function mapNoticeType(platform, raw, options) {
+    const parts = mapNoticeParts(platform, raw, options);
+    return composeSideEventName('notice', parts.scene_type, parts.sub_type);
+}
+/** 组合完整 Request 类型名（兼容旧 API） */
+export function mapRequestType(platform, raw, subType) {
+    const parts = mapRequestParts(platform, raw, subType);
+    return composeSideEventName('request', parts.scene_type, parts.sub_type);
+}
+export function senderFromId(id, name) {
+    if (id == null || id === '')
+        return undefined;
+    const s = String(id);
+    return { id: s, name: name ?? s };
+}
+export function buildNotice(input, format) {
+    return Notice.from(input, format);
+}
+export function buildRequest(input, format) {
+    return Request.from(input, format);
+}

package/lib/side-event/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Side Event 标准类型。
+ * 运行时 `$type` 仅存命名空间（`notice` / `request`）；
+ * 完整名由 `${$type}.${$scene_type}.${$sub_type}` 组合。
+ */
+export type SideEventKind = 'notice' | 'request';
+export type NoticeKind = 'notice';
+export type RequestKind = 'request';
+/** 完整组合名（测试 / 文档 / 消费者匹配用） */
+export type ComposedNoticeName = 'notice.group.member_increase' | 'notice.group.member_decrease' | 'notice.group.admin_change' | 'notice.group.ban' | 'notice.group.recall' | 'notice.group.poke' | 'notice.group.transfer' | 'notice.group.upload' | 'notice.group.emoji_reaction' | 'notice.group.card_change' | 'notice.group.essence_add' | 'notice.group.essence_delete' | 'notice.friend.recall' | 'notice.friend.increase' | 'notice.friend.poke' | 'notice.endpoint.lifecycle' | (string & {});
+export type ComposedRequestName = 'request.friend.add' | 'request.group.add' | 'request.group.invite' | (string & {});
+/** @deprecated 使用 ComposedNoticeName + formatSideEventName */
+export type NoticeType = ComposedNoticeName;
+/** @deprecated 使用 ComposedRequestName + formatSideEventName */
+export type RequestType = ComposedRequestName;
+export interface SideEventParts {
+    scene_type: string;
+    sub_type: string;
+}
+/** OneBot / icqq 等平台 notice_type 原始值 → 标准 scene_type + sub_type */
+export declare const ONEBOT_NOTICE_PARTS_MAP: Record<string, SideEventParts>;
+/** KOOK extra.type 原始值 → 标准 scene_type + sub_type */
+export declare const KOOK_NOTICE_PARTS_MAP: Record<string, SideEventParts>;
+/** Slack event type 原始值 → 标准 scene_type + sub_type */
+export declare const SLACK_NOTICE_PARTS_MAP: Record<string, SideEventParts>;

package/lib/side-event/types.js

@@ -0,0 +1,55 @@
+/**
+ * Side Event 标准类型。
+ * 运行时 `$type` 仅存命名空间（`notice` / `request`）；
+ * 完整名由 `${$type}.${$scene_type}.${$sub_type}` 组合。
+ */
+/** OneBot / icqq 等平台 notice_type 原始值 → 标准 scene_type + sub_type */
+export const ONEBOT_NOTICE_PARTS_MAP = {
+    group_increase: { scene_type: 'group', sub_type: 'member_increase' },
+    group_decrease: { scene_type: 'group', sub_type: 'member_decrease' },
+    group_admin: { scene_type: 'group', sub_type: 'admin_change' },
+    group_ban: { scene_type: 'group', sub_type: 'ban' },
+    group_recall: { scene_type: 'group', sub_type: 'recall' },
+    friend_recall: { scene_type: 'friend', sub_type: 'recall' },
+    friend_add: { scene_type: 'friend', sub_type: 'increase' },
+    group_upload: { scene_type: 'group', sub_type: 'upload' },
+    group_transfer: { scene_type: 'group', sub_type: 'transfer' },
+    group_card: { scene_type: 'group', sub_type: 'card_change' },
+    group_msg_emoji_like: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    'group.increase': { scene_type: 'group', sub_type: 'member_increase' },
+    'group.decrease': { scene_type: 'group', sub_type: 'member_decrease' },
+    'group.admin': { scene_type: 'group', sub_type: 'admin_change' },
+    'group.ban': { scene_type: 'group', sub_type: 'ban' },
+    'group.recall': { scene_type: 'group', sub_type: 'recall' },
+    'friend.increase': { scene_type: 'friend', sub_type: 'increase' },
+    'friend.decrease': { scene_type: 'friend', sub_type: 'recall' },
+    'friend.recall': { scene_type: 'friend', sub_type: 'recall' },
+};
+/** KOOK extra.type 原始值 → 标准 scene_type + sub_type */
+export const KOOK_NOTICE_PARTS_MAP = {
+    joined_guild: { scene_type: 'group', sub_type: 'member_increase' },
+    exited_guild: { scene_type: 'group', sub_type: 'member_decrease' },
+    deleted_message: { scene_type: 'group', sub_type: 'recall' },
+    deleted_private_message: { scene_type: 'friend', sub_type: 'recall' },
+    added_reaction: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    deleted_reaction: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    private_added_reaction: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    private_deleted_reaction: { scene_type: 'group', sub_type: 'emoji_reaction' },
+};
+/** Slack event type 原始值 → 标准 scene_type + sub_type */
+export const SLACK_NOTICE_PARTS_MAP = {
+    member_joined_channel: { scene_type: 'group', sub_type: 'member_increase' },
+    member_left_channel: { scene_type: 'group', sub_type: 'member_decrease' },
+    reaction_added: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    reaction_removed: { scene_type: 'group', sub_type: 'emoji_reaction' },
+    message_deleted: { scene_type: 'group', sub_type: 'recall' },
+    channel_archive: { scene_type: 'slack', sub_type: 'channel_archive' },
+    channel_unarchive: { scene_type: 'slack', sub_type: 'channel_unarchive' },
+    channel_rename: { scene_type: 'slack', sub_type: 'channel_rename' },
+    channel_created: { scene_type: 'slack', sub_type: 'channel_created' },
+    channel_deleted: { scene_type: 'slack', sub_type: 'channel_deleted' },
+    pin_added: { scene_type: 'slack', sub_type: 'pin_added' },
+    pin_removed: { scene_type: 'slack', sub_type: 'pin_removed' },
+    app_home_opened: { scene_type: 'slack', sub_type: 'app_home_opened' },
+    team_join: { scene_type: 'friend', sub_type: 'increase' },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,6 +21,11 @@
       "development": "./src/built/queue-im-field-contract.ts",
       "import": "./lib/built/queue-im-field-contract.js"
     },
+    "./runtime": {
+      "types": "./lib/plugin-runtime/im/index.d.ts",
+      "development": "./src/plugin-runtime/im/index.ts",
+      "import": "./lib/plugin-runtime/im/index.js"
+    },
     "./jsx": {
       "types": "./lib/jsx.d.ts",
       "development": "./src/jsx.ts",
@@ -45,9 +50,14 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.0",
     "yaml": "^2.9.0",
-    "@zhin.js/database": "1.0.75",
-    "@zhin.js/kernel": "1.0.2",
-    "@zhin.js/logger": "1.0.73",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/command": "1.0.1",
+    "@zhin.js/component": "1.0.1",
+    "@zhin.js/kernel": "1.0.4",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/middleware": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.0.1",
+    "@zhin.js/database": "1.0.77",
     "@zhin.js/schema": "1.0.71"
   },
   "peerDependencies": {
@@ -62,7 +72,7 @@
     "@types/node": "^26.1.0",
     "@types/qrcode": "^1.5.5",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.4.3"
+    "@zhin.js/ai": "1.4.5"
   },
   "repository": {
     "type": "git",