lark-remote 0.3.0 → 0.4.1

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),
         });
     }
     /**
@@ -209,7 +208,7 @@ export class Bridge {
             if (!settings)
                 continue;
             void runner.updateApprovalMode(settings).catch((err) => {
-                getLogger().warn(`[bridge] sync approval mode failed cwd=${cwd}: ${err.message}`);
+                getLogger().warn(`[lark-remote] sync approval mode failed cwd=${cwd}: ${err.message}`);
             });
         }
     }
@@ -521,7 +520,7 @@ export class Bridge {
             if (active.userId === input.userId && active.chatId === input.chatId) {
                 if (input.runId && active.runId !== input.runId)
                     continue;
-                getLogger().info(`[bridge] interrupt hit runId=${active.runId} cwd=${cwd} userId=${input.userId}`);
+                getLogger().info(`[lark-remote] interrupt hit runId=${active.runId} cwd=${cwd} userId=${input.userId}`);
                 // Stop the EXACT runner instance that is running (carried by activeRun),
                 // not whatever getRunner(cwd) would return now. clearRunners() may have
                 // emptied the cache mid-run, in which case getRunner creates a fresh empty
@@ -564,7 +563,7 @@ export class Bridge {
                 if (stoppedSlot !== undefined) {
                     this.queueManager.resetExecutingCount(cwd, stoppedSlot);
                 }
-                getLogger().info(`[bridge] interrupt stop done runId=${active.runId}`);
+                getLogger().info(`[lark-remote] interrupt stop done runId=${active.runId}`);
                 return true;
             }
         }
@@ -576,16 +575,16 @@ export class Bridge {
             if (b.userId === input.userId && b.chatId === input.chatId) {
                 if (input.runId && runId !== input.runId)
                     continue;
-                getLogger().info(`[bridge] interrupt hit bash runId=${runId} cwd=${b.cwd} userId=${input.userId}`);
+                getLogger().info(`[lark-remote] interrupt hit bash runId=${runId} cwd=${b.cwd} userId=${input.userId}`);
                 await b.bashRunner.stop({ immediate: true });
                 // Update card to show interrupted state
                 await b.cardSession.finish('interrupted', { exitCode: -1 });
                 this.activeBashRuns.delete(runId);
-                getLogger().info(`[bridge] interrupt bash stop done runId=${runId}`);
+                getLogger().info(`[lark-remote] interrupt bash stop done runId=${runId}`);
                 return true;
             }
         }
-        getLogger().debug(`[bridge] interrupt miss userId=${input.userId}`);
+        getLogger().debug(`[lark-remote] interrupt miss userId=${input.userId}`);
         return false;
     }
     /** Send a result message to the user (§7). Returns true on success, false on failure. */
