@spzxg/cli-ui 0.6.2 → 0.6.6

package/src/board/context.ts

@@ -0,0 +1,65 @@
+import type { BoardFile, BoardView } from './workspace';
+import { serializeBlock, splitMessage, VIEWING_NAME } from '../core/blocks';
+export const BOARD_HISTORY_MAX = 40;
+const identity=(file:BoardFile)=>JSON.stringify([file.sourceId??'',file.path]);
+export function rememberBoardFile(history:readonly BoardFile[],file:BoardFile):BoardFile[]{
+ return [...history.filter(item=>identity(item)!==identity(file)),{...file}].slice(-BOARD_HISTORY_MAX);
+}
+export function cloneBoardView(view:BoardView):BoardView {
+ return {...view,files:[...view.files],current:view.current?{...view.current}:view.current,opened:view.opened?.map(file=>({...file})),history:view.history?.map(file=>({...file})),browser:view.browser?{title:view.browser.title,url:browserUrl(view.browser.url)}:view.browser};
+}
+function browserUrl(raw:string):string {
+ try{const url=new URL(raw);return url.protocol==='http:'||url.protocol==='https:'?`${url.origin}${url.pathname}`:url.protocol==='about:'?`${url.protocol}${url.pathname}`:url.protocol;}catch{return '';}
+}
+function describe(file:BoardFile,currentSourceId?:string){
+ return file.sourceId&&file.sourceId!==currentSourceId?{path:file.path,sourceTask:file.sourceId,note:'来源任务的工作区，非当前执行分支'}:{path:file.path};
+}
+/** Metadata only; do not silently read/upload file bodies, URLs with auth tokens or arbitrary DOM. */
+export function formatBoardContext(view:BoardView,currentSourceId?:string):string {
+ if(view.autoContext===false)return '';
+ const current=view.current===undefined?(view.file?{path:view.file}:null):view.current;
+ const opened=view.opened??view.files.map(path=>({path}));
+ const history=view.history??[];
+ if(!current&&!opened.length&&!history.length&&!view.browser)return '';
+ const data={panelVisible:view.visible!==false,activeTab:view.tab,currentFile:current?describe(current,currentSourceId):null,
+  openFiles:opened.slice(-8).map(file=>describe(file,currentSourceId)),recentlyVisited:history.slice(-BOARD_HISTORY_MAX).map(file=>describe(file,currentSourceId)),
+  ...(view.browser?{browser:{url:browserUrl(view.browser.url),title:view.browser.title}}:{})};
+ const text=JSON.stringify(data,null,2);
+ // Bound context without truncating a path into a different, plausible filename.
+ if(text.length>16000){data.recentlyVisited=[];const compact=JSON.stringify(data,null,2);if(compact.length>16000)return '看板浏览背景较大，本次未自动附带；请用户明确引用需要的文件。';return `用户工作区浏览背景（仅元信息；较早浏览记录已省略）：\n${compact}`;}
+ return `用户工作区浏览背景（自动附带，仅元信息；最近访问不代表仍在查看；panelVisible=false 时 currentFile 是收起前选中的文件）：\n${text}`;
+}
+export function appendBoardContext(text:string,view:BoardView|null,currentSourceId?:string):string {
+ const context=view?formatBoardContext(view,currentSourceId):'';
+ return context?[text,serializeBlock({name:VIEWING_NAME,kind:'viewing',text:context})].filter(Boolean).join('\n\n'):text;
+}
+
+export function withoutBoardContext(text:string):string {
+ return splitMessage(text).filter(part=>part.kind!=='block'||part.block.kind!=='viewing').map(part=>part.kind==='text'?part.text:serializeBlock(part.block)).join('\n\n');
+}
+
+/** Local selection changes may select an owner; shared history and remote page
+ * metadata updates must not steal the user's active board. */
+const localBoardView=(view:BoardView)=>JSON.stringify({tab:view.tab,dir:view.dir,file:view.file,files:view.files,current:view.current,opened:view.opened,visible:view.visible!==false});
+export function selectedBoardOwner(sources:Map<string,BoardView>):[string,BoardView]|undefined {
+ const entries=[...sources.entries()];return entries.reverse().find(([,view])=>view.visible!==false)??entries[0];
+}
+export function reportBoardOwner(sources:Map<string,BoardView>,owner:string,view:BoardView):[string,BoardView]|undefined {
+ const previous=sources.get(owner),active=selectedBoardOwner(sources);
+ if(previous){if(localBoardView(previous)!==localBoardView(view)){sources.delete(owner);sources.set(owner,view);}else sources.set(owner,view);}
+ else if(active&&active[1].visible!==false){const existing=[...sources];sources.clear();sources.set(owner,view);for(const [id,value]of existing)sources.set(id,value);}
+ else sources.set(owner,view);
+ return selectedBoardOwner(sources);
+}
+export function activateBoardOwner(sources:Map<string,BoardView>,owner:string):[string,BoardView]|undefined {
+ const view=sources.get(owner);if(view){sources.delete(owner);sources.set(owner,view);}return selectedBoardOwner(sources);
+}
+export function mergeBoardHistory(existing:readonly BoardFile[],previous:BoardView|undefined,next:BoardView):BoardFile[] {
+ const old=previous?.history??[],incoming=next.history??[];let history=[...existing];
+ const known=new Set(old.map(identity));
+ // Newly mounted boards may restore old history; only adopt previously unknown
+ // records so a late restore cannot reorder the live workspace's recent visits.
+ const additions=incoming.filter(file=>!known.has(identity(file))&&(!previous?!history.some(item=>identity(item)===identity(file)):true));
+ if(previous&&incoming.length&&identity(incoming[incoming.length-1])!==identity(old[old.length-1]??{path:''}))additions.push(incoming[incoming.length-1]);
+ for(const file of additions)history=rememberBoardFile(history,file);return history;
+}

