@zhin.js/core 1.1.33 → 1.1.35

package/lib/index.d.ts

@@ -1,24 +1,37 @@
-export * from './bot.js';
+/**
+ * Canonical IM messages, Endpoints, rendering, and plugin-facing core types.
+ * @module @zhin.js/core
+ */
+export * from './endpoint.js';
+export * from './endpoint-capabilities.js';
 export * from './plugin.js';
 export * from './command.js';
 export * from './component.js';
 export * from './adapter.js';
 export * from './message.js';
-export { quoteIdFromContent, quoteIdFromRaw, syncQuoteId, alignReplySegments } from './message-quote.js';
-export { htmlToPlainText, htmlToPlainTextWithBlockBreaks } from './built/html-to-text.js';
-export { prependQuoteContext, resolveQuotedMessagePayload, resolveQuoteContextBlock, buildUserTurnWithQuoteContext, formatQuoteContextBlock, QUOTED_MESSAGE_CONTEXT_MARKER, CURRENT_USER_MESSAGE_MARKER, QUOTE_CONTEXT_SYSTEM_HINT, QUOTE_CONTEXT_SYSTEM_EXTRA_KEY, QUOTED_CONTENT_UNTRUSTED_NOTE, sanitizeQuotedBodyForPrompt, } from './built/prepend-quote-context.js';
+export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
-export * from './prompt.js';
-export * from './models/system-log.js';
-export * from './models/user.js';
+export * from './system-event.js';
+export * from './side-event/index.js';
+export * from './schema-interaction.js';
+export type * from '@zhin.js/interaction';
+export * from './types.js';
+export * from './utils.js';
+export * from './errors.js';
 export * from './built/config.js';
 export * from './built/command.js';
-export * from './built/cron.js';
-export * from './built/permission.js';
-export * from './built/adapter-process.js';
-export { isDenoDeploy, isInteractiveStdin, shouldBindProcessStdin, runtimePid, runtimeUser, } from './built/runtime-io.js';
-export * from './built/component.js';
+export * from './built/schedule.js';
+export type { ScheduleDescriptor, ScheduleHandle, ScheduleContextExtensions } from './built/schedule.js';
+export * from './models/system-log.js';
+export * from './models/user.js';
+export * from './built/permit-parse.js';
+export * from './built/permit-check.js';
+export * from './built/platform-permit.js';
+export * from './built/authorization.js';
+export * from './built/message-enrich.js';
+export type { AgentTurnMessage, SyntheticMessageInput } from './built/message-enrich.js';
+export * from './built/runtime-io.js';
 export * from './built/database.js';
 export * from './built/message-filter.js';
 export * from './built/tool.js';
@@ -26,20 +39,45 @@ export * from './built/skill.js';
 export * from './built/agent-preset.js';
 export * from './built/common-adapter-tools.js';
 export * from './built/roles.js';
+export * from './im-session-id.js';
 export * from './built/ai-trigger.js';
+export * from './built/ai-access.js';
 export * from './built/dispatcher.js';
 export * from './built/schema-feature.js';
 export * from './built/login-assist.js';
