@zhin.js/core 1.3.2 → 1.3.4

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

@@ -4,4 +4,3 @@ export declare function registerRichSegmentCapabilityLoader(id: string, loader:
 /** 测试隔离 */
 export declare function resetRichSegmentCapabilityLoadersForTests(): void;
 export declare function createRichSegmentRenderContext(options?: RichSegmentCapabilityLoaderOptions): RichSegmentRenderContext;
-//# sourceMappingURL=capabilities.d.ts.map

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

@@ -37,4 +37,3 @@ export function createRichSegmentRenderContext(options = {}) {
         logContentChain: options.logContentChain,
     };
 }
-//# sourceMappingURL=capabilities.js.map

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

@@ -1,5 +1,5 @@
 import { RichSegment } from './base.js';
-import type { RichSegmentRenderContext, RichSegmentRenderResult } from './types.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
 export interface HtmlSegmentData {
     html: string;
     text?: string;
@@ -13,4 +13,3 @@ export declare class HtmlSegment extends RichSegment<HtmlSegmentData> {
     render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
 }
 export declare function wrapHtmlSegment(data: Record<string, unknown>): HtmlSegment;
-//# sourceMappingURL=html-segment.d.ts.map

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

@@ -63,4 +63,3 @@ export function wrapHtmlSegment(data) {
         fileName: typeof data.fileName === 'string' ? data.fileName : undefined,
     });
 }
-//# sourceMappingURL=html-segment.js.map

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

@@ -11,4 +11,3 @@ export * from './tts-segment.js';
 export * from './markdown-to-text.js';
 export * from './resolve.js';
 export * from './adapter-policies.js';
-//# sourceMappingURL=index.d.ts.map

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

@@ -11,4 +11,3 @@ export * from './tts-segment.js';
 export * from './markdown-to-text.js';
 export * from './resolve.js';
 export * from './adapter-policies.js';
-//# sourceMappingURL=index.js.map

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

@@ -1,5 +1,5 @@
 import { RichSegment } from './base.js';
-import type { RichSegmentRenderContext, RichSegmentRenderResult } from './types.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
 export interface MarkdownSegmentData {
     content: string;
     width?: number;
@@ -12,4 +12,3 @@ export declare class MarkdownSegment extends RichSegment<MarkdownSegmentData> {
     render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
 }
 export declare function wrapMarkdownSegment(data: Record<string, unknown>): MarkdownSegment;
-//# sourceMappingURL=markdown-segment.d.ts.map

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

@@ -59,4 +59,3 @@ export function wrapMarkdownSegment(data) {
         fileName: typeof data.fileName === 'string' ? data.fileName : undefined,
     });
 }
-//# sourceMappingURL=markdown-segment.js.map

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

@@ -1,4 +1,3 @@
 /** 将 Markdown 转为可读纯文本（出站 text 降级用） */
 export declare function markdownToPlainText(md: string): string;
 export declare function markdownToHtmlForRender(md: string): string;
-//# sourceMappingURL=markdown-to-text.d.ts.map

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

@@ -25,4 +25,3 @@ export function markdownToHtmlForRender(md) {
         .replace(/>/g, '>');
     return `<pre style="white-space:pre-wrap;font-family:sans-serif;font-size:14px;line-height:1.5;padding:16px;">${escaped}</pre>`;
 }
-//# sourceMappingURL=markdown-to-text.js.map

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

@@ -1,7 +1,7 @@
 import type { MessageElement } from '../../types.js';
 import { type GenerateQrCodeOptions } from '../generated-qrcode.js';
 import { RichSegment } from './base.js';
