@zhin.js/core 1.3.4 → 1.3.5

package/README.md

@@ -1,5 +1,17 @@
 # @zhin.js/core
 
+## Plugin Runtime 子路径
+
+新的 owner-aware IM 能力已经并入 Core，作为 Plugin Runtime 的正式领域接口：
+
+- `@zhin.js/core/runtime`
+
+`@zhin.js/adapter`、`@zhin.js/command`、`@zhin.js/component` 与
+`@zhin.js/middleware` 提供纯 definition、约定发现 provider 和 generation projection；
+Core Runtime 只消费它们发布的 snapshot。
+旧根入口的 `addCommand`、`addComponent`、`addMiddleware` 暂时作为作者兼容接口保留，后续
+只向 RuntimeSnapshot 投影，不再维护第二套运行时权威。
+
 Zhin.js **IM/多通道运行时**包：Plugin、Adapter、**Endpoint**、MessageDispatcher 与统一出站链。**AI 编排（ZhinAgent、工具安全、MCP）在 [`@zhin.js/agent`](../agent/README.md)**；本包仅 selective re-export `@zhin.js/ai` 的 Provider / Agent 原语供插件直接使用。
 
 领域词汇见 [CONTEXT.md](./CONTEXT.md)；入站/出站流程见 [消息如何流转](../../docs/essentials/message-flow.md)。

package/lib/built/authorization.js

@@ -1,6 +1,6 @@
 import { mergeAITriggerConfig, resolveSenderRoles, } from './ai-trigger.js';
