@cubeai/dsh-feishu-channels 0.0.0-stage → 0.2.0

package/src/engine/deferred-delivery.js

@@ -0,0 +1,260 @@
+import { readFileSync } from 'node:fs';
+import { writeFileAtomicSync } from './atomic-file.js';
+import { KeyedSerialQueue } from './keyed-queue.js';
+import { assistantText } from './assistant-text.js';
+/** 只从精确请求所在回合恢复最终文字，绝不调用模型或重放工具。 */
+export function recoverTurn(events, requestId, skipInterimText = false) {
+    let turn;
+    let matched = false;
+    let target;
+    const replies = [];
+    for (const event of events) {
+        const data = event.data;
+        if (event.type === 'turn/start') {
+            if (matched && data?.turn !== target)
+                return undefined;
+            turn = data?.turn;
+        }
+        if (!matched && event.type === 'user/message' && (data?.id === requestId || data?.source?.rpcId === requestId)) {
+            if (!Number.isSafeInteger(turn))
+                return;
+            matched = true;
+            target = turn;
+        }
+        if (!matched)
+            continue;
+        if (event.type === 'assistant/message' && data?.turn === target && !data?.interrupted) {
+            const text = assistantText(data?.message?.content, skipInterimText);
+            if (text)
+                replies.push(text);
+            if (replies.reduce((size, value) => size + value.length, 0) > 1_000_000)
+                return undefined;
+        }
+        if (event.type === 'turn/end' && data?.turn === target)
+            return { turn: target, text: replies.join('\n\n'), kind: data?.reason?.kind ?? 'unknown' };
+    }
+}
+export class DeferredDelivery {
+    file;
+    entries = [];
+    queue = new KeyedSerialQueue();
+    active = new Set();
+    quarantined = new Set();
+    constructor(file) {
+        this.file = file;
+        if (!file)
+            return;
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.entries))
+                throw new Error('Invalid delivery journal');
+            for (const entry of parsed.entries) {
+                if (typeof entry.id !== 'string' || typeof entry.sessionId !== 'string' || typeof entry.channelId !== 'string'
+                    || typeof entry.message?.chatId !== 'string' || !['dm', 'group'].includes(entry.message.kind)
+                    || !Number.isFinite(entry.createdAt) || !Number.isSafeInteger(entry.offset) || entry.offset < 0
+                    || !['waiting', 'ready', 'sending', 'sent', 'unknown', 'blocked', 'expired', 'rejected'].includes(entry.status)
+                    || (entry.message.userId !== undefined && typeof entry.message.userId !== 'string')
+                    || (entry.turn !== undefined && !Number.isSafeInteger(entry.turn))
+                    || this.entries.some(e => e.id === entry.id)
+                    || (entry.parts !== undefined && (!Array.isArray(entry.parts) || !entry.parts.every((p) => typeof p === 'string') || entry.offset > entry.parts.length))
+                    || (entry.text !== undefined && typeof entry.text !== 'string'))
+                    throw new Error('Invalid delivery record');
+                if (entry.status === 'sending')
+                    entry.status = 'unknown';
+                this.entries.push(entry);
+            }
+            this.flush();
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    flush() { if (this.file)
+        writeFileAtomicSync(this.file, JSON.stringify({ version: 1, entries: this.entries }), 0o600); }
+    list(channelId, message) {
+        return this.entries.filter(e => (!channelId || e.channelId === channelId) && (!message || (e.message.chatId === message.chatId && e.message.kind === (message.kind ?? 'dm') && e.message.userId === message.userId))).map(e => structuredClone(e));
+    }
+    turnEntries(sessionId, turn) {
+        return this.entries.filter(e => e.sessionId === sessionId && e.turn === turn).map(e => ({ ...e, text: undefined, parts: undefined, message: { ...e.message } }));
+    }
+    begin(id, sessionId, channelId, message) {
+        const previous = this.entries;
+        this.entries = this.entries.filter(e => Date.now() - e.createdAt < 7 * 86400_000);
+        while (this.entries.length >= 1000 && this.entries.some(e => ['sent', 'rejected'].includes(e.status)))
+            this.entries.splice(this.entries.findIndex(e => ['sent', 'rejected'].includes(e.status)), 1);
+        if (this.entries.length >= 1000) {
+            this.entries = previous;
+            throw new Error('Delivery journal full; inspect /delivery');
+        }
+        this.entries.push({ id, sessionId, channelId, message: { chatId: message.chatId, userId: message.userId, kind: message.kind ?? 'dm', text: '', addressed: true }, createdAt: Date.now(), status: 'waiting', offset: 0 });
+        try {
+            this.flush();
+        }
+        catch (error) {
+            this.entries = previous;
+            throw error;
+        }
+        this.active.add(id);
+    }
+    reject(id, definite = false) {
+        try {
+            this.patch(id, { status: definite ? 'rejected' : 'unknown' });
+        }
+        catch (error) {
+            this.quarantined.add(id);
+            throw error;
+        }
+        finally {
+            this.active.delete(id);
+        }
+    }
+    patch(id, update) {
+        const entry = this.entries.find(e => e.id === id);
+        if (!entry)
+            return;
+        if (Object.entries(update).every(([key, value]) => Object.is(entry[key], value)))
+            return;
+        const previous = { ...entry };
+        Object.assign(entry, update);
+        try {
+            this.flush();
+        }
+        catch (error) {
+            for (const key of Object.keys(entry))
+                delete entry[key];
+            Object.assign(entry, previous);
+            throw error;
+        }
+    }
+    claim(sessionId, turn, requestId) {
+        for (const e of this.entries)
+            if (e.sessionId === sessionId && e.id === requestId && e.turn === undefined)
+                this.patch(e.id, { turn });
+    }
+    liveStart(sessionId, turn) {
+        const ids = this.entries.filter(e => e.sessionId === sessionId && e.turn === turn && this.active.has(e.id) && !['blocked', 'expired'].includes(e.status)).map(e => e.id);
+        for (const id of ids)
+            this.patch(id, { status: 'unknown' });
+        return ids;
+    }
+    /**
+     * 实时投递收口。`ok` 表示全部确认送达；`rejected` 表示一片都没送到、
+     * 且每次失败都是平台明确拒绝（服务端已应答），此时不存在「可能已送达」
+     * 的歧义，直接置为 `ready`，交回 30s 巡检自动补发。
+     * 其余失败保持 `unknown`，不猜测、不自动重发。
+     */
+    complete(sessionId, turn, ok, rejected = false) {
+        for (const e of this.entries)
+            if (e.sessionId === sessionId && e.turn === turn && this.active.has(e.id)) {
+                // waiting 表示实时路径根本未发送，留给冷读取；unknown 不猜测为失败。
+                if (e.status === 'unknown' && ok)
+                    this.patch(e.id, { status: 'sent' });
+                else if (e.status === 'unknown' && rejected)
+                    this.patch(e.id, { status: 'ready' });
+                this.active.delete(e.id);
+            }
+    }
+    block(channelId) {
+        for (const e of this.entries)
+            if (e.channelId === channelId && !['sent', 'rejected'].includes(e.status))
+                this.patch(e.id, { status: 'blocked' });
+        this.release(undefined, channelId);
+    }
+    coldTurn(sessionId, turn) {
+        return turn !== undefined && this.entries.some(e => e.sessionId === sessionId && e.turn === turn && !this.active.has(e.id));
+    }
+    release(sessionId, channelId) {
+        for (const e of this.entries)
+            if ((!sessionId || e.sessionId === sessionId) && (!channelId || e.channelId === channelId))
+                this.active.delete(e.id);
+    }
+    async recover(id, read, valid, send, chunks, explicit = false) {
+        const sessionId = this.entries.find(e => e.id === id)?.sessionId ?? id;
+        return this.queue.run(sessionId, async () => {
+            const entry = this.entries.find(e => e.id === id);
+            if (!entry || this.active.has(id) || this.quarantined.has(id))
+                return;
+            const originalStatus = entry.status;
+            const pausedRetry = explicit && ['unknown', 'blocked'].includes(originalStatus);
+            if (!pausedRetry && !['waiting', 'ready'].includes(entry.status))
+                return;
+            if (Date.now() - entry.createdAt > 7 * 86400_000) {
+                this.patch(id, { status: 'expired' });
+                return;
+            }
+            if (!valid(entry)) {
+                this.patch(id, { status: 'blocked' });
+                return;
+            }
+            if (!entry.text) {
+                let result;
+                try {
+                    result = await read({ ...entry });
+                }
+                catch (error) {
+                    if (explicit)
+                        return 'unavailable';
+                    throw error;
+                }
+                if (!result)
+                    return explicit ? 'missing' : undefined;
+                if (entry.status !== originalStatus)
+                    return;
+                this.patch(id, { text: result.text, turn: result.turn ?? entry.turn, status: 'ready' });
+            }
+            if (!valid(entry)) {
+                this.patch(id, { status: 'blocked' });
+                return;
+            }
+            const duplicate = this.entries.find(e => e.id !== id && e.sessionId === entry.sessionId && e.turn !== undefined && e.turn === entry.turn && ['sent', 'unknown', 'sending'].includes(e.status));
+            if (duplicate && !explicit) {
+                this.patch(id, { status: duplicate.status === 'sent' ? 'sent' : 'unknown' });
+                return;
+            }
+            if (!entry.parts)
+                this.patch(id, { parts: chunks(entry.text) });
+            const parts = entry.parts;
+            if (!parts.length) {
+                this.patch(id, { status: 'sent' });
+                return;
+            }
+            for (let index = entry.offset; index < parts.length; index++) {
+                if (!valid(entry)) {
+                    this.patch(id, { status: 'blocked' });
+                    return;
+                }
+                this.patch(id, { status: 'sending' });
+                try {
+                    await send(entry, parts[index]);
+                }
+                catch (error) {
+                    // 只有适配器明确确认请求未提交时才保留自动恢复资格。
+                    this.patch(id, { status: error instanceof DeliveryUnavailable ? 'ready' : 'unknown' });
+                    return;
+                }
+                const blocked = entry.status === 'blocked';
+                this.patch(id, { offset: index + 1, status: blocked ? 'blocked' : index + 1 === parts.length ? 'sent' : 'ready' });
+                if (blocked)
+                    return;
+            }
+        });
+    }
+}
+export class DeliveryUnavailable extends Error {
+}
+/**
+ * 渠道显式声明「平台已应答且明确拒收，本次发送没有落地」。
+ * 只有抛出该类型时，引擎才会退避重试并允许自动补发；
+ * 其余错误（超时、网络中断、本地校验或上传失败）一律按「送达未知」处理。
+ */
+export class DeliveryRejected extends Error {
+    name = 'DeliveryRejected';
+}
+/**
+ * 渠道内部分多片发送时，已有分片送达后再被拒收，就不再是「整条未送达」：
+ * 整条重发会让用户看到重复内容，因此退化为结果不明的普通错误。
+ */
+export function afterPartialDelivery(error) {
+    return error instanceof DeliveryRejected ? new Error(error.message, { cause: error }) : error;
+}

