@zhin.js/core 1.1.33 → 1.1.35

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

@@ -0,0 +1,220 @@
+import { htmlToFallbackText } from '../../built/html-to-text.js';
+import { toCanonicalSegments } from '../../built/generic-segment-mapper.js';
+import { effectiveKeyboardFallbackMap, renderKeyboardAsText, } from '../../built/interactive-segments/resolve.js';
+import { DEFAULT_INTERACTIVE_POLICY, isKeyboardSegment, } from '../../built/interactive-segments/types.js';
+import { isMediaRef } from '../../built/segment-contract/index.js';
+import { markdownToPlainText } from '../../built/rich-segments/markdown-to-text.js';
+const DEFAULT_CARD_WIDTH = 540;
+const DEFAULT_CARD_FILENAME = 'card.png';
+const DEFAULT_MEDIA_POLICY = 'url-or-text';
+/**
+ * 解析端点的出站媒体策略：读 adapter definition 声明的 `segments.outboundMedia`
+ * （多 endpoint 展开的 `slot~entry` id 回退到 slot id 查声明）；
+ * 未声明回退 `url-or-text`（仅 URL 媒体可达，其余文本降级）。
+ */
+export function resolveOutboundMediaPolicy(adapter, snapshot) {
+    const slot = snapshot.capabilities.get(adapter)
+        ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
+    return readDeclaredMediaPolicy(slot?.definition) ?? DEFAULT_MEDIA_POLICY;
+}
+function readDeclaredMediaPolicy(definition) {
+    if (!definition || typeof definition !== 'object')
+        return undefined;
+    const segments = definition.segments;
+    if (!segments || typeof segments !== 'object')
+        return undefined;
+    const declared = segments.outboundMedia;
+    if (!Array.isArray(declared))
+        return undefined;
+    if (declared.includes('base64'))
+        return 'base64';
+    if (declared.includes('upload') || declared.includes('path'))
+        return 'passthrough';
+    if (declared.includes('url'))
+        return 'url-or-text';
+    return undefined;
+}
+export function isOutboundSegment(value) {
+    return typeof value === 'object'
+        && value !== null
+        && !Array.isArray(value)
+        && typeof value.type === 'string';
+}
+/**
+ * 平台名 → 出站 interactive 策略（adapter 未声明 `segments.interactive` 时
+ * 的内置来源）：telegram / discord 端点自行把 keyboard 编码为原生按钮；
+ * 其余平台默认 'text'（编号文本降级，对齐旧轨 DEFAULT_INTERACTIVE_POLICY）。
+ */
+const OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER = {
+    telegram: 'native',
+    discord: 'native',
+};
+/**
+ * 解析端点的出站 interactive 策略：优先读 adapter definition 上声明的
+ * `segments.interactive`，否则按平台名查内置表，未知平台回退 'text'。
+ */
+export function resolveOutboundInteractivePolicy(adapter, snapshot) {
+    const slot = snapshot.capabilities.get(adapter)
+        ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
+    const declared = readDeclaredInteractivePolicy(slot?.definition);
+    if (declared)
+        return declared;
+    const packageName = slot ? snapshot.tree.get(slot.owner)?.packageName : undefined;
+    const adapterType = adapterTypeName(packageName);
+    return (adapterType ? OUTBOUND_INTERACTIVE_POLICY_BY_ADAPTER[adapterType] : undefined)
+        ?? DEFAULT_INTERACTIVE_POLICY;
+}
+/** Preserve semantic Markdown only when the endpoint explicitly declares native consumption. */
+export function resolveOutboundMarkdownPolicy(adapter, snapshot) {
+    const slot = snapshot.capabilities.get(adapter)
+        ?? snapshot.capabilities.get(baseSlotCapabilityId(adapter));
+    if (!slot?.definition || typeof slot.definition !== 'object')
+        return 'text';
+    const segments = slot.definition.segments;
+    if (!segments || typeof segments !== 'object')
+        return 'text';
+    return segments.markdown === 'native' ? 'native' : 'text';
+}
+export function applyOutboundMarkdownPolicy(payload, policy) {
+    if (policy === 'native')
+        return payload;
+    const convert = (item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return item;
+        const segment = item;
+        if (segment.type !== 'markdown')
+            return item;
+        const content = String(segment.data?.content ?? segment.data?.text ?? '');
+        return { type: 'text', data: { text: markdownToPlainText(content) } };
+    };
+    return Array.isArray(payload) ? payload.map(convert) : convert(payload);
+}
+function readDeclaredInteractivePolicy(definition) {
+    if (!definition || typeof definition !== 'object')
+        return undefined;
+    const segments = definition.segments;
+    if (!segments || typeof segments !== 'object')
+        return undefined;
+    const declared = segments.interactive;
+    return declared === 'native' || declared === 'text' ? declared : undefined;
+}
+/**
+ * keyboard 段中央降级：'text' 端点把 keyboard 渲染为编号文本（复用旧轨
+ * `renderKeyboardAsText`），并把有效 fallback 映射经 `remember` 回调写入
+ * 中央存储（供入站数字回跳解析）；'native' 端点透传 keyboard。
+ */
+export function applyOutboundInteractivePolicy(payload, policy, remember) {
+    if (policy !== 'text' || !Array.isArray(payload))
+        return payload;
+    return payload.map((item) => {
+        if (!isKeyboardSegment(item))
+            return item;
+        const data = item.data;
+        remember?.(effectiveKeyboardFallbackMap(data));
+        return { type: 'text', data: { text: renderKeyboardAsText(data) } };
+    });
+}
+/** 多 endpoint 展开的 record id（`slot.id~entry`）→ slot id（entry 名禁含 `~`，见 adapter-index）。 */
+function baseSlotCapabilityId(adapter) {
+    const tilde = adapter.indexOf('~');
+    return (tilde === -1 ? adapter : adapter.slice(0, tilde));
+}
+/** `@zhin.js/adapter-icqq` → `icqq`；非 adapter 包名原样返回。 */
+function adapterTypeName(packageName) {
+    if (!packageName)
+        return undefined;
+    return packageName.replace(/^@[^/]+\/adapter-/, '');
+}
+/**
+ * Normalize a rendered outbound payload toward canonical wire segments:
+ * - segment arrays stay arrays (html segments converted per element,
+ *   其余段经 `toCanonicalSegments` 归一为 canonical Segment)；
+ * - 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, options) {
+    const mediaPolicy = options?.mediaPolicy ?? DEFAULT_MEDIA_POLICY;
+    if (Array.isArray(payload)) {
+        const resolved = await Promise.all(payload.map((item) => normalizeOneSegment(item, renderer, mediaPolicy)));
+        return applyOutboundMediaPolicy(resolved, mediaPolicy);
+    }
+    if (isOutboundSegment(payload)) {
+        return applyOutboundMediaPolicy([await normalizeOneSegment(payload, renderer, mediaPolicy)], mediaPolicy);
+    }
+    return payload;
+}
+/**
+ * 单个出站项 → canonical Segment：
+ * - html 段走渲染/文本降级专线（产物已是 canonical 兼容形状，不再过
+ *   `toCanonicalSegments`，以免 legacy 双写字段被 strip）；
+ * - 其余项经 `toCanonicalSegments` 归一（字符串→text、at→mention、
+ *   旧 wire 字段 `{url,file,base64}`→MediaRef）。
+ */
+async function normalizeOneSegment(item, renderer, mediaPolicy) {
+    if (isOutboundSegment(item) && item.type === 'html') {
+        return renderHtmlSegment(item, renderer, mediaPolicy);
+    }
+    return toCanonicalSegments([item])[0];
+}
+async function renderHtmlSegment(segment, renderer, mediaPolicy) {
+    const data = segment.data ?? {};
+    const html = typeof data.html === 'string' ? data.html : '';
+    // url-or-text 端点无法投递 base64 图片（本层无上传通道），直接文本降级，跳过渲染。
+    if (html && renderer && mediaPolicy !== 'url-or-text') {
+        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') {
+                const base64 = Buffer.from(result.data).toString('base64');
+                return {
+                    type: 'image',
+                    data: {
+                        media: {
+                            kind: 'base64',
+                            value: base64,
+                            mime_type: 'image/png',
+                            file_name: typeof data.fileName === 'string' ? data.fileName : DEFAULT_CARD_FILENAME,
+                        },
+                    },
+                };
+            }
+        }
+        catch {
+            // 渲染失败 → 文本降级
+        }
+    }
+    return { type: 'text', data: { text: htmlSegmentFallbackText(data, html) } };
+}
+/**
+ * 媒体协商：仅 `url-or-text` 需要在本层动作——媒体段的非 URL MediaRef
+ * （base64 / 本地路径）无法投递，降级为文本（alt / file_name 优先）。
+ */
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+function applyOutboundMediaPolicy(segments, mediaPolicy) {
+    if (mediaPolicy !== 'url-or-text')
+        return segments;
+    return segments.map((segment) => {
+        if (!MEDIA_SEGMENT_TYPES.has(segment.type))
+            return segment;
+        const data = segment.data;
+        const media = data.media;
+        if (!isMediaRef(media) || media.kind === 'url')
+            return segment;
+        const label = typeof data.alt === 'string' && data.alt
+            ? data.alt
+            : typeof data.name === 'string' && data.name
+                ? data.name
+                : media.file_name ?? `[${segment.type}]`;
+        return { type: 'text', data: { text: label } };
+    });
+}
+function htmlSegmentFallbackText(data, html) {
+    if (typeof data.text === 'string' && data.text.length > 0)
+        return data.text;
+    return html ? htmlToFallbackText(html) : '';
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Public IM gateway contract exposed from `zhin.js/core/runtime`.
+ * @module zhin.js/core/runtime
+ */
+export { outboundMessageToken } from './im-runtime.js';
+export { Message, type ComponentCall, type ConversationAddress, type IncomingContext, type IncomingMessage, type MessageDispatchResult, type OutboundMessageService, type MessageSenderRef, type OutboundEnvelope, type RawContent, type SendContent, type SendRequest, } from './contracts.js';

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

@@ -0,0 +1,6 @@
+/**
+ * Public IM gateway contract exposed from `zhin.js/core/runtime`.
+ * @module zhin.js/core/runtime
+ */
+export { outboundMessageToken } from './im-runtime.js';
+export { Message, } from './contracts.js';

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

@@ -0,0 +1,18 @@
+/**
+ * Core service tokens — typed Token 替代 legacy string-based inject('x')。
+ *
+ * Slice 2：Token 指向当前 Feature 实例（双写窗口）。
+ * Slice 4：Feature 删除后，Token 类型改为 Runtime projection 接口。
+ */
+import type { CommandFeature } from '../../built/command.js';
+import type { ComponentFeature } from '../../built/component.js';
+import type { ScheduleFeature } from '../../built/schedule.js';
+import type { ConfigFeature } from '../../built/config.js';
+import type { SchemaFeature } from '../../built/schema-feature.js';
+import type { MessageDispatcherService } from '../../built/dispatcher.js';
+export declare const commandServiceToken: import("@zhin.js/plugin-runtime").Token<CommandFeature>;
+export declare const componentServiceToken: import("@zhin.js/plugin-runtime").Token<ComponentFeature>;
+export declare const schedulerServiceToken: import("@zhin.js/plugin-runtime").Token<ScheduleFeature>;
+export declare const configServiceToken: import("@zhin.js/plugin-runtime").Token<ConfigFeature>;
+export declare const schemaServiceToken: import("@zhin.js/plugin-runtime").Token<SchemaFeature>;
+export declare const dispatcherServiceToken: import("@zhin.js/plugin-runtime").Token<MessageDispatcherService>;

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

@@ -0,0 +1,13 @@
+/**
+ * Core service tokens — typed Token 替代 legacy string-based inject('x')。
+ *
+ * Slice 2：Token 指向当前 Feature 实例（双写窗口）。
+ * Slice 4：Feature 删除后，Token 类型改为 Runtime projection 接口。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+export const commandServiceToken = createToken('zhin.im.command-service');
+export const componentServiceToken = createToken('zhin.im.component-service');
+export const schedulerServiceToken = createToken('zhin.im.scheduler-service');
+export const configServiceToken = createToken('zhin.im.config-service');
+export const schemaServiceToken = createToken('zhin.im.schema-service');
+export const dispatcherServiceToken = createToken('zhin.im.dispatcher-service');

package/lib/plugin.d.ts

@@ -6,12 +6,13 @@
  * - 生命周期事件类型安全（Plugin.Lifecycle）
  * - 中间件系统、适配器管理、useContext 等
  */
-import { AsyncLocalStorage } from "node:async_hooks";
-import type { PluginManifest } from "./types.js";
-import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions, MessageSendPayload } from "./types.js";
+import { MessageMiddleware, RegisteredAdapter, MaybePromise, ArrayItem, SendOptions, MessageSendPayload, type PluginManifest } from './types.js';
+import type { InteractiveHandler } from "./built/interactive-segments/types.js";
 import { Adapter, Adapters } from "./adapter.js";
