@spzxg/cli-ui 0.6.1 → 0.6.5

package/src/board/CliBoard.tsx

@@ -8,18 +8,23 @@
 // 同步：任务每有进展（实时流里的轮次 / 输出变化）就刷新，运行中再定时刷新；打开着的文件改了会自动重读。
 // 和 cli-chat 放在同一个 Provider 里时，对话里点本地文件 / 「查看浏览器」会在这里打开（store.openInBoard）。
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
-import { CliErrorBoundary } from "../ui/ErrorBoundary.js";
-import type { BoardRef, CliEvent, CliStore, CliStoreOptions, OpenTarget } from "../core/store.js";
-import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider.js";
-import { convKey, parseConvKey, isRunning } from "../core/conversation.js";
-import { toolDataOf } from "../ui/transcriptModel.js";
-import type { BoardInfo, FileEntry } from "../core/types.js";
-import { Icon } from "../ui/icons.js";
-import { CenterError } from "../core/client.js";
-import { FileViewer, type FileAction } from "./FileViewer.js";
-import { FilesPane } from "./FilesPane.js";
-import { ChangesPane } from "./ChangesPane.js";
-import { BrowserPane } from "./BrowserPane.js";
+import { CliErrorBoundary } from "../ui/ErrorBoundary";
+import type { BoardRef, CliEvent, CliStore, CliStoreOptions, OpenTarget } from "../core/store";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider";
+import { convKey, parseConvKey, isRunning } from "../core/conversation";
+import { toolDataOf } from "../ui/transcriptModel";
+import type { BoardInfo, FileEntry } from "../core/types";
+import { Icon } from "../ui/icons";
+import { CenterError } from "../core/client";
+import { FileViewer, type FileAction } from "./FileViewer";
+import { FilesPane } from "./FilesPane";
+import { ChangesPane } from "./ChangesPane";
+import { BrowserPane } from "./BrowserPane";
+import { rememberBoardFile } from "./context";
+import type { BoardFile } from "./workspace";
+import type { WorkspaceHandlers } from "../core/provider";
+import { useBoardPanels } from "./panels";
+import { PanelControls, PanelTab } from "./PanelControls";
 
 export type BoardTab = "files" | "changes" | "browser";
 
@@ -36,28 +41,33 @@ const FILE_TAB = "file:";
 const fileTabId = (path: string) => `${FILE_TAB}${path}`;
 /** 开着的文件页签记在会话存储里（按对话）：刷新页面后还在。 */
 const tabsKey = (jobId: string) => `cli-ui:board-tabs:${jobId}`;
-function loadTabs(jobId: string | null): { files: string[]; tab: string | null } {
-  if (!jobId) return { files: [], tab: null };
+function loadTabs(jobId: string | null): { files: string[]; tab: string | null; history: BoardFile[] } {
+  if (!jobId) return { files: [], tab: null, history: [] };
   try {
-    const v = JSON.parse(sessionStorage.getItem(tabsKey(jobId)) ?? "null") as { files?: unknown; tab?: unknown } | null;
+    const v = JSON.parse(sessionStorage.getItem(tabsKey(jobId)) ?? "null") as { files?: unknown; tab?: unknown; history?: BoardFile[] } | null;
     const files = Array.isArray(v?.files) ? v.files.filter((f): f is string => typeof f === "string").slice(-MAX_FILE_TABS) : [];
-    return { files, tab: typeof v?.tab === "string" ? v.tab : null };
-  } catch { return { files: [], tab: null }; }
+    return { files, tab: typeof v?.tab === "string" ? v.tab : null, history: Array.isArray(v?.history) ? v.history.filter(f=>typeof f?.path==="string").slice(-40) : files.map(path=>({path})) };
+  } catch { return { files: [], tab: null, history: [] }; }
 }
 const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
