@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/CliBoard.tsx

@@ -0,0 +1,484 @@
+import { retryWorkspaceFiles } from "./fileWatch";
+import { retainFileScope } from "./fileScope";
+// 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, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+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 type { BoardInfo, FileEntry } from "../core/types";
+import { Icon } from "../ui/icons";
+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, type InlineBoardLayout } from "./PanelControls";
+import { useBoardVisibility } from "./useBoardVisibility";
+import { useBoardUpload } from "./useBoardUpload";
+
+export type BoardTab = "files" | "changes" | "browser";
+
+/** 宿主加的看板页签。 */
+export interface BoardExtraTab {
+  id: string;
+  label: string;
+  render: (ctx: { jobId: string; store: CliStore; quote: (ref: Omit<BoardRef, "id"> & { id?: string }) => void }) => ReactNode;
+}
+const TAB_LABEL: Record<BoardTab, string> = { files: "工作区", changes: "改动", browser: "浏览器" };
+/** 同时开着的文件页签最多几个：再开新的，关掉最早打开、当前没在看的那个。 */
+export const MAX_FILE_TABS = 8;
+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; history: BoardFile[] } {
+  if (!jobId) return { files: [], tab: null, history: [] };
+  try {
+    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, 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, history: BoardFile[]) {
+  try { sessionStorage.setItem(tabsKey(jobId), JSON.stringify({ files, tab, history })); } catch { /* 存不下就不记 */ }
+}
+
+export interface CliBoardProps extends CliStoreOptions, WorkspaceHandlers {
+  /** @internal 同一个看板在 Chat 标题区放置页签。 */
+  inlineLayout?: InlineBoardLayout;
+  /** @internal 将当前 Chat 的打开请求交给自己的内嵌看板。 */
+  inlineOwner?: string;
+  /** @internal 手机抽屉沿用看板内容，独立控制它的可见状态。 */
+  visible?: boolean;
+  /** @internal 引用后返回当前 Chat。 */
+  onQuoteToChat?: () => void;
+  /** 默认在轮次结束、恢复页面和手动刷新时检查已打开文件与可见目录。收起后暂停文件读取。 */
+  watchFiles?: boolean;
+  /** @deprecated 保留兼容；文件同步由事件触发，不再使用定时间隔。 */
+  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;
+  /** 文件上的自定义操作（预览头部的按钮）。 */
+  fileActions?: FileAction[];
+  /** @deprecated 保留兼容；文件同步由事件触发，不再进行定时轮询。 */
+  pollMs?: number;
+  /** 接不接对话里的「打开文件 / 查看浏览器」，缺省接。 */
+  acceptOpen?: boolean;
+  /**
+   * 显示「引用到对话」（文件预览、浏览器）：把看板里的东西带进这个对话的下一条消息（store.addRef）。
+   * 缺省：和对话放在同一个 Provider 里时显示。
+   */
+  quoteToChat?: boolean;
+  /**
+   * 宿主自己加的页签（例如终端、另一个浏览器），排在内置页签后面。ctx.quote 可以把页签里的东西引用到对话。
+   */
+  extraTabs?: BoardExtraTab[];
+  /**
+   * 看板上打开着的文件缺省带进对话的下一条消息一次（对话输入框上方显示「正在看」，可以点掉）。
+   * 缺省和 quoteToChat 一样。
+   */
+  autoQuoteOpenFile?: boolean;
+  /** 保留旧宿主兼容；看板不再显示内置收起按钮。 */
+  onCollapse?: () => void;
+  /**
+   * 收起状态：只显示一条窄栏（点一下展开）。收起时仍然接对话里的打开请求——接到就记下要打开的东西并调 onExpand，
+   * 宿主把 collapsed 改回 false 后直接显示。
+   */
+  collapsed?: boolean;
+  onExpand?: () => void;
+  /** 选中 / 打开文件 / 切页签时通知宿主（例如记到地址栏）。 */
+  onNavigate?: (state: { tab: BoardTab | string; 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 <CliErrorBoundary component="cli-board" theme={props.theme}>{withOwnProvider(props, <BoardInner {...props} inProvider={!!ctx} />, !!ctx)}</CliErrorBoundary>;
+}
+
+interface OpenFile { name?: string; reloadKey?:number; path: string; size?: number; mtime?: number; version: number }
+
+function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs, defaultTab, readOnly, fileActions, acceptOpen = true, quoteToChat, autoQuoteOpenFile, extraTabs, collapsed, onExpand, onNavigate, onEvent, onFilesChange, onFilesWatch, onBoardContextChange, watchFiles = true, fileWatchIntervalMs, theme = "light", className, style, inProvider, inlineLayout, inlineOwner, visible: visibilityOverride, onQuoteToChat }: 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 rootRef = useRef<HTMLElement | null>(null);
+  const isInline = !!inlineOwner || !!inlineLayout;
+  const cssVisible = useBoardVisibility(rootRef, !isInline);
+  const visible = !collapsed && (isInline ? visibilityOverride ?? inlineLayout?.active ?? true : cssVisible);
+  const layoutRef = useRef(inlineLayout);
+  layoutRef.current = inlineLayout;
+  const quoteCallbackRef = useRef(onQuoteToChat);
+  quoteCallbackRef.current = onQuoteToChat;
+
+  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[]>([]);
+  // 文件变化、恢复页面与手动刷新更新视图；流式轮末检查由 store 直接触发。
+  const [tick, setTick] = useState(0);
+
+  // 换了对话：回到初始状态。
+  const lastJob = useRef(jobId);
+  if (lastJob.current !== jobId) {
+    lastJob.current = jobId;
+    setInfo(null); setInfoError(null); setDir(""); setFiles([]); setHistory([]);
+    setTab(defaultTab ?? tabs?.[0] ?? "files");
+  }
+  // 恢复上次开着的文件页签（存在 sessionStorage）：挂上之后、绘制之前做——服务端渲染和首次渲染一致，不会对不上。
+  const restored = useRef<string | null>(null);
+  const [hydrated, setHydrated] = useState<{ id: string | null; visible: boolean }>({ id: null, visible: false });
+  const restoreNeeded = hydrated.id !== storageId || (!isInline && visible && !hydrated.visible);
+
+  // 实时流：看板单独用时也要知道任务在不在跑（同一对话只连一次）。
+  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 ?? ""}|${conv.task?.id ?? ""}:${conv.task?.status ?? ""}:${conv.remoteTaskId ?? conv.task?.remote_task_id ?? ""}`
+    : "";
+  const bump = useCallback(() => setTick((n) => n + 1), []);
+  const [manual, setManual] = useState(0);
+  const refreshAll = useCallback(() => {
+    setManual((n) => n + 1); bump();
+    if (backend && jobId) retryWorkspaceFiles(backend, jobId, { manual: true });
+  }, [bump, backend, jobId]);
+  useEffect(() => {
+    const on = () => { if (document.visibilityState === "visible") bump(); };
+    document.addEventListener("visibilitychange", on);
+    return () => document.removeEventListener("visibilitychange", on);
+  }, [bump]);
+
+  // 派发和节点变化由已有聊天流驱动，不为文件看板再开启轮询。
+  useEffect(() => {
+    if (!backend || !jobId) return;
+    let alive = true;
+    void backend.info(jobId).then((i) => {
+      if (!alive) return;
+      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);
+    }, (e: unknown) => { if (alive) setInfoError(e instanceof Error ? e.message : String(e)); });
+    return () => { alive = false; };
+  }, [backend, jobId, statusKey, manual]);
+
+  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)]);
+  useIsoLayoutEffect(() => {
+    if (!restoreNeeded) {
+      if (!visible && hydrated.visible) setHydrated({ id: storageId, visible: false });
+      return;
+    }
+    if (storageId) {
+      const current = jobId ? store.getState().boardContext[jobId] : undefined;
+      const saved = loadTabs(storageId);
+      const paths = current?.files ?? saved.files;
+      restored.current = storageId;
+      setFiles(previous => paths.map(path => previous.find(file => file.path === path) ?? { path, version: 0 }));
+      setHistory((current?.history ?? saved.history).map(file => ({ ...file, sourceId: file.sourceId ?? jobId ?? undefined })));
+      setDir(current?.dir ?? "");
+      const selectedTab = current?.tab ?? saved.tab;
+      if (selectedTab) { setTab(selectedTab); if (allowedPanels.includes(selectedTab)) panels.show(selectedTab); }
+    }
+    setHydrated({ id: storageId, visible });
+  }, [store, storageId, jobId, visible, restoreNeeded]); // eslint-disable-line react-hooks/exhaustive-deps
+  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) ? files.find(file => file.path === t.slice(FILE_TAB.length))?.name || t.slice(FILE_TAB.length).split("/").pop() || t : undefined) ?? extraTabs?.find((x) => x.id === t)?.label ?? t;
+  // 页签多了横向滚动：当前页签总是滚到看得见的地方（新开的文件页签在最后，窄看板里容易被挤出去）。
+  const [toolbarHost, setToolbarHost] = useState<HTMLSpanElement | null>(null);
+  const tabsRef = useRef<HTMLDivElement | null>(null);
+  const revealTab = useCallback(() => {
+    // 直接算滚动位置，不用 scrollIntoView：它会连带滚动宿主页面。
+    const box = tabsRef.current;
+    const on = box?.querySelector<HTMLElement>(".rail-tab.on");
+    if (!box || !on) return;
+    const b = box.getBoundingClientRect();
+    const r = on.getBoundingClientRect();
+    if (r.left < b.left) box.scrollLeft -= b.left - r.left + 8;
+    else if (r.right > b.right) box.scrollLeft += r.right - b.right + 8;
+  }, []);
+  useEffect(() => {
+    // 用定时器而不是 requestAnimationFrame：后台 / 被遮住的页面里 rAF 不跑。字体加载完页签会变宽，再对一次。
+    const timers = [setTimeout(revealTab, 0), setTimeout(revealTab, 400)];
+    let alive = true;
+    void document.fonts?.ready.then(() => { if (alive) revealTab(); });
+    return () => { alive = false; timers.forEach(clearTimeout); };
+  }, [activeTab, shownTabs.length, collapsed, visible, inlineLayout?.active, inlineLayout?.tabsHost, revealTab]);
+  // 看板宽度或页签宽度变了（分栏拖动、刚挂上时分栏才给出宽度、字体加载完页签变宽）：再对一次。
+  useEffect(() => {
+    const box = tabsRef.current;
+    if (!box || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(() => revealTab());
+    ro.observe(box);
+    for (const child of box.children) ro.observe(child);
+    return () => ro.disconnect();
+  }, [collapsed, visible, inlineLayout?.tabsHost, revealTab, shownTabs.length]);
+  // 记下开着的文件页签和当前页签（刷新页面后恢复）。恢复之前不写，免得用空的盖掉上次的。
+  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}` }); if (quoteCallbackRef.current) quoteCallbackRef.current(); else layoutRef.current?.onChat(); }
+  }, [store, jobId]);
+  const quoteText = useCallback((path: string, text: string, context?: { revision: string }) => {
+    const name = path.split("/").pop() || path;
+    const short = text.replace(/\s+/g, " ").slice(0, 24);
+    // 同一个文件里选不同的段落各算一条（按内容区分），同一段重复点只留一条。
+    quote({ id: `sel:${path}:${text.length}:${short}`, kind: "selection", label: `${name}：${short}${text.length > 24 ? "…" : ""}`, text: `${context ? `文件修订：${context.revision}\n` : ""}工作区文件 ${path} 里选中的这段：\n${text.split("\n").map((l) => `  > ${l}`).join("\n")}` });
+  }, [quote]);
+  // 正在看的东西（打开的文件、浏览器当前页面）：告诉对话（缺省带进下一条消息一次）。收起、切走、关掉、离开时撤掉。
+  const autoView = (autoQuoteOpenFile ?? canQuote) && !!jobId;
+  const [browserPage, setBrowserPage] = useState<{ url: string; title: string } | null>(null);
+  const viewingPath = autoView && visible && file ? file.path : null;
+  const viewingPage = autoView && visible && activeTab === "browser" && browserPage ? browserPage : null;
+  // 这个看板自己的标识：同一个对话开着两个看板时，各撤各的「正在看」和看板状态。
+  const owner = useMemo(() => `board-${Math.random().toString(36).slice(2, 10)}`, []);
+  useIsoLayoutEffect(() => {
+    if (jobId && !isInline) store.reportBoardPresence(jobId, owner, visible, { availableTabs, readOnly });
+  }, [store, jobId, owner, visible, isInline, availableTabs?.join(","), readOnly]); // eslint-disable-line react-hooks/exhaustive-deps
+  useIsoLayoutEffect(() => () => { if (jobId && !isInline) store.reportBoardPresence(jobId, owner, null); }, [store, jobId, owner, isInline]);
+  useEffect(() => {
+    if (!jobId || !autoView) return;
+    store.setViewing(jobId, viewingPath
+      ? { id: `file:${viewingPath}`, kind: "file", label: viewingPath.split("/").pop() || viewingPath, text: `用户当前在看板里打开着工作区文件 ${viewingPath}` }
+      : viewingPage
+        ? { id: "browser:page", kind: "browser", label: viewingPage.title || viewingPage.url, text: `用户当前在看板里看着任务浏览器页面：${viewingPage.title ? `${viewingPage.title} — ` : ""}${viewingPage.url}` }
+        : null, owner);
+  }, [store, jobId, autoView, viewingPath, viewingPage?.url, viewingPage?.title, owner]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => () => { if (jobId) store.setViewing(jobId, null, owner); }, [store, jobId, owner]);
+  const allFileActions = useMemo<FileAction[]>(() => [
+    ...(canQuote ? [{ label: "引用到对话", title: "把这个文件带进下一条消息（智能体会按路径去读）", onClick: (f: { path: string; name: string }) => quote({ id: `file:${f.path}`, kind: "file", label: f.name, text: `工作区文件 ${f.path}` }) }] : []),
+    ...(fileActions ?? []),
+  ], [canQuote, quote, fileActions]);
+
+  // 打开着的文件：每次刷新查一下它的修改时间，变了就重读。
+  useEffect(() => {
+    if (!backend || !jobId || !file || !info?.dispatched || collapsed) return;
+    let alive = true;
+    const path = file.path;
+    const update = (fn: (f: OpenFile) => OpenFile) => setFiles((list) => list.map((f) => (f.path === path ? fn(f) : f)));
+    backend.stat(jobId, path).then((s) => {
+      if (!alive || s.type !== "file") return;
+      // 第一次拿到修改时间（从对话里打开的、刷新后恢复的）只记下来；之后变了才重读。
+      update((f) => (f.mtime === s.mtime && f.name === s.name ? f : { ...f, name: s.name, size: s.size, mtime: s.mtime, version: f.mtime === undefined ? f.version : f.version + 1 }));
+    }, (e: unknown) => {
+      // 打开着的文件被删了：重读一次，预览里显示「文件不存在」，不继续显示旧内容。
+      if (alive && (e as { status?: number }).status === 404) update((f) => (f.mtime !== -1 ? { ...f, mtime: -1, version: f.version + 1 } : f));
+    });
+    return () => { alive = false; };
+    // 只看正在看的那个文件：切到别的文件页签时查一次它（后台的页签不轮询）。
+  }, [tick, file?.path, info?.dispatched]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const activeRef = useRef(activeTab);
+  activeRef.current = activeTab;
+  /** 打开文件：已经开着就切过去（并重读），否则新开一个页签；超过 MAX_FILE_TABS 关掉最早的（不关正在看的）。 */
+  const openPath = useCallback((path: string, entry?: Partial<FileEntry>) => {
+    const clean = path.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!clean) return;
+    setFiles((list) => {
+      const have = list.find((f) => f.path === clean);
+      if (have) return list.map((f) => (f.path === clean ? { ...f, name: entry?.name ?? f.name, size: entry?.size ?? f.size, mtime: entry?.mtime ?? f.mtime, version: f.version + 1 } : f));
+      const next = [...list, { path: clean, name: entry?.name, size: entry?.size, mtime: entry?.mtime, version: 0 }];
+      while (next.length > MAX_FILE_TABS) {
+        const i = next.findIndex((f) => fileTabId(f.path) !== activeRef.current && f.path !== clean);
+        next.splice(i >= 0 ? i : 0, 1);
+      }
+      return next;
+    });
+    setTab(fileTabId(clean));
+    const parent = clean.includes("/") && !clean.startsWith("/") ? clean.split("/").slice(0, -1).join("/") : "";
+    setDir(parent);
+  }, []);
+  const uploadToWorkspace = useMemo(() => !readOnly && jobId && backend?.uploadFile
+    ? (file: File, options: import("../core/documentUpload").DocumentUploadOptions) => backend.uploadFile!(jobId, file, options)
+    : undefined, [backend, jobId, readOnly]);
+  const upload = useBoardUpload(jobId, uploadToWorkspace, receipt => {
+    openPath(receipt.path!, { name: receipt.name, size: receipt.size });
+    setTick(value => value + 1);
+  });
+  /** 关文件页签：关的是正在看的，就切到它旁边的文件页签，没有了回文件列表。 */
+  const closeFile = useCallback((path: string) => {
+    setFiles((list) => {
+      const i = list.findIndex((f) => f.path === path);
+      if (i < 0) return list;
+      const next = list.filter((f) => f.path !== path);
+      if (activeRef.current === fileTabId(path)) setTab(next.length ? fileTabId(next[Math.min(i, next.length - 1)].path) : "files");
+      return next;
+    });
+  }, []);
+
+  // 接对话里的打开请求（只接自己正在看的对话）。
+  const jobRef = useRef(jobId);
+  jobRef.current = jobId;
+  const expandRef = useRef(onExpand);
+  expandRef.current = onExpand;
+  const visibleRef = useRef(visible);
+  visibleRef.current = visible;
+  useEffect(() => {
+    if (!acceptOpen || !backend) return;
+    return store.registerBoard((target: string, what: OpenTarget) => {
+      if (!jobRef.current || target !== jobRef.current) return false;
+      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 ?? "");
+      }
+      if (layoutRef.current) layoutRef.current.onActivate(); else expandRef.current?.();
+      return true;
+    }, { owner: inlineOwner ?? owner, inline: isInline, priority: () => isInline ? 1 : visibleRef.current ? 2 : 0 });
+  }, [store, backend, acceptOpen, openPath, builtinTabs.join(","), allowedPanels.join(","), panels.show, inlineOwner, owner, isInline]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const navRef = useRef(onNavigate);
+  navRef.current = onNavigate;
+  useEffect(() => { navRef.current?.({ tab: activeTab, dir, file: file?.path ?? null }); }, [activeTab, dir, file?.path]);
+  // 看板现在的样子报给仓库：业务方用 store.workspace().openFile() / openFiles() 拿到当前打开的文件。
+  const openPaths = JSON.stringify(files.map((f) => f.path));
+  const filesEnabled = builtinTabs.includes("files");
+  useEffect(() => {
+    if (!backend || !jobId || !watchFiles || !visible || !filesEnabled) return;
+    return retainFileScope(backend, jobId, { paths: JSON.parse(openPaths) as string[], dirs: [] });
+  }, [backend, jobId, watchFiles, visible, openPaths, filesEnabled]);
+  useEffect(() => {
+    if (!jobId || restoreNeeded) return;
+    const currentFile = isInline && !visible ? null : file;
+    store.reportBoard(jobId, { tab: activeTab, dir, file: currentFile?.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,autoContext:autoQuoteOpenFile??canQuote }, owner);
+  }, [store, jobId, activeTab, dir, file?.path, openPaths, history, browserPage, visible, autoQuoteOpenFile, canQuote, owner, restoreNeeded]);
+  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} <button className="cli-fv-btn" onClick={refreshAll}>重试</button></> : "读取中…"}</div>;
+    if (!info.dispatched) return <div className="tc-note">任务还没开始执行（{info.detail ?? "等待分配执行节点"}）。开始后这里会显示工作区文件。</div>;
+    if (!visible) return null;
+    if (activeTab === "changes") return <ChangesPane key={jobId} backend={backend} jobId={jobId} refreshKey={tick} settled={conv?.settled ?? 0} onOpen={(p) => openPath(p)} />;
+    if (activeTab === "browser") {
+      if (!visible) return null;
+      return <BrowserPane key={`${jobId}:${info.remote_task_id}`} backend={backend} jobId={jobId} readOnly={readOnly}
+        onPage={setBrowserPage}
+        onQuote={canQuote ? (p) => quote({ id: "browser:page", kind: "browser", label: p.title || p.url, text: `任务浏览器当前打开的页面：${p.title ? `${p.title} — ` : ""}${p.url}` }) : undefined}
+        onQuoteText={canQuote ? (text, p) => {
+          const clipped = text.length > 3_000 ? `${text.slice(0, 3_000)}…` : text;
+          const short = clipped.replace(/\s+/g, " ").slice(0, 24);
+          quote({ id: `bsel:${p.url}:${text.length}:${short}`, kind: "selection", label: `网页：${short}${clipped.length > 24 ? "…" : ""}`, text: `任务浏览器页面 ${p.title ? `「${p.title}」` : ""}${p.url} 里复制的这段：\n${clipped.split("\n").map((l) => `  > ${l}`).join("\n")}` });
+        } : undefined} />;
+    }
+    const extra = extraTabs?.find((t) => t.id === activeTab);
+    if (extra) return extra.render({ jobId, store, quote });
+    if (activeTab.startsWith(FILE_TAB) && file) {
+      return (
+        <FileViewer toolbarHost={toolbarHost}
+          key={file.path}
+          backend={backend}
+          jobId={jobId}
+          path={file.path}
+          displayName={file.name}
+          size={file.size}
+          mtime={file.mtime}
+          version={file.version + manual} reloadKey={file.reloadKey}
+          actions={allFileActions}
+          onOpenPath={(p) => openPath(p)}
+          onQuoteText={canQuote ? (text, context) => quoteText(file.path, text, context) : undefined}
+          onBack={() => { setDir(file.path.includes("/") ? file.path.slice(0, file.path.lastIndexOf("/")) : ""); panels.show("files"); setTab("files"); }}
+        />
+      );
+    }
+    return <FilesPane toolbarHost={toolbarHost} key={jobId} backend={backend} jobId={jobId} dir={dir} onDir={setDir} onOpen={(e) => openPath(e.path, e)} refreshKey={tick} />;
+  };
+
+  if (collapsed) {
+    return (
+      <aside ref={rootRef} 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">{tabLabel(t)}</span>)}
+          {running && <span className="cli-sync-dot on" />}
+        </button>
+      </aside>
+    );
+  }
+
+  const selectTab = (id: string) => { setTab(id); layoutRef.current?.onActivate(); };
+  const tabBar = <div className="rail-tabs">
+        <div className="rail-tabs-scroll" role={inlineLayout ? undefined : "tablist"} ref={tabsRef}>
+          {shownTabs.map((t) => t.startsWith(FILE_TAB) ? (
+            <span key={t} className={`rail-tab rail-ftab ${activeTab === t && (!inlineLayout || inlineLayout.active) ? "on" : ""}`} title={t.slice(FILE_TAB.length)}
+              onMouseDown={(e) => { if (e.button === 1) { e.preventDefault(); closeFile(t.slice(FILE_TAB.length)); } }}>
+              <button className="rail-ftab-l" role="tab" aria-selected={activeTab === t && (!inlineLayout || inlineLayout.active)} aria-label={tabLabel(t)} onClick={() => selectTab(t)}>{Icon.doc()}<span className="rail-ftab-text">{tabLabel(t)}</span></button>
+              <button className="rail-ftab-x" onClick={() => closeFile(t.slice(FILE_TAB.length))} title="关闭（鼠标中键也可以）" aria-label={`关闭 ${tabLabel(t)}`}>{Icon.x()}</button>
+            </span>
+          ) : (
+            <PanelTab key={t} id={t} label={tabLabel(t)} active={activeTab === t && (!inlineLayout || inlineLayout.active)} onSelect={() => selectTab(t)} onClose={() => {
+              panels.close(t);
+              if (activeTab === t) setTab(shownTabs.find(id => id !== t) ?? "");
+              if (inlineLayout && shownTabs.length === 1) inlineLayout.onChat();
+            }} />
+          ))}
+        </div>
+        <PanelControls toolbarRef={setToolbarHost} available={allowedPanels} open={panels.open} label={tabLabel}
+          upload={!readOnly && builtinTabs.includes("files") && uploadToWorkspace ? { onChoose: upload.choose, disabled: upload.busy || !info?.dispatched, hint: !info?.dispatched ? "工作区尚未就绪" : "保存到当前会话，不发送消息" } : undefined}
+          onShow={id => { panels.show(id); selectTab(id); }}
+          onClose={id => { panels.close(id); if (activeTab === id) setTab(shownTabs.find(t => t !== id) ?? ""); }} />
+        {info?.dispatched && !file && <button className="rail-collapse" onClick={refreshAll} title={running ? "运行中 · 本轮结束后同步，点击立即检查" : "刷新"}>
+          <span className={`cli-sync-dot ${running ? "on" : ""}`} />↻
+        </button>}
+      </div>;
+  return <>
+    {inlineLayout?.tabsHost && createPortal(tabBar, inlineLayout.tabsHost)}
+    <aside ref={rootRef} className={`cli-ui cli-board sess-rail${isInline ? " cli-inline-board" : ""} ${className ?? ""}`} data-theme={theme} hidden={isInline && !visible} style={{ ...style, ...(isInline && !visible ? { display: "none" } : {}) }} onPointerDown={()=>jobId&&store.activateBoard(jobId,owner)} onClickCapture={()=>jobId&&store.activateBoard(jobId,owner)} onFocusCapture={()=>jobId&&store.activateBoard(jobId,owner)}>
+      {!inlineLayout && tabBar}
+      {upload.input}
+      {upload.progress}
+      <div className="rail-scroll">{body()}</div>
+    </aside>
+  </>;
+}