@spzxg/cli-ui 0.1.0 → 0.3.0

package/src/board/blocks.tsx

@@ -0,0 +1,96 @@
+// 看板的两个核心，各自是一块独立的积木，放到哪里都能用：
+//
+//   <CliFilePreview jobId path />   任务工作区里一个文件的预览 + 下载（Markdown / 代码 / CSV / 图片 / PDF / HTML / Word）
+//   <CliBrowserView jobId />        任务浏览器的实时画面 + 接管 / 交还 / 打开 / 关闭
+//
+// 和别的组件一样：外面有 <CliCenterProvider> 就共用它（同一个对话只连一条流）；没有就用自己的连接参数
+// （baseUrl / token / line / headers）建一个。不给 jobId 时跟 Provider 的选中走。
+// 它们只依赖中枢的看板接口（/api/jobs/:id/files、/browser…），不依赖 cli-chat / cli-board。
+import { useState, type CSSProperties } from "react";
+import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.js";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider.js";
+import { FileViewer, type FileAction } from "./FileViewer.js";
+import { BrowserPane } from "./BrowserPane.js";
+
+interface BlockProps extends CliStoreOptions {
+  /** 哪个对话（center 的 job_id）。不给就跟 Provider 的选中走。 */
+  jobId?: string | null;
+  theme?: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  store?: CliStore;
+  onEvent?: (event: CliEvent) => void;
+}
+
+export interface CliFilePreviewProps extends BlockProps {
+  /** 工作区里的相对路径（如 "outputs/报告.md"），或节点上的绝对路径。 */
+  path: string;
+  /** 预览里点了别的本地文件（Markdown 里的链接）。不给就在本组件里切换过去。 */
+  onOpenPath?: (path: string) => void;
+  /** 给了就显示关闭按钮。 */
+  onClose?: () => void;
+  /** 头部的自定义按钮。 */
+  actions?: FileAction[];
+  /** 变了就重读（宿主知道文件更新时递增）。 */
+  version?: number;
+  /** 不要头部（宿主自己做标题和按钮）。 */
+  bare?: boolean;
+}
+
+export function CliFilePreview(props: CliFilePreviewProps) {
+  const ctx = useCliStoreContext();
+  return withOwnProvider(props, <FilePreviewInner {...props} inProvider={!!ctx} />, !!ctx);
+}
+
+function FilePreviewInner({ jobId: jobIdProp, path, onOpenPath, onClose, actions, version, bare, theme = "light", className, style, onEvent, inProvider }: CliFilePreviewProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {}, inProvider);
+  const store = useCliStore();
+  const selected = useCliState((s) => s.selected);
+  const jobId = jobIdProp !== undefined ? jobIdProp : selected;
+  const [shown, setShown] = useShownPath(path);
+  const backend = store.client.board;
+  return (
+    <div className={`cli-ui cli-file-preview ${className ?? ""}`} data-theme={theme} style={style}>
+      {!backend ? <div className="cli-fv-note">当前后端不支持文件预览（需要任务中心的 /api/jobs/:id/files 接口）。</div>
+        : !jobId ? <div className="cli-fv-note">没有指定对话。</div>
+          : !shown ? <div className="cli-fv-note">没有指定文件。</div>
+            : <FileViewer key={`${jobId}:${shown}`} backend={backend} jobId={jobId} path={shown} version={version} actions={actions} onClose={onClose} bare={bare}
+                onOpenPath={onOpenPath ?? setShown} />}
+    </div>
+  );
+}
+
+export interface CliBrowserViewProps extends BlockProps {
+  /** 只看：不能打开 / 关闭 / 接管。 */
+  readOnly?: boolean;
+}
+
+export function CliBrowserView(props: CliBrowserViewProps) {
+  const ctx = useCliStoreContext();
+  return withOwnProvider(props, <BrowserViewInner {...props} inProvider={!!ctx} />, !!ctx);
+}
+
+function BrowserViewInner({ jobId: jobIdProp, readOnly, theme = "light", className, style, onEvent, inProvider }: CliBrowserViewProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, {}, inProvider);
+  const store = useCliStore();
+  const selected = useCliState((s) => s.selected);
+  const jobId = jobIdProp !== undefined ? jobIdProp : selected;
+  const backend = store.client.board;
+  return (
+    <div className={`cli-ui cli-browser-view ${className ?? ""}`} data-theme={theme} style={style}>
+      {!backend ? <div className="cli-fv-note">当前后端不支持任务浏览器（需要任务中心的 /api/jobs/:id/browser 接口）。</div>
+        : !jobId ? <div className="cli-fv-note">没有指定对话。</div>
+          : <BrowserPane key={jobId} backend={backend} jobId={jobId} readOnly={readOnly} />}
+    </div>
+  );
+}
+
+/** 显示的路径：跟着 prop 走；预览里点了别的文件时在组件内切换，prop 变了再以 prop 为准。 */
+function useShownPath(path: string): [string, (p: string) => void] {
+  const [state, setState] = useState({ prop: path, shown: path });
+  if (state.prop !== path) {
+    setState({ prop: path, shown: path });
+    return [path, (p) => setState({ prop: path, shown: p })];
+  }
+  return [state.shown, (p) => setState((s) => ({ ...s, shown: p }))];
+}

