dsh-my-computer 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,7 @@ pnpm add dsh-my-computer
 # 然后把 "dsh-my-computer" 加进 package.json 的 dsh.profile.bundles，重启 dsh web
 ```
 
-> 已实测环境：DSH 0.2.2-rc.1 + Windows 10/11 + Node 24，宿主侧 11 条路由 + 客户端右栏 tab 均正常。
+> 已实测环境：DSH 0.2.2-rc.1 + Windows 10/11 + Node 24，宿主侧 12 条路由 + 客户端右栏 tab 均正常。
 
 ---
 
@@ -35,11 +35,13 @@ dsh-my-computer/
 ├── package.json          # dsh.bundle.patch + dsh.client 声明
 ├── cordis.patch.yml      # insert: [{ id: my-computer, name: dsh-my-computer }]
 ├── lib/
-│   ├── index.js          # host 半区：ESM cordis 插件，注册 11 条 HTTP 路由（零依赖，只用 node: 内置）
+│   ├── index.js          # host 半区：ESM cordis 插件，注册 12 条 HTTP 路由（零依赖，只用 node: 内置）
+│   ├── zip.js            # 整目录打包：自己写的流式 zip 写入器（零依赖，走 node:zlib）
 │   └── client.js         # 客户端 bundle：window.__ModuleLoader__.load({id, factory}) 格式，手写 React.createElement
 ├── tools/
-│   ├── smoke.mjs         # host 冒烟测试（伪造 ctx，直接打路由）
-│   └── client-check.mjs  # 客户端 bundle 自检（语法/注册/四个渲染状态）
+│   ├── smoke.mjs         # host 冒烟测试（伪造 ctx，直接打路由，含 zip 解包校验）
+│   ├── client-check.mjs  # 客户端 bundle 自检（语法/注册/渲染状态）
+│   └── right-tab-check.mjs # 右栏 tab 三件套注册轨迹检查
 └── README.md
 ```
 
@@ -67,7 +69,8 @@ dsh-my-computer/
 | `/list` | `GET /api/my-computer/list?path=D:\foo` | GET | 列目录。目录在前、`localeCompare(zh-Hans-CN, numeric)` 排序。返回 `{ok,path,parent,entries:[{name,path,kind,size,mtime,ext,targetKind,statError}],count,total,free}`；盘符根 `parent:null` |
 | `/read` | `GET /api/my-computer/read?path=&maxBytes=` | GET | 文本预览，默认 ≤512KB、硬上限 8MB。UTF-8 优先，失败退 GB18030，再失败判二进制。返回 `{ok,path,size,mtime,truncated,encoding,text}` |
 | `/write` | `POST /api/my-computer/write` | POST | `{path,text}` 覆盖写：先写同目录 `.dsh-mc-write-*.tmp` 再 rename。返回 `{ok,path,size,mtime}` |
-| `/download` | `GET /api/my-computer/download?path=` | GET | 单文件流式下载，`Content-Disposition: attachment`（含 `filename*=UTF-8''`，中文名不乱码）。**目录 → 422**，不做 zip |
+| `/download` | `GET /api/my-computer/download?path=` | GET | 单文件流式下载，`Content-Disposition: attachment`（含 `filename*=UTF-8''`，中文名不乱码）。给目录会 400 `IS_DIRECTORY`，提示改用下一个 |
+| `/download-dir` | `GET /api/my-computer/download-dir?path=` | GET | **整目录打包成 zip 流式下发**，不落临时文件、不占内存。响应头带 `x-zip-entries` / `x-zip-bytes`。空目录 400 `ZIP_EMPTY`，条目 >20000 或 >3.9GB 在发头之前就 413，整盘根 403 |
 | `/upload` | `PUT /api/my-computer/upload?path=<目录>&name=<文件名>[&overwrite=1]` | PUT | 原始二进制 body 流式落盘（`requestBody:'streaming'`），先写 `.dsh-mc-upload-*.tmp` 再 rename。同名 409，`overwrite=1` 才覆盖 |
 | `/mkdir` | `POST /api/my-computer/mkdir` | POST | `{path:父目录,name}`，不带 `recursive`，重名 409 |
 | `/rename` | `POST /api/my-computer/rename` | POST | `{path,name}`，同目录改名，目标存在 409 |