-function saveTabs(jobId: string, files: string[], tab: string) {
-  try { sessionStorage.setItem(tabsKey(jobId), JSON.stringify({ files, tab })); } catch { /* 存不下就不记 */ }
+function saveTabs(jobId: string, files: string[], tab: string, history: BoardFile[]) {
+  try { sessionStorage.setItem(tabsKey(jobId), JSON.stringify({ files, tab, history })); } catch { /* 存不下就不记 */ }
 }
 /** 有输出就刷新文件，但两次之间至少隔这么久（智能体连写几十个文件时不至于每个都打一次中枢）。 */
 const ACTIVITY_GAP_MS = 700;
 
-export interface CliBoardProps extends CliStoreOptions {
+export interface CliBoardProps extends CliStoreOptions, WorkspaceHandlers {
+  /** 默认监听整个工作区，收起后继续。旧中枢降级状态可由 onFilesWatch 观察。 */
+  watchFiles?: boolean;
+  fileWatchIntervalMs?: number;
   /** 看哪个对话（center 的 job_id）。不给就跟共享仓库的选中走（和 cli-msglist / cli-chat 联动）。 */
   jobId?: string | null;
   /** 对话任务里的哪个对话（和 jobId 一起用，同 cli-chat 的 taskId）。不给 = 缺省那个（最近派发过的）。 */
   taskId?: string | null;
-  /** 显示哪些页签、什么顺序。缺省三个都有（节点没开浏览器功能时不显示「浏览器」）。 */
+  /** 默认打开的模块及顺序；用户仍可手动打开其他可用模块。[] 表示初始全部关闭。 */
   tabs?: BoardTab[];
+  /** 允许使用的模块；与 tabs 的默认可见状态分开。缺省允许全部受后端支持的模块。 */
+  availableTabs?: BoardTab[];
   defaultTab?: BoardTab;
   /** 只看：不能接管 / 打开 / 关闭浏览器。 */
   readOnly?: boolean;
@@ -103,22 +113,24 @@ export function CliBoard(props: CliBoardProps) {
   return <CliErrorBoundary component="cli-board" theme={props.theme}>{withOwnProvider(props, <BoardInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
 }
 
-interface OpenFile { path: string; size?: number; mtime?: number; version: number }
+interface OpenFile { reloadKey?:number; path: string; size?: number; mtime?: number; version: number }
 
-function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, readOnly, fileActions, pollMs = 15_000, acceptOpen = true, quoteToChat, autoQuoteOpenFile, extraTabs, onCollapse, collapsed, onExpand, onNavigate, onEvent, theme = "light", className, style, inProvider }: CliBoardProps & { inProvider: boolean }) {
-  useComponentEvents(onEvent, {}, inProvider);
+function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs, defaultTab, readOnly, fileActions, pollMs = 15_000, acceptOpen = true, quoteToChat, autoQuoteOpenFile, extraTabs, onCollapse, collapsed, onExpand, onNavigate, onEvent, onFilesChange, onFilesWatch, onBoardContextChange, watchFiles = true, fileWatchIntervalMs, theme = "light", className, style, inProvider }: CliBoardProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {onFilesChange,onFilesWatch,onBoardContextChange}, inProvider);
   const store = useCliStore();
   const backend = store.client.board;
   const selected = useCliState((s) => s.selected);
   // 内部用对话键（见 core/conversation.ts）：看板接口按它找对话任务里的那个对话。
   const jobId = jobIdProp !== undefined ? (jobIdProp ? convKey(parseConvKey(jobIdProp).jobId, taskIdProp ?? parseConvKey(jobIdProp).taskId) : null) : selected;
 
+  const storageId = jobId && store.draftScope ? `${store.draftScope}:${jobId}` : jobId;
   const [info, setInfo] = useState<BoardInfo | null>(null);
   const [infoError, setInfoError] = useState<string | null>(null);
   // 页签：内置的（文件列表 / 改动 / 浏览器）、打开的文件（file:<路径>，可以开多个、可以关）、宿主加的。
   const [tab, setTab] = useState<string>(defaultTab ?? tabs?.[0] ?? "files");
   const [dir, setDir] = useState("");
   const [files, setFiles] = useState<OpenFile[]>([]);
+  const [history,setHistory] = useState<BoardFile[]>([]);
   // 刷新信号，按代价分开：
   //   tick     进展（实时流有新输出 / 轮次变化，节流）、切回页面、手动刷新 —— 文件、改动、打开的文件都跟着刷新；
   //   pollTick 运行中的定时刷新 —— 只刷文件列表和打开的文件（改动要在节点上跑 git diff，不轮询）；
@@ -130,18 +142,19 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
   const lastJob = useRef(jobId);
   if (lastJob.current !== jobId) {
     lastJob.current = jobId;
-    setInfo(null); setInfoError(null); setDir(""); setFiles([]);
+    setInfo(null); setInfoError(null); setDir(""); setFiles([]); setHistory([]);
     setTab(defaultTab ?? tabs?.[0] ?? "files");
   }
   // 恢复上次开着的文件页签（存在 sessionStorage）：挂上之后、绘制之前做——服务端渲染和首次渲染一致，不会对不上。
   const restored = useRef<string | null>(null);
   useIsoLayoutEffect(() => {
-    if (!jobId || restored.current === jobId) return;
-    restored.current = jobId;
-    const saved = loadTabs(jobId);
+    if (!storageId || restored.current === storageId) return;
+    restored.current = storageId;
+    const saved = loadTabs(storageId);
+    setHistory(saved.history.map(file=>({...file,sourceId:file.sourceId??jobId??undefined})));
     if (saved.files.length) setFiles((cur) => (cur.length ? cur : saved.files.map((path) => ({ path, version: 0 }))));
     if (saved.tab) setTab((cur) => (cur === (defaultTab ?? tabs?.[0] ?? "files") ? saved.tab! : cur));
-  }, [jobId]);
+  }, [storageId]);
 
   // 实时流：看板单独用时也要知道任务在不在跑（同一对话只连一次）。
   useEffect(() => (jobId ? store.open(jobId) : undefined), [store, jobId]);