package/src/board/fileKind.ts

@@ -0,0 +1,81 @@
+// 看板按扩展名决定怎么预览一个文件。
+export type PreviewKind = "markdown" | "code" | "text" | "csv" | "image" | "pdf" | "html" | "docx" | "binary";
+
+const CODE_LANG: Record<string, string> = {
+  ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx", mjs: "javascript", cjs: "javascript",
+  json: "json", py: "python", rb: "ruby", go: "go", rs: "rust", java: "java", kt: "kotlin", swift: "swift",
+  c: "c", h: "c", cpp: "cpp", hpp: "cpp", cs: "csharp", php: "php", sh: "bash", bash: "bash", zsh: "bash",
+  sql: "sql", yaml: "yaml", yml: "yaml", toml: "ini", ini: "ini", xml: "xml", css: "css", scss: "scss",
+  vue: "xml", svelte: "xml", dockerfile: "dockerfile", makefile: "makefile", diff: "diff", patch: "diff",
+};
+const TEXT_EXT = new Set(["txt", "log", "env", "gitignore", "conf", "cfg", "properties", "lock", "tsv"]);
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "svg", "avif"]);
+
+export function extOf(path: string): string {
+  const name = path.split("/").pop() ?? "";
+  const lower = name.toLowerCase();
+  if (lower === "dockerfile" || lower === "makefile") return lower;
+  const dot = lower.lastIndexOf(".");
+  return dot > 0 ? lower.slice(dot + 1) : "";
+}
+
+export function previewKind(path: string, contentType = ""): PreviewKind {
+  const ext = extOf(path);
+  if (ext === "md" || ext === "markdown") return "markdown";
+  if (ext === "csv") return "csv";
+  if (IMAGE_EXT.has(ext)) return "image";
+  if (ext === "pdf") return "pdf";
+  if (ext === "html" || ext === "htm") return "html";
+  if (ext === "docx") return "docx";
+  if (CODE_LANG[ext]) return "code";
+  if (TEXT_EXT.has(ext)) return "text";
+  if (/^text\//.test(contentType) || /json|xml|javascript/.test(contentType)) return "text";
+  if (!ext) return "text"; // README、LICENSE 之类
+  return "binary";
+}
+
+export const codeLang = (path: string) => CODE_LANG[extOf(path)] ?? "";
+
+export function fmtSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/** 相对某个文件所在目录解析链接（Markdown 里的 ./img.png、../a.md）。 */
+export function resolveRelative(fromFile: string, href: string): string {
+  if (href.startsWith("/") || href.startsWith("~")) return href;
+  const base = fromFile.split("/").slice(0, -1);
+  for (const seg of href.split("/")) {
+    if (!seg || seg === ".") continue;
+    if (seg === "..") base.pop();
+    else base.push(seg);
+  }
+  return base.join("/");
+}
+
+/** 一行 CSV（支持引号里的逗号和 "" 转义）。 */
+export function parseCsv(text: string, maxRows = 500): { rows: string[][]; more: boolean } {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cell = "";
+  let quoted = false;
+  const sep = text.includes("\t") && !text.split("\n")[0].includes(",") ? "\t" : ",";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') { cell += '"'; i++; }
+      else if (ch === '"') quoted = false;
+      else cell += ch;
+    } else if (ch === '"' && cell === "") quoted = true;
+    else if (ch === sep) { row.push(cell); cell = ""; }
+    else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      row.push(cell); cell = "";
+      rows.push(row); row = [];
+      if (rows.length > maxRows) return { rows: rows.slice(0, maxRows), more: true };
+    } else cell += ch;
+  }
+  if (cell || row.length) { row.push(cell); rows.push(row); }
+  return { rows: rows.slice(0, maxRows), more: rows.length > maxRows };
+}

package/src/chat/CliChat.tsx

@@ -3,22 +3,34 @@
 // 每条消息是中枢的一轮，排队 / 执行 / 结束都跟 center 保持一致。
 import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
 import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.js";
