@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/chat/export.ts

@@ -0,0 +1,34 @@
+import type { CenterTurn, Msg } from "../core/types";
+import { toolDataOf } from "../ui/transcriptModel";
+
+/** 把对话过程导出成 Markdown 下载（对应 Operator 的「导出执行过程」，这里在前端用已加载的转录生成）。 */
+export function buildMarkdown(title: string, jobId: string, messages: Msg[], turns: CenterTurn[]): string {
+  const tokens = turns.reduce((sum, turn) => sum + (turn.total_tokens || 0), 0);
+  const lines = [`# ${title}`, "", `- 对话：${jobId}`, `- 轮次：${turns.length}`, `- tokens：${tokens.toLocaleString()}`, `- 导出时间：${new Date().toLocaleString()}`, ""];
+  for (const m of messages) {
+    const time = m.ts ? ` · ${new Date(m.ts).toLocaleString()}` : "";
+    if (m.role === "user" || m.role === "queued") lines.push(`## 你${m.role === "queued" ? "（排队中）" : ""}${time}`, "", m.content, "");
+    else if (m.role === "assistant") lines.push(`## 智能体${time}`, "", m.content, "");
+    else if (m.role === "system") lines.push(`> ${m.content.replace(/\n/g, "\n> ")}`, "");
+    else if (m.role === "tool") {
+      const data = toolDataOf(m);
+      lines.push(`<details><summary>工具：${data.title}${data.isError ? "（失败）" : ""}</summary>`, "");
+      if (data.detail) lines.push("```", data.detail, "```", "");
+      if (data.result !== undefined) lines.push("结果：", "", "```", data.result, "```", "");
+      lines.push("</details>", "");
+    }
+  }
+  return lines.join("\n");
+}
+
+export function exportMarkdown(title: string, jobId: string, messages: Msg[], turns: CenterTurn[]) {
+  const blob = new Blob([buildMarkdown(title, jobId, messages, turns)], { type: "text/markdown;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${title.replace(/[\\/:*?"<>|]+/g, "_").slice(0, 60) || "对话"}.md`;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

package/src/chat/queueEdit.ts

@@ -0,0 +1,27 @@
+// 编辑排队消息：把排队的正文拆回输入框——输入的文字 + 文本块（粘贴的长文本、文件原件、引用、业务背景）。
+// 只去掉发送时会自动重新附带的部分：「看板正在看」的被动背景、带原件时自动加的那句提示。
+import { ORIGINALS_NOTE, splitMessage, type TextBlock } from "../core/blocks";
+import { clientId } from "../core/id";
+import { updateComposerDraft } from "./draft";
+
+export function queuedToDraft(content: string): { text: string; blocks: TextBlock[] } {
+  const texts: string[] = [];
+  const blocks: TextBlock[] = [];
+  for (const part of splitMessage(content)) {
+    if (part.kind === "text") texts.push(part.text);
+    else if (part.block.kind !== "viewing") blocks.push(part.block);
+  }
+  const text = texts.join("\n\n").split("\n").filter((line) => line.trim() !== ORIGINALS_NOTE).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  return { text, blocks };
+}
+
+/** 放回输入框：排队的内容在前，输入框里还没发的草稿接在后面——两边都不丢。 */
+export function restoreQueuedToDraft(draftId: string, content: string) {
+  const restored = queuedToDraft(content);
+  updateComposerDraft(draftId, (current) => ({
+    ...current,
+    text: [restored.text, current.text].filter((value) => value.trim()).join("\n\n"),
+    blocks: [...restored.blocks.map((block) => ({ ...block, key: clientId() })), ...current.blocks],
+    error: null,
+  }));
+}

package/src/chat/useExecutionConfig.ts

@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { CenterError, type ConversationBackend } from "../core/client";
+import type { ExecutionConfiguration, ExecutionOptions } from "../core/execution";
+import { isConfigurationBusy, useConfigurationBusy } from "./configuration";
+import { readComposerDraft, updateComposerDraft, useComposerDraft } from "./draft";
+
+const errorText = (error: unknown) => error instanceof CenterError && [404, 405, 501].includes(error.status)
+  ? "当前服务尚未支持执行设置，请升级配套服务。"
+  : error instanceof Error ? error.message : "执行设置读取失败，请重试。";
+
+function validate(result: ExecutionConfiguration) {
+  if (!result || typeof result.agent !== "string" || !Number.isSafeInteger(result.revision) || result.revision < 0 || !Array.isArray(result.agents)
+    || result.agents.some(agent => typeof agent?.id !== "string" || typeof agent.label !== "string" || !agent.capabilities
+      || [agent.capabilities.models, agent.capabilities.reasoningOptions, agent.capabilities.permissionModes].some(options => !Array.isArray(options)
+        || options.some(option => typeof option?.value !== "string" || typeof option.label !== "string")))) {
+    throw new Error("服务未返回有效的执行设置，请检查配套服务版本。");
+  }
+}
+
+/** 按对话隔离读取与保存，不轮询；换对话后的迟到响应不覆盖当前选择。 */
+export function useExecutionConfig({ client, scope, target, enabled, ready = true, initial, running }: {
+  client: ConversationBackend; scope: string; target: string | null; enabled: boolean;
+  initial?: ExecutionOptions; running: boolean; ready?: boolean;
+}) {
+  const [view, setView] = useState<{ scope: string; config?: ExecutionConfiguration; error?: string; loading: boolean; saveFailed?: boolean }>({ scope, loading: false });
+  const current = useRef(scope);
+  const request = useRef(0);
+  const mounted = useRef(true);
+  useLayoutEffect(() => { current.current = scope; request.current++; }, [scope]);
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; request.current++; }; }, []);
+  const draft = useComposerDraft(scope);
+  const busy = useConfigurationBusy(scope);
+  const config = view.scope === scope ? view.config : undefined;
+  const reload = useCallback(async () => {
+    const serial = ++request.current;
+    const active = () => mounted.current && current.current === scope && request.current === serial;
+    if (!ready || (!enabled && !readComposerDraft(scope).executionUncertain)) return;
+    if (!client.getExecutionConfig) {
+      setView({ scope, loading: false, error: "当前接入尚未提供执行设置。" });
+      return;
+    }
+    setView(value => ({ ...(value.scope === scope ? value : {}), scope, loading: true }));
+    try {
+      const result = await client.getExecutionConfig(target);
+      validate(result);
+      if (active()) {
+        if (!isConfigurationBusy(scope) && readComposerDraft(scope).executionUncertain) updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: false }));
+        setView({ scope, config: result, loading: false });
+      }
+    } catch (error) {
+      if (active()) setView(value => ({ ...(value.scope === scope ? value : {}), scope, error: errorText(error), loading: false }));
+    }
+  }, [client, scope, target, enabled, ready]);
+  useEffect(() => { void reload(); return () => { request.current++; }; }, [reload]);
+  const wasRunning = useRef(running);
+  useEffect(() => {
+    if (wasRunning.current && !running && !isConfigurationBusy(scope)) void reload();
+    wasRunning.current = running;
+  }, [running, reload, scope]);
+
+  const local = target === null ? { ...initial, ...draft.executionConfig } : undefined;
+  const selected = config ? { ...config, ...local } : undefined;
+  const save = async (changes: ExecutionOptions) => {
+    if (!config || !enabled || running) throw new Error("当前无法修改执行设置，请稍后重试。");
+    if (target === null) {
+      updateComposerDraft(scope, value => ({ ...value, executionConfig: { agent: config.agent, ...initial, ...value.executionConfig, ...changes } }));
+      return;
+    }
+    if (!client.setExecutionConfig) throw new Error("当前接入尚未提供保存执行设置的接口。");
+    // An earlier GET must not overwrite the response to this save.
+    const serial = ++request.current;
+    updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: true }));
+    try {
+      const result = await client.setExecutionConfig(target, changes, config.revision);
+      validate(result);
+      updateComposerDraft(scope, draft => ({ ...draft, executionUncertain: false }));
+      if (mounted.current && current.current === scope && request.current === serial) setView({ scope, config: result, loading: false });
+    } catch (error) {
+      if (mounted.current && current.current === scope && request.current === serial) setView({ scope, config, loading: false, saveFailed: true, error: `${errorText(error)} 请重新读取设置后再发送。` });
+      throw error;
+    }
+  };
+  return {
+    config: selected, busy, loading: view.scope === scope && view.loading,
+    error: view.scope === scope && (enabled || view.saveFailed || draft.executionUncertain) ? view.error ?? (draft.executionUncertain && !busy ? "执行设置尚未确认，请重新读取后再发送。" : undefined) : undefined,
+    blocked: busy || !!draft.executionUncertain || (view.scope === scope && !!view.saveFailed), reload, save,
+    /** Read at submit time, including changes committed before React paints. */
+    prepareSend: () => {
+      if (isConfigurationBusy(scope) || readComposerDraft(scope).executionUncertain || (view.scope === scope && view.saveFailed)) throw new Error("请等待执行设置保存或重新读取设置后再发送。");
+      return target === null ? { executionConfig: readComposerDraft(scope).executionConfig } : { expectedExecutionRevision: config?.revision };
+    },
+  };
+}

package/src/components.tsx

@@ -0,0 +1,13 @@
+import type { ComponentProps } from "react";
+import { CliMsgList as CenterMsgList, type CliMsgListProps as CenterMsgListProps } from "./msglist/CliMsgList";
+import { CliChat as CenterChat, type CliChatProps as CenterChatProps } from "./chat/CliChat";
+import { CliBoard as CenterBoard, type CliBoardProps as CenterBoardProps } from "./board/CliBoard";
+import { TasksColumn } from "./operator/node/TasksColumn";
+import { SessionView } from "./operator/node/SessionView";
+import { SessionRail } from "./operator/node/SessionRail";
+export interface CliMsgListProps extends CenterMsgListProps { operator?: ComponentProps<typeof TasksColumn> }
+export interface CliChatProps extends CenterChatProps { operator?: ComponentProps<typeof SessionView> }
+export interface CliBoardProps extends CenterBoardProps { operator?: ComponentProps<typeof SessionRail> }
+export function CliMsgList(props: CliMsgListProps) { return props.operator ? <TasksColumn {...props.operator}/> : <CenterMsgList {...props}/>; }
+export function CliChat(props: CliChatProps) { return props.operator ? <SessionView {...props.operator} composer={props.config?.composer ?? props.operator.composer} board={{...props.operator.board,autoContext:props.operator.board?.autoContext??props.passiveContext,onFilesChange:props.operator.board?.onFilesChange??props.onFilesChange,onFilesWatch:props.operator.board?.onFilesWatch??props.onFilesWatch,onBoardContextChange:props.operator.board?.onBoardContextChange??props.onBoardContextChange}}/> : <CenterChat {...props}/>; }
+export function CliBoard(props: CliBoardProps) { return props.operator ? <SessionRail key={props.operator.task.id} {...props.operator} tabs={props.operator.tabs ?? props.tabs} availableTabs={props.operator.availableTabs ?? props.availableTabs} defaultTab={props.operator.defaultTab ?? props.defaultTab} autoContext={props.operator.autoContext ?? props.autoQuoteOpenFile} watchFiles={props.operator.watchFiles ?? props.watchFiles} fileWatchIntervalMs={props.operator.fileWatchIntervalMs ?? props.fileWatchIntervalMs} onFilesChange={props.operator.onFilesChange ?? props.onFilesChange} onFilesWatch={props.operator.onFilesWatch ?? props.onFilesWatch} onBoardContextChange={props.operator.onBoardContextChange ?? props.onBoardContextChange} onEvent={props.operator.onEvent ?? props.onEvent}/> : <CenterBoard {...props}/>; }

package/src/core/blocks.ts

@@ -0,0 +1,205 @@
+/**
+ * 「文本块」：上传的文档（Word / Excel / Markdown / TXT / HTML / CSV）和粘贴的大段文字。
+ *
+ * 前端先把文件解析成纯文本，再按统一格式拼进消息正文发给 center——center 只收纯文本。
+ * 同一个格式两头用：输入框里是可折叠的卡片，发出去之后转录里也解析回同样的卡片，
+ * 所以长内容在输入框和对话里都只显示开头，点开才看全部，不会把页面卡住。
+ *
+ *   ----- 附件：需求说明.docx（12,345 字）-----
+ *   ……纯文本……
+ *   ----- 附件结束：需求说明.docx -----
+ *
+ * 对 Agent 来说这也是清楚的分隔：哪段是附件、叫什么、在哪结束。
+ */
+
+import { decodeText } from "./textDecode";
+
+export interface TextBlock {
+  /** 显示名：文件名，粘贴的文字为「粘贴的文本」。 */
+  name: string;
+  text: string;
+  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}。用户没有另外说明时，消息里说的「这个」「这里」「改一下」等就是指它。` };
+}
+
+/** 补充背景合成的块的名字（转录里显示成「补充背景」卡片）。 */
+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、YAML、HTML、CSV / TSV。都在浏览器里转成文字。 */
+export const ACCEPTED_EXTENSIONS = [".docx", ".xlsx", ".xlsm", ".md", ".markdown", ".txt", ".yaml", ".yml", ".html", ".htm", ".csv", ".tsv"] as const;
+export const ACCEPT_ATTR = [
+  ...ACCEPTED_EXTENSIONS,
+  "text/plain", "text/markdown", "text/yaml", "application/yaml", "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、YAML（.yaml / .yml）、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;
+/** center 单条消息上限（POST /api/jobs/:id/messages 的 text 最长 200,000 字符）。 */
+export const MAX_MESSAGE_CHARS = 200_000;
+/** Same source-file budget as the full node composer; reject before reading/parsing. */
+export const MAX_DOCUMENT_BYTES = 10 * 1024 * 1024;
+export const PASTE_NAME = "粘贴的文本";
+
+const OPEN = /^----- 附件：(.+?)（[\d,]+ 字）-----$/;
+const CLOSE = (name: string) => `----- 附件结束：${name} -----`;
+
+export const charCount = (text: string) => Array.from(text).length;
+
+export function serializeBlock(block: TextBlock): string {
+  const name = block.name.replace(/[\r\n]/g, " ").trim() || PASTE_NAME;
+  return `----- 附件：${name}（${charCount(block.text).toLocaleString("en-US")} 字）-----\n${block.text}\n${CLOSE(name)}`;
+}
+
+/** 带原件附件时自动加在正文后的一句（编辑排队消息放回输入框时去掉，发送时会重新加上）。 */
+export const ORIGINALS_NOTE = "请先读取以下附件原件，再处理本条消息。";
+
+/** 输入框里的文字 + 文本块 → 发给 center 的正文。 */
+export function composeMessage(typed: string, blocks: TextBlock[]): string {
+  const originals = blocks.some(block => block.kind === "file" && (/^\[Attached (?:file|image): /.test(block.text) || /^\[文件原件：.*\]\(cli-upload:\/\//.test(block.text)));
+  return [typed.trim(), originals ? ORIGINALS_NOTE : "", ...blocks.map(serializeBlock)].filter(Boolean).join("\n\n");
+}
+
+export type MessagePart = { kind: "text"; text: string } | { kind: "block"; block: TextBlock };
+
+/** 正文 → 文字段和文本块（转录里渲染用）。不成对的标记原样当文字。 */
+export function splitMessage(content: string): MessagePart[] {
+  if (!content.includes("----- 附件：")) return [{ kind: "text", text: content }];
+  const lines = content.split("\n");
+  const parts: MessagePart[] = [];
+  let text: string[] = [];
+  const flush = () => {
+    const value = text.join("\n").trim();
+    if (value) parts.push({ kind: "text", text: value });
+    text = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const open = OPEN.exec(lines[i]);
+    const end = open ? lines.indexOf(CLOSE(open[1]), i + 1) : -1;
+    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 === VIEWING_NAME ? "viewing" : name === BACKGROUND_NAME ? "background" : "file" } });
+    i = end;
+  }
+  flush();
+  return parts.length ? parts : [{ kind: "text", text: content }];
+}
+
+/** 粘贴的内容是不是该转成文本块。 */
+export function isLongText(text: string) {
+  if (text.length > PASTE_BLOCK_CHARS) return true;
+  let lines = 1;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10 && ++lines > PASTE_BLOCK_LINES) return true;
+  return false;
+}
+
+export function extensionOf(name: string) {
+  const dot = name.lastIndexOf(".");
+  return dot === -1 ? "" : name.slice(dot).toLowerCase();
+}
+
+export class FileReadError extends Error {}
+
+/**
+ * 读出文件的纯文本：
+ *   · 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> {
+  if (file.size > MAX_DOCUMENT_BYTES) throw new FileReadError(`“${file.name}”超过 10 MB，请缩小后重试。`);
+  const text = await extractFileText(file);
+  if (text.length > MAX_MESSAGE_CHARS) throw new FileReadError(`“${file.name}”解析后的正文超过 ${MAX_MESSAGE_CHARS.toLocaleString("en-US")} 字符，请拆分后重试。`);
+  return text;
+}
+
+async function extractFileText(file: File): Promise<string> {
+  const ext = extensionOf(file.name);
+  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");
+    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");
+    const extract = (mammoth as unknown as { extractRawText: typeof import("mammoth").extractRawText }).extractRawText
+      ?? (mammoth as unknown as { default: typeof import("mammoth") }).default.extractRawText;
+    try {
+      const arrayBuffer = await readAs(file, "buffer");
+      // 浏览器版 mammoth 读 arrayBuffer；Node 版（测试、SSR）只认 buffer，有 Buffer 时一并给上。
+      const NodeBuffer = (globalThis as { Buffer?: { from(data: ArrayBuffer): unknown } }).Buffer;
+      const result = await extract({ arrayBuffer, ...(NodeBuffer ? { buffer: NodeBuffer.from(arrayBuffer) } : {}) } as { arrayBuffer: ArrayBuffer });
+      return normalizeText(result.value);
+    } catch {
+      throw new FileReadError("Word 文件解析失败，文件可能已损坏或不是 .docx 格式");
+    }
+  }
+  const { text } = decodeText(new Uint8Array(await readAs(file, "buffer")));
+  // YAML literal scalars depend on blank lines, indentation and the final newline.
+  if (ext === ".yaml" || ext === ".yml") return text;
+  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。 */
+function readAs(file: Blob, as: "text"): Promise<string>;
+function readAs(file: Blob, as: "buffer"): Promise<ArrayBuffer>;
+function readAs(file: Blob, as: "text" | "buffer"): Promise<string | ArrayBuffer> {
+  if (as === "text" && typeof file.text === "function") return file.text();
+  if (as === "buffer" && typeof file.arrayBuffer === "function") return file.arrayBuffer();
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string | ArrayBuffer);
+    reader.onerror = () => reject(reader.error ?? new FileReadError("文件读取失败"));
+    if (as === "text") reader.readAsText(file, "utf-8");
+    else reader.readAsArrayBuffer(file);
+  });
+}
+
+/** 统一换行、去掉 BOM 和首尾空行；段落间多余的空行压成一个。 */
+export function normalizeText(text: string) {
+  return text.replace(/^/, "").replace(/\r\n?/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}

package/src/core/callbacks.ts

@@ -0,0 +1,8 @@
+/** A host subscriber must not interrupt state updates or another subscriber. */
+export function notifyCallback<T>(callback: ((value: T) => unknown) | undefined, value: T): void {
+  const report = (error: unknown) => console.error("[@xgspz/cli-ui] subscriber callback failed", error);
+  try {
+    const result = callback?.(value);
+    if (result && typeof (result as PromiseLike<unknown>).then === "function") void Promise.resolve(result).catch(report);
+  } catch (error) { report(error); }
+}