@spzxg/cli-ui 0.6.6 → 0.6.7

package/src/core/client.ts

@@ -5,6 +5,9 @@ import type {
   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）对话任务接口的浏览器端客户端。组件的数据全部从这里来。
@@ -92,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：只要对话任务里这一个对话的轮次。 */
@@ -143,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>;
@@ -286,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();
@@ -326,7 +341,8 @@ 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 } : {}),
@@ -339,7 +355,7 @@ export function createCenterClient(options: CenterClientOptions = {}): Conversat
     /** 带 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 } : {}),
@@ -347,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] };
     },
@@ -356,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 } : {}),
@@ -534,31 +550,6 @@ function boardPath(key: string, rest: string, query = "") {
   return `/api/jobs/${job}/${rest}${params ? `?${params}` : ""}`;
 }
 
-/** Reject a malformed manifest as a whole: silently dropping entries could invent deletions. */
-function isWorkspaceFileBatch(value: unknown): value is WorkspaceFileBatch {
-  if (!value || typeof value !== "object") return false;
-  const batch = value as Record<string, unknown>;
-  if (typeof batch.complete !== "boolean" || (batch.revision !== undefined && typeof batch.revision !== "string")) return false;
-  const file = (value: unknown) => {
-    if (!value || typeof value !== "object") return false;
-    const entry = value as Record<string, unknown>;
-    return typeof entry.name === "string" && typeof entry.path === "string" && !!entry.path
-      && (entry.type === "file" || entry.type === "dir")
-      && typeof entry.size === "number" && Number.isFinite(entry.size) && entry.size >= 0
-      && typeof entry.mtime === "number" && Number.isFinite(entry.mtime)
-      && (entry.changeToken === undefined || typeof entry.changeToken === "string");
-  };
-  if (batch.type === "snapshot") return Array.isArray(batch.files) && batch.files.every(file);
-  if (batch.type === "resync") return batch.complete === false && typeof batch.reason === "string";
-  return batch.type === "changes" && Array.isArray(batch.changes) && batch.changes.every(value => {
-    if (!value || typeof value !== "object") return false;
-    const change = value as Record<string, unknown>;
-    return ["created", "modified", "deleted"].includes(String(change.kind)) && typeof change.path === "string" && !!change.path
-      && (change.file === undefined || (file(change.file) && (change.file as { path: string }).path === change.path))
-      && (change.previous === undefined || (file(change.previous) && (change.previous as { path: string }).path === change.path));
-  });
-}
-
 function createBoardClient(
   base: string,
   headers: (extra?: Record<string, string>) => Record<string, string>,
@@ -698,37 +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,
-    info: (jobId) => request<BoardInfo>(boardPath(jobId, "board")),
-    watchFiles(jobId, handlers) {
-      let active = true;
-      let stop: () => void = () => {};
-      const close = (error: CenterError | null) => {
-        if (!active) return;
-        active = false; stop(); handlers.onClose(error);
-      };
-      const fetchStream: typeof fetch = async (input, init) => {
-        const response = await doFetch(input, init);
-        if (response.ok && !/^text\/event-stream(?:\s*;|$)/i.test(response.headers.get("content-type") ?? "")) {
-          await response.body?.cancel().catch(() => undefined);
-          throw new CenterError("文件事件接口未返回事件流，请检查服务代理配置", "INVALID_RESPONSE", 502);
-        }
-        return response;
-      };
-      stop = openSse(fetchStream, `${base}${boardPath(jobId, "files/events")}`, headers(), (event, data) => {
-        if (!active) return;
-        if (event === "files" || event === "message") {
-          if (!isWorkspaceFileBatch(data)) { close(new CenterError("文件事件数据不完整，正在重新同步", "INVALID_RESPONSE", 502)); return; }
-          handlers.onEvent(data);
-        } else if (event === "end") {
-          const end = data && typeof data === "object" ? data as Record<string, unknown> : {};
-          close(new CenterError(typeof end.detail === "string" ? end.detail : "文件监听连接中断，正在重连", typeof end.reason === "string" ? end.reason : "NETWORK", typeof end.status === "number" ? end.status : 0));
-        }
-      }, close);
-      return () => { active = false; stop(); };
+    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);
     },
