@larksuite/openclaw-lark 2025.7.15-beta.0

package/src/messaging/converters/post.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "post" (rich text) message type.
+ *
+ * Preserves structure as Markdown: links as `[text](href)`,
+ * images as `![image](key)`, code blocks, and mention resolution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertPost = void 0;
+const lark_logger_1 = require("../../core/lark-logger.js");
+const content_converter_helpers_1 = require("./content-converter-helpers.js");
+const utils_1 = require("./utils.js");
+const log = (0, lark_logger_1.larkLogger)('converters/post');
+/** Preferred locale order for multi-language post unwrapping. */
+const LOCALE_PRIORITY = ['zh_cn', 'en_us', 'ja_jp'];
+/**
+ * Scan token for native markdown: a code region to SKIP, OR an image to intercept.
+ * Group 1 (code region) matches first so `![alt](key)` inside code is consumed
+ * verbatim and never intercepted:
+ *   - fenced block: ```...``` or ~~~...~~~ (multi-line, lazy)
+ *   - inline span:  ``...`` or `...` (single-line)
+ * Group 2 (alt) + Group 3 (target) are the image when no code region matched.
+ */
+const MD_SCAN_RE = /(```[\s\S]*?```|~~~[\s\S]*?~~~|``[\s\S]*?``|`[^`\n]*`)|!\[([^\]]*)\]\(([^)]+)\)/g;
+/** Feishu image_key prefix (aligned with markdown-style.ts stripInvalidImageKeys & case 'img'). */
+const FEISHU_IMAGE_KEY_RE = /^img_/;
+/**
+ * Inbound native-markdown size ceiling (chars). Guards against pathological
+ * posts (huge tables / deep nesting) blowing up memory/token before the
+ * downstream chunker runs. One order above the outbound chunk magnitude
+ * (outbound default 15000). Tunable; per-account config override is a follow-up.
+ */
+const MAX_INBOUND_MD_LEN = 100_000;
+/**
+ * Unwrap a parsed post object that may be locale-wrapped.
+ *
+ * Feishu post messages come in two shapes:
+ *   - Flat:   `{ title, content }`
+ *   - Locale: `{ zh_cn: { title, content }, en_us: { title, content } }`
+ */
+function unwrapLocale(parsed) {
+    if ('title' in parsed || 'content' in parsed || 'content_v2' in parsed) {
+        return parsed;
+    }
+    for (const locale of LOCALE_PRIORITY) {
+        const localeData = parsed[locale];
+        if (localeData != null && typeof localeData === 'object') {
+            return localeData;
+        }
+    }
+    const firstKey = Object.keys(parsed)[0];
+    if (firstKey) {
+        const firstValue = parsed[firstKey];
+        if (firstValue != null && typeof firstValue === 'object') {
+            return firstValue;
+        }
+    }
+    return undefined;
+}
+const convertPost = (raw, ctx) => {
+    const rawParsed = (0, utils_1.safeParse)(raw);
+    if (rawParsed == null || typeof rawParsed !== 'object') {
+        return { content: '[rich text message]', resources: [] };
+    }
+    const parsed = unwrapLocale(rawParsed);
+    if (!parsed) {
+        return { content: '[rich text message]', resources: [] };
+    }
+    const resources = [];
+    const lines = [];
+    const seenFileKeys = new Set();
+    // Title
+    if (parsed.title) {
+        lines.push(`**${parsed.title}**`, '');
+    }
+    const v2 = parsed.content_v2;
+    const usedV2 = Array.isArray(v2) && v2.length > 0;
+    const contentBlocks = usedV2 ? v2 : (parsed.content ?? []);
+    log.info('post content source selected', {
+        messageId: ctx.messageId,
+        source: usedV2 ? 'content_v2' : 'content',
+        hasV2: Array.isArray(v2),
+        v2Len: Array.isArray(v2) ? v2.length : 0,
+    });
+    for (const paragraph of contentBlocks) {
+        if (!Array.isArray(paragraph))
+            continue;
+        let line = '';
+        for (const el of paragraph) {
+            line += renderElement(el, ctx, resources, seenFileKeys);
+        }
+        lines.push(line);
+    }
+    let content = lines.join('\n').trim() || '[rich text message]';
+    content = (0, content_converter_helpers_1.resolveMentions)(content, ctx);
+    content = capInboundLength(content, resources);
+    return { content, resources };
+};
+exports.convertPost = convertPost;
+function renderElement(el, ctx, resources, seenFileKeys) {
+    switch (el.tag) {
+        case 'text': {
+            let text = el.text ?? '';
+            text = applyStyle(text, el.style);
+            return text;
+        }
+        case 'a': {
+            const text = el.text ?? el.href ?? '';
+            return el.href ? `[${text}](${el.href})` : text;
+        }
+        case 'at': {
+            // At-mention in post — use placeholder key if available via context,
+            // otherwise fall back to @user_name.
+            const userId = el.user_id ?? '';
+            if (userId === 'all')
+                return '@all';
+            const name = el.user_name ?? userId;
+            // O(1) lookup via reverse map
+            const info = ctx.mentionsByOpenId.get(userId);
+            if (info) {
+                // Let resolveMentions handle it — return the placeholder key
+                return info.key;
+            }
+            return `@${name}`;
+        }
+        case 'img': {
+            if (el.image_key) {
+                resources.push({ type: 'image', fileKey: el.image_key });
+                return `![image](${el.image_key})`;
+            }
+            return '';
+        }
+        case 'media': {
+            if (el.file_key) {
+                resources.push({ type: 'file', fileKey: el.file_key });
+                return `<file key="${el.file_key}"/>`;
+            }
+            return '';
+        }
+        case 'md': {
+            return renderInlineImages(el.text ?? '', resources, seenFileKeys);
+        }
+        case 'code_block': {
+            const lang = el.language ?? '';
+            const code = el.text ?? '';
+            return `\n\`\`\`${lang}\n${code}\n\`\`\`\n`;
+        }
+        case 'hr':
+            return '\n---\n';
+        default:
+            return el.text ?? '';
+    }
+}
+function applyStyle(text, style) {
+    if (!style || style.length === 0)
+        return text;
+    let result = text;
+    if (style.includes('bold'))
+        result = `**${result}**`;
+    if (style.includes('italic'))
+        result = `*${result}*`;
+    if (style.includes('underline'))
+        result = `<u>${result}</u>`;
+    if (style.includes('lineThrough'))
+        result = `~~${result}~~`;
+    if (style.includes('codeInline'))
+        result = `\`${result}\``;
+    return result;
+}
+/**
+ * Scan native markdown for `![alt](target)` and intercept feishu image_keys.
+ * - target matches `^img_` → register a downloadable resource (Set-deduped) and
+ *   normalize the FIRST occurrence to `![image](key)` (the only form
+ *   substituteMediaPaths can replace); later occurrences of the same key collapse
+ *   to sanitized alt text so no bare key / un-replaceable marker leaks downstream.
+ * - everything else (https/http, data:, protocol-relative, relative/anchor) is kept
+ *   verbatim and never downloaded.
+ * Image syntax inside a code region (fenced block or inline span) is left verbatim
+ * and never intercepted — code is shown as-is, not rendered.
+ */
+function renderInlineImages(md, resources, seen) {
+    return md.replace(MD_SCAN_RE, (whole, codeRegion, alt, target) => {
+        if (codeRegion !== undefined) {
+            return whole; // fenced block / inline code → keep verbatim, never intercept
+        }
+        if (!FEISHU_IMAGE_KEY_RE.test(target)) {
+            return whole;
+        }
+        if (!seen.has(target)) {
+            seen.add(target);
+            resources.push({ type: 'image', fileKey: target });
+            return `![image](${target})`;
+        }
+        return sanitizeAlt(alt);
+    });
+}
+/** Strip nested image syntax and bare feishu keys from alt so it cannot be
+ *  re-matched by substituteMediaPaths nor inject UGC markers. */
+function sanitizeAlt(alt) {
+    return alt
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+        .replace(/img_[A-Za-z0-9_-]+/g, '')
+        .trim();
+}
+/**
+ * Cap inbound text length at a safe boundary (never split an `![image](key)`
+ * marker), tag `[truncated]`, and drop image resources whose marker fell off the
+ * end so we never register an orphan download with no in-text marker.
+ */
+function capInboundLength(content, resources) {
+    if (content.length <= MAX_INBOUND_MD_LEN)
+        return content;
+    let cut = content.lastIndexOf('\n', MAX_INBOUND_MD_LEN);
+    if (cut <= 0) {
+        // Single huge line: back off so we never cut inside an image marker.
+        cut = MAX_INBOUND_MD_LEN;
+        const markerStart = content.lastIndexOf('![image](', cut);
+        if (markerStart !== -1) {
+            const markerEnd = content.indexOf(')', markerStart);
+            if (markerEnd === -1 || markerEnd >= cut)
+                cut = markerStart;
+        }
+    }
+    const truncated = `${content.slice(0, cut).replace(/\s+$/, '')}\n[truncated]`;
+    for (let i = resources.length - 1; i >= 0; i--) {
+        const r = resources[i];
+        if (r.type === 'image' && !truncated.includes(`![image](${r.fileKey})`)) {
+            resources.splice(i, 1);
+        }
+    }
+    return truncated;
+}

