@zhin.js/core 1.5.1 → 1.5.4

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

@@ -1,4 +1,4 @@
-import type { CapabilityId, 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,77 +24,74 @@ 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 adapter: CapabilityId;
-    /** Structured identity supplied by migrated adapters; target remains the bridge. */
-    readonly conversation?: ConversationRef;
-    /** Structured native message identity supplied by migrated adapters. */
+    readonly conversation: ConversationRef;
     readonly message?: MessageRef;
-    readonly target: string;
-    /**
-     * 纯文本视图：与 `segments` 同源（adapter 从同一份入站载荷派生二者）。
-     * 触发判定与 Console 预览读取此字段；命令匹配在有 segments 时优先使用结构化视图。
-     */
     readonly content: string;
-    /**
-     * 结构化段视图（canonical Segment SSOT，见 built/segment-contract）。
-     * 与 `content` 同源：segments 承载纯文本无法表达的媒体（image/audio/video/file
-     * 的 MediaRef）、mention、reply 等信息。旧 adapter 未迁移时可缺省，
-     * 读取方必须容忍 undefined。
-     */
     readonly segments?: readonly Segment[];
-    readonly id?: string;
-    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 adapter: CapabilityId;
-    /** Structured destination supplied to Adapter endpoints in parallel with target. */
-    readonly conversation?: ConversationRef;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly requester: PluginId;
     readonly content: SendContent;
-    readonly parent?: ChannelParent;
-}
-/** Console 通道的来源场景（群临时会话 parent.group / QQ 子频道 parent.guild）。 */
-export interface ChannelParent {
-    readonly type?: string;
-    readonly id?: string;
-    readonly name?: string;
+    /** Incoming message context (absent for scheduled / cross-channel sends). */
+    readonly incoming?: IncomingContext;
 }
