Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* deviceProvidersCache —— 被控端供应商目录的 deviceId-aware 缓存核心(**纯逻辑,零 react-native**)。
*
* 刻意不 import react-native / hook,便于 node 环境单测直接验证缓存语义(对齐 tokens.ts /
* monoFont.ts 的拆分约定)。React hook 在 `./useDeviceProviders.ts` 里消费本模块。
*
* 语义对齐桌面 `useDeviceProviders`:按 deviceId 隔离 + inflight 去重 + 代际驱逐
* (evict 时自增代际,作废在途 fetch 的回写,防设备切换 / 重连后串旧供应商)。
*/
import type { ProviderView } from '@cindy/model-providers/registry';
/** PROVIDER_LIST 隧道回包:目录 + 被控端「模型显示/隐藏」override 快照(旧被控端无)。 */
export interface DeviceProvidersPayload {
providers: ProviderView[];
/** Host-owned display order; absent on older hosts. */
providerOrder?: string[];
/** key = `${agent}:${providerId}:${modelId}`;undefined = 旧被控端,调用方不过滤。 */
modelVisibilityOverrides?: Record<string, boolean>;
}
/** 被控端供应商目录的取数器(通常 = `() => transport.listProviders()`)。 */
export type DeviceProvidersFetcher = () => Promise<DeviceProvidersPayload>;
/** Recognize both transport codes and the host's serialized IPC error prefix. */
function providerErrorCode(error: unknown): string | undefined {
const code = error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
if (typeof code === 'string' && code !== 'IPC_ERROR') return code;
const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
return /^(?:Error invoking remote method '[^']+': Error: )?\[([A-Z0-9_]+)\]/.exec(message)?.[1];
}
/** Short retries and mounted-picker recovery must recognize the same IPC forms. */
export function isDeviceProvidersVisibilityNotReadyError(error: unknown): boolean {
return providerErrorCode(error) === 'MODEL_VISIBILITY_NOT_READY';
}
/** Only an explicitly unsupported channel permits the legacy capabilities fallback. */
export function isDeviceProvidersUnsupportedError(error: unknown): boolean {
const code = providerErrorCode(error);
return code === 'CHANNEL_NOT_ALLOWED' || code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED';
}
/**
* Apply the host-owned display order (Desktop semantics): explicitly ordered ids first,
* new ids append in catalog order. Payloads without an order are returned unchanged.
*/
export function orderDeviceProviders(payload: DeviceProvidersPayload): DeviceProvidersPayload {
if (!Array.isArray(payload.providerOrder)) return payload;
const byId = new Map(payload.providers.map(provider => [provider.id, provider]));
const providers: ProviderView[] = [];
const seen = new Set<string>();
for (const id of payload.providerOrder) {
const provider = byId.get(id);
if (!provider || seen.has(id)) continue;
seen.add(id);
providers.push(provider);
}
for (const provider of payload.providers) {
if (seen.has(provider.id)) continue;
seen.add(provider.id);
providers.push(provider);
}
return { ...payload, providers };
}
async function requestDeviceProviders(
fetcher: DeviceProvidersFetcher,
isCurrent: () => boolean,
): Promise<DeviceProvidersPayload> {
for (let attempt = 0; ; attempt++) {
try {
return orderDeviceProviders(await fetcher());
} catch (error) {
if (!isDeviceProvidersVisibilityNotReadyError(error) || attempt >= 2 || !isCurrent()) throw error;
await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
if (!isCurrent()) throw error;
}
}
}
// 缓存按被控设备隔离;代际同桌面(evict 时自增,作废在途 fetch 的回写)。
const cache = new Map<string, DeviceProvidersPayload>();
const inflight = new Map<string, Promise<DeviceProvidersPayload>>();
const readGeneration = new WeakMap<Promise<DeviceProvidersPayload>, number>();
const deviceGen = new Map<string, number>();
const listeners = new Map<string, Set<(payload: DeviceProvidersPayload) => void>>();
const errorListeners = new Map<string, Set<(error: unknown) => void>>();
/** Fresh reads also report failure to mounted pickers without reviving stale catalogs. */
export function subscribeDeviceProvidersError(deviceId: string, listener: (error: unknown) => void): () => void {
const bucket = errorListeners.get(deviceId) ?? new Set<(error: unknown) => void>();
bucket.add(listener);
errorListeners.set(deviceId, bucket);
return () => {
bucket.delete(listener);
if (bucket.size === 0) errorListeners.delete(deviceId);
};
}
function notifyDeviceProvidersError(deviceId: string, error: unknown): void {
// A downgraded host cannot serve any of the cached provider routes. Retire only
// that device's snapshot; an empty success notification would incorrectly mark it ready.
if (isDeviceProvidersUnsupportedError(error)) cache.delete(deviceId);
for (const listener of errorListeners.get(deviceId) ?? []) listener(error);
}
// 各设备缓存写入时的连接代际(模块级,组件卸载不丢):hook 用它对「重连时未挂载 /
// 正看其它设备」的旧缓存做重连判定(codex review P1)——组件本地 ref 会随卸载
// 丢失,旧设备再打开会被当首次挂载、采信断线前缓存。
const deviceFetchEpoch = new Map<string, number>();
/** hook 在缓存命中 / 拉取完成后标记该设备缓存所属的连接代际。 */
export function markDeviceFetchEpoch(deviceId: string, epoch: number): void {
deviceFetchEpoch.set(deviceId, epoch);
}
/** 读该设备缓存写入时的连接代际;无记录 = 该设备从未标记(首次挂载语义)。 */
export function getDeviceFetchEpoch(deviceId: string): number | undefined {
return deviceFetchEpoch.get(deviceId);
}
function notifyDeviceProviders(deviceId: string, payload: DeviceProvidersPayload): void {
for (const listener of listeners.get(deviceId) ?? []) listener(payload);
}
/** 订阅某设备缓存的新快照;provider revision push 刷新后通知已挂载 hook。 */
export function subscribeDeviceProviders(
deviceId: string,
listener: (payload: DeviceProvidersPayload) => void,
): () => void {
const bucket = listeners.get(deviceId) ?? new Set<(payload: DeviceProvidersPayload) => void>();
bucket.add(listener);
listeners.set(deviceId, bucket);
return () => {
bucket.delete(listener);
if (bucket.size === 0) listeners.delete(deviceId);
};
}
/** 读缓存命中(同步),供 hook 初始化 state 用。 */
export function getCachedDeviceProviders(deviceId: string): DeviceProvidersPayload | undefined {
return cache.get(deviceId);
}
/**
* 取某被控设备的供应商目录(带缓存 + inflight 去重 + 代际作废)。纯逻辑、可单测。
* fetcher 注入,便于按 deviceId 绑定 transport,也便于测试。
*/
export async function fetchDeviceProviders(
deviceId: string,
fetcher: DeviceProvidersFetcher,
): Promise<DeviceProvidersPayload> {
const cached = cache.get(deviceId);
if (cached) return cached;
// 重连期间 fresh 在途时 join fresh(greptile P1:重连请求覆盖 fresh 目录)——
// connectionEpoch 变化会让 useDeviceProviders 重跑 effect 发起普通请求;该请求
// 捕获与 fresh 相同的代际,晚于 fresh 返回仍通过 isCurrent() 覆盖共享缓存。
// fresh 结果即工作站最新真相,普通读取 join 它语义正确且不会产生竞争请求。
const fp = freshInflight.get(deviceId);
if (fp) return joinProviderRead(deviceId, fp, () => fetchDeviceProviders(deviceId, fetcher));
const ip = inflight.get(deviceId);
if (ip) return joinProviderRead(deviceId, ip, () => fetchDeviceProviders(deviceId, fetcher));
// 捕获发起时代际;回调里若代际已变(被 evict)则认为本次请求作废,不回写 cache / 不动 inflight。
const startGen = deviceGen.get(deviceId) ?? 0;
const isCurrent = (): boolean => (deviceGen.get(deviceId) ?? 0) === startGen;
const p = requestDeviceProviders(fetcher, isCurrent)
.then((res) => {
const payload: DeviceProvidersPayload = {
providers: res?.providers ?? [],
...(res?.modelVisibilityOverrides !== undefined
? { modelVisibilityOverrides: res.modelVisibilityOverrides }
: {}),
};
if (isCurrent()) {
cache.set(deviceId, payload);
inflight.delete(deviceId);
notifyDeviceProviders(deviceId, payload);
}
return payload;
})
.catch((e) => {
if (isCurrent()) {
inflight.delete(deviceId);
notifyDeviceProvidersError(deviceId, e);
}
throw e;
});
inflight.set(deviceId, p);
readGeneration.set(p, startGen);
void p.finally(() => {
if (inflight.get(deviceId) === p) inflight.delete(deviceId);
}).catch(() => undefined);
return p;
}
/** A revision retires the result, not the physical request. New readers wait for
* it to settle, then share one current-generation read instead of flooding the link. */
function joinProviderRead(
deviceId: string,
pending: Promise<DeviceProvidersPayload>,
next: () => Promise<DeviceProvidersPayload>,
): Promise<DeviceProvidersPayload> {
const generation = getDeviceProvidersGen(deviceId);
if (readGeneration.get(pending) === generation) return pending;
return pending.catch(() => undefined).then(() => {
if (getDeviceProvidersGen(deviceId) !== generation) throw new Error('Provider read superseded');
return next();
});
}
/** Catalog push refresh owns the replacement read; mounted hooks only retire
* readiness. Keep in-flight slots so a burst cannot start overlapping reads. */
export function invalidateDeviceProvidersForRefresh(deviceId: string): void {
cache.delete(deviceId);
deviceGen.set(deviceId, getDeviceProvidersGen(deviceId) + 1);
notifyDeviceProvidersGen(deviceId, 'fresh-invalidate');
}
/**
* 强制刷新取某被控设备的供应商目录(codex review P2):**跳过缓存命中短路**——
* 即使缓存仍存在也执行 fetcher 访问工作站,成功后回写缓存并推送 payload 订阅者。
* 用途:提交终检的 revalidate(缓存命中分支要拿到工作站当前真相,而不是旧目录),
* 与普通读取的 cache-first 语义区分。
* 不复用普通 fetch 的在途请求(greptile review P1):普通请求可能发起于工作站目录
* 变更之前、本地代际尚未递增——fresh 语义是「强制访问工作站拿当前真相」,join
* 旧请求会拿过期目录当已知目录。fresh 自身并发仍经独立 inflight 槽去重。
*/
const freshInflight = new Map<string, Promise<DeviceProvidersPayload>>();
export async function fetchDeviceProvidersFresh(
deviceId: string,
fetcher: DeviceProvidersFetcher,
): Promise<DeviceProvidersPayload> {
const fp = freshInflight.get(deviceId);
// After an obsolete read settles, all waiters share the replacement started
// after this call. Re-entering fresh would invalidate a sibling waiter's new
// read and send a duplicate; independent fresh calls still bypass cache below.
if (fp) return joinProviderRead(deviceId, fp, () => fetchDeviceProviders(deviceId, fetcher));
// fresh 语义 = 强制访问工作站拿当前真相。仅当确有普通请求在途时才作废它
// (greptile/copilot/codex review P1/P2):旧普通请求若在 fresh 之后返回,仍会
// 通过 isCurrent() 回写旧目录覆盖 fresh 结果——代际 +1 使更早请求失效并清掉
// 普通 inflight 槽。**无普通在途时不得推进代际**(codex review P2):守卫
// resolveSubmitGuardCatalog 在 fetch 前记录 genAt,fresh 自推进会让守卫误判
// 为外部驱逐而丢弃结果;仅在确有在途时推进,守卫下一轮重跑(普通在途已清)
// 即收敛,gen 保持稳定时 fetch 前后一致直接采信。
const ip = inflight.get(deviceId);
if (ip && readGeneration.get(ip) !== getDeviceProvidersGen(deviceId)) {
return joinProviderRead(deviceId, ip, () => fetchDeviceProviders(deviceId, fetcher));
}
if (ip) {
inflight.delete(deviceId);
deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
// 内部作废(greptile/codex review P1/P2):hook 不得因此启动替代普通请求——
// fresh 自身会写缓存并经 payload 订阅恢复;若 hook 重拉普通请求会与 fresh
// 竞争(同代际、较晚返回仍通过 isCurrent() 把 fresh 结果覆盖回旧目录)。
notifyDeviceProvidersGen(deviceId, 'fresh-invalidate');
}
const startGen = deviceGen.get(deviceId) ?? 0;
const isCurrent = (): boolean => (deviceGen.get(deviceId) ?? 0) === startGen;
const p = requestDeviceProviders(fetcher, isCurrent)
.then((res) => {
const payload: DeviceProvidersPayload = {
providers: res?.providers ?? [],
...(res?.modelVisibilityOverrides !== undefined
? { modelVisibilityOverrides: res.modelVisibilityOverrides }
: {}),
};
if (isCurrent()) {
cache.set(deviceId, payload);
notifyDeviceProviders(deviceId, payload);
}
return payload;
})
.catch((error: unknown) => {
if (isCurrent()) notifyDeviceProvidersError(deviceId, error);
throw error;
});
freshInflight.set(deviceId, p);
readGeneration.set(p, startGen);
void p.finally(() => {
if (freshInflight.get(deviceId) === p) freshInflight.delete(deviceId);
}).catch(() => undefined);
return p;
}
/** device-link:被控设备切换 / 下线时驱逐其供应商缓存(只清该设备 + 代际自增作废在途)。 */
export function evictDeviceProviders(deviceId: string): void {
cache.delete(deviceId);
inflight.delete(deviceId);
freshInflight.delete(deviceId);
deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
notifyDeviceProvidersGen(deviceId, 'evict');
}
/**
* 读某设备当前的缓存代际(evict 一次 +1)。useDeviceProviders 的 ready 判定用:
* 置位 readyFor 时记录当时代际,之后代际不一致 = 目录已被驱逐、正在重拉(或重拉失败),
* ready 必须为 false —— 否则旧 payload 会在重拉窗口期继续被当作就绪目录(codex review P2)。
*/
export function getDeviceProvidersGen(deviceId: string): number {
return deviceGen.get(deviceId) ?? 0;
}
// ── 代际变更订阅 ────────────────────────────────────────────────────────────
// evict/clearAll 只改模块级 Map,不通知 payload 订阅者,React 不会重渲染 ——
// 单靠渲染期的代际比对,ready 的失效要等下一次碰巧渲染(codex review P2)。
// 这里给代际变化一条主动推送通道,hook 收到即立即使 ready 失效。
/**
* 代际失效原因(codex review P2):evict/clearAll 是**外部驱逐**——hook 应清空展示
* 并主动重拉;fetchDeviceProvidersFresh 作废普通在途是**内部作废**——fresh 自身会
* 写缓存并经 payload 订阅恢复,若 hook 再启动普通请求会与 fresh 竞争(普通请求
* 捕获同一代际、较晚返回仍通过 isCurrent() 把 fresh 结果覆盖回旧目录)。
*/
export type DeviceProvidersGenInvalidationReason = 'evict' | 'fresh-invalidate';
const genListeners = new Map<string, Set<(reason: DeviceProvidersGenInvalidationReason) => void>>();
/** 订阅某设备的缓存代际变更(evict/clearAll/fresh 作废时触发);返回退订函数。 */
export function subscribeDeviceProvidersGen(
deviceId: string,
listener: (reason: DeviceProvidersGenInvalidationReason) => void,
): () => void {
const bucket = genListeners.get(deviceId) ?? new Set<(reason: DeviceProvidersGenInvalidationReason) => void>();
bucket.add(listener);
genListeners.set(deviceId, bucket);
return () => {
bucket.delete(listener);
if (bucket.size === 0) genListeners.delete(deviceId);
};
}
function notifyDeviceProvidersGen(
deviceId: string,
reason: DeviceProvidersGenInvalidationReason,
): void {
for (const listener of genListeners.get(deviceId) ?? []) listener(reason);
}
/**
* 账号登出 / 进程内切号时清空**全部**被控设备的供应商缓存。
*
* 这是 module 级单例缓存,不随 React 组件卸载清空。若不在登出时清,下一个登录账号会通过
* `getCachedDeviceProviders` 命中上一个账号留下的被控端供应商目录(跨账号串数据)。除清
* cache / inflight 外,对每个已知 deviceId 自增代际,作废所有仍在途 fetch 的回写,防其在
* clear 之后又把旧数据写回。
*/
export function clearAllDeviceProviders(): void {
// fresh-only 在途设备也要纳入代际作废(greptile/copilot/codex review P1/P2):
// 只有 freshInflight 在途时(如提交终检触发的 fresh 拉取),登出后旧响应仍会
// 通过 isCurrent() 回写并广播,造成跨账号残留。
const ids = new Set<string>([
...cache.keys(),
...inflight.keys(),
...freshInflight.keys(),
...deviceGen.keys(),
]);
// 先清空三张 Map,再通知(codex review P2:清空缓存后再通知订阅者)——hook 的
// gen 订阅收到 'evict' 会立即 fetchDeviceProviders 重拉,若通知发生在清空之前,
// 重拉只会命中旧账号缓存或加入旧请求,随后 Map 被清掉,既没真正访问新账号,
// 也没有 payload 通知恢复 hook,目录长期停在 ready=false。
cache.clear();
inflight.clear();
freshInflight.clear();
for (const id of ids) {
deviceGen.set(id, (deviceGen.get(id) ?? 0) + 1);
notifyDeviceProvidersGen(id, 'evict');
// 注意:不再推送空 payload(codex review P2:清空账号缓存时不要把空载荷标为
// 就绪)——payload 订阅回调把任何 payload 视为已确认快照,会重新置位
// readyFor/readyGen,最终暴露为 ready:true 的 loaded-empty 目录;且
// [deviceId, maker] effect 不因重新登录重跑,新账号目录永不重拉。清空展示
// 与未就绪由 hook 的 gen 失效订阅承担(清 payload + 保持未就绪 + 主动重拉),
// 见 useDeviceProviders。登出后短窗口残留由该订阅的清空兜底(copilot P2 意图)。
}
}