@spzxg/cli-ui 0.0.0-stage → 0.1.0

package/src/core/provider.tsx

@@ -0,0 +1,89 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useSyncExternalStore, type ReactNode } from "react";
+import { createCliStore, type CliEvent, type CliState, type CliStore, type CliStoreOptions } from "./store.js";
+import type { ConversationCallback } from "./types.js";
+
+/**
+ * 积木的拼接点。放在同一个 <CliCenterProvider> 里的组件共享一个仓库：
+ * 列表点哪个对话，对话组件就显示哪个；同一个对话只连一条实时流。
+ *
+ *   <CliCenterProvider baseUrl="/api/center">
+ *     <CliMsgList />
+ *     <CliChat />
+ *   </CliCenterProvider>
+ *
+ * 组件单独使用时不需要它：组件发现外面没有 Provider，会用自己的 props 建一个。
+ */
+const StoreContext = createContext<CliStore | null>(null);
+
+export interface CliCenterProviderProps extends CliStoreOptions {
+  /** 外部建好的仓库（例如 Web Component 按 group 共享的）；给了就不再自己建。 */
+  store?: CliStore;
+  /** 监听仓库事件：选中、一轮结束、对话结束、job 变化、错误。 */
+  onEvent?: (event: CliEvent) => void;
+  /**
+   * 前端回调：每轮结束 / 对话结束时调用，载荷与 center 投递给 callback.url 的请求体同名同义
+   * （conversation_turn / conversation_closed）。用来刷新业务界面；落库以后端回调为准。
+   */
+  onCallback?: (payload: ConversationCallback) => void;
+  children: ReactNode;
+}
+
+export function CliCenterProvider({ store: external, onEvent, onCallback, children, ...options }: CliCenterProviderProps) {
+  // 连接参数只在建仓库时用一次：中途换 baseUrl / token 请换 key 重建。
+  const optionsRef = useRef(options);
+  const store = useMemo(() => external ?? createCliStore(optionsRef.current), [external]);
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const onCallbackRef = useRef(onCallback);
+  onCallbackRef.current = onCallback;
+  useEffect(() => store.on((event) => {
+    onEventRef.current?.(event);
+    if (event.type === "conversation_turn" || event.type === "conversation_closed") onCallbackRef.current?.(event.payload);
+  }), [store]);
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}
+
+export function useCliStoreContext(): CliStore | null {
+  return useContext(StoreContext);
+}
+
+export function useCliStore(): CliStore {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error("useCliStore 必须在 <CliCenterProvider> 内使用");
+  return store;
+}
+
+/** 订阅仓库状态的一部分。选择器返回的值按引用比较，状态是不可变的，所以返回子对象是安全的。 */
+export function useCliState<T>(selector: (state: CliState) => T): T {
+  const store = useCliStore();
+  return useSyncExternalStore(store.subscribe, () => selector(store.getState()), () => selector(store.getState()));
+}
+
+/** 组件外面没有 Provider 时，用组件自己的 props 包一层。 */
+export function withOwnProvider<P extends object>(props: P & CliStoreOptions & { onEvent?: (event: CliEvent) => void; onCallback?: (payload: ConversationCallback) => void; store?: CliStore }, inner: ReactNode, hasContext: boolean) {
+  if (hasContext) return inner;
+  const { baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onCallback, store } = props;
+  // 连接参数变了（换了中枢地址、令牌、产品线、命名空间）就换一个新仓库重连，不沿用旧连接。
+  const connection = [baseUrl ?? "", token ?? "", line ?? "", namespace ?? ""].join("\u0000");
+  return (
+    <CliCenterProvider key={store ? "external" : connection} {...{ baseUrl, token, line, headers, fetch, client, namespace, newConversation, createConversation, businessIdFor, onEvent, onCallback, store }}>
+      {inner}
+    </CliCenterProvider>
+  );
+}
+
+/**
+ * 组件自己的 onEvent / onCallback：组件放在外层 Provider 里时由这里订阅（自己建 Provider 时交给那个 Provider，免得调两次）。
+ */
+export function useComponentEvents(onEvent: ((event: CliEvent) => void) | undefined, onCallback: ((payload: ConversationCallback) => void) | undefined, enabled: boolean) {
+  const store = useContext(StoreContext);
+  const ref = useRef({ onEvent, onCallback });
+  ref.current = { onEvent, onCallback };
+  useEffect(() => {
+    if (!enabled || !store) return;
+    return store.on((event) => {
+      ref.current.onEvent?.(event);
+      if (event.type === "conversation_turn" || event.type === "conversation_closed") ref.current.onCallback?.(event.payload);
+    });
+  }, [store, enabled]);
+}