+/**
+ * Host 侧未锚定 endpoint 的会话地址（Console RPC / OutboundHost 入参）；
+ * ImRuntime 解析 adapter/endpointKey 后锚定为完整 ConversationRef。
+ */
+export type ConversationAddress = Omit<ConversationRef, 'endpoint'>;
 export interface OutboundEnvelope {
-    readonly adapter: CapabilityId;
-    readonly conversation?: ConversationRef;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly requester: PluginId;
     readonly generation: number;
     readonly payload: unknown;
-    readonly parent?: ChannelParent;
     replace(payload: unknown): void;
 }
 export interface MessageGateway {
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
-    /**
-     * Compatibility surface for existing Adapter-facing gateway consumers.
-     * Runtime callers that need an outcome use DeliveryMessageGateway instead.
-     */
-    send(request: SendRequest): Promise<unknown>;
+    send(request: SendRequest): Promise<DeliveryReceipt>;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
      * 平台 callback 的 action 段、'text' 端点的数字回跳与指令预填直出
      * 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;
-}
-/** Structured outbound gateway exposed by the Plugin Runtime. */
-export interface DeliveryMessageGateway extends MessageGateway {
-    send(request: SendRequest): Promise<DeliveryReceipt>;
 }
 export interface MessageDispatchResult {
     readonly matched: boolean;
@@ -103,33 +100,80 @@ export interface MessageDispatchResult {
     readonly value?: unknown;
 }
 export declare class Message {
-    readonly adapter: CapabilityId;
-    readonly target: string;
+    readonly conversation: ConversationRef;
     readonly content: string;
     readonly generation: number;
-    readonly id?: string | undefined;
-    readonly sender?: string | undefined;
+    readonly sender?: MessageSenderRef | undefined;
     readonly metadata: Readonly<Record<string, unknown>>;
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     readonly segments?: readonly Segment[] | undefined;
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    readonly conversation?: ConversationRef | undefined;
-    /** Structured inbound message identity when supplied by a migrated adapter. */
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
     readonly message?: MessageRef | undefined;
-    constructor(adapter: CapabilityId, target: string, content: string, generation: number, reply: (content: SendContent, requester?: PluginId) => Promise<unknown>, id?: string | undefined, 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, 
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    conversation?: ConversationRef | undefined, 
-    /** Structured inbound message identity when supplied by a migrated adapter. */
-    message?: MessageRef | undefined);
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
+    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;

package/lib/plugin-runtime/im/contracts.js

@@ -33,46 +33,116 @@ export function isSegmentContent(value) {
         && value.data !== null;
 }
 export class Message {
-    adapter;
-    target;
+    conversation;
     content;
     generation;
-    id;
     sender;
     metadata;
     segments;
-    conversation;
     message;
-    constructor(adapter, target, content, generation, 
-    // Compatibility at the construction boundary: legacy tests and embedders
-    // may still supply an untyped reply callback. ImRuntime always supplies a
-    // DeliveryReceipt-producing implementation.
-    reply, id, sender, metadata = Object.freeze({}), 
+    endpointId;
+    mentioned;
+    replyTo;
+    constructor(conversation, content, generation, reply, sender, metadata = Object.freeze({}), 
     /**
      * 结构化段视图（与 `content` 纯文本视图同源，见 IncomingMessage.segments）。
      * Command dispatcher 优先使用此字段，以支持 mention、image 等结构化参数。
      */
     segments, 
-    /** Structured inbound conversation when supplied by a migrated adapter. */
-    conversation, 
-    /** Structured inbound message identity when supplied by a migrated adapter. */
-    message) {
-        this.adapter = adapter;
-        this.target = target;
+    /** 结构化入站消息身份（平台原生 message id 经 MessageRef 传递）。 */
+    message, endpointId, mentioned, replyTo) {
+        this.conversation = conversation;
         this.content = content;
         this.generation = generation;
-        this.id = id;
         this.sender = sender;
         this.metadata = metadata;
         this.segments = segments;
-        this.conversation = conversation;
         this.message = message;
+        this.endpointId = endpointId;
+        this.mentioned = mentioned;
+        this.replyTo = replyTo;
         this.$reply = (content) => reply(content);
         this.$replyFrom = (requester, content) => reply(content, requester);
+        this.$sendTo = (target, content) => reply(content, undefined, target);
+        this.$replyToPrivate = (content, from) => {
+            if (!sender)
+                throw new Error('Cannot $replyToPrivate: message has no sender');
+            let parent;
+            if (from === true) {
+                if (conversation.kind !== 'group' && conversation.kind !== 'channel') {
+                    throw new Error('Cannot $replyToPrivate with from=true: current conversation must be a group or channel');
+                }
+                parent = { kind: conversation.kind, id: conversation.id };
+            }
+            else if (from != null && typeof from === 'object') {
+                parent = from;
+            }
+            return reply(content, undefined, {
+                kind: 'private',
+                id: sender.id,
+                ...(parent ? { parent } : {}),
+            });
+        };
+        this.$replyToGroup = (groupId, content) => {
+            return reply(content, undefined, { kind: 'group', id: groupId });
+        };
+        this.$replyToChannel = (channelId, guildId, content, threadId) => {
+            return reply(content, undefined, {
+                kind: 'channel',
+                id: channelId,
+                parent: { kind: 'channel', id: guildId },
+                ...(threadId ? { threadId } : {}),
+            });
+        };
         Object.freeze(this);
     }
+    /** 平台原生消息 id（`message` 未提供时为 undefined）。 */
+    get id() {
+        return this.message?.id;
+    }
     $reply;
     $replyFrom;
+    /**
+     * 向同 Endpoint 的另一个通道发送消息（通用）。
+     *
+     * ```ts
+     * await message.$sendTo({ kind: 'channel', id: 'ch-1', parent: { kind: 'channel', id: 'guild-1' } }, '频道通知');
+     * ```
+     */
+    $sendTo;
+    /**
+     * 私信当前消息的发送者（同 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' });
+     * ```
+     */
+    $replyToPrivate;
+    /**
+     * 向指定群发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToGroup('67890', '群通知');
+     * ```
+     */
+    $replyToGroup;
+    /**
+     * 向指定频道/子频道发送消息（同 Endpoint）。
+     *
+     * ```ts
+     * await message.$replyToChannel('channel-1', 'guild-1', '频道通知');
+     * await message.$replyToChannel('channel-1', 'guild-1', '话题回复', 'thread-1');
+     * ```
+     */
+    $replyToChannel;
 }
 export function createOutboundEnvelope(request, initialPayload) {
     let payload = initialPayload;

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

@@ -1,21 +1,24 @@
-import { Scope, type CapabilityId, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { Scope, type PluginId, type SnapshotLease, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { MessageBus } from './message-bus.js';
 import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
 import { type ConversationRef, type DeliveryReceipt, type MessageRef } from '@zhin.js/im-contract';
-import { Message, type ChannelParent, type DeliveryMessageGateway, type IncomingMessage, type MessageDispatchResult, type SendRequest } from './contracts.js';
+import { Message, type ConversationAddress, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type MessageSenderRef, type SendRequest } from './contracts.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { type RuntimeInteractiveHandler } from './interactive.js';
-export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<DeliveryMessageGateway>;
+export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+/** Generation-owned terminal route after interactive/command routing misses. */
+export interface IngressRoute {
+    route(message: Message, lease: SnapshotLease, requester: PluginId): Promise<boolean>;
+}
+export declare const ingressRouteToken: import("@zhin.js/plugin-runtime").Token<IngressRoute>;
 /** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
 export interface RuntimeMessageEvent {
     readonly direction: 'inbound' | 'outbound';
-    readonly adapter: CapabilityId;
-    readonly target: string;
-    /** inbound：发送者 id。 */
-    readonly sender?: string;
+    readonly conversation: ConversationRef;
+    /** inbound：发送者。 */
+    readonly sender?: MessageSenderRef;
     /** outbound：发起方插件。 */
     readonly requester?: PluginId;
-    /** inbound：从 target 前缀解析的场景（`group:xx` → `group`）。 */
-    readonly channelType?: string;
     /** 预览文本，截断至 200 字。 */
     readonly contentPreview: string;
     readonly messageId?: string;
@@ -29,17 +32,15 @@ export interface ImRuntimeOptions {
      */
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
+    /** Process-root ingress claim (pending interaction, authentication challenge, etc.). */
+    readonly inboundClaim?: (message: Message) => boolean | Promise<boolean>;
 }
-export declare class ImRuntime implements DeliveryMessageGateway {
+export declare class ImRuntime implements MessageGateway {
     #private;
     constructor(options?: ImRuntimeOptions);
     attach(snapshots: SnapshotStore): void;
-    /**
-     * Optional Host AI / fallback path after Command miss (or non-prefixed text).
-     * Return true when the message was handled (reply already sent).
-     * `requester` is the Adapter Endpoint owner (for CapabilityIngress inheritance).
-     */
-    setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
+    readonly permissionHost: import("@zhin.js/permission").PermissionHost;
+    readonly messageBus: MessageBus;
     install(resources: Scope): void;
     /**
      * 注册 interactive action 回跳 handler（prefix 最长匹配；返回注销函数）。
@@ -63,7 +64,18 @@ export declare class ImRuntime implements DeliveryMessageGateway {
         readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
         readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
-    getEndpoint(adapter: string, endpointId: string): {
+    /**
+     * Console `GET /api/stats` 同源计数：非 root 插件节点 + AdapterIndex endpoints。
+     * 供命令 / 状态卡等在 Plugin Runtime 下读取（legacy `root.adapters` / `root.children` 已不存在）。
+     */
+    inventory(): Readonly<{
+        plugins: number;
+        endpoints: {
+            readonly total: number;
+            readonly online: number;
+        };
+    }>;
+    getEndpoint(adapter: string, endpointKey: string): {
         readonly name: string;
         readonly adapter: string;
         readonly connected: boolean;
@@ -73,19 +85,16 @@ export declare class ImRuntime implements DeliveryMessageGateway {
     } | null;
     sendEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
-        readonly conversation?: ConversationRef;
-        readonly channelId?: string;
-        readonly channelType?: string;
+        readonly endpointKey: string;
+        readonly conversation: ConversationAddress;
         readonly content: unknown;
-        readonly parent?: ChannelParent;
     }): Promise<{
         messageId: string;
     }>;
     /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
     addEndpointReaction(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly emoji: string;
@@ -94,7 +103,7 @@ export declare class ImRuntime implements DeliveryMessageGateway {
     }): Promise<string | null>;
     removeEndpointReaction(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly reactionId: string;
@@ -102,33 +111,27 @@ export declare class ImRuntime implements DeliveryMessageGateway {
     /** Activity-feedback autoRemove: recall a previously sent status message. */
     recallEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
     }): Promise<void>;
     editEndpointMessage(input: {
         readonly adapter: string;
-        readonly endpointId: string;
+        readonly endpointKey: string;
         readonly message?: MessageRef;
         readonly messageId?: string;
         readonly content: unknown;
     }): Promise<string | null>;
     setEndpointTyping(input: {
         readonly adapter: string;
-        readonly endpointId: string;
-        readonly conversation?: ConversationRef;
-        readonly target?: string;
+        readonly endpointKey: string;
+        readonly conversation: ConversationRef;
         readonly active?: boolean;
     }): Promise<void>;
-    /**
-     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
-     * @deprecated Host callers should use `getEndpointManagement()`.
-     */
-    getLiveEndpoint(adapter: string, endpointId: string): unknown | null;
     /**
      * Narrow Host seam for Console social/group management. An empty object means
      * the Endpoint exists but implements no management operations; null means it
      * cannot be resolved.
      */
-    getEndpointManagement(adapter: string, endpointId: string): EndpointManagement | null;
+    getEndpointManagement(adapter: string, endpointKey: string): EndpointManagement | null;
 }