@spzxg/cli-ui 0.1.0 → 0.3.0

package/src/core/store.ts

@@ -2,13 +2,16 @@
  * 组件共享的状态仓库（纯 TS，无 React）。积木之间靠它拼起来：
  *
  *   · 选中哪个对话（cli-msglist 点一下，cli-chat 跟着切）；
- *   · 列表里有哪些对话（宿主给 jobIds，或本地记住 + 从 center 发现）；
+ *   · 列表里有哪些对话任务（宿主给 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 { applyItems, applySnapshot, closedCallback, emptyConv, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation.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";
 
@@ -22,9 +25,13 @@ export interface JobEntry {
 }
 
 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;
@@ -32,14 +39,28 @@ export interface CliState {
 
 /** 与 center 回调同名同义的事件，方便宿主把前端事件和后端回调对上。 */
 export type CliEvent =
+  /** jobId 是选中的对话键（只有 job_id，或 "job_id#task_id"）。 */
   | { 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 };
+  /** 一轮结束。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;
@@ -80,6 +101,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
   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;
@@ -89,12 +111,12 @@ export function createCliStore(options: CliStoreOptions = {}) {
     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 patchConv = (key: string, fn: (conv: ConvState) => ConvState) => {
+    const prev = state.convs[key] ?? emptyConv(key);
     const next = fn(prev);
     if (next !== prev) {
-      noticeTransitions(jobId, prev, next);
-      set({ convs: { ...state.convs, [jobId]: next } });
+      noticeTransitions(key, prev, next);
+      set({ convs: { ...state.convs, [key]: next } });
     }
   };
   const patchJob = (jobId: string, patch: Partial<JobEntry>) => {
@@ -103,32 +125,36 @@ export function createCliStore(options: CliStoreOptions = {}) {
   };
 
   // 一轮从未结束变成结束 → conversation_turn；对话变成结束 → conversation_closed。
-  function noticeTransitions(jobId: string, prev: ConvState, next: ConvState) {
+  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) || settledTurns.has(turn.turn_id)) continue;
+        if (!TERMINAL_TURN.has(turn.status)) break;
+        if (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);
-        }
+        // 被合并进别的轮次的消息不单独发（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 && !TERMINAL_JOB.has(next.job.status)) seenOpen.add(jobId);
-    if (next.job && TERMINAL_JOB.has(next.job.status) && seenOpen.has(jobId) && !closedJobs.has(jobId)) {
+    // 对话结束（整个对话任务结束，或只关掉了这一个对话）：只对本页看着还开着的对话发（打开时就已结束的不算）；
+    // 而且要等所有轮次都收尾之后再发，保证 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(jobId);
-        emit({ type: "conversation_closed", jobId, reason: next.job.closed_reason, continuedBy: next.continuedBy, payload: closedCallback(next) });
+        closedJobs.add(key);
+        const payload = closedCallback(next);
+        emit({ type: "conversation_closed", jobId, key, reason: payload.closed_reason, continuedBy: next.continuedBy, payload });
       }
     }
     // 实时流里的对话状态同步给列表。
@@ -165,14 +191,17 @@ export function createCliStore(options: CliStoreOptions = {}) {
     persist(ids);
   }
 
-  /** 对话接续：旧 job 换成新 job（列表位置不变，选中跟过去）。 */
+  /** 对话接续：旧 job 换成新 job（列表位置不变，选中跟过去）。oldId / newId 可以是对话键。 */
   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];
+    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: newId, previousJobId: oldId });
-    void refreshJob(newId, true);
+    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>();
@@ -186,16 +215,17 @@ export function createCliStore(options: CliStoreOptions = {}) {
       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() });
-      // 新数据里已包含实时用量，清零累计。
-      if (state.convs[jobId]) patchConv(jobId, (conv) => ({ ...conv, liveUsage: { fresh: 0, cacheRead: 0 } }));
+      // 新数据里已包含实时用量，清零累计（这个对话任务里的每个对话）。
+      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 !== jobId) {
+      if (!hostIds && error instanceof CenterError && error.status === 404 && (!state.selected || parseConvKey(state.selected).jobId !== jobId)) {
         refreshAgain.delete(jobId);
         removeJob(jobId);
         return;
@@ -259,38 +289,41 @@ export function createCliStore(options: CliStoreOptions = {}) {
 
   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);
+  function connect(key: string) {
+    const entry = streams.get(key);
     if (!entry || entry.refs <= 0) return;
-    patchConv(jobId, (conv) => ({ ...conv, stream: entry.attempt ? "reconnecting" : "connecting", streamError: null }));
+    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(jobId, (conv) => ({ ...conv, stream: "live", streamError: null })); },
-      onSnapshot: (snapshot) => patchConv(jobId, (conv) => applySnapshot(conv, snapshot)),
-      onChunk: (items) => patchConv(jobId, (conv) => applyItems(conv, items)),
+      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;
-        patchConv(jobId, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy: end.continued_by_job_id ?? null, nodeRunning: false }));
+        // 接续的新对话：指定了对话的跟到接续它的那个对话（还没有就不跟，再发消息时 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(jobId);
+        const current = streams.get(key);
         if (!current || current.refs <= 0) return;
         // 对话结束（end）不再连；中枢停机（server_shutdown）稍后重连。
