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.2 KB
Raw Blame
import { shouldShowOpenPathError } from '../../shared/openPathResult';
import { isDangerousAttachmentName } from '../../shared/attachmentSafety';
/**
 * remoteFileOpen — 聊天流文件类交互的远程分流入口(renderer 侧)。
 * ---------------------------------------------------------------------------
 * 聊天里点文件(打开 / 定位 / 复制文件 / 文本预览)在远程会话下不能拿远端绝对
 * 路径直打本机文件系统。本模块包装 `maker:chat-file:fetch`(远端路径 → 本地缓存
 * 副本,main 侧编排见 main/file-browser/chat-file.ts),并统一「取回中 / 失败 /
 * 陈旧副本」的 toast UX:
 *
 *   - 取回超过 600ms 才弹「正在从远端获取」toast(缓存命中秒回时零打扰),
 *     完成即撤;
 *   - 失败按 code 分流文案:SSH workdir 外(本期明确不支持)/ 文件不存在 /
 *     取回失败;
 *   - 断线兜底拿到历史副本(stale)时以 warning 提示「可能不是最新版本」。
 *
 * 所有函数只在 origin 为远程时可用;local 来源的调用属于编码错误(调用方应
 * 走原有本机路径),直接抛错暴露。
 */

import { i18n } from '@/i18n';
import { createFileTransferToast } from './fileTransferProgress';
import { toast } from './toast';
import type { SessionFileOrigin } from './sessionFileOrigin';

/** 远程来源窄化(local 不进本模块)。 */
export type RemoteFileOrigin = Exclude<SessionFileOrigin, { kind: 'local' }>;

export type ChatFileFetchOutcome =
  | { ok: true; cachePath: string; stale: boolean; size: number }
  | {
      ok: false;
      code: 'BAD_ARGS' | 'OUTSIDE_WORKDIR' | 'NOT_FOUND' | 'FETCH_FAILED';
      message?: string;
    };

/** 失败 code → i18n 文案。 */
export function chatFileErrorText(
  code: Exclude<ChatFileFetchOutcome, { ok: true }>['code'],
): string {
  if (code === 'OUTSIDE_WORKDIR') return i18n.t('chat.remoteFile.outsideWorkdir');
  if (code === 'NOT_FOUND') return i18n.t('chat.remoteFile.notFound');
  return i18n.t('chat.remoteFile.fetchFailed');
}

/** 裸取回(无 toast UX):TextLightbox 等有自己进度态的调用方用。 */
export async function fetchChatFileToCache(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
  requestId?: string,
): Promise<ChatFileFetchOutcome> {
  const wireOrigin =
    origin.kind === 'device'
      ? ({ kind: 'device', deviceId: origin.deviceId } as const)
      : ({ kind: 'ssh', remoteHostId: origin.remoteHostId } as const);
  try {
    return await window.electronAPI.fileBrowser.chatFetch({
      origin: wireOrigin,
      workdir,
      absPath,
      ...(requestId ? { requestId } : {}),
    });
  } catch (err) {
    return { ok: false, code: 'FETCH_FAILED', message: String(err) };
  }
}

/**
 * 带 toast UX 的取回:成功返回缓存副本路径(stale 时附 warning 提示),失败
 * toast 后返回 null;用户在进度 toast 上点了「取消」则静默返回 null。适用于「取到副本后马上做一个本机动作」的一次性交互
 * (打开 / 定位 / 复制文件)。
 */
export async function fetchChatFileWithToasts(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): Promise<string | null> {
  const progress = createFileTransferToast(absPath);
  try {
    const res = await fetchChatFileToCache(origin, workdir, absPath, progress.requestId);
    if (progress.cancelled) return null;
    if (!res.ok) {
      toast.error(chatFileErrorText(res.code));
      return null;
    }
    if (res.stale) toast.warning(i18n.t('chat.remoteFile.staleCopy'));
    return res.cachePath;
  } finally {
    progress.dispose();
  }
}

