@spzxg/cli-ui 0.4.0 → 0.6.0

package/src/board/FileViewer.tsx

@@ -1,12 +1,21 @@
 // 文件预览：Markdown / 代码 / 文本 / CSV / 图片 / PDF / HTML（沙箱）/ Word，其余给下载。
 // 看板和对话里的弹窗共用。文件经 center 转发读取（浏览器不直连执行节点）。
-import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
-import type { BoardBackend } from "../core/client.js";
+//
+// 远端、实时、超大文件：
+//   · 图片 / PDF / HTML / 下载一律用浏览器能直接打开的地址（同源代理时就是文件接口；没有代理注入令牌时用中枢发的短期链接），
+//     流式加载、支持断点，不把文件读进浏览器内存。中枢太旧发不了短期链接时才先 fetch 成 blob，这时超大的文件不预览、只给下载。
+//   · 文本只读开头 512 KB（Range），超过的可以切到「看末尾」（日志）；GBK 导出的文件按 GB18030 解。
+//   · 文件在变（任务还在写）：看板递增 version 时重读；读的时候保留滚动位置，原本在最底下的继续贴着底（像 tail -f）。
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } 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, type PreviewKind } from "./fileKind.js";
 import { relTime } from "../ui/format.js";
+import { downloadFile, mimeOf } from "./fileOps.js";
+
+export { downloadFile };
 
 /** 看板 / 预览里给文件加的自定义操作（例如「在对话里引用」「发到工作协同」）。 */
 export interface FileAction {
@@ -19,54 +28,76 @@ export interface FileAction {
 
 const TEXT_MAX = 512 * 1024;
 const HIGHLIGHT_MAX = 120 * 1024;
+/** Markdown 超过这么多按纯文本显示（渲染几百 KB 的 Markdown 会让页面卡住）。 */
+const MARKDOWN_RENDER_MAX = 300 * 1024;
+/** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的不预览、不在浏览器里拼下载。 */
+const BLOB_PREVIEW_MAX = 50 * 1024 * 1024;
+/** Word 在浏览器里转换，太大的只给下载。 */
+const DOCX_PREVIEW_MAX = 30 * 1024 * 1024;
+/** 短期链接 30 分钟有效：每 5 分钟问一次（客户端缓存着，快到期才真的换），长时间开着的预览不会失效。 */
+const LINK_RECHECK_MS = 5 * 60_000;
+
+/**
+ * 浏览器能直接打开的文件地址。directLinks（同源代理）时马上有；否则等中枢发的短期链接（pending = 还在换）；
+ * 中枢发不了（太旧）时 url 为 null、blob = true，调用方退回先 fetch 再显示。
+ */
+function useFileLinks(backend: BoardBackend, jobId: string): { url: ((path: string, download?: boolean) => string) | null; pending: boolean; blob: boolean } {
+  const [linkBase, setLinkBase] = useState<string | null | undefined>(undefined);
+  useEffect(() => {
+    if (backend.directLinks || !backend.fileLinkBase) return;
+    let alive = true;
+    const check = () => backend.fileLinkBase!(jobId).then((b) => { if (alive) setLinkBase(b); }, () => { if (alive) setLinkBase((old) => old ?? null); });
+    void check();
+    const timer = setInterval(check, LINK_RECHECK_MS);
+    return () => { alive = false; clearInterval(timer); };
+  }, [backend, jobId]);
+  return useMemo(() => {
+    if (backend.directLinks) return { url: (path: string, download?: boolean) => backend.fileUrl(jobId, path, { download }), pending: false, blob: false };
+    if (!backend.fileLinkBase || linkBase === null) return { url: null, pending: false, blob: true };
+    if (linkBase === undefined) return { url: null, pending: true, blob: false };
+    return { url: (path: string, download?: boolean) => fileUrlFromBase(linkBase, path, download), pending: false, blob: false };
+  }, [backend, jobId, linkBase]);
+}
 
-const MIME: Record<string, string> = {
-  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
-  bmp: "image/bmp", ico: "image/x-icon", avif: "image/avif", pdf: "application/pdf", html: "text/html", htm: "text/html",
+const withVersion = (url: string, version: number, attempt = 0) => {
+  const q = [version ? `v=${version}` : "", attempt ? `r=${attempt}` : ""].filter(Boolean).join("&");
+  return q ? `${url}${url.includes("?") ? "&" : "?"}${q}` : url;
 };
+/** 读了这么久还没好：提示「网络较慢」，不让人以为卡死了。 */
+const SLOW_HINT_MS = 8_000;
+function useSlow(loading: boolean) {
+  const [slow, setSlow] = useState(false);
+  useEffect(() => {
+    setSlow(false);
+    if (!loading) return;
+    const t = setTimeout(() => setSlow(true), SLOW_HINT_MS);
+    return () => clearTimeout(t);
+  }, [loading]);
+  return slow;
+}
 
-/** 能直接用的地址；需要请求头时先 fetch 成 blob 地址（离开时释放）。 */
-function useFileSrc(backend: BoardBackend, jobId: string, path: string, enabled: boolean, version: number) {
+/** 图片 / PDF / HTML 的地址：能直接用就用；只能 fetch 时先读成 blob（离开时释放），太大的不读。 */
+function useFileSrc(backend: BoardBackend, jobId: string, path: string, enabled: boolean, version: number, size: number | undefined, links: ReturnType<typeof useFileLinks>, attempt = 0) {
   const [state, setState] = useState<{ url: string | null; error: string | null }>({ url: null, error: null });
+  const direct = enabled && links.url ? withVersion(links.url(path), version, attempt) : null;
   useEffect(() => {
-    if (!enabled) return;
-    if (backend.directLinks) {
-      const url = backend.fileUrl(jobId, path);
-      setState({ url: version ? `${url}${url.includes("?") ? "&" : "?"}v=${version}` : url, error: null });
-      return;
-    }
+    if (!enabled || !links.blob) return;
+    setState({ url: null, error: null });
+    if (size !== undefined && size > BLOB_PREVIEW_MAX) { setState({ url: null, error: `文件较大（${fmtSize(size)}），请下载后查看` }); return; }
     let alive = true;
     let objectUrl: string | null = null;
     backend.readBuffer(jobId, path).then((buffer) => {
       if (!alive) return;
-      const ext = path.split(".").pop()?.toLowerCase() ?? "";
-      objectUrl = URL.createObjectURL(new Blob([buffer], { type: MIME[ext] ?? "application/octet-stream" }));
+      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); };
-  }, [backend, jobId, path, enabled, version]);
-  return state;
-}
-
-/** 下载：能直接用地址就用（不占内存），否则 fetch 成 blob 再存。 */
-export async function downloadFile(backend: BoardBackend, jobId: string, path: string) {
-  const name = path.split("/").pop() || "file";
-  const a = document.createElement("a");
-  a.download = name;
-  let objectUrl: string | null = null;
-  if (backend.directLinks) a.href = backend.fileUrl(jobId, path, { download: true });
-  else {
-    objectUrl = URL.createObjectURL(new Blob([await backend.readBuffer(jobId, path)]));
-    a.href = objectUrl;
-  }
-  document.body.appendChild(a);
-  a.click();
-  a.remove();
-  if (objectUrl) setTimeout(() => URL.revokeObjectURL(objectUrl!), 30_000);
+  }, [backend, jobId, path, enabled, version, links.blob, size, attempt]);
+  return direct ? { url: direct, error: null } : state;
 }
 
 type Loaded =
-  | { kind: "text"; text: string; truncated: boolean; size: number }
+  | { kind: "text"; text: string; truncated: boolean; size: number; tail: boolean; encoding?: string }
   | { kind: "docx"; html: string }
   | { kind: "none" };
 
@@ -87,9 +118,14 @@ export interface FileViewerProps {
   actions?: FileAction[];
   /** 隐藏头部（宿主自己做）。 */
   bare?: boolean;
+  /** 给了就支持「选中文字 → 引用到对话」：在预览里选中一段文字时浮出按钮（Markdown / 代码 / 文本 / 表格）。 */
+  onQuoteText?: (text: string) => void;
 }
 
-export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onOpenPath, onClose, lead, actions = [], bare }: 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 name = path.split("/").pop() || path;
   const kind: PreviewKind = previewKind(path);
   const [loaded, setLoaded] = useState<Loaded | null>(null);
@@ -97,14 +133,75 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
   const [copied, setCopied] = useState(false);
   const [busy, setBusy] = useState(false);
   const [mode, setMode] = useState<"preview" | "source">("preview");
+  // 超大文本：看开头还是看末尾（日志看末尾）。
+  const [tail, setTail] = useState(false);
+  // 放大：盖住页面看（看板窄的时候看报告、表格、图片）。Esc 还原。
+  const [big, setBig] = useState(false);
+  // 点「重试」：重新读（图片 / PDF 换一个地址参数，绕开浏览器缓存的失败）。
+  const [attempt, setAttempt] = useState(0);
+  const retry = () => { setError(null); setLoaded(null); setAttempt((n) => n + 1); };
+  useEffect(() => {
+    if (!big) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") setBig(false); };
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    window.addEventListener("keydown", onKey);
+    return () => { window.removeEventListener("keydown", onKey); document.body.style.overflow = prev; };
+  }, [big]);
   const needsSrc = kind === "image" || kind === "pdf" || kind === "html";
-  const src = useFileSrc(backend, jobId, path, needsSrc, version);
+  const links = useFileLinks(backend, jobId);
+  const knownSize = size ?? (loaded?.kind === "text" ? loaded.size : undefined);
+  const src = useFileSrc(backend, jobId, path, needsSrc, version, knownSize, links, attempt);
 
+  // 重读时保留滚动位置；原本贴着底（或在看末尾）的继续贴着底——任务在往文件里写时像 tail -f。
+  const bodyRef = useRef<HTMLDivElement | null>(null);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const stick = useRef(false);
+  // 选中文字 → 浮出「引用到对话」。按钮放在选区上方；滚动、点别处、选区清空时收起。
+  const [sel, setSel] = useState<{ text: string; x: number; y: number } | null>(null);
+  useEffect(() => {
+    if (!onQuoteText) return;
+    const read = () => {
+      const s = window.getSelection();
+      const body = bodyRef.current;
+      const root = rootRef.current;
+      if (!s || s.isCollapsed || !s.rangeCount || !body || !root || !body.contains(s.anchorNode) || !body.contains(s.focusNode)) { setSel(null); return; }
+      const text = s.toString().trim();
+      if (!text) { setSel(null); return; }
+      const box = root.getBoundingClientRect();
+      // 取不到选区位置的环境（老浏览器、测试环境）：按钮放在预览顶部中间。
+      const range = s.getRangeAt(0);
+      const r = typeof range.getBoundingClientRect === "function" ? range.getBoundingClientRect() : { left: box.left + box.width / 2, width: 0, top: box.top + 48 };
+      setSel({ text, x: Math.min(Math.max(8, r.left - box.left + r.width / 2), box.width - 8), y: Math.max(40, r.top - box.top) });
+    };
+    const onUp = () => setTimeout(read, 0);
+    const onChange = () => { const s = window.getSelection(); if (!s || s.isCollapsed) setSel(null); };
+    const body = bodyRef.current;
+    document.addEventListener("mouseup", onUp);
+    document.addEventListener("keyup", onUp);
+    document.addEventListener("selectionchange", onChange);
+    const onScroll = () => setSel(null);
+    body?.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      document.removeEventListener("mouseup", onUp);
+      document.removeEventListener("keyup", onUp);
+      document.removeEventListener("selectionchange", onChange);
+      body?.removeEventListener("scroll", onScroll);
+    };
+  }, [onQuoteText, loaded]);
+  const quoteSelection = () => {
+    if (!sel || !onQuoteText) return;
+    const text = sel.text.length > QUOTE_SELECTION_MAX ? `${sel.text.slice(0, QUOTE_SELECTION_MAX)}…` : sel.text;
+    onQuoteText(text);
+    window.getSelection()?.removeAllRanges();
+    setSel(null);
+  };
   useEffect(() => {
     let alive = true;
     setError(null);
     if (needsSrc || kind === "binary") { setLoaded({ kind: "none" }); return; }
     if (kind === "docx") {
+      if (size !== undefined && size > DOCX_PREVIEW_MAX) { setError(`文件较大（${fmtSize(size)}），请下载后查看`); return; }
       backend.readBuffer(jobId, path).then(async (buffer) => {
         const mammoth = await import("mammoth");
         const convert = (mammoth as unknown as { convertToHtml: typeof import("mammoth").convertToHtml }).convertToHtml
@@ -116,39 +213,59 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
         if (alive) setLoaded({ kind: "docx", html: out.value });
       }).catch((e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); });
     } else {
-      backend.readText(jobId, path, TEXT_MAX).then(
-        (r) => { if (alive) setLoaded({ kind: "text", text: r.text, truncated: r.truncated, size: r.size }); },
+      backend.readText(jobId, path, TEXT_MAX, { tail }).then(
+        (r) => {
+          if (!alive) return;
+          const box = bodyRef.current;
+          stick.current = tail || (!!box && box.scrollHeight > box.clientHeight && box.scrollHeight - box.scrollTop - box.clientHeight < 40);
+          setLoaded({ kind: "text", text: r.text, truncated: r.truncated, size: r.size, tail: !!r.tail, encoding: r.encoding });
+        },
         (e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); },
       );
     }
     return () => { alive = false; };
-  }, [backend, jobId, path, kind, needsSrc, version]);
+  }, [backend, jobId, path, kind, needsSrc, version, 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;
+  }, [loaded]);
 
   const fileInfo = useCallback(() => ({
-    path, name, url: backend.fileUrl(jobId, path), downloadUrl: backend.fileUrl(jobId, path, { download: true }),
-  }), [backend, jobId, path, name]);
+    path, name, url: links.url?.(path) ?? backend.fileUrl(jobId, path), downloadUrl: links.url?.(path, true) ?? backend.fileUrl(jobId, path, { download: true }),
+  }), [backend, jobId, path, name, links]);
 
   const download = async () => {
     setBusy(true);
-    try { await downloadFile(backend, jobId, path); } catch (e) { setError(e instanceof Error ? e.message : String(e)); } finally { setBusy(false); }
-  };
-  const openNew = () => {
-    if (backend.directLinks) window.open(backend.fileUrl(jobId, path), "_blank", "noopener");
-    else if (src.url) window.open(src.url, "_blank", "noopener");
+    try { await downloadFile(backend, jobId, path, knownSize); } catch (e) { setError(e instanceof Error ? e.message : String(e)); } finally { setBusy(false); }
   };