@@ -191,7 +204,7 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
     let timer: ReturnType<typeof setTimeout> | undefined;
     const load = () => backend.info(jobId).then((i) => {
       if (!alive) return;
-      setInfo((old) => (old && old.dispatched === i.dispatched && old.remote_task_id === i.remote_task_id && old.browser === i.browser && old.node?.health === i.node?.health ? old : i));
+      setInfo((old) => (old && old.dispatched === i.dispatched && old.remote_task_id === i.remote_task_id && old.files === i.files && old.browser === i.browser && old.node?.health === i.node?.health ? old : i));
       setInfoError(null);
       if (!i.dispatched) timer = setTimeout(load, 3000);
     }, (e: unknown) => {
@@ -203,15 +216,13 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
     return () => { alive = false; if (timer) clearTimeout(timer); };
   }, [backend, jobId, statusKey, manual]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  const builtinTabs = useMemo<string[]>(() => (tabs ?? ["files", "changes", "browser"]).filter((t) => t !== "browser" || !info || info.browser !== false), [tabs, info]);
-  const fileTabsOn = builtinTabs.includes("files");
-  const shownTabs = useMemo<string[]>(() => [
-    ...builtinTabs,
-    ...(fileTabsOn ? files.map((f) => fileTabId(f.path)) : []),
-    ...(extraTabs ?? []).map((t) => t.id),
-  ], [builtinTabs, fileTabsOn, files, extraTabs]);
-  const activeTab = shownTabs.includes(tab) ? tab : shownTabs[0] ?? "files";
+  const builtinTabs = useMemo<string[]>(() => (availableTabs ?? ["files", "changes", "browser"]).filter(t => ["files","changes","browser"].includes(t)).filter(t => t !== "browser" || !info || info.browser !== false).filter(t => t !== "files" || !info || info.files !== false), [availableTabs, info?.browser, info?.files]);
+  const allowedPanels = [...builtinTabs, ...(extraTabs ?? []).map(t => t.id)];
+  const panels = useBoardPanels(jobId ? `center:${storageId}` : null, allowedPanels, [...(tabs ?? builtinTabs.filter(tab=>tab!=="changes")), ...(extraTabs ?? []).map(t => t.id)]);
+  const shownTabs = [...panels.open, ...(builtinTabs.includes("files") ? files.map(f => fileTabId(f.path)) : [])];
+  const activeTab = shownTabs.includes(tab) ? tab : shownTabs[0] ?? "";
   const file = activeTab.startsWith(FILE_TAB) ? files.find((f) => fileTabId(f.path) === activeTab) ?? null : null;
+  useEffect(()=>{if(file&&jobId)setHistory(previous=>{const next=rememberBoardFile(previous,{path:file.path,sourceId:jobId});return JSON.stringify(next)===JSON.stringify(previous)?previous:next;});},[file?.path,jobId]);
   const tabLabel = (t: string) => TAB_LABEL[t as BoardTab] ?? (t.startsWith(FILE_TAB) ? t.slice(FILE_TAB.length).split("/").pop() || t : undefined) ?? extraTabs?.find((x) => x.id === t)?.label ?? t;
   // 页签多了横向滚动：当前页签总是滚到看得见的地方（新开的文件页签在最后，窄看板里容易被挤出去）。
   const tabsRef = useRef<HTMLDivElement | null>(null);
@@ -242,8 +253,16 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
     return () => ro.disconnect();
   }, [collapsed, revealTab, shownTabs.length]);
   // 记下开着的文件页签和当前页签（刷新页面后恢复）。恢复之前不写，免得用空的盖掉上次的。
-  useEffect(() => { if (jobId && restored.current === jobId) saveTabs(jobId, files.map((f) => f.path), activeTab); }, [jobId, files, activeTab]);
+  useEffect(() => { if (storageId && restored.current === storageId) saveTabs(storageId, files.map((f) => f.path), activeTab, history); }, [storageId, files, activeTab, history]);
   // 引用到对话：和对话在同一个 Provider 里时缺省开。
