@zhin.js/core 1.1.33 → 1.1.35

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

@@ -0,0 +1,17 @@
+import type { Schema } from '@zhin.js/schema';
+import { Adapter } from '../adapter.js';
+import type { EndpointConfigRecord, EndpointManager, ProvisionContext } from './endpoint-manager.js';
+export declare class SchemaEndpointManager implements EndpointManager {
+    private readonly adapter;
+    private readonly schema;
+    constructor(adapter: Adapter, schema: Schema);
+    supportsProvision(): boolean;
+    listEndpoints(): EndpointConfigRecord[];
+    addEndpoint(ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    editEndpoint(name: string, ctx: ProvisionContext): Promise<EndpointConfigRecord>;
+    removeEndpoint(name: string): Promise<boolean>;
+    startEndpoint(name: string, ctx: ProvisionContext): Promise<void>;
+    stopEndpoint(name: string): Promise<boolean>;
+}
+export declare function resolveEndpointManager(adapter: Adapter): EndpointManager | null;
+export declare function adapterSupportsProvision(adapter: Adapter): boolean;

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

@@ -0,0 +1,73 @@
+import { SchemaInteraction } from '../schema-interaction.js';
+function readConfigEndpoints(root, context) {
+    const configService = root.inject('config');
+    const raw = configService?.getRaw(configService.primaryFile);
+    return (raw?.endpoints ?? []).filter((e) => e.context === context);
+}
+export class SchemaEndpointManager {
+    adapter;
+    schema;
+    constructor(adapter, schema) {
+        this.adapter = adapter;
+        this.schema = schema;
+    }
+    supportsProvision() {
+        return true;
+    }
+    listEndpoints() {
+        return readConfigEndpoints(this.adapter.plugin.root, String(this.adapter.name));
+    }
+    async addEndpoint(ctx) {
+        const interaction = new SchemaInteraction(this.adapter.plugin, ctx.message);
+        await ctx.onStatusUpdate(`请按提示填写 ${String(this.adapter.name)} endpoint 配置：`);
+        const name = await interaction.text('Endpoint id（zhin.config endpoints[].id）：');
+        const fields = await interaction.getValueWithSchema(this.schema);
+        return {
+            context: String(this.adapter.name),
+            id: name.trim(),
+            ...fields,
+        };
+    }
+    async editEndpoint(name, ctx) {
+        const existing = this.listEndpoints().find((e) => e.id === name);
+        if (!existing) {
+            throw new Error(`配置中不存在 ${String(this.adapter.name)}/${name}`);
+        }
+        await ctx.onStatusUpdate(`编辑 ${String(this.adapter.name)}/${name}，留空字段将保留原值。`);
+        const interaction = new SchemaInteraction(this.adapter.plugin, ctx.message);
+        const fields = await interaction.getValueWithSchema(this.schema);
+        return {
+            ...existing,
+            ...fields,
+            context: String(this.adapter.name),
+            id: name,
+        };
+    }
+    async removeEndpoint(name) {
+        return this.listEndpoints().some((e) => e.id === name);
+    }
+    async startEndpoint(name, ctx) {
+        const rec = this.listEndpoints().find((e) => e.id === name);
+        if (!rec)
+            throw new Error(`配置中不存在 ${String(this.adapter.name)}/${name}`);
+        await ctx.onStatusUpdate(`正在连接 ${String(this.adapter.name)}/${name}…`);
+    }
+    async stopEndpoint(name) {
+        return this.adapter.endpoints.has(name);
+    }
+}
+export function resolveEndpointManager(adapter) {
+    const custom = adapter.getEndpointManager?.();
+    if (custom)
+        return custom;
+    const schema = adapter.getEndpointConfigSchema?.() ??
+        adapter.constructor.endpointConfigSchema;
+    if (schema) {
+        return new SchemaEndpointManager(adapter, schema);
+    }
+    return null;
+}
+export function adapterSupportsProvision(adapter) {
+    const manager = resolveEndpointManager(adapter);
+    return manager?.supportsProvision() ?? false;
+}

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,7 @@
+import type { Segment } from './types.js';
+/**
+ * 内建 canonical 类型始终走 schema 严格校验。Core 预留扩展和命名空间扩展
+ * 只承诺稳定顶层形状；裸未知类型会被拒绝，避免拼写错误绕过 canonical 校验。
+ */
+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,39 @@
+import { isStrictCanonicalSegment } from './validate.js';
+const STRICT_CANONICAL_TYPES = new Set([
+    'text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'forward', 'face', 'dice', 'rps',
+]);
+// These are Core-owned wire extensions rather than canonical data types. Keep
+// their gradual contracts isolated here; third-party extensions must be
+// namespaced so a future canonical type cannot silently collide with them.
+const CORE_EXTENSION_TYPES = new Set([
+    'action', 'html', 'keyboard', 'link', 'markdown', 'qrcode', 'record', 'tts', 'voice',
+]);
+const extensionTypePattern = /^[a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)+$/u;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 内建 canonical 类型始终走 schema 严格校验。Core 预留扩展和命名空间扩展
+ * 只承诺稳定顶层形状；裸未知类型会被拒绝，避免拼写错误绕过 canonical 校验。
+ */
+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 isStrictCanonicalSegment(value);
+    return CORE_EXTENSION_TYPES.has(value.type) || extensionTypePattern.test(value.type);
+}
+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,10 @@
+export type { Segment, SegmentBase, MediaRef, TextSegment, MentionSegment, ImageSegment, AudioSegment, VideoSegment, FileSegment, ReplySegment, ForwardSegment, FaceSegment, DiceSegment, RpsSegment, } from './types.js';
+export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, audioSegmentSchema, videoSegmentSchema, fileSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
+export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
+export { segmentsForImDelivery } from './delivery.js';
+export { isMediaRef, collectSegmentMedia, type SegmentMediaRef, } from './media.js';
+export { createImageSegment } from './image.js';
+export { formatSegmentPreview } from './preview.js';
+export { segmentsToPlainText } from './text.js';
+export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

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

