@zhin.js/core 1.3.1 → 1.3.3

package/lib/built/rich-segments/html-segment.js

@@ -0,0 +1,65 @@
+import { segment } from '../../utils.js';
+import { htmlToFallbackText } from '../html-to-text.js';
+import { RichSegment } from './base.js';
+import { RICH_SEGMENT_MODE } from './types.js';
+async function resolveHtmlRenderer(ctx) {
+    if (!ctx)
+        return undefined;
+    if (ctx.resolveCapability) {
+        return ctx.resolveCapability('html-renderer');
+    }
+    return ctx.getHtmlRenderer?.();
+}
+export class HtmlSegment extends RichSegment {
+    segmentType = 'html';
+    type = 'html';
+    async render(mode, ctx) {
+        if (mode === RICH_SEGMENT_MODE.ORIGIN) {
+            return this.toJSON();
+        }
+        if (mode === RICH_SEGMENT_MODE.TEXT) {
+            if (typeof this.data.text === 'string' && this.data.text.length > 0) {
+                return segment.text(this.data.text);
+            }
+            const html = typeof this.data.html === 'string' ? this.data.html : '';
+            return segment.text(html ? htmlToFallbackText(html) : '');
+        }
+        if (mode === RICH_SEGMENT_MODE.IMAGE) {
+            const html = typeof this.data.html === 'string' ? this.data.html : '';
+            if (!html) {
+                return segment.text('');
+            }
+            const renderer = await resolveHtmlRenderer(ctx);
+            if (!renderer) {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+            try {
+                const result = await renderer.render(html, {
+                    width: typeof this.data.width === 'number' ? this.data.width : 540,
+                    format: 'png',
+                    backgroundColor: typeof this.data.backgroundColor === 'string' ? this.data.backgroundColor : '#d8dce3',
+                });
+                if (result.format !== 'png' || typeof result.data !== 'object') {
+                    return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+                }
+                const base64 = Buffer.from(result.data).toString('base64');
+                const fileName = typeof this.data.fileName === 'string' ? this.data.fileName : 'card.png';
+                return segment('image', { url: `base64://${base64}`, name: fileName });
+            }
+            catch {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+        }
+        return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+    }
+}
+export function wrapHtmlSegment(data) {
+    const html = typeof data.html === 'string' ? data.html : '';
+    return new HtmlSegment({
+        html,
+        text: typeof data.text === 'string' ? data.text : undefined,
+        width: typeof data.width === 'number' ? data.width : undefined,
+        backgroundColor: typeof data.backgroundColor === 'string' ? data.backgroundColor : undefined,
+        fileName: typeof data.fileName === 'string' ? data.fileName : undefined,
+    });
+}

package/lib/built/rich-segments/index.d.ts

@@ -0,0 +1,13 @@
+import './builtins.js';
+export * from './types.js';
+export * from './registry.js';
+export * from './capabilities.js';
+export { DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY, resetBuiltinRichSegmentKindsForTests, } from './builtins.js';
+export * from './base.js';
+export * from './qrcode-segment.js';
+export * from './html-segment.js';
+export * from './markdown-segment.js';
+export * from './tts-segment.js';
+export * from './markdown-to-text.js';
+export * from './resolve.js';
+export * from './adapter-policies.js';

package/lib/built/rich-segments/index.js

@@ -0,0 +1,13 @@
+import './builtins.js';
+export * from './types.js';
+export * from './registry.js';
+export * from './capabilities.js';
+export { DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY, resetBuiltinRichSegmentKindsForTests, } from './builtins.js';
+export * from './base.js';
+export * from './qrcode-segment.js';
+export * from './html-segment.js';
+export * from './markdown-segment.js';
+export * from './tts-segment.js';
+export * from './markdown-to-text.js';
+export * from './resolve.js';
+export * from './adapter-policies.js';

package/lib/built/rich-segments/markdown-segment.d.ts

@@ -0,0 +1,14 @@
+import { RichSegment } from './base.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
+export interface MarkdownSegmentData {
+    content: string;
+    width?: number;
+    backgroundColor?: string;
+    fileName?: string;
+}
+export declare class MarkdownSegment extends RichSegment<MarkdownSegmentData> {
+    readonly segmentType: "markdown";
+    readonly type: "markdown";
+    render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
+}
+export declare function wrapMarkdownSegment(data: Record<string, unknown>): MarkdownSegment;

package/lib/built/rich-segments/markdown-segment.js

@@ -0,0 +1,61 @@
+import { segment } from '../../utils.js';
+import { RichSegment } from './base.js';
+import { markdownToHtmlForRender, markdownToPlainText } from './markdown-to-text.js';
+import { RICH_SEGMENT_MODE } from './types.js';
+async function resolveHtmlRenderer(ctx) {
+    if (!ctx)
+        return undefined;
+    if (ctx.resolveCapability) {
+        return ctx.resolveCapability('html-renderer');
+    }
+    return ctx.getHtmlRenderer?.();
+}
+export class MarkdownSegment extends RichSegment {
+    segmentType = 'markdown';
+    type = 'markdown';
+    async render(mode, ctx) {
+        if (mode === RICH_SEGMENT_MODE.ORIGIN) {
+            return { type: 'markdown', data: { content: this.data.content } };
+        }
+        if (mode === RICH_SEGMENT_MODE.TEXT) {
+            return segment.text(markdownToPlainText(this.data.content));
+        }
+        if (mode === RICH_SEGMENT_MODE.IMAGE) {
+            const renderer = await resolveHtmlRenderer(ctx);
+            if (!renderer) {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+            try {
+                const html = markdownToHtmlForRender(this.data.content);
+                const result = await renderer.render(html, {
+                    width: typeof this.data.width === 'number' ? this.data.width : 540,
+                    format: 'png',
+                    backgroundColor: typeof this.data.backgroundColor === 'string' ? this.data.backgroundColor : '#ffffff',
+                });
+                if (result.format !== 'png' || typeof result.data !== 'object') {
+                    return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+                }
+                const base64 = Buffer.from(result.data).toString('base64');
+                const fileName = typeof this.data.fileName === 'string' ? this.data.fileName : 'markdown.png';
+                return segment('image', { url: `base64://${base64}`, name: fileName });
+            }
+            catch {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+        }
+        return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+    }
+}
+export function wrapMarkdownSegment(data) {
+    const content = typeof data.content === 'string'
+        ? data.content
+        : typeof data.text === 'string'
+            ? data.text
+            : '';
+    return new MarkdownSegment({
+        content,
+        width: typeof data.width === 'number' ? data.width : undefined,
+        backgroundColor: typeof data.backgroundColor === 'string' ? data.backgroundColor : undefined,
+        fileName: typeof data.fileName === 'string' ? data.fileName : undefined,
+    });
+}

package/lib/built/rich-segments/markdown-to-text.d.ts

@@ -0,0 +1,3 @@
+/** 将 Markdown 转为可读纯文本（出站 text 降级用） */
+export declare function markdownToPlainText(md: string): string;
+export declare function markdownToHtmlForRender(md: string): string;

package/lib/built/rich-segments/markdown-to-text.js

@@ -0,0 +1,27 @@
+/** 将 Markdown 转为可读纯文本（出站 text 降级用） */
+export function markdownToPlainText(md) {
+    let text = md;
+    text = text.replace(/```[\s\S]*?```/g, (block) => {
+        const inner = block.replace(/^```[^\n]*\n?/, '').replace(/\n?```$/, '');
+        return inner.trim() ? `${inner.trim()}\n` : '';
+    });
+    text = text.replace(/`([^`]+)`/g, '$1');
+    text = text.replace(/!\[[^\]]*\]\([^)]*\)/g, '');
+    text = text.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
+    text = text.replace(/^#{1,6}\s+/gm, '');
+    text = text.replace(/^\s*>\s?/gm, '');
+    text = text.replace(/^\s*[-*+]\s+/gm, '');
+    text = text.replace(/\*\*([^*]+)\*\*/g, '$1');
+    text = text.replace(/__([^_]+)__/g, '$1');
+    text = text.replace(/\*([^*]+)\*/g, '$1');
+    text = text.replace(/_([^_]+)_/g, '$1');
+    text = text.replace(/~~([^~]+)~~/g, '$1');
+    return text.trim();
+}
+export function markdownToHtmlForRender(md) {
+    const escaped = md
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<pre style="white-space:pre-wrap;font-family:sans-serif;font-size:14px;line-height:1.5;padding:16px;">${escaped}</pre>`;
+}

package/lib/built/rich-segments/qrcode-segment.d.ts

@@ -0,0 +1,18 @@
+import type { MessageElement } from '../../types.js';
+import { type GenerateQrCodeOptions } from '../generated-qrcode.js';
+import { RichSegment } from './base.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
+export interface QrcodeSegmentData extends GenerateQrCodeOptions {
+    text: string;
+    /** process origin 模式终端渲染时使用 */
+    small?: boolean;
+}
+export declare function readQrcodeSegmentData(data: Record<string, unknown>): QrcodeSegmentData;
+export declare class QrcodeSegment extends RichSegment<QrcodeSegmentData> {
+    readonly segmentType: "qrcode";
+    readonly type: "qrcode";
+    render(mode: string, _ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
+}
+export declare function wrapQrcodeSegment(data: Record<string, unknown>): QrcodeSegment;
+/** process endpoint：origin qrcode 段 → 终端 ASCII + 文本占位 */
+export declare function interpretOriginQrcodeForProcess(content: MessageElement | string | (MessageElement | string)[]): Promise<MessageElement | string | (MessageElement | string)[]>;

package/lib/built/rich-segments/qrcode-segment.js

@@ -0,0 +1,73 @@
+import { segment } from '../../utils.js';
+import { GeneratedQrCode } from '../generated-qrcode.js';
+import { RichSegment } from './base.js';
+import { RICH_SEGMENT_MODE } from './types.js';
+export function readQrcodeSegmentData(data) {
+    const text = typeof data.text === 'string' ? data.text : '';
+    if (!text) {
+        throw new Error('qrcode segment: missing data.text');
+    }
+    return {
+        text,
+        width: typeof data.width === 'number' ? data.width : undefined,
+        margin: typeof data.margin === 'number' ? data.margin : undefined,
+        errorCorrectionLevel: data.errorCorrectionLevel === 'L'
+            || data.errorCorrectionLevel === 'M'
+            || data.errorCorrectionLevel === 'Q'
+            || data.errorCorrectionLevel === 'H'
+            ? data.errorCorrectionLevel
+            : undefined,
+        small: data.small === true ? true : undefined,
+    };
+}
+export class QrcodeSegment extends RichSegment {
+    segmentType = 'qrcode';
+    type = 'qrcode';
+    async render(mode, _ctx) {
+        if (mode === RICH_SEGMENT_MODE.ORIGIN) {
+            return this.toJSON();
+        }
+        if (mode === RICH_SEGMENT_MODE.TEXT) {
+            return segment.text(`[二维码] ${this.data.text}`);
+        }
+        if (mode === RICH_SEGMENT_MODE.IMAGE) {
+            const qr = await GeneratedQrCode.generate(this.data.text, this.data);
+            return segment('image', {
+                url: qr.toDataUrl(),
+                base64: qr.toString('base64'),
+            });
+        }
+        return this.render(RICH_SEGMENT_MODE.TEXT, _ctx);
+    }
+}
+export function wrapQrcodeSegment(data) {
+    return new QrcodeSegment(readQrcodeSegmentData(data));
+}
+/** process endpoint：origin qrcode 段 → 终端 ASCII + 文本占位 */
+export async function interpretOriginQrcodeForProcess(content) {
+    const items = Array.isArray(content) ? content : [content];
+    const out = [];
+    let changed = false;
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (item.type !== 'qrcode') {
+            out.push(item);
+            continue;
+        }
+        changed = true;
+        const payload = readQrcodeSegmentData(item.data ?? {});
+        const qr = await GeneratedQrCode.generate(payload.text, payload);
+        await qr.printToTerminal({ small: payload.small ?? true });
+        out.push(segment.text(`[二维码] ${payload.text}`));
+    }
+    if (!changed)
+        return content;
+    if (out.length === 0)
+        return segment.text('');
+    if (out.length === 1)
+        return out[0];
+    return out;
+}

package/lib/built/rich-segments/registry.d.ts

@@ -0,0 +1,16 @@
+import type { OutboundRichSegmentPolicy, RichSegmentKindDefinition } from './types.js';
+export declare class RichSegmentRegistry {
+    #private;
+    register(definition: RichSegmentKindDefinition): void;
+    has(kind: string): boolean;
+    get(kind: string): RichSegmentKindDefinition | undefined;
+    list(): RichSegmentKindDefinition[];
+    buildDefaultPolicy(): OutboundRichSegmentPolicy;
+    resolveMode(policy: OutboundRichSegmentPolicy, kind: string): string;
+    wrap(kind: string, data: Record<string, unknown>): import("./types.js").RichSegmentLike;
+    /** 测试隔离：清空后需重新 register builtins */
+    clearForTests(): void;
+}
+export declare const RICH_SEGMENT_FALLBACK_MODE = "origin";
+export declare const richSegmentRegistry: RichSegmentRegistry;
+export declare function registerRichSegmentKind(definition: RichSegmentKindDefinition): void;

package/lib/built/rich-segments/registry.js

@@ -0,0 +1,52 @@
+export class RichSegmentRegistry {
+    #kinds = new Map();
+    register(definition) {
+        if (this.#kinds.has(definition.kind)) {
+            throw new Error(`Rich segment kind already registered: ${definition.kind}`);
+        }
+        if (!definition.modes.includes(definition.defaultMode)) {
+            throw new Error(`Rich segment ${definition.kind}: defaultMode "${definition.defaultMode}" not in modes`);
+        }
+        this.#kinds.set(definition.kind, definition);
+    }
+    has(kind) {
+        return this.#kinds.has(kind);
+    }
+    get(kind) {
+        return this.#kinds.get(kind);
+    }
+    list() {
+        return [...this.#kinds.values()];
+    }
+    buildDefaultPolicy() {
+        const policy = {};
+        for (const def of this.#kinds.values()) {
+            policy[def.kind] = def.defaultMode;
+        }
+        return policy;
+    }
+    resolveMode(policy, kind) {
+        const def = this.#kinds.get(kind);
+        const requested = policy[kind] ?? def?.defaultMode ?? RICH_SEGMENT_FALLBACK_MODE;
+        if (def && !def.modes.includes(requested)) {
+            return def.defaultMode;
+        }
+        return requested;
+    }
+    wrap(kind, data) {
+        const def = this.#kinds.get(kind);
+        if (!def) {
+            throw new Error(`Unknown rich segment kind: ${kind}`);
+        }
+        return def.wrap(data);
+    }
+    /** 测试隔离：清空后需重新 register builtins */
+    clearForTests() {
+        this.#kinds.clear();
+    }
+}
+export const RICH_SEGMENT_FALLBACK_MODE = 'origin';
+export const richSegmentRegistry = new RichSegmentRegistry();
+export function registerRichSegmentKind(definition) {
+    richSegmentRegistry.register(definition);
+}

package/lib/built/rich-segments/resolve.d.ts

@@ -0,0 +1,5 @@
+import type { SendContent } from '../../types.js';
+import { type OutboundRichSegmentPolicy, type RichSegmentRenderContext } from './types.js';
+export declare function hasRichSegment(content: SendContent | undefined): boolean;
+/** 按 Adapter 出站策略在 renderSendMessage 首步统一渲染富媒体段 */
+export declare function resolveRichSegments(content: SendContent, policy: OutboundRichSegmentPolicy, ctx?: RichSegmentRenderContext): Promise<SendContent>;

package/lib/built/rich-segments/resolve.js

@@ -0,0 +1,87 @@
+import { isRichSegment, richSegmentKind } from './base.js';
+import { richSegmentRegistry } from './registry.js';
+import { RICH_SEGMENT_MODE } from './types.js';
+import { CONTENT_CHAIN_STAGE } from '@zhin.js/logger';
+function asArray(content) {
+    return Array.isArray(content) ? content : [content];
+}
+function packSegments(out) {
+    if (out.length === 0)
+        return { type: 'text', data: { text: '' } };
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+function appendRendered(out, rendered) {
+    if (Array.isArray(rendered)) {
+        out.push(...rendered);
+        return;
+    }
+    out.push(rendered);
+}
+function primarySegmentType(rendered) {
+    if (typeof rendered === 'string')
+        return 'text';
+    if (Array.isArray(rendered)) {
+        const first = rendered[0];
+        if (typeof first === 'string')
+            return 'text';
+        const t = first?.type;
+        return typeof t === 'string' ? t : 'unknown';
+    }
+    const t = rendered.type;
+    return typeof t === 'string' ? t : 'unknown';
+}
+function detectRichSegmentFallback(mode, renderedType) {
+    if (mode === RICH_SEGMENT_MODE.IMAGE && renderedType !== 'image')
+        return true;
+    if (mode === RICH_SEGMENT_MODE.AUDIO && renderedType !== 'audio')
+        return true;
+    if (mode === RICH_SEGMENT_MODE.FILE && renderedType !== 'file')
+        return true;
+    return false;
+}
+export function hasRichSegment(content) {
+    if (content == null)
+        return false;
+    return asArray(content).some((item) => {
+        if (typeof item === 'string')
+            return false;
+        return richSegmentKind(item) != null || isRichSegment(item);
+    });
+}
+/** 按 Adapter 出站策略在 renderSendMessage 首步统一渲染富媒体段 */
+export async function resolveRichSegments(content, policy, ctx) {
+    if (!hasRichSegment(content)) {
+        return content;
+    }
+    const items = asArray(content);
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        const kind = isRichSegment(item) ? item.segmentType : richSegmentKind(item);
+        if (!kind || !richSegmentRegistry.has(kind)) {
+            out.push(item);
+            continue;
+        }
+        const rich = isRichSegment(item)
+            ? item
+            : richSegmentRegistry.wrap(kind, item.data ?? {});
+        const mode = richSegmentRegistry.resolveMode(policy, kind);
+        const rendered = await rich.render(mode, ctx);
+        const renderedType = primarySegmentType(rendered);
+        const fallback = detectRichSegmentFallback(mode, renderedType);
+        ctx?.logContentChain?.({
+            stage: CONTENT_CHAIN_STAGE.RICH_SEGMENT,
+            kind,
+            mode,
+            fallback,
+            result: renderedType,
+        });
+        appendRendered(out, rendered);
+    }
+    return packSegments(out);
+}

package/lib/built/rich-segments/tts-segment.d.ts

@@ -0,0 +1,13 @@
+import { RichSegment } from './base.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
+export interface TtsSegmentData {
+    text: string;
+    voice?: string;
+    provider?: string;
+}
+export declare class TtsSegment extends RichSegment<TtsSegmentData> {
+    readonly segmentType: "tts";
+    readonly type: "tts";
+    render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
+}
+export declare function wrapTtsSegment(data: Record<string, unknown>): TtsSegment;

package/lib/built/rich-segments/tts-segment.js

@@ -0,0 +1,51 @@
+import { segment } from '../../utils.js';
+import { RichSegment } from './base.js';
+import { RICH_SEGMENT_MODE } from './types.js';
+async function resolveSpeechPipeline(ctx) {
+    if (!ctx?.resolveCapability)
+        return undefined;
+    return ctx.resolveCapability('speech');
+}
+export class TtsSegment extends RichSegment {
+    segmentType = 'tts';
+    type = 'tts';
+    async render(mode, ctx) {
+        if (mode === RICH_SEGMENT_MODE.ORIGIN) {
+            return this.toJSON();
+        }
+        const text = typeof this.data.text === 'string' ? this.data.text : '';
+        if (mode === RICH_SEGMENT_MODE.TEXT) {
+            return segment.text(text);
+        }
+        if (mode === RICH_SEGMENT_MODE.AUDIO) {
+            if (!text.trim()) {
+                return segment.text('');
+            }
+            const pipeline = await resolveSpeechPipeline(ctx);
+            if (!pipeline) {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+            try {
+                const result = await pipeline.synthesize({
+                    text,
+                    voice: typeof this.data.voice === 'string' ? this.data.voice : undefined,
+                    provider: typeof this.data.provider === 'string' ? this.data.provider : undefined,
+                });
+                const base64 = result.data.toString('base64');
+                const mime = result.format === 'wav' ? 'audio/wav' : 'audio/mpeg';
+                return segment('audio', { url: `data:${mime};base64,${base64}`, format: result.format });
+            }
+            catch {
+                return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+            }
+        }
+        return this.render(RICH_SEGMENT_MODE.TEXT, ctx);
+    }
+}
+export function wrapTtsSegment(data) {
+    return new TtsSegment({
+        text: String(data.text ?? ''),
+        voice: typeof data.voice === 'string' ? data.voice : undefined,
+        provider: typeof data.provider === 'string' ? data.provider : undefined,
+    });
+}

package/lib/built/rich-segments/types.d.ts

@@ -0,0 +1,84 @@
+import type { MessageElement } from '../../types.js';
+import type { ContentChainLogFields } from '@zhin.js/logger';
+/** 内置 kind 常量（外部可增删，registry 为 SSOT） */
+export declare const BUILTIN_RICH_SEGMENT_KINDS: {
+    readonly QRCODE: "qrcode";
+    readonly HTML: "html";
+    readonly MARKDOWN: "markdown";
+    readonly TTS: "tts";
+};
+export type BuiltinRichSegmentKind = (typeof BUILTIN_RICH_SEGMENT_KINDS)[keyof typeof BUILTIN_RICH_SEGMENT_KINDS];
+/** 通用 mode 名；各 kind 在 registry 中声明支持的子集 */
+export declare const RICH_SEGMENT_MODE: {
+    readonly ORIGIN: "origin";
+    readonly TEXT: "text";
+    readonly IMAGE: "image";
+    readonly FILE: "file";
+    readonly URL: "url";
+    readonly AUDIO: "audio";
+    readonly VIDEO: "video";
+};
+export type RichSegmentMode = (typeof RICH_SEGMENT_MODE)[keyof typeof RICH_SEGMENT_MODE] | string;
+/** 任意已注册 kind → 渲染 mode */
+export type OutboundRichSegmentPolicy = Record<string, string>;
+/** @deprecated 使用 OutboundRichSegmentPolicy；保留别名便于迁移 */
+export type RichSegmentKind = string;
+export type RichRenderMode = string;
+/** html-renderer 可选包契约 */
+export interface HtmlRendererForRichSegment {
+    render(html: string, options?: {
+        width?: number;
+        format?: 'png';
+        backgroundColor?: string;
+    }): Promise<{
+        format: string;
+        data: Buffer | string;
+    }>;
+}
+/** speech 可选包契约（@zhin.js/speech） */
+export interface SpeechPipelineForRichSegment {
+    transcribe(input: {
+        data: Buffer;
+        mimeType?: string;
+    }): Promise<string>;
+    synthesize(input: {
+        text: string;
+        voice?: string;
+        format?: 'mp3' | 'wav';
+        speed?: number;
+        provider?: string;
+    }): Promise<{
+        data: Buffer;
+        format: 'mp3' | 'wav';
+    }>;
+}
+/** 未来 media-pipeline / ffmpeg 等 optional 包可复用同一 id */
+export type RichSegmentCapabilityId = 'html-renderer' | 'speech' | 'media-pipeline' | string;
+export interface RichSegmentRenderContext {
+    /** 按 id 懒加载能力（core 或 optional 包 register loader） */
+    resolveCapability: <T>(id: RichSegmentCapabilityId) => Promise<T | undefined>;
+    /** @deprecated 请用 resolveCapability('html-renderer') */
+    getHtmlRenderer?: () => Promise<HtmlRendererForRichSegment | undefined>;
+    /** 可选：rich_segment stage 结构化日志 */
+    logContentChain?: (fields: ContentChainLogFields) => void;
+    warn?: (message: string) => void;
+}
+export type RichSegmentRenderResult = MessageElement | MessageElement[];
+export interface RichSegmentLike {
+    readonly segmentType: string;
+    render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
+}
+export interface RichSegmentKindDefinition {
+    kind: string;
+    /** policy 未指定时使用的 mode */
+    defaultMode: string;
+    /** 该 kind 支持的 mode 列表（policy 非法值会回退 defaultMode） */
+    modes: readonly string[];
+    wrap: (data: Record<string, unknown>) => RichSegmentLike;
+}
+export interface RichSegmentCapabilityLoaderOptions {
+    warn?: (message: string) => void;
+    getConfig?: () => Record<string, unknown> | undefined;
+    logContentChain?: RichSegmentRenderContext['logContentChain'];
+}
+export type RichSegmentCapabilityLoader = (options: RichSegmentCapabilityLoaderOptions) => Promise<unknown>;

package/lib/built/rich-segments/types.js

@@ -0,0 +1,17 @@
+/** 内置 kind 常量（外部可增删，registry 为 SSOT） */
+export const BUILTIN_RICH_SEGMENT_KINDS = {
+    QRCODE: 'qrcode',
+    HTML: 'html',
+    MARKDOWN: 'markdown',
+    TTS: 'tts',
+};
+/** 通用 mode 名；各 kind 在 registry 中声明支持的子集 */
+export const RICH_SEGMENT_MODE = {
+    ORIGIN: 'origin',
+    TEXT: 'text',
+    IMAGE: 'image',
+    FILE: 'file',
+    URL: 'url',
+    AUDIO: 'audio',
+    VIDEO: 'video',
+};

package/lib/built/roles.d.ts

@@ -12,4 +12,3 @@ export declare function hasSenderRole(roles: Iterable<SenderRole>, role: SenderR
 export declare function formatSenderRolesForLabel(roles: readonly SenderRole[]): string;
 /** 剥离用户正文里自造的发送者前缀 */
 export declare function stripUserSpoofedSenderPrefix(rawContent: string): string;
-//# sourceMappingURL=roles.d.ts.map

package/lib/built/roles.js

@@ -60,4 +60,3 @@ export function stripUserSpoofedSenderPrefix(rawContent) {
     }
     return text;
 }
-//# sourceMappingURL=roles.js.map

package/lib/built/runtime-io.d.ts

@@ -7,4 +7,3 @@ export declare function shouldBindProcessStdin(): boolean;
 export declare function isInteractiveStdin(): boolean;
 export declare function isDenoDeploy(): boolean;
 export declare function bindStdin(onChunk: (chunk: string) => void): () => void;
-//# sourceMappingURL=runtime-io.d.ts.map

package/lib/built/runtime-io.js

@@ -65,4 +65,3 @@ export function bindStdin(onChunk) {
     process.stdin.on("data", handler);
     return () => process.stdin.removeListener("data", handler);
 }
-//# sourceMappingURL=runtime-io.js.map