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.8 KB
Raw Blame
/**
 * remoteMediaUrl.ts — 远程会话媒体层的「远程媒体 URL」编解码(renderer 与 main 共用)。
 * ---------------------------------------------------------------------------
 * 远程会话(device-link 跨设备镜像 / SSH 远端 host)里,消息中的本机媒体 URL
 * (`xdt-image://` / `xdt-video://` / `xdt-file://` / `xdt-audio://`,以及媒体总仓
 * 的 `cindy-media://` blob 地址)指向的是**远端
 * 机器**的本地文件 / 缓存,控制端本机并没有这些字节 —— 原样渲染必然 404。本模块把
 * 这些 URL 改写成统一的:
 *
 *     cindy-remote-media://m/{b64url(originToken)}/{b64url(原始媒体URL)}
 *
 * 控制端 main 注册的 `cindy-remote-media://` handler 解出 (origin, 原始URL),按来源
 * 分流取字节(见 device-link/remoteMediaProtocol.ts):
 *   - device(跨设备):经 OSS 中转向被控端取(media:fetch,接受任意绝对路径);
 *   - ssh(远端 host):经 remote-file-service 分片拉到本地磁盘缓存再服务
 *     (只能读会话 workdir 内的文件,见 isSshRewritableMediaUrl)。
 *
 * originToken 线格式(见 encode/decodeRemoteMediaOriginToken):
 *   - device:**裸 deviceId 字符串**(与 ssh 支持引入前逐字节一致 —— device-link
 *     的既有 URL 形态零变化,gallery includes 匹配、缓存键等都不受影响);
 *   - ssh:JSON `{"k":"ssh","id":remoteHostId,"wd":workdir}`。带 workdir 是刻意的:
 *     原始 URL 里只有绝对路径,handler 无状态就能算出 workdir 相对路径去调
 *     file-service,不必反查会话表。
 *   - 解码兼容:非 JSON / 非法 JSON 一律按裸 deviceId 处理(URL 是渲染期临时产物、
 *     不落库,兼容层只为升级混跑窗口)。
 *
 * 设计要点:
 *  - **固定 host `m`**:token / 原始URL 都放进**路径段**。URL host 会被解析器强制
 *    小写(`new URL` 行为),而 deviceId 在本地联调时可被 `XDT_DEVICE_ID_OVERRIDE`
 *    设成任意大小写 —— 放 host 会被静默小写化导致两端 deviceId 对不上。路径段保留大小写。
 *  - **base64url 编码**:原始 URL 含 `://` `?` `/` 等字符,即便 percent-encode 也会干扰
 *    privileged scheme 的标准 URL 解析。base64url 产物只含 `[A-Za-z0-9_-]`,作为单个
 *    路径段绝对安全、无歧义。UTF-8 安全(CJK 文件名)、renderer(btoa/atob)与 main
 *    (Buffer)双环境通用。
 */

/** 远程媒体统一 scheme。 */
export const REMOTE_MEDIA_SCHEME = 'cindy-remote-media';
/** 固定 host 哨兵(避免把 deviceId 放 host 被小写化)。 */
export const REMOTE_MEDIA_HOST = 'm';

/**
 * 远程媒体来源(URL 线格式的判别单元):
 *  - device:device-link 被控端,经 OSS 中转,可取任意绝对路径;
 *  - ssh:SSH 远端 host,经 file-service 分片取回,只能读 workdir 内文件,
 *    故 token 必须携带会话 workdir。
 */
export type RemoteMediaOrigin =
  | { kind: 'device'; deviceId: string }
  | { kind: 'ssh'; remoteHostId: string; workdir: string };

/**
 * 需要在远程会话里改写的本机媒体 scheme 前缀(device 来源全量适用;ssh 来源
 * 另有更窄的白名单,见 isSshRewritableMediaUrl)。`xdt-model://`(3D)不在聊天
 * 媒体范围,暂不纳入;未来如需再加。cindy-media:// 是媒体总仓的内容寻址 blob
 * 地址(迁移后生成图/视频的新形态),字节同样只在被控端本机,必须经中转。
 */
export const LOCAL_MEDIA_SCHEMES = [
  'xdt-image://',
  'xdt-video://',
  'xdt-file://',
  'xdt-audio://',
  'cindy-media://',
] as const;

