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。

22.6 KB
Raw Blame
/**
 * useDeviceLinkDeviceList —— 机器切换栏用的「全量同账号设备」共享只读列表(push 驱动,失败低频退避)。
 * ---------------------------------------------------------------------------
 * 切换栏要区分「已连接 / 连接中 / 被拒」三态,需要 remoteProjectsStore(只含已同步设备)之外的
 * 全量设备(含在线未同步、离线、被拒)。这里做最小读:listDevices 初始拉取,之后靠 push 重拉;
 * 失败时按低频退避静默恢复 —— presence 变化、relay 重连 'online'、关「我控制它」
 * (control-target-changed,改 controlEnabled);relay 'stopped'(登出 / 停服)则清空缓存设备,
 * 避免登出后残留上一账号的远程机器。
 *
 * **模块级共享单例**:切换栏组件 + CCAgentSidebarUpper 的两个合并点都要读这份列表做归一化,若各挂
 * 一个 hook 就会有 3 次 listDevices + 3 套监听且可能短暂不一致。这里收成一份:首个订阅者触发启动,
 * 之后所有消费者共享同一快照(app 生命周期常驻,与 useDeviceLinkRemoteProjects 同口径:稳态靠 push,
 * 失败时仅按低频退避静默重试)。
 *
 * 故意不复用 useDeviceLinkSettings:那是设置页数据层,带 30s 轮询 + 一堆写操作回调,常驻侧边栏太重。
 */

import { useSyncExternalStore } from 'react';

let devices: DeviceLinkDeviceView[] | null = null;
const subs = new Set<() => void>();
const removalSubs = new Set<(deviceId: string) => void>();
let started = false;
const DEVICE_LIST_RETRY_BASE_MS = 2_000;
const DEVICE_LIST_RETRY_MAX_MS = 30_000;
export type DeviceLinkDeviceListStatus = 'loading' | 'ready' | 'error';
export interface DeviceLinkDeviceListRequestState {
  status: DeviceLinkDeviceListStatus;
  error: string | null;
}
let requestState: DeviceLinkDeviceListRequestState = { status: 'loading', error: null };
let refreshImpl: (() => void) | null = null;
/**
 * 设备目录是否已进入终态 —— 上层(shouldWaitForRemoteSessionBootstrap)据此决定还要不要等。
 * 两种终态:最新一次 listDevices 已 resolve / reject(见 setDevices / markRequestFailed),
 * 或 relay 已停(登出 / 本地模式,见 clearDevices)。false 必须意味着「还有结果会来」。
 */
let initialRequestSettled = false;
/**
 * 加载代次:**每次 refresh 发起**与**每次清空(登出 / relay stop)**都自增,作废所有更早的在途
 * listDevices 响应 —— 只有"最新一次操作"的响应能落地(同 remoteProjectsStore 的 snapshotEpoch 思路)。
 * 解决两类乱序:
 *  - stop / 登出后,早发的 listDevices 晚到 → 不得回填上个账号 / 旧 server 快照;
 *  - 同期并发的两次 refresh(如 presence 与 control-target 接连触发)乱序 resolve → 较早那次
 *    (可能还带着已 opt-out 的设备)不得盖掉较新一次的结果。
 * refresh 发起前自增并抓代次,resolve 时代次变了就丢弃。
 */
let loadGeneration = 0;

/** 更新设备目录请求态但不通知,便于与列表快照合并成一次发布。 */
function setRequestState(status: DeviceLinkDeviceListStatus, error: string | null): boolean {
  if (requestState.status === status && requestState.error === error) return false;
  requestState = { status, error };
  return true;
}

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

function isNullableString(value: unknown): value is string | null {
  return value === null || typeof value === 'string';
}

function isDeviceLinkDeviceView(value: unknown): value is DeviceLinkDeviceView {
  if (!isRecord(value)) return false;
  return (
    typeof value.deviceId === 'string' &&
    value.deviceId.length > 0 &&
    typeof value.name === 'string' &&
    isNullableString(value.platform) &&
    typeof value.online === 'boolean' &&
    typeof value.remoteControlEnabled === 'boolean' &&
    typeof value.controlEnabled === 'boolean' &&
    typeof value.isSelf === 'boolean'
  );
}

