dsh-vscode-mode 0.25.0 → 0.25.1

package/README.md

@@ -274,7 +274,9 @@ cmaps 支持中文渲染）；工具条进入注释编辑：✎ 文本框 / 🖌
     （在集成终端中打开 / 运行测试 / Build 等）不显示。
   - **下载到本机**（仅远程访问时出现，落在「复制相对路径」与「重命名」之间）：
     文件直接下载原文件；文件夹与根空白区弹出确认框，按需懒加载展开目录树、
-    逐级勾选文件后逐个下载（不打包，勾选几个就下几个）。判定口径与页面的
+    逐级勾选文件后逐个下载（不打包，勾选几个就下几个）。点下载后先选保存文件夹
+    （Chrome/Edge 安全上下文下用目录选择器；Firefox/Safari 或非 https 回落浏览器
+    默认下载目录并提示），文件按工作区相对路径写入。判定口径与页面的
     远程通道一致（`channelPrefix()` 非空），本机回环页面不显示。
   - 文件管理写操作走 `edrv.fsCreateFile / fsCreateDir / fsRename / fsDelete /
     fsCopy / fsMove`（工作区边界 + 同名拒绝 + 名称校验），删除带确认；重命名 /
@@ -576,13 +578,13 @@ profile 请替换为实际目标，不要把示例目录当成当前运行 profi
 
 ```bash
 # ① Git 安装（clone + prepare 构建；推荐打固定 tag）
-dsh plugin --profile web add github:Lenonss/DSH_VsCodeMode#v0.25.0
+dsh plugin --profile web add github:Lenonss/DSH_VsCodeMode#v0.25.1
 
 # ② npm 注册表（发布到 npm 后）
-dsh plugin --profile web add dsh-vscode-mode@0.25.0
+dsh plugin --profile web add dsh-vscode-mode@0.25.1
 
 # ③ GitHub Release tgz 直装（Release asset 可用后）
-dsh plugin --profile web add https://github.com/Lenonss/DSH_VsCodeMode/releases/download/v0.25.0/dsh-vscode-mode-0.25.0.tgz
+dsh plugin --profile web add https://github.com/Lenonss/DSH_VsCodeMode/releases/download/v0.25.1/dsh-vscode-mode-0.25.1.tgz
 ```
 
 > **DSH 版本政策（0.17.0 起）**：六项 DSH peer 仍统一声明为 `*`，另以
@@ -962,6 +964,7 @@ Keep All / Undo All 却是亮的。修复：单文件 Keep / Undo 覆盖冲突
 
 | 版本 | 要点 |
 | --- | --- |
+| v0.25.1 | 下载到本机支持选择保存文件夹（目录选择器），按工作区相对路径写入 |
 | v0.25.0 | 资源管理器右键「下载到本机」：远程访问时把工作区文件拉回浏览器所在机器 |
 | v0.24.0 | 经第三方远程访问插件时，文件管理器与 Monaco 恢复可用；加载失败提示按状态区分 |
 | v0.23.5 | 同一文件不再算成两条差异；新建文件按整文件新增渲染 |
@@ -972,8 +975,9 @@ Keep All / Undo All 却是亮的。修复：单文件 Keep / Undo 覆盖冲突
 | v0.23.0 | 快捷菜单：可拖动悬浮按钮 + 自定义菜单树 |
 
 <details>
-<summary>完整版本记录（v0.25.0 → v0.1.5x，点击展开）</summary>
+<summary>完整版本记录（v0.25.1 → v0.1.5x，点击展开）</summary>
 