/** 远程会话「打开文件」:取回缓存副本后交给系统默认应用(绝不对远端路径 openPath)。 */
export async function openRemoteChatFile(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): Promise<void> {
  // Remote scripts/installers follow the attachment save-only policy. Guard the
  // common entry so menu, modifier-click and ordinary fallback cannot diverge.
  if (isDangerousAttachmentName(absPath)) {
    await downloadRemoteChatEntry(origin, workdir, absPath);
    return;
  }
  const cachePath = await fetchChatFileWithToasts(origin, workdir, absPath);
  if (!cachePath) return;
  if (isDangerousAttachmentName(cachePath)) {
    await downloadRemoteChatEntry(origin, workdir, absPath);
    return;
  }
  const res = await window.electronAPI.openPath(cachePath);
  if (shouldShowOpenPathError(res)) toast.error(res.error || i18n.t('logic.errors.openFileFailed'));
}

type ChatDownloadFailureCode = Extract<
  Awaited<ReturnType<typeof window.electronAPI.fileBrowser.chatDownload>>,
  { ok: false }
>['code'];

function chatDownloadErrorText(code: ChatDownloadFailureCode): string {
  if (code === 'REMOTE_UNSUPPORTED') return i18n.t('chat.remoteFile.downloadUnsupported');
  if (code === 'NO_SPACE') return i18n.t('chat.remoteFile.downloadNoSpace');
  return chatFileErrorText(code);
}

/**
 * 远程会话「下载到本地」:文件或文件夹下载到系统「下载」文件夹(重名自动加编号),
 * 完成后在文件管理器中选中。取回超过 600ms 才弹进度 toast(缓存命中秒回时零打扰)。
 */
export async function downloadRemoteChatEntry(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): Promise<void> {
  const progress = createFileTransferToast(absPath);
  const wireOrigin =
    origin.kind === 'device'
      ? ({ kind: 'device', deviceId: origin.deviceId } as const)
      : ({ kind: 'ssh', remoteHostId: origin.remoteHostId } as const);
  try {
    const res = await window.electronAPI.fileBrowser
      .chatDownload({ origin: wireOrigin, workdir, absPath, requestId: progress.requestId })
      .catch((err: unknown) => ({
        ok: false as const,
        code: 'FETCH_FAILED' as const,
        message: String(err),
      }));
    if (progress.cancelled) return;
    if (!res.ok) {
      toast.error(chatDownloadErrorText(res.code));
      return;
    }
    if (res.stale) toast.warning(i18n.t('chat.remoteFile.staleCopy'));
    if (res.skipped > 0) toast.warning(i18n.t('chat.remoteFile.downloadSkipped'));
    const shown = await window.electronAPI.showItemInFolder({ filePath: res.path });
    if (!shown.success) toast.error(shown.error ?? i18n.t('chat.media.openFolderFailed'));
  } finally {
    progress.dispose();
  }
}

// ── chip 点亮预检(远端精确 stat)──────────────────────────────────────────
// 远程会话下 chip 点亮前先问远端「这是不是个文件」:目录 / 不存在 / SSH workdir
// 外保持纯文本(与本机"存在且唯一才点亮"的语义对齐);链路断等无法判定的情况按
// 形状分档乐观点亮(DESIGN.md §14.5 规则 5,判据见 markdownTarget.isAmbiguousPathShape)。
//
// ⚠️ **`unknown` 不是结论,只是「这一次没问到」**,因此绝不能和 file / directory /
// nonfile 同层缓存(不变量 A,与移动端 session/remotePathVerdict.ts 逐条对称):
//   - 确定态(file/directory/nonfile)按 (端点, workdir, absPath) 无 TTL 缓存——与本机
//     smartResolveCache 同款「无 TTL、容量兜底」策略,聊天引用的文件在视图生命周期内
//     视作不变,切走再回来 chip 必须同步点亮不闪烁;
//   - `unknown` 只落**短 TTL 负缓存**,不进 verdictCache、因此也不进 peek。它存在的
//     唯一理由是限流:链路差时长转录反复挂卸 chip,每次重挂都重发 stat 会打满通道
//     (移动端 2026-07 线上实捉)。TTL 过后重挂自愈重验。
//     曾把 unknown 写进 verdictCache:一次断链就把该路径永久钉成「已验证 = unknown」,
//     peek 有值 → 异步 effect 直接 return → 链路恢复后再也不重验;叠上歧义形状不吃
//     乐观点亮这道门槛,`src/components` 会永久停在纯文本(PR #1144 review 实捉)。
//     代价:断链期间乐观点亮的引用每次重挂会先画一帧纯文本再点亮(peek 拿不到
//     unknown)。这是刻意取舍——让「peek 有值」严格等价于「有确定结论」,
//     「把 unknown 当结论」这个错误在类型与结构上不可表达,比省一帧重绘值钱。