-import type { RichSegmentRenderContext, RichSegmentRenderResult } from './types.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
 export interface QrcodeSegmentData extends GenerateQrCodeOptions {
     text: string;
     /** process origin 模式终端渲染时使用 */
@@ -16,4 +16,3 @@ export declare class QrcodeSegment extends RichSegment<QrcodeSegmentData> {
 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)[]>;
-//# sourceMappingURL=qrcode-segment.d.ts.map

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

@@ -71,4 +71,3 @@ export async function interpretOriginQrcodeForProcess(content) {
         return out[0];
     return out;
 }
-//# sourceMappingURL=qrcode-segment.js.map

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

@@ -14,4 +14,3 @@ export declare class RichSegmentRegistry {
 export declare const RICH_SEGMENT_FALLBACK_MODE = "origin";
 export declare const richSegmentRegistry: RichSegmentRegistry;
 export declare function registerRichSegmentKind(definition: RichSegmentKindDefinition): void;
-//# sourceMappingURL=registry.d.ts.map

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

@@ -50,4 +50,3 @@ export const richSegmentRegistry = new RichSegmentRegistry();
 export function registerRichSegmentKind(definition) {
     richSegmentRegistry.register(definition);
 }
-//# sourceMappingURL=registry.js.map

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

@@ -1,6 +1,5 @@
 import type { SendContent } from '../../types.js';
-import type { OutboundRichSegmentPolicy, RichSegmentRenderContext } 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>;
-//# sourceMappingURL=resolve.d.ts.map

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

@@ -85,4 +85,3 @@ export async function resolveRichSegments(content, policy, ctx) {
     }
     return packSegments(out);
 }
-//# sourceMappingURL=resolve.js.map

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

@@ -1,5 +1,5 @@
 import { RichSegment } from './base.js';
-import type { RichSegmentRenderContext, RichSegmentRenderResult } from './types.js';
+import { type RichSegmentRenderContext, type RichSegmentRenderResult } from './types.js';
 export interface TtsSegmentData {
     text: string;
     voice?: string;
@@ -11,4 +11,3 @@ export declare class TtsSegment extends RichSegment<TtsSegmentData> {
     render(mode: string, ctx?: RichSegmentRenderContext): Promise<RichSegmentRenderResult>;
 }
 export declare function wrapTtsSegment(data: Record<string, unknown>): TtsSegment;
-//# sourceMappingURL=tts-segment.d.ts.map

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

@@ -49,4 +49,3 @@ export function wrapTtsSegment(data) {
         provider: typeof data.provider === 'string' ? data.provider : undefined,
     });
 }
-//# sourceMappingURL=tts-segment.js.map

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

@@ -82,4 +82,3 @@ export interface RichSegmentCapabilityLoaderOptions {
     logContentChain?: RichSegmentRenderContext['logContentChain'];
 }
 export type RichSegmentCapabilityLoader = (options: RichSegmentCapabilityLoaderOptions) => Promise<unknown>;
-//# sourceMappingURL=types.d.ts.map

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

@@ -15,4 +15,3 @@ export const RICH_SEGMENT_MODE = {
     AUDIO: 'audio',
     VIDEO: 'video',
 };
-//# sourceMappingURL=types.js.map

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

package/lib/built/schedule.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ScheduleFeature — 管理插件注册的内存定时任务
+ */
+import { Feature, FeatureJSON, type ScheduleKind, type HolidayInput, type ScatterInput } from '@zhin.js/kernel';
+export interface ScheduleDescriptor {
+    kind: ScheduleKind | 'every' | 'at';
+    /** 6 段 cron（solar/lunar/workday/freeDay/holiday） */
+    cron?: string;
+    everyMs?: number;
+    atMs?: number;
+    scatterInput?: ScatterInput;
+    holidayInput?: HolidayInput;
+    tz?: string;
+}
+export interface ScheduleHandle {
+    id: string;
+    descriptor: ScheduleDescriptor;
+    dispose: () => void;
+}
+export interface ScheduleContextExtensions {
+    addSchedule(descriptor: ScheduleDescriptor, callback: () => void | Promise<void>, id?: string): () => void;
+}
+declare module '../plugin.js' {
+    namespace Plugin {
+        interface Extensions extends ScheduleContextExtensions {
+        }
+        interface Contexts {
+            schedule: ScheduleFeature;
+        }
+    }
+}
+export declare class ScheduleFeature extends Feature<ScheduleHandle> {
+    readonly name: "schedule";
+    readonly icon = "Clock";
+    readonly desc = "\u65E5\u5386\u8C03\u5EA6";
+    readonly byName: Map<string, ScheduleHandle>;
+    add(handle: ScheduleHandle, pluginName: string): () => void;
+    remove(handle: ScheduleHandle): boolean;
+    get(id: string): ScheduleHandle | undefined;
+    stopAll(): void;
+    getStatus(): Array<{
+        id: string;
+        kind: string;
+        expression?: string;
+        running: boolean;
+        nextExecution: Date | null;
+        plugin: string;
+    }>;
+    dispose(): void;
+    toJSON(pluginName?: string): FeatureJSON;
+    get extensions(): {
+        addSchedule(descriptor: ScheduleDescriptor, callback: () => void | Promise<void>, id?: string): () => void;
+    };
+}