-    stat: (jobId, path = ".") => request<DirListing | FileInfo>(boardPath(jobId, "files", `path=${encodeURIComponent(path)}`)),
+    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")),
+    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);
@@ -761,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/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/store.ts

@@ -19,6 +19,7 @@ import { formatAnswersText } from "../ui/format";
 import { backgroundBlock, charCount, MAX_MESSAGE_CHARS, serializeBlock } from "./blocks";
 import { cloneBoardView, reportBoardOwner, activateBoardOwner, selectedBoardOwner, mergeBoardHistory, rememberBoardFile } from "../board/context";
 import { cloneWorkspaceChange, subscribeWorkspaceFiles, retryWorkspaceFiles, type WorkspaceWatchOptions } from "../board/fileWatch";
+import { retainFileScope } from "../board/fileScope";
 import type { WorkspaceChangeEvent, WorkspaceWatchStatus } from "./types";
 import { createWorkspace, type BoardView, type CliWorkspace } from "../board/workspace";
 import type { AskAnswers, AskQuestion, CenterJob, CenterTurn, ConversationClosedCallback, ConversationTurnCallback, NewConversationOptions } from "./types";
@@ -52,6 +53,12 @@ export interface CliState {
   viewing: Record<string, { ref: BoardRef; off: boolean }>;
   /** 看板现在的样子（按对话键）：正在看的文件、开着的文件页签、当前页签。没有看板时没有。 */
   boards: Record<string, BoardView>;
+  /** 当前对话是否有展开且可见的外置看板；Chat 内嵌看板不计入。 */
+  externalBoards: Record<string, boolean>;
+  /** 同一工作区中是否有展开且可见的对话列表。 */
+  listVisible: boolean;
+  /** 外置看板的模块和只读限制，内嵌视图沿用同一约束。 */
+  externalBoardOptions: Record<string, { availableTabs: ("files" | "changes" | "browser")[]; readOnly: boolean }>;
   /** 最近看板背景，收起/卸载后保留，供下一条消息被动参考。 */
   boardContext: Record<string, BoardView>;
   /** 业务方补充的项目背景（按对话键；"" = 还没建的新对话），随下一条消息发出（见 appendContext）。 */
@@ -222,7 +229,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
   // 列表只放宿主给的 jobIds 和本页里新建 / 接续出来的对话：不从 center 发现，也不从本地存储恢复——
   // 不传就不加载，免得把这个产品线令牌下别的业务、别的用户的对话列出来。
 
-  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, boardContext: {}, context: {} };
+  let state: CliState = { selected: null, jobIds: [], jobs: {}, convs: {}, listLoading: false, listError: null, refs: {}, viewing: {}, boards: {}, externalBoards: {}, listVisible: false, externalBoardOptions: {}, boardContext: {}, context: {} };
   const listeners = new Set<() => void>();
   const eventListeners = new Set<(event: CliEvent) => void>();
   const settledTurns = new Set<string>();
