@zhin.js/core 1.1.34 → 1.1.35

package/lib/built/permission.js

@@ -3,67 +3,59 @@
  * 权限管理服务，继承自 Feature 抽象类
  */
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
+import logger, { formatCompact } from "@zhin.js/logger";
+import { isBuiltinPermit, parsePermitName } from "./permit-parse.js";
+import { checkBuiltinPermit } from "./permit-check.js";
+import { senderRolesFromMessage } from "./message-enrich.js";
+function rolesForPermitCheck(message) {
+    return senderRolesFromMessage(message);
+}
+function auditPermitDenied(permit, message, reason) {
+    logger.debug(formatCompact({
+        op: 'permit_denied',
+        permit,
+        reason,
+        senderId: message.$sender.id,
+        adapter: message.$adapter,
+        endpoint: message.$endpoint,
+    }));
+}
 export class PermissionFeature extends Feature {
     name = 'permission';
     icon = 'Shield';
     desc = '权限';
     constructor() {
         super();
-        // 注册默认权限检查器（使用 'built-in' 作为插件名）
-        this.add(Permissions.define(/^adapter\([^)]+\)$/, (name, message) => {
-            return message.$adapter === name.replace(/^adapter\(([^)]+)\)$/, '$1');
-        }), '__built-in__');
-        this.add(Permissions.define(/^group\([^)]+\)$/, (name, message) => {
-            const match = name.match(/^group\(([^)]+)\)$/);
-            if (!match)
-                return false;
-            const id = match[1];
-            if (message.$channel.type !== 'group')
-                return false;
-            if (id === '' || id === '*')
-                return true;
-            return message.$channel.id === id;
-        }), '__built-in__');
-        this.add(Permissions.define(/^private\([^)]+\)$/, (name, message) => {
-            const match = name.match(/^private\(([^)]+)\)$/);
-            if (!match)
-                return false;
-            const id = match[1];
-            if (message.$channel.type !== 'private')
-                return false;
-            if (id === '' || id === '*')
-                return true;
-            return message.$channel.id === id;
-        }), '__built-in__');
-        this.add(Permissions.define(/^channel\([^)]+\)$/, (name, message) => {
-            const match = name.match(/^channel\(([^)]+)\)$/);
-            if (!match)
-                return false;
-            const id = match[1];
-            if (message.$channel.type !== 'channel')
-                return false;
-            if (id === '' || id === '*')
-                return true;
-            return message.$channel.id === id;
-        }), '__built-in__');
-        this.add(Permissions.define(/^user\([^)]+\)$/, (name, message) => {
-            const match = name.match(/^user\(([^)]+)\)$/);
-            if (!match)
-                return false;
-            const id = match[1];
-            return message.$sender.id === id;
+        const builtinRe = /^(adapter|group|private|channel|user|role)\([^)]*\)$/;
+        this.add(Permissions.define(builtinRe, (name, message) => {
+            const parsed = parsePermitName(name);
+            if (parsed && parsed.kind !== 'role') {
+                return checkBuiltinPermit(name, message, ['user']);
+            }
+            return checkBuiltinPermit(name, message, rolesForPermitCheck(message));
         }), '__built-in__');
     }
     /**
-     * 检查权限
+     * 检查权限（subject 为 Message 通讯上下文）
      */
