lark-remote 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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
 
 ### 新增

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

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