/** ssh 来源可改写的 scheme:只有这两个的 URL 带 `?path=` 绝对路径语义。 */
const SSH_PATH_SCHEMES = ['xdt-file://', 'xdt-audio://'] as const;

/** UTF-8 安全的 base64url 编码(无 padding,`+/`→`-_`),renderer/main 双环境通用。 */
export function toBase64Url(input: string): string {
  const bytes = new TextEncoder().encode(input);
  let binary = '';
  for (const b of bytes) binary += String.fromCharCode(b);
  const b64 =
    typeof btoa !== 'undefined'
      ? btoa(binary)
      : Buffer.from(binary, 'binary').toString('base64');
  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

/** toBase64Url 的逆:base64url → 原始 UTF-8 字符串。非法输入抛错(调用方需 try/catch)。 */
export function fromBase64Url(input: string): string {
  const b64 = input.replace(/-/g, '+').replace(/_/g, '/');
  const binary =
    typeof atob !== 'undefined'
      ? atob(b64)
      : Buffer.from(b64, 'base64').toString('binary');
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
  return new TextDecoder().decode(bytes);
}

/** origin → token 线格式(device 裸串保持既有 URL 逐字节稳定;ssh JSON)。 */
export function encodeRemoteMediaOriginToken(origin: RemoteMediaOrigin): string {
  if (origin.kind === 'device') return origin.deviceId;
  return JSON.stringify({ k: 'ssh', id: origin.remoteHostId, wd: origin.workdir });
}

/**
 * token 线格式 → origin。JSON 且判别字段合法 → 按类型解;其余(含非法 JSON、
 * 数字/布尔等偶然可解析值)一律按 legacy 裸 deviceId。空串 → null。
 */
export function decodeRemoteMediaOriginToken(token: string): RemoteMediaOrigin | null {
  if (!token) return null;
  if (token.startsWith('{')) {
    try {
      const parsed: unknown = JSON.parse(token);
      if (typeof parsed === 'object' && parsed !== null) {
        const rec = parsed as Record<string, unknown>;
        if (rec.k === 'ssh' && typeof rec.id === 'string' && rec.id && typeof rec.wd === 'string' && rec.wd) {
          return { kind: 'ssh', remoteHostId: rec.id, workdir: rec.wd };
        }
        // 预留:当前 encode 对 device 恒输出裸 deviceId(保持既有 URL 逐字节
        // 稳定),不会产生此 JSON 形态;保留解码宽容度是为未来 encode 若切换
        // JSON 形态时的混跑窗口,并把 token 语法完整性留在解码侧文档化。
        if (rec.k === 'dev' && typeof rec.id === 'string' && rec.id) {
          return { kind: 'device', deviceId: rec.id };
        }
        return null; // JSON 对象但判别不合法:按畸形拒绝,不当 deviceId 误用
      }
    } catch {
      // 非法 JSON → 按 legacy 裸 deviceId 处理
    }
  }
  return { kind: 'device', deviceId: token };
}

/** 该 URL 是否是「本机媒体 scheme」(device 来源下需要改写)。 */
export function isRewritableMediaUrl(url: unknown): url is string {
  return (
    typeof url === 'string' &&
    LOCAL_MEDIA_SCHEMES.some((scheme) => url.startsWith(scheme))
  );
}

/**
 * 从 `xdt-file://local/?path=<abs>` / `xdt-audio://…?path=<abs>` 提取绝对路径。
 * 非这两个 scheme / 无 path 参数 / 相对路径 → null。POSIX 与 Windows 盘符绝对
 * 路径都接受(device-link 被控端可能是 Windows;ssh 恒 POSIX,由调用方进一步约束)。
 */
export function extractMediaPathQuery(url: string): string | null {
  if (!SSH_PATH_SCHEMES.some((s) => url.startsWith(s))) return null;
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    return null;
  }
  const p = parsed.searchParams.get('path');
  if (!p) return null;
  const isAbs = p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
  return isAbs ? p : null;
}

