@spzxg/cli-ui 0.6.0 → 0.6.1

package/src/board/textLoad.ts

@@ -0,0 +1,99 @@
+// 预览里文本文件（代码、日志、Markdown、CSV）的读取。
+//
+// 能读多大：一次最多 max 字节（预览里是 32 MB），更大的只看开头或末尾。
+// 文件在变（任务在写日志、在改报告）时不整个重读：后端有 readBytes 时，从上次读到的地方往前多取一小段（OVERLAP），
+// 这一小段和手里的末尾一模一样就说明文件只是往后追加了，只取新增的部分接上；对不上（文件被改写、变短了）才整个重读。
+// 只对 UTF-8 文件这样做（GBK 的字节边界不好对齐，整个重读）。
+
+import type { BoardBackend } from "../core/client.js";
+import { decodeText } from "../core/textDecode.js";
+
+/** 往前多取这么多字节，用来确认文件只是追加。 */
+export const OVERLAP = 256;
+/** 追加的段落多了合成一段（每段是 <pre> 里的一个文字节点）。 */
+const MAX_PARTS = 200;
+
+export interface LoadedText {
+  text: string;
+  /** 分段的文字（追加的每次一段）：<pre> 里按段渲染，追加时前面的不用重排。 */
+  parts: string[];
+  /** 文件比读到的大（只读了开头或末尾）。 */
+  truncated: boolean;
+  /** 文件总大小。 */
+  size: number;
+  /** 读的是末尾。 */
+  tail: boolean;
+  encoding?: string;
+  /** 读到的内容在文件里的字节范围 [start, end)。 */
+  start: number;
+  end: number;
+  /** end 之前的最后 OVERLAP 个字节（只有 UTF-8、后端有 readBytes 时有），用来确认文件只是追加。 */
+  tailBytes: Uint8Array | null;
+}
+
+/** 末尾有几个字节是没写完的 UTF-8 字（0 = 完整）。 */
+export function incompleteUtf8Tail(bytes: Uint8Array) {
+  const len = bytes.length;
+  for (let i = len - 1; i >= 0 && i >= len - 4; i--) {
+    const b = bytes[i];
+    if ((b & 0xc0) === 0x80) continue;
+    const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+    const have = len - i;
+    return have < need ? have : 0;
+  }
+  return 0;
+}
+
+const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((x, i) => x === b[i]);
+
+/** 第一次读：开头（或末尾）最多 max 字节。 */
+export async function loadText(backend: BoardBackend, jobId: string, path: string, opts: { max: number; tail?: boolean; onBytes?: (bytes: number) => void }): Promise<LoadedText> {
+  if (!backend.readBytes) {
+    const r = await backend.readText(jobId, path, opts.max, { tail: opts.tail, onBytes: opts.onBytes });
+    return { text: r.text, parts: [r.text], truncated: r.truncated, size: r.size, tail: !!r.tail, encoding: r.encoding, start: 0, end: 0, tailBytes: null };
+  }
+  const chunk = await backend.readBytes(jobId, path, { maxBytes: opts.max, tail: opts.tail, onBytes: opts.onBytes });
+  const { text, encoding } = decodeText(chunk.bytes, { fromMiddle: chunk.start > 0 });
+  const k = encoding === "utf-8" ? incompleteUtf8Tail(chunk.bytes) : 0;
+  const end = chunk.start + chunk.bytes.length - k;
+  const tailBytes = encoding === "utf-8" ? chunk.bytes.slice(Math.max(0, chunk.bytes.length - k - OVERLAP), chunk.bytes.length - k) : null;
+  return {
+    text, parts: [text], truncated: chunk.start + chunk.bytes.length < chunk.size || chunk.start > 0, size: chunk.size,
+    tail: chunk.start > 0, encoding, start: chunk.start, end, tailBytes,
+  };
+}
+
+/**
+ * 文件变了：能接上就只取新增的部分，返回新的内容；返回 null = 接不上（被改写 / 变短 / 不是 UTF-8 / 后端不支持），调用方整个重读。
+ * 只看开头且文件比 max 大时，开头没变就不用重读（追加的在后面，本来就不显示）。
+ */
+export async function refreshText(backend: BoardBackend, jobId: string, path: string, prev: LoadedText, max: number): Promise<LoadedText | null> {
+  if (!backend.readBytes || !prev.tailBytes) return null;
+  const overlap = prev.tailBytes.length;
+  const from = prev.end - overlap;
+  const headOnly = !prev.tail && prev.truncated;
+  // 末尾模式攒多了（超过 1.5 倍）：整个重读末尾，免得越攒越大。
+  if (prev.tail && prev.end - prev.start > max * 1.5) return null;
+  const room = headOnly ? 0 : prev.tail ? max : Math.max(0, max - (prev.end - prev.start));
+  const chunk = await backend.readBytes(jobId, path, { start: from, maxBytes: overlap + room });
+  if (chunk.size < prev.end || chunk.start !== from || chunk.bytes.length < overlap) return null;
+  if (!sameBytes(chunk.bytes.subarray(0, overlap), prev.tailBytes)) return null;
+  const readEnd = from + chunk.bytes.length;
+  if (headOnly) return { ...prev, size: chunk.size };
+  const added = chunk.bytes.subarray(overlap);
+  const k = incompleteUtf8Tail(added);
+  const delta = added.subarray(0, added.length - k);
+  let addedText: string;
+  try { addedText = new TextDecoder("utf-8", { fatal: true }).decode(delta); } catch { return null; }
+  const end = prev.end + delta.length;
+  const tailBytes = new Uint8Array(Math.min(OVERLAP, overlap + delta.length));
+  const joined = new Uint8Array(overlap + delta.length);
+  joined.set(prev.tailBytes, 0);
+  joined.set(delta, overlap);
+  tailBytes.set(joined.subarray(joined.length - tailBytes.length));
+  const parts = addedText ? (prev.parts.length >= MAX_PARTS ? [prev.text, addedText] : [...prev.parts, addedText]) : prev.parts;
+  return {
+    ...prev, text: addedText ? prev.text + addedText : prev.text, parts, size: chunk.size, end, tailBytes,
+    truncated: prev.tail || chunk.size > readEnd,
+  };
+}

