@xgspz/cli-ui 0.0.0-stage → 0.6.14

package/src/board/context.ts

@@ -0,0 +1,65 @@
+import type { BoardFile, BoardView } from './workspace';
+import { serializeBlock, splitMessage, VIEWING_NAME } from '../core/blocks';
+export const BOARD_HISTORY_MAX = 40;
+const identity=(file:BoardFile)=>JSON.stringify([file.sourceId??'',file.path]);
+export function rememberBoardFile(history:readonly BoardFile[],file:BoardFile):BoardFile[]{
+ return [...history.filter(item=>identity(item)!==identity(file)),{...file}].slice(-BOARD_HISTORY_MAX);
+}
+export function cloneBoardView(view:BoardView):BoardView {
+ return {...view,files:[...view.files],current:view.current?{...view.current}:view.current,opened:view.opened?.map(file=>({...file})),history:view.history?.map(file=>({...file})),browser:view.browser?{title:view.browser.title,url:browserUrl(view.browser.url)}:view.browser};
+}
+function browserUrl(raw:string):string {
+ try{const url=new URL(raw);return url.protocol==='http:'||url.protocol==='https:'?`${url.origin}${url.pathname}`:url.protocol==='about:'?`${url.protocol}${url.pathname}`:url.protocol;}catch{return '';}
+}
+function describe(file:BoardFile,currentSourceId?:string){
+ return file.sourceId&&file.sourceId!==currentSourceId?{path:file.path,sourceTask:file.sourceId,note:'来源任务的工作区，非当前执行分支'}:{path:file.path};
+}
+/** Metadata only; do not silently read/upload file bodies, URLs with auth tokens or arbitrary DOM. */
+export function formatBoardContext(view:BoardView,currentSourceId?:string):string {
+ if(view.autoContext===false)return '';
+ const current=view.current===undefined?(view.file?{path:view.file}:null):view.current;
+ const opened=view.opened??view.files.map(path=>({path}));
+ const history=view.history??[];
+ if(!current&&!opened.length&&!history.length&&!view.browser)return '';
+ const data={panelVisible:view.visible!==false,activeTab:view.tab,currentFile:current?describe(current,currentSourceId):null,
+  openFiles:opened.slice(-8).map(file=>describe(file,currentSourceId)),recentlyVisited:history.slice(-BOARD_HISTORY_MAX).map(file=>describe(file,currentSourceId)),
+  ...(view.browser?{browser:{url:browserUrl(view.browser.url),title:view.browser.title}}:{})};
+ const text=JSON.stringify(data,null,2);
+ // Bound context without truncating a path into a different, plausible filename.
+ if(text.length>16000){data.recentlyVisited=[];const compact=JSON.stringify(data,null,2);if(compact.length>16000)return '看板浏览背景较大，本次未自动附带；请用户明确引用需要的文件。';return `用户工作区浏览背景（仅元信息；较早浏览记录已省略）：\n${compact}`;}
+ return `用户工作区浏览背景（自动附带，仅元信息；最近访问不代表仍在查看；panelVisible=false 时 currentFile 是收起前选中的文件）：\n${text}`;
+}
+export function appendBoardContext(text:string,view:BoardView|null,currentSourceId?:string):string {
+ const context=view?formatBoardContext(view,currentSourceId):'';
+ return context?[text,serializeBlock({name:VIEWING_NAME,kind:'viewing',text:context})].filter(Boolean).join('\n\n'):text;
+}
+
+export function withoutBoardContext(text:string):string {
+ return splitMessage(text).filter(part=>part.kind!=='block'||part.block.kind!=='viewing').map(part=>part.kind==='text'?part.text:serializeBlock(part.block)).join('\n\n');
+}
+
+/** Local selection changes may select an owner; shared history and remote page
+ * metadata updates must not steal the user's active board. */
+const localBoardView=(view:BoardView)=>JSON.stringify({tab:view.tab,dir:view.dir,file:view.file,files:view.files,current:view.current,opened:view.opened,visible:view.visible!==false});
+export function selectedBoardOwner(sources:Map<string,BoardView>):[string,BoardView]|undefined {
+ const entries=[...sources.entries()];return entries.reverse().find(([,view])=>view.visible!==false)??entries[0];
+}
+export function reportBoardOwner(sources:Map<string,BoardView>,owner:string,view:BoardView):[string,BoardView]|undefined {
+ const previous=sources.get(owner),active=selectedBoardOwner(sources);
+ if(previous){if(localBoardView(previous)!==localBoardView(view)){sources.delete(owner);sources.set(owner,view);}else sources.set(owner,view);}
+ else if(active&&active[1].visible!==false){const existing=[...sources];sources.clear();sources.set(owner,view);for(const [id,value]of existing)sources.set(id,value);}
+ else sources.set(owner,view);
+ return selectedBoardOwner(sources);
+}
+export function activateBoardOwner(sources:Map<string,BoardView>,owner:string):[string,BoardView]|undefined {
+ const view=sources.get(owner);if(view){sources.delete(owner);sources.set(owner,view);}return selectedBoardOwner(sources);
+}
+export function mergeBoardHistory(existing:readonly BoardFile[],previous:BoardView|undefined,next:BoardView):BoardFile[] {
+ const old=previous?.history??[],incoming=next.history??[];let history=[...existing];
+ const known=new Set(old.map(identity));
+ // Newly mounted boards may restore old history; only adopt previously unknown
+ // records so a late restore cannot reorder the live workspace's recent visits.
+ const additions=incoming.filter(file=>!known.has(identity(file))&&(!previous?!history.some(item=>identity(item)===identity(file)):true));
+ if(previous&&incoming.length&&identity(incoming[incoming.length-1])!==identity(old[old.length-1]??{path:''}))additions.push(incoming[incoming.length-1]);
+ for(const file of additions)history=rememberBoardFile(history,file);return history;
+}

