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。

17.4 KB
Raw Blame
/**
 * useDeviceProviders — 拉取**被控端**(device-link)的模型供应商目录。
 *
 * 本机供应商走 `useProviders()`;远程会话(deviceId 非空)必须列**被控端**的供应商结构
 * (隧道 `maker:provider:list`,被控端 dispatch 已剥离 routing 等执行字段,仅回显示用字段)。
 *
 * 缓存按 deviceId 隔离 + 代际驱逐 —— 与 `useAgentCapabilities` 的 device-scoping 同范式:
 * 两台机器供应商配置可能不同,绝不能串;设备下线 / 断链后在途 fetch 的 `.then` 不得把陈旧
 * 供应商复活回缓存。deviceId 省略 = 不拉取(调用方改用本机 `useProviders`)。
 *
 * 优雅回退:被控端为旧版(allowlist 无 `maker:provider:list`)→ invoke reject → 暴露 error,
 * 调用方(ModelSelector)回退到基于 capabilities 的扁平列表(`selectVisibleModels`)。
 */
import { useEffect, useState } from 'react';

import { CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2 } from '@cindy/device-link';
import type { ProviderView } from '@cindy/model-providers';
import { defaultEffortForCapabilities } from '@cindy/model-providers';
import { isTransientRemoteError, isDeviceUnresponsiveRemoteError } from '@cindy/maker-shared/device-link-contract';
import { getDataOwnerGeneration, isDataOwnerGenerationCurrent } from '@/contexts/dataOwnerGeneration';

import { createLogger } from '@/lib/logger';
import { extractIpcError } from '@/utils/ipcError';

const log = createLogger('useDeviceProviders');

interface DeviceLinkShape {
  invoke: (deviceId: string, channel: string, args: unknown[]) => Promise<unknown>;
}

function getDeviceLink(): DeviceLinkShape | null {
  const dl = (
    window as unknown as {
      electronAPI?: { deviceLink?: DeviceLinkShape };
    }
  ).electronAPI?.deviceLink;
  return dl ?? null;
}

// 缓存按被控设备隔离;代际同 useAgentCapabilities(evict 时自增,作废在途 fetch 的回写)。
export interface DeviceProvidersPayload {
  providers: ProviderView[];
  /** 被控端「模型显示/隐藏」override 快照;undefined = 旧被控端,不过滤。 */
  modelVisibilityOverrides?: Record<string, boolean>;
}

const EMPTY_PAYLOAD: DeviceProvidersPayload = { providers: [] };
const cache = new Map<string, DeviceProvidersPayload>();
// Retained across a policy refresh failure; discarded on disconnect/owner
// eviction. Otherwise a failed refresh loses the identity needed to retry it.
const subscriptionFetchedAt = new Map<string, number>();
const inflight = new Map<string, Promise<DeviceProvidersPayload>>();
const deviceGen = new Map<string, number>();
export type DeviceProvidersEvent =
  | { status: 'loading'; retainDisplaySnapshot?: boolean }
  | ({ status: 'ready' } & DeviceProvidersPayload)
  | { status: 'error'; error: string; unsupported: boolean };
const listeners = new Map<string, Set<(event: DeviceProvidersEvent) => void>>();

function isRecord(value: unknown): value is Record<string, unknown> {
  return !!value && typeof value === 'object' && !Array.isArray(value);
}

function isOptionalBoolean(value: unknown): boolean {
  return value === undefined || typeof value === 'boolean';
}

function isProviderWireProtocol(value: unknown): boolean {
  return (
    value === undefined ||
    value === 'anthropic-messages' ||
    value === 'openai-responses' ||
    value === 'openai-chat' ||
    value === 'google-generative-ai'
  );
}

function isProviderModel(value: unknown): boolean {
  if (!isRecord(value)) return false;
  const efforts = value.efforts;
  const defaultEffort = value.defaultEffort;
  return (
    typeof value.id === 'string' &&
    value.id.length > 0 &&
    typeof value.name === 'string' &&
    typeof value.contextWindow === 'number' &&
    Number.isFinite(value.contextWindow) &&
    value.contextWindow > 0 &&
    Array.isArray(efforts) &&
    efforts.every((effort) => typeof effort === 'string') &&
    (defaultEffort === undefined || defaultEffort === null ||
      (typeof defaultEffort === 'string' && efforts.includes(defaultEffort))) &&
    isOptionalBoolean(value.disabled) &&
    isOptionalBoolean(value.supportsFastMode) &&
    isOptionalBoolean(value.defaultEnabled)
  );
}

function isProviderRoute(value: unknown): boolean {
  return (
    isRecord(value) &&
    isOptionalBoolean(value.disabled) &&
    isProviderWireProtocol(value.wireProtocol)
  );
}