/** 仅比较切换栏关心的字段(忽略 busy / lastSeenAt 等高频字段,避免无谓重渲染)。 */
function relevantEqual(a: DeviceLinkDeviceView[] | null, b: DeviceLinkDeviceView[]): boolean {
  if (a === null || a.length !== b.length) return false;
  for (let i = 0; i < a.length; i += 1) {
    const x = a[i];
    const y = b[i];
    if (
      x.deviceId !== y.deviceId ||
      x.name !== y.name ||
      // platform 决定移动端过滤(buildSwitcherDevices 用 isMobilePlatform):若首次上报 null
      // 后变 'ios',不比较 platform 会让快照不刷新、该手机继续留在切换栏。
      x.platform !== y.platform ||
      x.online !== y.online ||
      x.remoteControlEnabled !== y.remoteControlEnabled ||
      x.controlEnabled !== y.controlEnabled ||
      x.isSelf !== y.isSelf
    ) {
      return false;
    }
  }
  return true;
}

/** platform 在目录里可为 null、在 presence 里是字符串;比较前归一化,空值等价。 */
function normalizePlatform(value: string | null | undefined): string {
  return (value ?? '').trim();
}

/**
 * 这条 presence 是否可能改变切换栏关心的字段 —— 不可能就别重拉整份目录(纯函数,可单测)。
 *
 * relay 把 presence-changed 广播给同账号所有连接、**含本机**(dispatch.ts 写明这是控制端崩溃 /
 * 拔网后回收僵尸订阅的兜底信号,刻意保留)。而本机每开始 / 跑完一轮任务都会翻转 busy 并上报,
 * 于是自己的 busy 绕一圈回来就触发一次全量 listDevices —— 开跑一次、跑完一次,纯浪费(issue #1726)。
 *
 * 判据与 `relevantEqual` 同源:只有切换栏真正消费的字段变化才值得重拉。`busy` / `lastSeenAt` /
 * `appVersion` / `deviceInfo` 虽然在 `DeviceLinkDeviceView` 里,但 `relevantEqual` 刻意不比较
 * 它们(「忽略 busy / lastSeenAt 等高频字段,避免无谓重渲染」)—— 既然它们变了也不会让快照替换,
 * 为它们重拉一整份目录就纯是浪费。
 *
 * 刻意**不**比较 `controlEnabled`:它由本地 opt-out 决定、不在 presence 里,其改动走
 * `control-target-changed` 事件的既有刷新路径。
 *
 * `isSelf` 直接跳过是安全的:`switcherDevices.ts` 明确「本机(isSelf)排除」,本机行的
 * online / remoteControlEnabled 不参与列表内容。
 */
export function shouldRefreshForPresence(
  current: readonly DeviceLinkDeviceView[] | null,
  snap: DeviceLinkPresenceSnapshot,
  requestStatus: DeviceLinkDeviceListStatus,
): boolean {
  // 上一次拉取失败(且此前已有快照 → `devices` 仍非空、状态停在 'error')时**一律放行**:
  // 自动退避之外,这条 push 信号也是低延迟恢复机会;若此时还按「字段没变」把 presence 滤掉,
  // 一次瞬时 REST 失败就会把侧栏钉在错误 / 陈旧目录上,直到下一次退避、status 或
  // control-target 事件 (review: codex P1)。
  //
  // 'loading' 不放行:那说明已有一笔在飞,`loadGeneration` 会让后到的结果胜出,再叠一次
  // refresh 只是徒增请求;它若失败会落到 'error',下一条 presence 自然接管重试。
  if (requestStatus === 'error') return true;
  // 还没有首份目录 → 照常拉(这条 presence 可能正是「终于连上了」的信号)。
  if (current === null) return true;
  const row = current.find((d) => d.deviceId === snap.deviceId);
  // 目录里没有这台设备 → 它是新出现的,必须重拉才能进列表。
  if (row === undefined) return true;
  // 自 presence 自回声:本机不进切换栏,重拉不会改变任何可见内容。
  if (row.isSelf) return false;
  return (
    row.online !== snap.online ||
    row.remoteControlEnabled !== snap.remoteControlEnabled ||
    normalizePlatform(row.platform) !== normalizePlatform(snap.platform) ||
    row.name.trim() !== snap.deviceName.trim()
  );
}