package/src/messaging/converters/share.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "share_chat" and "share_user" message types.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertShareChat: ContentConverterFn;
+export declare const convertShareUser: ContentConverterFn;

package/src/messaging/converters/share.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "share_chat" and "share_user" message types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertShareUser = exports.convertShareChat = void 0;
+const utils_1 = require("./utils.js");
+const convertShareChat = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const chatId = parsed?.chat_id ?? '';
+    return {
+        content: `<group_card id="${chatId}"/>`,
+        resources: [],
+    };
+};
+exports.convertShareChat = convertShareChat;
+const convertShareUser = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const userId = parsed?.user_id ?? '';
+    return {
+        content: `<contact_card id="${userId}"/>`,
+        resources: [],
+    };
+};
+exports.convertShareUser = convertShareUser;

package/src/messaging/converters/sticker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "sticker" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertSticker: ContentConverterFn;

package/src/messaging/converters/sticker.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "sticker" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertSticker = void 0;
+const utils_1 = require("./utils.js");
+const convertSticker = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const fileKey = parsed?.file_key;
+    if (!fileKey) {
+        return { content: '[sticker]', resources: [] };
+    }
+    return {
+        content: `<sticker key="${fileKey}"/>`,
+        resources: [{ type: 'sticker', fileKey }],
+    };
+};
+exports.convertSticker = convertSticker;

