lark-remote 0.3.0 → 0.4.1

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.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
+
+### 新增
+
+- **运行期间阻止系统休眠**：运行中自动阻止系统休眠（macOS 用 `caffeinate`、Windows 用 `SetThreadExecutionState`）——典型用法是人不在电脑前远程使用，系统一旦休眠连接即断。只阻止系统休眠，不影响显示器睡眠；退出（含异常退出）后自动解除，helper 意外退出也会留痕兜底。注意：MacBook 合盖睡眠无法阻止（除非接电源并外接显示器）
+- **入站媒体保存提示带完整路径**：收到的图片/文件落盘后，提示带目录完整路径，方便直接定位
+
+### 修复
+
+- **卡片更新瞬态失败自动重试**：飞书卡片更新遇到连接瞬时中断等瞬态传输错误时就地重试（最多 3 次），不再把失败直接落到未处理 rejection 上导致进程退出
+- **Kimi 审批卡恢复完整 Bash 命令**：审批卡片按 `toolCallId` 关联流式参数，恢复展示完整命令而非截断片段
+- **Kimi 权限模式文案对齐 kimi 0.40+ 语义**：`yolo` 现指「必要时询问」而非完全放行，完全自动请选 `auto`；README 与配置文档同步更新
+
+### 变更
+
+- **文档自称统一**：README、使用文档与架构文档中的自称统一为 lark-remote
+
 ## [0.3.0] - 2026-09-13
 
 ### 新增

package/README.en.md

@@ -16,7 +16,7 @@ Designed for a single-user, peer-to-peer private chat. The agent's system prompt
 
 ## ⚠️ Security Warning (read first)
 
-This tool turns Feishu messages directly into local agent executions. **Out of the box, agents run without approval prompts**: Claude defaults to `bypassPermissions` (no approval card), but that permission mode is **configurable** — set it to anything other than `bypassPermissions` (`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`) to enable interactive approval, where high-risk actions wait for your confirmation on the Feishu card. Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`); Kimi defaults to `manual` (per-action approval); other agents run with their CLI defaults. **In any mode**, agents can read and write the local directories you specify. You MUST:
+This tool turns Feishu messages directly into local agent executions. **Out of the box, agents run without approval prompts**: Claude defaults to `bypassPermissions` (no approval card), but that permission mode is **configurable** — set it to anything other than `bypassPermissions` (`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`) to enable interactive approval, where high-risk actions wait for your confirmation on the Feishu card. Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`); Kimi defaults to `manual` (per-action approval; note that since kimi 0.40, `yolo` means Ask-When-Needed rather than allow-everything — use `auto` for fully unattended, no-approval execution); other agents run with their CLI defaults. **In any mode**, agents can read and write the local directories you specify. You MUST:
 
 - **Use it only in your own private (p2p) chat.** Never add the bot to any group chat; never let anyone else talk to it.
 - Restrict the app's visibility to **yourself only** in the Feishu Open Platform.
@@ -52,7 +52,7 @@ git clone https://github.com/bungabungawoda/lark-remote.git
 cd lark-remote
 bun install
 bun run build
-bun install -g "$(pwd)"  # install globally as the lark-remote command (bun parses `.` as an empty package name; use an absolute path)
+bun install -g "$(pwd)"  # install globally as lark-remote command (bun parses `.` as an empty package name; use an absolute path)
 ```
 
 ## Configuration
@@ -94,7 +94,7 @@ lark-remote --config-dir ~/.lark-remote-test    # custom config dir (multiple in
 lark-remote --settings ~/.claude/settings.json  # specify Claude settings file
 ```
 
-The bridge prints nothing to the terminal after startup; logs go to `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log` (rotated daily, one subdirectory per day). Only one `lark-remote` instance is allowed per `configDir` — a duplicate start fails with the existing pid. After connecting to Feishu, a startup notification (with start time and pid) is sent to the most recent private chat.
+lark-remote prints nothing to the terminal after startup; logs go to `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log` (rotated daily, one subdirectory per day). Only one `lark-remote` instance is allowed per `configDir` — a duplicate start fails with the existing pid. After connecting to Feishu, a startup notification (with start time and pid) is sent to the most recent private chat.
 
 Each agent run creates one CardKit 2.0 card that updates in place with thinking, body text, and tool summaries in real time.
 Timestamps are read from the JSONL and shown in local time as `YYYY-MM-DD HH:mm` for thinking, body, tool call/result, and session history events.
