@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/board/fileSyncProcessor.ts

@@ -0,0 +1,72 @@
+import { decodeText } from "../core/textDecode";
+import { sha256 } from "../core/sha256";
+
+const aborted = () => new DOMException("文件同步已取消", "AbortError");
+const integrity = (message: string) => Object.assign(new Error(message), { status: 422, code: "integrity" });
+const digest = async (bytes: Uint8Array<ArrayBuffer>) => globalThis.crypto?.subtle ? [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))].map(byte => byte.toString(16).padStart(2, "0")).join("") : sha256(bytes);
+type Processed = { bytes: Uint8Array<ArrayBuffer>; text?: string; encoding?: string };
+
+/** One worker owns the assembled buffer; chunks are transferred, not copied into a second main-thread file. */
+export class FileSyncProcessor {
+  private worker: Worker | null = null;
+  private url: string | null = null;
+  private sequence = 0;
+  private pending = new Map<number, { resolve: (value: any) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private output: Uint8Array<ArrayBuffer> | null = null;
+  private offset = 0;
+  private size = 0;
+  private stopped = false;
+  private failed: Error | null = null;
+  constructor(private signal: AbortSignal) {
+    if (typeof Worker !== "undefined" && typeof URL.createObjectURL === "function") try {
+      const script = `const decode=${decodeText.toString()},fallback=${sha256.toString()};let output=null,offset=0;
+const hash=async b=>globalThis.crypto?.subtle?Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256',b)),v=>v.toString(16).padStart(2,'0')).join(''):fallback(b instanceof Uint8Array?b:new Uint8Array(b));
+onmessage=async({data:m})=>{try{let value;
+if(m.op==='start'){output=new Uint8Array(m.size);offset=0;value=true;}
+if(m.op==='verify'){if(await hash(m.bytes)!==m.hash)throw Error('文件块校验失败');value={bytes:m.bytes};}
+if(m.op==='append'){if(!output||offset+m.bytes.byteLength>output.length||await hash(m.bytes)!==m.hash)throw Error('文件块校验失败');output.set(new Uint8Array(m.bytes),offset);offset+=m.bytes.byteLength;value=true;}
+if(m.op==='finish'){if(!output||offset!==output.length||(m.hash&&await hash(output)!==m.hash))throw Error('完整文件校验失败');const bytes=m.start===0&&m.length===output.length?output:output.slice(m.start,m.start+m.length);const decoded=m.decode?decode(bytes,{fromMiddle:m.fromMiddle}):{};value={bytes:bytes.buffer,...decoded};output=null;}
+postMessage({id:m.id,value},value&&value.bytes?[value.bytes]:[]);}catch(error){postMessage({id:m.id,error:error.message});}};`;
+      this.url = URL.createObjectURL(new Blob([script], { type: "text/javascript" }));
+      this.worker = new Worker(this.url);
+      this.worker.onmessage = event => { const item = this.pending.get(event.data.id); if (!item) return; this.pending.delete(event.data.id); clearTimeout(item.timer); if (event.data.error) item.reject(integrity(event.data.error)); else item.resolve(event.data.value); };
+      this.worker.onerror = () => this.fail(new Error("文件校验 Worker 不可用"));
+    } catch { this.worker?.terminate(); this.worker = null; }
+    signal.addEventListener("abort", this.cancel, { once: true });
+  }
+  private fail(error: Error) { this.failed = error; this.worker?.terminate(); this.worker = null; for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(error); } this.pending.clear(); }
+  private cancel = () => { this.stopped = true; this.worker?.terminate(); for (const item of this.pending.values()) { clearTimeout(item.timer); item.reject(aborted()); } this.pending.clear(); this.output = null; };
+  private check() { if (this.stopped || this.signal.aborted) throw aborted(); if (this.failed) throw this.failed; }
+  private rpc(op: string, data: Record<string, unknown>, transfers: Transferable[] = []) {
+    this.check();
+    return new Promise<any>((resolve, reject) => { const id = ++this.sequence, timer = setTimeout(() => this.fail(new Error("文件校验 Worker 超时")), op === "start" ? 5000 : 120_000); this.pending.set(id, { resolve, reject, timer }); try { this.worker!.postMessage({ id, op, ...data }, transfers); } catch (error) { this.pending.delete(id); clearTimeout(timer); reject(error); } });
+  }
+  async start(size: number) {
+    this.check();
+    this.size = size;
+    if (this.worker) {
+      try { await this.rpc("start", { size }); return; }
+      catch (error) { if (this.signal.aborted || this.stopped) throw aborted(); this.worker?.terminate(); this.worker = null; this.failed = null; if (error instanceof DOMException && error.name === "AbortError") throw error; }
+    }
+    this.output = new Uint8Array(size); this.offset = 0;
+  }
+  async verify(bytes: Uint8Array<ArrayBuffer>, hash: string): Promise<Uint8Array<ArrayBuffer>> {
+    this.check();
+    if (this.worker) { const result = await this.rpc("verify", { bytes: bytes.buffer, hash }, [bytes.buffer]); this.check(); return new Uint8Array(result.bytes); }
+    if (await digest(bytes) !== hash) throw integrity("文件块校验失败"); this.check(); return bytes;
+  }
+  async append(bytes: Uint8Array<ArrayBuffer>, hash: string) {
+    this.check();
+    if (this.worker) { await this.rpc("append", { bytes: bytes.buffer, hash }, [bytes.buffer]); this.check(); return; }
+    if (!this.output || this.offset + bytes.length > this.output.length || await digest(bytes) !== hash) throw integrity("文件块校验失败");
+    this.check(); this.output.set(bytes, this.offset); this.offset += bytes.length;
+  }
+  async finish(hash: string | null, decode: boolean, range = { start: 0, length: this.size, fromMiddle: false }): Promise<Processed> {
+    this.check();
+    if (this.worker) { const result = await this.rpc("finish", { hash, decode, ...range }); this.check(); return { ...result, bytes: new Uint8Array(result.bytes) }; }
+    if (!this.output || this.offset !== this.output.length || (hash && await digest(this.output) !== hash)) throw integrity("完整文件校验失败");
+    this.check(); const bytes = range.start === 0 && range.length === this.output.length ? this.output : this.output.slice(range.start, range.start + range.length);
+    return { bytes, ...(decode ? decodeText(bytes, { fromMiddle: range.fromMiddle }) : {}) };
+  }
+  dispose() { this.signal.removeEventListener("abort", this.cancel); this.cancel(); if (this.url) URL.revokeObjectURL(this.url); }
+}