-import type { ConversationCallback } from "../core/types.js";
-import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider } from "../core/provider.js";
-import { emptyConv, isRunning, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
+import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider.js";
+import { convKey, emptyConv, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
 import type { AskAnswers, AskQuestion, Msg } from "../core/types.js";
 import { Icon } from "../ui/icons.js";
 import { agentLabel as labelOf, fmtTokens, formatAnswersText, modelLabel } from "../ui/format.js";
 import { AgentBadge, Avatar, Skel, StatusDot, type DotCls } from "../ui/shared.js";
-import { MessageView, SessionBreak, type MessageHandlers } from "../ui/Transcript.js";
+import { HANDOFF_NOTICE_PREFIX, MessageView, SessionBreak, type MessageHandlers } from "../ui/Transcript.js";
 import { RENDER_MAX, RENDER_STEP, RENDER_WINDOW, buildTranscriptItems, hasOpenAsk, toolDataOf } from "../ui/transcriptModel.js";
 import { Composer, type ComposerOptions } from "./Composer.js";
 import { fillTemplate, resolveChatConfig, type CliChatConfig } from "../core/config.js";
 import { exportMarkdown } from "./export.js";
+import { FileLinkContext, FileOpenContext } from "../ui/fileLinks.js";
+import { FileViewer } from "../board/FileViewer.js";
+import { BrowserPane } from "../board/BrowserPane.js";
 
-export interface CliChatProps extends CliStoreOptions {
-  /** 显示哪个对话（center 的 job_id）。不给就跟共享仓库的选中走（和 cli-msglist 联动）；都没有 = 新对话。 */
+/** onTurnEnd / onConversationEnd：浏览器里从实时流算出的结果通知，不依赖 center 的 callback.url。 */
+export interface CliChatProps extends CliStoreOptions, ResultHandlers {
+  /**
+   * 显示哪个对话（center 的 job_id）。不给就跟共享仓库的选中走（和 cli-msglist 联动）；都没有 = 新对话。
+   * 也可以直接给对话键 "job_id#task_id"（cli-msglist 的 onSelect、job_change 事件的 key 就是它）。
+   */
   jobId?: string | null;
+  /**
+   * 对话任务里的哪个对话（子任务 task_id），和 jobId 一起用。不给 = 对话任务的第一个对话（只有一个对话时就是它）；
+   * "new" = 在这个对话任务里新开一个对话（同一节点、同一工作区，新的 Agent 会话），第一条消息发出后组件跟到开出来的那个。
+   * 结束对话时：给了 taskId 只关掉这一个对话，没给结束整个对话任务。
+   */
+  taskId?: string | null;
   /** 面包屑里的名称与色块（如业务 / 项目名）。 */
   title?: string;
   color?: string;
@@ -28,10 +40,24 @@ export interface CliChatProps extends CliStoreOptions {
   allowClose?: boolean;
   /** 界面配置：顶部栏、输入框、对话区各模块的显示与文案，见 core/config.ts。 */
   config?: CliChatConfig;
+  /**
+   * Agent 消息里本地文件链接（report.md、/abs/path、src/a.ts:12）的打开地址。缺省没有：显示成不可点的文字。
+   * 有文件服务时（例如以后的看板 / Operator 后端）给出地址，链接就能打开（与 Operator 一致）。
+   * taskId：看的是对话任务里指定的那个对话时才有。
+   */
+  fileUrl?: (path: string, jobId: string, kind: "link" | "image", taskId?: string | null) => string | null;
+  /**
+   * 点了本地文件链接 / 「查看浏览器」怎么打开：
+   *   · "auto"（缺省）—— 同一个 Provider 里有 cli-board 在看这个对话就在看板里打开，否则在对话里弹窗预览；
+   *   · "board" —— 只交给看板（没有看板时按 fileUrl 的地址打开）；
+   *   · "modal" —— 总是在对话里弹窗；
+   *   · "link" —— 不拦截，按 fileUrl 的地址在新窗口打开（以前的行为）。
+   * 无论哪种，都会发 open 事件（onEvent），宿主可以据此展开右侧面板。
+   */
+  fileOpen?: "auto" | "board" | "modal" | "link";
   /** 一轮结束（≈ center 回调 conversation_turn）、对话结束、job 变化等。 */
   onEvent?: (event: CliEvent) => void;
-  /** 前端回调：载荷与 center 回调 conversation_turn / conversation_closed 的请求体同名同义。 */
-  onCallback?: (payload: ConversationCallback) => void;
+
   theme?: "light" | "dark";
   className?: string;
   style?: CSSProperties;
@@ -44,9 +70,9 @@ export function CliChat(props: CliChatProps) {
 }
 
 // 不能再发消息的结束原因（调用方关闭 / 取消）。其余原因（过期、换线、节点丢失）再发会自动开新对话。
-const FINAL_REASONS = new Set(["closed", "cancelled"]);
+const FINAL_REASONS = new Set(["closed", "cancelled", "conversation_closed"]);
 const REASON_TEXT: Record<string, string> = {
-  closed: "对话已结束", cancelled: "对话已取消", expired: "对话空闲太久已过期",
+  closed: "对话已结束", cancelled: "对话已取消", conversation_closed: "这个对话已结束", expired: "对话空闲太久已过期",
   node_reassigned: "执行机器换到了别的产品线", node_lost: "执行节点长时间连不上",
 };
 
@@ -76,8 +102,8 @@ function RunningIndicator({ agent, agentName, startedAt, lastActivityRef }: { ag
   );
 }
 
-function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", readOnly: readOnlyProp, allowClose = true, config, theme = "light", className, style, onEvent, onCallback, inProvider, newConversation, createConversation, businessIdFor }: CliChatProps & { inProvider: boolean }) {
-  useComponentEvents(onEvent, onCallback, inProvider);
+function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", color = "#b8613f", readOnly: readOnlyProp, allowClose = true, config, theme = "light", className, style, onEvent, onTurnEnd, onConversationEnd, onCallback, inProvider, fileUrl, fileOpen = "auto", newConversation, createConversation, businessIdFor }: CliChatProps & { inProvider: boolean }) {
+  useComponentEvents(onEvent, { onTurnEnd, onConversationEnd, onCallback }, inProvider);
   // 配置按内容比较：宿主每次渲染传新对象也不会让消息行全部重渲染。
   const configKey = JSON.stringify(config ?? {});
   const cfg = useMemo(() => resolveChatConfig(config), [configKey]); // eslint-disable-line react-hooks/exhaustive-deps
@@ -87,31 +113,39 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
   // 显示哪个对话：
   //   · 不传 jobId → 跟仓库的选中走（和同一 Provider 里的 cli-msglist 联动）；
   //   · 传了 jobId（含 null = 新对话）→ 组件自己接管：从传入的 id 开始，之后自己新建出的对话、
-  //     center 接续出的新对话都由组件自己跟过去（同时发 job_change 告诉宿主）；宿主改了 jobId 就以宿主为准。
-  // 新对话的草稿按组件实例存（对话的草稿按 job_id 存，看同一个对话的组件共用一份是对的）。
+  //     center 接续出的新对话都由组件自己跟过去（同时发 job_change 告诉宿主）；宿主改了 jobId / taskId 就以宿主为准。
+  // 内部用对话键（key）：只有 job_id = 对话任务的第一个对话；"job#task" = 里面指定的那个对话（见 core/conversation.ts）。
+  // 新对话的草稿按组件实例存（对话的草稿按对话键存，看同一个对话的组件共用一份是对的）。
   const instanceId = useId();
   const controlled = jobIdProp !== undefined;
-  const [followed, setShown] = useState<{ prop: string | null | undefined; id: string | null }>(() => ({ prop: jobIdProp, id: jobIdProp ?? null }));
+  // jobId 也可以直接给对话键（例如 cli-msglist 的 onSelect 给的 "job#task"），taskId 再给就以 taskId 为准。
+  const keyProp = jobIdProp === undefined ? undefined : jobIdProp ? convKey(parseConvKey(jobIdProp).jobId, taskIdProp ?? parseConvKey(jobIdProp).taskId) : null;
+  const [followed, setShown] = useState<{ prop: string | null | undefined; id: string | null }>(() => ({ prop: keyProp, id: keyProp ?? null }));
   let viewId = followed.id;
-  if (followed.prop !== jobIdProp) {
-    viewId = jobIdProp ?? null;
-    setShown({ prop: jobIdProp, id: viewId });
+  if (followed.prop !== keyProp) {
+    viewId = keyProp ?? null;
+    setShown({ prop: keyProp, id: viewId });
   }
-  const jobId = controlled ? viewId : selected;
+  const key = controlled ? viewId : selected;
+  const ref = key ? parseConvKey(key) : null;
+  const jobId = ref?.jobId ?? null;
+  // 「在这个对话任务里新开一个对话」：还没有对话，第一条消息开出来。
+  const isNew = isNewInJob(key);
+  const taskId = ref?.taskId && !isNew ? ref.taskId : null;
   const go = useCallback((id: string | null) => {
     if (controlled) setShown((v) => (v.id === id ? v : { ...v, id }));
     else store.select(id);
   }, [controlled, store]);
-  const conv = useCliState((s) => (jobId ? s.convs[jobId] : undefined)) ?? (jobId ? emptyConv(jobId) : null);
+  const conv = useCliState((s) => (key && !isNew ? s.convs[key] : undefined)) ?? (key && !isNew ? emptyConv(key) : null);
   const entry = useCliState((s) => (jobId ? s.jobs[jobId] : undefined));
 
   // 看这个对话：开实时流（同一对话多处看只连一次）。
-  useEffect(() => (jobId ? store.open(jobId) : undefined), [store, jobId]);
+  useEffect(() => (key ? store.open(key) : undefined), [store, key]);
   // 正在看的对话被接续成了新 job（别处发消息触发的也算）：跟过去。
-  const jobIdRef = useRef(jobId);
-  jobIdRef.current = jobId;
+  const keyRef = useRef(key);
+  keyRef.current = key;
   useEffect(() => store.on((event) => {
-    if (event.type === "job_change" && event.previousJobId && event.previousJobId === jobIdRef.current) go(event.jobId);
+    if (event.type === "job_change" && event.previousKey && event.previousKey === keyRef.current) go(event.key);
   }), [store, go]);
 
   const allMessages = useMemo(() => (conv ? viewMessages(conv) : []), [conv]);
@@ -123,39 +157,54 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
   })), [allMessages, cfg.transcript.tools]);
   const running = conv ? isRunning(conv) : false;
   const job = entry?.job;
-  const task = job?.tasks?.[0];
+  // 这个对话对应的子任务：指定了就是它，否则对话任务的第一个（「新开」时借用第一个的智能体显示）。
+  const task = (taskId ? job?.tasks?.find((t) => t.id === taskId) : undefined) ?? (taskId ? undefined : job?.tasks?.[0]);
+  const info = taskId ? job?.conversation?.conversations?.find((c) => c.task_id === taskId) : undefined;
   const agent = task?.agent ?? conv?.turns[conv.turns.length - 1]?.agent ?? null;
   const agentText = labelOf(agent);
-  const status = conv?.job?.status ?? job?.status ?? null;
-  const closedReason = conv?.job?.closed_reason ?? job?.conversation?.closed_reason ?? null;
-  const ended = !!status && TERMINAL_JOB.has(status);
+  const jobStatus = conv?.job?.status ?? job?.status ?? null;
+  const jobEnded = !!jobStatus && TERMINAL_JOB.has(jobStatus);
+  // 只关掉了这一个对话（对话任务还开着）：按「这个对话已结束」显示，不能再发消息。
+  const convClosed = !jobEnded && !!(conv?.task?.closed ?? info?.closed);
+  const status = convClosed ? "succeeded" : jobStatus;
+  const closedReason = convClosed ? "conversation_closed" : conv?.job?.closed_reason ?? job?.conversation?.closed_reason ?? null;
+  const ended = jobEnded || convClosed;
   const finalEnd = ended && FINAL_REASONS.has(closedReason ?? "closed");
   const continuedFrom = job?.conversation?.continued_from_job_id ?? null;
-  const continuedBy = conv?.continuedBy ?? job?.conversation?.continued_by_job_id ?? null;
-  const convTitle = job?.title ?? conv?.job?.title ?? (jobId ? "对话" : "新对话");
+  // 接续自旧对话任务里的哪个对话（指定了对话时跟回那一个）。
+  const continuedFromKey = continuedFrom ? convKey(continuedFrom, taskId ? task?.continue_from_task_id ?? info?.continue_from_task_id ?? null : null) : null;
+  const continuedBy = conv?.continuedBy ?? (taskId ? null : job?.conversation?.continued_by_job_id ?? null);
+  const jobTitle = job?.title ?? conv?.job?.title;
+  // 对话任务里有几个对话时，标题是「对话任务 / 这个对话」。
+  const manyConvs = (job?.conversation?.conversations?.length ?? 0) > 1;
+  const convName = conv?.task?.title ?? info?.title ?? task?.title;
+  const convTitle = isNew ? `${jobTitle ? `${jobTitle} / ` : ""}新对话`
+    : taskId && manyConvs && convName && convName !== jobTitle ? `${jobTitle ?? "对话"} / ${convName}`
+      : jobTitle ?? (key ? "对话" : "新对话");
   const awaitingAnswer = useMemo(() => hasOpenAsk(messages), [messages]);
   const lastTurn = conv?.turns[conv.turns.length - 1];
   const awaiting = !ended && !running && !!lastTurn?.asked && lastTurn.status === "succeeded";
-  const loading = !!jobId && !!conv && !conv.hasTranscript && !conv.turns.length && conv.stream !== "error";
+  const loading = !!key && !isNew && !!conv && !conv.hasTranscript && !conv.turns.length && conv.stream !== "error";
 
-  // 用量：任务详情里的累计 + 实时流里上次刷新后的增量。
-  const fresh = (task ? Math.max(0, task.total_tokens - task.cache_read_tokens) : 0) + (conv?.liveUsage.fresh ?? 0);
-  const cacheRead = (task?.cache_read_tokens ?? 0) + (conv?.liveUsage.cacheRead ?? 0);
+  // 用量：任务详情里的累计 + 实时流里上次刷新后的增量（「新开」的对话还没有用量，不借第一个对话的）。
+  const usageTask = isNew ? undefined : task;
+  const fresh = (usageTask ? Math.max(0, usageTask.total_tokens - usageTask.cache_read_tokens) : 0) + (conv?.liveUsage.fresh ?? 0);
+  const cacheRead = (usageTask?.cache_read_tokens ?? 0) + (conv?.liveUsage.cacheRead ?? 0);
   const resolvedModel = conv?.resolvedModel ?? task?.resolved_model ?? null;
 
   const { dotCls, statusText } = useMemo((): { dotCls: DotCls; statusText: string } => {
-    if (!jobId) return { dotCls: "r", statusText: "未开始" };
+    if (!key || isNew) return { dotCls: "r", statusText: "未开始" };
     if (ended) return { dotCls: status === "succeeded" ? "g" : "x", statusText: REASON_TEXT[closedReason ?? ""] ?? (status === "succeeded" ? "已结束" : status === "cancelled" ? "已取消" : "已失败") };
     if (awaiting) return { dotCls: "a", statusText: "需要你处理" };
     if (running) return { dotCls: "a", statusText: "运行中" };
     if (status === "queued") return { dotCls: "a", statusText: "等待执行节点" };
     return { dotCls: "a", statusText: "进行中" };
-  }, [jobId, ended, status, closedReason, awaiting, running]);
+  }, [key, isNew, ended, status, closedReason, awaiting, running]);
 
   // ── 处理器（引用稳定，MessageView 的 memo 才有效） ──
   // 输入框之外的操作（回答提问、撤回排队、结束对话、停止）失败时在顶部提示，不静默吞掉。
   const [actionError, setActionError] = useState<string | null>(null);