+- **v0.25.1**：下载到本机支持选择保存位置——点「下载」先弹系统目录选择器（File System Access API：Chrome/Edge、https 或 localhost 安全上下文），选一次目标文件夹后，文件按**工作区相对路径**逐个写入（文件夹下载自动建子目录，仍不打包）。用户取消选择则整批中止并提示「已取消下载」；Firefox/Safari、局域网 http、或目录写入权限被拒时自动回落浏览器默认下载目录，并分别提示具体原因，不静默改语义。确认框底栏按钮改为「选择位置并下载 N 个文件」并加一行说明；选择器在用户手势的同步栈内触发，不依赖额外点击。验证：typecheck 0 error；全量 288 文件、3733 通过 + 22 跳过；build 四 bundle 通过；本机冒烟覆盖 4 条分支（取消 / 拒绝授权回落 / 选中目录按 `tests/officialBackfill.test.ts` 相对路径写 4328 B / 文件夹流程写 `.codegraph/.gitignore` 229 B）。见 [0.25.1 发布说明](docs/release-0.25.1.md)。
 - **v0.25.0**：新增远程下载——经远程访问插件打开 DSH 时，工作区文件原本只能到远端机器上自己下载再传回，现在资源管理器右键菜单新增「下载到本机」（仅远程访问页可见，本机回环不出现）：文件右键直接下载原文件；文件夹与根空白区弹出确认框，按需懒加载展开目录树、逐级勾选文件后逐个下载原文件（不打包）。取字节复用既有链路（`edrv.readBinary` 二进制直出，远程代理剥掉 `x-edrv-*` 时自动回落 `edrv.read` 的 base64 分支），点选的文件名与远端一致，超过 32MB 的文件在弹窗内标明并禁用、不静默失败；确认框复用 `ModalShell`（自动满足 `data-edrv-view` 浮层契约与 z-index 阶梯），目录整行可展开、点文件名也能勾选、加载失败行带重试。可见性判据与 v0.24.0 的远程通道同源（`src/shared/remoteChannel.ts` 新增 `isRemoteChannel()`，即 `channelPrefix()` 非空），非远程页面完全不出现该条目、打开菜单也不发请求。不新增 host 路由、不改鉴权、不动既有导出实现。验证：typecheck 0 error；全量 287 文件、3715 通过 + 22 跳过；`node --test tests/nativeOpen.test.mjs` 9/9；build 四 bundle 通过；本机 GUI 注入远程座位后冒烟：菜单出现且位置正确、单文件下载落盘名正确、根/文件夹弹窗展开 105 行、单选 1 / 全选已展开 82 / 清空 0、勾选 2 个文件逐个下载成功（`edrv.readBinary` ×2），干净刷新后控制台无新增报错；**真实远程设备（真插件 + 真配对）未验收，缺口保留**。见 [0.25.0 发布说明](docs/release-0.25.0.md)。
 
 - **v0.24.0**：修复经第三方远程访问插件（如 `@linxin666/dsh-remote-web-ui`）访问 DSH Web GUI 时，文件管理器报「DSH 拒绝了当前页面的访问」、编辑器报「Monaco loader 加载失败」。根因在宿主准入顺序：`connection.requestRejection()` 先用 `isTrustedApiRequest` 判 Host/Origin，不属于回环、监听地址或 `trustedHosts` 就**直接 403**，根本不看登录态（401 才是认证失败），而本插件的 `/edrv/rpc` 与 `/edrv/vendor/**` 都不在远程插件的改写白名单里，于是 RPC、Monaco 的脚本/CSS/字体/Worker、pdf.js 模块 import 与角标图片全部直连宿主被拒。现按远程通道选路径前缀：`window.__DSH_REMOTE_CHANNEL_BOOT__` 存在（远程插件在 `<head>` 解析期安装的座位对象）时，所有插件内部路径改挂其已接管的 `/remote` catch-all（`/remote/edrv/...`），本地与桌面入口保持 `/edrv/...` 原样。新增 `src/shared/remoteChannel.ts`（`channelPrefix` / `transportPath` / `transportUrl`，仍经 `appUrl` 继承应用基址与 `dsh-app:`），RPC、二进制预览、Monaco 基址、pdf.js 基址与角标图片统一走它；**服务端零改动**，不新增路由、不取消鉴权、不读也不写任何凭据，`/remote` 门禁仍要求已配对设备。另新增 `src/client/loadFailure.ts`：加载失败先 HEAD 探测真实状态，403（Host 围栏）/401（登录失效）/404（资源或路由缺失）/0（请求未到达宿主）分别给不同提示，且只带 pathname 与状态码；设备未配对（403 `code:'unpaired'`）直接提示去配对，不再把所有 Monaco 失败都说成「检查资源是否完整」。验证：typecheck 0 error；全量 284 文件、3691 通过 + 22 跳过；`node --test tests/nativeOpen.test.mjs` 9/9；build 四 bundle 通过；本机 GUI 全链 200 并确认无 cookie 仍 401；远程通道用本地回环代理复刻转发语义后，138/138 请求落 `/remote/edrv/…`、目录/读/写/保存与 Monaco+Worker 全部通；**真机 + 真插件的配对门禁与 TLS 未验收（缺口保留）**。见 [0.24.0 发布说明](docs/release-0.24.0.md)。