package/src/board/fileSyncQueue.ts

@@ -0,0 +1,56 @@
+/** A finite FIFO for one transport. Waiting work never owns a buffer or request. */
+export function createFileWorkQueue(concurrency: number, maxQueued = 128, waitMs = 180_000) {
+  let active = 0;
+  type Waiting = { start: () => void; cancel: () => void };
+  const waiting: Waiting[] = [];
+  const drain = () => { while (active < concurrency && waiting.length) waiting.shift()!.start(); };
+  return {
+    run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+      return new Promise<T>((resolve, reject) => {
+        const abort = () => new DOMException("文件同步已取消", "AbortError");
+        if (signal?.aborted) { reject(abort()); return; }
+        if (active >= concurrency && waiting.length >= maxQueued) {
+          reject(Object.assign(new Error("文件同步队列繁忙，请稍后重试"), { status: 429, code: "client_queue_full", retryAfterMs: 1000 })); return;
+        }
+        let started = false, running = false, settled = false, released = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const settle = (ok: boolean, result: unknown) => {
+          if (settled) return;
+          settled = true; signal?.removeEventListener("abort", item.cancel);
+          if (timer !== undefined) clearTimeout(timer);
+          if (ok) resolve(result as T); else reject(result);
+        };
+        const release = () => {
+          if (released) return;
+          released = true;
+          if (started) active--;
+          else { const index = waiting.indexOf(item); if (index !== -1) waiting.splice(index, 1); }
+          drain();
+        };
+        const finish = (ok: boolean, result: unknown) => { settle(ok, result); release(); };
+        const item: Waiting = {
+          start: () => {
+            if (settled) return;
+            if (timer !== undefined) clearTimeout(timer);
+            started = true; active++;
+            // A caller can cancel before this microtask starts; do not execute retired work.
+            void Promise.resolve().then(() => { if (settled) throw abort(); running = true; return work(); }).then(value => finish(true, value), error => finish(false, error));
+          },
+          cancel: () => {
+            settle(false, abort());
+            // Uncooperative legacy hosts may ignore cancellation. Keep their actual
+            // request/buffer counted until work settles, while rejecting the caller now.
+            if (!running) release();
+          },
+        };
+        signal?.addEventListener("abort", item.cancel, { once: true });
+        if (active < concurrency) item.start();
+        else {
+          waiting.push(item);
+          timer = setTimeout(() => finish(false, Object.assign(new Error("文件同步等待超时，请稍后重试"), { status: 429, code: "client_queue_timeout", retryAfterMs: 1000 })), waitMs);
+        }
+        if (signal?.aborted) item.cancel();
+      });
+    },
+  };
+}

package/src/board/fileSyncTransport.ts

