@zhin.js/core 1.1.34 → 1.1.35

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

@@ -0,0 +1,159 @@
+/**
+ * Canonical Segment[] log / debug preview (SSOT).
+ * @see docs/architecture/segment-content-model.md
+ */
+import { htmlToFallbackText } from '../html-to-text.js';
+import { readMentionName, readMentionTarget } from './mention.js';
+import { isMediaRef } from './validate.js';
+const PREVIEW_MAX = 80;
+function clip(text, max = PREVIEW_MAX) {
+    const normalized = text.trim();
+    if (normalized.length <= max)
+        return normalized;
+    return `${normalized.slice(0, max)}…`;
+}
+function previewMedia(data) {
+    const media = isMediaRef(data.media) ? data.media : undefined;
+    if (!media)
+        return undefined;
+    if (media.kind === 'base64') {
+        const mime = media.mime_type ?? 'data';
+        return `base64:${mime}[${media.value.length}]`;
+    }
+    if (media.kind === 'path') {
+        const base = media.value.split(/[/\\]/).pop() ?? media.value;
+        return clip(base, 48);
+    }
+    return clip(media.value, 60);
+}
+function previewMediaSegment(type, data) {
+    const media = previewMedia(data);
+    const alt = typeof data.alt === 'string'
+        ? data.alt
+        : typeof data.name === 'string'
+            ? data.name
+            : undefined;
+    if (media && alt)
+        return `[${type}:${media} alt=${clip(alt, 24)}]`;
+    if (media)
+        return `[${type}:${media}]`;
+    return `[${type}]`;
+}
+/** Single canonical segment → compact human-readable preview for logs. */
+export function formatSegmentPreview(item) {
+    const { type } = item;
+    const data = item.data ?? {};
+    switch (type) {
+        case 'text':
+            return typeof data.text === 'string' ? data.text : '';
+        case 'mention': {
+            const target = readMentionTarget(data);
+            if (target === 'all')
+                return '@all';
+            const name = readMentionName(data);
+            if (name)
+                return `@${name}`;
+            return `@${target}`;
+        }
+        case 'at': {
+            const target = readMentionTarget(data);
+            const name = readMentionName(data);
+            if (name)
+                return `@${name}`;
+            return `@${target}`;
+        }
+        case 'image':
+        case 'video':
+        case 'audio':
+        case 'voice':
+        case 'record':
+        case 'file':
+            return previewMediaSegment(type, data);
+        case 'face': {
+            const id = data.id ?? data.face_id;
+            const name = typeof data.name === 'string'
+                ? data.name
+                : typeof data.text === 'string'
+                    ? data.text
+                    : undefined;
+            if (id != null && name)
+                return `[face:${id} ${name}]`;
+            if (id != null)
+                return `[face:${id}]`;
+            if (name)
+                return `{face}(${name})`;
+            return '[face]';
+        }
+        case 'reply': {
+            const id = data.message_id ?? data.id;
+            return id ? `↩${id}` : '[reply]';
+        }
+        case 'forward': {
+            const id = data.forward_id ?? data.id;
+            const title = typeof data.title === 'string' ? data.title : undefined;
+            const count = Array.isArray(data.messages) ? data.messages.length : 0;
+            let out = `[forward${id ? `:${id}` : ''}`;
+            if (title)
+                out += ` ${clip(title, 32)}`;
+            if (count > 0)
+                out += ` ×${count}`;
+            return `${out}]`;
+        }
+        case 'link': {
+            const url = typeof data.url === 'string' ? data.url : '';
+            const text = typeof data.text === 'string' ? data.text : '';
+            if (text && url)
+                return clip(`${text} <${url}>`);
+            return clip(url || text || '[link]');
+        }
+        case 'dice':
+            return data.result != null ? `{dice}(${data.result})` : '{dice}';
+        case 'rps':
+            return data.result != null ? `{rps}(${data.result})` : '{rps}';
+        case 'html': {
+            if (typeof data.text === 'string' && data.text)
+                return clip(data.text);
+            if (typeof data.html === 'string') {
+                const stripped = htmlToFallbackText(data.html);
+                return stripped ? clip(`[html] ${stripped}`) : '[html]';
+            }
+            return '[html]';
+        }
+        case 'qrcode': {
+            const text = typeof data.text === 'string' ? data.text : '';
+            return text ? clip(`[qrcode] ${text}`) : '[qrcode]';
+        }
+        case 'markdown': {
+            const text = typeof data.content === 'string'
+                ? data.content
+                : typeof data.text === 'string'
+                    ? data.text
+                    : '';
+            return text ? clip(`[markdown] ${text}`) : '[markdown]';
+        }
+        case 'tts': {
+            const text = typeof data.text === 'string' ? data.text : '';
+            return text ? clip(`[tts] ${text}`) : '[tts]';
+        }
+        case 'keyboard': {
+            const rows = Array.isArray(data.rows)
+                ? data.rows.length
+                : Array.isArray(data.buttons)
+                    ? data.buttons.length
+                    : 0;
+            return rows > 0 ? `[keyboard:${rows}]` : '[keyboard]';
+        }
+        case 'thinking': {
+            const text = typeof data.text === 'string' ? data.text : '';
+            return text ? clip(`[thinking] ${text}`, 60) : '[thinking]';
+        }
+        case 'tool_call': {
+            const name = typeof data.name === 'string' ? data.name : 'tool';
+            return `[tool:${name}]`;
+        }
+        default:
+            if (typeof data.text === 'string' && data.text)
+                return `{${type}}(${clip(data.text)})`;
+            return `{${type}}`;
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { Segment } from './types.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export declare function segmentsToPlainText(segments: readonly Segment[]): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Canonical Segment[] → 纯文本视图（SSOT）。
+ * 入站双轨：结构化段为唯一内部契约，纯文本视图供命令匹配 / AI 兜底消费。
+ * @see docs/architecture/segment-content-model.md
+ */
+import { readMentionName, readMentionTarget } from './mention.js';
+/**
+ * 提取纯文本视图：text 段原文拼接，mention/at 段渲染为 `@name`（无名回退
+ * `@target`，`all` → `@all`）；其余段类型不产生文本（媒体 / 回复等结构化
+ * 信息经 `segments` 轨道消费，不污染命令输入）。
+ */
+export function segmentsToPlainText(segments) {
+    let out = '';
+    for (const segment of segments) {
+        // Segment 含 SegmentBase 兜底成员，type 窄化不能联动窄化 data，统一按字典读
+        const data = segment.data;
+        if (segment.type === 'text') {
+            if (typeof data.text === 'string')
+                out += data.text;
+            continue;
+        }
+        if (segment.type === 'mention' || segment.type === 'at') {
+            const name = readMentionName(data);
+            if (name) {
+                out += `@${name}`;
+                continue;
+            }
+            const target = readMentionTarget(data);
+            if (target)
+                out += `@${target}`;
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,58 @@
+/** Canonical Segment SSOT lives in @zhin.js/im-contract. */
+import type { MediaRef, SegmentBase } from '@zhin.js/im-contract';
+export type { ForwardSegment, MediaRef, MentionSegment, ReplySegment, Segment, SegmentBase, TextSegment, } from '@zhin.js/im-contract';
+/**
+ * 媒体引用占位（全框架唯一媒体表达）。
+ * kind=file：平台侧不透明文件引用（如 Telegram file_id、Milky resource_id），
+ * 非 URL/本地路径，消费方需经平台 API 解析。
+ */
+export interface ImageSegment extends SegmentBase {
+    type: 'image';
+    data: {
+        media: MediaRef;
+        alt?: string;
+    };
+}
+export interface AudioSegment extends SegmentBase {
+    type: 'audio';
+    data: {
+        media: MediaRef;
+        duration?: number;
+    };
+}
+export interface VideoSegment extends SegmentBase {
+    type: 'video';
+    data: {
+        media: MediaRef;
+        duration?: number;
+        alt?: string;
+    };
+}
+export interface FileSegment extends SegmentBase {
+    type: 'file';
+    data: {
+        media: MediaRef;
+        name?: string;
+    };
+}
+export interface FaceSegment extends SegmentBase {
+    type: 'face';
+    data: {
+        id: string | number;
+        name?: string;
+    };
+}
+export interface DiceSegment extends SegmentBase {
+    type: 'dice';
+    data: {
+        result?: number;
+    };
+}
+export interface RpsSegment extends SegmentBase {
+    type: 'rps';
+    data: {
+        result?: number;
+    };
+}
+/** 规范态 segment（严格校验 text / mention / image / audio / video / file / reply / forward / face / dice / rps） */
+export type LegacySpecificSegment = ImageSegment | AudioSegment | VideoSegment | FileSegment | FaceSegment | DiceSegment | RpsSegment;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,229 @@
+import { Schema } from '@zhin.js/schema';
+import type { MediaRef, Segment } from './types.js';
+export declare const mediaRefSchema: Schema<{
+    kind?: any;
+    value?: string | undefined;
+    mime_type?: string | undefined;
+    file_name?: string | undefined;
+    size?: number | undefined;
+}, {
+    kind?: any;
+    value?: string | undefined;
+    mime_type?: string | undefined;
+    file_name?: string | undefined;
+    size?: number | undefined;
+}>;
+export declare const textSegmentSchema: Schema<{
+    type?: "text" | undefined;
+    data?: {
+        text?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "text" | undefined;
+    data?: {
+        text?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const mentionSegmentSchema: Schema<{
+    type?: "mention" | undefined;
+    data?: {
+        target?: string | undefined;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "mention" | undefined;
+    data?: {
+        target?: string | undefined;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const imageSegmentSchema: Schema<{
+    type?: "image" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        alt?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "image" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        alt?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const audioSegmentSchema: Schema<{
+    type?: "audio" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        duration?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "audio" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        duration?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const videoSegmentSchema: Schema<{
+    type?: "video" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        duration?: number | undefined;
+        alt?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "video" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        duration?: number | undefined;
+        alt?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const fileSegmentSchema: Schema<{
+    type?: "file" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "file" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+            file_name?: string | undefined;
+            size?: number | undefined;
+        } | undefined;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const replySegmentSchema: Schema<{
+    type?: "reply" | undefined;
+    data?: {
+        message_id?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "reply" | undefined;
+    data?: {
+        message_id?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const forwardSegmentSchema: Schema<{
+    type?: "forward" | undefined;
+    data?: {
+        forward_id?: string | undefined;
+        title?: string | undefined;
+        messages?: any[][] | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "forward" | undefined;
+    data?: {
+        forward_id?: string | undefined;
+        title?: string | undefined;
+        messages?: any[][] | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const faceSegmentSchema: Schema<{
+    type?: "face" | undefined;
+    data?: {
+        id?: any;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "face" | undefined;
+    data?: {
+        id?: any;
+        name?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const diceSegmentSchema: Schema<{
+    type?: "dice" | undefined;
+    data?: {
+        result?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "dice" | undefined;
+    data?: {
+        result?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const rpsSegmentSchema: Schema<{
+    type?: "rps" | undefined;
+    data?: {
+        result?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "rps" | undefined;
+    data?: {
+        result?: number | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}>;
+export declare const canonicalSegmentSchema: Schema<any, any>;
+export declare const segmentArraySchema: Schema<any[], any[]>;
+export declare function isMediaRef(value: unknown): value is MediaRef;
+/** 严格 canonical 段校验（@zhin.js/schema validate-only） */
+export declare function isStrictCanonicalSegment(value: unknown): value is Segment;

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

@@ -0,0 +1,174 @@
+import { Schema } from '@zhin.js/schema';
+const platformSchema = Schema.dict(Schema.any());
+const mediaKindSchema = Schema.union([
+    Schema.const('url'),
+    Schema.const('path'),
+    Schema.const('base64'),
+    Schema.const('file'),
+]);
+export const mediaRefSchema = Schema.object({
+    kind: mediaKindSchema.required(),
+    value: Schema.string().required(),
+    mime_type: Schema.string(),
+    file_name: Schema.string(),
+    size: Schema.number(),
+});
+export const textSegmentSchema = Schema.object({
+    type: Schema.const('text'),
+    data: Schema.object({ text: Schema.string().required() }).required(),
+    platform: platformSchema,
+});
+export const mentionSegmentSchema = Schema.object({
+    type: Schema.const('mention'),
+    data: Schema.object({
+        target: Schema.string().required(),
+        name: Schema.string(),
+    }).required(),
+    platform: platformSchema,
+});
+export const imageSegmentSchema = Schema.object({
+    type: Schema.const('image'),
+    data: Schema.object({
+        media: mediaRefSchema.required(),
+        alt: Schema.string(),
+    }).required(),
+    platform: platformSchema,
+});
+export const audioSegmentSchema = Schema.object({
+    type: Schema.const('audio'),
+    data: Schema.object({
+        media: mediaRefSchema.required(),
+        duration: Schema.number(),
+    }).required(),
+    platform: platformSchema,
+});
+export const videoSegmentSchema = Schema.object({
+    type: Schema.const('video'),
+    data: Schema.object({
+        media: mediaRefSchema.required(),
+        duration: Schema.number(),
+        alt: Schema.string(),
+    }).required(),
+    platform: platformSchema,
+});
+export const fileSegmentSchema = Schema.object({
+    type: Schema.const('file'),
+    data: Schema.object({
+        media: mediaRefSchema.required(),
+        name: Schema.string(),
+    }).required(),
+    platform: platformSchema,
+});
+export const replySegmentSchema = Schema.object({
+    type: Schema.const('reply'),
+    data: Schema.object({ message_id: Schema.string().required() }).required(),
+    platform: platformSchema,
+});
+export const forwardSegmentSchema = Schema.object({
+    type: Schema.const('forward'),
+    data: Schema.object({
+        forward_id: Schema.string().required(),
+        title: Schema.string(),
+        messages: Schema.list(Schema.list(Schema.any())),
+    }).required(),
+    platform: platformSchema,
+});
+const stringOrNumberSchema = Schema.union([
+    Schema.string(),
+    Schema.number(),
+]);
+export const faceSegmentSchema = Schema.object({
+    type: Schema.const('face'),
+    data: Schema.object({
+        id: stringOrNumberSchema.required(),
+        name: Schema.string(),
+    }).required(),
+    platform: platformSchema,
+});
+export const diceSegmentSchema = Schema.object({
+    type: Schema.const('dice'),
+    data: Schema.object({ result: Schema.number() }).required(),
+    platform: platformSchema,
+});
+export const rpsSegmentSchema = Schema.object({
+    type: Schema.const('rps'),
+    data: Schema.object({ result: Schema.number() }).required(),
+    platform: platformSchema,
+});
+export const canonicalSegmentSchema = Schema.discriminatedUnion('type', {
+    text: {
+        data: Schema.object({ text: Schema.string().required() }).required(),
+        platform: platformSchema,
+    },
+    mention: {
+        data: Schema.object({
+            target: Schema.string().required(),
+            name: Schema.string(),
+        }).required(),
+        platform: platformSchema,
+    },
+    image: {
+        data: Schema.object({
+            media: mediaRefSchema.required(),
+            alt: Schema.string(),
+        }).required(),
+        platform: platformSchema,
+    },
+    audio: {
+        data: Schema.object({
+            media: mediaRefSchema.required(),
+            duration: Schema.number(),
+        }).required(),
+        platform: platformSchema,
+    },
+    video: {
+        data: Schema.object({
+            media: mediaRefSchema.required(),
+            duration: Schema.number(),
+            alt: Schema.string(),
+        }).required(),
+        platform: platformSchema,
+    },
+    file: {
+        data: Schema.object({
+            media: mediaRefSchema.required(),
+            name: Schema.string(),
+        }).required(),
+        platform: platformSchema,
+    },
+    reply: {
+        data: Schema.object({ message_id: Schema.string().required() }).required(),
+        platform: platformSchema,
+    },
+    forward: {
+        data: Schema.object({
+            forward_id: Schema.string().required(),
+            title: Schema.string(),
+            messages: Schema.list(Schema.list(Schema.any())),
+        }).required(),
+        platform: platformSchema,
+    },
+    face: {
+        data: Schema.object({
+            id: stringOrNumberSchema.required(),
+            name: Schema.string(),
+        }).required(),
+        platform: platformSchema,
+    },
+    dice: {
+        data: Schema.object({ result: Schema.number() }).required(),
+        platform: platformSchema,
+    },
+    rps: {
+        data: Schema.object({ result: Schema.number() }).required(),
+        platform: platformSchema,
+    },
+});
+export const segmentArraySchema = Schema.list(canonicalSegmentSchema);
+export function isMediaRef(value) {
+    return mediaRefSchema.safeParse(value).success;
+}
+/** 严格 canonical 段校验（@zhin.js/schema validate-only） */
+export function isStrictCanonicalSegment(value) {
+    return canonicalSegmentSchema.safeParse(value).success;
+}

package/lib/built/skill.d.ts

@@ -118,4 +118,3 @@ export declare class SkillFeature extends Feature<Skill> {
      */
     toJSON(pluginName?: string): FeatureJSON;
 }
-//# sourceMappingURL=skill.d.ts.map

package/lib/built/skill.js

@@ -149,4 +149,3 @@ export class SkillFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=skill.js.map

package/lib/built/speech-loader.d.ts

@@ -0,0 +1,14 @@
+import type { SpeechPipelineForRichSegment } from './rich-segments/types.js';
+/** 动态 import 时使用的包名（与 @zhin.js/speech package.json 一致） */
+export declare const SPEECH_PACKAGE = "@zhin.js/speech";
+export interface LoadSpeechPipelineOptions {
+    getConfig?: () => Record<string, unknown> | undefined;
+    warn?: (message: string) => void;
+}
+/** zhin 启动时已创建 pipeline 时注入 */
+export declare function seedSpeechPipeline(pipeline: SpeechPipelineForRichSegment): void;
+/** 动态加载 @zhin.js/speech；未安装时 warn 一次并返回 undefined */
+export declare function loadSpeechPipeline(opts?: LoadSpeechPipelineOptions): Promise<SpeechPipelineForRichSegment | undefined>;
+/** 测试用：重置加载缓存 */
+export declare function resetSpeechLoaderForTests(): void;
+export type { SpeechPipelineForRichSegment };