@spzxg/cli-ui 0.4.0 → 0.6.1

package/src/core/blocks.ts

@@ -1,5 +1,5 @@
 /**
- * 「文本块」：上传的文件（TXT / Markdown / Word）和粘贴的大段文字。
+ * 「文本块」：上传的文档（Word / Excel / Markdown / TXT / HTML / CSV）和粘贴的大段文字。
  *
  * 前端先把文件解析成纯文本，再按统一格式拼进消息正文发给 center——center 只收纯文本。
  * 同一个格式两头用：输入框里是可折叠的卡片，发出去之后转录里也解析回同样的卡片，
@@ -12,16 +12,61 @@
  * 对 Agent 来说这也是清楚的分隔：哪段是附件、叫什么、在哪结束。
  */
 
+import { decodeText } from "./textDecode.js";
+
 export interface TextBlock {
   /** 显示名：文件名，粘贴的文字为「粘贴的文本」。 */
   name: string;
   text: string;
-  kind: "file" | "paste";
+  kind: "file" | "paste" | "context" | "background" | "viewing";
+}
+
+/** 看板引用合成的块的名字（转录里按它认出来，显示成「看板上下文」卡片）。 */
+export const BOARD_CONTEXT_NAME = "看板上下文";
+
+/** 看板引用 → 发给智能体的块。 */
+export function boardContextBlock(lines: string[]): TextBlock {
+  return { name: BOARD_CONTEXT_NAME, kind: "context", text: ["用户在右侧看板里引用了下面这些，供这条消息参考：", ...lines.map((l) => `- ${l}`)].join("\n") };
+}
+
+/** 看板上正在看的东西（缺省随消息带上、不显示）合成的块的名字：和明确引用的分开，转录里可以单独不显示。 */
+export const VIEWING_NAME = "看板正在看";
+
+/** 看板上正在看的东西 → 发给智能体的块。 */
+export function viewingBlock(line: string): TextBlock {
+  return { name: VIEWING_NAME, kind: "viewing", text: `${line}。用户没有另外说明时，消息里说的「这个」「这里」「改一下」等就是指它。` };
 }
 
