dsh-vscode-mode 0.24.0 → 0.25.1

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/sidebar/menuItems.ts

@@ -23,6 +23,8 @@ import { rpc } from '../rpc.js'
 import { absoluteOf, relativeOf } from '../tabActions.js'
 import { copyText } from '../copyText.js'
 import { clearFileClip, fileClipOf, setFileClip } from '../fileClipboard.js'
+import { downloadTarget } from '../downloadFile.js'
+import { isRemoteChannel } from '../../shared/remoteChannel.js'
 import type { TreeMenuItem } from './contextMenu.js'
 import type { SidebarCtx } from './types.js'
 import type { TreeMenuTarget } from './contextMenu.js'
@@ -39,6 +41,8 @@ const ORDER_COPY = 80
 const ORDER_PASTE = 90
 const ORDER_COPY_PATH = 110
 const ORDER_COPY_REL = 120
+/** 远程下载（仅远程访问可见）落在复制路径段之后、重命名段之前，不新起视觉块。 */
+const ORDER_DOWNLOAD = 125
 const ORDER_RENAME = 140
 const ORDER_DELETE = 150
 const SVN_ORDER_BASE = 200
@@ -454,6 +458,28 @@ function editGroupItems(): TreeMenuItem[] {
 
 // --endregion
 
+// --region 远程下载（仅远程访问可见）
+
+/**
+ * 「下载到本机」菜单项：远程访问时把工作区文件拉回浏览器所在机器。
+ * 可见性唯一判据是通道 seat（{@link isRemoteChannel}）——本机回环页面完全看不到该项，
+ * 也不因打开菜单发出任何请求；文件目标直下，文件夹 / 根空白区弹勾选弹窗。
+ * @author ddj 2026年11月03号
+ * @returns 菜单项数组（固定 1 项，显隐交给 visible）
+ */
+function downloadItems(): TreeMenuItem[] {
+  return [{
+    id: 'remote-download',
+    label: (target) => (target.type === 'file' ? '下载到本机' : '下载到本机…'),
+    order: ORDER_DOWNLOAD,
+    group: GROUP_COPY_PATH,
+    visible: () => isRemoteChannel(),
+    run: (target, ctx) => { void downloadTarget(target, ctx) },
+  }]
+}
+
+// --endregion
+
 // --region SVN 组（动作清单来自 shared/svnActions.ts）
 
 /** 目标路径对应的变更条目（不在清单里返回 undefined）。 */
@@ -559,6 +585,7 @@ export function createDefaultFileMenuItems(): TreeMenuItem[] {
     ...refGroupItems(),
     ...clipGroupItems(),
     ...copyPathItems(),
+    ...downloadItems(),
     ...editGroupItems(),
     ...svnMenuItems(),
   ]

package/src/client/styles/editor.css

@@ -899,6 +899,30 @@
 
 
 
+/* 远程下载确认框（仅远程访问时由资源管理器右键打开）：懒加载目录树 + 文件勾选。
+   卡片与遮罩由 ModalShell 提供（vsm-mcp-dialog / edrv-modal-mask，z-index 190），
+   此处只补树列表与底栏布局。⚠️ 规则一律以 [data-edrv-view] 开头，否则整块失配。 */
+[data-edrv-view] .edrv-dl-dialog { display: flex; flex-direction: column; gap: 10px; }
+[data-edrv-view] .edrv-dl-sub { margin: -6px 0 2px; font-size: 12px; color: var(--dsw-alias-label-tertiary, #9aa5b1); word-break: break-all; }
+[data-edrv-view] .edrv-dl-tree { display: flex; flex-direction: column; gap: 1px; min-height: 120px; max-height: min(48vh, 420px); overflow: auto; padding: 4px; border: 1px solid var(--dsw-alias-border-l1, #3a3a3a); border-radius: 8px; background: var(--dsw-alias-bg-layer-1, #262626); }
+[data-edrv-view] .edrv-dl-row { display: flex; align-items: center; gap: 6px; min-height: 26px; padding: 2px 6px; border-radius: 6px; font-size: 13px; color: var(--dsw-alias-label-primary, #e6e6e6); }
+[data-edrv-view] .edrv-dl-row:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255, 255, 255, .06)); }
+[data-edrv-view] .edrv-dl-row.is-dir { cursor: pointer; }
+[data-edrv-view] .edrv-dl-twist { flex: 0 0 auto; width: 18px; height: 18px; color: var(--dsw-alias-label-secondary, #aaa); font-size: 11px; line-height: 18px; text-align: center; }
+[data-edrv-view] .edrv-dl-name { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; cursor: pointer; }
+[data-edrv-view] .edrv-dl-dir { font-weight: 600; }
+[data-edrv-view] .edrv-dl-size { flex: 0 0 auto; font-size: 11px; color: var(--dsw-alias-label-tertiary, #9aa5b1); }
+[data-edrv-view] .edrv-dl-size.is-large { color: var(--dsw-alias-state-warn-primary, #e5b93f); }
+[data-edrv-view] .edrv-dl-hint { padding: 3px 8px; font-size: 11px; color: var(--dsw-alias-label-tertiary, #9aa5b1); }
+[data-edrv-view] .edrv-dl-hint.is-error { display: flex; align-items: center; gap: 8px; color: var(--dsw-alias-state-error-primary, #f07878); }
+[data-edrv-view] .edrv-dl-hint button { padding: 2px 8px; border: 1px solid var(--dsw-alias-border-l2, #555); border-radius: 5px; background: none; color: var(--dsw-alias-label-primary, #eee); font-size: 11px; cursor: pointer; }
+[data-edrv-view] .edrv-dl-foot { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+[data-edrv-view] .edrv-dl-count { margin-right: auto; font-size: 12px; color: var(--dsw-alias-label-secondary, #aaa); }
+[data-edrv-view] .edrv-dl-foot button { padding: 6px 12px; border: 1px solid var(--dsw-alias-border-l2, #555); border-radius: 6px; background: none; color: var(--dsw-alias-label-primary, #eee); font-size: 12px; cursor: pointer; }
+[data-edrv-view] .edrv-dl-foot button:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover, rgba(255, 255, 255, .06)); }
+[data-edrv-view] .edrv-dl-foot button:disabled { opacity: .55; cursor: default; }
+[data-edrv-view] .edrv-dl-go { border-color: var(--dsw-alias-brand-primary, #6d55ff); }
+
 /* 调试（DAP）：断点圆点 / 停帧行 / 浮动调试工具条。
    圆点挂在 Monaco glyphMargin（glyphMarginClassName），行背景为 isWholeLine className；
    工具条绝对定位于编辑区右上（editorArea relative 由 .edrv-editor-area 自身定位）。 */

package/src/client/ui/DownloadPicker.ts

@@ -0,0 +1,306 @@
+/**
+ * dsh-vscode-mode client — 「下载到本机」确认框（仅远程访问时由右键菜单打开）。
+ *
+ * 形态：ModalShell 居中卡片 + 懒加载目录树 + 文件勾选。产品决策是「不打包」：
+ * 这里只收集勾选，由调用方（downloadFile.ts）逐个下载原文件。
+ *
+ * 目录节点只负责展开、不带勾选框：勾选粒度是文件，避免半选目录的语义歧义；
+ * 「全选」只覆盖已展开（已加载）的文件，不会为了全选把整棵树拉一遍。
+ * 样式见 editor.css 的 `[data-edrv-view] .edrv-dl-*`；本组件不新建 portal，
+ * 因此自动满足 tests/overlayScope.test.ts 的 data-edrv-view 契约。
+ * 作者 ddj 2026年11月03号
+ */
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import { rpc } from '../rpc.js'
+import type { TreeEntry } from '../../shared/rpc.js'
+import { ModalShell } from './ModalShell.js'
+import {
+  clearSelected, collapseDir, createDlState, expandDir, formatSize, hasLoaded, isOversized, markError, markLoading,
+  mergeChildren, rowList, selectLoaded, selectedFiles, toggleFile,
+} from '../downloadPickerModel.js'
+import type { DlRow, DlState } from '../downloadPickerModel.js'
+
+/** 弹窗属性：只做「选文件」这件事，下载编排由调用方负责。 */
+export interface DownloadPickerProps {
+  /** 弹窗根：工作区相对路径；'' = 整个工作区。 */
+  root: string
+  /** 会话 id（工作区解析用）。 */
+  sessionId?: string
+  /** 取消（Esc / 遮罩 / 取消按钮）。 */
+  onClose: () => void
+  /** 确认：传勾选的文件路径（至少 1 个）。 */
+  onConfirm: (paths: string[]) => void
+}
+
+/**
+ * 「下载到本机」确认框。
+ * @author ddj 2026年11月03号
+ * @param props 弹窗属性
+ * @returns 弹窗元素
+ */
+export function DownloadPicker(props: DownloadPickerProps): React.ReactElement {
+  const { root, sessionId, onClose, onConfirm } = props
+  const [state, setState] = React.useState<DlState>(() => createDlState(root))
+  const aliveRef = React.useRef(true)
+
+  React.useEffect(() => () => { aliveRef.current = false }, [])
+
+  /**
+   * 拉取某目录一层子项（懒加载的唯一入口）。
+   * @author ddj 2026年11月03号
+   * @param dirPath 目录路径（'' = 工作区根）
+   */
+  const loadDir = React.useCallback(async (dirPath: string): Promise<void> => {
+    setState((prev) => markLoading(prev, dirPath))
+    try {
+      const args = sessionId ? { sessionId, path: dirPath } : { path: dirPath }
+      const out = await rpc('edrv.listDir', args)
+      if (!aliveRef.current) return
+      if (!out.ok) {
+        setState((prev) => markError(prev, dirPath, out.error))
+        return
+      }
+      setState((prev) => mergeChildren(prev, dirPath, out.entries))
+    } catch (error) {
+      if (!aliveRef.current) return
+      setState((prev) => markError(prev, dirPath, textOfError(error)))
+    }
+  }, [sessionId])
+
+  React.useEffect(() => { void loadDir(root) }, [loadDir, root])
+
+  /**
+   * 展开 / 收起目录；首次展开才发 listDir。
+   * @author ddj 2026年11月03号
+   * @param path 目录路径
+   */
+  function onToggleDir(path: string): void {
+    const expanded = state.expanded.has(path)
+    setState((prev) => (expanded ? collapseDir(prev, path) : expandDir(prev, path)))
+    if (expanded || hasLoaded(state, path) || state.loading.has(path)) return
+    void loadDir(path)
+  }
+
+  /**
+   * 勾选 / 取消勾选单个文件。
+   * @author ddj 2026年11月03号
+   * @param path 文件路径
+   */
+  function onToggleFile(path: string): void {
+    setState((prev) => toggleFile(prev, path))
+  }
+
+  const rows = rowList(state)
+  const picked = selectedFiles(state)
+  const empty = hasLoaded(state, root) && rows.length === 0 && !state.loading.has(root)
+
+  /**
+   * 单行渲染（目录出三角、文件出勾选框；超限文件置灰不可勾）。
+   * @author ddj 2026年11月03号
+   * @param row 行数据
+   * @returns 行元素
+   */
+  function renderRow(row: DlRow): React.ReactElement {
+    const indent = { paddingLeft: 6 + row.depth * 14 }
+    if (row.kind === 'directory') return renderDirRow(row, indent, onToggleDir, loadDir)
+    return renderFileRow(row, indent, onToggleFile)
+  }
+
+  return React.createElement(ModalShell, {
+    dialogClass: 'edrv-dl-dialog',
+    width: 'min(640px, calc(100vw - 40px))',
+    onClose,
+  },
+    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,
+      rows,
+      onSelectAll: () => setState(selectLoaded),
+      onClear: () => setState(clearSelected),
+      onClose,
+      onConfirm,
+    }),
+  )
+}
+
+/** 目录树区域属性（全部由组件传入，渲染函数本身不持有状态）。 */
+interface TreeOpts {
+  state: DlState
+  root: string
+  rows: DlRow[]
+  empty: boolean
+  loadDir: (dirPath: string) => Promise<void>
+  renderRow: (row: DlRow) => React.ReactElement
+  onToggleDir: (path: string) => void
+  onToggleFile: (path: string) => void
+}
+
+/**
+ * 目录树区域：行列表 + 根加载态 + 根错误重试 + 空态。
+ * @author ddj 2026年11月03号
+ * @param opts 树区域属性
+ * @returns 树区域元素
+ */
+function renderTree(opts: TreeOpts): React.ReactElement {
+  const { state, root, rows, empty, loadDir, renderRow } = opts
+  return React.createElement('div', { className: 'edrv-dl-tree' },
+    rows.length ? rows.map(renderRow) : null,
+    state.loading.has(root) ? React.createElement('div', { className: 'edrv-dl-hint' }, '加载中…') : null,
+    state.errors.has(root) ? renderRetry(root, state.errors.get(root) || '', loadDir) : null,
+    empty ? React.createElement('div', { className: 'edrv-dl-hint' }, '此文件夹内没有可下载的文件') : null,
+  )
+}
+
+/** 底栏属性：已选数量、批量勾选动作与确认/取消回调。 */
+interface FootOpts {
+  picked: string[]
+  rows: DlRow[]
+  onSelectAll: () => void
+  onClear: () => void
+  onClose: () => void
+  onConfirm: (paths: string[]) => void
+}
+
+/**
+ * 底栏：已选数量 + 全选已展开 / 清空 / 取消 / 下载。
+ * @author ddj 2026年11月03号
+ * @param opts 底栏属性
+ * @returns 底栏元素
+ */
+function renderFoot(opts: FootOpts): React.ReactElement {
+  const { picked, rows, onSelectAll, onClear, onClose, onConfirm } = opts
+  return React.createElement('div', { className: 'edrv-dl-foot' },
+    React.createElement('span', { className: 'edrv-dl-count' }, '已选 ' + picked.length + ' 个文件'),
+    React.createElement('button', { type: 'button', disabled: !rows.length, onClick: onSelectAll }, '全选已展开'),
+    React.createElement('button', { type: 'button', disabled: !picked.length, onClick: onClear }, '清空'),
+    React.createElement('button', { type: 'button', onClick: onClose }, '取消'),
+    React.createElement('button', {
+      type: 'button',
+      className: 'edrv-dl-go',
+      disabled: !picked.length,
+      onClick: () => onConfirm(picked),
+    }, '选择位置并下载 ' + picked.length + ' 个文件'),
+  )
+}
+
+/**
+ * 目录行：三角展开 / 收起，名称后带加载或错误提示。
+ * @author ddj 2026年11月03号
+ * @param row 行数据
+ * @param indent 缩进样式
+ * @param onToggle 展开回调
+ * @param retry 重试加载回调
+ * @returns 目录行元素
+ */
+function renderDirRow(
+  row: DlRow,
+  indent: React.CSSProperties,
+  onToggle: (path: string) => void,
+  retry: (path: string) => Promise<void>,
+): React.ReactElement {
+  // 整行可点（三角与名称都展开），避免只有三角能点导致误以为无子项
+  return React.createElement('div', {
+    key: row.path,
+    className: 'edrv-dl-row is-dir',
+    style: indent,
+    onClick: () => onToggle(row.path),
+  },
+    React.createElement('span', { className: 'edrv-dl-twist' }, row.expanded ? '▾' : '▸'),
+    React.createElement('span', { className: 'edrv-dl-name edrv-dl-dir' }, row.name),
+    row.loading ? React.createElement('span', { className: 'edrv-dl-hint' }, '加载中…') : null,
+    row.error ? renderRetry(row.path, row.error, retry) : null,
+  )
+}
+
+/**
+ * 文件行：勾选框 + 名称 + 体积；超限文件禁用勾选并标注原因。
+ * @author ddj 2026年11月03号
+ * @param row 行数据
+ * @param indent 缩进样式
+ * @param onToggle 勾选回调
+ * @returns 文件行元素
+ */
+function renderFileRow(
+  row: DlRow,
+  indent: React.CSSProperties,
+  onToggle: (path: string) => void,
+): React.ReactElement {
+  const oversized = isOversized(row.size)
+  return React.createElement('div', { key: row.path, className: 'edrv-dl-row', style: indent },
+    React.createElement('input', {
+      type: 'checkbox',
+      checked: row.checked,
+      disabled: oversized,
+      onChange: () => onToggle(row.path),
+    }),
+    React.createElement('span', { className: 'edrv-dl-name', onClick: () => onToggle(row.path) }, row.name),
+    oversized
+      ? React.createElement('span', { className: 'edrv-dl-size is-large' }, '超过 32MB')
+      : (typeof row.size === 'number' ? React.createElement('span', { className: 'edrv-dl-size' }, formatSize(row.size)) : null),
+  )
+}
+
+/**
+ * 错误行 + 重试按钮（保留主机错误原文）。
+ * @author ddj 2026年11月03号
+ * @param path 目录路径
+ * @param message 错误原文
+ * @param retry 重试回调
+ * @returns 提示行元素
+ */
+function renderRetry(path: string, message: string, retry: (path: string) => Promise<void>): React.ReactElement {
+  return React.createElement('div', { key: 'err:' + path, className: 'edrv-dl-hint is-error' },
+    React.createElement('span', null, message),
+    React.createElement('button', {
+      type: 'button',
+      onClick: (event: React.MouseEvent) => {
+        // 错误行嵌在目录行内，重试不应顺带切换该目录的展开态
+        event.stopPropagation()
+        void retry(path)
+      },
+    }, '重试'),
+  )
+}
+
+/**
+ * 挂载弹窗：临时宿主 + createRoot，关闭时卸载并移除（与工作区选择弹窗同一范式）。
+ * @author ddj 2026年11月03号
+ * @param opts 根目录 / 会话 / 确认回调
+ * @sideEffects 向 body 追加一个宿主节点，关闭时移除
+ */
+export function openDownloader(opts: { root: string; sessionId?: string; onConfirm: (paths: string[]) => void }): void {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  const mount = createRoot(host)
+
+  function close(): void {
+    mount.unmount()
+    host.remove()
+  }
+
+  function confirm(paths: string[]): void {
+    close()
+    opts.onConfirm(paths)
+  }
+
+  mount.render(React.createElement(DownloadPicker, {
+    root: opts.root,
+    sessionId: opts.sessionId,
+    onClose: close,
+    onConfirm: confirm,
+  }))
+}
+
+/**
+ * 错误可读文案（Error.message 优先，其余 String 化）。
+ * @author ddj 2026年11月03号
+ * @param error 捕获值
+ * @returns 提示文案
+ */
+function textOfError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/shared/remoteChannel.ts

@@ -37,6 +37,17 @@ export function channelPrefix(): string {
   }
 }
 
+/**
+ * 本页是否经远程访问通道接入（远程 vs 本机回环）。
+ * 与 {@link import('../client/rpc.js').channelNote} 同口径：只认通道 seat，不解析地址。
+ * 用于「仅远程可用」能力的显隐，例如资源管理器的「下载到本机」。
+ * @author ddj 2026年11月03号
+ * @returns 已接入远程通道为 true；本机、桌面 dsh-app:、未装该插件均为 false
+ */
+export function isRemoteChannel(): boolean {
+  return channelPrefix() !== ''
+}
+
 /**
  * 给插件内部路径加通道前缀。
  * @author ddj 2026年11月02号