+  useEffect(()=>{
+    if(!watchFiles||!jobId||!backend||!info?.dispatched||info.files===false)return;
+    return store.watchWorkspace(jobId,event=>{
+      setTick(value=>value+1);
+      const changed=new Set(event.changes.map(change=>change.path));
+      setFiles(previous=>previous.map(file=>changed.has(file.path)?{...file,version:file.version+1,reloadKey:(file.reloadKey??0)+1}:file));
+    },{intervalMs:fileWatchIntervalMs});
+  },[store,backend,jobId,watchFiles,fileWatchIntervalMs,info?.dispatched,info?.files]);
   const canQuote = (quoteToChat ?? inProvider) && !!jobId;
   const quote = useCallback((ref: Omit<BoardRef, "id"> & { id?: string }) => {
     if (jobId) store.addRef(jobId, { ...ref, id: ref.id ?? `${ref.kind}:${ref.label}` });
@@ -333,14 +352,17 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
     if (!acceptOpen || !backend) return;
     return store.registerBoard((target: string, what: OpenTarget) => {
       if (!jobRef.current || target !== jobRef.current) return false;
-      if (what.kind === "file") openPath(what.path);
-      else if (what.kind === "files") { setTab("files"); setDir(what.path ?? ""); }
-      else if (what.kind === "tab") setTab(what.id);
-      else setTab(what.kind);
+      if (what.kind === "file") { if (!builtinTabs.includes("files")) return false; openPath(what.path); }
+      else {
+        const targetPanel = what.kind === "tab" ? what.id : what.kind;
+        if (!panels.show(targetPanel)) return false;
+        setTab(targetPanel);
+        if (what.kind === "files") setDir(what.path ?? "");
+      }
       expandRef.current?.();
       return true;
     });
-  }, [store, backend, acceptOpen, openPath]);
+  }, [store, backend, acceptOpen, openPath, builtinTabs.join(","), allowedPanels.join(","), panels.show]);
 
   const navRef = useRef(onNavigate);
   navRef.current = onNavigate;
@@ -349,11 +371,12 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
   const openPaths = files.map((f) => f.path).join("\n");
   useEffect(() => {
     if (!jobId) return;
-    store.reportBoard(jobId, { tab: activeTab, dir, file: file?.path ?? null, files: openPaths ? openPaths.split("\n") : [] }, owner);
-  }, [store, jobId, activeTab, dir, file?.path, openPaths, owner]);
+    store.reportBoard(jobId, { tab: activeTab, dir, file: file?.path ?? null, files: files.map(file=>file.path), current:file?{path:file.path,sourceId:jobId}:null,opened:files.map(file=>({path:file.path,sourceId:jobId})),history,browser:activeTab==="browser"?browserPage:null,visible:!collapsed,autoContext:autoQuoteOpenFile??canQuote }, owner);
+  }, [store, jobId, activeTab, dir, file?.path, openPaths, history, browserPage, collapsed, autoQuoteOpenFile, canQuote, owner]);
   useEffect(() => () => { if (jobId) store.reportBoard(jobId, null, owner); }, [store, jobId, owner]);
 
   const body = () => {
+    if (!activeTab) return <div className="cli-board-empty">看板模块已全部关闭。通过右上角“管理看板模块”重新打开。</div>;
     if (!backend) return <div className="tc-note">当前后端不支持看板（需要任务中心提供 /api/jobs/:id/board）。</div>;
     if (!jobId) return <div className="tc-note">选择或开始一个对话后，这里显示它的文件、改动和浏览器。</div>;
     if (!info) return <div className="tc-note">{infoError ? `读取看板失败：${infoError}（稍后自动重试）` : "读取中…"}</div>;
@@ -380,11 +403,11 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
           path={file.path}
           size={file.size}
           mtime={file.mtime}
-          version={file.version}
+          version={file.version} reloadKey={file.reloadKey}
           actions={allFileActions}
           onOpenPath={(p) => openPath(p)}
           onQuoteText={canQuote ? (text) => quoteText(file.path, text) : undefined}
-          lead={<button className="cli-fv-back" onClick={() => setTab("files")} title="返回文件列表">‹</button>}
+          lead={<button className="cli-fv-back" onClick={() => { panels.show("files"); setTab("files"); }} title="返回文件列表">‹</button>}
         />
       );
     }
