@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/frameQuote.ts

@@ -0,0 +1,52 @@
+// HTML / Word 预览里「选中文字 → 引用到对话」。
+//
+// 这两种预览放在沙箱 iframe 里（不给同源，页面碰不到宿主），宿主反过来也读不到 iframe 里的选区。
+// 所以预览改成 srcdoc：在文档最前面插一段小脚本，选区变了用 postMessage 报给宿主（带口令，宿主只认自己这个 iframe）。
+//   · 页面自己的脚本照旧不让跑（和执行节点返回 HTML 时的 CSP 一致）：插入的 CSP 只放行带 nonce 的这一段；
+//   · 相对路径的样式 / 图片按文件原地址解析（<base>），文档里的 #锚点 在页内滚动（不然会按 <base> 整页跳走）。
+
+/** iframe → 宿主：选区（text 为空 = 取消了选择）或滚动了（收起按钮）。 */
+export interface FrameSelMessage { cliUiSel: string; text?: string; rect?: { left: number; top: number; width: number } | null; scroll?: boolean; top?: number; left?: number; ready?: boolean }
+
+const randomId = () => Math.random().toString(36).slice(2, 12) + Math.random().toString(36).slice(2, 12);
+
+/** 每个预览一个口令 / nonce。 */
+export const frameToken = randomId;
+
+function bridgeScript(token: string) {
+  const t = JSON.stringify(token);
+  return `(function(){var t=${t};function post(m){m.cliUiSel=t;try{parent.postMessage(m,"*")}catch(e){}}
+function ready(){requestAnimationFrame(function(){requestAnimationFrame(function(){post({ready:true})})})}if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',ready,{once:true});else ready();
+function send(){var s=getSelection(),text=s&&!s.isCollapsed?String(s).trim():"",rect=null;
+if(text&&s.rangeCount){var b=s.getRangeAt(0).getBoundingClientRect();rect={left:b.left,top:b.top,width:b.width}}post({text:text,rect:rect})}
+var timer;function later(){clearTimeout(timer);timer=setTimeout(send,0)}
+document.addEventListener("mouseup",later);document.addEventListener("keyup",later);
+document.addEventListener("selectionchange",later);
+addEventListener("scroll",function(){post({scroll:true,top:scrollY,left:scrollX})},true);
+addEventListener("message",function(e){if(e.source===parent&&e.data&&e.data.cliUiClear===t){var s=getSelection();s&&s.removeAllRanges()}});
+addEventListener("message",function(e){if(e.source===parent&&e.data&&e.data.cliUiRestore===t)scrollTo(Number(e.data.left)||0,Number(e.data.top)||0)});
+document.addEventListener("click",function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href^="#"]');if(!a)return;e.preventDefault();
+var id=decodeURIComponent(a.getAttribute("href").slice(1)),el=id?document.getElementById(id)||document.getElementsByName(id)[0]:document.body;el&&el.scrollIntoView()});})();`;
+}
+
+const escAttr = (s: string) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+/**
+ * 给 HTML 文档插上选区桥：CSP（页面脚本不跑、只能从文件所在地址取资源）、<base>、桥脚本。
+ * base = 文件的绝对地址（相对资源按它解析）；不给（Word 转出来的，图片都内嵌）时只允许 data: 资源。
+ */
+export function bridgeDoc(html: string, opts: { token: string; base?: string }) {
+  let origin = "";
+  if (opts.base) { try { origin = new URL(opts.base).origin; } catch { origin = ""; } }
+  const src = origin ? `${origin} ` : "";
+  const csp = `default-src 'none'; script-src 'nonce-${opts.token}'; img-src ${src}data: blob:; style-src ${src}'unsafe-inline'; font-src ${src}data:; media-src ${src}data: blob:`;
+  const head = `<meta http-equiv="Content-Security-Policy" content="${escAttr(csp)}">`
+    + (opts.base ? `<base href="${escAttr(opts.base)}">` : "")
+    + `<script nonce="${opts.token}">${bridgeScript(opts.token)}</script>`;
+  // 只保留首部完整、常见的 doctype；其他原件内容必须全部位于 CSP 和桥之后。
+  // 不搜索原件中的 <head>：它可能在注释 / 脚本字符串中，未闭合标签也会令全文正则反复回溯。
+  // 有界首部匹配同时避开带引号的异常 doctype 把策略吞进声明里的情况。
+  const doctype = /^(?:\uFEFF)?[ \t\r\n\f]*(<!doctype[ \t\r\n\f]+html(?:[ \t\r\n\f]+(?:public[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*')(?:[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*'))?|system[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*')))?[ \t\r\n\f]*>)/i.exec(html.slice(0, 4096));
+  // 解析器会自动建立 head，再读取原件的 html/head/body，保留文档内容及 html 属性。
+  return doctype ? doctype[1] + head + html.slice(doctype[0].length) : "<!doctype html>" + head + html;
+}

package/src/board/htmlReading.ts

@@ -0,0 +1,148 @@
+import { Parser } from "htmlparser2";
+
+export interface HtmlReadingBlock {
+  kind: "heading" | "paragraph" | "list-item" | "code" | "table-row" | "image";
+  text: string;
+  level?: number;
+}
+export interface HtmlReadingPage { blocks: HtmlReadingBlock[]; textLength: number }
+export interface HtmlReadingResult {
+  pages: HtmlReadingPage[];
+  pageCount: number;
+  pageOffset: number;
+  limited: boolean;
+  reason?: "depth" | "markup";
+  complete: boolean;
+}
+
+const BATCH = 8 * 1024, BLOCK_TEXT = 8 * 1024, PAGE_TEXT = 16 * 1024;
+const TOKEN_GAP = 64 * 1024, EMPTY_TAGS = 100_000;
+const ignored = new Set(["head", "script", "style", "iframe", "object", "embed", "svg", "math", "canvas", "template", "video", "audio"]);
+const boundaries = new Set(["p", "div", "section", "article", "main", "header", "footer", "nav", "aside", "blockquote", "figure", "figcaption", "address", "details", "summary", "dl", "dt", "dd", "ul", "ol", "li", "pre", "table", "tr", "hr", "h1", "h2", "h3", "h4", "h5", "h6"]);
+interface Frame { tag: string; skipped: boolean; kind?: HtmlReadingBlock["kind"]; level?: number; count?: number; marker?: string; alt?: string }
+
+/** Static reader only: outputs text, never markup, attributes, CSS or resource URLs.
+ * Reparse each verified prefix. Only call end() at actual EOF, so partial tags/entities
+ * remain pending instead of being mistaken for completed source content.
+ */
+export async function readHtmlSections(text: string, options: { signal?: AbortSignal; eof?: boolean; page?: number } = {}): Promise<HtmlReadingResult> {
+  const pages: HtmlReadingPage[] = [], stack: Frame[] = [];
+  const target = options.page === undefined ? undefined : Math.max(0, Number.isFinite(options.page) ? Math.floor(options.page) : 0);
+  let currentPage: HtmlReadingPage | undefined, selectedPage: HtmlReadingPage | undefined, pageCount = 0;
+  let active: HtmlReadingBlock | undefined, reason: HtmlReadingResult["reason"], emptyTags = 0;
+  const check = () => { if (options.signal?.aborted) throw new DOMException("已取消", "AbortError"); };
+  const emit = () => {
+    if (!active) return;
+    const block = active; active = undefined;
+    if (block.kind !== "code") block.text = block.text.trim();
+    if (!block.text.trim()) return;
+    if (!currentPage || currentPage.blocks.length >= 64 || currentPage.textLength + block.text.length > PAGE_TEXT) {
+      currentPage = { blocks: [], textLength: 0 }; pageCount++;
+      if (target === undefined) pages.push(currentPage);
+      else if (pageCount - 1 === target) selectedPage = currentPage;
+    }
+    // With a requested page, all other completed pages are released immediately.
+    // Keep the last page too, so a shortened revision can fall back without another scan.
+    currentPage.blocks.push(block); currentPage.textLength += block.text.length;
+  };
+  const context = (): Frame | undefined => {
+    // A paragraph inside a cell/code block must not break its enclosing row/code.
+    const fixed = stack.find(frame => frame.kind === "code" || frame.kind === "table-row");
+    const closest = [...stack].reverse();
+    return fixed ?? closest.find(frame => frame.kind && frame.kind !== "paragraph") ?? closest.find(frame => frame.kind);
+  };
+  const append = (data: string) => {
+    if (!data || stack[stack.length - 1]?.skipped || reason) return;
+    const frame = context(), kind = frame?.kind ?? "paragraph", level = frame?.level;
+    if (kind !== "code") data = data.replace(/[ \t\r\n\f]+/g, " ");
+    if (kind !== "code" && !data.trim() && !active) return;
+    if (data.trim()) emptyTags = 0;
+    if (active && (active.kind !== kind || active.level !== level)) emit();
+    if (frame?.marker && data.trim()) { data = frame.marker + data.trimStart(); frame.marker = undefined; }
+    let offset = 0;
+    while (offset < data.length) {
+      active ??= { kind, text: "", ...(level === undefined ? {} : { level }) };
+      if (kind !== "code" && data[offset] === " " && (!active.text || active.text.endsWith(" "))) offset++;
+      if (offset >= data.length) break;
+      let take = Math.min(BLOCK_TEXT - active.text.length, data.length - offset);
+      // Do not cut an emoji/supplementary character into two React text blocks.
+      const last = data.charCodeAt(offset + take - 1), next = data.charCodeAt(offset + take);
+      if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) take--;
+      if (!take) { emit(); continue; }
+      active.text += data.slice(offset, offset + take); offset += take;
+      if (active.text.length >= BLOCK_TEXT) emit();
+    }
+  };
+  const stop = (why: NonNullable<HtmlReadingResult["reason"]>) => { reason = why; parser.pause(); };
+  const parser = new Parser({
+    onopentagname(tag) {
+      if (reason) return;
+      if (stack.length >= 32) { stop("depth"); return; }
+      if (++emptyTags > EMPTY_TAGS) { stop("markup"); return; }
+      const skipped = !!stack[stack.length - 1]?.skipped || ignored.has(tag);
+      const fixed = context();
+      if (!skipped && (boundaries.has(tag) || tag === "img") && fixed?.kind !== "code" && fixed?.kind !== "table-row") emit();
+      const frame: Frame = { tag, skipped };
+      if (tag.length === 2 && tag[0] === "h" && tag[1] >= "1" && tag[1] <= "6") { frame.kind = "heading"; frame.level = Number(tag[1]); }
+      else if (tag === "pre") frame.kind = "code";
+      else if (tag === "tr") { frame.kind = "table-row"; frame.count = 0; }
+      else if (tag === "li") {
+        const list = [...stack].reverse().find(parent => parent.tag === "ol" || parent.tag === "ul");
+        frame.kind = "list-item";
+        frame.marker = list?.tag === "ol" ? `${list.count = (list.count ?? 0) + 1}. ` : "• ";
+      }
+      else if (boundaries.has(tag)) frame.kind = "paragraph";
+      if (!skipped && (tag === "td" || tag === "th")) {
+        const row = stack.find(parent => parent.tag === "tr");
+        if (row && (row.count = (row.count ?? 0) + 1) > 1) append(" | ");
+      }
+      stack.push(frame);
+      if (!skipped && tag === "br") append(fixed?.kind === "code" ? "\n" : " ");
+    },
+    // No onopentag callback: htmlparser2 does not build an attributes object.
+    // The one permitted attribute is copied as bounded, inert text.
+    onattribute(name, value) {
+      const frame = stack[stack.length - 1];
+      if (!reason && frame?.tag === "img" && !frame.skipped && name === "alt") frame.alt = value.slice(0, BLOCK_TEXT - 6);
+    },
+    ontext: append,
+    onclosetag(tag) {
+      if (reason) return;
+      const frame = stack[stack.length - 1];
+      if (!frame || frame.tag !== tag) return;
+      if (!frame.skipped) {
+        if (tag === "img") {
+          emit(); active = { kind: "image", text: frame.alt?.trim() ? `[图片：${frame.alt.trim()}]` : "[图片]" }; emit();
+        }
+        const fixed = context();
+        if (boundaries.has(tag) && (fixed?.kind !== "code" && fixed?.kind !== "table-row" || fixed === frame)) emit();
+      }
+      stack.pop();
+    },
+  }, { decodeEntities: true });
+  check();
+  let yieldedAt = performance.now();
+  try {
+    for (let offset = 0; offset < text.length && !reason;) {
+      check(); let end = Math.min(text.length, offset + BATCH);
+      const last = text.charCodeAt(end - 1), next = text.charCodeAt(end);
+      if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) end--;
+      parser.write(text.slice(offset, end));
+      offset = end;
+      // Bound parser retention for a single unfinished comment/tag/attribute.
+      if (!reason && end - Math.max(parser.startIndex, parser.endIndex) > TOKEN_GAP) stop("markup");
+      if (performance.now() - yieldedAt >= 8) {
+        await new Promise<void>(resolve => setTimeout(resolve, 0)); check(); yieldedAt = performance.now();
+      }
+    }
+    check();
+    if (options.eof && !reason) parser.end();
+    emit();
+    const selected = selectedPage ?? currentPage;
+    return {
+      pages: target === undefined ? pages : selected ? [selected] : [], pageCount,
+      pageOffset: target === undefined ? 0 : selectedPage ? target : Math.max(0, pageCount - 1),
+      limited: !!reason, ...(reason ? { reason } : {}), complete: !!options.eof && !reason,
+    };
+  } finally { parser.reset(); }
+}

package/src/board/panels.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+const useLayout = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+/** Initial visibility is separate from capability. Closing a panel never disables its backend. */
+export function useBoardPanels(scope: string | null, available: readonly string[], initial: readonly string[]) {
+  const allowed = [...new Set(available)];
+  const defaults = [...new Set(initial)].filter(id => allowed.includes(id));
+  const signature = JSON.stringify([allowed, defaults]);
+  const key = scope ? `cli-ui:panels:${scope}:${signature}` : null;
+  const [state, setState] = useState<{ key: string | null; open: string[] }>({ key, open: defaults });
+  const current = state.key === key ? state.open.filter(id => allowed.includes(id)) : defaults;
+  useLayout(() => {
+    let open = defaults;
+    try {
+      const saved = key ? JSON.parse(sessionStorage.getItem(key) ?? 'null') : null;
+      if (Array.isArray(saved)) open = [...new Set(saved.filter((id): id is string => typeof id === 'string' && allowed.includes(id)))];
+    } catch { /* Restricted storage does not disable panel controls. */ }
+    setState({ key, open });
+  }, [key, signature]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    if (key && state.key === key) try { sessionStorage.setItem(key, JSON.stringify(state.open)); } catch { /* In-memory only. */ }
+  }, [key, state]);
+  const set = useCallback((id: string, open: boolean) => {
+    if (!allowed.includes(id)) return false;
+    setState(previous => {
+      const list = previous.key === key ? previous.open : defaults;
+      return { key, open: open ? [...new Set([...list, id])] : list.filter(item => item !== id) };
+    });
+    return true;
+  }, [key, signature]); // eslint-disable-line react-hooks/exhaustive-deps
+  const show=useCallback((id:string)=>set(id,true),[set]);
+  const close=useCallback((id:string)=>set(id,false),[set]);
+  return { open: current, available: allowed, show, close };
+}

