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。

7.2 KB
Raw Blame
/**
 * 文件浏览 → ImageLightbox(聊天同款图片查看器)的桥接。
 *
 * 统一决策(2026-07-04 产品):图片文件不再走 Quick Look 预览页,直接进
 * ImageLightbox,与聊天看图同一套体验(左右滑/捏合缩放/下拉关闭/分享)。
 * 做法:把目录里的图片文件包装成 `xdt-file://open?path=<绝对路径>` 的
 * gallery 项(previewable:false)——这是被控端媒体取件通道原生认可的 scheme,
 * lightbox 经 onResolveRemoteMedia 走「取件上传 OSS → presign」既有管线拿到
 * 可显示 URL,对老版本被控端同样生效,零新协议。
 */
import { i18n } from '@/i18n';
import { buildMediaPayload } from '@/session/messagePayload';
import type { MobileMessageGalleryImage } from '@/session/messageGallery';
import {
  isResolvedRemoteMediaFresh,
  resolveMobileRemoteMedia,
  type MobileRemoteMediaResolverDeps,
  type MobileResolvedRemoteMedia,
  type ResolveRemoteMediaFn,
} from '@/session/remoteMedia';
import type { FileBrowserGridItem } from '@/session/fileBrowserGrid';

/**
 * 远程文件的媒体取件 URL(被控端 mediaFetch 的 parsePathQuery 消费,只读
 * `path` 参数)。`v`(文件 mtime)仅用于让 URL 随文件版本变化:同路径文件被
 * 覆写后,以 URL 为 key 的手机端 resolver 缓存自然失效,不会复用旧图;被控端
 * 忽略该参数,新老版本均兼容。
 */
/**
 * SSH 远程工作区的取件上下文。被控端 parseSshMediaOrigin 要求 sessionId /
 * remoteHostId / workdir **三者同时提供**,并按 sessionId 反查本地会话库逐项比对后
 * 才使用 —— 缺项直接抛错,少给一项等于取件必失败。
 */
export interface RemoteMediaSshContext {
  sessionId: string;
  remoteHostId: string;
  workdir: string;
}

/**
 * 三项齐备(trim 后非空)才算有效上下文,与被控端 parseSshMediaOrigin 的完整性要求同口径。
 *
 * **URL 构造与取件缓存键必须共用这一份判定**(review P2 实捉):此前 URL 侧要求「三项 trim
 * 后均非空」,而 fetchRemoteAbsFileToUrl 的缓存键只看 `ssh` 对象是否存在就无条件拼接三个
 * 字段 —— 调用方误传 `{sessionId:'', …}` 时 URL 退化成不带 SSH 参数(按本机路径取件),
 * 缓存键却被这些空字段区分开,同一次取件永远命中不了缓存,白发请求。
 */
export function effectiveRemoteMediaSshContext(
  ssh: RemoteMediaSshContext | null | undefined,
): RemoteMediaSshContext | null {
  if (!ssh) return null;
  const sessionId = ssh.sessionId.trim();
  const remoteHostId = ssh.remoteHostId.trim();
  const workdir = ssh.workdir.trim();
  if (!sessionId || !remoteHostId || !workdir) return null;
  return { sessionId, remoteHostId, workdir };
}

function sshContextQuery(ssh: RemoteMediaSshContext | null | undefined): string {
  const eff = effectiveRemoteMediaSshContext(ssh);
  if (!eff) return '';
  return `&sessionId=${encodeURIComponent(eff.sessionId)}`
    + `&remoteHostId=${encodeURIComponent(eff.remoteHostId)}`
    + `&workdir=${encodeURIComponent(eff.workdir)}`;
}

/**
 * 取件的**服务端强制约束**(被控端 mediaFetch 消费,不是手机端的自我约束)。
 *
 * 为什么必须由被控端强制:手机侧的词法校验与下载后判断都晚于「被控端 stat → 上传 OSS
 * (SSH 场景还要先整份拉到 Desktop 磁盘缓存)」,一份不可信 HTML 引用一个 2 GB 的
 * `.css` 就能在手机看到 `media.size` 之前打出数 GB 的磁盘/网络/OSS 流量(review P2)。
 *
 * **版本歪斜是 fail-open**:老被控端不认这两个参数会照旧取件,约束等于不生效。这不构成
 * 回退(它今天本来就没有这两道校验),但手机侧的既有判断必须全部保留作第二道。
 */