export type RemotePathVerdict = 'file' | 'directory' | 'nonfile' | 'unknown';
export type RemoteModifiedWindow = { startMs: number; endMs: number | null };

const VERDICT_CACHE_CAP = 1000;
/** unknown 负缓存 TTL:链路差时同 key 最多每 30s 重验一次(与移动端同值)。 */
const UNKNOWN_TTL_MS = 30_000;
const UNKNOWN_CACHE_CAP = 1000;
const verdictCache = new Map<string, RemotePathVerdict>();
const verdictInflight = new Map<string, Promise<RemotePathVerdict>>();
/** key → 负缓存过期时刻(epoch ms)。只存 unknown,永不与确定态混放。 */
const unknownUntil = new Map<string, number>();

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 过后自愈重验」
// 只在组件重挂时才真的发生 —— 一条渲染完就一直挂着不动的消息,链路恢复后仍停在纯
// 文本,直到用户切走再回来(PR #1144 review 实捉,与移动端同款缺口)。
//
// 由本模块把它翻译成一次通知,而不是让消费方各自处理:
//   - **一个**模块级定时器,对齐「最早的负缓存到期时刻」;不是每个引用挂一个表
//     (一条消息几十个引用 = 几十个定时器);
//   - 没有 unknown 待期时**零定时器**,不轮询;
//   - 到期时清掉过期条目 → 发**一次**通知(不是每 key 一次)→ 消费方重跑验证。
//     已有确定结论的引用会在 peek 处早退,所以实际重验的只有仍是 unknown 的那批,
//     节奏就是 TTL 本身(30s),正是负缓存设计时想要的 pace。
const changeListeners = new Set<(key: string) => void>();
let staleTimer: ReturnType<typeof setTimeout> | null = null;

/**
 * 订阅「某个 key 的缓存状态变了」——**确定态落库、或 unknown 负缓存到期**都会通知。
 * listener 收到变化的 key(用 remotePathVerdictKey 构造自己的 key 做比对),按 key 过滤
 * 是刻意的:一屏几十个引用,若每次写入都通知全部订阅者,首屏 N 次 stat 会引发 N×N 次
 * 重渲染。
 *
 * 为什么需要「确定态落库也通知」:同一路径可能在多个挂载点出现,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);
}

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),
  );
}

function verdictKey(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
  modifiedWindow?: RemoteModifiedWindow,
): string {
  const endpoint =
    origin.kind === 'device' ? `dev:${origin.deviceId}` : `ssh:${origin.remoteHostId}`;
  return (
    `${endpoint}|${workdir}|${absPath}` +
    (modifiedWindow ? `|mtime:${modifiedWindow.startMs}:${modifiedWindow.endMs}` : '')
  );
}

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

/**
 * 同步读**确定结论**(未验证 / 仅负缓存 unknown → undefined,调用方走异步验证)。
 * 返回值有值 ⇔ 远端给过确定答案 —— 调用方可以直接把「peek 有值」当作「不必重验」,
 * 不会把一次断链的 unknown 误当成终态(见本节头注释的不变量 A)。
 *
 * ⚠️ **判定「要不要重验」用这个;决定「怎么渲染」用下面的 ForRender 版。** 混用会
 * 让断链期间的乐观点亮态无处表达,渲染层只能自己存一份 → 那份就会变陈旧。
 */
export function peekRemotePathVerdict(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): RemotePathVerdict | undefined {
  return verdictCache.get(verdictKey(origin, workdir, absPath));
}