+  const openUrl = links.url ? links.url(path) : src.url;
+  const openNew = () => { if (openUrl) window.open(openUrl, "_blank", "noopener"); };
   const copyPath = () => {
     void navigator.clipboard?.writeText(path).then(() => { setCopied(true); setTimeout(() => setCopied(false), 1200); }, () => undefined);
   };
 
   // Markdown 里的相对链接 / 图片：相对这个文件所在目录。
-  const mdResolve = useMemo(() => (href: string) => (backend.directLinks ? backend.fileUrl(jobId, resolveRelative(path, href)) : null), [backend, jobId, path]);
+  const mdResolve = useMemo(() => (href: string) => links.url?.(resolveRelative(path, href)) ?? null, [links, path]);
   const mdOpen = useMemo(() => (onOpenPath ? (href: string) => { onOpenPath(resolveRelative(path, href)); return true; } : null), [onOpenPath, path]);
 
   const canSource = kind === "markdown" || kind === "html" || kind === "csv";
-  const shownSize = size ?? (loaded?.kind === "text" ? loaded.size : undefined);
+  const shownSize = knownSize;
+  const text = loaded?.kind === "text" ? loaded : null;
+  // 太大的 Markdown 按纯文本显示（渲染会卡住页面）。
+  const mdTooBig = !!text && kind === "markdown" && text.text.length > MARKDOWN_RENDER_MAX;
+  const loading = !error && !src.error && (needsSrc ? !src.url : !loaded);
+  const slow = useSlow(loading);
+  const slowNote = slow ? <div className="cli-fv-slow">网络较慢或执行节点忙，仍在读取{shownSize ? `（${fmtSize(shownSize)}）` : ""}…</div> : null;
 
   return (
-    <div className="cli-fv">
+    <>
+    {big && <div className="cli-ui cli-fv-backdrop" onClick={() => setBig(false)} />}
+    <div className={`cli-fv ${big ? "cli-fv-big" : ""}`} ref={rootRef}>
+      {sel && (
+        <button className="cli-fv-selq" style={{ left: sel.x, top: sel.y }} onMouseDown={(e) => e.preventDefault()} onClick={quoteSelection} title="把选中的这段带进下一条消息">
+          {Icon.board()} 引用到对话{sel.text.length > 1 ? `（${sel.text.length > QUOTE_SELECTION_MAX ? `前 ${QUOTE_SELECTION_MAX}` : sel.text.length} 字）` : ""}
+        </button>
+      )}
       {!bare && (
         <div className="cli-fv-h">
           {lead}
@@ -157,6 +274,7 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
           <span className="cli-fv-meta">
             {shownSize !== undefined && fmtSize(shownSize)}
             {mtime && mtime > 0 ? ` · ${relTime(mtime)}更新` : ""}
+            {text?.encoding && text.encoding !== "utf-8" ? ` · ${text.encoding.toUpperCase()}` : ""}
           </span>
           <span className="cli-fv-sp" />
           {canSource && (
@@ -168,14 +286,16 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
             <button key={a.label} className="cli-fv-btn" title={a.title} onClick={() => a.onClick(fileInfo(), jobId)}>{a.label}</button>
           ))}
           <button className="cli-fv-icon" onClick={copyPath} title={copied ? "已复制" : "复制路径"}>{copied ? Icon.check() : Icon.copy()}</button>
-          <button className="cli-fv-icon" onClick={openNew} title="在新窗口打开" disabled={!backend.directLinks && !src.url}>{Icon.external()}</button>
+          <button className="cli-fv-icon cli-fv-zoom" onClick={() => setBig((b) => !b)} title={big ? "还原（Esc）" : "放大查看"} aria-pressed={big}>{big ? "⤡" : "⤢"}</button>
+          <button className="cli-fv-icon" onClick={openNew} title="在新窗口打开" disabled={!openUrl}>{Icon.external()}</button>
           <button className="cli-fv-icon" onClick={() => void download()} title="下载" disabled={busy}>{Icon.download()}</button>
           {onClose && <button className="cli-fv-icon" onClick={onClose} title="关闭">{Icon.x()}</button>}
         </div>
       )}
