@spzxg/cli-ui 0.6.5 → 0.6.7

package/src/core/client.ts

@@ -2,9 +2,12 @@ import { createSseParser } from "./sse";
 import { NEW_TASK, parseConvKey } from "./conversation";
 import type {
   BoardInfo, BrowserMessage, BrowserStatus, CenterJob, CenterTask, CenterTurn, DiffResult, DirListing, FileInfo, Message,
-  BatchStreamSnapshot, BrowserFramesState, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot,
+  BatchStreamSnapshot, BrowserFramesState, NewConversationOptions, SendResult, StreamEnd, StreamItem, StreamSnapshot, WorkspaceFileBatch,
 } from "./types";
 import { decodeText } from "./textDecode";
+import { createDocumentUploader, extractDocumentReferences, documentRequest, isTaskUploadPath, type UploadDocument, type DocumentUploadOptions, type DocumentReceipt } from "./documentUpload";
+import { syncFile, type FileSyncTransport } from "../board/fileSync";
+import { createFileSyncTransport } from "../board/fileSyncTransport";
 
 /**
  * center 服务（cli-task-center）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
@@ -78,6 +81,11 @@ const ERROR_TEXT: Record<string, string> = {
   task_already_finished: "当前子任务已经结束，请刷新状态后继续",
   task_not_paused: "当前子任务没有暂停，请刷新状态后重试",
   job_already_paused: "整个任务已暂停，请先恢复整个任务",
+  file_watch_unsupported: "当前服务不支持文件事件",
+  browser_required: "传递浏览器 YAML 手册或操作间隔时，需要同时启用 browser: true",
+  invalid_browser_playbook: "浏览器 YAML 手册校验失败，请检查格式和步骤配置",
+  invalid_browser_pacing: "浏览器操作间隔无效，请检查最小值和最大值",
+  conversation_browser_fields_fixed: "浏览器手册和操作间隔在创建对话时确定，追加消息不能修改",
 };
 
 /**
@@ -87,6 +95,8 @@ const ERROR_TEXT: Record<string, string> = {
  * 带 ? 的是可选能力：后端不提供，界面就按 Operator 在「没有这个能力」时的样子显示（例如提问的回答改走下一条消息）。
  */
 export interface ConversationBackend {
+  /** Upload original HTML/Markdown without embedding document bytes in a message. */
+  uploadDocument?: UploadDocument;
   baseUrl: string;
   getJob(jobId: string): Promise<CenterJob>;
   /** taskId：只要对话任务里这一个对话的轮次。 */
@@ -138,6 +148,15 @@ export interface ConversationBackend {
  * 方法里的 jobId 也可以是对话键（"job_x#task_y"）：看对话任务里那个对话的文件、改动和浏览器。
  */
 export interface BoardBackend {
+  /** Save an original file to this conversation without sending a message or starting the agent. */
+  uploadFile?(jobId: string, file: File, options: DocumentUploadOptions): Promise<DocumentReceipt>;
+  /** Authorized input directory of this task; browsing it never starts an agent turn. */
+  uploadDirectory?(jobId: string, signal?: AbortSignal): Promise<string | null>;
+  /** Immutable revisions and content-addressed blocks; refreshes reuse validated local blocks. */
+  fileSync?: FileSyncTransport;
+  /** One directory page only. No recursive scan or file body prefetch. */
+  listFiles?(jobId: string, dir: string, options?: { cursor?: string; limit?: number; signal?: AbortSignal }): Promise<DirListing>;
+  pollFiles?(jobId: string, scope: { paths: string[]; dirs: string[]; cursor?: string }, signal?: AbortSignal): Promise<WorkspaceFileBatch & { cursor?: string; directories: Array<{ path: string; revision: string | null }> }>;
   /** fileUrl 给出的地址浏览器能直接打开（不需要额外请求头）。false 时看板先 fetch 再显示。 */
   directLinks: boolean;
   info(jobId: string): Promise<BoardInfo>;
@@ -158,12 +177,12 @@ export interface BoardBackend {
    * 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>;
+  readText(jobId: string, path: string, maxBytes?: number, opts?: { tail?: boolean; signal?: AbortSignal; 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>;
+  readBytes?(jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; signal?: AbortSignal; onBytes?: (bytes: number) => void }): Promise<ByteChunk>;
   /**
    * 读整个文件。signal 取消（打包下载点了取消）；onBytes 报已收到的字节数（大文件显示进度）。
    * 弱网：FILE_HEADER_TIMEOUT_MS 内没回响应头、或传输中 FILE_STALL_MS 没收到数据，按网络错误（NETWORK）失败。
@@ -281,6 +300,7 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
 
   return {
     baseUrl: base,
+    uploadDocument: createDocumentUploader(doFetch, `${base}/api/file-sync`, headers),
     getJob: (jobId: string) => request<CenterJob>(`/api/jobs/${id(jobId)}`),
     listTurns: (jobId: string, query: { afterSeq?: number; limit?: number; taskId?: string } = {}) => {
       const params = new URLSearchParams();
@@ -321,18 +341,21 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
         ...(opts.callback ? { callback: opts.callback } : {}),
         tasks: [{
           title,
-          prompt: firstMessage,
+          prompt: extractDocumentReferences(firstMessage).text,
+          ...(extractDocumentReferences(firstMessage).attachments ? { attachments: extractDocumentReferences(firstMessage).attachments } : {}),
           ...(opts.businessId ? { business_id: opts.businessId } : {}),
           ...(opts.agent ? { agent: opts.agent } : {}),
           ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
-          ...(opts.browser ? { browser: true } : {}),
+          ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
+          ...(opts.browserPlaybook !== undefined ? { browser_playbook: opts.browserPlaybook } : {}),
+          ...(opts.browserPacing !== undefined ? { browser_pacing: opts.browserPacing } : {}),
         }],
       });
     },
     /** 带 business_id 时 center 按它去重，网络超时可以放心重发同一条。 */
     sendMessage: (jobId: string, text: string, opts: { businessId?: string; timeoutSeconds?: number; taskId?: string } = {}) =>
       post<SendResult>(`/api/jobs/${id(jobId)}/messages`, {
-        text,
+        ...extractDocumentReferences(text),
         ...(opts.taskId ? { task_id: opts.taskId } : {}),
         ...(opts.businessId ? { business_id: opts.businessId } : {}),
         ...(opts.timeoutSeconds ? { timeout_seconds: opts.timeoutSeconds } : {}),
@@ -340,7 +363,7 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
     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 } : {}) }],
+        tasks: [{ title: opts.title || firstLine(text, 60), prompt: extractDocumentReferences(text).text, ...(extractDocumentReferences(text).attachments ? { attachments: extractDocumentReferences(text).attachments } : {}), continue_from: taskId, ...(opts.businessId ? { business_id: opts.businessId } : {}) }],
       });
       return { task_id: result.task_ids[0] };
     },
