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。

10.0 KB
Raw Blame
/**
 * remotePathVerdict — 聊天文件 chip 点亮前的远端存在性验证(verdict 缓存层)。
 * ---------------------------------------------------------------------------
 * 手机端一切会话都是 device-link 远程会话:chip 点亮不能打本机文件系统,必须
 * 问被控端「这个绝对路径是不是文件 / 目录」。本模块与桌面
 * renderer/lib/remoteFileOpen.ts 的 verdict 层同语义:
 *
 *   - `file` / `directory` → 点亮;`nonfile`(远端明确不存在)→ 保持纯文本;
 *   - `unknown`(链路断 / stat 异常等无法判定)→ **按形状分档**:形状明确是路径的
 *     乐观点亮(点击后由预览页自己的错误 UX 兜底,绝不因为断链把整条消息的 chip
 *     全灭掉),歧义形状必须等确定答案(判据 chatPathCandidate.isAmbiguousChatPathShape,
 *     门槛落地在 MessageRenderer.ChatPathChipSpan;DESIGN.md §14.5 规则 5);
 *   - 确定态(file/directory/nonfile)按 (deviceId, workdir, absPath) 缓存,
 *     无 TTL、容量兜底:聊天引用的文件在视图生命周期内视作不变,切会话回来
 *     chip 必须同步点亮不闪烁;
 *   - unknown 按同 key 落短 TTL 负缓存(不进 peek):链路差时 FlatList 窗口化
 *     反复挂卸 chip,若每次重挂都重发 stat,长转录 × 断续链路会形成打满
 *     device-link 通道的重验风暴(2026-07 线上实捉:整机点按延迟秒级)。TTL 内
 *     直接按 unknown 乐观点亮,TTL 过后重挂自愈重验,自愈语义不变、只是不再
 *     每次重挂都打一发;
 *   - 并发去重:同一路径在同屏多处出现时只发一次 stat;
 *   - 并发限流:不同路径的 stat 全局最多同时在飞 STAT_MAX_CONCURRENCY 条。
 *     stat 与消息收发共用同一条 device-link 通道,首屏一次性点亮几十个 chip
 *     时不限流会把用户操作挤在长队后面(同上事故的另一半成因)。
 *
 * stat 执行体由调用方注入(会话屏包装 device-link transport),本模块零 IO
 * 依赖,可直接单测。
 */

import type { RemotePathStatResult } from '@/device-link/mobileMakerTransport';

export type RemotePathVerdict = 'file' | 'directory' | 'nonfile' | 'unknown';

/** stat 执行体:被控端 `fs:stat-path`(dir / file / missing 三态)。 */
export type RemotePathStatFn = (absPath: string) => Promise<RemotePathStatResult>;

const VERDICT_CACHE_CAP = 1000;
/** unknown 负缓存 TTL:链路差时同 key 最多每 30s 重验一次(重挂不再必发)。 */
const UNKNOWN_TTL_MS = 30_000;
const UNKNOWN_CACHE_CAP = 1000;
/** 全局 stat 并发上限:pace 住验证流量,别挤占用户操作的 device-link 往返。 */
const STAT_MAX_CONCURRENCY = 3;

const verdictCache = new Map<string, RemotePathVerdict>();
const verdictInflight = new Map<string, Promise<RemotePathVerdict>>();
/** key → 负缓存过期时刻(epoch ms)。 */
const unknownUntil = new Map<string, number>();

let statActive = 0;
const statWaiters: Array<() => void> = [];

/** 占一个 stat 并发槽;满员时排队(FIFO),由 releaseStatSlot 交接唤醒。 */
function acquireStatSlot(): Promise<void> {
  if (statActive < STAT_MAX_CONCURRENCY) {
    statActive += 1;
    return Promise.resolve();
  }
  return new Promise<void>((resolve) => {
    statWaiters.push(resolve);
  });
}

/** 释放并发槽:有排队者则把槽原地交接(计数不变),否则归还计数。 */
function releaseStatSlot(): void {
  const next = statWaiters.shift();
  if (next) {
    next();
    return;
  }
  statActive -= 1;
}

function verdictKey(deviceId: string, workdir: string, absPath: string): string {
  return `${deviceId}|${workdir}|${absPath}`;
}

function capMapSize(map: Map<string, unknown>, cap: number): void {
  if (map.size < cap) return;
  const oldest = map.keys().next().value;
  if (oldest !== undefined) map.delete(oldest);
}

// ── 负缓存到期的通知 ────────────────────────────────────────────────────────
// TTL 到期**本身不是事件**:没有任何 React 依赖会因它而变。所以「TTL 过后重挂自愈」
// 只在真的重挂时才发生 —— 短转录不会被 FlatList 回收,一条挂着不动的消息在链路恢复
// 后会一直停在纯文本(PR #1144 review 实捉,与桌面同款缺口)。
//
// 由本模块把它翻译成一次通知:**一个**模块级定时器对齐「最早的负缓存到期时刻」
// (不是每个 chip 挂一个表 —— 一屏几十个 chip 就是几十个定时器),没有 unknown 待期时
// 零定时器、不轮询;到期清掉过期条目后发**一次**通知,已有确定结论的 chip 会在 peek
// 处早退,于是实际重验的只有仍是 unknown 的那批,节奏就是 TTL 本身(30s)。
const changeListeners = new Set<(key: string) => void>();
let staleTimer: ReturnType<typeof setTimeout> | null = null;