function sanitizeProviderModels(
  models: unknown,
): Record<string, unknown[]> | null {
  if (!isRecord(models)) return null;
  const sanitized: Record<string, unknown[]> = {};
  for (const [agent, entries] of Object.entries(models)) {
    if (!Array.isArray(entries)) return null;
    sanitized[agent] = entries.filter(isProviderModel).map((entry: Record<string, unknown>) =>
      entry.defaultEffort === undefined
        ? { ...entry, defaultEffort: defaultEffortForCapabilities(entry.efforts as string[]) }
        : entry,
    );
  }
  return sanitized;
}

function isProviderView(value: unknown): value is ProviderView {
  if (!isRecord(value)) return false;
  const routing = value.routing;
  const models = sanitizeProviderModels(value.models);
  if (!models) return false;
  value.models = models;
  return (
    typeof value.id === 'string' &&
    value.id.length > 0 &&
    typeof value.name === 'string' &&
    Array.isArray(value.agents) &&
    value.agents.every((agent) => typeof agent === 'string') &&
    (routing === undefined ||
      (isRecord(routing) && Object.values(routing).every(isProviderRoute))) &&
    typeof value.connected === 'boolean' &&
    isOptionalBoolean(value.suspended)
  );
}

export function parseDeviceProvidersPayload(value: unknown): DeviceProvidersPayload {
  if (!isRecord(value)) {
    throw new Error('Invalid provider list response');
  }
  if (!Array.isArray(value.providers)) {
    throw new Error('Invalid provider list response');
  }
  const rawProviders = value.providers;
  const providersIn = rawProviders.filter(isProviderView);
  if (providersIn.length === 0 && rawProviders.length > 0) {
    throw new Error('Invalid provider list response');
  }
  const overrides = value.modelVisibilityOverrides;
  if (
    overrides !== undefined &&
    (!isRecord(overrides) ||
      Object.values(overrides).some((visible) => typeof visible !== 'boolean'))
  ) {
    throw new Error('Invalid provider visibility response');
  }
  // device-link 的 provider:list 是只读展示投影;旧/部分被控端可能省略 routing,
  // 但 model-providers 的 connectedProvidersForAgent 需要每个声明的 agent 有一个
  // routing entry 才会把供应商视为可用。只在远程解析边界补齐空 entry,不改变本机
  // registry 对缺失 route 的严格语义,也保留已有 disabled 标记。
  const providers = providersIn.map((provider) => {
    const routing = { ...(provider.routing ?? {}) } as ProviderView['routing'];
    for (const agent of provider.agents) {
      if (routing[agent as keyof ProviderView['routing']] === undefined) {
        Object.assign(routing, { [agent]: {} });
      }
    }
    return { ...provider, routing };
  });
  return {
    providers,
    ...(overrides !== undefined
      ? { modelVisibilityOverrides: overrides as Record<string, boolean> }
      : {}),
  };
}

/** 旧被控端没有 provider:list 时允许退化到 capabilities flat 列表;其它错误都是真失败。 */
export function isDeviceProvidersUnsupportedError(error: unknown): boolean {
  return extractIpcError(error)?.code === 'DEVICE_LINK_CHANNEL_NOT_ALLOWED';
}

function notifyDeviceProviders(deviceId: string, event: DeviceProvidersEvent): void {
  for (const listener of listeners.get(deviceId) ?? []) listener(event);
}

/** 订阅某设备缓存的新快照;live provider push 后已挂载 hook 也能无空白帧地更新。 */
export function subscribeDeviceProviders(
  deviceId: string,
  listener: (event: DeviceProvidersEvent) => void,
): () => void {
  const bucket = listeners.get(deviceId) ?? new Set<(event: DeviceProvidersEvent) => void>();
  bucket.add(listener);
  listeners.set(deviceId, bucket);
  return () => {
    bucket.delete(listener);
    if (bucket.size === 0) listeners.delete(deviceId);
  };
}

