@zhin.js/core 1.5.2 → 1.5.4

package/lib/command.js

@@ -1,4 +1,5 @@
 import { SegmentMatcher } from 'segment-matcher';
+import { toPermissionSubject } from '@zhin.js/permission';
 /**
  * MessageCommand类：经典命令系统（segment-matcher）。
  *
@@ -75,26 +76,22 @@ export class MessageCommand extends SegmentMatcher {
         return this.#permissions;
     }
     /** 与 handle 一致的 permit 校验，供帮助菜单等场景过滤不可见命令 */
-    async checkPermits(message, plugin) {
+    async checkPermits(message, host) {
         if (!this.#permissions.length)
             return true;
-        const auth = plugin.contextIsReady('permission') ? plugin.inject('permission') : null;
-        if (!auth)
+        if (!host)
             return false;
-        for (const permit of this.#permissions) {
-            if (!(await auth.check(permit, message)))
-                return false;
-        }
-        return true;
+        const subject = toPermissionSubject(message);
+        return host.checkAll(this.#permissions, subject);
     }
     /**
      * 处理消息，自动匹配命令并执行回调
      * @param message 消息对象
-     * @param plugin 插件实例
+     * @param host PermissionHost（null 时有 permit 的命令 fail-closed）
      * @returns 命令返回内容或undefined
      */
-    async handle(message, plugin) {
-        if (!(await this.checkPermits(message, plugin))) {
+    async handle(message, host) {
+        if (!(await this.checkPermits(message, host))) {
             return;
         }
         const matched = this.match(message.$content);

package/lib/endpoint-capabilities.d.ts

@@ -22,15 +22,14 @@ export interface OutboundEndpoint<Config extends object = object> {
     $config: Config;
     $connected: boolean;
     $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
 }
 export type FullEndpoint<Config extends object = object, Event extends object = object> = InboundEndpoint<Config, Event> & OutboundEndpoint<Config>;
 export type CapableEndpoint<Config extends object, Event extends object, Caps extends readonly EndpointCapability[]> = ('inbound' extends Caps[number] ? InboundEndpoint<Config, Event> : object) & ('outbound' extends Caps[number] ? OutboundEndpoint<Config> : object);
 export declare class OutboundNotSupportedError extends Error {
-    constructor(endpointId?: string);
+    constructor(endpointKey?: string);
 }
 export declare class InboundNotSupportedError extends Error {
-    constructor(endpointId?: string);
+    constructor(endpointKey?: string);
 }
 export declare function registerEndpointCapabilities(endpoint: object, caps: readonly EndpointCapability[]): void;
 export declare function getEndpointCapabilities(endpoint: object): readonly EndpointCapability[] | undefined;

package/lib/endpoint-capabilities.js

@@ -1,13 +1,13 @@
 export const DEFAULT_ENDPOINT_CAPABILITIES = ['inbound', 'outbound'];
 export class OutboundNotSupportedError extends Error {
-    constructor(endpointId) {
-        super(endpointId ? `Endpoint ${endpointId} does not support outbound` : 'Outbound not supported');
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support outbound` : 'Outbound not supported');
         this.name = 'OutboundNotSupportedError';
     }
 }
 export class InboundNotSupportedError extends Error {
-    constructor(endpointId) {
-        super(endpointId ? `Endpoint ${endpointId} does not support inbound` : 'Inbound not supported');
+    constructor(endpointKey) {
+        super(endpointKey ? `Endpoint ${endpointKey} does not support inbound` : 'Inbound not supported');
         this.name = 'InboundNotSupportedError';
     }
 }

package/lib/endpoint.d.ts

@@ -3,6 +3,8 @@ import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabi
 import type { EndpointWithManagement } from '@zhin.js/adapter';
 export type { EndpointChannel, EndpointChannelParent, EndpointFriend, EndpointGroup, EndpointManagement, EndpointWithManagement, EndpointManagementCapability, } from '@zhin.js/adapter';
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export type { EndpointControl, EndpointWithControl } from '@zhin.js/adapter';
+export { resolveEndpointControl } from '@zhin.js/adapter';
 export type { EndpointCapability, EndpointCapabilitiesConfig, InboundEndpoint, OutboundEndpoint, FullEndpoint, CapableEndpoint, } from './endpoint-capabilities.js';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';
 /**

package/lib/endpoint.js

@@ -1,2 +1,3 @@
 export { endpointManagementCapabilityIds, listEndpointManagementCapabilities, resolveEndpointManagement, } from '@zhin.js/adapter';
+export { resolveEndpointControl } from '@zhin.js/adapter';
 export { DEFAULT_ENDPOINT_CAPABILITIES, OutboundNotSupportedError, InboundNotSupportedError, resolveEndpointCapabilities, registerEndpointCapabilities, getEndpointCapabilities, getAdapterCapabilities, hasInbound, hasOutbound, assertInbound, assertOutbound, } from './endpoint-capabilities.js';

package/lib/errors.d.ts

@@ -8,8 +8,8 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export declare class AdapterError extends ZhinError {
     readonly adapterName: string;
-    readonly endpointId?: string;
-    constructor(message: string, adapterName: string, endpointId?: string, context?: Record<string, any>);
+    readonly endpointKey?: string;
+    constructor(message: string, adapterName: string, endpointKey?: string, context?: Record<string, any>);
 }
 /**
  * 消息处理错误

package/lib/errors.js

@@ -8,11 +8,11 @@ import { ZhinError } from '@zhin.js/kernel';
  */
 export class AdapterError extends ZhinError {
     adapterName;
-    endpointId;
-    constructor(message, adapterName, endpointId, context) {
-        super(message, 'ADAPTER_ERROR', { ...context, adapterName, endpointId });
+    endpointKey;
+    constructor(message, adapterName, endpointKey, context) {
+        super(message, 'ADAPTER_ERROR', { ...context, adapterName, endpointKey });
         this.adapterName = adapterName;
-        this.endpointId = endpointId;
+        this.endpointKey = endpointKey;
     }
 }
 /**

package/lib/host-plugin-registry.d.ts

@@ -1,7 +1,8 @@
 /**
- * 宿主根插件引用 — 在 Bot 启动/装配阶段注册，供运行时路径读取。
- * 避免在中间件、工具 execute、命令 action 等回调内调用 getPlugin()（ALS 易丢失）。
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
  */
-import type { Plugin } from './plugin.js';
-export declare function setHostRootPlugin(plugin: Plugin | null): void;
-export declare function getHostRootPlugin(): Plugin | null;
+/** @deprecated 已删除——不做任何事。 */
+export declare function setHostRootPlugin(_plugin: unknown): void;
+/** @deprecated 已删除——总是返回 null。 */
+export declare function getHostRootPlugin(): null;

package/lib/host-plugin-registry.js

@@ -1,7 +1,12 @@
-let hostRoot = null;
-export function setHostRootPlugin(plugin) {
-    hostRoot = plugin ? (plugin.root ?? plugin) : null;
+/**
+ * @deprecated **已删除**。全局根插件注册表已移除；服务通过 Scope+Token 提供。
+ * 保留 no-op 签名供编译期过渡。
+ */
+/** @deprecated 已删除——不做任何事。 */
+export function setHostRootPlugin(_plugin) {
+    // no-op: legacy host root plugin registry has been removed
 }
+/** @deprecated 已删除——总是返回 null。 */
 export function getHostRootPlugin() {
-    return hostRoot;
+    return null;
 }

package/lib/im-scene.d.ts

@@ -9,7 +9,7 @@ export interface IMSceneParentRef {
 }
 export interface IMSceneRef {
     platform: string;
-    endpointId: string;
+    endpointKey: string;
     sceneId: string;
     kind: IMSceneKind;
     senderId?: string;

package/lib/im-scene.js

@@ -12,9 +12,9 @@ export function normalizeIMSceneParentKind(value) {
 }
 export function sceneRefFromMessage(message) {
     const platform = nonEmptyString(message.$adapter);
-    const endpointId = nonEmptyString(message.$endpoint);
+    const endpointKey = nonEmptyString(message.$endpoint);
     const kind = message.$channel?.type;
-    if (!platform || !endpointId || !kind)
+    if (!platform || !endpointKey || !kind)
         return undefined;
     const senderId = nonEmptyString(message.$sender?.id);
     const channelId = nonEmptyString(message.$channel?.id);
@@ -34,7 +34,7 @@ export function sceneRefFromMessage(message) {
         : undefined;
     return {
         platform,
-        endpointId,
+        endpointKey,
         sceneId,
         kind,
         ...(senderId ? { senderId } : {}),
@@ -45,7 +45,7 @@ export function sceneRefToSendOptions(target, content) {
     const { scene } = target;
     return {
         context: scene.platform,
-        endpoint: scene.endpointId,
+        endpoint: scene.endpointKey,
         id: scene.sceneId,
         type: scene.kind,
         parent: scene.parent
@@ -59,7 +59,7 @@ export function sceneRefToSendOptions(target, content) {
 export function resolveIMSceneSessionId(scene) {
     return resolveIMSceneSessionIdKernel({
         platform: scene.platform,
-        endpointId: scene.endpointId,
+        endpointKey: scene.endpointKey,
         sceneId: scene.sceneId,
         kind: scene.kind,
     });

package/lib/im-session-id.d.ts

@@ -1,7 +1,7 @@
 /**
  * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
  *
- * 格式：`platform:endpointId:kind:sceneId`
+ * 格式：`platform:endpointKey:kind:sceneId`
  */
 import { type ResolveIMSessionIdInput } from '@zhin.js/kernel';
 import { type IMSceneKind, type IMSceneRef } from './im-scene.js';
@@ -33,7 +33,7 @@ export declare function resolveSceneFieldsFromMessage(message: {
     };
 }): {
     platform: string;
-    endpointId: string;
+    endpointKey: string;
     sceneId: string;
     sceneType: IMSceneKind;
 };

package/lib/im-session-id.js

@@ -1,7 +1,7 @@
 /**
  * IM 会话 ID 解析（SSOT 在 @zhin.js/kernel + im-scene）
  *
- * 格式：`platform:endpointId:kind:sceneId`
+ * 格式：`platform:endpointKey:kind:sceneId`
  */
 import { resolveIMSceneIdForSession as resolveIMSceneIdForSessionKernel, resolveIMSessionId as resolveIMSessionIdKernel, } from '@zhin.js/kernel';
 import { resolveIMSceneSessionId, sceneRefFromMessage, } from './im-scene.js';
@@ -21,7 +21,7 @@ export function resolveIMSessionIdFromMessage(message) {
     const kind = (message.$channel?.type || 'private');
     return resolveIMSessionId({
         platform: String(message.$adapter || ''),
-        endpointId: String(message.$endpoint || ''),
+        endpointKey: String(message.$endpoint || ''),
         kind,
         sceneId: resolveIMSceneIdForSession(kind, message.$channel?.id, message.$sender?.id),
     });
@@ -32,7 +32,7 @@ export function resolveSceneFieldsFromMessage(message) {
     if (scene) {
         return {
             platform: scene.platform,
-            endpointId: scene.endpointId,
+            endpointKey: scene.endpointKey,
             sceneId: scene.sceneId,
             sceneType: scene.kind,
         };
@@ -40,7 +40,7 @@ export function resolveSceneFieldsFromMessage(message) {
     const sceneType = (message.$channel?.type || 'private');
     return {
         platform: String(message.$adapter || ''),
-        endpointId: String(message.$endpoint || ''),
+        endpointKey: String(message.$endpoint || ''),
         sceneType,
         sceneId: resolveIMSceneIdForSession(sceneType, message.$channel?.id, message.$sender?.id),
     };

package/lib/index.d.ts

@@ -20,7 +20,6 @@ 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/permission.js';
 export * from './built/permit-parse.js';
 export * from './built/permit-check.js';
 export * from './built/platform-permit.js';
@@ -42,7 +41,6 @@ export * from './built/dispatcher.js';
 export * from './built/schema-feature.js';
 export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
-export * from './built/qrcode-segment.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
 export * from './built/ai-outbound/index.js';
@@ -52,6 +50,7 @@ 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';

package/lib/index.js

@@ -22,7 +22,6 @@ export * from './built/schedule.js';
 // Models
 export * from './models/system-log.js';
 export * from './models/user.js';
-export * from './built/permission.js';
 export * from './built/permit-parse.js';
 export * from './built/permit-check.js';
 export * from './built/platform-permit.js';
@@ -43,7 +42,6 @@ export * from './built/dispatcher.js';
 export * from './built/schema-feature.js';
 export * from './built/login-assist.js';
 export * from './built/generated-qrcode.js';
-export * from './built/qrcode-segment.js';
 export * from './built/rich-segments/index.js';
 export * from './built/interactive-segments/index.js';
 export * from './built/ai-outbound/index.js';

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;

package/lib/jsx.d.ts

@@ -1,30 +1,28 @@
-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>;

package/lib/message.d.ts

@@ -1,4 +1,4 @@
-import { MessageElement, MessageSender, SendContent } from "./types.js";
+import type { MessageElement, MessageSender, SendContent } from "./types.js";
 import { Component } from "./component.js";
 import { Adapters } from "./adapter.js";
 /**

package/lib/message.js

@@ -6,7 +6,7 @@ export var Message;
      * 工具方法：合并自定义字段与基础消息结构
      */
     function from(input, format) {
-        return Object.assign(input, format);
+        return Object.assign({}, input, format);
     }
     Message.from = from;
     function quoteIdFromContent(content) {

package/lib/notice.d.ts

@@ -1,7 +1,7 @@
 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 { 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';
 /**
@@ -12,7 +12,7 @@ export { composeSideEventName, formatSideEventName, matchesSideEventName, parseS
  * const notice = Notice.from(rawEvent, {
  *   $id: rawEvent.id,
  *   $adapter: 'icqq',
- *   $endpoint: endpointId,
+ *   $endpoint: endpointKey,
  *   $type: 'notice',
  *   $scene_id: groupId,
  *   $scene_type: 'group',

package/lib/plugin-context.d.ts

@@ -7,23 +7,21 @@
 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;
 /**
- * getPlugin - 获取当前 AsyncLocalStorage 中的插件实例
- *
- * **调用时机（重要）**
- * - ✅ 插件**初始化/装配**阶段：模块顶层、register/init 函数内、注册命令/中间件/工具**之前**
- * - ❌ **运行时回调**内严禁调用：中间件、命令 `.action()`、工具 `.execute()`、Cron、生命周期 `.on()` 等
- *
- * 运行时回调应使用初始化时捕获的 `plugin` / `root` 闭包引用，而非再次 `getPlugin()`。
- * AsyncLocalStorage 在跨 await、线程池、部分平台适配器回调中可能丢失，导致线上 `getPlugin() must be called within a plugin context`。
- *
- * 插件作者优先在模块顶层使用 `usePlugin()` 解构 API，一般不需要 `getPlugin()`。
- * Bot 启动时框架调用 `setHostRootPlugin(root)`；运行时模块用 `getHostRootPlugin()` 代替 `getPlugin()`。
- *
- * @see docs/guide/plugin-development.md#getplugin-与-useplugin
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
  */
 export declare function getPlugin(): Plugin;

package/lib/plugin-context.js

@@ -11,6 +11,22 @@ 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;
+}
 /**
  * 获取当前文件路径（调用者）
  */
@@ -38,24 +54,11 @@ export function getCurrentFile(metaUrl = import.meta.url) {
     }
 }
 /**
- * getPlugin - 获取当前 AsyncLocalStorage 中的插件实例
- *
- * **调用时机（重要）**
- * - ✅ 插件**初始化/装配**阶段：模块顶层、register/init 函数内、注册命令/中间件/工具**之前**
- * - ❌ **运行时回调**内严禁调用：中间件、命令 `.action()`、工具 `.execute()`、Cron、生命周期 `.on()` 等
- *
- * 运行时回调应使用初始化时捕获的 `plugin` / `root` 闭包引用，而非再次 `getPlugin()`。
- * AsyncLocalStorage 在跨 await、线程池、部分平台适配器回调中可能丢失，导致线上 `getPlugin() must be called within a plugin context`。
- *
- * 插件作者优先在模块顶层使用 `usePlugin()` 解构 API，一般不需要 `getPlugin()`。
- * Bot 启动时框架调用 `setHostRootPlugin(root)`；运行时模块用 `getHostRootPlugin()` 代替 `getPlugin()`。
- *
- * @see docs/guide/plugin-development.md#getplugin-与-useplugin
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录；运行时通过 Scope+Token 访问服务。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
  */
 export function getPlugin() {
-    const plugin = storage.getStore();
-    if (!plugin) {
-        throw new Error('getPlugin() must be called within a plugin context');
-    }
-    return plugin;
+    throw new Error('getPlugin() has been removed. Use `definePlugin` + convention directories, '
+        + 'and access services via Scope+Token. '
+        + 'See docs/contributing/public-api-surface.md');
 }

package/lib/plugin-runtime/im/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { PluginId } from '@zhin.js/plugin-runtime';
 import type { ConversationRef, DeliveryReceipt, MessageRef } from '@zhin.js/im-contract';
 import type { MediaRef, Segment } from '../../built/segment-contract/types.js';
 export type { MediaRef, Segment };
@@ -24,22 +24,56 @@ export declare function isComponentCall(value: SendContent): value is ComponentC
 export declare function isRawContent(value: SendContent): value is RawContent;
 /** canonical Segment 一等公民判定（与 ComponentCall/RawContent 的 $content brand 互斥）。 */
 export declare function isSegmentContent(value: unknown): value is Segment;
+export interface MessageSenderRef {
+    readonly id: string;
+    readonly name?: string;
+    readonly roles?: readonly string[];
+}
 export interface IncomingMessage {
     readonly conversation: ConversationRef;
     readonly message?: MessageRef;
     readonly content: string;
     readonly segments?: readonly Segment[];
-    readonly sender?: string;
+    readonly sender?: MessageSenderRef;
+    /** Endpoint 实例名（如 ICQQ uin、sandbox bot name），区别于 conversation.endpoint.id（CapabilityId）。 */
+    readonly endpointId?: string;
+    /** 消息是否 @了机器人。 */
+    readonly mentioned?: boolean;
+    /** 引用/回复的原始消息。 */
+    readonly replyTo?: {
+        readonly id: string;
+    };
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/**
+ * 入站消息上下文快照 — 由 reply 闭包捕获，沿出站链路传递到模板编译。
+ * 定时任务 / 跨通道发送时整个 incoming 为 undefined。
+ */
+export interface IncomingContext {
+    readonly sender?: MessageSenderRef;
+    /** 收到的消息纯文本内容。 */
+    readonly content: string;
+    /** 结构化消息段（图片、@、引用等）。 */
+    readonly segments?: readonly Segment[];
+    /** 平台原生消息 ID。 */
+    readonly messageId?: string;
+    /** 消息到达时间戳（ms）。 */
+    readonly timestamp: number;
+    /** Endpoint 实例名（如 ICQQ uin、sandbox bot name）。 */
+    readonly endpointId?: string;
+    /** 消息是否 @了机器人。 */
+    readonly mentioned?: boolean;
+}
 export interface SendRequest {
     readonly conversation: ConversationRef;
     readonly requester: PluginId;
     readonly content: SendContent;
+    /** Incoming message context (absent for scheduled / cross-channel sends). */
+    readonly incoming?: IncomingContext;
 }
 /**
  * Host 侧未锚定 endpoint 的会话地址（Console RPC / OutboundHost 入参）；
- * ImRuntime 解析 adapter/endpointId 后锚定为完整 ConversationRef。
+ * ImRuntime 解析 adapter/endpointKey 后锚定为完整 ConversationRef。
  */
 export type ConversationAddress = Omit<ConversationRef, 'endpoint'>;
 export interface OutboundEnvelope {
@@ -58,12 +92,6 @@ export interface MessageGateway {
      * payload 都会路由到这里。
      */
     registerInteractiveHandler(prefix: string, handler: (message: Message) => Promise<boolean> | boolean): () => void;
-    /**
-     * Command miss（或非前缀文本）后的回退处理：Host AI 对话、单文件 bot 用。
-     * 返回 true 表示已处理（回复已发送）；后注册者覆盖前者。
-     * `requester` 是消息所属 Adapter Endpoint 的 owner（用于 CapabilityIngress 继承）。
-     */
-    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
 }
 export interface MessageDispatchResult {
     readonly matched: boolean;
@@ -75,7 +103,7 @@ export declare class Message {
     readonly conversation: ConversationRef;
     readonly content: string;
     readonly generation: number;
-    readonly sender?: string | undefined;
+    readonly sender?: MessageSenderRef | undefined;
     readonly metadata: Readonly<Record<string, unknown>>;
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
@@ -84,17 +112,68 @@ export declare class Message {
     readonly segments?: readonly Segment[] | undefined;
     /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     readonly message?: MessageRef | undefined;
-    constructor(conversation: ConversationRef, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<DeliveryReceipt>, sender?: string | undefined, metadata?: Readonly<Record<string, unknown>>, 
+    readonly endpointId?: string | undefined;
+    readonly mentioned?: boolean | undefined;
+    readonly replyTo?: {
+        readonly id: string;
+    } | undefined;
+    constructor(conversation: ConversationRef, content: string, generation: number, reply: (content: SendContent, requester?: PluginId, targetConversation?: ConversationAddress) => Promise<DeliveryReceipt>, sender?: MessageSenderRef | undefined, metadata?: Readonly<Record<string, unknown>>, 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     segments?: readonly Segment[] | undefined, 
     /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
-    message?: MessageRef | undefined);
+    message?: MessageRef | undefined, endpointId?: string | undefined, mentioned?: boolean | undefined, replyTo?: {
+        readonly id: string;
+    } | undefined);
     /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
     get id(): string | undefined;
     readonly $reply: (content: SendContent) => Promise<DeliveryReceipt>;
     readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 向同 Endpoint 的另一个通道发送消息（通用）。
+     *
+     * ```ts
+     * await message.$sendTo({ kind: 'channel', id: 'ch-1', parent: { kind: 'channel', id: 'guild-1' } }, '频道通知');
+     * ```
+     */
+    readonly $sendTo: (conversation: ConversationAddress, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 私信当前消息的发送者（同 Endpoint）。
+     *
+     * @param content 消息内容
+     * @param from 会话上下文：
+     *   - `true` — 用当前群/频道作为 parent（要求当前不在私聊中）
+     *   - `{ kind, id }` — 显式指定 parent（群或子频道）
+     *   - 省略 — 直接私信
+     *
+     * ```ts
+     * await message.$replyToPrivate('直接私信');
+     * await message.$replyToPrivate('群临时私信', true);
+     * await message.$replyToPrivate('频道私信', { kind: 'channel', id: '子频道ID' });
+     * ```
+     */
+    readonly $replyToPrivate: (content: SendContent, from?: boolean | {
+        readonly kind: 'group' | 'channel';
+        readonly id: string;
+    }) => Promise<DeliveryReceipt>;
+    /**
+     * 向指定群发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToGroup('67890', '群通知');
+     * ```
+     */
+    readonly $replyToGroup: (groupId: string, content: SendContent) => Promise<DeliveryReceipt>;
+    /**
+     * 向指定频道/子频道发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToChannel('channel-1', 'guild-1', '频道通知');
+     * await message.$replyToChannel('channel-1', 'guild-1', '话题回复', 'thread-1');
+     * ```
+     */
+    readonly $replyToChannel: (channelId: string, guildId: string, content: SendContent, threadId?: string) => Promise<DeliveryReceipt>;
 }
 export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;