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。

14.3 KB
Raw Blame
/**
 * useDeviceProviders(mobile)—— 拉取**被控端**(device-link)的模型供应商目录,用于
 * provider-aware 模型下拉(同一 model 可挂多家来源)。手机版始终是 device-link 控制端,
 * 故没有「本机供应商」分支:deviceId 非空就隧道 `maker:provider:list` 取被控端结构,
 * 被控端 dispatch 已剥离 routing 等执行字段、仅回显示用字段。
 *
 * 缓存 / 去重 / 代际驱逐核心在 `./deviceProvidersCache`(纯逻辑、node 可测);本文件只做
 * React 接线。优雅回退:被控端为旧版(allowlist 无 `maker:provider:list`)→ listProviders
 * reject → 暴露 unsupported,调用方才回退到基于 capabilities 的扁平模型列表。
 */
import { useEffect, useState } from 'react';
import { AppState } from 'react-native';

import type { ProviderView } from '@cindy/model-providers/registry';

import { connectionRecoverySyncRetryDelayMs, formatRemoteError, isAutoRecoveringRemoteError } from './remoteStatus';
import { useDeviceLink } from './DeviceLinkContext';
import {
  fetchDeviceProviders,
  fetchDeviceProvidersFresh,
  getCachedDeviceProviders,
  getDeviceFetchEpoch,
  getDeviceProvidersGen,
  markDeviceFetchEpoch,
  isDeviceProvidersUnsupportedError,
  isDeviceProvidersVisibilityNotReadyError,
  subscribeDeviceProviders,
  subscribeDeviceProvidersGen,
  subscribeDeviceProvidersError,
  type DeviceProvidersPayload,
} from './deviceProvidersCache';
import { useMobileMakerTransport } from './useMobileMakerTransport';

export { evictDeviceProviders } from './deviceProvidersCache';

export interface UseDeviceProvidersResult {
  providers: ProviderView[];
  /** 被控端「模型显示/隐藏」override 快照;undefined = 旧被控端(列表不过滤)。 */
  modelVisibilityOverrides?: Record<string, boolean>;
  loading: boolean;
  /** 非 null = 拉取失败(典型:旧版被控端不识别通道);仅 unsupported 允许回退扁平列表。 */
  error: string | null;
  /** Only true for a host that explicitly lacks provider:list. */
  unsupported: boolean;
  /**
   * 「当前目录确为所选设备的就绪目录」——仅当 payload 来自该设备的缓存命中或拉取完成
   * (经订阅回调确认)才为 true。`loading === false` 不能替代本信号:loading 初始值就是
   * false(挂载 effect 尚未开拉)、切设备瞬间还会短暂保留上一设备的 payload
   * (codex review P1)。消费方做「目录就绪后」的判定(如来源终检)必须用 ready。
   */
  ready: boolean;
}

const EMPTY_PAYLOAD: DeviceProvidersPayload = { providers: [] };

function canRecoverProviderRead(error: unknown): boolean {
  return isAutoRecoveringRemoteError(error)
    || isDeviceProvidersVisibilityNotReadyError(error);
}