package/src/board/textLoad.ts

@@ -0,0 +1,76 @@
+// 预览里文本文件（代码、日志、Markdown、CSV）的读取。
+//
+// 能读多大：一次最多 max 字节（预览里是 32 MB），更大的只看开头或末尾。
+// 新协议以不可变修订和内容块进行同步；旧后端不能通过尾部重叠推断整份文件未变化。
+
+import type { BoardBackend } from "../core/client";
+import { decodeText } from "../core/textDecode";
+import { syncFile } from "./fileSync";
+
+/** 往前多取这么多字节，用来确认文件只是追加。 */
+export const OVERLAP = 256;
+/** 追加的段落多了合成一段（每段是 <pre> 里的一个文字节点）。 */
+
+
+export interface LoadedText {
+  text: string;
+  /** 分段的文字（追加的每次一段）：<pre> 里按段渲染，追加时前面的不用重排。 */
+  parts: string[];
+  /** 文件比读到的大（只读了开头或末尾）。 */
+  truncated: boolean;
+  /** 文件总大小。 */
+  size: number;
+  /** 读的是末尾。 */
+  tail: boolean;
+  encoding?: string;
+  revision?: string;
+  /** 读到的内容在文件里的字节范围 [start, end)。 */
+  start: number;
+  end: number;
+  /** end 之前的最后 OVERLAP 个字节（只有 UTF-8、后端有 readBytes 时有），用来确认文件只是追加。 */
+  tailBytes: Uint8Array | null;
+}
+
+/** 末尾有几个字节是没写完的 UTF-8 字（0 = 完整）。 */
+export function incompleteUtf8Tail(bytes: Uint8Array) {
+  const len = bytes.length;
+  for (let i = len - 1; i >= 0 && i >= len - 4; i--) {
+    const b = bytes[i];
+    if ((b & 0xc0) === 0x80) continue;
+    const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+    const have = len - i;
+    return have < need ? have : 0;
+  }
+  return 0;
+}
+
+
+
+/** 第一次读：开头（或末尾）最多 max 字节。 */
+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, 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, 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;
+  const tailBytes = encoding === "utf-8" ? chunk.bytes.slice(Math.max(0, chunk.bytes.length - k - OVERLAP), chunk.bytes.length - k) : null;
+  return {
+    text, parts: [text], truncated: chunk.start + chunk.bytes.length < chunk.size || chunk.start > 0, size: chunk.size,
+    tail: chunk.start > 0, encoding, start: chunk.start, end, tailBytes,
+  };
+}
+
+/** 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

@@ -0,0 +1,200 @@
+/**
+ * 给业务方的工作区接口：不显示看板也能拿到任务产出的文件。
+ *
+ *   const ws = store.workspace("job_xxx");        // 不传 = 当前选中的对话；Web Component：el.workspace()
+ *   await ws.listAll();                            // 工作区里所有文件（递归）
+ *   await ws.readText("reports/报告.md");          // 读成文字
+ *   await ws.readFile("reports/图.png");           // 读成 Blob（可以自己上传）
+ *   await ws.zip("reports");                       // 打成 ZIP 的 Blob
+ *   await ws.download("reports/报告.md");          // 下载到用户本地；ws.downloadFolder("reports") 打包下载
+ *   ws.openFile();                                 // 看板上正在看的文件（没有看板 / 没打开文件时为 null）
+ *
+ * 数据都经中枢读执行节点（和看板一样），弱网时按网络错误（CenterError，code = "NETWORK"）失败，可以重试。
+ */
+import { retryWorkspaceFiles, subscribeWorkspaceFiles, type WorkspaceWatchOptions, type WorkspaceRefreshOptions } from "./fileWatch";
+import type { BoardBackend } from "../core/client";
+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）。 */
+export const WORKSPACE_TEXT_MAX = 20 * 1024 * 1024;
+/** readFile 最多读这么大进内存（更大的用 fileUrl / download，浏览器流式下载）。 */
+export const WORKSPACE_FILE_MAX = 500 * 1024 * 1024;
+/** listAll 最多列这么多个文件。 */
+export const WORKSPACE_LIST_MAX = 10_000;
+
+export interface BoardFile { path: string; sourceId?: string }
+
+/** 看板现在的样子（看板组件报告给仓库；没有看板时没有）。 */
+export interface BoardView {
+  /** 当前页签：files / changes / browser、"file:<路径>"（打开的文件）或自己加的页签 id。 */
+  tab: string;
+  /** 文件列表所在目录（"" = 工作区根目录）。 */
+  dir: string;
+  /** 正在看的文件（当前页签是文件时），否则 null。 */
+  file: string | null;
+  /** 开着的文件页签。 */
+  files: string[];
+  /** 当前文件身份；切到目录/浏览器时为 null。sourceId 保留来源任务。 */
+  current?: BoardFile | null;
+  opened?: BoardFile[];
+  /** 最近真正访问过的文件（关闭页签后保留，最多40条）。 */
+  history?: BoardFile[];
+  browser?: { url: string; title: string } | null;
+  visible?: boolean;
+  autoContext?: boolean;
+}
+
+export interface CliWorkspace {
+  /** 这个工作区属于哪个对话（对话键）。 */
+  readonly jobId: string;
+  /** 看板概况：派发到节点没有、节点是否在线、有没有浏览器。 */
+  info(): Promise<BoardInfo>;
+  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, 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。 */
+  fileUrl(path: string, opts?: { download?: boolean }): Promise<string | null>;
+  /** 下载一个文件到用户本地。 */
+  download(path: string): Promise<void>;
+  /** 把目录打包成 ZIP 下载到用户本地（"" = 整个工作区）。 */
+  downloadFolder(dir?: string, opts?: FolderOptions): Promise<FolderResult>;
+  /** 把目录打成 ZIP，返回 Blob，不下载。 */
+  zip(dir?: string, opts?: FolderOptions): Promise<FolderZip>;
+  /** 看板上正在看的文件；没有看板或没打开文件时为 null。 */
+  openFile(): string | null;
+  /** 看板上开着的所有文件页签。 */
+  openFiles(): string[];
+  /** 在看板里打开这个文件（没有看板接时返回 false）。 */
+  open(path: string): boolean;
+}
+
+export function createWorkspace(deps: {
+  backend: BoardBackend | undefined;
+  key: string;
+  view: () => BoardView | undefined;
+  open: (path: string) => boolean;
+  context?: () => BoardView | null;
+  watch?: (listener:(event:WorkspaceChangeEvent)=>void,options?:WorkspaceWatchOptions)=>()=>void;
+}): CliWorkspace {
+  const { key } = deps;
+  const backend = () => {
+    if (!deps.backend) throw new Error("当前后端不支持读取工作区文件（需要任务中心的看板接口）");
+    return deps.backend;
+  };
+  const clean = (path: string) => path.replace(/^\.\//, "").replace(/\/+$/, "");
+  return {
+    jobId: key,
+    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 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, 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();
+      opts.signal?.addEventListener("abort", stop, { once: true });
+      if(opts.signal?.aborted)ctl.abort();
+      let tooBig = false;
+      let rejectAbort:(()=>void)|undefined;
+      try {
+        if(ctl.signal.aborted)throw new DOMException("已取消", "AbortError");
+        const aborted=new Promise<never>((_resolve,reject)=>{rejectAbort=()=>reject(new DOMException("已取消", "AbortError"));ctl.signal.addEventListener("abort",rejectAbort,{once:true});});
+        const buffer = await Promise.race([backend().readBuffer(key, p, {
+          signal: ctl.signal,
+          onBytes: (n) => { if(ctl.signal.aborted)return; if (n > max) { tooBig = true; ctl.abort(); } else opts.onProgress?.(n); },
+        }),aborted]);
+        if(buffer.byteLength>max){tooBig=true;throw new Error("文件超过读取上限");}
+        if(ctl.signal.aborted)throw new DOMException("已取消", "AbortError");
+        return new Blob([buffer], { type: mimeOf(p) });
+      } catch (error) {
+        if (tooBig) throw new Error(`文件超过 ${fmtSize(max)}，请用 fileUrl / download（浏览器流式下载，不占内存）`);
+        throw error;
+      } finally {
+        opts.signal?.removeEventListener("abort", stop);
+        if(rejectAbort)ctl.signal.removeEventListener("abort",rejectAbort);
+      }
+    },
+    async fileUrl(path, opts = {}) {
+      const url = await directFileUrl(backend(), key, clean(path), opts.download);
+      return url && typeof location !== "undefined" ? new URL(url, location.href).href : url;
+    },
+    download: (path) => downloadFile(backend(), key, clean(path)),
+    downloadFolder: (dir = "", opts) => downloadFolder(backend(), key, clean(dir), opts),
+    zip: (dir = "", opts) => zipFolder(backend(), key, clean(dir), opts),
+    openFile: () => deps.view()?.file ?? null,
+    openFiles: () => [...(deps.view()?.files ?? [])],
+    open: (path) => deps.open(clean(path)),
+  };
+}