@@ -81,6 +84,19 @@ dsh-my-computer/
 
 只校验三件事：非空、是绝对 Windows 路径（`X:\` 或 `\\server\share`）、不含 NUL。**不做 workspace 门卫**——用户要的就是全盘权限，设门卫反而把「远程救火」的场景卡死。真正的边界交给 Windows 自己的 ACL：没权限就返回 `PERMISSION_DENIED`。
 
+### 3.4 整目录打包（`lib/zip.js`）
+
+没在 `/download` 上加个 `?zip=1`，而是单独一条路由、单独一个模块，因为「打包」的坑和「读一个文件」完全不同：
+
+- **先扫再发**：`scanDir()` 先走一遍目录树（只 `stat`、不读内容），拿到条目清单与总字节数，**在写响应头之前**就判断「空目录 / 条目超 20000 / 超 3.9GB」。所以客户端拿到的是 JSON 错误，而不是下到一半的残包。
+- **小文件先试压**：≤8MB 的文件读进内存，`zlib.deflateRawSync` 压得动就 DEFLATE、压不动就 STORE（jpg/mp4/zip/pdf 这类直接跳过压缩），CRC 与大小在写本地头之前就已知。
+- **大文件走数据描述符**：>8MB 直接 STORE 流式吐出，边读边算 CRC，写完补 16 字节 data descriptor（通用标志 bit 3）。内存恒定，不落临时文件。
+- **中文名**：所有条目带 UTF-8 标志（bit 11），解压不乱码；目录条目带尾部 `/`，空目录也能还原。
+- **符号链接跳过**：不跟随，避免环和跨盘。
+- **不支持 Zip64**：超阈值明确报 `ZIP_TOO_LARGE` / `ZIP_TOO_MANY_ENTRIES`，不静默截断。
+
+已验证：Windows 自带 `Expand-Archive` 能直接解开（含中文文件名、空目录、11MB 大文件），解出来的文件 sha256 与源文件一致；`tools/smoke.mjs` 还会自己解析中央目录逐条比对 CRC。
+
 ---
 
 ## 4. 面板
@@ -94,8 +110,10 @@ dsh-my-computer/
 
 - **顶部**：盘符行（chip，显示可用空间，一键切换）+ 面包屑（每一级可点）+ 刷新
 - **路径框**：粘贴 `D:\dsh-workspace\vault` 回车直接跳转（远程操作的主力功能）
-- **列表**：图标 + 名称 + 大小/时间两行式；点目录进入，点文件开预览抽屉；每行右侧 下载 / 改名 / 删除
-- **多选**：行首复选框 + 「全选」，选中后出现「删除 N 项」
+- **列表**：图标 + 名称 + 大小/时间两行式；点目录进入，点文件开预览抽屉；每行右侧 下载（文件）/ 打包（目录 zip）/ 剪切 / 改名 / 删除
+- **打包下载**：目录行点 🗜 直接下 `<目录名>.zip`，走浏览器原生下载（不把整包攒成 blob，手机上下几百 MB 也不会崩标签页）
+- **剪切 / 粘贴**：行内 ✂ 或选中多项后点「✂ 剪切 N 项」→ 进目标目录点「📋 粘贴到此处」，走 `POST /move`（同盘 rename，跨盘自动退化成 复制+删除）。剪切板只在内存里，刷新即失，避免误粘
+- **多选**：行首复选框 + 「全选」，选中后出现「删除 N 项」/「剪切 N 项」
 - **筛选**：一个输入框过滤当前目录（手机上一个目录几百个文件时很有用）
 - **底部**：共 N 项、可用/总容量、已选数、上传进度
 - **底部工具条**：新建文件夹 / 上传（`<input type=file multiple>`，逐个 PUT，遇到同名弹「覆盖上传」确认）/ 全选 / 删除
@@ -167,7 +185,7 @@ Get-Content D:\dsh\dsh.log -Tail 40
 启动日志里应该能看到一行：
 
 ```
-[dsh-my-computer] 已注册 11 条路由：GET /api/my-computer/health, GET /api/my-computer/drives, ...
+[dsh-my-computer] 已注册 12 条路由：GET /api/my-computer/health, GET /api/my-computer/drives, ...
 ```
 
 （这行是 `ctx.logger.info`，`console.log` 也会打一份。）
@@ -209,7 +227,7 @@ pnpm remove dsh-my-computer
 
 ```powershell
 cd D:\dsh-workspace\packages\dsh-my-computer