package/src/core/sse.ts

@@ -0,0 +1,51 @@
+/**
+ * 极简 SSE 解析器。用 fetch 读流而不是 EventSource：EventSource 不能带 Authorization 头，
+ * 而 center 的接口按产品线令牌鉴权（直连或经代理都可能需要带头）。
+ *
+ * 按 https://html.spec.whatwg.org/multipage/server-sent-events.html 的行规则：
+ * `event:` 设事件名，`data:` 累加数据，空行派发；以 `:` 开头的是注释（心跳 ping）。
+ */
+export interface SseMessage { event: string; data: string }
+
+export function createSseParser(onMessage: (message: SseMessage) => void) {
+  let buffer = "";
+  let event = "";
+  let data: string[] = [];
+
+  const dispatch = () => {
+    if (data.length) onMessage({ event: event || "message", data: data.join("\n") });
+    event = "";
+    data = [];
+  };
+
+  const line = (raw: string) => {
+    if (raw === "") return dispatch();
+    if (raw.startsWith(":")) return;
+    const colon = raw.indexOf(":");
+    const field = colon === -1 ? raw : raw.slice(0, colon);
+    let value = colon === -1 ? "" : raw.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") event = value;
+    else if (field === "data") data.push(value);
+  };
+
+  return {
+    push(chunk: string) {
+      buffer += chunk;
+      let index: number;
+      // 行尾可能是 \n、\r\n 或 \r。
+      while ((index = buffer.search(/\r\n|\r|\n/)) !== -1) {
+        const sep = buffer.startsWith("\r\n", index) ? 2 : 1;
+        // 只剩一个 \r 时等下一块：它可能是 \r\n 的前半。
+        if (buffer[index] === "\r" && sep === 1 && index === buffer.length - 1) break;
+        line(buffer.slice(0, index));
+        buffer = buffer.slice(index + sep);
+      }
+    },
+    end() {
+      if (buffer) line(buffer);
+      buffer = "";
+      dispatch();
+    },
+  };
+}

package/src/core/store.ts

