@zhin.js/core 1.3.2 → 1.3.4

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 { mediaRefFromLegacyData } from './media.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 = mediaRefFromLegacyData(data);
+    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/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Canonical Segment SSOT — IM + AI 共用 JSON 形状（snake_case data）。
+ * @see docs/architecture/segment-content-model.md
+ */
+export interface SegmentBase {
+    type: string;
+    data: Record<string, unknown>;
+    platform?: Record<string, unknown>;
+}
+/** 媒体引用占位（完整 schema 随 adapter 迁移补齐） */
+export interface MediaRef {
+    kind: 'url' | 'path' | 'base64';
+    value: string;
+    mime_type?: string;
+}
+export interface TextSegment extends SegmentBase {
+    type: 'text';
+    data: {
+        text: string;
+    };
+}
+export interface MentionSegment extends SegmentBase {
+    type: 'mention';
+    data: {
+        target: string;
+        name?: string;
+    };
+}
+export interface ImageSegment extends SegmentBase {
+    type: 'image';
+    data: {
+        media: MediaRef;
+        alt?: string;
+    };
+}
+export interface ReplySegment extends SegmentBase {
+    type: 'reply';
+    data: {
+        message_id: string;
+    };
+}
+export interface ForwardSegment extends SegmentBase {
+    type: 'forward';
+    data: {
+        forward_id: string;
+        title?: string;
+        messages?: Segment[][];
+    };
+}
+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 / reply / forward / face / dice / rps） */
+export type Segment = TextSegment | MentionSegment | ImageSegment | ReplySegment | ForwardSegment | FaceSegment | DiceSegment | RpsSegment | SegmentBase;

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

@@ -0,0 +1,5 @@
+/**
+ * Canonical Segment SSOT — IM + AI 共用 JSON 形状（snake_case data）。
+ * @see docs/architecture/segment-content-model.md
+ */
+export {};

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

@@ -0,0 +1,138 @@
+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;
+}, {
+    kind?: any;
+    value?: string | undefined;
+    mime_type?: string | 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;
+        } | undefined;
+        alt?: string | undefined;
+    } | undefined;
+    platform?: Record<string, any> | undefined;
+}, {
+    type?: "image" | undefined;
+    data?: {
+        media?: {
+            kind?: any;
+            value?: string | undefined;
+            mime_type?: string | undefined;
+        } | undefined;
+        alt?: 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,124 @@
+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'),
+]);
+export const mediaRefSchema = Schema.object({
+    kind: mediaKindSchema.required(),
+    value: Schema.string().required(),
+    mime_type: Schema.string(),
+});
+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 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,
+    },
+    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

@@ -5,9 +5,10 @@ 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 };
-//# sourceMappingURL=speech-loader.d.ts.map

package/lib/built/speech-loader.js

@@ -1,15 +1,20 @@
 import { createWarnOnce, resetWarnOnceForTests } from '@zhin.js/logger';
+import { importOptionalPeerPackage } from './optional-peer-import.js';
 /** 动态 import 时使用的包名（与 @zhin.js/speech package.json 一致） */
 export const SPEECH_PACKAGE = '@zhin.js/speech';
 let cached;
 const speechPeerWarnOnce = createWarnOnce('speech');
