@zhin.js/core 1.3.1 → 1.3.3

package/lib/built/endpoint-lifecycle-service.js

@@ -0,0 +1,241 @@
+import { Adapter } from '../adapter.js';
+import { segment } from '../utils.js';
+import { connectEndpointInstance, disconnectEndpointInstance } from './connect-endpoint-instance.js';
+import { adapterSupportsProvision, resolveEndpointManager } from './schema-endpoint-manager.js';
+function getConfigService(root) {
+    const configService = root.inject('config');
+    if (!configService?.primaryFile) {
+        throw new Error('配置服务不可用');
+    }
+    const loader = configService.configs.get(configService.primaryFile);
+    if (!loader) {
+        throw new Error('配置文件未加载');
+    }
+    return configService;
+}
+function readAllEndpoints(root) {
+    const configService = getConfigService(root);
+    const raw = configService.getRaw(configService.primaryFile);
+    return [...(raw?.endpoints ?? [])];
+}
+function assertUniqueName(endpoints, context, name, replaceIndex) {
+    const conflict = endpoints.findIndex((e) => e.context === context && e.name === name);
+    if (conflict >= 0 && conflict !== replaceIndex) {
+        throw new Error(`zhin.config 中已存在 ${context}/${name}`);
+    }
+}
+function buildProvisionContext(root, message) {
+    return {
+        message,
+        root,
+        onStatusUpdate: async (status, extra) => {
+            if (message.$reply) {
+                let content = status;
+                if (extra?.qrcode && typeof extra.qrcode === 'string') {
+                    content = [segment.qrcode(extra.qrcode), segment.text(status)];
+                }
+                await message.$reply(content);
+            }
+        },
+    };
+}
+export class EndpointLifecycleService {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    resolveAdapter(adapterKey) {
+        const adapter = this.root.inject(adapterKey);
+        if (!(adapter instanceof Adapter)) {
+            throw new Error(`适配器 ${adapterKey} 未安装或未就绪`);
+        }
+        return adapter;
+    }
+    resolveManager(adapterKey) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = resolveEndpointManager(adapter);
+        if (!manager) {
+            throw new Error(`适配器 ${adapterKey} 不支持运行时 Endpoint 管理（无 EndpointManager 且未声明 endpointConfigSchema）`);
+        }
+        return manager;
+    }
+    listProvisionableAdapters() {
+        return this.root.adapters.filter((name) => {
+            try {
+                const adapter = this.resolveAdapter(String(name));
+                return adapterSupportsProvision(adapter);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    async persistEndpoints(endpoints) {
+        const configService = getConfigService(this.root);
+        const loader = configService.configs.get(configService.primaryFile);
+        loader.patchKey('endpoints', endpoints);
+    }
+    /** 将内存中的 endpoints 写回 zhin.config（修复运行时与磁盘不一致） */
+    async syncToDisk() {
+        const configService = getConfigService(this.root);
+        const loader = configService.configs.get(configService.primaryFile);
+        const endpoints = readAllEndpoints(this.root);
+        await this.persistEndpoints(endpoints);
+        const configPath = loader.resolvedPath;
+        const names = endpoints.map((e) => `${e.context}/${e.name}`).join(', ') || '（无）';
+        return {
+            message: `✅ 已将 ${endpoints.length} 个 endpoint 写入 \`${configPath}\`：${names}`,
+        };
+    }
+    async connectConfig(adapter, config) {
+        const name = config.name;
+        if (adapter.endpoints.has(name)) {
+            throw new Error(`Endpoint ${name} 已在线，请先 /endpoint stop ${String(adapter.name)} ${name}`);
+        }
+        const endpoint = await connectEndpointInstance({
+            plugin: this.root,
+            adapter,
+            config: config,
+        });
+        adapter.endpoints.set(endpoint.$id, endpoint);
+        return endpoint;
+    }
+    async disconnectRuntime(adapter, name) {
+        const endpoint = adapter.endpoints.get(name);
+        if (!endpoint)
+            return false;
+        if (endpoint.$connected) {
+            await disconnectEndpointInstance(this.root, adapter, endpoint);
+        }
+        adapter.endpoints.delete(name);
+        return true;
+    }
+    async add(adapterKey, message, initialReply) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const ctx = buildProvisionContext(this.root, message);
+        const config = await manager.addEndpoint(ctx);
+        if (!config.context)
+            config.context = adapterKey;
+        if (!config.name?.trim()) {
+            throw new Error('Endpoint 名称不能为空');
+        }
+        const endpoints = readAllEndpoints(this.root);
+        try {
+            assertUniqueName(endpoints, config.context, config.name);
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes('已存在')) {
+                const online = adapter.endpoints.has(config.name);
+                const hint = online
+                    ? '该 Endpoint 已在运行时注册，无需重复扫码；可发 /endpoints 确认。若 zhin.config.yml 未更新，请 /endpoint sync。'
+                    : '可用 /endpoint start 重试连接，或 /endpoint remove 后重新添加。';
+                throw new Error(`${err.message}。${hint}`);
+            }
+            throw err;
+        }
+        endpoints.push(config);
+        await this.persistEndpoints(endpoints);
+        try {
+            await this.connectConfig(adapter, config);
+        }
+        catch (err) {
+            const needsRestart = adapter.getEndpointNeedsRestart?.() ??
+                adapter.constructor.endpointNeedsRestart;
+            const hint = needsRestart
+                ? '配置已写入，请重启进程后连接。'
+                : `配置已写入，可用 /endpoint start ${adapterKey} ${config.name} 重试。`;
+            throw new Error(`${err instanceof Error ? err.message : String(err)}（${hint}）`);
+        }
+        const prefix = initialReply ? `${initialReply}\n` : '';
+        return {
+            message: `${prefix}✅ 已添加并连接 endpoint \`${config.name}\`（${adapterKey}），已写入 zhin.config。`,
+            config,
+        };
+    }
+    async edit(adapterKey, name, message) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const endpoints = readAllEndpoints(this.root);
+        const index = endpoints.findIndex((e) => e.context === adapterKey && e.name === name);
+        if (index < 0) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        if (adapter.endpoints.has(name)) {
+            await this.disconnectRuntime(adapter, name);
+        }
+        const ctx = buildProvisionContext(this.root, message);
+        const updated = await manager.editEndpoint(name, ctx);
+        updated.context = adapterKey;
+        updated.name = name;
+        endpoints[index] = updated;
+        await this.persistEndpoints(endpoints);
+        try {
+            await this.connectConfig(adapter, updated);
+        }
+        catch (err) {
+            throw new Error(`配置已更新，但连接失败：${err instanceof Error ? err.message : String(err)}。` +
+                `可用 /endpoint start ${adapterKey} ${name} 重试。`);
+        }
+        return {
+            message: `✅ 已更新并连接 endpoint \`${name}\`（${adapterKey}）。`,
+            config: updated,
+        };
+    }
+    async remove(adapterKey, name) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        await this.stop(adapterKey, name);
+        const ok = await manager.removeEndpoint(name);
+        if (!ok) {
+            throw new Error(`无法移除 ${adapterKey}/${name}`);
+        }
+        const endpoints = readAllEndpoints(this.root);
+        const next = endpoints.filter((e) => !(e.context === adapterKey && e.name === name));
+        if (next.length === endpoints.length) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        await this.persistEndpoints(next);
+        return { message: `✅ 已从配置移除 endpoint \`${name}\`（${adapterKey}）。` };
+    }
+    async start(adapterKey, name, message) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const endpoints = readAllEndpoints(this.root);
+        const config = endpoints.find((e) => e.context === adapterKey && e.name === name);
+        if (!config) {
+            throw new Error(`zhin.config 中不存在 ${adapterKey}/${name}`);
+        }
+        if (adapter.endpoints.has(name)) {
+            return { message: `Endpoint ${adapterKey}/${name} 已在线。` };
+        }
+        const ctx = buildProvisionContext(this.root, message);
+        await manager.startEndpoint(name, ctx);
+        await this.connectConfig(adapter, config);
+        return { message: `✅ 已连接 endpoint \`${name}\`（${adapterKey}）。`, config };
+    }
+    async stop(adapterKey, name) {
+        const adapter = this.resolveAdapter(adapterKey);
+        const manager = this.resolveManager(adapterKey);
+        const stopped = await this.disconnectRuntime(adapter, name);
+        await manager.stopEndpoint(name);
+        if (!stopped) {
+            return { message: `Endpoint ${adapterKey}/${name} 当前未在线。` };
+        }
+        return { message: `✅ 已断开 endpoint \`${name}\`（${adapterKey}），配置仍保留。` };
+    }
+    cancelProvision() {
+        for (const adapterName of this.root.adapters) {
+            const adapter = this.root.inject(adapterName);
+            if (!(adapter instanceof Adapter))
+                continue;
+            const manager = resolveEndpointManager(adapter);
+            if (manager?.cancelProvision?.())
+                return true;
+        }
+        return false;
+    }
+}
+export function createEndpointLifecycleService(root) {
+    return new EndpointLifecycleService(root);
+}

