lark-remote 0.3.0 → 0.4.1

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

package/dist/config/dir.js

@@ -52,6 +52,9 @@ export function parseCliArgs(args = process.argv.slice(2)) {
         else if (arg === '--dev') {
             result.dev = true;
         }
+        else if (arg === '--advance-help') {
+            result.advanceHelp = true;
+        }
         else if (arg === '--update' || arg === 'update') {
             // 裸子命令等价形式：`lark-remote update` 与 `--update` 同义。
             // 不识别时它会落到守护进程路径去抢单例锁，被正在运行的实例挡下
@@ -91,9 +94,75 @@ export function printHelp() {
         '  --settings <path>     指定 Claude 配置文件路径',
         '  --dev                 开发模式：标记从源码 bun src/index.ts 启动（看门狗据此选择拉起方式）',
         '  --update              升级到最新版本后退出（用于 cron/脚本自动化升级）',
+        '  --advance-help        高级配置参考：config.yaml 全部高级字段的语义与改法（面向 coding agent）',
         '  -h, --help            显示本帮助信息',
         '  -v, --version         显示版本号',
     ];
     process.stdout.write(lines.join('\n') + '\n');
 }
+/**
+ * Print advanced-config reference to stdout (CLI `--advance-help`).
+ *
+ * 目标读者是 coding agent（用户让 agent 代改 config.yaml）：披露所有
+ * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。飞书侧
+ * 等价命令为 /advancehelp（内容同源，卡片渲染）。
+ */
+export function printAdvanceHelp() {
+    const configDir = resolveConfigDir(parseCliArgs().configDir);
+    const configPath = configDir + '/config.yaml';
+    const lines = [
+        'lark-remote 高级配置参考（--advance-help）',
+        '',
+        '目标读者：coding agent。用户把本输出交给 agent，agent 据此代改配置。',
+        '',
+        '配置文件：' + configPath,
+        '',
+        '修改方式（三选一）：',
+        '  1. 直接编辑上面的 config.yaml，改完由用户发送 /restart 生效',
+        '  2. 用户发送 /config <key> <value> 文本直写（立盘即生效），',
+        '     如 /config claude.approvalTimeoutMs 300000',
+        '  3. 常用项走 /config 卡片交互（模型/审批档位/超时等已暴露，不在此列）',
+        '',
+        'Key 映射规则：pi./codex./opencode./kimi./dsh. 开头自动映射到 agents.<agent>.<字段>；',
+        'claude. 开头在顶层；其余原样。',
+        '',
+        'Claude（顶层 claude.*）：',
+        '  approvalTimeoutMs     (默认 300000)  审批请求超时(ms)，超时自动 cancel；0=立即过期；勿随意改短',
+        '  idleTtlMinutes        (默认 30)      会话空闲回收(分钟)，turn 间无新消息超窗回收长驻进程；0=不回收',
+        '  stopGraceMs           (默认 5000)    SIGTERM→SIGKILL 宽限(ms)，内部实现细节，勿改',
+        '',
+        'Codex（agents.codex.appServer.*）：',
+        '  binary                (默认 codex)     codex 二进制路径',
+        '  requestTimeoutMs      (默认 60000)     单次 RPC 请求超时(ms)',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
+        '',
+        'Kimi（agents.kimi.acp.*）：',
+        '  binary                (默认 kimi)      kimi 二进制路径',
+        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
+        '',
+        'OpenCode（agents.opencode.acp.*）：',
+        '  binary                (默认 opencode)  opencode 二进制路径',
+        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
+        '',
+        'Pi：',
+        '  agents.pi.tools       (默认 read,bash,edit,write,grep,find,ls) 逗号分隔工具白名单',
+        '',
+        '入站媒体（inboundMedia.*）：',
+        '  enabled               (默认 true)              图片/文件落盘开关',
+        '  dirName               (默认 .lark-remote-temp) 落盘目录名（位于当前 cwd 下）',
+        '  maxFileSizeMb         (默认 100)               单文件上限(MiB)；飞书 >100MB 需分片，实际不可用更大值',
+        '',
+        '其他：',
+        '  checkUpdateOnStartup  (默认 false)   启动时检查更新',
+        '',
+        '字段全集与校验规则见 Zod schema（src/config/index.ts，代码内唯一事实源）。',
+        '直接改 YAML 后必须 /restart；/config 文本直写与卡片保存即时生效。',
+    ];
+    process.stdout.write(lines.join('\n') + '\n');
+}
 //# sourceMappingURL=dir.js.map

package/dist/config/index.d.ts

@@ -20,9 +20,16 @@ export declare const PI_THINKING_LEVELS: readonly ["off", "minimal", "low", "med
 export declare const DEFAULT_STOP_GRACE_MS: 5000;
 /** Codex app-server turn idle timeout default (minutes). */
 export declare const DEFAULT_TURN_IDLE_TIMEOUT_MINUTES: 30;
-/** 入站媒体默认配置（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 declare const DEFAULT_INBOUND_MEDIA_DIR_NAME = ".lark-remote-temp";
-export declare const DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB = 50;
+export declare const DEFAULT_INBOUND_MEDIA_MAX_SIZE_MB = 100;
 /** 模型 ID → alias 映射。 */
 export declare const MODEL_ID_TO_ALIAS: Record<string, string>;
 /** alias → model ID 反向映射。 */
@@ -71,7 +78,7 @@ export declare const CodexConfigSchema: z.ZodObject<{
         turnIdleTimeoutMinutes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/** OpenCode-specific configuration (run mode: opencode run --format json --auto). */
+/** OpenCode-specific configuration (pure ACP mode: `opencode acp` over stdio). */
 declare const OpencodeConfigSchema: z.ZodObject<{
     providerID: z.ZodDefault<z.ZodString>;
     modelID: z.ZodDefault<z.ZodString>;
@@ -79,6 +86,12 @@ declare const OpencodeConfigSchema: z.ZodObject<{
         plan: "plan";
         build: "build";
     }>>;
+    acp: z.ZodOptional<z.ZodObject<{
+        binary: z.ZodDefault<z.ZodString>;
+        requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        idleTtlMs: z.ZodDefault<z.ZodNumber>;
+        turnIdleTimeoutMinutes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Pi-specific configuration. pi is a spawn-per-message CLI like Claude. */
 declare const PiConfigSchema: z.ZodObject<{
@@ -179,6 +192,12 @@ export declare const AppConfigSchema: z.ZodObject<{
                 plan: "plan";
                 build: "build";
             }>>;
+            acp: z.ZodOptional<z.ZodObject<{
+                binary: z.ZodDefault<z.ZodString>;
+                requestTimeoutMs: z.ZodDefault<z.ZodNumber>;
+                idleTtlMs: z.ZodDefault<z.ZodNumber>;
+                turnIdleTimeoutMinutes: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         pi: z.ZodOptional<z.ZodObject<{
             provider: z.ZodDefault<z.ZodString>;

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({
@@ -256,7 +278,7 @@ export const AppConfigSchema = z.object({
     inboundMedia: InboundMediaConfigSchema.default(InboundMediaConfigSchema.parse({})),
     /** Default agent for new runs. */
     defaultAgent: z.enum(['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh']).default('claude'),
-    /** Check for updates on bridge startup (default: false). */
+    /** Check for updates on lark-remote startup (default: false). */
     checkUpdateOnStartup: z.boolean().default(false),
 });
 const TEMPLATE = `feishu:

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>;
@@ -82,6 +103,12 @@ type InboundMediaDetectedHandler = (msg: InboundMediaMessage) => void | Promise<
  * means "no immediate response" (original behavior).
  */
 type CardActionHandler = (action: CardActionEvent) => void | CardActionResponse | Promise<void | CardActionResponse>;
+/**
+ * 卡片 patch 的重试上限。含义：1 次原始尝试 + 最多 PATCH_MAX_RETRIES 次重试。
+ */
+export declare const PATCH_MAX_RETRIES = 3;
+/** 重试退避基数（ms）；第 n 次重试前等待 n × 基数，给对端恢复的时间。 */
+export declare const PATCH_RETRY_BASE_DELAY_MS = 150;
 export declare class FeishuConnector {
     /** 飞书 channel 实例（public：测试直接访问/注入 mock，替代 as unknown as）。 */
     channel: LarkChannel;

package/dist/connector/index.js

@@ -2,7 +2,9 @@ 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';
 import fs from 'node:fs';
 import { silentlyUnlink } from '../common/fs.js';
@@ -44,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);
@@ -88,6 +127,72 @@ function shouldRetrySendError(err) {
         return true;
     return false;
 }
+/**
+ * 卡片 patch 的重试上限。含义：1 次原始尝试 + 最多 PATCH_MAX_RETRIES 次重试。
+ */
+export const PATCH_MAX_RETRIES = 3;
+/** 重试退避基数（ms）；第 n 次重试前等待 n × 基数，给对端恢复的时间。 */
+export const PATCH_RETRY_BASE_DELAY_MS = 150;
+/** 记日志用的错误摘要（不打印 axios 巨型循环对象）。 */
+function formatErrorForLog(err) {
+    if (err instanceof Error) {
+        // For axios errors, extract useful info without circular refs
+        const axiosErr = err;
+        if (axiosErr.response?.status) {
+            return `${err.message} (HTTP ${axiosErr.response.status})`;
+        }
+        if (axiosErr.code) {
+            return `${err.message} (code: ${axiosErr.code})`;
+        }
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * 卡片 patch 是否值得重试：传输层瞬态失败 + 5xx。
+ * 4xx（业务拒绝/请求构造错误）不重试 —— 重试只会得到同样的结果。
+ */
+function isRetryablePatchError(err) {
+    if (isTransientTransportError(err))
+        return true;
+    if (err == null || typeof err !== 'object')
+        return false;
+    const status = err.response?.status;
+    return typeof status === 'number' && status >= 500 && status < 600;
+}
+/**
+ * 带重试的 `im.v1.message.patch`。
+ *
+ * 为什么必须在这一层重试：流式卡片的 patch 由 @larksuite/channel 的
+ * CardStreamController 经 throttle 延迟触发 —— `controller.update()` 调完
+ * `throttle.note()` 就 resolve，不等真正的 patch。失败时是一条脱离 await 链的
+ * detached rejection，只能冒泡到 `process.unhandledRejection`，调用方的
+ * try/catch 根本挡不住。2026-09-15 00:09 的事故正是如此：卡片 patch 时
+ * socket 被关（AxiosError `ERR_SOCKET_CLOSED`），整进程退出，正在跑的 run 陪葬。
+ *
+ * 这里在唯一的底层 patch 出口上兜住：瞬态错误重试最多 PATCH_MAX_RETRIES 次，
+ * 全部失败才把最后一个错误抛出去（此时上层 classifyRejection 也会判为
+ * recoverable，不会击穿进程）。patch 是整卡替换，重试天然幂等。
+ */
+async function patchWithRetry(patchFn, request, options) {
+    let lastError;
+    for (let attempt = 0; attempt <= PATCH_MAX_RETRIES; attempt += 1) {
+        try {
+            return await patchFn(request, options);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt === PATCH_MAX_RETRIES || !isRetryablePatchError(err))
+                throw err;
+            const delayMs = PATCH_RETRY_BASE_DELAY_MS * (attempt + 1);
+            getLogger().warn(`[feishu] message.patch transient failure ` +
+                `(attempt ${attempt + 1}/${PATCH_MAX_RETRIES + 1}), retrying in ${delayMs}ms: ` +
+                `${formatErrorForLog(err)}`);
+            await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}
 /**
  * Safely extract the im.v1.message.patch service from a LarkChannel.
  * Returns undefined when the channel mock omits rawClient (unit tests).
@@ -126,16 +231,19 @@ export class FeishuConnector {
                 },
             },
         });
-        // 观测探针（2026-08-11 run 卡定格事故）：飞书业务码错误以 HTTP 200 + {code!=0}
-        // 返回时，lark SDK 正常 resolve、@larksuite/channel 的 patchCard 丢弃返回值，
-        // 导致终态卡 patch 被业务层拒绝时全链路无日志无兜底。这里只观测不改行为——
-        // 不 throw、不重试，返回值原样透传。
+        // 卡片 patch 的统一出口（观测 + 重试）：
+        // 1) 观测（2026-08-11 run 卡定格事故）：飞书业务码错误以 HTTP 200 + {code!=0}
+        //    返回时，lark SDK 正常 resolve、@larksuite/channel 的 patchCard 丢弃返回值，
+        //    导致终态卡 patch 被业务层拒绝时全链路无日志无兜底。这里把业务码记 warn，
+        //    返回值原样透传。
+        // 2) 重试（2026-09-15 socket-close 事故）：瞬态传输失败就地重试，最多
+        //    PATCH_MAX_RETRIES 次，不把失败直接落到 unhandledRejection 打死进程。
         // Guard: unit-test mocks may omit rawClient; skip probe installation in that case.
         const messageService = tryGetPatchService(this.channel);
         if (messageService?.patch) {
             const origPatch = messageService.patch.bind(messageService);
             messageService.patch = (async (request, options) => {
-                const res = await origPatch(request, options);
+                const res = await patchWithRetry(origPatch, request, options);
                 if (typeof res?.code === 'number' && res.code !== 0) {
                     const content = request?.data?.content;
                     const bytes = typeof content === 'string' ? Buffer.byteLength(content, 'utf8') : undefined;
@@ -148,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
@@ -202,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,
                 })),
             });
         }
@@ -237,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 {
@@ -344,18 +479,7 @@ export class FeishuConnector {
     }
     /** Format error for logging without causing circular serialization */
     formatError(err) {
-        if (err instanceof Error) {
-            // For axios errors, extract useful info without circular refs
-            const axiosErr = err;
-            if (axiosErr.response?.status) {
-                return `${err.message} (HTTP ${axiosErr.response.status})`;
-            }
-            if (axiosErr.code) {
-                return `${err.message} (code: ${axiosErr.code})`;
-            }
-            return err.message;
-        }
-        return String(err);
+        return formatErrorForLog(err);
     }
     async addReaction(messageId, emoji) {
         try {

package/dist/error-classification.d.ts

@@ -11,5 +11,12 @@
  * （recoverable，记日志不 exit）还是「进程状态损坏」（fatal，exit）。
  */
 type RejectionVerdict = 'recoverable' | 'fatal';
+/**
+ * Whether `reason` is a transient transport failure (connection/socket level).
+ *
+ * Exported because the card-patch retry path needs the same judgement:
+ * one definition, so "retry" and "don't kill the process" never drift apart.
+ */
+export declare function isTransientTransportError(reason: unknown): boolean;
 export declare function classifyRejection(reason: unknown): RejectionVerdict;
 export {};

package/dist/error-classification.js

@@ -1,3 +1,36 @@
+/**
+ * 传输层瞬态错误码（Node errno + axios 包装码）。
+ *
+ * 这些错误代表"这次请求没送出去/连接断了"，重试或忽略都是安全的；
+ * 它们不携带任何"程序状态损坏"的信息。典型场景：本地 mitmdump 代理重启
+ * （ECONNREFUSED）、Wi-Fi 抖动（ENOTFOUND/EAI_AGAIN）、对端关连接
+ * （ECONNRESET/EPIPE/ERR_SOCKET_CLOSED）。
+ */
+const TRANSIENT_TRANSPORT_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ECONNABORTED',
+    'EPIPE',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'ERR_SOCKET_CLOSED',
+    'ERR_NETWORK',
+]);
+/**
+ * Whether `reason` is a transient transport failure (connection/socket level).
+ *
+ * Exported because the card-patch retry path needs the same judgement:
+ * one definition, so "retry" and "don't kill the process" never drift apart.
+ */
+export function isTransientTransportError(reason) {
+    if (reason == null || typeof reason !== 'object')
+        return false;
+    const code = reason.code;
+    return typeof code === 'string' && TRANSIENT_TRANSPORT_CODES.has(code);
+}
 export function classifyRejection(reason) {
     // Guard against null/undefined/primitive reasons: the `as` cast below is
     // TS-only (erased at runtime), so `null.response` would throw a TypeError
@@ -10,7 +43,10 @@ export function classifyRejection(reason) {
     const status = err.response?.status;
     if (status !== undefined && status >= 500 && status < 600)
         return 'recoverable';
-    if (err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET')
+    // 传输层瞬态失败：连接/socket 级别，与进程状态无关。
+    // 2026-09-15 00:09 的崩溃就是这条漏了 —— AxiosError `ERR_SOCKET_CLOSED`
+    // （卡片 patch 时 socket 被关）落到 fatal → process.exit(1)，正在跑的 agent run 陪葬。
+    if (isTransientTransportError(reason))
         return 'recoverable';
     // 飞书 API 业务错误（如 230027 外部会话无权限）—— 经 SDK throttle detach 路径逃逸的
     // patch rejection。流式卡片是尽力而为的展示层，飞书侧业务拒绝不应击穿进程。