/** 取被控设备的供应商目录;deviceId 省略 = 不拉取(返回空,调用方回退扁平列表)。 */
export function useDeviceProviders(deviceId?: string, pickerOpen = false): UseDeviceProvidersResult {
  // hooks 规则:无条件取 transport(deviceId 空时其 call 会 reject,但本 hook 不会在空时调用)。
  const maker = useMobileMakerTransport(deviceId ?? '');
  // 连接代际:重连/恢复时 +1。离线驱逐(evict)后重拉失败时,依赖 [deviceId, maker]
  // 的 effect 不会因连接恢复重跑(maker.invoke 跨重连稳定,codex review P2)——把
  // connectionEpoch 纳入 effect 依赖,连接恢复即重跑 effect、经 cache-miss 重新
  // 拉取,不再永久停在 ready=false 的空目录。
  const { connectionEpoch, status, recoveringDeviceIds } = useDeviceLink();
  const recovering = !!deviceId && recoveringDeviceIds.has(deviceId);
  const [payload, setPayload] = useState<DeviceProvidersPayload>(
    deviceId ? getCachedDeviceProviders(deviceId) ?? EMPTY_PAYLOAD : EMPTY_PAYLOAD,
  );
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [errorDeviceId, setErrorDeviceId] = useState<string | null>(null);
  const [catalogGeneration, setCatalogGeneration] = useState(() => deviceId ? getDeviceProvidersGen(deviceId) : 0);
  // ready 的判定载体:payload 已确认属于哪个设备 + 置位时的缓存代际。仅在缓存命中 /
  // 拉取完成(订阅回调)时置位;切设备 cache-miss 立即清 null。首渲染即按
  // `readyFor === deviceId` 计算,不依赖 effect 先跑,故无「loading 初值 false」窗口;
  // 代际比对兜住「同设备 evict 后重拉中/重拉失败」——旧 payload 在重拉窗口期不再
  // 被当作就绪目录(codex review P2)。
  const [readyFor, setReadyFor] = useState<string | null>(() => {
    if (!deviceId) return null;
    if (!getCachedDeviceProviders(deviceId)) return null;
    const cachedAtEpoch = getDeviceFetchEpoch(deviceId);
    // 缓存属旧连接代际(重连后 hook 重挂载)→ 首帧保持未就绪(codex review P2):
    // 否则消费者先看到一次 ready:true,外层 auto-default effect 可能按旧目录首行
    // 写草稿并设置 autoDefaultDeviceRef,fresh 目录到达后不再重新选默认项;由 effect
    // 判 reconnected 强制 fresh。无记录 = 该设备首次标记(缓存命中快路径语义)。
    if (cachedAtEpoch !== undefined && cachedAtEpoch !== connectionEpoch) return null;
    return deviceId;
  });
  const [readyGen, setReadyGen] = useState<number>(() =>
    deviceId ? getDeviceProvidersGen(deviceId) : 0,
  );
  // 各设备缓存写入时的连接代际存在模块级(deviceProvidersCache):重连(epoch
  // 变化)后缓存命中分支必须强制刷新(codex review P1)——relay 断线期间被控端
  // 可能已改供应商且无 provider push,缓存命中短路会让模型选择器无限期展示旧
  // 来源。模块级 Map 跨组件卸载存活:重连时 hook 未挂载 / 正查看其它设备,旧设备
  // 再打开仍能读到断线前代际 → reconnected → 强制 fresh(组件本地 ref 会随卸载
  // 丢失,把旧设备误判为首次挂载、采信断线前缓存,codex review P1)。无记录 =
  // 该设备首次标记(正常缓存命中快路径,与原 null 语义一致)。

  useEffect(() => {
    setCatalogGeneration(deviceId ? getDeviceProvidersGen(deviceId) : 0);
    if (!deviceId) {
      setPayload(EMPTY_PAYLOAD);
      setError(null);
      setLoading(false);
      setReadyFor(null);
      return;
    }
    let cancelled = false;
    const unsubscribeError = subscribeDeviceProvidersError(deviceId, (error) => {
      if (cancelled) return;
      if (isDeviceProvidersUnsupportedError(error)) setPayload(EMPTY_PAYLOAD);
      setReadyFor(null);
      setLoading(false);
      setError(formatRemoteError(error));
      setErrorDeviceId(deviceId);
    });
    const unsubscribe = subscribeDeviceProviders(deviceId, (next) => {
      if (cancelled) return;
      setPayload(next);
      setError(null);
      setLoading(false);
      setReadyFor(deviceId);
      setReadyGen(getDeviceProvidersGen(deviceId));
      // payload 被采纳(拉取成功)才更新该设备缓存所属连接代际(codex review P1):
      // 若在 refresh 前就 mark 新 epoch,刷新失败后同 epoch 重挂载会把断线前旧
      // 缓存判为「未重连」直接标记就绪,且永不重试;只在成功路径更新,失败保持
      // 旧代际 → 下次 effect 重跑仍判定 reconnected → 重试 fresh。
      markDeviceFetchEpoch(deviceId, connectionEpoch);
    });
    // 代际变更(evict/clearAll/fresh 作废)主动推送:模块级 Map 变化不触发渲染,
    // 光靠渲染期代际比对,ready 失效要等下一次碰巧渲染(codex review P2)——收到
    // 通知立即失效,重拉完成经上面的 payload 订阅恢复。
    // 区分失效原因(greptile/codex review P1/P2):
    // - 'evict'(evict/clearAll 外部驱逐/登出切号):必须**清空展示但保持未就绪**——
    //   否则 payload 残留旧账号 + readyFor 被误置,暴露为 ready:true 的 loaded-empty;
    //   且 [deviceId, maker] effect 不因重新登录重跑,需显式重拉新账号目录;
    // - 'fresh-invalidate'(fresh 内部作废普通在途):**不得**启动替代普通请求——
    //   fresh 自身会写缓存并经 payload 订阅恢复;hook 重拉会与 fresh 竞争,普通
    //   响应较晚返回仍通过 isCurrent() 把 fresh 的新目录覆盖回旧目录。
    const unsubscribeGen = subscribeDeviceProvidersGen(deviceId, (reason) => {
      if (cancelled) return;
      // Restart recovery even when React batches invalidation and an identical error.
      setCatalogGeneration(getDeviceProvidersGen(deviceId));
      setReadyFor(null);
      if (reason === 'fresh-invalidate') return;
      setPayload(EMPTY_PAYLOAD);
      setLoading(true);
      setError(null);
      const refreshGen = getDeviceProvidersGen(deviceId);
      const isCurrentRefresh = () => !cancelled && getDeviceProvidersGen(deviceId) === refreshGen;
      void fetchDeviceProviders(deviceId, () => maker.listProviders())
        .catch(() => undefined) // current-generation errors arrive through the cache subscription
        .finally(() => {
          if (isCurrentRefresh()) setLoading(false);
        });
    });
    const cached = getCachedDeviceProviders(deviceId);
    // 重连(connectionEpoch 变化)后缓存命中也要强制刷新(codex review P1):
    // relay 断线期间被控端可能已改供应商且无 provider push,直接短路会无限期
    // 展示旧来源。该设备无代际记录(首次标记)走正常缓存命中快路径。
    // 注:此处**不** mark 当前 epoch——mark 只发生在成功路径(payload 订阅回调 /
    // 缓存命中快路径),refresh 失败时保持旧代际,同 epoch 重挂载仍会重试 fresh。
    const prevEpoch = getDeviceFetchEpoch(deviceId);
    const reconnected = prevEpoch !== undefined && prevEpoch !== connectionEpoch;
    if (cached && !reconnected) {
      setPayload(cached);
      setError(null);
      // Reset loading on the cache-hit path too: if a prior device's fetch is still in flight
      // (loading=true) when we switch to a cached device, its cancelled `finally` won't clear it,
      // so the cache-hit return must, or the UI stays stuck "loading" over fully-populated data.
      setLoading(false);
      setReadyFor(deviceId);
      setReadyGen(getDeviceProvidersGen(deviceId));
      // 缓存命中快路径:当前缓存即当前 epoch 获取的,确认标记(不依赖订阅回调)。
      markDeviceFetchEpoch(deviceId, connectionEpoch);
      // 缓存命中分支也必须返回统一 cleanup(codex review P2):只退 payload 订阅会让
      // 代际订阅漏订存活——切走后旧设备的 evict 通知仍会 setReadyFor(null),误伤新设备。
      return () => {
        cancelled = true;
        unsubscribe();
        unsubscribeGen();
        unsubscribeError();
      };
    }
    if (cached && reconnected) {
      // 重连 + 缓存命中:旧目录先展示,但保持未就绪并强制 fresh 刷新拿工作站
      // 当前真相;成功经 payload 订阅恢复 ready(与 cache-miss 分支同恢复路径)。
      setPayload(cached);
      setLoading(true);
      setReadyFor(null);
      const requestGen = getDeviceProvidersGen(deviceId);
      fetchDeviceProvidersFresh(deviceId, () => maker.listProviders())
        .catch(() => undefined)
        .finally(() => {
          if (!cancelled && getDeviceProvidersGen(deviceId) === requestGen) setLoading(false);
        });
      return () => {
        cancelled = true;
        unsubscribe();
        unsubscribeGen();
        unsubscribeError();
      };
    }
    // cache miss:先清空,避免 fetch 解析前(失败则永远)残留上一设备的供应商。
    setPayload(EMPTY_PAYLOAD);
    setLoading(true);
    setError(null);
    setReadyFor(null);
    const requestGen = getDeviceProvidersGen(deviceId);
    fetchDeviceProviders(deviceId, () => maker.listProviders())
      .catch(() => undefined)
      .finally(() => {
        if (!cancelled && getDeviceProvidersGen(deviceId) === requestGen) setLoading(false);
      });
    return () => {
      cancelled = true;
      unsubscribe();
      unsubscribeGen();
      unsubscribeError();
    };
  }, [connectionEpoch, deviceId, maker]);

  // A peer link can recover without a new relay epoch. Retry only this failed
  // catalog read; never reset the transport or turn cached rows into ready data.
  const needsRecovery = errorDeviceId === deviceId && error !== null && canRecoverProviderRead(error);
  useEffect(() => {
    if (!deviceId || !needsRecovery || status !== 'online' || recovering) return;
    let cancelled = false;
    let inFlight = false;
    let attempt = 0;
    let timer: ReturnType<typeof setTimeout> | undefined;
    let generation = getDeviceProvidersGen(deviceId);
    const current = () => !cancelled && generation === getDeviceProvidersGen(deviceId);
    const schedule = (delay: number) => {
      clearTimeout(timer);
      if (!current() || inFlight || AppState.currentState !== 'active') return;
      timer = setTimeout(() => { void retry(); }, delay);
    };
    const retry = async () => {
      if (!current() || inFlight || AppState.currentState !== 'active') return;
      inFlight = true;
      // Fresh bypasses a retained pre-failure cache and shares its in-flight read
      // with other consumers. Existing generation guards reject late responses.
      const request = fetchDeviceProvidersFresh(deviceId, () => maker.listProviders());
      generation = getDeviceProvidersGen(deviceId);
      try {
        await request;
      } catch (failure) {
        inFlight = false;
        if (canRecoverProviderRead(failure)) schedule(connectionRecoverySyncRetryDelayMs(attempt++));
      } finally {
        inFlight = false;
      }
    };
    const subscription = AppState.addEventListener('change', (next) => {
      clearTimeout(timer);
      if (next === 'active') schedule(0);
    });
    schedule(pickerOpen ? 0 : connectionRecoverySyncRetryDelayMs(attempt++));
    return () => {
      cancelled = true;
      clearTimeout(timer);
      subscription.remove();
    };
  }, [catalogGeneration, connectionEpoch, deviceId, needsRecovery, maker, pickerOpen, recovering, status]);

  return {
    providers: payload.providers,
    ...(payload.modelVisibilityOverrides !== undefined
      ? { modelVisibilityOverrides: payload.modelVisibilityOverrides }
      : {}),
    loading,
    error: errorDeviceId === deviceId ? error : null,
    unsupported: errorDeviceId === deviceId && isDeviceProvidersUnsupportedError(error),
    ready: deviceId !== undefined
      && readyFor === deviceId
      && readyGen === getDeviceProvidersGen(deviceId),
  };
}