lark-remote 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-09-19
+
+### 新增
+
+- **`/ws` `/ls` 列表卡关键词搜索**：两张列表卡各多出一行搜索输入框，输入关键词后**按回车提交**即可筛选。`/ws` 匹配别名或完整路径，`/ls` 只匹配**当前层**条目名（不递归子目录），均大小写不敏感、子串包含；计数与页码一律按过滤后的结果计算。筛选词不落服务端（只随卡片回调 payload 传递，且仅非空时注入），服务端保持零状态，未筛选时的卡片形态与旧版完全一致。筛选态下翻页/刷新/排序/使用/删除会保留关键词，进入其他目录或切换工作目录则清除筛选（换目录后旧关键词没有意义）
+
+### 修复
+
+- **卡片提交指引不再写「点 ✓」**：飞书移动端的 `input` 组件没有提交图标，只有键盘的回车/完成键（真机反馈）。所有用户可见文案统一为「按回车提交」，包括分页页码跳转、别名编辑、指令文本编辑与审批卡的修改意见
+- **取消筛选改走显式按钮**：「清空输入再回车」在部分客户端不会触发回调（官方文档未承诺空串会发回调），实测清空后回车没有反应。现在筛选态下搜索行右侧会出现**「清除筛选」**按钮，走显式标记强制清除，不再依赖「读不到输入值」这一隐式条件
+- **别名编辑卡不再把「留空提交」当删除入口**：同一处隐式条件问题，删除别名统一走列表卡别名旁的 ✕
+
+### 变更
+
+- 卡片布局文档（中英）补齐 CardKit `input` 的三条约束：没有逐键回调所以「边输边过滤」做不到、文案不写「点 ✓」、取消语义要有显式控件；`design.md` 中「input 提交图标」的表述改为「input 提交回传」（图标只是桌面端的一种触发方式）
+- 英文文档补齐 `/ws` `/ls` 关键词搜索：`README.en.md` 与 `docs/en/usage.md` 的命令表和功能段跟上中文口径
+
+## [0.4.1] - 2026-09-18
+
+### 新增
+
+- **入站消息统一处理（图 + 文合并为一个回合）**：图片、文件、视频、语音、表情、富文本内嵌图一律自动保存到当前工作目录（`.lark-remote-temp/<时间目录>/`），附件绝对路径**自动写进 agent 的提示词**，不再需要你把"文件已保存"提示卡整段转述给 agent。同一静默期窗口（700 毫秒）内到达的文字与附件合并成一个回合：先发图再发文字、先发文字再发图，agent 拿到的内容完全相同
+- **附件按种类命名**：视频/语音/表情保留原文件名；无原名时按 MIME 类型或文件头自动补扩展名（`.mp4` / `.opus` / `.gif` 等）
+- **不支持消息类型明确回执**：卡片、位置、投票、日程、合并转发等拿不到内容的消息，回一条"暂不支持"提示，不再把占位符静默塞给 agent；纯附件无文字时只回执"已保存 N 个文件" + 引导语，不自动起回合（避免误耗 token）
+- **`--advance-help` 高级配置参考**：命令行可输出高级配置项说明
+- **OpenCode 配置卡支持回合空闲超时**：`turnIdleTimeoutMinutes`（默认 30 分钟，0 关闭），回合长时间无输出自动结束
+
+### 修复
+
+- **P0：以图片占位符开头的消息被误当 shell 命令执行**：飞书会把"图片 + 文字"合成富文本，图片被渲染成 `![image](…)` 后首字符恰好是 `!`，命中 `!` 命令判定，整段用户消息被送进 shell 执行。现在命令识别有前置条件：仅当消息是纯文本、剥离结构占位符后仍以 `/` 或 `!` 开头时才按命令处理，其余一律按文本转发
+
+### 变更
+
+- `inboundMedia.maxFileSizeMb` 默认值 50 → **100 MB**（更大的飞书文件需要分片下载，SDK 不支持，超限提示里已写明）
+
 ## [0.4.0] - 2026-09-15
 
 ### 新增