async function fetchDeviceProviders(deviceId: string): Promise<DeviceProvidersPayload> {
  const cached = cache.get(deviceId);
  if (cached) return cached;
  const ip = inflight.get(deviceId);
  if (ip) return ip;

  // 捕获发起时代际;回调里若代际已变(被 evict)则认为本次请求作废,不回写 cache / 不动 inflight。
  const startGen = deviceGen.get(deviceId) ?? 0;
  const isCurrent = (): boolean => (deviceGen.get(deviceId) ?? 0) === startGen;

  const dl = getDeviceLink();
  if (!dl) throw new Error('device-link IPC not available');
  const request = async (): Promise<DeviceProvidersPayload> => {
    for (let attempt = 0; ; attempt++) {
      try {
        return await dl.invoke(deviceId, 'maker:provider:list', [
          { capabilities: [CONTROLLER_CAPABILITY_PROVIDER_LOGO_KINDS_V2] },
        ]) as DeviceProvidersPayload;
      } catch (error) {
        if (extractIpcError(error)?.code !== 'MODEL_VISIBILITY_NOT_READY' || attempt >= 2 || !isCurrent()) throw error;
        await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
        if (!isCurrent()) throw error;
      }
    }
  };
  const p = request()
    .then((res) => {
      const payload = parseDeviceProvidersPayload(res);
      if (isCurrent()) {
        cache.set(deviceId, payload);
        if (deviceId.startsWith('share:') && payload.providers.some(provider => !!provider.subscriptionFastPolicy))
          subscriptionFetchedAt.set(deviceId, Date.now());
        else subscriptionFetchedAt.delete(deviceId);
        inflight.delete(deviceId);
        notifyDeviceProviders(deviceId, { status: 'ready', ...payload });
      }
      return payload;
    })
    .catch((e) => {
      if (isCurrent()) {
        inflight.delete(deviceId);
        notifyDeviceProviders(deviceId, {
          status: 'error',
          error: e instanceof Error ? e.message : String(e),
          unsupported: isDeviceProvidersUnsupportedError(e),
        });
      }
      throw e;
    });
  inflight.set(deviceId, p);
  return p;
}

export interface UseDeviceProvidersResult {
  providers: ProviderView[];
  /** 被控端「模型显示/隐藏」override 快照;undefined = 旧被控端,不过滤。 */
  modelVisibilityOverrides?: Record<string, boolean>;
  loading: boolean;
  /** 非 null = 拉取失败(典型:旧版被控端不识别通道);调用方据此回退扁平列表。 */
  error: string | null;
  /** true 仅表示老被控端没有 provider:list,可安全回退 capabilities-only 列表。 */
  unsupported: boolean;
}

export function useDeviceProviders(deviceId?: string): UseDeviceProvidersResult {
  const initialPayload = deviceId ? cache.get(deviceId) : undefined;
  const [ownerDeviceId, setOwnerDeviceId] = useState<string | null>(
    initialPayload ? (deviceId ?? null) : null,
  );
  const [payload, setPayload] = useState<DeviceProvidersPayload>(initialPayload ?? EMPTY_PAYLOAD);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [unsupported, setUnsupported] = useState(false);

  useEffect(() => {
    if (!deviceId) {
      setOwnerDeviceId(null);
      setPayload(EMPTY_PAYLOAD);
      setLoading(false);
      setError(null);
      setUnsupported(false);
      return;
    }
    let cancelled = false;
    let retryOwner = getDataOwnerGeneration();
    let retryGeneration: number | undefined;
    const retryCurrent = () => !cancelled && isDataOwnerGenerationCurrent(retryOwner)
      && retryGeneration !== undefined && retryGeneration === (deviceGen.get(deviceId) ?? 0);
    // Recover on foreground entry only. Periodic per-hook retries would bypass
    // shared peer recovery scheduling and multiply across renderer windows.
    // Reconnect and provider-change refreshes retain their existing owners.
    const onVisibility = () => {
      if (document.visibilityState === 'visible' && retryCurrent()) {
        void fetchDeviceProviders(deviceId).catch(() => undefined);
      }
    };
    document.addEventListener('visibilitychange', onVisibility);
    const unsubscribe = subscribeDeviceProviders(deviceId, (event) => {
      if (cancelled) return;
      if (event.status === 'loading') {
        retryGeneration = undefined;
        // 配置刷新可保留显示快照;断链或账号切换必须立即清掉旧目录。
        if (!event.retainDisplaySnapshot) setPayload(EMPTY_PAYLOAD);
        setOwnerDeviceId(deviceId);
        setLoading(true);
        setError(null);
        setUnsupported(false);
        return;
      }
      if (event.status === 'error') {
        retryOwner = getDataOwnerGeneration();
        retryGeneration = !event.unsupported && (
          isTransientRemoteError(event.error) || isDeviceUnresponsiveRemoteError(event.error)
          || extractIpcError(new Error(event.error))?.code === 'MODEL_VISIBILITY_NOT_READY'
        ) ? (deviceGen.get(deviceId) ?? 0) : undefined;
        setOwnerDeviceId(deviceId);
        if (event.unsupported) setPayload(EMPTY_PAYLOAD);
        setLoading(false);
        setError(event.error);
        setUnsupported(event.unsupported);
        return;
      }
      retryGeneration = undefined;
      setOwnerDeviceId(deviceId);
      setPayload({
        providers: event.providers,
        ...(event.modelVisibilityOverrides !== undefined
          ? { modelVisibilityOverrides: event.modelVisibilityOverrides }
          : {}),
      });
      setError(null);
      setUnsupported(false);
      setLoading(false);
    });
    const cleanup = () => {
      cancelled = true;
      document.removeEventListener('visibilitychange', onVisibility);
      unsubscribe();
    };
    const cached = cache.get(deviceId);
    if (cached) {
      setOwnerDeviceId(deviceId);
      setPayload(cached);
      setError(null);
      setUnsupported(false);
      setLoading(false);
      return cleanup;
    }
    // cache miss:先清空,避免 fetch 解析前(失败则永远)残留上一设备的供应商。
    setOwnerDeviceId(deviceId);
    setPayload(EMPTY_PAYLOAD);
    setLoading(true);
    setError(null);
    setUnsupported(false);
    const remoteGeneration = deviceGen.get(deviceId) ?? 0;
    fetchDeviceProviders(deviceId)
      .catch((e: unknown) => {
        if (cancelled) return;
        if ((deviceGen.get(deviceId) ?? 0) !== remoteGeneration) return;
        const nextUnsupported = isDeviceProvidersUnsupportedError(e);
        if (nextUnsupported) setPayload(EMPTY_PAYLOAD);
        setError(e instanceof Error ? e.message : String(e));
        setUnsupported(nextUnsupported);
      })
      .finally(() => {
        if (cancelled || (deviceGen.get(deviceId) ?? 0) !== remoteGeneration) return;
        setLoading(false);
      });
    return cleanup;
  }, [deviceId]);

  const ownsSelectedDevice = ownerDeviceId === (deviceId ?? null);
  const selectedError = ownsSelectedDevice ? error : null;
  const selectedUnsupported = ownsSelectedDevice ? unsupported : false;
  const selectedPayload =
    ownsSelectedDevice && !(selectedError && selectedUnsupported) ? payload : EMPTY_PAYLOAD;

  return {
    providers: selectedPayload.providers,
    ...(selectedPayload.modelVisibilityOverrides !== undefined
      ? { modelVisibilityOverrides: selectedPayload.modelVisibilityOverrides }
      : {}),
    loading: !!deviceId && (!ownsSelectedDevice || loading),
    error: selectedError,
    unsupported: selectedUnsupported,
  };
}