@@ -117,12 +117,12 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 | `/status` | `/s` | Current directory, session, model, process status |
 | `/stop` | `/t` | Kill the current agent process (SIGKILL) |
 | `/ps` | - | Whether a process is running |
-| `/restart` | - | In-place bridge self-restart (new process takes over with the same config) |
-| `/clone [name]` | - | Clone the bridge: copies the current config into a new directory and walks you through creating a brand-new Feishu app by QR scan; on success it binds, syncs state, and launches the new instance |
+| `/restart` | - | In-place lark-remote self-restart (new process takes over with the same config) |
+| `/clone [name]` | - | Clone lark-remote: copies the current config into a new directory and walks you through creating a brand-new Feishu app by QR scan; on success it binds, syncs state, and launches the new instance |
 | `/config get\|set` | `/c` | View/change runtime config (agent-aware card) |
 | `/order save\|list\|edit` | `/o` | Save, list, or edit frequently used prompts |
 | `!<cmd>` | - | Run a bash command with streaming card output (bypasses the serial queue) |
-| `/exit` | `/e` | Exit the bridge |
+| `/exit` | `/e` | Exit lark-remote |
 
 Any message not starting with `/` is forwarded to the current default agent.
 

package/README.md

@@ -16,7 +16,7 @@
 
 ## ⚠️ 安全警告（必读）
 
-本工具会把飞书消息直接转为本地 agent 执行。**开箱默认是不弹审批的**：Claude 默认以 `bypassPermissions` 运行（无审批卡），但该权限模式**可配置**——把它改成 `bypassPermissions` 以外的值（`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`）即启用交互式审批，高风险操作会在飞书卡片上等你确认；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`）；Kimi 默认 `manual`（逐条审批）；其他 agent 以各自 CLI 的默认权限运行。**无论哪种模式**，agent 都能读写你指定的本地目录，请务必：
+本工具会把飞书消息直接转为本地 agent 执行。**开箱默认是不弹审批的**：Claude 默认以 `bypassPermissions` 运行（无审批卡），但该权限模式**可配置**——把它改成 `bypassPermissions` 以外的值（`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`）即启用交互式审批，高风险操作会在飞书卡片上等你确认；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`）；Kimi 默认 `manual`（逐条审批；注意 kimi 0.40+ 起 `yolo` 已改为「必要时询问」而非全部放行，要完全不弹审批需选 `auto`）；其他 agent 以各自 CLI 的默认权限运行。**无论哪种模式**，agent 都能读写你指定的本地目录，请务必：
 
 - **仅限你自己的私聊（p2p）使用**。不要把机器人拉进任何群聊，不要让任何其他人能与它对话。
 - 在飞书开放平台把应用可见范围限制到**只有你自己**。