/** 设备目录静默恢复的退避:持续恢复,但长期故障时不每 2 秒打一次 IPC。 */
export function nextDeviceListRetryDelay(previousMs: number): number {
  if (!Number.isFinite(previousMs) || previousMs < DEVICE_LIST_RETRY_BASE_MS) {
    return DEVICE_LIST_RETRY_BASE_MS;
  }
  return Math.min(previousMs * 2, DEVICE_LIST_RETRY_MAX_MS);
}

/**
 * 就地改名(纯函数,可单测):返回把 `deviceId` 的 name 改成 `name`(trim 后)的新数组;
 * 无需改动(空名 / null 列表 / 设备不在列表 / 名字未变)时**返回原引用**,调用方可用 `===` 判定 no-op。
 */
export function applyDeviceRename(
  list: readonly DeviceLinkDeviceView[] | null,
  deviceId: string,
  name: string,
): readonly DeviceLinkDeviceView[] | null {
  const trimmed = name.trim();
  if (!trimmed || list === null) return list;
  const idx = list.findIndex((d) => d.deviceId === deviceId);
  if (idx < 0 || list[idx].name === trimmed) return list;
  const next = list.slice();
  next[idx] = { ...next[idx], name: trimmed };
  return next;
}

function setDevices(next: DeviceLinkDeviceView[]): void {
  // 按 deviceId 稳定排序,避免服务端返回顺序抖动触发无谓重渲染。
  const sorted = [...next].sort((a, b) => a.deviceId.localeCompare(b.deviceId));
  const devicesChanged = !relevantEqual(devices, sorted);
  const settledChanged = !initialRequestSettled;
  const requestChanged = setRequestState('ready', null);
  if (!devicesChanged && !settledChanged && !requestChanged) return;
  devices = sorted;
  initialRequestSettled = true;
  subs.forEach((fn) => fn());
}

/**
 * 清空缓存设备(null → 切换栏隐藏)。登出 / relay 停止时调用。
 *
 * `initialRequestSettled` **置 true**:link 已停 = 此刻确定没有可用的远端设备目录,而且在途
 * 请求刚被 loadGeneration 作废、不会再有结果落地 —— 这与 refresh 失败兜底同一个终态
 * (devices=null + settled=true)。若像早先那样置回 false,登出后进入本地模式 / 保持未登录
 * 就再也收不到 relay 'online' 来重新结算,shouldWaitForRemoteSessionBootstrap 恒为 true,
 * 侧栏「对话」分区卡在「加载中…」直到冷重启(#797)。
 * 重新登录不受影响:relay 'online' → refresh() 会因 `devices === null && initialRequestSettled`
 * 主动退回 loading,远程设备首快照的等待行为保持原样。
 */
function clearDevices(): void {
  loadGeneration += 1; // 作废所有在途 listDevices 响应(见 loadGeneration 注释)。
  const requestChanged = setRequestState('ready', null);
  const changed = devices !== null || !initialRequestSettled || requestChanged;
  if (!changed) return;
  devices = null;
  initialRequestSettled = true;
  subs.forEach((fn) => fn());
}

function markRequestFailed(error: unknown): void {
  const requestChanged = setRequestState(
    'error',
    error instanceof Error ? error.message : String(error),
  );
  if (initialRequestSettled && !requestChanged) return;
  initialRequestSettled = true;
  subs.forEach((fn) => fn());
}

