@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/board/CliBoard.tsx

@@ -0,0 +1,246 @@
+// cli-board：右侧看板。界面取自 Operator 的会话右栏（SessionRail）：文件 / 改动 / 浏览器三个页签。
+// 数据经 center 的 /api/jobs/:id/board、files、diff、browser 转发自执行节点（浏览器不直连节点）。
+//
+//   · 文件：工作区目录浏览、预览（Markdown / 代码 / CSV / 图片 / PDF / HTML / Word）、下载；
+//   · 改动：分支上的 diff（只读）；
+//   · 浏览器：任务浏览器的实时画面、接管 / 交还、打开 / 关闭。
+//
+// 同步：任务每有进展（实时流里的轮次 / 输出变化）就刷新，运行中再定时刷新；打开着的文件改了会自动重读。
+// 和 cli-chat 放在同一个 Provider 里时，对话里点本地文件 / 「查看浏览器」会在这里打开（store.openInBoard）。
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
+import type { 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 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";
+
+export type BoardTab = "files" | "changes" | "browser";
+const TAB_LABEL: Record<BoardTab, string> = { files: "文件", changes: "改动", browser: "浏览器" };
+
+export interface CliBoardProps extends CliStoreOptions {
+  /** 看哪个对话（center 的 job_id）。不给就跟共享仓库的选中走（和 cli-msglist / cli-chat 联动）。 */
+  jobId?: string | null;
+  /** 对话任务里的哪个对话（和 jobId 一起用，同 cli-chat 的 taskId）。不给 = 缺省那个（最近派发过的）。 */
+  taskId?: string | null;
+  /** 显示哪些页签、什么顺序。缺省三个都有（节点没开浏览器功能时不显示「浏览器」）。 */
+  tabs?: BoardTab[];
+  defaultTab?: BoardTab;
+  /** 只看：不能接管 / 打开 / 关闭浏览器。 */
+  readOnly?: boolean;
+  /** 文件上的自定义操作（预览头部的按钮）。 */
+  fileActions?: FileAction[];
+  /** 运行中定时刷新文件列表的间隔，缺省 4000ms；0 = 只在实时流有变化时刷新。改动（diff）不轮询，只在有进展时刷新。 */
+  pollMs?: number;
+  /** 接不接对话里的「打开文件 / 查看浏览器」，缺省接。 */
+  acceptOpen?: boolean;
+  /** 给了就在页签栏右侧显示「隐藏面板」按钮。 */
+  onCollapse?: () => void;
+  /**
+   * 收起状态：只显示一条窄栏（点一下展开）。收起时仍然接对话里的打开请求——接到就记下要打开的东西并调 onExpand，
+   * 宿主把 collapsed 改回 false 后直接显示。
+   */
+  collapsed?: boolean;
+  onExpand?: () => void;
+  /** 选中 / 打开文件 / 切页签时通知宿主（例如记到地址栏）。 */
+  onNavigate?: (state: { tab: BoardTab; dir: string; file: string | null }) => void;
+  onEvent?: (event: CliEvent) => void;
+  theme?: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  store?: CliStore;
+}
+
+export function CliBoard(props: CliBoardProps) {
+  const ctx = useCliStoreContext();
+  return withOwnProvider(props, <BoardInner {...props} inProvider={!!ctx} />, !!ctx);
+}
+
+interface OpenFile { path: string; size?: number; mtime?: number; version: number }
+
+function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, defaultTab, readOnly, fileActions, pollMs = 4000, acceptOpen = true, onCollapse, collapsed, onExpand, onNavigate, onEvent, theme = "light", className, style, inProvider }: CliBoardProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {}, 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 [info, setInfo] = useState<BoardInfo | null>(null);
+  const [infoError, setInfoError] = useState<string | null>(null);
+  const [tab, setTab] = useState<BoardTab>(defaultTab ?? tabs?.[0] ?? "files");
+  const [dir, setDir] = useState("");
+  const [file, setFile] = useState<OpenFile | null>(null);
+  // 刷新信号，按代价分开：
+  //   tick     进展（实时流有新输出 / 轮次变化，节流）、切回页面、手动刷新 —— 文件、改动、打开的文件都跟着刷新；
+  //   pollTick 运行中的定时刷新 —— 只刷文件列表和打开的文件（改动要在节点上跑 git diff，不轮询）；
+  //   statusKey 轮次 / 对话状态变化 —— 才重新查看板概况（它会探测节点的浏览器接口，不随输出刷新）。
+  const [tick, setTick] = useState(0);
+  const [pollTick, setPollTick] = useState(0);
+
+  // 换了对话：回到初始状态。
+  const lastJob = useRef(jobId);
+  if (lastJob.current !== jobId) {
+    lastJob.current = jobId;
+    setInfo(null); setInfoError(null); setDir(""); setFile(null);
+  }
+
+  // 实时流：看板单独用时也要知道任务在不在跑（同一对话只连一次）。
+  useEffect(() => (jobId ? store.open(jobId) : undefined), [store, jobId]);
+  const conv = useCliState((s) => (jobId ? s.convs[jobId] : undefined));
+  const running = conv ? isRunning(conv) : false;
+  // 进展签名：轮次状态 + 转录条数。变了就刷新（节流）。
+  const statusKey = conv ? `${conv.turns.map((t) => `${t.turn_id}:${t.status}`).join(",")}|${conv.job?.status ?? ""}` : "";
+  const activity = conv ? `${statusKey}|${conv.msgs.length}` : "";
+
+  const bump = useCallback(() => setTick((n) => n + 1), []);
+  // 手动刷新（页签栏的 ↻）：连看板概况一起重查。
+  const [manual, setManual] = useState(0);
+  const refreshAll = useCallback(() => { setManual((n) => n + 1); bump(); }, [bump]);
+  const lastBump = useRef(0);
+  const pending = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => {
+    if (!activity) return;
+    const wait = Math.max(0, 1500 - (Date.now() - lastBump.current));
+    if (pending.current) clearTimeout(pending.current);
+    pending.current = setTimeout(() => { lastBump.current = Date.now(); bump(); }, wait);
+    return () => { if (pending.current) clearTimeout(pending.current); };
+  }, [activity, bump]);
+  useEffect(() => {
+    if (!running || !pollMs) return;
+    const t = setInterval(() => { if (document.visibilityState === "visible") setPollTick((n) => n + 1); }, pollMs);
+    return () => clearInterval(t);
+  }, [running, pollMs, bump]);
+  useEffect(() => {
+    const on = () => { if (document.visibilityState === "visible") bump(); };
+    document.addEventListener("visibilitychange", on);
+    return () => document.removeEventListener("visibilitychange", on);
+  }, [bump]);
+
+  // 看板信息：还没派发到节点时每 3 秒再问一次。
+  useEffect(() => {
+    if (!backend || !jobId) return;
+    let alive = true;
+    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));
+      setInfoError(null);
+      if (!i.dispatched) timer = setTimeout(load, 3000);
+    }, (e: unknown) => {
+      if (!alive) return;
+      setInfoError(e instanceof Error ? e.message : String(e));
+      timer = setTimeout(load, 5000);
+    });
+    void load();
+    return () => { alive = false; if (timer) clearTimeout(timer); };
+  }, [backend, jobId, statusKey, manual]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const shownTabs = useMemo(() => (tabs ?? ["files", "changes", "browser"]).filter((t) => t !== "browser" || !info || info.browser), [tabs, info]);
+  const activeTab = shownTabs.includes(tab) ? tab : shownTabs[0] ?? "files";
+
+  // 打开着的文件：每次刷新查一下它的修改时间，变了就重读。
+  useEffect(() => {
+    if (!backend || !jobId || !file || !(tick + pollTick) || !info?.dispatched || collapsed) return;
+    let alive = true;
+    backend.stat(jobId, file.path).then((s) => {
+      if (!alive || s.type !== "file") return;
+      setFile((f) => {
+        if (!f || f.path !== file.path || f.mtime === s.mtime) return f;
+        // 第一次拿到修改时间（从对话里打开的）只记下来；之后变了才重读。
+        return { ...f, size: s.size, mtime: s.mtime, version: f.mtime === undefined ? f.version : f.version + 1 };
+      });
+    }, (e: unknown) => {
+      // 打开着的文件被删了：重读一次，预览里显示「找不到文件」，不继续显示旧内容。
+      if (alive && e instanceof CenterError && e.status === 404) setFile((f) => (f && f.path === file.path && f.mtime !== -1 ? { ...f, mtime: -1, version: f.version + 1 } : f));
+    });
+    return () => { alive = false; };
+  }, [tick, pollTick]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const openPath = useCallback((path: string, entry?: Partial<FileEntry>) => {
+    const clean = path.replace(/^\.\//, "");
+    setTab("files");
+    setFile((f) => ({ path: clean, size: entry?.size, mtime: entry?.mtime, version: (f?.version ?? 0) + 1 }));
+    const parent = clean.includes("/") && !clean.startsWith("/") ? clean.split("/").slice(0, -1).join("/") : "";
+    setDir(parent);
+  }, []);
+
+  // 接对话里的打开请求（只接自己正在看的对话）。
+  const jobRef = useRef(jobId);
+  jobRef.current = jobId;
+  const expandRef = useRef(onExpand);
+  expandRef.current = onExpand;
+  useEffect(() => {
+    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"); setFile(null); setDir(what.path ?? ""); }
+      else setTab(what.kind);
+      expandRef.current?.();
+      return true;
+    });
+  }, [store, backend, acceptOpen, openPath]);
+
+  const navRef = useRef(onNavigate);
+  navRef.current = onNavigate;
+  useEffect(() => { navRef.current?.({ tab: activeTab, dir, file: file?.path ?? null }); }, [activeTab, dir, file?.path]);
+
+  const body = () => {
+    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>;
+    if (!info.dispatched) return <div className="tc-note">任务还没开始执行（{info.detail ?? "等待分配执行节点"}）。开始后这里会显示工作区文件。</div>;
+    if (activeTab === "changes") return <ChangesPane key={jobId} backend={backend} jobId={jobId} refreshKey={tick} onOpen={(p) => openPath(p)} />;
+    if (activeTab === "browser") return <BrowserPane key={`${jobId}:${info.remote_task_id}`} backend={backend} jobId={jobId} readOnly={readOnly} />;
+    if (file) {
+      return (
+        <FileViewer
+          key={file.path}
+          backend={backend}
+          jobId={jobId}
+          path={file.path}
+          size={file.size}
+          mtime={file.mtime}
+          version={file.version}
+          actions={fileActions}
+          onOpenPath={(p) => openPath(p)}
+          lead={<button className="cli-fv-back" onClick={() => setFile(null)} title="返回文件列表">‹</button>}
+        />
+      );
+    }
+    return <FilesPane key={jobId} backend={backend} jobId={jobId} dir={dir} onDir={setDir} onOpen={(e) => openPath(e.path, e)} refreshKey={tick + pollTick} />;
+  };
+
+  if (collapsed) {
+    return (
+      <aside className={`cli-ui cli-board collapsed ${className ?? ""}`} data-theme={theme} style={style}>
+        <button className="cli-board-strip" onClick={onExpand} title="显示看板">
+          {Icon.chevRight()}
+          {shownTabs.map((t) => <span key={t} className="cli-board-strip-t">{TAB_LABEL[t]}</span>)}
+          {running && <span className="cli-sync-dot on" />}
+        </button>
+      </aside>
+    );
+  }
+
+  return (
+    <aside className={`cli-ui cli-board sess-rail ${className ?? ""}`} data-theme={theme} style={style}>
+      <div className="rail-tabs">
+        {shownTabs.map((t) => (
+          <button key={t} className={`rail-tab ${activeTab === t ? "on" : ""}`} onClick={() => { setTab(t); if (t === "files" && activeTab === "files") setFile(null); }}>{TAB_LABEL[t]}</button>
+        ))}
+        <span style={{ flex: 1 }} />
+        {info?.dispatched && <button className="rail-collapse" onClick={refreshAll} title={running ? "运行中 · 自动同步" : "刷新"}>
+          <span className={`cli-sync-dot ${running ? "on" : ""}`} />↻
+        </button>}
+        {onCollapse && <button className="rail-collapse" onClick={onCollapse} title="隐藏面板">{Icon.chevRight()}</button>}
+      </div>
+      <div className="rail-scroll">{body()}</div>
+    </aside>
+  );
+}