package/src/messaging/converters/system.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "system" message type.
+ *
+ * System messages use a template string with placeholders like
+ * `{from_user}`, `{to_chatters}`, `{divider_text}` that are replaced
+ * with actual values from the message body.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertSystem: ContentConverterFn;

package/src/messaging/converters/system.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "system" message type.
+ *
+ * System messages use a template string with placeholders like
+ * `{from_user}`, `{to_chatters}`, `{divider_text}` that are replaced
+ * with actual values from the message body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertSystem = void 0;
+const utils_1 = require("./utils.js");
+const convertSystem = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    if (!parsed?.template) {
+        return { content: '[system message]', resources: [] };
+    }
+    let content = parsed.template;
+    const replacements = {
+        '{from_user}': parsed.from_user?.length ? parsed.from_user.filter(Boolean).join(', ') : undefined,
+        '{to_chatters}': parsed.to_chatters?.length ? parsed.to_chatters.filter(Boolean).join(', ') : undefined,
+        '{divider_text}': parsed.divider_text?.text,
+    };
+    for (const [placeholder, value] of Object.entries(replacements)) {
+        if (value != null) {
+            content = content.replaceAll(placeholder, value);
+        }
+        else {
+            content = content.replaceAll(placeholder, '');
+        }
+    }
+    return { content: content.trim(), resources: [] };
+};
+exports.convertSystem = convertSystem;

package/src/messaging/converters/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "text" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertText: ContentConverterFn;

package/src/messaging/converters/text.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "text" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertText = void 0;
+const content_converter_helpers_1 = require("./content-converter-helpers.js");
+const utils_1 = require("./utils.js");
+const convertText = (raw, ctx) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const text = parsed?.text ?? raw;
+    const content = (0, content_converter_helpers_1.resolveMentions)(text, ctx);
+    return { content, resources: [] };
+};
+exports.convertText = convertText;

