@xgspz/cli-ui 0.6.15 → 0.6.16

package/dist/cli-ui.js

@@ -1,4 +1,4 @@
-import { C as a, b as i, d as r, e as t, f as o, h as C, i as l, j as n, k as m, m as d, l as u, n as w, o as B, p as f } from "./cli-ui-embed-vIXVNs6k.js";
+import { C as a, b as i, d as r, e as t, f as o, h as C, i as l, j as n, k as m, m as d, l as u, n as w, o as B, p as f } from "./cli-ui-embed-D9xgur2y.js";
 export {
   a as CliBoard,
   i as CliBrowserView,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgspz/cli-ui",
-  "version": "0.6.15",
+  "version": "0.6.16",
   "type": "module",
   "description": "相互联动的 CliMsgList、CliChat、CliBoard，支持任务中枢和完整 Operator 工作区。",
   "main": "src/index.ts",

package/src/board/ChangesPane.tsx

@@ -1,6 +1,7 @@
 // 改动：移植自 Operator 的 TaskChanges（只读部分：分支、统计、文件列表、逐文件 diff）。
 // 合并 / 解决冲突 / 建 PR 是 Operator 里的操作，经中枢的对话任务不提供。
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useDiffRefreshSignal } from "./diffRefresh";
 import { CenterError, type BoardBackend } from "../core/client";
 import type { DiffFile, DiffResult } from "../core/types";
 import { countChanges, diffLineKinds, hunkLines } from "./diffLines";
@@ -70,8 +71,13 @@ function transient(error: unknown): boolean {
 }
 const clock = (at: number) => new Date(at).toLocaleTimeString("zh-CN", { hour12: false });
 
