@weniatall/dsh-file-viewer 0.2.8 → 0.2.10

package/README.md

@@ -46,6 +46,8 @@ dsh plugin --profile web add <release-tgz-url>
   - **会话中点击文件**：在会话回复（变更文件卡片、产物交付卡片、行内代码引用等）中点击任何文件路径，自动唤起文件查看抽屉并直接选中预览该文件。
 - `Esc` 或点击抽屉外部遮罩关闭。
 
+**桌面端接管说明**：桌面版宿主判定自己能在系统里打开路径，因此会在文件路径与更改卡片旁额外渲染原生「在应用中打开」按钮，更改卡片还会走 `/api/changes.open` 这条直接交给操作系统的路由。插件在这两处都会先接管，改为唤起文件查看抽屉：原生打开按钮按 `data-open-path-open` 识别，更改卡片打开路由则从 URL 里的 `sessionId / seq / index` 回查文件路径。取不到路径时一律放行，仍按宿主原方式打开，不会出现点了没反应。
+
 顶部可切换工作区、刷新、显示或隐藏点文件。目录在树中原地展开，子级首次展开时才加载。
 
 文件树支持**右键上下文菜单**与单项 `@` 快捷按钮：
@@ -80,7 +82,10 @@ dsh plugin --profile web add <release-tgz-url>
       #   label: 共享数据盘
       # Windows 示例：
       # - D:/Notes
+    # 在线预览（图片/PDF/表格/文档）单文件上限，默认 20 MB
     maxBytes: 20971520
+    # 下载到本地单文件上限，默认 100 MB
+    maxDownloadBytes: 104857600
 ```
 
 配置后：
@@ -90,7 +95,24 @@ dsh plugin --profile web add <release-tgz-url>
 - 为保持向后兼容，原有的 `extraRoots` 与 `safeAccessPaths` 别名依然有效并会自动合并；
 - **Web 界面动态配置与双重持久化**：可在输入框工具栏文件查看器入口或文件树顶部的「安全访问路径设置」弹窗中直接添加、查看或删除安全路径，保存后会自动双重持久化写入当前 Profile 配置（`cordis.patch.yml`）与本地文件（`~/.dsh/file-viewer/settings.json`），DSH 服务重启后配置稳定保留不丢失。
 
-插件不注册任何 HTTP 路由，全部通过 `trusted-host` 权限的 RPC 通道通信，从而复用 DSH `/api` 的浏览器信任围栏（Host/Origin 校验、DNS rebinding 防护）。二进制文件经 RPC 取回后在浏览器侧生成 blob URL，默认单文件上限 20 MB。
+### 下载与预览使用两套上限
+
+下载上限（`maxDownloadBytes`，默认 100 MB）与在线预览上限（`maxBytes`，默认 20 MB）是**独立**的两个值，因为两条通道的代价不同：
+
+- **预览**把整个文件以 base64 塞进 JSON 响应，浏览器还要再 `atob` 解码一次；20 MB 的文件已经会产生约 27 MB 的传输文本，因此这条通道刻意保持小预算；
+- **下载**由浏览器直接消费，或由桌面端流式读取后交给保存流程，不需要解码进页面，因此可以给到 100 MB。
+
+两个上限都支持通过配置调整；把 `maxDownloadBytes` 调大时，宿主仍需一次性读出该文件，请按可用内存权衡。
+
+### 下载在不同宿主中的行为
+
+插件在 `/api` 之下注册了一个带鉴权的流式下载端点，并让客户端按宿主能力选择传输方式：
+
+- **浏览器**：先发一次 `HEAD` 预检（超限直接提示「文件超过下载限制（上限 100MB）」，不会产生一条失败的下载记录），随后把鉴权后的 URL 交给浏览器原生下载管理器。进度、暂停、续传与保存位置都由浏览器负责，页面内存不随文件大小增长；
+- **桌面端（Electron）**：桌面外壳没有浏览器的下载面板，因此改用 `fetch` 流式读取，并在抽屉内实时显示百分比进度（如 `正在下载 dataset.zip (45% - 45.2 MB / 100.0 MB)...`），完成后交给保存流程；
+- **兜底**：流式端点不可用（旧宿主或路由被占用）时，自动回退到既有的 RPC `bytes` 通道，功能不缺失。
+
+下载端点的错误响应只回传机器可读的原因码（如 `FS_TOO_LARGE`、`too-large`），不会回显宿主的绝对路径；这与 RPC 通道既有的「绝不泄露路径」约定一致。
 
 ## 未知后缀文件的文本识别
 

package/lib/client.js

@@ -299,7 +299,7 @@ window.__ModuleLoader__.load({
     const inject = ["slots", "connection", "workspaces"];
 
     const css = `