-  useEffect(() => setActionError(null), [jobId]);
+  useEffect(() => setActionError(null), [key]);
   const report = useCallback(async <T,>(work: Promise<T>, what: string) => {
     try {
       const result = await work;
@@ -166,46 +215,81 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
       throw error;
     }
   }, []);
-  const latest = useRef({ jobId, messages, conv });
-  latest.current = { jobId, messages, conv };
+  const latest = useRef({ key, messages, conv });
+  latest.current = { key, messages, conv };
   // 本组件的新建参数随每次发送带上：放进共享 Provider 时也用自己的，不依赖仓库是谁建的。
   const sendOpts = useRef({ newConversation, createConversation, businessIdFor, select: !controlled });
   sendOpts.current = { newConversation, createConversation, businessIdFor, select: !controlled };
   const send = useCallback(async (text: string) => {
-    const id = latest.current.jobId;
+    const id = latest.current.key;
     const target = await store.send(id ?? null, text, sendOpts.current);
     if (target !== id) go(target);
   }, [store, go]);
+  // AI 把浏览器交给用户（实时新来的「🖐 …」行）：同一 Provider 里有看板在看这个对话，就把看板切到浏览器（收起的会请宿主展开）。
+  // 打开对话时已有的交接行不算（先记下已有的再开始比较）；没有看板时不弹窗打扰，行里有「查看浏览器」按钮。
+  const handoffSeen = useRef<{ key: string | null; ids: Set<string> | null }>({ key: null, ids: null });
+  useEffect(() => {
+    if (!key || !conv || fileOpen === "link" || fileOpen === "modal") return;
+    if (handoffSeen.current.key !== key) handoffSeen.current = { key, ids: null };
+    if (!conv.hasTranscript) return;
+    const handoffs = conv.msgs.filter((m) => m.role === "system" && m.content.startsWith(HANDOFF_NOTICE_PREFIX));
+    const seen = handoffSeen.current;
+    if (!seen.ids) { seen.ids = new Set(handoffs.map((m) => m.id)); return; }
+    const fresh = handoffs.filter((m) => !seen.ids!.has(m.id));
+    for (const m of fresh) seen.ids.add(m.id);
+    if (fresh.length) store.openInBoard(key, { kind: "browser" });
+  }, [key, conv, fileOpen, store]);
+
+  // 对话里弹窗打开的文件 / 浏览器（没有看板接的时候）。换对话就关掉。
+  const [popup, setPopup] = useState<{ kind: "file"; path: string } | { kind: "browser" } | null>(null);
+  useEffect(() => setPopup(null), [key]);
+  useEffect(() => {
+    if (!popup) return;
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") setPopup(null); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [popup]);
   const handlers = useMemo<MessageHandlers>(() => ({
     // 与 Operator 的 answerQuestion 一致：先把卡片标成已答，再把回答发出去（center 已结束提问那一轮，回答就是下一条消息）。
     onAnswer: readOnly ? undefined : async (askId: string, questions: AskQuestion[], answers: AskAnswers) => {
-      const id = latest.current.jobId;
+      const id = latest.current.key;
       if (!id) return;
       const sent = askId
         ? store.answerAsk(id, askId, questions, answers, sendOpts.current).then((target) => { if (target !== id) go(target); })
         : send(formatAnswersText(questions, answers));
       await report(sent, "回答没有发出去");
     },
-    onCancelQueued: readOnly ? undefined : (m: Msg) => { const id = latest.current.jobId; if (id && m.turnId) void report(store.cancelTurn(id, m.turnId), "撤回失败").catch(() => undefined); },
+    onCancelQueued: readOnly ? undefined : (m: Msg) => { const id = latest.current.key; if (id && m.turnId) void report(store.cancelTurn(id, m.turnId), "撤回失败").catch(() => undefined); },
     // 后端能直接处理的浏览器动作（Operator 后端）才给；center 不提供，卡片按 Operator「没有浏览器能力」时的样子显示。
     onInput: readOnly || !store.client.submitInput ? undefined : async (inputId: string, values: string[]) => {
-      const id = latest.current.jobId;
+      const id = latest.current.key;
       if (!id) return "对话还没开始";
       try { return await store.client.submitInput!(id, inputId, values); } catch (error) { return error instanceof Error ? error.message : String(error); }
     },
-    onHandback: readOnly || !store.client.handback ? undefined : async () => {
-      const id = latest.current.jobId;
+    // 交还浏览器：后端自己的 handback（Operator 后端），没有就走看板接口（center 转发到节点）。
+    onHandback: readOnly || !(store.client.handback || store.client.board) ? undefined : async () => {
+      const id = latest.current.key;
       if (!id) return "对话还没开始";
-      try { return await store.client.handback!(id); } catch (error) { return error instanceof Error ? error.message : String(error); }
+      try {
+        if (store.client.handback) return await store.client.handback(id);
+        await store.client.board!.browserAction(id, "handback");
+        return null;
+      } catch (error) { return error instanceof Error ? error.message : String(error); }
+    },
+    onShowBrowser: !store.client.board || fileOpen === "link" ? undefined : () => {
+      const id = latest.current.key;
+      if (!id) return;
+      if (fileOpen !== "modal" && store.openInBoard(id, { kind: "browser" })) return;
+      if (fileOpen !== "board") setPopup({ kind: "browser" });
     },
     onRetry: readOnly ? undefined : (msgId: string) => {
       const list = latest.current.messages;
       const at = list.findIndex((m) => m.id === msgId);
       for (let j = (at === -1 ? list.length : at) - 1; j >= 0; j--) if (list[j].role === "user") { void report(send(list[j].content), "重试没有发出去").catch(() => undefined); return; }
     },
-  }), [readOnly, send, store, go, report]);
+  }), [readOnly, send, store, go, report, fileOpen]);
   const stop = useCallback(async () => {
-    const { jobId: id, conv: c } = latest.current;
+    const { key: id, conv: c } = latest.current;
     const turn = c ? runningTurn(c) : null;
     if (id && turn) await report(store.cancelTurn(id, turn.turn_id), "停止失败");
   }, [store, report]);