-      <div className={`cli-fv-b k-${kind}`}>
+      <div className={`cli-fv-b k-${kind}`} ref={bodyRef}>
         {error || src.error ? (
           <div className="cli-fv-note err">读取失败：{error ?? src.error}
+            <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={retry}>重试</button>
             <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={() => void download()}>{Icon.download()} 下载</button>
           </div>
         ) : kind === "binary" ? (
@@ -183,36 +303,97 @@ export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onO
             <button className="btn btn-accent btn-sm" style={{ marginLeft: 8 }} onClick={() => void download()} disabled={busy}>{Icon.download()} 下载</button>
           </div>
         ) : needsSrc ? (
-          !src.url ? <div className="cli-fv-note">加载中…</div>
-            : kind === "image" ? <div className="cli-fv-img"><img src={src.url} alt={name} /></div>
+          !src.url ? <div className="cli-fv-note">加载中…{slowNote}</div>
+            : kind === "image" ? <ImageView key={src.url} src={src.url} name={name} onRetry={retry} />
               : kind === "pdf" ? <iframe className="cli-fv-frame" src={src.url} title={name} />
                 : mode === "source" ? <SourceView backend={backend} jobId={jobId} path={path} version={version} />
                   // HTML：节点按沙箱 CSP 返回；这里再加 iframe 沙箱（不给同源），页面脚本碰不到宿主。
                   : <iframe className="cli-fv-frame" src={src.url} title={name} sandbox="allow-scripts allow-popups allow-forms allow-modals" />
         ) : !loaded ? (
-          <div className="cli-fv-note">加载中…</div>
+          <div className="cli-fv-note">加载中…{slowNote}</div>
         ) : loaded.kind === "docx" ? (
           <iframe className="cli-fv-frame doc" title={name} sandbox="" srcDoc={docxPage(loaded.html)} />
-        ) : loaded.kind === "text" ? (
+        ) : text ? (
           <>
-            {loaded.truncated && <div className="cli-fv-trunc">文件较大，只显示前 {fmtSize(TEXT_MAX)}；完整内容请下载。</div>}
-            {kind === "markdown" && mode === "preview" ? (
+            {(text.truncated || tail) && (
+              <div className="cli-fv-trunc">
+                {tail && !text.tail ? "执行节点不支持只读末尾，下面仍是开头；" : ""}
+                文件较大（{fmtSize(text.size)}），只显示{text.tail ? "最后" : "前"} {fmtSize(TEXT_MAX)}；完整内容请下载。
+                <button className="cli-fv-btn" onClick={() => setTail(!tail)}>{tail ? "看开头" : "看末尾"}</button>
+              </div>
+            )}
+            {mdTooBig && <div className="cli-fv-trunc">Markdown 较大，按纯文本显示。</div>}
+            {kind === "markdown" && mode === "preview" && !mdTooBig ? (
               <FileLinkContext.Provider value={mdResolve}>
                 <FileOpenContext.Provider value={mdOpen}>
-                  <div className="cli-fv-md"><Markdown>{loaded.text}</Markdown></div>
+                  <div className="cli-fv-md"><Markdown>{text.text}</Markdown></div>
                 </FileOpenContext.Provider>
               </FileLinkContext.Provider>
             ) : kind === "csv" && mode === "preview" ? (
-              <CsvTable text={loaded.text} />
-            ) : kind === "code" && loaded.text.length <= HIGHLIGHT_MAX ? (
-              <div className="cli-fv-code"><Markdown>{fenced(loaded.text, codeLang(path))}</Markdown></div>
+              <CsvTable text={text.text} />
+            ) : kind === "code" && text.text.length <= HIGHLIGHT_MAX ? (
+              <div className="cli-fv-code"><Markdown>{fenced(text.text, codeLang(path))}</Markdown></div>
             ) : (
-              <pre className="cli-fv-pre">{loaded.text}</pre>
+              <pre className="cli-fv-pre">{text.text}</pre>
             )}
           </>
         ) : null}
       </div>
     </div>
+    </>
+  );
+}
+
+/** 图片：缺省适应宽度；可以放大缩小、看原始大小，Ctrl / ⌘ + 滚轮也能缩放。 */
+function ImageView({ src, name, onRetry }: { src: string; name: string; onRetry?: () => void }) {
+  const [scale, setScale] = useState<number | null>(null); // null = 适应
+  const [natural, setNatural] = useState<{ w: number; h: number } | null>(null);
+  // 加载失败（网络断了、链接过期、文件坏了 / 不是浏览器认识的图片）：说清楚，给重试。
+  const [failed, setFailed] = useState(false);
+  const loadingImg = !natural && !failed;
+  const slow = useSlow(loadingImg);
+  const boxRef = useRef<HTMLDivElement | null>(null);
+  const fitScale = () => {
+    const box = boxRef.current;
+    if (!box || !natural) return 1;
+    return Math.min(1, (box.clientWidth - 32) / natural.w);
+  };
+  const zoom = (factor: number) => setScale((s) => Math.min(8, Math.max(0.1, (s ?? fitScale()) * factor)));
+  useEffect(() => {
+    const box = boxRef.current;
+    if (!box) return;
+    const onWheel = (e: WheelEvent) => {
+      if (!e.ctrlKey && !e.metaKey) return;
+      e.preventDefault();
+      zoom(e.deltaY < 0 ? 1.1 : 1 / 1.1);
+    };
+    box.addEventListener("wheel", onWheel, { passive: false });
+    return () => box.removeEventListener("wheel", onWheel);
+  }); // eslint-disable-line react-hooks/exhaustive-deps
+  const style = scale === null || !natural ? undefined : { width: Math.round(natural.w * scale), maxWidth: "none" };
+  return (
+    <div className="cli-fv-imgwrap">
+      <div className="cli-fv-imgbar">
+        <button className="cli-fv-btn" onClick={() => zoom(1 / 1.25)} title="缩小">−</button>
+        <span className="cli-fv-imgpct">{scale === null ? "适应" : `${Math.round(scale * 100)}%`}</span>
+        <button className="cli-fv-btn" onClick={() => zoom(1.25)} title="放大">＋</button>
+        <button className="cli-fv-btn" onClick={() => setScale(null)} disabled={scale === null}>适应</button>
+        <button className="cli-fv-btn" onClick={() => setScale(1)} disabled={scale === 1}>原始大小</button>
+        {natural && <span className="cli-fv-imgpct">{natural.w} × {natural.h}</span>}
+      </div>
+      <div className={`cli-fv-img ${scale === null ? "" : "zoomed"}`} ref={boxRef}>
+        {failed ? (
+          <div className="cli-fv-img-err">图片没有加载出来（网络中断、链接过期，或文件损坏 / 格式不支持）。
+            {onRetry && <button className="btn btn-line btn-sm" onClick={onRetry}>重试</button>}
+          </div>
+        ) : (
+          <>
+            <img src={src} alt={name} style={style} onLoad={(e) => setNatural({ w: e.currentTarget.naturalWidth, h: e.currentTarget.naturalHeight })} onError={() => setFailed(true)} />
+            {slow && <div className="cli-fv-slow">图片较大或网络较慢，仍在加载…</div>}
+          </>
+        )}
+      </div>
+    </div>
   );
 }
 