package/src/board/diffLines.ts

@@ -0,0 +1,46 @@
+// diff 正文的分行与着色：中枢看板的「改动」（ChangesPane）与节点的 TaskChanges 共用。
+//
+// 只按位置判断：文件头（`diff --git ` 到下一个 `@@` 之间的 index / --- / +++ / mode / rename…）不着色；
+// hunk 里由第一个字符决定：`+` 新增、`-` 删除、空格是上下文、`\` 是「No newline at end of file」。
+// 不能用「以 +++ / --- 开头就不是改动」来认文件头：被删掉的 `-- 注释` 显示为 `--- 注释`，
+// Markdown 的分隔线 `---` 被增删时是 `+---` / `----`，新增的 `++x` 显示为 `+++x`——它们都是真实改动。
+
+export type DiffLineKind = "hunk" | "add" | "del" | "";
+
+/** 去掉开头的文件头，从第一个 `@@` 起；没有 hunk（二进制、只改权限 / 重命名）时返回空。 */
+export function hunkLines(patch: string): string[] {
+  const lines = patch.split("\n");
+  const i = lines.findIndex((l) => l.startsWith("@@"));
+  return i >= 0 ? lines.slice(i) : [];
+}
+
+/**
+ * 每一行的种类。同一个文件的 patch 里可能再出现一段文件头（类型变化：一段删除 + 一段新增，
+ * 节点把两段拼在一起），那段文件头同样不着色。
+ */
+export function diffLineKinds(lines: string[]): DiffLineKind[] {
+  let header = false;
+  return lines.map((line) => {
+    if (line.startsWith("diff --git ")) {
+      header = true;
+      return "";
+    }
+    if (line.startsWith("@@")) {
+      header = false;
+      return "hunk";
+    }
+    if (header) return "";
+    return line[0] === "+" ? "add" : line[0] === "-" ? "del" : "";
+  });
+}
+
+/** 一个文件 patch 里新增、删除的行数（只给了整段 unified diff 的节点没有统计，自己数）。 */
+export function countChanges(patch: string): { additions: number; deletions: number } {
+  let additions = 0;
+  let deletions = 0;
+  for (const kind of diffLineKinds(hunkLines(patch))) {
+    if (kind === "add") additions++;
+    else if (kind === "del") deletions++;
+  }
+  return { additions, deletions };
+}

package/src/board/fileKind.ts

