@spzxg/cli-ui 0.3.1 → 0.6.0

package/src/board/folderDownload.ts

@@ -0,0 +1,161 @@
+// 工作区「下载整个文件夹」：逐级列目录、逐个读文件（经中枢），在浏览器里打成 ZIP 下载。
+// 有上限：文件数、总大小（读进内存再打包）；超了直接报出来，让用户进到更小的目录或单个下载，不会把页面撑爆。
+// 弱网 / 节点忙：每个请求失败了按退避重试几次；某个文件一直读不到（或读的时候被任务删了）就跳过，
+// 照样把其余的打包，失败的清单放进压缩包里的 FAILED_LIST_NAME，并告诉调用方。取消会中止正在传的请求。
+import { CenterError, type BoardBackend } from "../core/client.js";
+import { fmtSize } from "./fileKind.js";
+import { saveBlob } from "./fileOps.js";
+import { buildZip, type ZipEntry } from "./zip.js";
+
+export const FOLDER_MAX_FILES = 2000;
+export const FOLDER_MAX_BYTES = 300 * 1024 * 1024;
+/** 同时读几个文件：中枢 / 节点不被一个人的下载占满，浏览器连接也留给别的请求。 */
+const PARALLEL = 3;
+/** 每个请求最多试几次，两次之间等多久（毫秒；带 ±30% 浮动）。 */
+const ATTEMPTS = 3;
+const BACKOFF_MS = [1_000, 3_000];
+export const FAILED_LIST_NAME = "_下载失败的文件.txt";
+
+export type FolderProgress = { phase: "listing" | "reading" | "zipping"; files: number; total: number; bytes: number; totalBytes?: number; failed?: number; retrying?: string };
+export type FolderResult = { files: number; failed: Array<{ path: string; reason: string }> };
+export type FolderZip = FolderResult & { blob: Blob; name: string };
+export type ListOptions = { signal?: AbortSignal; backoff?: number[]; maxFiles?: number; maxBytes?: number };
+
+const abortError = () => new DOMException("已取消", "AbortError");
+const isAbort = (e: unknown) => e instanceof DOMException && e.name === "AbortError";
+
+/** 值得再试的失败：网络（超时、断线）、限流、中枢 / 节点临时出错。404、403 之类再试也一样。 */
+export function isTransient(error: unknown): boolean {
+  if (!(error instanceof CenterError)) return !isAbort(error);
+  return error.code === "NETWORK" || error.status === 429 || error.status === 408 || error.status >= 500 || error.code === "node_unreachable";
+}
+
+function sleep(ms: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    const t = setTimeout(() => { signal?.removeEventListener("abort", stop); resolve(); }, ms);
+    const stop = () => { clearTimeout(t); reject(abortError()); };
+    signal?.addEventListener("abort", stop, { once: true });
+  });
+}
+
+/** 失败了按退避再试（只试临时性的失败）。onRetry 告诉界面「正在重试」。 */
+export async function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal, onRetry?: (attempt: number, error: unknown) => void, backoff = BACKOFF_MS): Promise<T> {
+  for (let attempt = 1; ; attempt++) {
+    if (signal?.aborted) throw abortError();
+    try {
+      return await fn();
+    } catch (error) {
+      if (isAbort(error) || signal?.aborted) throw abortError();
+      if (attempt >= ATTEMPTS || !isTransient(error)) throw error;
+      onRetry?.(attempt, error);
+      const base = backoff[Math.min(attempt - 1, backoff.length - 1)] ?? 0;
+      await sleep(Math.round(base * (0.7 + Math.random() * 0.6)), signal);
+    }
+  }
+}
+
+/** 列出 dir 下所有文件（递归）。超过上限（缺省 FOLDER_MAX_FILES 个、FOLDER_MAX_BYTES）抛错。 */
+export async function listFolder(backend: BoardBackend, jobId: string, dir: string, opts: ListOptions = {}): Promise<Array<{ path: string; size: number; mtime: number }>> {
+  const { signal, backoff, maxFiles = FOLDER_MAX_FILES, maxBytes = FOLDER_MAX_BYTES } = opts;
+  const out: Array<{ path: string; size: number; mtime: number }> = [];
+  let bytes = 0;
+  const queue = [dir || "."];
+  while (queue.length) {
+    if (signal?.aborted) throw abortError();
+    const cur = queue.shift()!;
+    let res;
+    try {
+      res = await withRetry(() => backend.stat(jobId, cur), signal, undefined, backoff);
+    } catch (error) {
+      // 子目录在列的时候被任务删了：跳过它；要下载的目录本身没了照常报错。
+      if (cur !== (dir || ".") && error instanceof CenterError && error.status === 404) continue;
+      throw error;
+    }
+    if (res.type !== "dir") continue;
+    if (res.truncated) throw new Error(`「${cur === "." ? "工作区" : cur}」里文件太多，节点只列出了一部分；请进到更小的目录再下载`);
+    for (const e of res.entries) {
+      if (e.type === "dir") { queue.push(e.path); continue; }
+      out.push({ path: e.path, size: e.size, mtime: e.mtime });
+      bytes += e.size;
+      if (out.length > maxFiles) throw new Error(`文件超过 ${maxFiles} 个，请进到更小的目录再下载`);
+      if (bytes > maxBytes) throw new Error(`总大小超过 ${fmtSize(maxBytes)}，请进到更小的目录或单个下载`);
+    }
+  }
+  return out;
+}
+
+export type FolderOptions = { onProgress?: (p: FolderProgress) => void; signal?: AbortSignal; zipName?: string; backoff?: number[] };
+
+/** 打包下载 dir（"" = 整个工作区）到本地。返回打了几个文件、哪些没读到。 */
+export async function downloadFolder(backend: BoardBackend, jobId: string, dir: string, opts: FolderOptions = {}): Promise<FolderResult> {
+  const { blob, name, files, failed } = await zipFolder(backend, jobId, dir, opts);
+  saveBlob(blob, name);
+  return { files, failed };
+}
+
+/** 把 dir（"" = 整个工作区）打成 ZIP，返回 Blob（不下载；业务方可以自己上传到服务器）。 */
+export async function zipFolder(backend: BoardBackend, jobId: string, dir: string, opts: FolderOptions = {}): Promise<FolderZip> {
+  const { onProgress, signal } = opts;
+  onProgress?.({ phase: "listing", files: 0, total: 0, bytes: 0 });
+  const files = await listFolder(backend, jobId, dir, { signal, backoff: opts.backoff });
+  if (!files.length) throw new Error("这个目录里没有文件");
+  const totalBytes = files.reduce((n, f) => n + f.size, 0);
+  const base = dir ? `${dir.replace(/\/+$/, "")}/` : "";
+  const entries: Array<ZipEntry | null> = new Array(files.length).fill(null);
+  const failed: FolderResult["failed"] = [];
+  // 每个文件已收到的字节（含正在传的），进度条按它走：一个大文件慢慢传时也看得到在动。
+  const got = new Array<number>(files.length).fill(0);
+  let done = 0;
+  let next = 0;
+  let retrying: string | undefined;
+  let lastReport = 0;
+  const report = (force = false) => {
+    const now = Date.now();
+    if (!force && now - lastReport < 200) return;
+    lastReport = now;
+    onProgress?.({ phase: "reading", files: done, total: files.length, bytes: got.reduce((a, b) => a + b, 0), totalBytes, failed: failed.length, retrying });
+  };
+  const worker = async () => {
+    while (next < files.length) {
+      const i = next++;
+      if (signal?.aborted) throw abortError();
+      const f = files[i];
+      try {
+        const buffer = await withRetry(
+          () => { got[i] = 0; return backend.readBuffer(jobId, f.path, { signal, onBytes: (n) => { got[i] = n; report(); } }); },
+          signal,
+          () => { retrying = f.path; report(true); },
+          opts.backoff,
+        );
+        const data = new Uint8Array(buffer);
+        got[i] = data.length;
+        // 任务在写、文件比列的时候大了很多：总量还是要守住上限。
+        if (got.reduce((a, b) => a + b, 0) > FOLDER_MAX_BYTES * 1.1) throw new Error(`读到的总大小超过 ${fmtSize(FOLDER_MAX_BYTES)}（文件还在变大），请进到更小的目录或单个下载`);
+        // ZIP 里的路径相对下载的目录（文件夹名本身作为 ZIP 文件名）。
+        entries[i] = { path: f.path.startsWith(base) ? f.path.slice(base.length) : f.path, data, mtime: f.mtime };
+      } catch (error) {
+        if (isAbort(error) || signal?.aborted) throw abortError();
+        if (!(error instanceof CenterError)) throw error;
+        got[i] = 0;
+        failed.push({ path: f.path, reason: error.message });
+      }
+      if (retrying === f.path) retrying = undefined;
+      done++;
+      report(true);
+    }
+  };
+  // 列完马上报「读取 0 / N」：网络慢时第一个文件要好一会儿才有字节，不能一直停在「正在列出」。
+  report(true);
+  await Promise.all(Array.from({ length: Math.min(PARALLEL, files.length) }, worker));
+  const ok = entries.filter((e): e is ZipEntry => !!e);
+  if (!ok.length) throw new Error(`${failed.length} 个文件都没读到：${failed[0]?.reason ?? "未知原因"}`);
+  onProgress?.({ phase: "zipping", files: done, total: files.length, bytes: got.reduce((a, b) => a + b, 0), totalBytes, failed: failed.length });
+  if (failed.length) {
+    const list = ["下面这些文件没有下载下来（其余文件都在压缩包里）：", "", ...failed.map((f) => `${f.path}\t${f.reason}`), ""].join("\n");
+    ok.push({ path: FAILED_LIST_NAME, data: new TextEncoder().encode(list) as Uint8Array<ArrayBuffer> });
+  }
+  const blob = buildZip(ok);
+  const name = opts.zipName ?? `${(dir.split("/").filter(Boolean).pop() || "工作区")}.zip`;
+  return { blob, name, files: ok.length - (failed.length ? 1 : 0), failed };
+}

