@zhin.js/core 1.3.2 → 1.3.3

package/lib/built/config.d.ts

@@ -10,6 +10,8 @@ export declare class ConfigLoader<T extends object> {
     get data(): T;
     get raw(): T;
     get extension(): string;
+    /** `load()` / `patchKey()` 使用的绝对路径 */
+    get resolvedPath(): string;
     constructor(filename: string, initial: T, schema?: Schema<T> | undefined);
     resolvePath(baseDir?: string): string;
     load(baseDir?: string): void;
@@ -20,6 +22,8 @@ export declare class ConfigLoader<T extends object> {
      */
     patchKey(key: string, value: any): void;
 }
+/** 解析 endpoint 配置中的 `${ENV}` 引用（运行时 add 后热连接用） */
+export declare function resolveEndpointConfigEnv(config: Record<string, unknown>): Record<string, unknown>;
 export declare function mergeConfigDefaults<T>(defaults: T, overrides: unknown): T;
 export declare namespace ConfigLoader {
     const supportedExtensions: string[];
@@ -96,4 +100,3 @@ export declare class ConfigFeature extends Feature<ConfigRecord> {
  * @deprecated Use ConfigFeature instead
  */
 export declare const ConfigService: typeof ConfigFeature;
-//# sourceMappingURL=config.d.ts.map

package/lib/built/config.js

@@ -8,7 +8,6 @@ import fs from "node:fs";
 import { stringify as stringifyYaml, parse as parseYaml, parseDocument } from "yaml";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
 /** Deno / Node 统一的工作目录（`Deno.chdir` 后应与 `process.cwd()` 一致） */
 export function runtimeCwd() {
     const g = globalThis;
@@ -37,6 +36,10 @@ export class ConfigLoader {
     get extension() {
         return path.extname(this.filename).toLowerCase();
     }
+    /** `load()` / `patchKey()` 使用的绝对路径 */
+    get resolvedPath() {
+        return this.#resolvedPath || this.resolvePath();
+    }
     constructor(filename, initial, schema) {
         this.filename = filename;
         this.initial = initial;
@@ -96,8 +99,10 @@ export class ConfigLoader {
             ? this.filename
             : path.resolve(baseDir, this.filename);
     }
-    load(baseDir = runtimeCwd()) {
-        const fullPath = this.resolvePath(baseDir);
+    load(baseDir) {
+        const fullPath = baseDir !== undefined
+            ? this.resolvePath(baseDir)
+            : (this.#resolvedPath || this.resolvePath());
         this.#resolvedPath = fullPath;
         if (!fs.existsSync(fullPath)) {
             try {
@@ -197,6 +202,23 @@ function isPlainObject(value) {
         && !Array.isArray(value)
         && Object.getPrototypeOf(value) === Object.prototype;
 }
+/** 解析 endpoint 配置中的 `${ENV}` 引用（运行时 add 后热连接用） */
+export function resolveEndpointConfigEnv(config) {
+    const out = { ...config };
+    for (const [key, value] of Object.entries(out)) {
+        if (typeof value !== 'string')
+            continue;
+        const match = value.match(/^\$\{([^}]+)\}$/);
+        if (!match)
+            continue;
+        const envKey = match[1];
+        const resolved = envLookup(envKey);
+        if (resolved != null && resolved !== '') {
+            out[key] = resolved;
+        }
+    }
+    return out;
+}
 export function mergeConfigDefaults(defaults, overrides) {
     if (Array.isArray(defaults)) {
         return (Array.isArray(overrides) ? overrides : defaults);
@@ -327,7 +349,7 @@ export class ConfigFeature extends Feature {
         const feature = this;
         return {
             addConfig(key, defaultValue) {
-                const plugin = getPlugin();
+                const plugin = this;
                 // 尝试写入主配置文件（如果 key 不存在）
                 if (feature.#primaryConfigFile) {
                     const config = feature.configs.get(feature.#primaryConfigFile);
@@ -352,4 +374,3 @@ export class ConfigFeature extends Feature {
  * @deprecated Use ConfigFeature instead
  */
 export const ConfigService = ConfigFeature;
-//# sourceMappingURL=config.js.map

package/lib/built/connect-endpoint-instance.d.ts

@@ -15,4 +15,3 @@ export declare function connectEndpointInstance(options: ConnectEndpointInstance
  * 按 Endpoint capabilities 断开单个实例。
  */
 export declare function disconnectEndpointInstance(plugin: Plugin, adapter: Adapter, endpoint: Endpoint): Promise<void>;
-//# sourceMappingURL=connect-endpoint-instance.d.ts.map

package/lib/built/connect-endpoint-instance.js

@@ -1,5 +1,6 @@
 import { assertInbound, getAdapterCapabilities, hasInbound, registerEndpointCapabilities, resolveEndpointCapabilities, } from '../endpoint-capabilities.js';
 import { emitEndpointLifecycle } from './endpoint-lifecycle.js';
+import { resolveEndpointConfigEnv } from './config.js';
 /**
  * 按 Endpoint capabilities 连接或注册单个实例（connectEndpoints 与 Adapter.start 共用）。
  */
@@ -7,7 +8,8 @@ export async function connectEndpointInstance(options) {
     const { plugin, adapter, config } = options;
     const adapterCaps = getAdapterCapabilities(adapter);
     const caps = resolveEndpointCapabilities(adapterCaps, config.capabilities);
-    const endpoint = adapter.createEndpoint(config);
+    const resolvedConfig = resolveEndpointConfigEnv(config);
+    const endpoint = adapter.createEndpoint(resolvedConfig);
     registerEndpointCapabilities(endpoint, caps);
     if (caps.includes('inbound')) {
         assertInbound(endpoint);
@@ -38,4 +40,3 @@ export async function disconnectEndpointInstance(plugin, adapter, endpoint) {
     await endpoint.$disconnect();
     await emitEndpointLifecycle(plugin, adapter, endpoint, 'disconnect');
 }
-//# sourceMappingURL=connect-endpoint-instance.js.map

package/lib/built/database.d.ts

@@ -67,4 +67,3 @@ export declare class DatabaseFeature extends Feature<ModelRecord> {
     };
 }
 export {};
-//# sourceMappingURL=database.d.ts.map

package/lib/built/database.js

@@ -5,7 +5,6 @@
 import { Registry } from "@zhin.js/database";
 import { formatCompact } from '@zhin.js/logger';
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
 import { SystemLogDefinition } from "../models/system-log.js";
 import { UserDefinition } from "../models/user.js";
 const databaseAfterStartHooks = [];
@@ -96,7 +95,7 @@ export class DatabaseFeature extends Feature {
         const feature = this;
         return {
             defineModel(name, definition) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const record = { name: name, definition };
                 const dispose = feature.add(record, plugin.name);
                 plugin.recordFeatureContribution(feature.name, name);
@@ -105,4 +104,3 @@ export class DatabaseFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=database.js.map

package/lib/built/dispatcher.d.ts

@@ -27,12 +27,9 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { Message } from '../message.js';
-import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware } from '../types.js';
+import type { MessageMiddleware, RegisteredAdapter, MaybePromise, SendContent, OutboundReplySource, OutboundPolishMiddleware, OutboundReplyStore } from '../types.js';
 import type { Context } from '../plugin.js';
-export declare function getOutboundReplyStore(): {
-    message: Message<any>;
-    source: OutboundReplySource;
-} | undefined;
+export declare function getOutboundReplyStore(): OutboundReplyStore | undefined;
 /**
  * 路由判定结果（互斥模式 legacy）
  */
@@ -110,6 +107,10 @@ export interface MessageDispatcherService {
      * 在 `before.sendMessage` 管道内调用 `message.$reply`（与 Adapter#sendMessage 同一出站链）
      */
     replyWithPolish(message: Message<any>, source: ReplySource, content: SendContent, options?: ReplyWithPolishOptions): Promise<unknown>;
+    /** Proactive 出站：在 ALS 内执行 send，触发 outbound polish / before.sendMessage */
+    runWithOutboundPolish<T>(store: Pick<OutboundReplyStore, 'message' | 'trigger' | 'proactiveSource'> & {
+        source?: OutboundReplySource;
+    }, fn: () => Promise<T>): Promise<T>;
     /**
      * 是否匹配为指令路径（与 dispatch 内判定一致）
      */
@@ -136,4 +137,3 @@ declare module '../plugin.js' {
     }
 }
 export declare function createMessageDispatcher(options?: CreateMessageDispatcherOptions): Context<'dispatcher', DispatcherContextExtensions>;
-//# sourceMappingURL=dispatcher.d.ts.map

package/lib/built/dispatcher.js

@@ -27,7 +27,7 @@
  * 默认路由为 exclusive（命令与 AI 互斥）；需双轨时请显式 dualRoute.mode: 'dual'。
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { getPlugin } from '../plugin.js';
+import { isActionMessage } from './interactive-segments/action.js';
 /** Dispatcher 管理的「会话回复」异步上下文，供 `before.sendMessage` 内读取（与 Adapter.renderSendMessage 同链） */
 const outboundReplyAls = new AsyncLocalStorage();
 export function getOutboundReplyStore() {
@@ -206,10 +206,22 @@ export function createMessageDispatcher(options) {
         if (!rootPlugin) {
             return quote ? message.$reply(content, quote) : message.$reply(content);
         }
-        return outboundReplyAls.run({ message, source }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+        return outboundReplyAls.run({
+            message,
+            source,
+            trigger: 'inbound',
+        }, () => quote ? message.$reply(content, quote) : message.$reply(content));
+    }
+    async function runWithOutboundPolish(store, fn) {
+        return outboundReplyAls.run({
+            message: store.message,
+            source: store.source ?? 'proactive',
+            trigger: store.trigger,
+            proactiveSource: store.proactiveSource,
+        }, fn);
     }
     async function maybeRecordGroupPassiveContext(message) {
-        if (!groupPassiveContextHandler)
+        if (!groupPassiveContextHandler || isActionMessage(message))
             return;
         const scope = message.$channel?.type;
         if (scope !== 'group' && scope !== 'channel')
@@ -336,6 +348,9 @@ export function createMessageDispatcher(options) {
         replyWithPolish(message, source, content, options) {
             return replyWithPolishInternal(message, source, content, options);
         },
+        runWithOutboundPolish(store, fn) {
+            return runWithOutboundPolish(store, fn);
+        },
         matchCommand(message) {
             return matchCommandInternal(message);
         },
@@ -354,18 +369,15 @@ export function createMessageDispatcher(options) {
         },
         extensions: {
             addGuardrail(guardrail) {
-                const plugin = getPlugin();
                 const dispose = service.addGuardrail(guardrail);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
             addOutboundPolish(handler) {
-                const plugin = getPlugin();
                 const dispose = service.addOutboundPolish(handler);
-                plugin.onDispose(dispose);
+                rootPlugin?.onDispose(dispose);
                 return dispose;
             },
         },
     };
 }
-//# sourceMappingURL=dispatcher.js.map

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

@@ -1,4 +1,3 @@
 import type { CommandFeature } from './command.js';
 import type { Plugin } from '../plugin.js';
 export declare function registerEndpointManagementCommands(plugin: Plugin, commandService: CommandFeature): () => void;
-//# sourceMappingURL=endpoint-commands.d.ts.map

package/lib/built/endpoint-commands.js

@@ -3,7 +3,7 @@
  */
 import { Adapter } from '../adapter.js';
 import { MessageCommand } from '../command.js';
-import { rejectUnlessManagementOperator } from './management-command-guard.js';
+import { MANAGEMENT_OPERATOR_PERMIT } from './management-command-guard.js';
 import { createEndpointLifecycleService } from './endpoint-lifecycle-service.js';
 import { endpointHelpText, formatEndpointsList } from './introspection-format.js';
 function collectRuntimeEndpoints(root) {
@@ -26,17 +26,11 @@ export function registerEndpointManagementCommands(plugin, commandService) {
     const root = plugin.root;
     const disposers = [];
     const service = () => createEndpointLifecycleService(root);
-    const guard = (message) => {
-        const ai = root.inject('ai');
-        return rejectUnlessManagementOperator(message, root, ai?.getTriggerConfig?.());
-    };
     const register = (pattern, desc, handler) => {
         const cmd = new MessageCommand(pattern)
             .desc(desc)
+            .permit(MANAGEMENT_OPERATOR_PERMIT)
             .action(async (message, match) => {
-            const denied = guard(message);
-            if (denied)
-                return denied;
             try {
                 return await handler(message, match);
             }
@@ -93,10 +87,13 @@ export function registerEndpointManagementCommands(plugin, commandService) {
         }
         return '已取消 Endpoint 绑定流程。';
     });
+    register('/endpoint sync', '将内存中的 endpoint 配置写回 zhin.config', async () => {
+        const result = await service().syncToDisk();
+        return result.message;
+    });
     register('/endpoints', '列出各适配器下的 Endpoint 及在线状态', () => formatEndpointsList(collectRuntimeEndpoints(root)));
     return () => {
         for (const d of disposers)
             d();
     };
 }
-//# sourceMappingURL=endpoint-commands.js.map

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

@@ -14,6 +14,8 @@ export declare class EndpointLifecycleService {
     resolveManager(adapterKey: string): EndpointManager;
     listProvisionableAdapters(): string[];
     persistEndpoints(endpoints: EndpointConfigRecord[]): Promise<void>;
+    /** 将内存中的 endpoints 写回 zhin.config（修复运行时与磁盘不一致） */
+    syncToDisk(): Promise<EndpointLifecycleResult>;
     connectConfig(adapter: Adapter, config: EndpointConfigRecord): Promise<Endpoint>;
     disconnectRuntime(adapter: Adapter, name: string): Promise<boolean>;
     add(adapterKey: string, message: Message, initialReply?: string): Promise<EndpointLifecycleResult>;
@@ -24,4 +26,3 @@ export declare class EndpointLifecycleService {
     cancelProvision(): boolean;
 }
 export declare function createEndpointLifecycleService(root: Plugin): EndpointLifecycleService;
-//# sourceMappingURL=endpoint-lifecycle-service.d.ts.map

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

@@ -74,7 +74,18 @@ export class EndpointLifecycleService {
         const configService = getConfigService(this.root);
         const loader = configService.configs.get(configService.primaryFile);
         loader.patchKey('endpoints', endpoints);
-        loader.load();
+    }
+    /** 将内存中的 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;
@@ -110,7 +121,19 @@ export class EndpointLifecycleService {
             throw new Error('Endpoint 名称不能为空');
         }
         const endpoints = readAllEndpoints(this.root);
-        assertUniqueName(endpoints, config.context, config.name);
+        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 {
@@ -216,4 +239,3 @@ export class EndpointLifecycleService {
 export function createEndpointLifecycleService(root) {
     return new EndpointLifecycleService(root);
 }
-//# sourceMappingURL=endpoint-lifecycle-service.js.map

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

@@ -32,4 +32,3 @@ export interface EndpointManagerClass {
     /** 通用 schema 驱动 add/edit 时使用 */
     readonly endpointConfigSchema?: Schema;
 }
-//# sourceMappingURL=endpoint-manager.d.ts.map

package/lib/built/endpoint-manager.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=endpoint-manager.js.map

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

@@ -22,4 +22,3 @@ export declare class GeneratedQrCode {
 }
 /** 便捷别名 */
 export declare const generateQrCode: typeof GeneratedQrCode.generate;
-//# sourceMappingURL=generated-qrcode.d.ts.map

package/lib/built/generated-qrcode.js

@@ -43,4 +43,3 @@ export class GeneratedQrCode {
 }
 /** 便捷别名 */
 export const generateQrCode = GeneratedQrCode.generate.bind(GeneratedQrCode);
-//# sourceMappingURL=generated-qrcode.js.map

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

@@ -5,8 +5,9 @@ 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;
-//# sourceMappingURL=html-renderer-loader.d.ts.map

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

@@ -1,14 +1,19 @@
+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 import(HTML_RENDERER_PACKAGE);
+        const mod = await importOptionalPeerPackage(HTML_RENDERER_PACKAGE);
         cached = mod.createHtmlRenderer(opts?.getConfig?.() ?? {});
         return cached;
     }
@@ -26,4 +31,3 @@ export function resetHtmlRendererLoaderForTests() {
     cached = undefined;
     warned = false;
 }
-//# sourceMappingURL=html-renderer-loader.js.map