package/src/engine/delivery-history.js

@@ -0,0 +1,39 @@
+import { recoverTurn } from './deferred-delivery.js';
+/** 使用 Chat 的冷历史读取接口，不 resolveAgent，不恢复执行。读取窗口有界。 */
+export async function readDeliveryHistory(host, sessionId, requestId, signal, skipInterimText = false) {
+    const reader = host.get('sessionController');
+    if (!reader?.follow)
+        return undefined;
+    const address = { kind: 'session', sessionId };
+    let snapshot;
+    for await (const frame of await reader.follow({ address, maxMessages: 100 }, signal)) {
+        if (frame.type !== 'snapshot')
+            return undefined;
+        snapshot = frame;
+        break;
+    }
+    if (!snapshot)
+        return undefined;
+    let records = snapshot.records;
+    let hasMore = snapshot.hasMore;
+    for (let count = 0; count < 20 && !signal.aborted; count++) {
+        const events = records.flatMap(record => record.type === 'event' && record.event ? [record.event] : []);
+        const result = recoverTurn(events, requestId, skipInterimText);
+        if (result)
+            return result;
+        if (!hasMore || !reader.page)
+            return undefined;
+        const beforeSeq = events[0]?.seq;
+        if (!Number.isSafeInteger(beforeSeq))
+            return undefined;
+        const page = await reader.page({ address, throughSeq: snapshot.cursor, beforeSeq, maxMessages: 100 }, signal);
+        const first = page.records.find(record => record.type === 'event')?.event?.seq;
+        if (first === undefined || first >= beforeSeq)
+            return undefined;
+        records = [...page.records, ...records];
+        if (records.length > 20000)
+            return undefined;
+        hasMore = page.hasMore;
+    }
+    return undefined;
+}

