@zhin.js/core 1.3.2 → 1.3.3

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;

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 {};