/** device-link:订阅某被控设备时预取其供应商目录(与 prefetchDeviceCapabilities 并列调用)。 */
export async function prefetchDeviceProviders(deviceId: string): Promise<void> {
  try {
    await fetchDeviceProviders(deviceId);
  } catch (err) {
    // swallow:打开会话时 hook 会再取一次(旧版被控端不支持时回退扁平列表)。
    log.debug('prefetchDeviceProviders failed (non-fatal)', {
      deviceId,
      error: err instanceof Error ? err.message : String(err),
    });
  }
}

/** device-link:被控设备下线 / 断链时驱逐其供应商缓存(只清该设备的 key + 代际自增)。 */
export function getCachedDeviceProviders(deviceId: string): DeviceProvidersPayload | null {
  return cache.get(deviceId) ?? null;
}

/** Only subscription shares opt into freshness polling; custom API catalogs keep their existing lifetime. */
export function hasSubscriptionShareCatalog(deviceId: string): boolean {
  return subscriptionFetchedAt.has(deviceId);
}

export function isSubscriptionShareCatalogStale(deviceId: string, now = Date.now()): boolean {
  return hasSubscriptionShareCatalog(deviceId)
    && now - (subscriptionFetchedAt.get(deviceId) ?? 0) >= 60_000;
}

export function isDeviceProvidersGenerationCurrent(deviceId: string, generation: number): boolean {
  return (deviceGen.get(deviceId) ?? 0) === generation;
}

export function evictDeviceProviders(
  deviceId: string,
  options?: { retainDisplaySnapshot?: boolean },
): number {
  cache.delete(deviceId);
  if (!options?.retainDisplaySnapshot) subscriptionFetchedAt.delete(deviceId);
  inflight.delete(deviceId);
  deviceGen.set(deviceId, (deviceGen.get(deviceId) ?? 0) + 1);
  notifyDeviceProviders(deviceId, {
    status: 'loading',
    ...(options?.retainDisplaySnapshot ? { retainDisplaySnapshot: true } : {}),
  });
  return deviceGen.get(deviceId)!;
}

/** 账号边界:缓存、在途读取及挂载中的旧账号目录一起失效。 */
export function evictAllDeviceProviders(): void {
  const devices = new Set([...cache.keys(), ...inflight.keys(), ...listeners.keys(), ...deviceGen.keys()]);
  for (const deviceId of devices) evictDeviceProviders(deviceId);
}