-/** 支持的文件：只有 TXT、Markdown、Word（.docx）。 */
-export const ACCEPTED_EXTENSIONS = [".txt", ".md", ".markdown", ".docx"] as const;
-export const ACCEPT_ATTR = ".txt,.md,.markdown,.docx,text/plain,text/markdown,application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** 补充背景合成的块的名字（转录里显示成「补充背景」卡片）。 */
+export const BACKGROUND_NAME = "补充背景";
+
+/** 补充背景（store.appendContext）→ 发给智能体的块。每条有标题时写成「【标题】」。 */
+export function backgroundBlock(items: Array<{ title?: string; text: string }>): TextBlock {
+  // 内容里碰巧有附件分隔行时错开一个空格，免得把块提前截断。
+  const safe = (t: string) => t.replace(/^(----- 附件)/gm, " $1");
+  const body = items.map((i) => (i.title ? `【${i.title}】\n${safe(i.text)}` : safe(i.text))).join("\n\n");
+  return { name: BACKGROUND_NAME, kind: "background", text: `以下是补充的项目背景信息，请在这次及之后的工作中一并参考：\n\n${body}` };
+}
+
+/** 支持的文件：只收文档——Word（.docx）、Excel（.xlsx / .xlsm）、Markdown、TXT、HTML、CSV / TSV。都在浏览器里转成文字。 */
+export const ACCEPTED_EXTENSIONS = [".docx", ".xlsx", ".xlsm", ".md", ".markdown", ".txt", ".html", ".htm", ".csv", ".tsv"] as const;
+export const ACCEPT_ATTR = [
+  ...ACCEPTED_EXTENSIONS,
+  "text/plain", "text/markdown", "text/html", "text/csv", "text/tab-separated-values",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel.sheet.macroEnabled.12",
+].join(",");
+/** 不支持时提示里列的格式。 */
+export const ACCEPTED_LABEL = "Word（.docx）、Excel（.xlsx）、Markdown、TXT、HTML、CSV";
+/** 一些常见但读不了的文档：给出另存为什么。 */
+const SAVE_AS: Record<string, string> = {
+  ".doc": "老版 Word（.doc）请另存为 .docx 后再上传",
+  ".xls": "老版 Excel（.xls）请另存为 .xlsx 或 CSV 后再上传",
+  ".wps": "WPS 文字请另存为 .docx 后再上传",
+  ".et": "WPS 表格请另存为 .xlsx 后再上传",
+};
+/** HTML 里内嵌的大段 data: 数据（图片、字体）：换成占位，免得一张图就把消息撑爆。 */
+const INLINE_DATA = /data:[\w.+-]+\/[\w.+-]+(?:;[\w=.+-]+)*,[^"')\s]{200,}/g;
 /** 粘贴超过这个长度（或行数）就转成文本块，不放进输入框。 */
 export const PASTE_BLOCK_CHARS = 2_000;
 export const PASTE_BLOCK_LINES = 40;
@@ -63,7 +108,7 @@ export function splitMessage(content: string): MessagePart[] {
     if (!open || end === -1) { text.push(lines[i]); continue; }
     flush();
     const name = open[1];
-    parts.push({ kind: "block", block: { name, text: lines.slice(i + 1, end).join("\n"), kind: name === PASTE_NAME ? "paste" : "file" } });
+    parts.push({ kind: "block", block: { name, text: lines.slice(i + 1, end).join("\n"), kind: name === PASTE_NAME ? "paste" : name === BOARD_CONTEXT_NAME ? "context" : name === VIEWING_NAME ? "viewing" : name === BACKGROUND_NAME ? "background" : "file" } });
     i = end;
   }
   flush();
@@ -86,13 +131,24 @@ export function extensionOf(name: string) {
 export class FileReadError extends Error {}
 
 /**
- * 读出文件的纯文本。TXT / Markdown 直接按 UTF-8 读；Word 用 mammoth 取正文文字（不带格式、图片）。
- * 老式 .doc（二进制）浏览器里读不了，提示另存为 .docx。
+ * 读出文件的纯文本：
+ *   · TXT / Markdown / CSV / TSV / HTML —— 按编码解（UTF-8，导出的 GBK 文件按 GB18030），HTML 保留源码、内嵌的大段 data: 数据换成占位；
+ *   · Word —— mammoth 取正文文字（不带格式、图片）；
+ *   · Excel —— 每个工作表一段 CSV（单元格的值，日期写成 2026-08-10），见 xlsx.ts。
+ * 其他文件（图片、PDF、压缩包……）不收；老版 .doc / .xls 浏览器里读不了，提示另存为。
  */
 export async function readFileText(file: File): Promise<string> {
   const ext = extensionOf(file.name);
-  if (ext === ".doc") throw new FileReadError("不支持老版 Word（.doc），请另存为 .docx 后再上传");
-  if (!(ACCEPTED_EXTENSIONS as readonly string[]).includes(ext)) throw new FileReadError("只支持 TXT、Markdown 和 Word（.docx）文件");
+  if (SAVE_AS[ext]) throw new FileReadError(`不支持这种格式：${SAVE_AS[ext]}`);
+  if (!(ACCEPTED_EXTENSIONS as readonly string[]).includes(ext)) throw new FileReadError(`「${file.name}」不是支持的文档，只能上传 ${ACCEPTED_LABEL}`);
+  if (ext === ".xlsx" || ext === ".xlsm") {
+    const { readXlsx, sheetsToText } = await import("./xlsx.js");
+    try {
+      return normalizeText(sheetsToText(await readXlsx(await readAs(file, "buffer"))));
+    } catch {
+      throw new FileReadError("Excel 文件解析失败，文件可能已损坏、加了密码，或不是 .xlsx 格式");
+    }
+  }
   if (ext === ".docx") {
     // 按需加载：mammoth 不小，只有真的传 Word 时才下载。
     const mammoth = await import("mammoth");
@@ -108,7 +164,9 @@ export async function readFileText(file: File): Promise<string> {
       throw new FileReadError("Word 文件解析失败，文件可能已损坏或不是 .docx 格式");
     }
   }
-  return normalizeText(await readAs(file, "text"));
+  const { text } = decodeText(new Uint8Array(await readAs(file, "buffer")));
+  if (ext === ".html" || ext === ".htm") return normalizeText(text.replace(INLINE_DATA, (m) => `${m.slice(0, m.indexOf(",") + 1)}…（内嵌数据已省略）`));
+  return normalizeText(text);
 }
 
 /** Blob.text() / arrayBuffer() 老浏览器（Safari 14 以前）没有，退回 FileReader。 */

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,6 +89,11 @@ 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>;
@@ -94,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>;
@@ -118,9 +139,28 @@ 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; onBytes?: (bytes: number) => void }): Promise<TextChunk>;
+  /**
+   * 读一段原始字节：从 start 开始（缺省 0）最多 maxBytes；tail = 末尾 maxBytes。返回这段在文件里的起点和文件总大小。
+   * 看板用它在文件变长时只取新增的部分（日志、还在写的报告），不整个重读。没有这个方法的后端每次整个重读。
+   */
+  readBytes?(jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; onBytes?: (bytes: number) => void }): Promise<ByteChunk>;
+  /**
+   * 读整个文件。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>;
@@ -129,6 +169,53 @@ 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;
+}
+
+/** readBytes 读到的一段。 */
+export interface ByteChunk {
+  bytes: Uint8Array<ArrayBuffer>;
+  /** 这段在文件里从第几个字节开始。 */
+  start: number;
+  /** 文件总大小。 */
+  size: number;
+}
+
+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 {
@@ -142,18 +229,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);
@@ -177,6 +284,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", {
@@ -387,58 +514,167 @@ 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 { text: new TextDecoder().decode(all), truncated, size: size || got, contentType };
+      return all;
+    };
+    return { response, body };
+  };
+  /**
+   * 读一段：开头 / 从 start 起 maxBytes，或者末尾 maxBytes（超大日志）。只向中枢要这一段（Range）；
+   * 不支持 Range 的节点回整个文件（200），这里边读边截，大文件不整个拉进浏览器。
+   */
+  const readRange = async (jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; onBytes?: (bytes: number) => void }) => {
+    const from = Math.max(0, opts.start ?? 0);
+    const { maxBytes } = opts;
+    const { response, body } = await fileFetch(jobId, path, { Range: opts.tail ? `bytes=-${maxBytes}` : `bytes=${from}-${from + maxBytes - 1}` });
+    const contentType = response.headers.get("content-type") ?? "text/plain";
+    const total = /\/(\d+)\s*$/.exec(response.headers.get("content-range") ?? "")?.[1];
+    // 416：要的起点不在文件里（空文件，或文件变短了）。
+    if (response.status === 416) { await body(); return { bytes: new Uint8Array(0), start: from, size: total ? Number(total) : 0, contentType }; }
+    const length = Number(response.headers.get("content-length") ?? 0);
+    if (response.status === 206) {
+      // 节点给的一段可能比要的长（不严格按 Range）：也只留 maxBytes。
+      const bytes = await body({ limit: maxBytes, onBytes: opts.onBytes });
+      const start = Number(/bytes (\d+)-/.exec(response.headers.get("content-range") ?? "")?.[1] ?? 0);
+      return { bytes, start, size: total ? Number(total) : start + bytes.length, contentType };
+    }
+    // 回了整个文件：跳过 from 之前的，留 maxBytes。
+    const all = await body({ limit: from + maxBytes, onBytes: opts.onBytes });
+    const size = length || all.length;
+    return { bytes: all.slice(Math.min(from, all.length)), start: Math.min(from, all.length), size, contentType };
+  };
+  // 文件链接令牌：按对话键缓存，离过期不到 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 = {}) {
+      const { bytes, start, size, contentType } = await readRange(jobId, path, { maxBytes, tail: opts.tail, onBytes: opts.onBytes });
+      if (!size && !bytes.length) return { text: "", truncated: false, size: 0, contentType };
+      const { text, encoding } = decodeText(bytes, { fromMiddle: start > 0 });
+      return { text, truncated: bytes.length < size, size, contentType, tail: start > 0, encoding };
+    },
+    async readBytes(jobId, path, opts) {
+      const { bytes, start, size } = await readRange(jobId, path, opts);
+      return { bytes, start, size };
+    },
+    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),
@@ -450,5 +686,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