package/lib/built/schedule.js

@@ -0,0 +1,112 @@
+/**
+ * ScheduleFeature — 管理插件注册的内存定时任务
+ */
+import { Feature, ScheduleEngine, getScheduleEngine, setScheduleEngine } from '@zhin.js/kernel';
+function ensureEngine() {
+    let engine = getScheduleEngine();
+    if (!engine) {
+        engine = new ScheduleEngine();
+        setScheduleEngine(engine);
+    }
+    return engine;
+}
+export class ScheduleFeature extends Feature {
+    name = 'schedule';
+    icon = 'Clock';
+    desc = '日历调度';
+    byName = new Map();
+    add(handle, pluginName) {
+        this.byName.set(handle.id, handle);
+        return super.add(handle, pluginName);
+    }
+    remove(handle) {
+        if (!this.byName.has(handle.id) && !this.items.includes(handle)) {
+            return false;
+        }
+        this.byName.delete(handle.id);
+        const removed = super.remove(handle);
+        if (removed) {
+            handle.dispose();
+        }
+        return removed;
+    }
+    get(id) {
+        return this.byName.get(id);
+    }
+    stopAll() {
+        for (const handle of this.items) {
+            handle.dispose();
+        }
+    }
+    getStatus() {
+        const engine = getScheduleEngine();
+        const engineStatus = engine?.getStatus() ?? [];
+        const byId = new Map(engineStatus.map((s) => [s.id, s]));
+        return this.items.map((handle) => {
+            let pluginName = 'unknown';
+            for (const [name, items] of this.pluginItems) {
+                if (items.includes(handle)) {
+                    pluginName = name;
+                    break;
+                }
+            }
+            const st = byId.get(handle.id);
+            return {
+                id: handle.id,
+                kind: handle.descriptor.kind,
+                expression: handle.descriptor.cron,
+                running: st?.running ?? true,
+                nextExecution: st?.nextExecution ?? null,
+                plugin: pluginName,
+            };
+        });
+    }
+    dispose() {
+        this.stopAll();
+    }
+    toJSON(pluginName) {
+        const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+        return {
+            name: this.name,
+            icon: this.icon,
+            desc: this.desc,
+            count: list.length,
+            items: list.map((h) => ({
+                id: h.id,
+                kind: h.descriptor.kind,
+                cron: h.descriptor.cron,
+            })),
+        };
+    }
+    get extensions() {
+        const feature = this;
+        return {
+            addSchedule(descriptor, callback, id) {
+                const plugin = this;
+                const jobId = id ?? `sched_${Math.random().toString(36).slice(2, 10)}`;
+                const engine = ensureEngine();
+                const disposeEngine = engine.register(jobId, descriptor.kind, async () => {
+                    await callback();
+                }, {
+                    cron: descriptor.cron,
+                    everyMs: descriptor.everyMs,
+                    atMs: descriptor.atMs,
+                    scatterInput: descriptor.scatterInput,
+                    holidayInput: descriptor.holidayInput,
+                    tz: descriptor.tz,
+                });
+                const handle = {
+                    id: jobId,
+                    descriptor,
+                    dispose: () => {
+                        disposeEngine();
+                    },
+                };
+                const dispose = feature.add(handle, plugin.name);
+                plugin.recordFeatureContribution(feature.name, jobId);
+                plugin.onDispose(dispose);
+                return dispose;
+            },
+        };
+    }
+}

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

@@ -15,4 +15,3 @@ export declare class SchemaEndpointManager implements EndpointManager {
 }
 export declare function resolveEndpointManager(adapter: Adapter): EndpointManager | null;
 export declare function adapterSupportsProvision(adapter: Adapter): boolean;
-//# sourceMappingURL=schema-endpoint-manager.d.ts.map

package/lib/built/schema-endpoint-manager.js

@@ -71,4 +71,3 @@ export function adapterSupportsProvision(adapter) {
     const manager = resolveEndpointManager(adapter);
     return manager?.supportsProvision() ?? false;
 }
-//# sourceMappingURL=schema-endpoint-manager.js.map

package/lib/built/schema-feature.d.ts

@@ -75,4 +75,3 @@ export declare class SchemaFeature extends Feature<SchemaRecord> {
         }): Required<T>;
     };
 }
-//# sourceMappingURL=schema-feature.d.ts.map

package/lib/built/schema-feature.js

