@zhin.js/core 1.3.2 → 1.3.4

package/lib/message.js

@@ -1,4 +1,5 @@
 import { alignReplySegments as alignReplySegmentsImpl, quoteIdFromContent as quoteIdFromContentImpl, syncQuoteId as syncQuoteIdImpl, } from "./message-quote.js";
+import { isActionMessage as isActionMessageImpl } from "./built/interactive-segments/action.js";
 export var Message;
 (function (Message) {
     /**
@@ -20,5 +21,19 @@ export var Message;
         alignReplySegmentsImpl(content, quoteId);
     }
     Message.alignReplySegments = alignReplySegments;
+    function actionPayload(message) {
+        for (const item of message.$content ?? []) {
+            if (typeof item === 'string')
+                continue;
+            if (item.type === 'action' && item.data?.payload) {
+                return String(item.data.payload);
+            }
+        }
+        return undefined;
+    }
+    Message.actionPayload = actionPayload;
+    function isAction(message) {
+        return isActionMessageImpl(message);
+    }
+    Message.isAction = isAction;
 })(Message || (Message = {}));
-//# sourceMappingURL=message.js.map

package/lib/models/system-log.d.ts

@@ -8,4 +8,3 @@ export interface SystemLog {
     timestamp: Date;
 }
 export declare const SystemLogDefinition: Definition<SystemLog>;
-//# sourceMappingURL=system-log.d.ts.map

package/lib/models/system-log.js

@@ -6,4 +6,3 @@ export const SystemLogDefinition = {
     source: { type: 'text', nullable: false },
     timestamp: { type: 'date', nullable: false }
 };
-//# sourceMappingURL=system-log.js.map

package/lib/models/user.d.ts

@@ -7,4 +7,3 @@ export interface User {
     permissions?: string[];
 }
 export declare const UserDefinition: Definition<User>;
-//# sourceMappingURL=user.d.ts.map

package/lib/models/user.js

@@ -5,4 +5,3 @@ export const UserDefinition = {
     third_part: { type: 'json', default: [] },
     permissions: { type: 'json', default: [] }
 };
-//# sourceMappingURL=user.js.map

package/lib/notice.d.ts

@@ -1,82 +1,38 @@
-import { Adapters } from './adapter.js';
-import type { MessageSender } from './types.js';
+import type { Adapters } from './adapter.js';
+import type { NoticeKind } from './side-event/types.js';
+import type { SideEventBase } from './side-event/base.js';
+export type { NoticeKind, ComposedNoticeName, NoticeType } from './side-event/types.js';
+export type { SideEventBase } from './side-event/base.js';
+export { composeSideEventName, formatSideEventName, matchesSideEventName, parseSideEventName, sideEventSendChannel, } from './side-event/base.js';
 /**
- * 通知类型枚举
- *
- * 常见 IM 通知事件分类：
- * - group_member_increase: 群成员增加（入群）
- * - group_member_decrease: 群成员减少（退群/被踢）
- * - group_admin_change:    群管理员变动
- * - group_ban:             群禁言
- * - group_recall:          群消息撤回
- * - friend_recall:         好友消息撤回
- * - friend_add:            新增好友
- * - group_poke:            群戳一戳
- * - friend_poke:           好友戳一戳
- * - group_transfer:        群转让
- * - endpoint.lifecycle:         Endpoint 连接/断开/错误（$subType: connect | disconnect | error）
- *
- * 适配器可自行扩展更多子类型
- */
-export type NoticeType = 'group_member_increase' | 'group_member_decrease' | 'group_admin_change' | 'group_ban' | 'group_recall' | 'friend_recall' | 'friend_add' | 'group_poke' | 'friend_poke' | 'group_transfer' | (string & {});
-/**
- * 通知频道信息
- */
-export interface NoticeChannel {
-    id: string;
-    type: 'group' | 'private' | 'channel';
-}
-/**
- * 通知基础结构
- *
- * 与 MessageBase 同构设计，所有通知共享以下字段。
- * 适配器通过 `Notice.from(raw, base)` 合并平台原始数据和标准字段。
+ * 通知基础结构 — 继承 SideEventBase。
  *
  * @example
  * ```typescript
- * // 适配器中格式化通知
  * const notice = Notice.from(rawEvent, {
  *   $id: rawEvent.id,
  *   $adapter: 'icqq',
  *   $endpoint: endpointId,
- *   $type: 'group_member_decrease',
- *   $subType: 'kick',
- *   $channel: { id: groupId, type: 'group' },
- *   $operator: { id: operatorId, name: '管理员' },
+ *   $type: 'notice',
+ *   $scene_id: groupId,
+ *   $scene_type: 'group',
+ *   $sub_type: 'member_decrease',
+ *   $actor: { id: operatorId, name: '管理员' },
  *   $target: { id: userId, name: '被踢者' },
  *   $timestamp: Date.now(),
  * });
+ * // formatSideEventName(notice) === 'notice.group.member_decrease'
  * this.adapter.emit('notice.receive', notice);
  * ```
  */
-export interface NoticeBase {
-    /** 通知唯一 ID（平台提供或自生成） */
-    $id: string;
-    /** 适配器名称 */
+export interface NoticeBase extends SideEventBase {
     $adapter: keyof Adapters;
-    /** Endpoint 名称 */
-    $endpoint: string;
-    /** 通知类型 */
-    $type: NoticeType;
-    /** 通知子类型（如 leave/kick、set/unset） */
-    $subType?: string;
-    /** 通知发生的频道/群/会话 */
-    $channel: NoticeChannel;
-    /** 操作者信息（如管理员） */
-    $operator?: MessageSender;
-    /** 被操作目标信息（如被踢的成员） */
-    $target?: MessageSender;
-    /** 通知时间戳 */
-    $timestamp: number;
+    $type: NoticeKind;
 }
 /**
  * 完整通知类型，支持平台原始数据扩展
  */
 export type Notice<T extends object = {}> = NoticeBase & T;
 export declare namespace Notice {
-    /**
-     * 工具方法：合并自定义字段与基础通知结构
-     */
     function from<T extends object>(input: T, format: NoticeBase): Notice<T>;
 }
-//# sourceMappingURL=notice.d.ts.map

package/lib/notice.js

@@ -1,11 +1,8 @@
+export { composeSideEventName, formatSideEventName, matchesSideEventName, parseSideEventName, sideEventSendChannel, } from './side-event/base.js';
 export var Notice;
 (function (Notice) {
-    /**
-     * 工具方法：合并自定义字段与基础通知结构
-     */
     function from(input, format) {
         return Object.assign(input, format);
     }
     Notice.from = from;
 })(Notice || (Notice = {}));
-//# sourceMappingURL=notice.js.map

package/lib/plugin-context.d.ts

@@ -27,4 +27,3 @@ export declare function getCurrentFile(metaUrl?: string): string;
  * @see docs/guide/plugin-development.md#getplugin-与-useplugin
  */
 export declare function getPlugin(): Plugin;
-//# sourceMappingURL=plugin-context.d.ts.map

package/lib/plugin-context.js

@@ -59,4 +59,3 @@ export function getPlugin() {
     }
     return plugin;
 }
-//# sourceMappingURL=plugin-context.js.map

package/lib/plugin.d.ts

@@ -6,11 +6,10 @@
  * - 生命周期事件类型安全（Plugin.Lifecycle）
  * - 中间件系统、适配器管理、useContext 等
  */
-import type { PluginManifest } from "./types.js";
-import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions, MessageSendPayload } from "./types.js";
+import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions, MessageSendPayload, type PluginManifest } from './types.js';
+import type { InteractiveHandler } from "./built/interactive-segments/types.js";
 import { Adapter, Adapters } from "./adapter.js";