package/src/board/fileOps.ts

@@ -1,7 +1,7 @@
 // 工作区文件的基础操作（不依赖界面）：可直接打开的地址、下载到本地、读成 Blob。
 // 看板、文件预览和给业务方的工作区接口（workspace.ts）共用。
-import { fileUrlFromBase, type BoardBackend } from "../core/client.js";
-import { extOf, fmtSize } from "./fileKind.js";
+import { fileUrlFromBase, type BoardBackend } from "../core/client";
+import { extOf, fmtSize } from "./fileKind";
 
 /** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的不在浏览器里拼下载。 */
 const BLOB_DOWNLOAD_MAX = 300 * 1024 * 1024;
@@ -26,6 +26,29 @@ export async function directFileUrl(backend: BoardBackend, jobId: string, path:
   return linkBase ? fileUrlFromBase(linkBase, path, download) : null;
 }
 
+export class FileReadLimitError extends Error {
+  constructor(maxBytes:number){super(`文件超过当前读取上限（${fmtSize(maxBytes)}），请使用直接下载链接`);this.name="FileReadLimitError";}
+}
+/** Bound bytes even with stale metadata; cancellation must settle callers when a custom backend ignores AbortSignal. */
+export async function readBoundedBuffer(backend:BoardBackend,jobId:string,path:string,maxBytes:number,options:{signal?:AbortSignal;onBytes?:(bytes:number)=>void}={}):Promise<ArrayBuffer> {
+  const ctl=new AbortController();let limit:FileReadLimitError|undefined;
+  const abort=()=>ctl.abort();options.signal?.addEventListener("abort",abort,{once:true});
+  if(options.signal?.aborted)ctl.abort();
+  let rejectAbort:(()=>void)|undefined;
+  try{
+    if(ctl.signal.aborted)throw new DOMException("已取消","AbortError");
+    const cancelled=new Promise<never>((_resolve,reject)=>{rejectAbort=()=>reject(limit??new DOMException("已取消","AbortError"));ctl.signal.addEventListener("abort",rejectAbort,{once:true});});
+    const result=await Promise.race([backend.readBuffer(jobId,path,{signal:ctl.signal,onBytes:bytes=>{
+      if(ctl.signal.aborted)return;
+      if(bytes>maxBytes){limit=new FileReadLimitError(maxBytes);ctl.abort();return;}
+      options.onBytes?.(bytes);
+    }}),cancelled]);
+    if(ctl.signal.aborted)throw limit??new DOMException("已取消","AbortError");
+    if(result.byteLength>maxBytes)throw new FileReadLimitError(maxBytes);
+    return result;
+  }finally{options.signal?.removeEventListener("abort",abort);if(rejectAbort)ctl.signal.removeEventListener("abort",rejectAbort);ctl.abort();}
+}
+
 /** 把 Blob 存到本地（浏览器下载）。 */
 export function saveBlob(blob: Blob, name: string) {
   const url = URL.createObjectURL(blob);
@@ -51,5 +74,5 @@ export async function downloadFile(backend: BoardBackend, jobId: string, path: s
   const url = await directFileUrl(backend, jobId, path, true);
   if (url) { clickDownload(url, name); return; }
   if (size !== undefined && size > BLOB_DOWNLOAD_MAX) throw new Error(`文件较大（${fmtSize(size)}），当前接入方式不能在浏览器里下载，请升级任务中心`);
-  saveBlob(new Blob([await backend.readBuffer(jobId, path)]), name);
+  saveBlob(new Blob([await readBoundedBuffer(backend, jobId, path, BLOB_DOWNLOAD_MAX)]), name);
 }

package/src/board/fileWatch.ts

@@ -0,0 +1,94 @@
+import { CenterError, isMissingRoute, type BoardBackend } from '../core/client';
+import { notifyCallback } from '../core/callbacks';
+import type { FileEntry, WorkspaceChangeEvent, WorkspaceFileBatch, WorkspaceFileChange, WorkspaceWatchStatus } from '../core/types';
+import { listFolder } from './folderDownload';
+export interface WorkspaceWatchOptions { intervalMs?:number; onStatus?:(status:WorkspaceWatchStatus)=>void }
+type Listener={change:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']};
+type Entry={listeners:Set<Listener>;stop:()=>void;retry?:()=>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 MAX_TRACKED_FILES=100000;
+/** Internal: a new lease in an aggregating store can retry a terminal stream. */
+export function retryWorkspaceFiles(backend:BoardBackend,jobId:string):void {registries.get(backend)?.get(jobId)?.retry?.();}
+/** One transport per backend/workspace; independent of the active directory or file tab. */
+export function subscribeWorkspaceFiles(backend:BoardBackend,jobId:string,listener:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}):()=>void {
+ let entries=registries.get(backend);if(!entries){entries=new Map();registries.set(backend,entries);}
+ let entry=entries.get(jobId);const subscription={change:listener,status:options.onStatus};
+ if(!entry){
+  let mode:WorkspaceWatchStatus['mode']=backend.watchFiles?'events':'poll',coverage:WorkspaceWatchStatus['coverage']=mode==='events'?'workspace':'listed-files';
+  entry={listeners:new Set(),stop:()=>{},status:{type:'files_watch',jobId,state:'connecting',mode,coverage,complete:false}};entries.set(jobId,entry);
+  const owned=entry;let alive=true,baseline:Map<string,FileEntry>|null=null,limited=false,blocked=false,stopTransport:(()=>void)|null=null;
+  let timer:ReturnType<typeof setTimeout>|undefined,controller:AbortController|null=null,attempt=0,generation=0;
+  const status=(state:WorkspaceWatchStatus['state'],complete=false,error?:string)=>{
+   if(!alive)return;owned.status={type:'files_watch',jobId,state,mode,coverage,complete:mode==='events'&&complete&&!limited,...(error?{error}:{})};
+   for(const item of [...owned.listeners])notifyCallback(item.status,{...owned.status});
+  };
+  const publish=(changes:WorkspaceFileChange[],batch:WorkspaceFileBatch,resync=false)=>{
+   if(!alive||!changes.length)return;
+   const event:WorkspaceChangeEvent={type:'files_changed',jobId,mode,coverage,complete:mode==='events'&&batch.complete&&!limited,changes,revision:batch.revision,...(resync?{resync:true}:{})};
+   for(const item of [...owned.listeners])notifyCallback(item.change,cloneWorkspaceChange(event));
+  };
+  const accept=(batch:WorkspaceFileBatch)=>{
+   if(!alive)return;
+   if(batch.type==='resync'){if(batch.reason==='workspace_unavailable'&&baseline===null)baseline=new Map();status('reconnecting',false,batch.reason);return;}
+   if(batch.type==='snapshot'){
+    const next=new Map<string,FileEntry>();let overflow=false;const changes:WorkspaceFileChange[]=[];
+    for(const file of batch.files)if(file.type==='file'){if(next.has(file.path)||next.size<MAX_TRACKED_FILES)next.set(file.path,{...file});else overflow=true;}
+    if(baseline){
+     for(const [path,file] of next){const previous=baseline.get(path);if(!previous)changes.push({kind:'created',path,file});else if(previous.mtime!==file.mtime||previous.size!==file.size||previous.changeToken!==file.changeToken)changes.push({kind:'modified',path,file,previous});}
+     if(batch.complete&&!overflow)for(const [path,previous] of baseline)if(!next.has(path))changes.push({kind:'deleted',path,previous});
+    }
+    // Once tracking overflows, only a complete, bounded snapshot restores
+    // completeness. Partial snapshots never prove that missing files vanished.
+    if(batch.complete){baseline=next;limited=overflow;}
+    else{baseline??=new Map();for(const [path,file] of next){if(baseline.has(path)||baseline.size<MAX_TRACKED_FILES)baseline.set(path,file);else overflow=true;}limited||=overflow;}
+    publish(changes,batch,true);
+   }else{
+    baseline??=new Map();for(const change of batch.changes){if(change.kind==='deleted')baseline.delete(change.path);else if(change.file){if(baseline.has(change.path)||baseline.size<MAX_TRACKED_FILES)baseline.set(change.path,{...change.file});else limited=true;}}
+    // Native change events are authoritative even when size/mtime are unchanged.
+    publish(batch.changes,batch);
+   }
+   attempt=0;status('ready',batch.complete);
+  };
+  const interval=Math.max(1000,options.intervalMs??15000);
+  const scan=async()=>{
+   if(!alive)return;controller=new AbortController();const signal=controller.signal;
+   try{const files=await listFolder(backend,jobId,'',{signal,maxFiles:10000,maxBytes:Infinity});if(alive&&!signal.aborted)accept({type:'snapshot',files:files.map(file=>({...file,name:file.path.split('/').pop()??file.path,type:'file' as const})),complete:true});}
+   catch(error){if(alive&&!signal.aborted){attempt++;status('error',false,error instanceof Error?error.message:String(error));}}
+   finally{controller=null;if(alive)timer=setTimeout(()=>{timer=undefined;void scan();},Math.min(120000,interval*Math.max(1,attempt)));}
+  };
+  const connect=()=>{
+   if(!alive||!backend.watchFiles)return;const token=++generation;let finished=false,cleanup:(()=>void)|null=null;
+   blocked=false;
+   status(attempt?'reconnecting':'connecting');
+   if(!alive||token!==generation)return;
+   // Retirement can precede watchFiles returning its disposer. Clearing the
+   // owned handle first also makes reentrant cancellation release it once.
+   const retire=()=>{finished=true;if(stopTransport===retire)stopTransport=null;const dispose=cleanup;cleanup=null;notifyCallback(dispose??undefined,undefined);};
+   const close=(error:unknown)=>{
+    if(!alive||finished||token!==generation)return;retire();if(!alive||token!==generation)return;const code=error instanceof CenterError?error.status:0;
+    if(error instanceof CenterError&&(isMissingRoute(error)||(code===501&&error.code==='file_watch_unsupported'))){
+     // A directory listing has narrower coverage than native events. Establish
+     // a fresh baseline rather than reporting inaccessible paths as deleted.
+     mode='poll';coverage='listed-files';baseline=null;limited=false;attempt=0;blocked=false;
+     status('connecting',false,error.message);if(alive&&token===generation)void scan();return;
+    }
+    blocked=[400,404,405,410,413,501].includes(code);const slow=[401,403,429].includes(code);
+    status(blocked||slow?'error':'reconnecting',false,error instanceof Error?error.message:undefined);
+    if(!alive||token!==generation||blocked)return;
+    const delay=slow?30000:Math.min(30000,1000*2**Math.min(attempt++,5));
+    timer=setTimeout(()=>{timer=undefined;connect();},delay);
+   };
+   stopTransport=retire;
+   try{cleanup=backend.watchFiles(jobId,{onEvent:batch=>{if(alive&&!finished&&token===generation)accept(batch);},onClose:close});if(finished||!alive||token!==generation)retire();}catch(error){close(error);}
+  };
+  const wake=()=>{if(!alive)return;if(typeof document!=='undefined'&&document.visibilityState==='hidden')return;if(timer){clearTimeout(timer);timer=undefined;}if(mode==='poll'){if(!controller)void scan();}else{const token=++generation,retire=stopTransport;stopTransport=null;retire?.();if(alive&&token===generation)connect();}};
+  owned.retry=()=>{if(blocked)wake();};
+  if(typeof window!=='undefined'){window.addEventListener('online',wake);document.addEventListener('visibilitychange',wake);}
+  owned.stop=()=>{alive=false;generation++;if(timer)clearTimeout(timer);controller?.abort();stopTransport?.();if(typeof window!=='undefined'){window.removeEventListener('online',wake);document.removeEventListener('visibilitychange',wake);}};
+  // Defer initialization until the first listener has been registered.
+  queueMicrotask(()=>{if(alive){if(mode==='events')connect();else void scan();}});
+ }
+ const owned=entry;owned.listeners.add(subscription);notifyCallback(subscription.status,{...owned.status});owned.retry?.();
+ let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(subscription);if(!owned.listeners.size){if(entries!.get(jobId)===owned)entries!.delete(jobId);owned.stop();}};
+}

package/src/board/folderDownload.ts

@@ -2,10 +2,10 @@
 // 有上限：文件数、总大小（读进内存再打包）；超了直接报出来，让用户进到更小的目录或单个下载，不会把页面撑爆。
 // 弱网 / 节点忙：每个请求失败了按退避重试几次；某个文件一直读不到（或读的时候被任务删了）就跳过，
 // 照样把其余的打包，失败的清单放进压缩包里的 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";
+import { CenterError, type BoardBackend } from "../core/client";
+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;
@@ -17,7 +17,7 @@ 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 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 };
 
