@spzxg/cli-ui 0.6.5 → 0.6.7

package/src/board/textLoad.ts

@@ -1,17 +1,16 @@
 // 预览里文本文件（代码、日志、Markdown、CSV）的读取。
 //
 // 能读多大：一次最多 max 字节（预览里是 32 MB），更大的只看开头或末尾。
-// 文件在变（任务在写日志、在改报告）时不整个重读：后端有 readBytes 时，从上次读到的地方往前多取一小段（OVERLAP），
-// 这一小段和手里的末尾一模一样就说明文件只是往后追加了，只取新增的部分接上；对不上（文件被改写、变短了）才整个重读。
-// 只对 UTF-8 文件这样做（GBK 的字节边界不好对齐，整个重读）。
+// 新协议以不可变修订和内容块进行同步；旧后端不能通过尾部重叠推断整份文件未变化。
 
 import type { BoardBackend } from "../core/client";
 import { decodeText } from "../core/textDecode";
+import { syncFile } from "./fileSync";
 
 /** 往前多取这么多字节，用来确认文件只是追加。 */
 export const OVERLAP = 256;
 /** 追加的段落多了合成一段（每段是 <pre> 里的一个文字节点）。 */
-const MAX_PARTS = 200;
+
 
 export interface LoadedText {
   text: string;
@@ -24,6 +23,7 @@ export interface LoadedText {
   /** 读的是末尾。 */
   tail: boolean;
   encoding?: string;
+  revision?: string;
   /** 读到的内容在文件里的字节范围 [start, end)。 */
   start: number;
   end: number;
@@ -44,15 +44,21 @@ export function incompleteUtf8Tail(bytes: Uint8Array) {
   return 0;
 }
 
-const sameBytes = (a: Uint8Array, b: Uint8Array) => a.length === b.length && a.every((x, i) => x === b[i]);
+
 
 /** 第一次读：开头（或末尾）最多 max 字节。 */
-export async function loadText(backend: BoardBackend, jobId: string, path: string, opts: { max: number; tail?: boolean; onBytes?: (bytes: number) => void }): Promise<LoadedText> {
+export async function loadText(backend: BoardBackend, jobId: string, path: string, opts: { max: number; tail?: boolean; onBytes?: (bytes: number) => void; signal?: AbortSignal; preview?: boolean; fresh?: boolean }): Promise<LoadedText> {
+  if (opts.signal?.aborted) throw new DOMException("文件读取已取消", "AbortError");
+  if (backend.fileSync) {
+    const result = await syncFile(backend.fileSync, jobId, path, { signal: opts.signal, preview: opts.preview, fresh: opts.fresh, range: { maxBytes: opts.max, ...(opts.tail ? { tail: true } : {}) }, onProgress: progress => opts.onBytes?.(progress.loadedBytes) });
+    const text = result.text ?? decodeText(result.bytes, { fromMiddle: result.start > 0 }).text;
+    return { text, parts: [text], truncated: result.truncated, size: result.size, tail: result.start > 0, encoding: result.encoding, revision: result.revision, start: result.start, end: result.start + result.bytes.length, tailBytes: null };
+  }
   if (!backend.readBytes) {
-    const r = await backend.readText(jobId, path, opts.max, { tail: opts.tail, onBytes: opts.onBytes });
+    const r = await backend.readText(jobId, path, opts.max, { tail: opts.tail, onBytes: opts.onBytes, signal: opts.signal });
     return { text: r.text, parts: [r.text], truncated: r.truncated, size: r.size, tail: !!r.tail, encoding: r.encoding, start: 0, end: 0, tailBytes: null };
   }
-  const chunk = await backend.readBytes(jobId, path, { maxBytes: opts.max, tail: opts.tail, onBytes: opts.onBytes });
+  const chunk = await backend.readBytes(jobId, path, { maxBytes: opts.max, tail: opts.tail, onBytes: opts.onBytes, signal: opts.signal });
   const { text, encoding } = decodeText(chunk.bytes, { fromMiddle: chunk.start > 0 });
   const k = encoding === "utf-8" ? incompleteUtf8Tail(chunk.bytes) : 0;
   const end = chunk.start + chunk.bytes.length - k;
@@ -63,37 +69,8 @@ export async function loadText(backend: BoardBackend, jobId: string, path: strin
   };
 }
 
-/**
- * 文件变了：能接上就只取新增的部分，返回新的内容；返回 null = 接不上（被改写 / 变短 / 不是 UTF-8 / 后端不支持），调用方整个重读。
- * 只看开头且文件比 max 大时，开头没变就不用重读（追加的在后面，本来就不显示）。
- */
-export async function refreshText(backend: BoardBackend, jobId: string, path: string, prev: LoadedText, max: number): Promise<LoadedText | null> {
-  if (!backend.readBytes || !prev.tailBytes) return null;
-  const overlap = prev.tailBytes.length;
-  const from = prev.end - overlap;
-  const headOnly = !prev.tail && prev.truncated;
-  // 末尾模式攒多了（超过 1.5 倍）：整个重读末尾，免得越攒越大。
-  if (prev.tail && prev.end - prev.start > max * 1.5) return null;
-  const room = headOnly ? 0 : prev.tail ? max : Math.max(0, max - (prev.end - prev.start));
-  const chunk = await backend.readBytes(jobId, path, { start: from, maxBytes: overlap + room });
-  if (chunk.size < prev.end || chunk.start !== from || chunk.bytes.length < overlap) return null;
-  if (!sameBytes(chunk.bytes.subarray(0, overlap), prev.tailBytes)) return null;
-  const readEnd = from + chunk.bytes.length;
-  if (headOnly) return { ...prev, size: chunk.size };
-  const added = chunk.bytes.subarray(overlap);
-  const k = incompleteUtf8Tail(added);
-  const delta = added.subarray(0, added.length - k);
-  let addedText: string;
-  try { addedText = new TextDecoder("utf-8", { fatal: true }).decode(delta); } catch { return null; }
-  const end = prev.end + delta.length;
-  const tailBytes = new Uint8Array(Math.min(OVERLAP, overlap + delta.length));
-  const joined = new Uint8Array(overlap + delta.length);
-  joined.set(prev.tailBytes, 0);
-  joined.set(delta, overlap);
-  tailBytes.set(joined.subarray(joined.length - tailBytes.length));
-  const parts = addedText ? (prev.parts.length >= MAX_PARTS ? [prev.text, addedText] : [...prev.parts, addedText]) : prev.parts;
-  return {
-    ...prev, text: addedText ? prev.text + addedText : prev.text, parts, size: chunk.size, end, tailBytes,
-    truncated: prev.tail || chunk.size > readEnd,
-  };
+/** Every refresh verifies a revision. A matching tail cannot prove the rest stayed unchanged. */
+export async function refreshText(backend: BoardBackend, jobId: string, path: string, prev: LoadedText, max: number, options: { signal?: AbortSignal; preview?: boolean; fresh?: boolean } = {}): Promise<LoadedText | null> {
+  if (options.signal?.aborted) throw new DOMException("文件读取已取消", "AbortError");
+  return backend.fileSync ? loadText(backend, jobId, path, { max, tail: prev.tail, signal: options.signal, preview: options.preview, fresh: options.fresh }) : null;
 }

package/src/board/useBoardUpload.tsx

@@ -0,0 +1,51 @@
+import { useLayoutEffect, useRef, useState } from "react";
+import { clientId } from "../core/id";
+import type { DocumentReceipt, UploadDocument, UploadPhase } from "../core/documentUpload";
+import { FILE_UPLOAD_ACCEPT } from "../core/documentUpload";
+import { UploadProgress } from "../ui/UploadProgress";
+
+type PendingUpload = { file: File; phase: UploadPhase | "ready" | "error"; bytes: number; error?: string };
+
+/** Uploading a file only changes the current workspace. It never submits a message. */
+export function useBoardUpload(scope: string | null, upload: UploadDocument | undefined, onUploaded: (receipt: DocumentReceipt) => void) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const active = useRef<AbortController | null>(null);
+  const committedScope = useRef(scope);
+  const [pending, setPending] = useState<PendingUpload | null>(null);
+  useLayoutEffect(() => {
+    committedScope.current = scope;
+    setPending(null);
+    return () => { active.current?.abort(); active.current = null; };
+  }, [scope, upload]);
+
+  const start = (file: File) => {
+    if (!scope || !upload || active.current) return;
+    const controller = new AbortController();
+    active.current = controller;
+    const current = () => active.current === controller && committedScope.current === scope && !controller.signal.aborted;
+    setPending({ file, phase: "queued", bytes: 0 });
+    void Promise.resolve().then(() => upload(file, {
+      draftId: clientId(), signal: controller.signal,
+      onPhase: phase => { if (current()) setPending(previous => previous ? { ...previous, phase } : previous); },
+      onBytes: bytes => { if (current()) setPending(previous => previous ? { ...previous, bytes } : previous); },
+    })).then(receipt => {
+      if (!current()) return;
+      if (!receipt.path) throw new Error("文件尚未进入当前工作区，请稍后重试");
+      setPending({ file, phase: "ready", bytes: file.size });
+      onUploaded(receipt);
+    }).catch(error => {
+      if (current()) setPending(previous => previous ? { ...previous, phase: "error", error: error instanceof Error ? error.message : "上传失败，请重试" } : previous);
+    }).finally(() => { if (active.current === controller) active.current = null; });
+  };
+  const dismiss = () => { active.current?.abort(); active.current = null; setPending(null); };
+  const busy = !!pending && pending.phase !== "ready" && pending.phase !== "error";
+  return {
+    busy,
+    choose: () => { if (!busy) inputRef.current?.click(); },
+    input: <input ref={inputRef} type="file" hidden accept={FILE_UPLOAD_ACCEPT} aria-label="上传文件到工作区"
+      onChange={event => { const file = event.target.files?.[0]; event.target.value = ""; if (file) start(file); }} />,
+    progress: pending && <div className="cli-board-upload"><UploadProgress name={pending.file.name} status={pending.phase}
+      bytes={pending.bytes} total={pending.file.size} error={pending.error} onCancel={dismiss} onRemove={dismiss}
+      onRetry={() => start(pending.file)} /></div>,
+  };
+}

package/src/board/useBoardVisibility.ts

@@ -0,0 +1,35 @@
+import { useEffect, useLayoutEffect, useState, type RefObject } from "react";
+
+const useLayout = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/** Observe this board's ancestor chain, including host CSS that hides a pane. */
+export function useBoardVisibility(ref: RefObject<HTMLElement | null>, enabled: boolean) {
+  const [visible, setVisible] = useState(true);
+  useLayout(() => {
+    if (!enabled || !ref.current) return;
+    const ancestors: HTMLElement[] = [];
+    for (let node: HTMLElement | null = ref.current; node; node = node.parentElement) ancestors.push(node);
+    let pending = false, alive = true;
+    const read = () => {
+      pending = false;
+      if (!alive) return;
+      setVisible(ancestors.every(node => {
+        const style = getComputedStyle(node);
+        return !node.hidden && style.display !== "none" && style.visibility !== "hidden" && style.visibility !== "collapse" && style.contentVisibility !== "hidden";
+      }));
+    };
+    const schedule = () => {
+      if (pending) return;
+      pending = true;
+      queueMicrotask(read);
+    };
+    const mutations = new MutationObserver(schedule);
+    for (const node of ancestors) mutations.observe(node, { attributes: true, attributeFilter: ["class", "style", "hidden"] });
+    const resize = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+    resize?.observe(ref.current);
+    window.addEventListener("resize", schedule);
+    read();
+    return () => { alive = false; mutations.disconnect(); resize?.disconnect(); window.removeEventListener("resize", schedule); };
+  }, [ref, enabled]);
+  return visible;
+}

package/src/board/workspace.ts

@@ -11,11 +11,14 @@
  *
  * 数据都经中枢读执行节点（和看板一样），弱网时按网络错误（CenterError，code = "NETWORK"）失败，可以重试。
  */
-import { subscribeWorkspaceFiles, type WorkspaceWatchOptions } from "./fileWatch";
+import { retryWorkspaceFiles, subscribeWorkspaceFiles, type WorkspaceWatchOptions, type WorkspaceRefreshOptions } from "./fileWatch";
 import type { BoardBackend } from "../core/client";
-import type { BoardInfo, FileEntry, WorkspaceChangeEvent } from "../core/types";
+import type { BoardInfo, FileEntry, DirListing, WorkspaceChangeEvent } from "../core/types";
 import { directFileUrl, downloadFile, mimeOf } from "./fileOps";
 import { fmtSize } from "./fileKind";
+import { syncFile, FILE_SYNC_MAX } from "./fileSync";
+import { isOriginalDocument } from "../core/documentUpload";
+import { loadText } from "./textLoad";
 import { downloadFolder, listFolder, zipFolder, type FolderOptions, type FolderResult, type FolderZip } from "./folderDownload";
 
 /** readText 最多读这么大（更大的用 readFile）。 */
@@ -55,14 +58,18 @@ export interface CliWorkspace {
   stat(path: string): ReturnType<BoardBackend["stat"]>;
   /** 订阅文件变更。初始快照只建立基线；返回取消函数。 */
   watch(listener: (event: WorkspaceChangeEvent) => void, options?: WorkspaceWatchOptions): () => void;
+  /** 请求一次增量检查。轮末回调用无参；用户明确重试可传 manual:true（仍遵守服务端冷却）。不创建连接或周期轮询。 */
+  refresh(options?: WorkspaceRefreshOptions): void;
   /** 包括当前文件、打开页签、最近浏览和显示状态的背景快照。 */
   context(): BoardView | null;
-  /** 列一个目录（不递归）。 */
+  /** 按需读取单层目录的一页；nextCursor 非空时还有后续页。 */
+  listPage(dir?: string, opts?: { cursor?: string; limit?: number; signal?: AbortSignal }): Promise<DirListing>;
+  /** 显式列出一个目录（不递归，最多10000项）；界面首屏推荐 listPage。 */
   list(dir?: string): Promise<FileEntry[]>;
   /** 列 dir 下所有文件（递归，只含文件）。 */
   listAll(dir?: string, opts?: { signal?: AbortSignal }): Promise<FileEntry[]>;
   /** 读成文字（GBK 导出的文件会自动转码）。 */
-  readText(path: string): Promise<string>;
+  readText(path: string, opts?: { signal?: AbortSignal }): Promise<string>;
   /** 读成 Blob。onProgress 报已收到的字节数；超过 maxBytes（缺省 500 MB）报错，改用 fileUrl / download。 */
   readFile(path: string, opts?: { signal?: AbortSignal; onProgress?: (bytes: number) => void; maxBytes?: number }): Promise<Blob>;
   /** 浏览器能直接打开 / 下载的地址（没有同源代理时是 30 分钟有效的短期链接）；接入方式不支持时为 null，改用 readFile。 */
@@ -100,25 +107,60 @@ export function createWorkspace(deps: {
     info: () => backend().info(key),
     stat: path => backend().stat(key, clean(path) || "."),
     watch: (listener, options) => deps.watch ? deps.watch(listener,options) : subscribeWorkspaceFiles(backend(), key, listener, options),
+    refresh: options => options ? retryWorkspaceFiles(backend(), key, options) : retryWorkspaceFiles(backend(), key),
     context: () => deps.context?.() ?? deps.view() ?? null,
+    async listPage(dir = "", opts = {}) {
+      const api = backend();
+      const result = api.listFiles ? await api.listFiles(key, clean(dir) || ".", opts) : await api.stat(key, clean(dir) || ".");
+      if (result.type !== "dir") throw new Error(`「${dir}」不是目录`);
+      return result;
+    },
     async list(dir = "") {
-      const res = await backend().stat(key, clean(dir) || ".");
-      if (res.type !== "dir") throw new Error(`「${dir}」不是目录`);
-      return res.entries;
+      const api = backend(), entries: FileEntry[] = [], seen = new Set<string>();
+      let cursor: string | undefined;
+      do {
+        const result = api.listFiles ? await api.listFiles(key, clean(dir) || ".", { cursor, limit: 200 }) : await api.stat(key, clean(dir) || ".");
+        if (result.type !== "dir") throw new Error(`「${dir}」不是目录`);
+        entries.push(...result.entries);
+        if (entries.length > WORKSPACE_LIST_MAX) throw new Error("目录超过10000项，请用 listPage 按需读取");
+        cursor = result.nextCursor;
+        if ((result.truncated && (!cursor || !api.listFiles)) || (cursor && seen.has(cursor))) throw new Error("目录列表不完整，请使用支持分页的服务端");
+        if (cursor) seen.add(cursor);
+      } while (cursor);
+      return entries;
     },
     async listAll(dir = "", opts = {}) {
       const files = await listFolder(backend(), key, clean(dir), { signal: opts.signal, maxFiles: WORKSPACE_LIST_MAX, maxBytes: Infinity });
       return files.map((f) => ({ name: f.path.split("/").pop() || f.path, path: f.path, type: "file" as const, size: f.size, mtime: f.mtime }));
     },
-    async readText(path) {
-      const r = await backend().readText(key, clean(path), WORKSPACE_TEXT_MAX);
-      if (r.truncated) throw new Error(`文件较大（超过 ${WORKSPACE_TEXT_MAX / 1024 / 1024} MB），请用 readFile 读成 Blob`);
-      return r.text;
+    async readText(path, opts = {}) {
+      const signal = opts.signal;
+      if (signal?.aborted) throw new DOMException("已取消", "AbortError");
+      let rejectAbort: (() => void) | undefined;
+      try {
+        if (backend().fileSync && isOriginalDocument(path)) {
+          const result = await loadText(backend(), key, clean(path), { max: FILE_SYNC_MAX, signal });
+          return result.text;
+        }
+        const reading = signal ? backend().readText(key, clean(path), WORKSPACE_TEXT_MAX, { signal }) : backend().readText(key, clean(path), WORKSPACE_TEXT_MAX);
+        const r = signal ? await Promise.race([reading, new Promise<never>((_resolve, reject) => {
+          rejectAbort = () => reject(new DOMException("已取消", "AbortError"));
+          signal.addEventListener("abort", rejectAbort, { once: true });
+          if (signal.aborted) rejectAbort();
+        })]) : await reading;
+        if (r.truncated) throw new Error(`文件较大（超过 ${WORKSPACE_TEXT_MAX / 1024 / 1024} MB），请用 readFile 读成 Blob`);
+        return r.text;
+      } finally { if (rejectAbort) signal?.removeEventListener("abort", rejectAbort); }
     },
     async readFile(path, opts = {}) {
       const p = clean(path);
       const max = opts.maxBytes ?? WORKSPACE_FILE_MAX;
       if(!Number.isFinite(max)||max<0)throw new RangeError("maxBytes 必须是非负有限字节数");
+      if (backend().fileSync && isOriginalDocument(p)) {
+        const result = await syncFile(backend().fileSync!, key, p, { signal: opts.signal, decode: false, range: { maxBytes: Math.min(max, FILE_SYNC_MAX) }, onProgress: progress => opts.onProgress?.(progress.loadedBytes) });
+        if (result.truncated) throw new Error(`文件超过 ${fmtSize(max)}，请用 fileUrl / download`);
+        return new Blob([result.bytes], { type: mimeOf(p) });
+      }
       // 太大的读到一半就停：整个读进内存会把页面撑爆。
       const ctl = new AbortController();
       const stop = () => ctl.abort();