@zhin.js/core 1.3.5 → 1.4.0

package/lib/adapter.js

@@ -77,7 +77,11 @@ export class Adapter extends EventEmitter {
             logger: this.logger,
             getMaxConcurrentMessages: () => this.maxConcurrentMessages,
             getPendingMessages: () => this.#pendingMessages,
-            decrementPending: () => { this.#pendingMessages--; },
+            decrementPending: () => {
+                // stop() may zero the counter while in-flight receives still finish;
+                // never let the budget go negative.
+                this.#pendingMessages = Math.max(0, this.#pendingMessages - 1);
+            },
         });
     }
     /** 入站消息管线（替代 emit override 的隐式管线） */
@@ -291,6 +295,9 @@ export class Adapter extends EventEmitter {
         }
         // 无论是否有错误，始终完成清理
         this.endpoints.clear();
+        // Drop in-flight concurrency counter so a subsequent start() does not
+        // inherit a stale backpressure budget from the previous generation.
+        this.#pendingMessages = 0;
         // 从 adapters 数组中移除（可能因重复 start 出现多条同名，需全部删掉）
         const rootAdapters = this.plugin.root.adapters;
         for (let i = rootAdapters.length - 1; i >= 0; i--) {

package/lib/built/login-assist.d.ts

@@ -7,9 +7,12 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
 import type { Plugin } from '../plugin.js';
 export type LoginAssistType = 'qrcode' | 'sms' | 'slider' | 'device' | 'auth' | 'other';
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export declare const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS: number;
 export interface PendingLoginTaskPayload {
     /** 说明文案（如「请扫码登录」） */
     message?: string;
@@ -27,16 +30,30 @@ export interface PendingLoginTask {
     type: LoginAssistType;
     payload: PendingLoginTaskPayload;
     createdAt: number;
+    /** 到期时间戳（ms）；无超时则为 undefined */
+    expiresAt?: number;
+}
+export interface WaitForInputOptions {
+    /**
+     * 超时毫秒。默认 {@link DEFAULT_LOGIN_ASSIST_TIMEOUT_MS}。
+     * 传 `0` / `Infinity` / 负数表示不超时（仅测试或显式长驻场景）。
+     */
+    timeoutMs?: number;
 }
 export declare class LoginAssist {
     private readonly plugin;
     private readonly pending;
     private idSeq;
-    constructor(plugin: Plugin);
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    private readonly defaultTimeoutMs;
+    constructor(plugin: Plugin, options?: {
+        defaultTimeoutMs?: number;
+    });
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload): Promise<string | Record<string, unknown>>;
+    waitForInput(adapter: string, endpointId: string, type: LoginAssistType, payload?: PendingLoginTaskPayload, options?: WaitForInputOptions): Promise<string | Record<string, unknown>>;
     /**
      * 消费者：提交结果，对应 waitForInput 的 Promise 会 resolve。
      */

package/lib/built/login-assist.js

@@ -7,7 +7,10 @@
  *
  * 事件：
  *   endpoint.login.pending — 有新待办时触发，payload: PendingLoginTask
+ *   endpoint.login.expired — 超时自动取消时触发，payload: PendingLoginTask
  */
+/** 默认 5 分钟；扫码/滑块长期挂起会泄漏 Promise 与 Map 条目 */
+export const DEFAULT_LOGIN_ASSIST_TIMEOUT_MS = 5 * 60 * 1000;
 // ============================================================================
 // LoginAssist 服务
 // ============================================================================
@@ -15,24 +18,48 @@ export class LoginAssist {
     plugin;
     pending = new Map();
     idSeq = 0;
-    constructor(plugin) {
+    /** 构造时默认超时；可被 waitForInput options 覆盖 */
+    defaultTimeoutMs;
+    constructor(plugin, options) {
         this.plugin = plugin;
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_LOGIN_ASSIST_TIMEOUT_MS;
     }
     /**
      * 生产者：等待用户输入后 resolve。会发出 endpoint.login.pending 事件，未消费前可被 listPending 拉取（刷新后可继续消费）。
+     * 超时后 reject 并 emit `endpoint.login.expired`。
      */
-    waitForInput(adapter, endpointId, type, payload = {}) {
+    waitForInput(adapter, endpointId, type, payload = {}, options) {
         const id = `login-${Date.now()}-${++this.idSeq}`;
+        const timeoutMs = resolveTimeoutMs(options?.timeoutMs, this.defaultTimeoutMs);
+        const createdAt = Date.now();
         const task = {
             id,
             adapter,
             endpointId,
             type,
             payload: { message: payload.message ?? '', ...payload },
-            createdAt: Date.now(),
+            createdAt,
+            ...(timeoutMs != null ? { expiresAt: createdAt + timeoutMs } : {}),
         };
         const promise = new Promise((resolve, reject) => {
-            this.pending.set(id, { task, resolve, reject });
+            const entry = { task, resolve, reject };
+            if (timeoutMs != null) {
+                entry.timer = setTimeout(() => {
+                    if (!this.pending.has(id))
+                        return;
+                    this.pending.delete(id);
+                    try {
+                        this.plugin.emit('endpoint.login.expired', task);
+                    }
+                    catch {
+                        /* observer failure must not leave the producer hanging forever */
+                    }
+                    reject(new Error(`LoginAssist task timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // Node: 不阻止进程退出
+                entry.timer.unref?.();
+            }
+            this.pending.set(id, entry);
             this.plugin.emit('endpoint.login.pending', task);
         });
         return promise;
@@ -45,6 +72,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.resolve(value);
         return true;
     }
@@ -56,6 +85,8 @@ export class LoginAssist {
         if (!entry)
             return false;
         this.pending.delete(id);
+        if (entry.timer)
+            clearTimeout(entry.timer);
         entry.reject(new Error(reason));
         return true;
     }
@@ -67,8 +98,16 @@ export class LoginAssist {
     }
     dispose() {
         for (const [, entry] of this.pending) {
+            if (entry.timer)
+                clearTimeout(entry.timer);
             entry.reject(new Error('LoginAssist disposed'));
         }
         this.pending.clear();
     }
 }
+function resolveTimeoutMs(explicit, fallback) {
+    const raw = explicit === undefined ? fallback : explicit;
+    if (!Number.isFinite(raw) || raw <= 0)
+        return undefined;
+    return raw;
+}

package/lib/built/segment-contract/index.d.ts

@@ -1,6 +1,7 @@
 export type { Segment, SegmentBase, MediaRef, TextSegment, MentionSegment, ImageSegment, ReplySegment, ForwardSegment, FaceSegment, DiceSegment, RpsSegment, } from './types.js';
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
 export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
 export { createImageSegment } from './image.js';

package/lib/built/segment-contract/index.js

@@ -1,5 +1,6 @@
 export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
 export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
 export { segmentsForImDelivery } from './delivery.js';
 export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
 export { createImageSegment } from './image.js';

package/lib/built/segment-contract/json-schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+type JsonSchemaObject = Record<string, unknown>;
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export declare const mediaRefJsonSchema: JsonSchemaObject;
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export declare const STRICT_OUTBOUND_SEGMENT_TYPES: readonly ["text", "mention", "image", "reply", "forward", "face", "dice", "rps"];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export declare const outboundSegmentJsonSchema: JsonSchemaObject;
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export declare const aiOutboundJsonSchema: JsonSchemaObject;
+export {};

package/lib/built/segment-contract/json-schema.js

@@ -0,0 +1,128 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+const platformJsonSchema = {
+    type: 'object',
+    additionalProperties: true,
+    description: '平台专有字段（一般无需输出）',
+};
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export const mediaRefJsonSchema = {
+    type: 'object',
+    properties: {
+        kind: {
+            type: 'string',
+            enum: ['url', 'path', 'base64'],
+            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据',
+        },
+        value: { type: 'string', description: '媒体内容：URL / 文件路径 / 纯 base64' },
+        mime_type: { type: 'string', description: '如 image/png、audio/mpeg' },
+    },
+    required: ['kind', 'value'],
+    additionalProperties: false,
+};
+function strictBranch(type, data) {
+    return {
+        type: 'object',
+        properties: {
+            type: { const: type },
+            data,
+            platform: platformJsonSchema,
+        },
+        required: ['type', 'data'],
+        additionalProperties: false,
+    };
+}
+function dataObject(properties, required) {
+    return { type: 'object', properties, required: [...required], additionalProperties: false };
+}
+/** 宽松分支：未纳入严格契约的段类型，仅约束顶层形状（与 isCanonicalSegment 宽松路径一致） */
+const looseBranch = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            enum: ['video', 'audio', 'voice', 'record', 'file', 'link', 'markdown', 'html', 'keyboard', 'action'],
+        },
+        data: { type: 'object' },
+        platform: platformJsonSchema,
+    },
+    required: ['type', 'data'],
+    additionalProperties: false,
+};
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export const STRICT_OUTBOUND_SEGMENT_TYPES = [
+    'text', 'mention', 'image', 'reply', 'forward', 'face', 'dice', 'rps',
+];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export const outboundSegmentJsonSchema = {
+    description: 'zhin 消息段 {type, data, platform?}',
+    anyOf: [
+        strictBranch('text', dataObject({
+            text: { type: 'string', description: '文本内容' },
+        }, ['text'])),
+        strictBranch('mention', dataObject({
+            target: { type: 'string', description: '被 @ 用户的平台 id' },
+            name: { type: 'string' },
+        }, ['target'])),
+        strictBranch('image', dataObject({
+            media: mediaRefJsonSchema,
+            alt: { type: 'string' },
+        }, ['media'])),
+        strictBranch('reply', dataObject({
+            message_id: { type: 'string', description: '被引用消息的平台消息 id' },
+        }, ['message_id'])),
+        strictBranch('forward', dataObject({
+            forward_id: { type: 'string' },
+            title: { type: 'string' },
+            messages: { type: 'array', items: { type: 'array' } },
+        }, ['forward_id'])),
+        strictBranch('face', dataObject({
+            id: { anyOf: [{ type: 'string' }, { type: 'number' }], description: '平台表情 id' },
+            name: { type: 'string' },
+        }, ['id'])),
+        strictBranch('dice', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        strictBranch('rps', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        looseBranch,
+    ],
+};
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export const aiOutboundJsonSchema = {
+    type: 'object',
+    properties: {
+        text: {
+            type: 'string',
+            description: '纯文本回复正文；与 segments 至少输出一项。使用 mentions 时必填',
+        },
+        mentions: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '要 @ 的会话成员引用（昵称或 id，由宿主解析为平台账号）；需配合 text 使用',
+        },
+        segments: {
+            type: 'array',
+            items: outboundSegmentJsonSchema,
+            description: 'zhin 消息段数组，如 [{type:"image",data:{media:{kind:"url",value:"https://…"}}},{type:"text",data:{text:"…"}}]',
+        },
+    },
+    additionalProperties: false,
+};

package/lib/endpoint.d.ts

@@ -1,12 +1,15 @@
 import type { Adapters, Adapter } from './adapter.js';
 import type { EndpointCapabilitiesConfig, FullEndpoint } from './endpoint-capabilities.js';
+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 { 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';
 /**
  * Endpoint 接口：全双工平台机器人（入站 + 出站）。
  * 纯入站 / 纯出站请实现 InboundEndpoint / OutboundEndpoint。
  */
-export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event>;
+export type Endpoint<Config extends object = object, Event extends object = object> = FullEndpoint<Config, Event> & EndpointWithManagement;
 export declare namespace Endpoint {
     type Config<K extends keyof Adapters = keyof Adapters> = Adapter.EndpointConfig<Adapter.InferEndpoint<Adapters[K]>> & EndpointCapabilitiesConfig & {
         context: K;

package/lib/endpoint.js

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

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

@@ -1,8 +1,30 @@
-import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { Scope, type CapabilityId, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+import { type EndpointManagement, type EndpointManagementCapability } from '@zhin.js/adapter';
 import { Message, type ChannelParent, type IncomingMessage, type MessageDispatchResult, type MessageGateway, type SendRequest } from './contracts.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 export declare const messageGatewayToken: import("@zhin.js/plugin-runtime").Token<MessageGateway>;
+/** Console 实时消息事件（SSE 推送源；content 仅为截断预览，不含完整原始段）。 */
+export interface RuntimeMessageEvent {
+    readonly direction: 'inbound' | 'outbound';
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    /** inbound：发送者 id。 */
+    readonly sender?: string;
+    /** outbound：发起方插件。 */
+    readonly requester?: PluginId;
+    /** inbound：从 target 前缀解析的场景（`group:xx` → `group`）。 */
+    readonly channelType?: string;
+    /** 预览文本，截断至 200 字。 */
+    readonly contentPreview: string;
+    readonly messageId?: string;
+    readonly timestamp: number;
+}
+export declare const messagePreviewLimit = 200;
 export interface ImRuntimeOptions {
+    /**
+     * 全局静态命令前缀（如 `'/'`）。缺省时按适配器实例 config 的
+     * `commandPrefix` 解析（`endpoints[i]` 可逐项覆盖），默认 `''` 无前缀。
+     */
     readonly commandPrefix?: string;
     readonly renderer?: OutboundRenderer;
 }
@@ -17,15 +39,22 @@ export declare class ImRuntime implements MessageGateway {
      */
     setUnmatchedHandler(handler: (message: Message, snapshot: RuntimeSnapshot, requester: PluginId) => Promise<boolean>): void;
     install(resources: Scope): void;
+    /**
+     * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
+     * 返回注销函数。listener 抛错不会阻断消息链路。
+     */
+    onMessage(listener: (event: RuntimeMessageEvent) => void): () => void;
     receive(input: IncomingMessage): Promise<MessageDispatchResult>;
     send(request: SendRequest): Promise<unknown>;
     /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
     listEndpoints(): readonly {
         readonly name: string;
         readonly adapter: string;
+        readonly owner: string;
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
         readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
     }[];
     getEndpoint(adapter: string, endpointId: string): {
         readonly name: string;
@@ -33,6 +62,7 @@ export declare class ImRuntime implements MessageGateway {
         readonly connected: boolean;
         readonly status: 'online' | 'offline';
         readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+        readonly managementCapabilities: readonly EndpointManagementCapability[];
     } | null;
     sendEndpointMessage(input: {
         readonly adapter: string;
@@ -65,6 +95,15 @@ export declare class ImRuntime implements MessageGateway {
         readonly endpointId: string;
         readonly messageId: string;
     }): Promise<void>;
-    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    /**
+     * 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;
 }

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

@@ -1,18 +1,22 @@
 import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
-import { adapterFeatureId, isAdapterIndex } from '@zhin.js/adapter';
+import { adapterFeatureId, isAdapterIndex, resolveEndpointManagement, } from '@zhin.js/adapter';
 import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
 import { Message, createOutboundEnvelope, } from './contracts.js';
-import { MessageDispatcher } from './message-dispatcher.js';
+import { defaultCommandPrefixResolver, MessageDispatcher } from './message-dispatcher.js';
 import { OutboundRenderer } from './outbound-renderer.js';
 import { normalizeOutboundPayload } from './outbound-segments.js';
 export const messageGatewayToken = createToken('zhin.im.message-gateway');
+export const messagePreviewLimit = 200;
 export class ImRuntime {
     #dispatcher;
     #renderer;
+    #messageListeners = new Set();
     #snapshots;
     #unmatchedHandler;
     constructor(options = {}) {
-        this.#dispatcher = new MessageDispatcher(options.commandPrefix);
+        this.#dispatcher = new MessageDispatcher(options.commandPrefix === undefined
+            ? defaultCommandPrefixResolver
+            : () => options.commandPrefix ?? '');
         this.#renderer = options.renderer ?? new OutboundRenderer();
     }
     attach(snapshots) {
@@ -32,6 +36,24 @@ export class ImRuntime {
     install(resources) {
         resources.provide(messageGatewayToken, this);
     }
+    /**
+     * 订阅消息事件（入站 dispatch 完成后 / 出站发送成功后回调）。
+     * 返回注销函数。listener 抛错不会阻断消息链路。
+     */
+    onMessage(listener) {
+        this.#messageListeners.add(listener);
+        return () => { this.#messageListeners.delete(listener); };
+    }
+    #emitMessage(event) {
+        for (const listener of this.#messageListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // listener 异常不得影响消息收发
+            }
+        }
+    }
     async receive(input) {
         const lease = this.#acquire();
         let active = true;
@@ -57,6 +79,18 @@ export class ImRuntime {
                     }
                 }
             }, 'inbound');
+            this.#emitMessage({
+                direction: 'inbound',
+                adapter: input.adapter,
+                target: input.target,
+                ...(input.sender !== undefined ? { sender: input.sender } : {}),
+                ...(channelTypeOf(input.target)
+                    ? { channelType: channelTypeOf(input.target) }
+                    : {}),
+                contentPreview: previewText(input.content),
+                ...(input.id !== undefined ? { messageId: input.id } : {}),
+                timestamp: Date.now(),
+            });
             return result;
         }
         finally {
@@ -82,9 +116,11 @@ export class ImRuntime {
                     name: row.name,
                     // adapter 列显示平台类型（owner 包名去 scope/adapter- 前缀），不是 slot localName
                     adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
+                    owner: row.owner,
                     connected: row.connected,
                     status: row.status,
                     phase: row.phase,
+                    managementCapabilities: row.managementCapabilities,
                 }));
             }
             finally {
@@ -106,12 +142,15 @@ export class ImRuntime {
                 const row = index.describe().find((item) => item.id === id);
                 if (!row)
                     return null;
+                // adapter 与 listEndpoints 对齐：平台类型（owner 包名去 scope/adapter- 前缀），
+                // 不是 live name（如 ICQQ uin）。此前误写 row.name 导致 endpoint.info 与 list 不一致。
                 return Object.freeze({
                     name: row.name,
-                    adapter: row.name,
+                    adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
                     connected: row.connected,
                     status: row.status,
                     phase: row.phase,
+                    managementCapabilities: row.managementCapabilities,
                 });
             }
             finally {
@@ -203,10 +242,24 @@ export class ImRuntime {
             return null;
         }
     }
-    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    /**
+     * Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。
+     * @deprecated Host callers should use `getEndpointManagement()`.
+     */
     getLiveEndpoint(adapter, endpointId) {
         return this.#liveEndpoint(adapter, endpointId);
     }
+    /**
+     * 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, endpointId) {
+        const endpoint = this.#liveEndpoint(adapter, endpointId);
+        if (!endpoint)
+            return null;
+        return resolveEndpointManagement(endpoint) ?? Object.freeze({});
+    }
     async #sendWithSnapshot(request, snapshot) {
         const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
         // 单段对象 / html 段在此归一为适配器可消费的 wire 段数组；
@@ -229,6 +282,14 @@ export class ImRuntime {
                 ...(request.parent ? { parent: request.parent } : {}),
             });
         }, 'outbound');
+        this.#emitMessage({
+            direction: 'outbound',
+            adapter: request.adapter,
+            target: request.target,
+            requester: request.requester,
+            contentPreview: previewText(envelope.payload),
+            timestamp: Date.now(),
+        });
         return result;
     }
     #acquire() {
@@ -297,3 +358,42 @@ function normalizeConsoleContent(content) {
         return content;
     return String(content);
 }
+/** target 前缀场景：`group:123` → `group`；无前缀返回 undefined。 */
+function channelTypeOf(target) {
+    const match = /^([a-z0-9-]+):/iu.exec(target);
+    return match?.[1];
+}
+/** 消息内容 → 预览文本（截断 200 字）；wire 段取 `data.text`，其余段记 `[type]`。 */
+function previewText(content) {
+    const text = flattenContent(content);
+    return text.length > messagePreviewLimit
+        ? `${text.slice(0, messagePreviewLimit)}…`
+        : text;
+}
+function flattenContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (content == null)
+        return '';
+    if (Array.isArray(content)) {
+        return content.map((item) => flattenContent(item)).join('');
+    }
+    if (typeof content === 'object') {
+        const record = content;
+        const data = record.data;
+        if (typeof record.type === 'string') {
+            if (data && typeof data.text === 'string')
+                return data.text;
+            return `[${record.type}]`;
+        }
+        if (typeof record.text === 'string')
+            return record.text;
+        try {
+            return JSON.stringify(content) ?? '';
+        }
+        catch {
+            return String(content);
+        }
+    }
+    return String(content);
+}

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

@@ -1,7 +1,17 @@
 import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { Message, MessageDispatchResult } from './contracts.js';
+/**
+ * 命令前缀解析器：返回该消息要求的命令前缀。
+ * `''` 表示无前缀（任意文本都尝试按命令匹配）。
+ */
+export type CommandPrefixResolver = (message: Message, snapshot: RuntimeSnapshot) => string;
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export declare const defaultCommandPrefixResolver: CommandPrefixResolver;
 export declare class MessageDispatcher {
-    private readonly prefix;
-    constructor(prefix?: string);
+    private readonly resolvePrefix;
+    constructor(resolvePrefix?: CommandPrefixResolver);
     dispatch(message: Message, snapshot: RuntimeSnapshot): Promise<MessageDispatchResult>;
 }

package/lib/plugin-runtime/im/message-dispatcher.js

@@ -1,15 +1,39 @@
 import { commandFeatureId, isCommandIndex } from '@zhin.js/command';
+function ownerOfMessage(message) {
+    return String(message.adapter).split('\0')[0];
+}
+/**
+ * 默认解析：读消息所属适配器实例 config 的 `commandPrefix`（默认 `''`）；
+ * 实例声明 `endpoints` 数组时，按消息 endpoint 名找 entry，`entry.commandPrefix` 覆盖顶层。
+ */
+export const defaultCommandPrefixResolver = (message, snapshot) => {
+    const config = snapshot.config.get(ownerOfMessage(message));
+    if (!config)
+        return '';
+    const endpointName = typeof message.metadata?.endpoint === 'string'
+        ? message.metadata.endpoint
+        : undefined;
+    if (endpointName && Array.isArray(config.endpoints)) {
+        const entry = config.endpoints.find((item) => !!item && typeof item === 'object'
+            && item.name === endpointName);
+        if (typeof entry?.commandPrefix === 'string')
+            return entry.commandPrefix;
+    }
+    return typeof config.commandPrefix === 'string' ? config.commandPrefix : '';
+};
 export class MessageDispatcher {
-    prefix;
-    constructor(prefix = '/') {
-        this.prefix = prefix;
-        if (!prefix)
-            throw new TypeError('Command prefix cannot be empty');
+    resolvePrefix;
+    constructor(resolvePrefix = defaultCommandPrefixResolver) {
+        this.resolvePrefix = resolvePrefix;
     }
     async dispatch(message, snapshot) {
-        if (!message.content.startsWith(this.prefix))
-            return Object.freeze({ matched: false });
-        const input = message.content.slice(this.prefix.length).trim();
+        const prefix = this.resolvePrefix(message, snapshot);
+        let input = message.content.trim();
+        if (prefix) {
+            if (!input.startsWith(prefix))
+                return Object.freeze({ matched: false });
+            input = input.slice(prefix.length).trim();
+        }
         if (!input)
             return Object.freeze({ matched: false });
         const commands = snapshot.projections.get(commandFeatureId);

package/lib/plugin.d.ts

@@ -180,6 +180,7 @@ export declare namespace Plugin {
         'message.send': [MessageSendPayload];
         "message.receive": [import('./message.js').Message];
         "endpoint.login.pending": [import('./built/login-assist.js').PendingLoginTask];
+        "endpoint.login.expired": [import('./built/login-assist.js').PendingLoginTask];
         'endpoint.connect': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];
         'endpoint.disconnect': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];
         'endpoint.error': [import('./built/endpoint-lifecycle.js').EndpointLifecyclePayload];

package/lib/tool-zod.d.ts

@@ -10,9 +10,24 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-import type { Tool } from './types.js';
+import type { Tool, ToolParametersSchema } from './types.js';
 import type { Message } from './message.js';
 type MaybePromise<T> = T | Promise<T>;
+export type ToolSchemaParseResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export declare function toolInputSchemaToParameters(schema: unknown): ToolParametersSchema;
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export declare function parseToolInputSchema<T>(schema: unknown, input: unknown): ToolSchemaParseResult<T>;
 export interface CreateToolFromZodOptions {
     tags?: string[];
     keywords?: string[];

package/lib/tool-zod.js

@@ -10,62 +10,151 @@
  *   const tool = createToolFromZod('my_tool', '描述', z.object({ id: z.string() }), async (args) => { ... });
  *   plugin.addTool(tool);
  */
-function zodFieldToJsonSchema(z) {
-    if (!z || !z._def)
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function getShape(schema) {
+    const shape = schema?.shape;
+    if (typeof shape === 'function') {
+        const value = shape();
+        return isRecord(value) ? value : undefined;
+    }
+    return isRecord(shape) ? shape : undefined;
+}
+function acceptsUndefined(schema) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse === 'function') {
+        try {
+            return candidate.safeParse(undefined).success;
+        }
+        catch {
+            // Fall through to structural compatibility for non-Zod lookalikes.
+        }
+    }
+    const def = candidate?._def;
+    const kind = def?.typeName ?? def?.type;
+    return kind === 'ZodOptional'
+        || kind === 'ZodDefault'
+        || kind === 'optional'
+        || kind === 'default';
+}
+function requiredFromShape(schema, fallback) {
+    const shape = getShape(schema);
+    if (!shape)
+        return fallback?.length ? [...fallback] : undefined;
+    const required = Object.entries(shape)
+        .filter(([, field]) => !acceptsUndefined(field))
+        .map(([key]) => key);
+    return required.length ? required : undefined;
+}
+function descriptionOf(schema, def) {
+    const description = schema?.description ?? def.description;
+    return typeof description === 'string' ? description : undefined;
+}
+function zodFieldToJsonSchema(schema) {
+    const candidate = schema;
+    const def = candidate?._def;
+    if (!isRecord(def))
         return { type: 'string' };
-    const def = z._def;
-    const typeName = def.typeName;
-    if (typeName === 'ZodOptional' || typeName === 'ZodDefault') {
-        const inner = def.innerType ?? def.type;
-        return zodFieldToJsonSchema(inner);
+    const kind = def.typeName ?? def.type;
+    if (kind === 'ZodOptional' || kind === 'ZodDefault' || kind === 'optional' || kind === 'default') {
+        return zodFieldToJsonSchema(def.innerType ?? def.type);
     }
-    if (typeName === 'ZodString') {
-        const out = { type: 'string' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    const description = descriptionOf(schema, def);
+    const withDescription = (type) => description
+        ? { type, description }
+        : { type };
+    if (kind === 'ZodString' || kind === 'string')
+        return withDescription('string');
+    if (kind === 'ZodNumber' || kind === 'number')
+        return withDescription('number');
+    if (kind === 'ZodBoolean' || kind === 'boolean')
+        return withDescription('boolean');
+    if (kind === 'ZodEnum' || kind === 'enum') {
+        const values = Array.isArray(def.values)
+            ? def.values
+            : isRecord(def.entries)
+                ? Object.values(def.entries)
+                : [];
+        return { ...withDescription('string'), enum: values };
     }
-    if (typeName === 'ZodNumber') {
-        const out = { type: 'number' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodArray' || kind === 'array') {
+        return {
+            ...withDescription('array'),
+            items: zodFieldToJsonSchema(def.element ?? def.type),
+        };
     }
-    if (typeName === 'ZodBoolean') {
-        const out = { type: 'boolean' };
-        if (def.description)
-            out.description = def.description;
-        return out;
+    if (kind === 'ZodObject' || kind === 'object') {
+        return toolInputSchemaToParameters(schema);
     }
-    if (typeName === 'ZodEnum') {
-        return { type: 'string', enum: def.values };
+    return withDescription('string');
+}
+function isJsonObjectSchema(schema) {
+    if (!isRecord(schema) || schema.type !== 'object')
+        return false;
+    return typeof schema.safeParse !== 'function';
+}
+function fromNativeJsonSchema(schema) {
+    const candidate = schema;
+    if (typeof candidate?.toJSONSchema !== 'function')
+        return undefined;
+    try {
+        const converted = candidate.toJSONSchema();
+        if (!isRecord(converted) || converted.type !== 'object')
+            return undefined;
+        return {
+            ...converted,
+            type: 'object',
+            properties: isRecord(converted.properties)
+                ? converted.properties
+                : {},
+            required: requiredFromShape(schema, Array.isArray(converted.required)
+                ? converted.required.filter((key) => typeof key === 'string')
+                : undefined),
+        };
     }
-    if (typeName === 'ZodArray') {
-        return { type: 'array', items: zodFieldToJsonSchema(def.type ?? def.element) };
+    catch {
+        return undefined;
     }
-    return { type: 'string' };
 }
-function zodToJsonSchema(schema) {
-    const result = {
+/**
+ * Normalize a JSON Schema or Zod object schema into the canonical Core tool
+ * parameter schema. Zod remains an optional peer: this adapter uses only its
+ * public instance methods and retains a structural fallback for Zod 3.
+ */
+export function toolInputSchemaToParameters(schema) {
+    if (isJsonObjectSchema(schema))
+        return schema;
+    const native = fromNativeJsonSchema(schema);
+    if (native)
+        return native;
+    const shape = getShape(schema);
+    const properties = {};
+    if (shape) {
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodFieldToJsonSchema(value);
+        }
+    }
+    return {
         type: 'object',
-        properties: {},
-        required: [],
+        properties: properties,
+        required: requiredFromShape(schema),
     };
-    if (!schema || !schema.shape)
-        return result;
-    const shape = schema.shape;
-    const properties = result.properties;
-    const required = [];
-    for (const [key, value] of Object.entries(shape)) {
-        const zodValue = value;
-        properties[key] = zodFieldToJsonSchema(zodValue);
-        const typeName = zodValue?._def?.typeName;
-        if (typeName !== 'ZodOptional' && typeName !== 'ZodDefault') {
-            required.push(key);
-        }
+}
+/** Validate input with a Zod-like schema, or pass it through for JSON Schema. */
+export function parseToolInputSchema(schema, input) {
+    const candidate = schema;
+    if (typeof candidate?.safeParse !== 'function') {
+        return { ok: true, data: input };
     }
-    result.required = required.length > 0 ? required : undefined;
-    return result;
+    const parsed = candidate.safeParse(input);
+    if (parsed.success)
+        return { ok: true, data: parsed.data };
+    const issues = parsed.error?.issues ?? parsed.error?.errors ?? [];
+    const error = issues
+        .map((issue) => `${(issue.path ?? []).join('.') || 'root'}: ${issue.message ?? 'invalid'}`)
+        .join('; ');
+    return { ok: false, error: error || 'Invalid arguments' };
 }
 /**
  * 从 Zod 模式创建 Tool，便于类型安全与校验。
@@ -75,17 +164,15 @@ export function createToolFromZod(name, description, schema, execute, options) {
     if (!schema?.safeParse) {
         throw new Error('createToolFromZod: schema must be a Zod object schema (e.g. z.object({ ... })). Install zod: pnpm add zod');
     }
-    const parameters = zodToJsonSchema(schema);
+    const parameters = toolInputSchemaToParameters(schema);
     return {
         name,
         description,
         parameters,
         execute: async (args, message) => {
-            const parsed = schema.safeParse(args);
-            if (!parsed.success) {
-                const msg = parsed.error.errors?.map((e) => `${e.path?.join('.') ?? 'root'}: ${e instanceof Error ? e.message : String(e)}`).join('; ') ?? 'Invalid arguments';
-                return `Error: ${msg}`;
-            }
+            const parsed = parseToolInputSchema(schema, args);
+            if (!parsed.ok)
+                return `Error: ${parsed.error}`;
             return execute(parsed.data, message);
         },
         tags: options?.tags,

package/lib/utils.d.ts

@@ -17,6 +17,9 @@ import type { ButtonData, KeyboardFallback, KeyboardSegmentData } from "./built/
 import type { MediaRef } from "./built/segment-contract/types.js";
 /**
  * 组合中间件,洋葱模型
+ *
+ * 空中间件列表时必须仍调用 `next`——入站管线把 MessageDispatcher
+ * 作为 terminal next 传入；吞掉 next 会导致命令/AI 永远不跑。
  */
 export declare function compose<P extends RegisteredAdapter = RegisteredAdapter>(middlewares: MessageMiddleware<P>[]): (message: Message<AdapterMessage<P>>, next?: () => Promise<void>) => Promise<void>;
 export declare function segment<T extends object>(type: string, data: T): {

package/lib/utils.js

@@ -15,12 +15,15 @@ import { KeyboardSegment } from "./built/interactive-segments/keyboard-segment.j
 import { ButtonSpec, normalizeKeyboardRows } from "./built/interactive-segments/button-spec.js";
 /**
  * 组合中间件,洋葱模型
+ *
+ * 空中间件列表时必须仍调用 `next`——入站管线把 MessageDispatcher
+ * 作为 terminal next 传入；吞掉 next 会导致命令/AI 永远不跑。
  */
 export function compose(middlewares) {
-    if (middlewares.length === 0) {
-        return () => Promise.resolve();
-    }
     return function (message, next = () => Promise.resolve()) {
+        if (middlewares.length === 0) {
+            return next();
+        }
         let index = -1;
         const dispatch = async (i = 0) => {
             if (i <= index) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -50,14 +50,14 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.0",
     "yaml": "^2.9.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/command": "1.0.1",
-    "@zhin.js/component": "1.0.1",
+    "@zhin.js/adapter": "1.1.0",
+    "@zhin.js/command": "1.0.2",
+    "@zhin.js/component": "1.0.2",
+    "@zhin.js/database": "1.0.77",
     "@zhin.js/kernel": "1.0.4",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/middleware": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "@zhin.js/database": "1.0.77",
+    "@zhin.js/middleware": "1.0.2",
+    "@zhin.js/plugin-runtime": "1.1.0",
     "@zhin.js/schema": "1.0.71"
   },
   "peerDependencies": {
@@ -71,6 +71,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "@types/qrcode": "^1.5.5",
+    "ajv": "8.18.0",
     "typescript": "^6.0.3",
     "@zhin.js/ai": "1.4.5"
   },