-export { BaseProvider, OpenAIProvider, DeepSeekProvider, MoonshotProvider, ZhipuProvider, AnthropicProvider, OllamaProvider, CloudflareProvider, GoogleProvider, Agent, createAgent, formatToolTitle, filterTools, tokenize, SessionManager, MemorySessionManager, DatabaseSessionManager, createSessionManager, createMemorySessionManager, createDatabaseSessionManager, AI_SESSION_MODEL, resolveIMSessionId, resolveIMSceneIdForSession, resolveIMSessionIdFromToolContext, ContextManager, createContextManager, CHAT_MESSAGE_MODEL, CONTEXT_SUMMARY_MODEL, ConversationMemory, AI_MESSAGE_MODEL, AI_SUMMARY_MODEL, estimateTokens, estimateMessagesTokens, DEFAULT_CONTEXT_TOKENS, microCompactMessages, CostTracker, CachedToolFilter, computeToolSetHash, FileStateCache, RateLimiter, detectTone, parseOutput, renderToPlainText, renderToSatori, MemoryStorageBackend, DatabaseStorageBackend, createSwappableBackend, ModelRegistry, extractModelRoot, computeTierScore, } from '@zhin.js/ai';
-export type { AIConfig, AIProvider, ProviderConfig, ProviderCapabilities, ChatMessage, ChatCompletionRequest, ChatCompletionResponse, ChatCompletionChunk, ContentPart, ToolCall, MessageRole, AgentTool, AgentConfig, AgentResult, ToolFilterOptions, Usage, SessionConfig, Session, JsonSchema, AgentState, AgentEvents, ContextConfig, MessageRecord as AIMessageRecord, ConversationMemoryConfig, ContextWindowSource, ContextWindowInfo, ContextWindowGuardResult, PruneResult, MicroCompactOptions, MicroCompactResult, ModelUsage, ModelPricing, CostSnapshot, RateLimitConfig, RateLimitResult, Tone, OutputElement, TextElement, ImageElement, AudioElement, VideoElement, CardElement, FileElement, StorageBackend, DbModel as AIDbModel, AIModelInfo, ModelTask, } from '@zhin.js/ai';
-export * from './types.js';
-export * from './agent-prompt.js';
-export * from './utils.js';
-export * from './errors.js';
+export * from './built/generated-qrcode.js';
+export * from './built/rich-segments/index.js';
+export * from './built/interactive-segments/index.js';
+export * from './built/user-interaction.js';
+export * from './built/ai-outbound/index.js';
+export { loadHtmlRenderer, seedHtmlRenderer, HTML_RENDERER_PACKAGE } from './built/html-renderer-loader.js';
+export { loadSpeechPipeline, seedSpeechPipeline, SPEECH_PACKAGE } from './built/speech-loader.js';
+export * from './built/outbound-media-utils.js';
+export * from './built/outbound-media-contract.js';
+export * from './built/interactive-segment-contract.js';
+export * from './built/segment-contract/index.js';
+export type { SegmentMediaRef } from './built/segment-contract/media.js';
+export * from './built/generic-segment-mapper.js';
+export * from './built/adapter-process.js';
+export * from './built/component.js';
+export * from './built/inbound-runner.js';
+export type { RunInboundMessageOptions, InboundRunResult } from './built/inbound-runner.js';
+export * from './built/connect-endpoint-instance.js';
+export type { ConnectEndpointInstanceOptions } from './built/connect-endpoint-instance.js';
+export * from './built/endpoint-lifecycle.js';
+export type { EndpointLifecycleKind, EndpointLifecyclePayload } from './built/endpoint-lifecycle.js';
+export * from './built/endpoint-manager.js';
+export type { EndpointConfigRecord, EndpointManager, ProvisionContext } from './built/endpoint-manager.js';
+export * from './built/endpoint-lifecycle-service.js';
+export * from './built/schema-endpoint-manager.js';
+export * from './built/endpoint-commands.js';
+export * from './built/introspection-format.js';
+export * from './built/management-command-guard.js';
+export * from './built/html-to-text.js';
+export * from './built/html-segment-fallback.js';
 export * from '@zhin.js/database';
 export * from '@zhin.js/logger';
 export { Schema } from '@zhin.js/schema';
 export type { PluginLike } from '@zhin.js/kernel';
-export { Feature, Cron, Scheduler, getScheduler, setScheduler, } from '@zhin.js/kernel';
-export type { FeatureJSON, FeatureListener, Schedule, JobPayload, JobState, ScheduledJob, JobStore, JobCallback, AddJobOptions, IScheduler, SchedulerOptions, } from '@zhin.js/kernel';
-//# sourceMappingURL=index.d.ts.map
+export { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine, Scheduler, getScheduler, setScheduler, } from '@zhin.js/kernel';
+export type { FeatureJSON, FeatureListener, Schedule, JobPayload, JobState, ScheduledJob, JobStore, JobCallback, AddJobOptions, IScheduler, SchedulerOptions, ScheduleFireCallback, MemoryScheduleRegistration, ScheduleEngineOptions, JobContext, ResolvedJob, ScheduleKind, } from '@zhin.js/kernel';

package/lib/index.js

@@ -1,52 +1,77 @@
-// Core exports
-export * from './bot.js';
+/**
+ * Canonical IM messages, Endpoints, rendering, and plugin-facing core types.
+ * @module @zhin.js/core
+ */
+// ── Core 类模块 ──────────────────────────────────────────────────────
+export * from './endpoint.js';
+export * from './endpoint-capabilities.js';
 export * from './plugin.js';
 export * from './command.js';
 export * from './component.js';
 export * from './adapter.js';
 export * from './message.js';
