@cowwo/dsh-lookout 0.5.1 → 0.5.3

package/README.md

@@ -48,7 +48,7 @@
 文件面板里每个文件 / 文件夹行的右侧多出一个「⋯」按钮，点开可以：
 
 - **复制路径**：把这一行的**绝对路径**原样放进剪贴板（不是屏幕上显示的短名）。
-- **下载**：下载单个文件，上限 20 MB；超过会提示「文件超过 20MB，暂不支持下载」。
+- **下载**：下载单个文件；上限由服务端决定（默认 50 MiB，可配置），超过会提示「文件太大，超出服务器允许的下载上限」。
 - **文件夹**：菜单仍可打开，但「下载」是灰的，并标注「文件夹暂不支持」。
 
 设置页里有「文件行 ⋯ 菜单」开关，可以整体关掉。这个菜单是贴着宿主文件树画上去的：DSH 升级换了文件面板结构时，它可能不再出现，但**文件树本身不受影响**；连续 3 次注入失败会自动停止，并且只提示一次（可点「不再提示」）。

package/client/client.js

@@ -7264,13 +7264,17 @@ window.__ModuleLoader__.load({
    * pair, no React for the menu itself, and nothing but DOM writes into the
    * shipped file tree.
    *
-   * Host contract (read-only reference: @deepseek-ai/dsh-client-ui-sidebar-files):
-   *   [data-files-body] li[data-files-entry="file"|"directory"][data-files-path]
-   *     > button.row
+   * Host contract (read-only reference: @deepseek-ai/dsh-client-ui-sidebar-files).
+   * Two shapes ship today and both are supported:
+   *   legacy  (0.2.1): li > button
+   *   current (0.2.2): li > div.row > (button.action, div.accessory), and an
+   *                    expanded directory keeps its <ul class="level"> beside div.row
    * The absolute path is ALWAYS read from data-files-path; it is never rebuilt
-   * from the row text. Rows of type "other" are left alone. The menu button is
-   * inserted as a SIBLING after that row button, never inside it: a nested
-   * button is invalid HTML and its click would bubble into "open this file".
+   * from the row text. Rows of type "other" are left alone. In the legacy shape
+   * the menu button is inserted as a SIBLING after that row button; in the
+   * current shape it becomes one more item inside the host's own accessory slot.
+   * Either way it is never nested inside the host's button: a nested button is
+   * invalid HTML and its click would bubble into "open this file".
    *
    * Every entry point is guarded. A selector that stops matching after a host
    * upgrade can only cost these buttons, never the host's own rendering; three
@@ -7279,12 +7283,21 @@ window.__ModuleLoader__.load({
   const ROW_MENU_NS = "dsh-lookout";
   /** Sibling button injected after the row button; its presence is the idempotency key. */
   const ROW_MENU_ATTR = "data-lookout-rowmenu";
+  /** Modifier for the current host shape: inline inside the host's accessory slot. */
+  const ROW_MENU_INLINE_CLASS = "dsh-lookout-rowmenu--inline";
+  /** The host's right-hand slot inside li > div.row (sidebar-files 0.2.2). */
+  const ROW_MENU_ACCESSORY_CLASS = "accessory";
   const ROW_MENU_POP_ATTR = "data-lookout-rowmenu-pop";
   const ROW_MENU_TOAST_ATTR = "data-lookout-toast";
   const ROW_MENU_STYLE_KEY = "lookout-row-menu";
   const ROW_MENU_BODY_SELECTOR = "[data-files-body]";
   const ROW_MENU_ROWS_SELECTOR = 'li[data-files-entry="file"],li[data-files-entry="directory"]';
   const ROW_MENU_PATH_ATTR = "data-files-path";
+  /** Same-origin download route: HEAD is our pre-flight, the browser streams the GET. */
+  const ROW_MENU_DOWNLOAD_ROUTE = "/api/lookout.download";
+  /** Where the current session id is read from, sidebar marker first, storage second. */
+  const ROW_MENU_SESSION_ATTR = "data-sidebar-right-session";
+  const ROW_MENU_SESSION_KEY = "dsh.sessions.current";
   /** A run that places nothing at all, this many times in a row, gives up. */
   const ROW_MENU_MAX_FAILURES = 3;
   const ROW_MENU_SCAN_DEBOUNCE = 200;
@@ -7314,12 +7327,13 @@ window.__ModuleLoader__.load({
     download: "下载",
     folderUnsupported: "文件夹暂不支持",
     copyFailed: "复制失败，请手动选择路径",
+    err400: "下载参数不完整：缺少会话或文件路径",
     err401: "登录已过期，请刷新页面重新登录",
-    err413: "文件超过 20MB，暂不支持下载",
     err404: "文件不存在或已被删除",
-    err403: "没有权限读取这个文件",
+    err403: "只能下载当前会话工作区内的文件",
     errOther: "下载失败（HTTP {status}）",
     errNetwork: "下载失败，请检查连接",
+    errSession: "无法确定当前会话，已取消下载",
     givingUp: "文件行「⋯」菜单连续注入失败，已自动停止；文件树本身不受影响。",
     dismiss: "不再提示"
   };
@@ -7332,12 +7346,13 @@ window.__ModuleLoader__.load({
     download: "Download",
     folderUnsupported: "Folders not supported",
     copyFailed: "Copy failed — select the path and copy it manually",
+    err400: "The download request is incomplete: missing session or file path.",
     err401: "Your session has expired. Refresh the page and sign in again.",
-    err413: "This file is larger than 20 MB and cannot be downloaded yet.",
     err404: "The file no longer exists or was deleted.",
-    err403: "You do not have permission to read this file.",
+    err403: "You can only download files inside the current session's workspace.",
     errOther: "Download failed (HTTP {status}).",
     errNetwork: "Download failed — check your connection.",
+    errSession: "Cannot determine the current session — download cancelled.",
     givingUp: "The file-row ⋯ menu could not be injected repeatedly and stopped; the file tree itself is unaffected.",
     dismiss: "Do not show again"
   };
@@ -7348,6 +7363,7 @@ window.__ModuleLoader__.load({
    */
   const ROW_MENU_CSS = [
     ".dsh-lookout-rowmenu{position:absolute;top:4px;right:4px;z-index:2;display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;padding:0;border:0;border-radius:6px;background:transparent;color:var(--dsw-alias-label-tertiary);cursor:pointer;line-height:1;touch-action:manipulation;-webkit-tap-highlight-color:transparent;}",
+    ".dsh-lookout-rowmenu--inline{position:static;top:auto;right:auto;flex:none;}",
     ".dsh-lookout-rowmenu:hover,.dsh-lookout-rowmenu:focus-visible{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover);outline:none;}",
     ".dsh-lookout-rowmenu svg{display:block;width:16px;height:16px;pointer-events:none;}",
     ".dsh-lookout-rowmenu[data-lookout-copied]{color:var(--dsw-alias-state-success-primary);}",
@@ -7527,27 +7543,113 @@ window.__ModuleLoader__.load({
     }
 
     // ---- injected row button -------------------------------------------
-    function directRowButton(row) {
+    /** True for one of our own ⋯ buttons, whichever shape it currently sits in. */
+    function isMenuButton(node) {
+      return node !== null && node !== undefined && typeof node.getAttribute === "function" && node.getAttribute(ROW_MENU_ATTR) !== null;
+    }
+
+    /** classList when the DOM has one, className text otherwise (svg / minimal hosts). */
+    function hasClass(node, name) {
+      if (node === null || node === undefined) return false;
+      const list = node.classList;
+      if (list !== undefined && list !== null && typeof list.contains === "function") {
+        try { return list.contains(name) === true; } catch { /* fall back to className */ }
+      }
+      const raw = node.className;
+      const text = typeof raw === "string" ? raw : raw !== null && raw !== undefined && typeof raw.baseVal === "string" ? raw.baseVal : "";
+      return text.split(/\s+/).indexOf(name) >= 0;
+    }
+
+    /** Toggle the inline modifier without touching any other class on the button. */
+    function setInlineClass(button, inline) {
+      if (hasClass(button, ROW_MENU_INLINE_CLASS) === inline) return;
+      const list = button.classList;
+      if (list !== undefined && list !== null && typeof list.add === "function" && typeof list.remove === "function") {
+        try {
+          if (inline) list.add(ROW_MENU_INLINE_CLASS);
+          else list.remove(ROW_MENU_INLINE_CLASS);
+          return;
+        } catch { /* fall back to className */ }
+      }
+      const kept = String(button.className === null || button.className === undefined ? "" : button.className)
+        .split(/\s+/)
+        .filter((item) => item !== "" && item !== ROW_MENU_INLINE_CLASS);
+      if (inline) kept.push(ROW_MENU_INLINE_CLASS);
+      button.className = kept.join(" ");
+    }
+
+    /** The host's own row button: first direct child BUTTON that is not ours. */
+    function directRowButton(container) {
+      for (const child of container.children) {
+        if (child.tagName === "BUTTON" && !isMenuButton(child)) return child;
+      }
+      return null;
+    }
+
+    /**
+     * Split one row into the host's button and the slot our ⋯ may occupy.
+     *
+     * Both shipped shapes are accepted, so an upgrade (or a rollback) never costs
+     * the menu:
+     *   legacy  0.2.1: li > button
+     *   current 0.2.2: li > div.row > (button.action, div.accessory)
+     * The accessory is found by class alone and may sit before or after the
+     * button; when a row has none, the ⋯ is appended to div.row itself.
+     * @param row - one li[data-files-entry] row.
+     * @returns {{rowButton: Element, mount: Element|null, legacy: boolean}|null} null when the row matches neither shape.
+     */
+    function rowParts(row) {
+      const legacyButton = directRowButton(row);
+      if (legacyButton !== null) return { rowButton: legacyButton, mount: null, legacy: true };
       for (const child of row.children) {
-        if (child.tagName === "BUTTON" && child.getAttribute(ROW_MENU_ATTR) === null) return child;
+        if (child.tagName !== "DIV") continue;
+        const rowButton = directRowButton(child);
+        if (rowButton === null) continue;
+        let mount = null;
+        for (const inner of child.children) {
+          if (inner.tagName === "DIV" && hasClass(inner, ROW_MENU_ACCESSORY_CLASS)) { mount = inner; break; }
+        }
+        return { rowButton, mount: mount !== null ? mount : child, legacy: false };
       }
       return null;
     }
 
+    /**
+     * The one ⋯ button we own in this row, in either shape. Looking one level
+     * deeper (div.row, then div.accessory) is what keeps a row at exactly one ⋯
+     * while the host re-renders or the shape changes under us.
+     */
     function directMenuButton(row) {
       for (const child of row.children) {
-        if (child.getAttribute(ROW_MENU_ATTR) !== null) return child;
+        if (isMenuButton(child)) return child;
+        if (child.tagName !== "DIV") continue;
+        for (const inner of child.children) {
+          if (isMenuButton(inner)) return inner;
+          if (!hasClass(inner, ROW_MENU_ACCESSORY_CLASS)) continue;
+          for (const deep of inner.children) if (isMenuButton(deep)) return deep;
+        }
       }
       return null;
     }
 
+    /**
+     * Legacy shape only: the ⋯ floats, so the row must become its positioning
+     * parent and the host button must give it room. A style is recorded only at
+     * the moment it really changes, so restoreStyles() never writes back a value
+     * it did not set. The current shape calls neither — its accessory slot is
+     * already the host's own layout space.
+     */
     function ensureStyles(row, rowButton) {
-      if (!savedRowPositions.has(row)) savedRowPositions.set(row, row.style.position);
-      try {
-        if (window.getComputedStyle(row).position === "static") row.style.position = "relative";
-      } catch { row.style.position = "relative"; }
-      if (!savedButtonPadding.has(rowButton)) savedButtonPadding.set(rowButton, rowButton.style.paddingRight);
-      if (rowButton.style.paddingRight !== ROW_MENU_BUTTON_PADDING) rowButton.style.paddingRight = ROW_MENU_BUTTON_PADDING;
+      let position = "static";
+      try { position = window.getComputedStyle(row).position; } catch { position = "static"; }
+      if (position === "static") {
+        if (!savedRowPositions.has(row)) savedRowPositions.set(row, row.style.position);
+        if (row.style.position !== "relative") row.style.position = "relative";
+      }
+      if (rowButton.style.paddingRight !== ROW_MENU_BUTTON_PADDING) {
+        if (!savedButtonPadding.has(rowButton)) savedButtonPadding.set(rowButton, rowButton.style.paddingRight);
+        rowButton.style.paddingRight = ROW_MENU_BUTTON_PADDING;
+      }
     }
 
     function pruneDetachedStyles() {
@@ -7666,15 +7768,22 @@ window.__ModuleLoader__.load({
           for (const row of rows) {
             const path = row.getAttribute(ROW_MENU_PATH_ATTR);
             if (typeof path !== "string" || path === "") { missed++; continue; }
-            const rowButton = directRowButton(row);
-            if (rowButton === null) { missed++; continue; }
+            const parts = rowParts(row);
+            if (parts === null) { missed++; continue; }
             const isDirectory = row.getAttribute("data-files-entry") === "directory";
-            ensureStyles(row, rowButton);
             let button = directMenuButton(row);
-            if (button === null) {
-              button = createRowButton();
-              rowButton.insertAdjacentElement("afterend", button);
+            if (parts.legacy) {
+              // Legacy shape: float the ⋯ over the row, and restyle only then.
+              ensureStyles(row, parts.rowButton);
+              if (button === null) button = createRowButton();
+              if (button.parentNode !== parts.rowButton.parentNode) parts.rowButton.insertAdjacentElement("afterend", button);
+            } else {
+              // Current shape: the host already owns the right-hand slot, so nothing
+              // is restyled — the ⋯ is one more inline item inside that slot.
+              if (button === null) button = createRowButton();
+              if (button.parentNode !== parts.mount) parts.mount.appendChild(button);
             }
+            setInlineClass(button, !parts.legacy);
             const previousPath = button.getAttribute("data-lookout-path");
             if (previousPath !== path) {
               if (menuAnchor === button) closeMenu();
@@ -8031,18 +8140,49 @@ window.__ModuleLoader__.load({
 
     function downloadErrorText(status) {
       switch (status) {
+        case 400: return translate("err400");
         case 401: return translate("err401");
-        case 413: return translate("err413");
-        case 404: return translate("err404");
         case 403: return translate("err403");
+        case 404: return translate("err404");
         default: return translate("errOther", { status: status > 0 ? status : "?" });
       }
     }
 
+    /** The current session id: sidebar marker first, persisted pointer second, "" if neither. */
+    function currentSessionId() {
+      try {
+        const marker = document.querySelector("[" + ROW_MENU_SESSION_ATTR + "]");
+        const attr = marker !== null && marker !== undefined ? marker.getAttribute(ROW_MENU_SESSION_ATTR) : null;
+        if (typeof attr === "string" && attr !== "") return attr;
+      } catch (error) { /* fall through to storage */ }
+      try {
+        const stored = window.localStorage.getItem(ROW_MENU_SESSION_KEY);
+        if (typeof stored === "string" && stored !== "") return stored;
+      } catch (error) { /* no storage: no session */ }
+      return "";
+    }
+
+    function downloadUrl(sessionId, path) {
+      return ROW_MENU_DOWNLOAD_ROUTE
+        + "?sessionId=" + encodeURIComponent(sessionId)
+        + "&path=" + encodeURIComponent(path);
+    }
+
+    /**
+     * Download without ever holding the file: HEAD pre-flights the route, then a
+     * plain <a download> lets the browser stream its own GET to disk. A failed
+     * pre-flight never starts a download, it only explains why.
+     */
     async function downloadRowFile(path) {
+      const sessionId = currentSessionId();
+      if (sessionId === "") {
+        if (!disposed) showToast(translate("errSession"), false);
+        return;
+      }
+      const url = downloadUrl(sessionId, path);
       let response = null;
       try {
-        response = await window.fetch("api/file?path=" + encodeURIComponent(path), { credentials: "same-origin" });
+        response = await window.fetch(url, { method: "HEAD", credentials: "same-origin" });
       } catch (error) {
         if (!disposed) showToast(translate("errNetwork"), false);
         return;
@@ -8052,19 +8192,16 @@ window.__ModuleLoader__.load({
         if (!disposed) showToast(downloadErrorText(status), false);
         return;
       }
+      if (disposed) return;
       try {
-        const blob = await response.blob();
-        if (disposed) return;
-        const objectUrl = window.URL.createObjectURL(blob);
         const link = document.createElement("a");
-        link.href = objectUrl;
+        link.href = url;
         link.download = fileNameFor(path);
         link.rel = "noopener";
         link.style.display = "none";
         document.body.appendChild(link);
         link.click();
         link.remove();
-        window.setTimeout(() => { try { window.URL.revokeObjectURL(objectUrl); } catch { /* gone */ } }, 1000);
       } catch (error) {
         if (!disposed) showToast(translate("errNetwork"), false);
       }

package/lib/download.js

@@ -0,0 +1,344 @@
+/**
+ * dsh-lookout · 宿主侧流式下载路由
+ *
+ * 一条精确的 Fetch 路由 `GET|HEAD /api/lookout.download`，把**某个会话 cwd 之内**的
+ * 一个普通文件流式发给浏览器（内存恒定：createReadStream → Readable.toWeb → Response）。
+ *
+ * 三条硬约束（改代码时别动）：
+ *   1. 路径逐段必须匹配 [A-Za-z0-9_$.-]+，且宿主强制 `/api/` 前缀——所以是
+ *      `/api/lookout.download` 这个字面量，不能把参数拼进路径。
+ *   2. **不要把 connection/fs 塞进 lib/index.js 顶层的 inject 数组**：那会让没有 web 载体的
+ *      组合（CLI）一直等不到服务、卡死插件加载。这里用 ctx.inject 局部等待。
+ *   3. 放行判定是"词法归一化 + realpath"两道：只有词法那道挡不住符号链接逃逸。
+ *
+ * 错误码：缺参/非绝对路径 400；越界或非普通文件 403；不存在 404；其它 500（只 warn 一次，不吐堆栈）。
+ */
+import { createReadStream, fstat } from 'node:fs'
+import { realpath } from 'node:fs/promises'
+import { Readable } from 'node:stream'
+import { basename, isAbsolute, normalize, sep } from 'node:path'
+
+/** 路由路径：宿主强制 /api/ 前缀，且每段要过 [A-Za-z0-9_$.-]+ 校验。 */
+export const DOWNLOAD_ROUTE_PATH = '/api/lookout.download'
+
+/** 同一路由路径的短名（老调用方只认这个名字）。 */
+export const DOWNLOAD_ROUTE = DOWNLOAD_ROUTE_PATH
+
+/** 认不出扩展名时一律给这个，避免浏览器瞎猜。 */
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream'
+
+/**
+ * 最小扩展名映射。只有一张表，不做内容嗅探：下载场景里"猜错"比"给 stream"更糟。
+ * @type {Record<string, string>}
+ */
+const CONTENT_TYPES = {
+	'.txt': 'text/plain',
+	'.md': 'text/markdown',
+	'.json': 'application/json',
+	'.csv': 'text/csv',
+	'.html': 'text/html',
+	'.css': 'text/css',
+	'.js': 'text/javascript',
+	'.mjs': 'text/javascript',
+	'.xml': 'application/xml',
+	'.yaml': 'text/yaml',
+	'.yml': 'text/yaml',
+	'.png': 'image/png',
+	'.jpg': 'image/jpeg',
+	'.jpeg': 'image/jpeg',
+	'.gif': 'image/gif',
+	'.webp': 'image/webp',
+	'.svg': 'image/svg+xml',
+	'.pdf': 'application/pdf',
+	'.zip': 'application/zip',
+	'.gz': 'application/gzip',
+	'.mp3': 'audio/mpeg',
+	'.wav': 'audio/wav',
+	'.mp4': 'video/mp4',
+}
+
+/**
+ * 按扩展名给出 content-type。
+ * @param {string} fileName 文件名（大小写不敏感）
+ * @returns {string} MIME 类型；认不出给 application/octet-stream
+ */
+export function contentTypeOf(fileName) {
+	const dot = fileName.lastIndexOf('.')
+	if (dot <= 0) return DEFAULT_CONTENT_TYPE
+	return CONTENT_TYPES[fileName.slice(dot).toLowerCase()] ?? DEFAULT_CONTENT_TYPE
+}
+
+/**
+ * content-disposition 里 filename="..." 那份的 ASCII 兜底：
+ * 非可见 ASCII 与引号/反斜杠一律换成下划线，空名字退回 download。
+ * @param {string} fileName 原始文件名
+ * @returns {string} 纯 ASCII 文件名
+ */
+export function asciiFileName(fileName) {
+	const cleaned = String(fileName).replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_').trim()
+	return cleaned.length === 0 ? 'download' : cleaned
+}
+
+/**
+ * 拼完整的 content-disposition：ASCII 兜底 + RFC 5987 的 filename*（真名，中文不丢）。
+ * @param {string} fileName 原始文件名
+ * @returns {string} 头值
+ */
+export function contentDisposition(fileName) {
+	const name = String(fileName ?? '')
+	return `attachment; filename="${asciiFileName(name)}"; filename*=UTF-8''${encodeURIComponent(name || 'download')}`
+}
+
+/**
+ * 判定 candidate 是否落在 root 之内（root 自身算在内）。两边都应是已归一化的绝对路径。
+ * @param {string} root 边界目录
+ * @param {string} candidate 待判定路径
+ * @returns {boolean} 是否在范围内
+ */
+export function withinRoot(root, candidate) {
+	if (candidate === root) return true
+	const base = root.endsWith(sep) ? root : root + sep
+	return candidate.startsWith(base)
+}
+
+/**
+ * 读一个宿主服务：先用 Reflect.get（普通对象与 ctx 都吃），再退回 ctx.get。
+ * @param {object} ctx 上下文（真实 ctx、inject 回调里的 scoped，或 {fs, sessions} 这类直给对象）
+ * @param {string} name 服务名
+ * @returns {any} 服务实例或 undefined
+ */
+function serviceOf(ctx, name) {
+	const direct = Reflect.get(ctx, name)
+	if (direct !== undefined && direct !== null) return direct
+	return typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+}
+
+/**
+ * 取会话 cwd。字段名现场确认过：dsh-session 的 Session 上是 `session.header.cwd`
+ * （SessionHeader.cwd，创建时校验必须是绝对路径字符串）；`meta.cwd` / `cwd` 只作兜底。
+ * @param {object|undefined} session ctx.sessions.get() 的返回值
+ * @returns {string|undefined} 绝对路径 cwd
+ */
+export function sessionCwd(session) {
+	if (session === null || typeof session !== 'object') return undefined
+	const candidates = [session.header?.cwd, session.meta?.cwd, session.cwd]
+	for (const value of candidates) if (typeof value === 'string' && value.length > 0) return value
+	return undefined
+}
+
+/**
+ * 取某个会话的工作区目录（下载的边界）。先 get，拿不到再在 list 里按 id 匹配一次。
+ * @param {object|undefined} sessions ctx.sessions
+ * @param {string} sessionId 会话 id
+ * @returns {string|null} 绝对路径，取不到给 null
+ */
+export function sessionWorkspace(sessions, sessionId) {
+	if (sessions === null || typeof sessions !== 'object') return null
+	if (typeof sessions.get === 'function') {
+		const cwd = sessionCwd(sessions.get(sessionId))
+		if (cwd !== undefined) return cwd
+	}
+	if (typeof sessions.list === 'function') {
+		for (const session of sessions.list() ?? []) {
+			if (session?.header?.id === sessionId || session?.id === sessionId) {
+				const cwd = sessionCwd(session)
+				if (cwd !== undefined) return cwd
+			}
+		}
+	}
+	return null
+}
+
+/**
+ * realpath 的"宽容版"：路径不存在/无权限时原样返回，让后面的 stat 去定 404。
+ * @param {string} path 绝对路径
+ * @returns {Promise<string>} realpath，或原路径
+ */
+async function realPathOrSelf(path) {
+	try {
+		return await realpath(path)
+	} catch {
+		return path
+	}
+}
+
+/**
+ * 统一的错误响应：纯文本 + 禁缓存。
+ * @param {number} status HTTP 状态码
+ * @param {string} message 一行说明（不吐内部细节）
+ * @returns {Response} 响应
+ */
+function errorResponse(status, message) {
+	return new Response(message, {
+		status,
+		headers: {
+			'content-type': 'text/plain; charset=utf-8',
+			'cache-control': 'private, no-store',
+		},
+	})
+}
+
+/**
+ * 把 fs 层的失败翻译成状态码：FS_NOT_FOUND / ENOENT 当"不存在"，其它交给外层 500。
+ * @param {unknown} error 抛出的错误
+ * @returns {boolean} 是否属于"不存在"
+ */
+function isNotFound(error) {
+	const code = error !== null && typeof error === 'object' ? error.code : undefined
+	return code === 'FS_NOT_FOUND' || code === 'ENOENT'
+}
+
+/**
+ * 造一个下载 handler。
+ *
+ * deps 只为一件事存在：单测要数"到底有没有真去读文件"。生产路径不传，用 node:fs 的真身。
+ * @param {object} ctx 上下文（真实 ctx / inject 回调里的 scoped / {fs, sessions} 直给对象）
+ * @param {{createReadStream?: typeof createReadStream}} [deps] 可替换的底层流工厂
+ * @returns {(request: Request) => Promise<Response>} Fetch handler
+ */
+export function createDownloadHandler(ctx, deps = {}) {
+	const openStream = typeof deps.createReadStream === 'function' ? deps.createReadStream : createReadStream
+
+	return async function handleDownload(request) {
+		try {
+			const signal = request.signal
+			const params = new URL(request.url).searchParams
+			const sessionId = params.get('sessionId')
+			const requestedPath = params.get('path')
+
+			// —— 400：参数这一关先过，不合法就不碰文件系统 ——
+			if (sessionId === null || sessionId.length === 0) return errorResponse(400, 'missing sessionId')
+			if (requestedPath === null || requestedPath.length === 0) return errorResponse(400, 'missing path')
+			if (!isAbsolute(requestedPath)) return errorResponse(400, 'path must be absolute')
+			// 尾随分隔符是"目录写法"：按"没有这个文件"处理，别让它走到 stat 再变成 500。
+			if (/[\\/]$/.test(requestedPath)) return errorResponse(404, 'file not found')
+
+			const sessions = serviceOf(ctx, 'sessions')
+			if (sessions === undefined) return errorResponse(500, 'download unavailable: missing sessions service')
+
+			// —— 403：会话或它的 cwd 拿不到，就没有边界可谈 ——
+			const cwd = sessionWorkspace(sessions, sessionId)
+			if (cwd === null) return errorResponse(403, 'session cwd unavailable')
+
+			// —— 第一道：词法归一化（挡 .. 这类纯文本穿越） ——
+			const root = normalize(cwd)
+			const candidate = normalize(requestedPath)
+			if (!withinRoot(root, candidate)) return errorResponse(403, 'path outside session cwd')
+
+			const fs = serviceOf(ctx, 'fs')
+			if (typeof fs?.resolve !== 'function' || typeof fs?.stat !== 'function' || typeof fs?.processPath !== 'function') {
+				return errorResponse(500, 'download unavailable: missing fs service')
+			}
+
+			let target
+			let rootTarget
+			try {
+				target = await fs.resolve(candidate, { signal })
+				rootTarget = await fs.resolve(root, { signal })
+			} catch (error) {
+				if (isNotFound(error)) return errorResponse(404, 'file not found')
+				throw error
+			}
+
+			// —— 第二道：realpath 之后仍在范围内（挡符号链接逃逸） ——
+			// 双保险：既信后端的 processPath（本地后端本身就是 realpath 结果），
+			// 也自己 realpath 一次，后端换成非 realpath 的实现时这道闸照样有效。
+			const realRoot = String(fs.processPath(rootTarget))
+			const hostPath = String(fs.processPath(target))
+			const [realRootPath, realTargetPath] = await Promise.all([realPathOrSelf(realRoot), realPathOrSelf(hostPath)])
+			if (!withinRoot(realRootPath, realTargetPath)) return errorResponse(403, 'path outside session cwd after realpath')
+
+			let info
+			try {
+				info = await fs.stat(target, signal)
+			} catch (error) {
+				if (isNotFound(error) || error?.code === 'ENOTDIR' || error?.code === 'EISDIR') return errorResponse(404, 'file not found')
+				throw error
+			}
+			if (info === undefined) return errorResponse(404, 'file not found')
+			if (info.type !== 'file') return errorResponse(403, 'not a regular file')
+
+			const fileName = basename(candidate)
+			const headers = {
+				'content-type': contentTypeOf(fileName),
+				'content-disposition': contentDisposition(fileName),
+				'cache-control': 'private, no-store',
+			}
+			// 后端不保证给 size；缺了就不写 content-length（宁可不写，也不写一个假的 0）。
+			let declaredSize = 0
+			if (typeof info.size === 'number' && Number.isFinite(info.size) && info.size >= 0) {
+				declaredSize = info.size
+				headers['content-length'] = String(info.size)
+			}
+
+			// HEAD 只要头：同样的 status + headers，body 必须为空，且**不打开文件**。
+			if (request.method === 'HEAD') return new Response(null, { status: 200, headers })
+
+			const stream = openStream(realTargetPath)
+			// 打开后用同一个 fd 复核一次大小：stat 与 open 之间被换掉的极端情况，
+			// 宁可断流也不要发出一份长度对不上的响应。
+			stream.once('open', (fd) => {
+				if (declaredSize === 0) return
+				try {
+					fstat(fd, (error, stats) => {
+						if (error === null && stats !== undefined && stats.size !== declaredSize) stream.destroy(new Error('size changed while downloading'))
+					})
+				} catch { /* best effort */ }
+			})
+			stream.on('error', (error) => {
+				const code = error?.code ?? ''
+				// 客户端主动取消/连接被掐断是常态，不该刷日志。
+				if (code === 'ERR_STREAM_PREMATURE_CLOSE' || code === 'ECONNRESET' || code === 'EPIPE' || error?.name === 'AbortError') return
+				console.warn('[dsh-lookout] download stream failed:', code !== '' ? code : (error?.message ?? error))
+			})
+			return new Response(Readable.toWeb(stream), { status: 200, headers })
+		} catch (error) {
+			// 500 只说一句，不带堆栈：日志里也不要整段内部路径。
+			console.warn('[dsh-lookout] download route failed:', error?.message ?? error)
+			return errorResponse(500, 'download failed')
+		}
+	}
+}
+
+/**
+ * 把下载路由挂到 connection 上。
+ *
+ * 用 ctx.inject 局部等 connection/fs/sessions：缺任何一个就不注册，而不是让整个插件
+ * 卡在加载阶段（那正是不能把它们塞进顶层 inject 的原因）。
+ * @param {object} ctx 插件上下文
+ * @param {{createReadStream?: typeof createReadStream}} [deps] 仅单测使用
+ * @returns {void}
+ */
+const REGISTERED_CONNECTIONS = new WeakSet()
+
+export function registerDownloadRoute(ctx, deps = {}) {
+	const attach = (scoped) => {
+		const connection = serviceOf(scoped, 'connection')
+		if (typeof connection?.fetch?.register !== 'function') return
+		// 同一个 connection 只挂一次：宿主对重复路径会直接抛错，抛在 apply 里会带崩整个插件。
+		if (REGISTERED_CONNECTIONS.has(connection)) return
+		const route = {
+			path: DOWNLOAD_ROUTE_PATH,
+			methods: ['GET', 'HEAD'],
+			requestBody: 'buffered',
+			fetch: createDownloadHandler(scoped, deps),
+		}
+		const register = () => {
+			if (REGISTERED_CONNECTIONS.has(connection)) return
+			try {
+				const dispose = connection.fetch.register(route)
+				REGISTERED_CONNECTIONS.add(connection)
+				return dispose
+			} catch (error) {
+				// 已经被别人占了同名路径（或宿主换了校验）：记一条，不拖累插件加载。
+				console.warn('[dsh-lookout] download route not registered:', error?.code ?? error?.message ?? error)
+				return undefined
+			}
+		}
+		// 包一层 effect：插件卸载时路由跟着撤掉。
+		if (typeof scoped?.effect === 'function') scoped.effect(register, `dsh-lookout: ${DOWNLOAD_ROUTE_PATH}`)
+		else register()
+	}
+	if (typeof ctx?.inject === 'function') ctx.inject(['connection', 'fs', 'sessions'], attach)
+	else attach(ctx)
+}

package/lib/index.js

@@ -22,6 +22,7 @@ import { FaviconCustomService } from './icon/index.js'
 import { apply as applyNotify } from './notify/index.js'
 import { apply as applySessionInfo } from './session/index.js'
 import { MailSchema } from './notify/config.js'
+import { registerDownloadRoute } from './download.js'
 
 export const name = 'dsh-lookout'
 
@@ -68,4 +69,6 @@ export function apply(ctx, config) {
 	applyNotify(ctx, config)
 	// ③ C:宿主侧本来就是空实现。
 	applySessionInfo(ctx)
+	// ④ 宿主流式下载路由:自己 inject(connection/fs/sessions),缺服务就不挂,不动顶层 inject。
+	registerDownloadRoute(ctx)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cowwo/dsh-lookout",
   "description": "瞭望哨：盯着你的每个会话——谁跑完了、谁出错了、谁卡住了、谁在等你审批，用浏览器图标角标、红点/黄点和邮件通知你；顺带显示当前会话 ID。· Lookout: watches every session — who finished, who errored, who is stuck, and who is waiting for your approval — and notifies you through the browser favicon badge, red/yellow dots, and email, while also showing the current session ID.",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",