package/src/engine/file-delivery.js

@@ -0,0 +1,215 @@
+import { basename, resolve } from 'node:path';
+import { KeyedSerialQueue } from './keyed-queue.js';
+import { replyText, withReplyLocale } from './command-locale.js';
+import { readLiveSessionHistory } from './session-history.js';
+/** 与 Chat 的成功文件变更规则保持一致；不从助手回复中猜路径。 */
+function mutationPath(name, raw) {
+    if (typeof raw !== 'string')
+        return;
+    let args;
+    try {
+        args = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!args || typeof args !== 'object')
+        return;
+    const path = name === 'str_replace_editor' ? args.path : args.file_path;
+    if (typeof path !== 'string' || !path.trim())
+        return;
+    if (name === 'write' && typeof args.content === 'string')
+        return path;
+    if (name === 'edit' && typeof args.old_string === 'string' && args.old_string.length > 0
+        && typeof args.new_string === 'string' && args.old_string !== args.new_string
+        && (args.replace_all === undefined || typeof args.replace_all === 'boolean'))
+        return path;
+    if (name !== 'str_replace_editor')
+        return;
+    if (args.command === 'create' && typeof args.file_text === 'string')
+        return path;
+    if (args.command === 'str_replace' && typeof args.old_str === 'string' && args.old_str.length > 0
+        && (args.new_str === undefined || typeof args.new_str === 'string'))
+        return path;
+    if (args.command === 'insert' && Number.isInteger(args.insert_line) && args.insert_line >= 0 && typeof args.new_str === 'string')
+        return path;
+}
+/** 只选当前回复所在回合、已成功产生或明确 present 的文件。 */
+export function filesForReply(events, closing) {
+    let end = events.findIndex(event => event === closing || (closing.seq !== undefined && event.seq === closing.seq));
+    if (end < 0)
+        end = events.length;
+    if (closing.surfaceOp !== 'append' || closing.data?.interrupted
+        || closing.data?.message?.content?.some((part) => part.type === 'tool-call'))
+        return;
+    const prefix = events.slice(0, end);
+    const turn = closing.data?.turn;
+    if (!Number.isSafeInteger(turn))
+        return;
+    const calls = new Map();
+    const paths = new Set();
+    for (const event of prefix) {
+        const data = event.data;
+        if (event.type === 'tool/call' && data?.turn === turn) {
+            const path = mutationPath(data.name, data.arguments);
+            if (path && typeof data.callId === 'string')
+                calls.set(data.callId, path);
+        }
+        else if (event.type === 'tool/result' && data?.turn === turn && event.surfaceOp === 'append') {
+            const path = calls.get(data?.message?.source?.callId);
+            if (path && !toolResultFailed(data))
+                paths.add(path);
+        }
+        else if (event.type === 'deliverables/presented' && data?.turn === turn && Array.isArray(data.files)) {
+            for (const file of data.files)
+                if (typeof file?.path === 'string' && file.path.trim())
+                    paths.add(file.path);
+        }
+    }
+    return { turn, paths: [...paths] };
+}
+/** V4 把 isError 放到 message 上；旧日志仍在 tool-result 内容块上。 */
+export function toolResultFailed(data) {
+    if (data?.message?.isError === true)
+        return true;
+    return data?.message?.content?.[0]?.isError === true;
+}
+/** 文件在投递前已被删除（例如同一回合写入后又被清理）不是投递失败：静默跳过，不打扰用户。 */
+export function missingFileError(error) {
+    const code = error?.code;
+    if (typeof code === 'string') {
+        const tail = code.slice(code.lastIndexOf('/') + 1);
+        if (tail === 'not-found')
+            return true;
+    }
+    const message = error instanceof Error ? error.message : '';
+    return message === 'file-not-found';
+}
+/** 复用 Chat 完整文件读取服务，宿主负责路径、文件类型和大小限制。 */
+export class FileDelivery {
+    host;
+    log;
+    queue = new KeyedSerialQueue();
+    sent = new Map();
+    lifetime = new AbortController();
+    constructor(host, log) {
+        this.host = host;
+        this.log = log;
+    }
+    dispose() { this.lifetime.abort(); this.sent.clear(); }
+    deliver(session, closing, target, onContent) {
+        let ok = true;
+        const initial = target();
+        return this.queue.run(String(session.id), async () => {
+            if (this.lifetime.signal.aborted) {
+                ok = false;
+                return;
+            }
+            const selected = filesForReply(readLiveSessionHistory(session) ?? [], closing);
+            if (!selected?.paths.length)
+                return;
+            onContent?.();
+            if (!initial) {
+                ok = false;
+                return;
+            }
+            const key = `${session.id}:${selected.turn}:${initial.channel.id}:${initial.chatId}`;
+            const sent = this.sent.get(key) ?? new Set();
+            this.sent.set(key, sent);
+            if (this.sent.size > 256)
+                this.sent.delete(this.sent.keys().next().value);
+            for (const path of selected.paths) {
+                if (this.lifetime.signal.aborted) {
+                    ok = false;
+                    return;
+                }
+                const current = target();
+                if (!current || current.channel !== initial.channel || current.chatId !== initial.chatId) {
+                    ok = false;
+                    return;
+                }
+                const name = basename(path.replace(/\\/g, '/'));
+                try {
+                    const cwd = session.header?.cwd ?? this.host.get('sandboxPolicy')?.workspaceRoot;
+                    if (!cwd || !current.channel.sendFile)
+                        throw new Error('file-delivery-unavailable');
+                    // 同一文件可能同时以 write 的绝对路径和 present 的相对路径出现。
+                    // 仅规范化去重键，实际读取仍由 Chat 服务校验原始路径。
+                    const identity = resolve(cwd, path);
+                    if (sent.has(identity))
+                        continue;
+                    const signal = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(120_000)]);
+                    const result = await readWorkspaceFile(this.host, String(session.id), cwd, path, signal);
+                    signal.throwIfAborted();
+                    if (!result.eof || result.offset !== 0 || typeof result.data !== 'string')
+                        throw new Error('incomplete-file');
+                    const latest = target();
+                    if (!latest || latest.channel !== initial.channel || latest.chatId !== initial.chatId) {
+                        ok = false;
+                        return;
+                    }
+                    await latest.channel.sendFile(latest.chatId, { name, data: Buffer.from(result.data, 'base64') }, signal);
+                    sent.add(identity);
+                }
+                catch (error) {
+                    if (this.lifetime.signal.aborted) {
+                        ok = false;
+                        return;
+                    }
+                    if (missingFileError(error))
+                        continue;
+                    ok = false;
+                    const code = typeof error?.code === 'string' ? ` code=${error.code}` : '';
+                    this.log(`[${initial.channel.id}] 文件回传失败（${error instanceof Error ? error.name : 'Error'}${code}；敏感详情已隐藏）`);
+                    const latest = target();
+                    if (!latest || latest.channel !== initial.channel || latest.chatId !== initial.chatId) {
+                        ok = false;
+                        return;
+                    }
+                    const text = withReplyLocale(this.host, () => replyText('文件“{0}”未能发送，请在网页 Chat 中打开该文件；也可让助手重新交付。', name));
+                    await initial.channel.send(initial.chatId, text).catch(() => undefined);
+                }
+            }
+        }).then(() => ok).catch(error => { this.log(`[file-delivery] ${error instanceof Error ? error.message : String(error)}`); return false; });
+    }
+}
+/** `readBytes(scope, path, {}, signal)` 不带 range：要么整文件，要么 too-large 抛错，不返回分片。0.1.7-alpha.1、alpha.2 和 rc.1 该分支写的是 `offset: 0, eof: true`。缺字段按完整文件处理；显式 `eof: false` 或非零 offset 仍拒绝。 */
+function encodeFileBytes(result) {
+    const offset = result.offset ?? 0;
+    const eof = result.eof !== false;
+    if (typeof result.data === 'string')
+        return { data: result.data, eof, offset };
+    if (result.data instanceof Uint8Array)
+        return { data: Buffer.from(result.data).toString('base64'), eof, offset };
+    throw new Error('incomplete-file');
+}
+/** 0.1.5 用 readAll；0.1.7 起改为 readBytes({}, 完整文件)；0.1.2-rc.1 没有该服务，走本机 fs。0.1.6 已不在 peer 里，不再单独分支。 */
+async function readWorkspaceFile(host, sessionId, cwd, path, signal) {
+    const files = host.get('workspaceFiles');
+    if (typeof files?.readAll === 'function') {
+        return encodeFileBytes(await files.readAll({ sessionId, workspaceRoot: cwd }, path, signal));
+    }
+    if (typeof files?.readBytes === 'function') {
+        return encodeFileBytes(await files.readBytes({ sessionId, workspaceRoot: cwd }, path, {}, signal));
+    }
+    return readLegacyFile(host, cwd, path, signal);
+}
+/** 旧 Chat 只有本机路径打开；使用宿主 fs，沿用新版完整下载默认 32 MiB 上限。 */
+async function readLegacyFile(host, cwd, path, signal) {
+    const fs = host.get('fs');
+    if (!fs?.readBytes)
+        throw new Error('file-service-unavailable');
+    const limit = 32 * 1024 * 1024;
+    if ((await fs.lstat(path, { cwd }, signal))?.type !== 'file')
+        throw new Error('not-regular-file');
+    const target = await fs.resolve(path, { cwd, signal });
+    const info = await fs.stat(target, signal);
+    if (info?.type !== 'file')
+        throw new Error('not-regular-file');
+    if (info.size !== undefined && info.size > limit)
+        throw new Error('file-too-large');
+    const bytes = await fs.readBytes(target, signal, limit);
+    if (bytes.byteLength > limit)
+        throw new Error('file-too-large');
+    return { data: Buffer.from(bytes).toString('base64'), offset: 0, eof: true };
+}