/**
 * 同步读**渲染用状态**:确定态优先,否则 TTL 未过期的负缓存回 `'unknown'`,都没有回
 * `undefined`。
 *
 * 这个出口存在的理由是把「点亮态」变成**缓存的纯派生**:断链期间的乐观点亮以前只能
 * 存在组件 state 里(peek 不返回 unknown),于是渲染态有了第二个真值来源,而缓存变化
 * 传不到它 —— 三轮 review 各捉到这个状态机的一条边(TTL 到期无通道 / 派生值没被新结论
 * 覆盖 / 另一挂载点写入的确定态传不过来)。有了它,渲染层不必自己存任何结论。
 */
export function peekRemotePathVerdictForRender(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): RemotePathVerdict | undefined {
  const key = verdictKey(origin, workdir, absPath);
  const definitive = verdictCache.get(key);
  if (definitive) return definitive;
  const until = unknownUntil.get(key);
  return until !== undefined && until > Date.now() ? 'unknown' : undefined;
}

/** 异步验证(并发去重 + 落缓存)。IPC 自身异常按 unknown 处理,绝不 throw。 */
export function verifyRemotePathCached(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
  modifiedWindow?: RemoteModifiedWindow,
): Promise<RemotePathVerdict> {
  const key = verdictKey(origin, workdir, absPath, modifiedWindow);
  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) {
    // TTL 内不再发 stat(限流),但语义仍是「没问到」:TTL 过后下一次调用重验自愈。
    if (negativeUntil > Date.now()) return Promise.resolve('unknown');
    unknownUntil.delete(key);
  }
  const wireOrigin =
    origin.kind === 'device'
      ? ({ kind: 'device', deviceId: origin.deviceId } as const)
      : ({ kind: 'ssh', remoteHostId: origin.remoteHostId } as const);
  const p = window.electronAPI.fileBrowser
    .chatStat({
      origin: wireOrigin,
      workdir,
      absPath,
      ...(modifiedWindow ? { modifiedWindow } : {}),
    })
    .then((res) => res.verdict)
    .catch(() => 'unknown' as const)
    .then((verdict) => {
      if (verdict === 'unknown') {
        // 短 TTL 负缓存,**不进 verdictCache**(见本节头注释的不变量 A)。
        capMapSize(unknownUntil, UNKNOWN_CACHE_CAP);
        unknownUntil.set(key, Date.now() + UNKNOWN_TTL_MS);
        // 到期时通知挂载中的消费方重验(否则「自愈」只在重挂时发生)。
        scheduleStaleSweep(UNKNOWN_TTL_MS);
      } else {
        capMapSize(verdictCache, VERDICT_CACHE_CAP);
        verdictCache.set(key, verdict);
      }
      // 两条分支都通知:确定态落库要让其它挂载点收敛(含把乐观点亮降级成纯文本),
      // unknown 落负缓存要让本次发起者之外的挂载点也能画出乐观点亮态。
      notifyVerdictChange(key);
      return verdict;
    })
    .finally(() => verdictInflight.delete(key));
  verdictInflight.set(key, p);
  return p;
}

/** Test-only:清空确定态缓存、unknown 负缓存、在途请求、到期定时器与订阅者
 *  (对称于移动端同名出口)。 */
export function _clearRemotePathVerdictCache(): void {
  verdictCache.clear();
  verdictInflight.clear();
  unknownUntil.clear();
  if (staleTimer !== null) {
    clearTimeout(staleTimer);
    staleTimer = null;
  }
  changeListeners.clear();
}

/** 远程会话「复制文件」:取回缓存副本后以副本作为剪贴板文件引用。 */
export async function copyRemoteChatFile(
  origin: RemoteFileOrigin,
  workdir: string,
  absPath: string,
): Promise<void> {
  const cachePath = await fetchChatFileWithToasts(origin, workdir, absPath);
  if (!cachePath) return;
  const res = await window.electronAPI.copyMediaToClipboard({ filePath: cachePath });
  if (res.success) toast.success(i18n.t('chat.markdownRenderer.fileCopied'));
  else toast.error(res.error ?? i18n.t('chat.media.copyFailed'));
}