-import { PluginBase, PluginBaseLifecycle } from "@zhin.js/kernel";
-import type { PluginLike } from "@zhin.js/kernel";
+import { PluginBase, PluginBaseLifecycle, type PluginLike } from '@zhin.js/kernel';
 export { getPlugin } from "./plugin-context.js";
 export { storage, getCurrentFile } from "./plugin-context.js";
 export { setHostRootPlugin, getHostRootPlugin } from "./host-plugin-registry.js";
@@ -64,6 +63,10 @@ export declare class Plugin extends PluginBase implements PluginLike {
      * 中间件用于处理消息流转
      */
     addMiddleware<T extends RegisteredAdapter>(middleware: MessageMiddleware<T>, name?: string): () => void;
+    /**
+     * 注册交互式 action 回调处理器（自动安装根中间件，优先于 Dispatcher）
+     */
+    registerInteractiveHandler(prefix: string, handler: InteractiveHandler): () => void;
     /**
      * 插件名称
      */
@@ -159,7 +162,7 @@ export declare namespace Plugin {
     interface Features {
         commands: string[];
         components: string[];
-        crons: string[];
+        schedules: string[];
         middlewares: string[];
     }
     /**
@@ -193,6 +196,8 @@ export declare namespace Plugin {
         "ai.response": [Plugin.AIEventPayload];
         "ai.typing.start": [Plugin.AIEventPayload];
         "ai.typing.stop": [Plugin.AIEventPayload];
+        "ai.activity.queued.start": [Plugin.AIEventPayload];
+        "ai.activity.queued.clear": [Plugin.AIEventPayload];
         "ai.subagent.spawn": [Plugin.AIEventPayload];
         "ai.subagent.start": [Plugin.AIEventPayload];
         "ai.subagent.finish": [Plugin.AIEventPayload];
@@ -204,6 +209,9 @@ export declare namespace Plugin {
         "ai.session.new": [Plugin.AIEventPayload];
         "ai.session.compact": [Plugin.AIEventPayload];
         "ai.hook": [Plugin.AIEventPayload];
+        "schedule.start": [Plugin.AIEventPayload];
+        "schedule.finish": [Plugin.AIEventPayload];
+        "schedule.error": [Plugin.AIEventPayload];
     }
     interface AIEventPayload {
         sessionId: string;
@@ -257,4 +265,3 @@ export declare namespace Plugin {
     interface Extensions {
     }
 }
-//# sourceMappingURL=plugin.d.ts.map

package/lib/plugin.js

@@ -11,9 +11,9 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import { formatCompact } from "@zhin.js/logger";
 import { compose, remove, resolveEntry } from "./utils.js";
+import { ensureInteractiveMiddleware, registerInteractiveHandler as registerInteractiveHandlerCore, } from "./built/interactive-segments/handlers.js";
 import { Adapter } from "./adapter.js";
-import { Feature } from "@zhin.js/kernel";
-import { PluginBase, resolvePluginResolveDir as _resolvePluginResolveDir, pluginCreateRequire as _pluginCreateRequire, getFileHash, watchFile, registerExtension, unregisterExtensions, installExtensionProxy, } from "@zhin.js/kernel";
+import { Feature, PluginBase, resolvePluginResolveDir as _resolvePluginResolveDir, pluginCreateRequire as _pluginCreateRequire, getFileHash, watchFile, registerExtension, unregisterExtensions, installExtensionProxy } from '@zhin.js/kernel';
 import { storage, getCurrentFile } from "./plugin-context.js";
 // Re-export getPlugin from plugin-context for backward compatibility
 export { getPlugin } from "./plugin-context.js";
@@ -36,7 +36,9 @@ function pluginCreateRequire() {
  * 同一上下文中同一文件多次调用返回同一实例
  */
 export function usePlugin() {
-    const callerFile = getCurrentFile();
+    // 必须传入 plugin.ts 的 import.meta.url：getCurrentFile 默认锚定在 plugin-context.ts，
+    // 否则会多跳一层 usePlugin 帧，把调用方误判为 plugin.ts（plugin.name === "plugin"）。
+    const callerFile = getCurrentFile(import.meta.url);
     // 如果当前 store 已是同一文件创建的插件，直接返回
     const current = storage.getStore();
     if (current && current.filePath.replace(/\?t=\d+$/, '') === callerFile.replace(/\?t=\d+$/, '')) {
@@ -103,21 +105,35 @@ export class Plugin extends PluginBase {
         this.onDispose(dispose);
         return dispose;
     }
+    /**
+     * 注册交互式 action 回调处理器（自动安装根中间件，优先于 Dispatcher）
+     */
+    registerInteractiveHandler(prefix, handler) {
+        ensureInteractiveMiddleware((mw) => this.root.addMiddleware(mw));
+        const dispose = registerInteractiveHandlerCore(prefix, handler);
+        this.onDispose(dispose);
+        return dispose;
+    }
     /**
      * 插件名称
      */
     get name() {
         if (this.#cachedName)
             return this.#cachedName;
-        this.#cachedName = path
+        let name = path
             .relative(process.cwd(), this.filePath)
             .replace(/\?t=\d+$/, "")
             .replace(/\\/g, "/")
             .replace(/\/index\.(js|ts)x?$/, "")
-            .replace(/\/(lib|src|dist)$/, "")
-            .replace(/.*\/node_modules\//, "")
-            .replace(/.*\//, "")
-            .replace(/\.(js|ts)x?$/, "");
+            .replace(/\/(lib|src|dist)$/, "");
+        const nodeModulesIndex = name.indexOf("node_modules/");
+        if (nodeModulesIndex !== -1)
+            name = name.slice(nodeModulesIndex + "node_modules/".length);
+        const slash = name.lastIndexOf("/");
+        if (slash !== -1)
+            name = name.slice(slash + 1);
+        name = name.replace(/\.(js|ts)x?$/, "");
+        this.#cachedName = name;
         return this.#cachedName;
     }
     /**
@@ -212,7 +228,8 @@ export class Plugin extends PluginBase {
         contextReadyCallback();
     }
     inject(name) {
-        const context = this.root.contexts.get(name);
+        const resolved = name === 'cron' ? 'schedule' : name;
+        const context = this.root.contexts.get(resolved);
         return context?.value;
     }
     injectAdapter(name) {
@@ -291,11 +308,11 @@ export class Plugin extends PluginBase {
     get features() {
         const commandService = this.inject('command');
         const componentService = this.inject('component');
-        const cronService = this.inject('cron');
+        const scheduleService = this.inject('schedule');
         return {
             commands: commandService ? commandService.items.map(c => c.pattern) : [],
             components: componentService ? componentService.getAllNames() : [],
-            crons: cronService ? cronService.items.map(c => c.cronExpression) : [],
+            schedules: scheduleService ? scheduleService.items.map(s => s.id) : [],
             middlewares: this.#middlewares.map((m, i) => m.name || `middleware_${i}`),
         };
     }
@@ -310,8 +327,8 @@ export class Plugin extends PluginBase {
             result.push({ name: 'command', count: f.commands.length });
         if (f.components.length > 0)
             result.push({ name: 'component', count: f.components.length });
-        if (f.crons.length > 0)
-            result.push({ name: 'cron', count: f.crons.length });
+        if (f.schedules.length > 0)
+            result.push({ name: 'schedule', count: f.schedules.length });
         // #middlewares includes the default command middleware, only count user-added ones
         const userMiddlewareCount = this.#middlewares.length - 1; // subtract default #messageMiddleware
         if (userMiddlewareCount > 0)
@@ -413,7 +430,7 @@ export class Plugin extends PluginBase {
             installExtensionProxy(Plugin.prototype);
             for (const [name, fn] of Object.entries(context.extensions)) {
                 if (typeof fn === 'function') {
-                    registerExtension(name, fn); // eslint-disable-line @typescript-eslint/no-explicit-any
+                    registerExtension(name, fn);
                 }
             }
         }
@@ -573,4 +590,3 @@ export class Plugin extends PluginBase {
 export function defineContext(options) {
     return options;
 }
-//# sourceMappingURL=plugin.js.map

package/lib/prompt.d.ts

@@ -115,4 +115,3 @@ export declare namespace Prompt {
     };
     export {};
 }
-//# sourceMappingURL=prompt.d.ts.map

package/lib/prompt.js

@@ -245,4 +245,3 @@ export class Prompt {
         }
     }
 }
-//# sourceMappingURL=prompt.js.map

package/lib/request.d.ts

@@ -1,85 +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>;
 }
-//# sourceMappingURL=request.d.ts.map

package/lib/request.js

@@ -1,11 +1,7 @@
 export var Request;
 (function (Request) {
-    /**
-     * 工具方法：合并自定义字段与基础请求结构
-     */
     function from(input, format) {
         return Object.assign(input, format);
     }
     Request.from = from;
 })(Request || (Request = {}));
-//# sourceMappingURL=request.js.map

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>;