Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* deviceLinkCreateArgs —— 组装 device-link 远程建会话(maker:create-session 隧道)的参数。
* ---------------------------------------------------------------------------
* 抽成纯函数是为了把「归属一致」这条行为锁进单测,而不是只靠 grep 接线:
* 控制端在远程项目目录下建会话时,必须把 workspaceKind 传成 **'project'** —— 被控端据此
* 把会话挂到该项目目录下;若误传 'dialogue' / standalone,控制端在项目里、被控端却独立
* 在项目外(历史上真实出过的「两端归属不一致」bug)。
*
* 2026-07(#807):远程草稿**不再必带项目目录** —— 「在对端设备上开一个不绑项目的对话」是
* 合法意图(每台设备都有自己的一批对话)。此时 workingDir 缺省、workspaceKind 传 'dialogue',
* 由被控端按 standalone dialogue 自行分配运行目录,与本机侧
* `workspaceKind: workingDir ? 'project' : 'dialogue'` 完全同口径。
* 归属一致的约束反而更硬了:两个字段现在由同一个 workingDir 派生 —— 有目录必是 'project',
* 无目录必是 'dialogue',不可能再错配。
*
* agentKind 归一到 maker-core 形态('cc' → 'claude-code');其余字段原样透传。
*/
import { effectiveSourceIdForModel, getModel, reconcileInvocationEffort, type ProviderView } from '@cindy/model-providers';
import type { Session, WorkspaceKind } from '@/lib/ccAgent.types';
import type { AgentKind } from '@/hooks/useAgentCapabilities';
import type { Effort, PermissionMode } from '@/lib/userPreferences.types';
export interface DeviceLinkCreateParams {
/** 草稿 vendor 形态:'cc' | 'codex' | 'pi'(persistedAgentKind)。 */
agentKind: 'cc' | 'codex' | 'pi';
/**
* 被控端上的项目目录。缺省 / 空白 = 在该设备上建**不绑项目的 standalone dialogue**,
* workspaceKind 随之派生为 'dialogue',运行目录由被控端分配。
*/
workingDir?: string;
/**
* 预生成的 session id(可选)。远程 worktree 流程用:控制端先经隧道调被控端
* worktree:create(以该 id 登记 worktreeStore 绑定),再以同一 id 建会话——两步共用
* 一个 id,被控端 close-session 时才能按绑定回收 worktree。非 worktree 流程不传,
* 由被控端自行生成。
*/
id?: string;
model: string;
effort: Effort | null;
permissionMode: PermissionMode;
fastMode: boolean | 'ultrafast';
planModeEnabled?: boolean;
/**
* 附加只读引用目录(草稿期用户选的)。控制端选的是**本机路径**(extraDirs picker 走本机
* 原生目录对话框),随 create 透传到被控端后,被控端 create 落地在 bootstrapSession 里按
* 与 set-extra-dirs 同款的 validateExtraDirs(对被控端 workingDir + 本机 FS)校验,只保留
* 通过的子集 —— 与远程 set-extra-dirs 的既有行为完全一致(控制端路径在被控端常被拒)。
*/
extraDirs?: string[];
writableDirs?: string[];
/**
* 草稿选定的来源(**被控端**供应商 id;null / 省略 = 跟随被控端默认路由)。被控端 create 时
* 落 `sessions.provider_id`,使新远程会话首个请求即按所选来源路由(与会话内切来源对称)。
*/
providerId?: string | null;
/**
* 远程 Agent:Agent 在同账号另一台电脑运行(被控电脑支持时才会给)。此时 model / providerId
* 属于那台电脑的目录,被控电脑把它记进任务、经那台运行 Agent(与手机新建任务同一个参数)。
*/
agentDeviceId?: string | null;
}
export interface DeviceLinkCreateArgs {
agentKind: 'claude-code' | 'codex' | 'pi';
/** 仅远程 worktree 流程出现(与 worktree:create 登记的绑定同 id)。 */
id?: string;
/** 仅项目会话出现;dialogue 不带此字段(被控端自行分配运行目录)。 */
workingDir?: string;
/** 由 workingDir 派生 —— 有目录 'project',无目录 'dialogue'。归属一致的关键。 */
workspaceKind: WorkspaceKind;
model: string;
effort: Effort | '';
permissionMode: PermissionMode;
fastMode: boolean | 'ultrafast';
planMode?: boolean;
/** 仅当草稿有非空 extraDirs 时出现;被控端 bootstrapSession 再校验(单一真相源)。 */
extraDirs?: string[];
writableDirs?: string[];
/** 仅当草稿显式选了非空来源时出现(null/空 = 跟随默认路由 → 不放进 args,provider_id 留 NULL)。 */
providerId?: string;
/** 仅当 Agent 在另一台电脑运行时出现;缺省 = Agent 在被控电脑本身。 */
agentDeviceId?: string;
}
export function buildDeviceLinkCreateArgs(p: DeviceLinkCreateParams): DeviceLinkCreateArgs {
// 空白目录一律当「没选项目」处理(与本机 selectedWorkingDir 的 trim() || undefined 同口径),
// 免得 ' ' 这种脏值在被控端被当成一个真实路径去校验。
const dir = p.workingDir?.trim();
return {
agentKind: p.agentKind === 'cc' ? 'claude-code' : p.agentKind,
// 预生成 id 仅在远程 worktree 流程出现;不传时不放进 args,被控端自行生成。
...(p.id ? { id: p.id } : {}),
// 有目录 → 项目会话;无目录 → standalone dialogue,不带 workingDir,由被控端分配运行目录。
...(dir ? { workingDir: dir } : {}),
workspaceKind: dir ? 'project' : 'dialogue',
model: p.model,
// Empty string is the wire representation for a model without an effort selector;
// the remote host's admission layer treats it as unspecified.
effort: p.effort ?? '',
permissionMode: p.permissionMode,
fastMode: p.fastMode,
...(p.planModeEnabled ? { planMode: true } : {}),
// 空 / 缺省不放进 args:payload 干净,且被控端 bootstrapSession 也只在非空时才校验。
...(p.extraDirs && p.extraDirs.length > 0 ? { extraDirs: p.extraDirs } : {}),
...(p.writableDirs && p.writableDirs.length > 0 ? { writableDirs: p.writableDirs } : {}),
// providerId 同理:仅非空显式来源才放进 args;null/空 → 不带 → 被控端 provider_id 留 NULL(默认路由)。
...(p.providerId ? { providerId: p.providerId } : {}),
...(p.agentDeviceId ? { agentDeviceId: p.agentDeviceId } : {}),
};
}
/**
* 一次远程建会话要提交的「候选值」。两个来源:
* · 普通发送 —— ChatInput 回传的实时值(用户界面上此刻看到的那一组);
* · 新建目标 —— 组件级派生值(弹窗独立于 ChatInput,拿不到回传)。
* 两者形状相同,于是能过同一道校准。
*/
export interface DeviceLinkSubmissionCandidate {
model: string;
effort: Effort | null;
permissionMode: PermissionMode;
fastMode: boolean | 'ultrafast';
planModeEnabled?: boolean;
/** 用户显式选中的被控端来源;null / 省略 = 跟随被控端默认路由。 */
providerId?: string | null;
}
export interface DeviceLinkSubmissionParams {
agentKind: 'cc' | 'codex' | 'pi';
workingDir?: string;
id?: string;
extraDirs?: string[];
writableDirs?: string[];
candidate: DeviceLinkSubmissionCandidate;
/**
* 模型目录(useDeviceProviders 经隧道拉到的那一份):通常是**被控端**的;Agent 在另一台电脑运行时
* 是那台的(来源也在那份目录里解析)。
*/
deviceProviders: ProviderView[];
capabilityAgentKind: AgentKind;
/** 远程 Agent:运行 Agent 的另一台电脑;缺省 = 被控电脑本身。 */
agentDeviceId?: string | null;
}
/**
* 远程建会话参数的**唯一入口**:校准候选值 → 组装 args。
*
* 为什么必须只有一个入口(#807 review 第 25 轮的结构性教训):在此之前「发送」与「新建目标」
* 各自推导这组值 —— 发送用 ChatInput 回传的实时值,新建目标用组件级派生值 —— 最后才汇进同一个
* buildDeviceLinkCreateArgs。于是任何一条校准规则只要漏加在一边,就会长出一个**只在其中一条路径
* 上复现**的缺陷:那一轮的 providerId 正是如此,普通发送没事(ChatInput 内部会用 effectiveSourceId
* 重算、失效即回落),新建目标却把一个未认证的来源直接写进被控端 sessions.provider_id,新目标起不来。
* 同一个模具还压出过「新建目标不支持 device-only 草稿」(第 11 轮)与另外两处对称性缺口。
*
* 所以两条路径现在都只提供**候选值**,校准与组装都发生在这里 —— 规则改一次,两条路径同时受益,
* 想只改一边都做不到。
*
* 为什么发送路径也要在这里再校准一次(它以前靠 ChatInput 内部重算):那等于把正确性寄托在**另一个
* 组件的实现细节**上。ChatInput 今天恰好会重算,不代表它有义务永远重算;而这里离 `maker:create-session`
* 只有一步,是「提交什么就校准什么」最后也最可靠的位置。重复校准无副作用:仍有效的来源原样返回。
*
* 显式连接原样传给被控端,由被控端校验;控制端快照失效或未加载不能抹掉账号身份。
* 只有未指定连接时,才用 effectiveSourceIdForModel 解析默认来源。
*/
export function resolveDeviceLinkSubmission(p: DeviceLinkSubmissionParams): DeviceLinkCreateArgs {
const providerId = p.candidate.providerId || effectiveSourceIdForModel(
p.deviceProviders,
null,
p.candidate.model,
p.capabilityAgentKind,
);
const routeProvider = providerId
? p.deviceProviders.find((provider) => provider.id === providerId)
: undefined;
const routeModel = routeProvider
? getModel(routeProvider, p.candidate.model, p.capabilityAgentKind)
: undefined;
const effort =
!routeModel || routeModel.effortsUnknown === true ||
(routeModel.efforts.length === 0 && routeModel.effortsUnknown !== false)
? p.candidate.effort
: reconcileInvocationEffort({
requested: p.candidate.effort,
model: routeModel,
noEffortFallback: null,
});
return buildDeviceLinkCreateArgs({
agentKind: p.agentKind,
id: p.id,
workingDir: p.workingDir,
model: p.candidate.model,
effort,
permissionMode: p.candidate.permissionMode,
fastMode: p.candidate.fastMode,
planModeEnabled: p.candidate.planModeEnabled,
extraDirs: p.extraDirs,
writableDirs: p.writableDirs,
providerId,
agentDeviceId: p.agentDeviceId,
});
}
export interface ProvisionalRemoteSessionParams {
/** 被控端 create 响应里的会话 id。 */
sessionId: string;
/**
* 被控端**真正分配**的运行目录(create 响应的 `workDir`)。纯对话由对端分配,控制端猜不到,
* 所以只能取响应值 —— 而 SessionView 的 delayed-create 交接又硬要求 workingDir 非空。
*/
workDir: string;
/** 刚提交给被控端的那份 args:model / effort / permission / workspaceKind 等都以它为准。 */
args: DeviceLinkCreateArgs;
/** 当前时刻 ISO 串。由调用方注入,便于单测固定时间。 */
nowIso: string;
}
/**
* 远程会话的**临时行**:create 成功、权威快照(sessions:list 回流)还没到时先塞进镜像。
*
* 为什么必须有:origin 钉子只让「这条会话属于哪台设备」立刻可判定,但首条消息的交接另有门槛 ——
* CCAgentSessionView 的 delayed-create effect 要求 `session` 非空**且** `session.workingDir`
* 非空才会 consumePending。镜像里的会话行只有权威快照能带来,所以回流失败时那条消息就一直不发;
* 而 `gave-up` 里的永久错误(老被控端没把 `local-db:sessions:list` 放进 allowlist、
* REMOTE_DISABLED)意味着这一轮**永远**不会有快照,首条消息就永久躺着不发,草稿又已经清掉。
*
* 为什么不算编造:workDir 取 create 响应(对端真正分配的);model / effort / permissionMode /
* workspaceKind / extraDirs / providerId 就是我们刚提交给它的值;title / 计数 / 时间戳是新会话的
* 确定初值(被控端 create 出来的标题也正是 'New Maker')。权威快照到达后 setDeviceSessions 整片
* 替换该设备分片,一切以对端为准。
*
* userId 是唯一取不到的字段(那是被控端库里的行主键关联),留空串:镜像消费方(侧边栏分组 /
* SessionView / 传输层)都不读它,权威快照也会立刻覆盖。
*/
export function buildProvisionalRemoteSession(p: ProvisionalRemoteSessionParams): Session {
return {
id: p.sessionId,
userId: '',
// 被控端 create 的默认标题就是这个;auto-title 随后会按需覆盖(两端同一判据)。
title: 'New Maker',
workingDir: p.workDir,
workspaceKind: p.args.workspaceKind,
model: p.args.model,
effort: p.args.effort,
permissionMode: p.args.permissionMode,
providerId: p.args.providerId ?? null,
sdkSessionId: null,
totalTokenUsage: 0,
totalCostUsd: 0,
contextTokens: 0,
contextWindow: 0,
fastMode: p.args.fastMode,
planModeEnabled: p.args.planMode ?? false,
clearedAt: null,
pinnedAt: null,
// 与被控端刚建出的行一致:首条还没被收下,userSendAt 为空。「用户正在发第一条」由
// remoteProjectsStore 的首条发送叠加层在投影层补上 —— 写进分片的话,随后任何一次列表
// 回流都会把它冲回 null,会话就先掉进项目外的草稿区、首条落地后再跳回项目。
userSendAt: null,
status: 'active',
// Session.agentKind 是本机形态('cc' | 'codex' | 'pi'),args 里是 maker-core 形态,这里转回来。
agentKind: p.args.agentKind === 'claude-code' ? 'cc' : p.args.agentKind,
// 乐观行就带上 Agent 所在电脑:会话页的模型按钮与目录从一开始就按那台显示。
...(p.args.agentDeviceId ? { agentDeviceId: p.args.agentDeviceId } : {}),
extraDirs: p.args.extraDirs ?? [],
writableDirs: p.args.writableDirs ?? [],
createdAt: p.nowIso,
updatedAt: p.nowIso,
};
}