package/src/board/FileViewer.tsx

@@ -0,0 +1,257 @@
+// 文件预览：Markdown / 代码 / 文本 / CSV / 图片 / PDF / HTML（沙箱）/ Word，其余给下载。
+// 看板和对话里的弹窗共用。文件经 center 转发读取（浏览器不直连执行节点）。
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import 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";
+
+/** 看板 / 预览里给文件加的自定义操作（例如「在对话里引用」「发到工作协同」）。 */
+export interface FileAction {
+  label: string;
+  title?: string;
+  /** 只对某些文件显示。 */
+  when?: (file: { path: string; name: string }) => boolean;
+  onClick: (file: { path: string; name: string; url: string; downloadUrl: string }, jobId: string) => void;
+}
+
+const TEXT_MAX = 512 * 1024;
+const HIGHLIGHT_MAX = 120 * 1024;
+
+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",
+};
+
+/** 能直接用的地址；需要请求头时先 fetch 成 blob 地址（离开时释放）。 */
+function useFileSrc(backend: BoardBackend, jobId: string, path: string, enabled: boolean, version: number) {
+  const [state, setState] = useState<{ url: string | null; error: string | null }>({ url: null, error: 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;
+    }
+    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" }));
+      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);
+}
+
+type Loaded =
+  | { kind: "text"; text: string; truncated: boolean; size: number }
+  | { kind: "docx"; html: string }
+  | { kind: "none" };
+
+export interface FileViewerProps {
+  backend: BoardBackend;
+  jobId: string;
+  path: string;
+  /** 文件信息（列表里已有的话省一次请求）。 */
+  size?: number;
+  mtime?: number;
+  /** 变了就重新读（看板在文件更新时递增）。 */
+  version?: number;
+  /** 预览里点了别的本地文件（Markdown 里的链接）。 */
+  onOpenPath?: (path: string) => void;
+  onClose?: () => void;
+  /** 头部左侧额外内容（看板放「返回」按钮）。 */
+  lead?: ReactNode;
+  actions?: FileAction[];
+  /** 隐藏头部（宿主自己做）。 */
+  bare?: boolean;
+}
+
+export function FileViewer({ backend, jobId, path, size, mtime, version = 0, onOpenPath, onClose, lead, actions = [], bare }: FileViewerProps) {
+  const name = path.split("/").pop() || path;
+  const kind: PreviewKind = previewKind(path);
+  const [loaded, setLoaded] = useState<Loaded | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [mode, setMode] = useState<"preview" | "source">("preview");
+  const needsSrc = kind === "image" || kind === "pdf" || kind === "html";
+  const src = useFileSrc(backend, jobId, path, needsSrc, version);
+
+  useEffect(() => {
+    let alive = true;
+    setError(null);
+    if (needsSrc || kind === "binary") { setLoaded({ kind: "none" }); return; }
+    if (kind === "docx") {
+      backend.readBuffer(jobId, path).then(async (buffer) => {
+        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;
+        const input: Record<string, unknown> = { arrayBuffer: buffer };
+        const B = (globalThis as { Buffer?: { from(b: ArrayBuffer): unknown } }).Buffer;
+        if (B) input.buffer = B.from(buffer);
+        const out = await convert(input as unknown as Parameters<typeof convert>[0]);
+        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 }); },
+        (e: unknown) => { if (alive) setError(e instanceof Error ? e.message : String(e)); },
+      );
+    }
+    return () => { alive = false; };
+  }, [backend, jobId, path, kind, needsSrc, version]);
+
+  const fileInfo = useCallback(() => ({
+    path, name, url: backend.fileUrl(jobId, path), downloadUrl: backend.fileUrl(jobId, path, { download: true }),
+  }), [backend, jobId, path, name]);
+
+  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");
+  };
+  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 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);
+
+  return (
+    <div className="cli-fv">
+      {!bare && (
+        <div className="cli-fv-h">
+          {lead}
+          <span className="cli-fv-ic">{Icon.doc()}</span>
+          <span className="cli-fv-name" title={path}>{name}</span>
+          <span className="cli-fv-meta">
+            {shownSize !== undefined && fmtSize(shownSize)}
+            {mtime && mtime > 0 ? ` · ${relTime(mtime)}更新` : ""}
+          </span>
+          <span className="cli-fv-sp" />
+          {canSource && (
+            <button className="cli-fv-btn" onClick={() => setMode(mode === "preview" ? "source" : "preview")} title={mode === "preview" ? "查看源文件" : "查看预览"}>
+              {mode === "preview" ? "源文件" : "预览"}
+            </button>
+          )}
+          {actions.filter((a) => !a.when || a.when({ path, name })).map((a) => (
+            <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" 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}`}>
+        {error || src.error ? (
+          <div className="cli-fv-note err">读取失败：{error ?? src.error}
+            <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={() => void download()}>{Icon.download()} 下载</button>
+          </div>
+        ) : kind === "binary" ? (
+          <div className="cli-fv-note">这种文件不能在这里预览。
+            <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>
+              : 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>
+        ) : loaded.kind === "docx" ? (
+          <iframe className="cli-fv-frame doc" title={name} sandbox="" srcDoc={docxPage(loaded.html)} />
+        ) : loaded.kind === "text" ? (
+          <>
+            {loaded.truncated && <div className="cli-fv-trunc">文件较大，只显示前 {fmtSize(TEXT_MAX)}；完整内容请下载。</div>}
+            {kind === "markdown" && mode === "preview" ? (
+              <FileLinkContext.Provider value={mdResolve}>
+                <FileOpenContext.Provider value={mdOpen}>
+                  <div className="cli-fv-md"><Markdown>{loaded.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>
+            ) : (
+              <pre className="cli-fv-pre">{loaded.text}</pre>
+            )}
+          </>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function SourceView({ backend, jobId, path, version }: { backend: BoardBackend; jobId: string; path: string; version: number }) {
+  const [text, setText] = useState<string | null>(null);
+  useEffect(() => {
+    let alive = true;
+    backend.readText(jobId, path, TEXT_MAX).then((r) => { if (alive) setText(r.text); }, (e: unknown) => { if (alive) setText(`读取失败：${e instanceof Error ? e.message : String(e)}`); });
+    return () => { alive = false; };
+  }, [backend, jobId, path, version]);
+  return text === null ? <div className="cli-fv-note">加载中…</div> : <pre className="cli-fv-pre">{text}</pre>;
+}
+
+function CsvTable({ text }: { text: string }) {
+  const { rows, more } = useMemo(() => parseCsv(text), [text]);
+  if (!rows.length) return <div className="cli-fv-note">空文件。</div>;
+  const [head, ...body] = rows;
+  return (
+    <div className="cli-fv-csv">
+      <table>
+        <thead><tr>{head.map((c, i) => <th key={i}>{c}</th>)}</tr></thead>
+        <tbody>{body.map((r, i) => <tr key={i}>{r.map((c, j) => <td key={j}>{c}</td>)}</tr>)}</tbody>
+      </table>
+      {more && <div className="cli-fv-trunc">只显示前 500 行；完整内容请下载。</div>}
+    </div>
+  );
+}
+
+function fenced(text: string, lang: string) {
+  const runs = text.match(/`{3,}/g) ?? [];
+  const fence = "`".repeat(Math.max(3, ...runs.map((r) => r.length + 1)));
+  return `${fence}${lang}\n${text}\n${fence}`;
+}
+
+// Word 转出来的 HTML 放进无脚本的沙箱 iframe，配一份阅读样式。
+function docxPage(body: string) {
+  return `<!doctype html><meta charset="utf-8"><style>
+body{font:14px/1.7 -apple-system,"PingFang SC","Microsoft YaHei",sans-serif;color:#1f2328;max-width:820px;margin:0 auto;padding:24px 28px;}
+h1,h2,h3{line-height:1.35}table{border-collapse:collapse}td,th{border:1px solid #d0d7de;padding:4px 8px}img{max-width:100%}
+</style>${body}`;
+}
+

package/src/board/FilesPane.tsx

@@ -0,0 +1,109 @@
+// 工作区文件：面包屑 + 列表。目录点进去，文件点开预览；行尾可直接下载。
+// 列表随任务进展自动刷新（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 "./FileViewer.js";
+import { fmtSize } from "./fileKind.js";
+
+export interface FilesPaneProps {
+  backend: BoardBackend;
+  jobId: string;
+  dir: string;
+  onDir: (dir: string) => void;
+  onOpen: (entry: FileEntry) => void;
+  refreshKey: number;
+  /** 列表读到了（看板用来判断打开着的文件有没有更新）。 */
+  onListed?: (dir: string, entries: FileEntry[]) => void;
+}
+
+export function FilesPane({ backend, jobId, dir, onDir, onOpen, refreshKey, onListed }: FilesPaneProps) {
+  const [entries, setEntries] = useState<FileEntry[] | null>(null);
+  const [truncated, setTruncated] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  // 这个目录上一次看到的 mtime：用来标「新」。第一次打开目录不标。
+  const seen = useRef<{ dir: string; mtimes: Map<string, number> | null }>({ dir, mtimes: null });
+  const [fresh, setFresh] = useState<Set<string>>(new Set());
+  const onListedRef = useRef(onListed);
+  onListedRef.current = onListed;
+  const onDirRef = useRef(onDir);
+  onDirRef.current = onDir;
+
+  useEffect(() => {
+    let alive = true;
+    setLoading(true);
+    if (seen.current.dir !== dir) { seen.current = { dir, mtimes: null }; setEntries(null); setFresh(new Set()); }
+    backend.stat(jobId, dir || ".").then((res) => {
+      if (!alive) return;
+      setLoading(false);
+      if (res.type !== "dir") { setError("不是目录"); return; }
+      setError(null);
+      const prev = seen.current.mtimes;
+      if (prev) {
+        const changed = res.entries.filter((e) => e.type === "file" && prev.get(e.path) !== e.mtime).map((e) => e.path);
+        if (changed.length) setFresh((old) => new Set([...old, ...changed]));
+      }
+      seen.current.mtimes = new Map(res.entries.map((e) => [e.path, e.mtime]));
+      setEntries(res.entries);
+      setTruncated(res.truncated);
+      onListedRef.current?.(dir, res.entries);
+    }, (e: unknown) => {
+      if (!alive) return;
+      setLoading(false);
+      // 正在看的目录被删了（任务清理了输出）：回到上一级。
+      if (dir && e instanceof CenterError && e.status === 404) { onDirRef.current(dir.split("/").slice(0, -1).join("/")); return; }
+      setError(e instanceof Error ? e.message : String(e));
+    });
+    return () => { alive = false; };
+  }, [backend, jobId, dir, refreshKey]);
+
+  const segs = dir ? dir.split("/").filter(Boolean) : [];
+  return (
+    <div className="cli-files">
+      <div className="cli-crumbs">
+        <button className={`cli-crumb ${segs.length ? "" : "on"}`} onClick={() => onDir("")}>{Icon.folder()} 工作区</button>
+        {segs.map((s, i) => (
+          <span key={i} className="cli-crumb-w">
+            <span className="cli-crumb-sep">/</span>
+            <button className={`cli-crumb ${i === segs.length - 1 ? "on" : ""}`} onClick={() => onDir(segs.slice(0, i + 1).join("/"))}>{s}</button>
+          </span>
+        ))}
+        <span className="cli-fv-sp" />
+        {loading && entries && <span className="cli-files-sync" title="正在同步">同步中…</span>}
+      </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>
+      ) : !entries ? (
+        <div className="cli-fv-note">读取文件…</div>
+      ) : entries.length === 0 ? (
+        <div className="cli-fv-note">{dir ? "这个目录是空的。" : "工作区里还没有文件。任务生成的文件会出现在这里。"}</div>
+      ) : (
+        <div className="cli-files-list" role="list">
+          {dir && (
+            <button className="cli-frow" onClick={() => onDir(segs.slice(0, -1).join("/"))}>
+              <span className="cli-frow-ic">{Icon.folder()}</span><span className="cli-frow-name">..</span>
+            </button>
+          )}
+          {entries.map((e) => (
+            <div key={e.path} className={`cli-frow ${e.type} ${fresh.has(e.path) ? "fresh" : ""}`} role="listitem">
+              <button className="cli-frow-main" onClick={() => (e.type === "dir" ? onDir(e.path) : onOpen(e))} title={e.path}>
+                <span className="cli-frow-ic">{e.type === "dir" ? Icon.folder() : Icon.doc()}</span>
+                <span className="cli-frow-name">{e.name}</span>
+                {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>
+              )}
+            </div>
+          ))}
+          {truncated && <div className="cli-fv-trunc">文件太多，只列出前 2000 个。</div>}
+        </div>
+      )}
+    </div>
+  );
+}