package/lib/client.js

@@ -411139,6 +411139,107 @@ td.UniverTableCell, th.UniverTableCell{mso-padding-alt:0cm 5.4pt 0cm 5.4pt;}
 		function clearFileClip() {
 			clip = null;
 		}
+		//#endregion
+		//#region src/client/downloadSink.ts
+		/**
+		* 让用户选择保存目录。
+		* @author ddj 2026年11月03号
+		* @returns 所选目录 / 回落原因 / 'cancelled'（用户取消，整批终止）
+		* @sideEffects 弹出系统目录选择器，成功后可能触发一次写权限请求
+		*/
+		async function pickSaveSink() {
+			if (globalThis.isSecureContext === false) return {
+				kind: "browser",
+				reason: "insecure"
+			};
+			const picker = pickerOf();
+			if (!picker) return {
+				kind: "browser",
+				reason: "unsupported"
+			};
+			let dir;
+			try {
+				dir = await picker({
+					id: "vsm-download",
+					mode: "readwrite",
+					startIn: "downloads"
+				});
+			} catch (error) {
+				return isAbort(error) ? "cancelled" : {
+					kind: "browser",
+					reason: "denied"
+				};
+			}
+			return await ensureWritable(dir) ? {
+				kind: "dir",
+				dir
+			} : {
+				kind: "browser",
+				reason: "denied"
+			};
+		}
+		/**
+		* 取回 `showDirectoryPicker`（不安全上下文视为没有）。
+		* @author ddj 2026年11月03号
+		* @returns 绑定到 globalThis 的选目录函数；不可用为 undefined
+		*/
+		function pickerOf() {
+			const win = globalThis;
+			if (win.isSecureContext === false) return void 0;
+			return typeof win.showDirectoryPicker === "function" ? win.showDirectoryPicker.bind(win) : void 0;
+		}
+		/**
+		* 确认目录可写（部分浏览器选择后仍需显式请求一次 readwrite 权限）。
+		* @author ddj 2026年11月03号
+		* @param dir 目录句柄
+		* @returns 已获得写权限为 true
+		* @throws 权限查询本身抛错时向上透传（由调用方按回落处理）
+		*/
+		async function ensureWritable(dir) {
+			if (!dir.queryPermission) return true;
+			if (await dir.queryPermission({ mode: "readwrite" }) === "granted") return true;
+			if (!dir.requestPermission) return false;
+			return await dir.requestPermission({ mode: "readwrite" }) === "granted";
+		}
+		/**
+		* 把字节写到所选目录下的相对路径处（自动逐级建子目录）。
+		* @author ddj 2026年11月03号
+		* @param dir 目标目录句柄
+		* @param relPath 工作区相对路径（分隔符 `/`；越界段 `..` 会被丢弃）
+		* @param bytes 原始字节
+		* @sideEffects 在用户所选目录内创建目录与文件并覆盖同名文件
+		* @throws 磁盘写入失败或文件名非法时透传底层错误
+		*/
+		async function writeFileToDir(dir, relPath, bytes) {
+			const parts = pathSegments(relPath);
+			const fileName = parts.pop() ?? "download";
+			let parent = dir;
+			for (const part of parts) parent = await parent.getDirectoryHandle(part, { create: true });
+			const writable = await (await parent.getFileHandle(fileName, { create: true })).createWritable();
+			try {
+				await writable.write(bytes);
+			} finally {
+				await writable.close();
+			}
+		}
+		/**
+		* 相对路径切段（过滤空段、`.` 与越界 `..`，兼容反斜杠）。
+		* @author ddj 2026年11月03号
+		* @param relPath 工作区相对路径
+		* @returns 安全的路径段（末段为文件名）
+		*/
+		function pathSegments(relPath) {
+			return relPath.split(/[\\/]+/).map((part) => part.trim()).filter((part) => part !== "" && part !== "." && part !== "..");
+		}
+		/**
+		* 判断是否用户取消（AbortError），不依赖 DOMException 构造函数的存在。
+		* @author ddj 2026年11月03号
+		* @param error 捕获值
+		* @returns 取消为 true
+		*/
+		function isAbort(error) {
+			return typeof error === "object" && error !== null && error.name === "AbortError";
+		}
 		/**
 		* 初始状态：根目录默认展开，等待首层 listDir 填充。
 		* @author ddj 2026年11月03号
@@ -411513,7 +411614,7 @@ td.UniverTableCell, th.UniverTableCell{mso-padding-alt:0cm 5.4pt 0cm 5.4pt;}
 				dialogClass: "edrv-dl-dialog",
 				width: "min(640px, calc(100vw - 40px))",
 				onClose
-			}, react$1.default.createElement("h3", null, "下载到本机"), react$1.default.createElement("div", { className: "edrv-dl-sub" }, root ? "/" + root : "工作区根目录"), renderTree({
+			}, react$1.default.createElement("h3", null, "下载到本机"), react$1.default.createElement("div", { className: "edrv-dl-sub" }, root ? "/" + root : "工作区根目录"), react$1.default.createElement("div", { className: "edrv-dl-hint" }, "点下载后会先选择保存文件夹，文件按相对路径写入"), renderTree({
 				state,
 				root,
 				rows,
@@ -411565,7 +411666,7 @@ td.UniverTableCell, th.UniverTableCell{mso-padding-alt:0cm 5.4pt 0cm 5.4pt;}
 				className: "edrv-dl-go",
 				disabled: !picked.length,
 				onClick: () => onConfirm(picked)
-			}, "下载 " + picked.length + " 个文件"));
+			}, "选择位置并下载 " + picked.length + " 个文件"));
 		}
 		/**
 		* 目录行：三角展开 / 收起，名称后带加载或错误提示。
@@ -411723,16 +411824,17 @@ td.UniverTableCell, th.UniverTableCell{mso-padding-alt:0cm 5.4pt 0cm 5.4pt;}
 			};
 		}
 		/**
-		* 下载单个文件并交给浏览器落盘。
+		* 下载单个文件并落盘（所选目录则按相对路径写入，否则交给浏览器 `<a download>`）。
 		* @author ddj 2026年11月03号
 		* @param path 工作区相对路径
-		* @param opts 会话 / 取消选项
+		* @param opts 会话 / 取消 / 落盘选项
 		* @returns 路径与字节数
-		* @throws 读取失败透传主机错误
+		* @throws 读取失败透传主机错误；目录写入失败透传底层错误
 		*/
 		async function downloadOne(path, opts = {}) {
 			const file = await fetchDownload(path, opts.sessionId);
-			downloadBytes(file.bytes, baseNameOf$1(path) || "download", file.mime);
+			if (opts.sink?.kind === "dir") await writeFileToDir(opts.sink.dir, path, file.bytes);
+			else downloadBytes(file.bytes, baseNameOf$1(path) || "download", file.mime);
 			return {
 				path,
 				size: file.size
@@ -411787,22 +411889,43 @@ td.UniverTableCell, th.UniverTableCell{mso-padding-alt:0cm 5.4pt 0cm 5.4pt;}
 			});
 		}
 		/**
-		* 批量下载并统一反馈（开始一条、结束一条，避免逐文件刷屏）。
+		* 批量下载并统一反馈（先选保存目录，再逐文件落盘；开始一条、结束一条，避免逐文件刷屏）。
 		* @author ddj 2026年11月03号
 		* @param paths 勾选路径
 		* @param ctx 面板上下文
+		* @sideEffects 弹出目录选择器；用户取消则整批中止
 		*/
 		async function runBatch(paths, ctx) {
 			if (!paths.length) return;
+			const sink = await pickSaveSink();
+			if (sink === "cancelled") {
+				ctx?.notify?.("已取消下载");
+				return;
+			}
+			if (sink.kind === "browser") ctx?.notify?.(fallbackText(sink.reason));
 			if (paths.length > 1) ctx?.notify?.("正在下载 " + paths.length + " 个文件…");
 			try {
-				const out = await downloadMany(paths, { sessionId: ctx?.sessionId });
+				const out = await downloadMany(paths, {
+					sessionId: ctx?.sessionId,
+					sink
+				});
 				ctx?.notify?.(batchText(out));
 			} catch (error) {
 				ctx?.notify?.("下载失败：" + textOfError(error));
 			}
 		}
 		/**
+		* 目录选择不可用时的提示文案（说明文件去了浏览器默认下载目录）。
+		* @author ddj 2026年11月03号
+		* @param reason 回落原因
+		* @returns 单行提示文案
+		*/
+		function fallbackText(reason) {
+			if (reason === "unsupported") return "浏览器不支持选择保存目录，已保存到默认下载目录";
+			if (reason === "insecure") return "当前页面不是安全上下文（需 https 或 localhost），已保存到默认下载目录";
+			return "未获得目录写入权限，已保存到默认下载目录";
+		}
+		/**
 		* 批量结果口播文案。
 		* @author ddj 2026年11月03号
 		* @param out 批量结果

package/lib/client.js.map

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/lib/client.js.map
-size: 35747807 bytes
-sha256: 00397bc527477797630d5f114826604a5a5c212d3a8c79fe87a95140beb0b254
+size: 35757528 bytes
+sha256: 0d31913373f82b945772a46dce1f7840a2e71d3cf643543434c05dfef727fd81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ SVN 集成（侧栏变更面板/日志弹窗/并排差异）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车，界面状态（页签/光标/侧栏/编辑 Tab/导航历史）镜像到 DSH home 跨重启恢复",
   "icon": "assets/icon.svg",
   "keywords": [

package/src/client/downloadFile.ts

@@ -16,6 +16,8 @@
 import { readBinaryPreview } from '../shared/rpc.js'
 import { baseNameOf } from '../shared/fsNames.js'
 import { rpc } from './rpc.js'
+import type { SaveFallback, SaveSink } from './downloadSink.js'
+import { pickSaveSink, writeFileToDir } from './downloadSink.js'
 import type { TreeMenuTarget } from './sidebar/contextMenu.js'
 import type { SidebarCtx } from './sidebar/types.js'
 import { openDownloader } from './ui/DownloadPicker.js'
@@ -41,6 +43,8 @@ export interface DownloadOpts {
   signal?: AbortSignal
   /** 每完成一个文件回调一次（done 含成功与失败）。 */
   onProgress?: (done: number, total: number, path: string) => void
