lark-remote 0.3.0 → 0.4.1

package/dist/inbound/turn-assembler.js

@@ -0,0 +1,233 @@
+/**
+ * InboundTurnAssembler：统一静默期窗口 + 合并 + 下载等待 + commit。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4/§5.2。
+ *
+ * 规则：
+ * - 任何事件到达 → **重置** 700ms 定时器（按 `userId:chatId` 分桶），保证图/文任意顺序等价；
+ * - 定时器到点 → 若本 turn 仍有 in-flight 下载 → 等待，落定后再 commit；
+ * - 下载失败/超时 → 该项进 `rejected`，然后照常 commit；
+ * - commit → 构造 prompt（`prompt.ts`）→ `onCommit`；
+ * - **无文本且只有附件 → 不 commit**（决策 2），只发 `onReceipt` 回执；
+ * - 命令消息由调用方 `flush()` 强制提交，不等窗口。
+ */
+import { getLogger } from '../logger/index.js';
+import { isDownloadablePlaceholder } from './placeholder.js';
+import { buildPrompt } from './prompt.js';
+import { buildReceipt, unsupportedReason } from './receipt.js';
+import { bucketKey, } from './turn.js';
+/** 统一静默期窗口（ms）——决策 1：不做「纯文本零延迟」快路径。 */
+export const DEFAULT_TURN_WINDOW_MS = 700;
+export class InboundTurnAssembler {
+    deps;
+    buckets = new Map();
+    windowMs;
+    setTimer;
+    clearTimer;
+    disposed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.windowMs = deps.windowMs ?? DEFAULT_TURN_WINDOW_MS;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    /** 投递一个入站事件（文本 / 媒体[in-flight] / 拒绝）。 */
+    ingest(event) {
+        if (this.disposed) {
+            // 已 dispose（进程收尾）：不再装配，但必须吞掉 in-flight promise 的 rejection，
+            // 否则它会以 unhandledRejection 形式打死进程。
+            if (event.kind === 'media')
+                void event.outcome.catch(() => { });
+            return;
+        }
+        const key = bucketKey(event.userId, event.chatId);
+        const bucket = this.ensureBucket(key, event);
+        if (!bucket.messageIds.includes(event.messageId))
+            bucket.messageIds.push(event.messageId);
+        if (bucket.replyToMessageId === undefined && event.replyToMessageId !== undefined) {
+            bucket.replyToMessageId = event.replyToMessageId;
+        }
+        switch (event.kind) {
+            case 'text': {
+                if (event.text !== '')
+                    bucket.texts.push(event.text);
+                // 可下载占位符（图/文件/视频/语音/表情）由媒体通道处理，不在此记 rejected；
+                // 其余（位置/名片/投票/合并转发/降级态/未知）拿不到，明确回执。
+                for (const kind of event.placeholders) {
+                    if (isDownloadablePlaceholder(kind))
+                        continue;
+                    // 合并转发的子消息文本已被 SDK 渲染（text 非空）→ 只保留文本；
+                    // 附件能不能拿到由媒体通道的 outcome 决定，不在这里重复报「不支持」。
+                    if (kind === 'forwarded' && event.text !== '')
+                        continue;
+                    this.pushRejected(bucket, {
+                        kind,
+                        reason: unsupportedReason(kind),
+                        sourceMsgId: event.messageId,
+                    });
+                }
+                break;
+            }
+            case 'media': {
+                this.trackMediaOutcome(bucket, key, event.messageId, event.outcome);
+                break;
+            }
+            case 'rejected': {
+                this.pushRejected(bucket, {
+                    kind: event.rejectedKind ?? 'unknown',
+                    reason: event.reason,
+                    sourceMsgId: event.messageId,
+                });
+                break;
+            }
+        }
+        this.armTimer(key, bucket);
+    }
+    /**
+     * 强制提交窗口内已装配的内容（命令到达、退出前冲刷）。
+     * 仍有 in-flight 下载时先等它落定（避免丢掉附件路径）。
+     */
+    async flush(userId, chatId, reason = 'flush') {
+        const key = bucketKey(userId, chatId);
+        const bucket = this.buckets.get(key);
+        if (!bucket)
+            return;
+        bucket.windowElapsed = true;
+        bucket.forcedReason = reason;
+        if (bucket.pendingOutcomes.size > 0) {
+            await Promise.all([...bucket.pendingOutcomes]);
+        }
+        await (bucket.commitPromise ?? this.tryCommit(key, reason));
+    }
+    /** 冲刷全部窗口（/exit、/restart 干净退出前调用）。 */
+    async flushAll(reason = 'flush') {
+        const buckets = [...this.buckets.values()];
+        await Promise.all(buckets.map((b) => this.flush(b.userId, b.chatId, reason)));
+    }
+    /** 进程退出：丢弃定时器，避免悬挂。 */
+    dispose() {
+        this.disposed = true;
+        for (const bucket of this.buckets.values()) {
+            if (bucket.timer !== undefined)
+                this.clearTimer(bucket.timer);
+        }
+        this.buckets.clear();
+    }
+    ensureBucket(key, event) {
+        const existing = this.buckets.get(key);
+        if (existing)
+            return existing;
+        const bucket = {
+            userId: event.userId,
+            chatId: event.chatId,
+            texts: [],
+            attachments: [],
+            rejected: [],
+            messageIds: [],
+            pendingOutcomes: new Set(),
+            windowElapsed: false,
+            committed: false,
+        };
+        this.buckets.set(key, bucket);
+        return bucket;
+    }
+    pushRejected(bucket, item) {
+        const dup = bucket.rejected.some((r) => r.sourceMsgId === item.sourceMsgId && r.reason === item.reason);
+        if (!dup)
+            bucket.rejected.push(item);
+    }
+    armTimer(key, bucket) {
+        if (bucket.timer !== undefined)
+            this.clearTimer(bucket.timer);
+        bucket.windowElapsed = false;
+        bucket.timer = this.setTimer(() => {
+            bucket.timer = undefined;
+            bucket.windowElapsed = true;
+            if (bucket.pendingOutcomes.size > 0)
+                return; // 等 in-flight 下载落定
+            void this.tryCommit(key, bucket.forcedReason ?? 'idle');
+        }, this.windowMs);
+    }
+    /**
+     * 登记一次 in-flight 媒体下载：落定后合并结果，并在窗口已到期时触发 commit。
+     * 下载异常（含超时）记入 rejected，不阻断本 turn 的其它内容。
+     */
+    trackMediaOutcome(bucket, key, messageId, outcome) {
+        const tracked = Promise.resolve(outcome)
+            .then((result) => {
+            bucket.attachments.push(...result.attachments);
+            for (const item of result.rejected)
+                this.pushRejected(bucket, item);
+        }, (err) => {
+            this.pushRejected(bucket, {
+                kind: 'file',
+                reason: `下载失败: ${err?.message ?? String(err)}`,
+                sourceMsgId: messageId,
+            });
+        })
+            .then(() => {
+            bucket.pendingOutcomes.delete(tracked);
+            if (bucket.windowElapsed && bucket.pendingOutcomes.size === 0 && !bucket.committed) {
+                void this.tryCommit(key, bucket.forcedReason ?? 'idle');
+            }
+        });
+        bucket.pendingOutcomes.add(tracked);
+    }
+    tryCommit(key, reason) {
+        const bucket = this.buckets.get(key);
+        if (!bucket || bucket.committed)
+            return Promise.resolve();
+        if (bucket.pendingOutcomes.size > 0)
+            return Promise.resolve();
+        bucket.committed = true;
+        this.buckets.delete(key);
+        if (bucket.timer !== undefined) {
+            this.clearTimer(bucket.timer);
+            bucket.timer = undefined;
+        }
+        const promise = this.commit(bucket, reason);
+        bucket.commitPromise = promise;
+        return promise;
+    }
+    async commit(bucket, reason) {
+        const noText = bucket.texts.length === 0;
+        const turn = {
+            userId: bucket.userId,
+            chatId: bucket.chatId,
+            replyToMessageId: bucket.replyToMessageId,
+            texts: bucket.texts,
+            attachments: bucket.attachments,
+            rejected: bucket.rejected,
+            messageIds: bucket.messageIds,
+            commitReason: noText ? 'no-text' : reason,
+        };
+        const ctx = {
+            userId: bucket.userId,
+            chatId: bucket.chatId,
+            messageId: bucket.messageIds[bucket.messageIds.length - 1] ?? '',
+        };
+        try {
+            if (noText) {
+                // 决策 2：纯附件不自动起 turn，只回执并引导用户说一句话。
+                const text = buildReceipt({
+                    saved: bucket.attachments.map((a) => a.path),
+                    rejected: bucket.rejected,
+                    startWorkHint: true,
+                });
+                if (text)
+                    await this.deps.onReceipt?.(ctx, text);
+                return;
+            }
+            await this.deps.onCommit(turn, buildPrompt(turn));
+            if (bucket.rejected.length > 0) {
+                const text = buildReceipt({ saved: [], rejected: bucket.rejected, startWorkHint: false });
+                if (text)
+                    await this.deps.onReceipt?.(ctx, text);
+            }
+        }
+        catch (err) {
+            getLogger().error('[inbound] turn commit failed:', err?.message ?? String(err));
+        }
+    }
+}
+//# sourceMappingURL=turn-assembler.js.map