-    async check(name, message) {
+    async check(name, subject) {
+        const message = subject;
+        if (isBuiltinPermit(name)) {
+            const parsed = parsePermitName(name);
+            if (parsed && parsed.kind !== 'role') {
+                if (checkBuiltinPermit(name, message, ['user']))
+                    return true;
+            }
+            else if (checkBuiltinPermit(name, message, rolesForPermitCheck(message))) {
+                return true;
+            }
+        }
         for (const permission of this.items) {
             const passed = await permission.check(name, message);
             if (passed)
                 return true;
         }
+        auditPermitDenied(name, message);
         return false;
     }
     /**
@@ -88,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);
@@ -105,8 +97,3 @@ export var Permissions;
     }
     Permissions.define = define;
 })(Permissions || (Permissions = {}));
-/**
- * @deprecated Use PermissionFeature instead
- */
-export const PermissionService = PermissionFeature;
-//# sourceMappingURL=permission.js.map

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

@@ -0,0 +1,7 @@
+/**
+ * 内置 permit 同步校验（adapter/group/private/channel/user/role）
+ */
+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;

package/lib/built/permit-check.js

@@ -0,0 +1,35 @@
+import { isFrameworkSenderRole, roleSatisfies } from './roles.js';
+import { parsePermitName } from './permit-parse.js';
+function channelIdMatches(id, channelId) {
+    return id === '' || id === '*' || channelId === id;
+}
+export function checkBuiltinPermit(name, message, roles) {
+    const parsed = parsePermitName(name);
+    if (!parsed)
+        return false;
+    switch (parsed.kind) {
+        case 'adapter':
+            return parsed.values.some((v) => message.$adapter === v);
+        case 'group':
+            if (message.$channel?.type !== 'group')
+                return false;
+            return parsed.values.some((id) => channelIdMatches(id, String(message.$channel.id)));
+        case 'private':
+            if (message.$channel?.type !== 'private')
+                return false;
+            return parsed.values.some((id) => channelIdMatches(id, String(message.$channel.id)));
+        case 'channel':
+            if (message.$channel?.type !== 'channel')
+                return false;
+            return parsed.values.some((id) => channelIdMatches(id, String(message.$channel.id)));
+        case 'user':
+            return parsed.values.some((id) => String(message.$sender.id) === id);
+        case 'role':
+            return parsed.values.some((req) => isFrameworkSenderRole(req) && roleSatisfies(roles, [req]));
+        default:
+            return false;
+    }
+}
+export function checkBuiltinPermitList(permits, message, roles) {
+    return permits.every((p) => checkBuiltinPermit(p, message, roles));
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Permit 语法解析：type(a,b,c) 括号内逗号为 OR；链式 .permit().permit() 为 AND（由调用方保证）。
+ */
+export type PermitKind = 'adapter' | 'group' | 'private' | 'channel' | 'user' | 'role';
+export interface ParsedPermit {
+    kind: PermitKind;
+    values: string[];
+}
+export declare function parsePermitName(name: string): ParsedPermit | null;
+export declare function isBuiltinPermit(name: string): boolean;
+export interface ParsedPlatformPermit {
+    adapter: string;
+    perm: string;
+}
+export declare function parsePlatformPermitName(name: string): ParsedPlatformPermit | null;
+export declare function isPlatformPermit(name: string): boolean;

package/lib/built/permit-parse.js

@@ -0,0 +1,32 @@
+/**
+ * Permit 语法解析：type(a,b,c) 括号内逗号为 OR；链式 .permit().permit() 为 AND（由调用方保证）。
+ */
+const PERMIT_RE = /^(adapter|group|private|channel|user|role)\(([^)]*)\)$/;
+export function parsePermitName(name) {
+    const m = name.match(PERMIT_RE);
+    if (!m)
+        return null;
+    const kind = m[1];
+    const inner = m[2].trim();
+    if (!inner)
+        return { kind, values: [''] };
+    const values = inner.split(',').map((v) => v.trim()).filter((v) => v.length > 0);
+    return { kind, values: values.length > 0 ? values : [''] };
+}
+export function isBuiltinPermit(name) {
+    return PERMIT_RE.test(name);
+}
+const PLATFORM_PERMIT_RE = /^platform\(([^,)]+),([^)]*)\)$/;
+export function parsePlatformPermitName(name) {
+    const m = name.match(PLATFORM_PERMIT_RE);
+    if (!m)
+        return null;
+    const adapter = m[1].trim();
+    const perm = m[2].trim();
+    if (!adapter || !perm)
+        return null;
+    return { adapter, perm };
+}
+export function isPlatformPermit(name) {
+    return PLATFORM_PERMIT_RE.test(name);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Platform permit — 适配器注册的平台级权限校验（场景治理、频道身份等）
+ */
+import type { Message } from '../message.js';
+export type PlatformPermitChecker = (perm: string, message: Message<any>) => boolean;
+export declare function registerPlatformPermitChecker(adapter: string, checker: PlatformPermitChecker): () => void;
+export declare function clearPlatformPermitCheckers(): void;
+export declare function checkPlatformPermit(name: string, message: Message<any>): boolean;
+export declare function checkPlatformPermitList(permits: readonly string[], message: Message<any>): boolean;
+/** OneBot / QQ 系 sender.role 归一化 */
+export declare function normalizeQqSenderRole(role?: string): 'owner' | 'admin' | undefined;
+/** 从 OneBot sender 对象写入 MessageSender.role / permissions */
+export declare function applyQqSenderRoleToMessageSender(sender: {
+    role?: string;
+    permissions?: string[];
+}, role?: string): void;
+/** 常见 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

@@ -0,0 +1,91 @@
+import { parsePlatformPermitName, isPlatformPermit } from './permit-parse.js';
+const checkers = new Map();
+const defaultSceneRegistrations = new Map();
+export function registerPlatformPermitChecker(adapter, checker) {
+    const key = String(adapter);
+    const registrations = checkers.get(key) ?? [];
+    registrations.push(checker);
+    checkers.set(key, registrations);
+    return () => {
+        const current = checkers.get(key);
+        if (!current)
+            return;
+        const index = current.lastIndexOf(checker);
+        if (index >= 0)
+            current.splice(index, 1);
+        if (current.length === 0)
+            checkers.delete(key);
+    };
+}
+export function clearPlatformPermitCheckers() {
+    checkers.clear();
+    defaultSceneRegistrations.clear();
+}
+export function checkPlatformPermit(name, message) {
+    const parsed = parsePlatformPermitName(name);
+    if (!parsed)
+        return false;
+    if (String(message.$adapter) !== parsed.adapter)
+        return false;
+    const registrations = checkers.get(parsed.adapter);
+    const checker = registrations?.[registrations.length - 1];
+    if (!checker)
+        return false;
+    return checker(parsed.perm, message);
+}
+export function checkPlatformPermitList(permits, message) {
+    return permits.every((p) => isPlatformPermit(p) && checkPlatformPermit(p, message));
+}
+/** OneBot / QQ 系 sender.role 归一化 */
+export function normalizeQqSenderRole(role) {
+    if (!role || role === 'member')
+        return undefined;
+    if (role === 'owner' || role === 'admin')
+        return role;
+    return undefined;
+}
+/** 从 OneBot sender 对象写入 MessageSender.role / permissions */
+export function applyQqSenderRoleToMessageSender(sender, role) {
+    const normalized = normalizeQqSenderRole(role);
+    if (!normalized)
+        return;
+    sender.role = normalized;
+    sender.permissions = [normalized];
+}
+/** 常见 IM 平台场景身份：$sender.role 为 owner / admin */
+export function createSceneRolePlatformChecker() {
+    return (perm, message) => {
+        const role = message.$sender?.role;
+        if (perm === 'scene_admin')
+            return role === 'admin' || role === 'owner';
+        if (perm === 'scene_owner')
+            return role === 'owner';
+        return false;
+    };
+}
+/** 为适配器注册默认场景治理 platform checker（幂等） */
+export function registerDefaultScenePlatformPermitChecker(adapter) {
+    const key = String(adapter);
+    const existing = defaultSceneRegistrations.get(key);
+    if (existing) {
+        existing.references += 1;
+        return () => releaseDefaultSceneChecker(key, existing);
+    }
+    const checker = createSceneRolePlatformChecker();
+    const registration = {
+        checker,
+        dispose: registerPlatformPermitChecker(key, checker),
+        references: 1,
+    };
+    defaultSceneRegistrations.set(key, registration);
+    return () => releaseDefaultSceneChecker(key, registration);
+}
+function releaseDefaultSceneChecker(key, registration) {
+    if (defaultSceneRegistrations.get(key) !== registration)
+        return;
+    registration.references -= 1;
+    if (registration.references > 0)
+        return;
+    defaultSceneRegistrations.delete(key);
+    registration.dispose();
+}

package/lib/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;
@@ -8,7 +9,7 @@ export interface QueueEnvelope<TDetail extends Record<string, unknown> = Record<
 }
 export interface NormalizedQueueOutboundDetail {
     context: string;
-    bot: string;
+    endpoint: string;
     channelId: string;
     channelType: MessageType;
     content: SendContent;
@@ -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;
@@ -26,7 +27,7 @@ function requireContent(value) {
 /** Normalize queue outbound detail into the canonical queue-IM shape. */
 export function normalizeQueueOutboundDetail(record) {
     const context = requireString(record.context, 'context');
-    const bot = requireString(record.bot, 'bot');
+    const endpoint = requireString(record.endpoint, 'endpoint');
     const channelId = requireString(record.channelId, 'channelId');
     const channelTypeValue = record.channelType;
     if (!isMessageType(channelTypeValue)) {
@@ -34,7 +35,7 @@ export function normalizeQueueOutboundDetail(record) {
     }
     const normalized = {
         context,
-        bot,
+        endpoint,
         channelId,
         channelType: channelTypeValue,
         content: requireContent(record.content),
@@ -46,13 +47,21 @@ export function normalizeQueueOutboundDetail(record) {
 export function toSendOptions(detail) {
     return {
         context: detail.context,
-        bot: detail.bot,
+        endpoint: detail.endpoint,
         id: detail.channelId,
         type: detail.channelType,
         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,38 @@
+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,
+        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;

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

@@ -0,0 +1,62 @@
+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;
+    return ctx.resolveCapability('html-renderer');
+}
+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,
+    });
+}