@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/core/store.ts

@@ -0,0 +1,1103 @@
+/**
+ * 组件共享的状态仓库（纯 TS，无 React）。积木之间靠它拼起来：
+ *
+ *   · 选中哪个对话（cli-msglist 点一下，cli-chat 跟着切）；
+ *   · 列表里有哪些对话任务（宿主给 jobIds，或本地记住 + 从 center 发现）；
+ *   · 每个对话的实时状态：一个对话只开一条实时流，几个组件同时看也只连一次（引用计数）。
+ *
+ * 「一个对话」用对话键标识（见 conversation.ts convKey）：一个对话任务里可以有几个对话，"job_x#task_y" 是其中一个，
+ * 只有 "job_x" 是它的第一个（和以前一样）；"job_x#new" 是在这个对话任务里新开一个对话。jobs / jobIds 仍按对话任务。
+ *
+ * 单独用某个组件时它会自己建一个仓库；放进同一个 <CliCenterProvider>（或同一个 group 的 Web Component）就共享一个。
+ */
+import { clientId } from "./id";
+import { connectionDraftScope } from "./identity";
+import { notifyCallback } from "./callbacks";
+import { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client";
+import { addTurnsIfAbsent, applyItems, applyOlderPage, applySnapshot, closedCallback, convEnded, convKey, emptyConv, isChatTask, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation";
+import { formatAnswersText } from "../ui/format";
+import { backgroundBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "./blocks";
+import { cloneBoardView, reportBoardOwner, activateBoardOwner, selectedBoardOwner, mergeBoardHistory, rememberBoardFile } from "../board/context";
+import { cloneWorkspaceChange, subscribeWorkspaceFiles, retryWorkspaceFiles, type WorkspaceWatchOptions } from "../board/fileWatch";
+import { retainFileScope } from "../board/fileScope";
+import type { WorkspaceChangeEvent, WorkspaceWatchStatus } from "./types";
+import { createWorkspace, type BoardView, type CliWorkspace } from "../board/workspace";
+import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types";
+
+export interface JobEntry {
+  job: CenterJob | null;
+  /** 第 1 轮的消息（列表卡片的描述）。 */
+  firstInput: string | null;
+  loading: boolean;
+  error: string | null;
+  fetchedAt: number;
+}
+
+export interface CliState {
+  /** 选中的对话（对话键）。 */
+  selected: string | null;
+  /** 列表里的对话任务（job_id）。 */
+  jobIds: string[];
+  /** 按 job_id。 */
+  jobs: Record<string, JobEntry>;
+  /** 按对话键。 */
+  convs: Record<string, ConvState>;
+  listLoading: boolean;
+  listError: string | null;
+  /** 看板里引用到对话的东西（按对话键），下一条消息发出时一起带上（见 BoardRef）。 */
+  refs: Record<string, BoardRef[]>;
+  /**
+   * 看板上正在看的东西（按对话键，现在是打开着的文件）：缺省跟着下一条消息带上一次，对话输入框上方显示成虚线卡片；
+   * off = 这一个已经带过 / 用户点了不带。换了看的东西重新算。
+   */
+  viewing: Record<string, { ref: BoardRef; off: boolean }>;
+  /** 看板现在的样子（按对话键）：正在看的文件、开着的文件页签、当前页签。没有看板时没有。 */
+  boards: Record<string, BoardView>;
+  /** 当前对话是否有展开且可见的外置看板；Chat 内嵌看板不计入。 */
+  externalBoards: Record<string, boolean>;
+  /** 同一工作区中是否有展开且可见的对话列表。 */
+  listVisible: boolean;
+  /** 外置看板的模块和只读限制，内嵌视图沿用同一约束。 */
+  externalBoardOptions: Record<string, { availableTabs: ("files" | "changes" | "browser")[]; readOnly: boolean }>;
+  /** 最近看板背景，收起/卸载后保留，供下一条消息被动参考。 */
+  boardContext: Record<string, BoardView>;
+  /** 业务方补充的项目背景（按对话键；"" = 还没建的新对话），随下一条消息发出（见 appendContext）。 */
+  context: Record<string, ContextItem[]>;
+}
+
+/** 一条补充背景。 */
+export interface ContextItem {
+  /** 同一个 id 再追加会替换。 */
+  id: string;
+  /** 标题（输入框上方的小卡片、发给智能体的块里都显示）。 */
+  title?: string;
+  text: string;
+}
+/** 一条补充背景最长多少字（和创建任务时 workspace.context 的上限一致）。 */
+export const CONTEXT_ITEM_MAX = 20_000;
+
+/**
+ * 从看板引用到对话的一样东西：一个文件、浏览器当前页面、一处改动，或宿主自己加的页签里的内容（终端输出……）。
+ * 对话组件把它们显示在输入框上方；下一条消息发出时合成一个「看板上下文」块带给智能体
+ * （转录里显示成一张可展开的卡片，不占对话篇幅），发完清空。
+ */
+export interface BoardRef {
+  /** 同一个 id 再引用一次会替换（例如浏览器换了页面）。 */
+  id: string;
+  /** file / browser / changes，或宿主自定义的种类（terminal …）。 */
+  kind: string;
+  /** 输入框上方小卡片里显示的名字。 */
+  label: string;
+  /** 带给智能体的那一行（说清是什么、在哪）。 */
+  text: string;
+}
+
+/** 与 center 回调同名同义的事件，方便宿主把前端事件和后端回调对上。 */
+export type CliEvent =
+  /** jobId 是选中的对话键（只有 job_id，或 "job_id#task_id"）。 */
+  | { type: "select"; jobId: string | null }
+  /** 一轮结束。payload 与 center 回调 conversation_turn 的请求体同名同义。key 是这个对话的对话键。 */
+  | { type: "conversation_turn"; jobId: string; key: string; turn: CenterTurn; payload: ConversationTurnCallback }
+  /** 对话结束（整个对话任务结束，或只关掉了这一个对话）。payload 与 center 回调 conversation_closed 的请求体同名同义。 */
+  | { type: "conversation_closed"; jobId: string; key: string; reason: string | null; continuedBy: string | null; payload: ConversationClosedCallback }
+  /**
+   * 新建了对话（新对话任务，或在对话任务里新开的对话），或旧对话结束后消息开了新对话（job_id 变了）。
+   * taskId / key：新的那个对话；previousKey：之前的对话键（新建时是 null 或 "job#new"）。
+   */
+  | { type: "job_change"; jobId: string; previousJobId: string | null; taskId: string | null; key: string; previousKey: string | null }
+  | { type: "error"; jobId: string | null; error: CenterError }
+  /**
+   * 有人要在看板里打开东西（对话里点了本地文件链接、「查看浏览器」，或宿主调了 store.openInBoard）。
+   * handled = 有看板接住了；没有时对话组件自己弹窗打开。宿主可以据此展开右侧面板。
+   */
+  | { type: "open"; jobId: string; target: OpenTarget; handled: boolean }
+  /** 看板里引用 / 取消引用了东西（refs 是这个对话现在的全部引用），宿主可以据此做自己的提示。 */
+  | { type: "board_ref"; key: string; refs: BoardRef[] }
+  /** 看板上切了页签、打开 / 关掉了文件（view 为 null = 看板关了）。 */
+  | { type: "board_change"; key: string; view: BoardView | null }
+  | { type: "board_context"; jobId: string; view: BoardView }
+  | WorkspaceChangeEvent
+  | WorkspaceWatchStatus
+  /**
+   * 补充背景变了：追加 / 去掉（pending 是还没发出的），或随消息发出了（sent 是这次发出的）。
+   * key 是对话键；新对话还没建时是 ""。
+   */
+  | { type: "context"; key: string; pending: ContextItem[]; sent?: ContextItem[] };
+
+/** Public workspace metadata must not be shared between business listeners. */
+export function cloneWorkspaceEvent(event:CliEvent):CliEvent {
+  if(event.type==='files_changed')return cloneWorkspaceChange(event);
+  if(event.type==='files_watch')return {...event};
+  if(event.type==='board_ref')return {...event,refs:event.refs.map(ref=>({...ref}))};
+  if(event.type==='context')return {...event,pending:event.pending.map(item=>({...item})),...(event.sent?{sent:event.sent.map(item=>({...item}))}:{})};
+  if(event.type==='open')return {...event,target:{...event.target}};
+  if(event.type==='board_context')return {...event,view:cloneBoardView(event.view)};
+  if(event.type==='board_change')return {...event,view:event.view?cloneBoardView(event.view):null};
+  return event;
+}
+
+/** 看板要打开的东西。 */
+export type OpenTarget = { kind: "file"; path: string } | { kind: "browser" } | { kind: "changes" } | { kind: "files"; path?: string }
+  /** 宿主用 extraTabs 加的页签。 */
+  | { kind: "tab"; id: string };
+/** 看板登记的接收函数：接得住（显示的是这个对话）就返回 true。 */
+export type BoardSurface = (jobId: string, target: OpenTarget) => boolean;
+
+export interface CliStoreOptions extends CenterClientOptions {
+  client?: CenterClient;
+  /** 命名空间（不同业务 / 产品线请区分；Web Component 没写 group 时用它区分仓库）。列表不会按它在本机记住任何对话。 */
+  namespace?: string | null;
+  /**
+   * 新建对话时的参数（与 POST /api/jobs 对应）：标题、业务 ID、工作区、回调、智能体、超时、浏览器模式。
+   * 带了 callback，center 每轮结束就向 callback.url 投递 conversation_turn，结束时投递 conversation_closed。
+   */
+  newConversation?: NewConversationOptions;
+  /** 自己建对话（例如经业务后端建，以便把回调密钥留在服务端）：返回 center 的 job_id。 */
+  createConversation?: (firstMessage: string, options?: NewConversationOptions) => Promise<string>;
+  /**
+   * 每条消息的 business_id（center 按它去重，回调里原样带回）。缺省 `cli-<uuid>`。
+   * kind = "create" 是第一条（新建对话），"message" 是之后的每条。
+   */
+  businessIdFor?: (text: string, kind: "create" | "message") => string;
+}
+
+/** 发一条消息时可以单独指定的新建参数（组件自己的 props），优先于仓库的。 */
+export interface SendOptions {
+  expectedExecutionRevision?: number;
+  executionConfig?: import("./execution").ExecutionOptions;
+  /** 新建对话后是否改仓库的选中（缺省改）。 */
+  select?: boolean;
+  newConversation?: NewConversationOptions;
+  createConversation?: (firstMessage: string, options?: NewConversationOptions) => Promise<string>;
+  businessIdFor?: (text: string, kind: "create" | "message") => string;
+}
+
+/**
+ * 断线后自动重连的退避（约 2 分钟内重试 7 次）。用完就停下（stream: "offline"），不再定时重试：
+ * 网络恢复、页面回到前台、窗口重新获得焦点、这个对话发出消息或调用 store.reconnect() 时再连。
+ */
+const RECONNECT_MS = [1_000, 2_000, 5_000, 10_000, 20_000, 30_000, 60_000];
+/**
+ * 断线后先悄悄重连，这么久之内重新连上（收到快照）就不提示，stream 保持原样（live / connecting）；
+ * 超过仍没连上才变成 "reconnecting"，界面显示「正在重连」。网关回收长连接、网络抖动、电脑休眠唤醒、
+ * 中枢重启时的一次断线大多几秒内就接上，期间漏掉的事件由重连后的快照补齐，不必打扰用户。
+ */
+export const RECONNECT_NOTICE_MS = 15_000;
+/**
+ * 退避时间上下浮动 ±30%：中枢重启时所有页面同时断开，不错开的话会在同一秒一起重连、一起拉快照，
+ * 人多时把刚起来的中枢再压垮一次。
+ */
+export const jitter = (ms: number) => Math.round(ms * (0.7 + Math.random() * 0.6));
+/**
+ * 标签页在后台超过这么久：先断开实时流（中枢那头每条流都在轮询数据库、连着执行节点），切回来时重连并拉一次快照补齐。
+ * 很多人开着页面不看时，中枢和节点不用一直为他们推数据。
+ */
+export const PARK_HIDDEN_MS = 5 * 60_000;
+/**
+ * 401 / 403：多半是宿主的登录会话过期了。隔 30 秒再试，最多 AUTH_RETRIES 次；之后停下等事件
+ * （宿主续上会话后切回页面、获得焦点或调用 store.reconnect() 即恢复），不无限重试。
+ */
+const AUTH_RETRY_MS = 30_000;
+const AUTH_RETRIES = 3;
+
+// 全局只挂一份「网络恢复 / 切回页面」监听，转给当前有实时流的仓库。
+const reconnectors = new Set<() => void>();
+const parkers = new Set<() => void>();
+let listening = false;
+let parkTimer: ReturnType<typeof setTimeout> | null = null;
+const fireReconnect = () => { for (const fn of [...reconnectors]) fn(); };
+const onVisible = () => {
+  if (document.visibilityState === "visible") {
+    if (parkTimer) { clearTimeout(parkTimer); parkTimer = null; }
+    fireReconnect();
+    return;
+  }
+  parkTimer ??= setTimeout(() => { parkTimer = null; if (document.visibilityState === "hidden") for (const fn of [...parkers]) fn(); }, PARK_HIDDEN_MS);
+};
+function watchReconnect(fn: () => void, park: () => void) {
+  reconnectors.add(fn);
+  parkers.add(park);
+  if (listening || typeof window === "undefined") return;
+  listening = true;
+  window.addEventListener("online", fireReconnect);
+  window.addEventListener("focus", fireReconnect);
+  document.addEventListener("visibilitychange", onVisible);
+}
+function unwatchReconnect(fn: () => void, park: () => void) {
+  reconnectors.delete(fn);
+  parkers.delete(park);
+  if (!listening || reconnectors.size) return;
+  listening = false;
+  window.removeEventListener("online", fireReconnect);
+  window.removeEventListener("focus", fireReconnect);
+  document.removeEventListener("visibilitychange", onVisible);
+}
+/** 测试用：当前登记着的仓库数。 */
+export const liveReconnectors = () => reconnectors.size;
+const JOB_REFRESH_GAP_MS = 1_500;
+/**
+ * 列表在后台刷新 / 发现对话时同时最多发几个请求。HTTP/1.1 下浏览器对一个域名只有 6 个连接，
+ * 对话实时流、看板的浏览器画面又各占着长连接；列表少占一些，点开文件、发消息这类用户在等的请求才不用排队。
+ */
+const LIST_CONCURRENCY = 2;
+
+export function createCliStore(options: CliStoreOptions = {}) {
+  const client = options.client ?? createCenterClient(options);
+  // 只有明确给了 namespace 才在本机记住对话列表：不给就不落任何共享状态，几个独立的组件互不影响。
+  // 列表只放宿主给的 jobIds 和本页里新建 / 接续出来的对话：不从 center 发现，也不从本地存储恢复——
+  // 不传就不加载，免得把这个产品线令牌下别的业务、别的用户的对话列出来。
+
+  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, externalBoards: {}, listVisible: false, externalBoardOptions: {}, boardContext: {}, context: {} };
+  const listeners = new Set<() => void>();
+  const eventListeners = new Set<(event: CliEvent) => void>();
+  const settledTurns = new Set<string>();
+  const watchedTurns = new Set<string>();
+  const closedJobs = new Set<string>();
+  const seenOpen = new Set<string>();
+  let hostIds = false;
+
+  const set = (next: Partial<CliState>) => {
+    state = { ...state, ...next };
+    for (const fn of [...listeners]) notifyCallback(fn, undefined);
+  };
+  // Business callbacks may synchronously navigate or register more listeners.
+  // Preserve emission order and keep a fixed audience for each notification.
+  const eventQueue:Array<{event:CliEvent;listeners:Array<(event:CliEvent)=>void>}>=[];
+  let dispatching=false;
+  const emit = (event:CliEvent) => {
+    eventQueue.push({event,listeners:[...eventListeners]});if(dispatching)return;
+    dispatching=true;
+    try{while(eventQueue.length){const next=eventQueue.shift()!;for(const fn of next.listeners)notifyCallback(fn,cloneWorkspaceEvent(next.event));}}
+    finally{dispatching=false;}
+  };
+  const patchConv = (key: string, fn: (conv: ConvState) => ConvState) => {
+    const prev = state.convs[key] ?? emptyConv(key);
+    const next = fn(prev);
+    if (next !== prev) {
+      noticeTransitions(key, prev, next);
+      set({ convs: { ...state.convs, [key]: next } });
+    }
+  };
+  const patchJob = (jobId: string, patch: Partial<JobEntry>) => {
+    const prev = state.jobs[jobId] ?? { job: null, firstInput: null, loading: false, error: null, fetchedAt: 0 };
+    set({ jobs: { ...state.jobs, [jobId]: { ...prev, ...patch } } });
+  };
+
+  // 一轮从未结束变成结束 → conversation_turn；对话变成结束 → conversation_closed。
+  function noticeTransitions(key: string, prev: ConvState, next: ConvState) {
+    const { jobId } = next;
+    if (prev.turns !== next.turns) {
+      const before = new Map(prev.turns.map((turn) => [turn.turn_id, turn.status]));
+      // 有轮次开始执行 / 新排队：列表卡片的「运行中」「排队中」也要跟上，不等下一次轮询。
+      if (next.turns.some((turn) => before.get(turn.turn_id) !== turn.status && !TERMINAL_TURN.has(turn.status))) void refreshJob(jobId);
+      // 本页看着还没结束过的轮次才发结果（打开页面时就已结束的历史轮次不发）。
+      for (const turn of next.turns) if (!TERMINAL_TURN.has(turn.status)) watchedTurns.add(turn.turn_id);
+      // 按 seq 顺序发，与 center 投递 callback 的顺序一致：前面还有没结束的轮次，后面结束了的先等着
+      // （例如第 2 条排队消息被撤回时第 1 轮还在跑，要等第 1 轮结束后先发 1、再发 2）。
+      for (const turn of next.turns) {
+        if (!TERMINAL_TURN.has(turn.status)) break;
+        if (settledTurns.has(turn.turn_id)) continue;
+        settledTurns.add(turn.turn_id);
+        // 被合并进别的轮次的消息不单独发（center 也不单独投递），结果在那一轮的 messages 里。
+        if (!watchedTurns.has(turn.turn_id) || turn.status === "merged") continue;
+        const continuedFrom = state.jobs[jobId]?.job?.conversation?.continued_from_job_id ?? null;
+        emit({ type: "conversation_turn", jobId, key, turn, payload: turnCallback(next, turn, continuedFrom) });
+        void refreshJob(jobId, true);
+      }
+    }
+    // 对话结束（整个对话任务结束，或只关掉了这一个对话）：只对本页看着还开着的对话发（打开时就已结束的不算）；
+    // 而且要等所有轮次都收尾之后再发，保证 conversation_closed 排在这个对话最后一个 conversation_turn 之后（与 center 的 callback_seq 一致）。
+    if (next.job && !convEnded(next)) seenOpen.add(key);
+    // 一次性任务（只读查看）没有对话的结果通知。
+    if (next.job && convEnded(next) && seenOpen.has(key) && !closedJobs.has(key) && !next.batch) {
+      const settled = next.turns.every((turn) => TERMINAL_TURN.has(turn.status));
+      if (settled || next.stream === "ended") {
+        closedJobs.add(key);
+        const payload = closedCallback(next);
+        emit({ type: "conversation_closed", jobId, key, reason: payload.closed_reason, continuedBy: next.continuedBy, payload });
+      }
+    }
+    // 一次性任务里看着的子任务换了状态（开跑、结束）：列表里那一行马上跟上，不等列表的定时刷新。
+    if (next.batchTask && (prev.batchTask?.id !== next.batchTask.id || prev.batchTask?.status !== next.batchTask.status)) void refreshJob(jobId);
+    // 实时流里的对话状态同步给列表。
+    if (next.job && prev.job?.status !== next.job.status) {
+      const entry = state.jobs[jobId];
+      if (entry?.job) patchJob(jobId, { job: { ...entry.job, status: next.job.status } });
+    }
+  }
+
+  // ── 列表 ─────────────────────────────────────────────
+
+  function setJobIds(ids: string[]) {
+    hostIds = true;
+    const unique = [...new Set(ids.filter(Boolean))];
+    if (unique.join() === state.jobIds.join()) return;
+    set({ jobIds: unique });
+  }
+
+  function addJob(jobId: string) {
+    if (state.jobIds[0] === jobId) return;
+    const ids = [jobId, ...state.jobIds.filter((id) => id !== jobId)];
+    set({ jobIds: ids });
+  }
+
+  function removeJob(jobId: string) {
+    const ids = state.jobIds.filter((id) => id !== jobId);
+    set({ jobIds: ids, selected: state.selected && parseConvKey(state.selected).jobId === jobId ? null : state.selected });
+  }
+
+  /** 对话接续：旧 job 换成新 job（列表位置不变，选中跟过去）。oldId / newId 可以是对话键。 */
+  function replaceJob(oldId: string, newId: string) {
+    if (oldId === newId) return;
+    const from = parseConvKey(oldId);
+    const to = parseConvKey(newId);
+    const ids = from.jobId === to.jobId ? state.jobIds
+      : state.jobIds.includes(from.jobId) ? state.jobIds.map((id) => (id === from.jobId ? to.jobId : id)) : [to.jobId, ...state.jobIds];
+    set({ jobIds: [...new Set(ids)], selected: state.selected === oldId ? newId : state.selected });
+    emit({ type: "job_change", jobId: to.jobId, previousJobId: from.jobId, taskId: to.taskId, key: newId, previousKey: oldId });
+    void refreshJob(to.jobId, true);
+  }
+
+  const refreshAgain = new Set<string>();
+  async function refreshJob(jobId: string, force = false) {
+    const entry = state.jobs[jobId];
+    // 正在拉：拉完再补一次，免得错过这期间的变化（例如轮次刚从排队变成执行中）。
+    if (entry?.loading) { refreshAgain.add(jobId); return; }
+    if (!force && entry && Date.now() - entry.fetchedAt < JOB_REFRESH_GAP_MS) return;
+    patchJob(jobId, { loading: true });
+    try {
+      const job = await client.getJob(jobId);
+      let firstInput = state.jobs[jobId]?.firstInput ?? null;
+      if (firstInput === null && job.mode === "conversation") {
+        // 卡片描述取第一个对话的第一条消息（按 seq 最早的那一轮）。
+        const first = await client.listTurns(jobId, { limit: 1 }).catch(() => null);
+        firstInput = first?.turns[0]?.input ?? "";
+      }
+      patchJob(jobId, { job, firstInput, loading: false, error: null, fetchedAt: Date.now() });
+      // 新数据里已包含实时用量，清零累计（这个对话任务里的每个对话）。
+      for (const conv of Object.values(state.convs)) if (conv.jobId === jobId) patchConv(conv.key, (c) => ({ ...c, liveUsage: { fresh: 0, cacheRead: 0 } }));
+    } catch (error) {
+      patchJob(jobId, { loading: false, error: error instanceof Error ? error.message : String(error), fetchedAt: Date.now() });
+      // 本地记住的对话在 center 已经不存在（被删、换了环境）：从列表里拿掉。宿主给的 jobIds 不动，由宿主决定。
+      if (!hostIds && error instanceof CenterError && error.status === 404 && (!state.selected || parseConvKey(state.selected).jobId !== jobId)) {
+        refreshAgain.delete(jobId);
+        removeJob(jobId);
+        return;
+      }
+    }
+    if (refreshAgain.delete(jobId)) void refreshJob(jobId, true);
+  }
+
+  /**
+   * 刷新列表。缺省只刷还没结束的对话（结束了的不会再变，轮询不必每次都拉）；all = true 全部重拉（首次加载、手动刷新）。
+   */
+  async function refreshAll(opts: { all?: boolean } = {}) {
+    set({ listLoading: true, listError: null });
+    try {
+      const ids = opts.all ? state.jobIds : state.jobIds.filter((id) => {
+        const status = state.jobs[id]?.job?.status;
+        return !status || !TERMINAL_JOB.has(status);
+      });
+      await runLimited(ids, LIST_CONCURRENCY, (id) => refreshJob(id, true));
+      set({ listLoading: false });
+    } catch (error) {
+      set({ listLoading: false, listError: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  // ── 实时流（引用计数 + 断线重连） ─────────────────────
+
+  // synced：这个流已经收到过快照；之后的快照是断线重连后的补齐。
+  type StreamEntry = {
+    refs: number; stop: (() => void) | null; timer: ReturnType<typeof setTimeout> | null; attempt: number; parked?: boolean; synced?: boolean;
+    /** 这次断线从什么时候开始（还没恢复）；恢复 = 新连接收到快照或数据。 */
+    droppedAt?: number;
+    /** 到 RECONNECT_NOTICE_MS 还没恢复时把状态改成 reconnecting 的定时器。 */
+    notice?: ReturnType<typeof setTimeout> | null;
+    lastError?: string | null;
+  };
+  const streams = new Map<string, StreamEntry>();
+  const clearNotice = (entry: StreamEntry) => { if (entry.notice) { clearTimeout(entry.notice); entry.notice = null; } };
+  /** 不再算「断线中」：恢复了，或者转成了别的明确状态（停下、结束、出错、页面停放）。 */
+  const settleDrop = (entry: StreamEntry) => { clearNotice(entry); entry.droppedAt = undefined; entry.lastError = null; };
+
+  function connect(key: string) {
+    const entry = streams.get(key);
+    if (!entry || entry.refs <= 0) return;
+    const previous = entry.stop;
+    entry.stop = null;
+    previous?.();
+    if (streams.get(key) !== entry || entry.refs <= 0) return;
+    const { jobId, taskId } = parseConvKey(key);
+    let ended = false, retired = false, snapshotReceived = false;
+    let endReason: string | null = null;
+    let cleanup: (() => void) | null = null;
+    const owns = () => streams.get(key) === entry && entry.refs > 0 && entry.stop === retire;
+    const active = () => !retired && owns();
+    const refreshFiles = () => { if (active() && client.board) retryWorkspaceFiles(client.board, key); };
+    const retire = () => {
+      if (retired) return;
+      retired = true;
+      if (entry.stop === retire) entry.stop = null;
+      const dispose = cleanup; cleanup = null;
+      notifyCallback(dispose ?? undefined, undefined);
+    };
+    // 新连接真正送来了数据：断线算恢复，退避次数重新计。只连上响应头就又断的不算，
+    // 否则「连上即断」会把重试次数一直清零、变成无限重连。
+    const recovered = () => { entry.attempt = 0; settleDrop(entry); };
+    // 断线：先悄悄重连；到 RECONNECT_NOTICE_MS 还没恢复才显示「正在重连」（见 RECONNECT_NOTICE_MS）。
+    const noteDrop = (current: StreamEntry, error: CenterError | null) => {
+      current.lastError = error?.message ?? null;
+      current.droppedAt ??= Date.now();
+      const show = () => patchConv(key, (conv) => ({ ...conv, stream: "reconnecting", streamError: current.lastError ?? null }));
+      const waited = Date.now() - current.droppedAt;
+      if (waited >= RECONNECT_NOTICE_MS) { clearNotice(current); show(); return; }
+      if (current.notice) return;
+      current.notice = setTimeout(() => {
+        current.notice = null;
+        if (streams.get(key) !== current || current.refs <= 0 || current.parked || current.droppedAt === undefined) return;
+        show();
+      }, RECONNECT_NOTICE_MS - waited);
+    };
+    // 重试用完：停下等事件（见 RECONNECT_MS），对话照常可以看、可以发消息。
+    const goOffline = (current: NonNullable<ReturnType<typeof streams.get>>, error: CenterError | null) => {
+      settleDrop(current);
+      current.parked = true;
+      patchConv(key, (conv) => ({ ...conv, stream: "offline", streamError: error?.message ?? null }));
+      emit({ type: "error", jobId: key, error: error ?? new CenterError("实时连接已中断", "NETWORK", 0) });
+    };
+    const close = (error: CenterError | null) => {
+      if (!active()) return;
+      retire();
+      const current = streams.get(key);
+      if (current !== entry || current.refs <= 0 || current.stop) return;
+        // 对话结束（end）不再连；中枢停机（server_shutdown）按断线处理，稍后重连。
+        if (ended && endReason !== "server_shutdown") return;
+        // 404：对话不存在，重连也没用。
+        if (error && error.status === 404) {
+          settleDrop(current);
+          patchConv(key, (conv) => ({ ...conv, stream: "error", streamError: error.message }));
+          emit({ type: "error", jobId: key, error });
+          return;
+        }
+        // 401 / 403：多半是宿主的登录会话过期。报出来（宿主可以据此续会话），之后隔 30 秒再试几次，会话续上了自己恢复。
+        if (error && (error.status === 401 || error.status === 403)) {
+          settleDrop(current);
+          if (current.attempt === 0) emit({ type: "error", jobId: key, error });
+          if (current.attempt >= AUTH_RETRIES) { goOffline(current, error); return; }
+          patchConv(key, (conv) => ({ ...conv, stream: "error", streamError: error.message }));
+          current.attempt += 1;
+          current.timer = setTimeout(() => { current.timer = null; connect(key); }, jitter(AUTH_RETRY_MS));
+          return;
+        }
+        if (current.attempt >= RECONNECT_MS.length) { goOffline(current, error); return; }
+        const delay = RECONNECT_MS[current.attempt];
+        current.attempt += 1;
+        noteDrop(current, error);
+        current.timer = setTimeout(() => { current.timer = null; connect(key); }, jitter(delay));
+    };
+    entry.stop = retire;
+    // 断线后的重连尝试不改状态（悄悄进行，或已经在显示「正在重连」）；只有首次连接显示 connecting。
+    if (entry.droppedAt === undefined) patchConv(key, (conv) => ({ ...conv, stream: "connecting", streamError: null }));
+    if (!active()) return;
+    try {
+      cleanup = client.stream(jobId, {
+        onOpen: () => { if (!active()) return; clearNotice(entry); patchConv(key, (conv) => ({ ...conv, stream: "live", streamError: null })); },
+        onSnapshot: (snapshot) => {
+          if (!active()) return;
+          // 重连后的快照：断线期间可能有轮次结束，算一次收尾（首次连上不算，看板挂上时自己会读）。
+          const catchUp = !snapshotReceived && !!entry.synced;
+          entry.synced = true;
+          recovered();
+          patchConv(key, (conv) => { const next = applySnapshot(conv, snapshot); return catchUp ? { ...next, settled: next.settled + 1 } : next; });
+          // Each connection catches up once, including rounds completed while disconnected.
+          if (!snapshotReceived) { snapshotReceived = true; refreshFiles(); }
+        },
+        onChunk: (items) => {
+          if (!active()) return;
+          recovered();
+          let refresh = false;
+          patchConv(key, (conv) => {
+            let next = conv;
+            let settled = false;
+            for (const item of items) {
+              const previous = next;
+              next = applyItems(next, [item]);
+              // applyItems also rejects events from another batch task's node session.
+              if (next === previous) continue;
+              // Observe every event: end + next user in one chunk can leave running=true.
+              if (item.type === "node" && item.event.type === "turn_end" || item.type === "transcript") refresh = true;
+              // 有轮次的对话以中枢把这一轮标成结束为准（节点已停、轮末保存已做）；没有轮次的看节点 turn_end。
+              if (item.type === "node" && item.event.type === "turn_end" && !next.turns.length) settled = true;
+              if (item.type === "turn" && item.turn.status !== "merged" && TERMINAL_TURN.has(item.turn.status)
+                && !TERMINAL_TURN.has(previous.turns.find((turn) => turn.turn_id === item.turn.turn_id)?.status ?? "")) { refresh = true; settled = true; }
+            }
+            return settled ? { ...next, settled: next.settled + 1 } : next;
+          });
+          if (refresh) refreshFiles();
+        },
+        onEnd: (end) => {
+          if (!active() || ended) return;
+          ended = true;
+          endReason = end.reason;
+          // 中枢停机：连接随后会断，按断线悄悄重连，不显示成「已结束」。
+          if (end.reason === "server_shutdown") return;
+          settleDrop(entry);
+          const continuedBy = taskId ? (end.continued_by_job_id && end.continued_by_task_id ? convKey(end.continued_by_job_id, end.continued_by_task_id) : null) : end.continued_by_job_id ?? null;
+          patchConv(key, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy, nodeRunning: false, settled: conv.settled + 1 }));
+          refreshFiles();
+          void refreshJob(jobId, true);
+        },
+        onClose: close,
+      }, undefined, taskId);
+      // Some custom transports close synchronously before returning cleanup.
+      if (retired || !owns()) {
+        const dispose = cleanup; cleanup = null;
+        notifyCallback(dispose ?? undefined, undefined);
+      }
+    } catch (error) {
+      close(error instanceof CenterError ? error : new CenterError(String(error), "NETWORK", 0));
+    }
+  }
+
+  // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
+  // 只在有实时流时登记到全局（见 watchReconnect）：组件卸载、流都关了就撤掉，宿主单页应用里反复挂载组件不会越积越多。
+  function reconnectNow() {
+    for (const [jobId, entry] of streams) {
+      if (entry.parked && entry.refs > 0) { entry.parked = false; entry.attempt = 0; settleDrop(entry); connect(jobId); continue; }
+      if (!entry.timer) continue;
+      clearTimeout(entry.timer);
+      entry.timer = null;
+      entry.attempt = 0;
+      connect(jobId);
+    }
+  }
+  /** 手动重连：给了对话键只连这一个，否则所有停下的 / 正在退避等待的都立刻再连（重试次数重新计）。 */
+  function reconnect(key?: string) {
+    if (!key) { reconnectNow(); return; }
+    const entry = streams.get(key);
+    if (!entry || entry.refs <= 0 || (!entry.parked && !entry.timer)) return;
+    if (entry.timer) { clearTimeout(entry.timer); entry.timer = null; }
+    entry.parked = false; entry.attempt = 0;
+    connect(key);
+  }
+  // 页面在后台太久：停掉实时流（主动停止不算断线，不会触发重连），切回来由 reconnectNow 接上。
+  function parkAll() {
+    for (const entry of streams.values()) {
+      // 只停连着的和正在等重连的；对话已结束、不再连的不动。
+      if (entry.refs <= 0 || (!entry.stop && !entry.timer)) continue;
+      if (entry.timer) { clearTimeout(entry.timer); entry.timer = null; }
+      settleDrop(entry);
+      entry.stop?.();
+      entry.stop = null;
+      entry.parked = true;
+    }
+  }
+  const syncLive = () => { if (streams.size) watchReconnect(reconnectNow, parkAll); else unwatchReconnect(reconnectNow, parkAll); };
+
+  /**
+   * 开始看一个对话（对话键；返回停止函数）。同一对话多处同时看只连一次。
+   * "job#new"（还没开出来的对话）没有实时流，只拉对话任务的信息。
+   */
+  function open(key: string): () => void {
+    const { jobId, taskId } = parseConvKey(key);
+    if (taskId === NEW_TASK) {
+      void refreshJob(jobId);
+      return () => undefined;
+    }
+    let entry = streams.get(key);
+    if (!entry) {
+      entry = { refs: 0, stop: null, timer: null, attempt: 0 };
+      streams.set(key, entry);
+      syncLive();
+    }
+    entry.refs += 1;
+    if (entry.refs === 1) {
+      void refreshJob(jobId);
+      connect(key);
+    }
+    const owned = entry;
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      const current = streams.get(key);
+      if (current !== owned) return;
+      current.refs -= 1;
+      if (current.refs > 0) return;
+      // Retire the registry before calling host cleanup: it may synchronously
+      // acquire a new lease for the same task.
+      streams.delete(key);
+      if (current.timer) { clearTimeout(current.timer); current.timer = null; }
+      settleDrop(current);
+      syncLive();
+      current.stop?.();
+      if (!streams.has(key)) patchConv(key, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
+    };
+  }
+
+  // ── 发消息 / 新建 / 撤回 / 结束 ───────────────────────
+
+  /**
+   * 发一条消息。key 是对话键：null 时新建对话任务（这条就是第一轮）；"job#new" 时在这个对话任务里新开一个对话。
+   * 返回实际接收消息的对话键。带 business_id 发：网络抖动时重发一次也只会跑一轮。
+   */
+  // 同一个对话的消息严格按发出的顺序送到 center（输入框、提问卡片、重试可能同时发）：
+  // center 按到达顺序给轮次编号，并发发出去可能后发先到。每个对话一条队列，前一条失败不挡后面的。
+  const sendQueues = new Map<string, Promise<unknown>>();
+  function send(jobId: string | null, text: string, overrides: SendOptions = {}): Promise<string> {
+    const key = jobId ?? "\u0000new";
+    const prev = sendQueues.get(key) ?? Promise.resolve();
+    const run = prev.catch(() => undefined).then(() => sendNow(jobId, text, overrides));
+    const tail = run.catch(() => undefined);
+    sendQueues.set(key, tail);
+    void tail.then(() => { if (sendQueues.get(key) === tail) sendQueues.delete(key); });
+    return run;
+  }
+
+  async function sendNow(key: string | null, typed: string, overrides: SendOptions): Promise<string> {
+    // 业务方补充的背景：随这条消息带上（发出前取走，失败放回去）。超过单条上限就不发，背景留着。
+    const ck = ctxKey(key);
+    const ctx = state.context[ck] ?? [];
+    let text = typed;
+    if (ctx.length) {
+      text = `${typed}\n\n${serializeBlock(backgroundBlock(ctx))}`;
+      if (charCount(text) > MAX_MESSAGE_CHARS) {
+        const err = new CenterError(`补充背景加上这条消息超过单条上限（${MAX_MESSAGE_CHARS.toLocaleString()} 字），请精简补充背景`, "too_long", 0);
+        emit({ type: "error", jobId: key, error: err });
+        throw err;
+      }
+      setContext(ck, []);
+    }
+    try {
+      const target = await sendWithText(key, text, overrides);
+      if (ctx.length) emit({ type: "context", key: target, pending: state.context[ck] ?? [], sent: ctx });
+      // 实时流因重试用完停下了：消息已发出，马上再连，回复才能实时显示。
+      reconnect(target);
+      return target;
+    } catch (error) {
+      if (ctx.length) {
+        const have = new Set((state.context[ck] ?? []).map((c) => c.id));
+        setContext(ck, [...ctx.filter((c) => !have.has(c.id)), ...(state.context[ck] ?? [])]);
+      }
+      throw error;
+    }
+  }
+
+  async function sendWithText(key: string | null, text: string, overrides: SendOptions): Promise<string> {
+    // 发消息的组件自己的参数优先（同一个仓库里可以有几个对话组件，各带各的新建参数），没有再用仓库的。
+    const originalOptions = overrides.newConversation ?? options.newConversation;
+    const newConversation = overrides.executionConfig ? { ...originalOptions, agent: overrides.executionConfig.agent ?? originalOptions?.agent, executionConfig: overrides.executionConfig } : originalOptions;
+    const createConversation = overrides.createConversation ?? options.createConversation;
+    const businessIdFor = overrides.businessIdFor ?? options.businessIdFor;
+    const ref = key ? parseConvKey(key) : null;
+    const businessId = businessIdFor?.(text, ref && ref.taskId !== NEW_TASK ? "message" : "create") || `cli-${uid()}`;
+    try {
+      if (ref?.taskId === NEW_TASK) {
+        // 在对话任务里新开一个对话：标题取第一行，智能体 / 浏览器模式沿用对话任务的第一个对话（center 决定）。
+        if (!client.openConversation) throw new CenterError("当前后端不支持在对话任务里新开对话", "UNSUPPORTED", 0);
+        const result = await retryOnce(() => client.openConversation!(ref.jobId, text, { title: firstLine(text, 60), businessId, agent: newConversation?.agent, executionConfig: newConversation?.executionConfig, browser: newConversation?.browser, timeoutSeconds: newConversation?.timeoutSeconds }));
+        const target = convKey(result.job_id, result.task_id ?? result.turn.task_id);
+        patchConv(target, (conv) => ({ ...conv, turns: addTurnsIfAbsent(conv.turns, [{ ...result.turn, queue_position: result.queue_position }]) }));
+        addJobIfMissing(result.job_id);
+        if (overrides.select !== false && state.selected === key) set({ selected: target });
+        emit({ type: "job_change", jobId: result.job_id, previousJobId: result.job_id !== ref.jobId ? ref.jobId : null, taskId: parseConvKey(target).taskId, key: target, previousKey: key });
+        void refreshJob(result.job_id, true);
+        return target;
+      }
+      if (!key || !ref) {
+        const selectedBeforeCreate = state.selected;
+        let newId: string;
+        if (createConversation) {
+          newId = newConversation?.executionConfig ? await createConversation(text, newConversation) : await createConversation(text);
+        } else {
+          // 新建只发一次：center 的 POST /api/jobs 没有幂等，建好了却没收到响应时重发会建出第二个对话。
+          const created = await client.createConversation(text, { ...newConversation, title: newConversation?.title || firstLine(text), businessId: newConversation?.businessId || businessId });
+          newId = created.id;
+          patchConv(newId, (conv) => ({ ...conv, turns: addTurnsIfAbsent(conv.turns, created.turn ? [created.turn] : []) }));
+        }
+        addJob(newId);
+        // 共享选中只由「跟着选中走」的组件改；传了 jobId、自己接管的对话组件新建对话不去动别人的选中。
+        if (overrides.select !== false && state.selected === selectedBeforeCreate) set({ selected: newId });
+        emit({ type: "job_change", jobId: newId, previousJobId: null, taskId: null, key: newId, previousKey: null });
+        void refreshJob(newId, true);
+        return newId;
+      }
+      const shown = state.convs[key];
+      if (ref.taskId && (isChatTask(shown) || shown?.batch || state.convs[ref.jobId]?.batch)) {
+        // 一次性任务里的子任务（对话式的，或已经结束的普通子任务）：续派一条接着它的对话（中枢接到这个对话最新的那条后面），对话键不变。
+        // 续派没有按 business_id 去重，不重发。
+        if (!client.continueTask) throw new CenterError("当前后端不支持接着对话式子任务聊", "UNSUPPORTED", 0);
+        const { task_id } = await client.continueTask(ref.jobId, ref.taskId, text, { businessId });
+        // 先显示成排队中，不用等实时流的下一次轮询。
+        patchConv(key, (conv) => conv.batchTask && !conv.batchTask.queued?.some((q) => q.id === task_id)
+          ? { ...conv, batchTask: { ...conv.batchTask, queued: [...(conv.batchTask.queued ?? []), { id: task_id, prompt: text, created_at: new Date().toISOString() }] } }
+          : conv);
+        // 大任务结束时旧版中枢会关流：重新连上，接着看这一条。
+        const entry = streams.get(key);
+        if (entry && entry.refs > 0 && !entry.stop && !entry.timer) { entry.attempt = 0; connect(key); }
+        void refreshJob(ref.jobId, true);
+        return key;
+      }
+      const result = await retryOnce(() => client.sendMessage(ref.jobId, text, { businessId, ...(ref.taskId ? { taskId: ref.taskId } : {}), ...(overrides.expectedExecutionRevision !== undefined ? { expectedExecutionRevision: overrides.expectedExecutionRevision } : {}) }));
+      const jobTarget = result.job_id || ref.jobId;
+      // 指定了对话的：接续后跟到新对话任务里对应的那个对话；只有 job_id 的照旧只换 job。
+      const target = ref.taskId ? convKey(jobTarget, result.task_id ?? result.turn.task_id ?? ref.taskId) : jobTarget;
+      if (target !== key) replaceJob(key, target);
+      // 先把这一轮放进状态：排队气泡立刻出现，不用等实时流的下一个块。
+      patchConv(target, (conv) => ({ ...conv, turns: addTurnsIfAbsent(conv.turns, [{ ...result.turn, queue_position: result.queue_position }]) }));
+      if (jobTarget === ref.jobId) addJobIfMissing(ref.jobId);
+      return target;
+    } catch (error) {
+      const err = error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0);
+      emit({ type: "error", jobId: key, error: err });
+      throw err;
+    }
+  }
+
+  function addJobIfMissing(jobId: string) {
+    if (!state.jobIds.includes(jobId)) addJob(jobId);
+  }
+
+  /**
+   * 回答 Agent 的提问（AskUserQuestion 卡片）。center 在 Agent 提问时已经结束了那一轮（asked=true），
+   * 所以回答作为下一条消息发出——与 Operator 在没有等待中的回合时（/answer 返回 resolved=false）的做法一致；
+   * 卡片先在本地标成已答（Operator 同样是先乐观更新）。
+   */
+  /** fallback = false：只交给正在等的回合，不改发消息（一次性任务不能发消息）；没有在等的回合时报错。 */
+  async function answerAsk(key: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions & { fallback?: boolean } = {}): Promise<string> {
+    // 与 Operator 的 answerQuestion 同一流程：先乐观标成已答 → 交给正在等的回合 → 没有在等的回合就当普通回复发出。
+    patchConv(key, (conv) => ({ ...conv, localAnswers: { ...conv.localAnswers, [askId]: answers } }));
+    try {
+      if (askId && client.answerAsk) {
+        const { resolved } = await client.answerAsk(key, askId, answers);
+        if (resolved) return key;
+      }
+      if (overrides.fallback === false) throw new CenterError("这个提问已经没有在等回答了（回合已经结束）", "ASK_EXPIRED", 0);
+      return await send(key, formatAnswersText(questions, answers), overrides);
+    } catch (error) {
+      // 没发出去：卡片恢复成可回答。
+      patchConv(key, (conv) => {
+        const { [askId]: _drop, ...rest } = conv.localAnswers;
+        return { ...conv, localAnswers: rest };
+      });
+      throw error;
+    }
+  }
+
+  async function cancelTurn(key: string, turnId: string) {
+    try {
+      const turn = await client.cancelTurn(parseConvKey(key).jobId, turnId);
+      // 撤回排队的消息会立刻收尾（cancelled）：响应里已经结束、而我们还没收到的，先用上；其余以实时流为准。
+      patchConv(key, (conv) => {
+        const known = conv.turns.find((t) => t.turn_id === turn.turn_id);
+        if (known && (TERMINAL_TURN.has(known.status) || !TERMINAL_TURN.has(turn.status))) return conv;
+        return { ...conv, turns: upsertTurns(conv.turns, [turn]) };
+      });
+    } catch (error) {
+      const err = error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0);
+      emit({ type: "error", jobId: key, error: err });
+      throw err;
+    }
+  }
+
+  /** 结束对话：指定了对话（"job#task"）的只关掉这一个；只有 job_id 的结束整个对话任务（和以前一样）。 */
+  async function close(key: string) {
+    const { jobId, taskId } = parseConvKey(key);
+    try {
+      if (taskId && taskId !== NEW_TASK) {
+        if (!client.closeConversationTask) throw new CenterError("当前后端不支持单独关闭对话", "UNSUPPORTED", 0);
+        await client.closeConversationTask(jobId, taskId);
+      } else {
+        await client.closeConversation(jobId);
+      }
+      await refreshJob(jobId, true);
+    } catch (error) {
+      const err = error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0);
+      emit({ type: "error", jobId: key, error: err });
+      throw err;
+    }
+  }
+
+  /**
+   * 往上翻：取这个对话更早的一页节点消息，接在最前面。实时流只给最新一段（older 是更早还有几条）。
+   * 同一个对话同一时刻只取一页。返回取到没有。
+   */
+  const loadingOlder = new Set<string>();
+  async function loadOlder(key: string): Promise<boolean> {
+    const conv = state.convs[key];
+    // 节点会话：一次性任务是正在看的那个对话，对话任务是流里这个对话的远端任务。
+    const remote = conv ? conv.remoteTaskId ?? conv.task?.remote_task_id ?? null : null;
+    const first = conv?.msgs[0];
+    if (!conv || conv.older <= 0 || !remote || !first || !client.history || loadingOlder.has(key)) return false;
+    loadingOlder.add(key);
+    try {
+      const page = await client.history(key, remote, first.id, 200);
+      // 取的过程中换了节点会话（重建、续派切过去）：这一页作废。
+      patchConv(key, (c) => ((c.remoteTaskId ?? c.task?.remote_task_id ?? null) === remote && c.msgs[0]?.id === first.id ? applyOlderPage(c, page.messages ?? [], page.older) : c));
+      return true;
+    } catch (error) {
+      emit({ type: "error", jobId: key, error: error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0) });
+      return false;
+    } finally {
+      loadingOlder.delete(key);
+    }
+  }
+
+  // 同一个仓库里登记的看板（cli-board）。后登记的优先（例如弹出的看板盖在常驻的上面）。
+  const surfaces: { surface: BoardSurface; owner?: string; inline?: boolean; priority?: () => number }[] = [];
+  const visibleLists = new Set<string>();
+  function reportListPresence(owner: string, visible: boolean) {
+    if (visible) visibleLists.add(owner); else visibleLists.delete(owner);
+    const listVisible = visibleLists.size > 0;
+    if (state.listVisible !== listVisible) set({ listVisible });
+  }
+  const externalBoards = new Map<string, Map<string, { visible: boolean; availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean }>>();
+  function reportBoardPresence(key: string, owner: string, visible: boolean | null, options: { availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean } = {}) {
+    const owners = externalBoards.get(key) ?? new Map<string, { visible: boolean; availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean }>();
+    if (visible === null) owners.delete(owner); else owners.set(owner, { visible, ...options });
+    if (owners.size) externalBoards.set(key, owners); else externalBoards.delete(key);
+    const values = [...owners.values()];
+    const shown = values.some(value => value.visible);
+    const limits = owners.size ? { availableTabs: (["files", "changes", "browser"] as const).filter(tab => values.every(value => !value.availableTabs || value.availableTabs.includes(tab))), readOnly: values.some(value => value.readOnly) } : undefined;
+    if (!!state.externalBoards[key] === shown && JSON.stringify(state.externalBoardOptions[key]) === JSON.stringify(limits)) return;
+    const next = { ...state.externalBoards };
+    if (shown) next[key] = true; else delete next[key];
+    const configurations = { ...state.externalBoardOptions };
+    if (limits) configurations[key] = limits; else delete configurations[key];
+    set({ externalBoards: next, externalBoardOptions: configurations });
+  }
+  // ── 看板 → 对话的引用 ─────────────────────────────
+
+  function setRefs(key: string, refs: BoardRef[]) {
+    const next = { ...state.refs };
+    if (refs.length) next[key] = refs.map(ref => ({ ...ref })); else delete next[key];
+    set({ refs: next });
+    emit({ type: "board_ref", key, refs });
+  }
+  /** 把看板里的东西引用到这个对话的下一条消息（同 id 替换）。 */
+  function addRef(key: string, ref: BoardRef) {
+    const list = (state.refs[key] ?? []).filter((r) => r.id !== ref.id);
+    // 引用是「指向看板里的什么」，不是把内容整段塞进消息：每条截到 REF_TEXT_MAX，最多留 REF_MAX 条，消息不会因此超长。
+    const text = ref.text.length > REF_TEXT_MAX ? `${ref.text.slice(0, REF_TEXT_MAX)}…（已截断，共 ${ref.text.length} 字）` : ref.text;
+    setRefs(key, [...list, { ...ref, text }].slice(-REF_MAX));
+  }
+  function removeRef(key: string, id: string) {
+    const list = state.refs[key] ?? [];
+    if (list.some((r) => r.id === id)) setRefs(key, list.filter((r) => r.id !== id));
+  }
+  /** 取走这个对话的引用（发消息时用；发失败时用 restoreRefs 放回去）。 */
+  function takeRefs(key: string): BoardRef[] {
+    const list = state.refs[key] ?? [];
+    if (list.length) setRefs(key, []);
+    return list;
+  }
+  function restoreRefs(key: string, refs: BoardRef[]) {
+    if (!refs.length) return;
+    const have = new Set((state.refs[key] ?? []).map((r) => r.id));
+    setRefs(key, [...refs.filter((r) => !have.has(r.id)), ...(state.refs[key] ?? [])]);
+  }
+
+  // ── 看板上正在看的东西（缺省带进下一条消息一次）────────
+  function setViewingState(key: string, value: { ref: BoardRef; off: boolean } | null) {
+    const next = { ...state.viewing };
+    if (value) next[key] = value; else delete next[key];
+    set({ viewing: next });
+  }
+  /**
+   * 看板报告这个对话正在看什么（null = 没在看）。同一个东西重复报告不变。
+   * owner：哪个看板报的。同一个对话开着两个看板（常驻的 + 弹出的）时，一个撤掉只撤自己报的，不清掉另一个的。
+   */
+  // 每个看板各自报告（按 owner 记），生效的是最近报告、还开着的那个；一个看板撤掉只撤它自己的。
+  const viewSources = new Map<string, Map<string, BoardRef>>();
+  const boardSources = new Map<string, Map<string, BoardView>>();
+  /** 记下 owner 的报告，返回现在生效的那个（最近报告的）。 */
+  function latestReport<T>(sources: Map<string, Map<string, T>>, key: string, owner: string, value: T | null): T | null {
+    const m = sources.get(key) ?? new Map<string, T>();
+    m.delete(owner);
+    if (value) m.set(owner, value);
+    if (m.size) sources.set(key, m); else sources.delete(key);
+    return m.size ? [...m.values()][m.size - 1] : null;
+  }
+  function setViewing(key: string, ref: BoardRef | null, owner = "default") {
+    const top = latestReport(viewSources, key, owner, ref);
+    const cur = state.viewing[key];
+    if (!top) { if (cur) setViewingState(key, null); return; }
+    if (cur && cur.ref.id === top.id && cur.ref.text === top.text) return;
+    setViewingState(key, { ref: top, off: cur?.ref.id === top.id ? cur.off : false });
+  }
+
+  // ── 看板现在的样子（给业务方：当前打开的文件等）────────
+  function applyBoardSelection(key:string,top:BoardView|null,history:import("../board/workspace").BoardFile[]) {
+    const current=state.boards[key],previous=state.boardContext[key];
+    const boardChanged=JSON.stringify(top)!==JSON.stringify(current??null);
+    const retained=top?{...cloneBoardView(top),history,visible:top.visible!==false}:previous?{...cloneBoardView(previous),history,visible:false}:null;
+    const contextChanged=!!retained&&JSON.stringify(previous)!==JSON.stringify(retained);
+    if(!boardChanged&&!contextChanged)return;
+    const boards={...state.boards};if(top)boards[key]=cloneBoardView(top);else delete boards[key];
+    // Commit both public views before subscribers can read them or navigate again.
+    set({...(boardChanged?{boards}:{}),...(contextChanged?{boardContext:{...state.boardContext,[key]:retained!}}:{})});
+    if(boardChanged&&state.boards[key]===boards[key])emit({type:"board_change",key,view:top?cloneBoardView(top):null});
+    // A reentrant callback may already have selected a newer file. Do not emit
+    // or restore the older automatic context over that newer selection.
+    if(contextChanged&&state.boardContext[key]===retained)emit({type:"board_context",jobId:key,view:cloneBoardView(retained!)});
+  }
+  function reportBoard(key:string,view:BoardView|null,owner="default") {
+    const sources=boardSources.get(key)??new Map<string,BoardView>();
+    let history=state.boardContext[key]?.history??[];
+    if(view){history=mergeBoardHistory(history,sources.get(owner),view);reportBoardOwner(sources,owner,cloneBoardView(view));}
+    else sources.delete(owner);
+    if(sources.size)boardSources.set(key,sources);else boardSources.delete(key);
+    const top=selectedBoardOwner(sources)?.[1]??null;applyBoardSelection(key,top,history);
+  }
+  function activateBoard(key:string,owner:string) {
+    const sources=boardSources.get(key);if(!sources)return;
+    const top=activateBoardOwner(sources,owner)?.[1];if(!top)return;
+    const file=top.current??(top.file?{path:top.file,sourceId:key}:null);
+    const history=file?rememberBoardFile(state.boardContext[key]?.history??[],file):state.boardContext[key]?.history??[];
+    applyBoardSelection(key,top,history);
+  }
+  const fileSubscriptions = new Map<string,{listeners:Set<{change?:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']}>;stop:()=>void;status?:WorkspaceWatchStatus}>();
+  function watchWorkspace(key:string,listener?:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}) {
+    if(!client.board) throw new Error("当前后端不支持工作区文件订阅");
+    const releaseScope=options.paths?.length||options.dirs?.length?retainFileScope(client.board,key,{paths:[...options.paths??[]],dirs:[...options.dirs??[]]}):()=>{};
+    const item={change:listener,status:options.onStatus};let subscription=fileSubscriptions.get(key);
+    if(!subscription){
+      subscription={listeners:new Set([item]),stop:()=>{}};fileSubscriptions.set(key,subscription);const owned=subscription;
+      owned.stop=subscribeWorkspaceFiles(client.board,key,event=>{emit(event);for(const next of [...owned.listeners])notifyCallback(next.change,cloneWorkspaceChange(event));},{intervalMs:options.intervalMs,onStatus:status=>{owned.status=status;emit(status);for(const next of [...owned.listeners])notifyCallback(next.status,{...status});}});
+    }else{subscription.listeners.add(item);if(subscription.status)notifyCallback(item.status,{...subscription.status});retryWorkspaceFiles(client.board,key);}
+    const owned=subscription;let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(item);if(!owned.listeners.size){if(fileSubscriptions.get(key)===owned)fileSubscriptions.delete(key);owned.stop();}releaseScope();};
+  }
+
+  // ── 补充背景：业务方随时追加，随下一条消息发给智能体 ────────
+  const ctxKey = (key: string | null) => key ?? "";
+  function setContext(key: string, items: ContextItem[], sent?: ContextItem[]) {
+    const next = { ...state.context };
+    if (items.length) next[key] = items; else delete next[key];
+    set({ context: next });
+    emit({ type: "context", key, pending: items, ...(sent ? { sent } : {}) });
+  }
+  /**
+   * 给这个对话追加一段项目背景（null = 还没建的新对话，随第一条消息带上）。
+   * 下一条消息发出时一起带给智能体（对话里显示成一张「补充背景」卡片），发出后智能体在这个对话里一直记得。
+   * 同一个 id 再追加会替换。返回这条的 id。
+   */
+  function appendContext(key: string | null, text: string, opts: { title?: string; id?: string } = {}): string {
+    const body = String(text ?? "").trim();
+    if (!body) throw new Error("补充背景不能为空");
+    if (charCount(body) > CONTEXT_ITEM_MAX) throw new Error(`一条补充背景最长 ${CONTEXT_ITEM_MAX.toLocaleString()} 字，请拆成几条或精简`);
+    const k = ctxKey(key);
+    const id = opts.id ?? `ctx-${uid()}`;
+    const list = (state.context[k] ?? []).filter((c) => c.id !== id);
+    setContext(k, [...list, { id, text: body, ...(opts.title ? { title: opts.title.trim().slice(0, 60) } : {}) }]);
+    return id;
+  }
+  function removeContext(key: string | null, id?: string) {
+    const k = ctxKey(key);
+    const list = state.context[k] ?? [];
+    const next = id ? list.filter((c) => c.id !== id) : [];
+    if (next.length !== list.length) setContext(k, next);
+  }
+  /** 还没发出的补充背景。 */
+  const pendingContext = (key: string | null): ContextItem[] => (state.context[ctxKey(key)] ?? []).map(item => ({ ...item }));
+
+  function workspace(key?: string | null): CliWorkspace {
+    const k = key ?? state.selected;
+    if (!k) throw new Error("没有指定对话：请传 jobId，或先选中一个对话");
+    return createWorkspace({
+      backend: client.board,
+      key: k,
+      view: () => state.boards[k],
+      context: () => state.boardContext[k] ? cloneBoardView(state.boardContext[k]) : null,
+      watch: (listener, options) => watchWorkspace(k,listener,options),
+      open: (path) => openInBoard(k, { kind: "file", path }),
+    });
+  }
+  /** 这次不带上正在看的东西。 */
+  function dismissViewing(key: string) {
+    const cur = state.viewing[key];
+    if (cur && !cur.off) setViewingState(key, { ...cur, off: true });
+  }
+  /** 发消息时取走（取走后同一个东西不再重复带；看了别的才再带）。 */
+  function takeViewing(key: string): BoardRef | null {
+    const cur = state.viewing[key];
+    if (!cur || cur.off) return null;
+    setViewingState(key, { ...cur, off: true });
+    return cur.ref;
+  }
+  function restoreViewing(key: string, ref: BoardRef | null) {
+    const cur = state.viewing[key];
+    if (ref && cur && cur.ref.id === ref.id && cur.off) setViewingState(key, { ...cur, off: false });
+  }
+
+  function openInBoard(jobId: string, target: OpenTarget, preferredInlineOwner?: string): boolean {
+    let handled = false;
+    const available = [...surfaces].reverse().filter(item => !preferredInlineOwner || !item.inline || item.owner === preferredInlineOwner)
+      .sort((a, b) => (b.priority?.() ?? 2) - (a.priority?.() ?? 2));
+    for (const { surface } of available) {
+      try { handled = surface(jobId, { ...target }); }
+      catch (error) { console.error("[@xgspz/cli-ui] board surface callback failed", error); }
+      if (handled) break;
+    }
+    emit({ type: "open", jobId, target, handled });
+    return handled;
+  }
+
+  return {
+    client,
+    getNewConversationOptions: () => options.newConversation,
+    draftScope: connectionDraftScope(options),
+    getState: () => state,
+    /** 在看板里打开文件 / 浏览器 / 改动。返回有没有看板接住。 */
+    openInBoard,
+    /** 看板登记自己；返回注销函数。 */
+    registerBoard(surface: BoardSurface, options: { owner?: string; inline?: boolean; priority?: () => number } = {}) {
+      const entry = { surface, ...options };
+      surfaces.push(entry);
+      return () => { const i = surfaces.indexOf(entry); if (i >= 0) surfaces.splice(i, 1); };
+    },
+    subscribe(fn: () => void) { listeners.add(fn); return () => { listeners.delete(fn); }; },
+    on(fn: (event: CliEvent) => void) { eventListeners.add(fn); return () => { eventListeners.delete(fn); }; },
+    select(jobId: string | null) {
+      if (state.selected === jobId) return;
+      set({ selected: jobId });
+      emit({ type: "select", jobId });
+    },
+    setJobIds, addJob, removeJob, replaceJob, refreshJob, refreshAll,
+    addRef, removeRef, takeRefs, restoreRefs,
+    setViewing, dismissViewing, takeViewing, restoreViewing,
+    /** 看板报告自己的样子（看板组件用）。 */
+    reportBoard, activateBoard, reportBoardPresence, reportListPresence,
+    /** 业务方追加项目背景：随下一条消息发给智能体。 */
+    appendContext, removeContext, pendingContext,
+    /** 工作区文件接口（不显示看板也能用）：列文件、读文件、下载、打包。不传 = 当前选中的对话。 */
+    workspace, watchWorkspace,
+    open, send, answerAsk, cancelTurn, close, loadOlder, reconnect,
+  };
+}
+
+export type CliStore = ReturnType<typeof createCliStore>;
+
+
+async function runLimited<T>(items: T[], limit: number, fn: (item: T) => Promise<unknown>) {
+  let index = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (index < items.length) await fn(items[index++]);
+  });
+  await Promise.all(workers);
+}
+
+const REF_MAX = 20;
+const REF_TEXT_MAX = 4_000;
+
+/** 只有网络层失败（没收到响应）才重发：带 business_id，center 会去重。 */
+async function retryOnce<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof CenterError && error.code === "NETWORK") return fn();
+    throw error;
+  }
+}
+
+const uid = clientId;