+/** zhin 启动时已创建 pipeline 时注入 */
+export function seedSpeechPipeline(pipeline) {
+    cached = pipeline;
+}
 /** 动态加载 @zhin.js/speech；未安装时 warn 一次并返回 undefined */
 export async function loadSpeechPipeline(opts) {
     if (cached !== undefined) {
         return cached ?? undefined;
     }
     try {
-        const mod = await import(SPEECH_PACKAGE);
+        const mod = await importOptionalPeerPackage(SPEECH_PACKAGE);
         const speechConfig = opts?.getConfig?.()?.speech;
         cached = mod.createSpeechPipeline(speechConfig);
         return cached;
@@ -25,4 +30,3 @@ export function resetSpeechLoaderForTests() {
     cached = undefined;
     resetWarnOnceForTests('speech');
 }
-//# sourceMappingURL=speech-loader.js.map

package/lib/built/tool.d.ts

@@ -147,4 +147,3 @@ export declare class ToolFeature extends Feature<Tool> {
     };
 }
 export {};
-//# sourceMappingURL=tool.d.ts.map

package/lib/built/tool.js

@@ -3,7 +3,6 @@
  * 工具仅面向 AI（通过 MCP 注册），不再与 Command 互转
  */
 import { Feature } from "@zhin.js/kernel";
-import { getPlugin } from "../plugin.js";
 import { isBuiltinPermit, isPlatformPermit } from './permit-parse.js';
 import { checkBuiltinPermit } from './permit-check.js';
 import { checkPlatformPermit } from './platform-permit.js';
@@ -386,7 +385,7 @@ export class ToolFeature extends Feature {
         const feature = this;
         return {
             addTool(tool) {
-                const plugin = getPlugin();
+                const plugin = this;
                 const toolObj = isZhinTool(tool) ? tool.toTool() : tool;
                 const dispose = feature.addTool(tool, plugin.name);
                 plugin.recordFeatureContribution(feature.name, toolObj.name);
@@ -396,4 +395,3 @@ export class ToolFeature extends Feature {
         };
     }
 }
-//# sourceMappingURL=tool.js.map

package/lib/command.d.ts

@@ -1,9 +1,9 @@
-import { MatchResult, SegmentMatcher } from "segment-matcher";
-import { AdapterMessage, SendContent } from "./types.js";
-import { RegisteredAdapter } from "./types.js";
-import type { Message } from "./message.js";
-import { MaybePromise } from "./types.js";
-import { Plugin } from "./plugin.js";
+import { MatchResult, SegmentMatcher } from 'segment-matcher';
+import { AdapterMessage, SendContent, RegisteredAdapter, MaybePromise } from './types.js';
+import type { Message } from './message.js';
+import { Plugin } from './plugin.js';
+type ConstructFirstParam<T extends new (...args: any[]) => any> = T extends new (...args: [infer U, ...any[]]) => any ? U : never;
+type ConstructSecondParam<T extends new (...args: any[]) => any> = T extends new (...args: [any, infer V, ...any[]]) => any ? V : never;
 /**
  * MessageCommand类：命令系统核心，基于segment-matcher实现。
  * 支持多平台命令注册、作用域限制、参数解析、异步处理等。
@@ -11,6 +11,7 @@ import { Plugin } from "./plugin.js";
 export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdapter> extends SegmentMatcher {
     #private;
     get helpInfo(): MessageCommand.HelpInfo;
+    constructor(C: ConstructFirstParam<typeof SegmentMatcher>, P?: ConstructSecondParam<typeof SegmentMatcher>);
     get help(): string;
     desc(...desc: string[]): MessageCommand<T>;
     usage(...usage: string[]): MessageCommand<T>;
@@ -21,6 +22,10 @@ export declare class MessageCommand<T extends RegisteredAdapter = RegisteredAdap
      */
     action(callback: MessageCommand.Callback<T>): MessageCommand<T>;
     permit(...permissions: string[]): MessageCommand<T>;
+    /** 命令要求的 permit 列表（空表示所有人可用） */
+    get requiredPermits(): readonly string[];
+    /** 与 handle 一致的 permit 校验，供帮助菜单等场景过滤不可见命令 */
+    checkPermits(message: Message<AdapterMessage<T>>, plugin: Plugin): Promise<boolean>;
     /**
      * 处理消息，自动匹配命令并执行回调
      * @param message 消息对象
@@ -39,4 +44,4 @@ export declare namespace MessageCommand {
         examples: string[];
     };
 }
-//# sourceMappingURL=command.d.ts.map
+export {};