@@ -0,0 +1,85 @@
+import { FileSyncError, validateFileSyncManifest, type FileSyncManifest, type FileSyncTransport } from "./fileSync";
+
+const MANIFEST_MAX = 2 * 1024 * 1024;
+const BATCH_MAX = 1024 * 1024;
+const abortError = () => new DOMException("文件同步已取消", "AbortError");
+
+/** Short, bounded requests only; a 304 is reusable only in the same authenticated namespace. */
+export function createFileSyncTransport(fetcher: typeof fetch, pathBuilder: (jobId: string, operation: "manifest" | "chunks") => string,
+  headers: () => Record<string, string> = () => ({}), options: { requestTimeoutMs?: number } = {}): FileSyncTransport {
+  const namespaces = new Map<string, string>();
+  const call = async (url: string, init: RequestInit, limit: number, signal?: AbortSignal) => {
+    if (signal?.aborted) throw abortError();
+    const controller = new AbortController(); let timedOut = false;
+    const cancel = () => controller.abort(); signal?.addEventListener("abort", cancel, { once: true });
+    const timer = setTimeout(() => { timedOut = true; controller.abort(); }, options.requestTimeoutMs ?? 30_000);
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+    const stopped = new Promise<never>((_resolve, reject) => controller.signal.addEventListener("abort", () => reject(signal?.aborted ? abortError() : new FileSyncError("文件同步请求超时", 0, "timeout")), { once: true }));
+    try {
+      const fetching = fetcher(url, { ...init, headers: { ...headers(), ...init.headers }, signal: controller.signal, cache: "no-store" });
+      void fetching.then(response => { if (controller.signal.aborted) void response.body?.cancel().catch(() => undefined); }, () => undefined);
+      const response = await Promise.race([fetching, stopped]);
+      if (response.status === 304) { void response.body?.cancel().catch(() => undefined); return { response, bytes: new Uint8Array(0) }; }
+      const maximum = response.ok && response.status !== 202 ? limit : 8192;
+      const declared = Number(response.headers.get("Content-Length") ?? 0);
+      if (declared > maximum) { void response.body?.cancel().catch(() => undefined); throw new FileSyncError("文件同步响应超过协议上限", response.status, "response_too_large"); }
+      reader = response.body?.getReader();
+      const parts: Uint8Array[] = []; let size = 0;
+      if (reader) {
+        while (true) {
+          const next = await Promise.race([reader.read(), stopped]);
+          if (next.done) break;
+          size += next.value.byteLength;
+          if (size > maximum) throw new FileSyncError("文件同步响应超过协议上限", response.status, "response_too_large");
+          parts.push(next.value);
+        }
+      }
+      const bytes = new Uint8Array(size); let offset = 0;
+      for (const part of parts) { bytes.set(part, offset); offset += part.byteLength; }
+      if (!response.ok || response.status === 202) {
+        let error: { error?: string; detail?: string } = {};
+        try { error = JSON.parse(new TextDecoder().decode(bytes)); } catch { /* Status remains authoritative. */ }
+        const retry = response.headers.get("Retry-After");
+        const retryAfterMs = retry ? (/^\d+(\.\d+)?$/.test(retry) ? Number(retry) * 1000 : Math.max(0, Date.parse(retry) - Date.now())) : undefined;
+        const missingRoute = response.status === 501 || (response.status === 404 && !["file_not_found", "task_not_found", "job_not_found"].includes(error.error ?? ""));
+        const code = missingRoute ? "unsupported" : error.error ?? "http_error";
+        const common: Record<string, string> = { node_unreachable: "执行节点暂时连不上，请稍后重试", unsupported: "服务端尚未支持大文件增量同步，请升级节点和中枢", file_sync_unsupported: "服务端尚未支持大文件增量同步，请升级节点和中枢", file_not_found: "文件不存在（可能已删除或改名）", file_forbidden: error.detail || "文件不在当前任务允许访问的目录中，或没有访问权限", file_sync_busy: "文件服务繁忙，请稍后重试", too_many_snapshot_builds: "文件服务繁忙，请稍后重试", too_many_uploads: "上传任务较多，请稍后重试", file_sync_queue_timeout: "文件处理排队超时，请稍后重试", file_sync_timeout: "文件服务响应超时，请重试", snapshot_cache_full: "文件缓存空间不足，请稍后重试", upload_storage_full: "文件上传空间不足，请稍后重试" };
+        const message = response.status === 401 ? "登录已失效，请重新登录" : common[code] ?? (response.status === 403 ? error.detail || "没有读取该文件的权限，请检查任务访问权限" : error.detail ?? `文件同步失败（HTTP ${response.status})`);
+        throw new FileSyncError(message, response.status, code, retryAfterMs);
+      }
+      return { response, bytes };
+    } catch (error) {
+      if (signal?.aborted) throw abortError();
+      if (timedOut) throw new FileSyncError("文件同步请求超时", 0, "timeout");
+      throw error;
+    } finally {
+      clearTimeout(timer); signal?.removeEventListener("abort", cancel);
+      if (reader) { void reader.cancel().catch(() => undefined); try { reader.releaseLock(); } catch { /* A cancelled read can still be retiring. */ } }
+    }
+  };
+  return {
+    async manifest(jobId, path, settings = {}) {
+      const key = JSON.stringify([jobId, path]);
+      const read = async (revision?: string): Promise<FileSyncManifest | null> => {
+        const endpoint = pathBuilder(jobId, "manifest"), url = `${endpoint}${endpoint.includes("?") ? "&" : "?"}path=${encodeURIComponent(path)}`;
+        const { response, bytes } = await call(url, { headers: revision ? { "If-None-Match": `"${revision}"` } : {} }, MANIFEST_MAX, settings.signal);
+        if (response.status === 304) {
+          const namespace = response.headers.get("X-File-Sync-Namespace");
+          if (revision && namespace && namespace === namespaces.get(key)) return null;
+          if (revision) return read();
+          throw new FileSyncError("文件修订清单缺失", 502, "invalid_manifest");
+        }
+        let manifest: FileSyncManifest;
+        try { manifest = validateFileSyncManifest(JSON.parse(new TextDecoder().decode(bytes))); }
+        catch (error) { throw error instanceof FileSyncError ? error : new FileSyncError("文件修订清单格式错误", 502, "invalid_manifest"); }
+        namespaces.set(key, manifest.namespace); return manifest;
+      };
+      return read(settings.revision);
+    },
+    async chunks(jobId, input, settings = {}) {
+      if (!input.ids.length) return new Uint8Array(0);
+      const { bytes } = await call(pathBuilder(jobId, "chunks"), { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input) }, BATCH_MAX, settings.signal);
+      return bytes;
+    },
+  };
+}