package/src/chat/CliChat.tsx

@@ -5,7 +5,7 @@ import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useSta
 import { CliErrorBoundary } from "../ui/ErrorBoundary.js";
 import type { CliEvent, CliStore, CliStoreOptions } from "../core/store.js";
 import { useCliState, useCliStore, useCliStoreContext, useComponentEvents, withOwnProvider, type ResultHandlers } from "../core/provider.js";
-import { boardContextBlock, serializeBlock } from "../core/blocks.js";
+import { boardContextBlock, serializeBlock, viewingBlock } from "../core/blocks.js";
 import { convKey, emptyConv, isChatTask, isNewInJob, isRunning, parseConvKey, runningTurn, TERMINAL_JOB, viewMessages } from "../core/conversation.js";
 import type { AskAnswers, AskQuestion, Msg } from "../core/types.js";
 import { Icon } from "../ui/icons.js";
@@ -14,7 +14,7 @@ import { AgentBadge, Avatar, Skel, StatusDot, type DotCls } from "../ui/shared.j
 import { HANDOFF_NOTICE_PREFIX, MessageView, SessionBreak, type MessageHandlers } from "../ui/Transcript.js";
 import { RENDER_MAX, RENDER_STEP, RENDER_WINDOW, buildTranscriptItems, hasOpenAsk, toolDataOf } from "../ui/transcriptModel.js";
 import { Composer, type ComposerOptions } from "./Composer.js";
