Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(orca): worker 切换不再同步等待冷启动

Zhang Yunjin2b37adf65ad9
diff --git a/apps/desktop/src/main/__tests__/makerSendToSessionOrdering.test.ts b/apps/desktop/src/main/__tests__/makerSendToSessionOrdering.test.ts
index db45872c50..4d1827c00f 100644
--- a/apps/desktop/src/main/__tests__/makerSendToSessionOrdering.test.ts
+++ b/apps/desktop/src/main/__tests__/makerSendToSessionOrdering.test.ts
@@ -778,9 +778,17 @@ describe('sendToSession ordering', () => {
);
expectOrder(resumeBranch, '...directoryGrantsForRuntime(storedExtraDirs),', 'await bootstrapSession(opts);');
expect(serviceDepsBlock).toContain('resumeWorkerSession: async (target) => {');
- expect(serviceDepsBlock).toContain('await resumeOrcaWorkerSessionIfMissing(target);');
- expect(switchFocusIpcBlock).toContain('const didResume = await resumeOrcaWorkerSessionIfMissing(target);');
- expect(switchFocusMcpBlock).toContain('await resumeOrcaWorkerSessionIfMissing(target);');
+ expect(serviceDepsBlock).toContain('await orcaWorkerResumeScheduler.request(target);');
+ // focus 切换是纯 UI 操作:resume 只能后台调度,不能在 IPC / MCP handler 里同步 await
+ // 冷启动(首次切 dormant worker 的 ~5s 卡顿回归点)。
+ expect(switchFocusIpcBlock).toContain(
+ 'orcaWorkerResumeScheduler.requestInBackground(target, (err) => {',
+ );
+ expect(switchFocusIpcBlock).not.toContain('await resumeOrcaWorkerSessionIfMissing(target)');
+ expect(switchFocusMcpBlock).toContain(
+ 'orcaWorkerResumeScheduler.requestInBackground(target, (err) => {',
+ );
+ expect(switchFocusMcpBlock).not.toContain('await resumeOrcaWorkerSessionIfMissing(target)');
});
it('keeps IPC and MCP createWorker delegated to the shared lifecycle service', () => {
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/orcaWorkerResumeScheduler.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/orcaWorkerResumeScheduler.test.ts
new file mode 100644
index 0000000000..ea65c45cd2
--- /dev/null
+++ b/apps/desktop/src/main/maker-ipc/__tests__/orcaWorkerResumeScheduler.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOrcaWorkerResumeScheduler } from '../orcaWorkerResumeScheduler';
+
+describe('createOrcaWorkerResumeScheduler', () => {
+ it('shares one in-flight resume per session and clears it when settled', async () => {
+ let release!: (value: boolean) => void;
+ const resume = vi.fn(
+ () =>
+ new Promise<boolean>((resolve) => {
+ release = resolve;
+ }),
+ );
+ const scheduler = createOrcaWorkerResumeScheduler({
+ resume,
+ withSessionLock: (_sessionId, task) => task(),
+ });
+
+ const first = scheduler.request({ sessionId: 'worker-1' });
+ const second = scheduler.request({ sessionId: 'worker-1' });
+
+ expect(second).toBe(first);
+ expect(scheduler.pendingCount()).toBe(1);
+ expect(resume).toHaveBeenCalledTimes(1);
+
+ release(true);
+ await expect(first).resolves.toBe(true);
+ expect(scheduler.pendingCount()).toBe(0);
+
+ // A settled entry must not be reused: the next request starts a fresh resume.
+ resume.mockResolvedValueOnce(false);
+ await expect(scheduler.request({ sessionId: 'worker-1' })).resolves.toBe(false);
+ expect(resume).toHaveBeenCalledTimes(2);
+ });
+
+ it('runs resume inside the injected per-session lock', async () => {
+ let releaseLock!: () => void;
+ const lockGate = new Promise<void>((resolve) => {
+ releaseLock = resolve;
+ });
+ let lockEntered = false;
+ const resume = vi.fn(async () => true);
+ const scheduler = createOrcaWorkerResumeScheduler({
+ resume,
+ withSessionLock: async (_sessionId, task) => {
+ lockEntered = true;
+ await lockGate;
+ return task();
+ },
+ });
+
+ const pending = scheduler.request({ sessionId: 'worker-1' });
+ await Promise.resolve();
+
+ expect(lockEntered).toBe(true);
+ expect(resume).not.toHaveBeenCalled();
+
+ releaseLock();
+ await expect(pending).resolves.toBe(true);
+ expect(resume).toHaveBeenCalledTimes(1);
+ });
+
+ it('resumes different sessions without coupling them', async () => {
+ const releases = new Map<string, (value: boolean) => void>();
+ const resume = vi.fn(
+ (target: { sessionId: string }) =>
+ new Promise<boolean>((resolve) => {
+ releases.set(target.sessionId, resolve);
+ }),
+ );
+ const scheduler = createOrcaWorkerResumeScheduler({
+ resume,
+ withSessionLock: (_sessionId, task) => task(),
+ });
+
+ const first = scheduler.request({ sessionId: 'worker-1' });
+ const second = scheduler.request({ sessionId: 'worker-2' });
+
+ expect(resume).toHaveBeenCalledTimes(2);
+ expect(scheduler.pendingCount()).toBe(2);
+
+ releases.get('worker-2')?.(true);
+ await expect(second).resolves.toBe(true);
+ expect(scheduler.pendingCount()).toBe(1);
+
+ releases.get('worker-1')?.(false);
+ await expect(first).resolves.toBe(false);
+ expect(scheduler.pendingCount()).toBe(0);
+ });
+
+ it('reports background failures without rejecting and retries next time', async () => {
+ const onError = vi.fn();
+ const resume = vi
+ .fn(async () => true)
+ .mockRejectedValueOnce(new Error('boot failed'))
+ .mockResolvedValueOnce(true);
+ const scheduler = createOrcaWorkerResumeScheduler({
+ resume,
+ withSessionLock: (_sessionId, task) => task(),
+ });
+
+ expect(() => scheduler.requestInBackground({ sessionId: 'worker-1' }, onError)).not.toThrow();
+ await vi.waitFor(() => expect(onError).toHaveBeenCalledTimes(1));
+ expect(scheduler.pendingCount()).toBe(0);
+
+ await expect(scheduler.request({ sessionId: 'worker-1' })).resolves.toBe(true);
+ expect(resume).toHaveBeenCalledTimes(2);
+ });
+});
diff --git a/apps/desktop/src/main/maker-ipc/orcaWorkerResumeScheduler.ts b/apps/desktop/src/main/maker-ipc/orcaWorkerResumeScheduler.ts
new file mode 100644
index 0000000000..2498b9e9b1
--- /dev/null
+++ b/apps/desktop/src/main/maker-ipc/orcaWorkerResumeScheduler.ts
@@ -0,0 +1,68 @@
+/**
+ * orcaWorkerResumeScheduler —— 「冷 Worker 唤醒」的进程内调度器。
+ *
+ * 背景(2026-09 实报:协同里第一次切到某个 dormant worker 要等 ~5s,第二次很快):
+ * `switch_focus` 过去在 IPC / MCP handler 里同步 `await resumeOrcaWorkerSessionIfMissing`,
+ * 而 focus 切换是纯 UI 操作 —— 冷会话会 spawn 整个 agent runtime(Pi 实测 2~3s,含 MCP
+ * gateway)才返回,面板切换被冷启动阻塞。唤醒本身仍然需要(发送、派活都依赖 live
+ * runtime),但它可以后台化:worker 历史来自 DB,不需要 runtime。
+ *
+ * 本调度器给出两个保证:
+ * 1. per-session 去重:并发的 focus 切换 / 派活共享同一次 resume,不会把同一个会话
+ * bootstrap 两次(两个调用方都会看到同一结果);
+ * 2. 与发送路径共用同一把 per-session 锁(由调用方注入 `withSessionLock`,main 侧注入
+ * `withSendToSessionLock`):resume 期间到达的发送排在锁后;发送先持锁完成 lazy
+ * bootstrap 时,resume 在锁内重查 live 并直接跳过。
+ *
+ * 唤醒实现与锁都由调用方注入,逻辑本身可单测。
+ */
+
+/** 调度所需的 worker 身份;真实调用点传完整 worker 记录,只要求 sessionId 稳定。 */
+export interface OrcaWorkerResumeTarget {
+ sessionId: string;
+}
+
+export interface OrcaWorkerResumeSchedulerDeps<Target extends OrcaWorkerResumeTarget> {
+ /** 真正的唤醒实现;返回是否真的启动了 runtime(已 live 时 false)。 */
+ resume(target: Target): Promise<boolean>;
+ /** per-session 串行锁;必须与发送路径共用同一把。 */
+ withSessionLock<T>(sessionId: string, task: () => Promise<T>): Promise<T>;
+}
+
+export interface OrcaWorkerResumeScheduler<Target extends OrcaWorkerResumeTarget> {
+ /** 去重 + 串行的 resume;需要结果的调用方 await 它。 */
+ request(target: Target): Promise<boolean>;
+ /**
+ * 后台唤醒:不阻塞调用方,错误只经 onError 上报(避免 unhandled rejection)。
+ * focus 切换用这个入口,resume 结果不构成切换成功与否的一部分。
+ */
+ requestInBackground(target: Target, onError: (error: unknown) => void): void;
+ /** 诊断/测试用:当前处于 in-flight 的 session 数。 */
+ pendingCount(): number;
+}
+
+export function createOrcaWorkerResumeScheduler<Target extends OrcaWorkerResumeTarget>(
+ deps: OrcaWorkerResumeSchedulerDeps<Target>,
+): OrcaWorkerResumeScheduler<Target> {
+ const inFlight = new Map<string, Promise<boolean>>();
+
+ function request(target: Target): Promise<boolean> {
+ const existing = inFlight.get(target.sessionId);
+ if (existing) return existing;
+ // 锁在 resume 内部持有整个冷启动窗口:与发送、idle 释放等同一 session 的 critical
+ // section 串行;失败也要清掉 in-flight,让下一次 focus / 派活可以重试。
+ const promise = deps
+ .withSessionLock(target.sessionId, () => deps.resume(target))
+ .finally(() => {
+ if (inFlight.get(target.sessionId) === promise) inFlight.delete(target.sessionId);
+ });
+ inFlight.set(target.sessionId, promise);
+ return promise;
+ }
+
+ function requestInBackground(target: Target, onError: (error: unknown) => void): void {
+ void request(target).catch(onError);
+ }
+
+ return { request, requestInBackground, pendingCount: () => inFlight.size };
+}
diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.ts
index 37968902ce..e3d45a9477 100644
--- a/apps/desktop/src/main/maker-ipc/register.ts
+++ b/apps/desktop/src/main/maker-ipc/register.ts
@@ -513,6 +513,7 @@ import {
ORCA_IDLE_RELEASE_STATUSES,
type OrcaIdleReleaseWatcher,
} from './orcaIdleReleaseWatcher.js';
+import { createOrcaWorkerResumeScheduler } from './orcaWorkerResumeScheduler.js';
import {
ackSessionTurnEndedDurable,
hasAssistantProgressAfterMessage,
@@ -7242,6 +7243,29 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
return true;
}
+ // focus 切换是纯 UI 操作,不再同步等待冷启动(2026-09 实报: 首次切到 dormant worker
+ // 要等 ~5s)。resume 仍要发生,但转后台并走共享调度器: per-session 去重 + 与发送路径
+ // 共用 sendToSession 锁,避免并发双 bootstrap(实现与不变量见 orcaWorkerResumeScheduler.ts)。
+ const orcaWorkerResumeScheduler = createOrcaWorkerResumeScheduler({
+ resume: async (target: {
+ id: string;
+ teamId: string;
+ leadSessionId: string;
+ sessionId: string;
+ }) => {
+ const didResume = await resumeOrcaWorkerSessionIfMissing(target);
+ if (didResume) {
+ log.info('orcaWorkerResume: resumed idle worker (session only, no status change)', {
+ workerId: target.id,
+ sessionId: target.sessionId,
+ });
+ }
+ return didResume;
+ },
+ withSessionLock: (sessionId, task) =>
+ withSendToSessionLock(sessionId, task, () => 'orca-worker-resume'),
+ });
+
// sessionId → remoteHostId 的进程内缓存 reader(lazy resume 路径每次 send 都
// 经过 ensureRemoteReadyForSessionStart;实现与缓存语义见 localDb/ipc/sessions.ts,
// DB 异常不缓存 null)。
@@ -10638,23 +10662,16 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
// focused 切换: clear 旧 + set 新, 原子化 (review F4)
await setWorkerFocus(target.teamId, target.id);
- // idle worker → resume session (so it's ready for tasks), but don't set status
- // to 'running' — that only happens when actual work is dispatched via sendToWorker.
+ // idle worker → 后台预热 runtime(发送/派活时需要),但 focus 切换不等待冷启动:
+ // worker 历史来自 DB,切换立即生效;resume 失败只告警,不影响 focus 结果。
if (target.status === 'idle') {
- try {
- const didResume = await resumeOrcaWorkerSessionIfMissing(target);
- if (didResume) {
- log.info('switchFocus: resumed idle worker (session only, no status change)', {
- workerId: target.id,
- sessionId: target.sessionId,
- });
- }
- } catch (err) {
+ orcaWorkerResumeScheduler.requestInBackground(target, (err) => {
log.warn('switchFocus: resume failed', {
workerId: target.id,
+ sessionId: target.sessionId,
err: err instanceof Error ? err.message : String(err),
});
- }
+ });
}
broadcastToAllWindows(MAKER_PUSH.ORCA_WORKER_CHANGED, {
@@ -10696,7 +10713,8 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
listWorkersByLead,
getLiveSession: (sessionId) => maker.getSession(sessionId) ?? null,
resumeWorkerSession: async (target) => {
- await resumeOrcaWorkerSessionIfMissing(target);
+ // 与 focus 后台预热共享同一套去重/锁:派活不会和切换触发两次 bootstrap。
+ await orcaWorkerResumeScheduler.request(target);
},
updateWorkerStatus,
markWorkerIdle: async (workerId) => {
@@ -12225,12 +12243,20 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)
await setWorkerFocus(target.teamId, target.id);
- // Resume closed session so it's ready to receive tasks, but DON'T change
- // worker status — status only transitions to 'running' when actual work is
- // dispatched (sendToWorker). Setting 'running' here without a task causes
- // the icon to flash indefinitely (no turn → turn-done never fires).
+ // Resume a closed session in the background so it's ready to receive tasks,
+ // but DON'T change worker status — status only transitions to 'running' when
+ // actual work is dispatched (sendToWorker). Setting 'running' here without a
+ // task causes the icon to flash indefinitely (no turn → turn-done never fires).
+ // Focus must not wait for the cold boot: the transcript is DB-backed, and the
+ // send path lazily resumes through the same deduped scheduler.
if (target.status === 'idle') {
- await resumeOrcaWorkerSessionIfMissing(target);
+ orcaWorkerResumeScheduler.requestInBackground(target, (err) => {
+ log.warn('switchFocus: resume failed', {
+ workerId: target.id,
+ sessionId: target.sessionId,
+ err: err instanceof Error ? err.message : String(err),
+ });
+ });
}
broadcastToAllWindows(MAKER_PUSH.ORCA_WORKER_CHANGED, { leadSessionId });
return { ok: true, workerId: target.id };
diff --git a/docs/dev-rules/orca-team-architecture.md b/docs/dev-rules/orca-team-architecture.md
index ab51619a48..8168c716fc 100644
--- a/docs/dev-rules/orca-team-architecture.md
+++ b/docs/dev-rules/orca-team-architecture.md
@@ -318,6 +318,9 @@ Worker turn 被 vendor 报终止型 error,但 interrupted-turn auto-resume 仍
3. **idle worker 恢复必须保留 extraDirs(状态:不变量)**<br>
idle worker 被 `switch_focus` 或 `send_to_worker` 唤醒时,要从 DB 读取 `extra_dirs` 并带回 `bootstrapSession`,否则恢复后的 worker 会丢附加目录上下文。实现指针:`register.ts` 的 idle worker resume helper。
+3a. **focus 切换不等待 worker 冷启动(状态:不变量)**<br>
+ `switch_focus` 是纯 UI focus 操作:`setWorkerFocus` 成功并广播 `ORCA_WORKER_CHANGED` 后必须立即返回,不得同步 `await` 冷会话的 resume / `bootstrapSession`(Pi 冷启实测 2~3s,会阻塞面板切换)。idle worker 的 runtime 预热转后台,并与发送/派活路径共享同一套 per-session 去重 + `sendToSession` 锁:并发 focus / 派活只 bootstrap 一次;发送先取得锁完成懒恢复时,后台 resume 在锁内重查 live 并跳过;预热失败只告警,不改变 `switch_focus` 结果。worker 历史来自 DB,展示不需要 live runtime。实现指针:`register.ts` 的 `resumeOrcaWorkerSessionIfMissing` / `orcaWorkerResumeScheduler.ts`。
+
4. **worker 状态变更必须广播给 renderer(状态:不变量)**
创建 worker、`enableOrca` 创建首个 worker、任意真实 worker turn 开始后的 running、idle、archive、terminal done/error 都必须广播 `ORCA_WORKER_CHANGED`。worker DB `status` 跟随真实 turn 生命周期:Lead 派活或用户直接对话 worker 时,只有真实 turn 开始才置 `running`,**产品** terminal 才置 `done/error`(auto-resume 仍 pending/deferred 的 vendor 终态不是产品终态,见消息派发与 auto-bridge 5a);`switch_focus` / resume / restore 只能恢复可访问性,不能凭空置 `running`。实现指针:`orcaLifecycleService.ts` 的 `createWorker` / `enableTeam`、`orcaWorkerCreationService.ts` 的 `createWorkerInTeam`、`orcaTeamService.ts` 的 `dispatchWorkerTask` / `handleWorkerTurnStarted` / `handleWorkerTerminalTurn`、`register.ts` 的 status event adapter、`useWorkers.ts` 的 `useWorkers`。