package/lib/built/endpoint-lifecycle.d.ts

@@ -25,4 +25,3 @@ export declare function emitEndpointLifecycle(plugin: Plugin, adapter: Adapter,
     phase?: string;
     detail?: Record<string, unknown>;
 }): Promise<void>;
-//# sourceMappingURL=endpoint-lifecycle.d.ts.map

package/lib/built/endpoint-lifecycle.js

@@ -33,4 +33,3 @@ export async function emitEndpointLifecycle(plugin, adapter, endpoint, kind, det
     });
     adapter.emit('notice.receive', notice);
 }
-//# sourceMappingURL=endpoint-lifecycle.js.map

package/lib/built/endpoint-manager.d.ts

@@ -0,0 +1,34 @@
+import type { Schema } from '@zhin.js/schema';
+import type { Message } from '../message.js';
+import type { Plugin } from '../plugin.js';
+/** zhin.config.endpoints[] 单条记录 */
+export type EndpointConfigRecord = Record<string, unknown> & {
+    context: string;
+    name: string;
+};
+export type EndpointStatusExtra = Record<string, unknown>;
+export interface ProvisionContext {
+    message: Message;
+    root: Plugin;
+    /** 长连接 / 扫码 / 登录进度回调（由 core 转发到 message.$reply） */
+    onStatusUpdate: (status: string, extra?: EndpointStatusExtra) => void | Promise<void>;
+}
+export interface EndpointManager {
+    /** 是否支持运行时 add（含 schema 通用或自定义） */
+    supportsProvision(): boolean;
+    listEndpoints(): EndpointConfigRecord[];
+    addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    removeEndpoint(name: string): Promise<boolean>;
+    startEndpoint(name: string, ctx: ProvisionContext): Promise<void>;
+    stopEndpoint(name: string): Promise<boolean>;
+    /** 取消进行中的 add/edit 交互（如 QQ 扫码）；无则返回 false */
+    cancelProvision?(): boolean;
+}
+export interface EndpointManagerClass {
+    new (adapter: import('../adapter.js').Adapter): EndpointManager;
+    /** 热连接失败时是否建议重启进程 */
+    readonly needsRestart?: boolean;
+    /** 通用 schema 驱动 add/edit 时使用 */
+    readonly endpointConfigSchema?: Schema;
+}

