@spzxg/cli-ui 0.4.0 → 0.6.0

package/src/core/store.ts

@@ -11,8 +11,10 @@
  * 单独用某个组件时它会自己建一个仓库；放进同一个 <CliCenterProvider>（或同一个 group 的 Web Component）就共享一个。
  */
 import { CenterError, createCenterClient, firstLine, type CenterClient, type CenterClientOptions } from "./client.js";
-import { addTurnsIfAbsent, applyItems, applySnapshot, closedCallback, convEnded, convKey, emptyConv, isChatTask, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation.js";
+import { addTurnsIfAbsent, applyItems, applyOlderPage, applySnapshot, closedCallback, convEnded, convKey, emptyConv, isChatTask, NEW_TASK, parseConvKey, TERMINAL_JOB, TERMINAL_TURN, turnCallback, upsertTurns, type ConvState } from "./conversation.js";
 import { formatAnswersText } from "../ui/format.js";
+import { backgroundBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "./blocks.js";
+import { createWorkspace, type BoardView, type CliWorkspace } from "../board/workspace.js";
 import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types.js";
 
 export interface JobEntry {
@@ -35,6 +37,44 @@ export interface CliState {
   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>;
+  /** 业务方补充的项目背景（按对话键；"" = 还没建的新对话），随下一条消息发出（见 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 回调同名同义的事件，方便宿主把前端事件和后端回调对上。 */
@@ -55,16 +95,27 @@ export type CliEvent =
    * 有人要在看板里打开东西（对话里点了本地文件链接、「查看浏览器」，或宿主调了 store.openInBoard）。
    * handled = 有看板接住了；没有时对话组件自己弹窗打开。宿主可以据此展开右侧面板。
    */
-  | { type: "open"; jobId: string; target: OpenTarget; handled: boolean };
+  | { 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 }
+  /**
+   * 补充背景变了：追加 / 去掉（pending 是还没发出的），或随消息发出了（sent 是这次发出的）。
+   * key 是对话键；新对话还没建时是 ""。
+   */
+  | { type: "context"; key: string; pending: ContextItem[]; sent?: ContextItem[] };
 
 /** 看板要打开的东西。 */
-export type OpenTarget = { kind: "file"; path: string } | { kind: "browser" } | { kind: "changes" } | { kind: "files"; path?: string };
+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、工作区、回调、智能体、超时、浏览器模式。
@@ -90,14 +141,65 @@ export interface SendOptions {
 }
 
 const RECONNECT_MS = [1_000, 2_000, 5_000, 10_000, 20_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：多半是宿主的登录会话过期了。宿主续上会话后要能自己恢复，所以慢慢重试，不永久放弃。 */
+const AUTH_RETRY_MS = 30_000;
+
+// 全局只挂一份「网络恢复 / 切回页面」监听，转给当前有实时流的仓库。
+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);
+  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);
+  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 才在本机记住对话列表：不给就不落任何共享状态，几个独立的组件互不影响。
-  const storageKey = options.namespace ? `cli-ui:${options.namespace}:jobs` : null;
+  // 列表只放宿主给的 jobIds 和本页里新建 / 接续出来的对话：不从 center 发现，也不从本地存储恢复——
+  // 不传就不加载，免得把这个产品线令牌下别的业务、别的用户的对话列出来。
 
-  let state: CliState = { selected: null, jobIds: loadIds(storageKey), jobs: {}, convs: {}, listLoading: false, listError: null };
+  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, context: {} };
   const listeners = new Set<() => void>();
   const eventListeners = new Set<(event: CliEvent) => void>();
   const settledTurns = new Set<string>();
@@ -158,6 +260,8 @@ export function createCliStore(options: CliStoreOptions = {}) {
         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];
@@ -165,11 +269,6 @@ export function createCliStore(options: CliStoreOptions = {}) {
     }
   }
 
-  function persist(ids: string[]) {
-    if (!storageKey || hostIds) return;
-    try { localStorage.setItem(storageKey, JSON.stringify(ids.slice(0, 200))); } catch { /* 存不下就不记 */ }
-  }
-
   // ── 列表 ─────────────────────────────────────────────
 
   function setJobIds(ids: string[]) {
@@ -183,13 +282,11 @@ export function createCliStore(options: CliStoreOptions = {}) {
     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 可以是对话键。 */
@@ -200,7 +297,6 @@ export function createCliStore(options: CliStoreOptions = {}) {
     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);
   }
@@ -245,50 +341,16 @@ export function createCliStore(options: CliStoreOptions = {}) {
         const status = state.jobs[id]?.job?.status;
         return !status || !TERMINAL_JOB.has(status);
       });
-      await runLimited(ids, 4, (id) => refreshJob(id, true));
+      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) });
     }
   }
 
