@zhin.js/core 1.3.1 → 1.3.3

package/lib/built/optional-peer-import.d.ts

@@ -0,0 +1,3 @@
+/** 从应用根（ZHIN_PROJECT_ROOT / cwd）解析 optional peer，避免 core 包目录下 dynamic import 失败 */
+export declare function resolveOptionalPeerPackage(packageName: string): string | undefined;
+export declare function importOptionalPeerPackage<T = Record<string, unknown>>(packageName: string): Promise<T>;

package/lib/built/optional-peer-import.js

@@ -0,0 +1,33 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** 从应用根（ZHIN_PROJECT_ROOT / cwd）解析 optional peer，避免 core 包目录下 dynamic import 失败 */
+export function resolveOptionalPeerPackage(packageName) {
+    const roots = new Set();
+    const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+    if (envRoot)
+        roots.add(path.resolve(envRoot));
+    roots.add(process.cwd());
+    for (const root of roots) {
+        try {
+            const req = createRequire(path.join(root, 'package.json'));
+            return req.resolve(packageName);
+        }
+        catch {
+            // try next root
+        }
+    }
+    try {
+        return createRequire(import.meta.url).resolve(packageName);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function importOptionalPeerPackage(packageName) {
+    const resolved = resolveOptionalPeerPackage(packageName);
+    if (resolved) {
+        return import(pathToFileURL(resolved).href);
+    }
+    return import(packageName);
+}

package/lib/built/outbound-media-contract.d.ts

@@ -0,0 +1,22 @@
+import type { SendContent } from '../types.js';
+/**
+ * 出站两阶段契约（Adapter 实现参考）：
+ *
+ * 1. **resolveRichSegments**（Adapter.renderSendMessage 首步）
+ *    语义段（html / tts / qrcode / markdown）→ 标准 IM 段（image / audio / text）
+ *
+ * 2. **materializeOutboundMedia**（Endpoint.$sendMessage 前，各 adapter 可选）
+ *    标准段中的 base64 / 本地路径 → 平台 URL 或上传后的引用
+ */
+export interface OutboundMediaUploadContext {
+    /** 上传二进制，返回平台可发送的 URL */
+    uploadBuffer?(buffer: Buffer, mimeHint?: string): Promise<string>;
+    /** 上传本地文件路径 */
+    uploadFile?(filePath: string): Promise<string>;
+    outboundDir?: string;
+}
+export type OutboundMediaMaterializer = (content: SendContent, ctx: OutboundMediaUploadContext) => Promise<SendContent>;
+/** 契约测试：adapter 须声明 outboundRichSegmentPolicy */
+export declare function assertAdapterDeclaresRichSegmentPolicy(adapterClass: {
+    outboundRichSegmentPolicy?: Record<string, string>;
+}): void;

package/lib/built/outbound-media-contract.js

@@ -0,0 +1,10 @@
+/** 契约测试：adapter 须声明 outboundRichSegmentPolicy */
+export function assertAdapterDeclaresRichSegmentPolicy(adapterClass) {
+    if (!adapterClass.outboundRichSegmentPolicy) {
+        throw new Error('Adapter must declare static outboundRichSegmentPolicy');
+    }
+    const policy = adapterClass.outboundRichSegmentPolicy;
+    if (typeof policy !== 'object' || Object.keys(policy).length === 0) {
+        throw new Error('outboundRichSegmentPolicy must be a non-empty object');
+    }
+}

package/lib/built/outbound-media-utils.d.ts

@@ -0,0 +1,9 @@
+import type { MessageElement, SendContent } from '../types.js';
+export declare function isRemoteUrl(value: string): boolean;
+/** 从 message 段 data 提取 base64 Buffer（data: URL / base64:// / raw base64） */
+export declare function extractBase64Buffer(data: Record<string, unknown>): Buffer | undefined;
+/** 解析本地文件路径（非 http(s) / base64） */
+export declare function resolveLocalMediaPath(data: Record<string, unknown>): string | undefined;
+export declare function asMessageElements(content: SendContent): MessageElement[];
+export declare function isMediaSegmentType(type: string): boolean;
+export declare function collectOutboundMediaKinds(content: SendContent | undefined): string[];

package/lib/built/outbound-media-utils.js

@@ -0,0 +1,62 @@
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+export function isRemoteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+/** 从 message 段 data 提取 base64 Buffer（data: URL / base64:// / raw base64） */
+export function extractBase64Buffer(data) {
+    const url = typeof data.url === 'string' ? data.url : undefined;
+    const file = typeof data.file === 'string' ? data.file : undefined;
+    const base64 = typeof data.base64 === 'string' ? data.base64 : undefined;
+    if (url?.startsWith('base64://')) {
+        return Buffer.from(url.slice(9), 'base64');
+    }
+    if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
+        return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ''), 'base64');
+    }
+    if (file?.startsWith('base64://')) {
+        return Buffer.from(file.slice(9), 'base64');
+    }
+    if (base64) {
+        const raw = base64.startsWith('base64://') ? base64.slice(9) : base64;
+        return Buffer.from(raw, 'base64');
+    }
+    return undefined;
+}
+/** 解析本地文件路径（非 http(s) / base64） */
+export function resolveLocalMediaPath(data) {
+    const url = typeof data.url === 'string' ? data.url : undefined;
+    const file = typeof data.file === 'string' ? data.file : undefined;
+    const candidate = file ?? url;
+    if (!candidate || isRemoteUrl(candidate))
+        return undefined;
+    if (candidate.startsWith('base64://') || /^data:/.test(candidate))
+        return undefined;
+    if (candidate.startsWith('file://') || candidate.startsWith('/') || !candidate.includes('://')) {
+        return candidate;
+    }
+    return undefined;
+}
+export function asMessageElements(content) {
+    if (typeof content === 'string') {
+        return [{ type: 'text', data: { text: content } }];
+    }
+    if (!Array.isArray(content)) {
+        return [content];
+    }
+    return content.map((item) => typeof item === 'string' ? { type: 'text', data: { text: item } } : item);
+}
+export function isMediaSegmentType(type) {
+    return MEDIA_SEGMENT_TYPES.has(type);
+}
+export function collectOutboundMediaKinds(content) {
+    if (content == null)
+        return [];
+    const kinds = new Set();
+    for (const item of asMessageElements(content)) {
+        const t = item?.type;
+        if (typeof t === 'string' && isMediaSegmentType(t)) {
+            kinds.add(t);
+        }
+    }
+    return [...kinds];
+}

