@zhin.js/core 1.3.3 → 1.3.4

package/lib/adapter.js

@@ -194,7 +194,7 @@ export class Adapter extends EventEmitter {
         if (!endpoint)
             throw new Error(`Endpoint ${options.endpoint} not found`);
         assertOutbound(endpoint);
-        this.logger.info(formatCompact({
+        this.logger.debug(formatCompact({
             send: `${options.type}(${options.id})`,
             endpoint: options.endpoint,
             preview: truncatePreview(segment.raw(options.content)),
@@ -231,7 +231,7 @@ export class Adapter extends EventEmitter {
                 content: options.content,
             });
             await editable.$editMessage({ ...options, content: rendered.content });
-            this.logger.info(formatCompact({
+            this.logger.debug(formatCompact({
                 edit: `${options.type}(${options.id})`,
                 endpoint: options.endpoint,
                 messageId: options.messageId,

package/lib/built/ai-outbound/parse.js

@@ -21,19 +21,17 @@ export function parseOutboundSegment(raw) {
 /** 去掉嵌入 JSON 候选末尾的 markdown 围栏（模型常见 ```json … ``` 误输出）。 */
 export function trimTrailingMarkdownFence(raw) {
     let s = raw.trim();
-    const trailingFence = s.match(/^([\s\S]*?)\s*```\s*$/);
-    if (trailingFence)
-        s = trailingFence[1].trim();
+    if (s.endsWith('```'))
+        s = s.slice(0, -3).trimEnd();
     return s;
 }
 export function unwrapAiOutboundJsonCandidate(raw) {
     const trimmed = raw.trim();
-    const fenced = trimmed.match(/^```(?:json)?\s*([\s\S]*?)```\s*$/i);
-    if (fenced)
-        return fenced[1].trim();
-    const embeddedFence = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
-    if (embeddedFence && trimmed.indexOf('{') >= 0) {
-        return trimTrailingMarkdownFence(embeddedFence[1].trim());
+    const fenced = readMarkdownFence(trimmed);
+    if (fenced && fenced.full)
+        return fenced.body.trim();
+    if (fenced && trimmed.indexOf('{') >= 0) {
+        return trimTrailingMarkdownFence(fenced.body.trim());
     }
     return trimTrailingMarkdownFence(trimmed);
 }
@@ -42,12 +40,12 @@ export function extractEmbeddedAiOutboundJson(plain) {
     const trimmed = plain.trim();
     if (!trimmed.includes('{'))
         return null;
-    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const fenced = readMarkdownFence(trimmed);
     if (fenced) {
-        const jsonRaw = trimTrailingMarkdownFence(fenced[1].trim());
+        const jsonRaw = trimTrailingMarkdownFence(fenced.body.trim());
         const payload = parseAiOutboundJson(jsonRaw);
         if (payload?.mentions?.length && payload.text?.trim()) {
-            const prose = trimmed.slice(0, fenced.index).trim();
+            const prose = trimmed.slice(0, fenced.start).trim();
             return { prose, jsonRaw };
         }
     }
@@ -62,6 +60,22 @@ export function extractEmbeddedAiOutboundJson(plain) {
     }
     return null;
 }
+function readMarkdownFence(text) {
+    const start = text.indexOf('```');
+    if (start < 0)
+        return null;
+    let bodyStart = start + 3;
+    const langEnd = text.indexOf('\n', bodyStart);
+    if (langEnd >= 0) {
+        const lang = text.slice(bodyStart, langEnd).trim().toLowerCase();
+        if (lang === '' || lang === 'json')
+            bodyStart = langEnd + 1;
+    }
+    const end = text.indexOf('```', bodyStart);
+    if (end < 0)
+        return null;
+    return { start, body: text.slice(bodyStart, end), full: start === 0 && text.slice(end + 3).trim() === '' };
+}
 export function parseAiOutboundJson(raw) {
     const candidate = unwrapAiOutboundJsonCandidate(raw);
     if (!candidate.startsWith('{'))

package/lib/built/component.d.ts

@@ -2,9 +2,8 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 import { Component } from "../component.js";
-import type { PluginLike } from '@zhin.js/kernel';
 /**
  * ComponentContext 扩展方法类型
  */

package/lib/built/component.js

@@ -2,7 +2,7 @@
  * ComponentFeature
  * 管理所有插件注册的组件，继承自 Feature 抽象类
  */
-import { Feature } from "@zhin.js/kernel";
+import { Feature } from '@zhin.js/kernel';
 import { renderComponents } from "../component.js";
 /**
  * 组件服务 Feature

package/lib/built/database.d.ts

@@ -4,8 +4,7 @@
  */
 import { Definition, Database } from "@zhin.js/database";
 import { DatabaseConfig, Models } from "../types.js";
-import { Feature, FeatureJSON } from "@zhin.js/kernel";
-import type { PluginLike } from '@zhin.js/kernel';
+import { Feature, FeatureJSON, type PluginLike } from '@zhin.js/kernel';
 /**
  * 模型定义记录
  */

package/lib/built/database.js

@@ -4,7 +4,7 @@
  */
 import { Registry } from "@zhin.js/database";
 import { formatCompact } from '@zhin.js/logger';
-import { Feature } from "@zhin.js/kernel";
+import { Feature } from '@zhin.js/kernel';
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
 const databaseAfterStartHooks = [];

package/lib/built/dispatcher.d.ts

@@ -27,8 +27,8 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { Message } from '../message.js';
+import { type Context } from '../plugin.js';
 import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware, OutboundReplyStore } from '../types.js';
-import type { Context } from '../plugin.js';
 export declare function getOutboundReplyStore(): OutboundReplyStore | undefined;
 /**
  * 路由判定结果（互斥模式 legacy）

package/lib/built/endpoint-lifecycle-service.js

@@ -1,3 +1,4 @@
+import { formatDisplayPath } from '@zhin.js/logger';
 import { Adapter } from '../adapter.js';
 import { segment } from '../utils.js';
 import { connectEndpointInstance, disconnectEndpointInstance } from './connect-endpoint-instance.js';
@@ -81,7 +82,7 @@ export class EndpointLifecycleService {
         const loader = configService.configs.get(configService.primaryFile);
         const endpoints = readAllEndpoints(this.root);
         await this.persistEndpoints(endpoints);
-        const configPath = loader.resolvedPath;
+        const configPath = formatDisplayPath(loader.resolvedPath);
         const names = endpoints.map((e) => `${e.context}/${e.name}`).join(', ') || '（无）';
         return {
             message: `✅ 已将 ${endpoints.length} 个 endpoint 写入 \`${configPath}\`：${names}`,

package/lib/built/endpoint-lifecycle.js

@@ -26,9 +26,10 @@ export async function emitEndpointLifecycle(plugin, adapter, endpoint, kind, det
         $id: `endpoint-lifecycle:${endpoint.$id}:${kind}:${Date.now()}`,
         $adapter: adapter.name,
         $endpoint: endpoint.$id,
-        $type: 'endpoint.lifecycle',
-        $subType: kind,
-        $channel: { id: endpoint.$id, type: 'private' },
+        $type: 'notice',
+        $scene_id: endpoint.$id,
+        $scene_type: 'endpoint',
+        $sub_type: kind,
         $timestamp: Date.now(),
     });
     adapter.emit('notice.receive', notice);

package/lib/built/html-to-text.js

@@ -79,20 +79,21 @@ function stripRemainingTags(html) {
     return out;
 }
 function decodeCommonEntities(text) {
-    return text
-        .replace(/ /gi, ' ')
-        .replace(/&/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
-        .replace(/&apos;/g, "'")
-        .replace(/&#(\d+);/g, (_, code) => {
-        const n = Number(code);
-        return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
-    })
-        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => {
-        const n = parseInt(hex, 16);
+    return text.replace(/&(#x[0-9a-fA-F]+|#\d+|nbsp|amp|lt|gt|quot|apos);/gi, (entity) => {
+        const key = entity.slice(1, -1).toLowerCase();
+        if (key === 'nbsp')
+            return ' ';
+        if (key === 'amp')
+            return '&';
+        if (key === 'lt')
+            return '<';
+        if (key === 'gt')
+            return '>';
+        if (key === 'quot')
+            return '"';
+        if (key === 'apos')
+            return "'";
+        const n = key.startsWith('#x') ? parseInt(key.slice(2), 16) : Number(key.slice(1));
         return Number.isFinite(n) && n >= 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
     });
 }

package/lib/built/inbound-pipeline.d.ts

@@ -4,7 +4,7 @@
  * Extracted from Adapter.emit() override to improve testability and decoupling.
  * Handles: event routing, logging, backpressure, pipeline execution, observer emission.
  */
-import type { Logger } from '@zhin.js/logger';
+import { type Logger } from '@zhin.js/logger';
 import { type Message as MessageType } from '../message.js';
 import type { Plugin } from '../plugin.js';
 export interface InboundPipelineOptions {

package/lib/built/inbound-pipeline.js

@@ -54,7 +54,7 @@ export class InboundMessagePipeline {
         return result;
     }
     logIncoming(message) {
-        this.options.logger.info(formatCompact({
+        this.options.logger.debug(formatCompact({
             recv: `${message.$channel.type}(${message.$channel.id})`,
             endpoint: message.$endpoint,
             preview: truncatePreview(segment.raw(message.$content)),

package/lib/built/interactive-segments/action.js

@@ -19,11 +19,26 @@ const PAYLOAD_PATTERN = /^[a-z0-9_]+:[^:\s]+:[a-z0-9_-]+$/i;
 /** 去掉 @bot、XML at 段、首尾空白（QQ 指令预填文本归一化） */
 export function stripInteractiveCommandText(raw) {
     let text = raw.trim();
-    text = text.replace(/<at\s[^>]*\/>/gi, ' ');
+    text = stripXmlAtSegments(text);
     text = text.replace(/^@\S+\s+/u, '');
     text = text.replace(/\s+/g, ' ').trim();
     return text;
 }
+function stripXmlAtSegments(text) {
+    let out = '';
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.toLowerCase().indexOf('<at ', cursor);
+        if (start < 0)
+            break;
+        const end = text.indexOf('/>', start + 4);
+        if (end < 0)
+            break;
+        out += text.slice(cursor, start) + ' ';
+        cursor = end + 2;
+    }
+    return out + text.slice(cursor);
+}
 /** 从文本降级输入解析 payload（需在 active session 的 fallback.map 中查找） */
 export function resolveTextFallbackPayload(raw, map) {
     const trimmed = raw.trim();

package/lib/built/message-enrich.d.ts

@@ -5,7 +5,7 @@ import type { Plugin } from '../plugin.js';
 import { Message, type MessageChannel } from '../message.js';
 import type { Adapters } from '../adapter.js';
 import type { SendContent } from '../types.js';
-import type { SenderRole } from './roles.js';
+import { type SenderRole } from './roles.js';
 /** Agent turn 可挂载在 Message 扩展字段上的元数据 */
 export type AgentTurnMessage = Message<{
     extra?: Record<string, unknown>;

package/lib/built/permit-check.d.ts

@@ -2,6 +2,6 @@
  * 内置 permit 同步校验（adapter/group/private/channel/user/role）
  */
 import type { Message } from '../message.js';
-import type { SenderRole } from './roles.js';
+import { type SenderRole } from './roles.js';
 export declare function checkBuiltinPermit(name: string, message: Message<any>, roles: readonly SenderRole[]): boolean;
 export declare function checkBuiltinPermitList(permits: readonly string[], message: Message<any>, roles: readonly SenderRole[]): boolean;

package/lib/built/schedule.d.ts

@@ -1,8 +1,7 @@
 /**
  * ScheduleFeature — 管理插件注册的内存定时任务
  */
-import { Feature, FeatureJSON, type ScheduleKind } from '@zhin.js/kernel';
-import type { HolidayInput, ScatterInput } from '@zhin.js/kernel';
+import { Feature, FeatureJSON, type ScheduleKind, type HolidayInput, type ScatterInput } from '@zhin.js/kernel';
 export interface ScheduleDescriptor {
     kind: ScheduleKind | 'every' | 'at';
     /** 6 段 cron（solar/lunar/workday/freeDay/holiday） */

package/lib/built/schedule.js

@@ -1,7 +1,7 @@
 /**
  * ScheduleFeature — 管理插件注册的内存定时任务
  */
-import { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine, } from '@zhin.js/kernel';
+import { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine } from '@zhin.js/kernel';
 function ensureEngine() {
     let engine = getScheduleEngine();
     if (!engine) {

package/lib/component.js

@@ -176,24 +176,41 @@ function parseAttributeValue(str, startIndex, context) {
 function evaluateQuotedExpression(quotedValue, context) {
     if (!context)
         return quotedValue;
-    // 处理引号内的表达式，将 {expr} 格式转换为 ${expr} 格式
-    let result = quotedValue;
-    const expressionRegex = /\{([^}]+)\}/g;
-    let match;
-    while ((match = expressionRegex.exec(quotedValue)) !== null) {
-        const expr = match[1];
+    let result = '';
+    let cursor = 0;
+    for (const match of readBraceExpressions(quotedValue)) {
+        result += quotedValue.slice(cursor, match.start);
         try {
-            const value = context.getValue(expr);
-            if (value !== undefined && value !== expr) {
+            const value = context.getValue(match.expr);
+            if (value !== undefined && value !== match.expr) {
                 const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
-                result = result.replace(match[0], stringValue);
+                result += stringValue;
+            }
+            else {
+                result += quotedValue.slice(match.start, match.end);
             }
         }
         catch (error) {
-            // 如果求值失败，保持原始表达式
+            result += quotedValue.slice(match.start, match.end);
         }
+        cursor = match.end;
     }
-    return result;
+    return result + quotedValue.slice(cursor);
+}
+function readBraceExpressions(value) {
+    const matches = [];
+    let cursor = 0;
+    while (cursor < value.length) {
+        const start = value.indexOf('{', cursor);
+        if (start < 0)
+            break;
+        const end = value.indexOf('}', start + 1);
+        if (end < 0)
+            break;
+        matches.push({ start, end: end + 1, expr: value.slice(start + 1, end) });
+        cursor = end + 1;
+    }
+    return matches;
 }
 /**
  * 解析表达式值

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './side-event/index.js';
 export * from './prompt.js';
 export * from './types.js';
 export * from './agent-prompt.js';

package/lib/index.js

@@ -9,6 +9,7 @@ export * from './message.js';
 export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
+export * from './side-event/index.js';
 export * from './prompt.js';
 export * from './types.js';
 export * from './agent-prompt.js';

package/lib/notice.d.ts

@@ -1,81 +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>;
 }

package/lib/notice.js

@@ -1,8 +1,6 @@
+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);
     }

package/lib/plugin.d.ts

@@ -6,12 +6,10 @@
  * - 生命周期事件类型安全（Plugin.Lifecycle）
  * - 中间件系统、适配器管理、useContext 等
  */
-import type { PluginManifest } 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 { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions, MessageSendPayload } from "./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";

package/lib/plugin.js

@@ -13,8 +13,7 @@ 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";
@@ -121,15 +120,20 @@ export class Plugin extends PluginBase {
     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;
     }
     /**
@@ -426,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);
                 }
             }
         }

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.4",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,9 +45,9 @@
     "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/kernel": "1.0.3",
+    "@zhin.js/database": "1.0.76",
+    "@zhin.js/logger": "1.0.74",
     "@zhin.js/schema": "1.0.71"
   },
   "peerDependencies": {
@@ -62,7 +62,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.4"
   },
   "repository": {
     "type": "git",