@@ -43,15 +43,19 @@ function sleep(ms: number, signal?: AbortSignal) {
 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 {
-      return await fn();
+      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 || !isTransient(error)) throw error;
+      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);}
   }
 }
 
@@ -89,13 +93,21 @@ export type FolderOptions = { onProgress?: (p: FolderProgress) => void; signal?:
 
 /** 打包下载 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);
+  const { blob, name, files, failed, failedListName } = await zipFolder(backend, jobId, dir, opts);
+  if(opts.signal?.aborted)throw abortError();
   saveBlob(blob, name);
-  return { files, failed };
+  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 });
@@ -123,7 +135,7 @@ export async function zipFolder(backend: BoardBackend, jobId: string, dir: strin
       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(); } }); },
+          () => { 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,
@@ -131,7 +143,7 @@ export async function zipFolder(backend: BoardBackend, jobId: string, dir: strin
         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)}（文件还在变大），请进到更小的目录或单个下载`);
+        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) {
@@ -151,11 +163,15 @@ export async function zipFolder(backend: BoardBackend, jobId: string, dir: strin
   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: FAILED_LIST_NAME, data: new TextEncoder().encode(list) as Uint8Array<ArrayBuffer> });
+    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 };
+  return { blob, name, files: ok.length - (failed.length ? 1 : 0), failed, ...(failedListName?{failedListName}:{}) };
 }

package/src/board/frameQuote.ts

@@ -18,9 +18,9 @@ function bridgeScript(token: string) {
   return `(function(){var t=${t};function post(m){m.cliUiSel=t;try{parent.postMessage(m,"*")}catch(e){}}
 function send(){var s=getSelection(),text=s&&!s.isCollapsed?String(s).trim():"",rect=null;
 if(text&&s.rangeCount){var b=s.getRangeAt(0).getBoundingClientRect();rect={left:b.left,top:b.top,width:b.width}}post({text:text,rect:rect})}
-function later(){setTimeout(send,0)}
+var timer;function later(){clearTimeout(timer);timer=setTimeout(send,0)}
 document.addEventListener("mouseup",later);document.addEventListener("keyup",later);
-document.addEventListener("selectionchange",function(){var s=getSelection();if(!s||s.isCollapsed)post({text:""})});
+document.addEventListener("selectionchange",later);
 addEventListener("scroll",function(){post({scroll:true})},true);
 addEventListener("message",function(e){if(e.source===parent&&e.data&&e.data.cliUiClear===t){var s=getSelection();s&&s.removeAllRanges()}});
 document.addEventListener("click",function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href^="#"]');if(!a)return;e.preventDefault();

package/src/board/panels.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+const useLayout = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+/** Initial visibility is separate from capability. Closing a panel never disables its backend. */
+export function useBoardPanels(scope: string | null, available: readonly string[], initial: readonly string[]) {
+  const allowed = [...new Set(available)];
+  const defaults = [...new Set(initial)].filter(id => allowed.includes(id));
+  const signature = JSON.stringify([allowed, defaults]);
+  const key = scope ? `cli-ui:panels:${scope}:${signature}` : null;
+  const [state, setState] = useState<{ key: string | null; open: string[] }>({ key, open: defaults });
+  const current = state.key === key ? state.open.filter(id => allowed.includes(id)) : defaults;
+  useLayout(() => {
+    let open = defaults;
+    try {
+      const saved = key ? JSON.parse(sessionStorage.getItem(key) ?? 'null') : null;
+      if (Array.isArray(saved)) open = [...new Set(saved.filter((id): id is string => typeof id === 'string' && allowed.includes(id)))];
+    } catch { /* Restricted storage does not disable panel controls. */ }
+    setState({ key, open });
+  }, [key, signature]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    if (key && state.key === key) try { sessionStorage.setItem(key, JSON.stringify(state.open)); } catch { /* In-memory only. */ }
+  }, [key, state]);
+  const set = useCallback((id: string, open: boolean) => {
+    if (!allowed.includes(id)) return false;
+    setState(previous => {
+      const list = previous.key === key ? previous.open : defaults;
+      return { key, open: open ? [...new Set([...list, id])] : list.filter(item => item !== id) };
+    });
+    return true;
+  }, [key, signature]); // eslint-disable-line react-hooks/exhaustive-deps
+  const show=useCallback((id:string)=>set(id,true),[set]);
+  const close=useCallback((id:string)=>set(id,false),[set]);
+  return { open: current, available: allowed, show, close };
+}