-        if (ended && state.convs[jobId]?.endReason !== "server_shutdown") return;
+        if (ended && state.convs[key]?.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 });
+          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(jobId, (conv) => ({ ...conv, stream: "reconnecting", streamError: error?.message ?? null }));
-        current.timer = setTimeout(() => { current.timer = null; connect(jobId); }, delay);
+        patchConv(key, (conv) => ({ ...conv, stream: "reconnecting", streamError: error?.message ?? null }));
+        current.timer = setTimeout(() => { current.timer = null; connect(key); }, delay);
       },
-    });
+    }, undefined, taskId);
   }
 
   // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
@@ -308,35 +341,43 @@ export function createCliStore(options: CliStoreOptions = {}) {
     document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") reconnectNow(); });
   }
 
-  /** 开始看一个对话（返回停止函数）。同一对话多处同时看只连一次。 */
-  function open(jobId: string): () => void {
-    let entry = streams.get(jobId);
+  /**
+   * 开始看一个对话（对话键；返回停止函数）。同一对话多处同时看只连一次。
+   * "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(jobId, entry);
+      streams.set(key, entry);
     }
     entry.refs += 1;
     if (entry.refs === 1) {
       void refreshJob(jobId);
-      connect(jobId);
+      connect(key);
     }
     return () => {
-      const current = streams.get(jobId);
+      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(jobId);
-      patchConv(jobId, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
+      streams.delete(key);
+      patchConv(key, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
     };
   }
 
   // ── 发消息 / 新建 / 撤回 / 结束 ───────────────────────
 
   /**
-   * 发一条消息。jobId 为 null 时新建对话（这条就是第一轮）。返回实际接收消息的对话 id。
-   * 带 business_id 发：网络抖动时重发一次也只会跑一轮。
+   * 发一条消息。key 是对话键：null 时新建对话任务（这条就是第一轮）；"job#new" 时在这个对话任务里新开一个对话。
+   * 返回实际接收消息的对话键。带 business_id 发：网络抖动时重发一次也只会跑一轮。
    */
   // 同一个对话的消息严格按发出的顺序送到 center（输入框、提问卡片、重试可能同时发）：
   // center 按到达顺序给轮次编号，并发发出去可能后发先到。每个对话一条队列，前一条失败不挡后面的。
@@ -351,14 +392,27 @@ export function createCliStore(options: CliStoreOptions = {}) {
     return run;
   }
 
-  async function sendNow(jobId: string | null, text: string, overrides: SendOptions): Promise<string> {
+  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 businessId = businessIdFor?.(text, jobId ? "message" : "create") || `cli-${uid()}`;
+    const ref = key ? parseConvKey(key) : null;
+    const businessId = businessIdFor?.(text, ref && ref.taskId !== NEW_TASK ? "message" : "create") || `cli-${uid()}`;
     try {
-      if (!jobId) {
+      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);
@@ -366,25 +420,27 @@ export function createCliStore(options: CliStoreOptions = {}) {
           // 新建只发一次：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] : []) }));
+          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 });
+        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(jobId, text, { businessId }));
-      const target = result.job_id || jobId;
-      if (result.new_conversation && target !== jobId) replaceJob(jobId, target);
+      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: upsertTurns(conv.turns, [{ ...result.turn, queue_position: result.queue_position }]) }));
-      if (target === jobId) addJobIfMissing(jobId);
+      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, error: err });
+      emit({ type: "error", jobId: key, error: err });
       throw err;
     }
   }