-      .fv-scrim{position:absolute;inset:0;z-index:40;display:flex;align-items:stretch;justify-content:flex-end;background:transparent;pointer-events:auto;color-scheme:light dark;animation:fv-fade .16s ease-out}
+      .fv-scrim{position:absolute;inset:0;z-index:40;display:flex;align-items:stretch;justify-content:flex-end;background:transparent;pointer-events:auto;animation:fv-fade .16s ease-out}
       .fv-shell{display:flex;flex-direction:column;width:min(64vw,1100px);min-width:0;min-height:0;overflow:hidden;border-left:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2,var(--dsw-alias-bg-base,#fff));box-shadow:var(--dsw-shadow-lv3);font-family:var(--dsw-font-family);color:var(--dsw-alias-label-primary);animation:fv-slide .2s cubic-bezier(.2,.8,.2,1);transition:width .2s cubic-bezier(.2,.8,.2,1)}
       .fv-shell[data-fullscreen="true"]{width:100vw;border-left:none}
       /* Windows desktop paints the native caption buttons (minimize, maximize,
@@ -424,7 +424,7 @@ window.__ModuleLoader__.load({
       .fv-badge{display:inline-block;padding:0 4px;font-size:10px;font-weight:600;line-height:14px;border-radius:4px;margin-left:4px;flex:none}
       .fv-badge-mod{background:color-mix(in srgb,var(--dsw-alias-state-warning-primary,#d97706) 18%,transparent);color:var(--dsw-alias-state-warning-primary,#d97706)}
       .fv-badge-add{background:color-mix(in srgb,var(--dsw-alias-state-success-primary,#10b981) 18%,transparent);color:var(--dsw-alias-state-success-primary,#10b981)}
-      .fv-modal-scrim{position:fixed;inset:0;z-index:70;display:grid;place-items:center;padding:16px;background:color-mix(in srgb,#000 45%,transparent);animation:fv-fade .15s ease-out;color-scheme:light dark}
+      .fv-modal-scrim{position:fixed;inset:0;z-index:70;display:grid;place-items:center;padding:16px;background:color-mix(in srgb,#000 45%,transparent);animation:fv-fade .15s ease-out}
       .fv-modal{width:min(94vw,560px);max-height:86vh;display:flex;flex-direction:column;border:1px solid var(--dsw-alias-border-l2);border-radius:14px;background:var(--dsw-alias-bg-layer-2,var(--dsw-alias-bg-base,#fff));box-shadow:var(--dsw-shadow-lv3);color:var(--dsw-alias-label-primary);overflow:hidden;font-family:var(--dsw-font-family)}
       .fv-modal-head{display:flex;align-items:center;justify-content:space-between;padding:14px 18px;border-bottom:1px solid var(--dsw-alias-border-l1)}
       .fv-modal-title{font:var(--dsw-font-m-16);font-weight:600;display:flex;align-items:center;gap:6px}
@@ -870,10 +870,27 @@ window.__ModuleLoader__.load({
     // Guard so a hot reload or re-apply never double-wraps shared open
     // handlers; older hosts used workspaces.openPath.
     const wiredOpenPath = typeof WeakSet !== "undefined" ? new WeakSet() : null;
+    // The wrappers below outlive a single apply. They were closing over the
+    // store of whichever apply installed them, so a second apply left the Host
+    // calling the previous store: the click was swallowed, the drawer never
+    // opened, and the file viewer looked like it had stopped listening. These
+    // pointers are refreshed on every apply so the wrappers always write the
+    // store the mounted overlay is actually subscribed to.
+    let liveOpenStore = null;
+    let liveSessionStore = null;
 
-    function openViewerForPath(openStore, sessionStore, path) {
-      const sid = sessionStore.get();
-      openStore.set({ filePath: path, sessionId: sid, _t: Date.now() });
+    /**
+     * Open the drawer on one path.
+     *
+     * `sessionId` is optional: a `dsh-resource://file/session/<id>/…` address
+     * names the session it belongs to, and honouring it keeps the drawer on that
+     * session's project instead of whatever session happens to be current.
+     */
+    function openViewerForPath(openStore, sessionStore, path, sessionId) {
+      const target = liveOpenStore || openStore;
+      const session = liveSessionStore || sessionStore;
+      const sid = sessionId !== undefined && sessionId !== "" ? sessionId : (session ? session.get() : undefined);
+      target.set({ filePath: path, sessionId: sid, _t: Date.now() });
     }
 
     function parseFileResource(address) {
@@ -918,8 +935,7 @@ window.__ModuleLoader__.load({
       sr.openResource = function(address, options) {
         const parsed = parseFileResource(address);
         if (parsed && parsed.path) {
-          const sid = parsed.sessionId || sessionStore.get();
-          openStore.set({ filePath: parsed.path, sessionId: sid, _t: Date.now() });
+          openViewerForPath(openStore, sessionStore, parsed.path, parsed.sessionId);
           return;
         }
         const review = parseChangesReviewResource(address);
@@ -933,7 +949,7 @@ window.__ModuleLoader__.load({
             .then((data) => {
               const file = data?.files?.[idx]?.path || data?.files?.[0]?.path;
               if (file) {
-                openStore.set({ filePath: file, sessionId: sid, _t: Date.now() });
+                openViewerForPath(openStore, sessionStore, file);
               }
             })
             .catch(() => {});
@@ -946,8 +962,7 @@ window.__ModuleLoader__.load({
         sr.openResourceIn = function(sessionId, address, options) {
           const parsed = parseFileResource(address);
           if (parsed && parsed.path) {
-            const sid = sessionId || parsed.sessionId || sessionStore.get();
-            openStore.set({ filePath: parsed.path, sessionId: sid, _t: Date.now() });
+            openViewerForPath(openStore, sessionStore, parsed.path, sessionId || parsed.sessionId);
             return;
           }
           const review = parseChangesReviewResource(address);
@@ -960,7 +975,7 @@ window.__ModuleLoader__.load({
               .then((data) => {
                 const file = data?.files?.[idx]?.path || data?.files?.[0]?.path;
                 if (file) {
-                  openStore.set({ filePath: file, sessionId: sid, _t: Date.now() });
+                  openViewerForPath(openStore, sessionStore, file, sid);
                 }
               })
               .catch(() => {});
@@ -1000,6 +1015,63 @@ window.__ModuleLoader__.load({
       };
     }
 
+    /**
+     * Take over the Desktop Host's changed-file open route.
+     *
+     * The changes card's native open control does not go through the RPC
+     * carrier: it POSTs `/api/changes.open?sessionId=…&seq=…&index=…`, which
+     * hands the file to the operating system. Nothing in the RPC path can see
+     * that call, so on Desktop the changes card opened the system editor while
+     * the Web build (where the control is not mounted at all) opened the
+     * viewer. Resolving the same coordinates through the summary route gives the
+     * path, and a synthetic OK response keeps the Host's card state settled.
+     */
+    function wrapChangesOpenFetch(openStore, sessionStore) {
+      if (typeof window === "undefined" || typeof window.fetch !== "function") return;
+      const originalFetch = window.fetch;
+      if (wiredOpenPath === null || wiredOpenPath.has(originalFetch)) return;
+      wiredOpenPath.add(originalFetch);
+
+      const summaryPath = (sessionId, seq) =>
+        `/api/changes.summary?${new URLSearchParams({ sessionId, seq: String(seq) })}`;
+
+      window.fetch = function(input, init) {
+        const requestUrl = typeof input === "string" ? input : (input && typeof input.url === "string" ? input.url : "");
+        const method = String((init && init.method) || (input && input.method) || "GET").toUpperCase();
+        if (method !== "POST" || !/\/api\/changes\.open\b/.test(requestUrl)) {
+          return originalFetch.apply(this, arguments);
+        }
+        let coordinates;
+        try {
+          const query = new URLSearchParams(requestUrl.split("?")[1] || "");
+          coordinates = {
+            sessionId: query.get("sessionId") || "",
+            seq: Number(query.get("seq")),
+            index: Number(query.get("index") || 0),
+          };
+        } catch (_) {
+          coordinates = null;
+        }
+        if (!coordinates || !coordinates.sessionId || !Number.isFinite(coordinates.seq)) {
+          return originalFetch.apply(this, arguments);
+        }
+        const { sessionId, seq, index } = coordinates;
+        return originalFetch(summaryPath(sessionId, seq), { signal: init && init.signal })
+          .then((response) => (response && response.ok ? response.json() : null))
+          .then((data) => {
+            const files = Array.isArray(data && data.files) ? data.files : [];
+            const entry = files[Number.isFinite(index) ? index : 0] || files[0];
+            const file = entry && entry.path;
+            if (!file) return originalFetch.apply(this, arguments);
+            openViewerForPath(openStore, sessionStore, file, sessionId);
+            // The Host only reads `response.ok`; a bodiless 204 settles its card
+            // without claiming the OS actually opened anything.
+            return new Response(null, { status: 204 });
+          })
+          .catch(() => originalFetch.apply(this, arguments));
+      };
+    }
+
     const COMMON_FILE_EXTENSIONS = new Set([
       "go", "ts", "js", "tsx", "jsx", "mjs", "cjs", "py", "java", "c", "cpp", "h", "hpp", "rs", "php", "rb", "swift", "kt", "scala",
       "md", "markdown", "txt", "json", "jsonc", "yaml", "yml", "toml", "xml", "html", "css", "scss", "less", "vue", "svelte",
@@ -1113,6 +1185,25 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 3. The Host's native open control carries no path of its own: its label
+      //    is the action ("Open", "Open in …"), never the file. The path is
+      //    published by the surrounding row in a hidden description span, so
+      //    walk up a few levels and take the first span that holds a path. The
+      //    walk is bounded and every candidate still has to pass the path
+      //    shape check, so a miss falls through to the Host rather than opening
+      //    the wrong file.
+      if (element.closest && element.closest("[data-open-path-open]")) {
+        let scope = element.parentElement;
+        for (let depth = 0; scope && depth < 4; depth += 1) {
+          const hiddenPath = scope.querySelector ? scope.querySelector("span[hidden]") : null;
+          if (hiddenPath && hiddenPath.textContent) {
+            const p = normalizeClickedPath(hiddenPath.textContent);
+            if (p) return p;
+          }
+          scope = scope.parentElement;
+        }
+      }
+
       const sources = [
         element.getAttribute("data-file-path"),
         element.getAttribute("data-path"),
@@ -1130,6 +1221,13 @@ window.__ModuleLoader__.load({
     function isFileOpenControl(element) {
       if (!element) return false;
       if (element.hasAttribute("data-file-path") || element.hasAttribute("data-path")) return true;
+      // The Desktop Host answers `canOpenWorkspacePath` with true, so the shell
+      // mounts its native "open in application" button beside every file path
+      // (the changes card included). That button sits above the path control and
+      // takes the click, so it has to count as a file control or the viewer
+      // never sees the gesture. The `-more` chevron is a menu of applications,
+      // not a plain open, so it is deliberately left to the Host.
+      if (element.closest("[data-open-path-open]")) return true;
       if (element.closest("[data-produced-files-row]")) return true;
       // Support deliverables: changed files card (ChangedFiles) and presented file cards (PresentedFileCard)
       if (element.closest("[data-changed-files], [data-presented-file], [data-presented-files-row]")) return true;
@@ -1360,22 +1458,28 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Trigger browser file download from a Blob using an ephemeral anchor tag.
+     * Trigger browser file download from a Blob or URL using an ephemeral anchor tag.
      */
-    function triggerDownload(blob, filename) {
-      if (typeof window === "undefined" || typeof document === "undefined") return false;
+    function triggerDownload(target, filename) {
+      const currentWin = typeof globalThis !== "undefined" && globalThis.window ? globalThis.window : (typeof window !== "undefined" ? window : null);
+      const currentDoc = typeof globalThis !== "undefined" && globalThis.document ? globalThis.document : (typeof document !== "undefined" ? document : null);
+      if (!currentWin || !currentDoc) return false;
       try {
-        const url = URL.createObjectURL(blob);
-        const anchor = document.createElement("a");
+        const isBlob = typeof Blob !== "undefined" && target instanceof Blob;
+        const url = isBlob ? (currentWin.URL?.createObjectURL?.(target) || URL.createObjectURL(target)) : String(target);
+        const anchor = currentDoc.createElement("a");
         anchor.href = url;
         anchor.download = filename || "download";
         anchor.style.display = "none";
-        document.body.appendChild(anchor);
+        currentDoc.body.appendChild(anchor);
         anchor.click();
-        document.body.removeChild(anchor);
-        setTimeout(() => {
-          try { URL.revokeObjectURL(url); } catch (_) {}
-        }, 1500);
+        currentDoc.body.removeChild(anchor);
+        if (isBlob) {
+          const timer = setTimeout(() => {
+            try { (currentWin.URL?.revokeObjectURL || URL.revokeObjectURL)(url); } catch (_) {}
+          }, 60000);
+          if (typeof timer?.unref === "function") timer.unref();
+        }
         return true;
       } catch (_) {
         return false;
@@ -1383,14 +1487,160 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Request raw bytes from host via RPC and trigger browser download.
+     * Whether this page runs inside the Desktop (Electron) shell.
+     *
+     * The Desktop host ships this same UI inside Electron, where `<a download>`
+     * has no download panel to report progress in: the shell saves to a default
+     * folder or opens its own dialog, and a 100 MB transfer gives the user no
+     * feedback while it runs. A real browser owns progress, pause, resume and
+     * the save location, so handing it the URL is strictly better there than
+     * buffering the bytes in the page.
+     *
+     * Electron identifies itself in the UA (and in `process.versions`). A wrong
+     * answer only changes which transfer strategy runs, never which files may
+     * be read, so the probe stays cheap and silent.
+     * @param {any} win - the window to inspect.
+     * @returns {boolean} true when the page is the Desktop shell.
      */
-    function performDownload(requestFn, root, path, name, onToast) {
-      if (!root || !path || typeof requestFn !== "function") {
+    function isDesktopShell(win) {
+      try {
+        if (/Electron\//i.test(String(win?.navigator?.userAgent ?? ""))) return true;
+        const versions = win?.process?.versions;
+        return typeof versions?.electron === "string";
+      } catch (_) {
+        return false;
+      }
+    }
+
+    /**
+     * Download one file, choosing the transfer that fits the host shell.
+     *
+     * Two strategies, because the two shells have opposite needs:
+     *   - a browser has a download manager that owns progress, pause, resume
+     *     and the save location, so the authenticated URL is handed straight
+     *     to it — a HEAD probe first turns "413" and "404" into an immediate
+     *     notice instead of a failed download entry;
+     *   - the Desktop shell has no such panel, so the bytes stream through
+     *     `fetch` with a real-time percentage, then reach the save flow as a
+     *     blob. That path keeps the page responsive and is the only one that
+     *     can show progress inside the drawer.
+     * Both fall back to the RPC `bytes` method when the streaming route is
+     * unavailable, so an older host or a blocked route still downloads.
+     * @param {(method: string, payload: object) => Promise<any>} requestFn - RPC caller.
+     * @param {string} root - root id the file belongs to.
+     * @param {string} path - path relative to that root.
+     * @param {string} [name] - display name to save under.
+     * @param {(message: string) => void} [onToast] - progress and result sink.
+     * @returns {Promise<boolean>} whether a download was started.
+     */
+    async function performDownload(requestFn, root, path, name, onToast) {
+      if (!root || !path) {
         if (onToast) onToast("未指定下载文件路径");
-        return Promise.resolve(false);
+        return false;
       }
       const filename = name || baseNameOf(path);
+      const currentWin = typeof globalThis !== "undefined" && globalThis.window ? globalThis.window : (typeof window !== "undefined" ? window : null);
+      const currentDoc = typeof globalThis !== "undefined" && globalThis.document ? globalThis.document : (typeof document !== "undefined" ? document : null);
+
+      if (currentWin && currentDoc && currentWin.location && currentWin.location.origin) {
+        const downloadUrl = `/api/file-viewer/download?root=${encodeURIComponent(root)}&path=${encodeURIComponent(path)}&filename=${encodeURIComponent(filename)}`;
+        const canFetch = typeof currentWin.fetch === "function";
+
+        // 浏览器：把鉴权后的 URL 直接交给原生下载管理器（进度、暂停、续传、保存位置都由它负责）
+        if (canFetch && !isDesktopShell(currentWin)) {
+          try {
+            const head = await currentWin.fetch(downloadUrl, { method: "HEAD", credentials: "same-origin" });
+            if (head.status === 413) {
+              if (onToast) onToast("文件超过下载限制（上限 100MB）");
+              return false;
+            }
+            if (!head.ok) throw new Error(`HTTP ${head.status}`);
+          } catch (_) {
+            // A failed probe is not a failed download: the browser still owns
+            // the request and reports its own outcome.
+          }
+          const handed = triggerDownload(downloadUrl, filename);
+          if (handed) {
+            if (onToast) onToast(`已交由浏览器下载 ${filename}`);
+            return true;
+          }
+        }
+
+        // 桌面端（或直链不可用）：流式读取并实时显示百分比进度
+        if (canFetch) {
+          try {
+            if (onToast) onToast(`正在准备下载 ${filename}...`);
+            const resp = await currentWin.fetch(downloadUrl, { method: "GET", credentials: "same-origin" });
+            if (!resp.ok) {
+              if (resp.status === 413) {
+                if (onToast) onToast("文件超过下载限制（上限 100MB）");
+                return false;
+              }
+              throw new Error(`HTTP ${resp.status}`);
+            }
+
+            const contentLength = Number(resp.headers?.get?.("content-length")) || 0;
+            const total = Number.isFinite(contentLength) && contentLength > 0 ? contentLength : 0;
+
+            let blob;
+            if (resp.body && typeof resp.body.getReader === "function") {
+              const reader = resp.body.getReader();
+              const chunks = [];
+              let loaded = 0;
+              let lastUpdate = 0;
+
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                if (value) {
+                  chunks.push(value);
+                  loaded += value.byteLength;
+                  const now = Date.now();
+                  if (now - lastUpdate > 100 || (total > 0 && loaded >= total)) {
+                    lastUpdate = now;
+                    const percent = total > 0 ? Math.min(100, Math.round((loaded / total) * 100)) : 0;
+                    const progressText = total > 0
+                      ? `正在下载 ${filename} (${percent}% - ${formatBytes(loaded)} / ${formatBytes(total)})...`
+                      : `正在下载 ${filename} (${formatBytes(loaded)})...`;
+                    if (onToast) onToast(progressText);
+                  }
+                }
+              }
+              const mime = resp.headers?.get?.("content-type") || "application/octet-stream";
+              blob = new Blob(chunks, { type: mime });
+            } else if (typeof resp.blob === "function") {
+              blob = await resp.blob();
+            } else {
+              blob = new Blob([await resp.arrayBuffer()]);
+            }
+
+            const ok = triggerDownload(blob, filename);
+            if (onToast) {
+              onToast(ok ? `✓ 下载完成 ${filename} (${formatBytes(blob.size)})` : "下载触发失败，请重试");
+            }
+            return ok;
+          } catch (err) {
+            if (err?.message?.includes("413") || err?.code === "too-large") {
+              if (onToast) onToast("文件超过下载限制（上限 100MB）");
+              return false;
+            }
+            // 流式通道异常时继续尝试直链与 RPC
+          }
+        }
+
+        // 无 fetch 环境：只能把 URL 交给宿主处理
+        const direct = triggerDownload(downloadUrl, filename);
+        if (direct) {
+          if (onToast) onToast(`已交由浏览器下载 ${filename}`);
+          return true;
+        }
+      }
+
+      if (typeof requestFn !== "function") {
+        if (onToast) onToast("未配置有效的下载通道");
+        return false;
+      }
+
       if (onToast) onToast(`正在准备下载 ${filename}...`);
       return requestFn("bytes", { root, path })
         .then((res) => {
@@ -1405,7 +1655,7 @@ window.__ModuleLoader__.load({
         })
         .catch((err) => {
           const msg = err?.code === "too-large"
-            ? "文件超过下载限制（上限 20MB）"
+            ? "文件超过下载限制（上限 100MB）"
             : `下载失败: ${err?.message || "网络异常"}`;
           if (onToast) onToast(msg);
           return false;
@@ -1493,6 +1743,11 @@ window.__ModuleLoader__.load({
       // Which session the conversation header currently belongs to. The phone
       // entry is drawn outside that header and cannot receive its props.
       const sessionStore = createStore(undefined);
+      // Publish this apply's stores to the Host wrappers. A re-apply installs new
+      // stores but the wrappers are already in place, so they must follow the
+      // ones the freshly mounted overlay subscribes to.
+      liveOpenStore = openStore;
+      liveSessionStore = sessionStore;
       // The composer's draft accessors, captured from the slot that receives
       // them. The drawer renders in a different subtree and cannot reach the
       // input state through props.
@@ -3394,6 +3649,9 @@ window.__ModuleLoader__.load({
       // Intercept any openWorkspacePath RPC calls (connection is declared in inject)
       wrapConnectionRpc(ctx, openStore, sessionStore);
 
+      // The changes card's native open route bypasses the RPC carrier entirely.
+      wrapChangesOpenFetch(openStore, sessionStore);
+
       // Wrap sidebarRight if already registered or whenever injected. Direct
       // property access is not safe here: sidebarRight is not part of this
       // plugin's inject, so cordis would reject the read outright.
@@ -3441,8 +3699,8 @@ window.__ModuleLoader__.load({
       LANG_OVERRIDES_KEY, LANG_OVERRIDES_MAX, readLangOverrides, writeLangOverrides, readLangOverride, writeLangOverride,
       langOverrideKey, isKnownLanguageId, setLanguageCatalog, getLanguageCatalog: () => languageCatalog, LanguagePicker,
       MARKDOWN_LABELS, MARKDOWN_CODE_LABELS, READ_BLOCK_LABELS, JSON_TREE_LABELS, DIFF_BLOCK_LABELS, ErrorBoundary,
-      openViewerForPath, wrapWorkspaceOpenPath, wrapConnectionRpc, wrapSidebarRight, parseFileResource, setupGlobalFileClickInterceptor, extractClickedPath, normalizeClickedPath, looksLikeFilePath, isFileOpenControl, isFileMentionCode, renderRootOptions,
-      triggerDownload, performDownload, SvgIconDownload,
+      openViewerForPath, wrapWorkspaceOpenPath, wrapConnectionRpc, wrapChangesOpenFetch, wrapSidebarRight, parseFileResource, setupGlobalFileClickInterceptor, extractClickedPath, normalizeClickedPath, looksLikeFilePath, isFileOpenControl, isFileMentionCode, renderRootOptions,
+      triggerDownload, performDownload, isDesktopShell, SvgIconDownload,
     };
     return module.exports;
   }

package/lib/core.js

@@ -7,9 +7,26 @@
  * @module dsh-file-viewer/core
  */
 
-/** Largest binary payload the RPC channel will base64-encode for the browser. */
+/**
+ * Largest binary payload the RPC viewer channel will base64-encode (20 MB).
+ *
+ * This budget belongs to the in-page preview path, which ships bytes as a
+ * base64 string inside a JSON envelope: a 20 MB file already costs ~27 MB of
+ * wire text plus an `atob` decode on the main thread. Raising it would make
+ * every preview of a large PDF or image block the browser, so downloads —
+ * which have their own streaming path — deliberately do not share it.
+ */
 export const MAX_BYTES = 20 * 1024 * 1024
 
+/**
+ * Largest file the download endpoint will stream (100 MB).
+ *
+ * Kept separate from {@link MAX_BYTES} on purpose: a download is consumed by
+ * the save flow rather than decoded into the page, so it can afford a budget
+ * the in-page preview path could never justify.
+ */
+export const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024
+
 /** Largest text file the viewer reads as text at all. */
 export const MAX_TEXT_BYTES = 8 * 1024 * 1024
 
@@ -545,6 +562,38 @@ export function mediaTypeOf(path) {
   return Object.hasOwn(MEDIA_TYPE_BY_EXTENSION, ext) ? MEDIA_TYPE_BY_EXTENSION[ext] : undefined
 }
 
+/**
+ * Build a `Content-Disposition` value that survives non-ASCII file names.
+ *
+ * HTTP header values are ByteStrings: every code unit must be ≤ 0xFF, so a raw
+ * Chinese or emoji name makes `Response` reject the whole header (and the
+ * download fails with a 500). RFC 6266/5987 solves this with two parameters:
+ * a plain `filename=` fallback restricted to ASCII, and `filename*=` carrying
+ * the real name as percent-encoded UTF-8. Browsers prefer `filename*` when it
+ * is present, so the fallback only has to stay legal, not pretty.
+ *
+ * The fallback drops anything outside printable ASCII, then collapses the
+ * result so a name made entirely of non-ASCII characters still yields a usable
+ * value instead of an empty one.
+ * @param {string} name - the file name to advertise.
+ * @returns {string} a header value safe for any byte-string header carrier.
+ */
+export function contentDispositionFor(name) {
+  const raw = typeof name === 'string' ? name : ''
+  // Strip CR/LF first: those would end the header rather than appear in it.
+  const withoutBreaks = raw.replace(/[\r\n]+/g, ' ')
+  // Printable ASCII minus the quote and backslash that would break the quoting.
+  const ascii = withoutBreaks.replace(/[^\x20-\x7E]/g, '').replace(/["\\]/g, '')
+  const trimmed = ascii.trim()
+  const fallback = trimmed === '' || trimmed === '.' || trimmed === '..' ? 'download' : trimmed
+  const encoded = encodeURIComponent(withoutBreaks)
+  // encodeURIComponent leaves ' ( ) * ! unescaped; RFC 5987 forbids none of
+  // them but a stray ' would be read as the charset/language separator, so it
+  // is escaped explicitly.
+  const extValue = encoded.replace(/'/g, '%27')
+  return `attachment; filename="${fallback}"; filename*=UTF-8''${extValue}`
+}
+
 /**
  * Which viewer renders this path. The client switches on this one word, so the
  * host and the client can never disagree about a file's kind.

package/lib/index.js

@@ -23,11 +23,13 @@ import z from '@deepseek-ai/schemastery'
 import {
   LANGUAGE_CATALOG,
   MAX_BYTES,
+  MAX_DOWNLOAD_BYTES,
   MAX_PREVIEW_BYTES,
   MAX_TEXT_BYTES,
   TEXT_PROBE_BYTES,
   appendMention,
   baseNameOf,
+  contentDispositionFor,
   detectLanguageFromText,
   extensionOf,
   formatDocTextToMarkdown,
@@ -42,6 +44,7 @@ import {
   joinPath,
   kindOf,
   langOf,
+  mediaTypeOf,
   normalizeSafePaths,
   parseGitStatus,
   parsePatchToDiffs,
@@ -59,11 +62,13 @@ import {
 export {
   LANGUAGE_CATALOG,
   MAX_BYTES,
+  MAX_DOWNLOAD_BYTES,
   MAX_PREVIEW_BYTES,
   MAX_TEXT_BYTES,
   TEXT_PROBE_BYTES,
   appendMention,
   baseNameOf,
+  contentDispositionFor,
   detectLanguageFromText,
   extensionOf,
   formatDocTextToMarkdown,
@@ -79,6 +84,7 @@ export {
   joinPath,
   kindOf,
   langOf,
+  mediaTypeOf,
   normalizeSafePaths,
   parseGitStatus,
   parsePatchToDiffs,
@@ -101,6 +107,15 @@ export const inject = ['fs', 'connection', 'settings', 'workspaceRegistry', 'ses
 export const NS = 'file-viewer'
 export const RPC_CHANNEL = '/dsh-file-viewer'
 
+/**
+ * Exact Fetch route that streams one file to the browser's save flow.
+ *
+ * Lives below `/api` so the Connection carrier applies its Host/Origin fence
+ * and browser-cookie admission before this handler ever runs; only an owner
+ * Peer (the same principal the RPC channel serves) reaches it.
+ */
+export const DOWNLOAD_ROUTE = '/api/file-viewer/download'
+
 const VOLATILE_WRITE = Symbol.for('cosmokit.volatile.write')
 
 export function liveField(schema) {
@@ -222,7 +237,8 @@ export const Config = z.object({
   safePaths: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('安全访问路径（除工作区外的可访问路径列表）'),
   safeAccessPaths: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('安全访问路径（safePaths 别名）'),
   extraRoots: liveField(z.union([z.array(PathEntry), z.string()]).default([])).description('额外根目录（向后兼容 safePaths）'),
-  maxBytes: z.natural().default(MAX_BYTES),
+  maxBytes: z.natural().default(MAX_BYTES).description('在线预览（图片/PDF/表格等）单文件上限，默认 20 MB'),
+  maxDownloadBytes: z.natural().default(MAX_DOWNLOAD_BYTES).description('下载到本地单文件上限，默认 100 MB'),
   settingsFile: z.string().default('').description('安全访问路径本地持久化配置文件路径（留空则默认保存在 ~/.dsh/file-viewer/settings.json）'),
 })
 
@@ -1178,6 +1194,105 @@ export async function handleRpc(ctx, options, method, payload, signal) {
   }
 }
 
+/**
+ * Map one thrown value onto a status plus a body that is safe to echo.
+ *
+ * Two rules matter here and both are enforced by the existing RPC channel
+ * (`handleRpc`), so the streaming route must not be a weaker door:
+ *   - backend fs failures carry host codes (`FS_TOO_LARGE`, `FS_NOT_FOUND`,
+ *     …) and must land on the status the client already switches on, or the
+ *     "exceeds 100 MB" notice never fires;
+ *   - the body is an opaque reason, never `error.message`, because fs errors
+ *     embed absolute host paths (`EACCES: … 'D:/repo/secret/.env'`).
+ * @param {unknown} error - the thrown value.
+ * @returns {{status: number, reason: string}} status and a path-free reason.
+ */
+export function downloadFailure(error) {
+  if (error instanceof ViewerError) {
+    const viewerStatus = {
+      'not-found': 404,
+      'not-a-directory': 403,
+      'is-a-directory': 403,
+      'unknown-root': 404,
+      'no-roots': 404,
+      'outside-root': 403,
+      'access-denied': 403,
+      'too-large': 413,
+      unsupported: 415,
+    }
+    return { status: viewerStatus[error.code] ?? 400, reason: error.code }
+  }
+  const code = typeof error?.code === 'string' ? error.code : ''
+  const fsStatus = {
+    FS_NOT_FOUND: 404,
+    FS_NOT_DIRECTORY: 403,
+    FS_NOT_REGULAR_FILE: 403,
+    FS_PERMISSION_DENIED: 403,
+    FS_SANDBOX_DENIED: 403,
+    FS_TOO_LARGE: 413,
+    FS_ABORTED: 499,
+    FS_IO_ERROR: 500,
+  }
+  if (Object.hasOwn(fsStatus, code)) return { status: fsStatus[code], reason: code }
+  return { status: 500, reason: 'download-failed' }
+}
+
+/**
+ * Stream one file to the browser's save flow under the authenticated API fence.
+ *
+ * Files are read through `ctx.fs` with the caller's signal so a cancelled
+ * download stops the host read, and the byte budget comes from
+ * `maxDownloadBytes` rather than the much smaller in-page preview budget.
+ */
+export async function handleDownloadRequest(ctx, options, request) {
+  try {
+    const url = new URL(request.url, 'http://dsh.local')
+    const root = url.searchParams.get('root') || undefined
+    const path = url.searchParams.get('path') || ''
+    const customFilename = url.searchParams.get('filename') || ''
+
+    const { target, relative } = await resolveInRoot(ctx, options, { root, path }, request.signal)
+    const info = await ctx.fs.stat(target, request.signal)
+    if (info === undefined) {
+      return new Response('not-found', { status: 404 })
+    }
+    if (info.type === 'directory') {
+      return new Response('is-a-directory', { status: 403 })
+    }
+
+    const maxBytes = options().maxDownloadBytes ?? MAX_DOWNLOAD_BYTES
+    if (typeof info.size === 'number' && info.size > maxBytes) {
+      return new Response('too-large', { status: 413 })
+    }
+
+    const naming = relative === '' ? target.displayPath : relative
+    const filename = customFilename || baseNameOf(naming)
+    const mime = mediaTypeOf(naming) || 'application/octet-stream'
+
+    const headers = {
+      'Content-Type': mime,
+      'Content-Disposition': contentDispositionFor(filename),
+      'Cache-Control': 'private, no-store',
+      'X-Content-Type-Options': 'nosniff',
+    }
+
+    if (request.method === 'HEAD') {
+      if (info.size !== undefined) headers['Content-Length'] = String(info.size)
+      return new Response(null, { headers })
+    }
+
+    // `readBytes` enforces the same budget, so a backend that reports no size
+    // still cannot hand back more than the download limit.
+    const bytes = await ctx.fs.readBytes(target, request.signal, maxBytes)
+    headers['Content-Length'] = String(bytes.byteLength)
+    return new Response(bytes, { headers })
+  } catch (error) {
+    const { status, reason } = downloadFailure(error)
+    ctx.logger?.warn?.(`file-viewer: download failed with ${reason}`)
+    return new Response(reason, { status })
+  }
+}
+
 /**
  * Register the browser-facing channel.
  * @param {import('@deepseek-ai/cordis').Context} ctx - host context.
@@ -1227,6 +1342,7 @@ export function apply(ctx, config = {}) {
       safeAccessPaths: settings?.safeAccessPaths ?? [],
       extraRoots: settings?.extraRoots ?? [],
       maxBytes: settings?.maxBytes ?? MAX_BYTES,
+      maxDownloadBytes: settings?.maxDownloadBytes ?? MAX_DOWNLOAD_BYTES,
       _updateSafePaths: updateSafePaths,
       _settingsFile: settingsFile,
     }
@@ -1238,5 +1354,24 @@ export function apply(ctx, config = {}) {
       (method, payload, signal) => handleRpc(ctx, options, method, payload, signal),
       { authority: 'trusted-host' },
     )
+    /*
+     * The download route is an optimization, not a requirement: the RPC
+     * `bytes` method still downloads anything the streaming path cannot
+     * reach. Registering a duplicate path throws inside `connection.fetch`
+     * (its exact-route table rejects collisions), so a failure here must
+     * degrade to the RPC path instead of aborting the whole plugin apply.
+     */
+    try {
+      if (typeof connectionCtx.connection?.fetch?.register === 'function') {
+        connectionCtx.connection.fetch.register({
+          path: DOWNLOAD_ROUTE,
+          methods: ['GET', 'HEAD'],
+          requestBody: 'buffered',
+          fetch: (request) => handleDownloadRequest(ctx, options, request),
+        })
+      }
+    } catch (error) {
+      ctx.logger?.warn?.(`file-viewer: download route unavailable, falling back to RPC (${error?.message || error})`)
+    }
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weniatall/dsh-file-viewer",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Workspace file viewer for DeepSeek Harness: file tree, syntax-highlighted code with language detection and manual override, images, PDF, Excel and Word",
   "type": "module",
   "main": "lib/index.js",