export interface RemoteMediaFetchConstraints {
  /**
   * 资源必须落在这个目录内。被控端对**资源与该目录双方各自 realpath 后**判定包含关系,
   * 目的是挡住「产物目录内有一个指向目录外的软链」这条绕过(词法 `..` 校验挡不住它)。
   */
  baseDir?: string;
  /** 字节上限。被控端在 stat 之后、上传/拉取之前拒绝,不让超限文件产生任何流量。 */
  maxBytes?: number;
}

function constraintsQuery(c: RemoteMediaFetchConstraints | null | undefined): string {
  if (!c) return '';
  let q = '';
  const baseDir = c.baseDir?.trim();
  if (baseDir) q += `&baseDir=${encodeURIComponent(baseDir)}`;
  if (Number.isFinite(c.maxBytes) && (c.maxBytes as number) > 0) {
    q += `&maxBytes=${Math.floor(c.maxBytes as number)}`;
  }
  return q;
}

export function remoteFileMediaUrl(
  absPath: string,
  versionMs?: number,
  /**
   * SSH 会话必须带上,否则被控端会把 absPath 当**本机**路径交给 realpath:
   * 取件失败,而被控桌面恰有同名路径时还会读到错误来源(review P2 实捉)。
   * 本机会话传 null / 省略。
   */
  ssh?: RemoteMediaSshContext | null,
  /** 服务端强制约束(HTML 资源透传专用;普通媒体取件省略)。 */
  constraints?: RemoteMediaFetchConstraints | null,
): string {
  const base = `xdt-file://open?path=${encodeURIComponent(absPath)}`;
  const withSsh = `${base}${sshContextQuery(ssh)}${constraintsQuery(constraints)}`;
  return versionMs ? `${withSsh}&v=${versionMs}` : withSsh;
}

/** 当前目录的图片文件 → lightbox gallery(顺序与网格排序一致)。 */
export function buildFileBrowserGalleryImages(
  items: readonly FileBrowserGridItem[],
  absolutePathOf: (relPath: string) => string,
): MobileMessageGalleryImage[] {
  const images: MobileMessageGalleryImage[] = [];
  for (const item of items) {
    if (item.kind !== 'file' || item.thumb !== 'image') continue;
    const url = remoteFileMediaUrl(absolutePathOf(item.relPath), item.mtimeMs);
    const payload = buildMediaPayload(
      { kind: 'image', url, title: item.name, previewable: false },
      item.name,
    );
    if (payload.kind !== 'media') continue;
    images.push({ key: item.key, title: item.name, url, payload, subtitle: item.metaLabel || undefined });
  }
  return images;
}

/**
 * 文件浏览专用的媒体解析器:复用聊天媒体的 resolveMobileRemoteMedia,外加
 * 一层按 URL 的新鲜度缓存(presign 未过期不重取;文件浏览没有消息队列那套
 * resolve queue,这层小缓存补上重开 lightbox 不重导出的语义)。
 */
export function createFileBrowserMediaResolver(deps: MobileRemoteMediaResolverDeps): ResolveRemoteMediaFn {
  const cache = new Map<string, MobileResolvedRemoteMedia>();
  return async (media, opts) => {
    const cached = cache.get(media.url);
    if (cached && !opts?.forceRefresh && isResolvedRemoteMediaFresh(cached)) return cached;
    // cachedOnly(lightbox 垫底预取):只吃缓存,未命中不触发取件——本 resolver 不区分
    // 缩略图变体,放行会变成一次装饰性的整图导出+下载,与主取件叠成双下载。
    if (opts?.cachedOnly) throw new Error(i18n.t('files.gallery.cacheMiss'));
    // forceRefresh(Image 加载失败自愈)映射为被控端 skipCache,穿透上传去重缓存;
    // signal(长按导出/分享的「取消」)中止取件。
    const resolved = await resolveMobileRemoteMedia(media, deps, {
      ...(opts?.forceRefresh ? { skipCache: true } : {}),
      ...(opts?.signal ? { signal: opts.signal } : {}),
    });
    cache.set(media.url, resolved);
    return resolved;
  };
}