lark-remote 0.4.0 → 0.4.2

package/dist/inbound/prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * prompt 组装（结构化 `<attachments>` 标签块，设计依据见
+ * `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 输出形态：用户文本（按到达顺序、原样）+ 空行 + 附件块。
+ *
+ *   <用户文本，原样>
+ *
+ *   <attachments>
+ *     <file path="/abs/x.png" kind="image"/>
+ *     <file path="/abs/a.mp4" kind="video" duration="80.9s" name="a.mp4"/>
+ *   </attachments>
+ *
+ * 约定：无附件时 prompt 就是纯文本（与旧行为兼容，缩小回归面）；**绝不输出 file_key**
+ * （对 agent 无意义，且是敏感凭据）。
+ */
+import type { InboundTurn } from './turn.js';
+/** 时长格式化（对齐 SDK 的 formatDuration：80.9s / 3s / 500ms）。 */
+export declare function formatDuration(ms: number): string | undefined;
+export declare function buildPrompt(turn: InboundTurn): string;

package/dist/inbound/prompt.js

@@ -0,0 +1,47 @@
+/**
+ * prompt 组装（结构化 `<attachments>` 标签块，设计依据见
+ * `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 输出形态：用户文本（按到达顺序、原样）+ 空行 + 附件块。
+ *
+ *   <用户文本，原样>
+ *
+ *   <attachments>
+ *     <file path="/abs/x.png" kind="image"/>
+ *     <file path="/abs/a.mp4" kind="video" duration="80.9s" name="a.mp4"/>
+ *   </attachments>
+ *
+ * 约定：无附件时 prompt 就是纯文本（与旧行为兼容，缩小回归面）；**绝不输出 file_key**
+ * （对 agent 无意义，且是敏感凭据）。
+ */
+/** 属性值转义：只处理会破坏引号包裹的字符。 */
+function escapeAttr(value) {
+    return value.replace(/"/g, '&quot;');
+}
+/** 时长格式化（对齐 SDK 的 formatDuration：80.9s / 3s / 500ms）。 */
+export function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        return undefined;
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+export function buildPrompt(turn) {
+    const text = turn.texts.join('\n');
+    if (turn.attachments.length === 0)
+        return text;
+    const lines = turn.attachments.map((att) => {
+        let line = `  <file path="${escapeAttr(att.path)}" kind="${att.kind}"`;
+        const duration = att.durationMs === undefined ? undefined : formatDuration(att.durationMs);
+        if (duration)
+            line += ` duration="${duration}"`;
+        if (att.originalName)
+            line += ` name="${escapeAttr(att.originalName)}"`;
+        return `${line}/>`;
+    });
+    const block = `<attachments>\n${lines.join('\n')}\n</attachments>`;
+    return text === '' ? block : `${text}\n\n${block}`;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/inbound/receipt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 入站回执文案（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 两类回执合并成一条：
+ * 1. 无文本纯附件（决策 2）：不自动起 turn，只回已保存路径 + 引导语；
+ * 2. 拿不到的东西（不支持类型 / 超限 / 下载失败 / 媒体保存已关闭）：明确告知，
+ *    而不是把占位符塞给 agent。
+ *
+ * 用户可见文案指代本程序时只能写 `lark-remote`（AGENTS.md 命名纪律）。
+ */
+import type { PlaceholderKind } from './placeholder.js';
+import type { RejectedItem } from './turn.js';
+/** 单条回执最多列出的文件数；超出折叠为 "… 等 N 个文件"（沿用旧提示口径）。 */
+export declare const MAX_PATHS_IN_RECEIPT = 10;
+/** 「不支持」回执句式（§5.7 表：不支持类型统一「暂不支持 X」）。 */
+export declare function unsupportedReason(kind: PlaceholderKind): string;
+export interface ReceiptInput {
+    /** 本次已落盘的绝对路径（仅无文本场景展示）。 */
+    saved: string[];
+    /** 未处理项（不支持 / 超限 / 失败）。 */
+    rejected: RejectedItem[];
+    /** 本次没有用户文本：附上「说一句话我就开始处理」引导。 */
+    startWorkHint: boolean;
+}
+/**
+ * 生成回执文案；没有任何需要告知的内容时返回 undefined（调用方不发消息）。
+ */
+export declare function buildReceipt(input: ReceiptInput): string | undefined;

package/dist/inbound/receipt.js

@@ -0,0 +1,62 @@
+/**
+ * 入站回执文案（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 两类回执合并成一条：
+ * 1. 无文本纯附件（决策 2）：不自动起 turn，只回已保存路径 + 引导语；
+ * 2. 拿不到的东西（不支持类型 / 超限 / 下载失败 / 媒体保存已关闭）：明确告知，
+ *    而不是把占位符塞给 agent。
+ *
+ * 用户可见文案指代本程序时只能写 `lark-remote`（AGENTS.md 命名纪律）。
+ */
+import path from 'node:path';
+/** 单条回执最多列出的文件数；超出折叠为 "… 等 N 个文件"（沿用旧提示口径）。 */
+export const MAX_PATHS_IN_RECEIPT = 10;
+/** 占位符种类 → 面向人的名称。 */
+const PLACEHOLDER_LABELS = {
+    image: '图片',
+    file: '文件',
+    video: '视频',
+    audio: '语音',
+    sticker: '表情',
+    share: '名片/群分享',
+    location: '位置',
+    folder: '文件夹',
+    vote: '投票',
+    todo: '待办',
+    meeting: '视频会议',
+    calendar: '日程',
+    hongbao: '红包',
+    forwarded: '合并转发',
+    unsupported: '此类',
+    unknown: '未知类型',
+};
+/** 「不支持」回执句式（§5.7 表：不支持类型统一「暂不支持 X」）。 */
+export function unsupportedReason(kind) {
+    return `暂不支持${PLACEHOLDER_LABELS[kind]}消息`;
+}
+/**
+ * 生成回执文案；没有任何需要告知的内容时返回 undefined（调用方不发消息）。
+ */
+export function buildReceipt(input) {
+    const parts = [];
+    if (input.saved.length > 0) {
+        const lines = input.saved.slice(0, MAX_PATHS_IN_RECEIPT).map((p) => `- ${p}`);
+        const overflow = input.saved.length > MAX_PATHS_IN_RECEIPT ? `\n… 等 ${input.saved.length} 个文件` : '';
+        parts.push(`📎 已保存 ${input.saved.length} 个文件：\n${lines.join('\n')}${overflow}`);
+    }
+    if (input.rejected.length > 0) {
+        parts.push(`⚠️ ${input.rejected.map((r) => r.reason).join('；')}`);
+    }
+    if (input.startWorkHint && input.saved.length > 0) {
+        // 保存目录去重（跨分钟时可能落在两个目录，此时全部列出）。
+        const dirs = [...new Set(input.saved.map((p) => path.dirname(p)))];
+        const example = dirs.length === 1
+            ? `请处理 ${dirs[0]} 下的文件`
+            : `请处理以下目录下的文件：${dirs.join('、')}`;
+        parts.push(`💡 说一句话我就开始处理，例如：${example}`);
+    }
+    if (parts.length === 0)
+        return undefined;
+    return parts.join('\n');
+}
+//# sourceMappingURL=receipt.js.map

package/dist/inbound/turn-assembler.d.ts

@@ -0,0 +1,63 @@
+/**
+ * InboundTurnAssembler：统一静默期窗口 + 合并 + 下载等待 + commit。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4/§5.2。
+ *
+ * 规则：
+ * - 任何事件到达 → **重置** 700ms 定时器（按 `userId:chatId` 分桶），保证图/文任意顺序等价；
+ * - 定时器到点 → 若本 turn 仍有 in-flight 下载 → 等待，落定后再 commit；
+ * - 下载失败/超时 → 该项进 `rejected`，然后照常 commit；
+ * - commit → 构造 prompt（`prompt.ts`）→ `onCommit`；
+ * - **无文本且只有附件 → 不 commit**（决策 2），只发 `onReceipt` 回执；
+ * - 命令消息由调用方 `flush()` 强制提交，不等窗口。
+ */
+import type { InboundEvent } from './event.js';
+import { type CommitReason, type InboundTurn } from './turn.js';
+/** 统一静默期窗口（ms）——决策 1：不做「纯文本零延迟」快路径。 */
+export declare const DEFAULT_TURN_WINDOW_MS = 700;
+export interface AssemblerContext {
+    userId: string;
+    chatId: string;
+    messageId: string;
+}
+export interface AssemblerDeps {
+    /** 静默期窗口（毫秒），默认 700。 */
+    windowMs?: number;
+    /** 定时器注入（便于 vitest fake timers / 单元测试确定性）。 */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    /** commit 回调：组装完成的 turn + prompt 交给上层（进 agent）。 */
+    onCommit: (turn: InboundTurn, prompt: string) => void | Promise<void>;
+    /** 回执回调：面向用户的提示（无文本纯附件 / 有 rejected 项）。 */
+    onReceipt?: (ctx: AssemblerContext, text: string) => void | Promise<void>;
+}
+export declare class InboundTurnAssembler {
+    private readonly deps;
+    private readonly buckets;
+    private readonly windowMs;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private disposed;
+    constructor(deps: AssemblerDeps);
+    /** 投递一个入站事件（文本 / 媒体[in-flight] / 拒绝）。 */
+    ingest(event: InboundEvent): void;
+    /**
+     * 强制提交窗口内已装配的内容（命令到达、退出前冲刷）。
+     * 仍有 in-flight 下载时先等它落定（避免丢掉附件路径）。
+     */
+    flush(userId: string, chatId: string, reason?: CommitReason): Promise<void>;
+    /** 冲刷全部窗口（/exit、/restart 干净退出前调用）。 */
+    flushAll(reason?: CommitReason): Promise<void>;
+    /** 进程退出：丢弃定时器，避免悬挂。 */
+    dispose(): void;
+    private ensureBucket;
+    private pushRejected;
+    private armTimer;
+    /**
+     * 登记一次 in-flight 媒体下载：落定后合并结果，并在窗口已到期时触发 commit。
+     * 下载异常（含超时）记入 rejected，不阻断本 turn 的其它内容。
+     */
+    private trackMediaOutcome;
+    private tryCommit;
+    private commit;
+}

package/dist/inbound/turn-assembler.js

@@ -0,0 +1,233 @@
+/**
+ * InboundTurnAssembler：统一静默期窗口 + 合并 + 下载等待 + commit。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4/§5.2。
+ *
+ * 规则：
+ * - 任何事件到达 → **重置** 700ms 定时器（按 `userId:chatId` 分桶），保证图/文任意顺序等价；
+ * - 定时器到点 → 若本 turn 仍有 in-flight 下载 → 等待，落定后再 commit；
+ * - 下载失败/超时 → 该项进 `rejected`，然后照常 commit；
+ * - commit → 构造 prompt（`prompt.ts`）→ `onCommit`；
+ * - **无文本且只有附件 → 不 commit**（决策 2），只发 `onReceipt` 回执；
+ * - 命令消息由调用方 `flush()` 强制提交，不等窗口。
+ */
+import { getLogger } from '../logger/index.js';
+import { isDownloadablePlaceholder } from './placeholder.js';
+import { buildPrompt } from './prompt.js';
+import { buildReceipt, unsupportedReason } from './receipt.js';
+import { bucketKey, } from './turn.js';
+/** 统一静默期窗口（ms）——决策 1：不做「纯文本零延迟」快路径。 */
+export const DEFAULT_TURN_WINDOW_MS = 700;
+export class InboundTurnAssembler {
+    deps;
+    buckets = new Map();
+    windowMs;
+    setTimer;
+    clearTimer;
+    disposed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.windowMs = deps.windowMs ?? DEFAULT_TURN_WINDOW_MS;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    /** 投递一个入站事件（文本 / 媒体[in-flight] / 拒绝）。 */
+    ingest(event) {
+        if (this.disposed) {
+            // 已 dispose（进程收尾）：不再装配，但必须吞掉 in-flight promise 的 rejection，
+            // 否则它会以 unhandledRejection 形式打死进程。
+            if (event.kind === 'media')
+                void event.outcome.catch(() => { });
+            return;
+        }
+        const key = bucketKey(event.userId, event.chatId);
+        const bucket = this.ensureBucket(key, event);
+        if (!bucket.messageIds.includes(event.messageId))
+            bucket.messageIds.push(event.messageId);
+        if (bucket.replyToMessageId === undefined && event.replyToMessageId !== undefined) {
+            bucket.replyToMessageId = event.replyToMessageId;
+        }
+        switch (event.kind) {
+            case 'text': {
+                if (event.text !== '')
+                    bucket.texts.push(event.text);
+                // 可下载占位符（图/文件/视频/语音/表情）由媒体通道处理，不在此记 rejected；
+                // 其余（位置/名片/投票/合并转发/降级态/未知）拿不到，明确回执。
+                for (const kind of event.placeholders) {
+                    if (isDownloadablePlaceholder(kind))
+                        continue;
+                    // 合并转发的子消息文本已被 SDK 渲染（text 非空）→ 只保留文本；
+                    // 附件能不能拿到由媒体通道的 outcome 决定，不在这里重复报「不支持」。
+                    if (kind === 'forwarded' && event.text !== '')
+                        continue;
+                    this.pushRejected(bucket, {
+                        kind,
+                        reason: unsupportedReason(kind),
+                        sourceMsgId: event.messageId,
+                    });
+                }
+                break;
+            }
+            case 'media': {
+                this.trackMediaOutcome(bucket, key, event.messageId, event.outcome);
+                break;
+            }
+            case 'rejected': {
+                this.pushRejected(bucket, {
+                    kind: event.rejectedKind ?? 'unknown',
+                    reason: event.reason,
+                    sourceMsgId: event.messageId,
+                });
+                break;
+            }
+        }
+        this.armTimer(key, bucket);
+    }
+    /**
+     * 强制提交窗口内已装配的内容（命令到达、退出前冲刷）。
+     * 仍有 in-flight 下载时先等它落定（避免丢掉附件路径）。
+     */
+    async flush(userId, chatId, reason = 'flush') {
+        const key = bucketKey(userId, chatId);
+        const bucket = this.buckets.get(key);
+        if (!bucket)
+            return;
+        bucket.windowElapsed = true;
+        bucket.forcedReason = reason;
+        if (bucket.pendingOutcomes.size > 0) {
+            await Promise.all([...bucket.pendingOutcomes]);
+        }
+        await (bucket.commitPromise ?? this.tryCommit(key, reason));
+    }
+    /** 冲刷全部窗口（/exit、/restart 干净退出前调用）。 */
+    async flushAll(reason = 'flush') {
+        const buckets = [...this.buckets.values()];
+        await Promise.all(buckets.map((b) => this.flush(b.userId, b.chatId, reason)));
+    }
+    /** 进程退出：丢弃定时器，避免悬挂。 */
+    dispose() {
+        this.disposed = true;
+        for (const bucket of this.buckets.values()) {
+            if (bucket.timer !== undefined)
+                this.clearTimer(bucket.timer);
+        }
+        this.buckets.clear();
+    }
+    ensureBucket(key, event) {
+        const existing = this.buckets.get(key);
+        if (existing)
+            return existing;
+        const bucket = {
+            userId: event.userId,
+            chatId: event.chatId,
+            texts: [],
+            attachments: [],
+            rejected: [],
+            messageIds: [],
+            pendingOutcomes: new Set(),
+            windowElapsed: false,
+            committed: false,
+        };
+        this.buckets.set(key, bucket);
+        return bucket;
+    }
+    pushRejected(bucket, item) {
+        const dup = bucket.rejected.some((r) => r.sourceMsgId === item.sourceMsgId && r.reason === item.reason);
+        if (!dup)
+            bucket.rejected.push(item);
+    }
+    armTimer(key, bucket) {
+        if (bucket.timer !== undefined)
+            this.clearTimer(bucket.timer);
+        bucket.windowElapsed = false;
+        bucket.timer = this.setTimer(() => {
+            bucket.timer = undefined;
+            bucket.windowElapsed = true;
+            if (bucket.pendingOutcomes.size > 0)
+                return; // 等 in-flight 下载落定
+            void this.tryCommit(key, bucket.forcedReason ?? 'idle');
+        }, this.windowMs);
+    }
+    /**
+     * 登记一次 in-flight 媒体下载：落定后合并结果，并在窗口已到期时触发 commit。
+     * 下载异常（含超时）记入 rejected，不阻断本 turn 的其它内容。
+     */
+    trackMediaOutcome(bucket, key, messageId, outcome) {
+        const tracked = Promise.resolve(outcome)
+            .then((result) => {
+            bucket.attachments.push(...result.attachments);
+            for (const item of result.rejected)
+                this.pushRejected(bucket, item);
+        }, (err) => {
+            this.pushRejected(bucket, {
+                kind: 'file',
+                reason: `下载失败: ${err?.message ?? String(err)}`,
+                sourceMsgId: messageId,
+            });
+        })
+            .then(() => {
+            bucket.pendingOutcomes.delete(tracked);
+            if (bucket.windowElapsed && bucket.pendingOutcomes.size === 0 && !bucket.committed) {
+                void this.tryCommit(key, bucket.forcedReason ?? 'idle');
+            }
+        });
+        bucket.pendingOutcomes.add(tracked);
+    }
+    tryCommit(key, reason) {
+        const bucket = this.buckets.get(key);
+        if (!bucket || bucket.committed)
+            return Promise.resolve();
+        if (bucket.pendingOutcomes.size > 0)
+            return Promise.resolve();
+        bucket.committed = true;
+        this.buckets.delete(key);
+        if (bucket.timer !== undefined) {
+            this.clearTimer(bucket.timer);
+            bucket.timer = undefined;
+        }
+        const promise = this.commit(bucket, reason);
+        bucket.commitPromise = promise;
+        return promise;
+    }
+    async commit(bucket, reason) {
+        const noText = bucket.texts.length === 0;
+        const turn = {
+            userId: bucket.userId,
+            chatId: bucket.chatId,
+            replyToMessageId: bucket.replyToMessageId,
+            texts: bucket.texts,
+            attachments: bucket.attachments,
+            rejected: bucket.rejected,
+            messageIds: bucket.messageIds,
+            commitReason: noText ? 'no-text' : reason,
+        };
+        const ctx = {
+            userId: bucket.userId,
+            chatId: bucket.chatId,
+            messageId: bucket.messageIds[bucket.messageIds.length - 1] ?? '',
+        };
+        try {
+            if (noText) {
+                // 决策 2：纯附件不自动起 turn，只回执并引导用户说一句话。
+                const text = buildReceipt({
+                    saved: bucket.attachments.map((a) => a.path),
+                    rejected: bucket.rejected,
+                    startWorkHint: true,
+                });
+                if (text)
+                    await this.deps.onReceipt?.(ctx, text);
+                return;
+            }
+            await this.deps.onCommit(turn, buildPrompt(turn));
+            if (bucket.rejected.length > 0) {
+                const text = buildReceipt({ saved: [], rejected: bucket.rejected, startWorkHint: false });
+                if (text)
+                    await this.deps.onReceipt?.(ctx, text);
+            }
+        }
+        catch (err) {
+            getLogger().error('[inbound] turn commit failed:', err?.message ?? String(err));
+        }
+    }
+}
+//# sourceMappingURL=turn-assembler.js.map

package/dist/inbound/turn.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 统一入站回合（InboundTurn）模型。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4。
+ * 核心不变量：**一个用户意图 = 一个 turn**，且任何进 agent 的内容都必须已落到本地路径。
+ */
+/** 附件种类（命名/展示语义）。与下载语义 `InboundMediaItem.type` 分离（§5.3）。 */
+export type AttachmentKind = 'image' | 'file' | 'video' | 'audio' | 'sticker';
+export interface InboundAttachment {
+    /** 绝对路径（落盘后位置）。 */
+    path: string;
+    kind: AttachmentKind;
+    /** 来源飞书 messageId：下载凭据的一部分，也是排障锚点。 */
+    sourceMsgId: string;
+    /** 原始文件名（有则保留，用于 prompt 标注与排障）。 */
+    originalName?: string;
+    /** 视频/语音时长（毫秒）。 */
+    durationMs?: number;
+}
+/** 拿不到、不支持、超限、失败的项 —— 需要回执给人（不进 agent）。 */
+export interface RejectedItem {
+    /** 原 msg_type / 占位符种类 / 资源种类。 */
+    kind: string;
+    /** 面向人的说明。 */
+    reason: string;
+    sourceMsgId: string;
+}
+/** 提交原因，用于观测与测试断言。 */
+export type CommitReason = 'idle' | 'timeout' | 'flush' | 'no-text';
+export interface InboundTurn {
+    userId: string;
+    chatId: string;
+    replyToMessageId?: string;
+    /** 用户文本片段，按到达顺序；已剥离结构占位符。 */
+    texts: string[];
+    /** 已落盘的附件（绝对路径），按到达顺序。 */
+    attachments: InboundAttachment[];
+    rejected: RejectedItem[];
+    /** 本 turn 覆盖的飞书 messageId（回执、去重、排障）。 */
+    messageIds: string[];
+    commitReason: CommitReason;
+}
+/** 媒体下载 + 落盘的结果（装配器等待它落定后才 commit）。 */
+export interface MediaOutcome {
+    attachments: InboundAttachment[];
+    rejected: RejectedItem[];
+}
+export declare function bucketKey(userId: string, chatId: string): string;

package/dist/inbound/turn.js

@@ -0,0 +1,10 @@
+/**
+ * 统一入站回合（InboundTurn）模型。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4。
+ * 核心不变量：**一个用户意图 = 一个 turn**，且任何进 agent 的内容都必须已落到本地路径。
+ */
+export function bucketKey(userId, chatId) {
+    return `${userId}:${chatId}`;
+}
+//# sourceMappingURL=turn.js.map