/**
 * 设备改名传播:REST 改名只持久化 + 更新 remoteProjectsStore(已同步设备),**不**广播
 * presence / status,故本「全量设备」单例不会自动重拉 —— 连接中 / 被拒(无同步分片)的设备其切换栏
 * chip 名取自这里的缓存 `fullList`,会一直停在旧名,直到下一次无关的 presence / status / control-target
 * 事件触发 refresh。这里就地改名 + 通知,使 chip 即时刷新,与 remoteProjectsStore.renameDevice 同口径
 * (二者都在 useDeviceLinkSettings.rename 成功后调用)。设备未在缓存(null / 不含该 id)→ no-op,
 * 下次 refresh 会从 REST 拿到新名。
 */
export function renameDeviceLinkDevice(deviceId: string, name: string): void {
  const next = applyDeviceRename(devices, deviceId, name);
  if (next === devices) return; // 引用未变 = 无需改动
  devices = next as DeviceLinkDeviceView[];
  subs.forEach((fn) => fn());
}

/** Apply confirmed deletion even for an already-offline device; its presence
 * snapshot may not otherwise trigger a directory refresh. */
export function removeDeviceLinkDevice(deviceId: string): void {
  loadGeneration += 1;
  removalSubs.forEach(fn => fn(deviceId));
  if (devices?.some(device => device.deviceId === deviceId)) {
    devices = devices.filter(device => device.deviceId !== deviceId);
    subs.forEach(fn => fn());
  }
  refreshImpl?.();
}

/** Confirmed deletion must also invalidate mirrors, even before a shard exists. */
export function subscribeDeviceLinkDeviceRemoval(fn: (deviceId: string) => void): () => void {
  removalSubs.add(fn);
  return () => { removalSubs.delete(fn); };
}