package/src/board/workspace.ts

@@ -0,0 +1,129 @@
+/**
+ * 给业务方的工作区接口：不显示看板也能拿到任务产出的文件。
+ *
+ *   const ws = store.workspace("job_xxx");        // 不传 = 当前选中的对话；Web Component：el.workspace()
+ *   await ws.listAll();                            // 工作区里所有文件（递归）
+ *   await ws.readText("reports/报告.md");          // 读成文字
+ *   await ws.readFile("reports/图.png");           // 读成 Blob（可以自己上传）
+ *   await ws.zip("reports");                       // 打成 ZIP 的 Blob
+ *   await ws.download("reports/报告.md");          // 下载到用户本地；ws.downloadFolder("reports") 打包下载
+ *   ws.openFile();                                 // 看板上正在看的文件（没有看板 / 没打开文件时为 null）
+ *
+ * 数据都经中枢读执行节点（和看板一样），弱网时按网络错误（CenterError，code = "NETWORK"）失败，可以重试。
+ */
+import type { BoardBackend } from "../core/client.js";
+import type { BoardInfo, FileEntry } from "../core/types.js";
+import { directFileUrl, downloadFile, mimeOf } from "./fileOps.js";
+import { fmtSize } from "./fileKind.js";
+import { downloadFolder, listFolder, zipFolder, type FolderOptions, type FolderResult, type FolderZip } from "./folderDownload.js";
+
+/** readText 最多读这么大（更大的用 readFile）。 */
+export const WORKSPACE_TEXT_MAX = 20 * 1024 * 1024;
+/** readFile 最多读这么大进内存（更大的用 fileUrl / download，浏览器流式下载）。 */
+export const WORKSPACE_FILE_MAX = 500 * 1024 * 1024;
+/** listAll 最多列这么多个文件。 */
+export const WORKSPACE_LIST_MAX = 10_000;
+
+/** 看板现在的样子（看板组件报告给仓库；没有看板时没有）。 */
+export interface BoardView {
+  /** 当前页签：files / changes / browser、"file:<路径>"（打开的文件）或自己加的页签 id。 */
+  tab: string;
+  /** 文件列表所在目录（"" = 工作区根目录）。 */
+  dir: string;
+  /** 正在看的文件（当前页签是文件时），否则 null。 */
+  file: string | null;
+  /** 开着的文件页签。 */
+  files: string[];
+}
+
+export interface CliWorkspace {
+  /** 这个工作区属于哪个对话（对话键）。 */
+  readonly jobId: string;
+  /** 看板概况：派发到节点没有、节点是否在线、有没有浏览器。 */
+  info(): Promise<BoardInfo>;
+  /** 列一个目录（不递归）。 */
+  list(dir?: string): Promise<FileEntry[]>;
+  /** 列 dir 下所有文件（递归，只含文件）。 */
+  listAll(dir?: string, opts?: { signal?: AbortSignal }): Promise<FileEntry[]>;
+  /** 读成文字（GBK 导出的文件会自动转码）。 */
+  readText(path: string): Promise<string>;
+  /** 读成 Blob。onProgress 报已收到的字节数；超过 maxBytes（缺省 500 MB）报错，改用 fileUrl / download。 */
+  readFile(path: string, opts?: { signal?: AbortSignal; onProgress?: (bytes: number) => void; maxBytes?: number }): Promise<Blob>;
+  /** 浏览器能直接打开 / 下载的地址（没有同源代理时是 30 分钟有效的短期链接）；接入方式不支持时为 null，改用 readFile。 */
+  fileUrl(path: string, opts?: { download?: boolean }): Promise<string | null>;
+  /** 下载一个文件到用户本地。 */
+  download(path: string): Promise<void>;
+  /** 把目录打包成 ZIP 下载到用户本地（"" = 整个工作区）。 */
+  downloadFolder(dir?: string, opts?: FolderOptions): Promise<FolderResult>;
+  /** 把目录打成 ZIP，返回 Blob，不下载。 */
+  zip(dir?: string, opts?: FolderOptions): Promise<FolderZip>;
+  /** 看板上正在看的文件；没有看板或没打开文件时为 null。 */
+  openFile(): string | null;
+  /** 看板上开着的所有文件页签。 */
+  openFiles(): string[];
+  /** 在看板里打开这个文件（没有看板接时返回 false）。 */
+  open(path: string): boolean;
+}
+
+export function createWorkspace(deps: {
+  backend: BoardBackend | undefined;
+  key: string;
+  view: () => BoardView | undefined;
+  open: (path: string) => boolean;
+}): CliWorkspace {
+  const { key } = deps;
+  const backend = () => {
+    if (!deps.backend) throw new Error("当前后端不支持读取工作区文件（需要任务中心的看板接口）");
+    return deps.backend;
+  };
+  const clean = (path: string) => path.replace(/^\.\//, "").replace(/\/+$/, "");
+  return {
+    jobId: key,
+    info: () => backend().info(key),
+    async list(dir = "") {
+      const res = await backend().stat(key, clean(dir) || ".");
+      if (res.type !== "dir") throw new Error(`「${dir}」不是目录`);
+      return res.entries;
+    },
+    async listAll(dir = "", opts = {}) {
+      const files = await listFolder(backend(), key, clean(dir), { signal: opts.signal, maxFiles: WORKSPACE_LIST_MAX, maxBytes: Infinity });
+      return files.map((f) => ({ name: f.path.split("/").pop() || f.path, path: f.path, type: "file" as const, size: f.size, mtime: f.mtime }));
+    },
+    async readText(path) {
+      const r = await backend().readText(key, clean(path), WORKSPACE_TEXT_MAX);
+      if (r.truncated) throw new Error(`文件较大（超过 ${WORKSPACE_TEXT_MAX / 1024 / 1024} MB），请用 readFile 读成 Blob`);
+      return r.text;
+    },
+    async readFile(path, opts = {}) {
+      const p = clean(path);
+      // 太大的读到一半就停：整个读进内存会把页面撑爆。
+      const ctl = new AbortController();
+      const stop = () => ctl.abort();
+      opts.signal?.addEventListener("abort", stop, { once: true });
+      let tooBig = false;
+      const max = opts.maxBytes ?? WORKSPACE_FILE_MAX;
+      try {
+        const buffer = await backend().readBuffer(key, p, {
+          signal: ctl.signal,
+          onBytes: (n) => { if (n > max) { tooBig = true; ctl.abort(); } else opts.onProgress?.(n); },
+        });
+        return new Blob([buffer], { type: mimeOf(p) });
+      } catch (error) {
+        if (tooBig) throw new Error(`文件超过 ${fmtSize(max)}，请用 fileUrl / download（浏览器流式下载，不占内存）`);
+        throw error;
+      } finally {
+        opts.signal?.removeEventListener("abort", stop);
+      }
+    },
+    async fileUrl(path, opts = {}) {
+      const url = await directFileUrl(backend(), key, clean(path), opts.download);
+      return url && typeof location !== "undefined" ? new URL(url, location.href).href : url;
+    },
+    download: (path) => downloadFile(backend(), key, clean(path)),
+    downloadFolder: (dir = "", opts) => downloadFolder(backend(), key, clean(dir), opts),
+    zip: (dir = "", opts) => zipFolder(backend(), key, clean(dir), opts),
+    openFile: () => deps.view()?.file ?? null,
+    openFiles: () => [...(deps.view()?.files ?? [])],
+    open: (path) => deps.open(clean(path)),
+  };
+}

package/src/board/zip.ts

@@ -0,0 +1,85 @@
+// 在浏览器里把几个文件打成 ZIP（只存储、不压缩）：工作区「下载整个文件夹」用。
+// 中枢 / 节点没有打包接口，文件逐个经中枢读回来，在这里拼成一个 ZIP 交给浏览器下载。
+// 不压缩：报告、图片、表格多半已经压缩过，存储模式快、内存只多一份目录表；文件名按 UTF-8 标记（中文名不乱码）。
+// 不支持 ZIP64：调用方限制了总大小（远小于 4 GB）和文件数。
+
+export type ZipEntry = { path: string; data: Uint8Array<ArrayBuffer>; mtime?: number };
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c >>> 0;
+  }
+  return t;
+})();
+
+export function crc32(data: Uint8Array): number {
+  let c = 0xffffffff;
+  for (let i = 0; i < data.length; i++) c = CRC_TABLE[(c ^ data[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** DOS 时间 / 日期（ZIP 头里用）。 */
+function dosTime(ms: number | undefined): { time: number; date: number } {
+  const d = new Date(ms && ms > 0 ? ms : Date.now());
+  const year = Math.max(1980, d.getFullYear());
+  return {
+    time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+    date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+  };
+}
+
+export function buildZip(entries: ZipEntry[]): Blob {
+  const enc = new TextEncoder();
+  const parts: BlobPart[] = [];
+  const central: Uint8Array<ArrayBuffer>[] = [];
+  let offset = 0;
+  for (const e of entries) {
+    const name = enc.encode(e.path.replace(/^\/+/, ""));
+    const crc = crc32(e.data);
+    const { time, date } = dosTime(e.mtime);
+    const local = new Uint8Array(30 + name.length);
+    const lv = new DataView(local.buffer);
+    lv.setUint32(0, 0x04034b50, true);
+    lv.setUint16(4, 20, true);
+    lv.setUint16(6, 0x0800, true); // 文件名是 UTF-8
+    lv.setUint16(8, 0, true); // 存储
+    lv.setUint16(10, time, true);
+    lv.setUint16(12, date, true);
+    lv.setUint32(14, crc, true);
+    lv.setUint32(18, e.data.length, true);
+    lv.setUint32(22, e.data.length, true);
+    lv.setUint16(26, name.length, true);
+    local.set(name, 30);
+    parts.push(local, e.data);
+
+    const head = new Uint8Array(46 + name.length);
+    const cv = new DataView(head.buffer);
+    cv.setUint32(0, 0x02014b50, true);
+    cv.setUint16(4, 20, true);
+    cv.setUint16(6, 20, true);
+    cv.setUint16(8, 0x0800, true);
+    cv.setUint16(10, 0, true);
+    cv.setUint16(12, time, true);
+    cv.setUint16(14, date, true);
+    cv.setUint32(16, crc, true);
+    cv.setUint32(20, e.data.length, true);
+    cv.setUint32(24, e.data.length, true);
+    cv.setUint16(28, name.length, true);
+    cv.setUint32(42, offset, true);
+    head.set(name, 46);
+    central.push(head);
+    offset += local.length + e.data.length;
+  }
+  const centralSize = central.reduce((n, c) => n + c.length, 0);
+  const end = new Uint8Array(22);
+  const ev = new DataView(end.buffer);
+  ev.setUint32(0, 0x06054b50, true);
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, centralSize, true);
+  ev.setUint32(16, offset, true);
+  return new Blob([...parts, ...central, end], { type: "application/zip" });
+}