-/** settled：轮次收尾计数（store 的 ConvState.settled），每变一次重读一次。 */
-export function ChangesPane({ backend, jobId, refreshKey, settled = 0, onOpen }: { backend: BoardBackend; jobId: string; refreshKey: number; settled?: number; onOpen?: (path: string) => void }) {
+/**
+ * 自动重读（见 useDiffRefreshSignal，只看事件，没有定时轮询）：
+ *   settled：轮次收尾计数（store 的 ConvState.settled），变了马上重读；
+ *   edits：运行中工具执行完的次数（ConvState.edits），refreshKey：文件变化、回到页面等，这两个节流重读（最多每 5 秒一次）。
+ */
+export function ChangesPane({ backend, jobId, refreshKey, settled = 0, edits = 0, onOpen }: { backend: BoardBackend; jobId: string; refreshKey: number; settled?: number; edits?: number; onOpen?: (path: string) => void }) {
+  const signal = useDiffRefreshSignal(settled, edits + refreshKey);
   const [data, setData] = useState<DiffResult | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
@@ -88,7 +94,7 @@ export function ChangesPane({ backend, jobId, refreshKey, settled = 0, onOpen }:
   const [retrying, setRetrying] = useState(false);
   const [auto, setAuto] = useState(0);
   const attempts = useRef(0);
-  const trigger = `${refreshKey}|${settled}|${manual}`;
+  const trigger = `${signal}|${manual}`;
   const lastTrigger = useRef(trigger);
   // 首次读可以和同时打开的其他看板共用请求；之后每次刷新都单独发（fresh），不拿刷新之前就发出的结果。
   const loadedOnce = useRef(false);
@@ -119,7 +125,7 @@ export function ChangesPane({ backend, jobId, refreshKey, settled = 0, onOpen }:
     if (!refresh) { void load(); return () => { alive = false; clearTimeout(retryTimer); }; }
     const timer = setTimeout(load, REFRESH_COALESCE_MS);
     return () => { alive = false; clearTimeout(timer); clearTimeout(retryTimer); };
-  }, [backend, jobId, refreshKey, settled, manual, auto]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [backend, jobId, signal, manual, auto]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const toggle = useCallback((path: string) => setToggled((s) => { const n = new Set(s); if (n.has(path)) n.delete(path); else n.add(path); return n; }), []);
   const jump = (path: string) => {

package/src/board/CliBoard.tsx

@@ -9,12 +9,12 @@ import { retainFileScope } from "./fileScope";
 //
 // 同步：每轮实时输出结束、恢复页面或手动刷新时检查打开的文件，只读取缺失变化块；没有周期轮询。
 // 和 cli-chat 放在同一个 Provider 里时，对话里点本地文件 / 「查看浏览器」会在这里打开（store.openInBoard）。
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { memo, 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 { convKey, parseConvKey, isRunning, TERMINAL_JOB } from "../core/conversation";
 import type { BoardInfo, FileEntry } from "../core/types";
 import { Icon } from "../ui/icons";
 import { FileViewer, type FileAction } from "./FileViewer";
@@ -28,6 +28,7 @@ import { useBoardPanels } from "./panels";
 import { PanelControls, PanelTab, type InlineBoardLayout } from "./PanelControls";
 import { useBoardVisibility } from "./useBoardVisibility";
 import { useBoardUpload } from "./useBoardUpload";
+import { pathHints, resolveMissingPath } from "./pathResolve";
 
 export type BoardTab = "files" | "changes" | "browser";
 
@@ -118,12 +119,13 @@ export interface CliBoardProps extends CliStoreOptions, WorkspaceHandlers {
   store?: CliStore;
 }
 
-export function CliBoard(props: CliBoardProps) {
+// memo：嵌在对话里的看板不随对话的每次重画（流式输出时每来一块一次）重画，只在参数变了时才重画。
+export const CliBoard = memo(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 }
+interface OpenFile { name?: string; reloadKey?:number; path: string; size?: number; mtime?: number; version: number; /** 由对话里写的这个相对路径补全来的。 */ resolvedFrom?: string }
 
 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);
@@ -153,10 +155,12 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
   const [tick, setTick] = useState(0);
 
   // 换了对话：回到初始状态。
+  // 对话里写的相对路径 → 补全后确实存在的路径（这个对话里再点同一个链接直接打开补全后的）。
+  const aliases = useRef(new Map<string, string>());
   const lastJob = useRef(jobId);
   if (lastJob.current !== jobId) {
     lastJob.current = jobId;
-    setInfo(null); setInfoError(null); setDir(""); setFiles([]); setHistory([]);
+    setInfo(null); setInfoError(null); setDir(""); setFiles([]); setHistory([]); aliases.current.clear();
     setTab(defaultTab ?? tabs?.[0] ?? "files");
   }
   // 恢复上次开着的文件页签（存在 sessionStorage）：挂上之后、绘制之前做——服务端渲染和首次渲染一致，不会对不上。
@@ -166,12 +170,18 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
 
   // 实时流：看板单独用时也要知道任务在不在跑（同一对话只连一次）。
   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 running = useCliState((s) => { const conv = jobId ? s.convs[jobId] : undefined; return conv ? isRunning(conv) : false; });
+  // 看板概况（派发到哪个节点、节点上的会话、有没有文件 / 浏览器）只在这些变了时重查：派发到节点（节点、开始执行过没有）、
+  // 任务结束、看的子任务或它在节点上的会话换了（续派、重建）。每一轮的排队 → 执行 → 结束不影响概况，不重查。
+  const statusKey = useCliState((s) => {
+    const conv = jobId ? s.convs[jobId] : undefined;
+    if (!conv) return "";
+    const started = conv.turns.some((t) => !!t.started_at || t.status === "running" || t.status === "dispatching") || !!conv.batchTask?.remote_task_id;
+    return `${conv.job?.node_id ?? ""}|${started}|${TERMINAL_JOB.has(conv.job?.status ?? "")}|${conv.task?.id ?? ""}:${conv.remoteTaskId ?? conv.task?.remote_task_id ?? ""}`;
+  });
+  const settled = useCliState((s) => (jobId ? s.convs[jobId]?.settled ?? 0 : 0));
+  const edits = useCliState((s) => (jobId ? s.convs[jobId]?.edits ?? 0 : 0));
   const bump = useCallback(() => setTick((n) => n + 1), []);
   const [manual, setManual] = useState(0);
   const refreshAll = useCallback(() => {
@@ -319,12 +329,14 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
   activeRef.current = activeTab;
   /** 打开文件：已经开着就切过去（并重读），否则新开一个页签；超过 MAX_FILE_TABS 关掉最早的（不关正在看的）。 */
   const openPath = useCallback((path: string, entry?: Partial<FileEntry>) => {
-    const clean = path.replace(/^\.\//, "").replace(/\/+$/, "");
-    if (!clean) return;
+    const requested = path.replace(/^\.\//, "").replace(/\/+$/, "");
+    if (!requested) return;
+    const clean = aliases.current.get(requested) ?? requested;
+    const resolvedFrom = clean !== requested ? requested : undefined;
     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 }];
+      const next = [...list, { path: clean, name: entry?.name, size: entry?.size, mtime: entry?.mtime, version: 0, ...(resolvedFrom ? { resolvedFrom } : {}) }];
       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);
@@ -335,6 +347,25 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
     const parent = clean.includes("/") && !clean.startsWith("/") ? clean.split("/").slice(0, -1).join("/") : "";
     setDir(parent);
   }, []);
+  /** 打不开的相对路径换成补全后的：原来的页签原地换成新路径（已经开着就切过去），以后再点同一个链接直接打开它。 */
+  const replacePath = useCallback((from: string, to: string) => {
+    aliases.current.set(from, to);
+    setFiles((list) => {
+      const old = list.find((f) => f.path === from);
+      const resolvedFrom = old?.resolvedFrom ?? from;
+      if (list.some((f) => f.path === to)) return list.filter((f) => f.path !== from).map((f) => (f.path === to ? { ...f, resolvedFrom: f.resolvedFrom ?? resolvedFrom } : f));
+      return list.map((f) => (f.path === from ? { path: to, version: 0, resolvedFrom } : f));
+    });
+    setTab(fileTabId(to));
+    setDir(to.includes("/") && !to.startsWith("/") ? to.split("/").slice(0, -1).join("/") : "");
+  }, []);
+  const historyRef = useRef(history); historyRef.current = history;
+  const resolveMissing = useCallback((path: string, signal: AbortSignal) => {
+    if (!backend || !jobId) return Promise.resolve([]);
+    const conv = store.getState().convs[jobId];
+    const seen = [...(store.getState().boardContext[jobId]?.history ?? []), ...historyRef.current].map((f) => f.path);
+    return resolveMissingPath(backend, jobId, path, pathHints(conv?.msgs ?? [], seen), signal);
+  }, [backend, jobId, store]);
   const uploadToWorkspace = useMemo(() => !readOnly && jobId && backend?.uploadFile
     ? (file: File, options: import("../core/documentUpload").DocumentUploadOptions) => backend.uploadFile!(jobId, file, options)
     : undefined, [backend, jobId, readOnly]);
@@ -400,7 +431,7 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
     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 === "changes") return <ChangesPane key={jobId} backend={backend} jobId={jobId} refreshKey={tick} settled={settled + manual} edits={edits} 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}
@@ -429,6 +460,7 @@ function BoardInner({ jobId: jobIdProp, taskId: taskIdProp, tabs, availableTabs,
           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"); }}
+          resolveMissing={resolveMissing} onResolved={(to) => replacePath(file.path, to)} resolvedFrom={file.resolvedFrom}
         />
       );
     }

package/src/board/FileViewer.tsx

@@ -149,6 +149,15 @@ export interface FileViewerProps {
   toolbarHost?: HTMLElement | null;
   /** 给了就支持「选中文字 → 引用到对话」：在预览里选中一段文字时浮出按钮（Markdown / 代码 / 文本 / 表格 / HTML / Word，及各自的源文件）。 */
   onQuoteText?: (text: string, context?: { revision: string }) => void;
+  /**
+   * 打不开时（相对路径、后端说文件不存在）按对话里的线索补全：返回确实存在的候选路径（见 board/pathResolve.ts）。
+   * 只有一个就调 onResolved 直接换过去；有几个列出来让用户选。不给就只显示读取失败。
+   */
+  resolveMissing?: (path: string, signal: AbortSignal) => Promise<string[]>;
+  /** 换成补全后的路径打开。 */
+  onResolved?: (path: string) => void;
+  /** 这个文件是由对话里写的这个路径补全来的（显示一行说明）。 */
+  resolvedFrom?: string;
 }
 
 /** 选中的文字超过这么多只带开头（引用是给智能体指位置的，不是搬运全文）。 */
@@ -159,7 +168,7 @@ export function FileViewer(props:FileViewerProps) {
   let id=viewerBackendIds.get(props.backend);if(id===undefined){id=nextViewerBackendId++;viewerBackendIds.set(props.backend,id);}
   return <FileViewerInner key={JSON.stringify([id,props.jobId,props.path])} {...props}/>;
 }
-function FileViewerInner({ backend, jobId, path, displayName, size, mtime, version = 0, reloadKey, onOpenPath, onClose, lead, onBack, actions = [], bare, toolbarHost, onQuoteText }: FileViewerProps) {
+function FileViewerInner({ backend, jobId, path, displayName, size, mtime, version = 0, reloadKey, onOpenPath, onClose, lead, onBack, actions = [], bare, toolbarHost, onQuoteText, resolveMissing, onResolved, resolvedFrom }: FileViewerProps) {
   const name = displayName || path.split("/").pop() || path;
   const kind: PreviewKind = previewKind(path);
   const [loaded, setLoaded] = useState<Loaded | null>(null);
@@ -463,6 +472,24 @@ function FileViewerInner({ backend, jobId, path, displayName, size, mtime, versi
   const shownSize = knownSize;
   const text = loaded?.kind === "text" ? loaded : null;
   const loading = !error && !src.error && (needsSrc ? (bridged ? htmlDoc === null : !src.url) : !loaded);
+  // 读取失败：相对路径可能是智能体相对它进入的子目录写的，按对话里的线索补全（resolveMissing 由看板 / 对话给）。
+  // 只确认存在的才算；找到唯一一个直接换过去，几个就列出来选。
+  const failed = !!((error && loaded?.kind !== "text" && !(htmlDoc && typeof htmlDoc === "object")) || src.error);
+  const [lookup, setLookup] = useState<{ state: "searching" } | { state: "done"; found: string[] } | null>(null);
+  const resolveRef = useRef(resolveMissing); resolveRef.current = resolveMissing;
+  const resolvedRef = useRef(onResolved); resolvedRef.current = onResolved;
+  useEffect(() => {
+    setLookup(null);
+    if (!failed || !resolveRef.current) return;
+    const ctl = new AbortController();
+    setLookup({ state: "searching" });
+    resolveRef.current(path, ctl.signal).then((found) => {
+      if (ctl.signal.aborted) return;
+      if (found.length === 1 && resolvedRef.current) { resolvedRef.current(found[0]); return; }
+      setLookup({ state: "done", found });
+    }, () => { if (!ctl.signal.aborted) setLookup({ state: "done", found: [] }); });
+    return () => ctl.abort();
+  }, [failed, path, attempt]);
   const slow = useSlow(loading);
   // 大文件显示读到哪了；很久没读完提示网络慢。
   const progressText = progress > 0 ? `已读取 ${fmtSize(progress)}${shownSize ? ` / ${fmtSize(shownSize)}` : ""}` : "";
@@ -526,6 +553,7 @@ function FileViewerInner({ backend, jobId, path, displayName, size, mtime, versi
         <button className="cli-fv-btn" disabled={busy} onClick={() => void download()}>重试下载</button>
         <button className="cli-fv-btn" onClick={() => setDownloadError(null)} aria-label="关闭下载错误">关闭</button>
       </div>}
+      {resolvedFrom && resolvedFrom !== path && <div className="cli-fv-trunc cli-fv-resolved" role="status">对话里写的是 <code>{resolvedFrom}</code>，按对话里提到的目录打开了 <code>{path}</code>。</div>}
       {error && (loaded?.kind === "text" || (htmlDoc && typeof htmlDoc === "object")) && <div className="cli-fv-trunc" role="alert">同步失败：{error}。保留上次完整内容。<button className="cli-fv-btn" onClick={() => setAttempt(value => value + 1)}>重试</button></div>}
       {(syncing || parsing) && <div className="cli-fv-sync" role="status">{!syncing && parsing ? "正在整理正文…" : loaded?.kind === "text" || (htmlDoc && typeof htmlDoc === "object") ? "正在核对更新…" : "正在读取文件…"}<button className="cli-fv-btn" onClick={cancelRead}>暂停加载</button>{kind === "html" && mode === "preview" && !htmlReading && <button className="cli-fv-btn" onClick={() => setHtmlPresentation("reading")}>分段阅读</button>}</div>}
       {cancelled && <div className="cli-fv-trunc" role="status">已暂停加载，已读取的内容仍然保留。<button className="cli-fv-btn" onClick={() => setAttempt(value => value + 1)}>继续加载</button></div>}
@@ -538,6 +566,11 @@ function FileViewerInner({ backend, jobId, path, displayName, size, mtime, versi
           <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()} disabled={busy}>{Icon.download()} 下载</button>
+            {lookup?.state === "searching" && <div className="cli-fv-resolve" role="status">正在按对话里提到的目录查找这个文件…</div>}
+            {lookup?.state === "done" && lookup.found.length > 1 && <div className="cli-fv-resolve" role="group" aria-label="可能的文件">
+              对话里写的是相对路径，找到这几个可能的文件：
+              {lookup.found.map((candidate) => <button key={candidate} type="button" className="cli-fv-btn cli-fv-candidate" title={candidate} onClick={() => onResolved?.(candidate)}>{candidate}</button>)}
+            </div>}
           </div>
         ) : kind === "binary" ? (
           <div className="cli-fv-note">这种文件不能在这里预览。

package/src/board/diffRefresh.ts

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState } from "react";
+
+/** 运行中有工具执行完（可能改了文件）时，改动页签最多每这么久重读一次；最后一次变化之后一定再读一次。 */
+export const DIFF_LIVE_GAP_MS = 5_000;
+
+/**
+ * 改动页签（中枢看板 ChangesPane、节点 TaskChanges 共用）什么时候自动重读。只看事件，没有定时轮询：
+ *   · settled 变了（一轮结束、对话结束、断线重连补齐）：马上给信号；
+ *   · edits 变了（运行中有工具执行完、工作区文件有变化）：节流，最多每 DIFF_LIVE_GAP_MS 一次，
+ *     最后一次变化之后一定再给一次（只在有新事件时才排一次，没有事件就什么都不做）；
+ *   · 页面在后台时来的信号先记下，回到前台时给一次。
+ * 返回一个递增的数字，变了就重读。挂上时不给信号（组件挂上时自己会读一次）。
+ */
+export function useDiffRefreshSignal(settled: number, edits: number): number {
+  const [signal, setSignal] = useState(0);
+  const seen = useRef({ settled, edits });
+  const lastAt = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const missed = useRef(false);
+  // 同一次提交里 settled 和 edits 一起变了（例如手动刷新同时碰了两个）：只读一次。
+  const firedThisCommit = useRef(false);
+  const fire = useRef(() => {});
+  fire.current = () => {
+    if (timer.current) { clearTimeout(timer.current); timer.current = null; }
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") { missed.current = true; return; }
+    lastAt.current = Date.now();
+    setSignal((n) => n + 1);
+  };
+
+  useEffect(() => {
+    if (seen.current.settled === settled) return;
+    seen.current.settled = settled;
+    fire.current();
+    firedThisCommit.current = true;
+  }, [settled]);
+
+  useEffect(() => {
+    if (seen.current.edits === edits) return;
+    seen.current.edits = edits;
+    // 刚因为 settled 读过，或者已经排着一次：那一次读到的会包含这次变化。
+    if (firedThisCommit.current || timer.current) return;
+    const delay = lastAt.current + DIFF_LIVE_GAP_MS - Date.now();
+    // 离上次读已经够久：马上读；否则排到间隔满了再读（只排这一次）。
+    if (delay <= 0) { fire.current(); return; }
+    timer.current = setTimeout(() => { timer.current = null; fire.current(); }, delay);
+  }, [edits]);
+  useEffect(() => { firedThisCommit.current = false; });
+
+  useEffect(() => {
+    const onVisible = () => {
+      if (document.visibilityState !== "visible" || !missed.current) return;
+      missed.current = false;
+      fire.current();
+    };
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible);
+      if (timer.current) { clearTimeout(timer.current); timer.current = null; }
+    };
+  }, []);
+
+  return signal;
+}

package/src/board/linkage.ts

@@ -0,0 +1,68 @@
+// 对话与看板的联动（中枢适配的仓库 store、节点适配的 boardInteraction / boardState 共用）。纯 TS，没有 React。
+//
+//   · createBoardSurfaces：「在看板里打开」的接收方登记表——对话里点了文件 / 「查看浏览器」，交给哪个看板；
+//   · createBoardOwners：同一个对话（任务）开着几个看板时，各自报告的样子，生效的是哪一个。
+//
+// 每个适配各有一份实例（中枢：每个仓库一份；节点：页面里一份），规则只有这一份。
+import type { BoardView } from "./workspace";
+import { activateBoardOwner, reportBoardOwner, selectedBoardOwner } from "./context";
+
+export interface BoardSurfaceEntry<T> {
+  /** 接得住（显示的就是这个对话 / 任务）就打开并返回 true。 */
+  surface: (target: T) => boolean;
+  owner?: string;
+  /** 嵌在对话里的看板（只接它自己那个对话组件的请求）。 */
+  inline?: boolean;
+  /** 越大越先问；缺省 2。 */
+  priority?: () => number;
+}
+
+export function createBoardSurfaces<T>() {
+  const entries: BoardSurfaceEntry<T>[] = [];
+  return {
+    /** 登记一个接收方；返回注销函数。后登记的先问（例如弹出的看板盖在常驻的上面）。 */
+    register(surface: (target: T) => boolean, options: Omit<BoardSurfaceEntry<T>, "surface"> = {}): () => void {
+      const entry = { surface, ...options };
+      entries.push(entry);
+      return () => { const at = entries.indexOf(entry); if (at >= 0) entries.splice(at, 1); };
+    },
+    /** 依次问（后登记的先问，再按 priority 从高到低），有一个接住就停；filter 排除不该问的。一个接收方出错不影响别的。 */
+    open(target: T, filter?: (entry: BoardSurfaceEntry<T>) => boolean): boolean {
+      const available = [...entries].reverse().filter((entry) => !filter || filter(entry))
+        .sort((a, b) => (b.priority?.() ?? 2) - (a.priority?.() ?? 2));
+      for (const { surface } of available) {
+        let handled = false;
+        try { handled = surface(target); } catch (error) { console.error("[@xgspz/cli-ui] board surface callback failed", error); }
+        if (handled) return true;
+      }
+      return false;
+    },
+  };
+}
+
+/** 每个对话（任务）的各个看板（owner）报告的样子；生效的是最近在用、还开着的那个（规则见 board/context）。 */
+export function createBoardOwners() {
+  const all = new Map<string, Map<string, BoardView>>();
+  const top = (sources: Map<string, BoardView> | undefined) => (sources?.size ? selectedBoardOwner(sources)?.[1] ?? null : null);
+  return {
+    /** 这个看板上次报告的样子。 */
+    previous(key: string, owner: string): BoardView | undefined { return all.get(key)?.get(owner); },
+    /** 记下 owner 的报告（null = 这个看板撤了），返回现在生效的样子。 */
+    report(key: string, owner: string, view: BoardView | null): BoardView | null {
+      const sources = all.get(key) ?? new Map<string, BoardView>();
+      if (view) reportBoardOwner(sources, owner, view); else sources.delete(owner);
+      if (sources.size) all.set(key, sources); else all.delete(key);
+      return top(sources);
+    },
+    /** 用户在 owner 这个看板上操作了：它变成生效的。没有这个看板时返回 null。 */
+    activate(key: string, owner: string): BoardView | null {
+      const sources = all.get(key);
+      if (!sources) return null;
+      return activateBoardOwner(sources, owner)?.[1] ?? null;
+    },
+    /** 现在生效的样子。 */
+    top(key: string): BoardView | null { return top(all.get(key)); },
+    /** 这个对话（任务）的全部看板报告（按先后）。 */
+    entries(key: string): Array<[string, BoardView]> { return [...all.get(key) ?? []]; },
+  };
+}

package/src/board/pathResolve.ts

@@ -0,0 +1,108 @@
+// 智能体在回复里写的相对路径打不开时（相对它 cd 进去的子目录写的，例如 manual/rules.md，实际在 data/run-1/prepare/manual/rules.md），
+// 按这个对话自己的线索补全：消息里提到过的目录、工具读写过的完整路径、看板打开过的文件。
+// 只用对话里已有的东西，不扫工作区；补出来的地址逐个向后端确认存在才算（中枢和节点适配共用）。
+import type { BoardBackend } from "../core/client";
+import type { Msg } from "../core/types";
+import { localFilePath } from "../ui/fileLinks";
+import { toolDataOf } from "../ui/transcriptModel";
+
+/** 最多看最近这么多条消息、留这么多条线索、补出这么多个候选（每个候选要问一次后端）。 */
+const HINT_MESSAGES = 400;
+const HINT_MAX = 600;
+export const CANDIDATE_MAX = 8;
+/** 工具输出很长时只看开头这一段（ls / find 的结果里也有完整路径）。 */
+const TOOL_RESULT_SCAN = 20_000;
+
+export interface PathHint {
+  /** 规范化后的路径（相对工作目录或绝对路径，不带末尾斜杠）。 */
+  path: string;
+  /** 写的时候以 / 结尾：是目录。 */
+  dir: boolean;
+}
+
+// 路径样子的一段：至少有一个 /，不含空白、引号、括号和中文标点（路径里的中文本身照常保留）。
+const TOKEN = /[^\s`'"<>()[\]{}|，。；：、！？“”‘’（）【】《》]*\/[^\s`'"<>()[\]{}|，。；：、！？“”‘’（）【】《》]*/gu;
+const LINK = /\]\(([^)\s]+)\)/g;
+
+function hintsFromText(text: string, out: PathHint[]) {
+  const raw: string[] = [];
+  for (const m of text.matchAll(LINK)) raw.push(m[1]);
+  for (const m of text.matchAll(TOKEN)) raw.push(m[0]);
+  for (const token of raw) {
+    const trimmed = token.replace(/[.,;:!?]+$/, "");
+    if (!trimmed || trimmed === "/" || /^\/+$/.test(trimmed)) continue;
+    const path = localFilePath(trimmed);
+    if (!path || !path.includes("/")) continue;
+    out.push({ path, dir: trimmed.endsWith("/") });
+  }
+}
+
+/** 对话里的路径线索，最近的在前（去重）。 */
+export function pathHints(messages: readonly Msg[], extra: readonly string[] = []): PathHint[] {
+  const out: PathHint[] = [];
+  for (const path of [...extra].reverse()) { const p = localFilePath(path); if (p && p.includes("/")) out.push({ path: p, dir: false }); }
+  for (let i = messages.length - 1, seen = 0; i >= 0 && seen < HINT_MESSAGES; i--, seen++) {
+    const m = messages[i];
+    if (m.role === "tool") {
+      const data = toolDataOf(m);
+      hintsFromText([data.title, data.detail ?? "", (data.result ?? "").slice(0, TOOL_RESULT_SCAN)].join("\n"), out);
+    } else if (m.role !== "queued") hintsFromText(m.content, out);
+    if (out.length >= HINT_MAX * 2) break;
+  }
+  const seenPaths = new Set<string>();
+  return out.filter((h) => { const key = `${h.dir ? "d" : "f"}:${h.path}`; if (seenPaths.has(key)) return false; seenPaths.add(key); return true; }).slice(0, HINT_MAX);
+}
+
+const isAbsolute = (p: string) => p.startsWith("/") || p.startsWith("~") || /^[a-z]:\//i.test(p);
+
+/**
+ * 相对路径 requested 可能指的完整路径，最可能的在前，最多 CANDIDATE_MAX 个：
+ *   · 线索里的文件以 /requested 结尾；
+ *   · 线索里出现了 requested 的第一段目录：取它前面的部分接上 requested；
+ *   · 线索是目录：目录接上 requested。
+ * 绝对路径不补（照原样就是它）。
+ */
+export function candidatePaths(requested: string, hints: readonly PathHint[]): string[] {
+  const want = localFilePath(requested);
+  if (!want || isAbsolute(want)) return [];
+  const segs = want.split("/");
+  const out: string[] = [];
+  const add = (p: string) => { if (p !== want && !out.includes(p)) out.push(p); };
+  // 线索里直接就有这个文件：最可靠，放最前。
+  for (const h of hints) if (!h.dir && h.path.endsWith(`/${want}`)) add(h.path);
+  for (const h of hints) {
+    if (out.length >= CANDIDATE_MAX) break;
+    const parts = h.path.split("/");
+    for (let i = parts.length - 1; i > 0; i--) {
+      if (parts[i] !== segs[0]) continue;
+      add([...parts.slice(0, i), ...segs].join("/"));
+    }
+    if (h.dir) add(`${h.path}/${want}`);
+  }
+  return out.slice(0, CANDIDATE_MAX);
+}
+
+/**
+ * 原路径确实不存在（后端回 404）时，按线索补全并逐个确认：返回确实存在的那些（顺序同 candidatePaths）。
+ * 原路径存在、或者读失败不是因为不存在（断网、没权限）：返回 []，不乱猜。
+ */
+export async function resolveMissingPath(backend: Pick<BoardBackend, "stat">, jobId: string, requested: string, hints: readonly PathHint[], signal?: AbortSignal): Promise<string[]> {
+  const candidates = candidatePaths(requested, hints);
+  if (!candidates.length) return [];
+  try {
+    await backend.stat(jobId, requested);
+    return [];
+  } catch (error) {
+    if ((error as { status?: number }).status !== 404) return [];
+  }
+  const found = new Array<boolean>(candidates.length).fill(false);
+  let next = 0;
+  const worker = async () => {
+    while (next < candidates.length && !signal?.aborted) {
+      const at = next++;
+      try { const info = await backend.stat(jobId, candidates[at]); found[at] = info.type === "file"; } catch { /* 不存在或读不到：不算 */ }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, candidates.length) }, worker));
+  return signal?.aborted ? [] : candidates.filter((_, i) => found[i]);
+}