package/lib/built/endpoint-manager.js

@@ -0,0 +1 @@
+export {};

package/lib/built/generated-qrcode.d.ts

@@ -0,0 +1,24 @@
+export interface GenerateQrCodeOptions {
+    width?: number;
+    margin?: number;
+    errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+}
+export interface PrintQrCodeTerminalOptions {
+    small?: boolean;
+}
+/** 二维码实例：一次 generate，多种输出 */
+export declare class GeneratedQrCode {
+    #private;
+    private constructor();
+    static generate(text: string, options?: GenerateQrCodeOptions): Promise<GeneratedQrCode>;
+    /** data URL，含 `data:image/png;base64,...` 前缀 */
+    toDataUrl(): string;
+    /**
+     * encoding === 'base64' → 纯 base64 载荷（无 data: 前缀）
+     */
+    toString(encoding: 'base64'): string;
+    /** 输出 ASCII 二维码到 process.stdout */
+    printToTerminal(options?: PrintQrCodeTerminalOptions): Promise<void>;
+}
+/** 便捷别名 */
+export declare const generateQrCode: typeof GeneratedQrCode.generate;

package/lib/built/generated-qrcode.js

@@ -0,0 +1,45 @@
+import QRCode from 'qrcode';
+/** 二维码实例：一次 generate，多种输出 */
+export class GeneratedQrCode {
+    #text;
+    #dataUrl;
+    constructor(text, dataUrl) {
+        this.#text = text;
+        this.#dataUrl = dataUrl;
+    }
+    static async generate(text, options = {}) {
+        const dataUrl = await QRCode.toDataURL(text, {
+            width: options.width ?? 280,
+            margin: options.margin ?? 2,
+            errorCorrectionLevel: options.errorCorrectionLevel ?? 'M',
+        });
+        return new GeneratedQrCode(text, dataUrl);
+    }
+    /** data URL，含 `data:image/png;base64,...` 前缀 */
+    toDataUrl() {
+        return this.#dataUrl;
+    }
+    /**
+     * encoding === 'base64' → 纯 base64 载荷（无 data: 前缀）
+     */
+    toString(encoding) {
+        if (encoding !== 'base64') {
+            throw new Error(`GeneratedQrCode.toString: unsupported encoding "${encoding}"`);
+        }
+        const prefix = 'data:image/png;base64,';
+        if (!this.#dataUrl.startsWith(prefix)) {
+            throw new Error('GeneratedQrCode.toString: unexpected data URL format');
+        }
+        return this.#dataUrl.slice(prefix.length);
+    }
+    /** 输出 ASCII 二维码到 process.stdout */
+    async printToTerminal(options = {}) {
+        const terminalText = await QRCode.toString(this.#text, {
+            type: 'terminal',
+            small: options.small ?? true,
+        });
+        process.stdout.write(`${terminalText}\n`);
+    }
+}
+/** 便捷别名 */
+export const generateQrCode = GeneratedQrCode.generate.bind(GeneratedQrCode);

