lark-remote 0.4.0 → 0.4.2

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({

package/dist/connector/index.d.ts

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

package/dist/connector/index.js

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

package/dist/inbound/event.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
+ * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
+ * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，
+ * 窗口到期后等它落定再 commit（§5.2）。
+ */
+import type { PlaceholderKind } from './placeholder.js';
+import type { MediaOutcome } from './turn.js';
+export interface InboundEventBase {
+    userId: string;
+    chatId: string;
+    messageId: string;
+    replyToMessageId?: string;
+    /** 飞书原始 msg_type（`text` / `image` / `post` / `merge_forward` …）。 */
+    rawContentType: string;
+}
+export interface TextInboundEvent extends InboundEventBase {
+    kind: 'text';
+    /** 已剥离结构占位符的文本（可为空串：整条消息都是占位符）。 */
+    text: string;
+    /** 本条消息命中的占位符种类，用于「不支持」回执。 */
+    placeholders: PlaceholderKind[];
+    /** 未知标签（未来 SDK 新增），上层负责 warn。 */
+    unknownTags: string[];
+}
+export interface MediaInboundEvent extends InboundEventBase {
+    kind: 'media';
+    /** 下载 + 落盘结果；装配器在窗口到期后等它落定才 commit。 */
+    outcome: Promise<MediaOutcome>;
+}
+export interface RejectedInboundEvent extends InboundEventBase {
+    kind: 'rejected';
+    /** 面向人的说明（如「入站媒体保存已关闭」）。 */
+    reason: string;
+    /** 拒绝项的 kind（默认 `unknown`）。 */
+    rejectedKind?: string;
+}
+export type InboundEvent = TextInboundEvent | MediaInboundEvent | RejectedInboundEvent;

package/dist/inbound/event.js

@@ -0,0 +1,11 @@
+/**
+ * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
+ *
+ * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
+ * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
+ * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，
+ * 窗口到期后等它落定再 commit（§5.2）。
+ */
+export {};
+//# sourceMappingURL=event.js.map

package/dist/inbound/placeholder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
+ *
+ * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
+ * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
+ *
+ * 规则来源：`docs/zh/architecture/inbound-message-matrix.md` §1 的 22 种 message_type
+ * 实测渲染串。判定顺序**先清洗后判语义**：任何前缀判定都必须发生在剥离之后。
+ *
+ * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
+ * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
+ * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
+ * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ */
+export type PlaceholderKind = 'image' | 'file' | 'video' | 'audio' | 'sticker' | 'share' | 'location' | 'folder' | 'vote' | 'todo' | 'meeting' | 'calendar' | 'hongbao' | 'forwarded' | 'unsupported' | 'unknown';
+export interface StripResult {
+    /** 剥离占位符后的文本（trim 后；forwarded 块只剥标签、保留内部文本）。 */
+    clean: string;
+    /** 命中的占位符种类（去重、保序），用于 rejected 回执与排障。 */
+    kinds: PlaceholderKind[];
+    /** 未知标签（未来 SDK 新增）——必须 warn，防止再次静默漏。 */
+    unknownTags: string[];
+}
+export declare function isDownloadablePlaceholder(kind: PlaceholderKind): boolean;
+export declare function stripPlaceholders(raw: string): StripResult;

package/dist/inbound/placeholder.js

@@ -0,0 +1,149 @@
+/**
+ * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
+ *
+ * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
+ * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
+ *
+ * 规则来源：`docs/zh/architecture/inbound-message-matrix.md` §1 的 22 种 message_type
+ * 实测渲染串。判定顺序**先清洗后判语义**：任何前缀判定都必须发生在剥离之后。
+ *
+ * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
+ * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
+ * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
+ * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ */
+/**
+ * 可下载资源类占位符：这些占位符对应的资源会由媒体通道下载落盘，
+ * 因此文本侧不把它们记成「不支持」（否则图文混排会双重报错）。
+ */
+const DOWNLOADABLE_KINDS = new Set([
+    'image',
+    'file',
+    'video',
+    'audio',
+    'sticker',
+]);
+export function isDownloadablePlaceholder(kind) {
+    return DOWNLOADABLE_KINDS.has(kind);
+}
+/** 协议块哨兵：`<attachments>` 是本项目自己生成的 prompt 附件块，剥离时必须原样保留。 */
+const ATTACHMENT_BLOCK_RE = /<attachments>[\s\S]*?<\/attachments>/g;
+const SENTINEL_PREFIX = '\u0000lark-inbound-att-';
+const SENTINEL_SUFFIX = '\u0000';
+/** 自闭合标签 → kind（`<file key="…" name="…"/>` 等，属性可缺省）。 */
+const SELF_CLOSING_RULES = [
+    [/<file(?:\s[^<>]*)?\/>/g, 'file'],
+    [/<video(?:\s[^<>]*)?\/>/g, 'video'],
+    [/<audio(?:\s[^<>]*)?\/>/g, 'audio'],
+    [/<sticker(?:\s[^<>]*)?\/>/g, 'sticker'],
+    [/<group_card(?:\s[^<>]*)?\/>/g, 'share'],
+    [/<contact_card(?:\s[^<>]*)?\/>/g, 'share'],
+    [/<location(?:\s[^<>]*)?\/>/g, 'location'],
+    [/<folder(?:\s[^<>]*)?\/>/g, 'folder'],
+    [/<hongbao(?:\s[^<>]*)?\/>/g, 'hongbao'],
+];
+/** 整块剥离（含内部内容）的容器标签：内容无用户语义，只作噪声。 */
+const BLOCK_RULES = [
+    [/<vote>[\s\S]*?<\/vote>/g, 'vote'],
+    [/<todo>[\s\S]*?<\/todo>/g, 'todo'],
+    [/<meeting>[\s\S]*?<\/meeting>/g, 'meeting'],
+    [/<calendar_invite>[\s\S]*?<\/calendar_invite>/g, 'calendar'],
+    [/<calendar_share>[\s\S]*?<\/calendar_share>/g, 'calendar'],
+    [/<calendar>[\s\S]*?<\/calendar>/g, 'calendar'],
+];
+/** 图片渲染串：`![image](img_v3_…)` / `![]()`,富文本内嵌图与纯 image 消息同形。 */
+const IMAGE_MD_RE = /!\[(?:image)?\]\([^)]*\)/g;
+/** 合并转发：只剥标签、保留内部文本（子消息文本有语义）。 */
+const FORWARDED_TAG_RE = /<\/?forwarded_messages\s*\/?>/g;
+/** 提及标签：保留内部显示名，不作为占位符上报。 */
+const AT_TAG_RE = /<at(?:\s[^<>]*)?>([\s\S]*?)<\/at>/g;
+/** converter 的降级态（缺 key / 未识别类型 —— 都是纯噪声）。 */
+const BRACKET_FALLBACK_RE = /\[(?:unsupported message|rich text message|interactive card|image|file|video|audio|sticker|system message|folder)\]/g;
+/**
+ * 未知标签兜底：只在「有属性」或「成对闭合」时才剥离。
+ * 要求有属性可显著降低误伤——用户正文里的 `<3`、`a < b`、`<div>` 不会被吃掉。
+ */
+const UNKNOWN_SELF_CLOSING_RE = /<([a-z][a-z0-9_]*)\s[^<>]*\/>/g;
+const UNKNOWN_PAIRED_RE = /<([a-z][a-z0-9_]*)(?:\s[^<>]*)?>[\s\S]*?<\/\1>/g;
+/** 剥离后遗留的连续空行折叠为单空行（属剥离产物，不算对用户文本加工）。 */
+function collapseBlankLines(text) {
+    return text.replace(/\n{3,}/g, '\n\n');
+}
+export function stripPlaceholders(raw) {
+    const kinds = [];
+    const unknownTags = [];
+    /** 是否真的剥离过东西：没有命中时不做任何文本加工（保持用户原文）。 */
+    let stripped = false;
+    // 1. 先把本项目自己的 <attachments> 协议块摘出去，最后原样放回。
+    const protectedBlocks = [];
+    let working = raw.replace(ATTACHMENT_BLOCK_RE, (match) => {
+        const token = `${SENTINEL_PREFIX}${protectedBlocks.length}${SENTINEL_SUFFIX}`;
+        protectedBlocks.push(match);
+        return token;
+    });
+    const hit = (kind) => {
+        stripped = true;
+        if (!kinds.includes(kind))
+            kinds.push(kind);
+    };
+    // 2. 图片渲染串（必须在 forwarded 标签剥离之前，覆盖块内子消息的图）。
+    working = working.replace(IMAGE_MD_RE, () => {
+        hit('image');
+        return '';
+    });
+    // 3. 已知自闭合标签。
+    for (const [re, kind] of SELF_CLOSING_RULES) {
+        working = working.replace(re, () => {
+            hit(kind);
+            return '';
+        });
+    }
+    // 4. 已知容器块（整块剥离）。
+    for (const [re, kind] of BLOCK_RULES) {
+        working = working.replace(re, () => {
+            hit(kind);
+            return '';
+        });
+    }
+    // 5. 合并转发：只剥标签。
+    working = working.replace(FORWARDED_TAG_RE, () => {
+        hit('forwarded');
+        return '';
+    });
+    // 6. 提及标签：保留显示名。
+    working = working.replace(AT_TAG_RE, (_match, inner) => {
+        stripped = true;
+        return inner;
+    });
+    // 7. converter 降级态。
+    working = working.replace(BRACKET_FALLBACK_RE, () => {
+        hit('unsupported');
+        return '';
+    });
+    // 8. 未知标签兜底（未来 SDK 新增类型）：剥离 + 记录 tag 名。
+    working = working.replace(UNKNOWN_SELF_CLOSING_RE, (match, tag) => {
+        hit('unknown');
+        if (!unknownTags.includes(tag))
+            unknownTags.push(tag);
+        return '';
+    });
+    working = working.replace(UNKNOWN_PAIRED_RE, (match, tag) => {
+        hit('unknown');
+        if (!unknownTags.includes(tag))
+            unknownTags.push(tag);
+        return '';
+    });
+    // 9. 放回协议块。
+    if (protectedBlocks.length > 0) {
+        stripped = true;
+        for (let i = 0; i < protectedBlocks.length; i += 1) {
+            working = working.split(`${SENTINEL_PREFIX}${i}${SENTINEL_SUFFIX}`).join(protectedBlocks[i]);
+        }
+    }
+    // 未命中任何占位符时**不做文本加工**（保留原文的连续空行等），
+    // 确保 router.handle 对纯文本消息的转发与原行为逐字一致。
+    const clean = stripped ? collapseBlankLines(working).trim() : working.trim();
+    return { clean, kinds, unknownTags };
+}
+//# sourceMappingURL=placeholder.js.map