@@ -404,7 +427,7 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
   }
 
   return (
-    <aside className={`cli-ui cli-board sess-rail ${className ?? ""}`} data-theme={theme} style={style}>
+    <aside className={`cli-ui cli-board sess-rail ${className ?? ""}`} data-theme={theme} style={style} onPointerDown={()=>jobId&&store.activateBoard(jobId,owner)} onClickCapture={()=>jobId&&store.activateBoard(jobId,owner)} onFocusCapture={()=>jobId&&store.activateBoard(jobId,owner)}>
       <div className="rail-tabs">
         <div className="rail-tabs-scroll" role="tablist" ref={tabsRef}>
           {shownTabs.map((t) => t.startsWith(FILE_TAB) ? (
@@ -414,9 +437,15 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, re
               <button className="rail-ftab-x" onClick={() => closeFile(t.slice(FILE_TAB.length))} title="关闭（鼠标中键也可以）" aria-label={`关闭 ${tabLabel(t)}`}>{Icon.x()}</button>
             </span>
           ) : (
-            <button key={t} role="tab" aria-selected={activeTab === t} className={`rail-tab ${activeTab === t ? "on" : ""}`} onClick={() => setTab(t)}>{tabLabel(t)}</button>
+            <PanelTab key={t} id={t} label={tabLabel(t)} active={activeTab === t} onSelect={() => setTab(t)} onClose={() => {
+              panels.close(t);
+              if (activeTab === t) setTab(shownTabs.find(id => id !== t) ?? "");
+            }} />
           ))}
         </div>
+        <PanelControls available={allowedPanels} open={panels.open} label={tabLabel}
+          onShow={id => { panels.show(id); setTab(id); }}
+          onClose={id => { panels.close(id); if (activeTab === id) setTab(shownTabs.find(t => t !== id) ?? ""); }} />
         {info?.dispatched && <button className="rail-collapse" onClick={refreshAll} title={running ? "运行中 · 自动同步" : "刷新"}>
           <span className={`cli-sync-dot ${running ? "on" : ""}`} />↻
         </button>}

package/src/board/FileViewer.tsx

@@ -7,16 +7,16 @@
 //   · 文本只读开头 512 KB（Range），超过的可以切到「看末尾」（日志）；GBK 导出的文件按 GB18030 解。
 //   · 文件在变（任务还在写）：看板递增 version 时重读；读的时候保留滚动位置，原本在最底下的继续贴着底（像 tail -f）。
 import { Fragment, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type RefObject } from "react";
-import { fileUrlFromBase, type BoardBackend } from "../core/client.js";
-import { Icon } from "../ui/icons.js";
-import { Markdown } from "../ui/Markdown.js";
-import { FileLinkContext, FileOpenContext } from "../ui/fileLinks.js";
-import { codeLang, fmtSize, parseCsv, previewKind, resolveRelative, splitMarkdown, type PreviewKind } from "./fileKind.js";
-import { loadText, refreshText, type LoadedText } from "./textLoad.js";
-import { decodeText } from "../core/textDecode.js";
-import { relTime } from "../ui/format.js";
-import { downloadFile, mimeOf } from "./fileOps.js";
-import { bridgeDoc, frameToken, type FrameSelMessage } from "./frameQuote.js";
+import { fileUrlFromBase, type BoardBackend } from "../core/client";
+import { Icon } from "../ui/icons";
+import { Markdown } from "../ui/Markdown";
+import { FileLinkContext, FileOpenContext } from "../ui/fileLinks";
+import { codeLang, fmtSize, parseCsv, previewKind, resolveRelative, splitMarkdown, type PreviewKind } from "./fileKind";
+import { loadText, refreshText, type LoadedText } from "./textLoad";
+import { decodeText } from "../core/textDecode";
+import { relTime } from "../ui/format";
+import { downloadFile, mimeOf, readBoundedBuffer, FileReadLimitError } from "./fileOps";
+import { bridgeDoc, frameToken, type FrameSelMessage } from "./frameQuote";
 
 export { downloadFile };
 
@@ -93,13 +93,14 @@ function useFileSrc(backend: BoardBackend, jobId: string, path: string, enabled:
     setState({ url: null, error: null });
     if (size !== undefined && size > BLOB_PREVIEW_MAX) { setState({ url: null, error: `文件较大（${fmtSize(size)}），请下载后查看` }); return; }
     let alive = true;
+    const ctl = new AbortController();
     let objectUrl: string | null = null;
-    backend.readBuffer(jobId, path).then((buffer) => {
+    readBoundedBuffer(backend, jobId, path, BLOB_PREVIEW_MAX, {signal:ctl.signal}).then((buffer) => {
       if (!alive) return;
       objectUrl = URL.createObjectURL(new Blob([buffer], { type: mimeOf(path) }));
       setState({ url: objectUrl, error: null });
     }, (error: unknown) => { if (alive) setState({ url: null, error: error instanceof Error ? error.message : String(error) }); });
-    return () => { alive = false; if (objectUrl) URL.revokeObjectURL(objectUrl); };
+    return () => { alive = false; ctl.abort(); if (objectUrl) URL.revokeObjectURL(objectUrl); };
   }, [backend, jobId, path, enabled, version, links.blob, size, attempt]);
   return direct ? { url: direct, error: null } : state;
 }
@@ -118,6 +119,8 @@ export interface FileViewerProps {
   mtime?: number;
   /** 变了就重新读（看板在文件更新时递增）。 */
   version?: number;
+  /** 明确的文件变更事件使内容重新读取，不能只按末尾重叠判断为追加。 */
+  reloadKey?: number | string;
   /** 预览里点了别的本地文件（Markdown 里的链接）。 */
   onOpenPath?: (path: string) => void;
   onClose?: () => void;
@@ -133,7 +136,12 @@ export interface FileViewerProps {
 /** 选中的文字超过这么多只带开头（引用是给智能体指位置的，不是搬运全文）。 */
 const QUOTE_SELECTION_MAX = 3_000;
 
-export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onOpenPath, onClose, lead, actions = [], bare, onQuoteText }: FileViewerProps) {
+const viewerBackendIds=new WeakMap<BoardBackend,number>();let nextViewerBackendId=1;
+export function FileViewer(props:FileViewerProps) {
+  let id=viewerBackendIds.get(props.backend);if(id===undefined){id=nextViewerBackendId++;viewerBackendIds.set(props.backend,id);}
+  return <FileViewerInner key={JSON.stringify([id,props.jobId,props.path])} {...props}/>;
+}
+function FileViewerInner({ backend, jobId, path, size, mtime, version = 0, reloadKey, onOpenPath, onClose, lead, actions = [], bare, onQuoteText }: FileViewerProps) {
   const name = path.split("/").pop() || path;
   const kind: PreviewKind = previewKind(path);
   const [loaded, setLoaded] = useState<Loaded | null>(null);
@@ -177,20 +185,19 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
   useEffect(() => {
     if (!htmlBridge) return;
     const ctl = new AbortController();
-    let over = false;
     setHtmlDoc(null);
     setProgress(0);
-    backend.readBuffer(jobId, path, {
+    readBoundedBuffer(backend, jobId, path, HTML_QUOTE_MAX, {
       signal: ctl.signal,
       // 大小事先不知道（从对话里打开的）：读着读着超过上限就停下，改成直接打开。
-      onBytes: (n) => { setProgress(n); if (n > HTML_QUOTE_MAX && !over) { over = true; ctl.abort(); } },
+      onBytes: (n) => { setProgress(n); },
     }).then((buffer) => {
       if (ctl.signal.aborted) return;
       const url = linksRef.current.url?.(path);
       const base = url ? withVersion(new URL(url, window.location.href).href, version) : undefined;
       setHtmlDoc({ srcDoc: bridgeDoc(decodeText(new Uint8Array(buffer)).text, { token, base }) });
-    }, () => { if (over) setHtmlDoc("toobig"); else if (!ctl.signal.aborted) setHtmlDoc("fallback"); });
-    return () => { if (!over) ctl.abort(); };
+    }, (error:unknown) => { if (ctl.signal.aborted)return; if(error instanceof FileReadLimitError)setHtmlDoc("toobig");else setHtmlDoc("fallback"); });
+    return () => ctl.abort();
   }, [htmlBridge, backend, jobId, path, version, attempt, token]);
 
   // 重读时保留滚动位置；原本贴着底（或在看末尾）的继续贴着底——任务在往文件里写时像 tail -f。
@@ -267,15 +274,18 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
   };
   useEffect(() => {
     let alive = true;
+    const ctl=new AbortController();
     setError(null);
     if (needsSrc || kind === "binary") { setLoaded({ kind: "none" }); return; }
     if (kind === "docx") {
       if (size !== undefined && size > DOCX_PREVIEW_MAX) { setError(`文件较大（${fmtSize(size)}），请下载后查看`); return; }
       setProgress(0);
-      backend.readBuffer(jobId, path, { onBytes: (n) => { if (alive) setProgress(n); } }).then(async (buffer) => {
+      readBoundedBuffer(backend, jobId, path, DOCX_PREVIEW_MAX, { signal:ctl.signal,onBytes: (n) => { if (alive) setProgress(n); } }).then(async (buffer) => {
+        if(!alive)return;
         const mammoth = await import("mammoth");
         const convert = (mammoth as unknown as { convertToHtml: typeof import("mammoth").convertToHtml }).convertToHtml
           ?? (mammoth as unknown as { default: typeof import("mammoth") }).default.convertToHtml;
+        if(!alive)return;
         const input: Record<string, unknown> = { arrayBuffer: buffer };
         const B = (globalThis as { Buffer?: { from(b: ArrayBuffer): unknown } }).Buffer;
         if (B) input.buffer = B.from(buffer);
@@ -284,7 +294,7 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
       }).catch((e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); });
     } else {
       // 只是文件变了（同一个文件、同样看开头 / 末尾）：能接上就只取新增的部分（见 textLoad.ts），接不上再整个重读。
-      const key = `${path}|${tail}|${attempt}`;
+      const key = `${path}|${tail}|${attempt}|${reloadKey??""}`;
       const prev = loadedRef.current?.kind === "text" && textKey.current === key ? loadedRef.current : null;
       textKey.current = key;
       if (!prev) setProgress(0);
@@ -299,8 +309,8 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
         (e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); },
       );
     }
-    return () => { alive = false; };
-  }, [backend, jobId, path, kind, needsSrc, version, tail, attempt]); // eslint-disable-line react-hooks/exhaustive-deps
+    return () => { alive = false; ctl.abort(); };
+  }, [backend, jobId, path, kind, needsSrc, version, reloadKey, tail, attempt]); // eslint-disable-line react-hooks/exhaustive-deps
   useLayoutEffect(() => {
     const box = bodyRef.current;
     if (box && stick.current && loaded?.kind === "text") box.scrollTop = box.scrollHeight;

package/src/board/FilesPane.tsx

@@ -1,13 +1,13 @@
 // 工作区文件：面包屑 + 列表。目录点进去，文件点开预览；行尾可直接下载。
 // 列表随任务进展自动刷新（CliBoard 给 refreshKey），这次刷新里新出现 / 改过的文件标出来。
 import { useEffect, useRef, useState } from "react";
-import { CenterError, type BoardBackend } from "../core/client.js";
-import type { FileEntry } from "../core/types.js";
-import { Icon } from "../ui/icons.js";
-import { relTime } from "../ui/format.js";
-import { downloadFile } from "./fileOps.js";
-import { fmtSize } from "./fileKind.js";
-import { downloadFolder, FAILED_LIST_NAME, type FolderProgress } from "./folderDownload.js";
+import { CenterError, type BoardBackend } from "../core/client";
+import type { FileEntry } from "../core/types";
+import { Icon } from "../ui/icons";
+import { relTime } from "../ui/format";
+import { downloadFile } from "./fileOps";
+import { fmtSize } from "./fileKind";
+import { downloadFolder, FAILED_LIST_NAME, type FolderProgress } from "./folderDownload";
 
 export interface FilesPaneProps {
   backend: BoardBackend;
@@ -37,23 +37,40 @@ export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onLi
   const [zip, setZip] = useState<{ dir: string; progress: FolderProgress; abort: AbortController } | null>(null);
   // 下载的结果 / 失败（和「同步失败」分开：下载出错不代表列表过期）。
   const [notice, setNotice] = useState<{ text: string; err: boolean } | null>(null);
+  const zipAbort = useRef<AbortController | null>(null);
+  const downloadScope = useRef<object | null>({});
   const zipDir = (target: string) => {
-    if (zip) return;
+    if (zipAbort.current) return;
     const abort = new AbortController();
+    zipAbort.current = abort;
+    const current = () => zipAbort.current === abort && !abort.signal.aborted;
     setNotice(null);
     setZip({ dir: target, progress: { phase: "listing", files: 0, total: 0, bytes: 0 }, abort });
-    downloadFolder(backend, jobId, target, { signal: abort.signal, onProgress: (progress) => setZip((z) => (z && z.abort === abort ? { ...z, progress } : z)) })
-      .then(({ files, failed }) => {
-        if (failed.length) setNotice({ err: true, text: `已打包 ${files} 个文件；${failed.length} 个没读到（${failed[0].reason}${failed.length > 1 ? " 等" : ""}），清单在压缩包里的 ${FAILED_LIST_NAME}` });
+    downloadFolder(backend, jobId, target, { signal: abort.signal, onProgress: (progress) => { if (current()) setZip((z) => (z && z.abort === abort ? { ...z, progress } : z)); } })
+      .then(({ files, failed, failedListName }) => {
+        if (current() && failed.length) setNotice({ err: true, text: `已打包 ${files} 个文件；${failed.length} 个没读到（${failed[0].reason}${failed.length > 1 ? " 等" : ""}），清单在压缩包里的 ${failedListName??FAILED_LIST_NAME}` });
       })
-      .catch((err: unknown) => { if (!(err instanceof DOMException && err.name === "AbortError")) setNotice({ err: true, text: `打包下载失败：${err instanceof Error ? err.message : String(err)}` }); })
-      .finally(() => setZip((z) => (z && z.abort === abort ? null : z)));
+      .catch((err: unknown) => { if (current() && !(err instanceof DOMException && err.name === "AbortError")) setNotice({ err: true, text: `打包下载失败：${err instanceof Error ? err.message : String(err)}` }); })
+      .finally(() => { if (zipAbort.current === abort) { zipAbort.current = null; setZip(null); } });
   };
   const downloadOne = (path: string, size: number) => {
+    const scope = downloadScope.current;
     setNotice(null);
-    void downloadFile(backend, jobId, path, size).catch((err: unknown) => setNotice({ err: true, text: `下载失败：${err instanceof Error ? err.message : String(err)}` }));
+    void downloadFile(backend, jobId, path, size).catch((err: unknown) => { if (scope === downloadScope.current) setNotice({ err: true, text: `下载失败：${err instanceof Error ? err.message : String(err)}` }); });
   };
-  useEffect(() => () => zip?.abort.abort(), [jobId]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    downloadScope.current = {};
+    setZip(null);
+    setNotice(null);
+    setEntries(null);
+    seen.current = { dir, mtimes: null };
+    setFresh(new Set());
+    return () => {
+      downloadScope.current = null;
+      zipAbort.current?.abort();
+      zipAbort.current = null;
+    };
+  }, [jobId, backend]); // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
     let alive = true;

package/src/board/PanelControls.tsx

@@ -0,0 +1,28 @@
+import { useState } from 'react';
+import { Icon } from '../ui/icons';
+import { Popover } from '../ui/Popover';
+export function PanelTab({ id, label, active, onSelect, onClose }: {
+  id: string; label: string; active: boolean; onSelect: () => void; onClose: () => void;
+}) {
+  return <span className={`rail-tab rail-ftab ${active ? 'on' : ''}`} onClick={onSelect}>
+    <button className="rail-ftab-l" role="tab" aria-selected={active} aria-label={label} data-panel-id={id} onClick={event => { event.stopPropagation(); onSelect(); }}>{label}</button>
+    <button className="rail-ftab-x" aria-label={id.startsWith("file:") ? `关闭 ${label}` : `关闭${label}面板`} title={id === 'browser' ? '隐藏浏览器面板，浏览器任务继续运行' : `关闭${label}面板，可从添加模块重新打开`}
+      onClick={event => { event.stopPropagation(); onClose(); }}>{Icon.x()}</button>
+  </span>;
+}
+export function PanelControls({ available, open, label, onShow, onClose }: {
+  available: readonly string[]; open: readonly string[]; label: (id: string) => string;
+  onShow: (id: string) => void; onClose: (id: string) => void;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  return <div className="cli-panel-controls">
+    <button className="rail-collapse" aria-label="管理看板模块" title="添加或关闭看板模块" aria-expanded={expanded} onClick={() => setExpanded(value => !value)}>{Icon.plus()}</button>
+    {expanded && <Popover onClose={() => setExpanded(false)}>
+      <div className="pop-sec">看板模块 · 可独立打开或关闭</div>
+      {available.map(id => <button key={id} className="pop-item" aria-label={`${open.includes(id) ? '关闭' : '打开'}${label(id)}面板`} aria-pressed={open.includes(id)}
+        onClick={() => { if (open.includes(id)) onClose(id); else onShow(id); setExpanded(false); }}>
+        <span>{label(id)}</span>{open.includes(id) ? Icon.check() : Icon.plus()}
+      </button>)}
+    </Popover>}
+  </div>;
+}

package/src/board/blocks.tsx

@@ -7,11 +7,11 @@
 // （baseUrl / token / line / headers）建一个。不给 jobId 时跟 Provider 的选中走。
 // 它们只依赖中枢的看板接口（/api/jobs/:id/files、/browser…），不依赖 cli-chat / cli-board。
 import { 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 } from "../core/provider.js";
-import { FileViewer, type FileAction } from "./FileViewer.js";
-import { BrowserPane } from "./BrowserPane.js";
+import { CliErrorBoundary } from "../ui/ErrorBoundary";
+import type { CliEvent, CliStore, CliStoreOptions } from "../core/store";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider";
+import { FileViewer, type FileAction } from "./FileViewer";
+import { BrowserPane } from "./BrowserPane";
 
 interface BlockProps extends CliStoreOptions {
   /** 哪个对话（center 的 job_id）。不给就跟 Provider 的选中走。 */

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;
+}