-import { fillTemplate, resolveChatConfig, type CliChatConfig } from "../core/config.js";
+import { fillTemplate, refShown, resolveChatConfig, type CliChatConfig } from "../core/config.js";
 import { exportMarkdown } from "./export.js";
 import { FileLinkContext, FileOpenContext } from "../ui/fileLinks.js";
 import { FileViewer } from "../board/FileViewer.js";
@@ -263,12 +263,15 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
     // 一次性任务：发给正在看的那个子任务（接着它聊）。
     const id = latest.current.conv?.batch ? latest.current.runKey : latest.current.key;
     // 看板里引用到这个对话的东西：合成一个「看板上下文」块跟着这条消息发出去；发失败就放回去。
-    // 看板上正在看的文件缺省也带上一次（已经明确引用了的不重复）。
+    // 看板上正在看的文件缺省也带上一次（已经明确引用了的不重复），单独一块「看板正在看」：转录里按 config.refs.viewing 显示或不显示。
     const refKey = latest.current.key;
     const refs = refKey ? store.takeRefs(refKey) : [];
     const viewing = refKey ? store.takeViewing(refKey) : null;
-    const lines = [...(viewing && !refs.some((r) => r.id === viewing.id) ? [viewing.text] : []), ...refs.map((r) => r.text)];
-    const full = lines.length ? `${text}\n\n${serializeBlock(boardContextBlock(lines))}` : text;
+    const blocks = [
+      ...(viewing && !refs.some((r) => r.id === viewing.id) ? [viewingBlock(viewing.text)] : []),
+      ...(refs.length ? [boardContextBlock(refs.map((r) => r.text))] : []),
+    ];
+    const full = blocks.length ? [text, ...blocks.map(serializeBlock)].join("\n\n") : text;
     let target: string;
     try {
       target = await store.send(id ?? null, full, sendOpts.current);
@@ -280,7 +283,10 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
   }, [store, go]);
   const refs = useCliState((s) => (key ? s.refs[key] : undefined));
   const viewingState = useCliState((s) => (key ? s.viewing[key] : undefined));
-  const viewing = viewingState && !viewingState.off && !refs?.some((r) => r.id === viewingState.ref.id) ? viewingState.ref : null;
+  const viewingRef = viewingState && !viewingState.off && !refs?.some((r) => r.id === viewingState.ref.id) ? viewingState.ref : null;
+  // 输入框上方显示哪些（config.refs）：不显示的照样随消息带上。正在看的缺省不显示。
+  const viewing = viewingRef && refShown(cfg, "viewing") ? viewingRef : null;
+  const shownRefs = refs?.filter((r) => refShown(cfg, r.kind));
   // 业务方补充的背景（store.appendContext）：随下一条消息带上，输入框上方显示出来，让用户知道会带上什么。
   const contextItems = useCliState((s) => s.context[key ?? ""]);
   // AI 把浏览器交给用户（实时新来的「🖐 …」行）：同一 Provider 里有看板在看这个对话，就把看板切到浏览器（收起的会请宿主展开）。
@@ -527,7 +533,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
 
   const contextReset = !!lastTurn?.context_reset && conv?.turns.some((turn) => turn.context_reset);
   const h = cfg.header;
-  const view = useMemo(() => ({ timestamps: cfg.transcript.timestamps, initialBadge: cfg.transcript.initialBadge, userLabel: cfg.labels.user, agentName: cfg.labels.agent }), [cfg]);
+  const view = useMemo(() => ({ timestamps: cfg.transcript.timestamps, initialBadge: cfg.transcript.initialBadge, userLabel: cfg.labels.user, agentName: cfg.labels.agent, viewingBlock: refShown(cfg, "viewing") }), [cfg]);
   const composerOptions = useMemo<ComposerOptions>(() => ({
     placeholderRunning: cfg.composer.placeholderRunning, hints: cfg.composer.hints, charCount: cfg.composer.charCount,
     fileUpload: cfg.composer.fileUpload, fileButtonText: cfg.composer.fileButtonText, queue: cfg.composer.queue,
@@ -703,7 +709,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
             ))}
           </div>
         )}