package/dist/inbound/turn.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 统一入站回合（InboundTurn）模型。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4。
+ * 核心不变量：**一个用户意图 = 一个 turn**，且任何进 agent 的内容都必须已落到本地路径。
+ */
+/** 附件种类（命名/展示语义）。与下载语义 `InboundMediaItem.type` 分离（§5.3）。 */
+export type AttachmentKind = 'image' | 'file' | 'video' | 'audio' | 'sticker';
+export interface InboundAttachment {
+    /** 绝对路径（落盘后位置）。 */
+    path: string;
+    kind: AttachmentKind;
+    /** 来源飞书 messageId：下载凭据的一部分，也是排障锚点。 */
+    sourceMsgId: string;
+    /** 原始文件名（有则保留，用于 prompt 标注与排障）。 */
+    originalName?: string;
+    /** 视频/语音时长（毫秒）。 */
+    durationMs?: number;
+}
+/** 拿不到、不支持、超限、失败的项 —— 需要回执给人（不进 agent）。 */
+export interface RejectedItem {
+    /** 原 msg_type / 占位符种类 / 资源种类。 */
+    kind: string;
+    /** 面向人的说明。 */
+    reason: string;
+    sourceMsgId: string;
+}
+/** 提交原因，用于观测与测试断言。 */
+export type CommitReason = 'idle' | 'timeout' | 'flush' | 'no-text';
+export interface InboundTurn {
+    userId: string;
+    chatId: string;
+    replyToMessageId?: string;
+    /** 用户文本片段，按到达顺序；已剥离结构占位符。 */
+    texts: string[];
+    /** 已落盘的附件（绝对路径），按到达顺序。 */
+    attachments: InboundAttachment[];
+    rejected: RejectedItem[];
+    /** 本 turn 覆盖的飞书 messageId（回执、去重、排障）。 */
+    messageIds: string[];
+    commitReason: CommitReason;
+}
+/** 媒体下载 + 落盘的结果（装配器等待它落定后才 commit）。 */
+export interface MediaOutcome {
+    attachments: InboundAttachment[];
+    rejected: RejectedItem[];
+}
+export declare function bucketKey(userId: string, chatId: string): string;