/** POSIX 纯字符串包含判定:p 位于 dir 内(不含 dir 自身),拒绝 `..` 段。 */
function isPosixPathInside(dir: string, p: string): boolean {
  if (!dir.startsWith('/') || !p.startsWith('/')) return false;
  if (p.split('/').includes('..')) return false;
  const base = dir.replace(/\/+$/, '');
  return p.startsWith(`${base}/`) && p.length > base.length + 1;
}

/**
 * ssh 来源下该 URL 是否可改写:仅 `xdt-file://` / `xdt-audio://` 且 `?path=` 是
 * workdir 内的 POSIX 绝对路径。`xdt-image://` / `xdt-video://` 的 cache-id URL
 * 没有路径语义(字节在远端 daemon 数据目录、workdir 外),file-service 取不到,
 * 不改写 → 渲染层走「远端文件不可用」占位。
 */
export function isSshRewritableMediaUrl(url: unknown, workdir: string): url is string {
  if (typeof url !== 'string' || !workdir) return false;
  const p = extractMediaPathQuery(url);
  return p !== null && isPosixPathInside(workdir, p);
}

/** 组装远程媒体 URL(origin 任意来源)。 */
export function buildRemoteMediaUrl(origin: RemoteMediaOrigin, origUrl: string): string {
  const token = encodeRemoteMediaOriginToken(origin);
  return `${REMOTE_MEDIA_SCHEME}://${REMOTE_MEDIA_HOST}/${toBase64Url(token)}/${toBase64Url(origUrl)}`;
}

/** 该 URL 是否已是远程媒体 URL(避免二次改写)。 */
export function isRemoteMediaUrl(url: unknown): url is string {
  return typeof url === 'string' && url.startsWith(`${REMOTE_MEDIA_SCHEME}://`);
}

/**
 * 解析远程媒体 URL → { origin, origUrl }。非远程媒体 / 畸形 → null。
 * 控制端 main 的 `cindy-remote-media://` handler 用它把请求路由回正确来源 + 原始媒体引用。
 */
export function parseRemoteMediaUrl(
  url: string,
): { origin: RemoteMediaOrigin; origUrl: string } | null {
  if (!isRemoteMediaUrl(url)) return null;
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    return null;
  }
  if (parsed.host !== REMOTE_MEDIA_HOST) return null;
  // pathname 形如 /{b64url(originToken)}/{b64url(origUrl)}
  const segs = parsed.pathname.replace(/^\/+/, '').split('/');
  if (segs.length !== 2 || !segs[0] || !segs[1]) return null;
  try {
    const origin = decodeRemoteMediaOriginToken(fromBase64Url(segs[0]));
    const origUrl = fromBase64Url(segs[1]);
    if (!origin || !origUrl) return null;
    return { origin, origUrl };
  } catch {
    return null;
  }
}

/**
 * 远程会话媒体 URL 改写入口(按来源分流白名单):
 *  - origin 为空(本地会话)→ 原样返回,不改写。
 *  - 已是远程媒体 URL → 原样返回,避免二次包裹。
 *  - device 来源:LOCAL_MEDIA_SCHEMES 全量改写(media:fetch 都能取)。
 *  - ssh 来源:仅 workdir 内带路径的 xdt-file / xdt-audio(见 isSshRewritableMediaUrl)。
 *  - 其它(http(s)、data: 等)→ 原样返回。
 */
export function rewriteToRemoteMediaOrigin(
  url: string,
  origin: RemoteMediaOrigin | undefined,
): string {
  if (!origin) return url;
  if (isRemoteMediaUrl(url)) return url;
  if (origin.kind === 'device') {
    if (!isRewritableMediaUrl(url)) return url;
    return buildRemoteMediaUrl(origin, url);
  }
  if (!isSshRewritableMediaUrl(url, origin.workdir)) return url;
  return buildRemoteMediaUrl(origin, url);
}

/**
 * device-link 兼容入口(既有调用面:renderer 改写点全部走它)。行为与 ssh 支持
 * 引入前逐字节一致;ssh 来源的改写走 rewriteToRemoteMediaOrigin(PR3 起 renderer
 * 切换)。
 */
export function rewriteToRemoteMedia(url: string, deviceId: string | undefined): string {
  return rewriteToRemoteMediaOrigin(url, deviceId ? { kind: 'device', deviceId } : undefined);
}