Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* modelEnginePrefs —— 「(来源, 模型) → 用户显式选定的引擎(harness)」**override** 存储,
* localStorage 持久化,跨会话 / 跨重启在本机生效。统一模型选择器(model-selector-unified
* §2.3)的第五根轴。
*
* 背景:
* 新选择器让用户**只选模型**,引擎由推荐映射自动配好(推荐 = 模型生效来源 provider 的
* 主 root,纯客户端推导,见 M1 unifiedSelection)。用户在配置浮层里改引擎时,才在这里
* 记一条 override;浮层的「恢复推荐」= 删这条 override,之后随版本跟随新的推荐映射。
*
* 只存 override(configuration-and-overrides.md §2/§4):
* - 表里**没有**某 (providerId, modelId) ⇒ 该模型跟随推荐引擎,不是「没有引擎」。
* - 因此绝不把推荐值快照写进来:那会把当前版本的默认固化成用户配置,服务端改推荐后
* 未自定义的用户吃不到(三类用户行为见规格 §2.5:新用户 / 未自定义老用户 = 空表)。
* - 恢复推荐一律走 clearModelEngineOverride(删 key),不写「等于推荐值」的 override。
*
* 零迁移:
* 本 store 是新增的独立轴,不合并、不改写四根旧轴(newMakerDraft.lastByVendor /
* modelChosenByVendor / providerModelMemory 的 `<agent>:*` 深度+Fast 槽 /
* modelVisibilityPrefs)。老用户空表即「全部跟随推荐」,旧数据不搬不猜。
*
* 为什么 agent 用 'cc' | 'codex' | 'pi'(SelectableVendor)而不是 useAgentCapabilities
* 的 AgentKind('claude-code' | ...):
* 本 store 的下游是**选择器 → newMakerDraft** 那条链路 —— 选中确定后要派生
* `(vendor, model, effort, fastMode, providerId)` 写进 newMakerDraft(规格 §2.4),而
* newMakerDraft / agentVendors / ChatInput 全线用的是 vendor 口径。存 vendor 可以让
* 落盘值与写入 draft 的值同形,不必在持久层与消费层之间来回映射。需要 capabilities /
* catalog 那侧的 'claude-code' 口径时,在查能力的边界上转(仓内既有做法:
* modelDefinitions.agentKindForVendor)。
* 校验直接复用 agentVendors.isSelectableVendor —— 与 newMakerDraft.sanitize 同一张表,
* 将来新增引擎这里零改动(逐个写死三元的老写法每上线一个引擎都得手工补一次,漏补则
* 用户选中新引擎、重启后被静默重置)。
*
* 持久化频率极低(仅用户在浮层点引擎胶囊触发),**同步写** localStorage,不做 batch /
* debounce —— 与 newMakerDraft / providerModelMemory / modelVisibilityPrefs 的取舍一致:
* release 的「热更新 → relaunch」路径走 app.exit() 强退,异步写(setTimeout / debounce)
* 来不及 fire,最近一次改动会丢。写失败(localStorage 满 / 私密窗口禁写)静默吞,内存态
* 照常生效,不把用户当次操作打断。
*
* 多窗口:Electron 每个 renderer 有独立模块实例,localStorage 是它们之间的共享真相。
* 监听 storage 事件后**重读 localStorage**(而不是信事件里的 newValue)——迟到的事件带的
* 是旧值,直接采信会把本窗口刚写的新值回滚(newMakerDraft 的 rebase 先例)。
*
* 并发写(2026-08-17 review H1 / K1 / K2)—— 与 modelFavorites **同一套机制**(共用
* `storageOpReplay`,机制正文在那个文件的头注):写入表达成可重放且幂等的 op(set / clear),
* 同步乐观写保持不变,op 同时记进**该 storage key 的会话 op-log**;随后在 `navigator.locks`
* 里把**整条 log** 重放到该 key 此刻的真相上,并且**storage 事件也会再触发调和** —— 别窗用
* 旧基底做的迟到覆盖抹掉本窗的 op 时,本窗收到事件后把它重新断言回去(K2),owner 被切走
* 也照常按捕获的 key 调和(K1)。
* 少了这一层,两个 renderer 同时改不同模型的引擎时,后写者会拿旧快照整表覆盖先写者
* (对方那条 override 静默消失);「A 改引擎 + B 恢复推荐」交错时,A 的整表写还会把 B 已经
* 删掉的那条 override 复活。锁不可用时跳过调和,行为退回改动前;op 的退休条件(TTL / 断言
* 次数上界)与残余边界见 storageOpReplay.ts 文件头。
*
* 账号分区:key 带 dataOwnerId 后缀(setModelEnginePrefsOwner,与 newMakerDraft 同形),
* 吸取 providerModelMemory 不分账号导致多账号串号的教训。
*/
import { useSyncExternalStore } from 'react';
import { isSelectableVendor, type SelectableVendor } from '@/lib/agentVendors';
import { MODEL_PRESET_SLOT_ID } from './providerModelMemory';
import { createStorageReconciler } from './storageOpReplay';
const STORAGE_KEY = 'xdt:modelEnginePrefs:v1';
/** 引擎 override 的取值域 = 用户可选引擎表(见文件头对口径的说明)。 */
export type ModelEngine = SelectableVendor;
/**
* 单条 override。刻意用对象而不是裸字符串:规格预留了「同一 (来源, 模型) 上还要记别的
* 用户显式选择」的可能(如智能模式落位),对象形状加字段时老数据天然兼容。
*/
export interface ModelEngineOverride {
agent: ModelEngine;
}
/** 表:key=`${providerId}:${modelId}` → override。 */
type EnginePrefsMap = Record<string, ModelEngineOverride>;
let activeDataOwnerId: string | null = null;
function storageKey(): string {
return activeDataOwnerId ? `${STORAGE_KEY}:${encodeURIComponent(activeDataOwnerId)}` : STORAGE_KEY;
}
/**
* key 组合与 providerModelMemory / modelVisibilityPrefs 同形(冒号拼接)。这里**只按
* (providerId, modelId) 双参查表,从不反解 key**,所以 id 内含冒号也不会读错;不要新增
* 依赖「split(':') 还原两段」的读法。
*/
function keyOf(providerId: string, modelId: string): string {
return `${providerId}:${modelId}`;
}
/**
* `'*'` 是 providerModelMemory v2 schema 里的**保留来源 id**(同 agent 下跨真实 provider
* 的模型级预设槽)。新代码读写路径都要防撞(规格 §4「偏好/记忆」),否则一条用 `'*'` 拼出
* 的 key 会和真实来源的记录混在同一张表里,语义不可分辨。
*/
function isUsableProviderId(providerId: unknown): providerId is string {
return (
typeof providerId === 'string'
&& providerId.length > 0
&& providerId !== MODEL_PRESET_SLOT_ID
);
}
/**
* 严格校验:只保留 value 是 `{ agent: 可选引擎 }` 的条目;key 为空、value 形状不对、
* 引擎不在 SELECTABLE_VENDORS(如历史残留的 'orca')的条目一律丢弃 —— 丢弃 = 该模型回到
* 「跟随推荐」,是安全方向。老版本 / 手改 localStorage 损坏时静默回退空表,不抛。
*/
function sanitize(raw: unknown): EnginePrefsMap {
if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
const out: EnginePrefsMap = {};
for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
if (!k || !v || typeof v !== 'object') continue;
const agent = (v as { agent?: unknown }).agent;
if (!isSelectableVendor(agent)) continue;
out[k] = { agent };
}
return out;
}
// 进程内缓存(惰性加载)。读多写少,避免每次读都 parse localStorage。
let cache: EnginePrefsMap | null = null;
/**
* 按**给定 key** 读原始 localStorage(不碰缓存)。key 可能不是当前 active 分区 ——
* 登出 / 切号之后旧分区的调和仍要按它自己的 key 读写(见文件头「并发写」)。
*/
function loadFromKey(key: string): EnginePrefsMap {
if (typeof window === 'undefined') return {};
try {
const raw = window.localStorage.getItem(key);
return raw ? sanitize(JSON.parse(raw)) : {};
} catch {
return {};
}
}
function loadFromStorage(): EnginePrefsMap {
return loadFromKey(storageKey());
}
function load(): EnginePrefsMap {
if (!cache) cache = loadFromStorage();
return cache;
}
/**
* **写路径的基底** —— 每次写入前重读 localStorage,拿此刻的共享真相当底,而不是本窗口的
* 内存快照(与 modelFavorites 同一处理,同一理由)。
*
* `persist` 是整表写回:另一个窗口刚记下一条 override、`storage` 事件还没送到本窗口时,
* 本窗口任何写入都会用陈旧整表覆盖回去,对方那条静默消失(用户看到的是「刚选的引擎又变
* 回去了」)。读路径仍走缓存(读多写少,且陈旧一帧无害)。
*
* 读不到持久化值时退回内存缓存、不退回空表:私密窗口 / 写满时 `setItem` 静默失败(见
* persist),`getItem` 恒 null —— 拿空表当基底会把本次会话内的全部 override 一次抹掉。
*/
function freshMap(): EnginePrefsMap {
if (typeof window === 'undefined') return load();
let raw: string | null = null;
try {
raw = window.localStorage.getItem(storageKey());
} catch {
return load();
}
if (raw === null) return load();
try {
return sanitize(JSON.parse(raw));
} catch {
return load();
}
}
/**
* 两张表是否等价。storage 事件的「无变化短路」与并发重放的「有差异才写」共用这一份判据。
*/
function sameMap(a: EnginePrefsMap, b: EnginePrefsMap): boolean {
const aKeys = Object.keys(a);
const bKeys = Object.keys(b);
return aKeys.length === bKeys.length && bKeys.every((k) => a[k]?.agent === b[k]?.agent);
}
// ── 可重放的写操作(见文件头「并发写」)────────────────────────────────────
/** 一次写入的完整表达;只依赖 op 自身 + 目标表,能原样重放到最新状态上。 */
type EnginePrefsOp =
| { kind: 'set'; key: string; agent: ModelEngine }
| { kind: 'clear'; key: string };
/** 施加一个 op;**无实际变化时返回入参对象本身**(调用方按引用判等短路)。 */
function applyOp(map: EnginePrefsMap, op: EnginePrefsOp): EnginePrefsMap {
if (op.kind === 'set') {
// 幂等:同值(可能是本次同步写留下的,也可能是另一窗口写的)→ 原样返回。
if (map[op.key]?.agent === op.agent) return map;
return { ...map, [op.key]: { agent: op.agent } };
}
// 幂等:已经没有这条(如另一窗口先删了)→ 原样返回,不制造无意义落盘 / 通知。
if (!(op.key in map)) return map;
const next = { ...map };
delete next[op.key];
return next;
}
/**
* 会话 op-log 的归并:同一条 key 上**只留最后一次显式选择**(set 或 clear)。
* 这张表的每条 key 是各自独立的一维,历史 op 对它没有增量意义;不归并的话,重放会把用户
* 在本会话里先后做的两次相反选择(改引擎 → 又恢复推荐)按顺序全断言一遍,结果虽仍是最后
* 那次,却白写了一轮,也让 log 无谓膨胀。
*/
function compactEnginePrefsOps(
log: readonly EnginePrefsOp[],
op: EnginePrefsOp,
): readonly EnginePrefsOp[] {
return [...log.filter((entry) => entry.key !== op.key), op];
}
const reconciler = createStorageReconciler<EnginePrefsMap, EnginePrefsOp>({
// active 分区走 freshMap(带着「读不出来就退回内存缓存」的既有兜底);其它分区按 key 直读。
read: (key) => (key === storageKey() ? freshMap() : loadFromKey(key)),
apply: applyOp,
persist: (key, state) => persistTo(key, state),
adopt: (key, state) => {
if (key !== storageKey()) return;
if (sameMap(cache ?? {}, state)) return;
cache = state;
emit();
},
compact: compactEnginePrefsOps,
// 「恢复推荐」(删 override)比 set 活得久:并发窗口内两窗做相反动作时让删除胜出
// (见 storageOpReplay 文件头 —— 复活一条已被清掉的 override 是静默错误)。
tombstone: (op) => op.kind === 'clear',
});
/**
* 一次写入 = **同步乐观写**(热更强退不丢)+ 把 op 记进**当时那个 key** 的会话 op-log 并
* 调度一次锁内调和。与 modelFavorites.commitOp 逐字同形(K1 / K2 的修复也同形)。
*/
function commitOp(op: EnginePrefsOp): void {
const base = freshMap();
const next = applyOp(base, op);
if (next !== base) persist(next);
const key = storageKey();
reconciler.record(key, op);
reconciler.schedule(key);
}
// ── 订阅 / 版本(供 useSyncExternalStore)──────────────────────────────────
let version = 0;
const listeners = new Set<() => void>();
function emit(): void {
version += 1;
for (const l of listeners) l();
}
/**
* 落盘到**指定 key**。缓存与通知只在该 key 恰是当前 active 分区时才做 —— 调和可能发生在
* 登出 / 切号之后的旧分区上,那时本窗口的内存态属于新分区,绝不能被旧分区的内容覆盖。
*/
function persistTo(key: string, next: EnginePrefsMap): void {
if (typeof window !== 'undefined') {
try {
// 同步写:见文件头(热更 relaunch 走 app.exit(),异步写会丢最近一次改动)。
window.localStorage.setItem(key, JSON.stringify(next));
} catch {
// localStorage 满 / 私密窗口禁写 —— 静默吞,内存态仍生效。
}
}
if (key !== storageKey()) return;
cache = next;
emit();
}
function persist(next: EnginePrefsMap): void {
persistTo(storageKey(), next);
}
function subscribe(cb: () => void): () => void {
listeners.add(cb);
return () => {
listeners.delete(cb);
};
}
function getVersion(): number {
return version;
}
const removeStorageListener = (() => {
if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return null;
/** 本 owner 分区的内存态跟外来写入对齐(重读真相,不采信 event.newValue)。 */
const refreshActive = (): void => {
// 迟到的事件带旧值,直接写进内存会把本窗口刚保存的 override 回滚(newMakerDraft 同款 rebase)。
const next = loadFromStorage();
if (sameMap(cache ?? {}, next)) return;
cache = next;
emit();
};
const onStorage = (event: StorageEvent): void => {
if (event.storageArea && event.storageArea !== window.localStorage) return;
// key === null 表示 storage.clear():本分区刷新,并让**所有**还有 op-log 的分区各自调和。
if (event.key === null) {
refreshActive();
for (const key of reconciler.loggedKeys()) reconciler.schedule(key);
return;
}
if (event.key === storageKey()) {
refreshActive();
// 外来写入可能正是「别窗用旧基底做的迟到覆盖」,抹掉了本窗刚提交的 op(K2):
// 在锁内把本分区的整条 op-log 重新断言一遍,无差异即终止。
reconciler.schedule(event.key);
return;
}
// 非 active 分区:只要 op-log 里还有它的记录就照样调和(K1),但不动本窗口的内存态。
if (reconciler.hasOps(event.key)) reconciler.schedule(event.key);
};
window.addEventListener('storage', onStorage);
return () => window.removeEventListener('storage', onStorage);
})();
if (import.meta.hot) {
import.meta.hot.dispose(() => {
removeStorageListener?.();
});
}
/**
* 读某 (来源, 模型) 的引擎 override。
* `undefined` = **没有 override ⇒ 跟随推荐引擎**(调用方去查推荐映射),不是「无引擎」。
*/
export function getModelEngineOverride(
providerId: string,
modelId: string,
): ModelEngine | undefined {
if (!isUsableProviderId(providerId) || !modelId) return undefined;
return load()[keyOf(providerId, modelId)]?.agent;
}
/**
* 写某 (来源, 模型) 的引擎 override(用户在配置浮层显式点了引擎胶囊)。
* 同值短路;非法入参(空 id / 保留的 `'*'` 来源 / 未知引擎)静默忽略,不落脏数据。
*
* 注意:即便 agent 恰好等于当前推荐引擎,这里也照写 —— 「用户显式点过」本身是要记住的
* 状态(推荐将来变了,他的显式选择不该被顶掉)。调用方若想表达「恢复跟随推荐」,必须调
* clearModelEngineOverride。
*/
export function setModelEngineOverride(
providerId: string,
modelId: string,
agent: ModelEngine,
): void {
if (!isUsableProviderId(providerId) || !modelId || !isSelectableVendor(agent)) return;
// 基底取**重读后的**持久化快照(见 freshMap):整表写回不能带着陈旧缓存,否则会抹掉
// 另一个窗口刚写入、事件还没到达的 override。跨 renderer 的**并发**交错另由 commitOp
// 的锁内重放收敛(见文件头「并发写」)。
commitOp({ kind: 'set', key: keyOf(providerId, modelId), agent });
}
/**
* 恢复推荐 = **删除该 override**(configuration-and-overrides §4),不是写一份推荐值快照。
* 删完这个模型就重新跟随当前版本的推荐映射。无记录时短路,不做无意义落盘 / 通知。
*/
export function clearModelEngineOverride(providerId: string, modelId: string): void {
if (!isUsableProviderId(providerId) || !modelId) return;
commitOp({ kind: 'clear', key: keyOf(providerId, modelId) });
}
/** 该 (来源, 模型) 是否被用户自定义过 —— 行内三元组提亮 / 底栏「已自定义 · 恢复推荐」用。 */
export function hasModelEngineOverride(providerId: string, modelId: string): boolean {
return getModelEngineOverride(providerId, modelId) !== undefined;
}
/** 当前账号是否存在任一显式 Harness 选择;用于旧草稿迁移时保护用户意图。 */
export function hasAnyModelEngineOverride(): boolean {
return Object.keys(load()).length > 0;
}
/** 订阅引擎 override 变更(非 React 调用方)。 */
export function subscribeModelEnginePrefs(listener: () => void): () => void {
return subscribe(listener);
}
/**
* useSyncExternalStore 包装 —— 返回递增 version。组件把它当 useMemo 依赖,
* override 变更(含其它窗口写入触发的 storage 事件)后自动重算。
*/
export function useModelEnginePrefsVersion(): number {
return useSyncExternalStore(subscribe, getVersion, getVersion);
}
/**
* 随当前数据归属账号切换持久化命名空间(与 setNewMakerDraftOwner 同形)。
* 切换后丢缓存重新惰性加载 —— 不同账号各读各的分区,不串号。
*/
export function setModelEnginePrefsOwner(ownerId: string | null): void {
const normalized = typeof ownerId === 'string' && ownerId.trim().length > 0 ? ownerId : null;
if (activeDataOwnerId === normalized) return;
activeDataOwnerId = normalized;
cache = null;
emit();
}
/** 测试用 —— 重置缓存 / owner / 订阅者 / op-log + 清 localStorage(其它代码不应调用)。 */
export function __resetForTest(): void {
const keyBeforeReset = storageKey();
cache = null;
version = 0;
listeners.clear();
reconciler.__resetForTest();
if (typeof window !== 'undefined') {
try {
window.localStorage.removeItem(keyBeforeReset);
window.localStorage.removeItem(STORAGE_KEY);
} catch {
// ignore
}
}
activeDataOwnerId = null;
}
export const __STORAGE_KEY = STORAGE_KEY;