package/src/messaging/converters/todo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "todo" message type.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertTodo: ContentConverterFn;

package/src/messaging/converters/todo.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Converter for "todo" message type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertTodo = void 0;
+const utils_1 = require("./utils.js");
+/** Extract plain text from post-style content blocks. */
+function extractPlainText(content) {
+    const lines = [];
+    for (const paragraph of content) {
+        if (!Array.isArray(paragraph))
+            continue;
+        let line = '';
+        for (const el of paragraph) {
+            if (el.text)
+                line += el.text;
+        }
+        lines.push(line);
+    }
+    return lines.join('\n').trim();
+}
+const convertTodo = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    const parts = [];
+    // Build title from summary.title and summary.content
+    const title = parsed?.summary?.title ?? '';
+    const body = parsed?.summary?.content ? extractPlainText(parsed.summary.content) : '';
+    const fullTitle = [title, body].filter(Boolean).join('\n');
+    if (fullTitle) {
+        parts.push(fullTitle);
+    }
+    if (parsed?.due_time) {
+        parts.push(`Due: ${(0, utils_1.millisToDatetime)(parsed.due_time)}`);
+    }
+    const inner = parts.join('\n') || '[todo]';
+    return {
+        content: `<todo>\n${inner}\n</todo>`,
+        resources: [],
+    };
+};
+exports.convertTodo = convertTodo;

package/src/messaging/converters/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared types for the content converter system.
+ */
+import type { ClawdbotConfig } from 'openclaw/plugin-sdk';
+import type { LarkAccount } from '../../core/types';
+import type { MentionInfo, ResourceDescriptor } from '../types';
+/**
+ * Shape of a message item returned by the Feishu IM API.
+ *
+ * Used by `buildConvertContextFromItem` (content-converter) and the
+ * `merge_forward` converter to process sub-messages and history items
+ * without resorting to `any`.
+ */
+export interface ApiMessageItem {
+    message_id?: string;
+    msg_type?: string;
+    create_time?: string;
+    upper_message_id?: string;
+    body?: {
+        content?: string;
+    };
+    sender?: {
+        id?: string;
+        sender_type?: string;
+    };
+    mentions?: Array<{
+        key: string;
+        id: unknown;
+        name?: string;
+    }>;
+    parent_id?: string;
+    thread_id?: string;
+    deleted?: boolean;
+    updated?: boolean;
+}
+/** Context passed to every converter function. */
+export interface ConvertContext {
+    /** Map from placeholder key ("@_user_X") to structured mention info. */
+    mentions: Map<string, MentionInfo>;
+    /** Reverse map from openId to MentionInfo for O(1) lookup. */
+    mentionsByOpenId: Map<string, MentionInfo>;
+    messageId: string;
+    botOpenId?: string;
+    /** Plugin config — retained for non-converter downstream consumers. */
+    cfg?: ClawdbotConfig;
+    /**
+     * Pre-resolved account — retained for non-converter downstream consumers.
+     * merge_forward no longer reads this; it uses injected callbacks instead.
+     */
+    account?: LarkAccount;
+    /** Account identifier for multi-account setups. */
+    accountId?: string;
+    /** Synchronous lookup of cached user display name by openId. */
+    resolveUserName?: (openId: string) => string | undefined;
+    /**
+     * Async batch name resolution callback.
+     *
+     * Called by merge_forward to resolve sub-message sender names.
+     * The callback should populate whatever cache `resolveUserName` reads from.
+     * All callers must inject this; merge_forward has no internal fallback.
+     */
+    batchResolveNames?: (openIds: string[]) => Promise<void>;
+    /**
+     * Async callback to fetch sub-messages of a merge_forward container.
+     *
+     * Returns the flat items array from the IM API response.
+     * All callers must inject this; merge_forward has no internal fallback
+     * and returns `<forwarded_messages/>` when not provided.
+     */
+    fetchSubMessages?: (messageId: string) => Promise<ApiMessageItem[]>;
+    /**
+     * Recursive dispatcher used by converters such as merge_forward.
+     *
+     * Injected by `convertMessageContent()` so converter modules do not need
+     * to import the main dispatcher directly.
+     */
+    convertMessageContent?: (raw: string, messageType: string, ctx: ConvertContext) => Promise<ConvertResult>;
+    /** 是否删除机器人 mention（事件推送场景=true，历史消息读取=false） */
+    stripBotMentions?: boolean;
+}
+/** Result produced by a converter function. */
+export interface ConvertResult {
+    /** AI-friendly formatted text. */
+    content: string;
+    /** Resource descriptors (images, files, audio, video, stickers). */
+    resources: ResourceDescriptor[];
+}
+/**
+ * Converter function for a single message type.
+ *
+ * May return a ConvertResult synchronously or a Promise for types that
+ * require async operations (e.g. merge_forward expansion via API).
+ */
+export type ContentConverterFn = (raw: string, ctx: ConvertContext) => ConvertResult | Promise<ConvertResult>;
+/**
+ * Element within a Feishu "post" (rich text) content block.
+ *
+ * Shared by the `post` and `todo` converters.
+ */
+export interface PostElement {
+    tag: string;
+    text?: string;
+    href?: string;
+    image_key?: string;
+    file_key?: string;
+    user_id?: string;
+    user_name?: string;
+    style?: string[];
+    language?: string;
+    un_escape?: boolean;
+}

