@spzxg/cli-ui 0.3.1 → 0.6.0

package/src/core/client.ts

@@ -1,9 +1,10 @@
 import { createSseParser } from "./sse.js";
 import { NEW_TASK, parseConvKey } from "./conversation.js";
 import type {
-  BoardInfo, BrowserMessage, BrowserStatus, CenterJob, CenterTask, CenterTurn, DiffResult, DirListing, FileInfo,
-  BatchStreamSnapshot, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot,
+  BoardInfo, BrowserMessage, BrowserStatus, CenterJob, CenterTask, CenterTurn, DiffResult, DirListing, FileInfo, Message,
+  BatchStreamSnapshot, BrowserFramesState, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot,
 } from "./types.js";
+import { decodeText } from "./textDecode.js";
 
 /**
  * center 服务（cli-task-center）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
@@ -33,10 +34,19 @@ export interface CenterClientOptions {
    * （同源代理注入令牌）；否则浏览器直接请求带不上请求头，看板改为先 fetch 再用 blob 地址显示。
    */
   directFileLinks?: boolean;
+  /**
+   * 普通请求（不含实时流、文件下载）多久没有响应就放弃，缺省 30 秒。代理或网络挂住时组件不会一直「读取中」，
+   * 而是报「请求超时」并按各自的规则重试。打开任务浏览器另给 150 秒（节点要先启动浏览器）。
+   */
+  requestTimeoutMs?: number;
 }
 
 /** 实时流超过这么久没有任何数据（center 每 20 秒一次心跳）就当连接已断。 */
 export const STREAM_SILENCE_MS = 45_000;