package/lib/built/permission.d.ts

@@ -53,4 +53,3 @@ export declare namespace Permissions {
  * @deprecated Use PermissionFeature instead
  */
 export declare const PermissionService: typeof PermissionFeature;
-//# sourceMappingURL=permission.d.ts.map

package/lib/built/permission.js

@@ -4,7 +4,6 @@
  */
 import { Feature } from "@zhin.js/kernel";
 import logger, { formatCompact } from "@zhin.js/logger";
-import { getPlugin } from "../plugin.js";
 import { isBuiltinPermit, parsePermitName } from "./permit-parse.js";
 import { checkBuiltinPermit } from "./permit-check.js";
 import { senderRolesFromMessage } from "./message-enrich.js";
@@ -81,7 +80,7 @@ export class PermissionFeature extends Feature {
         const feature = this;
         return {
             addPermission(permission) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const dispose = feature.add(permission, plugin.name);
                 const permName = permission.name instanceof RegExp ? permission.name.source : permission.name;
                 plugin.recordFeatureContribution(feature.name, permName);
@@ -102,4 +101,3 @@ export var Permissions;
  * @deprecated Use PermissionFeature instead
  */
 export const PermissionService = PermissionFeature;
-//# sourceMappingURL=permission.js.map

package/lib/built/permit-check.d.ts

@@ -5,4 +5,3 @@ import type { Message } from '../message.js';
 import type { SenderRole } from './roles.js';
 export declare function checkBuiltinPermit(name: string, message: Message<any>, roles: readonly SenderRole[]): boolean;
 export declare function checkBuiltinPermitList(permits: readonly string[], message: Message<any>, roles: readonly SenderRole[]): boolean;
-//# sourceMappingURL=permit-check.d.ts.map

package/lib/built/permit-check.js

@@ -33,4 +33,3 @@ export function checkBuiltinPermit(name, message, roles) {
 export function checkBuiltinPermitList(permits, message, roles) {
     return permits.every((p) => checkBuiltinPermit(p, message, roles));
 }
-//# sourceMappingURL=permit-check.js.map

package/lib/built/permit-parse.d.ts

@@ -14,4 +14,3 @@ export interface ParsedPlatformPermit {
 }
 export declare function parsePlatformPermitName(name: string): ParsedPlatformPermit | null;
 export declare function isPlatformPermit(name: string): boolean;
-//# sourceMappingURL=permit-parse.d.ts.map

package/lib/built/permit-parse.js

@@ -30,4 +30,3 @@ export function parsePlatformPermitName(name) {
 export function isPlatformPermit(name) {
     return PLATFORM_PERMIT_RE.test(name);
 }
-//# sourceMappingURL=permit-parse.js.map

package/lib/built/platform-permit.d.ts

@@ -1,5 +1,5 @@
 /**
- * Platform permit — 适配器注册的平台级权限校验（群管、频道身份等）
+ * Platform permit — 适配器注册的平台级权限校验（场景治理、频道身份等）
  */
 import type { Message } from '../message.js';
 export type PlatformPermitChecker = (perm: string, message: Message<any>) => boolean;
@@ -14,8 +14,7 @@ export declare function applyQqSenderRoleToMessageSender(sender: {
     role?: string;
     permissions?: string[];
 }, role?: string): void;
-/** 常见 IM 平台群身份：$sender.role 为 owner / admin */
-export declare function createGroupRolePlatformChecker(): PlatformPermitChecker;
-/** 为适配器注册默认群管 platform checker（幂等） */
-export declare function registerDefaultGroupPlatformPermitChecker(adapter: string): () => void;
-//# sourceMappingURL=platform-permit.d.ts.map
+/** 常见 IM 平台场景身份：$sender.role 为 owner / admin */
+export declare function createSceneRolePlatformChecker(): PlatformPermitChecker;
+/** 为适配器注册默认场景治理 platform checker（幂等） */
+export declare function registerDefaultScenePlatformPermitChecker(adapter: string): () => void;

package/lib/built/platform-permit.js

@@ -1,6 +1,6 @@
 import { parsePlatformPermitName, isPlatformPermit } from './permit-parse.js';
 const checkers = new Map();
-const registeredDefaultGroupCheckers = new Set();
+const registeredDefaultSceneCheckers = new Set();
 export function registerPlatformPermitChecker(adapter, checker) {
     const key = String(adapter);
     checkers.set(key, checker);
@@ -12,7 +12,7 @@ export function registerPlatformPermitChecker(adapter, checker) {
 }
 export function clearPlatformPermitCheckers() {
     checkers.clear();
-    registeredDefaultGroupCheckers.clear();
+    registeredDefaultSceneCheckers.clear();
 }
 export function checkPlatformPermit(name, message) {
     const parsed = parsePlatformPermitName(name);
@@ -44,24 +44,23 @@ export function applyQqSenderRoleToMessageSender(sender, role) {
     sender.role = normalized;
     sender.permissions = [normalized];
 }
-/** 常见 IM 平台群身份：$sender.role 为 owner / admin */
-export function createGroupRolePlatformChecker() {
+/** 常见 IM 平台场景身份：$sender.role 为 owner / admin */
+export function createSceneRolePlatformChecker() {
     return (perm, message) => {
         const role = message.$sender?.role;
-        if (perm === 'group_admin')
+        if (perm === 'scene_admin')
             return role === 'admin' || role === 'owner';
-        if (perm === 'group_owner')
+        if (perm === 'scene_owner')
             return role === 'owner';
         return false;
     };
 }
-/** 为适配器注册默认群管 platform checker（幂等） */
-export function registerDefaultGroupPlatformPermitChecker(adapter) {
+/** 为适配器注册默认场景治理 platform checker（幂等） */
+export function registerDefaultScenePlatformPermitChecker(adapter) {
     const key = String(adapter);
-    if (registeredDefaultGroupCheckers.has(key)) {
+    if (registeredDefaultSceneCheckers.has(key)) {
         return () => { };
     }
-    registeredDefaultGroupCheckers.add(key);
-    return registerPlatformPermitChecker(key, createGroupRolePlatformChecker());
+    registeredDefaultSceneCheckers.add(key);
+    return registerPlatformPermitChecker(key, createSceneRolePlatformChecker());
 }
-//# sourceMappingURL=platform-permit.js.map

package/lib/built/prepend-quote-context.d.ts

@@ -32,4 +32,3 @@ export declare function resolveQuoteContextBlock(message: Message<any>, root: Pl
 export declare function prependQuoteContext(message: Message<any>, root: Plugin, userText: string, options?: {
     enabled?: boolean;
 }): Promise<string>;
-//# sourceMappingURL=prepend-quote-context.d.ts.map

package/lib/built/prepend-quote-context.js

@@ -128,4 +128,3 @@ export async function prependQuoteContext(message, root, userText, options) {
     const quoteBlock = await resolveQuoteContextBlock(message, root, options);
     return buildUserTurnWithQuoteContext(userText, quoteBlock);
 }
-//# sourceMappingURL=prepend-quote-context.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * 出站 `qrcode` 消息段（legacy 导出；新代码请用 rich-segments）。
+ * @deprecated 出站渲染由 Adapter.renderSendMessage → resolveRichSegments 统一处理
+ */
+import type { SendContent } from '../types.js';
+import { QrcodeSegment, readQrcodeSegmentData, type QrcodeSegmentData } from './rich-segments/qrcode-segment.js';
+export type { QrcodeSegmentData };
+export { QrcodeSegment, readQrcodeSegmentData };
+export type QrcodeOutboundMode = 'image' | 'terminal' | 'text';
+export declare function hasQrcodeSegment(content: SendContent | undefined): boolean;
+/** 创建 qrcode 出站段 */
+export declare function qrcodeSegment(text: string, options?: Omit<QrcodeSegmentData, 'text'>): QrcodeSegment;
+/** IM 适配器：qrcode → image(data URL + base64) */
+export declare function resolveQrcodeSegmentsToImages(content: SendContent | undefined): Promise<SendContent | undefined>;
+/** process 适配器：终端 ASCII + 文本占位（legacy；process endpoint 现解释 origin qrcode） */
+export declare function resolveQrcodeSegmentsToTerminal(content: SendContent | undefined): Promise<SendContent | undefined>;
+/** 不支持图片的平台：仅输出链接文本 */
+export declare function coerceQrcodeSegmentsToText(content: SendContent): SendContent;

package/lib/built/qrcode-segment.js

@@ -0,0 +1,78 @@
+import { segment } from '../utils.js';
+import { GeneratedQrCode } from './generated-qrcode.js';
+import { QrcodeSegment, readQrcodeSegmentData, } from './rich-segments/qrcode-segment.js';
+export { QrcodeSegment, readQrcodeSegmentData };
+function asArray(content) {
+    return Array.isArray(content) ? content : [content];
+}
+function packSegments(out) {
+    if (out.length === 0)
+        return segment.text('');
+    if (out.length === 1)
+        return out[0];
+    return out;
+}
+export function hasQrcodeSegment(content) {
+    if (content == null)
+        return false;
+    return asArray(content).some((item) => typeof item !== 'string' && item?.type === 'qrcode');
+}
+/** 创建 qrcode 出站段 */
+export function qrcodeSegment(text, options = {}) {
+    return new QrcodeSegment({ text, ...options });
+}
+const LEGACY_QRCODE_ONLY_POLICY = {
+    qrcode: 'image',
+    html: 'origin',
+    markdown: 'origin',
+};
+/** IM 适配器：qrcode → image(data URL + base64) */
+export async function resolveQrcodeSegmentsToImages(content) {
+    if (content == null)
+        return content;
+    const { resolveRichSegments } = await import('./rich-segments/index.js');
+    return resolveRichSegments(content, LEGACY_QRCODE_ONLY_POLICY);
+}
+/** process 适配器：终端 ASCII + 文本占位（legacy；process endpoint 现解释 origin qrcode） */
+export async function resolveQrcodeSegmentsToTerminal(content) {
+    if (content == null)
+        return content;
+    if (!hasQrcodeSegment(content))
+        return content;
+    const items = asArray(content);
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (item.type !== 'qrcode') {
+            out.push(item);
+            continue;
+        }
+        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}`));
+    }
+    return packSegments(out);
+}
+/** 不支持图片的平台：仅输出链接文本 */
+export function coerceQrcodeSegmentsToText(content) {
+    const items = asArray(content);
+    const out = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            out.push(item);
+            continue;
+        }
+        if (item?.type === 'qrcode') {
+            const text = typeof item.data?.text === 'string' ? item.data.text : '';
+            if (text)
+                out.push(segment.text(`[二维码] ${text}`));
+            continue;
+        }
+        out.push(item);
+    }
+    return packSegments(out);
+}

package/lib/built/queue-im-field-contract.d.ts

@@ -1,5 +1,6 @@
 import type { MessageType } from '../message.js';
 import type { SendContent, SendOptions } from '../types.js';
+import { type IMDeliveryTarget } from '../im-scene.js';
 export interface QueueEnvelope<TDetail extends Record<string, unknown> = Record<string, unknown>> {
     kind: string;
     type: string;
@@ -23,5 +24,9 @@ export declare function isMessageType(value: unknown): value is MessageType;
 /** Normalize queue outbound detail into the canonical queue-IM shape. */
 export declare function normalizeQueueOutboundDetail(record: Record<string, unknown>): NormalizedQueueOutboundDetail;
 export declare function toSendOptions(detail: NormalizedQueueOutboundDetail): SendOptions;
+export interface QueueIMSceneTargetDetail {
+    target: IMDeliveryTarget;
+    content: SendContent;
+}
+export declare function sceneTargetToSendOptions(detail: QueueIMSceneTargetDetail): SendOptions;
 export declare function normalizeRecordToSendOptions(record: Record<string, unknown>): SendOptions;
-//# sourceMappingURL=queue-im-field-contract.d.ts.map

package/lib/built/queue-im-field-contract.js

@@ -1,3 +1,4 @@
+import { sceneRefToSendOptions } from '../im-scene.js';
 export class QueueIMFieldContractError extends Error {
     code;
     field;
@@ -52,7 +53,15 @@ export function toSendOptions(detail) {
         content: detail.content,
     };
 }
+export function sceneTargetToSendOptions(detail) {
+    return sceneRefToSendOptions(detail.target, detail.content);
+}
 export function normalizeRecordToSendOptions(record) {
+    if (record.target && typeof record.target === 'object') {
+        return sceneTargetToSendOptions({
+            target: record.target,
+            content: requireContent(record.content),
+        });
+    }
     return toSendOptions(normalizeQueueOutboundDetail(record));
 }
-//# sourceMappingURL=queue-im-field-contract.js.map

package/lib/built/rich-segments/adapter-policies.d.ts

@@ -0,0 +1,9 @@
+import { type OutboundRichSegmentPolicy } from './types.js';
+/** 全功能 IM：html/markdown/qrcode→image，tts→audio */
+export declare const OUTBOUND_RICH_SEGMENT_POLICY_IM_FULL: OutboundRichSegmentPolicy;
+/** 仅文本降级（无富媒体出站能力） */
+export declare const OUTBOUND_RICH_SEGMENT_POLICY_TEXT_ONLY: OutboundRichSegmentPolicy;
+/** 默认 registry 等价（html/markdown 文本，qrcode 图片，tts 音频） */
+export declare const OUTBOUND_RICH_SEGMENT_POLICY_IM_DEFAULT: OutboundRichSegmentPolicy;
+/** 无音频出站（tts 降级 text） */
+export declare const OUTBOUND_RICH_SEGMENT_POLICY_NO_AUDIO: OutboundRichSegmentPolicy;

package/lib/built/rich-segments/adapter-policies.js

@@ -0,0 +1,27 @@
+import { BUILTIN_RICH_SEGMENT_KINDS, RICH_SEGMENT_MODE } from './types.js';
+/** 全功能 IM：html/markdown/qrcode→image，tts→audio */
+export const OUTBOUND_RICH_SEGMENT_POLICY_IM_FULL = {
+    [BUILTIN_RICH_SEGMENT_KINDS.QRCODE]: RICH_SEGMENT_MODE.IMAGE,
+    [BUILTIN_RICH_SEGMENT_KINDS.HTML]: RICH_SEGMENT_MODE.IMAGE,
+    [BUILTIN_RICH_SEGMENT_KINDS.MARKDOWN]: RICH_SEGMENT_MODE.IMAGE,
+    [BUILTIN_RICH_SEGMENT_KINDS.TTS]: RICH_SEGMENT_MODE.AUDIO,
+};
+/** 仅文本降级（无富媒体出站能力） */
+export const OUTBOUND_RICH_SEGMENT_POLICY_TEXT_ONLY = {
+    [BUILTIN_RICH_SEGMENT_KINDS.QRCODE]: RICH_SEGMENT_MODE.TEXT,
+    [BUILTIN_RICH_SEGMENT_KINDS.HTML]: RICH_SEGMENT_MODE.TEXT,
+    [BUILTIN_RICH_SEGMENT_KINDS.MARKDOWN]: RICH_SEGMENT_MODE.TEXT,
+    [BUILTIN_RICH_SEGMENT_KINDS.TTS]: RICH_SEGMENT_MODE.TEXT,
+};
+/** 默认 registry 等价（html/markdown 文本，qrcode 图片，tts 音频） */
+export const OUTBOUND_RICH_SEGMENT_POLICY_IM_DEFAULT = {
+    [BUILTIN_RICH_SEGMENT_KINDS.QRCODE]: RICH_SEGMENT_MODE.IMAGE,
+    [BUILTIN_RICH_SEGMENT_KINDS.HTML]: RICH_SEGMENT_MODE.TEXT,
+    [BUILTIN_RICH_SEGMENT_KINDS.MARKDOWN]: RICH_SEGMENT_MODE.TEXT,
+    [BUILTIN_RICH_SEGMENT_KINDS.TTS]: RICH_SEGMENT_MODE.AUDIO,
+};
+/** 无音频出站（tts 降级 text） */
+export const OUTBOUND_RICH_SEGMENT_POLICY_NO_AUDIO = {
+    ...OUTBOUND_RICH_SEGMENT_POLICY_IM_FULL,
+    [BUILTIN_RICH_SEGMENT_KINDS.TTS]: RICH_SEGMENT_MODE.TEXT,
+};

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

@@ -0,0 +1,11 @@
+import type { MessageElement } from '../../types.js';
+import type { RichSegmentRenderContext, RichSegmentRenderResult } from './types.js';
+export declare abstract class RichSegment<TData> {
+    readonly data: TData;
+    abstract readonly segmentType: string;
+    constructor(data: TData);
+    abstract render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
+    toJSON(): MessageElement;
+}
+export declare function isRichSegment(item: unknown): item is RichSegment<unknown>;
+export declare function richSegmentKind(item: MessageElement | string): string | null;

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

@@ -0,0 +1,24 @@
+import { richSegmentRegistry } from './registry.js';
+export class RichSegment {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    toJSON() {
+        return { type: this.segmentType, data: this.data };
+    }
+}
+export function isRichSegment(item) {
+    return item instanceof RichSegment;
+}
+export function richSegmentKind(item) {
+    if (typeof item === 'string')
+        return null;
+    const type = item.type;
+    if (typeof type !== 'string')
+        return null;
+    if (richSegmentRegistry.has(type)) {
+        return type;
+    }
+    return null;
+}

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

@@ -0,0 +1,4 @@
+/** 内置 kind 的默认出站 policy（由 registry 生成，增 kind 时自动包含） */
+export declare const DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY: import("./types.js").OutboundRichSegmentPolicy;
+/** 测试：清空 registry 后重新注册内置 kind */
+export declare function resetBuiltinRichSegmentKindsForTests(): void;

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

@@ -0,0 +1,40 @@
+import { registerRichSegmentKind, richSegmentRegistry } from './registry.js';
+import { wrapQrcodeSegment } from './qrcode-segment.js';
+import { wrapHtmlSegment } from './html-segment.js';
+import { wrapMarkdownSegment } from './markdown-segment.js';
+import { wrapTtsSegment } from './tts-segment.js';
+import { BUILTIN_RICH_SEGMENT_KINDS, RICH_SEGMENT_MODE } from './types.js';
+function registerBuiltinRichSegmentKinds() {
+    registerRichSegmentKind({
+        kind: BUILTIN_RICH_SEGMENT_KINDS.QRCODE,
+        defaultMode: RICH_SEGMENT_MODE.IMAGE,
+        modes: [RICH_SEGMENT_MODE.IMAGE, RICH_SEGMENT_MODE.TEXT, RICH_SEGMENT_MODE.ORIGIN],
+        wrap: wrapQrcodeSegment,
+    });
+    registerRichSegmentKind({
+        kind: BUILTIN_RICH_SEGMENT_KINDS.HTML,
+        defaultMode: RICH_SEGMENT_MODE.TEXT,
+        modes: [RICH_SEGMENT_MODE.IMAGE, RICH_SEGMENT_MODE.TEXT, RICH_SEGMENT_MODE.ORIGIN],
+        wrap: wrapHtmlSegment,
+    });
+    registerRichSegmentKind({
+        kind: BUILTIN_RICH_SEGMENT_KINDS.MARKDOWN,
+        defaultMode: RICH_SEGMENT_MODE.TEXT,
+        modes: [RICH_SEGMENT_MODE.IMAGE, RICH_SEGMENT_MODE.TEXT, RICH_SEGMENT_MODE.ORIGIN],
+        wrap: wrapMarkdownSegment,
+    });
+    registerRichSegmentKind({
+        kind: BUILTIN_RICH_SEGMENT_KINDS.TTS,
+        defaultMode: RICH_SEGMENT_MODE.AUDIO,
+        modes: [RICH_SEGMENT_MODE.ORIGIN, RICH_SEGMENT_MODE.AUDIO, RICH_SEGMENT_MODE.TEXT],
+        wrap: wrapTtsSegment,
+    });
+}
+registerBuiltinRichSegmentKinds();
+/** 内置 kind 的默认出站 policy（由 registry 生成，增 kind 时自动包含） */
+export const DEFAULT_OUTBOUND_RICH_SEGMENT_POLICY = richSegmentRegistry.buildDefaultPolicy();
+/** 测试：清空 registry 后重新注册内置 kind */
+export function resetBuiltinRichSegmentKindsForTests() {
+    richSegmentRegistry.clearForTests();
+    registerBuiltinRichSegmentKinds();
+}

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

@@ -0,0 +1,6 @@
+import type { RichSegmentCapabilityLoader, RichSegmentCapabilityLoaderOptions, RichSegmentRenderContext } from './types.js';
+/** 注册 optional 包能力（如 html-renderer、未来 media-pipeline） */
+export declare function registerRichSegmentCapabilityLoader(id: string, loader: RichSegmentCapabilityLoader): void;
+/** 测试隔离 */
+export declare function resetRichSegmentCapabilityLoadersForTests(): void;
+export declare function createRichSegmentRenderContext(options?: RichSegmentCapabilityLoaderOptions): RichSegmentRenderContext;

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

@@ -0,0 +1,39 @@
+import { loadHtmlRenderer } from '../html-renderer-loader.js';
+import { loadSpeechPipeline } from '../speech-loader.js';
+const capabilityLoaders = new Map();
+/** 注册 optional 包能力（如 html-renderer、未来 media-pipeline） */
+export function registerRichSegmentCapabilityLoader(id, loader) {
+    capabilityLoaders.set(id, loader);
+}
+/** 测试隔离 */
+export function resetRichSegmentCapabilityLoadersForTests() {
+    capabilityLoaders.clear();
+    registerCoreRichSegmentCapabilityLoaders();
+}
+function registerCoreRichSegmentCapabilityLoaders() {
+    registerRichSegmentCapabilityLoader('html-renderer', async (options) => loadHtmlRenderer({
+        getConfig: options.getConfig,
+        warn: options.warn,
+    }));
+    registerRichSegmentCapabilityLoader('speech', async (options) => loadSpeechPipeline({
+        getConfig: options.getConfig,
+        warn: options.warn,
+    }));
+}
+registerCoreRichSegmentCapabilityLoaders();
+export function createRichSegmentRenderContext(options = {}) {
+    const cache = new Map();
+    const resolveCapability = async (id) => {
+        if (!cache.has(id)) {
+            const loader = capabilityLoaders.get(id);
+            cache.set(id, loader ? loader(options) : Promise.resolve(undefined));
+        }
+        return cache.get(id);
+    };
+    return {
+        resolveCapability,
+        getHtmlRenderer: () => resolveCapability('html-renderer'),
+        warn: options.warn,
+        logContentChain: options.logContentChain,
+    };
+}

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

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