@@ -9,7 +9,6 @@
  *   - Schema.toJSON() 传给前端驱动 PluginConfigForm
  *   - reloadable 标记决定保存后是否自动重载插件
  */
-import { getPlugin } from '../plugin.js';
 import { Feature } from '@zhin.js/kernel';
 // ============================================================================
 // SchemaFeature
@@ -91,7 +90,7 @@ export class SchemaFeature extends Feature {
         const feature = this;
         return {
             declareConfig(key, schema, options) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const reloadable = options?.reloadable ?? true;
                 // 从 Schema 提取默认值
                 const defaults = extractDefaults(schema);
@@ -129,4 +128,3 @@ function extractDefaults(schema) {
     }
     return result;
 }
-//# sourceMappingURL=schema-feature.js.map

package/lib/built/segment-contract/assert.d.ts

@@ -0,0 +1,4 @@
+import type { Segment } from './types.js';
+/** 宽松判断：已知 canonical type 走严格校验；未知 type 仅校验顶层形状（adapter 渐进迁移） */
+export declare function isCanonicalSegment(value: unknown): value is Segment;
+export declare function assertCanonicalSegments(segments: unknown): asserts segments is Segment[];

package/lib/built/segment-contract/assert.js

@@ -0,0 +1,30 @@
+import { isStrictCanonicalSegment } from './validate.js';
+const STRICT_CANONICAL_TYPES = new Set([
+    'text', 'mention', 'image', 'reply', 'forward', 'face', 'dice', 'rps',
+]);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 宽松判断：已知 canonical type 走严格校验；未知 type 仅校验顶层形状（adapter 渐进迁移） */
+export function isCanonicalSegment(value) {
+    if (!isPlainObject(value) || typeof value.type !== 'string')
+        return false;
+    if (!isPlainObject(value.data))
+        return false;
+    if (value.platform !== undefined && !isPlainObject(value.platform))
+        return false;
+    if (!STRICT_CANONICAL_TYPES.has(value.type)) {
+        return true;
+    }
+    return isStrictCanonicalSegment(value);
+}
+export function assertCanonicalSegments(segments) {
+    if (!Array.isArray(segments)) {
+        throw new Error('segments must be an array');
+    }
+    for (let i = 0; i < segments.length; i++) {
+        if (!isCanonicalSegment(segments[i])) {
+            throw new Error(`segment[${i}] is not canonical`);
+        }
+    }
+}

package/lib/built/segment-contract/delivery.d.ts

@@ -0,0 +1,5 @@
+import type { Segment } from './types.js';
+/**
+ * 过滤 agent / AI 出站段，仅保留可经 IM 投递的 canonical 段。
+ */
+export declare function segmentsForImDelivery(segments: readonly unknown[]): Segment[];

package/lib/built/segment-contract/delivery.js

@@ -0,0 +1,40 @@
+import { isCanonicalSegment } from './assert.js';
+/** IM 可见段白名单（thinking / tool_call 等 AI-only 段过滤） */
+const IM_VISIBLE_TYPES = new Set([
+    'text',
+    'mention',
+    'image',
+    'video',
+    'audio',
+    'voice',
+    'record',
+    'file',
+    'face',
+    'reply',
+    'forward',
+    'link',
+    'dice',
+    'rps',
+    'markdown',
+    'html',
+    'qrcode',
+    'tts',
+    'keyboard',
+]);
+const AI_ONLY_TYPES = new Set(['thinking', 'tool_call']);
+/**
+ * 过滤 agent / AI 出站段，仅保留可经 IM 投递的 canonical 段。
+ */
+export function segmentsForImDelivery(segments) {
+    const out = [];
+    for (const item of segments) {
+        if (!isCanonicalSegment(item))
+            continue;
+        if (AI_ONLY_TYPES.has(item.type))
+            continue;
+        if (!IM_VISIBLE_TYPES.has(item.type))
+            continue;
+        out.push(item);
+    }
+    return out;
+}

package/lib/built/segment-contract/image.d.ts

@@ -0,0 +1,5 @@
+import type { MediaRef, Segment } from './types.js';
+export declare function createImageSegment(media: MediaRef, options?: {
+    alt?: string;
+    platform?: Record<string, unknown>;
+}): Segment;

package/lib/built/segment-contract/image.js

@@ -0,0 +1,10 @@
+export function createImageSegment(media, options) {
+    return {
+        type: 'image',
+        data: {
+            media,
+            ...(options?.alt ? { alt: options.alt } : {}),
+        },
+        ...(options?.platform ? { platform: options.platform } : {}),
+    };
+}

package/lib/built/segment-contract/index.d.ts

@@ -0,0 +1,8 @@
+export type { Segment, SegmentBase, MediaRef, TextSegment, MentionSegment, ImageSegment, ReplySegment, ForwardSegment, FaceSegment, DiceSegment, RpsSegment, } from './types.js';
+export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
+export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { segmentsForImDelivery } from './delivery.js';
+export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
+export { createImageSegment } from './image.js';
+export { formatSegmentPreview } from './preview.js';
+export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

package/lib/built/segment-contract/index.js

@@ -0,0 +1,7 @@
+export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
+export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { segmentsForImDelivery } from './delivery.js';
+export { isMediaRef, mediaRefFromLegacyData, mediaRefToLegacyFields } from './media.js';
+export { createImageSegment } from './image.js';
+export { formatSegmentPreview } from './preview.js';
+export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

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

@@ -0,0 +1,8 @@
+import type { MediaRef } from './types.js';
+import { isMediaRef } from './validate.js';
+export { isMediaRef };
+export declare function mediaRefFromLegacyData(data: Record<string, unknown>): MediaRef | undefined;
+export declare function mediaRefToLegacyFields(media: MediaRef): {
+    url?: string;
+    file?: string;
+};

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

@@ -0,0 +1,39 @@
+import { isMediaRef } from './validate.js';
+export { isMediaRef };
+export function mediaRefFromLegacyData(data) {
+    if (isMediaRef(data.media)) {
+        return data.media;
+    }
+    const mimeType = typeof data.mime_type === 'string' ? data.mime_type : undefined;
+    const base64 = typeof data.base64 === 'string' && data.base64.trim()
+        ? data.base64.trim()
+        : typeof data.data === 'string' && data.data.trim() && !String(data.data).startsWith('http')
+            ? data.data.trim()
+            : undefined;
+    if (base64) {
+        return { kind: 'base64', value: base64, ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
+    const raw = [data.url, data.file, data.src, data.href]
+        .find((v) => typeof v === 'string' && v.trim().length > 0);
+    if (!raw)
+        return undefined;
+    const value = raw.trim();
+    if (value.startsWith('base64://')) {
+        return { kind: 'base64', value: value.slice('base64://'.length), ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
+    if (value.startsWith('http://') || value.startsWith('https://')) {
+        return { kind: 'url', value, ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
+    if (value.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(value)) {
+        return { kind: 'path', value, ...(mimeType ? { mime_type: mimeType } : {}) };
+    }
+    return { kind: 'url', value, ...(mimeType ? { mime_type: mimeType } : {}) };
+}
+export function mediaRefToLegacyFields(media) {
+    if (media.kind === 'url')
+        return { url: media.value, file: media.value };
+    if (media.kind === 'path')
+        return { file: media.value, url: media.value };
+    const encoded = media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    return { file: encoded, url: encoded };
+}

package/lib/built/segment-contract/mention.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical mention field readers (SSOT).
+ */
+export declare function readMentionTarget(data: Record<string, unknown> | undefined): string;
+export declare function readMentionName(data: Record<string, unknown> | undefined): string | undefined;
+/** Resolve @ target from at / mention segment. */
+export declare function readMentionSegmentTarget(seg: {
+    type: unknown;
+    data?: unknown;
+}): string;

package/lib/built/segment-contract/mention.js

@@ -0,0 +1,26 @@
+/**
+ * Canonical mention field readers (SSOT).
+ */
+export function readMentionTarget(data) {
+    if (!data)
+        return '';
+    const raw = data.target ?? data.user_id ?? data.qq ?? data.id;
+    if (raw === 'all')
+        return 'all';
+    return raw != null ? String(raw) : '';
+}
+export function readMentionName(data) {
+    if (!data)
+        return undefined;
+    const name = data.name ?? data.nickname ?? data.username;
+    return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Resolve @ target from at / mention segment. */
+export function readMentionSegmentTarget(seg) {
+    if (seg.type !== 'at' && seg.type !== 'mention')
+        return '';
+    return readMentionTarget(isRecord(seg.data) ? seg.data : undefined);
+}

package/lib/built/segment-contract/preview.d.ts

@@ -0,0 +1,3 @@
+import type { SegmentBase } from './types.js';
+/** Single canonical segment → compact human-readable preview for logs. */
+export declare function formatSegmentPreview(item: SegmentBase): string;