package/lib/built/generic-segment-mapper.d.ts

@@ -0,0 +1,6 @@
+import type { MessageElement, SendContent } from '../types.js';
+import type { Segment } from './segment-contract/types.js';
+/** 通用 IM adapter：legacy wire → canonical Segment[] */
+export declare function toCanonicalSegments(content: readonly MessageElement[] | readonly unknown[]): Segment[];
+/** canonical → wire（mention→at；image MediaRef→legacy 字段） */
+export declare function fromCanonicalSegments(content: SendContent): MessageElement[];

package/lib/built/generic-segment-mapper.js

@@ -0,0 +1,232 @@
+import { createImageSegment, isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields, readMentionTarget, } from './segment-contract/index.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readPlatform(seg) {
+    const platform = seg.platform;
+    return platform && typeof platform === 'object' ? platform : undefined;
+}
+function normalizeMention(seg) {
+    const data = seg.data;
+    const target = readMentionTarget(data);
+    const name = typeof data.name === 'string' && data.name ? data.name : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'mention',
+        data: name ? { target, name } : { target },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeImage(seg) {
+    const data = seg.data;
+    const platform = readPlatform(seg);
+    if (isMediaRef(data.media)) {
+        return {
+            type: 'image',
+            data: {
+                media: data.media,
+                ...(typeof data.alt === 'string' ? { alt: data.alt } : {}),
+            },
+            ...(platform ? { platform } : {}),
+        };
+    }
+    const media = mediaRefFromLegacyData(data);
+    if (media) {
+        const mergedPlatform = { ...(platform ?? {}) };
+        for (const key of ['url', 'file', 'src', 'file_id']) {
+            if (typeof data[key] === 'string' && data[key])
+                mergedPlatform[key] = data[key];
+        }
+        const platformKeys = Object.keys(mergedPlatform);
+        const legacyPlatform = platformKeys.length === 0
+            ? undefined
+            : platformKeys.length === 1 && mergedPlatform[platformKeys[0]] === media.value
+                ? undefined
+                : mergedPlatform;
+        return createImageSegment(media, {
+            alt: typeof data.alt === 'string' ? data.alt : undefined,
+            platform: legacyPlatform,
+        });
+    }
+    return seg;
+}
+function normalizeReply(seg) {
+    const data = seg.data;
+    const messageId = String(data.message_id ?? data.id ?? '').trim();
+    if (!messageId)
+        return seg;
+    return { type: 'reply', data: { message_id: messageId } };
+}
+function normalizeLink(seg) {
+    const data = seg.data;
+    const url = String(data.url ?? data.href ?? '').trim();
+    if (!url)
+        return seg;
+    const text = typeof data.text === 'string' && data.text ? data.text : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'link',
+        data: text ? { url, text } : { url },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeForward(seg) {
+    const data = seg.data;
+    const forwardId = String(data.forward_id ?? data.id ?? data.resid ?? '').trim();
+    if (!forwardId)
+        return seg;
+    const title = typeof data.title === 'string' ? data.title : undefined;
+    const messages = Array.isArray(data.messages) ? data.messages : undefined;
+    const platform = { ...(readPlatform(seg) ?? {}) };
+    if (data.resid != null)
+        platform.resid = String(data.resid);
+    return {
+        type: 'forward',
+        data: {
+            forward_id: forwardId,
+            ...(title ? { title } : {}),
+            ...(messages ? { messages: messages } : {}),
+        },
+        ...(Object.keys(platform).length ? { platform } : {}),
+    };
+}
+function isPlatformSticker(seg) {
+    if (seg.type !== 'sticker')
+        return false;
+    const data = seg.data;
+    return data.package_id != null
+        || data.sticker_id != null
+        || data.packageId != null
+        || data.stickerId != null;
+}
+function normalizeFace(seg) {
+    if (isPlatformSticker(seg))
+        return seg;
+    const data = seg.data;
+    const rawId = data.id ?? data.face_id;
+    const name = typeof data.name === 'string'
+        ? data.name
+        : typeof data.text === 'string'
+            ? data.text
+            : undefined;
+    const platform = readPlatform(seg);
+    return {
+        type: 'face',
+        data: {
+            ...(rawId != null ? { id: rawId } : {}),
+            ...(name ? { name } : {}),
+        },
+        ...(platform ? { platform } : {}),
+    };
+}
+function normalizeMarkdown(seg) {
+    const data = seg.data;
+    const content = typeof data.content === 'string'
+        ? data.content
+        : typeof data.text === 'string'
+            ? data.text
+            : '';
+    return { type: 'markdown', data: { content } };
+}
+function normalizeSegment(seg) {
+    if (seg.type === 'at' || seg.type === 'mention')
+        return normalizeMention(seg);
+    if (seg.type === 'image')
+        return normalizeImage(seg);
+    if (seg.type === 'reply')
+        return normalizeReply(seg);
+    if (seg.type === 'forward')
+        return normalizeForward(seg);
+    if (seg.type === 'sticker' && isPlatformSticker(seg))
+        return seg;
+    if (seg.type === 'face' || seg.type === 'sticker' || seg.type === 'emoji')
+        return normalizeFace(seg);
+    if (seg.type === 'link')
+        return normalizeLink(seg);
+    if (seg.type === 'markdown')
+        return normalizeMarkdown(seg);
+    return seg;
+}
+function asMessageSegments(content) {
+    return content.map((item) => {
+        if (typeof item === 'string')
+            return { type: 'text', data: { text: item } };
+        return item;
+    });
+}
+function asCanonicalSegments(content) {
+    if (typeof content === 'string') {
+        return [{ type: 'text', data: { text: content } }];
+    }
+    const items = Array.isArray(content) ? content : [content];
+    return items.map((item) => {
+        if (typeof item === 'string')
+            return { type: 'text', data: { text: item } };
+        return item;
+    });
+}
+/** 通用 IM adapter：legacy wire → canonical Segment[] */
+export function toCanonicalSegments(content) {
+    return asMessageSegments(content).map((seg) => normalizeSegment(seg));
+}
+function mapCanonicalToWire(seg) {
+    if (seg.type === 'image' && isRecord(seg.data) && seg.data.media) {
+        const media = seg.data.media;
+        const legacy = mediaRefToLegacyFields(media);
+        return {
+            type: 'image',
+            data: {
+                ...legacy,
+                media,
+                ...(typeof seg.data.alt === 'string' ? { alt: seg.data.alt } : {}),
+            },
+            ...(seg.platform ? { platform: seg.platform } : {}),
+        };
+    }
+    if (seg.type === 'mention') {
+        const data = seg.data;
+        return {
+            type: 'at',
+            data: {
+                id: data.target,
+                ...(data.name ? { name: data.name } : {}),
+            },
+            ...(seg.platform ? { platform: seg.platform } : {}),
+        };
+    }
+    if (seg.type === 'reply') {
+        const messageId = String(seg.data.message_id);
+        return {
+            type: 'reply',
+            data: { id: messageId, message_id: messageId },
+            ...(seg.platform ? { platform: seg.platform } : {}),
+        };
+    }
+    if (seg.type === 'forward') {
+        const data = seg.data;
+        const resid = seg.platform?.resid ?? data.forward_id;
+        return {
+            type: 'forward',
+            data: {
+                id: data.forward_id,
+                resid,
+                ...(data.title ? { title: data.title } : {}),
+                ...(data.messages ? { messages: data.messages } : {}),
+            },
+            ...(seg.platform ? { platform: seg.platform } : {}),
+        };
+    }
+    if (seg.type === 'link') {
+        const data = seg.data;
+        return {
+            type: 'link',
+            data: { url: data.url, ...(data.text ? { text: data.text } : {}) },
+            ...(seg.platform ? { platform: seg.platform } : {}),
+        };
+    }
+    return seg;
+}
+/** canonical → wire（mention→at；image MediaRef→legacy 字段） */
+export function fromCanonicalSegments(content) {
+    return asCanonicalSegments(content).map((seg) => mapCanonicalToWire(seg));
+}

package/lib/built/html-renderer-loader.d.ts

@@ -0,0 +1,13 @@
+import type { HtmlRendererForRichSegment } from './rich-segments/types.js';
+/** 动态 import 时使用的包名（与 @zhin.js/html-renderer package.json 一致） */
+export declare const HTML_RENDERER_PACKAGE = "@zhin.js/html-renderer";
+export interface LoadHtmlRendererOptions {
+    getConfig?: () => Record<string, unknown> | undefined;
+    warn?: (message: string) => void;
+}
+/** zhin 启动时已创建 renderer 时注入，避免 core 目录下 peer 解析失败 */
+export declare function seedHtmlRenderer(renderer: HtmlRendererForRichSegment): void;
+/** 动态加载 @zhin.js/html-renderer；未安装时 warn 一次并返回 undefined */
+export declare function loadHtmlRenderer(opts?: LoadHtmlRendererOptions): Promise<HtmlRendererForRichSegment | undefined>;
+/** 测试用：重置加载缓存 */
+export declare function resetHtmlRendererLoaderForTests(): void;

package/lib/built/html-renderer-loader.js

@@ -0,0 +1,33 @@
+import { importOptionalPeerPackage } from './optional-peer-import.js';
+/** 动态 import 时使用的包名（与 @zhin.js/html-renderer package.json 一致） */
+export const HTML_RENDERER_PACKAGE = '@zhin.js/html-renderer';
+let cached;
+let warned = false;
+/** zhin 启动时已创建 renderer 时注入，避免 core 目录下 peer 解析失败 */
+export function seedHtmlRenderer(renderer) {
+    cached = renderer;
+}
+/** 动态加载 @zhin.js/html-renderer；未安装时 warn 一次并返回 undefined */
+export async function loadHtmlRenderer(opts) {
+    if (cached !== undefined) {
+        return cached ?? undefined;
+    }
+    try {
+        const mod = await importOptionalPeerPackage(HTML_RENDERER_PACKAGE);
+        cached = mod.createHtmlRenderer(opts?.getConfig?.() ?? {});
+        return cached;
+    }
+    catch {
+        if (!warned) {
+            warned = true;
+            opts?.warn?.(`未安装 ${HTML_RENDERER_PACKAGE}，html/markdown=>image 已降级为 text。安装: pnpm add ${HTML_RENDERER_PACKAGE}`);
+        }
+        cached = null;
+        return undefined;
+    }
+}
+/** 测试用：重置加载缓存 */
+export function resetHtmlRendererLoaderForTests() {
+    cached = undefined;
+    warned = false;
+}

package/lib/built/html-segment-fallback.d.ts

@@ -1,9 +1,9 @@
 /**
- * 出站 `html` 消息段兜底：未装 html-renderer 或转图失败时，自动剥离为 text 段。
+ * 出站 `html` 消息段兜底：等价于 Adapter policy `html:'text'`。
+ * 出站渲染首选 `resolveRichSegments`（renderSendMessage 首步）。
  */
 import type { Plugin } from '../plugin.js';
 import type { SendContent } from '../types.js';
 export declare function coerceHtmlSegmentsToText(content: SendContent): SendContent;
 /** 注册链尾 before.sendMessage：将未转换的 html 段降级为 text */
 export declare function registerHtmlSegmentFallback(plugin: Plugin): () => void;
-//# sourceMappingURL=html-segment-fallback.d.ts.map

package/lib/built/html-segment-fallback.js

@@ -47,4 +47,3 @@ export function registerHtmlSegmentFallback(plugin) {
     plugin.root.on('before.sendMessage', handler);
     return () => plugin.root.off('before.sendMessage', handler);
 }
-//# sourceMappingURL=html-segment-fallback.js.map

package/lib/built/html-to-text.d.ts

@@ -14,4 +14,3 @@ export declare function htmlToPlainTextWithBlockBreaks(html: string, options?: H
  * HTML 卡片出站回退：块级换行 + 语义标题轻量 markdown 前缀。
  */
 export declare function htmlToFallbackText(html: string, options?: HtmlToPlainTextOptions): string;
-//# sourceMappingURL=html-to-text.d.ts.map

package/lib/built/html-to-text.js

@@ -163,4 +163,3 @@ export function htmlToFallbackText(html, options) {
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
-//# sourceMappingURL=html-to-text.js.map