+  /** 落盘去处；缺省按浏览器默认下载目录（`<a download>`）。 */
+  sink?: SaveSink
 }
 
 // --endregion
@@ -85,16 +89,20 @@ export async function fetchDownload(path: string, sessionId?: string): Promise<{
 }
 
 /**
- * 下载单个文件并交给浏览器落盘。
+ * 下载单个文件并落盘（所选目录则按相对路径写入，否则交给浏览器 `<a download>`）。
  * @author ddj 2026年11月03号
  * @param path 工作区相对路径
- * @param opts 会话 / 取消选项
+ * @param opts 会话 / 取消 / 落盘选项
  * @returns 路径与字节数
- * @throws 读取失败透传主机错误
+ * @throws 读取失败透传主机错误；目录写入失败透传底层错误
  */
 export async function downloadOne(path: string, opts: DownloadOpts = {}): Promise<DownloadedFile> {
   const file = await fetchDownload(path, opts.sessionId)
-  downloadBytes(file.bytes, baseNameOf(path) || 'download', file.mime)
+  if (opts.sink?.kind === 'dir') {
+    await writeFileToDir(opts.sink.dir, path, file.bytes)
+  } else {
+    downloadBytes(file.bytes, baseNameOf(path) || 'download', file.mime)
+  }
   return { path, size: file.size }
 }
 
