@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/chat/CliChat.tsx

@@ -0,0 +1,639 @@
+// cli-chat：对话。界面取自 Operator 的会话视图（SessionView 的对话部分 + Composer），
+// 数据来自 center 的对话任务（mode=conversation）：实时流里的节点转录按 Operator 的规则渲染，
+// 每条消息是中枢的一轮，排队 / 执行 / 结束都跟 center 保持一致。
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
+import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.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 { 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";
+
+/** 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;
+  /** 只看不发。 */
+  readOnly?: boolean;
+  /** 是否显示「结束对话」按钮，缺省 true（等同 config.header.close）。 */
+  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;
+
+  theme?: "light" | "dark";
+  className?: string;
+  style?: CSSProperties;
+  store?: CliStore;
+}
+
+export function CliChat(props: CliChatProps) {
+  const ctx = useCliStoreContext();
+  return withOwnProvider(props, <ChatInner {...props} inProvider={!!ctx} />, !!ctx);
+}
+
+// 不能再发消息的结束原因（调用方关闭 / 取消）。其余原因（过期、换线、节点丢失）再发会自动开新对话。
+const FINAL_REASONS = new Set(["closed", "cancelled", "conversation_closed"]);
+const REASON_TEXT: Record<string, string> = {
+  closed: "对话已结束", cancelled: "对话已取消", conversation_closed: "这个对话已结束", expired: "对话空闲太久已过期",
+  node_reassigned: "执行机器换到了别的产品线", node_lost: "执行节点长时间连不上",
+};
+
+/** 「智能体在工作」那一行：跑了多久，很久没输出时提示可能卡住。与 Operator 的 RunningIndicator 一致。 */
+const QUIET_AFTER_MS = 180_000;
+function RunningIndicator({ agent, agentName, startedAt, lastActivityRef }: { agent: string | null; agentName: string; startedAt: number | null; lastActivityRef: React.MutableRefObject<number> }) {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => { const t = setInterval(() => setNow(Date.now()), 1000); return () => clearInterval(t); }, []);
+  const elapsed = startedAt ? Math.max(0, now - startedAt) : null;
+  const quiet = now - lastActivityRef.current;
+  const clock = (ms: number) => {
+    const s = Math.floor(ms / 1000);
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const ss = String(s % 60).padStart(2, "0");
+    return h ? `${h}:${String(m).padStart(2, "0")}:${ss}` : `${m}:${ss}`;
+  };
+  return (
+    <div className="msg assistant">
+      <div className="who"><Avatar who="cc" agent={agent} /> {agentName}</div>
+      <div className="msg-body run-ind">
+        <span className="typing"><i /><i /><i /></span>
+        {elapsed !== null && <span className="run-ind-t">运行中 · {clock(elapsed)}</span>}
+        {quiet >= QUIET_AFTER_MS && <span className="run-ind-quiet">已 {Math.floor(quiet / 60_000)} 分钟没有新输出（可能在执行耗时操作）；确认卡住时可点输入框右侧的停止按钮</span>}
+      </div>
+    </div>
+  );
+}
+
+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
+  const readOnly = !!readOnlyProp || !cfg.composer.show;
+  const store = useCliStore();
+  const selected = useCliState((s) => s.selected);
+  // 显示哪个对话：
+  //   · 不传 jobId → 跟仓库的选中走（和同一 Provider 里的 cli-msglist 联动）；
+  //   · 传了 jobId（含 null = 新对话）→ 组件自己接管：从传入的 id 开始，之后自己新建出的对话、
+  //     center 接续出的新对话都由组件自己跟过去（同时发 job_change 告诉宿主）；宿主改了 jobId / taskId 就以宿主为准。
+  // 内部用对话键（key）：只有 job_id = 对话任务的第一个对话；"job#task" = 里面指定的那个对话（见 core/conversation.ts）。
+  // 新对话的草稿按组件实例存（对话的草稿按对话键存，看同一个对话的组件共用一份是对的）。
+  const instanceId = useId();
+  const controlled = jobIdProp !== undefined;
+  // 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 !== keyProp) {
+    viewId = keyProp ?? null;
+    setShown({ prop: keyProp, id: viewId });
+  }
+  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) => (key && !isNew ? s.convs[key] : undefined)) ?? (key && !isNew ? emptyConv(key) : null);
+  const entry = useCliState((s) => (jobId ? s.jobs[jobId] : undefined));
+
+  // 看这个对话：开实时流（同一对话多处看只连一次）。
+  useEffect(() => (key ? store.open(key) : undefined), [store, key]);
+  // 正在看的对话被接续成了新 job（别处发消息触发的也算）：跟过去。
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  useEffect(() => store.on((event) => {
+    if (event.type === "job_change" && event.previousKey && event.previousKey === keyRef.current) go(event.key);
+  }), [store, go]);
+
+  const allMessages = useMemo(() => (conv ? viewMessages(conv) : []), [conv]);
+  // config.transcript.tools=false：去掉工具卡片，只留文字往来（提问 / 输入卡片要用户操作，照常显示）。
+  const messages = useMemo(() => (cfg.transcript.tools ? allMessages : allMessages.filter((m) => {
+    if (m.role !== "tool") return true;
+    const data = toolDataOf(m);
+    return !!(data.ask || data.input);
+  })), [allMessages, cfg.transcript.tools]);
+  const running = conv ? isRunning(conv) : false;
+  const job = entry?.job;
+  // 这个对话对应的子任务：指定了就是它，否则对话任务的第一个（「新开」时借用第一个的智能体显示）。
+  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 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 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 = !!key && !isNew && !!conv && !conv.hasTranscript && !conv.turns.length && conv.stream !== "error";
+
+  // 用量：任务详情里的累计 + 实时流里上次刷新后的增量（「新开」的对话还没有用量，不借第一个对话的）。
+  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 (!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: "进行中" };
+  }, [key, isNew, ended, status, closedReason, awaiting, running]);
+
+  // ── 处理器（引用稳定，MessageView 的 memo 才有效） ──
+  // 输入框之外的操作（回答提问、撤回排队、结束对话、停止）失败时在顶部提示，不静默吞掉。
+  const [actionError, setActionError] = useState<string | null>(null);
+  useEffect(() => setActionError(null), [key]);
+  const report = useCallback(async <T,>(work: Promise<T>, what: string) => {
+    try {
+      const result = await work;
+      setActionError(null);
+      return result;
+    } catch (error) {
+      setActionError(`${what}：${error instanceof Error ? error.message : String(error)}`);
+      throw error;
+    }
+  }, []);
+  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.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.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.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.key;
+      if (!id) return "对话还没开始";
+      try { return await store.client.submitInput!(id, inputId, values); } catch (error) { return error instanceof Error ? error.message : String(error); }
+    },
+    // 交还浏览器：后端自己的 handback（Operator 后端），没有就走看板接口（center 转发到节点）。
+    onHandback: readOnly || !(store.client.handback || store.client.board) ? undefined : async () => {
+      const id = latest.current.key;
+      if (!id) return "对话还没开始";
+      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, fileOpen]);
+  const stop = useCallback(async () => {
+    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]);
+  const [closing, setClosing] = useState<"idle" | "confirm" | "busy">("idle");
+
+  // ── 运行计时（与 Operator 一致：本页看着开始的轮次按本机时钟，进来时已在跑的按那条用户消息的时间） ──
+  const lastUserTs = useMemo(() => { for (let i = messages.length - 1; i >= 0; i--) if (messages[i].role === "user") return messages[i].ts ?? null; return null; }, [messages]);
+  const [runSeenAt, setRunSeenAt] = useState<number | null>(null);
+  const lastActivityRef = useRef(Date.now());
+  const wasRunningRef = useRef(running);
+  useEffect(() => {
+    if (running && !wasRunningRef.current) { setRunSeenAt(Date.now()); lastActivityRef.current = Date.now(); }
+    else if (!running) setRunSeenAt(null);
+    wasRunningRef.current = running;
+  }, [running]);
+  useEffect(() => { lastActivityRef.current = Date.now(); }, [messages]);
+  const turnStartedAt = runSeenAt ?? lastUserTs;
+
+  // ── 分窗渲染（移植自 Operator 的 SessionView）：DOM 里最多 RENDER_MAX 行，几千条消息也照样流畅 ──
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const pinned = useRef(true);
+  const [atBottom, setAtBottom] = useState(true);
+  const committed = useMemo(() => messages.filter((m) => m.role !== "queued"), [messages]);
+  const queued = useMemo(() => messages.filter((m) => m.role === "queued"), [messages]);
+  const items = useMemo(() => buildTranscriptItems(committed), [committed]);
+  const [win, setWin] = useState<{ start: string | null; end: string | null }>({ start: null, end: null });
+  const { startIdx, endIdx } = useMemo(() => {
+    const find = (key: string | null) => (key ? items.findIndex((it) => it.key === key) : -1);
+    const e = find(win.end);
+    const last = e >= 0 ? e : items.length - 1;
+    let s = find(win.start);
+    if (s >= 0) while (s > 0 && items[s - 1].kind !== "msg") s--;
+    return { startIdx: s >= 0 && s <= last ? s : Math.max(0, last + 1 - RENDER_WINDOW), endIdx: last };
+  }, [items, win]);
+  const shown = useMemo(() => items.slice(startIdx, endIdx + 1), [items, startIdx, endIdx]);
+  const hiddenAbove = useMemo(() => { let n = 0; for (let i = 0; i < startIdx; i++) if (items[i].kind === "msg") n++; return n; }, [items, startIdx]);
+  const hiddenBelow = useMemo(() => { let n = 0; for (let i = endIdx + 1; i < items.length; i++) if (items[i].kind === "msg") n++; return n; }, [items, endIdx]);
+  const itemsRef = useRef(items); itemsRef.current = items;
+  const rangeRef = useRef({ startIdx, endIdx }); rangeRef.current = { startIdx, endIdx };
+  const winRef = useRef(win); winRef.current = win;
+  type Anchor = { key: string; top: number };
+  const anchorRef = useRef<(Anchor & { win: typeof win }) | null>(null);
+
+  const measure = useCallback((key?: string): Anchor | null => {
+    const el = scrollRef.current;
+    const node = key ? el?.querySelector<HTMLElement>(`[data-tkey="${CSS.escape(key)}"]`) : el?.querySelector<HTMLElement>("[data-tkey][data-msg]");
+    return node?.dataset.tkey ? { key: node.dataset.tkey, top: node.getBoundingClientRect().top } : null;
+  }, []);
+  const setRange = useCallback((s: number, e: number, anchor?: Anchor | null) => {
+    const its = itemsRef.current;
+    let a = s; while (a < its.length && its[a].kind !== "msg") a++;
+    let b = e; while (b > 0 && its[b].kind !== "msg") b--;
+    const next = { start: its[a]?.key ?? null, end: e >= its.length - 1 ? null : its[b]?.key ?? null };
+    if (winRef.current.start === next.start && winRef.current.end === next.end) return;
+    if (anchor) anchorRef.current = { ...anchor, win: next };
+    setWin(next);
+  }, []);
+  const revealEarlier = useCallback(() => {
+    const { startIdx: s, endIdx: e } = rangeRef.current;
+    if (s <= 0) return;
+    const ns = Math.max(0, s - RENDER_STEP);
+    setRange(ns, Math.min(e, ns + RENDER_MAX - 1), measure());
+  }, [measure, setRange]);
+  const revealLater = useCallback(() => {
+    const its = itemsRef.current;
+    const { startIdx: s, endIdx: e } = rangeRef.current;
+    if (e >= its.length - 1) return;
+    const ne = Math.min(its.length - 1, e + RENDER_STEP);
+    const ns = Math.max(s, ne - RENDER_MAX + 1);
+    setRange(ns, ne, ns > s ? measure(its[ns].key) : null);
+  }, [measure, setRange]);
+  const revealRef = useRef({ earlier: revealEarlier, later: revealLater });
+  revealRef.current = { earlier: revealEarlier, later: revealLater };
+
+  const onScroll = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const bottom = el.scrollHeight - el.scrollTop - el.clientHeight < 60 && winRef.current.end === null;
+    pinned.current = bottom;
+    setAtBottom(bottom);
+    if (!bottom && winRef.current.start === null) {
+      const first = itemsRef.current.slice(rangeRef.current.startIdx).find((it) => it.kind === "msg");
+      if (first) setWin((w) => ({ ...w, start: first.key }));
+    } else if (bottom && winRef.current.start !== null) {
+      setWin({ start: null, end: null });
+    }
+  }, []);
+
+  const topSentinelRef = useRef<HTMLDivElement>(null);
+  const bottomSentinelRef = useRef<HTMLDivElement>(null);
+  const hasAbove = hiddenAbove > 0;
+  const hasBelow = hiddenBelow > 0;
+  useEffect(() => {
+    const root = scrollRef.current;
+    if (!root || typeof IntersectionObserver === "undefined") return;
+    const watch = (target: HTMLElement | null, margin: string, go: () => void) => {
+      if (!target) return null;
+      const io = new IntersectionObserver((entries) => { if (!pinned.current && entries.some((e) => e.isIntersecting)) go(); }, { root, rootMargin: margin });
+      io.observe(target);
+      return io;
+    };
+    const up = hasAbove ? watch(topSentinelRef.current, "1800px 0px 0px 0px", () => revealRef.current.earlier()) : null;
+    const down = hasBelow ? watch(bottomSentinelRef.current, "0px 0px 1800px 0px", () => revealRef.current.later()) : null;
+    return () => { up?.disconnect(); down?.disconnect(); };
+  }, [hasAbove, hasBelow]);
+
+  useLayoutEffect(() => {
+    if (win.start === null || win.end !== null || endIdx - startIdx + 1 <= RENDER_MAX + 2) return;
+    const el = scrollRef.current;
+    if (!el) return;
+    if (el.scrollTop < (el.scrollHeight - el.clientHeight) / 2) setRange(startIdx, startIdx + RENDER_MAX - 1);
+    else { const ns = endIdx - RENDER_MAX + 1; setRange(ns, endIdx, measure(itemsRef.current[ns].key)); }
+  }, [win, startIdx, endIdx, setRange, measure]);
+
+  const scrollToBottom = useCallback((behavior: ScrollBehavior = "smooth") => {
+    const el = scrollRef.current;
+    if (!el) return;
+    pinned.current = true;
+    setAtBottom(true);
+    if (winRef.current.start !== null || winRef.current.end !== null) { setWin({ start: null, end: null }); return; }
+    el.scrollTo({ top: el.scrollHeight, behavior });
+  }, []);
+
+  // 在「你」的消息之间跳。
+  const scrollToUserMsg = useCallback((dir: -1 | 1) => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const base = el.getBoundingClientRect().top;
+    const tops = Array.from(el.querySelectorAll<HTMLElement>(".msg.user:not(.queued)")).map((n) => n.getBoundingClientRect().top - base + el.scrollTop);
+    const cur = el.scrollTop;
+    const candidates = dir < 0 ? tops.filter((t) => t < cur - 8) : tops.filter((t) => t > cur + 8);
+    if (!candidates.length) { if (dir < 0) revealRef.current.earlier(); else revealRef.current.later(); }
+    if (!tops.length) return;
+    const target = candidates.length ? (dir < 0 ? candidates[candidates.length - 1] : candidates[0]) : dir < 0 ? tops[0] : tops[tops.length - 1];
+    el.scrollTo({ top: Math.max(0, target - 12), behavior: "smooth" });
+  }, []);
+
+  useLayoutEffect(() => {
+    const a = anchorRef.current;
+    const el = scrollRef.current;
+    if (a && a.win === win) {
+      anchorRef.current = null;
+      const node = el?.querySelector<HTMLElement>(`[data-tkey="${CSS.escape(a.key)}"]`);
+      if (el && node) { const delta = node.getBoundingClientRect().top - a.top; if (Math.abs(delta) > 1) el.scrollTop += delta; }
+    }
+  }, [win]);
+  useLayoutEffect(() => { if (pinned.current && scrollRef.current) scrollRef.current.scrollTop = scrollRef.current.scrollHeight; }, [messages, running, startIdx, endIdx]);
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const ro = new ResizeObserver(() => { if (pinned.current) el.scrollTop = el.scrollHeight; });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  useEffect(() => {
+    pinned.current = true;
+    setAtBottom(true);
+    setWin({ start: null, end: null });
+    if (scrollRef.current) scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+  }, [key]);
+
+  const contextReset = !!lastTurn?.context_reset && conv?.turns.some((turn) => turn.context_reset);
+  const h = cfg.header;
+  const view = useMemo(() => ({ timestamps: cfg.transcript.timestamps, initialBadge: cfg.transcript.initialBadge, userLabel: cfg.labels.user, agentName: cfg.labels.agent }), [cfg]);
+  const composerOptions = useMemo<ComposerOptions>(() => ({
+    placeholderRunning: cfg.composer.placeholderRunning, hints: cfg.composer.hints, charCount: cfg.composer.charCount,
+    fileUpload: cfg.composer.fileUpload, fileButtonText: cfg.composer.fileButtonText, queue: cfg.composer.queue,
+  }), [cfg]);
+  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">
+          {(h.crumb || h.export || h.title) && <div className="sh-main">
+            {(h.crumb || h.export) && <div className="crumb">
+              {h.crumb && <>
+                <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 && 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>}
+          </div>}
+          <div className="sh-tools">
+            {h.agent && agent && <AgentBadge label={agentText} />}
+            {h.usage && (fresh > 0 || cacheRead > 0) && (
+              <span className="usage-chip" title={`新增 ${fresh.toLocaleString()} tokens${cacheRead ? `\n缓存读取 ${cacheRead.toLocaleString()}（每轮重复读取的上下文）` : ""}`}>
+                {fmtTokens(fresh)} tok
+                {cacheRead > 0 && <> <span className="usage-dot">·</span> <span className="usage-cached">{fmtTokens(cacheRead)} 缓存</span></>}
+              </span>
+            )}
+            {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>}
+              </span>
+            )}
+            {h.status && <span className={`status-ctl ${awaiting ? "awaiting" : ""}`} style={{ cursor: "default" }}>
+              <StatusDot cls={dotCls} running={running} awaiting={awaiting} title={statusText} />
+              <span className="cv">{statusText}</span>
+            </span>}
+            {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" && key && (
+          <div className="clear-confirm">
+            <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(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>}
+        {conv?.stream === "reconnecting" && <div className="sync-banner"><span className="sync-msg">实时连接中断，正在重连…{conv.streamError ? `（${conv.streamError}）` : ""}</span></div>}
+        {conv?.stream === "error" && <div className="sync-banner conflict"><span className="sync-msg">⚠ {conv.streamError}</span></div>}
+
+        <div className="transcript-wrap">
+          <div className="transcript" ref={scrollRef} onScroll={onScroll}>
+            <div className="tw">
+              {(!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(continuedFromKey)}>查看上一个对话</button>
+                </div></div>
+              )}
+              {contextReset && <div className="msg system info"><div className="msg-body">ℹ 执行节点上的会话重建过：从那一轮起是新的 Agent 会话，之前的对话上下文没有带过去（工作区文件还在）。</div></div>}
+              {loading && (
+                <div aria-hidden>
+                  <div className="session-label"><span className="ln" />正在加载会话<span className="ln" /></div>
+                  <div className="msg user" style={{ opacity: .7 }}>
+                    <div className="who"><Skel w={18} h={18} r={5} /><Skel w={34} h={9} /></div>
+                    <div className="msg-body"><Skel w="72%" h={12} /><Skel w="46%" h={12} style={{ marginTop: 9 }} /></div>
+                  </div>
+                  <div className="msg" style={{ opacity: .7 }}>
+                    <div className="who"><Skel w={18} h={18} r={5} /><Skel w={70} h={9} /></div>
+                    <Skel w="90%" h={11} /><Skel w="83%" h={11} style={{ marginTop: 8 }} /><Skel w="58%" h={11} style={{ marginTop: 8 }} />
+                  </div>
+                </div>
+              )}
+              {hasAbove && (
+                <div ref={topSentinelRef} className="load-older">
+                  <button className="btn btn-ghost btn-sm" onClick={revealEarlier}>加载更早的消息（还有 {hiddenAbove} 条）</button>
+                </div>
+              )}
+              {shown.map((it) =>
+                it.kind === "label" ? (
+                  cfg.transcript.sessionLabel ? <div key={it.key} data-tkey={it.key} className="session-label"><span className="ln" />第 {it.n} 次会话{it.current ? " · 当前" : ""}<span className="ln" /></div> : null
+                ) : it.kind === "break" ? (
+                  <div key={it.key} data-tkey={it.key}><SessionBreak summary={it.summary} /></div>
+                ) : (
+                  <div key={it.key} data-tkey={it.key} data-msg="">
+                    <MessageView m={it.m} initial={it.initial} hideWho={it.hideWho} running={running} agent={agent} agentLabel={agentText} handlers={handlers} view={view} />
+                  </div>
+                ),
+              )}
+              {hasBelow && (
+                <div ref={bottomSentinelRef} className="load-older">
+                  <button className="btn btn-ghost btn-sm" onClick={revealLater}>显示后面的消息（还有 {hiddenBelow} 条）</button>
+                  <button className="btn btn-ghost btn-sm" onClick={() => scrollToBottom("auto")}>跳到最新</button>
+                </div>
+              )}
+              {cfg.transcript.runningIndicator && running && !awaitingAnswer && !hasBelow && <RunningIndicator agent={agent} agentName={cfg.labels.agent} startedAt={turnStartedAt} lastActivityRef={lastActivityRef} />}
+              {!hasBelow && queued.map((m) => <MessageView key={m.id} m={m} initial={false} hideWho={false} handlers={handlers} view={view} />)}
+              {ended && (
+                <div className="session-label"><span className="ln" />{REASON_TEXT[closedReason ?? ""] ?? "对话已结束"}{!finalEnd ? " · 再发消息会开一个新对话接着聊" : ""}<span className="ln" /></div>
+              )}
+              {continuedBy && (
+                <div className="load-older"><button className="btn btn-line btn-sm" onClick={() => go(continuedBy)}>转到接续的新对话</button></div>
+              )}
+            </div>
+          </div>
+          {cfg.transcript.nav && <div className="msg-nav">
+            <button className="msg-nav-btn" onClick={() => scrollToUserMsg(-1)} title="上一条消息" aria-label="滚动到上一条消息">{Icon.chevUp()}</button>
+            <button className="msg-nav-btn" onClick={() => scrollToUserMsg(1)} title="下一条消息" aria-label="滚动到下一条消息">{Icon.chevDown()}</button>
+            {!atBottom && <button className="msg-nav-btn" onClick={() => scrollToBottom()} title="跳到最新" aria-label="跳到最新">{Icon.toBottom()}</button>}
+          </div>}
+        </div>
+        {!readOnly && (
+          <Composer
+            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 && 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>
+  );
+}