function ensureStarted(): void {
  if (started) return;
  started = true;
  let linkStatus: 'stopped' | 'connecting' | 'online' | null = null;
  let linkStatusRevision = 0;
  let retryTimer: ReturnType<typeof setTimeout> | null = null;
  let retryDelayMs = 0;
  let backgroundRetryGeneration: number | null = null;
  let backgroundRetryRefreshPending = false;
  let backgroundRetryReplayActive = false;

  const finishRefresh = (gen: number, background: boolean): void => {
    // A foreground refresh can supersede a background retry. In that case the old
    // retry must not consume a presence queued for the newer operation; the
    // current operation will replay it when it settles.
    if (background) {
      if (backgroundRetryGeneration !== gen) return;
      backgroundRetryGeneration = null;
    }
    if (gen !== loadGeneration) return;
    const shouldRefresh = backgroundRetryRefreshPending && linkStatus !== 'stopped';
    backgroundRetryRefreshPending = false;
    backgroundRetryReplayActive = false;
    if (shouldRefresh) refresh(false, true);
  };

  const clearRetryTimer = (): void => {
    if (retryTimer !== null) {
      clearTimeout(retryTimer);
      retryTimer = null;
    }
  };

  const scheduleRetry = (): void => {
    if (retryTimer !== null || linkStatus === 'stopped') return;
    retryDelayMs = nextDeviceListRetryDelay(retryDelayMs);
    retryTimer = setTimeout(() => {
      retryTimer = null;
      // 后台恢复不能把已结算的目录重新打回 initialRequestSettled=false;否则持久化的
      // 远端选择会在每次退避尝试时暂时恢复、遮住本地侧栏。请求仍在飞,但选择/加载态保持稳定。
      refresh(false, true);
    }, retryDelayMs);
  };

  const enterLoading = (): void => {
    // 上一轮在尚无设备快照时失败只代表「该次请求已结算」。新的有效拉取开始后要重新
    // 进入 loading,直到本轮成功或失败;已有快照则保留,requestState 单独表达正在刷新。
    const settledChanged = devices === null && initialRequestSettled;
    if (settledChanged) initialRequestSettled = false;
    const requestChanged = setRequestState('loading', null);
    if (settledChanged || requestChanged) subs.forEach((fn) => fn());
  };

  const runRefresh = async (probeState: boolean, background = false): Promise<void> => {
    // getState 与 listDevices 共用同一个 operation generation。stop、状态 push、手动重试或
    // 更晚的 refresh 都会令旧操作失效,迟到的状态快照和目录快照都不得落地。
    loadGeneration += 1;
    const gen = loadGeneration;
    const statusRevisionAtStart = linkStatusRevision;
    if (background) backgroundRetryGeneration = gen;
    if (!background) {
      // The foreground operation owns the current generation now; any pending
      // presence from a superseded background retry must be replayed after it.
      if (backgroundRetryGeneration !== null) backgroundRetryReplayActive = true;
      backgroundRetryGeneration = null;
      enterLoading();
    }

    if (probeState || linkStatus === null) {
      try {
        const state = await window.electronAPI.deviceLink.getState();
        if (gen !== loadGeneration || statusRevisionAtStart !== linkStatusRevision) {
          finishRefresh(gen, background);
          return;
        }
        linkStatus = state.linkStatus;
      } catch {
        if (gen !== loadGeneration || statusRevisionAtStart !== linkStatusRevision) {
          finishRefresh(gen, background);
          return;
        }
        // getState 本身失败时保留既有 status 判断;未知 / 在线态仍尝试目录请求,让真正的
        // listDevices 结果决定 ready/error。已知 stopped 则不能误打成远程连接失败。
      }
    }

    // 未登录 / 本地模式 / Device Link 停服不是「远程目录读取失败」:此刻远端能力
    // 不在产品作用域内,目录应结算为 ready + null。手动重试也不能把 stopped 重新
    // 打成 error;只有 online / connecting 下真实发出的 listDevices 失败才是连接错误。
    if (linkStatus === 'stopped') {
      clearDevices();
      finishRefresh(gen, background);
      return;
    }

    try {
      const result = await window.electronAPI.deviceLink.listDevices();
      // 期间发生过清空(stop / 登出)或更晚的 refresh → 本次响应已陈旧,丢弃。
      if (gen !== loadGeneration) {
        finishRefresh(gen, background);
        return;
      }
      const list = result?.devices;
      if (!Array.isArray(list) || !list.every(isDeviceLinkDeviceView)) {
        throw new Error('Invalid device list response');
      }
      clearRetryTimer();
      retryDelayMs = 0;
      setDevices(list);
    } catch (error) {
      // 只有最新请求的失败才算本轮首拉已经结算;更晚的 refresh 仍在途时继续等待它。
      if (gen !== loadGeneration) {
        finishRefresh(gen, background);
        return;
      }
      markRequestFailed(error);
      // 瞬态拉取失败(relay 重连中等)保持当前快照;登出 / relay 停止由下面的 'stopped'
      // 状态事件显式清空,不靠这里的失败兜底(避免一次网络抖动就清掉、闪烁)。但把请求
      // 标成已结算,避免远端 sidebar bootstrap 因 devices 仍为 null 永久显示加载态。
      scheduleRetry();
    }
    finishRefresh(gen, background);
  };

  const refresh = (probeState = false, background = false): void => {
    clearRetryTimer();
    void runRefresh(probeState, background);
  };
  refreshImpl = () => refresh(true);
  // app 生命周期常驻(侧边栏始终有订阅者),不解绑监听。
  // 只有相关 presence 才重拉目录(见 shouldRefreshForPresence):本机 busy 自回声与对端的
  // busy / lastSeenAt 心跳都不改变切换栏内容,却各触发一次全量 listDevices(issue #1726)。
  window.electronAPI.deviceLink.onPresenceChanged((snap) => {
    // 后台退避请求在飞时保留 error/settled 快照;不要让 presence 噪音把它升级成前台
    // refresh,再次触发 loading 并恢复悬空的持久化远端选择。
    if (backgroundRetryGeneration !== null || backgroundRetryReplayActive) {
      // 不能丢掉真实的上线 / 改名 / 能力变化:本次 REST 响应可能早于 presence,结束后
      // 追加一次后台 refresh;同一请求期间的多条 presence 合并成一次。这里按 ready
      // 语义判断字段变化,避免 error 快速路径把本机 busy / lastSeenAt 噪音也排进补拉;
      // devices=null 时仍会放行,因为这时无法从快照判断设备是否新出现。
      if (shouldRefreshForPresence(devices, snap, 'ready')) backgroundRetryRefreshPending = true;
      return;
    }
    // A failed request may already have a backoff timer waiting. Treat presence
    // as a settled snapshot in that window so busy/lastSeen heartbeats do not
    // cancel the backoff and reopen the foreground loading state. Relevant
    // presence can still recover promptly, but stays in the background path.
    const retryPending = retryTimer !== null;
    // Without a directory snapshot there is no safe way to distinguish a new
    // device from this machine's heartbeat. Keep the scheduled backoff as the
    // recovery source instead of letting every presence cancel it.
    if (retryPending && devices === null) return;
    if (!shouldRefreshForPresence(devices, snap, retryPending ? 'ready' : requestState.status))
      return;
    refresh(false, retryPending);
  });
  window.electronAPI.deviceLink.onStatusChanged((p) => {
    linkStatusRevision += 1;
    linkStatus = p.status;
    if (p.status === 'stopped') {
      // 登出 / relay 停止:清掉缓存设备。否则登出后(或同进程换账号)上一账号的远程机器会
      // 一直留在切换栏里被当成可选 / 连接中(listDevices 此时多半失败,catch 又保留旧快照)。
      // 重新登录 → relay 重连到 'online' 时下面重新拉取。
      clearRetryTimer();
      retryDelayMs = 0;
      clearDevices();
      backgroundRetryGeneration = null;
      backgroundRetryRefreshPending = false;
      backgroundRetryReplayActive = false;
      return;
    }
    // online / connecting 都是远端目录仍在作用域内的状态:开始新一轮读取。connecting 下
    // 若 REST 仍可达可直接拿到目录;不可达则明确落 error,而不是误装成空列表。
    refresh();
  });
  // 关掉「我控制它」(本地 opt-out)只广播 control-target-changed、不发 presence;listDevices 的
  // controlEnabled 已据 disabledControlDeviceIds 计算,故重拉即可让被 opt-out 的设备立刻退出切换栏。
  window.electronAPI.deviceLink.onControlTargetChanged(() => refresh());

  // 监听必须先挂,再读初值:否则 hook 挂载前 relay 已 stopped,或 getState 在 push 后迟到,
  // 都可能把本地/未登录态误报成 listDevices 失败。revision + generation 保证 push 永远胜出。
  refresh(true);
}