@@ -392,10 +399,11 @@ export function createCliStore(options: CliStoreOptions = {}) {
     previous?.();
     if (streams.get(key) !== entry || entry.refs <= 0) return;
     const { jobId, taskId } = parseConvKey(key);
-    let ended = false, retired = false;
+    let ended = false, retired = false, snapshotReceived = false;
     let cleanup: (() => void) | null = null;
     const owns = () => streams.get(key) === entry && entry.refs > 0 && entry.stop === retire;
     const active = () => !retired && owns();
+    const refreshFiles = () => { if (active() && client.board) retryWorkspaceFiles(client.board, key); };
     const retire = () => {
       if (retired) return;
       retired = true;
@@ -435,13 +443,37 @@ export function createCliStore(options: CliStoreOptions = {}) {
     try {
       cleanup = client.stream(jobId, {
         onOpen: () => { if (!active()) return; entry.attempt = 0; patchConv(key, (conv) => ({ ...conv, stream: "live", streamError: null })); },
-        onSnapshot: (snapshot) => { if (active()) patchConv(key, (conv) => applySnapshot(conv, snapshot)); },
-        onChunk: (items) => { if (active()) patchConv(key, (conv) => applyItems(conv, items)); },
-        onEnd: (end) => {
+        onSnapshot: (snapshot) => {
+          if (!active()) return;
+          patchConv(key, (conv) => applySnapshot(conv, snapshot));
+          // Each connection catches up once, including rounds completed while disconnected.
+          if (!snapshotReceived) { snapshotReceived = true; refreshFiles(); }
+        },
+        onChunk: (items) => {
           if (!active()) return;
+          let refresh = false;
+          patchConv(key, (conv) => {
+            let next = conv;
+            for (const item of items) {
+              const previous = next;
+              next = applyItems(next, [item]);
+              // applyItems also rejects events from another batch task's node session.
+              if (next === previous) continue;
+              // Observe every event: end + next user in one chunk can leave running=true.
+              if (item.type === "node" && item.event.type === "turn_end" || item.type === "transcript") refresh = true;
+              if (item.type === "turn" && item.turn.status !== "merged" && TERMINAL_TURN.has(item.turn.status)
+                && !TERMINAL_TURN.has(previous.turns.find((turn) => turn.turn_id === item.turn.turn_id)?.status ?? "")) refresh = true;
+            }
+            return next;
+          });
+          if (refresh) refreshFiles();
+        },
+        onEnd: (end) => {
+          if (!active() || ended) return;
           ended = true;
           const continuedBy = taskId ? (end.continued_by_job_id && end.continued_by_task_id ? convKey(end.continued_by_job_id, end.continued_by_task_id) : null) : end.continued_by_job_id ?? null;
           patchConv(key, (conv) => ({ ...conv, stream: "ended", endReason: end.reason, continuedBy, nodeRunning: false }));
+          refreshFiles();
           void refreshJob(jobId, true);
         },
         onClose: close,
@@ -727,7 +759,28 @@ export function createCliStore(options: CliStoreOptions = {}) {
   }
 
   // 同一个仓库里登记的看板（cli-board）。后登记的优先（例如弹出的看板盖在常驻的上面）。
-  const surfaces: BoardSurface[] = [];
+  const surfaces: { surface: BoardSurface; owner?: string; inline?: boolean; priority?: () => number }[] = [];
+  const visibleLists = new Set<string>();
+  function reportListPresence(owner: string, visible: boolean) {
+    if (visible) visibleLists.add(owner); else visibleLists.delete(owner);
+    const listVisible = visibleLists.size > 0;
+    if (state.listVisible !== listVisible) set({ listVisible });
+  }
+  const externalBoards = new Map<string, Map<string, { visible: boolean; availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean }>>();
+  function reportBoardPresence(key: string, owner: string, visible: boolean | null, options: { availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean } = {}) {
+    const owners = externalBoards.get(key) ?? new Map<string, { visible: boolean; availableTabs?: readonly ("files" | "changes" | "browser")[]; readOnly?: boolean }>();
+    if (visible === null) owners.delete(owner); else owners.set(owner, { visible, ...options });
+    if (owners.size) externalBoards.set(key, owners); else externalBoards.delete(key);
+    const values = [...owners.values()];
+    const shown = values.some(value => value.visible);
+    const limits = owners.size ? { availableTabs: (["files", "changes", "browser"] as const).filter(tab => values.every(value => !value.availableTabs || value.availableTabs.includes(tab))), readOnly: values.some(value => value.readOnly) } : undefined;
+    if (!!state.externalBoards[key] === shown && JSON.stringify(state.externalBoardOptions[key]) === JSON.stringify(limits)) return;
+    const next = { ...state.externalBoards };
+    if (shown) next[key] = true; else delete next[key];
+    const configurations = { ...state.externalBoardOptions };
+    if (limits) configurations[key] = limits; else delete configurations[key];
+    set({ externalBoards: next, externalBoardOptions: configurations });
+  }
   // ── 看板 → 对话的引用 ─────────────────────────────
 
   function setRefs(key: string, refs: BoardRef[]) {
@@ -821,12 +874,13 @@ export function createCliStore(options: CliStoreOptions = {}) {
   const fileSubscriptions = new Map<string,{listeners:Set<{change?:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']}>;stop:()=>void;status?:WorkspaceWatchStatus}>();
   function watchWorkspace(key:string,listener?:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}) {
     if(!client.board) throw new Error("当前后端不支持工作区文件订阅");
+    const releaseScope=options.paths?.length||options.dirs?.length?retainFileScope(client.board,key,{paths:[...options.paths??[]],dirs:[...options.dirs??[]]}):()=>{};
     const item={change:listener,status:options.onStatus};let subscription=fileSubscriptions.get(key);
     if(!subscription){
       subscription={listeners:new Set([item]),stop:()=>{}};fileSubscriptions.set(key,subscription);const owned=subscription;
-      owned.stop=subscribeWorkspaceFiles(client.board,key,event=>{emit(event);for(const next of [...owned.listeners])notifyCallback(next.change,cloneWorkspaceChange(event));},{...options,onStatus:status=>{owned.status=status;emit(status);for(const next of [...owned.listeners])notifyCallback(next.status,{...status});}});
+      owned.stop=subscribeWorkspaceFiles(client.board,key,event=>{emit(event);for(const next of [...owned.listeners])notifyCallback(next.change,cloneWorkspaceChange(event));},{intervalMs:options.intervalMs,onStatus:status=>{owned.status=status;emit(status);for(const next of [...owned.listeners])notifyCallback(next.status,{...status});}});
     }else{subscription.listeners.add(item);if(subscription.status)notifyCallback(item.status,{...subscription.status});retryWorkspaceFiles(client.board,key);}
-    const owned=subscription;let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(item);if(!owned.listeners.size){if(fileSubscriptions.get(key)===owned)fileSubscriptions.delete(key);owned.stop();}};
+    const owned=subscription;let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(item);if(!owned.listeners.size){if(fileSubscriptions.get(key)===owned)fileSubscriptions.delete(key);owned.stop();}releaseScope();};
   }
 
   // ── 补充背景：业务方随时追加，随下一条消息发给智能体 ────────
@@ -890,9 +944,11 @@ export function createCliStore(options: CliStoreOptions = {}) {
     if (ref && cur && cur.ref.id === ref.id && cur.off) setViewingState(key, { ...cur, off: false });
   }
 
-  function openInBoard(jobId: string, target: OpenTarget): boolean {
+  function openInBoard(jobId: string, target: OpenTarget, preferredInlineOwner?: string): boolean {
     let handled = false;
-    for (const surface of [...surfaces].reverse()) {
+    const available = [...surfaces].reverse().filter(item => !preferredInlineOwner || !item.inline || item.owner === preferredInlineOwner)
+      .sort((a, b) => (b.priority?.() ?? 2) - (a.priority?.() ?? 2));
+    for (const { surface } of available) {
       try { handled = surface(jobId, { ...target }); }
       catch (error) { console.error("[@spzxg/cli-ui] board surface callback failed", error); }
       if (handled) break;
@@ -908,9 +964,10 @@ export function createCliStore(options: CliStoreOptions = {}) {
     /** 在看板里打开文件 / 浏览器 / 改动。返回有没有看板接住。 */
     openInBoard,
     /** 看板登记自己；返回注销函数。 */
-    registerBoard(surface: BoardSurface) {
-      surfaces.push(surface);
-      return () => { const i = surfaces.indexOf(surface); if (i >= 0) surfaces.splice(i, 1); };
+    registerBoard(surface: BoardSurface, options: { owner?: string; inline?: boolean; priority?: () => number } = {}) {
+      const entry = { surface, ...options };
+      surfaces.push(entry);
+      return () => { const i = surfaces.indexOf(entry); if (i >= 0) surfaces.splice(i, 1); };
     },
     subscribe(fn: () => void) { listeners.add(fn); return () => { listeners.delete(fn); }; },
     on(fn: (event: CliEvent) => void) { eventListeners.add(fn); return () => { eventListeners.delete(fn); }; },
@@ -923,7 +980,7 @@ export function createCliStore(options: CliStoreOptions = {}) {
     addRef, removeRef, takeRefs, restoreRefs,
     setViewing, dismissViewing, takeViewing, restoreViewing,
     /** 看板报告自己的样子（看板组件用）。 */
-    reportBoard, activateBoard,
+    reportBoard, activateBoard, reportBoardPresence, reportListPresence,
     /** 业务方追加项目背景：随下一条消息发给智能体。 */
     appendContext, removeContext, pendingContext,
     /** 工作区文件接口（不显示看板也能用）：列文件、读文件、下载、打包。不传 = 当前选中的对话。 */

package/src/core/types.ts

@@ -400,7 +400,7 @@ export interface FileEntry {
   changeToken?: string;
 }
 
-export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean; /** 目录里的条目总数（新版节点给）。 */ total?: number }
+export interface DirListing { type: "dir"; path: string; entries: FileEntry[]; truncated: boolean; /** 目录里的条目总数（新版节点给）。 */ total?: number; nextCursor?: string; revision?: string }
 export interface FileInfo { type: "file"; path: string; name: string; size: number; mtime: number; contentType: string; inline: boolean }
 
 export interface DiffFile {

package/src/index.ts

@@ -1,4 +1,5 @@
 export { CliMsgList, CliChat, CliBoard, type CliMsgListProps, type CliChatProps, type CliBoardProps } from "./components";
+export type { GroupChatAdapter, GroupChatMessage, GroupChatReference } from "./chat/GroupChat";
 /**
  * @spzxg/cli-ui —— 任务中心（cli-task-center）对话任务的前端积木，数据全部来自 center 服务。
  *
@@ -50,3 +51,5 @@ export { formatBoardContext, appendBoardContext, BOARD_HISTORY_MAX } from "./boa
 export { subscribeWorkspaceFiles, type WorkspaceWatchOptions } from "./board/fileWatch";
 export type { WorkspaceHandlers } from "./core/provider";
 export type { BoardFile } from "./board/workspace";
+
+export { syncFile, clearFileSyncNamespace, FILE_SYNC_MAX, type FileSyncTransport, type FileSyncManifest, type FileSyncProgress } from "./board/fileSync";

package/src/msglist/CliMsgList.tsx

@@ -1,7 +1,7 @@
 // cli-msglist：消息对话列表。界面取自 Operator 的任务栏（TasksColumn 的列表视图，不做看板），
 // 一张卡片是 center 里的一个对话任务（mode=conversation）。对话任务里开了几个对话时，卡片下面按对话展开，
 // 点哪个对话选哪个（选中值是对话键 "job#task"）；卡片上的「+」在这个对话任务里新开一个对话（同一个工作区）。
-import { useEffect, useMemo, useState, type CSSProperties } from "react";
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from "react";
 import { CliErrorBoundary } from "../ui/ErrorBoundary";
 import type { CliEvent, JobEntry } from "../core/store";
 import type { CliStoreOptions, CliStore } from "../core/store";
@@ -12,6 +12,7 @@ import { Icon } from "../ui/icons";
 import { agentLabel, relTime, toMs } from "../ui/format";
 import { AgentBadge, ErrNote, Skel, StatusDot, type DotCls } from "../ui/shared";
 import { resolveMsgListConfig, type CliMsgListConfig, type ResolvedMsgListConfig } from "../core/config";
+import { useBoardVisibility } from "../board/useBoardVisibility";
 
 /** onTurnEnd / onConversationEnd：浏览器里从实时流算出的结果通知，不依赖 center 的 callback.url。 */
 export interface CliMsgListProps extends CliStoreOptions, ResultHandlers {
@@ -284,6 +285,12 @@ function MsgListInner({ jobIds, selectedId, onSelect, onNew, title = "对话", c
   const cfg = useMemo(() => resolveMsgListConfig(config), [configKey]); // eslint-disable-line react-hooks/exhaustive-deps
   const h = cfg.header;
   const store = useCliStore();
+  const rootRef = useRef<HTMLDivElement>(null);
+  const owner = useId();
+  const visible = useBoardVisibility(rootRef, true);
+  const expanded = visible && !className?.split(/\s+/).includes("collapsed");
+  useLayoutEffect(() => { store.reportListPresence(owner, expanded); }, [store, owner, expanded]);
+  useLayoutEffect(() => () => { store.reportListPresence(owner, false); }, [store, owner]);
   const ids = useCliState((s) => s.jobIds);
   const jobs = useCliState((s) => s.jobs);
   const shared = useCliState((s) => s.selected);
@@ -343,7 +350,7 @@ function MsgListInner({ jobIds, selectedId, onSelect, onNew, title = "对话", c
   const showBanner = showRow || showContext;
 
   return (
-    <div className={`cli-ui cli-msglist ${className ?? ""}`} data-theme={theme} style={{ ...style, ...(width !== undefined ? { width } : null) }}>
+    <div ref={rootRef} className={`cli-ui cli-msglist ${className ?? ""}`} data-theme={theme} style={{ ...style, ...(width !== undefined ? { width } : null) }}>
       <div className="col col-tasks">
         {showBanner && <div className="proj-banner">
           {showRow && <div className="pb-row">