@@ -0,0 +1,9 @@
+export { mediaRefSchema, textSegmentSchema, mentionSegmentSchema, imageSegmentSchema, audioSegmentSchema, videoSegmentSchema, fileSegmentSchema, replySegmentSchema, forwardSegmentSchema, faceSegmentSchema, diceSegmentSchema, rpsSegmentSchema, canonicalSegmentSchema, segmentArraySchema, } from './validate.js';
+export { assertCanonicalSegments, isCanonicalSegment } from './assert.js';
+export { mediaRefJsonSchema, outboundSegmentJsonSchema, aiOutboundJsonSchema, STRICT_OUTBOUND_SEGMENT_TYPES, } from './json-schema.js';
+export { segmentsForImDelivery } from './delivery.js';
+export { isMediaRef, collectSegmentMedia, } from './media.js';
+export { createImageSegment } from './image.js';
+export { formatSegmentPreview } from './preview.js';
+export { segmentsToPlainText } from './text.js';
+export { readMentionTarget, readMentionName, readMentionSegmentTarget } from './mention.js';

package/lib/built/segment-contract/json-schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+type JsonSchemaObject = Record<string, unknown>;
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export declare const mediaRefJsonSchema: JsonSchemaObject;
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export declare const STRICT_OUTBOUND_SEGMENT_TYPES: readonly ["text", "mention", "image", "reply", "forward", "face", "dice", "rps"];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export declare const outboundSegmentJsonSchema: JsonSchemaObject;
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export declare const aiOutboundJsonSchema: JsonSchemaObject;
+export {};

package/lib/built/segment-contract/json-schema.js