-node tools/smoke.mjs          # host：11 条路由 + 正常/错误路径
+node tools/smoke.mjs          # host：12 条路由 + 正常/错误路径 + zip 解包比对
 node tools/client-check.mjs   # client：bundle 形状 + slots 注册 + 四个渲染状态
 node tools/right-tab-check.mjs # client：右栏 tab 三件套（sidebarRightTabs + pane.tab + title）注册轨迹
 ```
@@ -224,15 +242,17 @@ node tools/right-tab-check.mjs # client：右栏 tab 三件套（sidebarRightTab
 
 - **已实测（2026-11-11）**：Linux 容器与本机之外的 Windows 宿主上原生跑通，右栏「+」菜单出现「我的电脑」，盘符、路径跳转、上传下载、改名删除、文本编辑全部可用。客户端注册失败时会把原因挂在 `window.__MYCOMP_ERR`，方便定位。
 - **`dsh.client.inject` 故意留空 `[]`**：`slots` 服务在任何客户端插件里都直接可用（同 profile 里工作的 `dsh-a2a-panel` 就是 `inject: []`），而写一个本机不存在的模块 id 会让整个 bundle 加载失败。
-- **不做整目录下载（zip）**：按要求 MVP 跳过，目录下载返回 422 并说明原因。
-- **上传没有进度条**：只有「上传中 n/总数」。要字节级进度得换 XMLHttpRequest 或流式上传端点。
+- **整目录打包有限制**：超 20000 个条目或 3.9GB 会直接 413（不支持 Zip64，请分批下）。大文件是 STORE 不压缩（保速度与内存恒定），所以下大电影不会变小。
+- **上传没有字节进度**：只有「上传中 n/总数」。要字节级百分比得换 XMLHttpRequest。
 - **删除不进回收站**：`fs.rm` 是硬删除，所以面板做了两步确认 + 后端要求 `confirm:true` + 拒绝删盘符根。
 - **大文件文本编辑**：`/read` 只给前 512KB。截断状态下保存会用编辑器里的内容覆盖整个文件——面板在截断时给了红字提示，但这是真实风险，编辑大文件请先下载。
 - **NTFS 权限/长路径/只读盘**：没有做特殊处理，出错就按 `PERMISSION_DENIED` / `IO_ERROR` 报给面板。超过 260 字符的路径依赖 Node 的长路径支持，未实测。
-- **`/move` 没有 UI**：路由实现了（剪切粘贴用），面板暂未接。要接就在工具栏加「粘贴」按钮，调 `POST /move`。
+- **剪切板只在内存里**：刷新/关面板就没了（故意这样，避免手滑把文件粘到奇怪的地方）。跨目录批量移动请用「选中 → 剪切 → 粘贴」。
 
 ---
 
 ## 9. 版本
 
+0.2.0 —— 整目录打包下载（`GET /download-dir`，自研流式 zip，不落临时文件）+ 面板接上剪切/粘贴（走 `POST /move`）+ 客户端与宿主版本对不上时给提示而不是 404。
+
 0.1.0 —— 首个公开版本。11 条路由 + 右栏 tab 面板（盘符切换 / 面包屑 / 路径粘贴跳转 / 列表 / 多选删除 / 新建 / 上传 / 下载 / 改名 / 预览与文本编辑），Windows 原生，跨盘符、不受会话工作区限制。

package/lib/client.js

@@ -35,6 +35,9 @@ try {
       var PANEL_ID = 'my-computer'
       // DSH 的精确 fetch 路由挂在 /api 共享通道下（鉴权在那一层做），所以真实前缀是 /api/my-computer
       var BASE = '/api/my-computer'
+      // 与 package.json 同步；宿主 /health 会报它自己的版本，两边不一致说明
+      // 「客户端已经更新、宿主还没重启」，这时不能放用户去点新路由（会 404）
+      var CLIENT_VERSION = '0.2.0'
       var LS_KEY = 'dsh-my-computer:last-path'
 
       /* ------------------------------------------------------------ *
@@ -193,9 +196,15 @@ try {
         return BASE + '/download?path=' + enc(p)
       }
 
-      function triggerDownload(p) {
+      function downloadDirUrl(p) {
+        return BASE + '/download-dir?path=' + enc(p)
+      }
+
+      /* 用隐藏 <a> 触发浏览器原生下载：走 cookie 鉴权、直接落盘，
+         不用 fetch+blob（手机上几百 MB 的包塞进内存会直接崩标签页）。 */
+      function triggerAnchor(url) {
         var anchor = document.createElement('a')
-        anchor.href = downloadUrl(p)
+        anchor.href = url
         anchor.setAttribute('download', '')
         anchor.rel = 'noopener'
         document.body.appendChild(anchor)
@@ -205,6 +214,14 @@ try {
         }, 0)
       }
 
+      function triggerDownload(p) {
+        triggerAnchor(downloadUrl(p))
+      }
+
+      function triggerDirDownload(p) {
+        triggerAnchor(downloadDirUrl(p))
+      }
+
       /* ------------------------------------------------------------ *
        * 样式：跟随宿主主题变量（--dsw-alias-*），拿不到时退到明/暗两套兜底
        * ------------------------------------------------------------ */
@@ -370,6 +387,15 @@ try {
         var busy = _busy[0]
         var setBusy = _busy[1]
 
+        // 剪切板：{ paths: [...], label: '文件名' }，只活在内存里（刷新就没，避免误粘）
+        var _clip = useState(null)
+        var clip = _clip[0]
+        var setClip = _clip[1]
+
+        var _hostVer = useState('')
+        var hostVersion = _hostVer[0]
+        var setHostVersion = _hostVer[1]
+
         var fileInputRef = useRef(null)
         var mountedRef = useRef(true)
 
@@ -418,6 +444,49 @@ try {
             })
         }, [])
 
+        function pasteClip() {
+          if (!clip || !clip.paths || clip.paths.length === 0) return
+          var target = cwd
+          if (!target) return
+          clearMessages()
+          setBusy('正在移动 ' + clip.paths.length + ' 项…')
+          apiPost('/move', { sources: clip.paths, targetDir: target })
+            .then(function (data) {
+              if (!mountedRef.current) return
+              var count = (data.moved || []).length
+              var skipped = (data.failed || []).length
+              setClip(null)
+              return navigate(target).then(function () {
+                if (!mountedRef.current) return
+                setNotice('已移动 ' + count + ' 项到 ' + target + (skipped ? '（' + skipped + ' 项失败）' : ''))
+              })
+            })
+            .catch(function (error) {
+              if (mountedRef.current) reportError(error)
+            })
+            .then(function () {
+              if (mountedRef.current) setBusy('')
+            })
+        }
+
+        function setClipFrom(paths, label) {
+          if (!paths || paths.length === 0) return
+          setClip({ paths: paths.slice(), label: label })
+          setSelected([])
+          clearMessages()
+          setNotice('已剪切：' + label + '。到目标目录后点「粘贴到此处」')
+        }
+
+        useEffect(function () {
+          apiGet('/health')
+            .then(function (data) {
+              if (mountedRef.current && data && data.version) setHostVersion(String(data.version))
+            })
+            .catch(function () {
+              /* 探不到就当未知，不做任何限制 */
+            })
+        }, [])
+
         var loadDrives = useCallback(function () {
           return apiGet('/drives')
             .then(function (data) {
@@ -729,6 +798,47 @@ try {
             '＋ 新建文件夹',
           ),
           h('button', { type: 'button', className: 'mc-btn', onClick: pickFiles }, '⬆ 上传'),
+          selected.length > 0
+            ? h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'mc-btn',
+                  title: '剪切选中项，去别的目录粘贴',
+                  onClick: function () {
+                    setClipFrom(selected, selected.length + ' 项')
+                  },
+                },
+                '✂ 剪切 ' + selected.length + ' 项',
+              )
+            : null,
+          clip
+            ? h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'mc-btn solid',
+                  title: '把剪切板里的内容移动到当前目录：' + cwd,
+                  onClick: pasteClip,
+                },
+                '📋 粘贴「' + clip.label + '」到此处',
+              )
+            : null,
+          clip
+            ? h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'mc-btn',
+                  title: '清空剪切板',
+                  onClick: function () {
+                    setClip(null)
+                    clearMessages()
+                  },
+                },
+                '取消剪切',
+              )
+            : null,
           h(
             'button',
             { type: 'button', className: 'mc-btn', onClick: toggleSelectAll, disabled: visibleEntries.length === 0 },
@@ -825,6 +935,39 @@ try {
                     '⤓',
                   )
                 : null,
+              effective === 'dir' && !entry.statError
+                ? h(
+                    'button',
+                    {
+                      type: 'button',
+                      className: 'mc-ibtn',
+                      title: '打包下载这个目录（zip）',
+                      onClick: function () {
+                        if (hostVersion && hostVersion !== CLIENT_VERSION) {
+                          clearMessages()
+                          setNotice(
+                            '宿主侧还是 v' + hostVersion + '，「打包下载」要重启 dsh web 后才生效（本面板 v' + CLIENT_VERSION + '）',
+                          )
+                          return
+                        }
+                        triggerDirDownload(entry.path)
+                      },
+                    },
+                    '🗜',
+                  )
+                : null,
+              h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'mc-ibtn',
+                  title: '剪切（到别的目录粘贴）',
+                  onClick: function () {
+                    setClipFrom([entry.path], entry.name)
+                  },
+                },
+                '✂',
+              ),
               h(
                 'button',
                 {

package/lib/index.js

@@ -23,6 +23,7 @@ import fsp from 'node:fs/promises'
 import path from 'node:path'
 import { Readable } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
+import { createZipArchive } from './zip.js'
 
 export const name = 'dsh-my-computer'
 
@@ -36,7 +37,7 @@ const DEFAULT_READ_BYTES = 512 * 1024
 const HARD_READ_CAP = 8 * 1024 * 1024
 const MAX_JSON_BODY = 8 * 1024 * 1024
 
-const VERSION = '0.1.0'
+const VERSION = '0.2.0'
 
 /* ------------------------------------------------------------------ *
  * 错误与响应
@@ -535,7 +536,7 @@ async function handleDownload(request) {
   const target = requirePath(url.searchParams.get('path'))
   const st = await statOrFail(target)
   if (st.isDirectory()) {
-    fail('DIRECTORY_NOT_SUPPORTED', '不支持整目录下载（MVP 不做 zip 打包），请进入目录逐个下载文件', 422)
+    fail('IS_DIRECTORY', '这是目录，单文件下载不支持；整目录请用 /download-dir 打包成 zip', 400)
   }
 
   const headers = {
@@ -549,6 +550,48 @@ async function handleDownload(request) {
   return new Response(Readable.toWeb(stream), { status: 200, headers })
 }
 
+/**
+ * GET /download-dir?path= —— 整目录打包成 zip 流式下发（不落临时文件）。
+ *
+ * 发响应头之前已经把目录扫了一遍（条目数 / 总字节 / 可读性），所以「太大」
+ * 「空目录」这类问题会以 JSON 错误体正常返回，而不是下载到一半断掉。
+ * 中间读失败的文件会跳过，并把清单打在宿主日志里（压缩包本身仍然完整）。
+ */
+async function handleDownloadDir(request) {
+  const url = new URL(request.url)
+  const target = requirePath(url.searchParams.get('path'))
+  const st = await statOrFail(target)
+  if (!st.isDirectory()) {
+    fail('NOT_DIRECTORY', `不是目录：${target}（单文件请用 /download）`, 400)
+  }
+  if (isDriveRoot(target)) {
+    fail('FORBIDDEN', '整盘打包请进入具体目录后再下载（盘符根通常几十万文件）', 403)
+  }
+
+  const warnings = []
+  const archive = await createZipArchive(target, {
+    fail,
+    onWarn: (info) => {
+      warnings.push(info)
+      if (warnings.length <= 20) {
+        console.warn(`[dsh-my-computer] zip 跳过 ${info.path}：${info.message}`)
+      }
+    },
+  })
+
+  const headers = {
+    'content-type': 'application/zip',
+    'content-disposition': contentDisposition(archive.filename),
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+    // 面板拿来显示进度提示（非标准头，纯提示；跨站读不到也无所谓）
+    'x-zip-entries': String(archive.entries),
+    'x-zip-bytes': String(archive.bytes),
+    'x-zip-skipped': String(warnings.length),
+  }
+  return new Response(Readable.toWeb(Readable.from(archive.parts)), { status: 200, headers })
+}
+
 /** PUT /upload?path=<目录>&name=<文件名>[&overwrite=1] —— 原始二进制流式落盘。 */
 async function handleUpload(request) {
   const url = new URL(request.url)
@@ -736,6 +779,7 @@ const ROUTES = [
   { id: 'list', path: PREFIX + '/list', methods: ['GET'], requestBody: 'buffered', run: handleList },
   { id: 'read', path: PREFIX + '/read', methods: ['GET'], requestBody: 'buffered', run: handleRead },
   { id: 'download', path: PREFIX + '/download', methods: ['GET'], requestBody: 'buffered', run: handleDownload },
+  { id: 'downloadDir', path: PREFIX + '/download-dir', methods: ['GET'], requestBody: 'buffered', run: handleDownloadDir },
   { id: 'write', path: PREFIX + '/write', methods: ['POST'], requestBody: 'buffered', run: handleWrite },
   { id: 'upload', path: PREFIX + '/upload', methods: ['PUT'], requestBody: 'streaming', run: handleUpload },
   { id: 'mkdir', path: PREFIX + '/mkdir', methods: ['POST'], requestBody: 'buffered', run: handleMkdir },

package/lib/zip.js

@@ -0,0 +1,365 @@
+// dsh-my-computer —— 整目录打包（零依赖、流式、边读边发）
+//
+// 为什么自己写：这个插件承诺零 npm 依赖（profile 里 pnpm prune 会干掉
+// extraneous 包），为了一个 zip 引入 archiver / yazl 不划算，而 Node 自带
+// 的 zlib.deflateRawSync 已经足够——zip 的「压缩」就是把 deflateRaw 的字节
+// 塞进文件条目里。
+//
+// 策略（对手机远程下载友好）：
+//   * 小文件（<= 8MB）先读进内存 → 试压 → 压不动的就 STORE，压得动的用 DEFLATE，
+//     两种都能在写本地头之前知道大小和 CRC，不必用数据描述符；
+//   * 大文件 STORE + 流式，靠数据描述符（bit 3）补 CRC/大小，内存恒定；
+//   * 一律带 UTF-8 名字标志（bit 11），中文文件名解压不乱码；
+//   * 目录条目带尾部 '/'，空目录也能还原；
+//   * 打包前先扫一遍做上限检查（条目数 / 总字节），超了在发响应头之前就报错，
+//     避免「下载了一半才失败」。
+//
+// 不支持（明确报错，不静默降级）：Zip64（>4GB 或 >65535 个条目）。真需要就分批。
+
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import zlib from 'node:zlib'
+
+const MAX_ENTRIES = 20000
+const MAX_TOTAL_BYTES = 3.9 * 1000 * 1000 * 1000 // 留出 Zip64 阈值的余量
+const INLINE_LIMIT = 8 * 1024 * 1024 // 进内存试压的上限
+
+/** 已经是压缩格式的扩展名，再 deflate 只是白烧 CPU。 */
+const INCOMPRESSIBLE = new Set([
+  '.jpg', '.jpeg', '.png', '.gif', '.webp', '.avif', '.heic', '.bmp', '.ico',
+  '.mp4', '.mov', '.mkv', '.avi', '.webm', '.mp3', '.m4a', '.aac', '.ogg', '.flac', '.wav',
+  '.zip', '.7z', '.rar', '.gz', '.bz2', '.xz', '.zst', '.tgz',
+  '.pdf', '.docx', '.xlsx', '.pptx', '.odt', '.epub',
+  '.apk', '.exe', '.dll', '.msi', '.iso', '.bin', '.pak',
+  '.db', '.sqlite', '.sqlite3', '.woff', '.woff2', '.ttf', '.otf',
+])
+
+/* ------------------------------------------------------------------ *
+ * CRC32（zip 用的多项式，查表法）
+ * ------------------------------------------------------------------ */
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256)
+  for (let i = 0; i < 256; i += 1) {
+    let c = i
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    }
+    table[i] = c
+  }
+  return table
+})()
+
+function crc32(buffer) {
+  let crc = -1
+  for (let i = 0; i < buffer.length; i += 1) {
+    crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ buffer[i]) & 0xff]
+  }
+  return (crc ^ -1) >>> 0
+}
+
+/* ------------------------------------------------------------------ *
+ * 时间戳 → DOS 时间
+ * ------------------------------------------------------------------ */
+
+function dosDateTime(ms) {
+  const d = ms ? new Date(ms) : new Date()
+  const year = d.getFullYear()
+  if (!Number.isFinite(year) || year < 1980) return { date: 0x21, time: 0 }
+  const date = ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate()
+  const time = (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1)
+  return { date: date & 0xffff, time: time & 0xffff }
+}
+
+/* ------------------------------------------------------------------ *
+ * 扫描：先看清要打什么，才能在写响应头之前做上限判断
+ * ------------------------------------------------------------------ */
+
+async function scanDir(rootDir, { fail, onWarn }) {
+  const items = []
+  let totalBytes = 0
+
+  async function walk(absDir, relDir) {
+    let dirents
+    try {
+      dirents = await fsp.readdir(absDir, { withFileTypes: true })
+    } catch (error) {
+      // 读不动的子目录不要整个打包跟着失败，跳过并记一笔
+      onWarn?.({ path: absDir, message: String(error?.message || error) })
+      return
+    }
+    dirents.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    for (const dirent of dirents) {
+      const abs = path.win32.join(absDir, dirent.name)
+      const rel = relDir ? relDir + '/' + dirent.name : dirent.name
+      const isLink = dirent.isSymbolicLink()
+      let st
+      try {
+        // 快捷方式/链接按「不跟随」处理：跟随可能绕成环，也可能跨到别的盘
+        st = isLink ? await fsp.lstat(abs) : await fsp.stat(abs)
+      } catch (error) {
+        onWarn?.({ path: abs, message: String(error?.message || error) })
+        continue
+      }
+      if (isLink) {
+        onWarn?.({ path: abs, message: '跳过符号链接/快捷方式（避免打包出环）' })
+        continue
+      }
+      if (st.isDirectory()) {
+        items.push({ kind: 'dir', abs, rel, size: 0, mtimeMs: st.mtimeMs })
+        if (items.length > MAX_ENTRIES) fail('ZIP_TOO_MANY_ENTRIES', `目录内条目超过 ${MAX_ENTRIES} 个，请分批下载`, 413)
+        await walk(abs, rel)
+      } else if (st.isFile()) {
+        totalBytes += st.size
+        items.push({ kind: 'file', abs, rel, size: st.size, mtimeMs: st.mtimeMs })
+        if (items.length > MAX_ENTRIES) fail('ZIP_TOO_MANY_ENTRIES', `目录内条目超过 ${MAX_ENTRIES} 个，请分批下载`, 413)
+        if (totalBytes > MAX_TOTAL_BYTES) {
+          fail('ZIP_TOO_LARGE', '目录内容超过 3.9GB（Zip64 未支持），请分批下载', 413)
+        }
+      } else {
+        onWarn?.({ path: abs, message: '跳过非常规文件（设备/管道等）' })
+      }
+    }
+  }
+
+  await walk(rootDir, '')
+  return { items, totalBytes }
+}
+
+/* ------------------------------------------------------------------ *
+ * 结构体小工具
+ * ------------------------------------------------------------------ */
+
+function localHeader({ nameBuf, method, crc, compSize, size, dos, flags }) {
+  const head = Buffer.alloc(30)
+  head.writeUInt32LE(0x04034b50, 0)
+  head.writeUInt16LE(20, 4) // version needed
+  head.writeUInt16LE(flags, 6)
+  head.writeUInt16LE(method, 8)
+  head.writeUInt16LE(dos.time, 10)
+  head.writeUInt16LE(dos.date, 12)
+  head.writeUInt32LE(crc, 14)
+  head.writeUInt32LE(compSize, 18)
+  head.writeUInt32LE(size, 22)
+  head.writeUInt16LE(nameBuf.length, 26)
+  head.writeUInt16LE(0, 28) // extra
+  return Buffer.concat([head, nameBuf])
+}
+
+function dataDescriptor({ crc, compSize, size }) {
+  const buf = Buffer.alloc(16)
+  buf.writeUInt32LE(0x08074b50, 0)
+  buf.writeUInt32LE(crc, 4)
+  buf.writeUInt32LE(compSize, 8)
+  buf.writeUInt32LE(size, 12)
+  return buf
+}
+
+function centralHeader(entry) {
+  const head = Buffer.alloc(46)
+  head.writeUInt32LE(0x02014b50, 0)
+  head.writeUInt16LE(20, 4) // version made by
+  head.writeUInt16LE(20, 6) // version needed
+  head.writeUInt16LE(entry.flags, 8)
+  head.writeUInt16LE(entry.method, 10)
+  head.writeUInt16LE(entry.dos.time, 12)
+  head.writeUInt16LE(entry.dos.date, 14)
+  head.writeUInt32LE(entry.crc, 16)
+  head.writeUInt32LE(entry.compSize, 20)
+  head.writeUInt32LE(entry.size, 24)
+  head.writeUInt16LE(entry.nameBuf.length, 28)
+  head.writeUInt16LE(0, 30) // extra len
+  head.writeUInt16LE(0, 32) // comment len
+  head.writeUInt16LE(0, 34) // disk number start
+  head.writeUInt16LE(0, 36) // internal attrs
+  head.writeUInt32LE(entry.kind === 'dir' ? 0x10 : 0x20, 38) // external attrs
+  head.writeUInt32LE(entry.offset, 42)
+  return Buffer.concat([head, entry.nameBuf])
+}
+
+function endOfCentralDirectory({ count, cdSize, cdOffset }) {
+  const buf = Buffer.alloc(22)
+  buf.writeUInt32LE(0x06054b50, 0)
+  buf.writeUInt16LE(0, 4)
+  buf.writeUInt16LE(0, 6)
+  buf.writeUInt16LE(count, 8)
+  buf.writeUInt16LE(count, 10)
+  buf.writeUInt32LE(cdSize, 12)
+  buf.writeUInt32LE(cdOffset, 16)
+  buf.writeUInt16LE(0, 20)
+  return buf
+}
+
+const FLAG_UTF8 = 0x0800
+const FLAG_DESCRIPTOR = 0x0008
+
+async function* streamFile(abs, size) {
+  const stream = fs.createReadStream(abs, { highWaterMark: 256 * 1024 })
+  for await (const chunk of stream) {
+    yield chunk
+  }
+  if (size === 0) yield Buffer.alloc(0)
+}
+
+/* ------------------------------------------------------------------ *
+ * 主入口：返回 { parts, entries, bytes, skipped }
+ *   parts —— 异步生成器，yield Buffer（可以直接 Readable.from 成响应体）
+ * ------------------------------------------------------------------ */
+
+export async function createZipArchive(rootDir, options = {}) {
+  const { fail, onWarn } = options
+  const mustFail = fail || ((code, message, status) => {
+    const error = new Error(message)
+    error.code = code
+    error.status = status
+    throw error
+  })
+
+  const rootName = path.win32.basename(rootDir) || 'archive'
+  const { items, totalBytes } = await scanDir(rootDir, { fail: mustFail, onWarn })
+  if (items.length === 0) {
+    mustFail('ZIP_EMPTY', '这个目录是空的，没有可打包的内容', 400)
+  }
+  if (items.length >= 0xffff) {
+    mustFail('ZIP_TOO_MANY_ENTRIES', `条目数 ${items.length} 超过 65535（Zip64 未支持）`, 413)
+  }
+
+  async function* parts() {
+    let offset = 0
+    const central = []
+    const skipped = []
+
+    for (const item of items) {
+      const entryName = item.rel ? rootName + '/' + item.rel : rootName + '/'
+      const nameForZip = item.kind === 'dir' ? entryName.replace(/\/?$/, '/') : entryName
+      const nameBuf = Buffer.from(nameForZip, 'utf8')
+      const dos = dosDateTime(item.mtimeMs)
+      const entryOffset = offset
+
+      if (item.kind === 'dir') {
+        const header = localHeader({
+          nameBuf,
+          method: 0,
+          crc: 0,
+          compSize: 0,
+          size: 0,
+          dos,
+          flags: FLAG_UTF8,
+        })
+        yield header
+        offset += header.length
+        central.push({ kind: 'dir', nameBuf, method: 0, crc: 0, compSize: 0, size: 0, dos, flags: FLAG_UTF8, offset: entryOffset })
+        continue
+      }
+
+      let handled = false
+      if (item.size <= INLINE_LIMIT) {
+        let data
+        try {
+          data = await fsp.readFile(item.abs)
+        } catch (error) {
+          skipped.push({ path: item.abs, message: String(error?.message || error) })
+          onWarn?.({ path: item.abs, message: String(error?.message || error) })
+          continue
+        }
+        const crc = crc32(data)
+        let method = 0
+        let payload = data
+        const ext = path.win32.extname(item.abs).toLowerCase()
+        if (data.length > 0 && !INCOMPRESSIBLE.has(ext)) {
+          const deflated = zlib.deflateRawSync(data, { level: 6 })
+          if (deflated.length < data.length) {
+            method = 8
+            payload = deflated
+          }
+        }
+        const header = localHeader({
+          nameBuf,
+          method,
+          crc,
+          compSize: payload.length,
+          size: data.length,
+          dos,
+          flags: FLAG_UTF8,
+        })
+        yield header
+        if (payload.length > 0) yield payload
+        offset += header.length + payload.length
+        central.push({
+          kind: 'file',
+          nameBuf,
+          method,
+          crc,
+          compSize: payload.length,
+          size: data.length,
+          dos,
+          flags: FLAG_UTF8,
+          offset: entryOffset,
+        })
+        handled = true
+      }
+
+      if (!handled) {
+        // 大文件：STORE + 数据描述符，内存恒定
+        const flags = FLAG_UTF8 | FLAG_DESCRIPTOR
+        const header = localHeader({ nameBuf, method: 0, crc: 0, compSize: 0, size: 0, dos, flags })
+        yield header
+        offset += header.length
+        let crc = -1
+        let written = 0
+        try {
+          for await (const chunk of streamFile(item.abs, item.size)) {
+            if (chunk.length === 0) continue
+            for (let i = 0; i < chunk.length; i += 1) {
+              crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ chunk[i]) & 0xff]
+            }
+            written += chunk.length
+            offset += chunk.length
+            yield chunk
+          }
+        } catch (error) {
+          // 已经写出去一半的文件没法撤回，只能在中央目录里标成 0 长度并记一笔
+          skipped.push({ path: item.abs, message: String(error?.message || error) })
+          onWarn?.({ path: item.abs, message: String(error?.message || error) })
+          written = 0
+          crc = -1
+        }
+        const finalCrc = (crc ^ -1) >>> 0
+        const descriptor = dataDescriptor({ crc: finalCrc, compSize: written, size: written })
+        yield descriptor
+        offset += descriptor.length
+        central.push({
+          kind: 'file',
+          nameBuf,
+          method: 0,
+          crc: finalCrc,
+          compSize: written,
+          size: written,
+          dos,
+          flags,
+          offset: entryOffset,
+        })
+      }
+    }
+
+    const cdOffset = offset
+    let cdSize = 0
+    for (const entry of central) {
+      const header = centralHeader(entry)
+      yield header
+      cdSize += header.length
+    }
+    const eocd = endOfCentralDirectory({ count: central.length, cdSize, cdOffset })
+    yield eocd
+  }
+
+  return {
+    filename: rootName + '.zip',
+    entries: items.length,
+    bytes: totalBytes,
+    parts: parts(),
+  }
+}
+
+export const internals = { crc32, dosDateTime, MAX_ENTRIES, MAX_TOTAL_BYTES, INLINE_LIMIT }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-computer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DSH Web 右栏「我的电脑」：远程浏览与操作整台 Windows 磁盘（跨盘符、不受会话工作区限制）",
   "type": "module",
   "main": "lib/index.js",

package/tools/client-check.mjs

@@ -130,11 +130,17 @@ check('exports.inject 是数组', Array.isArray(mod.inject), JSON.stringify(mod.
 section('apply(ctx) 注册的 slots')
 
 const registrations = []
+const tabRegistrations = []
 const fakeClientCtx = {
   effect(fn) {
     const dispose = fn()
     return typeof dispose === 'function' ? dispose : () => {}
   },
+  // 真实宿主里 ctx.inject(names, cb) 会把依赖就绪后的服务集合交给 cb。
+  // 这里直接把 ctx 自己给过去（slots / sidebarRightTabs 都在上面）。
+  inject(names, callback) {
+    return callback(fakeClientCtx)
+  },
   slots: {
     inject(name, callback) {
       return callback()
@@ -144,6 +150,12 @@ const fakeClientCtx = {
       return () => {}
     },
   },
+  sidebarRightTabs: {
+    register(spec) {
+      tabRegistrations.push(spec)
+      return () => {}
+    },
+  },
 }
 
 let applyError = null
@@ -153,7 +165,7 @@ try {
   applyError = error
 }
 check('apply(ctx) 没抛异常', applyError === null, applyError ? String(applyError) : '')
-check('注册了 2 个 slot', registrations.length === 2, registrations.map((r) => r.spec && r.spec.name).join(', '))
+check('注册了 >=2 个 slot', registrations.length >= 2, registrations.map((r) => r.spec && r.spec.name).join(', '))
 check('注入了 <style>（样式跟随主题）', styleNodes.length === 1, styleNodes.length + ' 个 style 节点')
 
 const side = registrations.find((r) => r.spec && r.spec.name === 'sidebar.panellist')
@@ -173,6 +185,15 @@ check('有 main 注册', Boolean(main))
 check('main.key 与侧栏 id 一致', main && side && main.spec.key === side.spec.id, main ? String(main.spec.key) : '')
 check('面板是函数组件', main && typeof main.component === 'function')
 
+/* 右栏 tab 三件套（sidebarRightTabs + pane.tab + pane.tab.title） */
+const tab = tabRegistrations.find((spec) => spec && spec.id === 'my-computer')
+const paneTab = registrations.find((r) => r.spec && r.spec.name === 'sidebar.right.pane.tab')
+const paneTitle = registrations.find((r) => r.spec && r.spec.name === 'sidebar.right.pane.tab.title')
+check('有 sidebarRightTabs 注册', Boolean(tab))
+check('guide 非空（否则不进右栏「+」菜单）', Boolean(tab && Array.isArray(tab.guide) && tab.guide.length > 0))
+check('右栏 pane.tab key 与 tab id 一致', Boolean(paneTab && tab && paneTab.spec.key === tab.id))
+check('右栏 pane.tab.title 也注册了', Boolean(paneTitle && paneTitle.spec.key === 'my-computer'))
+
 /* ------------------------------------------------------------------ *
  * 手搭一个只够跑首屏的渲染器：真 React.createElement + 最小 hook dispatcher
  * ------------------------------------------------------------------ */

package/tools/smoke.mjs

@@ -12,6 +12,7 @@
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import path from 'node:path'
+import zlib from 'node:zlib'
 import { fileURLToPath } from 'node:url'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
@@ -119,7 +120,7 @@ console.log('  临时目录：' + TMP_DIR)
 
 section('路由注册')
 
-checkEqual('注册了 11 条路由', registered.length, 11)
+checkEqual('注册了 12 条路由', registered.length, 12)
 for (const route of registered) {
   const name = route.path.slice(route.path.lastIndexOf('/') + 1)
   const bodyModeOk = route.requestBody === 'buffered' || route.requestBody === 'streaming'
@@ -342,8 +343,60 @@ check('Content-Disposition 是 attachment',
 check('Content-Type 有值', Boolean(dl.headers.get('content-type')), String(dl.headers.get('content-type')))
 
 const dlDir = await call('download', { query: q({ path: TMP_DIR }) })
-checkEqual('下载目录 → 422（MVP 不做 zip）', dlDir.status, 422)
-checkEqual('下载目录 → DIRECTORY_NOT_SUPPORTED', dlDir.data.error && dlDir.data.error.code, 'DIRECTORY_NOT_SUPPORTED')
+checkEqual('用 /download 下目录 → 400（应改用 download-dir）', dlDir.status, 400)
+checkEqual('错误码提示 IS_DIRECTORY', dlDir.data.error && dlDir.data.error.code, 'IS_DIRECTORY')
+
+/* ---------------- GET /download-dir（整目录 zip） ---------------- */
+
+section('GET /download-dir（zip 打包）')
+
+const zipSrc = path.join(TMP_DIR, '打包测试')
+await fsp.mkdir(path.join(zipSrc, '空目录'), { recursive: true })
+await fsp.mkdir(path.join(zipSrc, '子目录'), { recursive: true })
+const zipFileA = path.join(zipSrc, 'a.txt')
+const zipFileB = path.join(zipSrc, '子目录', '中文名.md')
+await fsp.writeFile(zipFileA, 'hello zip\n'.repeat(50), 'utf8')
+await fsp.writeFile(zipFileB, '# 中文内容\n'.repeat(30), 'utf8')
+
+const zipRes = await call('download-dir', { query: q({ path: zipSrc }), raw: true })
+checkEqual('/download-dir 状态码 200', zipRes.status, 200)
+checkEqual('Content-Type 是 application/zip', String(zipRes.headers.get('content-type')), 'application/zip')
+check('Content-Disposition 是 <目录名>.zip',
+  String(zipRes.headers.get('content-disposition') || '').includes(encodeURIComponent('打包测试') + '.zip'),
+  String(zipRes.headers.get('content-disposition') || ''))
+const zipBuf = Buffer.from(await zipRes.arrayBuffer())
+check('ZIP 魔数正确', zipBuf.readUInt32LE(0) === 0x04034b50, zipBuf.length + ' 字节')
+
+let zipEntries = []
+let zipError = ''
+try {
+  zipEntries = parseZip(zipBuf)
+} catch (error) {
+  zipError = String(error && error.message)
+}
+const zipNames = zipEntries.map((entry) => entry.name).sort()
+check('zip 能解析出条目', zipError === '', zipError || zipNames.join(' | '))
+check('zip 含两个文件', zipNames.filter((name) => !name.endsWith('/')).length === 2, zipNames.join(' | '))
+check('zip 保留中文文件名', zipNames.some((name) => name.includes('中文名.md')))
+check('zip 保留空目录', zipNames.some((name) => name.endsWith('空目录/')), zipNames.join(' | '))
+
+const entryA = zipEntries.find((entry) => entry.name.endsWith('a.txt'))
+const entryB = zipEntries.find((entry) => entry.name.endsWith('中文名.md'))
+check('a.txt 内容与磁盘一致', Boolean(entryA) && entryA.data.equals(await fsp.readFile(zipFileA)))
+check('中文名.md 内容与磁盘一致', Boolean(entryB) && entryB.data.equals(await fsp.readFile(zipFileB)))
+check('每个条目 CRC 都对',
+  zipEntries.every((entry) => crc32Of(entry.data) === entry.crc),
+  zipEntries.map((entry) => entry.name + ':' + (crc32Of(entry.data) === entry.crc ? 'ok' : 'BAD')).join(' '))
+
+const zipEmpty = await call('download-dir', { query: q({ path: path.join(zipSrc, '空目录') }) })
+checkEqual('打包空目录 → 400', zipEmpty.status, 400)
+checkEqual('错误码 ZIP_EMPTY', zipEmpty.data.error && zipEmpty.data.error.code, 'ZIP_EMPTY')
+
+const zipOnFile = await call('download-dir', { query: q({ path: zipFileA }) })
+checkEqual('对文件用 download-dir → 400', zipOnFile.status, 400)
+
+const zipMissing = await call('download-dir', { query: q({ path: path.join(TMP_DIR, '没有这个目录') }) })
+checkEqual('打包不存在的目录 → 404', zipMissing.status, 404)
 
 section('POST /move')
 
@@ -395,3 +448,42 @@ if (passed !== total) {
 async function readByteLength(text) {
   return Buffer.byteLength(text, 'utf8')
 }
+
+/** 只够自检用的 zip 读取：走中央目录，支持 STORE(0) 与 DEFLATE(8)。 */
+function parseZip(buf) {
+  const eocd = buf.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]))
+  if (eocd < 0) throw new Error('找不到中央目录结尾（EOCD）')
+  const count = buf.readUInt16LE(eocd + 10)
+  let offset = buf.readUInt32LE(eocd + 16)
+  const out = []
+  for (let i = 0; i < count; i += 1) {
+    if (buf.readUInt32LE(offset) !== 0x02014b50) throw new Error('中央目录签名不对 @' + offset)
+    const flags = buf.readUInt16LE(offset + 8)
+    const method = buf.readUInt16LE(offset + 10)
+    const crc = buf.readUInt32LE(offset + 16)
+    const compSize = buf.readUInt32LE(offset + 20)
+    const size = buf.readUInt32LE(offset + 24)
+    const nameLen = buf.readUInt16LE(offset + 28)
+    const extraLen = buf.readUInt16LE(offset + 30)
+    const commentLen = buf.readUInt16LE(offset + 32)
+    const localOffset = buf.readUInt32LE(offset + 42)
+    const name = buf.slice(offset + 46, offset + 46 + nameLen).toString('utf8')
+    offset += 46 + nameLen + extraLen + commentLen
+    if (buf.readUInt32LE(localOffset) !== 0x04034b50) throw new Error('本地头签名不对：' + name)
+    const localNameLen = buf.readUInt16LE(localOffset + 26)
+    const localExtraLen = buf.readUInt16LE(localOffset + 28)
+    const dataStart = localOffset + 30 + localNameLen + localExtraLen
+    const raw = buf.slice(dataStart, dataStart + compSize)
+    let data
+    if (method === 0) data = raw
+    else if (method === 8) data = zlib.inflateRawSync(raw)
+    else throw new Error('不支持的压缩方法 ' + method + '：' + name)
+    out.push({ name, flags, method, crc, compSize, size, data })
+  }
+  return out
+}
+
+function crc32Of(buffer) {
+  // Node 24 自带 zlib.crc32，省得在自检里再维护一张表
+  return zlib.crc32(buffer) >>> 0
+}