-import { formatCompact, Logger } from '@zhin.js/logger';
-const logger = new Logger(null, 'Authorization');
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('Authorization');
 function findEndpointEntryFromConfig(config, adapter, endpointId) {
     const endpoints = config.endpoints;
     if (!Array.isArray(endpoints))

package/lib/built/platform-permit.js

@@ -1,18 +1,25 @@
 import { parsePlatformPermitName, isPlatformPermit } from './permit-parse.js';
 const checkers = new Map();
-const registeredDefaultSceneCheckers = new Set();
+const defaultSceneRegistrations = new Map();
 export function registerPlatformPermitChecker(adapter, checker) {
     const key = String(adapter);
-    checkers.set(key, checker);
+    const registrations = checkers.get(key) ?? [];
+    registrations.push(checker);
+    checkers.set(key, registrations);
     return () => {
-        if (checkers.get(key) === checker) {
+        const current = checkers.get(key);
+        if (!current)
+            return;
+        const index = current.lastIndexOf(checker);
+        if (index >= 0)
+            current.splice(index, 1);
+        if (current.length === 0)
             checkers.delete(key);
-        }
     };
 }
 export function clearPlatformPermitCheckers() {
     checkers.clear();
-    registeredDefaultSceneCheckers.clear();
+    defaultSceneRegistrations.clear();
 }
 export function checkPlatformPermit(name, message) {
     const parsed = parsePlatformPermitName(name);
@@ -20,7 +27,8 @@ export function checkPlatformPermit(name, message) {
         return false;
     if (String(message.$adapter) !== parsed.adapter)
         return false;
-    const checker = checkers.get(parsed.adapter);
+    const registrations = checkers.get(parsed.adapter);
+    const checker = registrations?.[registrations.length - 1];
     if (!checker)
         return false;
     return checker(parsed.perm, message);
@@ -58,9 +66,26 @@ export function createSceneRolePlatformChecker() {
 /** 为适配器注册默认场景治理 platform checker（幂等） */
 export function registerDefaultScenePlatformPermitChecker(adapter) {
     const key = String(adapter);
-    if (registeredDefaultSceneCheckers.has(key)) {
-        return () => { };
+    const existing = defaultSceneRegistrations.get(key);
+    if (existing) {
+        existing.references += 1;
+        return () => releaseDefaultSceneChecker(key, existing);
     }
-    registeredDefaultSceneCheckers.add(key);
-    return registerPlatformPermitChecker(key, createSceneRolePlatformChecker());
+    const checker = createSceneRolePlatformChecker();
+    const registration = {
+        checker,
+        dispose: registerPlatformPermitChecker(key, checker),
+        references: 1,
+    };
+    defaultSceneRegistrations.set(key, registration);
+    return () => releaseDefaultSceneChecker(key, registration);
+}
+function releaseDefaultSceneChecker(key, registration) {
+    if (defaultSceneRegistrations.get(key) !== registration)
+        return;
+    registration.references -= 1;
+    if (registration.references > 0)
+        return;
+    defaultSceneRegistrations.delete(key);
+    registration.dispose();
 }

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

@@ -0,0 +1,71 @@
+import type { CapabilityId, PluginId } from '@zhin.js/plugin-runtime';
+declare const componentCallBrand: "zhin.component-call/1";
+declare const rawContentBrand: "zhin.raw-content/1";
+export interface ComponentCall<TProps = unknown> {
+    readonly $content: typeof componentCallBrand;
+    readonly name: string;
+    readonly props: TProps;
+}
+export interface RawContent<TPayload = unknown> {
+    readonly $content: typeof rawContentBrand;
+    readonly payload: TPayload;
+}
+export type SendContent = string | ComponentCall | RawContent | readonly SendContent[];
+export declare function component<TProps>(name: string, props: TProps): ComponentCall<TProps>;
+export declare function raw<TPayload>(payload: TPayload): RawContent<TPayload>;
+export declare function isComponentCall(value: SendContent): value is ComponentCall;
+export declare function isRawContent(value: SendContent): value is RawContent;
+export interface IncomingMessage {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly id?: string;
+    readonly sender?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface SendRequest {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    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;
+}
+export interface OutboundEnvelope {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly requester: PluginId;
+    readonly generation: number;
+    readonly payload: unknown;
+    readonly parent?: ChannelParent;
+    replace(payload: unknown): void;
+}
+export interface MessageGateway {
+    receive(input: IncomingMessage): Promise<MessageDispatchResult>;
+    send(request: SendRequest): Promise<unknown>;
+}
+export interface MessageDispatchResult {
+    readonly matched: boolean;
+    readonly command?: string;
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
+export declare class Message {
+    readonly adapter: CapabilityId;
+    readonly target: string;
+    readonly content: string;
+    readonly generation: number;
+    readonly id?: string | undefined;
+    readonly sender?: string | undefined;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    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 $reply: (content: SendContent) => Promise<unknown>;
+    readonly $replyFrom: (requester: PluginId, content: SendContent) => Promise<unknown>;
+}
+export declare function createOutboundEnvelope(request: Omit<OutboundEnvelope, 'payload' | 'replace'>, initialPayload: unknown): OutboundEnvelope;
+export {};

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

@@ -0,0 +1,55 @@
+const componentCallBrand = 'zhin.component-call/1';
+const rawContentBrand = 'zhin.raw-content/1';
+export function component(name, props) {
+    if (!name.trim())
+        throw new TypeError('Component name cannot be empty');
+    return Object.freeze({ $content: componentCallBrand, name, props });
+}
+export function raw(payload) {
+    return Object.freeze({ $content: rawContentBrand, payload });
+}
+export function isComponentCall(value) {
+    return !Array.isArray(value)
+        && typeof value === 'object'
+        && value !== null
+        && '$content' in value
+        && value.$content === componentCallBrand;
+}
+export function isRawContent(value) {
+    return !Array.isArray(value)
+        && typeof value === 'object'
+        && value !== null
+        && '$content' in value
+        && value.$content === rawContentBrand;
+}
+export class Message {
+    adapter;
+    target;
+    content;
+    generation;
+    id;
+    sender;
+    metadata;
+    constructor(adapter, target, content, generation, reply, id, sender, metadata = Object.freeze({})) {
+        this.adapter = adapter;
+        this.target = target;
+        this.content = content;
+        this.generation = generation;
+        this.id = id;
+        this.sender = sender;
+        this.metadata = metadata;
+        this.$reply = (content) => reply(content);
+        this.$replyFrom = (requester, content) => reply(content, requester);
+        Object.freeze(this);
+    }
+    $reply;
+    $replyFrom;
+}
+export function createOutboundEnvelope(request, initialPayload) {
+    let payload = initialPayload;
+    return Object.freeze({
+        ...request,
+        get payload() { return payload; },
+        replace(next) { payload = next; },
+    });
+}

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

@@ -0,0 +1,70 @@
+import { Scope, type PluginId, type RuntimeSnapshot, type SnapshotStore } from '@zhin.js/plugin-runtime';
+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>;
+export interface ImRuntimeOptions {
+    readonly commandPrefix?: string;
+    readonly renderer?: OutboundRenderer;
+}
+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;
+    install(resources: Scope): 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 connected: boolean;
+        readonly status: 'online' | 'offline';
+        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+    }[];
+    getEndpoint(adapter: string, endpointId: string): {
+        readonly name: string;
+        readonly adapter: string;
+        readonly connected: boolean;
+        readonly status: 'online' | 'offline';
+        readonly phase: 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+    } | null;
+    sendEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly channelId: string;
+        readonly channelType: string;
+        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 messageId: string;
+        readonly emoji: string;
+        readonly sceneType?: string;
+        readonly channelId?: string;
+    }): Promise<string | null>;
+    removeEndpointReaction(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly messageId: string;
+        readonly reactionId: string;
+    }): Promise<void>;
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    recallEndpointMessage(input: {
+        readonly adapter: string;
+        readonly endpointId: string;
+        readonly messageId: string;
+    }): Promise<void>;
+    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    getLiveEndpoint(adapter: string, endpointId: string): unknown | null;
+}

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

@@ -0,0 +1,299 @@
+import { createToken, htmlRendererToken, } from '@zhin.js/plugin-runtime';
+import { adapterFeatureId, isAdapterIndex } from '@zhin.js/adapter';
+import { isMiddlewareIndex, middlewareFeatureId } from '@zhin.js/middleware';
+import { Message, createOutboundEnvelope, } from './contracts.js';
+import { 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 class ImRuntime {
+    #dispatcher;
+    #renderer;
+    #snapshots;
+    #unmatchedHandler;
+    constructor(options = {}) {
+        this.#dispatcher = new MessageDispatcher(options.commandPrefix);
+        this.#renderer = options.renderer ?? new OutboundRenderer();
+    }
+    attach(snapshots) {
+        if (this.#snapshots && this.#snapshots !== snapshots) {
+            throw new Error('ImRuntime is already attached to another Root');
+        }
+        this.#snapshots = snapshots;
+    }
+    /**
+     * 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) {
+        this.#unmatchedHandler = handler;
+    }
+    install(resources) {
+        resources.provide(messageGatewayToken, this);
+    }
+    async receive(input) {
+        const lease = this.#acquire();
+        let active = true;
+        try {
+            const requester = requireAdapters(lease.value).owner(input.adapter);
+            const message = new Message(input.adapter, input.target, input.content, lease.value.generation, (content, replyRequester = requester) => {
+                if (!active)
+                    throw new Error('Message reply scope has ended');
+                return this.#sendWithSnapshot({
+                    adapter: input.adapter,
+                    target: input.target,
+                    requester: replyRequester,
+                    content,
+                }, lease.value);
+            }, input.id, input.sender, Object.freeze({ ...input.metadata }));
+            let result = Object.freeze({ matched: false });
+            await runMiddleware(lease.value, message, async () => {
+                result = await this.#dispatcher.dispatch(message, lease.value);
+                if (!result.matched && this.#unmatchedHandler) {
+                    const handled = await this.#unmatchedHandler(message, lease.value, requester);
+                    if (handled) {
+                        result = Object.freeze({ matched: true, command: 'ai', owner: requester });
+                    }
+                }
+            }, 'inbound');
+            return result;
+        }
+        finally {
+            active = false;
+            lease.release();
+        }
+    }
+    async send(request) {
+        const lease = this.#acquire();
+        try {
+            return await this.#sendWithSnapshot(request, lease.value);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    /** Console `endpoint.list` — empty until Adapter Feature projection is ready. */
+    listEndpoints() {
+        try {
+            const lease = this.#acquire();
+            try {
+                return requireAdapters(lease.value).describe().map((row) => Object.freeze({
+                    name: row.name,
+                    // adapter 列显示平台类型（owner 包名去 scope/adapter- 前缀），不是 slot localName
+                    adapter: adapterTypeName(lease.value.tree.get(row.owner)?.packageName) ?? row.name,
+                    connected: row.connected,
+                    status: row.status,
+                    phase: row.phase,
+                }));
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return Object.freeze([]);
+        }
+    }
+    getEndpoint(adapter, endpointId) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const index = requireAdapters(lease.value);
+                const id = index.resolve(adapter, endpointId);
+                if (!id)
+                    return null;
+                const row = index.describe().find((item) => item.id === id);
+                if (!row)
+                    return null;
+                return Object.freeze({
+                    name: row.name,
+                    adapter: row.name,
+                    connected: row.connected,
+                    status: row.status,
+                    phase: row.phase,
+                });
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    async sendEndpointMessage(input) {
+        const lease = this.#acquire();
+        try {
+            const index = requireAdapters(lease.value);
+            const capabilityId = index.resolve(input.adapter, input.endpointId);
+            if (!capabilityId)
+                throw new Error('endpoint not found');
+            const target = composeSendTarget(input.channelType, input.channelId);
+            const content = normalizeConsoleContent(input.content);
+            const result = await this.#sendWithSnapshot({
+                adapter: capabilityId,
+                target,
+                requester: index.owner(capabilityId),
+                content,
+                ...(input.parent ? { parent: input.parent } : {}),
+            }, lease.value);
+            return { messageId: result == null ? '' : String(result) };
+        }
+        finally {
+            lease.release();
+        }
+    }
+    /** Activity-feedback: add a message reaction when the live Endpoint supports it. */
+    async addEndpointReaction(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return null;
+        if (typeof endpoint.addReaction === 'function') {
+            return endpoint.addReaction(input.messageId, input.emoji, {
+                sceneType: input.sceneType,
+                channelId: input.channelId,
+            });
+        }
+        if (typeof endpoint.$addReaction === 'function') {
+            return endpoint.$addReaction(input.messageId, input.emoji, {
+                sceneType: input.sceneType,
+                channelId: input.channelId,
+            });
+        }
+        return null;
+    }
+    async removeEndpointReaction(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return;
+        if (typeof endpoint.removeReaction === 'function') {
+            await endpoint.removeReaction(input.messageId, input.reactionId);
+            return;
+        }
+        if (typeof endpoint.$removeReaction === 'function') {
+            await endpoint.$removeReaction(input.messageId, input.reactionId);
+        }
+    }
+    /** Activity-feedback autoRemove: recall a previously sent status message. */
+    async recallEndpointMessage(input) {
+        const endpoint = this.#liveEndpoint(input.adapter, input.endpointId);
+        if (!endpoint)
+            return;
+        if (typeof endpoint.recallMessage === 'function') {
+            await endpoint.recallMessage(input.messageId);
+            return;
+        }
+        if (typeof endpoint.$recallMessage === 'function') {
+            await endpoint.$recallMessage(input.messageId);
+        }
+    }
+    #liveEndpoint(adapter, endpointId) {
+        try {
+            const lease = this.#acquire();
+            try {
+                const endpoint = requireAdapters(lease.value).instance(adapter, endpointId);
+                return endpoint ?? null;
+            }
+            finally {
+                lease.release();
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Console endpoint 社交/群管 RPC：解析 live Endpoint 实例（无则 null）。 */
+    getLiveEndpoint(adapter, endpointId) {
+        return this.#liveEndpoint(adapter, endpointId);
+    }
+    async #sendWithSnapshot(request, snapshot) {
+        const rendered = await this.#renderer.render(request.content, request.requester, snapshot);
+        // 单段对象 / html 段在此归一为适配器可消费的 wire 段数组；
+        // sandbox 适配器（控制台 UI）直接消费 html 段，跳过规范化。
+        const payload = isDirectHtmlConsumer(snapshot, request.adapter)
+            ? rendered
+            : await normalizeOutboundPayload(rendered, resolveHtmlRenderer(snapshot));
+        const envelope = createOutboundEnvelope({
+            adapter: request.adapter,
+            target: request.target,
+            requester: request.requester,
+            generation: snapshot.generation,
+            ...(request.parent ? { parent: request.parent } : {}),
+        }, payload);
+        let result;
+        await runMiddleware(snapshot, envelope, async () => {
+            result = await requireAdapters(snapshot).send(request.adapter, {
+                target: request.target,
+                payload: envelope.payload,
+                ...(request.parent ? { parent: request.parent } : {}),
+            });
+        }, 'outbound');
+        return result;
+    }
+    #acquire() {
+        if (!this.#snapshots)
+            throw new Error('ImRuntime is not attached to a Root');
+        return this.#snapshots.acquire();
+    }
+}
+function requireAdapters(snapshot) {
+    const projection = snapshot.projections.get(adapterFeatureId);
+    if (!isAdapterIndex(projection)) {
+        throw new Error('Adapter Feature projection is not installed');
+    }
+    return projection;
+}
+/** Root resources 上的可选 html-renderer Host（未安装时降级为文本）。 */
+function resolveHtmlRenderer(snapshot) {
+    const host = snapshot.resources.get(snapshot.root)?.get(htmlRendererToken.id);
+    return host && typeof host.render === 'function'
+        ? host
+        : undefined;
+}
+/**
+ * Sandbox（控制台 UI）按设计直接消费 html 段，不做 html→image/text 规范化。
+ * 通过 adapter 能力 slot 的 owner 包名判断平台类型。
+ */
+function isDirectHtmlConsumer(snapshot, adapter) {
+    const owner = snapshot.capabilities.get(adapter)?.owner;
+    return adapterTypeName(snapshot.tree.get(owner)?.packageName) === 'sandbox';
+}
+/**
+ * Build Adapter send target. If channelId already carries a scene prefix
+ * (`private:uid` / `group:gid`), do not double-prefix.
+ */
+function composeSendTarget(channelType, channelId) {
+    const id = channelId.trim();
+    if (!id)
+        return channelType || '';
+    if (/^(private|group|channel|direct|c2c|temp):/iu.test(id))
+        return id;
+    return channelType ? `${channelType}:${id}` : id;
+}
+/** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
+function adapterTypeName(packageName) {
+    if (!packageName)
+        return undefined;
+    return packageName.replace(/^@[^/]+\/adapter-/, '');
+}
+function middleware(snapshot) {
+    const projection = snapshot.projections.get(middlewareFeatureId);
+    return isMiddlewareIndex(projection) ? projection : undefined;
+}
+async function runMiddleware(snapshot, input, terminal, target) {
+    const index = middleware(snapshot);
+    if (index)
+        await index.run(input, terminal, target);
+    else
+        await terminal();
+}
+function normalizeConsoleContent(content) {
+    if (typeof content === 'string')
+        return content;
+    // Array content passes through untouched, matching the legacy console RPC
+    // contract (element arrays must not be stringified to '[object Object]').
+    if (Array.isArray(content))
+        return content;
+    return String(content);
+}

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

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';

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

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './im-runtime.js';
+export * from './message-dispatcher.js';
+export * from './outbound-renderer.js';
+export * from './outbound-segments.js';

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

@@ -0,0 +1,7 @@
+import type { RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { Message, MessageDispatchResult } from './contracts.js';
+export declare class MessageDispatcher {
+    private readonly prefix;
+    constructor(prefix?: string);
+    dispatch(message: Message, snapshot: RuntimeSnapshot): Promise<MessageDispatchResult>;
+}

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

@@ -0,0 +1,26 @@
+import { commandFeatureId, isCommandIndex } from '@zhin.js/command';
+export class MessageDispatcher {
+    prefix;
+    constructor(prefix = '/') {
+        this.prefix = prefix;
+        if (!prefix)
+            throw new TypeError('Command prefix cannot be empty');
+    }
+    async dispatch(message, snapshot) {
+        if (!message.content.startsWith(this.prefix))
+            return Object.freeze({ matched: false });
+        const input = message.content.slice(this.prefix.length).trim();
+        if (!input)
+            return Object.freeze({ matched: false });
+        const commands = snapshot.projections.get(commandFeatureId);
+        if (!isCommandIndex(commands))
+            return Object.freeze({ matched: false });
+        const result = await commands.dispatch(input, message);
+        if (result.matched && result.value !== undefined) {
+            if (!result.owner)
+                throw new Error('Matched Command is missing its owner');
+            await message.$replyFrom(result.owner, result.value);
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type SendContent } from './contracts.js';
+export declare class OutboundRenderer {
+    #private;
+    render(content: SendContent, requester: PluginId, snapshot: RuntimeSnapshot): Promise<unknown>;
+}

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

@@ -0,0 +1,31 @@
+import { componentFeatureId, isComponentIndex, } from '@zhin.js/component';
+import { isComponentCall, isRawContent, } from './contracts.js';
+const maxComponentDepth = 32;
+export class OutboundRenderer {
+    async render(content, requester, snapshot) {
+        return this.#render(content, requester, snapshot, 0);
+    }
+    async #render(content, requester, snapshot, depth) {
+        if (depth > maxComponentDepth)
+            throw new Error('Component render depth exceeded 32');
+        if (typeof content === 'string')
+            return content;
+        if (Array.isArray(content)) {
+            return Promise.all(content.map((item) => this.#render(item, requester, snapshot, depth)));
+        }
+        if (isRawContent(content))
+            return content.payload;
+        if (isComponentCall(content)) {
+            const rendered = await requireComponents(snapshot).render(requester, content.name, content.props);
+            return this.#render(rendered, requester, snapshot, depth + 1);
+        }
+        throw new TypeError('Unsupported SendContent');
+    }
+}
+function requireComponents(snapshot) {
+    const projection = snapshot.projections.get(componentFeatureId);
+    if (!isComponentIndex(projection)) {
+        throw new Error('Component Feature projection is not installed');
+    }
+    return projection;
+}

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

@@ -0,0 +1,22 @@
+import type { HtmlRendererHost } from '@zhin.js/plugin-runtime';
+/**
+ * Outbound payload normalization for the Plugin Runtime IM pipeline.
+ *
+ * `raw()` payloads reach adapters as-is; adapters only understand wire
+ * segments (`{ type, data }` arrays). A single segment object (non-array)
+ * would otherwise fall through to `String(payload)` → '[object Object]'.
+ * `html` segments additionally need a Host renderer: image when
+ * `@zhin.js/html-renderer` is installed, plain-text fallback otherwise.
+ */
+export interface OutboundSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export declare function isOutboundSegment(value: unknown): value is OutboundSegment;
+/**
+ * Normalize a rendered outbound payload to wire segments:
+ * - segment arrays stay arrays (html segments converted per element);
+ * - a single segment object is wrapped into a one-element array;
+ * - anything else (plain strings, legacy `{ text }` shorthands) passes through.
+ */
+export declare function normalizeOutboundPayload(payload: unknown, renderer?: HtmlRendererHost): Promise<unknown>;

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

@@ -0,0 +1,59 @@
+import { htmlToFallbackText } from '../../built/html-to-text.js';
+const DEFAULT_CARD_WIDTH = 540;
+const DEFAULT_CARD_FILENAME = 'card.png';
+export function isOutboundSegment(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && typeof value.type === 'string';
+}
+/**
+ * Normalize a rendered outbound payload to wire segments:
+ * - segment arrays stay arrays (html segments converted per element);
+ * - a single segment object is wrapped into a one-element array;
+ * - anything else (plain strings, legacy `{ text }` shorthands) passes through.
+ */
+export async function normalizeOutboundPayload(payload, renderer) {
+    if (Array.isArray(payload)) {
+        return Promise.all(payload.map((item) => normalizeOutboundSegment(item, renderer)));
+    }
+    if (isOutboundSegment(payload)) {
+        return [await normalizeOutboundSegment(payload, renderer)];
+    }
+    return payload;
+}
+async function normalizeOutboundSegment(segment, renderer) {
+    if (!isOutboundSegment(segment) || segment.type !== 'html')
+        return segment;
+    const data = segment.data ?? {};
+    const html = typeof data.html === 'string' ? data.html : '';
+    if (html && renderer) {
+        try {
+            const result = await renderer.render(html, {
+                width: typeof data.width === 'number' ? data.width : DEFAULT_CARD_WIDTH,
+                format: 'png',
+                ...(typeof data.backgroundColor === 'string'
+                    ? { backgroundColor: data.backgroundColor }
+                    : {}),
+            });
+            if (result.format === 'png' && result.data && typeof result.data === 'object') {
+                return {
+                    type: 'image',
+                    data: {
+                        base64: Buffer.from(result.data).toString('base64'),
+                        name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
+                    },
+                };
+            }
+        }
+        catch {
+            // 渲染失败 → 文本降级
+        }
+    }
+    return { type: 'text', data: { text: htmlSegmentFallbackText(data, html) } };
+}
+function htmlSegmentFallbackText(data, html) {
+    if (typeof data.text === 'string' && data.text.length > 0)
+        return data.text;
+    return html ? htmlToFallbackText(html) : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/core",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "Zhin机器人核心框架",
   "type": "module",
   "main": "./lib/index.js",
@@ -21,6 +21,11 @@
       "development": "./src/built/queue-im-field-contract.ts",
       "import": "./lib/built/queue-im-field-contract.js"
     },
+    "./runtime": {
+      "types": "./lib/plugin-runtime/im/index.d.ts",
+      "development": "./src/plugin-runtime/im/index.ts",
+      "import": "./lib/plugin-runtime/im/index.js"
+    },
     "./jsx": {
       "types": "./lib/jsx.d.ts",
       "development": "./src/jsx.ts",
@@ -45,9 +50,14 @@
     "segment-matcher": "^1.0.5",
     "smol-toml": "^1.7.0",
     "yaml": "^2.9.0",
-    "@zhin.js/kernel": "1.0.3",
-    "@zhin.js/database": "1.0.76",
-    "@zhin.js/logger": "1.0.74",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/command": "1.0.1",
+    "@zhin.js/component": "1.0.1",
+    "@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/schema": "1.0.71"
   },
   "peerDependencies": {
@@ -62,7 +72,7 @@
     "@types/node": "^26.1.0",
     "@types/qrcode": "^1.5.5",
     "typescript": "^6.0.3",
-    "@zhin.js/ai": "1.4.4"
+    "@zhin.js/ai": "1.4.5"
   },
   "repository": {
     "type": "git",