@@ -349,7 +372,7 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
     /** 同一个 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`, {
-        text,
+        ...extractDocumentReferences(text),
         ...(opts.title ? { title: opts.title } : {}),
         ...(opts.agent ? { agent: opts.agent } : {}),
         ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
@@ -465,6 +488,13 @@ function openSse(
     try {
       arm();
       const response = await doFetch(url, { headers: { ...headers, Accept: "text/event-stream" }, signal: ctl.signal });
+      // A host-supplied fetch may resolve after cancellation despite signal.
+      // Retire its body before acquiring a reader or restarting the watchdog.
+      if (ctl.signal.aborted) {
+        void response.body?.cancel().catch(() => undefined);
+        if (silent) onClose?.(new CenterError("连接长时间没有数据，已断开重连", "NETWORK", 0));
+        return;
+      }
       if (!response.ok || !response.body) {
         const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
         throw new CenterError(body?.detail ?? ERROR_TEXT[body?.error ?? ""] ?? `连接失败（HTTP ${response.status}）`, body?.error ?? `HTTP_${response.status}`, response.status);
@@ -548,7 +578,11 @@ function createBoardClient(
         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, cache: "no-store" }), stopped]);
+      const fetching = doFetch(boardFileUrl(base, jobId, path), { headers: headers(extra), signal: ctl.signal, cache: "no-store" });
+      // Host fetch adapters can ignore abort. Dispose a response that arrives
+      // after the caller already cancelled or timed out.
+      void fetching.then(late => { if (ctl.signal.aborted) void late.body?.cancel().catch(() => undefined); }, () => undefined);
+      response = await Promise.race([fetching, stopped]);
     } catch (error) {
       release();
       if (signal?.aborted) throw aborted();
@@ -556,21 +590,19 @@ function createBoardClient(
       throw new CenterError(`连不上任务中心：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
     }
     clearTimeout(timer);
-    if (!response.ok && response.status !== 416) {
-      release();
-      const body = (await response.json().catch(() => null)) as { error?: string; detail?: string } | null;
-      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);
-    }
     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>> => {
+      if (signal?.aborted) { release(); void response.body?.cancel().catch(() => undefined); throw aborted(); }
       // 空文件要「前 N 字节」：节点回 416，就是空的。
       if (response.status === 416) { release(); return new Uint8Array(0); }
       const reader = response.body?.getReader();
       if (!reader) {
         try { return new Uint8Array(await response.arrayBuffer()); } finally { release(); }
       }
+      const cancelBody = () => { void reader.cancel().catch(() => undefined); };
+      ctl.signal.addEventListener("abort", cancelBody, { once: true });
+      if (ctl.signal.aborted) cancelBody();
       const chunks: Uint8Array[] = [];
       let got = 0;
       let stalled = false;
@@ -598,6 +630,11 @@ function createBoardClient(
         throw new CenterError(`读取「${name}」中断：${error instanceof Error ? error.message : String(error)}`, "NETWORK", 0);
       } finally {
         clearTimeout(stall);
+        ctl.signal.removeEventListener("abort", cancelBody);
+        // Progress callbacks may throw too; no abandoned response should keep
+        // consuming the mobile connection after the read has failed.
+        void reader.cancel().catch(() => undefined);
+        try { reader.releaseLock(); } catch { /* already released */ }
         release();
       }
       if (signal?.aborted) throw aborted();
