@spzxg/cli-ui 0.6.2 → 0.6.5

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,88 @@
+import { CenterError, 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){
+  const mode=backend.watchFiles?'events':'poll',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;
+    blocked=[400,404,405,410,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/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;

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,6 +52,11 @@ 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 下所有文件（递归，只含文件）。 */
@@ -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}」不是目录`);
@@ -96,23 +117,31 @@ export function createWorkspace(deps: {
     },
     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 = {}) {

package/src/chat/CliChat.tsx

@@ -1,27 +1,36 @@
 // cli-chat：对话。界面取自 Operator 的会话视图（SessionView 的对话部分 + Composer），
 // 数据来自 center 的对话任务（mode=conversation）：实时流里的节点转录按 Operator 的规则渲染，
 // 每条消息是中枢的一轮，排队 / 执行 / 结束都跟 center 保持一致。
-import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
-import { CliErrorBoundary } from "../ui/ErrorBoundary.js";
-import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.js";
-import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider.js";
-import { boardContextBlock, serializeBlock, viewingBlock } from "../core/blocks.js";
-import { convKey, emptyConv, isChatTask, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
-import type { AskAnswers, AskQuestion, CenterTask, Msg } from "../core/types.js";
-import { Icon } from "../ui/icons.js";
-import { agentLabel as labelOf, fmtTokens, formatAnswersText, modelLabel } from "../ui/format.js";
-import { AgentBadge, Avatar, Skel, StatusDot, type DotCls } from "../ui/shared.js";
-import { HANDOFF_NOTICE_PREFIX, MessageView, SessionBreak, type MessageHandlers } from "../ui/Transcript.js";
-import { RENDER_MAX, RENDER_STEP, RENDER_WINDOW, buildTranscriptItems, hasOpenAsk, toolDataOf } from "../ui/transcriptModel.js";
-import { Composer, type ComposerOptions } from "./Composer.js";
-import { fillTemplate, refShown, resolveChatConfig, type CliChatConfig } from "../core/config.js";
-import { exportMarkdown } from "./export.js";
-import { FileLinkContext, FileOpenContext } from "../ui/fileLinks.js";
-import { FileViewer } from "../board/FileViewer.js";
-import { BrowserPane } from "../board/BrowserPane.js";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type CSSProperties } from "react";
+import { CliErrorBoundary } from "../ui/ErrorBoundary";
+import type { CliEvent, CliStore, CliStoreOptions } from "../core/store";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider";
+import { formatBoardContext, withoutBoardContext } from "../board/context";
+import { MAX_MESSAGE_CHARS, charCount, boardContextBlock, serializeBlock, viewingBlock } from "../core/blocks";
+import { convKey, emptyConv, isChatTask, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation";
+import type { AskAnswers, AskQuestion, CenterTask, Msg } from "../core/types";
+import { Icon } from "../ui/icons";
+import { agentLabel as labelOf, fmtTokens, formatAnswersText, modelLabel } from "../ui/format";
+import { AgentBadge, Avatar, Skel, StatusDot, type DotCls } from "../ui/shared";
+import { HANDOFF_NOTICE_PREFIX, MessageView, SessionBreak, type MessageHandlers } from "../ui/Transcript";
+import { RENDER_MAX, RENDER_STEP, RENDER_WINDOW, buildTranscriptItems, hasOpenAsk, toolDataOf } from "../ui/transcriptModel";
+import { Composer, type ComposerOptions } from "./Composer";
+import { fillTemplate, refShown, resolveChatConfig, type CliChatConfig } from "../core/config";
+import { exportMarkdown } from "./export";
+import { FileLinkContext, FileOpenContext } from "../ui/fileLinks";
+import { FileViewer } from "../board/FileViewer";
+import { BrowserPane } from "../board/BrowserPane";
 
 /** onTurnEnd / onConversationEnd：浏览器里从实时流算出的结果通知，不依赖 center 的 callback.url。 */
 export interface CliChatProps extends CliStoreOptions, ResultHandlers {
+  /** Integration slots share this transcript/composer; they do not create another chat implementation. */
+  slots?: { beforeMessages?: ReactNode; afterMessages?: ReactNode; composerToolbar?: ReactNode; beforeComposer?: ReactNode };
+  /** Saving execution settings blocks send until persistence completes. */
+  configurationBusy?: boolean;
+  onClear?: () => void;
+  /** 每条消息自动带入看板当前文件、页签和最近浏览；默认 true。 */
+  passiveContext?: boolean;
+
   /**
    * 显示哪个对话（center 的 job_id）。不给就跟共享仓库的选中走（和 cli-msglist 联动）；都没有 = 新对话。
    * 也可以直接给对话键 "job_id#task_id"（cli-msglist 的 onSelect、job_change 事件的 key 就是它）。
@@ -120,7 +129,7 @@ function RunningIndicator({ agent, agentName, startedAt, lastActivityRef }: { ag
   );
 }
 
-function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", color = "#b8613f", readOnly: readOnlyProp, allowClose = true, config, theme = "light", className, style, onEvent, onTurnEnd, onConversationEnd, onCallback, inProvider, fileUrl, fileOpen = "auto", newConversation, createConversation, businessIdFor }: CliChatProps & { inProvider: boolean }) {
+function ChatInner({ slots, passiveContext = true, configurationBusy, onClear, jobId: jobIdProp, taskId: taskIdProp, title = "对话", color = "#b8613f", readOnly: readOnlyProp, allowClose = true, config, theme = "light", className, style, onEvent, onTurnEnd, onConversationEnd, onCallback, inProvider, fileUrl, fileOpen = "auto", newConversation, createConversation, businessIdFor }: CliChatProps & { inProvider: boolean }) {
   useComponentEvents(onEvent, { onTurnEnd, onConversationEnd, onCallback }, inProvider);
   // 配置按内容比较：宿主每次渲染传新对象也不会让消息行全部重渲染。
   const configKey = JSON.stringify(config ?? {});
@@ -269,6 +278,9 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   // 本组件的新建参数随每次发送带上：放进共享 Provider 时也用自己的，不依赖仓库是谁建的。
   const sendOpts = useRef({ newConversation, createConversation, businessIdFor, select: !controlled });
   sendOpts.current = { newConversation, createConversation, businessIdFor, select: !controlled };
+  const [skipPassive,setSkipPassive]=useState(false);
+  const skipPassiveRef=useRef(false);skipPassiveRef.current=skipPassive;
+  useEffect(()=>setSkipPassive(false),[key]);
   const send = useCallback(async (text: string) => {
     // 一次性任务：发给正在看的那个子任务（接着它聊）。
     const id = latest.current.conv?.batch ? latest.current.runKey : latest.current.key;
@@ -276,26 +288,33 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     // 看板上正在看的文件缺省也带上一次（已经明确引用了的不重复），单独一块「看板正在看」：转录里按 config.refs.viewing 显示或不显示。
     const refKey = latest.current.key;
     const refs = refKey ? store.takeRefs(refKey) : [];
-    const viewing = refKey ? store.takeViewing(refKey) : null;
+    const passiveView=refKey?store.getState().boardContext[refKey]:null;
+    const passive=passiveContext&&!skipPassiveRef.current&&passiveView?formatBoardContext(passiveView,refKey??undefined):'';
+    const viewing = !passive && refKey ? store.takeViewing(refKey) : null;
     const blocks = [
+      ...(passive ? [{name:"看板正在看",kind:"viewing" as const,text:passive}] : []),
       ...(viewing && !refs.some((r) => r.id === viewing.id) ? [viewingBlock(viewing.text)] : []),
       ...(refs.length ? [boardContextBlock(refs.map((r) => r.text))] : []),
     ];
     const full = blocks.length ? [text, ...blocks.map(serializeBlock)].join("\n\n") : text;
     let target: string;
     try {
+      if(charCount(full)>MAX_MESSAGE_CHARS)throw new Error("加上看板背景后消息过长，请精简内容或取消本次自动附带。");
       target = await store.send(id ?? null, full, sendOpts.current);
     } catch (error) {
       if (refKey) { store.restoreRefs(refKey, refs); store.restoreViewing(refKey, viewing); }
       throw error;
     }
+    if(latest.current.key===refKey)setSkipPassive(false);
     if (target !== id) go(target);
-  }, [store, go]);
+  }, [store, go, passiveContext]);
+  const passiveView=useCliState(state=>key?state.boardContext[key]:undefined);
+  const passiveText=passiveContext&&passiveView?formatBoardContext(passiveView,key??undefined):'';
   const refs = useCliState((s) => (key ? s.refs[key] : undefined));
   const viewingState = useCliState((s) => (key ? s.viewing[key] : undefined));
   const viewingRef = viewingState && !viewingState.off && !refs?.some((r) => r.id === viewingState.ref.id) ? viewingState.ref : null;
   // 输入框上方显示哪些（config.refs）：不显示的照样随消息带上。正在看的缺省不显示。
-  const viewing = viewingRef && refShown(cfg, "viewing") ? viewingRef : null;
+  const viewing = !passiveText && viewingRef && refShown(cfg, "viewing") ? viewingRef : null;
   const shownRefs = refs?.filter((r) => refShown(cfg, r.kind));
   // 业务方补充的背景（store.appendContext）：随下一条消息带上，输入框上方显示出来，让用户知道会带上什么。
   const contextItems = useCliState((s) => s.context[key ?? ""]);
@@ -324,6 +343,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     return () => window.removeEventListener("keydown", onKey);
   }, [popup]);
   const handlers = useMemo<MessageHandlers>(() => ({
+    onQuote: readOnly ? undefined : (m,selected) => {const id=latest.current.key;if(id) store.addRef(id,{id:`message:${m.id}`,kind:"message",label:m.role==='user'?'引用你的消息':'引用智能体消息',text:selected||(m.role==='user'?withoutBoardContext(m.content):m.content)});},
     // 与 Operator 的 answerQuestion 一致：先把卡片标成已答，再把回答发出去（center 已结束提问那一轮，回答就是下一条消息）。
     onAnswer: readOnlyProp || (readOnly && !(batch && store.client.answerAsk)) ? undefined : async (askId: string, questions: AskQuestion[], answers: AskAnswers) => {
       const id = latest.current.key;
@@ -361,7 +381,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     onRetry: readOnly ? undefined : (msgId: string) => {
       const list = latest.current.messages;
       const at = list.findIndex((m) => m.id === msgId);
-      for (let j = (at === -1 ? list.length : at) - 1; j >= 0; j--) if (list[j].role === "user") { void report(send(list[j].content), "重试没有发出去").catch(() => undefined); return; }
+      for (let j = (at === -1 ? list.length : at) - 1; j >= 0; j--) if (list[j].role === "user") { void report(send(withoutBoardContext(list[j].content)), "重试没有发出去").catch(() => undefined); return; }
     },
   }), [readOnly, readOnlyProp, batch, chat, send, store, go, report, fileOpen]);
   const stop = useCallback(async () => {
@@ -369,7 +389,19 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     const turn = c ? runningTurn(c) : null;
     if (id && turn) await report(store.cancelTurn(id, turn.turn_id), "停止失败");
   }, [store, report]);
-  const [closing, setClosing] = useState<"idle" | "confirm" | "busy">("idle");
+  const [closeAction, setCloseAction] = useState<{ key: string; stage: "confirm" | "busy" } | null>(null);
+  const closing = closeAction?.key === key ? closeAction.stage : "idle";
+  useEffect(() => setCloseAction(null), [key]);
+  const confirmClose = () => {
+    if (!key || closeAction?.key !== key || closeAction.stage !== "confirm") return;
+    const pending = { key, stage: "busy" as const };
+    setCloseAction(pending);
+    void store.close(key).then(() => {
+      if (latest.current.key === pending.key) setActionError(null);
+    }, (error: unknown) => {
+      if (latest.current.key === pending.key) setActionError(`结束对话失败：${error instanceof Error ? error.message : String(error)}`);
+    }).finally(() => setCloseAction(current => current === pending ? null : current));
+  };
 
   // ── 运行计时（与 Operator 一致：本页看着开始的轮次按本机时钟，进来时已在跑的按那条用户消息的时间） ──
   const lastUserTs = useMemo(() => { for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "user") return messages[i].ts ?? null; return null; }, [messages]);
@@ -614,7 +646,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               {Icon.download()}<span>{older > 0 ? "导出已加载" : "导出"}</span>
             </button>}
             {h.close && key && !isNew && allowClose && !readOnly && !ended && !batch && (
-              <button className="btn btn-line btn-sm" onClick={() => setClosing("confirm")} disabled={closing === "busy"} title={taskId ? "只结束这个对话：之后它不再接收消息，正在跑的一轮会被中止；同一任务里的其他对话不受影响" : "结束这个对话：之后不再接收消息，正在跑的一轮会被中止"}>{Icon.stop()} 结束对话</button>
+              <button className="btn btn-line btn-sm" onClick={() => key && setCloseAction({ key, stage: "confirm" })} disabled={closing === "busy"} title={taskId ? "只结束这个对话：之后它不再接收消息，正在跑的一轮会被中止；同一任务里的其他对话不受影响" : "结束这个对话：之后不再接收消息，正在跑的一轮会被中止"}>{Icon.stop()} 结束对话</button>
             )}
           </div>
         </div>}
@@ -623,8 +655,8 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
           <div className="clear-confirm">
             <span>结束这个对话？结束后不能再发消息{running ? "，正在执行的一轮会被中止" : ""}{taskId && manyConvs ? "；同一任务里的其他对话不受影响" : ""}。</span>
             <span className="spacer" />
-            <button className="btn btn-ghost btn-sm" onClick={() => setClosing("idle")} disabled={closing === "busy"}>取消</button>
-            <button className="btn btn-accent btn-sm" disabled={closing === "busy"} onClick={() => { setClosing("busy"); void report(store.close(key), "结束对话失败").catch(() => undefined).finally(() => setClosing("idle")); }}>{closing === "busy" ? "正在结束…" : "确认结束"}</button>
+            <button className="btn btn-ghost btn-sm" onClick={() => setCloseAction(null)} disabled={closing === "busy"}>取消</button>
+            <button className="btn btn-accent btn-sm" disabled={closing === "busy"} onClick={confirmClose}>{closing === "busy" ? "正在结束…" : "确认结束"}</button>
           </div>
         )}
         {actionError && <div className="sync-banner conflict"><span className="sync-msg">⚠ {actionError}</span><span className="sync-spacer" /><button className="btn btn-ghost btn-sm" onClick={() => setActionError(null)}>知道了</button></div>}
@@ -634,6 +666,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
         <div className="transcript-wrap">
           <div className="transcript" ref={scrollRef} onScroll={onScroll}>
             <div className="tw">
+              {slots?.beforeMessages}
               {(!key || isNew) && cfg.empty.show && (
                 <div className="hero cli-hero">
                   <div className="h-ic">{Icon.bolt()}</div>
@@ -698,6 +731,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
               {ended && cfg.transcript.status && (
                 <div className="session-label"><span className="ln" />{batch ? statusText : <>{REASON_TEXT[closedReason ?? ""] ?? "对话已结束"}{!finalEnd ? " · 再发消息会开一个新对话接着聊" : ""}</>}<span className="ln" /></div>
               )}
+              {slots?.afterMessages}
               {continuedBy && (
                 <div className="load-older"><button className="btn btn-line btn-sm" onClick={() => go(continuedBy)}>转到接续的新对话</button></div>
               )}
@@ -737,15 +771,24 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
             ))}
           </div>
         )}
+        {showComposer && passiveText && passiveView && <div className="cli-board-background" role="note" aria-label="看板浏览背景">
+          <details><summary>看板背景 · {(passiveView.current?.path??passiveView.file)?.split('/').pop()??'未选中文件'} · 打开 {(passiveView.opened??passiveView.files).length} · 最近浏览 {passiveView.history?.length??0}</summary>
+            <div>{passiveView.visible===false?'看板已收起，将附带上次选中的文件及浏览记录。':'将附带当前文件、打开页签和最近浏览记录，仅发送路径等信息。'}</div>
+            <ul>{(passiveView.history??[]).map((file,index)=><li key={`${file.sourceId}:${file.path}:${index}`}>{file.path}{file.sourceId&&file.sourceId!==key?'（来源任务）':''}</li>)}</ul>
+          </details>
+          <label><input type="checkbox" checked={!skipPassive} onChange={event=>setSkipPassive(!event.target.checked)} />下条消息带入</label>
+        </div>}
+        {slots?.beforeComposer}
         {showComposer && (
           <Composer
             key={key ?? "new"}
-            draft={key ?? `new:${instanceId}`}
+            draft={store.draftScope ? `${store.draftScope}:${key ?? `new:${instanceId}`}` : key ?? `new:${instanceId}`}
             placeholder={fillTemplate(key && !isNew ? cfg.composer.placeholder : cfg.composer.placeholderNew, { title: convTitle, agent: agentText })}
-            disabled={composerDisabled}
+            disabled={composerDisabled || !!configurationBusy}
             disabledHint={cfg.composer.placeholderDisabled ? fillTemplate(cfg.composer.placeholderDisabled, { title: convTitle, agent: agentText }) : disabledHint}
             running={running || batchPending}
-            onSend={send}
+            toolbar={slots?.composerToolbar}
+            onSend={async text => { if (text.trim() === "/clear" && onClear) { onClear(); return; } await send(text); }}
             onStop={cfg.composer.stop && key && conv && runningTurn(conv) ? stop : undefined}
             taskControl={cfg.composer.stop && !readOnlyProp && controlTask && jobId && store.client.pauseTask && store.client.resumeTask ? {
               paused: controlTask.status === "paused",