@@ -0,0 +1,250 @@
+// 看板按扩展名决定怎么预览一个文件。
+export type PreviewKind = "markdown" | "code" | "text" | "csv" | "image" | "pdf" | "html" | "docx" | "binary";
+
+const CODE_LANG: Record<string, string> = {
+  ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx", mjs: "javascript", cjs: "javascript",
+  json: "json", py: "python", rb: "ruby", go: "go", rs: "rust", java: "java", kt: "kotlin", swift: "swift",
+  c: "c", h: "c", cpp: "cpp", hpp: "cpp", cs: "csharp", php: "php", sh: "bash", bash: "bash", zsh: "bash",
+  sql: "sql", yaml: "yaml", yml: "yaml", toml: "ini", ini: "ini", xml: "xml", css: "css", scss: "scss",
+  vue: "xml", svelte: "xml", dockerfile: "dockerfile", makefile: "makefile", diff: "diff", patch: "diff",
+};
+const TEXT_EXT = new Set(["txt", "log", "env", "gitignore", "conf", "cfg", "properties", "lock", "tsv"]);
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "svg", "avif"]);
+
+export function extOf(path: string): string {
+  const name = path.split("/").pop() ?? "";
+  const lower = name.toLowerCase();
+  if (lower === "dockerfile" || lower === "makefile") return lower;
+  const dot = lower.lastIndexOf(".");
+  return dot > 0 ? lower.slice(dot + 1) : "";
+}
+
+export function previewKind(path: string, contentType = ""): PreviewKind {
+  const ext = extOf(path);
+  if (ext === "md" || ext === "markdown") return "markdown";
+  if (ext === "csv") return "csv";
+  if (IMAGE_EXT.has(ext)) return "image";
+  if (ext === "pdf") return "pdf";
+  if (ext === "html" || ext === "htm") return "html";
+  if (ext === "docx") return "docx";
+  if (CODE_LANG[ext]) return "code";
+  if (TEXT_EXT.has(ext)) return "text";
+  if (/^text\//.test(contentType) || /json|xml|javascript/.test(contentType)) return "text";
+  if (!ext) return "text"; // README、LICENSE 之类
+  return "binary";
+}
+
+export const codeLang = (path: string) => CODE_LANG[extOf(path)] ?? "";
+
+export function fmtSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(bytes < 10240 ? 1 : 0)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+/** 相对某个文件所在目录解析链接（Markdown 里的 ./img.png、../a.md）。 */
+export function resolveRelative(fromFile: string, href: string): string {
+  if (href.startsWith("/") || href.startsWith("~")) return href;
+  const base = fromFile.split("/").slice(0, -1);
+  for (const seg of href.split("/")) {
+    if (!seg || seg === ".") continue;
+    if (seg === "..") base.pop();
+    else base.push(seg);
+  }
+  return base.join("/");
+}
+
+/** 一行 CSV（支持引号里的逗号和 "" 转义）。 */
+export function parseCsv(text: string, maxRows = 500): { rows: string[][]; more: boolean } {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cell = "";
+  let quoted = false;
+  const sep = text.includes("\t") && !text.split("\n")[0].includes(",") ? "\t" : ",";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '"' && text[i + 1] === '"') { cell += '"'; i++; }
+      else if (ch === '"') quoted = false;
+      else cell += ch;
+    } else if (ch === '"' && cell === "") quoted = true;
+    else if (ch === sep) { row.push(cell); cell = ""; }
+    else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      row.push(cell); cell = "";
+      rows.push(row); row = [];
+      if (rows.length > maxRows) return { rows: rows.slice(0, maxRows), more: true };
+    } else cell += ch;
+  }
+  if (cell || row.length) { row.push(cell); rows.push(row); }
+  return { rows: rows.slice(0, maxRows), more: rows.length > maxRows };
+}
+
+/**
+ * 大 Markdown 分段（每段约 size 字）：在代码块外的空行处切，各段单独渲染（整篇几 MB 一次渲染会卡住页面几十秒）。
+ * 一直没有空行的超长内容到 4 倍大小也切（在代码块里切时补上收尾、下一段重新开头）。
+ */
+export function splitMarkdown(text: string, size: number): string[] {
+  if (text.length <= size) return [text];
+  const out: string[] = [];
+  const lines = text.split("\n");
+  let cur: string[] = [];
+  let len = 0;
+  let fence: string | null = null;
+  for (const line of lines) {
+    const m = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (m) {
+      if (!fence) fence = line.trim();
+      else if (line.trim().startsWith(fence.slice(0, 3)) && line.trim().replace(/[`~]/g, "") === "") fence = null;
+    }
+    cur.push(line);
+    len += line.length + 1;
+    const atBreak = !fence && line.trim() === "" && len >= size;
+    if (atBreak || len >= size * 4) {
+      if (fence) cur.push(fence.replace(/[^`~].*$/, ""));
+      out.push(cur.join("\n"));
+      cur = fence ? [fence] : [];
+      len = 0;
+    }
+  }
+  if (cur.length && cur.some((l) => l !== "")) out.push(cur.join("\n"));
+  return out;
+}
+
+export interface MarkdownPart {
+  /** Exact source slice; offsets use JavaScript string positions, not UTF-8 bytes. */
+  text: string;
+  plain: boolean;
+  start: number;
+  end: number;
+  /** Ordinary link definitions for the renderer, never inserted into source text. */
+  definitions?: string;
+  /** Preview-only formatting; source slices and offsets always remain exact. */
+  code?: { start: number; end: number; language: string };
+  prefix?: string;
+  simplified?: string;
+}
+
+/** Bound each render tree without inventing closing fences or splitting a giant structure into misleading Markdown. */
+export function splitMarkdownParts(text: string, size: number, options: { preview?: boolean } = {}): MarkdownPart[] {
+  if (!Number.isSafeInteger(size) || size < 2) throw new RangeError("Markdown分段大小必须至少为2");
+  const parts: MarkdownPart[] = [], definitions = new Map<string, string>();
+  let pendingStart = 0, pendingEnd = 0, pendingCost = 0, blockStart = 0, cursor = 0, fence: { char: string; length: number; body: number; language: string } | null = null;
+  let definitionSize = 0, tooManyDefinitions = false;
+  const push = (start: number, end: number, plain: boolean, extra: Partial<MarkdownPart> = {}) => { if (end > start) parts.push({ text: text.slice(start, end), plain, start, end, ...extra }); };
+  const flush = () => { push(pendingStart, pendingEnd, false); pendingStart = pendingEnd; pendingCost = 0; };
+  const boundedEnd = (start: number, end: number) => {
+    let next = Math.min(end, start + size);
+    const previous = text.charCodeAt(next - 1), following = text.charCodeAt(next);
+    if (next < end && previous >= 0xd800 && previous <= 0xdbff && following >= 0xdc00 && following <= 0xdfff) next--;
+    return next;
+  };
+  const block = (start: number, end: number, code?: MarkdownPart["code"]) => {
+    if (end <= start) return;
+    if (options.preview && code) {
+      flush();
+      while (start < end) {
+        let next = boundedEnd(start, end);
+        const newline = text.lastIndexOf("\n", next - 1);
+        if (next < end && newline >= start && newline + 1 > start + size / 2) next = newline + 1;
+        push(start, next, false, { code: { ...code, start: Math.min(next, Math.max(start, code.start)), end: Math.max(start, Math.min(next, code.end)) } }); start = next;
+      }
+      pendingStart = pendingEnd = end; return;
+    }
+    if (options.preview) {
+      const firstEnd = text.indexOf("\n", start), secondEnd = firstEnd < 0 ? -1 : text.indexOf("\n", firstEnd + 1);
+      const headerEnd = secondEnd < 0 ? end : secondEnd + 1;
+      const delimiter = firstEnd >= start && firstEnd < end ? text.slice(firstEnd + 1, Math.min(headerEnd, end)).trim() : "";
+      // GFM tables are bounded by rows as well as characters: short cells can
+      // otherwise produce thousands of elements from a small source slice.
+      if (firstEnd >= start && firstEnd < end && headerEnd <= end && headerEnd - start <= Math.min(size / 2, 4096)
+        && /^\|?\s*:?-{1,}:?\s*(?:\|\s*:?-{1,}:?\s*)+\|?$/.test(delimiter)) {
+        const columns = delimiter.replace(/^\|/, "").replace(/\|$/, "").split("|").length;
+        if (columns <= 32) {
+          flush(); const header = text.slice(start, headerEnd); let at = start;
+          while (at < end) {
+            const first = at === start, bodyStart = first ? headerEnd : at, budget = size - (first ? 0 : header.length);
+            let next = bodyStart, rows = 0;
+            while (next < end && (rows + 2) * columns <= 384) {
+              const newline = text.indexOf("\n", next), rowEnd = newline < 0 ? end : Math.min(end, newline + 1);
+              if (rowEnd - at > budget) break;
+              next = rowEnd; rows++;
+            }
+            if (next > at && (first || rows)) push(at, next, false, first ? {} : { prefix: header });
+            else {
+              const newline = text.indexOf("\n", at), rowEnd = newline < 0 ? end : Math.min(end, newline + 1);
+              while (at < rowEnd) { next = boundedEnd(at, rowEnd); push(at, next, true, { simplified: "此表格行较长，以原文显示；文件内容保持完整。" }); at = next; }
+            }
+            at = next;
+          }
+          pendingStart = pendingEnd = end; return;
+        }
+        flush();
+        while (start < end) { const next = boundedEnd(start, end); push(start, next, true, { simplified: "此表格列数较多，以原文分段显示；文件内容保持完整。" }); start = next; }
+        pendingStart = pendingEnd = end; return;
+      }
+    }
+    if (end - start <= size) {
+      const source = options.preview ? text.slice(start, end) : "";
+      const cost = options.preview ? (source.match(/[|*_\[\]<>`~]/g)?.length ?? 0) : 0;
+      if (options.preview && (cost > 2000 || /\[\^[^\]\r\n]+\]/.test(source))) {
+        flush(); push(start, end, true, { simplified: cost > 2000 ? "此段格式较复杂，以原文显示；文件内容保持完整。" : "跨段脚注以原文显示，避免遗漏注释内容。" }); pendingStart = pendingEnd = end; return;
+      }
+      if (pendingEnd - pendingStart + end - start > size || pendingCost + cost > 2000) flush();
+      if (pendingEnd === pendingStart) pendingStart = start;
+      pendingEnd = end; pendingCost += cost;
+      return;
+    }
+    flush();
+    while (start < end) {
+      const next = boundedEnd(start, end);
+      push(start, next, true, options.preview ? { simplified: "此段内容较长，以原文分段显示；文件内容保持完整。" } : {}); start = next;
+    }
+    pendingStart = pendingEnd = end;
+  };
+  while (cursor < text.length) {
+    const newline = text.indexOf("\n", cursor), lineEnd = newline < 0 ? text.length : newline, next = newline < 0 ? text.length : newline + 1;
+    // Never pass a 100MiB single line into regex/trim/Markdown parsing.
+    const bounded = lineEnd - cursor <= size;
+    const line = text.slice(cursor, bounded ? lineEnd : Math.min(lineEnd, cursor + 512));
+    const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (fence) {
+      const closing = /^ {0,3}(`{3,}|~{3,})[ \t\r]*$/.exec(line);
+      if (bounded && closing && closing[1][0] === fence.char && closing[1].length >= fence.length) {
+        block(blockStart, next, { start: fence.body, end: cursor, language: fence.language }); fence = null; blockStart = next;
+      }
+    } else if (opening && !(opening[1][0] === "`" && opening[2].includes("`"))) {
+      block(blockStart, cursor); blockStart = cursor; fence = { char: opening[1][0], length: opening[1].length, body: next, language: opening[2].trim().split(/\s/)[0].slice(0, 80) };
+    } else {
+      if (bounded) {
+        const reference = /^ {0,3}\[(?!\^)([^\]\r\n]+)\]:[ \t]*(?:<[^>\r\n]+>|[^\s\r\n]+)(?:[ \t]+(?:"[^"\r\n]*"|'[^'\r\n]*'|\([^\)\r\n]*\)))?[ \t\r]*$/.exec(line);
+        if (reference) {
+          const label = reference[1].trim().replace(/\s+/g, " ").toLowerCase();
+          if (!definitions.has(label)) {
+            definitionSize += line.length + 1;
+            if (definitionSize <= Math.min(size, 256 * 1024)) definitions.set(label, line); else tooManyDefinitions = true;
+          }
+        }
+        if (/^[ \t\r]*$/.test(line)) { block(blockStart, next); blockStart = next; }
+      }
+    }
+    cursor = next;
+  }
+  block(blockStart, text.length, fence ? { start: fence.body, end: text.length, language: fence.language } : undefined); flush();
+  if (!parts.length) parts.push({ text, plain: false, start: 0, end: text.length });
+  const context = [...definitions.values()].join("\n");
+  for (const part of parts) {
+    if (options.preview) {
+      if (part.plain || part.code) continue;
+      const used = new Set<string>(); let length = 0;
+      for (const match of part.text.matchAll(/\[([^\]\r\n]+)\](?:\[([^\]\r\n]*)\])?/g)) {
+        const label = (match[2] || match[1]).trim().replace(/\s+/g, " ").toLowerCase(), definition = definitions.get(label);
+        if (definition && !used.has(definition)) { used.add(definition); length += definition.length + 1; }
+      }
+      if (length > 4096 || (tooManyDefinitions && part.text.includes("["))) { part.plain = true; part.simplified = "引用定义较多，以原文显示，避免显示不完整的链接。"; }
+      else if (used.size) part.definitions = [...used].join("\n");
+    } else if (tooManyDefinitions) part.plain = true;
+    else if (!part.plain && context) part.definitions = context;
+  }
+  return parts;
+}