@@ -398,18 +454,18 @@ export function createCliStore(options: CliStoreOptions = {}) {
    * 所以回答作为下一条消息发出——与 Operator 在没有等待中的回合时（/answer 返回 resolved=false）的做法一致；
    * 卡片先在本地标成已答（Operator 同样是先乐观更新）。
    */
-  async function answerAsk(jobId: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions = {}): Promise<string> {
+  async function answerAsk(key: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions = {}): Promise<string> {
     // 与 Operator 的 answerQuestion 同一流程：先乐观标成已答 → 交给正在等的回合 → 没有在等的回合就当普通回复发出。
-    patchConv(jobId, (conv) => ({ ...conv, localAnswers: { ...conv.localAnswers, [askId]: answers } }));
+    patchConv(key, (conv) => ({ ...conv, localAnswers: { ...conv.localAnswers, [askId]: answers } }));
     try {
       if (askId && client.answerAsk) {
-        const { resolved } = await client.answerAsk(jobId, askId, answers);
-        if (resolved) return jobId;
+        const { resolved } = await client.answerAsk(key, askId, answers);
+        if (resolved) return key;
       }
-      return await send(jobId, formatAnswersText(questions, answers), overrides);
+      return await send(key, formatAnswersText(questions, answers), overrides);
     } catch (error) {
       // 没发出去：卡片恢复成可回答。
-      patchConv(jobId, (conv) => {
+      patchConv(key, (conv) => {
         const { [askId]: _drop, ...rest } = conv.localAnswers;
         return { ...conv, localAnswers: rest };
       });
@@ -417,31 +473,59 @@ export function createCliStore(options: CliStoreOptions = {}) {
     }
   }
 
-  async function cancelTurn(jobId: string, turnId: string) {
+  async function cancelTurn(key: string, turnId: string) {
     try {
-      const turn = await client.cancelTurn(jobId, turnId);
-      patchConv(jobId, (conv) => ({ ...conv, turns: upsertTurns(conv.turns, [turn]) }));
+      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, error: err });
+      emit({ type: "error", jobId: key, error: err });
       throw err;
     }
   }
 
-  async function close(jobId: string) {
+  /** 结束对话：指定了对话（"job#task"）的只关掉这一个；只有 job_id 的结束整个对话任务（和以前一样）。 */
+  async function close(key: string) {
+    const { jobId, taskId } = parseConvKey(key);
     try {
-      await client.closeConversation(jobId);
+      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, error: err });
+      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) {

package/src/core/types.ts

@@ -46,6 +46,7 @@ export interface CenterTurn {
 export interface CenterTask {
   id: string;
   job_id: string;
+  seq?: number;
   title: string;
   status: string;
   agent: string | null;
@@ -57,9 +58,30 @@ export interface CenterTask {
   cache_creation_tokens: number;
   browser?: boolean;
   last_error: string | null;
+  /** 接续出来的对话：指回旧对话任务里对应的那个对话。 */
+  continue_from_task_id?: string;
+}
+
+/** 对话任务里的一个对话（一个子任务、一个 Agent 会话）。conversation.conversations 的一项。 */
+export interface ConversationInfo {
+  task_id: string;
+  seq: number;
+  title: string;
+  status: string;
+  /** 关掉了（单独关闭这一个，或整个对话任务结束）。 */
+  closed: boolean;
+  turns: number;
+  queued_turns: number;
+  running_turn: boolean;
+  last_turn: CenterTurn | null;
+  remote_task_id: string | null;
+  continue_from_task_id: string | null;
+  created_at: string | null;
 }
 
 export interface ConversationSummary {
+  /** 里面的每个对话（按开的先后）。旧版 center 没有这个字段：当作只有一个对话。 */
+  conversations?: ConversationInfo[];
   turns: number;
   queued_turns: number;
   running_turn: boolean;
@@ -81,9 +103,11 @@ export interface CenterJob {
   tasks: CenterTask[];
 }
 
-/** POST /api/jobs/:id/messages */
+/** POST /api/jobs/:id/messages、POST /api/jobs/:id/conversations */
 export interface SendResult {
   job_id: string;
+  /** 实际接收这条消息的对话（对话任务过期接续后是新对话任务里对应的那个）。 */
+  task_id?: string;
   status: JobStatus;
   duplicate: boolean;
   /** true = 原对话已结束，这条消息开了一个新对话（job_id 是新的）。 */
@@ -202,16 +226,27 @@ export type StreamItem =
   | { type: "transcript"; messages: Message[] | null; pending: PendingMessage[] | null; running: boolean | null }
   | { type: "node"; event: NodeEvent }
   | { type: "turn"; turn: CenterTurn }
-  | { type: "job"; job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null } };
+  | { type: "job"; job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null } }
+  /** 正在看的这个对话的状态变化（关闭了：closed=true）。 */
+  | { type: "task"; task: StreamTask };
+
+/** 实时流看的那个对话（GET /api/jobs/:id/stream?task=）。 */
+export interface StreamTask { id: string; seq: number; title: string; status: string; closed: boolean; remote_task_id: string | null; continue_from_task_id: string | null }
 
 export interface StreamSnapshot {
   job: { id: string; status: JobStatus; closed_reason: string | null; node_id: string | null; mode: string; title: string; conversation: ConversationSummary };
+  /** 旧版 center 没有。 */
+  task?: StreamTask;
   turns: CenterTurn[];
 }
 
 export interface StreamEnd {
+  /** 对话任务的结束原因；只是这个对话被关闭时为 conversation_closed。 */
   reason: string;
+  task_id?: string;
   continued_by_job_id?: string | null;
+  /** 接续这个对话的新对话（新对话任务里的子任务）；还没有为 null。 */
+  continued_by_task_id?: string | null;
 }
 
 // ── center 回调体（与中枢 conversation.ts turnCallbackPayload / job-callback.ts 的字段一一对应） ──
@@ -264,6 +299,8 @@ export interface ConversationClosedCallback {
   /** 投递顺序号：最后一轮的 seq + 1，永远排在这个对话所有 conversation_turn 之后。 */
   callback_seq: number;
   job_id: string;
+  /** 只关掉了对话任务里的这一个对话时才有（前端事件；center 只在整个对话任务结束时回调）。 */
+  task_id?: string;
   /** succeeded（关闭 / 过期 / 换线）/ cancelled / failed。 */
   status: JobStatus;
   /** closed / cancelled / expired / node_reassigned / node_lost。 */
@@ -276,3 +313,73 @@ export interface ConversationClosedCallback {
 }
 
 export type ConversationCallback = ConversationTurnCallback | ConversationClosedCallback;
+
+/** 一轮结束时 onTurnEnd 收到的载荷（字段与 center 的 conversation_turn 回调体一致）。 */
+export type TurnEndPayload = ConversationTurnCallback;
+/** 对话结束时 onConversationEnd 收到的载荷（字段与 center 的 conversation_closed 回调体一致）。 */
+export type ConversationEndPayload = ConversationClosedCallback;
+
+// ── 右侧看板（cli-board）：center 的 /api/jobs/:id/board、files、diff、browser ──
+
+export interface BoardInfo {
+  job_id: string;
+  /** false = 还没派发到执行节点（文件和浏览器都还没有）。 */
+  dispatched: boolean;
+  detail?: string;
+  task_id?: string;
+  remote_task_id?: string;
+  node?: { id: string; health: string };
+  files: boolean;
+  /** 节点开了浏览器功能。 */
+  browser: boolean;
+}
+
+export interface FileEntry {
+  name: string;
+  /** 相对工作目录的路径，用 / 分隔。 */
+  path: string;
+  type: "dir" | "file";
+  size: number;
+  mtime: number;
+}
+
+export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean }
+export interface FileInfo { type: "file"; path: string; name: string; size: number; mtime: number; contentType: string; inline: boolean }
+
+export interface DiffFile { path: string; status: string; additions: number; deletions: number; binary: boolean; patch: string; truncated?: boolean }
+/** Operator 的 /api/tasks/:id/diff（经 center 原样转发）。 */
+export interface DiffResult {
+  isolated?: boolean;
+  reason?: string;
+  branch?: string;
+  baseLabel?: string;
+  files?: DiffFile[];
+  isDirty?: boolean;
+  ahead?: number;
+  alreadyMerged?: boolean;
+  error?: string;
+  /** 有的节点只给一整段 unified diff。 */
+  diff?: string;
+  patch?: string;
+}
+
+/** Operator 的任务浏览器状态（/api/tasks/:id/browser）。 */
+export interface BrowserStatus {
+  feature: boolean;
+  state: "none" | "opening" | "running" | "closing";
+  origin: "ai" | "manual" | "check" | null;
+  control: "ai" | "human";
+  handoff: { instruction: string; by: "ai" | "user" | "browser" | "kept" } | null;
+  capability: "config" | "manual" | "ai" | null;
+  viewers: number;
+  spaceName: string;
+  instance: { running: boolean; spaces: number };
+  shownLocally: boolean;
+  error: string | null;
+}
+
+/** 浏览器画面流里的一条消息（节点原样转发）。 */
+export type BrowserMessage =
+  | { type: "frame"; data: string; metadata?: { deviceWidth: number; deviceHeight: number } }
+  | { type: "page"; url?: string; title?: string }
+  | { type: "error"; message?: string };