package/dist/inbound/turn.js

@@ -0,0 +1,10 @@
+/**
+ * 统一入站回合（InboundTurn）模型。
+ *
+ * 设计依据：`docs/zh/architecture/inbound-unified-input-design.md` §4。
+ * 核心不变量：**一个用户意图 = 一个 turn**，且任何进 agent 的内容都必须已落到本地路径。
+ */
+export function bucketKey(userId, chatId) {
+    return `${userId}:${chatId}`;
+}
+//# sourceMappingURL=turn.js.map

package/dist/index.js

@@ -19,9 +19,13 @@ import { OwnerBinder, formatBindGuidance } from './binder.js';
 import { CloneSession } from './clone.js';
 import { InstanceAlreadyRunningError, InstanceLock } from './instance-lock.js';
 import { spawnReplacementBridge, waitForPreviousInstance } from './restart.js';
+import { currentPlatform } from './platform/select.js';
+import { startSleepBlocker } from './platform/sleep-blocker.js';
 import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
 import { classifyRejection } from './error-classification.js';
 import { WorkspaceStore } from './workspace/index.js';
+import { InboundTurnAssembler } from './inbound/turn-assembler.js';
+import { stripPlaceholders } from './inbound/placeholder.js';
 import { buildSessionHistoryCard } from './router/card-helpers.js';
 import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/card-shared.js';
 import path from 'node:path';