@@ -148,22 +156,44 @@ export async function downloadTarget(target: TreeMenuTarget, ctx?: SidebarCtx):
 }
 
 /**
- * 批量下载并统一反馈（开始一条、结束一条，避免逐文件刷屏）。
+ * 批量下载并统一反馈（先选保存目录，再逐文件落盘；开始一条、结束一条，避免逐文件刷屏）。
  * @author ddj 2026年11月03号
  * @param paths 勾选路径
  * @param ctx 面板上下文
+ * @sideEffects 弹出目录选择器；用户取消则整批中止
  */
 async function runBatch(paths: string[], ctx?: SidebarCtx): Promise<void> {
   if (!paths.length) return
+
+  // 选择器必须在用户手势的同步栈里触发，故放在第一个 await 之前。
+  const sink = await pickSaveSink()
+  if (sink === 'cancelled') {
+    ctx?.notify?.('已取消下载')
+    return
+  }
+  if (sink.kind === 'browser') ctx?.notify?.(fallbackText(sink.reason))
   if (paths.length > 1) ctx?.notify?.('正在下载 ' + paths.length + ' 个文件…')
+
   try {
-    const out = await downloadMany(paths, { sessionId: ctx?.sessionId })
+    const out = await downloadMany(paths, { sessionId: ctx?.sessionId, sink })
     ctx?.notify?.(batchText(out))
   } catch (error) {
     ctx?.notify?.('下载失败：' + textOfError(error))
   }
 }
 