-        {showComposer && (!!refs?.length || !!viewing) && (
+        {showComposer && (!!shownRefs?.length || !!viewing) && (
           <div className="cli-refs" aria-label="引用自看板，下一条消息会带上">
             <span className="cli-refs-t">{Icon.board()} 引用自看板</span>
             {viewing && (
@@ -713,7 +719,7 @@ function ChatInner({ jobId: jobIdProp, taskId: taskIdProp, title = "对话", col
                 <button className="cli-ref-x" onClick={() => key && store.dismissViewing(key)} title="这次不带上" aria-label={`不带上 ${viewing.label}`}>{Icon.x()}</button>
               </span>
             )}
-            {(refs ?? []).map((r) => (
+            {(shownRefs ?? []).map((r) => (
               <span key={r.id} className={`cli-ref ${r.kind === "selection" ? "sel" : ""}`} title={r.text}>
                 <span className="cli-ref-l">{r.label}</span>
                 <button className="cli-ref-x" onClick={() => key && store.removeRef(key, r.id)} title="不带上" aria-label={`不带上 ${r.label}`}>{Icon.x()}</button>

package/src/chat/Composer.tsx

@@ -1,9 +1,9 @@
 // 输入框。结构与 Operator 的 Composer.tsx 一致（comp-box / comp-area / send-group / comp-foot），
-// 但只发文本：不收图片和其他附件。文件只收 TXT、Markdown、Word，在前端解析成纯文本，
+// 但只发文本：不收图片和其他附件。文件只收文档（Word、Excel、Markdown、TXT、HTML、CSV），在前端解析成纯文本，
 // 和长粘贴一样变成可折叠的文本块，发送时按统一格式拼进正文（见 core/blocks.ts）。
 import { useEffect, useRef, useState } from "react";
 import {
-  ACCEPT_ATTR, MAX_MESSAGE_CHARS, PASTE_NAME, charCount, composeMessage, isLongText, readFileText, type TextBlock,
+  ACCEPT_ATTR, ACCEPTED_LABEL, MAX_MESSAGE_CHARS, PASTE_NAME, charCount, composeMessage, isLongText, readFileText, type TextBlock,
 } from "../core/blocks.js";
 import { Icon } from "../ui/icons.js";
 import { TextBlockCard } from "../ui/TextBlock.js";
@@ -154,7 +154,7 @@ export function Composer({ draft, placeholder, disabled, disabledHint, running,
                 if (files.length) {
                   e.preventDefault();
                   if (!options.fileUpload) { setError("这里只能发送文字"); return; }
-                  if (files.some((f) => f.type.startsWith("image/"))) setError("不支持发送图片，只能发送文字，或上传 TXT / Markdown / Word 文件");
+                  if (files.some((f) => f.type.startsWith("image/"))) setError(`不支持发送图片，只能发送文字，或上传文档：${ACCEPTED_LABEL}`);
                   addFiles(files.filter((f) => !f.type.startsWith("image/")));
                   return;
                 }
@@ -184,7 +184,7 @@ export function Composer({ draft, placeholder, disabled, disabledHint, running,
             <span className="spacer" />
             {options.fileUpload && <input ref={fileRef} type="file" accept={ACCEPT_ATTR} multiple hidden onChange={(e) => { addFiles(Array.from(e.target.files ?? [])); e.target.value = ""; }} />}
             {options.fileUpload && !disabled && (
-              <button className="hint" style={{ cursor: "pointer" }} title="添加 TXT / Markdown / Word 文件（也可拖拽进来），内容会转成文字发送" onMouseDown={(e) => { e.preventDefault(); fileRef.current?.click(); }}>{Icon.clip()} {options.fileButtonText}</button>
+              <button className="hint" style={{ cursor: "pointer" }} title={`添加文档：${ACCEPTED_LABEL}（也可拖拽进来），内容会转成文字发送`} onMouseDown={(e) => { e.preventDefault(); fileRef.current?.click(); }}>{Icon.clip()} {options.fileButtonText}</button>
             )}
           </div>}
         </div>

package/src/core/blocks.ts

@@ -1,5 +1,5 @@
 /**
- * 「文本块」：上传的文件（TXT / Markdown / Word）和粘贴的大段文字。
+ * 「文本块」：上传的文档（Word / Excel / Markdown / TXT / HTML / CSV）和粘贴的大段文字。
  *
  * 前端先把文件解析成纯文本，再按统一格式拼进消息正文发给 center——center 只收纯文本。
  * 同一个格式两头用：输入框里是可折叠的卡片，发出去之后转录里也解析回同样的卡片，
@@ -12,11 +12,13 @@
  * 对 Agent 来说这也是清楚的分隔：哪段是附件、叫什么、在哪结束。
  */
 
+import { decodeText } from "./textDecode.js";
+
 export interface TextBlock {
   /** 显示名：文件名，粘贴的文字为「粘贴的文本」。 */
   name: string;
   text: string;
-  kind: "file" | "paste" | "context" | "background";
+  kind: "file" | "paste" | "context" | "background" | "viewing";
 }
 
 /** 看板引用合成的块的名字（转录里按它认出来，显示成「看板上下文」卡片）。 */
@@ -27,6 +29,14 @@ 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}。用户没有另外说明时，消息里说的「这个」「这里」「改一下」等就是指它。` };
+}
+
 /** 补充背景合成的块的名字（转录里显示成「补充背景」卡片）。 */
 export const BACKGROUND_NAME = "补充背景";
 
@@ -38,9 +48,25 @@ export function backgroundBlock(items: Array<{ title?: string; text: string }>):
   return { name: BACKGROUND_NAME, kind: "background", text: `以下是补充的项目背景信息，请在这次及之后的工作中一并参考：\n\n${body}` };
 }
 
-/** 支持的文件：只有 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";
+/** 支持的文件：只收文档——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;
@@ -82,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" : name === BOARD_CONTEXT_NAME ? "context" : name === BACKGROUND_NAME ? "background" : "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();
@@ -105,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");
@@ -127,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

@@ -150,7 +150,12 @@ export interface BoardBackend {
    * tail = 读末尾那一段（超大日志）；节点不支持只读一段时退回开头（返回的 tail 为 false）。
    * 不是 UTF-8 的（GBK 导出的 CSV 之类）按 GB18030 解，encoding 说明按什么解的。
    */
-  readText(jobId: string, path: string, maxBytes?: number, opts?: { tail?: boolean }): Promise<TextChunk>;
+  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）失败。
@@ -171,6 +176,15 @@ export interface BoardBackend {
   browserLive?(jobId: string, handlers: BrowserLiveHandlers): () => void;
 }
 
+/** readBytes 读到的一段。 */
+export interface ByteChunk {
+  bytes: Uint8Array<ArrayBuffer>;
+  /** 这段在文件里从第几个字节开始。 */
+  start: number;
+  /** 文件总大小。 */
+  size: number;
+}
+
 export interface TextChunk {
   text: string;
   /** 只读到了一部分。 */
@@ -590,6 +604,30 @@ function createBoardClient(
     };
     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>>();
@@ -621,25 +659,14 @@ function createBoardClient(
       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 };
-      }
-      // 不支持 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 };
+      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);

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>) },
   };
 }
 

package/src/core/xlsx.ts

@@ -0,0 +1,142 @@
+// Excel（.xlsx / .xlsm）→ 纯文本：每个工作表一段 CSV，发给智能体。
+//
+// .xlsx 是 ZIP 里的一堆 XML：workbook.xml 列出工作表，sharedStrings.xml 是共享字符串，worksheets/sheetN.xml 是单元格。
+// 只取单元格的值（公式取缓存的结果），不要格式、图片、图表；日期按单元格格式认出来写成 2026-08-10（带时间的加上时分），
+// 百分比写成 0.6%（和表格里看到的一致）。
+// 老版 .xls（二进制）读不了，调用方提示另存为 .xlsx。
+
+export interface SheetText { name: string; hidden: boolean; rows: string[][] }
+
+const NS_MAIN = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const NS_REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+/** 内置的日期 / 时间数字格式编号。 */
+const BUILTIN_DATE_FMTS = new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 27, 30, 36, 45, 46, 47, 50, 57]);
+
+const parseXml = (text: string) => new DOMParser().parseFromString(text, "application/xml");
+const els = (root: Document | Element, tag: string) => Array.from(root.getElementsByTagNameNS(NS_MAIN, tag));
+
+/** 「A1」→ 列号（从 0 开始）。 */
+export function columnIndex(ref: string) {
+  let n = 0;
+  for (const ch of ref) {
+    const c = ch.toUpperCase().charCodeAt(0);
+    if (c < 65 || c > 90) break;
+    n = n * 26 + (c - 64);
+  }
+  return n - 1;
+}
+
+/** 自定义格式里有年月日时（引号里的、[颜色] 不算）就当日期。 */
+function isDateFormat(code: string) {
+  const bare = code.replace(/"[^"]*"/g, "").replace(/\[[^\]]*\]/g, "").replace(/\\./g, "");
+  return /[ymdhs]/i.test(bare) && !/^[#0.,%E+\-\s]*$/i.test(bare);
+}
+
+/** Excel 序列日期 → 2026-08-10 / 2026-08-10 14:30。 */
+export function excelDate(serial: number) {
+  const ms = Math.round((serial - 25569) * 86_400_000); // 1970-01-01 = 25569
+  const d = new Date(ms);
+  if (Number.isNaN(d.getTime())) return String(serial);
+  const p = (n: number) => String(n).padStart(2, "0");
+  const date = `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())}`;
+  const secs = d.getUTCHours() * 3600 + d.getUTCMinutes() * 60 + d.getUTCSeconds();
+  if (!secs) return date;
+  const time = `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}${d.getUTCSeconds() ? `:${p(d.getUTCSeconds())}` : ""}`;
+  return serial < 1 ? time : `${date} ${time}`;
+}
+
+/** 单元格里的文字：<t> 连起来（富文本是多段 <r><t>），不要注音（<rPh>）。 */
+function richText(el: Element) {
+  return els(el, "t").filter((t) => t.parentElement?.localName !== "rPh").map((t) => t.textContent ?? "").join("");
+}
+
+/** 读出所有工作表（按工作簿里的顺序）。 */
+export async function readXlsx(data: ArrayBuffer): Promise<SheetText[]> {
+  // 按需加载（mammoth 也用它，不额外增加体积）。
+  const mod = (await import("jszip")) as unknown as { default?: typeof import("jszip") } & typeof import("jszip");
+  const JSZip = mod.default ?? mod;
+  const zip = await JSZip.loadAsync(data);
+  const read = async (path: string) => { const f = zip.file(path); return f ? f.async("string") : null; };
+
+  const workbook = await read("xl/workbook.xml");
+  if (!workbook) throw new Error("不是 Excel 工作簿");
+  const rels = new Map<string, string>();
+  const relsXml = await read("xl/_rels/workbook.xml.rels");
+  if (relsXml) {
+    for (const r of Array.from(parseXml(relsXml).getElementsByTagName("Relationship"))) {
+      const target = r.getAttribute("Target") ?? "";
+      rels.set(r.getAttribute("Id") ?? "", target.startsWith("/") ? target.slice(1) : `xl/${target}`);
+    }
+  }
+  const shared: string[] = [];
+  const sharedXml = await read("xl/sharedStrings.xml");
+  if (sharedXml) for (const si of els(parseXml(sharedXml), "si")) shared.push(richText(si));
+
+  // 哪些样式是日期 / 百分比：cellXfs 第 i 个 → numFmtId → 内置格式或自定义格式。
+  const dateStyles = new Set<number>();
+  const percentStyles = new Set<number>();
+  const stylesXml = await read("xl/styles.xml");
+  if (stylesXml) {
+    const styles = parseXml(stylesXml);
+    const custom = new Map(els(styles, "numFmt").map((f) => [Number(f.getAttribute("numFmtId")), f.getAttribute("formatCode") ?? ""]));
+    const xfs = els(styles, "cellXfs")[0];
+    if (xfs) {
+      Array.from(xfs.children).filter((x) => x.localName === "xf").forEach((xf, i) => {
+        const id = Number(xf.getAttribute("numFmtId") ?? 0);
+        const code = custom.get(id);
+        if (BUILTIN_DATE_FMTS.has(id) || (code !== undefined && isDateFormat(code))) dateStyles.add(i);
+        else if (id === 9 || id === 10 || (code !== undefined && code.replace(/"[^"]*"/g, "").includes("%"))) percentStyles.add(i);
+      });
+    }
+  }
+
+  const sheets: SheetText[] = [];
+  for (const s of els(parseXml(workbook), "sheet")) {
+    const name = s.getAttribute("name") ?? `Sheet${sheets.length + 1}`;
+    const path = rels.get(s.getAttributeNS(NS_REL, "id") ?? s.getAttribute("r:id") ?? "") ?? `xl/worksheets/sheet${sheets.length + 1}.xml`;
+    const xml = await read(path);
+    if (!xml) continue;
+    const rows: string[][] = [];
+    for (const row of els(parseXml(xml), "row")) {
+      const r = Number(row.getAttribute("r")) || rows.length + 1;
+      const cells: string[] = [];
+      let next = 0;
+      for (const c of Array.from(row.children).filter((x) => x.localName === "c")) {
+        const ref = c.getAttribute("r");
+        const col = ref ? columnIndex(ref) : next;
+        next = col + 1;
+        const type = c.getAttribute("t");
+        const v = els(c, "v")[0]?.textContent ?? "";
+        let value: string;
+        if (type === "s") value = shared[Number(v)] ?? "";
+        else if (type === "inlineStr") value = richText(c);
+        else if (type === "b") value = v === "1" ? "TRUE" : v === "0" ? "FALSE" : v;
+        else if (type === "str" || type === "e" || !v) value = v;
+        else if (dateStyles.has(Number(c.getAttribute("s") ?? -1)) && Number.isFinite(Number(v))) value = excelDate(Number(v));
+        else if (percentStyles.has(Number(c.getAttribute("s") ?? -1)) && Number.isFinite(Number(v))) value = `${Number((Number(v) * 100).toPrecision(12))}%`;
+        else value = v;
+        cells[col] = value;
+      }
+      rows[r - 1] = Array.from(cells, (x) => x ?? "");
+    }
+    const dense = Array.from(rows, (x) => x ?? []);
+    // 去掉末尾的空行、每行末尾的空格子。
+    while (dense.length && dense[dense.length - 1].every((x) => !x)) dense.pop();
+    for (const row of dense) while (row.length && !row[row.length - 1]) row.pop();
+    sheets.push({ name, hidden: (s.getAttribute("state") ?? "visible") !== "visible", rows: dense });
+  }
+  return sheets;
+}
+
+const csvCell = (v: string) => (/[",\n\r]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v);
+
+/** 工作表 → 发给智能体的文字：每个工作表一个标题 + CSV。 */
+export function sheetsToText(sheets: SheetText[]) {
+  return sheets
+    .map((s) => {
+      const head = `## 工作表：${s.name}${s.hidden ? "（隐藏）" : ""}（${s.rows.length} 行）`;
+      return s.rows.length ? `${head}\n${s.rows.map((r) => r.map(csvCell).join(",")).join("\n")}` : `${head}\n（空）`;
+    })
+    .join("\n\n");
+}