package/src/messaging/converters/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared types for the content converter system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/src/messaging/converters/unknown.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Fallback converter for unsupported message types.
+ */
+import type { ContentConverterFn } from './types';
+export declare const convertUnknown: ContentConverterFn;

package/src/messaging/converters/unknown.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Fallback converter for unsupported message types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertUnknown = void 0;
+const utils_1 = require("./utils.js");
+const convertUnknown = (raw) => {
+    const parsed = (0, utils_1.safeParse)(raw);
+    if (parsed != null && typeof parsed === 'object' && 'text' in parsed) {
+        const text = parsed.text;
+        if (typeof text === 'string')
+            return { content: text, resources: [] };
+    }
+    return { content: '[unsupported message]', resources: [] };
+};
+exports.convertUnknown = convertUnknown;

package/src/messaging/converters/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared utilities for content converters.
+ */
+/** Escape a string for safe use inside a RegExp. */
+export declare function escapeRegExp(str: string): string;
+/**
+ * Safely parse a JSON string, returning undefined on failure.
+ */
+export declare function safeParse(raw: string): unknown | undefined;
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ *
+ * Examples: 1500 → "1.5s", 65000 → "65s"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Convert a millisecond timestamp to "YYYY-MM-DD HH:mm" in UTC+8 (Beijing time).
+ */
+export declare function millisToDatetime(ms: string | number): string;

package/src/messaging/converters/utils.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Copyright (c) 2026 ByteDance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ *
+ * Shared utilities for content converters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeRegExp = escapeRegExp;
+exports.safeParse = safeParse;
+exports.formatDuration = formatDuration;
+exports.millisToDatetime = millisToDatetime;
+/** Escape a string for safe use inside a RegExp. */
+function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Safely parse a JSON string, returning undefined on failure.
+ */
+function safeParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ *
+ * Examples: 1500 → "1.5s", 65000 → "65s"
+ */
+function formatDuration(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 1)
+        return `${ms}ms`;
+    if (Number.isInteger(seconds))
+        return `${seconds}s`;
+    return `${seconds.toFixed(1)}s`;
+}
+/**
+ * Convert a millisecond timestamp to "YYYY-MM-DD HH:mm" in UTC+8 (Beijing time).
+ */
+function millisToDatetime(ms) {
+    const num = Number(ms);
+    if (!Number.isFinite(num))
+        return String(ms);
+    // UTC+8 offset in milliseconds
+    const utc8Offset = 8 * 60 * 60 * 1000;
+    const d = new Date(num + utc8Offset);
+    const year = d.getUTCFullYear();
+    const month = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    const hour = String(d.getUTCHours()).padStart(2, '0');
+    const minute = String(d.getUTCMinutes()).padStart(2, '0');
+    return `${year}-${month}-${day} ${hour}:${minute}`;
+}