/**
 * 订阅「某个 key 的缓存状态变了」——**确定态落库、或 unknown 负缓存到期**都会通知。
 * listener 收到变化的 key(用 remotePathVerdictKey 构造自己的 key 比对),按 key 过滤是
 * 刻意的:一屏几十个 chip 各自订阅,全量广播会让首屏 N 次 stat 引发 N×N 次重渲染。
 *
 * 「确定态落库也通知」是必需的:同一路径可能出现在多个 chip 上,A 先按 unknown 乐观
 * 点亮,B 随后拿到确定的 nonfile 写进缓存 —— 没有这条通道 A 永远不知道,已确认不存在的
 * 路径会一直带着下划线可点(PR #1144 review 实捉,桌面同款)。
 */
export function subscribeRemotePathVerdictChange(listener: (key: string) => void): () => void {
  changeListeners.add(listener);
  return () => {
    changeListeners.delete(listener);
  };
}

function notifyVerdictChange(key: string): void {
  for (const listener of [...changeListeners]) listener(key);
}

/** 缓存 key(供订阅方按 key 过滤变化通知)。 */
export function remotePathVerdictKey(deviceId: string, workdir: string, absPath: string): string {
  return verdictKey(deviceId, workdir, absPath);
}

/**
 * 同步读**渲染用状态**:确定态优先,否则 TTL 未过期的负缓存回 `'unknown'`,都没有回
 * `undefined`。让「点亮态」成为缓存的纯派生 —— 断链期间的乐观点亮不再需要 chip 自己
 * 存一份(自存的那份收不到缓存变化,就会变陈旧)。
 */
export function peekRemotePathVerdictForRender(
  deviceId: string,
  workdir: string,
  absPath: string,
): RemotePathVerdict | undefined {
  const key = verdictKey(deviceId, workdir, absPath);
  const definitive = verdictCache.get(key);
  if (definitive) return definitive;
  const until = unknownUntil.get(key);
  return until !== undefined && until > Date.now() ? 'unknown' : undefined;
}

function scheduleStaleSweep(delayMs: number): void {
  // 已有定时器就复用:它一定排在同一或更早的时刻,醒来后会把剩下的重新排期。
  if (staleTimer !== null) return;
  staleTimer = setTimeout(() => {
    staleTimer = null;
    const now = Date.now();
    let earliest = Number.POSITIVE_INFINITY;
    const expired: string[] = [];
    for (const [key, until] of unknownUntil) {
      if (until <= now) expired.push(key);
      else if (until < earliest) earliest = until;
    }
    for (const key of expired) unknownUntil.delete(key);
    if (earliest !== Number.POSITIVE_INFINITY) scheduleStaleSweep(earliest - now);
    for (const key of expired) notifyVerdictChange(key);
  }, Math.max(1, delayMs));
}

/** 同步读已验证结论(未验证 / 仅负缓存 unknown → undefined,调用方走异步验证)。 */
export function peekRemotePathVerdict(
  deviceId: string,
  workdir: string,
  absPath: string,
): RemotePathVerdict | undefined {
  return verdictCache.get(verdictKey(deviceId, workdir, absPath));
}

/** 异步验证(并发去重 + 限流 + 落缓存)。stat 异常按 unknown 处理,绝不 throw。 */
export function verifyRemotePathCached(
  deviceId: string,
  workdir: string,
  absPath: string,
  stat: RemotePathStatFn,
): Promise<RemotePathVerdict> {
  const key = verdictKey(deviceId, workdir, absPath);
  const hit = verdictCache.get(key);
  if (hit) return Promise.resolve(hit);
  const pending = verdictInflight.get(key);
  if (pending) return pending;
  const negativeUntil = unknownUntil.get(key);
  if (negativeUntil !== undefined) {
    if (negativeUntil > Date.now()) return Promise.resolve('unknown');
    unknownUntil.delete(key);
  }
  const p = (async (): Promise<RemotePathVerdict> => {
    await acquireStatSlot();
    try {
      const res = await stat(absPath);
      if (res.kind === 'dir') return 'directory';
      if (res.kind === 'file') return 'file';
      return 'nonfile';
    } catch {
      return 'unknown';
    } finally {
      releaseStatSlot();
    }
  })()
    .then((verdict) => {
      if (verdict === 'unknown') {
        // 短 TTL 负缓存(见头注释):TTL 内同 key 不再发 stat,乐观点亮语义不变。
        capMapSize(unknownUntil, UNKNOWN_CACHE_CAP);
        unknownUntil.set(key, Date.now() + UNKNOWN_TTL_MS);
        // 到期时通知挂载中的 chip 重验(否则「自愈」只在重挂时发生)。
        scheduleStaleSweep(UNKNOWN_TTL_MS);
      } else {
        capMapSize(verdictCache, VERDICT_CACHE_CAP);
        verdictCache.set(key, verdict);
      }
      // 两条分支都通知:确定态落库要让其它 chip 收敛(含把乐观点亮降级成纯文本),
      // unknown 落负缓存要让本次发起者之外的 chip 也能画出乐观点亮态。
      notifyVerdictChange(key);
      return verdict;
    })
    .finally(() => verdictInflight.delete(key));
  verdictInflight.set(key, p);
  return p;
}

/** Test-only:清空缓存、负缓存、在途请求与并发槽状态。调用前先把自己发起的
 *  在途 stat 全部 settle 掉,否则迟到的 releaseStatSlot 会污染下一个用例的计数。 */
export function _clearRemotePathVerdictCache(): void {
  verdictCache.clear();
  verdictInflight.clear();
  unknownUntil.clear();
  statActive = 0;
  statWaiters.length = 0;
  if (staleTimer !== null) {
    clearTimeout(staleTimer);
    staleTimer = null;
  }
  changeListeners.clear();
}