@@ -612,16 +649,25 @@ function createBoardClient(
       }
       return all;
     };
+    if (!response.ok && response.status !== 416) {
+      // Error bodies need the same abort/stall bounds as file data. A proxy
+      // returning 401 headers and then hanging must not park a read forever.
+      const bytes = await body({ limit: 8192 });
+      let problem: { error?: string; detail?: string } | null = null;
+      try { problem = JSON.parse(new TextDecoder().decode(bytes)); } catch { /* use the HTTP fallback */ }
+      const fallback = response.status === 404 ? "文件不存在（可能已被任务删除或改名）" : problem?.error ?? `读取失败（HTTP ${response.status})`;
+      throw new CenterError(problem?.detail ?? ERROR_TEXT[problem?.error ?? ""] ?? fallback, problem?.error ?? `HTTP_${response.status}`, response.status);
+    }
     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 readRange = async (jobId: string, path: string, opts: { start?: number; maxBytes: number; tail?: boolean; signal?: AbortSignal; 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 { response, body } = await fileFetch(jobId, path, { Range: opts.tail ? `bytes=-${maxBytes}` : `bytes=${from}-${from + maxBytes - 1}` }, opts.signal);
     const contentType = response.headers.get("content-type") ?? "text/plain";
     const total = /\/(\d+)\s*$/.exec(response.headers.get("content-range") ?? "")?.[1];
     // 416：要的起点不在文件里（空文件，或文件变短了）。
@@ -643,10 +689,28 @@ function createBoardClient(
   const minting = new Map<string, Promise<string | null>>();
   let linksUnsupported = false;
   const LINK_REFRESH_MS = 5 * 60_000;
+  const uploads = new Map<string, UploadDocument>();
+  const fileSync = createFileSyncTransport(doFetch, (jobId, operation) => `${base}${boardPath(jobId, `file-sync/${operation}`)}`, headers);
   return {
     directLinks,
+    uploadFile(jobId, file, options) {
+      let upload = uploads.get(jobId);
+      if (!upload) {
+        const { job, task } = boardTarget(jobId);
+        upload = createDocumentUploader(doFetch, `${base}/api/jobs/${job}${task ? `/tasks/${task}` : ""}/file-sync`, headers);
+        uploads.set(jobId, upload);
+      }
+      return upload(file, options);
+    },
+    async uploadDirectory(jobId, signal) {
+      const capabilities = await documentRequest<{ uploadsPath?: string }>(doFetch, `${base}${boardPath(jobId, "file-sync/capabilities")}`, { signal }, headers);
+      return typeof capabilities.uploadsPath === "string" ? capabilities.uploadsPath : null;
+    },
+    fileSync,
+    listFiles: (jobId, dir, options = {}) => documentRequest<DirListing>(doFetch, `${base}${boardPath(jobId, "file-sync/list", new URLSearchParams({ dir: dir || ".", limit: String(options.limit ?? 200), ...(options.cursor ? { cursor: options.cursor } : {}) }).toString())}`, { signal: options.signal }, headers),
     info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
-    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
+    pollFiles: (jobId, scope, signal) => documentRequest(doFetch, `${base}${boardPath(jobId, "file-sync/changes")}`, { method: "POST", signal, headers: { "Content-Type": "application/json" }, body: JSON.stringify(scope) }, headers),
+    stat: (jobId, path = ".") => documentRequest<DirListing | FileInfo>(doFetch, `${base}${boardPath(jobId, "file-sync/stat", `path=${encodeURIComponent(path)}`)}`, {}, headers),
     fileUrl: (jobId, path, opts = {}) => boardFileUrl(base, jobId, path, opts.download),
     async fileLinkBase(jobId) {
       const { job, task } = boardTarget(jobId);
@@ -669,7 +733,7 @@ function createBoardClient(
       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 });
+      const { bytes, start, size, contentType } = await readRange(jobId, path, { maxBytes, tail: opts.tail, signal: opts.signal, 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 };
@@ -679,6 +743,11 @@ function createBoardClient(
       return { bytes, start, size };
     },
     async readBuffer(jobId, path, opts = {}) {
+      if (isTaskUploadPath(path)) {
+        const file = await syncFile(fileSync, jobId, path, { signal: opts.signal, decode: false,
+          onProgress: progress => opts.onBytes?.(progress.loadedBytes) });
+        return file.bytes.buffer as ArrayBuffer;
+      }
       const { body } = await fileFetch(jobId, path, {}, opts.signal);
       return (await body({ onBytes: opts.onBytes })).buffer;
     },

package/src/core/conversation.ts

@@ -135,6 +135,7 @@ const batchStreamTask = (task: BatchStreamTask): StreamTask => ({
   // 对话式子任务跑完一条不算结束：还能接着聊。
   id: task.id, seq: task.seq, title: task.title, status: task.status, closed: !task.conversation && TERMINAL_TASK.has(task.status),
   remote_task_id: task.remote_task_id, continue_from_task_id: task.continue_from_task_id,
+  awaiting_input: task.awaiting_input, awaiting_input_observed_at: task.awaiting_input_observed_at,
 });
 
 /** 没指定子任务时看哪个：最近一个派发过的，都没派发过就是最后一个。 */

package/src/core/documentUpload.ts

@@ -0,0 +1,196 @@
+import { createFileWorkQueue } from "../board/fileSyncQueue";
+/** Original attachments. The message contains an authorized reference only. */
+export const DOCUMENT_MAX_BYTES = 100 * 1024 * 1024;
+export const UPLOAD_OTHER_MAX_BYTES = 10 * 1024 * 1024;
+export const DOCUMENT_CHUNK_BYTES = 1024 * 1024;
+export const isOriginalDocument = (name: string) => /\.(html?|md|markdown)$/i.test(name);
+export const isTaskUploadPath = (path: string) => /\/(?:uploads|attachments)\/[^/]+\/[^/]+$/.test(path.replace(/\\/g, "/"));
+const UPLOAD_TYPES: Record<string, string> = {
+  html: "text/html", htm: "text/html", md: "text/markdown", markdown: "text/markdown",
+  txt: "text/plain", log: "text/plain", yaml: "text/yaml", yml: "text/yaml", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+  js: "text/plain", jsx: "text/plain", mjs: "text/plain", cjs: "text/plain", ts: "text/plain", tsx: "text/plain", mts: "text/plain", cts: "text/plain", py: "text/plain", sh: "text/plain", css: "text/plain", mjsx: "text/plain", cjsx: "text/plain", mtsx: "text/plain", ctsx: "text/plain",
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", xlsm: "application/vnd.ms-excel.sheet.macroEnabled.12",
+};
+export const FILE_UPLOAD_ACCEPT = Object.keys(UPLOAD_TYPES).map(extension => `.${extension}`).join(",");
+export const uploadFileType = (name: string) => {
+  const dot = name.lastIndexOf(".");
+  const extension = dot > 0 ? name.slice(dot + 1).toLowerCase() : undefined;
+  return extension && Object.hasOwn(UPLOAD_TYPES, extension) ? UPLOAD_TYPES[extension] : undefined;
+};
+export type DocumentReceipt = { uploadId: string; draftId: string; name: string; size: number; sha256: string; path?: string; url?: string };
+export type UploadPhase = "queued" | "checking" | "uploading" | "verifying";
+export type DocumentUploadOptions = { draftId: string; signal?: AbortSignal; onBytes?: (bytes: number) => void; onPhase?: (phase: UploadPhase) => void };
+export type UploadDocument = (file: File, options: DocumentUploadOptions) => Promise<DocumentReceipt>;
+const aborted = () => new DOMException("上传已取消", "AbortError");
+function pause(ms: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) return reject(aborted());
+    const stop = () => { clearTimeout(timer); reject(aborted()); };
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", stop); resolve(); }, ms);
+    signal?.addEventListener("abort", stop, { once: true });
+  });
+}
+
+/** Blob cloning is cheap; hashing a 100 MiB file does not copy it through the UI thread. */
+export async function hashDocument(file: Blob, signal?: AbortSignal): Promise<string> {
+  if (signal?.aborted) throw aborted();
+  if (typeof Worker !== "undefined" && typeof URL.createObjectURL === "function") {
+    const source = `onmessage=async e=>{try{const bytes=await e.data.arrayBuffer();const hash=await crypto.subtle.digest('SHA-256',bytes);postMessage({hash:Array.from(new Uint8Array(hash),b=>b.toString(16).padStart(2,'0')).join('')});}catch(e){postMessage({error:String(e)})}}`;
+    const url = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+    let worker: Worker | undefined;
+    try {
+      worker = new Worker(url);
+      return await new Promise<string>((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", stop); worker!.onmessage = null; worker!.onerror = null; };
+        const stop = () => { cleanup(); reject(aborted()); };
+        const timer = setTimeout(() => { cleanup(); reject(Object.assign(new Error("文件校验超时，请重试"), { status: 408, code: "hash_timeout" })); }, 120_000);
+        signal?.addEventListener("abort", stop, { once: true });
+        worker!.onmessage = e => { cleanup(); e.data?.hash ? resolve(e.data.hash) : reject(new Error(e.data?.error || "文件校验失败，请重试")); };
+        worker!.onerror = () => { cleanup(); reject(new Error("文件校验失败，请重试")); };
+        if (signal?.aborted) { stop(); return; }
+        try { worker!.postMessage(file); } catch (error) { cleanup(); reject(error); }
+      });
+    } finally { worker?.terminate(); URL.revokeObjectURL(url); }
+  }
+  const digest = await crypto.subtle.digest("SHA-256", await file.arrayBuffer());
+  if (signal?.aborted) throw aborted();
+  return Array.from(new Uint8Array(digest), b => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** All calls are bounded short requests, including body reads. */
+export async function documentRequest<T>(fetcher: typeof fetch, url: string, init: RequestInit = {}, headers: () => Record<string, string> = () => ({})): Promise<T> {
+  const ctl = new AbortController();
+  const signal = init.signal;
+  const cancel = () => ctl.abort();
+  if (signal?.aborted) throw aborted();
+  signal?.addEventListener("abort", cancel, { once: true });
+  const timer = setTimeout(cancel, 30_000);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let rejectAbort: (() => void) | undefined;
+  try {
+    const cancelled = new Promise<never>((_resolve, reject) => { rejectAbort = () => reject(aborted()); ctl.signal.addEventListener("abort", rejectAbort, { once: true }); });
+    return await Promise.race([cancelled, (async () => {
+    const response = await fetcher(url, { ...init, cache: "no-store", signal: ctl.signal, headers: { ...headers(), ...init.headers } });
+    if (ctl.signal.aborted) { void response.body?.cancel().catch(() => undefined); throw aborted(); }
+    reader = response.body?.getReader();
+    let raw = "", bytes = 0;
+    if (reader) {
+      const decoder = new TextDecoder();
+      for (;;) {
+        const part = await reader.read(); if (part.done) break;
+        bytes += part.value.byteLength;
+        if (bytes > 2 * 1024 * 1024) throw Object.assign(new Error("文件响应超过协议上限"), { status: 502, code: "response_too_large" });
+        raw += decoder.decode(part.value, { stream: true });
+      }
+      raw += decoder.decode();
+    } else raw = await response.text();
+    let value: Record<string, unknown>;
+    try { value = raw ? JSON.parse(raw) : {}; } catch { throw Object.assign(new Error("文件接口返回的数据无效"), { status: 502, code: "invalid_response" }); }
+    const retryHeader = response.headers.get("retry-after");
+    const retryHint = retryHeader ? (/^\d+(\.\d+)?$/.test(retryHeader) ? Number(retryHeader) * 1000 : Date.parse(retryHeader) - Date.now()) : undefined;
+    const retryAfterMs = retryHint !== undefined && Number.isFinite(retryHint) ? Math.max(0, retryHint) : undefined;
+    if (response.status === 202) throw Object.assign(new Error("文件正在校验"), { status: 202, retryAfterMs: retryAfterMs ?? 1000 });
+    if (!response.ok) {
+      const missing = value.error === "file_not_found" ? "文件不存在（可能已被删除或改名）" : "服务端尚未支持原件上传或增量文件同步，请升级节点和中枢";
+      const common: Record<string, string> = { file_sync_busy: "文件服务繁忙，请稍后重试", too_many_snapshot_builds: "文件服务繁忙，请稍后重试", too_many_uploads: "上传任务较多，请稍后重试", file_sync_queue_timeout: "文件处理排队超时，请稍后重试", file_sync_timeout: "文件服务响应超时，请重试", snapshot_cache_full: "文件缓存空间不足，请稍后重试", upload_storage_full: "文件上传空间不足，请稍后重试" };
+      const error = new Error(common[String(value.error)] ?? String(value.detail || (response.status === 404 ? missing : value.error) || `文件请求失败（HTTP ${response.status}）`));
+      Object.assign(error, { status: response.status, code: value.error, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
+      throw error;
+    }
+    return value as T;
+    })()]);
+  } catch (error) {
+    if (signal?.aborted) throw aborted();
+    if (ctl.signal.aborted) throw Object.assign(new Error("文件请求超时，请重试"), { status: 0, code: "timeout" });
+    throw error;
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", cancel); if (rejectAbort) ctl.signal.removeEventListener("abort", rejectAbort); ctl.abort(); void reader?.cancel().catch(() => undefined); }
+}
+
+const uploadQueues = new WeakMap<typeof fetch, ReturnType<typeof createFileWorkQueue>>();
+async function retryUploadRequest<T>(work: () => Promise<T>, signal: AbortSignal | undefined, busyOnly = false, deadline = Date.now() + 180_000): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw aborted();
+    try { return await work(); } catch (error) {
+      const failure = error as { status?: number; code?: string; name?: string; retryAfterMs?: number };
+      const status = failure.status ?? 0;
+      const retryable = busyOnly ? status === 429 : !status || [408, 429, 500, 502, 503, 504].includes(status);
+      if (signal?.aborted || failure.name === "AbortError" || !retryable || attempt >= 3 || ["invalid_response", "response_too_large", "integrity", "client_queue_full"].includes(failure.code ?? "")) throw error;
+      const base = 500 * 2 ** attempt, hint = Number(failure.retryAfterMs ?? 0);
+      const delay = Math.max(base, Number.isFinite(hint) ? hint : 0) + Math.floor(Math.random() * base / 4);
+      if (delay > deadline - Date.now()) throw error;
+      await pause(delay, signal);
+    }
+  }
+}
+export function createDocumentUploader(fetcher: typeof fetch, base: string, headers: () => Record<string, string> = () => ({})): UploadDocument {
+  // Share hashing/upload slots across tasks using this client, with cancellable bounded waiters.
+  let queue = uploadQueues.get(fetcher);
+  if (!queue) { queue = createFileWorkQueue(1, 128); uploadQueues.set(fetcher, queue); }
+  return (file, options) => {
+    options.onPhase?.("queued");
+    const upload = async (): Promise<DocumentReceipt> => {
+      const { signal, onBytes, onPhase, draftId } = options;
+      if (signal?.aborted) throw aborted();
+      const type = uploadFileType(file.name);
+      if (!type) throw new Error("暂不支持此文件类型，请选择文档、图片或文本文件");
+      const maxBytes = isOriginalDocument(file.name) ? DOCUMENT_MAX_BYTES : UPLOAD_OTHER_MAX_BYTES;
+      if (file.size > maxBytes) throw new Error(`“${file.name}”超过 ${isOriginalDocument(file.name) ? "100" : "10"} MiB，请缩小后重试。`);
+      if (new TextEncoder().encode(file.name).length > 240) throw new Error("文件名超过 240 个 UTF-8 字节，请缩短文件名后重试。");
+      onPhase?.("checking");
+      const sha256 = await hashDocument(file, signal);
+      const request = <T>(path: string, init: RequestInit) => documentRequest<T>(fetcher, `${base}${path}`, { ...init, signal }, headers);
+      const session = await retryUploadRequest(() => request<{ uploadId: string; chunkBytes: number }>("/uploads", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ draftId, name: file.name, size: file.size, type, sha256 }) }), signal, true);
+      if (!session.uploadId || session.chunkBytes !== DOCUMENT_CHUNK_BYTES) throw new Error("上传协议不匹配，请升级服务端");
+      const root = `/uploads/${encodeURIComponent(session.uploadId)}`;
+      try {
+        onPhase?.("uploading");
+        onBytes?.(0);
+        for (let start = 0, index = 0; start < file.size; start += session.chunkBytes, index++) {
+          const body = file.slice(start, Math.min(file.size, start + session.chunkBytes));
+          // Only these numbered chunks are safely idempotent after ambiguous network failures.
+          await retryUploadRequest(() => request(`${root}/chunks/${index}`, { method: "PUT", headers: { "Content-Type": "application/octet-stream" }, body }), signal);
+          onBytes?.(Math.min(file.size, start + session.chunkBytes));
+        }
+        onPhase?.("verifying");
+        const deadline = Date.now() + 180_000;
+        for (;;) {
+          try {
+            const result = await retryUploadRequest(() => request<DocumentReceipt>(`${root}/complete`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ draftId }) }), signal, false, deadline);
+            if (result.sha256 !== sha256) throw new Error("上传文件校验不一致，请重试");
+            return { ...result, draftId, name: file.name, size: file.size };
+          } catch (error) {
+            const pending = error as { status?: number; retryAfterMs?: number };
+            if (pending.status !== 202 || Date.now() >= deadline) throw error;
+            const delay = Math.max(100, pending.retryAfterMs ?? 1000);
+            if (delay > deadline - Date.now()) throw error;
+            await pause(delay, signal);
+          }
+        }
+      } catch (error) {
+        void documentRequest(fetcher, `${base}${root}`, { method: "DELETE" }, headers).catch(() => undefined);
+        throw error;
+      }
+    };
+    return queue.run(upload, options.signal);
+  };
+}
+
+export function documentMarker(receipt: DocumentReceipt) {
+  if (receipt.path) {
+    if (/[\r\n\]]/.test(receipt.path)) throw new Error("上传文件路径无效，请重试");
+    return `[Attached ${uploadFileType(receipt.name)?.startsWith("image/") ? "image" : "file"}: ${receipt.path}]`;
+  }
+  const name = receipt.name.replace(/[\r\n\[\]]/g, " ");
+  return `[文件原件：${name}](cli-upload://${encodeURIComponent(receipt.draftId)}/${encodeURIComponent(receipt.uploadId)})`;
+}
+
+export function extractDocumentReferences(text: string) {
+  const attachments: Array<{ uploadId: string; draftId: string }> = [];
+  const clean = text.replace(/\[文件原件：([^\]\r\n]*)\]\(cli-upload:\/\/([^/\s)]+)\/([^\s)]+)\)/g, (_match, name, draft, upload) => {
+    try { attachments.push({ draftId: decodeURIComponent(draft), uploadId: decodeURIComponent(upload) }); } catch { throw new Error("文件引用无效，请移除后重新上传"); }
+    return `[文件原件：${name}]`;
+  });
+  return { text: clean, ...(attachments.length ? { attachments } : {}) };
+}

package/src/core/provider.tsx

@@ -70,6 +70,13 @@ export function CliCenterProvider({ store: external, selectedId, onEvent, onTurn
     if (selectedId !== undefined) { created.select(selectedId); applied.current = selectedId; }
     return created;
   }, [external]); // eslint-disable-line react-hooks/exhaustive-deps
+  // Creation defaults can arrive after a file/configuration load. Update only
+  // these defaults on commit; the connection and workspace state stay stable.
+  useLayoutEffect(() => {
+    optionsRef.current.newConversation = options.newConversation;
+    optionsRef.current.createConversation = options.createConversation;
+    optionsRef.current.businessIdFor = options.businessIdFor;
+  }, [options.newConversation, options.createConversation, options.businessIdFor]);
   // 之后宿主改了 selectedId：一起切过去（在绘制前，免得闪一下旧的）。
   useLayoutEffect(() => {
     if (selectedId === undefined || selectedId === applied.current) return;