@@ -0,0 +1,128 @@
+/**
+ * Canonical outbound segment 的 JSON Schema SSOT —— 供 AI structured output
+ * （AI SDK `Output.object({ schema })`）约束模型直接输出 zhin 消息段数组。
+ *
+ * 与 validate.ts（@zhin.js/schema 运行时校验）表达同一组约束的 JSON Schema 形态；
+ * 严格段类型集合必须与 assert.ts 的 STRICT_CANONICAL_TYPES 保持一致
+ * （tests/segment-contract/json-schema.test.ts 有交叉防漂移测试）。
+ *
+ * 注意：解析侧 parseOutboundSegment 对严格段要求 canonical 形态
+ * （如 image 必须携带 data.media: MediaRef），本 schema 与之对齐。
+ */
+const platformJsonSchema = {
+    type: 'object',
+    additionalProperties: true,
+    description: '平台专有字段（一般无需输出）',
+};
+/** MediaRef（canonical 媒体引用）：types.ts 的 MediaRef 接口 */
+export const mediaRefJsonSchema = {
+    type: 'object',
+    properties: {
+        kind: {
+            type: 'string',
+            enum: ['url', 'path', 'base64', 'file'],
+            description: 'url=http(s) 链接；path=本地文件路径；base64=内联 base64 数据；file=平台不透明文件引用（如 Telegram file_id）',
+        },
+        value: { type: 'string', description: '媒体内容：URL / 文件路径 / 纯 base64' },
+        mime_type: { type: 'string', description: '如 image/png、audio/mpeg' },
+    },
+    required: ['kind', 'value'],
+    additionalProperties: false,
+};
+function strictBranch(type, data) {
+    return {
+        type: 'object',
+        properties: {
+            type: { const: type },
+            data,
+            platform: platformJsonSchema,
+        },
+        required: ['type', 'data'],
+        additionalProperties: false,
+    };
+}
+function dataObject(properties, required) {
+    return { type: 'object', properties, required: [...required], additionalProperties: false };
+}
+/** 宽松分支：未纳入严格契约的段类型，仅约束顶层形状（与 isCanonicalSegment 宽松路径一致） */
+const looseBranch = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            enum: ['video', 'audio', 'voice', 'record', 'file', 'link', 'markdown', 'html', 'keyboard', 'action'],
+        },
+        data: { type: 'object' },
+        platform: platformJsonSchema,
+    },
+    required: ['type', 'data'],
+    additionalProperties: false,
+};
+/** 严格段类型集合（SSOT：assert.ts STRICT_CANONICAL_TYPES） */
+export const STRICT_OUTBOUND_SEGMENT_TYPES = [
+    'text', 'mention', 'image', 'reply', 'forward', 'face', 'dice', 'rps',
+];
+/**
+ * 单条 outbound 消息段的 JSON Schema。
+ * 严格段镜像 validate.ts 的 data 约束；宽松段走 generic 分支。
+ */
+export const outboundSegmentJsonSchema = {
+    description: 'zhin 消息段 {type, data, platform?}',
+    anyOf: [
+        strictBranch('text', dataObject({
+            text: { type: 'string', description: '文本内容' },
+        }, ['text'])),
+        strictBranch('mention', dataObject({
+            target: { type: 'string', description: '被 @ 用户的平台 id' },
+            name: { type: 'string' },
+        }, ['target'])),
+        strictBranch('image', dataObject({
+            media: mediaRefJsonSchema,
+            alt: { type: 'string' },
+        }, ['media'])),
+        strictBranch('reply', dataObject({
+            message_id: { type: 'string', description: '被引用消息的平台消息 id' },
+        }, ['message_id'])),
+        strictBranch('forward', dataObject({
+            forward_id: { type: 'string' },
+            title: { type: 'string' },
+            messages: { type: 'array', items: { type: 'array' } },
+        }, ['forward_id'])),
+        strictBranch('face', dataObject({
+            id: { anyOf: [{ type: 'string' }, { type: 'number' }], description: '平台表情 id' },
+            name: { type: 'string' },
+        }, ['id'])),
+        strictBranch('dice', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        strictBranch('rps', dataObject({
+            result: { type: 'number' },
+        }, [])),
+        looseBranch,
+    ],
+};
+/**
+ * AI 结构化出站根对象（ADR 0025 JSON DSL 的 schema 形态）。
+ * 与 parseAiOutboundJson / ZhinAiOutboundPayload 对齐：text、mentions、segments
+ * 均为可选（provider strict 模式兼容性考虑），"至少一项"由 prompt 与下游校验兜底。
+ */
+export const aiOutboundJsonSchema = {
+    type: 'object',
+    properties: {
+        text: {
+            type: 'string',
+            description: '纯文本回复正文；与 segments 至少输出一项。使用 mentions 时必填',
+        },
+        mentions: {
+            type: 'array',
+            items: { type: 'string' },
+            description: '要 @ 的会话成员引用（昵称或 id，由宿主解析为平台账号）；需配合 text 使用',
+        },
+        segments: {
+            type: 'array',
+            items: outboundSegmentJsonSchema,
+            description: 'zhin 消息段数组，如 [{type:"image",data:{media:{kind:"url",value:"https://…"}}},{type:"text",data:{text:"…"}}]',
+        },
+    },
+    additionalProperties: false,
+};

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

@@ -0,0 +1,12 @@
+import type { MediaRef, Segment } from './types.js';
+import { isMediaRef } from './validate.js';
+export { isMediaRef };
+export interface SegmentMediaRef {
+    readonly type: string;
+    readonly media: MediaRef;
+}
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 只认 canonical `data.media`；无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export declare function collectSegmentMedia(segments: readonly Segment[] | undefined): SegmentMediaRef[];

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

@@ -0,0 +1,22 @@
+import { isMediaRef } from './validate.js';
+export { isMediaRef };
+/** 入站段携带媒体引用的段类型（纯文本视图无法承载的信息）。 */
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+/**
+ * 从入站 canonical 段收集媒体引用（image / audio / video / file）。
+ * 只认 canonical `data.media`；无媒体段时返回空数组（调用方无需特判 undefined）。
+ */
+export function collectSegmentMedia(segments) {
+    if (!segments?.length)
+        return [];
+    const out = [];
+    for (const segment of segments) {
+        if (!segment || typeof segment.type !== 'string' || !MEDIA_SEGMENT_TYPES.has(segment.type)) {
+            continue;
+        }
+        const media = segment.data?.media;
+        if (isMediaRef(media))
+            out.push({ type: segment.type, media });
+    }
+    return out;
+}

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;