package/src/board/fileWatch.ts

@@ -0,0 +1,211 @@
+import { type BoardBackend } from '../core/client';
+import { notifyCallback } from '../core/callbacks';
+import type { FileEntry, WorkspaceChangeEvent, WorkspaceFileBatch, WorkspaceFileChange, WorkspaceWatchStatus } from '../core/types';
+import { denyFileScope, onFileScope, readFileScope, retainFileScope } from './fileScope';
+import { onFilePreviewScope, refreshFilePreviews } from './fileSync';
+import { createFileWorkQueue } from './fileSyncQueue';
+export interface WorkspaceWatchOptions { /** @deprecated Retained for compatibility; checks are event-driven, never periodic. */ intervalMs?:number; paths?:readonly string[]; dirs?:readonly string[]; onStatus?:(status:WorkspaceWatchStatus)=>void }
+type Listener={change:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']};
+export interface WorkspaceRefreshOptions { manual?:boolean }
+type Entry={listeners:Set<Listener>;stop:()=>void;retry:(manual?:boolean)=>void;status:WorkspaceWatchStatus};
+export function cloneWorkspaceChange(event:WorkspaceChangeEvent):WorkspaceChangeEvent {return {...event,changes:event.changes.map(change=>({...change,file:change.file?{...change.file}:undefined,previous:change.previous?{...change.previous}:undefined}))};}
+const registries=new WeakMap<BoardBackend,Map<string,Entry>>();
+const metadataQueues=new WeakMap<BoardBackend,ReturnType<typeof createFileWorkQueue>>();
+function metadataQueue(backend:BoardBackend){
+ let queue=metadataQueues.get(backend);if(!queue){queue=createFileWorkQueue(4,128);metadataQueues.set(backend,queue);}return queue;
+}
+export function retryWorkspaceFiles(backend:BoardBackend,jobId:string,options:WorkspaceRefreshOptions={}):void {registries.get(backend)?.get(jobId)?.retry(options.manual);}
+const fingerprint=(file:FileEntry)=>`${file.type}:${file.size}:${file.mtime}:${file.changeToken??''}`;
+const validFile=(file:FileEntry)=>!!file&&typeof file.path==='string'&&typeof file.name==='string'&&['file','dir'].includes(file.type)&&Number.isFinite(file.size)&&Number.isFinite(file.mtime);
+const invalidResponse=(message:string)=>Object.assign(new Error(message),{status:502,code:'invalid_response'});
+/** Shared event-driven HTTP checks. No recurring file timer or file event connection. */
+export function subscribeWorkspaceFiles(backend:BoardBackend,jobId:string,listener:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}):()=>void {
+ const releaseOwnedScope=options.paths?.length||options.dirs?.length?retainFileScope(backend,jobId,{paths:[...options.paths??[]],dirs:[...options.dirs??[]]}):()=>{};
+ let jobs=registries.get(backend);if(!jobs){jobs=new Map();registries.set(backend,jobs);}
+ let entry=jobs.get(jobId);
+ if(!entry){
+  // Keep the public transport value for compatibility; it denotes bounded HTTP, not a timer.
+  const statusBase={type:'files_watch' as const,jobId,mode:'poll' as const,coverage:'listed-files' as const,complete:false};
+  entry={listeners:new Set(),stop:()=>{},retry:()=>{},status:{...statusBase,state:'connecting'}};jobs.set(jobId,entry);
+  const owned=entry;
+  let alive=true,controller:AbortController|null=null,timer:ReturnType<typeof setTimeout>|undefined,failed=0,generation=0,dirty=false;
+  let scopeKey=JSON.stringify(readFileScope(backend,jobId));
+  const retryDelays=[1000,2000,4000];
+  let serverNotBefore=0,retryAt=0,exhaustedUntil=0;
+  const requests=metadataQueue(backend);
+  let baseline=new Map<string,FileEntry>(),directories=new Map<string,string|null>(),cursors=new Map<string,string>();
+  let known=new Set<string>();
+  type ScanState={baseline:Map<string,FileEntry>;known:Set<string>};
+  const status=(state:WorkspaceWatchStatus['state'],error?:string)=>{owned.status={...statusBase,state,...(error?{error}:{})};for(const item of [...owned.listeners])notifyCallback(item.status,{...owned.status});};
+  const publish=(changes:WorkspaceFileChange[],revision?:string)=>{
+   if(!alive||!changes.length)return;
+   const event:WorkspaceChangeEvent={type:'files_changed',jobId,mode:'poll',coverage:'listed-files',complete:false,changes,revision};
+   for(const item of [...owned.listeners])notifyCallback(item.change,cloneWorkspaceChange(event));
+  };
+  const snapshot=(files:FileEntry[],paths:string[],state:ScanState):WorkspaceFileChange[]=>{
+   if(!Array.isArray(files)||!files.every(validFile))throw invalidResponse('文件变化响应不完整，请重试');
+   const current=new Map(files.map(file=>[file.path,file])),changes:WorkspaceFileChange[]=[];
+   for(const path of paths){
+    const file=current.get(path),previous=state.baseline.get(path);
+    if(state.known.has(path)){
+     if(file&&!previous)changes.push({kind:'created',path,file});
+     else if(!file&&previous)changes.push({kind:'deleted',path,previous});
+     else if(file&&previous&&fingerprint(file)!==fingerprint(previous))changes.push({kind:'modified',path,file,previous});
+    }
+    state.known.add(path);if(file)state.baseline.set(path,{...file});else state.baseline.delete(path);
+   }
+   return changes;
+  };
+  const accept=(batch:WorkspaceFileBatch,paths:string[],state:ScanState)=>{
+   if(batch.type==='resync')return [];
+   if(batch.type==='snapshot')return snapshot(batch.files,paths,state);
+   if(batch.type!=='changes'||!Array.isArray(batch.changes)||batch.changes.some(change=>!change||!paths.includes(change.path)||!['created','modified','deleted'].includes(change.kind)||(change.file&&!validFile(change.file))))throw invalidResponse('文件变化响应不完整，请重试');
+   for(const change of batch.changes){state.known.add(change.path);if(change.kind==='deleted')state.baseline.delete(change.path);else if(change.file)state.baseline.set(change.path,{...change.file});}
+   return batch.changes;
+  };
+  const hidden=()=>typeof document!=='undefined'&&document.visibilityState==='hidden';
+  const scan=async()=>{
+   if(!alive||controller||hidden())return;
+   // A real event retained during cooldown starts one new bounded attempt wave.
+   if(dirty&&exhaustedUntil&&Date.now()>=exhaustedUntil){failed=0;exhaustedUntil=0;}
+   clearTimer();dirty=false;
+   const scope=readFileScope(backend,jobId);
+   // No open document/list: no idle root scan and no network subscription.
+   if(!scope.paths.length&&!scope.dirs.length){status('ready');return;}
+   const ctl=new AbortController();controller=ctl;const token=++generation;
+   let retryable=false;
+   const current=()=>alive&&!ctl.signal.aborted&&token===generation;
+   const state={baseline:new Map(baseline),known:new Set(known)},nextDirectories=new Map(directories),nextCursors=new Map(cursors);
+   try{
+    const changes:WorkspaceFileChange[]=[];
+    let accessError:string|undefined;
+    const forbidden=(error:unknown)=>(error as {status?:number;code?:string})?.status===403&&(error as {code?:string}).code==='file_forbidden';
+    const deny=(error:unknown,paths:string[],dirs:string[])=>{
+     accessError=error instanceof Error?error.message:String(error);
+     denyFileScope(backend,jobId,accessError,{paths,dirs});
+    };
+    // A rejected path in a batch is not evidence that the whole task lost access.
+    // Inspect only that batch's metadata; healthy files and directories remain usable.
+    const inspect=async(paths:string[],dirs:string[])=>{
+     const listed=new Map<string,FileEntry>(),deniedPaths=new Set<string>();
+     for(const dir of dirs){
+      try{
+       const result=await requests.run(()=>backend.stat(jobId,dir||'.'),ctl.signal);if(!current())return;
+       if(result.type!=='dir')continue;
+       for(const file of result.entries)listed.set(file.path,file);
+       const revision=result.revision??JSON.stringify(result.entries.map(file=>[file.path,fingerprint(file)]));
+       if(nextDirectories.has(dir)&&nextDirectories.get(dir)!==revision)changes.push({kind:'modified',path:dir});
+       nextDirectories.set(dir,revision);
+      }catch(error){if(!current())return;if(!forbidden(error))throw error;deny(error,[],[dir||'.']);}
+     }
+     const files:FileEntry[]=[];
+     for(const path of paths){
+      const listedFile=listed.get(path);if(listedFile){files.push(listedFile);continue;}
+      try{const result=await requests.run(()=>backend.stat(jobId,path),ctl.signal);if(result.type==='file')files.push(result);}
+      catch(error){if(!current())return;if(forbidden(error)){deniedPaths.add(path);state.baseline.delete(path);state.known.delete(path);deny(error,[path],[]);}else if((error as {status?:number}).status!==404)throw error;}
+      if(!current())return;
+     }
+     changes.push(...snapshot(files,paths.filter(path=>!deniedPaths.has(path)),state));
+    };
+    if(backend.pollFiles){
+     const activeKeys=new Set<string>();
+     const count=Math.max(Math.ceil(scope.paths.length/200),Math.ceil(scope.dirs.length/32));
+     for(let index=0;index<count;index++){
+      const paths=scope.paths.slice(index*200,index*200+200),dirs=scope.dirs.slice(index*32,index*32+32),key=JSON.stringify([paths,dirs]);activeKeys.add(key);
+      let batch:Awaited<ReturnType<NonNullable<BoardBackend['pollFiles']>>>;
+      try{batch=await requests.run(()=>backend.pollFiles!(jobId,{paths,dirs,cursor:nextCursors.get(key)},ctl.signal),ctl.signal);}
+      catch(error){if(!forbidden(error))throw error;nextCursors.delete(key);await inspect(paths,dirs);if(!current())return;continue;}
+      if(!current())return;
+      if(!batch||typeof batch!=='object')throw invalidResponse('文件变化响应不完整，请重试');
+      if(batch.type==='resync'){cursors.delete(key);throw new Error('文件修订已变化，请重新核对');}
+      if(batch.cursor)nextCursors.set(key,batch.cursor);
+      changes.push(...accept(batch,paths,state));
+      if(!Array.isArray(batch.directories))throw invalidResponse('目录变化响应不完整，请重试');
+      for(const dir of batch.directories){
+       if(!dir||!dirs.includes(dir.path)||(dir.revision!==null&&typeof dir.revision!=='string'))throw invalidResponse('目录变化响应范围错误');
+       if(nextDirectories.has(dir.path)&&nextDirectories.get(dir.path)!==dir.revision)changes.push({kind:dir.revision===null?'deleted':'modified',path:dir.path});
+       nextDirectories.set(dir.path,dir.revision);
+      }
+     }
+     for(const key of nextCursors.keys())if(!activeKeys.has(key))nextCursors.delete(key);
+    }else{
+     // Compatibility hosts: inspect requested entries, never recurse a workspace.
+     await inspect(scope.paths,scope.dirs);
+    }
+    if(!current())return;
+    const previews=backend.fileSync?await refreshFilePreviews(backend.fileSync,jobId,scope.paths,ctl.signal):undefined;
+    if(!current())return;
+    for(const file of previews?.denied??[])deny(new Error(file.message),[file.path],[]);
+    const changedPaths=new Set(changes.map(change=>change.path));
+    for(const path of previews?.changed??[])if(!changedPaths.has(path)){changes.push({kind:'modified',path});changedPaths.add(path);}
+    const active=new Set(scope.paths);for(const path of state.known)if(!active.has(path)){state.known.delete(path);state.baseline.delete(path);}
+    for(const dir of nextDirectories.keys())if(!scope.dirs.includes(dir))nextDirectories.delete(dir);
+    baseline=state.baseline;known=state.known;directories=nextDirectories;cursors=nextCursors;
+    publish(changes);
+    if(previews?.error)throw previews.error;
+    failed=0;serverNotBefore=0;retryAt=0;exhaustedUntil=0;if(current())status(accessError?'error':'ready',accessError);
+   }catch(error){if(current()){
+    failed++;const code=(error as {status?:number}).status??0;
+    const failureCode=(error as {code?:string}).code;
+    retryable=!['invalid_manifest','invalid_response','integrity','response_too_large','client_queue_timeout'].includes(failureCode??'')&&(!code||[408,429,500,502,503,504].includes(code));
+    if(retryable){
+     const hint=Number((error as {retryAfterMs?:number}).retryAfterMs);
+     if(Number.isFinite(hint)&&hint>0)serverNotBefore=Math.max(serverNotBefore,Date.now()+hint);
+     const base=retryDelays[Math.min(failed-1,retryDelays.length-1)];
+     retryAt=Math.max(Date.now()+base,serverNotBefore)+Math.floor(Math.random()*base/2);
+     if(failed>retryDelays.length)exhaustedUntil=Math.max(Date.now()+30000,serverNotBefore);
+    }
+    if([401,403].includes(code))denyFileScope(backend,jobId,error instanceof Error?error.message:undefined);
+    status('error',error instanceof Error?error.message:String(error));
+   }}
+   finally{if(controller===ctl){
+    controller=null;
+    if(alive&&!hidden()){
+     if(retryable){
+      // A new round during an outage cannot skip backoff or replenish this retry budget.
+      if(failed<=retryDelays.length){const pending=dirty;dirty=false;schedule(Math.max(0,retryAt-Date.now()),pending);}
+      else if(dirty)schedule(Math.max(0,exhaustedUntil-Date.now(),serverNotBefore-Date.now()),true);
+     }else if(dirty)schedule(Math.max(100,serverNotBefore-Date.now()),true);
+    }
+   }}
+  };
+  function clearTimer(){if(timer!==undefined)clearTimeout(timer);timer=undefined;}
+  function schedule(delay:number,pending=false){
+   clearTimer();
+   // Long server cooldowns defer a real event once, never extend idle retries.
+   // Do not let setTimeout overflow and retry before the server's deadline.
+   if(delay>2147483647||(!pending&&delay>180000))return;
+   timer=setTimeout(()=>{timer=undefined;void scan();},delay);
+  }
+  const wake=(manual=false)=>{
+   if(!alive)return;
+   const now=Date.now();
+   if(manual){failed=0;exhaustedUntil=0;clearTimer();}
+   else if(exhaustedUntil&&now>=exhaustedUntil){
+    // Exhaustion alone never restarts work; a later event can restore its budget.
+    failed=0;exhaustedUntil=0;
+   }
+   dirty=true;
+   // Pending events coalesce, and automatic wakes cannot bypass an existing retry delay.
+   if(!controller&&!hidden()&&timer===undefined)schedule(Math.max(100,serverNotBefore-now,manual?0:Math.max(retryAt,exhaustedUntil)-now),true);
+  };
+  const recover=()=>wake();
+  const scopeChanged=()=>{
+   if(!alive)return;
+   const next=JSON.stringify(readFileScope(backend,jobId));if(next===scopeKey)return;scopeKey=next;
+   generation++;const old=controller;controller=null;old?.abort();wake(true);
+  };
+  const visibility=()=>{
+   if(hidden()){generation++;const old=controller;controller=null;old?.abort();clearTimer();dirty=true;}
+   else recover();
+  };
+  const releaseScope=onFileScope(backend,jobId,scopeChanged);
+  const releasePreviews=backend.fileSync?onFilePreviewScope(backend.fileSync,jobId,()=>wake()):()=>{};
+  if(typeof window!=='undefined'){window.addEventListener('online',recover);document.addEventListener('visibilitychange',visibility);}
+  owned.retry=wake;
+  owned.stop=()=>{alive=false;clearTimer();controller?.abort();releaseScope();releasePreviews();if(typeof window!=='undefined'){window.removeEventListener('online',recover);document.removeEventListener('visibilitychange',visibility);}};
+  queueMicrotask(()=>{if(alive)void scan();});
+ }
+ const owned=entry,subscription={change:listener,status:options.onStatus};owned.listeners.add(subscription);notifyCallback(subscription.status,{...owned.status});
+ let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(subscription);if(!owned.listeners.size){if(jobs!.get(jobId)===owned)jobs!.delete(jobId);owned.stop();}releaseOwnedScope();};
+}