package/src/engine/file-input.js

@@ -0,0 +1,52 @@
+import { open } from 'node:fs/promises';
+import { replyText } from './command-locale.js';
+import { fileOperation, timeoutSignal } from './abort.js';
+export class FileInputError extends Error {
+}
+export const MAX_INPUT_FILE_BYTES = 20 * 1024 * 1024;
+/** 渠道只提交字节及显示名；持久化、可读范围和模型呈现由 Chat 上传服务决定。 */
+export async function filePromptParts(host, sessionId, media, parent) {
+    const signal = timeoutSignal(120_000, parent);
+    signal.throwIfAborted();
+    const upload = host.get('fileUploads');
+    if (!upload?.uploadStream)
+        throw new FileInputError(replyText('当前 DSH 不支持 Chat 文件输入，请升级到 0.1.5-rc.1 或更新的兼容版本后重新发送。'));
+    if (media.length > 4)
+        throw new FileInputError(replyText('一次最多发送 4 个文件，累计不超过 20 MiB。'));
+    let total = 0;
+    const parts = [];
+    try {
+        for (const file of media) {
+            signal.throwIfAborted();
+            if (file.data && file.data.byteLength > MAX_INPUT_FILE_BYTES - total)
+                throw new Error('file-size');
+            let data = file.data ? Buffer.from(file.data) : undefined;
+            if (!data && file.path) {
+                const handle = await open(file.path, 'r');
+                try {
+                    const stat = await handle.stat();
+                    if (!stat.isFile() || stat.size > MAX_INPUT_FILE_BYTES - total)
+                        throw new Error('file-size');
+                    data = await handle.readFile({ signal });
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            if (!data || !data.length || (total += data.length) > MAX_INPUT_FILE_BYTES)
+                throw new Error('file-size');
+            const value = await fileOperation(upload.uploadStream({ sessionId, name: file.name,
+                data: (async function* () { signal.throwIfAborted(); yield data; })(), signal }), signal);
+            signal.throwIfAborted();
+            if (typeof value.receiptId !== 'string' || !value.receiptId)
+                throw new Error('missing-receipt');
+            parts.push({ type: 'file', receiptId: value.receiptId });
+        }
+        return parts;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        throw new FileInputError(replyText('文件输入失败，整条消息未提交。请检查文件大小和格式后重新发送，或在网页 Chat 上传。'), { cause: error });
+    }
+}

package/src/engine/file-log.js

@@ -0,0 +1,25 @@
+import { appendFile, chmod, rename, rm, stat } from 'node:fs/promises';
+/** 串行异步追加；当前文件超限时只保留一个上一代归档，限定磁盘占用。 */
+export function createRotatingFileAppender(file, maxBytes = 5 * 1024 * 1024) {
+    let queue = Promise.resolve();
+    const write = async (line) => {
+        const bytes = Buffer.byteLength(line);
+        const current = await stat(file).then((value) => value.size).catch(() => 0);
+        if (current > 0 && current + bytes > maxBytes) {
+            const archive = `${file}.1`;
+            await rm(archive, { force: true }).catch(() => undefined);
+            await rename(file, archive).catch((error) => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+        }
+        await appendFile(file, line, { encoding: 'utf8', mode: 0o600 });
+        await chmod(file, 0o600).catch(() => undefined);
+    };
+    return {
+        append(line) {
+            queue = queue.then(() => write(line)).catch(() => undefined);
+        },
+        flush() { return queue; },
+    };
+}