-export { quoteIdFromContent, quoteIdFromRaw, syncQuoteId, alignReplySegments } from './message-quote.js';
-export { htmlToPlainText, htmlToPlainTextWithBlockBreaks } from './built/html-to-text.js';
-export { prependQuoteContext, resolveQuotedMessagePayload, resolveQuoteContextBlock, buildUserTurnWithQuoteContext, formatQuoteContextBlock, QUOTED_MESSAGE_CONTEXT_MARKER, CURRENT_USER_MESSAGE_MARKER, QUOTE_CONTEXT_SYSTEM_HINT, QUOTE_CONTEXT_SYSTEM_EXTRA_KEY, QUOTED_CONTENT_UNTRUSTED_NOTE, sanitizeQuotedBodyForPrompt, } from './built/prepend-quote-context.js';
+export * from './im-scene.js';
 export * from './notice.js';
 export * from './request.js';
-export * from './prompt.js';
+export * from './system-event.js';
+export * from './side-event/index.js';
+export * from './schema-interaction.js';
+export * from './types.js';
+export * from './utils.js';
+export * from './errors.js';
+// ── Built 模块 ──────────────────────────────────────────────────────
+export * from './built/config.js';
+export * from './built/command.js';
+export * from './built/schedule.js';
 // Models
 export * from './models/system-log.js';
 export * from './models/user.js';
-// Built-in Contexts
-export * from './built/config.js';
-export * from './built/command.js';
-export * from './built/cron.js';
-export * from './built/permission.js';
-export * from './built/adapter-process.js';
-export { isDenoDeploy, isInteractiveStdin, shouldBindProcessStdin, runtimePid, runtimeUser, } from './built/runtime-io.js';
-export * from './built/component.js';
+export * from './built/permit-parse.js';
+export * from './built/permit-check.js';
+export * from './built/platform-permit.js';
+export * from './built/authorization.js';
+export * from './built/message-enrich.js';
+export * from './built/runtime-io.js';
 export * from './built/database.js';
 export * from './built/message-filter.js';
-// Tool/Skill/AgentPreset Features (backward-compat; canonical source is @zhin.js/agent)
 export * from './built/tool.js';
 export * from './built/skill.js';
 export * from './built/agent-preset.js';
 export * from './built/common-adapter-tools.js';
-// AI Trigger Service (纯工具，无副作用)
 export * from './built/roles.js';
+export * from './im-session-id.js';
 export * from './built/ai-trigger.js';
-// MessageDispatcher (消息调度器)
+export * from './built/ai-access.js';
 export * from './built/dispatcher.js';
-// Schema 注册表 (插件配置声明)
 export * from './built/schema-feature.js';
-// Login assist (producer-consumer for QR / SMS / slider etc.)
 export * from './built/login-assist.js';
