lark-remote 0.3.0 → 0.4.1

package/dist/inbound/event.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
+ * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
+ * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，
+ * 窗口到期后等它落定再 commit（§5.2）。
+ */
+import type { PlaceholderKind } from './placeholder.js';
+import type { MediaOutcome } from './turn.js';
+export interface InboundEventBase {
+    userId: string;
+    chatId: string;
+    messageId: string;
+    replyToMessageId?: string;
+    /** 飞书原始 msg_type（`text` / `image` / `post` / `merge_forward` …）。 */
+    rawContentType: string;
+}
+export interface TextInboundEvent extends InboundEventBase {
+    kind: 'text';
+    /** 已剥离结构占位符的文本（可为空串：整条消息都是占位符）。 */
+    text: string;
+    /** 本条消息命中的占位符种类，用于「不支持」回执。 */
+    placeholders: PlaceholderKind[];
+    /** 未知标签（未来 SDK 新增），上层负责 warn。 */
+    unknownTags: string[];
+}
+export interface MediaInboundEvent extends InboundEventBase {
+    kind: 'media';
+    /** 下载 + 落盘结果；装配器在窗口到期后等它落定才 commit。 */
+    outcome: Promise<MediaOutcome>;
+}
+export interface RejectedInboundEvent extends InboundEventBase {
+    kind: 'rejected';
+    /** 面向人的说明（如「入站媒体保存已关闭」）。 */
+    reason: string;
+    /** 拒绝项的 kind（默认 `unknown`）。 */
+    rejectedKind?: string;
+}
+export type InboundEvent = TextInboundEvent | MediaInboundEvent | RejectedInboundEvent;

package/dist/inbound/event.js

@@ -0,0 +1,11 @@
+/**
+ * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
+ * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
+ * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，
+ * 窗口到期后等它落定再 commit（§5.2）。
+ */
+export {};
+//# sourceMappingURL=event.js.map

package/dist/inbound/placeholder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
+ *
+ * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
+ * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
+ *
+ * 规则来源：`docs/zh/architecture/inbound-message-matrix.md` §1 的 22 种 message_type
+ * 实测渲染串。判定顺序**先清洗后判语义**：任何前缀判定都必须发生在剥离之后。
+ *
+ * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
+ * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
+ * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
+ * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ */
+export type PlaceholderKind = 'image' | 'file' | 'video' | 'audio' | 'sticker' | 'share' | 'location' | 'folder' | 'vote' | 'todo' | 'meeting' | 'calendar' | 'hongbao' | 'forwarded' | 'unsupported' | 'unknown';
+export interface StripResult {
+    /** 剥离占位符后的文本（trim 后；forwarded 块只剥标签、保留内部文本）。 */
+    clean: string;
+    /** 命中的占位符种类（去重、保序），用于 rejected 回执与排障。 */
+    kinds: PlaceholderKind[];
+    /** 未知标签（未来 SDK 新增）——必须 warn，防止再次静默漏。 */
+    unknownTags: string[];
+}
+export declare function isDownloadablePlaceholder(kind: PlaceholderKind): boolean;
+export declare function stripPlaceholders(raw: string): StripResult;

package/dist/inbound/placeholder.js