function subscribe(fn: () => void): () => void {
  subs.add(fn);
  ensureStarted();
  return () => {
    subs.delete(fn);
  };
}

function getSnapshot(): DeviceLinkDeviceView[] | null {
  return devices;
}

/** 订阅全量设备列表(共享单例);null = 尚未加载。 */
export function useDeviceLinkDeviceList(): DeviceLinkDeviceView[] | null {
  return useSyncExternalStore(subscribe, getSnapshot);
}

function getInitialRequestSettledSnapshot(): boolean {
  return initialRequestSettled;
}

/** 首次设备清单请求是否已结算;失败也算结算,后续退避 / push / online 事件仍会继续 refresh。 */
export function useDeviceLinkDeviceListSettled(): boolean {
  return useSyncExternalStore(subscribe, getInitialRequestSettledSnapshot);
}

function getRequestStateSnapshot(): DeviceLinkDeviceListRequestState {
  return requestState;
}

/** 设备目录的 loading / ready / error 状态;只有 ready + [] 才是权威空目录。 */
export function useDeviceLinkDeviceListRequestState(): DeviceLinkDeviceListRequestState {
  return useSyncExternalStore(subscribe, getRequestStateSnapshot);
}

/** 兼容现有调用方的显式重试入口;正常失败恢复由上面的静默退避自动完成。 */
export function retryDeviceLinkDeviceList(): void {
  if (!started) {
    ensureStarted();
    return;
  }
  refreshImpl?.();
}