@@ -365,7 +449,7 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
     setAtBottom(true);
     setWin({ start: null, end: null });
     if (scrollRef.current) scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
-  }, [jobId]);
+  }, [key]);
 
   const contextReset = !!lastTurn?.context_reset && conv?.turns.some((turn) => turn.context_reset);
   const h = cfg.header;
@@ -377,7 +461,29 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
   const composerDisabled = !!readOnly || finalEnd || conv?.stream === "error";
   const disabledHint = readOnly ? "只读" : finalEnd ? "对话已结束，不能再发消息" : conv?.streamError ?? undefined;
 
+  const fileUrlRef = useRef(fileUrl);
+  fileUrlRef.current = fileUrl;
+  const board = store.client.board;
+  // 文件地址：宿主给的 fileUrl 优先；没给且后端有看板接口、地址能直接打开时，用 center 的文件接口。
+  const resolveFile = useMemo(() => {
+    if (fileUrl) return (path: string, kind: "link" | "image") => (jobId ? fileUrlRef.current?.(path, jobId, kind, taskId) ?? null : null);
+    if (board?.directLinks && key) return (path: string) => board.fileUrl(key, path);
+    return null;
+  }, [!!fileUrl, key, jobId, taskId, board]); // eslint-disable-line react-hooks/exhaustive-deps
+  // 点了本地文件：看板 → 弹窗 → 地址（见 fileOpen）。
+  const openFile = useMemo(() => {
+    if (!key || fileOpen === "link") return null;
+    return (path: string) => {
+      if (fileOpen !== "modal" && store.openInBoard(key, { kind: "file", path })) return true;
+      if (fileOpen === "board" || !board) return false;
+      setPopup({ kind: "file", path });
+      return true;
+    };
+  }, [key, fileOpen, store, board]);
+
   return (
+    <FileLinkContext.Provider value={resolveFile}>
+    <FileOpenContext.Provider value={openFile}>
     <div className={`cli-ui cli-chat ${className ?? ""}`} data-theme={theme} style={style}>
       <div className="session">
         {h.show && (h.crumb || h.export || h.title || h.agent || h.usage || h.model || h.status || h.close) && <div className="sess-head">
@@ -387,8 +493,8 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
                 <span className="pic" style={{ width: 16, height: 16, borderRadius: 5, background: color, display: "grid", placeItems: "center", color: "#fff", fontSize: 9, fontWeight: 700 }}>{title[0]}</span>
                 {title} <span className="sep">/</span> 对话
               </>}
-              {h.export && jobId && allMessages.length > 0 && (
-                <button className="crumb-export" onClick={() => exportMarkdown(convTitle, jobId, allMessages, conv?.turns ?? [])} title="导出这个对话的完整过程（Markdown）">{Icon.download()} 导出执行过程</button>
+              {h.export && key && allMessages.length > 0 && (
+                <button className="crumb-export" onClick={() => exportMarkdown(convTitle, taskId ? `${jobId}-${taskId}` : jobId!, allMessages, conv?.turns ?? [])} title="导出这个对话的完整过程（Markdown）">{Icon.download()} 导出执行过程</button>
               )}
             </div>}
             {h.title && <div className="sh-title"><span className="sht-text" title={convTitle}>{convTitle}</span></div>}
@@ -401,7 +507,7 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
                 {cacheRead > 0 && <> <span className="usage-dot">·</span> <span className="usage-cached">{fmtTokens(cacheRead)} 缓存</span></>}
               </span>
             )}