@@ -195,6 +199,12 @@ function initializeRunner(config, configDir, cliArgs) {
             model,
             sessionReader: opencodeSessionReader,
             mode: ocConfig?.mode ?? 'build',
+            binary: ocConfig?.acp?.binary,
+            requestTimeoutMs: ocConfig?.acp?.requestTimeoutMs,
+            idleTtlMs: ocConfig?.acp?.idleTtlMs,
+            turnIdleTimeoutMs: ocConfig?.acp?.turnIdleTimeoutMinutes != null
+                ? ocConfig.acp.turnIdleTimeoutMinutes * 60_000
+                : undefined,
         });
     });
     sessionReaderRegistry.register('opencode', opencodeSessionReader);
@@ -290,9 +300,48 @@ function initializeRunner(config, configDir, cliArgs) {
 }
 /** Setup message and card action handlers. */
 function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession) {
-    // 入站媒体（图片/文件）：先认证后下载（P1 review 修复）。
+    // 入站统一装配器（2026-09-15）：图/文任意顺序 → 同一个 turn、同一个 prompt，
+    // 附件路径统一注入 prompt；无文本纯附件只回执（决策 2）。
+    const assembler = new InboundTurnAssembler({
+        onCommit: (turn, prompt) => {
+            // 入队时刻（T0）快照 workspace + agent/session 绑定，语义与旧路径一致
+            // （排队期间 /cd、/config 不再导致语义漂移）。
+            const messageId = turn.messageIds[turn.messageIds.length - 1] ?? '';
+            const ctx = { userId: turn.userId, chatId: turn.chatId, messageId };
+            let workspace = sessionStore.getCwd(turn.userId) ?? '';
+            if (!workspace && workspaceStore) {
+                const workspaces = workspaceStore.list();
+                if (workspaces.length > 0)
+                    workspace = workspaces[0].path;
+            }
+            const binding = bridge.currentBinding(turn.userId);
+            bridge.enqueue(workspace, async () => {
+                // allowCommandPrefix: false —— prompt 已剥离占位符，绝不再做命令分发。
+                await router.handle(prompt, ctx, {
+                    cwdOverride: workspace,
+                    binding,
+                    allowCommandPrefix: false,
+                });
+            }, {
+                taskMeta: {
+                    userId: turn.userId,
+                    chatId: turn.chatId,
+                    messageId,
+                    messagePreview: prompt.slice(0, 3000),
+                    binding,
+                },
+            });
+        },
+        onReceipt: async (ctx, text) => {
+            await bridge.sendResult({ text }, ctx);
+        },
+    });
+    router.setInboundFlusher(() => assembler.flushAll('flush'));
+    // 入站媒体（图片/文件/视频/语音/表情）：先认证后下载（P1 review 修复）。
     // connector 只上报"媒体到达"，这里先过 owner + enabled 闸门，通过后才
     // 下载——未认证/关闭配置时不会发生任何网络下载或内存/磁盘占用。
+    // 下载是异步的：立刻把在途 promise 交给装配器（`kind: 'media'`），
+    // 保证「先图后文」不会先提交一个只含文本的 turn。
     connector.setInboundMediaDetectedHandler((msg) => {
         if (!binder.isOwner(msg.userId)) {
             logger.warn(`[media] rejected inbound media from non-owner ${msg.userId}`);
@@ -302,35 +351,45 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         // 启动时捕获的 config 参数会过期（P2 review 修复）。
         if (!router.config.inboundMedia.enabled) {
             // 不静默（P3 review）：关闭时给 owner 明确反馈，避免发图后无任何反应。
-            // 不下载、不落盘，只回一条说明。
-            void bridge
-                .sendResult({
-                text: '⚠️ 入站媒体保存已关闭（inboundMedia.enabled: false），未保存文件。' +
-                    '如需自动保存图片/文件，请开启后重试',
-            }, {
+            // 不下载、不落盘，只进 rejected（随 turn 回执一起发出）。
+            assembler.ingest({
+                kind: 'rejected',
                 userId: msg.userId,
                 chatId: msg.chatId,
                 messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[media] disabled feedback send failed:', err));
+                replyToMessageId: msg.replyToMessageId,
+                rawContentType: msg.rawContentType,
+                rejectedKind: 'file',
+                reason: '入站媒体保存已关闭（inboundMedia.enabled: false），未保存文件。' +
+                    '如需自动保存图片/文件，请开启后重试',
+            });
             return;
         }
-        void (async () => {
+        const outcome = (async () => {
             const payload = await connector.downloadInboundMedia(msg, {
                 maxFileSizeMb: router.config.inboundMedia.maxFileSizeMb,
             });
             try {
-                await bridge.onInboundMedia(payload);
+                return await bridge.saveInboundMedia(payload);
             }
             catch (err) {
-                // handle() 的正常路径会清理临时文件；这里兜底 handle 进入 mkdir
+                // save() 的正常路径会清理临时文件；这里兜底 save 进入 mkdir
                 // try 之前意外抛错的情况，避免 os.tmpdir 残留。
                 for (const item of payload.media) {
                     silentlyUnlink(item.tempPath);
                 }
                 throw err;
             }
-        })().catch((err) => logger.error('[media] inbound media download/save failed:', err));
+        })();
+        assembler.ingest({
+            kind: 'media',
+            userId: msg.userId,
+            chatId: msg.chatId,
+            messageId: msg.messageId,
+            replyToMessageId: msg.replyToMessageId,
+            rawContentType: msg.rawContentType,
+            outcome,
+        });
     });
     connector.setMessageHandler((msg) => {
         // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息（任意内容）认领
@@ -385,10 +444,7 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             return;
         }
         // decision.kind === 'owner'：正常处理（不再每条覆盖 startup-contact）
-        logger.info(`message from ${msg.userId}: ${msg.content.slice(0, 100)}`);
-        // 文本到达先冲刷待合批的媒体保存提示（先图后文字时文字到达
-        // 先冲刷批次，避免合批提示被后续消息淹没/丢图）。
-        bridge.flushMediaNotifications(msg.userId, msg.chatId);
+        logger.info(`message from ${msg.userId} (${msg.rawContentType}): ${msg.content.slice(0, 100)}`);
         // Add Typing reaction to indicate "still alive"
         void connector.addReaction(msg.messageId, 'Typing');
         // 复制分身流程活跃期：一切消息先经 clone 状态机（stop 命令除外，保留其
@@ -423,67 +479,38 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
             })().catch((err) => logger.error('[control] /stop failed:', err));
             return;
         }
-        if (content.trim().startsWith('/')) {
-            void router
-                .handle(content, {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[control] slash command failed:', err));
-            return;
+        // 先清洗，后判语义（§5.6）：结构占位符永远不能触发命令分发。
+        // `![image](img_v3_…)` 的首字符恰好是 `!` —— 2026-09-15 事故就是这么进 shell 的。
+        const stripped = stripPlaceholders(content);
+        if (stripped.unknownTags.length > 0) {
+            logger.warn(`[inbound] unknown placeholder tags stripped: ${stripped.unknownTags.join(', ')} ` +
+                `(msg_type=${msg.rawContentType})`);
         }
-        // `!` bash commands bypass the serial queue: they don't start claude and
-        // don't touch session state, so they must run in parallel with claude runs
-        // in the same workspace (design.md §9.6: the queue exists to prevent
-        // concurrent claude runs, not to serialize bash). router.handle dispatches
-        // `!` to bridge.executeBash, which tracks the run independently.
-        if (content.trim().startsWith('!')) {
+        const commandEligible = msg.rawContentType === 'text' && stripped.kinds.length === 0 && stripped.clean !== '';
+        // 命令消息旁路装配窗口：其它 /命令 立即执行，窗口内已装配的内容
+        // 作为独立提交冲刷（/stop 已在上面处理，立即生效不等待）。
+        if (commandEligible && (stripped.clean.startsWith('/') || stripped.clean.startsWith('!'))) {
+            void assembler.flush(msg.userId, msg.chatId, 'flush');
             void router
-                .handle(content, {
+                .handle(stripped.clean, {
                 userId: msg.userId,
                 chatId: msg.chatId,
                 messageId: msg.messageId,
-            })
-                .catch((err) => logger.error('[control] bang command failed:', err));
+            }, { allowCommandPrefix: true })
+                .catch((err) => logger.error('[control] command failed:', err));
             return;
         }
-        // Compute workspace with same fallback logic as executeBash:
-        // 1. sessionStore cwd → 2. first saved workspace
-        let workspace = sessionStore.getCwd(msg.userId) ?? '';
-        if (!workspace && workspaceStore) {
-            const workspaces = workspaceStore.list();
-            if (workspaces.length > 0) {
-                // NOTE: fallback uses insertion order, not sort preference — by design
-                // (cwd fallback stays insertion-order for now)
-                workspace = workspaces[0].path;
-            }
-        }
-        // Step4/D4: 入队时刻（T0）快照 agent+session，随任务闭包带到 T1 执行时刻，
-        // 避免排队期间 /new、/config 改写 live 状态导致语义漂移（方案 D4）。唯一
-        // 捕获点 Bridge.currentBinding。
-        const binding = bridge.currentBinding(msg.userId);
-        bridge.enqueue(workspace, async () => {
-            await router.handle(content, {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-            }, 
-            // P1-14: lane 与执行 cwd 同源 —— 入队时捕获的 workspace 显式传给
-            // forwardToClaude，排队期间 /cd 不再导致旧 lane 消息被 busy-drop。
-            // D4/Step4: binding 同源 —— 入队时快照的 agent+session 一并透传，
-            // 排队期间 /new、/config 不再导致旧 lane 消息语义漂移。
-            { cwdOverride: workspace, binding });
-        }, {
-            taskMeta: {
-                userId: msg.userId,
-                chatId: msg.chatId,
-                messageId: msg.messageId,
-                messagePreview: content.slice(0, 3000),
-                // D3/Step4: binding 随 taskMeta 存进 QueuedTask，供替换闭包
-                // （queue.edit/queue.immediate）复用，不重新快照。
-                binding,
-            },
+        // 普通消息：进装配器，等静默期窗口到期（下载落定）后合并成一个 turn。
+        assembler.ingest({
+            kind: 'text',
+            userId: msg.userId,
+            chatId: msg.chatId,
+            messageId: msg.messageId,
+            replyToMessageId: msg.replyToMessageId,
+            rawContentType: msg.rawContentType,
+            text: stripped.clean,
+            placeholders: stripped.kinds,
+            unknownTags: stripped.unknownTags,
         });
     });
     connector.setCardActionHandler(async (action) => {
@@ -622,9 +649,17 @@ async function main() {
     }
     const { config, configDir, logger, instanceLock } = await initializeCliAndConfig();
     // Restart handoff: if spawned as a /restart replacement, wait for the old
-    // bridge to die (and release the instance lock) before acquiring it.
+    // lark-remote to die (and release the instance lock) before acquiring it.
     await waitForPreviousInstance();
     setupInstanceLockAndHandlers(instanceLock, logger, configDir);
+    // 阻止系统休眠（macOS caffeinate / Windows SetThreadExecutionState）：lark-remote
+    // 的场景是人不在电脑前远程使用，系统休眠即失联。恒开启、无配置开关；helper 进程
+    // 绑定本进程生命周期（caffeinate -w / powershell 轮询父 pid），崩溃也能自清理；
+    // 'exit' 钩子里的 stop() 仅覆盖优雅退出路径。
+    const sleepBlocker = startSleepBlocker({ platform: currentPlatform, pid: process.pid });
+    if (sleepBlocker) {
+        process.on('exit', () => sleepBlocker.stop());
+    }
     logger.info('config loaded');
     logger.info(`configDir = ${configDir}`);
     logger.info(`feishu.appId = ${config.feishu.appId}`);
@@ -741,7 +776,7 @@ async function main() {
             }
         }
     }
-    logger.info('bridge is running, press Ctrl+C to exit');
+    logger.info('lark-remote is running, press Ctrl+C to exit');
 }
 main().catch((err) => {
     getLogger().error('fatal error:', err);

package/dist/platform/command.js

@@ -46,7 +46,7 @@ function isBashQuery(name) {
     return lower === 'bash' || lower === 'bash.exe';
 }
 /**
- * 缓存 TTL：probe 层（runner/probe.ts）5 分钟，本层更短——bridge 运行期间
+ * 缓存 TTL：probe 层（runner/probe.ts）5 分钟，本层更短——lark-remote 运行期间
  * 用户新装/卸载 agent（典型场景：按 /config 不可用提示去安装）后，最迟
  * TTL 过期即可被重新探测到，不必重启。null（未找到）结果同样过期重查。
  */

package/dist/platform/sleep-blocker.d.ts

@@ -0,0 +1,17 @@
+import { spawnProcess } from './spawn.js';
+export interface SleepBlocker {
+    /** 防御性停止 helper（正常路径 helper 随 lark-remote 死亡自行退出）。 */
+    stop(): void;
+}
+export interface SleepBlockerOptions {
+    platform: NodeJS.Platform;
+    pid: number;
+    /** 测试注入点：默认走 platform/spawn.ts 的 cross-spawn 收口。 */
+    spawnFn?: typeof spawnProcess;
+}
+/**
+ * PowerShell 托管脚本：声明 P/Invoke → 设置持续唤醒 → 轮询父 pid 直至父进程消失。
+ * 单字符串经 `-Command` 传入（不经 shell，内嵌双引号安全）；父 pid 是 number，插值安全。
+ */
+export declare function win32SleepBlockerScript(parentPid: number): string;
+export declare function startSleepBlocker(opts: SleepBlockerOptions): SleepBlocker | null;

package/dist/platform/sleep-blocker.js

@@ -0,0 +1,73 @@
+import { spawnProcess } from './spawn.js';
+import { getLogger } from '../logger/index.js';
+/** ES_CONTINUOUS (0x80000000) | ES_SYSTEM_REQUIRED (0x00000001)。 */
+const ES_FLAGS = '0x80000001';
+/**
+ * PowerShell 托管脚本：声明 P/Invoke → 设置持续唤醒 → 轮询父 pid 直至父进程消失。
+ * 单字符串经 `-Command` 传入（不经 shell，内嵌双引号安全）；父 pid 是 number，插值安全。
+ */
+export function win32SleepBlockerScript(parentPid) {
+    return [
+        `Add-Type -TypeDefinition 'using System.Runtime.InteropServices; public static class SleepBlocker { [DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags); }'`,
+        `[SleepBlocker]::SetThreadExecutionState(${ES_FLAGS}) | Out-Null`,
+        `while (Get-Process -Id ${parentPid} -ErrorAction SilentlyContinue) { Start-Sleep -Seconds 30 }`,
+    ].join('; ');
+}
+export function startSleepBlocker(opts) {
+    const { platform, pid } = opts;
+    const spawnFn = opts.spawnFn ?? spawnProcess;
+    const logger = getLogger();
+    let command;
+    let args;
+    if (platform === 'darwin') {
+        command = 'caffeinate';
+        args = ['-i', '-w', String(pid)];
+    }
+    else if (platform === 'win32') {
+        command = 'powershell.exe';
+        args = ['-NoProfile', '-NonInteractive', '-Command', win32SleepBlockerScript(pid)];
+    }
+    else {
+        return null;
+    }
+    let proc;
+    try {
+        proc = spawnFn(command, args, { stdio: 'ignore' });
+    }
+    catch (err) {
+        logger.warn(`[sleep-blocker] failed to spawn ${command}:`, err);
+        return null;
+    }
+    // spawn 二进制缺失早检 + error 事件兜底（同 runner 层纪律）
+    if (proc.pid === undefined) {
+        logger.warn(`[sleep-blocker] ${command} unavailable (spawn failed), sleep prevention off`);
+        return null;
+    }
+    proc.on('error', (err) => {
+        logger.warn(`[sleep-blocker] ${command} error:`, err);
+    });
+    // helper 意外死亡 = 防休眠静默失效（win32 上 Add-Type 动态编译被企业策略/
+    // 杀软拦掉、Get-Process 权限失败；darwin 上 caffeinate 早退）。桥此时还活着，
+    // 是唯一能留痕的时机——否则日志里只剩启动那句 "active"，误以为防休眠在生效。
+    let stopping = false;
+    proc.on('exit', (code, signal) => {
+        if (stopping)
+            return;
+        logger.warn(`[sleep-blocker] ${command} exited unexpectedly (code=${code}, signal=${signal}), sleep prevention off`);
+    });
+    // helper 不得阻止 lark-remote 自身退出；父进程死后 helper 走各自的自清理机制退出
+    proc.unref();
+    logger.info(`[sleep-blocker] active via ${command} pid=${proc.pid}`);
+    return {
+        stop() {
+            stopping = true;
+            try {
+                proc.kill();
+            }
+            catch {
+                // helper 已死或不可杀——正常路径下它会自行退出，忽略
+            }
+        },
+    };
+}
+//# sourceMappingURL=sleep-blocker.js.map