@@ -43,7 +43,7 @@ export interface CliChatConfig {
     hints?: boolean;
     /** 底部字数统计。 */
     charCount?: boolean;
-    /** 文件上传（按钮、拖拽、粘贴文件）。只收 TXT / Markdown / Word。 */
+    /** 文件上传（按钮、拖拽、粘贴文件）。只收文档：Word、Excel、Markdown、TXT、HTML、CSV。 */
     fileUpload?: boolean;
     /** 「文件」按钮的文字。 */
     fileButtonText?: string;
@@ -73,6 +73,12 @@ export interface CliChatConfig {
   labels?: { user?: string; agent?: string };
   /** 新对话的空白页。false = 不显示。 */
   empty?: boolean | { title?: string; description?: string };
+  /**
+   * 输入框上方显示哪些看板引用（不显示的照样随下一条消息带给智能体，只是不占地方、也不能点掉）。
+   * 种类：viewing（看板上正在看的文件 / 浏览器页面，缺省带上）、file、selection（选中的一段）、browser、changes，或宿主自定义的种类；
+   * "*" = 没列出的种类。true 全显示，false 全不显示。缺省 { viewing: false }：正在看的不显示，明确引用的都显示。
+   */
+  refs?: boolean | Record<string, boolean>;
 }
 
 export interface ResolvedChatConfig {
@@ -84,22 +90,28 @@ export interface ResolvedChatConfig {
   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 };
+  /** 按种类显示 / 不显示；"*" 是没列出的种类。用 refShown 判断。 */
+  refs: Record<string, boolean>;
 }
 
+/** 这个种类的看板引用（"viewing" = 正在看的）要不要显示在输入框上方。 */
+export const refShown = (cfg: Pick<ResolvedChatConfig, "refs">, kind: string) => cfg.refs[kind] ?? cfg.refs["*"] ?? true;
+
 export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
   // 顶部栏缺省整栏隐藏（模型、状态、用量这些对使用者是干扰），需要的项在 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 文件）",
-    placeholderNew: "输入第一条消息，开始新对话…（可拖入 TXT / Markdown / Word 文件）",
+    placeholder: "在“{title}”中回复 {agent}…（可拖入 Word / Excel / Markdown 等文档）",
+    placeholderNew: "输入第一条消息，开始新对话…（可拖入 Word / Excel / Markdown 等文档）",
     placeholderRunning: "排队一条后续消息…（本轮结束后发送）",
     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, status: false },
   labels: { user: "你", agent: "智能体" },