package/README.en.md

@@ -108,9 +108,9 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 |---------|-------|----------|
 | `/help` | `/h` | Command list |
 | `/cd <path>` | - | Switch agent working directory (`~`, absolute/relative; clears the session) |
-| `/ls [dir\|file]` | - | Directory/file card; click a directory to browse, click a file ≤30MB to send it to Feishu; paginates beyond 30 entries with a page-number jump input. Passing a file path lists that file itself |
+| `/ls [dir\|file]` | - | Directory/file card; click a directory to browse, click a file ≤30MB to send it to Feishu; paginates beyond 30 entries with a page-number jump input, and current-level entries can be filtered by keyword. Passing a file path lists that file itself |
 | `/download <path>` | `/d` | Send a local file straight to the chat (`~`, absolute/relative paths, 30MB cap) |
-| `/ws save\|use\|remove` | - | Named directory aliases (`/ws` lists by default) |
+| `/ws save\|use\|remove` | - | Named directory aliases (`/ws` lists by default, filterable by alias name or path keyword) |
 | `/resume [agent] [N\|id]` | `/r` | List/switch agent sessions for the current directory (card) |
 | `/active` | - | List all running sessions |
 | `/new` | - | Clear the current session (keeps cwd) |

package/README.md

@@ -108,9 +108,9 @@ lark-remote 启动后不在终端输出，运行日志写入 `~/.lark-remote/log
 |------|------|------|
 | `/help` | `/h` | 命令列表 |
 | `/cd <path>` | - | 切换 agent 工作目录（支持 `~`、绝对/相对路径，清空会话） |
-| `/ls [dir\|file]` | - | 弹出目录/文件卡片；点击目录切换，点击 30MB 内文件发送到飞书；条目 >30 时支持翻页与直接输入页码跳转。传文件路径时直接列出该文件（可下载） |
+| `/ls [dir\|file]` | - | 弹出目录/文件卡片；点击目录切换，点击 30MB 内文件发送到飞书；条目 >30 时支持翻页与直接输入页码跳转，卡片内可按关键词筛选本层条目。传文件路径时直接列出该文件（可下载） |
 | `/download <path>` | `/d` | 直接下载（发送）指定文件到飞书（支持 `~`、绝对/相对路径，上限 30MB） |
-| `/ws save\|use\|remove` | - | 命名目录别名管理（`/ws` 默认列出） |
+| `/ws save\|use\|remove` | - | 命名目录别名管理（`/ws` 默认列出，可按名称/路径关键词筛选） |
 | `/resume [agent] [N\|id]` | `/r` | 列出/切换当前目录的 agent session（卡片） |
 | `/active` | - | 列出所有正在进行中的 session |
 | `/new` | - | 清空当前会话（保留工作目录） |

package/dist/bridge/inbound-media.d.ts

@@ -1,16 +1,11 @@
 import { type AppConfig } from '../config/index.js';
-import type { InboundMediaItem, InboundMediaPayload } from '../connector/index.js';
+import type { MediaOutcome } from '../inbound/turn.js';
+import type { InboundResourceKind, InboundMediaItem, InboundMediaPayload } from '../connector/index.js';
 export interface InboundMediaDeps {
     /** 解析用户 cwd（bridge.resolveCwd 注入，统一三份复制点）。 */
     resolveCwd: (userId: string) => string | undefined;
     /** 读取当前配置（活引用，随 /config 保存更新，避免启动快照过期）。 */
     getConfig: () => AppConfig;
-    /** 发送提示消息（bridge.sendResult 包装）。 */
-    send(ctx: {
-        userId: string;
-        chatId: string;
-        messageId: string;
-    }, text: string): Promise<boolean>;
 }
 /**
  * 文件名 sanitize：
@@ -19,10 +14,10 @@ export interface InboundMediaDeps {
  */
 export declare function sanitizeFileName(name: string): string;
 /**
- * image 消息扩展名：优先 MIME 映射，未知时按魔数兜底；
+ * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
-export declare function imageExtension(mimeType: string | undefined, head: Buffer): string | undefined;
+export declare function extensionFor(_kind: InboundResourceKind, mimeType: string | undefined, head: Buffer): string | undefined;
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。
@@ -30,23 +25,22 @@ export declare function imageExtension(mimeType: string | undefined, head: Buffe
 export declare function limitFileNameLength(name: string, maxBytes?: number): string;
 /**
  * 生成落盘文件名：
- * - file 消息：保留原始文件名（已 sanitize）；无文件名兜底 file_<HHmmss>_<n>；
- * - image 消息：image_<HHmmss>_<n>.<ext>，ext 按 MIME。
+ * - image：`image_<HHmmss>_<n>.<ext>`（ext 按 MIME/魔数）；
+ * - 其它有原名的资源（file/video/audio/sticker）：保留原名（已 sanitize）；
+ * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
+ *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
  */
 export declare function buildFileName(item: InboundMediaItem, index: number, receivedAt: Date): string;
 /** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
 export declare function uniqueTargetPath(dir: string, fileName: string): string;
 export declare class InboundMediaHandler {
     private readonly deps;
-    private readonly pending;
-    private readonly batchWindowMs;
     constructor(deps: InboundMediaDeps);
-    /** 落盘并安排/合并提示。 */
-    handle(payload: InboundMediaPayload): Promise<void>;
-    /** 立即冲刷某用户的全部待合批提示（文本到达时调用）。 */
-    flushAll(userId: string, chatId: string): void;
-    /** 冲刷全部待合批提示（/exit、/restart 干净退出前调用，避免丢最后一条提示）。 */
-    flushAllPending(): Promise<void>;
+    /**
+     * 落盘并返回结果（不改时间语义、不发消息）。
+     * 失败/超限/无 cwd 一律进 `rejected`，由装配器决定回执文案。
+     */
+    save(payload: InboundMediaPayload): Promise<MediaOutcome>;
     /**
      * dirName 配置校验：只允许单层目录名（不允许 `/`、`\`、`..`、`.`、控制字符），
      * 非法值回退默认 `.lark-remote-temp`，避免配置意外把文件写到 cwd 之外。
@@ -55,5 +49,4 @@ export declare class InboundMediaHandler {
     /** 清理未被移动的临时文件（无 cwd / 目录创建失败等提前返回路径）。 */
     private cleanupTemps;
     private resolveCwd;
-    private flush;
 }

package/dist/bridge/inbound-media.js

@@ -8,26 +8,37 @@ import { silentlyUnlink } from '../common/fs.js';
  * 入站媒体落盘。
  *
  * 核心设计：
- * - 存储"到达即存"：每个 media 立即原子写入
+ * - 存储「到达即存」：每个 media 立即原子写入
  *   `<cwd>/.lark-remote-temp/<YYYYMMDDHHmm>/`，不等待合批窗口；
- * - 合批只影响提示：500ms 窗口内同一 (userId, chatId, replyTo) 的保存结果
- *   合并成一条"已保存 N 个文件"提示；
- * - 文本消息到达时由 Bridge.flushMediaNotifications 立即冲刷批次
- *   （"先图后文字时文字到达先冲刷批次"），避免提示被后续消息淹没。
+ * - 只负责「落盘 + 报告结果」：把落盘路径与失败原因交回装配器
+ *   （`InboundTurnAssembler`），由装配器决定注入 prompt 还是发回执。
+ *   时间语义统一由装配器的静默期窗口负责（2026-09-15 起取代旧的
+ *   500ms 合批提示窗口 ——「现有合批窗口由 700ms 装配窗口取代」）。
  */
-/** 合批窗口（毫秒）。同一窗口内到达的保存提示合并为一条。 */
-const DEFAULT_BATCH_WINDOW_MS = 500;
-/** 单条提示最多列出的文件数；超出折叠为 "… 等 N 个文件"。 */
-const MAX_PATHS_IN_NOTIFICATION = 10;
 /** 文件名最长字节数（macOS/APFS 单组件上限 255 字节，留余量用 240）。 */
 const MAX_FILE_NAME_BYTES = 240;
-/** 魔数检测读取的头部字节数（png/jpg/gif/webp 签名都在前 12 字节内）。 */
+/** 魔数检测读取的头部字节数（png/jpg/gif/webp/mp4/ogg 签名都在前 12 字节内）。 */
 const MAGIC_HEAD_BYTES = 12;
 const MIME_TO_EXT = {
     'image/png': 'png',
     'image/jpeg': 'jpg',
+    'image/jpg': 'jpg',
     'image/gif': 'gif',
     'image/webp': 'webp',
+    'image/bmp': 'bmp',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'video/webm': 'webm',
+    'video/x-matroska': 'mkv',
+    'audio/opus': 'opus',
+    'audio/ogg': 'ogg',
+    'audio/mpeg': 'mp3',
+    'audio/mp3': 'mp3',
+    'audio/wav': 'wav',
+    'audio/x-wav': 'wav',
+    'audio/aac': 'aac',
+    'audio/amr': 'amr',
+    'audio/mp4': 'm4a',
 };
 function pad2(n) {
     return String(n).padStart(2, '0');
@@ -74,17 +85,23 @@ export function sanitizeFileName(name) {
     return sanitized;
 }
 /**
- * image 消息扩展名：优先 MIME 映射，未知时按魔数兜底；
+ * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
-export function imageExtension(mimeType, head) {
-    if (mimeType && MIME_TO_EXT[mimeType])
-        return MIME_TO_EXT[mimeType];
+export function extensionFor(_kind, mimeType, head) {
+    const normalized = mimeType?.split(';')[0]?.trim().toLowerCase();
+    if (normalized && MIME_TO_EXT[normalized])
+        return MIME_TO_EXT[normalized];
     if (head.length >= 12 &&
         head.subarray(0, 4).toString('latin1') === 'RIFF' &&
         head.subarray(8, 12).toString('latin1') === 'WEBP') {
         return 'webp';
     }
+    if (head.length >= 12 &&
+        head.subarray(0, 4).toString('latin1') === 'RIFF' &&
+        head.subarray(8, 12).toString('latin1') === 'WAVE') {
+        return 'wav';
+    }
     if (head.length >= 8 &&
         head.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
         return 'png';
@@ -95,6 +112,29 @@ export function imageExtension(mimeType, head) {
     if (head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'GIF8') {
         return 'gif';
     }
+    if (head.length >= 4 && head.subarray(0, 4).toString('latin1') === 'OggS') {
+        return 'opus';
+    }
+    // MP4/MOV 家族：ISO BMFF 在偏移 4 处写 'ftyp'。
+    if (head.length >= 8 && head.subarray(4, 8).toString('latin1') === 'ftyp') {
+        return 'mp4';
+    }
+    if (head.length >= 2 && head[0] === 0x42 && head[1] === 0x4d) {
+        return 'bmp';
+    }
+    if (head.length >= 3 && head.subarray(0, 3).toString('latin1') === 'ID3') {
+        return 'mp3';
+    }
+    // MPEG audio frame sync（0xFFE0 掩码）+ 常见 layer/bitrate 组合。
+    if (head.length >= 2 && head[0] === 0xff && (head[1] & 0xfe) === 0xfa) {
+        return 'mp3';
+    }
+    if (head.length >= 5 && head.subarray(0, 5).toString('latin1') === '#!AMR') {
+        return 'amr';
+    }
+    if (head.length >= 4 && head.readUInt32BE(0) === 0x1a45dfa3) {
+        return 'mkv';
+    }
     return undefined;
 }
 /** 按 UTF-8 字节数截断字符串（避免截在多字节字符中间）。 */
@@ -127,17 +167,17 @@ function readFileHead(filePath, maxBytes = MAGIC_HEAD_BYTES) {
 }
 /**
  * 生成落盘文件名：
- * - file 消息：保留原始文件名（已 sanitize）；无文件名兜底 file_<HHmmss>_<n>；
- * - image 消息：image_<HHmmss>_<n>.<ext>，ext 按 MIME。
+ * - image：`image_<HHmmss>_<n>.<ext>`（ext 按 MIME/魔数）；
+ * - 其它有原名的资源（file/video/audio/sticker）：保留原名（已 sanitize）；
+ * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
+ *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
  */
 export function buildFileName(item, index, receivedAt) {
-    if (item.type === 'file') {
-        const sanitized = item.fileName ? sanitizeFileName(item.fileName) : '';
-        return ((sanitized ? limitFileNameLength(sanitized) : '') ||
-            `file_${timeStampHms(receivedAt)}_${index}`);
-    }
-    const ext = imageExtension(item.mimeType, readFileHead(item.tempPath));
-    return `image_${timeStampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
+    const original = item.fileName ? limitFileNameLength(sanitizeFileName(item.fileName)) : '';
+    if (item.kind !== 'image' && original)
+        return original;
+    const ext = extensionFor(item.kind, item.mimeType, readFileHead(item.tempPath));
+    return `${item.kind}_${timeStampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
 }
 /** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
 export function uniqueTargetPath(dir, fileName) {
@@ -151,27 +191,29 @@ export function uniqueTargetPath(dir, fileName) {
     }
     return candidate;
 }
-function formatFailure(f) {
-    return f.fileName ? `${f.fileName}: ${f.reason}` : f.reason;
-}
-function batchKey(payload) {
-    return `${payload.userId}:${payload.chatId}:${payload.replyToMessageId ?? ''}`;
-}
 export class InboundMediaHandler {
     deps;
-    pending = new Map();
-    batchWindowMs;
     constructor(deps) {
         this.deps = deps;
-        this.batchWindowMs = DEFAULT_BATCH_WINDOW_MS;
     }
-    /** 落盘并安排/合并提示。 */
-    async handle(payload) {
+    /**
+     * 落盘并返回结果（不改时间语义、不发消息）。
+     * 失败/超限/无 cwd 一律进 `rejected`，由装配器决定回执文案。
+     */
+    async save(payload) {
         const cwd = this.resolveCwd(payload.userId);
         if (!cwd) {
             this.cleanupTemps(payload);
-            await this.deps.send({ userId: payload.userId, chatId: payload.chatId, messageId: payload.messageId }, '⚠️ 未设置工作目录，无法保存文件。请先使用 /cd <path> 或 /ws use 设置');
-            return;
+            return {
+                attachments: [],
+                rejected: [
+                    {
+                        kind: 'file',
+                        reason: '未设置工作目录，无法保存文件。请先使用 /cd <path> 或 /ws use 设置',
+                        sourceMsgId: payload.messageId,
+                    },
+                ],
+            };
         }
         const receivedAt = new Date();
         const dir = path.join(cwd, this.safeDirName(), timeStampDir(receivedAt));
@@ -181,55 +223,49 @@ export class InboundMediaHandler {
         catch (err) {
             // 写盘失败必须明确提示；临时文件一并清理避免泄漏。
             this.cleanupTemps(payload);
-            await this.deps.send({ userId: payload.userId, chatId: payload.chatId, messageId: payload.messageId }, `⚠️ 保存失败：无法创建目录 ${dir}：${err.message}`);
-            return;
+            return {
+                attachments: [],
+                rejected: [
+                    {
+                        kind: 'file',
+                        reason: `保存失败：无法创建目录 ${dir}：${err.message}`,
+                        sourceMsgId: payload.messageId,
+                    },
+                ],
+            };
         }
-        const errors = payload.failures.map(formatFailure);
-        const saved = [];
+        const rejected = payload.failures.map((f) => ({
+            kind: f.kind ?? 'file',
+            reason: f.fileName ? `${f.fileName}: ${f.reason}` : f.reason,
+            sourceMsgId: payload.messageId,
+        }));
+        const attachments = [];
         for (let i = 0; i < payload.media.length; i += 1) {
             const item = payload.media[i];
             try {
                 const target = uniqueTargetPath(dir, buildFileName(item, i + 1, receivedAt));
                 atomicMoveFile(item.tempPath, target);
-                saved.push(target);
+                attachments.push({
+                    path: target,
+                    kind: item.kind,
+                    sourceMsgId: payload.messageId,
+                    originalName: item.fileName,
+                    durationMs: item.durationMs,
+                });
             }
             catch (err) {
                 silentlyUnlink(item.tempPath);
                 const label = item.fileName
                     ? sanitizeFileName(item.fileName) || item.fileName
                     : `第 ${i + 1} 个`;
-                errors.push(`${label}: ${err.message}`);
+                rejected.push({
+                    kind: item.kind,
+                    reason: `${label}: ${err.message}`,
+                    sourceMsgId: payload.messageId,
+                });
             }
         }
-        if (saved.length === 0) {
-            await this.deps.send({ userId: payload.userId, chatId: payload.chatId, messageId: payload.messageId }, `⚠️ 保存失败：${errors.join('；') || '未知错误'}`);
-            return;
-        }
-        const key = batchKey(payload);
-        const existing = this.pending.get(key);
-        if (existing) {
-            existing.saved.push(...saved);
-            existing.errors.push(...errors);
-            clearTimeout(existing.timer);
-            existing.timer = setTimeout(() => void this.flush(key), this.batchWindowMs);
-            return;
-        }
-        const timer = setTimeout(() => void this.flush(key), this.batchWindowMs);
-        this.pending.set(key, { payload, saved, errors, timer });
-    }
-    /** 立即冲刷某用户的全部待合批提示（文本到达时调用）。 */
-    flushAll(userId, chatId) {
-        for (const key of [...this.pending.keys()]) {
-            const batch = this.pending.get(key);
-            if (batch && batch.payload.userId === userId && batch.payload.chatId === chatId) {
-                void this.flush(key);
-            }
-        }
-    }
-    /** 冲刷全部待合批提示（/exit、/restart 干净退出前调用，避免丢最后一条提示）。 */
-    async flushAllPending() {
-        const keys = [...this.pending.keys()];
-        await Promise.all(keys.map((key) => this.flush(key)));
+        return { attachments, rejected };
     }
     /**
      * dirName 配置校验：只允许单层目录名（不允许 `/`、`\`、`..`、`.`、控制字符），
@@ -257,27 +293,5 @@ export class InboundMediaHandler {
     resolveCwd(userId) {
         return this.deps.resolveCwd(userId);
     }
-    async flush(key) {
-        const batch = this.pending.get(key);
-        if (!batch)
-            return;
-        this.pending.delete(key);
-        clearTimeout(batch.timer);
-        const lines = batch.saved.slice(0, MAX_PATHS_IN_NOTIFICATION).map((p) => `- ${p}`);
-        const overflow = batch.saved.length > MAX_PATHS_IN_NOTIFICATION ? `\n… 等 ${batch.saved.length} 个文件` : '';
-        const failures = batch.errors.length > 0 ? `\n⚠️ ${batch.errors.join('；')}` : '';
-        // 提示带上保存目录：用户把整句转给 agent 即可定位，无需靠目录约定反查。
-        // 合批窗口跨分钟时可能落在两个目录，此时全部列出。
-        const dirs = [...new Set(batch.saved.map((p) => path.dirname(p)))];
-        const hint = dirs.length === 1
-            ? `\n💡 你可以直接说：请处理 ${dirs[0]} 下的文件`
-            : `\n💡 你可以直接说：请处理以下目录下的文件：${dirs.join('、')}`;
-        const text = `📎 已保存 ${batch.saved.length} 个文件：\n` + lines.join('\n') + overflow + failures + hint;
-        await this.deps.send({
-            userId: batch.payload.userId,
-            chatId: batch.payload.chatId,
-            messageId: batch.payload.messageId,
-        }, text);
-    }
 }
 //# sourceMappingURL=inbound-media.js.map

package/dist/bridge/index.d.ts

@@ -7,6 +7,7 @@ import type { RunTerminal } from '../card/run-state.js';
 import type { AgentKind } from '../runner/types.js';
 import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding } from './queue-manager.js';
 import type { InboundMediaPayload } from '../connector/index.js';
+import type { MediaOutcome } from '../inbound/turn.js';
 /**
  * Seam (§7): the channel capabilities the bridge needs. `sendWithRetry` is
  * the minimum a Feishu channel must offer for the bridge to push messages
@@ -318,12 +319,11 @@ export declare class Bridge {
     updateCardInPlace(card: object, ctx: BridgeContext): Promise<boolean>;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: BridgeContext): Promise<void>;
-    /** 入站媒体落盘入口（connector 下载完成后调用）。 */
-    onInboundMedia(payload: InboundMediaPayload): Promise<void>;
-    /** 文本消息到达时立即冲刷待合批的媒体保存提示。 */
-    flushMediaNotifications(userId: string, chatId: string): void;
-    /** 冲刷全部待合批提示（/exit、/restart 干净退出前调用）。 */
-    flushAllMediaNotifications(): Promise<void>;
+    /**
+     * 入站媒体落盘（connector 下载完成后调用）：只落盘并回报结果，
+     * 时间语义与回执由 `InboundTurnAssembler` 统一负责。
+     */
+    saveInboundMedia(payload: InboundMediaPayload): Promise<MediaOutcome>;
     /**
      * Resolve the working directory for a user.
      * First checks sessionStore (set by /cd), then falls back to first workspace.

package/dist/bridge/index.js

@@ -135,7 +135,6 @@ export class Bridge {
         this.mediaHandler = new InboundMediaHandler({
             resolveCwd: (userId) => this.resolveCwd(userId),
             getConfig: () => this.config,
-            send: async (ctx, text) => this.sendResult({ text }, ctx),
         });
     }
     /**
@@ -671,17 +670,12 @@ export class Bridge {
             await this.sendResult({ text: `发送文件失败: ${err.message}` }, ctx);
         }
     }
-    /** 入站媒体落盘入口（connector 下载完成后调用）。 */
-    async onInboundMedia(payload) {
-        await this.mediaHandler.handle(payload);
-    }
-    /** 文本消息到达时立即冲刷待合批的媒体保存提示。 */
-    flushMediaNotifications(userId, chatId) {
-        this.mediaHandler.flushAll(userId, chatId);
-    }
-    /** 冲刷全部待合批提示（/exit、/restart 干净退出前调用）。 */
-    async flushAllMediaNotifications() {
-        await this.mediaHandler.flushAllPending();
+    /**
+     * 入站媒体落盘（connector 下载完成后调用）：只落盘并回报结果，
+     * 时间语义与回执由 `InboundTurnAssembler` 统一负责。
+     */
+    async saveInboundMedia(payload) {
+        return this.mediaHandler.save(payload);
     }
     /**
      * Resolve the working directory for a user.

package/dist/card/approval-render.js

@@ -207,9 +207,9 @@ function renderPlanApproval(approval, expired, runId) {
     return elements;
 }
 /**
- * 计划修改意见输入行：输入后点击右侧 ✓ 提交图标，input_value 经 connector
- * raw 事件回传（CardKit input 的 input_value 会被 SDK normalizer 丢弃，
- * 必须走 includeRawEvent 路径，同 answerNote）。
+ * 计划修改意见输入行：输入后提交（移动端键盘回车/完成键，桌面端右侧提交图标），
+ * input_value 经 connector raw 事件回传（CardKit input 的 input_value 会被
+ * SDK normalizer 丢弃，必须走 includeRawEvent 路径，同 answerNote）。
  */
 function renderPlanFeedbackInput(requestId, runId) {
     return {
@@ -430,8 +430,9 @@ function renderQuestionApproval(approval, expired, runId) {
                 text: { tag: 'lark_md', content: `✍️ 自定义答案：${customSelected}` },
             });
         }
-        // review P3-4：单选问题提供自定义答案（Other）输入——输入文本后点击
-        // 输入框右侧 ✓ 提交图标，input_value 经 connector raw 事件回传。
+        // review P3-4：单选问题提供自定义答案（Other）输入——输入文本后提交
+        // （移动端键盘回车/完成键，桌面端输入框右侧提交图标），input_value 经
+        // connector raw 事件回传。
         // 显隐按 isOther !== false：Kimi form 会丢弃非声明选项值，翻译时置
         // isOther=false 隐藏输入；Claude 未设置该字段默认显示（行为不变）。
         if (!q.multiSelect && q.isOther !== false) {
@@ -517,9 +518,9 @@ function renderOptionRow(requestId, questionIndex, option, isSelected, icon, run
     };
 }
 /**
- * 文本输入行（Other 输入与自由文本题共用）：输入后点击右侧 ✓ 提交图标，
- * input_value 经 connector raw 事件回传（CardKit input 的 input_value 会被
- * SDK normalizer 丢弃，必须走 includeRawEvent 路径）。
+ * 文本输入行（Other 输入与自由文本题共用）：输入后提交（移动端键盘回车/完成键，
+ * 桌面端右侧提交图标），input_value 经 connector raw 事件回传（CardKit input 的
+ * input_value 会被 SDK normalizer 丢弃，必须走 includeRawEvent 路径）。
  */
 function renderAnswerInput(requestId, questionIndex, placeholder, runId, cmd = 'approval.answerCustom') {
     // name 必须含 cmd，保证同一题同时渲染多个输入框（如单选选项题的

package/dist/cli.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { printHelp, printVersion } from './config/dir.js';
+import { printAdvanceHelp, printHelp, printVersion } from './config/dir.js';
 const entryUrl = new URL('./index.js', import.meta.url);
 const entry = fileURLToPath(entryUrl);
 /**
@@ -32,6 +32,10 @@ export function handlePreflight(args, nodeVersion = process.versions.node) {
             printHelp();
             return 0;
         }
+        if (arg === '--advance-help') {
+            printAdvanceHelp();
+            return 0;
+        }
     }
     const major = parseInt(String(nodeVersion).split('.')[0], 10);
     if (!Number.isNaN(major) && major > 0 && major < MIN_NODE_MAJOR) {

package/dist/config/dir.d.ts

@@ -5,6 +5,7 @@ interface CliArgs {
     help?: boolean;
     version?: boolean;
     update?: boolean;
+    advanceHelp?: boolean;
 }
 export declare function resolveConfigDir(configDirArg: string | undefined): string;
 export declare function getConfigDir(): string;
@@ -16,4 +17,12 @@ export declare function getVersion(): string;
 export declare function printVersion(): void;
 /** Print CLI help to stdout. */
 export declare function printHelp(): void;
+/**
+ * Print advanced-config reference to stdout (CLI `--advance-help`).
+ *
+ * 目标读者是 coding agent（用户让 agent 代改 config.yaml）：披露所有
+ * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。飞书侧
+ * 等价命令为 /advancehelp（内容同源，卡片渲染）。
+ */
+export declare function printAdvanceHelp(): void;
 export {};