@@ -94,7 +94,7 @@ lark-remote --config-dir ~/.lark-remote-test    # 自定义配置目录（同机
 lark-remote --settings ~/.claude/settings.json  # 指定 Claude 配置文件
 ```
 
-bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log`（按日期轮转，每天一个子目录）。同一 `configDir` 只允许一个 `lark-remote` 实例，重复启动会直接报错并提示已有 pid。连接飞书成功后会向最近私聊用户发送启动通知，包含启动时间和进程号。
+lark-remote 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log`（按日期轮转，每天一个子目录）。同一 `configDir` 只允许一个 `lark-remote` 实例，重复启动会直接报错并提示已有 pid。连接飞书成功后会向最近私聊用户发送启动通知，包含启动时间和进程号。
 
 每次 agent 运行会创建一张 CardKit 2.0 卡片，并在原地实时更新 thinking、正文和工具摘要。
 卡片会读取 JSONL 的 `timestamp`，以本地时间 `YYYY-MM-DD HH:mm` 显示 thinking、正文、tool call/result 和会话历史事件。
@@ -117,20 +117,21 @@ bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYY
 | `/status` | `/s` | 当前目录、session、模型、进程状态 |
 | `/stop` | `/t` | 终止当前 agent 进程（SIGKILL） |
 | `/ps` | - | 是否有进程在跑 |
-| `/restart` | - | 原地自重启 bridge（新进程同 config 接管） |
+| `/restart` | - | 原地自重启 lark-remote（新进程同 config 接管） |
 | `/clone [name]` | - | 复制分身：克隆当前配置到新目录并扫码创建新飞书应用，完成后自动绑定、同步状态并拉起新实例 |
 | `/config get\|set` | `/c` | 查改运行时配置（agent-aware 卡片） |
 | `/order save\|list\|edit\|alias` | `/o` | 收藏常用指令；`/order edit` 修改指令文本（保留别名/使用统计）；`/order alias` 注册快捷别名（输入 `$name` 展开） |
 | `!<cmd>` | - | 执行 bash 命令并流式输出到卡片（绕过串行队列） |
-| `/exit` | `/e` | 退出 bridge |
+| `/exit` | `/e` | 退出 lark-remote |
 
 直接发非 `/` 开头的消息即转发给当前默认 agent。
 
-**复制分身（`/clone`）**：想在另一个项目/机器目录旁跑一个独立 bridge 实例时，发 `/clone 名字` 即可——当前配置目录会被克隆为 `<configDir>-<名字>`（除飞书凭据外全部复制），二维码以图片消息发进私聊引导你扫码创建一个全新飞书应用；扫码成功后自动完成绑定，workspace 别名、常用指令、工作目录与会话状态一并迁移，新实例自动拉起并可直接续聊。也可直接点 `/help` 卡片上的「/clone」按钮。详见 [docs/zh/usage.md](docs/zh/usage.md)。
+**复制分身（`/clone`）**：想在另一个项目/机器目录旁跑一个独立 lark-remote 实例时，发 `/clone 名字` 即可——当前配置目录会被克隆为 `<configDir>-<名字>`（除飞书凭据外全部复制），二维码以图片消息发进私聊引导你扫码创建一个全新飞书应用；扫码成功后自动完成绑定，workspace 别名、常用指令、工作目录与会话状态一并迁移，新实例自动拉起并可直接续聊。也可直接点 `/help` 卡片上的「/clone」按钮。详见 [docs/zh/usage.md](docs/zh/usage.md)。
 
 往飞书私聊发**图片/文件**会自动保存到当前目录的 `.lark-remote-temp/<YYYYMMDDHHmm>/`
-（建议把 `.lark-remote-temp/` 加进项目 `.gitignore`），随后说「请处理刚才保存的文件」
-即可让 agent 直接读本地文件。更多用法见 [docs/zh/usage.md](docs/zh/usage.md)。
+（建议把 `.lark-remote-temp/` 加进项目 `.gitignore`），保存提示里会带上目录完整路径，
+随后说「请处理刚才保存的文件」（或直接把提示转给 agent）即可让 agent 直接读本地文件。
+更多用法见 [docs/zh/usage.md](docs/zh/usage.md)。
 
 ## 测试
 

package/dist/binder.d.ts

@@ -10,7 +10,7 @@ type BindDecision = {
 /**
  * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
  * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
  * 本类复用已有 startup-contact.json，不新增配置字段。

package/dist/binder.js

@@ -2,7 +2,7 @@ import { getLogger } from './logger/index.js';
 /**
  * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
  * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
  * 本类复用已有 startup-contact.json，不新增配置字段。

package/dist/bridge/final-usage.js

@@ -26,7 +26,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             // EnterWorktree relocate (2026-08-04): jsonl read silently returned no
             // usage (e.g. transcript moved mid-session). Surface it so token-stat
             // fallback to per-run live usage is visible in logs, not silent.
-            getLogger().warn(`[bridge] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
+            getLogger().warn(`[lark-remote] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
         }
         return content.usage
             ? {
@@ -48,7 +48,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             : undefined;
     }
     catch (err) {
-        getLogger().warn(`[bridge] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);
+        getLogger().warn(`[lark-remote] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);
         return undefined;
     }
 }

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,25 +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('；')}` : '';
-        const text = `📎 已保存 ${batch.saved.length} 个文件：\n` +
-            lines.join('\n') +
-            overflow +
-            failures +
-            '\n💡 你可以直接说：请处理刚才保存的文件';
-        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.