-// AI 模块 — selective re-export from @zhin.js/ai to avoid conflicts with core types
-export { BaseProvider, OpenAIProvider, DeepSeekProvider, MoonshotProvider, ZhipuProvider, AnthropicProvider, OllamaProvider, CloudflareProvider, GoogleProvider, Agent, createAgent, formatToolTitle, filterTools, tokenize, SessionManager, MemorySessionManager, DatabaseSessionManager, createSessionManager, createMemorySessionManager, createDatabaseSessionManager, AI_SESSION_MODEL, resolveIMSessionId, resolveIMSceneIdForSession, resolveIMSessionIdFromToolContext, ContextManager, createContextManager, CHAT_MESSAGE_MODEL, CONTEXT_SUMMARY_MODEL, ConversationMemory, AI_MESSAGE_MODEL, AI_SUMMARY_MODEL, estimateTokens, estimateMessagesTokens, DEFAULT_CONTEXT_TOKENS, microCompactMessages, CostTracker, CachedToolFilter, computeToolSetHash, FileStateCache, RateLimiter, detectTone, parseOutput, renderToPlainText, renderToSatori, MemoryStorageBackend, DatabaseStorageBackend, createSwappableBackend, ModelRegistry, extractModelRoot, computeTierScore, } from '@zhin.js/ai';
-export * from './types.js';
-export * from './agent-prompt.js';
-export * from './utils.js';
-export * from './errors.js'; // 导出错误处理系统
+export * from './built/generated-qrcode.js';
+export * from './built/rich-segments/index.js';
+export * from './built/interactive-segments/index.js';
+export * from './built/user-interaction.js';
+export * from './built/ai-outbound/index.js';
+export { loadHtmlRenderer, seedHtmlRenderer, HTML_RENDERER_PACKAGE } from './built/html-renderer-loader.js';
+export { loadSpeechPipeline, seedSpeechPipeline, SPEECH_PACKAGE } from './built/speech-loader.js';
+export * from './built/outbound-media-utils.js';
+export * from './built/outbound-media-contract.js';
+export * from './built/interactive-segment-contract.js';
+export * from './built/segment-contract/index.js';
+export * from './built/generic-segment-mapper.js';
+export * from './built/adapter-process.js';
+export * from './built/component.js';
+export * from './built/inbound-runner.js';
+export * from './built/connect-endpoint-instance.js';
+export * from './built/endpoint-lifecycle.js';
+export * from './built/endpoint-manager.js';
+export * from './built/endpoint-lifecycle-service.js';
+export * from './built/schema-endpoint-manager.js';
+export * from './built/endpoint-commands.js';
+export * from './built/introspection-format.js';
+export * from './built/management-command-guard.js';
+export * from './built/html-to-text.js';
+export * from './built/html-segment-fallback.js';
+// ── 外部库 re-export ──────────────────────────────────────────────────
 export * from '@zhin.js/database';
 export * from '@zhin.js/logger';
-// 只导出 Schema 类，避免与 utils.js 的 isEmpty 冲突
 export { Schema } from '@zhin.js/schema';
-export { Feature, Cron, Scheduler, getScheduler, setScheduler, } from '@zhin.js/kernel';
-//# sourceMappingURL=index.js.map
+export { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine, Scheduler, getScheduler, setScheduler, } from '@zhin.js/kernel';

package/lib/jsx-dev-runtime.d.ts

@@ -1,3 +1,2 @@
 export * from './jsx-runtime.js';
 export { jsx as jsxDEV } from './jsx.js';
-//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/lib/jsx-dev-runtime.js

@@ -1,3 +1,2 @@
 export * from './jsx-runtime.js';
 export { jsx as jsxDEV } from './jsx.js';
-//# sourceMappingURL=jsx-dev-runtime.js.map

package/lib/jsx-runtime.d.ts

@@ -1,5 +1,6 @@
 import { jsx, jsxs, Fragment, renderJSX } from './jsx.js';
 export { jsx, jsxs, Fragment, renderJSX };