+/** 读文件：这么久没回响应头（节点卡住、代理挂住）就放弃。 */
+export const FILE_HEADER_TIMEOUT_MS = 30_000;
+/** 读文件：传输中这么久一个字节都没收到就当断了（大文件慢慢传不算，只要还在动）。 */
+export const FILE_STALL_MS = 60_000;
 
 export class CenterError extends Error {
   constructor(message: string, readonly code: string, readonly status: number, readonly detail?: unknown) {
@@ -63,6 +73,8 @@ const ERROR_TEXT: Record<string, string> = {
   too_many_viewers: "同时观看这个浏览器的人太多，请稍后再试",
   viewer_not_found: "画面连接已断开，正在重连",
   viewer_not_ready: "画面连接还没就绪，正在重连",
+  link_expired: "文件链接已失效，请刷新",
+  task_not_found: "这个子任务不在对应的任务里",
 };
 
 /**
@@ -77,9 +89,19 @@ export interface ConversationBackend {
   /** taskId：只要对话任务里这一个对话的轮次。 */
   listTurns(jobId: string, query?: { afterSeq?: number; limit?: number; taskId?: string }): Promise<{ job_id: string; turns: CenterTurn[] }>;
   listTasks(): Promise<{ tasks: CenterTask[] }>;
+  /**
+   * 更早的节点转录（往上翻）：remote 是流里给的节点会话，before 是手里最早那条消息的 id。
+   * 返回这一页（旧的在前）和再往前还剩几条。旧版中枢没有这个接口（实时流也就给的是全量，用不到）。
+   */
+  history?(jobId: string, remote: string, before: string, limit?: number): Promise<{ messages: Message[]; older: number }>;
   createConversation(firstMessage: string, opts?: NewConversationOptions & { businessId?: string }): Promise<{ id: string; job_id: string; status: string; task_ids?: string[]; turn: CenterTurn }>;
   /** taskId：发给对话任务里的哪个对话，不给 = 第一个。 */
   sendMessage(jobId: string, text: string, opts?: { businessId?: string; timeoutSeconds?: number; taskId?: string }): Promise<SendResult>;
+  /**
+   * 一次性任务里的对话式子任务接着聊：续派一条 mode=conversation、continue_from 这个子任务的子任务（接在同一个 Agent 会话里）。
+   * 返回新子任务的 id。
+   */
+  continueTask?(jobId: string, taskId: string, text: string, opts?: { title?: string; businessId?: string }): Promise<{ task_id: string }>;
   /** 在对话任务里新开一个对话（同一节点、同一工作区），text 是它的第一条消息。 */
   openConversation?(jobId: string, text: string, opts?: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number }): Promise<SendResult>;
   cancelTurn(jobId: string, turnId: string): Promise<CenterTurn>;
@@ -89,11 +111,15 @@ export interface ConversationBackend {
   /** taskId：看对话任务里的哪个对话，不给 = 第一个。 */
   stream(jobId: string, handlers: StreamHandlers, intervalMs?: number, taskId?: string | null): () => void;
   /**
-   * 把回答直接交给正停在提问上的回合（Operator 的 POST /api/tasks/:id/answer）。
-   * resolved=false 表示没有在等的回合，调用方改用「下一条消息」发回答。center 不提供：它在 Agent 提问时已经结束那一轮。
+   * 把回答直接交给正停在提问上的回合（中枢 POST /api/jobs/:id/answer → 节点 /answer）。
+   * resolved=false 表示没有在等的回合：对话任务改用「下一条消息」发回答（中枢在 Agent 提问时已经结束那一轮）；
+   * 一次性任务的子任务提问时回合开着等，答案直接交过去。
    */
   answerAsk?(jobId: string, askId: string, answers: string[][]): Promise<{ resolved: boolean }>;
-  /** 提交浏览器输入卡片（Operator 的 POST /api/tasks/:id/input），返回错误文案或 null。center 不提供。 */
+  /**
+   * 提交浏览器输入卡片（验证码、账号、密码、选项；中枢 POST /api/jobs/:id/input → 节点 /input），返回错误文案或 null。
+   * 密码只交给节点上的浏览器脚本，不进模型、不进转录、中枢不落库。
+   */
   submitInput?(jobId: string, inputId: string, values: string[]): Promise<string | null>;
   /** 浏览器交接后交还给 AI（Operator 的 POST /api/tasks/:id/browser），返回错误文案或 null。center 不提供。 */
   handback?(jobId: string): Promise<string | null>;
@@ -113,9 +139,23 @@ export interface BoardBackend {
   stat(jobId: string, path?: string): Promise<DirListing | FileInfo>;
   /** 文件地址（给 <img> / <iframe> / 下载链接用）。相对路径用路径式地址，HTML 里的相对资源能跟着解析。 */
   fileUrl(jobId: string, path: string, opts?: { download?: boolean }): string;
-  /** 读文本（最多 maxBytes，超过的截断）。 */
-  readText(jobId: string, path: string, maxBytes?: number): Promise<{ text: string; truncated: boolean; size: number; contentType: string }>;
-  readBuffer(jobId: string, path: string): Promise<ArrayBuffer>;
+  /**
+   * 浏览器能直接打开的文件地址前缀（…/files/raw，后面接相对路径或 ?path=）：directLinks 时就是 fileUrl 的前缀；
+   * 否则向中枢换一个短期令牌放进路径（<img> / <iframe> / 下载都不需要请求头，大文件流式下载、不进浏览器内存），
+   * 快过期时自动换新的。中枢不支持时返回 null（看板退回先 fetch 再显示）。
+   */
+  fileLinkBase?(jobId: string): Promise<string | null>;
+  /**
+   * 读文本（最多 maxBytes，超过的截断）。只向中枢要这一段（Range），超大文件不整个传过来。
+   * tail = 读末尾那一段（超大日志）；节点不支持只读一段时退回开头（返回的 tail 为 false）。
+   * 不是 UTF-8 的（GBK 导出的 CSV 之类）按 GB18030 解，encoding 说明按什么解的。
+   */
+  readText(jobId: string, path: string, maxBytes?: number, opts?: { tail?: boolean }): Promise<TextChunk>;
+  /**
+   * 读整个文件。signal 取消（打包下载点了取消）；onBytes 报已收到的字节数（大文件显示进度）。
+   * 弱网：FILE_HEADER_TIMEOUT_MS 内没回响应头、或传输中 FILE_STALL_MS 没收到数据，按网络错误（NETWORK）失败。
+   */
+  readBuffer(jobId: string, path: string, opts?: { signal?: AbortSignal; onBytes?: (bytes: number) => void }): Promise<ArrayBuffer>;
   diff(jobId: string): Promise<DiffResult>;
   browserStatus(jobId: string): Promise<BrowserStatus>;
   browserAction(jobId: string, action: "open" | "close" | "takeover" | "handback"): Promise<BrowserStatus>;
@@ -124,6 +164,44 @@ export interface BoardBackend {
   /** 浏览器实时画面；onViewer 给出发输入要用的 viewer id。 */
   browserFrames(jobId: string, handlers: { onViewer: (viewer: string) => void; onMessage: (message: BrowserMessage) => void; onEnd?: (end: { reason: string; detail?: string }) => void; onClose?: (error: CenterError | null) => void }): () => void;
   browserInput(jobId: string, viewer: string, events: Array<Record<string, unknown>>): Promise<void>;
+  /**
+   * 浏览器的一条实时连接（状态 + 画面 + 弹窗 + 复制出的文字，见中枢 board-live.ts）。新版中枢才有：
+   * 旧版中枢回 404（路由不存在，error 为 "Not Found"），组件退回 browserEvents + browserFrames 两条。
+   */
+  browserLive?(jobId: string, handlers: BrowserLiveHandlers): () => void;
+}
+
+export interface TextChunk {
+  text: string;
+  /** 只读到了一部分。 */
+  truncated: boolean;
+  /** 文件总大小。 */
+  size: number;
+  contentType: string;
+  /** 读的是末尾那一段。 */
+  tail?: boolean;
+  encoding?: string;
+}
+
+export interface BrowserLiveHandlers {
+  /** 这条连接的 viewer id；ready = 输入能送到节点（画面连接已建好）。 */
+  onViewer: (viewer: string, ready: boolean) => void;
+  onStatus: (status: BrowserStatus) => void;
+  onMessage: (message: BrowserMessage) => void;
+  onFrames?: (state: BrowserFramesState) => void;
+  /** 不会再有数据（节点拒绝、中枢停机）。 */
+  onEnd?: (end: { reason: string; status?: number; detail?: string }) => void;
+  onClose?: (error: CenterError | null) => void;
+}
+
+/** 旧版中枢没有这个接口：Fastify 的「路由不存在」404（和「任务不存在」的 not_found 区分开）。 */
+export const isMissingRoute = (error: CenterError | null | undefined) => !!error && error.status === 404 && error.code === "Not Found";
+
+/** 由 fileLinkBase 给的前缀拼出文件地址。 */
+export function fileUrlFromBase(linkBase: string, path: string, download = false) {
+  const clean = path.replace(/^\.\//, "");
+  if (clean.startsWith("/") || clean.startsWith("~") || /^[a-z]:[\\/]/i.test(clean)) return `${linkBase}?path=${encodeURIComponent(clean)}${download ? "&download=1" : ""}`;
+  return `${linkBase}/${clean.split("/").filter(Boolean).map(encodeURIComponent).join("/")}${download ? "?download=1" : ""}`;
 }
 
 export function createCenterClient(options: CenterClientOptions = {}): ConversationBackend {
@@ -137,18 +215,38 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
     return result;
   }
 
-  async function request<T>(path: string, init: RequestInit = {}): Promise<T> {
+  // 同一时刻对同一地址的 GET 只发一次，后来的共用结果：列表、对话、看板经常同时要同一份数据（同一个任务的详情、看板概况、目录），
+  // 浏览器对一个域名的连接有限，重复请求会把真正要紧的（点开文件、发消息）挤到后面排队。
+  const inflight = new Map<string, Promise<unknown>>();
+  function request<T>(path: string, init: RequestInit = {}, timeoutMs = options.requestTimeoutMs ?? 30_000): Promise<T> {
+    if ((init.method ?? "GET") !== "GET" || init.body) return send<T>(path, init, timeoutMs);
+    const shared = inflight.get(path);
+    if (shared) return shared as Promise<T>;
+    const p = send<T>(path, init, timeoutMs).finally(() => inflight.delete(path));
+    inflight.set(path, p);
+    return p;
+  }
+  async function send<T>(path: string, init: RequestInit, timeoutMs: number): Promise<T> {
     let response: Response;
+    const ctl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; ctl.abort(); }, timeoutMs);
     try {
       response = await doFetch(`${base}${path}`, {
         ...init,
+        signal: ctl.signal,
         headers: headers(init.body ? { "Content-Type": "application/json" } : {}),
       });
     } catch (error) {
+      clearTimeout(timer);
+      if (timedOut) throw new CenterError(`任务中心 ${Math.round(timeoutMs / 1000)} 秒没有响应，请稍后重试`, "NETWORK", 0);
       throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
     }
-    const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+    // 响应体也算在时限里（代理把响应头发了、正文却挂住）。
+    const body = (await response.json().catch(() => null).finally(() => clearTimeout(timer))) as Record<string, unknown> | null;
     if (!response.ok) {
+      // 413：消息 / 请求体超过中枢上限（中枢回的是 Fastify 的英文说明）。
+      if (response.status === 413) throw new CenterError("内容太大，超过任务中心单次请求的上限，请删减或分几条发送", "payload_too_large", 413, body);
       const code = typeof body?.error === "string" ? body.error : `HTTP_${response.status}`;
       const detail = typeof body?.detail === "string" ? body.detail : undefined;
       throw new CenterError(ERROR_TEXT[code] ?? detail ?? `任务中心返回错误（HTTP ${response.status}）`, code, response.status, body);
@@ -172,6 +270,26 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
     },
     /** 列表用：本产品线全部子任务（对话任务每个对话一条），用来发现对话。 */
     listTasks: () => request<{ tasks: CenterTask[] }>("/api/tasks"),
+    async answerAsk(jobId: string, askId: string, answers: string[][]) {
+      try {
+        return await request<{ resolved: boolean }>(boardPath(jobId, "answer"), { method: "POST", body: JSON.stringify({ ask_id: askId, answers }) });
+      } catch (error) {
+        // 旧版中枢没有这个接口：当作没有在等的回合（对话任务照旧走下一条消息）。
+        if (error instanceof CenterError && isMissingRoute(error)) return { resolved: false };
+        throw error;
+      }
+    },
+    async submitInput(jobId: string, inputId: string, values: string[]) {
+      try {
+        await request(boardPath(jobId, "input"), { method: "POST", body: JSON.stringify({ input_id: inputId, values }) });
+        return null;
+      } catch (error) {
+        if (error instanceof CenterError && isMissingRoute(error)) return "当前任务中心版本不支持在这里填写，请升级任务中心";
+        return error instanceof Error ? error.message : String(error);
+      }
+    },
+    history: (jobId: string, remote: string, before: string, limit = 200) =>
+      request<{ messages: Message[]; older: number }>(`/api/jobs/${id(parseConvKey(jobId).jobId)}/history?remote=${id(remote)}&before=${id(before)}&limit=${limit}`),
     createConversation: (firstMessage: string, opts: NewConversationOptions & { businessId?: string } = {}) => {
       const title = (opts.title || firstLine(firstMessage)).slice(0, 120);
       return post<{ id: string; job_id: string; status: string; task_ids?: string[]; turn: CenterTurn }>("/api/jobs", {
@@ -197,6 +315,13 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
         ...(opts.businessId ? { business_id: opts.businessId } : {}),
         ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
       }),
+    continueTask: async (jobId: string, taskId: string, text: string, opts: { title?: string; businessId?: string } = {}) => {
+      const result = await post<{ task_ids: string[] }>(`/api/jobs`, {
+        job_id: jobId, mode: "conversation",
+        tasks: [{ title: opts.title || firstLine(text, 60), prompt: text, continue_from: taskId, ...(opts.businessId ? { business_id: opts.businessId } : {}) }],
+      });
+      return { task_id: result.task_ids[0] };
+    },
     /** 同一个 business_id 重发只开一个对话。 */
     openConversation: (jobId: string, text: string, opts: { title?: string; agent?: string; browser?: boolean; businessId?: string; timeoutSeconds?: number } = {}) =>
       post<SendResult>(`/api/jobs/${id(jobId)}/conversations`, {
@@ -375,58 +500,154 @@ function createBoardClient(
   base: string,
   headers: (extra?: Record<string, string>) => Record<string, string>,
   doFetch: typeof fetch,
-  request: <T>(path: string, init?: RequestInit) => Promise<T>,
+  request: <T>(path: string, init?: RequestInit, timeoutMs?: number) => Promise<T>,
   directLinks: boolean,
 ): BoardBackend {
-  const fileFetch = async (jobId: string, path: string) => {
+  /**
+   * 取文件：响应头限时 FILE_HEADER_TIMEOUT_MS；body() 边读边看门（FILE_STALL_MS 没数据就断），
+   * limit 读够就停（大文件只要开头）。外面给的 signal 取消时一并中止。
+   */
+  const fileFetch = async (jobId: string, path: string, extra: Record<string, string> = {}, signal?: AbortSignal) => {
+    const name = path.split("/").pop() || path;
+    const aborted = () => new DOMException("已取消", "AbortError");
+    if (signal?.aborted) throw aborted();
+    const ctl = new AbortController();
+    const cancel = () => ctl.abort();
+    signal?.addEventListener("abort", cancel, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; ctl.abort(); }, FILE_HEADER_TIMEOUT_MS);
+    const release = () => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); };
     let response: Response;
     try {
-      response = await doFetch(boardFileUrl(base, jobId, path), { headers: headers() });
+      // 和中止赛跑：宿主自定义的 fetch 不一定理会 signal，取消 / 超时也要马上生效。
+      const stopped = new Promise<never>((_r, reject) => {
+        if (ctl.signal.aborted) reject(new DOMException("aborted", "AbortError"));
+        ctl.signal.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")), { once: true });
+      });
+      response = await Promise.race([doFetch(boardFileUrl(base, jobId, path), { headers: headers(extra), signal: ctl.signal }), stopped]);
     } catch (error) {
+      release();
+      if (signal?.aborted) throw aborted();
+      if (timedOut) throw new CenterError(`读取「${name}」${FILE_HEADER_TIMEOUT_MS / 1000} 秒没有响应（执行节点忙或网络慢），请稍后重试`, "NETWORK", 0);
       throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
     }
-    if (!response.ok) {
+    clearTimeout(timer);
+    if (!response.ok && response.status !== 416) {
+      release();
       const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
-      throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? body?.error ?? `读取失败（HTTP ${response.status}）`, body?.error ?? `HTTP_${response.status}`, response.status);
+      const fallback = response.status === 404 ? "文件不存在（可能已被任务删除或改名）" : body?.error ?? `读取失败（HTTP ${response.status}）`;
+      throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? fallback, body?.error ?? `HTTP_${response.status}`, response.status);
     }
-    return response;
-  };
-  return {
-    directLinks,
-    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
-    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
-    fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
-    async readText(jobId, path, maxBytes = 512 * 1024) {
-      const response = await fileFetch(jobId, path);
-      const contentType = response.headers.get("content-type") ?? "";
-      const size = Number(response.headers.get("content-length") ?? 0);
-      // 只读前 maxBytes：大文件不整个拉进浏览器。
+    const stallError = () => new CenterError(`读取「${name}」时 ${FILE_STALL_MS / 1000} 秒没有收到数据，传输已中断，请重试`, "NETWORK", 0);
+    /** 读响应体：limit 读够就停；onBytes 报进度；FILE_STALL_MS 没数据当断线。 */
+    const body = async (opts: { limit?: number; onBytes?: (bytes: number) => void } = {}): Promise<Uint8Array<ArrayBuffer>> => {
+      // 空文件要「前 N 字节」：节点回 416，就是空的。
+      if (response.status === 416) { release(); return new Uint8Array(0); }
       const reader = response.body?.getReader();
-      if (!reader) return { text: await response.text(), truncated: false, size, contentType };
+      if (!reader) {
+        try { return new Uint8Array(await response.arrayBuffer()); } finally { release(); }
+      }
       const chunks: Uint8Array[] = [];
       let got = 0;
-      let truncated = false;
-      for (;;) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(value);
-        got += value.length;
-        if (got >= maxBytes) { truncated = true; await reader.cancel().catch(() => undefined); break; }
+      let stalled = false;
+      let stall: ReturnType<typeof setTimeout> | undefined;
+      const arm = () => {
+        clearTimeout(stall);
+        stall = setTimeout(() => { stalled = true; ctl.abort(); void reader.cancel().catch(() => undefined); }, FILE_STALL_MS);
+      };
+      try {
+        arm();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (stalled) throw stallError();
+          if (done) break;
+          arm();
+          chunks.push(value);
+          got += value.length;
+          opts.onBytes?.(got);
+          if (opts.limit !== undefined && got >= opts.limit) { await reader.cancel().catch(() => undefined); break; }
+        }
+      } catch (error) {
+        if (signal?.aborted) throw aborted();
+        if (stalled) throw stallError();
+        if (error instanceof CenterError) throw error;
+        throw new CenterError(`读取「${name}」中断：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
+      } finally {
+        clearTimeout(stall);
+        release();
       }
-      const all = new Uint8Array(Math.min(got, maxBytes));
+      if (signal?.aborted) throw aborted();
+      const size = opts.limit !== undefined ? Math.min(got, opts.limit) : got;
+      const all = new Uint8Array(size);
       let offset = 0;
       for (const chunk of chunks) {
-        const take = Math.min(chunk.length, all.length - offset);
+        const take = Math.min(chunk.length, size - offset);
         all.set(chunk.subarray(0, take), offset);
         offset += take;
-        if (offset >= all.length) break;
+        if (offset >= size) break;
+      }
+      return all;
+    };
+    return { response, body };
+  };
+  // 文件链接令牌：按对话键缓存，离过期不到 5 分钟就换新的；同一时刻只换一次。
+  const links = new Map<string, { base: string; until: number }>();
+  const minting = new Map<string, Promise<string | null>>();
+  let linksUnsupported = false;
+  const LINK_REFRESH_MS = 5 * 60_000;
+  return {
+    directLinks,
+    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
+    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
+    fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
+    async fileLinkBase(jobId) {
+      const { job, task } = boardTarget(jobId);
+      if (directLinks) return `${base}/api/jobs/${job}${task ? `/tasks/${task}` : ""}/files/raw`;
+      if (linksUnsupported) return null;
+      const cached = links.get(jobId);
+      if (cached && cached.until - Date.now() > LINK_REFRESH_MS) return cached.base;
+      const running = minting.get(jobId);
+      if (running) return running;
+      const work = request<{ base?: unknown; expires_at?: string }>(boardPath(jobId, "files/token"), { method: "POST", body: "{}" }).then((r) => {
+        if (typeof r?.base !== "string") { linksUnsupported = true; return null; }
+        const linkBase = `${base}${r.base}`;
+        links.set(jobId, { base: linkBase, until: Date.parse(r.expires_at ?? "") || Date.now() + 30 * 60_000 });
+        return linkBase;
+      }, (error: unknown) => {
+        if (error instanceof CenterError && isMissingRoute(error)) { linksUnsupported = true; return null; }
+        throw error;
+      }).finally(() => minting.delete(jobId));
+      minting.set(jobId, work);
+      return work;
+    },
+    async readText(jobId, path, maxBytes = 512 * 1024, opts = {}) {
+      // 只要需要的那一段：开头 maxBytes，或者末尾 maxBytes（超大日志）。不支持 Range 的节点回整个文件（200），下面边读边截。
+      const { response, body } = await fileFetch(jobId, path, { Range: opts.tail ? `bytes=-${maxBytes}` : `bytes=0-${maxBytes - 1}` });
+      const contentType = response.headers.get("content-type") ?? "text/plain";
+      if (response.status === 416) { await body(); return { text: "", truncated: false, size: 0, contentType }; }
+      const total = /\/(\d+)\s*$/.exec(response.headers.get("content-range") ?? "")?.[1];
+      const length = Number(response.headers.get("content-length") ?? 0);
+      if (response.status === 206) {
+        // 节点给的一段可能比要的长（不严格按 Range）：也只留 maxBytes。
+        const bytes = await body({ limit: maxBytes });
+        const size = total ? Number(total) : bytes.length;
+        const start = Number(/bytes (\d+)-/.exec(response.headers.get("content-range") ?? "")?.[1] ?? 0);
+        const { text, encoding } = decodeText(bytes, { fromMiddle: start > 0 });
+        return { text, truncated: bytes.length < size, size, contentType, tail: start > 0, encoding };
       }
-      return { text: new TextDecoder().decode(all), truncated, size: size || got, contentType };
+      // 不支持 Range（回 200 整个文件）：只读前 maxBytes，大文件不整个拉进浏览器。
+      const all = await body({ limit: maxBytes });
+      const truncated = all.length >= maxBytes && (!length || length > maxBytes);
+      const { text, encoding } = decodeText(all);
+      return { text, truncated, size: length || all.length, contentType, encoding };
+    },
+    async readBuffer(jobId, path, opts = {}) {
+      const { body } = await fileFetch(jobId, path, {}, opts.signal);
+      return (await body({ onBytes: opts.onBytes })).buffer;
     },
-    readBuffer: async (jobId, path) => (await fileFetch(jobId, path)).arrayBuffer(),
     diff: (jobId) => request<DiffResult>(boardPath(jobId, "diff")),
     browserStatus: (jobId) => request<BrowserStatus>(boardPath(jobId, "browser")),
-    browserAction: (jobId, action) => request<BrowserStatus>(boardPath(jobId, "browser"), { method: "POST", body: JSON.stringify({ action }) }),
+    browserAction: (jobId, action) => request<BrowserStatus>(boardPath(jobId, "browser"), { method: "POST", body: JSON.stringify({ action }) }, 150_000),
     browserEvents: (jobId, handlers) => openSse(doFetch, `${base}${boardPath(jobId, "browser/events")}`, headers(), (event, data) => {
       if (event === "status") handlers.onStatus(data as BrowserStatus);
     }, handlers.onClose),
@@ -438,5 +659,13 @@ function createBoardClient(
     async browserInput(jobId, viewer, events) {
       await request(boardPath(jobId, "browser/input"), { method: "POST", body: JSON.stringify({ viewer, events }) });
     },
+    browserLive: (jobId, h) => openSse(doFetch, `${base}${boardPath(jobId, "browser/live")}`, headers(), (event, data) => {
+      const d = data as Record<string, unknown>;
+      if (event === "viewer") h.onViewer(String(d.viewer), d.ready === true);
+      else if (event === "status") h.onStatus(data as BrowserStatus);
+      else if (event === "message") h.onMessage(data as BrowserMessage);
+      else if (event === "frames") h.onFrames?.(data as BrowserFramesState);
+      else if (event === "end") h.onEnd?.(data as { reason: string; status?: number; detail?: string });
+    }, h.onClose),
   };
 }

package/src/core/config.ts

@@ -1,7 +1,7 @@
 /**
- * 组件的界面配置：哪些模块显示、文案怎么写。全部可选，不给就是缺省（全部显示、默认文案）。
+ * 组件的界面配置：哪些模块显示、文案怎么写。全部可选，不给就是缺省（默认文案；cli-chat 的顶部栏缺省隐藏，其余全部显示）。
  *
- *   <CliChat config={{ header: { export: false, close: false }, composer: { placeholder: "问点什么…", fileUpload: false } }} />
+ *   <CliChat config={{ header: { title: true, status: true }, composer: { placeholder: "问点什么…", fileUpload: false } }} />
  *   <CliMsgList config={{ header: { refresh: false }, card: { turns: false } }} />
  *
  * 开关类的模块写 false 就整块隐藏，写对象就逐项开关；文案里可以用 {title}（对话标题）、{agent}（智能体名）。
@@ -10,7 +10,7 @@
 // ── cli-chat ─────────────────────────────────────────
 
 export interface CliChatConfig {
-  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  /** 顶部栏。缺省隐藏；true = 每一项都显示；对象 = 只显示写了 true 的项。 */
   header?: boolean | {
     /** 面包屑：色块 + 名称 / 对话。 */
     crumb?: boolean;
@@ -66,6 +66,8 @@ export interface CliChatConfig {
     tools?: boolean;
     /** 「智能体 · 运行中 0:12」那一行。 */
     runningIndicator?: boolean;
+    /** 状态说明行：新对话的「尚未开始」、结束时的「对话已结束」「子任务已完成」等。缺省不显示。 */
+    status?: boolean;
   };
   /** 消息头上的称呼。 */
   labels?: { user?: string; agent?: string };
@@ -79,13 +81,14 @@ export interface ResolvedChatConfig {
     show: boolean; placeholder: string; placeholderNew: string; placeholderRunning: string; placeholderDisabled: string | null;
     hints: boolean; charCount: boolean; fileUpload: boolean; fileButtonText: string; stop: boolean; queue: boolean;
   };
-  transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean };
+  transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean; status: boolean };
   labels: { user: string; agent: string };
   empty: { show: boolean; title: string; description: string };
 }
 
 export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
-  header: { show: true, crumb: true, export: true, title: true, agent: true, usage: true, model: true, status: true, close: true },
+  // 顶部栏缺省整栏隐藏（模型、状态、用量这些对使用者是干扰），需要的项在 config.header 里打开。
+  header: { show: true, crumb: false, export: false, title: false, agent: false, usage: false, model: false, status: false, close: false },
   composer: {
     show: true,
     placeholder: "在“{title}”中回复 {agent}…（可拖入 TXT / Markdown / Word 文件）",
@@ -94,14 +97,14 @@ export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
     placeholderDisabled: null,
     hints: true, charCount: true, fileUpload: true, fileButtonText: "文件", stop: true, queue: true,
   },
-  transcript: { nav: true, sessionLabel: true, timestamps: true, initialBadge: true, tools: true, runningIndicator: true },
+  transcript: { nav: true, sessionLabel: true, timestamps: true, initialBadge: true, tools: true, runningIndicator: true, status: false },
   labels: { user: "你", agent: "智能体" },
   empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 TXT、Markdown 或 Word 文件，内容会转成文字一起发送。" },
 };
 
 export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfig {
   const d = DEFAULT_CHAT_CONFIG;
-  const header = toggle(config.header, d.header);
+  const header = config.header === true ? allOn(d.header) : toggle(config.header, d.header);
   const composer = toggle(config.composer, d.composer);
   const empty = toggle(config.empty, d.empty);
   // 没有文件上传时，缺省文案里的「可拖入文件」提示也去掉。
@@ -138,22 +141,26 @@ export interface CliMsgListConfig {
   /** 搜索框：true 总是显示，false 不显示，"auto"（缺省）对话数 ≥ 6 时显示。 */
   search?: boolean | "auto";
   searchPlaceholder?: string;
+  /**
+   * 按状态分组（需要你处理 / 进行中 / 已结束 / 已取消），配合 groups 改组名。缺省不分组：一个列表，最近活动的在前。
+   */
+  grouped?: boolean;
   /** 卡片上显示哪些内容。 */
   card?: {
-    /** 状态点和状态文字。 */
+    /** 状态点、状态文字，以及底部的「运行中 / 等你处理 / 已完成」等字样。缺省不显示（底部只有时间）。 */
     status?: boolean;
     /** 智能体标签。 */
     agent?: boolean;
     /** 第一条消息摘要。 */
     description?: boolean;
-    /** 底部活动（运行中 · 3 分钟前……）。 */
+    /** 底部活动（3 分钟前；打开 status 时带上运行中、排队等状态）。 */
     activity?: boolean;
     /** 「N 轮对话」。 */
     turns?: boolean;
     /** 「+」按钮：在这个任务（对话任务）里新开一个对话，共用同一个工作区。 */
     newInJob?: boolean;
   };
-  /** 分组标题；写 false 隐藏这一组。 */
+  /** 分组标题（grouped 时）；写 false 隐藏这一组。 */
   groups?: { needs?: string | false; active?: string | false; done?: string | false; cancelled?: string | false };
   /** 没有对话时的提示。 */
   emptyTitle?: string;
@@ -164,6 +171,7 @@ export interface ResolvedMsgListConfig {
   header: { show: boolean; title: boolean; newButton: boolean; newButtonText: string; refresh: boolean; context: boolean };
   search: boolean | "auto";
   searchPlaceholder: string;
+  grouped: boolean;
   card: { status: boolean; agent: boolean; description: boolean; activity: boolean; turns: boolean; newInJob: boolean };
   groups: { needs: string | false; active: string | false; done: string | false; cancelled: string | false };
   emptyTitle: string;
@@ -174,7 +182,9 @@ export const DEFAULT_MSGLIST_CONFIG: ResolvedMsgListConfig = {
   header: { show: true, title: true, newButton: true, newButtonText: "对话", refresh: true, context: true },
   search: "auto",
   searchPlaceholder: "搜索对话…",
-  card: { status: true, agent: true, description: true, activity: true, turns: true, newInJob: true },
+  grouped: false,
+  // 状态缺省不显示（未开始、进行中、已完成……对使用者是干扰），需要时打开 card.status / grouped。
+  card: { status: false, agent: true, description: true, activity: true, turns: true, newInJob: true },
   groups: { needs: "需要你处理", active: "进行中", done: "已结束", cancelled: "已取消" },
   emptyTitle: "还没有对话",
   emptyDescription: "点「对话」开始一个新的对话。",
@@ -186,6 +196,7 @@ export function resolveMsgListConfig(config: CliMsgListConfig = {}): ResolvedMsg
     header: toggle(config.header, d.header),
     search: config.search ?? d.search,
     searchPlaceholder: config.searchPlaceholder ?? d.searchPlaceholder,
+    grouped: config.grouped ?? d.grouped,
     card: { ...d.card, ...defined(config.card) },
     groups: { ...d.groups, ...defined(config.groups) },
     emptyTitle: config.emptyTitle ?? d.emptyTitle,
@@ -211,6 +222,12 @@ function defined<T extends object>(value: T | undefined): Partial<T> {
 /**
  * 开关型模块：false → 全关（show=false 且布尔项全 false，文案保留）；true / 不给 → 缺省；对象 → 合并缺省。
  */
+function allOn<T extends { show: boolean }>(defaults: T): T {
+  const on = { ...defaults } as Record<string, unknown>;
+  for (const key of Object.keys(on)) if (typeof on[key] === "boolean") on[key] = true;
+  return on as T;
+}
+
 function toggle<T extends { show: boolean }>(value: boolean | object | undefined, defaults: T): T {
   if (value === false) {
     const off = { ...defaults, show: false } as Record<string, unknown>;