lark-remote 0.4.0 → 0.4.1

package/dist/config/index.js

@@ -48,9 +48,16 @@ const DEFAULTS = {
 export const DEFAULT_STOP_GRACE_MS = DEFAULTS.STOP_GRACE_MS;
 /** Codex app-server turn idle timeout default (minutes). */
 export const DEFAULT_TURN_IDLE_TIMEOUT_MINUTES = DEFAULTS.TURN_IDLE_TIMEOUT_MINUTES;
-/** 入站媒体默认配置（schema 默认与 connector 兜底共用，避免双源漂移）。 */
+/**
+ * 入站媒体默认配置（schema 默认与 connector 兜底共用，避免双源漂移）。
+ *
+ * 单文件上限默认 100MB：50MB 对视频偏小（2026-09-15 事故就是 mp4 被丢弃）。
+ * 注意飞书侧 `type=file` 超过 100MB 必须用 Range 分片下载，而 SDK 的
+ * `downloadResourceToFile` 不分片（必报 234037），所以 100 是实际可用上限
+ * （inbound-message-matrix.md §4.4）。
+ */
 export const DEFAULT_INBOUND_MEDIA_DIR_NAME = '.lark-remote-temp';
-export const DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB = 50;
+export const DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB = 100;
 /** 模型 ID → alias 映射。 */
 export const MODEL_ID_TO_ALIAS = {
     'claude-opus-4-8': 'opus',
@@ -119,7 +126,7 @@ export const CodexConfigSchema = z.object({
     /** App-server connection configuration. */
     appServer: CodexAppServerConfigSchema.optional(),
 });
-/** OpenCode-specific configuration (run mode: opencode run --format json --auto). */
+/** OpenCode-specific configuration (pure ACP mode: `opencode acp` over stdio). */
 const OpencodeConfigSchema = z.object({
     /** Provider ID for the LLM backend (e.g. 'anthropic'). */
     providerID: z.string().default('anthropic'),
@@ -127,6 +134,21 @@ const OpencodeConfigSchema = z.object({
     modelID: z.string().default('claude-sonnet-4-20250514'),
     /** Session mode (opencode agent name): 'build' (default) or 'plan'. */
     mode: z.enum(['build', 'plan']).default('build'),
+    /** ACP sub-configuration. Structurally mirrors kimi: the card exposes
+     *  turnIdleTimeoutMinutes; binary/requestTimeoutMs/idleTtlMs are YAML-only
+     *  engineering params. */
+    acp: z
+        .object({
+        /** Path to opencode binary for ACP mode. */
+        binary: z.string().default('opencode'),
+        /** Request timeout in milliseconds. */
+        requestTimeoutMs: z.number().int().min(0).default(60000),
+        /** Idle TTL for ACP connection in milliseconds. */
+        idleTtlMs: z.number().int().min(0).default(1800000),
+        /** Turn idle timeout in minutes (0 disables). */
+        turnIdleTimeoutMinutes: z.number().int().min(0).default(DEFAULT_TURN_IDLE_TIMEOUT_MINUTES),
+    })
+        .optional(),
 });
 /** Pi-specific configuration. pi is a spawn-per-message CLI like Claude. */
 const PiConfigSchema = z.object({

package/dist/connector/index.d.ts

@@ -25,6 +25,10 @@ interface FeishuMessage {
     messageId: string;
     chatId: string;
     content: string;
+    /** 飞书原始 msg_type（`text` / `image` / `post` / `merge_forward` …）。 */
+    rawContentType: string;
+    /** 引用消息 id（回复某条消息时存在）。 */
+    replyToMessageId?: string;
 }
 type MessageHandler = (msg: FeishuMessage) => void;
 /**
@@ -33,12 +37,19 @@ type MessageHandler = (msg: FeishuMessage) => void;
  * （bridge 负责把这些失败提示回用户）。
  */
 export interface InboundMediaItem {
-    /** 资源类型：image 消息按 MIME 生成 image_<HHmmss>_<n>.<ext>，file 保留文件名。 */
+    /**
+     * 下载 type（飞书 `im.v1.messageResource.get` 只认 image/file 两个值，
+     * 见 inbound-message-matrix.md §4 —— 不要扩展成 video/audio/sticker）。
+     */
     type: 'image' | 'file';
+    /** 资源种类（image/file/video/audio/sticker）：命名/展示语义，与下载 type 分离。 */
+    kind: InboundResourceKind;
     /** 原始文件名（file 消息有；image 消息无，由 bridge 按 MIME 生成）。 */
     fileName?: string;
     /** 服务端 content-type（参数已剥离；可能缺失，bridge 有兜底）。 */
     mimeType?: string;
+    /** 视频/语音时长（毫秒），透传给 prompt 附件块。 */
+    durationMs?: number;
     /**
      * 下载内容所在临时文件（流式落盘，避免大文件全量进堆内存）。
      * 由 bridge 移动到最终位置；任何未移动路径都必须清理该文件。
@@ -46,6 +57,8 @@ export interface InboundMediaItem {
     tempPath: string;
 }
 export interface InboundMediaFailure {
+    /** 资源种类（排障/回执分组用）。 */
+    kind?: InboundResourceKind;
     fileName?: string;
     reason: string;
 }
@@ -62,16 +75,24 @@ export interface InboundMediaPayload {
  * 媒体消息到达的轻量描述（未下载）：供上层先做 owner/配置闸门，
  * 通过后再调 downloadInboundMedia —— 下载发生在认证之后（P1 review 修复）。
  */
+/** SDK 给出的可下载资源种类（`resources[].type`）。 */
+export type InboundResourceKind = 'image' | 'file' | 'audio' | 'video' | 'sticker';
 export interface InboundMediaMessage {
     userId: string;
     chatId: string;
     messageId: string;
+    /** 飞书原始 msg_type（未识别类型时用于 warn，default-deny 而非 default-text）。 */
+    rawContentType: string;
     /** 引用上下文：不同 replyTo 强制拆批。 */
     replyToMessageId?: string;
     resources: Array<{
+        /** 飞书下载接口 type（只有 image/file 两值）。 */
         type: 'image' | 'file';
+        /** 资源种类（透传 SDK 的 `resources[].type`）。 */
+        kind: InboundResourceKind;
         fileKey: string;
         fileName?: string;
+        durationMs?: number;
     }>;
 }
 type InboundMediaDetectedHandler = (msg: InboundMediaMessage) => void | Promise<void>;

package/dist/connector/index.js

@@ -2,6 +2,7 @@ import { createLarkChannel, } from '@larksuite/channel';
 import { getLogger } from '../logger/index.js';
 import { MAX_FILE_UPLOAD_SIZE } from './file-limits.js';
 import { DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB } from '../config/index.js';
+import { stripPlaceholders } from '../inbound/placeholder.js';
 import { sleep } from '../common/sleep.js';
 import { isTransientTransportError } from '../error-classification.js';
 import axios from 'axios';
@@ -45,8 +46,45 @@ const noKeepAliveAgent = new https.Agent({ keepAlive: false });
  * 详见 design.md §9.8。原地更新逻辑新增按钮时参考该节去重风险分类。
  */
 export const DEDUP_TTL_MS = 300;
+/**
+ * SDK converter 注册表支持的 msg_type（@larksuite/channel 0.3.0 实测）。
+ * 带资源但类型不在其中 = 未来新增类型：照常下载 + warn（default-deny）。
+ */
+const KNOWN_RESOURCE_CONTENT_TYPES = new Set([
+    'text',
+    'post',
+    'image',
+    'file',
+    'audio',
+    'video',
+    'media',
+    'sticker',
+    'interactive',
+    'merge_forward',
+    'share_chat',
+    'share_user',
+    'location',
+    'system',
+    'vote',
+    'todo',
+    'calendar',
+    'general_calendar',
+    'share_calendar_event',
+    'folder',
+    'hongbao',
+    'video_chat',
+]);
 /** 单资源下载超时（毫秒）：SDK 无内置超时，挂起会导致提示丢失 + 残留临时文件。 */
 const RESOURCE_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * 合并转发（merge_forward）的聚合资源缺少 `message_id`，飞书要求 key 与 message_id
+ * 同属一条消息（234003），且合并转发的资源下载本身被列为不支持（234043）。
+ * 自建子消息遍历需要真机验证（inbound-message-matrix.md §5 Step 3），
+ * 在验证完成前下载必然失败的场景给用户可执行的替代方案。
+ */
+const MERGE_FORWARD_HINT = {
+    merge_forward: '（合并转发里的附件暂不支持保存，可逐条转发或直接发送文件）',
+};
 function withTimeout(promise, ms, label) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
@@ -218,21 +256,27 @@ export class FeishuConnector {
         this.channel.on('message', (msg) => {
             if (msg.chatType !== 'p2p')
                 return;
-            // 入站图片/文件：不转发文本内容（图片消息的 content 只是占位文案），
-            // 而是下载资源后交给 bridge 落盘（runner 零改动）。
-            if ((msg.rawContentType === 'image' || msg.rawContentType === 'file') &&
-                msg.resources.length > 0) {
-                // 只上报"媒体到达"，不在此下载：owner/配置闸门在 index.ts 里先执行，
+            // 判据是「是否携带可下载资源」（`msg.resources`），不是 `msg_type` 白名单：
+            // SDK 只为 image/file/audio/video/media/sticker 五类产出非空 resources，
+            // 枚举 msg_type 必然漏（2026-09-15 事故：mp4 被当文本转发给 agent）。
+            // 一条消息可以**同时**产出资源事件与文本事件（post 既有文字又有图），
+            // 由 B3 的装配器合并成同一个 turn。
+            const hasResources = msg.resources.length > 0;
+            if (hasResources) {
+                // 只上报「媒体到达」，不在此下载：owner/配置闸门在 index.ts 里先执行，
                 // 通过后才调用 downloadInboundMedia（避免未认证大文件下载打爆内存）。
                 void this.handleInboundMediaDetected(msg);
-                return;
             }
-            this.onMessage?.({
-                userId: msg.senderId,
-                messageId: msg.messageId,
-                chatId: msg.chatId,
-                content: msg.content,
-            });
+            if (!hasResources || stripPlaceholders(msg.content).clean !== '') {
+                this.onMessage?.({
+                    userId: msg.senderId,
+                    messageId: msg.messageId,
+                    chatId: msg.chatId,
+                    content: msg.content,
+                    rawContentType: msg.rawContentType,
+                    replyToMessageId: msg.replyToMessageId,
+                });
+            }
         });
         this.channel.on('cardAction', (action) => {
             // Return the handler's response (toast / in-place card update) so the
@@ -272,16 +316,26 @@ export class FeishuConnector {
             getLogger().warn('[feishu] inbound media received but no detected handler registered');
             return;
         }
+        // default-deny 但可见：未识别类型（未来 SDK 新增）照常下载，但必须留痕，
+        // 否则会重演「静默降级成占位符」的事故。
+        if (!KNOWN_RESOURCE_CONTENT_TYPES.has(msg.rawContentType)) {
+            getLogger().warn(`[feishu] inbound media with unrecognized msg_type="${msg.rawContentType}" ` +
+                `resources=${msg.resources.length}, downloading anyway`);
+        }
         try {
             await this.onInboundMediaDetected({
                 userId: msg.senderId,
                 chatId: msg.chatId,
                 messageId: msg.messageId,
+                rawContentType: msg.rawContentType,
                 replyToMessageId: msg.replyToMessageId,
                 resources: msg.resources.map((r) => ({
+                    // 下载 type 只有 image/file 两个合法值（传 video/audio/sticker 会 400）。
                     type: r.type === 'image' ? 'image' : 'file',
+                    kind: r.type,
                     fileKey: r.fileKey,
                     fileName: r.fileName,
+                    durationMs: r.durationMs,
                 })),
             });
         }
@@ -307,23 +361,34 @@ export class FeishuConnector {
                 const { contentType, bytesWritten } = await withTimeout(this.channel.downloadResourceToFile(msg.messageId, res.fileKey, res.type, tmpPath), timeoutMs, `downloadResource fileKey=${res.fileKey}`);
                 if (bytesWritten > maxBytes) {
                     silentlyUnlink(tmpPath);
+                    const limitMb = maxBytes / (1024 * 1024);
                     failures.push({
+                        kind: res.kind,
                         fileName: res.fileName,
-                        reason: `超过 ${maxBytes / (1024 * 1024)}MB 大小限制`,
+                        // 飞书侧 >100MB 必须 Range 分片（SDK 不分片），到上限就是下不动：
+                        // 提示写清楚，避免用户以为"再放大上限就能存"（matrix §4.4/§2 #11）。
+                        reason: `超过 ${limitMb}MB 大小限制` +
+                            (limitMb >= 100 ? '（飞书 >100MB 的文件需分片下载，暂不支持）' : ''),
                     });
                     continue;
                 }
                 media.push({
                     type: res.type,
+                    kind: res.kind,
                     fileName: res.fileName,
                     mimeType: contentType,
+                    durationMs: res.durationMs,
                     tempPath: tmpPath,
                 });
             }
             catch (err) {
                 silentlyUnlink(tmpPath);
                 getLogger().warn(`[feishu] downloadResource failed fileKey=${res.fileKey} type=${res.type}:`, err.message);
-                failures.push({ fileName: res.fileName, reason: `下载失败: ${err.message}` });
+                failures.push({
+                    kind: res.kind,
+                    fileName: res.fileName,
+                    reason: `下载失败: ${err.message}${MERGE_FORWARD_HINT[msg.rawContentType] ?? ''}`,
+                });
             }
         }
         return {

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;