-            {h.model && jobId && (
+            {h.model && key && !isNew && (
               <span className="status-ctl" style={{ cursor: "default" }} title="模型由任务中心按产品线配置分配">
                 {Icon.spark()}<span className="cv">默认</span>
                 {resolvedModel && <span className="model-badge" title={`上次运行于 ${resolvedModel}`}>{modelLabel(resolvedModel)}</span>}
@@ -411,18 +517,18 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
               <StatusDot cls={dotCls} running={running} awaiting={awaiting} title={statusText} />
               <span className="cv">{statusText}</span>
             </span>}
-            {h.close && jobId && allowClose && !readOnly && !ended && (
-              <button className="btn btn-line btn-sm" onClick={() => setClosing("confirm")} disabled={closing === "busy"} title="结束这个对话：之后不再接收消息，正在跑的一轮会被中止">{Icon.stop()} 结束对话</button>
+            {h.close && key && !isNew && allowClose && !readOnly && !ended && (
+              <button className="btn btn-line btn-sm" onClick={() => setClosing("confirm")} disabled={closing === "busy"} title={taskId ? "只结束这个对话：之后它不再接收消息，正在跑的一轮会被中止；同一任务里的其他对话不受影响" : "结束这个对话：之后不再接收消息，正在跑的一轮会被中止"}>{Icon.stop()} 结束对话</button>
             )}
           </div>
         </div>}
 
-        {closing !== "idle" && jobId && (
+        {closing !== "idle" && key && (
           <div className="clear-confirm">
-            <span>结束这个对话？结束后不能再发消息{running ? "，正在执行的一轮会被中止" : ""}。</span>
+            <span>结束这个对话？结束后不能再发消息{running ? "，正在执行的一轮会被中止" : ""}{taskId && manyConvs ? "；同一任务里的其他对话不受影响" : ""}。</span>
             <span className="spacer" />
             <button className="btn btn-ghost btn-sm" onClick={() => setClosing("idle")} disabled={closing === "busy"}>取消</button>
-            <button className="btn btn-accent btn-sm" disabled={closing === "busy"} onClick={() => { setClosing("busy"); void report(store.close(jobId), "结束对话失败").catch(() => undefined).finally(() => setClosing("idle")); }}>{closing === "busy" ? "正在结束…" : "确认结束"}</button>
+            <button className="btn btn-accent btn-sm" disabled={closing === "busy"} onClick={() => { setClosing("busy"); void report(store.close(key), "结束对话失败").catch(() => undefined).finally(() => setClosing("idle")); }}>{closing === "busy" ? "正在结束…" : "确认结束"}</button>
           </div>
         )}
         {actionError && <div className="sync-banner conflict"><span className="sync-msg">⚠ {actionError}</span><span className="sync-spacer" /><button className="btn btn-ghost btn-sm" onClick={() => setActionError(null)}>知道了</button></div>}
@@ -432,17 +538,18 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
         <div className="transcript-wrap">
           <div className="transcript" ref={scrollRef} onScroll={onScroll}>
             <div className="tw">
-              {!jobId && cfg.empty.show && (
+              {(!key || isNew) && cfg.empty.show && (
                 <div className="hero cli-hero">
                   <div className="h-ic">{Icon.bolt()}</div>
                   <div className="h-status"><StatusDot cls="r" /> 新对话 · 尚未开始</div>
                   <h2>{cfg.empty.title}</h2>
+                  {isNew && <p className="h-desc">在「{jobTitle ?? "这个任务"}」里新开一个对话：和任务里的其他对话共用同一个工作区（能看到彼此产出的文件），对话内容各自独立。</p>}
                   {cfg.empty.description && <p className="h-desc">{cfg.empty.description}</p>}
                 </div>
               )}
               {continuedFrom && (
                 <div className="msg system info"><div className="msg-body">ℹ 这个对话接续自上一个已结束的对话（{continuedFrom}）。工作区文件沿用，之前的对话内容没有带进来。
-                  <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={() => go(continuedFrom)}>查看上一个对话</button>
+                  <button className="btn btn-line btn-sm" style={{ marginLeft: 8 }} onClick={() => go(continuedFromKey)}>查看上一个对话</button>
                 </div></div>
               )}
               {contextReset && <div className="msg system info"><div className="msg-body">ℹ 执行节点上的会话重建过：从那一轮起是新的 Agent 会话，之前的对话上下文没有带过去（工作区文件还在）。</div></div>}
@@ -499,18 +606,34 @@ function ChatInner({ jobId: jobIdProp, title = "对话", color = "#b8613f", read
         </div>
         {!readOnly && (
           <Composer
-            key={jobId ?? "new"}
-            draft={jobId ?? `new:${instanceId}`}
-            placeholder={fillTemplate(jobId ? cfg.composer.placeholder : cfg.composer.placeholderNew, { title: convTitle, agent: agentText })}
+            key={key ?? "new"}
+            draft={key ?? `new:${instanceId}`}
+            placeholder={fillTemplate(key && !isNew ? cfg.composer.placeholder : cfg.composer.placeholderNew, { title: convTitle, agent: agentText })}
             disabled={composerDisabled}
             disabledHint={cfg.composer.placeholderDisabled ? fillTemplate(cfg.composer.placeholderDisabled, { title: convTitle, agent: agentText }) : disabledHint}
             running={running}
             onSend={send}
-            onStop={cfg.composer.stop && jobId && conv && runningTurn(conv) ? stop : undefined}
+            onStop={cfg.composer.stop && key && conv && runningTurn(conv) ? stop : undefined}
             options={composerOptions}
           />
         )}
       </div>
+      {popup && key && board && (
+        <div className="scrim" onClick={(e) => { if (e.target === e.currentTarget) setPopup(null); }}>
+          <div className={`modal cli-popup ${popup.kind}`} role="dialog" aria-modal="true" aria-label={popup.kind === "file" ? popup.path : "任务浏览器"}>
+            {popup.kind === "file" ? (
+              <FileViewer backend={board} jobId={key} path={popup.path} onClose={() => setPopup(null)} onOpenPath={(p) => setPopup({ kind: "file", path: p })} />
+            ) : (
+              <>
+                <div className="cli-fv-h"><span className="cli-fv-name">任务浏览器</span><span className="cli-fv-sp" /><button className="cli-fv-icon" onClick={() => setPopup(null)} title="关闭">{Icon.x()}</button></div>
+                <BrowserPane backend={board} jobId={key} readOnly={readOnly} />
+              </>
+            )}
+          </div>
+        </div>
+      )}
     </div>
+    </FileOpenContext.Provider>
+    </FileLinkContext.Provider>
   );
 }