-  empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 TXT、Markdown 或 Word 文件，内容会转成文字一起发送。" },
+  empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 Word、Excel、Markdown、TXT、HTML、CSV 文档，内容会转成文字一起发送。" },
+  refs: { "*": true, viewing: false },
 };
 
 export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfig {
@@ -109,7 +121,7 @@ export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfi
   const empty = toggle(config.empty, d.empty);
   // 没有文件上传时，缺省文案里的「可拖入文件」提示也去掉。
   if (!composer.fileUpload) {
-    const strip = (text: string) => text.replace(/（可拖入 TXT \/ Markdown \/ Word 文件）$/, "");
+    const strip = (text: string) => text.replace(/（可拖入 Word \/ Excel \/ Markdown 等文档）$/, "");
     if (!isObj(config.composer) || config.composer.placeholder === undefined) composer.placeholder = strip(composer.placeholder);
     if (!isObj(config.composer) || config.composer.placeholderNew === undefined) composer.placeholderNew = strip(composer.placeholderNew);
   }
@@ -119,6 +131,7 @@ export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfi
     transcript: { ...d.transcript, ...defined(config.transcript) },
     labels: { ...d.labels, ...defined(config.labels) },
     empty,
+    refs: config.refs === true ? { "*": true } : config.refs === false ? { "*": false } : { ...d.refs, ...(defined(isObj(config.refs) ? config.refs : undefined) as Record<string, boolean>) },
   };
 }