package/src/board/FilesPane.tsx

@@ -5,8 +5,9 @@ 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 "./FileViewer.js";
+import { downloadFile } from "./fileOps.js";
 import { fmtSize } from "./fileKind.js";
+import { downloadFolder, FAILED_LIST_NAME, type FolderProgress } from "./folderDownload.js";
 
 export interface FilesPaneProps {
   backend: BoardBackend;
@@ -22,6 +23,7 @@ export interface FilesPaneProps {
 export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onListed }: FilesPaneProps) {
   const [entries, setEntries] = useState<FileEntry[] | null>(null);
   const [truncated, setTruncated] = useState(false);
+  const [total, setTotal] = useState<number | undefined>(undefined);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
   // 这个目录上一次看到的 mtime：用来标「新」。第一次打开目录不标。
@@ -31,6 +33,27 @@ export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onLi
   onListedRef.current = onListed;
   const onDirRef = useRef(onDir);
   onDirRef.current = onDir;
+  // 打包下载文件夹：同一时间只打一个，可以取消。
+  const [zip, setZip] = useState<{ dir: string; progress: FolderProgress; abort: AbortController } | null>(null);
+  // 下载的结果 / 失败（和「同步失败」分开：下载出错不代表列表过期）。
+  const [notice, setNotice] = useState<{ text: string; err: boolean } | null>(null);
+  const zipDir = (target: string) => {
+    if (zip) return;
+    const abort = new AbortController();
+    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}` });
+      })
+      .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)));
+  };
+  const downloadOne = (path: string, size: number) => {
+    setNotice(null);
+    void downloadFile(backend, jobId, path, size).catch((err: unknown) => setNotice({ err: true, text: `下载失败：${err instanceof Error ? err.message : String(err)}` }));
+  };
+  useEffect(() => () => zip?.abort.abort(), [jobId]); // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
     let alive = true;
@@ -49,6 +72,7 @@ export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onLi
       seen.current.mtimes = new Map(res.entries.map((e) => [e.path, e.mtime]));
       setEntries(res.entries);
       setTruncated(res.truncated);
+      setTotal(res.total);
       onListedRef.current?.(dir, res.entries);
     }, (e: unknown) => {
       if (!alive) return;
@@ -73,7 +97,28 @@ export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onLi
         ))}
         <span className="cli-fv-sp" />
         {loading && entries && <span className="cli-files-sync" title="正在同步">同步中…</span>}
+        {entries && entries.length > 0 && !zip && (
+          <button className="cli-fv-icon" title={`把「${dir || "工作区"}」打包成 ZIP 下载`} onClick={() => zipDir(dir)}>{Icon.download()}</button>
+        )}
       </div>
+      {zip && (
+        <div className="cli-fv-trunc cli-zip-bar">
+          {zip.progress.phase === "listing" ? `正在列出「${zip.dir || "工作区"}」里的文件…`
+            : zip.progress.phase === "reading" ? `正在读取 ${zip.progress.files} / ${zip.progress.total} 个文件（${fmtSize(zip.progress.bytes)}${zip.progress.totalBytes ? ` / ${fmtSize(zip.progress.totalBytes)}` : ""}）`
+              + (zip.progress.retrying ? ` · 网络不稳，正在重试 ${zip.progress.retrying.split("/").pop()}` : "")
+              + (zip.progress.failed ? ` · ${zip.progress.failed} 个没读到` : "") + "…"
+              : "正在打包…"}
+          {zip.progress.phase === "reading" && zip.progress.totalBytes ? (
+            <span className="cli-zip-meter"><span style={{ width: `${Math.min(100, (zip.progress.bytes / Math.max(1, zip.progress.totalBytes)) * 100)}%` }} /></span>
+          ) : null}
+          <button className="cli-fv-btn" onClick={() => zip.abort.abort()}>取消</button>
+        </div>
+      )}
+      {notice && (
+        <div className={`cli-fv-trunc ${notice.err ? "cli-files-err" : ""}`}>{notice.text}
+          <button className="cli-fv-btn" onClick={() => setNotice(null)}>知道了</button>
+        </div>
+      )}
       {error && entries && <div className="cli-fv-trunc">同步失败：{error}（下面是上次读到的列表，有进展时会自动再试，也可以点右上角 ↻）</div>}
       {error && !entries ? (
         <div className="cli-fv-note err">{error}<br /><span style={{ color: "var(--ink-3)" }}>有进展时会自动再试，也可以点右上角 ↻ 重试。</span></div>
@@ -96,12 +141,14 @@ export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onLi
                 {fresh.has(e.path) && <span className="cli-frow-new">有更新</span>}
                 <span className="cli-frow-meta">{e.type === "file" ? `${fmtSize(e.size)} · ` : ""}{relTime(e.mtime)}</span>
               </button>
-              {e.type === "file" && (
-                <button className="cli-frow-dl" title="下载" onClick={() => void downloadFile(backend, jobId, e.path).catch((err: unknown) => setError(err instanceof Error ? err.message : String(err)))}>{Icon.download()}</button>
+              {e.type === "file" ? (
+                <button className="cli-frow-dl" title="下载" onClick={() => downloadOne(e.path, e.size)}>{Icon.download()}</button>
+              ) : (
+                <button className="cli-frow-dl" title="打包成 ZIP 下载" disabled={!!zip} onClick={() => zipDir(e.path)}>{Icon.download()}</button>
               )}
             </div>
           ))}
-          {truncated && <div className="cli-fv-trunc">文件太多，只列出前 2000 个。</div>}
+          {truncated && <div className="cli-fv-trunc">文件太多{total ? `（共 ${total.toLocaleString()} 个）` : ""}，只列出前 {entries.length.toLocaleString()} 个。</div>}
         </div>
       )}
     </div>

package/src/board/blocks.tsx

@@ -7,6 +7,7 @@
 // （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";
@@ -39,7 +40,7 @@ export interface CliFilePreviewProps extends BlockProps {
 
 export function CliFilePreview(props: CliFilePreviewProps) {
   const ctx = useCliStoreContext();
-  return withOwnProvider(props, <FilePreviewInner {...props} inProvider={!!ctx} />, !!ctx);
+  return <CliErrorBoundary component="cli-file-preview" theme={props.theme}>{withOwnProvider(props, <FilePreviewInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
 }
 
 function FilePreviewInner({ jobId: jobIdProp, path, onOpenPath, onClose, actions, version, bare, theme = "light", className, style, onEvent, inProvider }: CliFilePreviewProps & { inProvider: boolean }) {
@@ -67,7 +68,7 @@ export interface CliBrowserViewProps extends BlockProps {
 
 export function CliBrowserView(props: CliBrowserViewProps) {
   const ctx = useCliStoreContext();
-  return withOwnProvider(props, <BrowserViewInner {...props} inProvider={!!ctx} />, !!ctx);
+  return <CliErrorBoundary component="cli-browser" theme={props.theme}>{withOwnProvider(props, <BrowserViewInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
 }
 
 function BrowserViewInner({ jobId: jobIdProp, readOnly, theme = "light", className, style, onEvent, inProvider }: CliBrowserViewProps & { inProvider: boolean }) {

package/src/board/fileOps.ts

@@ -0,0 +1,55 @@
+// 工作区文件的基础操作（不依赖界面）：可直接打开的地址、下载到本地、读成 Blob。
+// 看板、文件预览和给业务方的工作区接口（workspace.ts）共用。
+import { fileUrlFromBase, type BoardBackend } from "../core/client.js";
+import { extOf, fmtSize } from "./fileKind.js";
+
+/** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的不在浏览器里拼下载。 */
+const BLOB_DOWNLOAD_MAX = 300 * 1024 * 1024;
+
+export const MIME: Record<string, string> = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+  bmp: "image/bmp", ico: "image/x-icon", avif: "image/avif", pdf: "application/pdf", html: "text/html", htm: "text/html",
+  md: "text/markdown", txt: "text/plain", csv: "text/csv", json: "application/json", zip: "application/zip",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+export const mimeOf = (path: string) => MIME[extOf(path)] ?? "application/octet-stream";
+
+/**
+ * 浏览器能直接打开的地址（不需要请求头）：同源代理时就是文件接口；没有代理注入令牌时用中枢发的短期链接。
+ * 中枢太旧发不了短期链接时返回 null（调用方改用读成 Blob）。
+ */
+export async function directFileUrl(backend: BoardBackend, jobId: string, path: string, download = false): Promise<string | null> {
+  if (backend.directLinks) return backend.fileUrl(jobId, path, { download });
+  const linkBase = backend.fileLinkBase ? await backend.fileLinkBase(jobId) : null;
+  return linkBase ? fileUrlFromBase(linkBase, path, download) : null;
+}
+
+/** 把 Blob 存到本地（浏览器下载）。 */
+export function saveBlob(blob: Blob, name: string) {
+  const url = URL.createObjectURL(blob);
+  clickDownload(url, name);
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+function clickDownload(href: string, name: string) {
+  const a = document.createElement("a");
+  a.href = href;
+  a.download = name;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+
+/**
+ * 下载：用浏览器能直接打开的地址（流式、可断点续传，不占内存）；同源代理以外的接入向中枢换短期链接。
+ * 只有中枢太旧时才 fetch 成 blob 再存（太大的拒绝，免得撑爆浏览器内存）。
+ */
+export async function downloadFile(backend: BoardBackend, jobId: string, path: string, size?: number) {
+  const name = path.split("/").pop() || "file";
+  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);
+}