package/src/board/fileOps.ts

@@ -0,0 +1,85 @@
+// 工作区文件的基础操作（不依赖界面）：可直接打开的地址、下载到本地、读成 Blob。
+// 看板、文件预览和给业务方的工作区接口（workspace.ts）共用。
+import { fileUrlFromBase, type BoardBackend } from "../core/client";
+import { extOf, fmtSize } from "./fileKind";
+import { syncFile } from "./fileSync";
+import { isOriginalDocument, isTaskUploadPath } from "../core/documentUpload";
+
+/** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的不在浏览器里拼下载。 */
+const BLOB_DOWNLOAD_MAX = 300 * 1024 * 1024;
+
+export const MIME: Record<string, string> = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+  bmp: "image/bmp", ico: "image/x-icon", avif: "image/avif", pdf: "application/pdf", html: "text/html", htm: "text/html",
+  md: "text/markdown", markdown: "text/markdown", txt: "text/plain", csv: "text/csv", json: "application/json", zip: "application/zip",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+export const mimeOf = (path: string) => MIME[extOf(path)] ?? "application/octet-stream";
+
+/**
+ * 浏览器能直接打开的地址（不需要请求头）：同源代理时就是文件接口；没有代理注入令牌时用中枢发的短期链接。
+ * 中枢太旧发不了短期链接时返回 null（调用方改用读成 Blob）。
+ */
+export async function directFileUrl(backend: BoardBackend, jobId: string, path: string, download = false): Promise<string | null> {
+  if (backend.directLinks) return backend.fileUrl(jobId, path, { download });
+  const linkBase = backend.fileLinkBase ? await backend.fileLinkBase(jobId) : null;
+  return linkBase ? fileUrlFromBase(linkBase, path, download) : null;
+}
+
+export class FileReadLimitError extends Error {
+  constructor(maxBytes:number){super(`文件超过当前读取上限（${fmtSize(maxBytes)}），请使用直接下载链接`);this.name="FileReadLimitError";}
+}
+/** Bound bytes even with stale metadata; cancellation must settle callers when a custom backend ignores AbortSignal. */
+export async function readBoundedBuffer(backend:BoardBackend,jobId:string,path:string,maxBytes:number,options:{signal?:AbortSignal;onBytes?:(bytes:number)=>void}={}):Promise<ArrayBuffer> {
+  const ctl=new AbortController();let limit:FileReadLimitError|undefined;
+  const abort=()=>ctl.abort();options.signal?.addEventListener("abort",abort,{once:true});
+  if(options.signal?.aborted)ctl.abort();
+  let rejectAbort:(()=>void)|undefined;
+  try{
+    if(ctl.signal.aborted)throw new DOMException("已取消","AbortError");
+    const cancelled=new Promise<never>((_resolve,reject)=>{rejectAbort=()=>reject(limit??new DOMException("已取消","AbortError"));ctl.signal.addEventListener("abort",rejectAbort,{once:true});});
+    const result=await Promise.race([backend.readBuffer(jobId,path,{signal:ctl.signal,onBytes:bytes=>{
+      if(ctl.signal.aborted)return;
+      if(bytes>maxBytes){limit=new FileReadLimitError(maxBytes);ctl.abort();return;}
+      options.onBytes?.(bytes);
+    }}),cancelled]);
+    if(ctl.signal.aborted)throw limit??new DOMException("已取消","AbortError");
+    if(result.byteLength>maxBytes)throw new FileReadLimitError(maxBytes);
+    return result;
+  }finally{options.signal?.removeEventListener("abort",abort);if(rejectAbort)ctl.signal.removeEventListener("abort",rejectAbort);ctl.abort();}
+}
+
+/** 把 Blob 存到本地（浏览器下载）。 */
+export function saveBlob(blob: Blob, name: string) {
+  const url = URL.createObjectURL(blob);
+  clickDownload(url, name);
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+function clickDownload(href: string, name: string) {
+  const a = document.createElement("a");
+  a.href = href;
+  a.download = name;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+
+/**
+ * 下载：用浏览器能直接打开的地址（流式、可断点续传，不占内存）；同源代理以外的接入向中枢换短期链接。
+ * 只有中枢太旧时才 fetch 成 blob 再存（太大的拒绝，免得撑爆浏览器内存）。
+ */
+export async function downloadFile(backend: BoardBackend, jobId: string, path: string, size?: number) {
+  let name = path.split("/").pop() || "file";
+  if (backend.fileSync && (isOriginalDocument(path) || isTaskUploadPath(path))) {
+    const info = await backend.stat(jobId, path); if (info.type === "file" && info.name) name = info.name;
+    const result = await syncFile(backend.fileSync, jobId, path, { decode: false });
+    saveBlob(new Blob([result.bytes], { type: mimeOf(path) }), name); return;
+  }
+  const url = await directFileUrl(backend, jobId, path, true);
+  if (url) { clickDownload(url, name); return; }
+  if (size !== undefined && size > BLOB_DOWNLOAD_MAX) throw new Error(`文件较大（${fmtSize(size)}），当前接入方式不能在浏览器里下载，请升级任务中心`);
+  saveBlob(new Blob([await readBoundedBuffer(backend, jobId, path, BLOB_DOWNLOAD_MAX)]), name);
+}

package/src/board/fileScope.ts

@@ -0,0 +1,32 @@
+import type { BoardBackend } from "../core/client";
+
+type Scope = { paths: string[]; dirs: string[]; onDenied?: (message?: string) => void };
+const scopes = new WeakMap<BoardBackend, Map<string, Map<object, Scope>>>();
+const listeners = new WeakMap<BoardBackend, Map<string, Set<() => void>>>();
+/** A preview/list owns its subscription. Unmounted/closed directories are not polled. */
+export function retainFileScope(backend: BoardBackend, jobId: string, scope: Scope): () => void {
+  let jobs = scopes.get(backend); if (!jobs) { jobs = new Map(); scopes.set(backend, jobs); }
+  let owners = jobs.get(jobId); if (!owners) { owners = new Map(); jobs.set(jobId, owners); }
+  const owner = {}; owners.set(owner, scope);
+  const notify = () => listeners.get(backend)?.get(jobId)?.forEach(fn => fn());
+  notify();
+  let active = true;
+  return () => { if (!active) return; active = false; owners!.delete(owner); if (!owners!.size && jobs!.get(jobId) === owners) jobs!.delete(jobId); notify(); };
+}
+export function readFileScope(backend: BoardBackend, jobId: string): Scope {
+  const active = [...(scopes.get(backend)?.get(jobId)?.values() ?? [])];
+  return { paths: [...new Set(active.flatMap(scope => scope.paths))].sort(), dirs: [...new Set(active.flatMap(scope => scope.dirs))].sort() };
+}
+export function denyFileScope(backend: BoardBackend, jobId: string, message?: string, denied?: { paths: readonly string[]; dirs: readonly string[] }) {
+  for (const scope of scopes.get(backend)?.get(jobId)?.values() ?? []) {
+    // A list owns its directory; a rejected child file must not erase that list.
+    if (!denied || (scope.dirs.length ? scope.dirs.some(dir => denied.dirs.includes(dir || ".")) : scope.paths.some(path => denied.paths.includes(path)))) scope.onDenied?.(message);
+  }
+}
+export function onFileScope(backend: BoardBackend, jobId: string, listener: () => void) {
+  let jobs = listeners.get(backend); if (!jobs) { jobs = new Map(); listeners.set(backend, jobs); }
+  let set = jobs.get(jobId); if (!set) { set = new Set(); jobs.set(jobId, set); }
+  set.add(listener);
+  let active = true;
+  return () => { if (!active) return; active = false; set!.delete(listener); if (!set!.size && jobs!.get(jobId) === set) jobs!.delete(jobId); };
+}