+/**
+ * 目录选择不可用时的提示文案（说明文件去了浏览器默认下载目录）。
+ * @author ddj 2026年11月03号
+ * @param reason 回落原因
+ * @returns 单行提示文案
+ */
+function fallbackText(reason: SaveFallback): string {
+  if (reason === 'unsupported') return '浏览器不支持选择保存目录，已保存到默认下载目录'
+  if (reason === 'insecure') return '当前页面不是安全上下文（需 https 或 localhost），已保存到默认下载目录'
+  return '未获得目录写入权限，已保存到默认下载目录'
+}
+
 /**
  * 批量结果口播文案。
  * @author ddj 2026年11月03号

package/src/client/downloadSink.ts

@@ -0,0 +1,162 @@
+/**
+ * dsh-vscode-mode client — 下载落盘位置（目录选择器）。
+ *
+ * 浏览器原生 `<a download>` 由浏览器决定保存位置，页面拿不到路径；本模块用
+ * File System Access API 的 `showDirectoryPicker` 让用户在点「下载」时选一次目标文件夹，
+ * 之后把文件按工作区相对路径逐个写进去（文件夹下载自动建子目录，仍不打包）。
+ *
+ * 约束：
+ * - 选择器必须在用户手势的同步栈里调用，故入口函数都把 `pickSaveSink()` 放在第一个 await；
+ * - 需要安全上下文（https / localhost）与 Chromium 系浏览器，Firefox / Safari / 局域网 http
+ *   一律回落到浏览器默认下载目录，并在界面上说明原因，不静默改语义；
+ * - 用户取消选择（AbortError）与「不可用」区分开：前者终止整批，后者继续下载。
+ * 作者 ddj 2026年11月03号
+ */
+
+// --region 类型
+
+/** 落盘去处：写入用户所选目录，或回落到浏览器默认下载目录。 */
+export type SaveSink =
+  | { kind: 'dir'; dir: SinkDir }
+  | { kind: 'browser'; reason: SaveFallback }
+
+/** 回落到浏览器下载的原因（调用方据此给出提示文案）。 */
+export type SaveFallback = 'unsupported' | 'insecure' | 'denied'
+
+/** 可写文件的句柄（File System Access API 的子集）。 */
+export interface SinkWritable {
+  write(data: Uint8Array): Promise<void>
+  close(): Promise<void>
+}
+
+/** 文件句柄（仅用到创建可写流）。 */
+export interface SinkFileHandle {
+  createWritable(): Promise<SinkWritable>
+}
+
+/** 目录句柄（仅用到列目录与建子目录/文件）。 */
+export interface SinkDir {
+  name: string
+  getDirectoryHandle(name: string, opts?: { create?: boolean }): Promise<SinkDir>
+  getFileHandle(name: string, opts?: { create?: boolean }): Promise<SinkFileHandle>
+  queryPermission?(opts: { mode: 'readwrite' }): Promise<string>
+  requestPermission?(opts: { mode: 'readwrite' }): Promise<string>
+}
+
+/** `window.showDirectoryPicker` 的最小签名。 */
+type DirPicker = (opts?: { id?: string; mode?: string; startIn?: string }) => Promise<SinkDir>
+
+// --endregion
+
+// --region 选择器
+
+/**
+ * 当前浏览器/上下文是否可能弹出目录选择器（安全上下文 + API 存在）。
+ * @author ddj 2026年11月03号
+ * @returns 可用为 true；不安全上下文或缺 API 为 false
+ */
+export function canPickDirectory(): boolean {
+  return pickerOf() !== undefined
+}
+
+/**
+ * 让用户选择保存目录。
+ * @author ddj 2026年11月03号
+ * @returns 所选目录 / 回落原因 / 'cancelled'（用户取消，整批终止）
+ * @sideEffects 弹出系统目录选择器，成功后可能触发一次写权限请求
+ */
+export async function pickSaveSink(): Promise<SaveSink | 'cancelled'> {
+  const win = globalThis as { isSecureContext?: boolean; showDirectoryPicker?: DirPicker }
+  if (win.isSecureContext === false) return { kind: 'browser', reason: 'insecure' }
+
+  const picker = pickerOf()
+  if (!picker) return { kind: 'browser', reason: 'unsupported' }
+
+  let dir: SinkDir
+  try {
+    dir = await picker({ id: 'vsm-download', mode: 'readwrite', startIn: 'downloads' })
+  } catch (error) {
+    return isAbort(error) ? 'cancelled' : { kind: 'browser', reason: 'denied' }
+  }
+
+  return (await ensureWritable(dir)) ? { kind: 'dir', dir } : { kind: 'browser', reason: 'denied' }
+}
+
+/**
+ * 取回 `showDirectoryPicker`（不安全上下文视为没有）。
+ * @author ddj 2026年11月03号
+ * @returns 绑定到 globalThis 的选目录函数；不可用为 undefined
+ */
+function pickerOf(): DirPicker | undefined {
+  const win = globalThis as { isSecureContext?: boolean; showDirectoryPicker?: DirPicker }
+  if (win.isSecureContext === false) return undefined
+  return typeof win.showDirectoryPicker === 'function' ? win.showDirectoryPicker.bind(win) : undefined
+}
+
+/**
+ * 确认目录可写（部分浏览器选择后仍需显式请求一次 readwrite 权限）。
+ * @author ddj 2026年11月03号
+ * @param dir 目录句柄
+ * @returns 已获得写权限为 true
+ * @throws 权限查询本身抛错时向上透传（由调用方按回落处理）
+ */
+async function ensureWritable(dir: SinkDir): Promise<boolean> {
+  if (!dir.queryPermission) return true
+  if ((await dir.queryPermission({ mode: 'readwrite' })) === 'granted') return true
+  if (!dir.requestPermission) return false
+  return (await dir.requestPermission({ mode: 'readwrite' })) === 'granted'
+}
+
+// --endregion
+
+// --region 写入
+
+/**
+ * 把字节写到所选目录下的相对路径处（自动逐级建子目录）。
+ * @author ddj 2026年11月03号
+ * @param dir 目标目录句柄
+ * @param relPath 工作区相对路径（分隔符 `/`；越界段 `..` 会被丢弃）
+ * @param bytes 原始字节
+ * @sideEffects 在用户所选目录内创建目录与文件并覆盖同名文件
+ * @throws 磁盘写入失败或文件名非法时透传底层错误
+ */
+export async function writeFileToDir(dir: SinkDir, relPath: string, bytes: Uint8Array): Promise<void> {
+  const parts = pathSegments(relPath)
+  const fileName = parts.pop() ?? 'download'
+
+  let parent = dir
+  for (const part of parts) parent = await parent.getDirectoryHandle(part, { create: true })
+
+  const handle = await parent.getFileHandle(fileName, { create: true })
+  const writable = await handle.createWritable()
+  try {
+    await writable.write(bytes)
+  } finally {
+    await writable.close()
+  }
+}
+
+/**
+ * 相对路径切段（过滤空段、`.` 与越界 `..`，兼容反斜杠）。
+ * @author ddj 2026年11月03号
+ * @param relPath 工作区相对路径
+ * @returns 安全的路径段（末段为文件名）
+ */
+function pathSegments(relPath: string): string[] {
+  return relPath
+    .split(/[\\/]+/)
+    .map((part) => part.trim())
+    .filter((part) => part !== '' && part !== '.' && part !== '..')
+}
+
+/**
+ * 判断是否用户取消（AbortError），不依赖 DOMException 构造函数的存在。
+ * @author ddj 2026年11月03号
+ * @param error 捕获值
+ * @returns 取消为 true
+ */
+function isAbort(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && (error as { name?: string }).name === 'AbortError'
+}
+
+// --endregion

package/src/client/ui/DownloadPicker.ts

@@ -114,6 +114,7 @@ export function DownloadPicker(props: DownloadPickerProps): React.ReactElement {
   },
     React.createElement('h3', null, '下载到本机'),
     React.createElement('div', { className: 'edrv-dl-sub' }, root ? '/' + root : '工作区根目录'),
+    React.createElement('div', { className: 'edrv-dl-hint' }, '点下载后会先选择保存文件夹，文件按相对路径写入'),
     renderTree({ state, root, rows, empty, loadDir, renderRow, onToggleDir, onToggleFile }),
     renderFoot({
       picked,
@@ -182,7 +183,7 @@ function renderFoot(opts: FootOpts): React.ReactElement {
       className: 'edrv-dl-go',
       disabled: !picked.length,
       onClick: () => onConfirm(picked),
-    }, '下载 ' + picked.length + ' 个文件'),
+    }, '选择位置并下载 ' + picked.length + ' 个文件'),
   )
 }