+export type { JSX } from './jsx.js';
 declare const _default: {
     jsx: typeof jsx;
     jsxs: typeof jsxs;
@@ -9,4 +10,3 @@ declare const _default: {
     renderJSX: typeof renderJSX;
 };
 export default _default;
-//# sourceMappingURL=jsx-runtime.d.ts.map

package/lib/jsx-runtime.js

@@ -8,4 +8,3 @@ export default {
     Fragment,
     renderJSX
 };
-//# sourceMappingURL=jsx-runtime.js.map

package/lib/jsx.d.ts

@@ -1,33 +1,30 @@
-import { SendContent, MessageElement } from './types.js';
-import { MessageComponent } from './message.js';
-import { Component, ComponentContext } from './component.js';
+import type { SendContent, MessageElement } from './types.js';
+import type { MessageComponent } from './message.js';
+import type { Component, ComponentContext } from './component.js';
 export type JSXChildren = MessageElement | string | number | boolean | null | undefined | JSXChildren[];
 export type JSXElementType = string | Component<any>;
 export type JSXProps = Record<string, any> & {
     children?: JSXChildren;
 };
 export { Fragment } from './component.js';
-declare global {
-    namespace JSX {
-        type Element = SendContent | Promise<SendContent>;
-        interface ElementClass {
-            render(props: any, context?: ComponentContext): Element;
-        }
-        interface ElementAttributesProperty {
-            data: {};
-        }
-        interface ElementChildrenAttribute {
-            children: {};
-        }
-        interface IntrinsicElements {
-            [elemName: string]: any;
-        }
-        interface IntrinsicAttributes {
-            key?: string | number;
-        }
+export declare namespace JSX {
+    type Element = SendContent | Promise<SendContent>;
+    interface ElementClass {
+        render(props: any, context?: ComponentContext): Element;
+    }
+    interface ElementAttributesProperty {
+        data: {};
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    interface IntrinsicElements {
+        [elemName: string]: any;
+    }
+    interface IntrinsicAttributes {
+        key?: string | number;
     }
 }
 export declare function jsx(type: JSXElementType, data: JSXProps): MessageComponent<any>;
 export declare function jsxs(type: JSXElementType, props: JSXProps): MessageElement;
 export declare function renderJSX(element: MessageComponent<any>, context?: ComponentContext): Promise<SendContent>;
-//# sourceMappingURL=jsx.d.ts.map

package/lib/jsx.js

@@ -91,4 +91,3 @@ async function renderChildren(children, context) {
     }
     return '';
 }
-//# sourceMappingURL=jsx.js.map

package/lib/message.d.ts

@@ -1,4 +1,4 @@
-import { MessageElement, MessageSender, SendContent } from "./types";
+import type { MessageElement, MessageSender, SendContent } from "./types.js";
 import { Component } from "./component.js";
 import { Adapters } from "./adapter.js";
 /**
@@ -16,6 +16,15 @@ export type MessageComponent<T extends object> = {
 export interface MessageChannel {
     id: string;
     type: MessageType;
+    /**
+     * 私聊/子频道消息的来源场景：
+     * - 群临时会话：type=private + parent.group
+     * - QQ 子频道：type=channel + parent.guild
+     */
+    parent?: {
+        type: 'group' | 'channel' | 'guild';
+        id: string;
+    };
 }
 /**
  * 消息类型枚举
@@ -27,28 +36,25 @@ export type MessageType = 'group' | 'private' | 'channel';
 export interface MessageBase {
     $id: string;
     $adapter: keyof Adapters;
-    $bot: string;
+    $endpoint: string;
     $content: MessageElement[];
     $sender: MessageSender;
-    $reply(content: SendContent, quote?: boolean | string): Promise<string>;
-    $recall(): Promise<void>;
+    $reply?(content: SendContent, quote?: boolean | string): Promise<string>;
+    $recall?(): Promise<void>;
     $channel: MessageChannel;
     $timestamp: number;
     $raw: string;
-    /** 本条消息引用的上游 message_id（平台原样字符串） */
-    $quote_id?: string;
 }
 /**
  * 完整消息类型，支持扩展
  */
 export type Message<T extends object = {}> = MessageBase & T;
+/** @internal Legacy static helpers; not part of Agent resource authoring. */
 export declare namespace Message {
     /**
      * 工具方法：合并自定义字段与基础消息结构
      */
     function from<T extends object>(input: T, format: MessageBase): Message<T>;
-    function quoteIdFromContent(content: MessageElement[]): string | undefined;
-    function syncQuoteId(message: Message<any>): void;
-    function alignReplySegments(content: MessageElement[], quoteId?: string): void;
+    function actionPayload(message: Message<any>): string | undefined;
+    function isAction(message: Message<any>): boolean;
 }
-//# sourceMappingURL=message.d.ts.map

package/lib/message.js

@@ -1,24 +1,27 @@
-import { alignReplySegments as alignReplySegmentsImpl, quoteIdFromContent as quoteIdFromContentImpl, syncQuoteId as syncQuoteIdImpl, } from "./message-quote.js";
+import { isActionMessage as isActionMessageImpl } from "./built/interactive-segments/action.js";
+/** @internal Legacy static helpers; not part of Agent resource authoring. */
 export var Message;
 (function (Message) {
     /**
      * 工具方法：合并自定义字段与基础消息结构
      */
     function from(input, format) {
-        return Object.assign(input, format);
+        return Object.assign({}, input, format);
     }
     Message.from = from;
-    function quoteIdFromContent(content) {
-        return quoteIdFromContentImpl(content);
+    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.quoteIdFromContent = quoteIdFromContent;
-    function syncQuoteId(message) {
-        syncQuoteIdImpl(message);
+    Message.actionPayload = actionPayload;
+    function isAction(message) {
+        return isActionMessageImpl(message);
     }
-    Message.syncQuoteId = syncQuoteId;
-    function alignReplySegments(content, quoteId) {
-        alignReplySegmentsImpl(content, quoteId);
-    }
-    Message.alignReplySegments = alignReplySegments;
+    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,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 } 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:        群转让
- *
- * 适配器可自行扩展更多子类型
- */
-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',
- *   $bot: botName,
- *   $type: 'group_member_decrease',
- *   $subType: 'kick',
- *   $channel: { id: groupId, type: 'group' },
- *   $operator: { id: operatorId, name: '管理员' },
+ *   $endpoint: endpointKey,
+ *   $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;
-    /** Bot 名称 */
-    $bot: 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

@@ -0,0 +1,27 @@
+/**
+ * Plugin 上下文管理 — AsyncLocalStorage + getPlugin
+ *
+ * 从 plugin.ts 提取的独立关注点，消除与 Plugin 类的循环依赖。
+ * usePlugin() 保留在 plugin.ts（需要 Plugin 构造函数）。
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Plugin } from "./plugin.js";
+export declare const storage: AsyncLocalStorage<Plugin>;
+/**
+ * Plugin Runtime (`zhin runtime start`) 启动时调用。
+ * 标记后 getPlugin()/usePlugin() 在 ALS 为空时抛出更明确的迁移提示，
+ * 而非通用的 "must be called within a plugin context"。
+ */
+export declare function markPluginRuntimeActive(): void;
+export declare function isPluginRuntimeActive(): boolean;
+/** 测试重置 */
+export declare function resetPluginRuntimeFlag(): void;
+/**
+ * 获取当前文件路径（调用者）
+ */
+export declare function getCurrentFile(metaUrl?: string): string;
+/**
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
+ */
+export declare function getPlugin(): Plugin;

package/lib/plugin-context.js

@@ -0,0 +1,64 @@
+/**
+ * Plugin 上下文管理 — AsyncLocalStorage + getPlugin
+ *
+ * 从 plugin.ts 提取的独立关注点，消除与 Plugin 类的循环依赖。
+ * usePlugin() 保留在 plugin.ts（需要 Plugin 构造函数）。
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+// ============================================================================
+// AsyncLocalStorage 上下文
+// ============================================================================
+export const storage = new AsyncLocalStorage();
+let _pluginRuntimeActive = false;
+/**
+ * Plugin Runtime (`zhin runtime start`) 启动时调用。
+ * 标记后 getPlugin()/usePlugin() 在 ALS 为空时抛出更明确的迁移提示，
+ * 而非通用的 "must be called within a plugin context"。
+ */
+export function markPluginRuntimeActive() {
+    _pluginRuntimeActive = true;
+}
+export function isPluginRuntimeActive() {
+    return _pluginRuntimeActive;
+}
+/** 测试重置 */
+export function resetPluginRuntimeFlag() {
+    _pluginRuntimeActive = false;
+}
+/**
+ * 获取当前文件路径（调用者）
+ */
+export function getCurrentFile(metaUrl = import.meta.url) {
+    if (typeof metaUrl !== "string" || metaUrl.length === 0) {
+        return path.join(process.cwd(), "__zhin_edge_bootstrap__.mjs");
+    }
+    const previousPrepareStackTrace = Error.prepareStackTrace;
+    Error.prepareStackTrace = function (_, stack) {
+        return stack;
+    };
+    const stack = new Error().stack;
+    Error.prepareStackTrace = previousPrepareStackTrace;
+    const stackFiles = Array.from(new Set(stack.map((site) => site.getFileName())));
+    const idx = stackFiles.findIndex((f) => (metaUrl.startsWith('file://') ? f === fileURLToPath(metaUrl) : false) || f === metaUrl);
+    const result = stackFiles[idx + 1];
+    if (!result) {
+        return path.join(process.cwd(), "__zhin_edge_bootstrap__.mjs");
+    }
+    try {
+        return fileURLToPath(result);
+    }
+    catch {
+        return result;
+    }
+}
+/**
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
+ */
+export function getPlugin() {
+    throw new Error('getPlugin() has been removed. Use `definePlugin` + convention directories, '
+        + 'and access services via Scope+Token. '
+        + 'See docs/contributing/public-api-surface.md');
+}