package/src/board/folderDownload.ts

@@ -0,0 +1,211 @@
+// 工作区「下载整个文件夹」：逐级列目录、逐个读文件（经中枢），在浏览器里打成 ZIP 下载。
+// 有上限：文件数、总大小（读进内存再打包）；超了直接报出来，让用户进到更小的目录或单个下载，不会把页面撑爆。
+// 弱网 / 节点忙：每个请求失败了按退避重试几次；某个文件一直读不到（或读的时候被任务删了）就跳过，
+// 照样把其余的打包，失败的清单放进压缩包里的 FAILED_LIST_NAME，并告诉调用方。取消会中止正在传的请求。
+import { CenterError, type BoardBackend } from "../core/client";
+import type { DirListing, FileEntry } from "../core/types";
+import { fmtSize } from "./fileKind";
+import { saveBlob, readBoundedBuffer, FileReadLimitError } from "./fileOps";
+import { buildZip, type ZipEntry } from "./zip";
+
+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 }>; /** ZIP failure report path, when generated; may differ to preserve a user file. */ failedListName?: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();
+    let stop:(()=>void)|undefined;
+    try {
+      const cancelled=new Promise<never>((_resolve,reject)=>{stop=()=>reject(abortError());signal?.addEventListener("abort",stop,{once:true});});
+      const value=await Promise.race([fn(),cancelled]);
+      if(signal?.aborted)throw abortError();
+      return value;
+    } catch (error) {
+      if (isAbort(error) || signal?.aborted) throw abortError();
+      if (attempt >= ATTEMPTS || error instanceof FileReadLimitError || !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);
+    } finally {if(stop)signal?.removeEventListener("abort",stop);}
+  }
+}
+
+/** 列出 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()!;
+    const entries = new Map<string, FileEntry>();
+    const cursors = new Set<string>();
+    let cursor: string | undefined, revision: string | undefined;
+    let directoryBytes = 0, directoryFiles = 0;
+    try {
+      do {
+        const res = await withRetry(async () => {
+          try { return backend.listFiles ? await backend.listFiles(jobId, cur, { cursor, limit: 200, signal }) : await backend.stat(jobId, cur); }
+          catch (error) {
+            // New short-HTTP clients preserve status on ordinary Errors too.
+            const http = error as { status?: number; code?: string; message?: string };
+            if (!(error instanceof CenterError) && typeof http.status === "number") throw new CenterError(http.message ?? "列出目录失败", http.code ?? `HTTP_${http.status}`, http.status);
+            throw error;
+          }
+        }, signal, undefined, backoff);
+        if (res.type !== "dir") {
+          if (cursor) throw new Error("目录在读取时发生变化，请重新下载");
+          break;
+        }
+        const page: DirListing = res;
+        if (cursor && (!revision || page.revision !== revision)) throw new Error("目录在读取时发生变化，请重新下载");
+        revision ??= page.revision;
+        for (const entry of page.entries) {
+          if (entries.has(entry.path)) throw new Error("目录分页数据重复，请重新下载");
+          entries.set(entry.path, entry);
+          if (entry.type === "file") {
+            directoryFiles++; directoryBytes += entry.size;
+            if (out.length + directoryFiles > maxFiles) throw new Error(`文件超过 ${maxFiles} 个，请进到更小的目录再下载`);
+            if (bytes + directoryBytes > maxBytes) throw new Error(`总大小超过 ${fmtSize(maxBytes)}，请进到更小的目录或单个下载`);
+          }
+        }
+        cursor = page.nextCursor;
+        if (page.truncated && (!cursor || !backend.listFiles)) throw new Error(`「${cur === "." ? "工作区" : cur}」里文件太多，节点只列出了一部分；请进到更小的目录再下载`);
+        if (cursor && (!revision || cursors.has(cursor))) throw new Error("目录分页游标无效，请重新下载");
+        if (cursor) cursors.add(cursor);
+      } while (cursor);
+    } catch (error) {
+      // 子目录在列的时候被任务删了：跳过它；要下载的目录本身没了照常报错。
+      if (cur !== (dir || ".") && error instanceof CenterError && error.status === 404) continue;
+      if (error instanceof CenterError && error.status === 409) throw new Error("目录在读取时发生变化，请重新下载");
+      throw error;
+    }
+    // Commit a directory only after every page has the same revision.
+    for (const e of entries.values()) {
+      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, failedListName } = await zipFolder(backend, jobId, dir, opts);
+  if(opts.signal?.aborted)throw abortError();
+  saveBlob(blob, name);
+  return { files, failed, ...(failedListName?{failedListName}:{}) };
+}
+
+/** 把 dir（"" = 整个工作区）打成 ZIP，返回 Blob（不下载；业务方可以自己上传到服务器）。 */
+export async function zipFolder(backend: BoardBackend, jobId: string, dir: string, opts: FolderOptions = {}): Promise<FolderZip> {
+  const ctl=new AbortController(),abort=()=>ctl.abort();let limit:FileReadLimitError|undefined;
+  opts.signal?.addEventListener("abort",abort,{once:true});if(opts.signal?.aborted)ctl.abort();
+  try{return await zipFolderRun(backend,jobId,dir,{...opts,signal:ctl.signal},()=>{limit=new FileReadLimitError(FOLDER_MAX_BYTES);ctl.abort();});}
+  catch(error){throw limit??error;}
+  finally{opts.signal?.removeEventListener("abort",abort);ctl.abort();}
+}
+async function zipFolderRun(backend: BoardBackend, jobId: string, dir: string, opts: FolderOptions,exceeded:()=>void): 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 readBoundedBuffer(backend,jobId,f.path,FOLDER_MAX_BYTES,{ signal, onBytes: (n) => { got[i] = n; if(got.reduce((a,b)=>a+b,0)>FOLDER_MAX_BYTES){exceeded();return;} 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) 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(signal?.aborted)throw abortError();
+  let failedListName:string|undefined;
+  if (failed.length) {
+    const names=new Set(ok.map(entry=>entry.path));failedListName=FAILED_LIST_NAME;
+    for(let suffix=1;names.has(failedListName);suffix++)failedListName=`_下载失败的文件 (${suffix}).txt`;
+    const list = ["下面这些文件没有下载下来（其余文件都在压缩包里）：", "", ...failed.map((f) => `${f.path}\t${f.reason}`), ""].join("\n");
+    ok.push({ path: failedListName, 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, ...(failedListName?{failedListName}:{}) };
+}