@@ -595,26 +594,26 @@ export class Bridge {
                 // 静态卡片体积保护：确保卡片不超过飞书大小限制
                 const { card: safeCard, wasTruncated, reason, bytesBefore, bytesAfter, } = enforceCardBudget(result.card);
                 if (wasTruncated) {
-                    getLogger().info(`[bridge] card size exceeded limit, applied budget enforcement: reason=${reason} bytesBefore=${bytesBefore} bytesAfter=${bytesAfter}`);
+                    getLogger().info(`[lark-remote] card size exceeded limit, applied budget enforcement: reason=${reason} bytesBefore=${bytesBefore} bytesAfter=${bytesAfter}`);
                 }
-                getLogger().debug(`[bridge] sendResult kind=card chatId=${ctx.chatId}`);
+                getLogger().debug(`[lark-remote] sendResult kind=card chatId=${ctx.chatId}`);
                 await this.connector.sendWithRetry(ctx.chatId, { card: safeCard }, { replyTo: ctx.messageId });
                 return true;
             }
             else if (result.markdown) {
-                getLogger().debug(`[bridge] sendResult kind=markdown chatId=${ctx.chatId}`);
+                getLogger().debug(`[lark-remote] sendResult kind=markdown chatId=${ctx.chatId}`);
                 await this.connector.sendWithRetry(ctx.chatId, { markdown: result.markdown }, { replyTo: ctx.messageId });
                 return true;
             }
             else if (result.text) {
-                getLogger().debug(`[bridge] sendResult kind=text chatId=${ctx.chatId}`);
+                getLogger().debug(`[lark-remote] sendResult kind=text chatId=${ctx.chatId}`);
                 await this.connector.sendWithRetry(ctx.chatId, { text: result.text }, { replyTo: ctx.messageId });
                 return true;
             }
             return false;
         }
         catch (err) {
-            getLogger().error('[bridge] failed to send result:', err);
+            getLogger().error('[lark-remote] failed to send result:', err);
             // 不静默：向用户发送一条纯文本消息，告知具体错误（如飞书 11310 element exceeds
             // the limit）。如果用户看到空白无反馈，无法判断是命令无效还是卡片发送失败。
             try {
@@ -622,7 +621,7 @@ export class Bridge {
                 await this.connector.sendWithRetry(ctx.chatId, { text: `⚠️ 卡片发送失败：${errMsg}` }, { replyTo: ctx.messageId });
             }
             catch (fallbackErr) {
-                getLogger().error('[bridge] fallback text send also failed:', fallbackErr);
+                getLogger().error('[lark-remote] fallback text send also failed:', fallbackErr);
             }
             return false;
         }
@@ -642,18 +641,18 @@ export class Bridge {
      */
     async updateCardInPlace(card, ctx) {
         if (!ctx.messageId) {
-            getLogger().warn('[bridge] updateCardInPlace missing messageId, falling back to sendResult');
+            getLogger().warn('[lark-remote] updateCardInPlace missing messageId, falling back to sendResult');
             await this.sendResult({ card }, ctx);
             return false;
         }
         try {
-            getLogger().debug(`[bridge] updateCardInPlace messageId=${ctx.messageId}`);
+            getLogger().debug(`[lark-remote] updateCardInPlace messageId=${ctx.messageId}`);
             await this.connector.updateCard(ctx.messageId, card);
             return true;
         }
         catch (err) {
             const errMsg = err.message ?? String(err);
-            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${errMsg}`);
+            getLogger().warn(`[lark-remote] updateCardInPlace failed, falling back to sendResult: ${errMsg}`);
             // 先尝试 fallback 发卡片；若卡片本身有问题（如 11310），
             // sendResult 内部 catch 会发纯文本通知用户。
             await this.sendResult({ card }, ctx);
@@ -663,25 +662,20 @@ export class Bridge {
     /** Send a file to the user via Feishu. */
     async sendFile(filePath, ctx) {
         try {
-            getLogger().debug(`[bridge] sendFile path=${filePath} chatId=${ctx.chatId}`);
+            getLogger().debug(`[lark-remote] sendFile path=${filePath} chatId=${ctx.chatId}`);
             await this.connector.sendFile(ctx.chatId, filePath);
         }
         catch (err) {
-            getLogger().error('[bridge] failed to send file:', err);
+            getLogger().error('[lark-remote] failed to send file:', err);
             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.
@@ -697,7 +691,7 @@ export class Bridge {
                 // NOTE: fallback uses insertion order, not sort preference — by design
                 // (cwd fallback stays insertion-order for now)
                 cwd = workspaces[0].path;
-                getLogger().info(`[bridge] resolveCwd fallback cwd=${cwd} (first saved workspace)`);
+                getLogger().info(`[lark-remote] resolveCwd fallback cwd=${cwd} (first saved workspace)`);
             }
         }
         return cwd;
@@ -724,11 +718,11 @@ export class Bridge {
             return;
         }
         const entry = this.sessionStore.get(ctx.userId);
-        getLogger().debug(`[bridge] forward entry userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} ` +
+        getLogger().debug(`[lark-remote] forward entry userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} ` +
             `agent=${agentKind} sessionId=${opts?.binding?.sessionId ?? entry?.sessions?.get(agentKind) ?? '(none)'} message=${message.slice(0, 100)}`);
         // Check if current workspace already has a run in progress
         if (this.activeRuns.has(cwd)) {
-            getLogger().warn(`[bridge] workspace busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
+            getLogger().warn(`[lark-remote] workspace busy, dropping message userId=${ctx.userId} cwd=${cwd}`);
             await this.sendResult({ text: '此 workspace 正在处理中，请 /stop 后重试' }, ctx);
             return;
         }
@@ -759,7 +753,7 @@ export class Bridge {
      */
     createRunSession(ctx, cwd, runner, agentKind = this.config.defaultAgent) {
         const runId = randomUUID();
-        getLogger().debug(`[bridge] creating runCard runId=${runId}`);
+        getLogger().debug(`[lark-remote] creating runCard runId=${runId}`);
         // D5: agentKind 来自入队绑定（forwardToClaude 解析），不再读 live config。
         // 缓存键 (cwd, agentKind) 和 eviction 都用这个值（review P2-3）。
         const cardSession = new RunCardSession({
@@ -785,7 +779,7 @@ export class Bridge {
             agentKind,
         };
         this.activeRuns.set(cwd, activeRun);
-        getLogger().info(`[bridge] activeRuns.set cwd=${cwd} runId=${runId}`);
+        getLogger().info(`[lark-remote] activeRuns.set cwd=${cwd} runId=${runId}`);
         return { runId, cardSession, activeRun };
     }
     /**
@@ -860,18 +854,18 @@ export class Bridge {
         });
         try {
             try {
-                getLogger().debug(`[bridge] cardSession.start() begin runId=${runId}`);
+                getLogger().debug(`[lark-remote] cardSession.start() begin runId=${runId}`);
                 await cardSession.start();
-                getLogger().info(`[bridge] cardSession.start() ok runId=${runId}`);
+                getLogger().info(`[lark-remote] cardSession.start() ok runId=${runId}`);
             }
             catch (err) {
-                getLogger().warn('[bridge] card stream unavailable, will use static fallback:', err);
+                getLogger().warn('[lark-remote] card stream unavailable, will use static fallback:', err);
                 // Card stream failed - continue with static fallback below, but ensure
                 // we don't silently fail if the fallback also fails (covered in catch below).
             }
             if (cardSession.currentState.terminal !== 'running') {
                 // Card session did not enter running state - still try to send static fallback
-                getLogger().info(`[bridge] cardSession not running, using static fallback`);
+                getLogger().info(`[lark-remote] cardSession not running, using static fallback`);
             }
             // P2-1: 单 interval 看门狗。事件到来时只刷新 lastEventTs（无 timer 操作）；
             // interval 周期检查 `now - lastEventTs > idleTimeoutMs`，超时才触发 stop。
@@ -891,7 +885,7 @@ export class Bridge {
                 if (idleInterval)
                     clearInterval(idleInterval);
                 idleInterval = null;
-                getLogger().warn(`[bridge] claude idle timeout, stopping process runId=${runId}`);
+                getLogger().warn(`[lark-remote] claude idle timeout, stopping process runId=${runId}`);
                 void Promise.allSettled([
                     cardSession.finish('idle_timeout', {
                         idleTimeoutMinutes: Math.max(1, Math.round(this.idleTimeoutMs / 60_000)),
@@ -912,7 +906,7 @@ export class Bridge {
             }
             resetIdle();
             let contextLength;
-            getLogger().info(`[bridge] runner.run() begin runId=${runId} message=${message.slice(0, 100)}`);
+            getLogger().info(`[lark-remote] runner.run() begin runId=${runId} message=${message.slice(0, 100)}`);
             // Extract agent-specific options from config
             const agentOpts = this.getAgentRunOptions(agentKind);
             const runOpts = { cwd, sessionId, ...agentOpts };
@@ -940,7 +934,7 @@ export class Bridge {
                     // task-notification 注入触发 Claude 重发 init，已终止的 run 被复活）。
                     const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
                     if (pointerMoved) {
-                        getLogger().info(`[bridge] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
+                        getLogger().info(`[lark-remote] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
                     }
                     else {
                         // L5: Use session's real directory from event.cwd (not runner's cwd parameter)
@@ -952,7 +946,7 @@ export class Bridge {
                         if (hasCwd && event.cwd && event.cwd !== cwd) {
                             // Session has its own cwd (e.g. EnterWorktree relocate). Keep the
                             // workspace cwd unchanged; record the session's actual cwd in sessionCwds.
-                            getLogger().info(`[bridge] system.init: workspace cwd=${cwd}, session cwd=${event.cwd}`);
+                            getLogger().info(`[lark-remote] system.init: workspace cwd=${cwd}, session cwd=${event.cwd}`);
                             this.sessionStore.setSessionIdAndSessionCwd(ctx.userId, agentKind, event.session_id, realCwd);
                         }
                         else {
@@ -962,7 +956,7 @@ export class Bridge {
                             this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, realCwd, bootstrapSessionCwd);
                         }
                     }
-                    getLogger().info(`[bridge] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
+                    getLogger().info(`[lark-remote] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
                 }
                 if (event.type === 'turn_started') {
                     // app-server runner 在 turn setup 成功后补发 synthetic system.init
@@ -972,10 +966,10 @@ export class Bridge {
                     const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
                     if (!pointerMoved) {
                         this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.threadId, cwd);
-                        getLogger().info(`[bridge] turn_started session write-back runId=${runId} sessionId=${event.threadId}`);
+                        getLogger().info(`[lark-remote] turn_started session write-back runId=${runId} sessionId=${event.threadId}`);
                     }
                     else {
-                        getLogger().info(`[bridge] turn_started write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.threadId}`);
+                        getLogger().info(`[lark-remote] turn_started write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.threadId}`);
                     }
                 }
                 // Track context length from compaction events
@@ -999,7 +993,7 @@ export class Bridge {
                     // 卡片不会把半初始化的 run 当作已收尾。
                     const preInitResult = !sawInit;
                     if (preInitResult && usageAuthority !== 'live') {
-                        getLogger().info(`[bridge] pre-init result ignored (resume replay) runId=${runId}`);
+                        getLogger().info(`[lark-remote] pre-init result ignored (resume replay) runId=${runId}`);
                         // Still reset idle timer — the CLI is alive and producing events.
                         resetIdle();
                         // Do NOT push to cardSession: the run-state reducer would also
@@ -1012,8 +1006,8 @@ export class Bridge {
                     }
                     resultNotSuccess = event.subtype !== 'success';
                     getLogger().info(preInitResult
-                        ? `[bridge] pre-init result from live runner (app-server setup failure) runId=${runId}`
-                        : `[bridge] result event received runId=${runId}`);
+                        ? `[lark-remote] pre-init result from live runner (app-server setup failure) runId=${runId}`
+                        : `[lark-remote] result event received runId=${runId}`);
                     // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）
                     // 不会有 turn_started 事件，store 不会写回新线程 id；runner 已在 result
                     // 里兜底上报（review P3-10）。此处仅当 runner 声明 live usage（app-server）
@@ -1023,7 +1017,7 @@ export class Bridge {
                         event.session_id &&
                         this.sessionStore.getSessionEpoch(ctx.userId, agentKind) === sessionEpochAtStart) {
                         this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, cwd);
-                        getLogger().info(`[bridge] result session write-back runId=${runId} sessionId=${event.session_id}`);
+                        getLogger().info(`[lark-remote] result session write-back runId=${runId} sessionId=${event.session_id}`);
                     }
                     // result 后进入 finalizing 非终态（暂存 subtype/errorMsg），由 for-await
                     // 自然结束后在 finally 转 done/error。提取 usage 信息。
@@ -1065,13 +1059,13 @@ export class Bridge {
                             await this.connector.removeReactionByEmoji(ctx.messageId, 'Typing');
                         }
                         catch (err) {
-                            getLogger().warn(`[bridge] remove Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                            getLogger().warn(`[lark-remote] remove Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
                         }
                         try {
                             await this.connector.addReaction(ctx.messageId, 'Typing');
                         }
                         catch (err) {
-                            getLogger().warn(`[bridge] re-add Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                            getLogger().warn(`[lark-remote] re-add Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
                         }
                     })();
                     let coordinator = this.approvalCoordinators.get(runId);
@@ -1095,7 +1089,7 @@ export class Bridge {
                             },
                         });
                         this.approvalCoordinators.set(runId, coordinator);
-                        getLogger().info(`[bridge] approval coordinator created runId=${runId.slice(0, 8)} requestId=${event.requestId}`);
+                        getLogger().info(`[lark-remote] approval coordinator created runId=${runId.slice(0, 8)} requestId=${event.requestId}`);
                     }
                     coordinator.onRequested(event);
                 }
@@ -1116,7 +1110,7 @@ export class Bridge {
                 resetIdle();
                 await cardSession.push(event);
             }
-            getLogger().info(`[bridge] runner stream end runId=${runId} sawResult=${sawResult}`);
+            getLogger().info(`[lark-remote] runner stream end runId=${runId} sawResult=${sawResult}`);
             // §9.12 红线（§P1-2 方案 A 第 2 点）：for-await 自然结束 = CLI 已退出，
             // 看门狗使命结束，立即摘除 interval（不再等 finally），堵掉「stream 已结束、
             // 收尾处理跨过死线被误标 idle_timeout」的同源小窗口（P2-4 随本修复一并关闭）。
@@ -1167,7 +1161,7 @@ export class Bridge {
                 finalCacheCreationTokens = finalUsage?.cacheCreationTokens ?? finalCacheCreationTokens;
                 finalTotalTokens = finalUsage?.totalTokens ?? finalTotalTokens;
             }
-            getLogger().info(`[bridge] final usage runId=${runId} contextLength=${finalContextLength} contextLimit=${finalContextLimit ?? 'undefined'} compactCount=${finalCompactCount ?? 'undefined'} cacheRead=${finalCacheReadTokens ?? 'undefined'} cacheCreate=${finalCacheCreationTokens ?? 'undefined'}`);
+            getLogger().info(`[lark-remote] final usage runId=${runId} contextLength=${finalContextLength} contextLimit=${finalContextLimit ?? 'undefined'} compactCount=${finalCompactCount ?? 'undefined'} cacheRead=${finalCacheReadTokens ?? 'undefined'} cacheCreate=${finalCacheCreationTokens ?? 'undefined'}`);
             // for-await 自然结束 = stream 关闭 = CLI 进程退出。
             // 进程退出（for-await end）= 唯一终态触发源。
             // 1) finalizing（result 已收到）-> 转 done/error + usage meta
@@ -1200,14 +1194,14 @@ export class Bridge {
             // else: 已终态且未收到 result（如 spawn 失败后 interrupted）-> 无 usage 可补，跳过
         }
         catch (err) {
-            getLogger().error(`[bridge] claude run error runId=${runId}:`, err);
+            getLogger().error(`[lark-remote] claude run error runId=${runId}:`, err);
             // P1-11 双保险：run() 的 finally 已负责杀子进程，但 catch 路径再补一次
             // runner.stop()（与 bash 路径对齐），覆盖任何 finally 之外的残留窗口。
             try {
                 await runner.stop();
             }
             catch (stopErr) {
-                getLogger().warn(`[bridge] runner stop failed:`, stopErr);
+                getLogger().warn(`[lark-remote] runner stop failed:`, stopErr);
             }
             // 终态守卫：running 或 finalizing（非终态）-> 转 error；
             // 已终态（interrupted/idle_timeout/done/error）-> 保留首终态，仅补充 usage。
@@ -1221,7 +1215,7 @@ export class Bridge {
                 });
             }
             else {
-                getLogger().info(`[bridge] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
+                getLogger().info(`[lark-remote] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
                 if (sawResult) {
                     await cardSession.finish(catchTerminal, usageMeta());
                 }
@@ -1244,7 +1238,7 @@ export class Bridge {
     async finalizeRun(cardSession, activeRun, ctx, cwd) {
         const runId = activeRun.runId;
         try {
-            getLogger().debug(`[bridge] finally settle runId=${runId} state.terminal=${cardSession.currentState.terminal}`);
+            getLogger().debug(`[lark-remote] finally settle runId=${runId} state.terminal=${cardSession.currentState.terminal}`);
             const settleResult = await cardSession.settle();
             let runCardSent = false;
             if (settleResult === 'unsent') {
@@ -1316,7 +1310,7 @@ export class Bridge {
                         });
                     }
                 }
-                getLogger().info(`[bridge] activeRuns.delete cwd=${cwd} runId=${runId}`);
+                getLogger().info(`[lark-remote] activeRuns.delete cwd=${cwd} runId=${runId}`);
             }
         }
     }
@@ -1353,14 +1347,14 @@ export class Bridge {
             // sessions produced >28KB cards that Feishu silently rejected).
             const sent = await this.sendResult({ card }, ctx);
             if (sent) {
-                getLogger().debug(`[bridge] completion notification sent sessionId=${sessionId} chatId=${ctx.chatId}`);
+                getLogger().debug(`[lark-remote] completion notification sent sessionId=${sessionId} chatId=${ctx.chatId}`);
             }
             else {
-                getLogger().warn(`[bridge] failed to send completion notification card sessionId=${sessionId}`);
+                getLogger().warn(`[lark-remote] failed to send completion notification card sessionId=${sessionId}`);
             }
         }
         catch (err) {
-            getLogger().warn(`[bridge] failed to send completion notification card:`, err);
+            getLogger().warn(`[lark-remote] failed to send completion notification card:`, err);
         }
     }
     // =============================================================================
@@ -1375,7 +1369,7 @@ export class Bridge {
         if (!coordinator) {
             // P2-7: run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
             // 不能静默。router 会把该异常转成 error toast。
-            getLogger().warn(`[bridge] no approval coordinator for runId=${runId.slice(0, 8)}`);
+            getLogger().warn(`[lark-remote] no approval coordinator for runId=${runId.slice(0, 8)}`);
             throw new Error('任务已结束，审批无法响应');
         }
         return fn(coordinator);
@@ -1386,7 +1380,7 @@ export class Bridge {
      */
     async handleApprovalRespond(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
+        log.info(`[lark-remote] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
         return this.withCoordinator(opts.runId, async (coordinator) => {
             // Build ApprovalAction from the decision string
             const action = decisionToApprovalAction(opts.decision);
@@ -1408,7 +1402,7 @@ export class Bridge {
      */
     async handleApprovalToggle(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
+        log.info(`[lark-remote] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
         return this.withCoordinator(opts.runId, async (coordinator) => {
             // selected 由卡片根据当前渲染状态传回（取反），不再硬编码只授不撤。
             const toggleAction = {
@@ -1424,7 +1418,7 @@ export class Bridge {
      */
     async handleApprovalAnswer(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalAnswer runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        log.info(`[lark-remote] handleApprovalAnswer runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.toggleAnswer({ questionIndex: opts.questionIndex, option: opts.option }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
@@ -1433,7 +1427,7 @@ export class Bridge {
      */
     async handleApprovalAnswerSubmit(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalAnswerSubmit runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        log.info(`[lark-remote] handleApprovalAnswerSubmit runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
@@ -1442,7 +1436,7 @@ export class Bridge {
      */
     async handleApprovalAnswerCustom(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalAnswerCustom runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        log.info(`[lark-remote] handleApprovalAnswerCustom runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.answerCustom({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
@@ -1452,7 +1446,7 @@ export class Bridge {
      */
     async handleApprovalAnswerNote(opts) {
         const log = getLogger();
-        log.info(`[bridge] handleApprovalAnswerNote runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        log.info(`[lark-remote] handleApprovalAnswerNote runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
         return this.withCoordinator(opts.runId, (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
     }
     /**
@@ -1463,7 +1457,7 @@ export class Bridge {
      */
     async handleCodexCompact(value, ctx) {
         const log = getLogger();
-        log.info(`[bridge] handleCodexCompact userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
+        log.info(`[lark-remote] handleCodexCompact userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
         const { runId } = value;
         if (!runId) {
             await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
@@ -1494,7 +1488,7 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
             return;
         }
-        log.info(`[bridge] handleCodexCompact executing runCompact for runId=${runId} cwd=${cwd}`);
+        log.info(`[lark-remote] handleCodexCompact executing runCompact for runId=${runId} cwd=${cwd}`);
         await this.streamCodexCompact({
             sessionId: last.sessionId,
             cwd,
@@ -1529,7 +1523,7 @@ export class Bridge {
             }
         }
         catch (err) {
-            getLogger().warn(`[bridge] readCompactionState failed sessionId=${sessionId}: ${errorMessage(err)}`);
+            getLogger().warn(`[lark-remote] readCompactionState failed sessionId=${sessionId}: ${errorMessage(err)}`);
         }
         return false;
     }
@@ -1546,7 +1540,7 @@ export class Bridge {
     async streamCodexCompact(opts) {
         const log = getLogger();
         const { sessionId, cwd, agentKind, runner, ctx } = opts;
-        log.info(`[bridge] streamCodexCompact sessionId=${sessionId} cwd=${cwd}`);
+        log.info(`[lark-remote] streamCodexCompact sessionId=${sessionId} cwd=${cwd}`);
         // 防御性能力检查：调用方已校验（runId / resume 两条路径），此处双保险并
         // 让 TS 收窄 runner 类型（'runCompact' in runner 之后的 cast 才合法）。
         if (!('runCompact' in runner) ||
@@ -1618,10 +1612,10 @@ export class Bridge {
                 cumulativeCacheReadTokens: finalUsage?.cumulativeCacheReadTokens,
                 cumulativeCacheCreationTokens: finalUsage?.cumulativeCacheCreationTokens,
             });
-            log.info(`[bridge] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
+            log.info(`[lark-remote] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
         }
         catch (err) {
-            log.error(`[bridge] streamCodexCompact failed: ${errorMessage(err)}`);
+            log.error(`[lark-remote] streamCodexCompact failed: ${errorMessage(err)}`);
             await cardSession.finish('error', { errorMsg: errorMessage(err) });
         }
     }
@@ -1636,7 +1630,7 @@ export class Bridge {
      */
     async handleResumeCompact(value, ctx) {
         const log = getLogger();
-        log.info(`[bridge] handleResumeCompact userId=${ctx.userId} sessionId=${value.sessionId?.slice(0, 16)} agent=${value.agent ?? 'default'}`);
+        log.info(`[lark-remote] handleResumeCompact userId=${ctx.userId} sessionId=${value.sessionId?.slice(0, 16)} agent=${value.agent ?? 'default'}`);
         const { sessionId } = value;
         if (!sessionId) {
             await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 sessionId' }, ctx);
@@ -1682,7 +1676,7 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
             return;
         }
-        log.info(`[bridge] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
+        log.info(`[lark-remote] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
         await this.streamCodexCompact({ sessionId, cwd, agentKind, runner, ctx });
     }
     /**
@@ -1693,13 +1687,13 @@ export class Bridge {
      */
     async executeBash(command, ctx) {
         const cwd = this.resolveCwd(ctx.userId);
-        getLogger().info(`[bridge] executeBash start userId=${ctx.userId} sessionCwd=${this.sessionStore.get(ctx.userId)?.cwd} command="${command.slice(0, 30)}..."`);
+        getLogger().info(`[lark-remote] executeBash start userId=${ctx.userId} sessionCwd=${this.sessionStore.get(ctx.userId)?.cwd} command="${command.slice(0, 30)}..."`);
         if (!cwd) {
-            getLogger().info(`[bridge] executeBash no cwd, sending error`);
+            getLogger().info(`[lark-remote] executeBash no cwd, sending error`);
             await this.sendResult({ text: '请先使用 /cd <path> 设置工作目录，或保存一个 workspace (/ws save <name>)' }, ctx);
             return;
         }
-        getLogger().info(`[bridge] executeBash proceeding cwd=${cwd}`);
+        getLogger().info(`[lark-remote] executeBash proceeding cwd=${cwd}`);
         // `!` commands bypass the serial queue entirely (design.md §9.6):
         // index.ts dispatches `!` to router.handle → executeBash directly, NOT via
         // bridge.enqueue. bash runs in parallel with same-workspace claude runs.
@@ -1715,7 +1709,7 @@ export class Bridge {
      * bypassing the serial queue — see executeBash).
      */
     async executeBashInternal(command, ctx, cwd) {
-        getLogger().debug(`[bridge] executeBashInternal userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} command="${command.slice(0, 50)}..."`);
+        getLogger().debug(`[lark-remote] executeBashInternal userId=${ctx.userId} chatId=${ctx.chatId} cwd=${cwd} command="${command.slice(0, 50)}..."`);
         // Note: We don't check activeRuns here because bash bypasses the serial
         // queue and runs in parallel with same-workspace agent runs (§9.6). The
         // activeRuns check in forwardToClaude is for a different purpose (detecting
@@ -1752,13 +1746,13 @@ export class Bridge {
         let stderr = '';
         let exitCode = null;
         try {
-            getLogger().info(`[bridge] executeBashInternal about to start stream chatId=${ctx.chatId} messageId=${ctx.messageId}`);
+            getLogger().info(`[lark-remote] executeBashInternal about to start stream chatId=${ctx.chatId} messageId=${ctx.messageId}`);
             try {
                 await cardSession.start();
-                getLogger().info(`[bridge] executeBash stream started runId=${runId}`);
+                getLogger().info(`[lark-remote] executeBash stream started runId=${runId}`);
             }
             catch (err) {
-                getLogger().warn('[bridge] bash card stream unavailable:', err);
+                getLogger().warn('[lark-remote] bash card stream unavailable:', err);
             }
             for await (const event of bashRunner.run(command, { cwd })) {
                 if (event.type === 'stdout') {
@@ -1780,7 +1774,7 @@ export class Bridge {
             await cardSession.finish(exitCode === 0 ? 'done' : 'error', { exitCode, output, stderr });
         }
         catch (err) {
-            getLogger().error(`[bridge] bash run error runId=${runId}:`, err);
+            getLogger().error(`[lark-remote] bash run error runId=${runId}:`, err);
             // If for-await threw mid-stream the bash child may still be running.
             // Stop it before finalizing the card — otherwise the finally block
             // removes the activeBashRuns entry and /stop can no longer reach it,
@@ -1789,7 +1783,7 @@ export class Bridge {
                 await bashRunner.stop();
             }
             catch (stopErr) {
-                getLogger().warn(`[bridge] bash stop failed:`, stopErr);
+                getLogger().warn(`[lark-remote] bash stop failed:`, stopErr);
             }
             await cardSession.finish('error', {
                 exitCode: 1,
@@ -1811,7 +1805,7 @@ export class Bridge {
             }
             if (this.activeBashRuns.has(runId)) {
                 this.activeBashRuns.delete(runId);
-                getLogger().info(`[bridge] executeBash done runId=${runId} exitCode=${exitCode}`);
+                getLogger().info(`[lark-remote] executeBash done runId=${runId} exitCode=${exitCode}`);
             }
             // Add a Done emoji reaction to the user's original message to signal completion
             void this.connector.addReaction(ctx.messageId, 'Done');

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/clone.d.ts

@@ -2,7 +2,7 @@ import { type QRCodeInfo, type RegisterAppResult } from '@larksuite/channel';
 /**
  * 复制分身（/clone）状态机。
  *
- * 在当前 bridge 进程内引导用户扫码创建一个新飞书应用，并生成一份"分身"
+ * 在当前 lark-remote 进程内引导用户扫码创建一个新飞书应用，并生成一份"分身"
  * 配置目录：除 feishu.appId/appSecret 来自新应用外，其余配置原样复制；
  * 创建完成后用新应用拿到的用户 openId 直接写好绑定（owner 无需再输入
  * 任意内容认领），并 detached 拉起指向新配置目录的新实例——启动后新

package/dist/common/fs.js

@@ -22,7 +22,7 @@ export function silentlyUnlink(path) {
  * win32 句柄占用重试：rename/unlink 目标被
  * 其他句柄持有时报 EPERM/EBUSY（共享冲突），短暂退避后重试通常即可成功。
  * 仅 win32 启用重试：posix 上这两个错误码不是「占用瞬态」语义（如 NFS 权限
- * 问题），立即失败——避免忙等阻塞单线程 bridge 的事件循环。
+ * 问题），立即失败——避免忙等阻塞单线程 lark-remote 的事件循环。
  */
 const BUSY_CODES = new Set(['EPERM', 'EBUSY']);
 /**