lark-remote 0.2.2 → 0.4.0

package/dist/config/codex-config.js

@@ -8,12 +8,17 @@
  * - catalog 模式（config.toml 声明 model_catalog_json）：模型列表/档位来自活动目录
  * - 非 catalog 模式：openai 用 bundled 全量；anthropic 仅在用户显式配置时存在
  */
-import { execFileSync, execFile } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import TOML from '@iarna/toml';
 import { getLogger } from '../logger/index.js';
+import { spawnProcess, spawnProcessSync } from '../platform/spawn.js';
+/** codex CLI 名（cross-spawn 负责 win32 .cmd 垫片解析）。 */
+const CODEX_BINARY = 'codex';
+/** codex CLI 调用超时 / 输出上限（同步与异步路径一致）。 */
+const CODEX_TIMEOUT_MS = 8_000;
+const CODEX_MAX_BUFFER = 4 * 1024 * 1024;
 /**
  * Resolve codex home directory.
  * Priority: explicit codexHome param > $CODEX_HOME env > ~/.codex
@@ -170,14 +175,7 @@ export function getCodexCatalogModels(codexHome) {
     }
     const now = Date.now();
     try {
-        const stdout = execFileSync('codex', catalogArgs(bundled), {
-            encoding: 'utf-8',
-            timeout: 8_000,
-            maxBuffer: 4 * 1024 * 1024,
-            env: process.env,
-            stdio: ['ignore', 'pipe', 'ignore'],
-            windowsHide: true, // codex 是 npm .cmd 垫片：不隐藏会闪 cmd.exe 控制台
-        });
+        const stdout = runCodexCommandSync(catalogArgs(bundled));
         const models = parseCodexModelsOutput(stdout);
         catalogCache = { key, models, ts: now, failed: models.length === 0 };
         return models;
@@ -208,7 +206,7 @@ export async function loadCodexCatalogModelsAsync(codexHome) {
     const p = (async () => {
         const now = Date.now();
         try {
-            const stdout = await execFileAsync('codex', catalogArgs(bundled));
+            const stdout = await runCodexCommandAsync(catalogArgs(bundled));
             const models = parseCodexModelsOutput(stdout);
             catalogCache = { key, models, ts: now, failed: models.length === 0 };
             return models;
@@ -236,7 +234,7 @@ export function warmCodexCatalogCache(codexHome) {
 }
 /** 计算目录缓存键（binary/home/mode + 指纹），同步与异步路径共享。 */
 function computeCodexCatalogKey(codexHome) {
-    const binary = 'codex';
+    const binary = CODEX_BINARY;
     const home = resolveCodexHome(codexHome);
     const catalogPath = readModelCatalogJsonPath(home);
     const bundled = catalogPath === undefined || catalogPath === TOML_PARSE_FAILED_SENTINEL;
@@ -277,20 +275,77 @@ function readCachedCatalog(key) {
 function catalogArgs(bundled) {
     return bundled ? ['debug', 'models', '--bundled'] : ['debug', 'models'];
 }
-/** Promisify execFile with the same 8s timeout / 4MB cap as the sync path. */
-function execFileAsync(file, args) {
+/**
+ * 同步运行 codex CLI（`debug models ...`），成功返回 stdout。
+ *
+ * 必须经 platform/spawn（cross-spawn）而非裸 execFileSync：codex 是 npm 全局
+ * 安装的 .cmd 垫片，win32 上 execFileSync 不做 PATHEXT 解析 —— 裸名 'codex'
+ * 会被解析到无扩展名的 sh 脚本（给 Git Bash/WSL 用的那份），Windows 原生
+ * 执行直接失败（bun 下 exit 1「系统找不到指定的路径」，node 下 ENOENT）；
+ * 而 execFileSync('codex.cmd') 又因 execFile 不经 shell 直接 EINVAL。
+ * cross-spawn 与 runner spawn 走同一垫片执行路径（posix 直通）。
+ * stderr 参与 pipe：失败信息带上 stderr 片段，避免只留一句无诊断价值的
+ * "Command failed"（历史教训：真因只存在于被丢弃的 stderr 里）。
+ */
+function runCodexCommandSync(args) {
+    const res = spawnProcessSync(CODEX_BINARY, args, {
+        encoding: 'utf-8',
+        timeout: CODEX_TIMEOUT_MS,
+        maxBuffer: CODEX_MAX_BUFFER,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (res.error)
+        throw res.error;
+    if (res.status !== 0) {
+        const stderr = String(res.stderr ?? '').trim();
+        throw new Error(`codex exited ${res.status}${stderr ? `: ${stderr.slice(0, 200)}` : ''}`);
+    }
+    return String(res.stdout ?? '');
+}
+/**
+ * 异步运行 codex CLI（spawnProcess + 流式收集），成功返回完整 stdout。
+ * 与同步路径同超时 / 输出上限；stdout 超 4MB 主动 kill（对齐 execFile maxBuffer 语义）。
+ */
+function runCodexCommandAsync(args) {
     return new Promise((resolve, reject) => {
-        execFile(file, args, {
-            encoding: 'utf-8',
-            timeout: 8_000,
-            maxBuffer: 4 * 1024 * 1024,
-            env: process.env,
-            windowsHide: true,
-        }, (err, stdout) => {
-            if (err)
-                reject(err);
-            else
-                resolve(stdout);
+        const child = spawnProcess(CODEX_BINARY, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => {
+                child.kill();
+                reject(new Error(`codex timed out after ${CODEX_TIMEOUT_MS}ms`));
+            });
+        }, CODEX_TIMEOUT_MS);
+        child.stdout?.on('data', (chunk) => {
+            stdout += String(chunk);
+            if (stdout.length > CODEX_MAX_BUFFER) {
+                settle(() => reject(new Error('codex stdout exceeded maxBuffer (4MB)')));
+                child.kill();
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', (err) => settle(() => reject(err)));
+        child.on('close', (code) => {
+            settle(() => {
+                if (code === 0) {
+                    resolve(stdout);
+                }
+                else {
+                    const tail = stderr.trim().slice(0, 200);
+                    reject(new Error(`codex exited ${code}${tail ? `: ${tail}` : ''}`));
+                }
+            });
         });
     });
 }

package/dist/config/index.js

@@ -256,7 +256,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/config/kimi-config.js

@@ -4,8 +4,8 @@
  * Dynamically reads available models from `kimi provider list --json`,
  * provides dynamic dropdown options for /config card.
  */
-import { execFileSync } from 'node:child_process';
 import { getLogger } from '../logger/index.js';
+import { spawnProcessSync } from '../platform/spawn.js';
 /** Valid thinking effort values for kimi (Layer 1: Schema enum source) */
 export const KIMI_THINKING_EFFORTS = ['low', 'high', 'max'];
 /** Fallback efforts when all values are filtered out */
@@ -30,13 +30,24 @@ export function loadKimiConfig() {
     }
     const logger = getLogger();
     try {
-        const output = execFileSync('kimi', ['provider', 'list', '--json'], {
-            stdio: ['ignore', 'pipe', 'ignore'],
+        // spawnProcessSync（cross-spawn）而非 execFileSync：kimi 是 npm 全局安装的
+        // .cmd 垫片，win32 上 execFileSync 不做 PATHEXT 解析（裸名解析到无扩展名的
+        // sh 脚本直接执行失败，.cmd 又 EINVAL）；cross-spawn 与 runner spawn 走
+        // 同一垫片执行路径（posix 直通）。stderr 参与 pipe 以便失败信息可诊断。
+        const res = spawnProcessSync('kimi', ['provider', 'list', '--json'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
             timeout: 10000,
             maxBuffer: 2 * 1024 * 1024,
-            windowsHide: true, // kimi 是 npm .cmd 垫片：不隐藏会闪 cmd.exe 控制台
+            encoding: 'utf-8',
         });
-        const data = JSON.parse(output.toString());
+        if (res.error)
+            throw res.error;
+        if (res.status !== 0) {
+            const stderr = String(res.stderr ?? '').trim();
+            throw new Error(`kimi exited ${res.status}${stderr ? `: ${stderr.slice(0, 200)}` : ''}`);
+        }
+        const output = String(res.stdout ?? '');
+        const data = JSON.parse(output);
         if (!data.models || Object.keys(data.models).length === 0) {
             logger.warn('[kimi-config] no models found in provider list, using defaults');
             return buildDefaultResult();

package/dist/connector/index.d.ts

@@ -82,6 +82,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;
@@ -140,11 +146,30 @@ export declare class FeishuConnector {
      * The SDK resolves the reaction id internally; missing reaction is a no-op.
      */
     removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
+    /**
+     * sendFile/sendImage 共用：校验文件存在与大小上限（30MB，对齐飞书
+     * im/v1 上传 API）。noun 是消息里的小写名词（'file'/'image'）。
+     */
+    private checkUploadable;
+    /**
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
+     * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
+     * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
+     * 标签（'sendFile' | 'sendImage'）。
+     */
+    private uploadAndSendMedia;
     /**
      * Upload a file to Feishu and send it to the specified chat.
      * Uses the im/v1/files upload API.
      */
     sendFile(chatId: string, filePath: string): Promise<string>;
+    /**
+     * Upload a local image file to Feishu and send it as an image message
+     * (im/v1/images + msg_type=image). Used by the clone wizard to deliver the
+     * scan-to-create QR code inline instead of as a downloadable file.
+     */
+    sendImage(chatId: string, filePath: string): Promise<string>;
     /**
      * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch

package/dist/connector/index.js

@@ -3,6 +3,7 @@ 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 { 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';
@@ -88,6 +89,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 +193,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;
@@ -344,18 +414,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 {
@@ -378,11 +437,10 @@ export class FeishuConnector {
         }
     }
     /**
-     * Upload a file to Feishu and send it to the specified chat.
-     * Uses the im/v1/files upload API.
+     * sendFile/sendImage 共用：校验文件存在与大小上限（30MB，对齐飞书
+     * im/v1 上传 API）。noun 是消息里的小写名词（'file'/'image'）。
      */
-    async sendFile(chatId, filePath) {
-        // Check file existence first with proper error handling
+    checkUploadable(filePath, noun) {
         let stat;
         try {
             stat = fs.statSync(filePath);
@@ -390,33 +448,32 @@ export class FeishuConnector {
         catch (err) {
             const code = err.code;
             if (code === 'ENOENT') {
-                throw new Error(`Cannot access file: file not found (${filePath})`, { cause: err });
+                throw new Error(`Cannot access ${noun}: file not found (${filePath})`, { cause: err });
             }
-            throw new Error(`Cannot access file: ${err.message}`, { cause: err });
+            throw new Error(`Cannot access ${noun}: ${err.message}`, { cause: err });
         }
-        // Check file size limit (30MB, aligned with Feishu im/v1/files API)
         if (stat.size > MAX_FILE_UPLOAD_SIZE) {
-            throw new Error(`File too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
+            const nounCap = noun.charAt(0).toUpperCase() + noun.slice(1);
+            throw new Error(`${nounCap} too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
         }
-        const fileName = displayName(filePath);
-        // P2-18: capture the read stream so it can be destroyed on any failure
-        // path. Without this, a token/upload/send failure leaks the fd (axios
-        // only closes the stream when it fully consumes it on success).
+    }
+    /**
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
+     * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
+     * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
+     * 标签（'sendFile' | 'sendImage'）。
+     */
+    async uploadAndSendMedia(chatId, filePath, label, uploadUrl, buildForm, keyField, msgType) {
         let fileStream = null;
         try {
-            // P2-18: tenant_access_token cache. Avoid re-fetching on every file send
-            // (token is valid ~2h); validate data.code before trusting the token.
+            // P2-18: tenant_access_token cache（~2h），避免每次发送都取 token。
             const accessToken = await this.getTenantAccessToken();
-            // Upload file
-            const form = new FormData();
             fileStream = fs.createReadStream(filePath);
-            form.append('file', fileStream);
-            form.append('file_name', fileName);
-            form.append('file_type', 'stream');
-            // P2-18: timeout on the upload (large file, slow link) — 120s.
-            // httpsAgent: noKeepAlive — prevents Bun from reusing a server-RST'd
-            // keep-alive socket (ECONNRESET after ~30s; see noKeepAliveAgent docs).
-            const uploadResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/files', form, {
+            const form = buildForm(fileStream);
+            // P2-18: timeout 120s（大文件慢链路）；httpsAgent: noKeepAlive 防止
+            // Bun 复用已被服务端 RST 的 keep-alive socket（ECONNRESET after ~30s）。
+            const uploadResp = await axios.post(uploadUrl, form, {
                 headers: {
                     ...form.getHeaders(),
                     Authorization: `Bearer ${accessToken}`,
@@ -425,15 +482,14 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (uploadResp.data.code !== 0) {
-                throw new Error(`File upload failed: ${uploadResp.data.msg}`);
+                throw new Error(`Upload failed: ${uploadResp.data.msg}`);
             }
-            const fileKey = uploadResp.data.data.file_key;
-            // Send file message. P2-18: timeout 30s.
-            // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
+            const mediaKey = uploadResp.data.data[keyField];
+            // P2-18: timeout 30s；noKeepAlive 同上。
             const sendResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/messages', {
                 receive_id: chatId,
-                msg_type: 'file',
-                content: JSON.stringify({ file_key: fileKey }),
+                msg_type: msgType,
+                content: JSON.stringify({ [keyField]: mediaKey }),
             }, {
                 headers: {
                     'Content-Type': 'application/json; charset=utf-8',
@@ -444,7 +500,7 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (sendResp.data.code !== 0) {
-                throw new Error(`File message failed: ${sendResp.data.msg}`);
+                throw new Error(`Media message failed: ${sendResp.data.msg}`);
             }
             return sendResp.data.data.message_id;
         }
@@ -458,12 +514,39 @@ export class FeishuConnector {
                     /* already destroyed */
                 }
             }
-            // Log the error but throw a formatted error to prevent unhandled rejection
             const errorInfo = this.formatError(err);
-            getLogger().error('[feishu] sendFile failed:', errorInfo);
-            throw new Error(`sendFile failed: ${errorInfo}`, { cause: err });
+            getLogger().error(`[feishu] ${label} failed:`, errorInfo);
+            throw new Error(`${label} failed: ${errorInfo}`, { cause: err });
         }
     }
+    /**
+     * Upload a file to Feishu and send it to the specified chat.
+     * Uses the im/v1/files upload API.
+     */
+    async sendFile(chatId, filePath) {
+        this.checkUploadable(filePath, 'file');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendFile', 'https://open.feishu.cn/open-apis/im/v1/files', (stream) => {
+            const form = new FormData();
+            form.append('file', stream);
+            form.append('file_name', displayName(filePath));
+            form.append('file_type', 'stream');
+            return form;
+        }, 'file_key', 'file');
+    }
+    /**
+     * Upload a local image file to Feishu and send it as an image message
+     * (im/v1/images + msg_type=image). Used by the clone wizard to deliver the
+     * scan-to-create QR code inline instead of as a downloadable file.
+     */
+    async sendImage(chatId, filePath) {
+        this.checkUploadable(filePath, 'image');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendImage', 'https://open.feishu.cn/open-apis/im/v1/images', (stream) => {
+            const form = new FormData();
+            form.append('image_type', 'message');
+            form.append('image', stream);
+            return form;
+        }, 'image_key', 'image');
+    }
     /**
      * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch

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。流式卡片是尽力而为的展示层，飞书侧业务拒绝不应击穿进程。