-  /**
-   * 从 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 }>();
+  const streams = new Map<string, { refs: number; stop: (() => void) | null; timer: ReturnType<typeof setTimeout> | null; attempt: number; parked?: boolean }>();
 
   function connect(key: string) {
     const entry = streams.get(key);
@@ -313,23 +375,33 @@ export function createCliStore(options: CliStoreOptions = {}) {
         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)) {
+        // 404：对话不存在，重连也没用。
+        if (error && error.status === 404) {
           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)) {
+          patchConv(key, (conv) => ({ ...conv, stream: "error", streamError: error.message }));
+          if (current.attempt === 0) emit({ type: "error", jobId: key, error });
+          current.attempt += 1;
+          current.timer = setTimeout(() => { current.timer = null; connect(key); }, jitter(AUTH_RETRY_MS));
+          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);
+        current.timer = setTimeout(() => { current.timer = null; connect(key); }, jitter(delay));
       },
     }, undefined, taskId);
   }
 
   // 网络恢复 / 标签页切回来时，正在退避等待的连接立刻重连，不用等完退避时间。
+  // 只在有实时流时登记到全局（见 watchReconnect）：组件卸载、流都关了就撤掉，宿主单页应用里反复挂载组件不会越积越多。
   function reconnectNow() {
     for (const [jobId, entry] of streams) {
+      if (entry.parked && entry.refs > 0) { entry.parked = false; entry.attempt = 0; connect(jobId); continue; }
       if (!entry.timer) continue;
       clearTimeout(entry.timer);
       entry.timer = null;
@@ -337,10 +409,18 @@ export function createCliStore(options: CliStoreOptions = {}) {
       connect(jobId);
     }
   }
-  if (typeof window !== "undefined") {
-    window.addEventListener("online", reconnectNow);
-    document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") reconnectNow(); });
+  // 页面在后台太久：停掉实时流（主动停止不算断线，不会触发重连），切回来由 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; }
+      entry.stop?.();
+      entry.stop = null;
+      entry.parked = true;
+    }
   }
+  const syncLive = () => { if (streams.size) watchReconnect(reconnectNow, parkAll); else unwatchReconnect(reconnectNow, parkAll); };
 
   /**
    * 开始看一个对话（对话键；返回停止函数）。同一对话多处同时看只连一次。
@@ -356,6 +436,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
     if (!entry) {
       entry = { refs: 0, stop: null, timer: null, attempt: 0 };
       streams.set(key, entry);
+      syncLive();
     }
     entry.refs += 1;
     if (entry.refs === 1) {
@@ -370,6 +451,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
       current.stop?.();
       if (current.timer) clearTimeout(current.timer);
       streams.delete(key);
+      syncLive();
       patchConv(key, (conv) => ({ ...conv, stream: conv.stream === "ended" ? "ended" : "idle" }));
     };
   }
@@ -393,7 +475,34 @@ export function createCliStore(options: CliStoreOptions = {}) {
     return run;
   }
 
-  async function sendNow(key: string | null, text: string, overrides: SendOptions): Promise<string> {
+  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 });
+      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 newConversation = overrides.newConversation ?? options.newConversation;
     const createConversation = overrides.createConversation ?? options.createConversation;
@@ -431,8 +540,8 @@ export function createCliStore(options: CliStoreOptions = {}) {
         return newId;
       }
       const shown = state.convs[key];
-      if (ref.taskId && isChatTask(shown)) {
-        // 一次性任务里的对话式子任务：续派一条接着它的对话（中枢接到这个对话最新的那条后面），对话键不变。
+      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 });
@@ -471,7 +580,8 @@ export function createCliStore(options: CliStoreOptions = {}) {
    * 所以回答作为下一条消息发出——与 Operator 在没有等待中的回合时（/answer 返回 resolved=false）的做法一致；
    * 卡片先在本地标成已答（Operator 同样是先乐观更新）。
    */