package/src/board/textLoad.ts

@@ -5,8 +5,8 @@
 // 这一小段和手里的末尾一模一样就说明文件只是往后追加了，只取新增的部分接上；对不上（文件被改写、变短了）才整个重读。
 // 只对 UTF-8 文件这样做（GBK 的字节边界不好对齐，整个重读）。
 
-import type { BoardBackend } from "../core/client.js";
-import { decodeText } from "../core/textDecode.js";
+import type { BoardBackend } from "../core/client";
+import { decodeText } from "../core/textDecode";
 
 /** 往前多取这么多字节，用来确认文件只是追加。 */
 export const OVERLAP = 256;
@@ -47,12 +47,13 @@ export function incompleteUtf8Tail(bytes: Uint8Array) {
 const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((x, i) => x === b[i]);
 
 /** 第一次读：开头（或末尾）最多 max 字节。 */
-export async function loadText(backend: BoardBackend, jobId: string, path: string, opts: { max: number; tail?: boolean; onBytes?: (bytes: number) => void }): Promise<LoadedText> {
+export async function loadText(backend: BoardBackend, jobId: string, path: string, opts: { max: number; tail?: boolean; onBytes?: (bytes: number) => void; signal?: AbortSignal }): Promise<LoadedText> {
+  if (opts.signal?.aborted) throw new DOMException("文件读取已取消", "AbortError");
   if (!backend.readBytes) {
-    const r = await backend.readText(jobId, path, opts.max, { tail: opts.tail, onBytes: opts.onBytes });
+    const r = await backend.readText(jobId, path, opts.max, { tail: opts.tail, onBytes: opts.onBytes, signal: opts.signal });
     return { text: r.text, parts: [r.text], truncated: r.truncated, size: r.size, tail: !!r.tail, encoding: r.encoding, start: 0, end: 0, tailBytes: null };
   }
-  const chunk = await backend.readBytes(jobId, path, { maxBytes: opts.max, tail: opts.tail, onBytes: opts.onBytes });
+  const chunk = await backend.readBytes(jobId, path, { maxBytes: opts.max, tail: opts.tail, onBytes: opts.onBytes, signal: opts.signal });
   const { text, encoding } = decodeText(chunk.bytes, { fromMiddle: chunk.start > 0 });
   const k = encoding === "utf-8" ? incompleteUtf8Tail(chunk.bytes) : 0;
   const end = chunk.start + chunk.bytes.length - k;
@@ -67,7 +68,8 @@ export async function loadText(backend: BoardBackend, jobId: string, path: strin
  * 文件变了：能接上就只取新增的部分，返回新的内容；返回 null = 接不上（被改写 / 变短 / 不是 UTF-8 / 后端不支持），调用方整个重读。
  * 只看开头且文件比 max 大时，开头没变就不用重读（追加的在后面，本来就不显示）。
  */
-export async function refreshText(backend: BoardBackend, jobId: string, path: string, prev: LoadedText, max: number): Promise<LoadedText | null> {
+export async function refreshText(backend: BoardBackend, jobId: string, path: string, prev: LoadedText, max: number, options: { signal?: AbortSignal } = {}): Promise<LoadedText | null> {
+  if (options.signal?.aborted) throw new DOMException("文件读取已取消", "AbortError");
   if (!backend.readBytes || !prev.tailBytes) return null;
   const overlap = prev.tailBytes.length;
   const from = prev.end - overlap;
@@ -75,7 +77,7 @@ export async function refreshText(backend: BoardBackend, jobId: string, path: st
   // 末尾模式攒多了（超过 1.5 倍）：整个重读末尾，免得越攒越大。
   if (prev.tail && prev.end - prev.start > max * 1.5) return null;
   const room = headOnly ? 0 : prev.tail ? max : Math.max(0, max - (prev.end - prev.start));
-  const chunk = await backend.readBytes(jobId, path, { start: from, maxBytes: overlap + room });
+  const chunk = await backend.readBytes(jobId, path, { start: from, maxBytes: overlap + room, signal: options.signal });
   if (chunk.size < prev.end || chunk.start !== from || chunk.bytes.length < overlap) return null;
   if (!sameBytes(chunk.bytes.subarray(0, overlap), prev.tailBytes)) return null;
   const readEnd = from + chunk.bytes.length;

package/src/board/workspace.ts

@@ -11,11 +11,12 @@
  *
  * 数据都经中枢读执行节点（和看板一样），弱网时按网络错误（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";
+import { subscribeWorkspaceFiles, type WorkspaceWatchOptions } from "./fileWatch";
+import type { BoardBackend } from "../core/client";
+import type { BoardInfo, FileEntry, WorkspaceChangeEvent } from "../core/types";
+import { directFileUrl, downloadFile, mimeOf } from "./fileOps";
+import { fmtSize } from "./fileKind";
+import { downloadFolder, listFolder, zipFolder, type FolderOptions, type FolderResult, type FolderZip } from "./folderDownload";
 
 /** readText 最多读这么大（更大的用 readFile）。 */
 export const WORKSPACE_TEXT_MAX = 20 * 1024 * 1024;
@@ -24,6 +25,8 @@ export const WORKSPACE_FILE_MAX = 500 * 1024 * 1024;
 /** listAll 最多列这么多个文件。 */
 export const WORKSPACE_LIST_MAX = 10_000;
 
+export interface BoardFile { path: string; sourceId?: string }
+
 /** 看板现在的样子（看板组件报告给仓库；没有看板时没有）。 */
 export interface BoardView {
   /** 当前页签：files / changes / browser、"file:<路径>"（打开的文件）或自己加的页签 id。 */
@@ -34,6 +37,14 @@ export interface BoardView {
   file: string | null;
   /** 开着的文件页签。 */
   files: string[];
+  /** 当前文件身份；切到目录/浏览器时为 null。sourceId 保留来源任务。 */
+  current?: BoardFile | null;
+  opened?: BoardFile[];
+  /** 最近真正访问过的文件（关闭页签后保留，最多40条）。 */
+  history?: BoardFile[];
+  browser?: { url: string; title: string } | null;
+  visible?: boolean;
+  autoContext?: boolean;
 }
 
 export interface CliWorkspace {
@@ -41,12 +52,17 @@ export interface CliWorkspace {
   readonly jobId: string;
   /** 看板概况：派发到节点没有、节点是否在线、有没有浏览器。 */
   info(): Promise<BoardInfo>;
+  stat(path: string): ReturnType<BoardBackend["stat"]>;
+  /** 订阅文件变更。初始快照只建立基线；返回取消函数。 */
+  watch(listener: (event: WorkspaceChangeEvent) => void, options?: WorkspaceWatchOptions): () => void;
+  /** 包括当前文件、打开页签、最近浏览和显示状态的背景快照。 */
+  context(): BoardView | null;
   /** 列一个目录（不递归）。 */
   list(dir?: string): Promise<FileEntry[]>;
   /** 列 dir 下所有文件（递归，只含文件）。 */
   listAll(dir?: string, opts?: { signal?: AbortSignal }): Promise<FileEntry[]>;
   /** 读成文字（GBK 导出的文件会自动转码）。 */
-  readText(path: string): Promise<string>;
+  readText(path: string, opts?: { signal?: AbortSignal }): 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。 */
@@ -70,6 +86,8 @@ export function createWorkspace(deps: {
   key: string;
   view: () => BoardView | undefined;
   open: (path: string) => boolean;
+  context?: () => BoardView | null;
+  watch?: (listener:(event:WorkspaceChangeEvent)=>void,options?:WorkspaceWatchOptions)=>()=>void;
 }): CliWorkspace {
   const { key } = deps;
   const backend = () => {
@@ -80,6 +98,9 @@ export function createWorkspace(deps: {
   return {
     jobId: key,
     info: () => backend().info(key),
+    stat: path => backend().stat(key, clean(path) || "."),
+    watch: (listener, options) => deps.watch ? deps.watch(listener,options) : subscribeWorkspaceFiles(backend(), key, listener, options),
+    context: () => deps.context?.() ?? deps.view() ?? null,
     async list(dir = "") {
       const res = await backend().stat(key, clean(dir) || ".");
       if (res.type !== "dir") throw new Error(`「${dir}」不是目录`);
@@ -89,30 +110,48 @@ export function createWorkspace(deps: {
       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 readText(path, opts = {}) {
+      const signal = opts.signal;
+      if (signal?.aborted) throw new DOMException("已取消", "AbortError");
+      let rejectAbort: (() => void) | undefined;
+      try {
+        const reading = signal ? backend().readText(key, clean(path), WORKSPACE_TEXT_MAX, { signal }) : backend().readText(key, clean(path), WORKSPACE_TEXT_MAX);
+        const r = signal ? await Promise.race([reading, new Promise<never>((_resolve, reject) => {
+          rejectAbort = () => reject(new DOMException("已取消", "AbortError"));
+          signal.addEventListener("abort", rejectAbort, { once: true });
+          if (signal.aborted) rejectAbort();
+        })]) : await reading;
+        if (r.truncated) throw new Error(`文件较大（超过 ${WORKSPACE_TEXT_MAX / 1024 / 1024} MB），请用 readFile 读成 Blob`);
+        return r.text;
+      } finally { if (rejectAbort) signal?.removeEventListener("abort", rejectAbort); }
     },
     async readFile(path, opts = {}) {
       const p = clean(path);
+      const max = opts.maxBytes ?? WORKSPACE_FILE_MAX;
+      if(!Number.isFinite(max)||max<0)throw new RangeError("maxBytes 必须是非负有限字节数");
       // 太大的读到一半就停：整个读进内存会把页面撑爆。
       const ctl = new AbortController();
       const stop = () => ctl.abort();
       opts.signal?.addEventListener("abort", stop, { once: true });
+      if(opts.signal?.aborted)ctl.abort();
       let tooBig = false;
-      const max = opts.maxBytes ?? WORKSPACE_FILE_MAX;
+      let rejectAbort:(()=>void)|undefined;
       try {
-        const buffer = await backend().readBuffer(key, p, {
+        if(ctl.signal.aborted)throw new DOMException("已取消", "AbortError");
+        const aborted=new Promise<never>((_resolve,reject)=>{rejectAbort=()=>reject(new DOMException("已取消", "AbortError"));ctl.signal.addEventListener("abort",rejectAbort,{once:true});});
+        const buffer = await Promise.race([backend().readBuffer(key, p, {
           signal: ctl.signal,
-          onBytes: (n) => { if (n > max) { tooBig = true; ctl.abort(); } else opts.onProgress?.(n); },
-        });
+          onBytes: (n) => { if(ctl.signal.aborted)return; if (n > max) { tooBig = true; ctl.abort(); } else opts.onProgress?.(n); },
+        }),aborted]);
+        if(buffer.byteLength>max){tooBig=true;throw new Error("文件超过读取上限");}
+        if(ctl.signal.aborted)throw new DOMException("已取消", "AbortError");
         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);
+        if(rejectAbort)ctl.signal.removeEventListener("abort",rejectAbort);
       }
     },
     async fileUrl(path, opts = {}) {