Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 手机端协同(Orca)页面状态。
*
* - useOrcaWorkerForm:「开启协同 / 创建新 Worker」表单状态(会话页与新建任务页共用),含
* 完全访问确认与 Worker 模型选择器的开合编排。
* - useSessionOrcaCollab:会话页 + 面板「协同模式」二级视图、团队操作与 Lead / Worker 导航。
*
* 真身在被控端;所有写操作完成后以被控端列表为准(整表重拉),本地只在开启 / 结束协同时
* 乐观改 orcaRole、归档 Worker 时乐观移出 Worker 任务(见 beginOptimisticWorkerArchive),
* 权威值随 sessions 推送回流。
*/
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { Alert } from 'react-native';
import type { ProviderView } from '@cindy/model-providers/registry';
import type { AgentKind } from '@cindy/model-providers/types';
import type { OrcaExecutionDeviceView } from '@cindy/device-link';
import type { MobileModelOption } from '@/session/agentCapabilities';
import { confirmFullAccessChange } from '@/session/fullAccessConfirmation';
import {
archiveOrcaWorker,
buildOrcaEnableOptions,
convergeOrcaWorkerModel,
createOrcaWorker,
describeOrcaError,
isOrcaAmbiguousTimeout,
isOrcaUnsupportedError,
parseOrcaExecutionDevices,
narrowOrcaWorkerProvider,
enableOrcaTeam,
isOrcaCollabEligible,
orcaAgentKindForSession,
orcaCollabEntryHint,
orcaWorkerAgentElsewhere,
orcaWorkerFormFromPrefs,
orcaWorkerDisplayName,
orcaWorkerStatusLabel,
readOrcaCollabEntryStatus,
type OrcaCollabEntryStatus,
type OrcaTeamWorker,
type OrcaWorkerAgentKind,
type OrcaWorkerFormValue,
type OrcaWorkerPermissionMode,
} from '@/session/orcaTeam';
import {
parseOrcaCollaborationSettings,
parseOrcaTeamWorkers,
readOrcaTeamLeadSessionId,
type OrcaCollaborationSettings,
} from '@cindy/maker-shared/orca-team';
import { subscribeRemoteOrcaWorkerChanged } from '@/device-link/DeviceLinkContext';
import { canSubmitOrcaWorkerForm, isPredefinedOrcaRole } from '@/session/ContextSheetCollabView';
import { normalizeMobileAgentCapabilities } from '@/session/agentCapabilities';
import {
defaultOrcaWorkerCreationPrefs,
hasLoadedOrcaWorkerCreationPrefs,
mergeOrcaWorkerChoice,
readOrcaWorkerCreationPrefs,
rememberOrcaWorkerChoice,
type OrcaWorkerCreationPrefs,
} from '@/session/orcaWorkerPrefs';
import {
remoteSessionStore,
resolveSessionWriteDevices,
sessionMetaWriteGuard,
sessionPendingWrites,
} from '@/session/remoteSessionStore';
import { writeGuardFields } from '@/session/swipeRowRegistry';
import { i18n } from '@/i18n';
import type { MobileMakerTransport } from '@/device-link/mobileMakerTransport';
import type { MobileModelConfiguration } from '@/session/unifiedMobileModels';
import type { RemoteSession } from '@/session/types';
import { useOrcaWorkerDirectoryPicker } from './useOrcaWorkerDirectoryPicker';
export type CollabSheetView = 'collab' | 'collab-create';
const ALL_AGENTS: readonly OrcaWorkerAgentKind[] = ['claude-code', 'codex', 'pi'];
const EMPTY_MODEL_OPTIONS: readonly MobileModelOption[] = [];
// ─── 团队状态 ────────────────────────────────────────────────────────────────
export interface OrcaTeamSnapshot {
workers: OrcaTeamWorker[];
/**
* 被控端的协同设置(只读权威值)。null = 还没读到;读取失败时保留上一次读到的值,
* 不用默认值冒充——否则会误判名额上限,错误地禁用或放行创建。
*/
settings: OrcaCollaborationSettings | null;
loading: boolean;
error: string | null;
}
const EMPTY_TEAM: OrcaTeamSnapshot = {
workers: [],
settings: null,
loading: false,
error: null,
};
/** Worker 任务有 status 在途写(乐观归档中):团队视图不展示它。 */
function isWorkerArchivePending(worker: OrcaTeamWorker): boolean {
return sessionPendingWrites.pendingFields(worker.sessionId).includes('status');
}
/**
* Worker 归档的乐观落地(协同面板长按与 Worker 自身菜单共用),写序与在途登记复用任务列表
* 归档那一套 app 级单例(sessionMetaWriteGuard / sessionPendingWrites):
* - 先登记 status 在途写,再按物理 shard 把 Worker 任务移出 store——在途期间 sessions 推送、
* 全量对账与单条 upsert 都不会把它复活,useOrcaTeam 也据此把它从团队视图藏起;
* - 返回 settle(ok):成功释放登记并主动对账该 shard(防归档前发出的读取迟到复活);
* 失败先释放登记(否则回滚的 upsert 会被在途保护挡掉),仍是最新写才把原会话整行插回
* 同一 shard,并一律 reseed——被同会话后续写取代时终态由新写负责。
*/
export function beginOptimisticWorkerArchive(
workerSessionId: string,
routeDeviceId: string | null,
): (ok: boolean) => void {
const session = remoteSessionStore.getSessions().find((item) => item.id === workerSessionId) ?? null;
const devices = resolveSessionWriteDevices(workerSessionId, session, routeDeviceId);
const patch = { status: 'archived' } as const;
const write = sessionMetaWriteGuard.begin(workerSessionId, writeGuardFields(patch));
const releasePending = sessionPendingWrites.track(workerSessionId, ['status']);
if (devices) remoteSessionStore.applySessionPatch(devices.shardId, workerSessionId, patch);
return (ok) => {
releasePending();
if (!devices) return;
const { shardId } = devices;
if (ok) {
// 归档 RPC 不回行:释放在途登记后,归档前已发出、成功后才落地的列表 / 单条读取
// 可能把旧 active 行插回。主动对账一次该 shard,以写库后的权威列表收敛。
remoteSessionStore.requestReseed(shardId);
return;
}
if (write.isLatest() && session) {
const shardName = remoteSessionStore.getSessions()
.find((item) => item.deviceLinkDeviceId === shardId)?.deviceLinkDeviceName
?? session.deviceLinkDeviceName
?? shardId;
remoteSessionStore.upsertDeviceSession(shardId, shardName, session);
}
remoteSessionStore.requestReseed(shardId);
};
}
/**
* Lead 任务的 Worker 列表 + 协同设置。`leadSessionId` 为 null 时不拉取。被控端推送
* worker-changed(需会话页持有 `session:<leadId>` topic)或调用 refresh 时整表重拉;
* 旧请求的迟到结果按请求代次丢弃。
*/
export function useOrcaTeam(params: {
maker: MobileMakerTransport;
deviceId: string | null;
leadSessionId: string | null;
/** 隧道重连代次:断线期间可能漏掉 worker-changed 推送,重连后整表重拉一次。 */
connectionEpoch?: number;
}): OrcaTeamSnapshot & {
refresh(): Promise<void>;
/** 乐观归档:把 Worker 从本地视图摘掉;返回的 restore 在失败时把它插回原位(团队没换时)。 */
dropWorker(worker: OrcaTeamWorker): () => void;
} {
const { maker, deviceId, leadSessionId, connectionEpoch } = params;
const [snapshot, setSnapshot] = useState<OrcaTeamSnapshot>(EMPTY_TEAM);
const generationRef = useRef(0);
const makerRef = useRef(maker);
makerRef.current = maker;
const snapshotRef = useRef(snapshot);
snapshotRef.current = snapshot;
const teamKeyRef = useRef(`${deviceId ?? ''}\n${leadSessionId ?? ''}`);
teamKeyRef.current = `${deviceId ?? ''}\n${leadSessionId ?? ''}`;
const refresh = useCallback(async () => {
const generation = ++generationRef.current;
if (!leadSessionId) {
setSnapshot(EMPTY_TEAM);
return;
}
setSnapshot((current) => ({ ...current, loading: true }));
try {
const [workers, settings] = await Promise.all([
makerRef.current.orca.listWorkers(leadSessionId),
makerRef.current.orca.getCollaborationSettings().catch(() => null),
]);
if (generation !== generationRef.current) return;
setSnapshot((current) => ({
workers: parseOrcaTeamWorkers(workers),
settings: settings === null ? current.settings : parseOrcaCollaborationSettings(settings),
loading: false,
error: null,
}));
} catch (error) {
if (generation !== generationRef.current) return;
setSnapshot((current) => ({
...current,
loading: false,
error: describeOrcaError(error, 'session.collab.errors.loadFailed'),
}));
}
}, [leadSessionId]);
useEffect(() => {
setSnapshot(EMPTY_TEAM);
void refresh();
return () => { generationRef.current += 1; };
}, [deviceId, refresh]);
const seenEpochRef = useRef(connectionEpoch);
useEffect(() => {
if (seenEpochRef.current === connectionEpoch) return;
seenEpochRef.current = connectionEpoch;
void refresh();
}, [connectionEpoch, refresh]);
useEffect(() => {
if (!deviceId || !leadSessionId) return undefined;
return subscribeRemoteOrcaWorkerChanged((pushDeviceId, pushLeadSessionId) => {
if (pushDeviceId === deviceId && pushLeadSessionId === leadSessionId) void refresh();
});
}, [deviceId, leadSessionId, refresh]);
const dropWorker = useCallback((worker: OrcaTeamWorker) => {
const teamKey = teamKeyRef.current;
const index = snapshotRef.current.workers.findIndex((item) => item.workerId === worker.workerId);
setSnapshot((current) => (current.workers.some((item) => item.workerId === worker.workerId)
? { ...current, workers: current.workers.filter((item) => item.workerId !== worker.workerId) }
: current));
return () => {
if (index < 0 || teamKeyRef.current !== teamKey) return;
setSnapshot((current) => {
if (current.workers.some((item) => item.workerId === worker.workerId)) return current;
const workers = [...current.workers];
workers.splice(Math.min(index, workers.length), 0, worker);
return { ...current, workers };
});
};
}, []);
// 归档在途的 Worker 不展示:在途期间迟到的整表重拉、其它页面加载过的旧快照都不得把它带回来。
const workers = snapshot.workers.some(isWorkerArchivePending)
? snapshot.workers.filter((worker) => !isWorkerArchivePending(worker))
: snapshot.workers;
return { ...snapshot, workers, refresh, dropWorker };
}
/** Worker 任务 → 所属 Lead(被控端团队记录为准;查不到 = null,「返回 Lead」入口不出现)。 */
export function useOrcaWorkerLeadSessionId(params: {
maker: MobileMakerTransport;
workerSessionId: string | null;
/** 隧道重连代次:首次查询赶上断线 / 瞬时失败时,重连后再查一次。 */
connectionEpoch?: number;
}): string | null {
const { maker, workerSessionId, connectionEpoch } = params;
const [leadSessionId, setLeadSessionId] = useState<string | null>(null);
const makerRef = useRef(maker);
makerRef.current = maker;
useEffect(() => {
setLeadSessionId(null);
}, [workerSessionId]);
useEffect(() => {
if (!workerSessionId) return undefined;
let cancelled = false;
makerRef.current.orca.getTeamByWorkerSession(workerSessionId)
.then((team) => { if (!cancelled) setLeadSessionId(readOrcaTeamLeadSessionId(team)); })
.catch(() => undefined);
return () => { cancelled = true; };
}, [workerSessionId, connectionEpoch]);
return leadSessionId;
}
/**
* Worker 表单状态(与桌面 CreateWorkerPopover 同一套记忆规则,见 orcaWorkerPrefs):
* 打开表单时恢复上次的 Agent 与该 Agent 的模型 / 推理强度 / Fast、权限;切 Agent 时带出
* 该 Agent 上次的选择;提交成功后调用 remember() 写回。完整手动选择按账号 / 任务电脑隔离,
* 不随 Lead 变化;旧版逐 Agent 记忆仍按当前电脑能力收敛。
*
* 模型选择器与 + 面板是两个 sheet(iOS 原生 sheet 不能叠开):选模型前收起面板,
* 选择器完全收起后再展开面板回到表单。
*/
export function useOrcaWorkerForm(params: {
maker: MobileMakerTransport;
executionDevicesEnabled?: boolean;
executionMakerForDevice?: (deviceId: string) => MobileMakerTransport;
/** 记忆按登录账号隔离;null = 未登录,不读写记忆(用首次默认值)。 */
prefsScope: string | null;
taskHostDeviceId?: string | null;
sshRemote?: boolean;
active: boolean;
setSheetOpen(open: boolean): void;
/** 隧道重连代次:断线时 Agent 列表 / 模型能力读失败,重连后在打开的表单上重读一次。 */
connectionEpoch?: number;
/** Lead 的 Agent 所在电脑(远程供应商);null / 缺省 = 任务所在电脑。Worker 默认跟它。 */
leadAgentDeviceId?: string | null;
/**
* 被控电脑支持给 Worker 单独选 Agent 所在电脑(supportsOrcaWorkerAgentDevice):表单带上位置,
* 模型选择器列出其他电脑与分享的供应商。不支持时不发送,Worker 跟 Lead。
*/
agentLocationSelectable?: boolean;
}) {
const { maker, prefsScope, active, setSheetOpen, connectionEpoch, taskHostDeviceId, sshRemote } = params;
const leadAgentDeviceIdRef = useRef(params.leadAgentDeviceId ?? null);
leadAgentDeviceIdRef.current = params.leadAgentDeviceId ?? null;
const agentLocationSelectableRef = useRef(params.agentLocationSelectable === true);
const leadLocationSelectableRef = useRef(params.agentLocationSelectable === true);
leadLocationSelectableRef.current = params.agentLocationSelectable === true;
/**
* 复位时 Worker 的 Agent 位置:跟 Lead。Lead 在另一台电脑时本机记忆的模型属于别的目录,
* 模型回到「默认」交给被控端按那台的目录解析(与桌面不指定模型时同口径)。
*/
const withLeadLocation = useCallback((value: OrcaWorkerFormValue): OrcaWorkerFormValue => {
const lead = leadAgentDeviceIdRef.current;
const selectable = leadLocationSelectableRef.current;
return {
...value,
...(lead ? { model: null } : {}),
agentDeviceId: selectable ? lead : undefined,
};
}, []);
const [form, setForm] = useState<OrcaWorkerFormValue>(() => {
const defaults = defaultOrcaWorkerCreationPrefs();
return orcaWorkerFormFromPrefs(defaults, defaults.lastAgent);
});
const executionMaker = useMemo(() => form.executionDeviceId && params.executionMakerForDevice
? params.executionMakerForDevice(form.executionDeviceId)
: maker, [form.executionDeviceId, maker, params.executionMakerForDevice]);
const [executionDevices, setExecutionDevices] = useState<OrcaExecutionDeviceView[]>([]);
const workerAgentLocationSelectable = params.agentLocationSelectable === true
&& (!form.executionDeviceId || executionDevices.some(device => device.deviceId === form.executionDeviceId && device.supportsAgentDevice === true));
agentLocationSelectableRef.current = workerAgentLocationSelectable;
const [executionDevicesLoading, setExecutionDevicesLoading] = useState(false);
const [executionDevicesError, setExecutionDevicesError] = useState<string | null>(null);
const [customRoleMode, setCustomRoleMode] = useState(false);
const [agents, setAgents] = useState<readonly OrcaWorkerAgentKind[]>(ALL_AGENTS);
const [modelPickerOpen, setModelPickerOpen] = useState(false);
const [modelsByAgent, setModelsByAgent] = useState<Partial<Record<OrcaWorkerAgentKind, readonly MobileModelOption[]>>>({});
const makerRef = useRef(executionMaker);
makerRef.current = executionMaker;
const formRef = useRef(form);
formRef.current = form;
const prefsRef = useRef<OrcaWorkerCreationPrefs>(defaultOrcaWorkerCreationPrefs());
const prefsLoadedRef = useRef(false);
/** 本次复位后用户是否动过表单:动过就不再让迟到的记忆 / 能力结果覆盖用户的选择。 */
const touchedRef = useRef(false);
/** 本次打开后用户是否明确选过 Agent(切 Agent / 选择器选模型 / 恢复草稿)。 */
const agentChosenRef = useRef(false);
const agentsRef = useRef(agents);
agentsRef.current = agents;
// 两个代次各管一条不变量,互不推进:
// - formEpochRef:当前这次「打开表单」(复位 / 恢复草稿 / 换账号各开一次)。迟到的记忆
// 只在同一次打开、且用户还没动过表单时补用;Agent 列表、能力这类非用户事件不推进它。
// - convergeGenRef:只让最近一次模型收敛请求的结果生效;用户手选模型也作废在途收敛。
const formEpochRef = useRef(0);
const convergeGenRef = useRef(0);
const hostRef = useRef(taskHostDeviceId);
hostRef.current = taskHostDeviceId;
const prefsScopeRef = useRef(prefsScope);
prefsScopeRef.current = prefsScope;
// 设备列表必须从 Lead 所在电脑读;模型与 Agent 则从选中的运行设备读。
// 老电脑不支持这个只读通道时隐藏选择入口,仍可创建 Lead 本机 Worker。
const leadMakerRef = useRef(maker);
useEffect(() => {
if (leadMakerRef.current !== maker || !params.executionDevicesEnabled) {
leadMakerRef.current = maker;
setExecutionDevices([]);
setExecutionDevicesError(null);
setForm((current) => current.executionDeviceId
? { ...current, executionDeviceId: undefined, remoteDirMode: undefined, remoteDir: undefined, model: null, modelSelectionExplicit: false }
: current);
}
}, [maker, params.executionDevicesEnabled]);
useEffect(() => {
if (!active || !params.executionDevicesEnabled) {
setExecutionDevicesLoading(false);
return undefined;
}
let cancelled = false;
setExecutionDevicesLoading(true);
setExecutionDevicesError(null);
void maker.orca.listExecutionDevices()
.then((value) => { if (!cancelled) setExecutionDevices(parseOrcaExecutionDevices(value)); })
.catch((error) => {
if (cancelled) return;
setExecutionDevices([]);
if (!isOrcaUnsupportedError(error)) {
setExecutionDevicesError(describeOrcaError(error, 'session.collab.errors.loadExecutionDevices'));
}
})
.finally(() => { if (!cancelled) setExecutionDevicesLoading(false); });
return () => { cancelled = true; };
}, [active, connectionEpoch, maker, params.executionDevicesEnabled]);
// 挂载 / 换账号时预读记忆,复位时即可同步恢复,不在用户操作期间异步覆盖表单。
// 换账号时推进代次:上一个账号还在路上的读取 / 能力收敛一律作废,不写进新账号的表单。
useEffect(() => {
formEpochRef.current += 1;
convergeGenRef.current += 1;
prefsLoadedRef.current = false;
prefsRef.current = defaultOrcaWorkerCreationPrefs();
setForm(withLeadLocation(orcaWorkerFormFromPrefs(prefsRef.current, prefsRef.current.lastAgent)));
if (!prefsScope) {
prefsLoadedRef.current = true;
return undefined;
}
let cancelled = false;
const scope = prefsScope;
void readOrcaWorkerCreationPrefs(scope).then((prefs) => {
if (cancelled) return;
prefsRef.current = prefs;
// 读取失败时仍按默认值展示,但不算「已读到」:复位时再读一次。
prefsLoadedRef.current = hasLoadedOrcaWorkerCreationPrefs(scope);
});
return () => { cancelled = true; };
}, [prefsScope, taskHostDeviceId, withLeadLocation]);
/**
* 按被控端能力收敛模型选择;能力读不到时保留原选择(提交时由被控端裁决)。
* 只改模型字段,且只有最近一次请求的结果生效(期间又收敛 / 用户又改了模型则丢弃)。
*/
const converge = useCallback((agent: OrcaWorkerAgentKind) => {
const generation = ++convergeGenRef.current;
const source = makerRef.current;
source.getCapabilities(agent)
.then((raw) => {
const capabilities = normalizeMobileAgentCapabilities(raw);
// 能力按 Agent 缓存,供老被控端(没有来源目录)时模型选择器的扁平回退列表使用。
// 只缓存当前这台电脑的结果:换电脑后迟到的上一台响应不写入。
if (capabilities && makerRef.current === source) {
setModelsByAgent((current) => ({ ...current, [agent]: capabilities.availableModels }));
}
if (generation !== convergeGenRef.current || makerRef.current !== source) return;
// Agent 在另一台电脑(远程供应商)时模型属于那台的目录,不按被控电脑的能力收敛。
setForm((current) => (current.agent === agent && !current.modelSelectionExplicit && !orcaWorkerAgentElsewhere(current)
? { ...current, model: convergeOrcaWorkerModel(current.model, capabilities) }
: current));
})
.catch(() => undefined);
}, []);
// 换了被控电脑(新建任务页切设备):上一台的 Agent 列表作废,回到乐观全集等这台的结果,
// 不让复位按上一台的列表挑 Agent。
const rosterMakerRef = useRef(executionMaker);
useEffect(() => {
if (rosterMakerRef.current === executionMaker) return;
rosterMakerRef.current = executionMaker;
convergeGenRef.current += 1;
agentsRef.current = ALL_AGENTS;
setAgents(ALL_AGENTS);
setModelsByAgent({});
}, [executionMaker]);
// 读被控端实际注册的 Agent。复位时列表可能还是乐观的三个:结果回来后,当前 Agent 不在这台
// 电脑上就切到第一个可用 Agent 并带出它的模型记忆(不论用户是否改过其它字段——角色、任务、
// 权限原样保留),避免表单停在一个必然提交失败的 Agent 上。当前 Agent 可用时也按能力再收敛
// 一次模型:重连后重跑本 effect 时,断线期间没能完成的收敛在这里补上。
useEffect(() => {
if (!active) return undefined;
let cancelled = false;
makerRef.current.listAvailableAgents()
.then((available) => {
if (cancelled) return;
const next = ALL_AGENTS.filter((agent) => available.includes(agent));
if (next.length === 0) return;
agentsRef.current = next;
setAgents(next);
// 目标 Agent:用户明确选过就尊重其选择;否则按记忆的上次 Agent(复位时可能因列表
// 还是乐观 / 上一台电脑的而落在别的 Agent 上)。不在这台电脑上时取第一个可用。
// 记住的路线由其所属电脑校验,不能被任务电脑的 Agent 列表改写。
if (formRef.current.modelSelectionExplicit || orcaWorkerAgentElsewhere(formRef.current)) return;
const current = formRef.current.agent;
const remembered = prefsRef.current.lastAgent;
const wanted = !agentChosenRef.current && next.includes(remembered) ? remembered : current;
if (wanted === current && next.includes(current)) {
converge(current);
return;
}
const switched = next.includes(wanted) ? wanted : next[0]!;
const agentPrefs = prefsRef.current.agents[switched];
setForm((value) => ({
...value,
agent: switched,
// 本机记忆的模型只属于被控电脑的目录;Agent 在另一台电脑时回到「默认」。
model: orcaWorkerAgentElsewhere(value)
? null
: { id: agentPrefs.model, providerId: null, effort: agentPrefs.effort, fast: agentPrefs.fast },
}));
converge(switched);
})
.catch(() => undefined);
return () => { cancelled = true; };
}, [active, connectionEpoch, converge, executionMaker]);
/** 重新打开已确认的表单(新建任务的协同草稿):角色模式跟随保存的角色,不沿用上次未提交的编辑。 */
const restore = useCallback((value: OrcaWorkerFormValue) => {
formEpochRef.current += 1;
agentChosenRef.current = true;
convergeGenRef.current += 1;
touchedRef.current = true;
setCustomRoleMode(!isPredefinedOrcaRole(value.role.trim().toLowerCase()));
setForm(value);
}, []);
/** 恢复记忆(上次的 Agent 不在当前电脑上时取第一个可用 Agent)。初始任务不记忆。 */
const reset = useCallback(() => {
const epoch = ++formEpochRef.current;
touchedRef.current = false;
agentChosenRef.current = false;
setCustomRoleMode(false);
const apply = (prefs: OrcaWorkerCreationPrefs) => {
const selection = !sshRemote && taskHostDeviceId ? prefs.modelSelectionByHost?.[taskHostDeviceId] : undefined;
const available = agentsRef.current;
const agent = selection?.agent ?? (available.includes(prefs.lastAgent) ? prefs.lastAgent : available[0] ?? prefs.lastAgent);
agentChosenRef.current = !!selection;
setForm(selection ? {
...orcaWorkerFormFromPrefs(prefs, agent),
...selection,
modelSelectionExplicit: true,
} : withLeadLocation(orcaWorkerFormFromPrefs(prefs, agent)));
converge(agent);
};
apply(prefsRef.current);
// 预读尚未完成(极少见:刚登录就打开表单):读完后仅在用户还没动过这张表单时补一次。
if (!prefsLoadedRef.current && prefsScope) {
const scope = prefsScope;
void readOrcaWorkerCreationPrefs(scope).then((prefs) => {
if (prefsScopeRef.current !== scope || hostRef.current !== taskHostDeviceId) return;
prefsRef.current = prefs;
prefsLoadedRef.current = hasLoadedOrcaWorkerCreationPrefs(scope);
if (epoch !== formEpochRef.current || touchedRef.current) return;
apply(prefs);
});
}
}, [converge, prefsScope, sshRemote, taskHostDeviceId, withLeadLocation]);
/** 切 Agent:带出该 Agent 上次的模型 / 推理强度 / Fast(对齐桌面)。 */
const changeAgent = useCallback((agent: OrcaWorkerAgentKind) => {
if (formRef.current.agent === agent) return;
touchedRef.current = true;
agentChosenRef.current = true;
const remembered = prefsRef.current.agents[agent];
setForm((current) => ({
...current,
agent,
// 自动带出的旧模型仍要按当前目录收敛,不能沿用上一行的显式选择标记。
modelSelectionExplicit: false,
// 本机记忆的模型只属于被控电脑的目录;Agent 在另一台电脑时回到「默认」。
model: orcaWorkerAgentElsewhere(current)
? null
: { id: remembered.model, providerId: null, effort: remembered.effort, fast: remembered.fast },
}));
converge(agent);
}, [converge]);
/** 提交成功后写回记忆(与桌面一样只在提交时记);读—合并—写由 rememberOrcaWorkerChoice 一处完成。 */
const remember = useCallback((choice: OrcaWorkerFormValue) => {
if (prefsScopeRef.current !== prefsScope || hostRef.current !== taskHostDeviceId) return;
// 未指定位置时按 Lead 的实际位置记忆,不能把旧端跟随远程 Lead 的模型写进本机旧槽。
const agentDeviceId = choice.agentDeviceId === undefined ? leadAgentDeviceIdRef.current : choice.agentDeviceId;
// 完整路线按任务电脑隔离,运行设备与 SSH 不进入这份记忆。
const submitted = {
...choice,
model: agentDeviceId !== null || choice.executionDeviceId ? null : choice.model,
...(!sshRemote && taskHostDeviceId && !choice.executionDeviceId ? {
taskHostDeviceId,
// 切 Agent 自动带出的模型仍按目录收敛;成功提交后不能再恢复上一条完整路线。
selection: choice.modelSelectionExplicit && choice.model
? { agent: choice.agent, agentDeviceId, model: choice.model }
: null,
} : {}),
};
prefsRef.current = mergeOrcaWorkerChoice(prefsRef.current, submitted);
if (!prefsScope) return;
const scope = prefsScope;
void rememberOrcaWorkerChoice(scope, submitted).then((next) => {
if (prefsScopeRef.current !== scope) return;
prefsRef.current = next;
prefsLoadedRef.current = hasLoadedOrcaWorkerCreationPrefs(scope);
});
}, [prefsScope, sshRemote, taskHostDeviceId]);
const patch = useCallback((next: Partial<OrcaWorkerFormValue>) => {
touchedRef.current = true;
if ('executionDeviceId' in next && next.executionDeviceId !== formRef.current.executionDeviceId) {
convergeGenRef.current += 1;
// 换工作电脑先回到它的本机默认;随后可单独选择它可调用的远程供应商。
setForm((current) => ({
...current,
...next,
model: null,
modelSelectionExplicit: false,
remoteDirMode: 'dialogue',
remoteDir: '',
agentDeviceId: next.executionDeviceId
? executionDevices.some(device => device.deviceId === next.executionDeviceId && device.supportsAgentDevice === true) ? null : undefined
: params.agentLocationSelectable ? leadAgentDeviceIdRef.current : undefined,
}));
} else {
setForm((current) => ({ ...current, ...next,
...('agentDeviceId' in next && !agentLocationSelectableRef.current ? { agentDeviceId: undefined } : {}),
}));
}
}, [executionDevices, params.agentLocationSelectable]);
const changePermission = useCallback(async (mode: OrcaWorkerPermissionMode) => {
touchedRef.current = true;
if (!await confirmFullAccessChange(form.permissionMode, mode)) return;
setForm((current) => ({ ...current, permissionMode: mode }));
}, [form.permissionMode]);
const openPicker = useCallback(() => {
setSheetOpen(false);
setModelPickerOpen(true);
}, [setSheetOpen]);
const close = useCallback(() => setModelPickerOpen(false), []);
const closed = useCallback(() => setSheetOpen(true), [setSheetOpen]);
const select = useCallback(async (
config: MobileModelConfiguration,
source?: { deviceId: string | null },
): Promise<boolean> => {
if (!ALL_AGENTS.includes(config.agent as OrcaWorkerAgentKind)) return false;
if (source !== undefined && formRef.current.executionDeviceId && !agentLocationSelectableRef.current) return false;
touchedRef.current = true;
agentChosenRef.current = true;
convergeGenRef.current += 1;
setForm((current) => ({
...current,
agent: config.agent as OrcaWorkerAgentKind,
modelSelectionExplicit: true,
model: {
id: config.modelId,
providerId: config.providerId || null,
effort: config.effort || null,
fast: config.fast ?? false,
},
// 选择器列出远程供应商时,行带着它所属的电脑(null = 任务所在电脑):Worker 的 Agent 跟着换过去。
...(source !== undefined && agentLocationSelectableRef.current
? { agentDeviceId: source.deviceId }
: {}),
}));
return true;
}, []);
const pickerAgents = useMemo<AgentKind[]>(() => [...agents], [agents]);
const directoryPicker = useOrcaWorkerDirectoryPicker({
deviceId: form.executionDeviceId, maker: executionMaker, scope: prefsScope,
formEpoch: formEpochRef.current, workingDir: form.remoteDir ?? '', setSheetOpen,
onChoose: (path) => patch({ remoteDirMode: path === null ? 'dialogue' : 'path', remoteDir: path ?? '' }),
});
/**
* 老被控端没有 `maker:provider:list` 时,模型选择器走扁平列表:用当前 Agent 的能力模型,
* 选中后按「不指定来源」写回表单(提交前再按实际来源对账 effort / Fast)。
*/
const flatModelOptions = modelsByAgent[form.agent] ?? EMPTY_MODEL_OPTIONS;
const selectFlatModel = useCallback((option: MobileModelOption) => {
setModelPickerOpen(false);
void select({
agent: formRef.current.agent,
modelId: option.id,
providerId: '',
effort: option.defaultEffort ?? '',
fast: false,
});
}, [select]);
return {
maker: executionMaker,
executionDevices,
executionDevicesLoading,
executionDevicesError,
form,
restore,
customRoleMode,
setCustomRoleMode,
patch,
changeAgent,
changePermission,
agents,
pickerAgents,
valid: canSubmitOrcaWorkerForm(form, customRoleMode)
&& (!form.modelSelectionExplicit || workerAgentLocationSelectable
|| form.agentDeviceId === undefined || form.agentDeviceId === (form.executionDeviceId ? null : params.leadAgentDeviceId ?? null))
&& (!form.executionDeviceId || executionDevices.some((device) => device.deviceId === form.executionDeviceId && device.supported)),
/** 模型选择器是否列出远程供应商(Lead 与选定工作电脑均支持独立 Agent 位置)。 */
agentLocationSelectable: workerAgentLocationSelectable,
reset,
remember,
directoryPicker,
modelPicker: { open: modelPickerOpen, openPicker, close, closed, select, flatModelOptions, selectFlatModel },
};
}
export function useSessionOrcaCollab(params: {
maker: MobileMakerTransport;
executionMakerForDevice?: (deviceId: string) => MobileMakerTransport;
deviceId: string | null;
sessionId: string;
session: RemoteSession | null;
/** Worker 创建偏好的记忆范围(按区域限定的账号键 accountKey);null = 不记忆。 */
prefsScope: string | null;
/** 隧道重连代次(会话页的 connectionEpoch):重连后补拉团队与 Worker 所属 Lead。 */
connectionEpoch?: number;
/** 提交时读被控端来源目录(未就绪 = null),用于收窄已失效的显式来源。 */
getProviders?: () => readonly ProviderView[] | null;
/** 共享任务访客 / 宿主托管任务不提供协同编排(不拉团队、不挂入口)。 */
enabled: boolean;
/** + 面板当前是否展示协同视图。 */
sheetView: CollabSheetView | null;
sheetOpen: boolean;
setSheetView(view: 'main' | CollabSheetView): void;
setSheetOpen(open: boolean): void;
/** target 缺省 = 当前任务所在电脑;在另一台电脑运行的 Worker 传那台。 */
openSession(sessionId: string, target?: { deviceId: string; deviceName?: string | null }): void;
/** 被控电脑支持给 Worker 单独选 Agent 所在电脑(远程供应商),见 useOrcaWorkerForm。 */
workerAgentLocationSelectable?: boolean;
}) {
const { maker, deviceId, sessionId, session, prefsScope, connectionEpoch, getProviders, enabled, sheetView, sheetOpen, setSheetView, setSheetOpen, openSession } = params;
// 远端真实任务的团队在另一台电脑,不能走本机团队查询或嵌套开启协同。
const role = enabled && !session?.orcaRemoteLead ? session?.orcaRole ?? null : null;
const isLead = role === 'lead';
const isWorker = role === 'worker';
const eligible = enabled && (isLead || isOrcaCollabEligible(session));
const team = useOrcaTeam({ maker, deviceId, leadSessionId: isLead ? sessionId : null, connectionEpoch });
const workerLeadSessionId = useOrcaWorkerLeadSessionId({
maker,
workerSessionId: isWorker ? sessionId : null,
connectionEpoch,
});
// Worker 任务自己在团队里的记录(焦点 / workerId),供详情菜单的 Worker 操作使用。
const workerTeam = useOrcaTeam({
maker,
deviceId,
leadSessionId: isWorker ? workerLeadSessionId : null,
connectionEpoch,
});
const workerSelf = isWorker
? workerTeam.workers.find((worker) => worker.sessionId === sessionId) ?? null
: null;
const workerForm = useOrcaWorkerForm({
maker,
executionMakerForDevice: params.executionMakerForDevice,
executionDevicesEnabled: eligible && !session?.remoteHostId,
prefsScope,
taskHostDeviceId: deviceId,
sshRemote: !!session?.remoteHostId,
active: eligible && sheetOpen && sheetView !== null,
setSheetOpen,
connectionEpoch,
leadAgentDeviceId: session?.remoteHostId ? null : (session?.agentDeviceId ?? null),
agentLocationSelectable: eligible && !session?.remoteHostId && params.workerAgentLocationSelectable === true,
});
const [entryStatus, setEntryStatus] = useState<OrcaCollabEntryStatus>('loading');
const [busy, setBusy] = useState(false);
const [error, setError] = useState<string | null>(null);
const makerRef = useRef(maker);
makerRef.current = maker;
const sessionRef = useRef(session);
sessionRef.current = session;
// 权威元数据补齐 Worker 身份时收起之前的协同表单。
useEffect(() => {
if (!eligible && (sheetView === 'collab' || sheetView === 'collab-create')) setSheetView('main');
}, [eligible, sheetView, setSheetView]);
// 换任务:错误与入口状态都属于上一个任务,整体复位。
useEffect(() => {
setEntryStatus('loading');
setError(null);
setBusy(false);
}, [sessionId, deviceId]);
// 打开 + 面板时读一次入口状态(能力 + 协同插件开关);Lead 只需确认能力。
// 重连后重读:断线时读失败会落成「不可用」,不能让已打开的表单一直卡住。
useEffect(() => {
const current = sessionRef.current;
if (!sheetOpen || !eligible || !current) return undefined;
let cancelled = false;
setEntryStatus('loading');
void readOrcaCollabEntryStatus(makerRef.current, current, orcaAgentKindForSession(current))
.then((status) => { if (!cancelled) setEntryStatus(status); });
return () => { cancelled = true; };
}, [sheetOpen, eligible, sessionId, role, connectionEpoch]);
// 协同视图展示中时顺带刷新一次团队(推送之外的兜底)。
const refreshTeam = team.refresh;
const dropTeamWorker = team.dropWorker;
useEffect(() => {
if (sheetOpen && sheetView === 'collab' && isLead) void refreshTeam();
}, [sheetOpen, sheetView, isLead, refreshTeam]);
const resetWorkerForm = workerForm.reset;
const rememberWorkerForm = workerForm.remember;
/** + 面板主视图的「协同模式」行:Lead 进团队面板,其它进开启表单。 */
const openFromMain = useCallback(() => {
if (!eligible || !isOrcaCollabEligible(sessionRef.current)) return;
setError(null);
if (!isLead) resetWorkerForm();
setSheetView('collab');
}, [eligible, isLead, resetWorkerForm, setSheetView]);
const openCreateWorker = useCallback(() => {
if (!eligible || !isOrcaCollabEligible(sessionRef.current)) return;
setError(null);
resetWorkerForm();
setSheetView('collab-create');
}, [eligible, resetWorkerForm, setSheetView]);
const form = workerForm.form;
const formValid = workerForm.valid;
const getProvidersRef = useRef(getProviders);
getProvidersRef.current = getProviders;
const submitEnable = useCallback(async () => {
if (!eligible || !isOrcaCollabEligible(sessionRef.current) || !deviceId || !formValid || busy) return;
setBusy(true);
setError(null);
try {
const submitted = narrowOrcaWorkerProvider(form, getProvidersRef.current?.() ?? null);
await enableOrcaTeam(makerRef.current, sessionId, buildOrcaEnableOptions(submitted, submitted.initialTask));
rememberWorkerForm(submitted);
remoteSessionStore.applySessionPatch(deviceId, sessionId, { orcaRole: 'lead' });
setSheetView('collab');
void refreshTeam();
} catch (err) {
setError(describeOrcaError(err, 'session.collab.errors.startFailed'));
} finally {
setBusy(false);
}
}, [busy, deviceId, eligible, form, formValid, refreshTeam, rememberWorkerForm, sessionId, setSheetView]);
const submitCreate = useCallback(async () => {
if (!eligible || !isOrcaCollabEligible(sessionRef.current) || !formValid || busy) return;
setBusy(true);
setError(null);
try {
const submitted = narrowOrcaWorkerProvider(form, getProvidersRef.current?.() ?? null);
await createOrcaWorker(makerRef.current, sessionId, submitted, team.workers);
rememberWorkerForm(submitted);
setSheetView('collab');
void refreshTeam();
} catch (err) {
setError(describeOrcaError(err, 'session.collab.errors.createFailed'));
} finally {
setBusy(false);
}
}, [busy, eligible, form, formValid, refreshTeam, rememberWorkerForm, sessionId, setSheetView, team.workers]);
const runTeamAction = useCallback(async (action: () => Promise<unknown>, fallbackKey: string) => {
setBusy(true);
setError(null);
try {
await action();
void refreshTeam();
return true;
} catch (err) {
// 超时不当作失败:主机可能仍在执行(结束协同会逐个关闭 Worker)。只读回查团队,提示以列表为准。
setError(describeOrcaError(
isOrcaAmbiguousTimeout(err) ? new Error('[ORCA_ACTION_UNCONFIRMED] timed out') : err,
fallbackKey,
));
void refreshTeam();
return false;
} finally {
setBusy(false);
}
}, [refreshTeam]);
/**
* 乐观归档 Worker(面板与 Worker 自身菜单共用):当帧从团队视图摘掉并把 Worker 任务移出
* store,RPC 在后台跑。成功后再摘一次(在途期间迟到的整表重拉可能把它带回快照)并以被控端
* 列表收敛;失败(含超时回查仍未确认)回滚 store 与团队视图并整表重拉。返回失败原因,null = 成功。
*/
const runWorkerArchive = useCallback(async (
leadId: string,
worker: OrcaTeamWorker,
view: { dropWorker(worker: OrcaTeamWorker): () => void; refresh(): Promise<void> },
): Promise<unknown> => {
const restoreView = view.dropWorker(worker);
const settle = beginOptimisticWorkerArchive(worker.sessionId, deviceId);
try {
await archiveOrcaWorker(makerRef.current, leadId, worker.workerId);
settle(true);
view.dropWorker(worker);
void view.refresh();
return null;
} catch (err) {
settle(false);
restoreView();
void view.refresh();
return err;
}
}, [deviceId]);
const openWorker = useCallback((worker: OrcaTeamWorker) => {
setSheetOpen(false);
// 看到「已完成」即确认(对齐桌面:可见的 done Worker 自动 acknowledge);状态已变则忽略。
if (worker.status === 'done') {
void makerRef.current.orca.acknowledgeDone(sessionId, worker.workerId).catch(() => undefined);
}
// 在另一台电脑运行的 Worker:本机这条只是代理任务,打开那台上的真实任务。
const remote = worker.executionDevice;
if (remote) {
openSession(remote.remoteSessionId, {
deviceId: remote.deviceId,
deviceName: remote.deviceName,
});
return;
}
openSession(worker.sessionId);
}, [openSession, sessionId, setSheetOpen]);
const confirmArchive = useCallback((worker: OrcaTeamWorker) => {
Alert.alert(
i18n.t('session.collab.archiveConfirmTitle', { name: orcaWorkerDisplayName(worker) }),
worker.executionDevice
? i18n.t('session.collab.archiveRemoteConfirmDesc', {
device: worker.executionDevice.deviceName ?? i18n.t('session.collab.otherComputer'),
})
: i18n.t('session.collab.archiveConfirmDesc'),
[
{ text: i18n.t('session.collab.cancel'), style: 'cancel' },
{
text: i18n.t('session.collab.archiveConfirm'),
style: 'destructive',
onPress: () => {
setError(null);
void runWorkerArchive(sessionId, worker, { dropWorker: dropTeamWorker, refresh: refreshTeam })
.then((err) => {
if (err) setError(describeOrcaError(err, 'session.collab.errors.archiveFailed'));
});
},
},
],
);
}, [dropTeamWorker, refreshTeam, runWorkerArchive, sessionId]);
/**
* 长按 Worker 行:管理操作(点按直接打开 Worker,不弹窗)。手机上只提供归档;「焦点」只决定
* 电脑端协同面板展开哪个 Worker,手机上不提供切换。
*/
const showWorkerActions = useCallback((worker: OrcaTeamWorker) => {
Alert.alert(orcaWorkerDisplayName(worker), orcaWorkerStatusLabel(worker.status), [
{
text: i18n.t('session.collab.archive'),
style: 'destructive',
onPress: () => confirmArchive(worker),
},
{ text: i18n.t('session.collab.cancel'), style: 'cancel' },
]);
}, [confirmArchive]);
const confirmEndTeam = useCallback(() => {
Alert.alert(
i18n.t('session.collab.stopConfirmTitle'),
i18n.t('session.collab.stopConfirmDesc'),
[
{ text: i18n.t('session.collab.cancel'), style: 'cancel' },
{
text: i18n.t('session.collab.stop'),
style: 'destructive',
onPress: () => {
void (async () => {
const ok = await runTeamAction(
() => makerRef.current.orca.disable(sessionId),
'session.collab.errors.stopFailed',
);
if (!ok || !deviceId) return;
remoteSessionStore.applySessionPatch(deviceId, sessionId, { orcaRole: null });
setSheetView('main');
setSheetOpen(false);
})();
},
},
],
);
}, [deviceId, runTeamAction, sessionId, setSheetOpen, setSheetView]);
const openLead = useCallback(() => {
if (workerLeadSessionId) openSession(workerLeadSessionId);
}, [openSession, workerLeadSessionId]);
// ─── Worker 任务自身的操作(详情菜单) ─────────────────────────────────────
const refreshWorkerTeam = workerTeam.refresh;
const dropWorkerTeamWorker = workerTeam.dropWorker;
/**
* 归档自身:确认弹窗在调用方的面板上直接弹出;用户确认后先调 onConfirmed(如收起详情面板),
* 立即回到 Lead(这个 Worker 任务即将不可用)并乐观归档;失败时 Worker 任务已插回,弹窗提示。
*/
const confirmArchiveSelf = useCallback((onConfirmed?: () => void) => {
if (!workerLeadSessionId || !workerSelf) return;
const leadId = workerLeadSessionId;
const worker = workerSelf;
Alert.alert(
i18n.t('session.collab.archiveConfirmTitle', { name: orcaWorkerDisplayName(worker) }),
i18n.t('session.collab.archiveConfirmDesc'),
[
{ text: i18n.t('session.collab.cancel'), style: 'cancel' },
{
text: i18n.t('session.collab.archiveConfirm'),
style: 'destructive',
onPress: () => {
onConfirmed?.();
openSession(leadId);
void runWorkerArchive(leadId, worker, { dropWorker: dropWorkerTeamWorker, refresh: refreshWorkerTeam })
.then((err) => {
if (err) Alert.alert(describeOrcaError(err, 'session.collab.errors.archiveFailed'));
});
},
},
],
);
}, [dropWorkerTeamWorker, openSession, refreshWorkerTeam, runWorkerArchive, workerLeadSessionId, workerSelf]);
return {
eligible,
isLead,
isWorker,
entryHint: !eligible || isLead ? null : orcaCollabEntryHint(entryStatus),
entryBlocked: !eligible || (!isLead && entryStatus !== 'ready'),
team,
workerLeadSessionId,
openLead,
/** Worker 任务自身在团队里的记录;查不到(老被控端 / 读取中)为 null,Worker 操作不出现。 */
workerSelf,
refreshWorkerSelf: refreshWorkerTeam,
confirmArchiveSelf,
workerForm,
busy,
error,
canSubmit: eligible && workerForm.valid && !busy,
openFromMain,
openCreateWorker,
submitEnable,
submitCreate,
openWorker,
showWorkerActions,
confirmEndTeam,
};
}