-  async function answerAsk(key: string, askId: string, questions: AskQuestion[], answers: AskAnswers, overrides: SendOptions = {}): Promise<string> {
+  /** 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 {
@@ -479,6 +589,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
         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) {
       // 没发出去：卡片恢复成可回答。
@@ -524,8 +635,164 @@ export function createCliStore(options: CliStoreOptions = {}) {
     }
   }
 
+  /**
+   * 往上翻：取这个对话更早的一页节点消息，接在最前面。实时流只给最新一段（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: BoardSurface[] = [];
+  // ── 看板 → 对话的引用 ─────────────────────────────
+
+  function setRefs(key: string, refs: BoardRef[]) {
+    const next = { ...state.refs };
+    if (refs.length) next[key] = refs; 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 reportBoard(key: string, view: BoardView | null, owner = "default") {
+    const top = latestReport(boardSources, key, owner, view ? { ...view, files: [...view.files] } : null);
+    const cur = state.boards[key];
+    if (!top && !cur) return;
+    if (top && cur && cur.tab === top.tab && cur.dir === top.dir && cur.file === top.file && cur.files.join("\n") === top.files.join("\n")) return;
+    const next = { ...state.boards };
+    if (top) next[key] = top; else delete next[key];
+    set({ boards: next });
+    emit({ type: "board_change", key, view: top ? { ...top, files: [...top.files] } : null });
+  }
+
+  // ── 补充背景：业务方随时追加，随下一条消息发给智能体 ────────
+  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)] ?? [])];
+
+  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],
+      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): boolean {
     let handled = false;
     for (let i = surfaces.length - 1; i >= 0 && !handled; i--) handled = surfaces[i](jobId, target);
@@ -550,22 +817,21 @@ export function createCliStore(options: CliStoreOptions = {}) {
       set({ selected: jobId });
       emit({ type: "select", jobId });
     },
-    setJobIds, addJob, removeJob, replaceJob, refreshJob, refreshAll, discover,
-    open, send, answerAsk, cancelTurn, close,
+    setJobIds, addJob, removeJob, replaceJob, refreshJob, refreshAll,
+    addRef, removeRef, takeRefs, restoreRefs,
+    setViewing, dismissViewing, takeViewing, restoreViewing,
+    /** 看板报告自己的样子（看板组件用）。 */
+    reportBoard,
+    /** 业务方追加项目背景：随下一条消息发给智能体。 */
+    appendContext, removeContext, pendingContext,
+    /** 工作区文件接口（不显示看板也能用）：列文件、读文件、下载、打包。不传 = 当前选中的对话。 */
+    workspace,
+    open, send, answerAsk, cancelTurn, close, loadOlder,
   };
 }
 
 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;
@@ -575,6 +841,9 @@ async function runLimited<T>(items: T[], limit: number, fn: (item: T) => Promise
   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 {

package/src/core/textDecode.ts

@@ -0,0 +1,24 @@
+/**
+ * 工作区文本文件的解码：智能体写的多是 UTF-8，但业务导出的 CSV / TXT 常常是 GBK（GB18030），
+ * 按 UTF-8 硬解会满屏乱码。顺序：BOM（UTF-8 / UTF-16）→ 严格 UTF-8 → GB18030。
+ *
+ * 只读了文件的一段（开头 / 末尾）时：开头那段末尾可能切在一个字中间——按流式解码，把不完整的尾巴留下不报错；
+ * 末尾那段开头可能切在一个 UTF-8 字中间——跳过开头最多 3 个续字节。
+ */
+export function decodeText(bytes: Uint8Array, opts: { fromMiddle?: boolean } = {}): { text: string; encoding: string } {
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) return { text: new TextDecoder("utf-8").decode(bytes.subarray(3), { stream: true }), encoding: "utf-8" };
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) return { text: new TextDecoder("utf-16le").decode(bytes.subarray(2), { stream: true }), encoding: "utf-16le" };
+  if (bytes[0] === 0xfe && bytes[1] === 0xff) return { text: new TextDecoder("utf-16be").decode(bytes.subarray(2), { stream: true }), encoding: "utf-16be" };
+  let start = 0;
+  if (opts.fromMiddle) while (start < 3 && start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  const body = bytes.subarray(start);
+  try {
+    return { text: new TextDecoder("utf-8", { fatal: true }).decode(body, { stream: true }), encoding: "utf-8" };
+  } catch {
+    try {
+      return { text: new TextDecoder("gb18030").decode(bytes, { stream: true }), encoding: "gb18030" };
+    } catch {
+      return { text: new TextDecoder("utf-8").decode(body, { stream: true }), encoding: "utf-8" };
+    }
+  }
+}