@@ -0,0 +1,149 @@
+/**
+ * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
+ *
+ * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
+ * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
+ *
+ * 规则来源：`docs/zh/architecture/inbound-message-matrix.md` §1 的 22 种 message_type
+ * 实测渲染串。判定顺序**先清洗后判语义**：任何前缀判定都必须发生在剥离之后。
+ *
+ * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
+ * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
+ * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
+ * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ */
+/**
+ * 可下载资源类占位符：这些占位符对应的资源会由媒体通道下载落盘，
+ * 因此文本侧不把它们记成「不支持」（否则图文混排会双重报错）。
+ */
+const DOWNLOADABLE_KINDS = new Set([
+    'image',
+    'file',
+    'video',
+    'audio',
+    'sticker',
+]);
+export function isDownloadablePlaceholder(kind) {
+    return DOWNLOADABLE_KINDS.has(kind);
+}
+/** 协议块哨兵：`<attachments>` 是本项目自己生成的 prompt 附件块，剥离时必须原样保留。 */
+const ATTACHMENT_BLOCK_RE = /<attachments>[\s\S]*?<\/attachments>/g;
+const SENTINEL_PREFIX = '\u0000lark-inbound-att-';
+const SENTINEL_SUFFIX = '\u0000';
+/** 自闭合标签 → kind（`<file key="…" name="…"/>` 等，属性可缺省）。 */
+const SELF_CLOSING_RULES = [
+    [/<file(?:\s[^<>]*)?\/>/g, 'file'],
+    [/<video(?:\s[^<>]*)?\/>/g, 'video'],
+    [/<audio(?:\s[^<>]*)?\/>/g, 'audio'],
+    [/<sticker(?:\s[^<>]*)?\/>/g, 'sticker'],
+    [/<group_card(?:\s[^<>]*)?\/>/g, 'share'],
+    [/<contact_card(?:\s[^<>]*)?\/>/g, 'share'],
+    [/<location(?:\s[^<>]*)?\/>/g, 'location'],
+    [/<folder(?:\s[^<>]*)?\/>/g, 'folder'],
+    [/<hongbao(?:\s[^<>]*)?\/>/g, 'hongbao'],
+];
+/** 整块剥离（含内部内容）的容器标签：内容无用户语义，只作噪声。 */
+const BLOCK_RULES = [
+    [/<vote>[\s\S]*?<\/vote>/g, 'vote'],
+    [/<todo>[\s\S]*?<\/todo>/g, 'todo'],
+    [/<meeting>[\s\S]*?<\/meeting>/g, 'meeting'],
+    [/<calendar_invite>[\s\S]*?<\/calendar_invite>/g, 'calendar'],
+    [/<calendar_share>[\s\S]*?<\/calendar_share>/g, 'calendar'],
+    [/<calendar>[\s\S]*?<\/calendar>/g, 'calendar'],
+];
+/** 图片渲染串：`![image](img_v3_…)` / `![]()`,富文本内嵌图与纯 image 消息同形。 */
+const IMAGE_MD_RE = /!\[(?:image)?\]\([^)]*\)/g;
+/** 合并转发：只剥标签、保留内部文本（子消息文本有语义）。 */
+const FORWARDED_TAG_RE = /<\/?forwarded_messages\s*\/?>/g;
+/** 提及标签：保留内部显示名，不作为占位符上报。 */
+const AT_TAG_RE = /<at(?:\s[^<>]*)?>([\s\S]*?)<\/at>/g;
+/** converter 的降级态（缺 key / 未识别类型 —— 都是纯噪声）。 */
+const BRACKET_FALLBACK_RE = /\[(?:unsupported message|rich text message|interactive card|image|file|video|audio|sticker|system message|folder)\]/g;
+/**
+ * 未知标签兜底：只在「有属性」或「成对闭合」时才剥离。
+ * 要求有属性可显著降低误伤——用户正文里的 `<3`、`a < b`、`<div>` 不会被吃掉。
+ */
+const UNKNOWN_SELF_CLOSING_RE = /<([a-z][a-z0-9_]*)\s[^<>]*\/>/g;
+const UNKNOWN_PAIRED_RE = /<([a-z][a-z0-9_]*)(?:\s[^<>]*)?>[\s\S]*?<\/\1>/g;
+/** 剥离后遗留的连续空行折叠为单空行（属剥离产物，不算对用户文本加工）。 */
+function collapseBlankLines(text) {
+    return text.replace(/\n{3,}/g, '\n\n');
+}
+export function stripPlaceholders(raw) {
+    const kinds = [];
+    const unknownTags = [];
+    /** 是否真的剥离过东西：没有命中时不做任何文本加工（保持用户原文）。 */
+    let stripped = false;
+    // 1. 先把本项目自己的 <attachments> 协议块摘出去，最后原样放回。
+    const protectedBlocks = [];
+    let working = raw.replace(ATTACHMENT_BLOCK_RE, (match) => {
+        const token = `${SENTINEL_PREFIX}${protectedBlocks.length}${SENTINEL_SUFFIX}`;
+        protectedBlocks.push(match);
+        return token;
+    });
+    const hit = (kind) => {
+        stripped = true;
+        if (!kinds.includes(kind))
+            kinds.push(kind);
+    };
+    // 2. 图片渲染串（必须在 forwarded 标签剥离之前，覆盖块内子消息的图）。
+    working = working.replace(IMAGE_MD_RE, () => {
+        hit('image');
+        return '';
+    });
+    // 3. 已知自闭合标签。
+    for (const [re, kind] of SELF_CLOSING_RULES) {
+        working = working.replace(re, () => {
+            hit(kind);
+            return '';
+        });
+    }
+    // 4. 已知容器块（整块剥离）。
+    for (const [re, kind] of BLOCK_RULES) {
+        working = working.replace(re, () => {
+            hit(kind);
+            return '';
+        });
+    }
+    // 5. 合并转发：只剥标签。
+    working = working.replace(FORWARDED_TAG_RE, () => {
+        hit('forwarded');
+        return '';
+    });
+    // 6. 提及标签：保留显示名。
+    working = working.replace(AT_TAG_RE, (_match, inner) => {
+        stripped = true;
+        return inner;
+    });
+    // 7. converter 降级态。
+    working = working.replace(BRACKET_FALLBACK_RE, () => {
+        hit('unsupported');
+        return '';
+    });
+    // 8. 未知标签兜底（未来 SDK 新增类型）：剥离 + 记录 tag 名。
+    working = working.replace(UNKNOWN_SELF_CLOSING_RE, (match, tag) => {
+        hit('unknown');
+        if (!unknownTags.includes(tag))
+            unknownTags.push(tag);
+        return '';
+    });
+    working = working.replace(UNKNOWN_PAIRED_RE, (match, tag) => {
+        hit('unknown');
+        if (!unknownTags.includes(tag))
+            unknownTags.push(tag);
+        return '';
+    });
+    // 9. 放回协议块。
+    if (protectedBlocks.length > 0) {
+        stripped = true;
+        for (let i = 0; i < protectedBlocks.length; i += 1) {
+            working = working.split(`${SENTINEL_PREFIX}${i}${SENTINEL_SUFFIX}`).join(protectedBlocks[i]);
+        }
+    }
+    // 未命中任何占位符时**不做文本加工**（保留原文的连续空行等），
+    // 确保 router.handle 对纯文本消息的转发与原行为逐字一致。
+    const clean = stripped ? collapseBlankLines(working).trim() : working.trim();
+    return { clean, kinds, unknownTags };
+}
+//# sourceMappingURL=placeholder.js.map

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