@spzxg/cli-ui 0.0.0-stage → 0.3.0

package/src/core/store.ts

@@ -0,0 +1,575 @@
+/**
+ * 组件共享的状态仓库（纯 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 { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client.js";
+import { addTurnsIfAbsent, applyItems, applySnapshot, closedCallback, convEnded, convKey, emptyConv, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation.js";
+import { formatAnswersText } from "../ui/format.js";
+import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types.js";
+
+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;
+}
+
+/** 与 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 };
+
+/** 看板要打开的东西。 */
+export type OpenTarget = { kind: "file"; path: string } | { kind: "browser" } | { kind: "changes" } | { kind: "files"; path?: string };
+/** 看板登记的接收函数：接得住（显示的是这个对话）就返回 true。 */
+export type BoardSurface = (jobId: string, target: OpenTarget) => boolean;
+
+export interface CliStoreOptions extends CenterClientOptions {
+  client?: CenterClient;
+  /** 在本机记住对话列表用的命名空间（不同业务 / 产品线请区分）。不给 = 不记，组件之间没有任何隐式共享。 */
+  namespace?: string | null;
+  /**
+   * 新建对话时的参数（与 POST /api/jobs 对应）：标题、业务 ID、工作区、回调、智能体、超时、浏览器模式。
+   * 带了 callback，center 每轮结束就向 callback.url 投递 conversation_turn，结束时投递 conversation_closed。
+   */
+  newConversation?: NewConversationOptions;
+  /** 自己建对话（例如经业务后端建，以便把回调密钥留在服务端）：返回 center 的 job_id。 */
+  createConversation?: (firstMessage: string) => Promise<string>;
+  /**
+   * 每条消息的 business_id（center 按它去重，回调里原样带回）。缺省 `cli-<uuid>`。
+   * kind = "create" 是第一条（新建对话），"message" 是之后的每条。
+   */
+  businessIdFor?: (text: string, kind: "create" | "message") => string;
+}
+
+/** 发一条消息时可以单独指定的新建参数（组件自己的 props），优先于仓库的。 */
+export interface SendOptions {
+  /** 新建对话后是否改仓库的选中（缺省改）。 */
+  select?: boolean;
+  newConversation?: NewConversationOptions;
+  createConversation?: (firstMessage: string) => Promise<string>;
+  businessIdFor?: (text: string, kind: "create" | "message") => string;
+}
+
+const RECONNECT_MS = [1_000, 2_000, 5_000, 10_000, 20_000];
+const JOB_REFRESH_GAP_MS = 1_500;
+
+export function createCliStore(options: CliStoreOptions = {}) {
+  const client = options.client ?? createCenterClient(options);
+  // 只有明确给了 namespace 才在本机记住对话列表：不给就不落任何共享状态，几个独立的组件互不影响。
+  const storageKey = options.namespace ? `cli-ui:${options.namespace}:jobs` : null;
+
+  let state: CliState = { selected: null, jobIds: loadIds(storageKey), jobs: {}, convs: {}, listLoading: false, listError: null };
+  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) fn();
+  };
+  const emit = (event: CliEvent) => { for (const fn of eventListeners) fn(event); };
+  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)) {
+      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.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 persist(ids: string[]) {
+    if (!storageKey || hostIds) return;
+    try { localStorage.setItem(storageKey, JSON.stringify(ids.slice(0, 200))); } catch { /* 存不下就不记 */ }
+  }
+
+  // ── 列表 ─────────────────────────────────────────────
+
+  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 });
+    persist(ids);
+  }
+
+  function removeJob(jobId: string) {
+    const ids = state.jobIds.filter((id) => id !== jobId);
+    set({ jobIds: ids, selected: state.selected === jobId ? null : state.selected });
+    persist(ids);
+  }
+
+  /** 对话接续：旧 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 });
+    persist(state.jobIds);
+    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, 4, (id) => refreshJob(id, true));
+      set({ listLoading: false });
+    } catch (error) {
+      set({ listLoading: false, listError: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  /**
+   * 从 center 发现本产品线的对话：center 没有「列出对话」接口，只能从全部子任务里按 job 去重，
+   * 再逐个看是不是对话任务。center 的 ID 是随机的，返回顺序不代表新旧，所以最多看 limit 个 job（缺省 200）；
+   * 对话多的产品线请由宿主传 jobIds。只在宿主没给 jobIds 时调用。
+   */
+  let discovering: Promise<void> | null = null;
+  function discover(limit = 200) {
+    // 同时多次调用（React StrictMode 下 effect 会跑两遍）只发现一次。
+    discovering ??= discoverOnce(limit).finally(() => { discovering = null; });
+    return discovering;
+  }
+
+  async function discoverOnce(limit: number) {
+    set({ listLoading: true, listError: null });
+    try {
+      const { tasks } = await client.listTasks();
+      const candidates = [...new Set(tasks.map((task) => task.job_id))].filter((id) => !state.jobIds.includes(id)).slice(0, limit);
+      const found: string[] = [];
+      await runLimited(candidates, 4, async (id) => {
+        const job = await client.getJob(id).catch(() => null);
+        if (job?.mode === "conversation") {
+          found.push(id);
+          patchJob(id, { job, firstInput: null, loading: false, error: null, fetchedAt: 0 });
+        }
+      });
+      const ids = [...new Set([...state.jobIds, ...found])];
+      set({ jobIds: ids, listLoading: false });
+      persist(ids);
+      await runLimited(found, 4, (id) => refreshJob(id, true));
+    } catch (error) {
+      set({ listLoading: false, listError: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  // ── 实时流（引用计数 + 断线重连） ─────────────────────
+
+  const streams = new Map<string, { refs: number; stop: (() => void) | null; timer: ReturnType<typeof setTimeout> | null; attempt: number }>();
+
+  function connect(key: string) {
+    const entry = streams.get(key);
+    if (!entry || entry.refs <= 0) return;
+    const { jobId, taskId } = parseConvKey(key);
+    patchConv(key, (conv) => ({ ...conv, stream: entry.attempt ? "reconnecting" : "connecting", streamError: null }));
+    let ended = false;
+    entry.stop = client.stream(jobId, {
+      onOpen: () => { entry.attempt = 0; patchConv(key, (conv) => ({ ...conv, stream: "live", streamError: null })); },
+      onSnapshot: (snapshot) => patchConv(key, (conv) => applySnapshot(conv, snapshot)),
+      onChunk: (items) => patchConv(key, (conv) => applyItems(conv, items)),
+      onEnd: (end) => {
+        ended = true;
+        // 接续的新对话：指定了对话的跟到接续它的那个对话（还没有就不跟，再发消息时 center 会开出来）；只有 job_id 的照旧跟新 job。
+        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 }));
+        void refreshJob(jobId, true);
+      },
+      onClose: (error) => {
+        entry.stop = null;
+        const current = streams.get(key);
+        if (!current || current.refs <= 0) return;
+        // 对话结束（end）不再连；中枢停机（server_shutdown）稍后重连。
+        if (ended && state.convs[key]?.endReason !== "server_shutdown") return;
+        // 404 / 401：对话不存在或没权限，重连也没用。
+        if (error && (error.status === 404 || error.status === 401 || error.status === 403)) {
+          patchConv(key, (conv) => ({ ...conv, stream: "error", streamError: error.message }));
+          emit({ type: "error", jobId: key, error });
+          return;
+        }
+        const delay = RECONNECT_MS[Math.min(current.attempt, RECONNECT_MS.length - 1)];
+        current.attempt += 1;
+        patchConv(key, (conv) => ({ ...conv, stream: "reconnecting", streamError: error?.message ?? null }));
+        current.timer = setTimeout(() => { current.timer = null; connect(key); }, delay);
+      },
+    }, undefined, taskId);
+  }
+
+  // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
+  function reconnectNow() {
+    for (const [jobId, entry] of streams) {
+      if (!entry.timer) continue;
+      clearTimeout(entry.timer);
+      entry.timer = null;
+      entry.attempt = 0;
+      connect(jobId);
+    }
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("online", reconnectNow);
+    document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") reconnectNow(); });
+  }
+
+  /**
+   * 开始看一个对话（对话键；返回停止函数）。同一对话多处同时看只连一次。
+   * "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);
+    }
+    entry.refs += 1;
+    if (entry.refs === 1) {
+      void refreshJob(jobId);
+      connect(key);
+    }
+    return () => {
+      const current = streams.get(key);
+      if (!current) return;
+      current.refs -= 1;
+      if (current.refs > 0) return;
+      current.stop?.();
+      if (current.timer) clearTimeout(current.timer);
+      streams.delete(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, text: string, overrides: SendOptions): Promise<string> {
+    // 发消息的组件自己的参数优先（同一个仓库里可以有几个对话组件，各带各的新建参数），没有再用仓库的。
+    const newConversation = overrides.newConversation ?? options.newConversation;
+    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 }));
+        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) {
+        let newId: string;
+        if (createConversation) {
+          newId = 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) set({ selected: newId });
+        emit({ type: "job_change", jobId: newId, previousJobId: null, taskId: null, key: newId, previousKey: null });
+        void refreshJob(newId, true);
+        return newId;
+      }
+      const result = await retryOnce(() => client.sendMessage(ref.jobId, text, { businessId, ...(ref.taskId ? { taskId: ref.taskId } : {}) }));
+      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 同样是先乐观更新）。
+   */
+  async function answerAsk(key: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions = {}): 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;
+      }
+      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;
+    }
+  }
+
+  // 同一个仓库里登记的看板（cli-board）。后登记的优先（例如弹出的看板盖在常驻的上面）。
+  const surfaces: BoardSurface[] = [];
+  function openInBoard(jobId: string, target: OpenTarget): boolean {
+    let handled = false;
+    for (let i = surfaces.length - 1; i >= 0 && !handled; i--) handled = surfaces[i](jobId, target);
+    emit({ type: "open", jobId, target, handled });
+    return handled;
+  }
+
+  return {
+    client,
+    getState: () => state,
+    /** 在看板里打开文件 / 浏览器 / 改动。返回有没有看板接住。 */
+    openInBoard,
+    /** 看板登记自己；返回注销函数。 */
+    registerBoard(surface: BoardSurface) {
+      surfaces.push(surface);
+      return () => { const i = surfaces.indexOf(surface); 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, discover,
+    open, send, answerAsk, cancelTurn, close,
+  };
+}
+
+export type CliStore = ReturnType<typeof createCliStore>;
+
+function loadIds(key: string | null): string[] {
+  if (!key) return [];
+  try {
+    const value = JSON.parse(localStorage.getItem(key) || "[]");
+    return Array.isArray(value) ? [...new Set(value.filter((id): id is string => typeof id === "string"))] : [];
+  } catch {
+    return [];
+  }
+}
+
+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);
+}
+
+/** 只有网络层失败（没收到响应）才重发：带 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;
+  }
+}
+
+function uid() {
+  const cryptoObj = globalThis.crypto as Crypto | undefined;
+  if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}