@@ -0,0 +1,491 @@
+/**
+ * 组件共享的状态仓库（纯 TS，无 React）。积木之间靠它拼起来：
+ *
+ *   · 选中哪个对话（cli-msglist 点一下，cli-chat 跟着切）；
+ *   · 列表里有哪些对话（宿主给 jobIds，或本地记住 + 从 center 发现）；
+ *   · 每个对话的实时状态：一个对话只开一条实时流，几个组件同时看也只连一次（引用计数）。
+ *
+ * 单独用某个组件时它会自己建一个仓库；放进同一个 <CliCenterProvider>（或同一个 group 的 Web Component）就共享一个。
+ */
+import { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client.js";
+import { applyItems, applySnapshot, closedCallback, emptyConv, 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;
+  jobIds: string[];
+  jobs: Record<string, JobEntry>;
+  convs: Record<string, ConvState>;
+  listLoading: boolean;
+  listError: string | null;
+}
+
+/** 与 center 回调同名同义的事件，方便宿主把前端事件和后端回调对上。 */
+export type CliEvent =
+  | { type: "select"; jobId: string | null }
+  /** 一轮结束。payload 与 center 回调 conversation_turn 的请求体同名同义。 */
+  | { type: "conversation_turn"; jobId: string; turn: CenterTurn; payload: ConversationTurnCallback }
+  /** 对话结束。payload 与 center 回调 conversation_closed 的请求体同名同义。 */
+  | { type: "conversation_closed"; jobId: string; reason: string | null; continuedBy: string | null; payload: ConversationClosedCallback }
+  /** 新建了对话，或旧对话结束后消息开了新对话（job_id 变了）。 */
+  | { type: "job_change"; jobId: string; previousJobId: string | null }
+  | { type: "error"; jobId: string | null; error: CenterError };
+
+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 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 = (jobId: string, fn: (conv: ConvState) => ConvState) => {
+    const prev = state.convs[jobId] ?? emptyConv(jobId);
+    const next = fn(prev);
+    if (next !== prev) {
+      noticeTransitions(jobId, prev, next);
+      set({ convs: { ...state.convs, [jobId]: 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(jobId: string, prev: ConvState, next: ConvState) {
+    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) || settledTurns.has(turn.turn_id)) continue;
+        settledTurns.add(turn.turn_id);
+        const was = before.get(turn.turn_id);
+        // 打开页面时已经结束的历史轮次不算「刚结束」。
+        // 被合并进别的轮次的消息不单独回调（center 也不单独投递），结果在那一轮的 messages 里。
+        if (was !== undefined && !TERMINAL_TURN.has(was) && turn.status !== "merged") {
+          const continuedFrom = state.jobs[jobId]?.job?.conversation?.continued_from_job_id ?? null;
+          emit({ type: "conversation_turn", jobId, turn, payload: turnCallback(next, turn, continuedFrom) });
+          void refreshJob(jobId, true);
+        }
+      }
+    }
+    // 对话结束：只对本页看着还开着的对话发（打开时就已结束的不算）；而且要等所有轮次都收尾之后再发，
+    // 保证 conversation_closed 排在这个对话最后一个 conversation_turn 之后（与 center 的 callback_seq 一致）。
+    if (next.job && !TERMINAL_JOB.has(next.job.status)) seenOpen.add(jobId);
+    if (next.job && TERMINAL_JOB.has(next.job.status) && seenOpen.has(jobId) && !closedJobs.has(jobId)) {
+      const settled = next.turns.every((turn) => TERMINAL_TURN.has(turn.status));
+      if (settled || next.stream === "ended") {
+        closedJobs.add(jobId);
+        emit({ type: "conversation_closed", jobId, reason: next.job.closed_reason, continuedBy: next.continuedBy, payload: closedCallback(next) });
+      }
+    }
+    // 实时流里的对话状态同步给列表。
+    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（列表位置不变，选中跟过去）。 */
+  function replaceJob(oldId: string, newId: string) {
+    if (oldId === newId) return;
+    const ids = state.jobIds.includes(oldId) ? state.jobIds.map((id) => (id === oldId ? newId : id)) : [newId, ...state.jobIds];
+    set({ jobIds: [...new Set(ids)], selected: state.selected === oldId ? newId : state.selected });
+    persist(state.jobIds);
+    emit({ type: "job_change", jobId: newId, previousJobId: oldId });
+    void refreshJob(newId, 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") {
+        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() });
+      // 新数据里已包含实时用量，清零累计。
+      if (state.convs[jobId]) patchConv(jobId, (conv) => ({ ...conv, 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 !== 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(jobId: string) {
+    const entry = streams.get(jobId);
+    if (!entry || entry.refs <= 0) return;
+    patchConv(jobId, (conv) => ({ ...conv, stream: entry.attempt ? "reconnecting" : "connecting", streamError: null }));
+    let ended = false;
+    entry.stop = client.stream(jobId, {
+      onOpen: () => { entry.attempt = 0; patchConv(jobId, (conv) => ({ ...conv, stream: "live", streamError: null })); },
+      onSnapshot: (snapshot) => patchConv(jobId, (conv) => applySnapshot(conv, snapshot)),
+      onChunk: (items) => patchConv(jobId, (conv) => applyItems(conv, items)),
+      onEnd: (end) => {
+        ended = true;
+        patchConv(jobId, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy: end.continued_by_job_id ?? null, nodeRunning: false }));
+        void refreshJob(jobId, true);
+      },
+      onClose: (error) => {
+        entry.stop = null;
+        const current = streams.get(jobId);
+        if (!current || current.refs <= 0) return;
+        // 对话结束（end）不再连；中枢停机（server_shutdown）稍后重连。
+        if (ended && state.convs[jobId]?.endReason !== "server_shutdown") return;
+        // 404 / 401：对话不存在或没权限，重连也没用。
+        if (error && (error.status === 404 || error.status === 401 || error.status === 403)) {
+          patchConv(jobId, (conv) => ({ ...conv, stream: "error", streamError: error.message }));
+          emit({ type: "error", jobId, error });
+          return;
+        }
+        const delay = RECONNECT_MS[Math.min(current.attempt, RECONNECT_MS.length - 1)];
+        current.attempt += 1;
+        patchConv(jobId, (conv) => ({ ...conv, stream: "reconnecting", streamError: error?.message ?? null }));
+        current.timer = setTimeout(() => { current.timer = null; connect(jobId); }, delay);
+      },
+    });
+  }
+
+  // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
+  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(); });
+  }
+
+  /** 开始看一个对话（返回停止函数）。同一对话多处同时看只连一次。 */
+  function open(jobId: string): () => void {
+    let entry = streams.get(jobId);
+    if (!entry) {
+      entry = { refs: 0, stop: null, timer: null, attempt: 0 };
+      streams.set(jobId, entry);
+    }
+    entry.refs += 1;
+    if (entry.refs === 1) {
+      void refreshJob(jobId);
+      connect(jobId);
+    }
+    return () => {
+      const current = streams.get(jobId);
+      if (!current) return;
+      current.refs -= 1;
+      if (current.refs > 0) return;
+      current.stop?.();
+      if (current.timer) clearTimeout(current.timer);
+      streams.delete(jobId);
+      patchConv(jobId, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
+    };
+  }
+
+  // ── 发消息 / 新建 / 撤回 / 结束 ───────────────────────
+
+  /**
+   * 发一条消息。jobId 为 null 时新建对话（这条就是第一轮）。返回实际接收消息的对话 id。
+   * 带 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(jobId: 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 businessId = businessIdFor?.(text, jobId ? "message" : "create") || `cli-${uid()}`;
+    try {
+      if (!jobId) {
+        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: upsertTurns(conv.turns, created.turn ? [created.turn] : []) }));
+        }
+        addJob(newId);
+        // 共享选中只由「跟着选中走」的组件改；传了 jobId、自己接管的对话组件新建对话不去动别人的选中。
+        if (overrides.select !== false) set({ selected: newId });
+        emit({ type: "job_change", jobId: newId, previousJobId: null });
+        void refreshJob(newId, true);
+        return newId;
+      }
+      const result = await retryOnce(() => client.sendMessage(jobId, text, { businessId }));
+      const target = result.job_id || jobId;
+      if (result.new_conversation && target !== jobId) replaceJob(jobId, target);
+      // 先把这一轮放进状态：排队气泡立刻出现，不用等实时流的下一个块。
+      patchConv(target, (conv) => ({ ...conv, turns: upsertTurns(conv.turns, [{ ...result.turn, queue_position: result.queue_position }]) }));
+      if (target === jobId) addJobIfMissing(jobId);
+      return target;
+    } catch (error) {
+      const err = error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0);
+      emit({ type: "error", jobId, 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(jobId: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions = {}): Promise<string> {
+    // 与 Operator 的 answerQuestion 同一流程：先乐观标成已答 → 交给正在等的回合 → 没有在等的回合就当普通回复发出。
+    patchConv(jobId, (conv) => ({ ...conv, localAnswers: { ...conv.localAnswers, [askId]: answers } }));
+    try {
+      if (askId && client.answerAsk) {
+        const { resolved } = await client.answerAsk(jobId, askId, answers);
+        if (resolved) return jobId;
+      }
+      return await send(jobId, formatAnswersText(questions, answers), overrides);
+    } catch (error) {
+      // 没发出去：卡片恢复成可回答。
+      patchConv(jobId, (conv) => {
+        const { [askId]: _drop, ...rest } = conv.localAnswers;
+        return { ...conv, localAnswers: rest };
+      });
+      throw error;
+    }
+  }
+
+  async function cancelTurn(jobId: string, turnId: string) {
+    try {
+      const turn = await client.cancelTurn(jobId, turnId);
+      patchConv(jobId, (conv) => ({ ...conv, turns: upsertTurns(conv.turns, [turn]) }));
+    } catch (error) {
+      const err = error instanceof CenterError ? error : new CenterError(String(error), "UNKNOWN", 0);
+      emit({ type: "error", jobId, error: err });
+      throw err;
+    }
+  }
+
+  async function close(jobId: string) {
+    try {
+      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, error: err });
+      throw err;
+    }
+  }
+
+  return {
+    client,
+    getState: () => state,
+    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)}`;
+}