-import { PluginBase, PluginBaseLifecycle } from "@zhin.js/kernel";
-import type { PluginLike } from "@zhin.js/kernel";
+import { PluginBase, PluginBaseLifecycle, type PluginLike } from '@zhin.js/kernel';
+export { getPlugin, markPluginRuntimeActive, isPluginRuntimeActive, resetPluginRuntimeFlag } from "./plugin-context.js";
+export { storage, getCurrentFile } from "./plugin-context.js";
+export { setHostRootPlugin, getHostRootPlugin } from "./host-plugin-registry.js";
 declare const contextsKey: unique symbol;
 export type SideEffect<A extends (keyof Plugin.Contexts)[]> = {
     (...args: ContextList<A>): MaybePromise<void | DisposeFn<ContextList<A>>>;
@@ -20,18 +21,11 @@ export type SideEffect<A extends (keyof Plugin.Contexts)[]> = {
 export type DisposeFn<A> = (context: ArrayItem<A>) => MaybePromise<void>;
 export type ContextList<CS extends (keyof Plugin.Contexts)[]> = CS extends [infer L, ...infer R] ? R extends (keyof Plugin.Contexts)[] ? [ContextItem<L>, ...ContextList<R>] : never[] : never[];
 type ContextItem<L> = L extends keyof Plugin.Contexts ? Plugin.Contexts[L] : never;
-export declare const storage: AsyncLocalStorage<Plugin>;
 /**
- * usePlugin - 获取或创建当前插件实例
- * 类似 React Hooks 的设计，根据调用文件自动创建插件树
- * 同一上下文中同一文件多次调用返回同一实例
+ * @deprecated **已删除**。请使用 `definePlugin` + 约定目录（`zhin runtime start`）。
+ * @throws 总是抛出——仅保留签名供编译期过渡。
  */
 export declare function usePlugin(): Plugin;
-/**
- * getPlugin - 获取当前 AsyncLocalStorage 中的插件实例
- * 用于 extensions 等场景，不创建新插件
- */
-export declare function getPlugin(): Plugin;
 export interface Plugin extends Plugin.Extensions {
     on<K extends keyof Plugin.Lifecycle>(name: K, listener: (...args: Plugin.Lifecycle[K]) => void): this;
     on(name: string | symbol, listener: (...args: any[]) => void): this;
@@ -59,7 +53,6 @@ export declare class Plugin extends PluginBase implements PluginLike {
     started: boolean;
     get root(): Plugin;
     get middleware(): MessageMiddleware<RegisteredAdapter>;
-    recordFeatureContribution(featureName: string, itemName: string): void;
     /**
      * 构造函数
      */
@@ -69,6 +62,10 @@ export declare class Plugin extends PluginBase implements PluginLike {
      * 中间件用于处理消息流转
      */
     addMiddleware<T extends RegisteredAdapter>(middleware: MessageMiddleware<T>, name?: string): () => void;
+    /**
+     * 注册交互式 action 回调处理器（自动安装根中间件，优先于 Dispatcher）
+     */
+    registerInteractiveHandler(prefix: string, handler: InteractiveHandler): () => void;
     /**
      * 插件名称
      */
@@ -87,8 +84,13 @@ export declare class Plugin extends PluginBase implements PluginLike {
     contextIsReady<T extends keyof Plugin.Contexts>(name: T): boolean;
     /**
      * 启动插件
+     * 覆盖 PluginBase.start() 以支持 Context 挂载失败回滚
      */
     start(t?: number): Promise<void>;
+    /**
+     * 覆盖 mountAllContexts：支持部分失败回滚
+     */
+    protected mountAllContexts(): Promise<void>;
     /**
      * 获取插件提供的功能
      * 从各个服务中获取数据
@@ -105,10 +107,10 @@ export declare class Plugin extends PluginBase implements PluginLike {
     info(): Record<string, any>;
     /**
      * 停止插件
+     * 委托 PluginBase.stop() 处理通用清理，仅补充 IM 特化逻辑
      */
     stop(): Promise<void>;
     onMounted(callback: () => void | Promise<void>): void;
-    onDispose(callback: () => void | Promise<void>): () => void;
     /**
      * dispatch - 向上冒泡到父插件，或者在根节点广播（类型安全版本）
      */
@@ -159,7 +161,7 @@ export declare namespace Plugin {
     interface Features {
         commands: string[];
         components: string[];
-        crons: string[];
+        schedules: string[];
         middlewares: string[];
     }
     /**
@@ -175,10 +177,15 @@ export declare namespace Plugin {
         "call.recallMessage": [string, string, string];
         'before.sendMessage': [SendOptions];
         'message.send': [MessageSendPayload];
-        "message.receive": [any];
-        "bot.login.pending": [import('./built/login-assist.js').PendingLoginTask];
-        "request.receive": [any];
-        "notice.receive": [any];
+        "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];
+        "request.receive": [import('./request.js').Request];
+        "notice.receive": [import('./notice.js').Notice];
+        "system.receive": [import('./system-event.js').SystemEvent];
         "ai.processing.start": [Plugin.AIEventPayload];
         "ai.processing.finish": [Plugin.AIEventPayload];
         "ai.processing.error": [Plugin.AIEventPayload];
@@ -190,6 +197,8 @@ export declare namespace Plugin {
         "ai.response": [Plugin.AIEventPayload];
         "ai.typing.start": [Plugin.AIEventPayload];
         "ai.typing.stop": [Plugin.AIEventPayload];
+        "ai.activity.queued.start": [Plugin.AIEventPayload];
+        "ai.activity.queued.clear": [Plugin.AIEventPayload];
         "ai.subagent.spawn": [Plugin.AIEventPayload];
         "ai.subagent.start": [Plugin.AIEventPayload];
         "ai.subagent.finish": [Plugin.AIEventPayload];
@@ -201,6 +210,9 @@ export declare namespace Plugin {
         "ai.session.new": [Plugin.AIEventPayload];
         "ai.session.compact": [Plugin.AIEventPayload];
         "ai.hook": [Plugin.AIEventPayload];
+        "schedule.start": [Plugin.AIEventPayload];
+        "schedule.finish": [Plugin.AIEventPayload];
+        "schedule.error": [Plugin.AIEventPayload];
     }
     interface AIEventPayload {
         sessionId: string;
@@ -209,7 +221,7 @@ export declare namespace Plugin {
         path?: 'chat' | 'fast' | 'agent' | 'multimodal' | 'rate_limited';
         userId?: string;
         platform?: string;
-        botId?: string;
+        endpointKey?: string;
         sceneId?: string;
         messageId?: string;
         scope?: string;
@@ -254,5 +266,3 @@ export declare namespace Plugin {
     interface Extensions {
     }
 }
-export {};
-//# sourceMappingURL=plugin.d.ts.map