zipcalm 1.0.1 → 1.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 > 一个跑在 NAS 上的 Node.js 网页服务端：浏览文件目录、选择文件/文件夹压缩（多算法多格式）、按类型去重（硬链接）、带性能监控看板。
 >
-> 当前状态：**M0~M8 已完成 + 硬链接去重已上线 + 硬链接预检提示**（版本 `1.0.1`），二十套验收全绿。手机端 PWA（M9）待做。
+> 当前状态：**M0~M8 已完成 + 硬链接去重已上线 + 硬链接预检提示**（版本 `1.0.3`），二十套验收全绿。手机端 PWA（M9）待做。
 
 ## 界面预览
 
@@ -131,7 +131,7 @@ npm run build   # 构建前端产物到 web/dist
 | **硬链接去重** | ✅ | 按白名单类型扫重复大文件 → 三层判定（`size` 分组 → 头尾+中间抽样**快筛** → **全量 SHA-256 终判**）→ 建硬链接省空间；dry-run 默认 + 强制确认弹窗 + 操作日志；替换走 `rename→link→unlink`，**崩溃时数据始终一份可达** |
 | **硬链接预检提示** | ✅ | 压前用 `dev + ino` 归组识别硬链接（零额外 syscall）：所选格式不保留硬链接且多存占比 ≥10% 时提示「预计产出 / 换 TAR 省多少」，tar 家族给正向说明；纯信息条不阻断，空间与删除判定不变 |
 | **RAR 解压（只读）** | ✅ | 新增 RAR 格式包：**只解压、不生成**（闭源商业算法，未授权不能压缩）；走用户已装的 `unrar`（优先）或 `7z`，缺二进制显式报错并给修复建议；rar4/rar5、多卷、加密（缺密码 / 密码错 / 包损坏三态分开）全支持；条目安全与 zip、tar 共用同一套 zip-slip 判定 |
-| **7z（双向）** | ✅ | 新增 7z 格式包：**可压缩可解压**，走三级回退链 —— 系统 `7z/7za`（本机 p7zip 16.02）→ WASM 引擎（`js7z-tools`，内置 7-Zip 25.01 多线程）→ 不可用（置灰 + 说明）。支持 `-mx0..9` 压缩级别、原生密码（三态错误分离）、条目安全与 zip/tar/rar 同一套；卖点是 **Windows 双击即开**（压缩率实测只比 tar.zst 优约 1%） |
+| **7z（双向）** | ✅ | 新增 7z 格式包：**可压缩可解压**，走三级回退链 —— 系统 `7z/7za`（如 p7zip 16.02）→ WASM 引擎（`js7z-tools`，内置 7-Zip 25.01 多线程）→ 不可用（置灰 + 说明）。支持 `-mx0..9` 压缩级别、原生密码（三态错误分离）、条目安全与 zip/tar/rar 同一套；卖点是 **Windows 双击即开**（压缩率实测只比 tar.zst 优约 1%） |
 | M9 | ⏳ | **手机端 PWA**（可添加到主屏幕；曾评估"做 MT 管理器插件"，两轮调研——文档调研 + APK 逆向——均确认**不可行**：v3 插件只有 editor/translation/regex 三类扩展点，且 `PluginContext` 无用户文件访问能力。详见 `docs/research/mt-apk-reverse-04-借鉴点与结论.md`） |
 
 **已实现能力**（截至 `0.12.1`）：
@@ -171,12 +171,14 @@ npm run build   # 构建前端产物到 web/dist
 
 | 版本 | 里程碑 | 内容 |
 |---|---|---|
-| **1.0.1** | **修 npx 启动** | 修一个让 `npx zipcalm` / 全局安装**完全不可用**的 bug：CLI 的「是否被直接执行」判据只比较 `path.resolve` 的字面路径，而 npm 在 `node_modules/.bin/` 下建的是**符号链接** —— 链接路径与真实路径字面不等，于是 `main()` 不跑、进程**静默 exit 0、零输出、服务不起**。改为比较 `realpath`（解析符号链接）。本机验证时用 `node <真实路径>` 跑所以一路没暴露，直到从 registry 装包跑 npx 才现形；新增 `cli` 套件（7 条）钉住这条，含符号链接调用用例，并已用「回退到旧判据」反向验证该用例确会变红。**同时**：构建不再产出 sourcemap（`.map` 是压缩产物的 5 倍大、且其 `sources` 会带出构建机目录结构），发布包 855 KB → **346 KB**；README 移除机器专属的依赖安装说明与内部参考快照段（此类内容归 `docs/14`） |
+| **1.0.3** | **构建工具链升级 + 依赖收敛** | 构建工具 vite 5→8（打包器改 rolldown）、`@vitejs/plugin-vue` 6；`overrides.glob` 到 `14.0.3`，`npm audit` 10 → 4（剩余为 archiver 链已知风险）；`build-web.mjs` 加固：依赖缓存按 lock 指纹分目录、打包器探测兼容 rolldown；文档补密码压缩的传参契约（`options.capabilities.password`）与 archiver 链风险记录 |
+| **1.0.2** | **识别层外置 + 措辞清理** | 平台识别改由 `sys-id@0.1.0` 提供（`PLATFORM_PROFILE` 映射表仍在本项目，对外接口与行为不变）；公开文档与注释去掉只对单一机型成立的描述（CIFS noexec、无系统 zstd 等改为通用表述）；`prepublishOnly` 改用 `build:web`，在无 `.bin/vite`、原生模块无法加载的工作区也能完成发布前构建 |
+| **1.0.1** | **修 npx 启动** | 修一个让 `npx zipcalm` / 全局安装**完全不可用**的 bug：CLI 的「是否被直接执行」判据只比较 `path.resolve` 的字面路径，而 npm 在 `node_modules/.bin/` 下建的是**符号链接** —— 链接路径与真实路径字面不等，于是 `main()` 不跑、进程**静默 exit 0、零输出、服务不起**。改为比较 `realpath`（解析符号链接）。验证时用 `node <真实路径>` 跑所以一路没暴露，直到从 registry 装包跑 npx 才现形；新增 `cli` 套件（7 条）钉住这条，含符号链接调用用例，并已用「回退到旧判据」反向验证该用例确会变红。**同时**：构建不再产出 sourcemap（`.map` 是压缩产物的 5 倍大、且其 `sources` 会带出构建机目录结构），发布包 855 KB → **346 KB**；README 移除机器专属的依赖安装说明与内部参考快照段（此类内容归 `docs/14`） |
 | **1.0.0** | **npm 首发** | 可 `npx zipcalm` / `npm i -g zipcalm` 运行：新增 CLI（`bin/zipcalm.js`，只做参数→环境变量翻译）、`files` 白名单（只带 `bin/ server/ shared/ web/dist/ README LICENSE`，不含 docs）、首次运行自动生成随机口令配置；数据默认落 `~/.zipcalm`（含 fs-root/trash/logs/tasks.json），**从 git 仓库启动的行为一字未变**（数据仍在 `<项目根>/storage`）。README 里 29 处相对文档/图片链接改为绝对地址（npm 上才不 404） |
 | 0.14.0 | 乱码名还原 | 解压时自动还原 PUA 转义的乱码文件名（共享阶段，zip/tar/7z/rar 通用）；新增 `POST /fs/repair-names` 与 CLI 修复已解压目录（dryRun 默认、绝不覆盖、四类计数）；RAR 引擎强制 `en_US.UTF-8`（默认 locale / C.UTF-8 会输出有损 `?`）；实测六款 RAR 解包库，结论是不换库、只做解码 |
 | 0.13.0 | RAR 双引擎 | RAR 解压引擎改为三级回退（系统 `unrar` → `node-unrar-js@2.0.2` 纯 JS 兜底 → 置灰），新增 `ZC_UNRAR_ENGINE=native\|js` 与 `probe().filenameSafe`。**实测澄清了根因**：RAR5 中文名乱码是 unrar 版本 bug（5.70 坏 / 7.23 好），而 js 引擎内置的 6.1.7 **同样坏** → 换引擎修不了文件名，因此**有原生 unrar 时仍优先原生**（它还能正确报损坏包，js 会静默部分解出）。版本判 minor：新增引擎与依赖、影响部署面（没装 unrar 的机器从"不可用"变"可用"） |
-| 0.12.1 | 7z 双引擎 | 接入回退② **WASM 引擎 `js7z-tools@2.5.0`（7-Zip 25.01）**：没装 p7zip 的机器也能压缩/解压 7z，产物与原生引擎**双向兼容**（同输入同尺寸、互解互验通过）。实现要点：每次操作独立子进程、严格等 `onExit`（MT 异步语义）再读产物；`ZC_7Z_DISABLE_WASM=1` 可关；单任务输入 >2 GB 提前拒绝并建议 tar.zst；CPU 默认绑「总核数 − 1」+ `nice` + 全局串行（这是本机 CPU 过载 503 事故的直接修复）。版本判 patch：对外仍是"7z 双向"，变的是引擎覆盖范围 |
-| 0.12.0 | 7z（双向） | 新增 7z 格式包（`server/plugins/formats/sevenzip/`）：可压缩可解压；三级引擎回退（系统 7z/7za → WASM `js7z-tools`（本版未接入，0.12.1 补齐）→ 不可用）；`-mx0..9` 级别透传；原生密码三态分离；条目安全复用共享判定；压缩用"条目名走 argv 分批"（本机 p7zip 16.02 是 `Utf16=off` 构建，读 UTF-8 listfile 的中文名会失败） |
+| 0.12.1 | 7z 双引擎 | 接入回退② **WASM 引擎 `js7z-tools@2.5.0`（7-Zip 25.01）**：没装 p7zip 的机器也能压缩/解压 7z，产物与原生引擎**双向兼容**（同输入同尺寸、互解互验通过）。实现要点：每次操作独立子进程、严格等 `onExit`（MT 异步语义）再读产物；`ZC_7Z_DISABLE_WASM=1` 可关；单任务输入 >2 GB 提前拒绝并建议 tar.zst；CPU 默认绑「总核数 − 1」+ `nice` + 全局串行（这是 CPU 过载 503 事故的直接修复）。版本判 patch：对外仍是"7z 双向"，变的是引擎覆盖范围 |
+| 0.12.0 | 7z（双向） | 新增 7z 格式包（`server/plugins/formats/sevenzip/`）：可压缩可解压；三级引擎回退（系统 7z/7za → WASM `js7z-tools`（本版未接入，0.12.1 补齐）→ 不可用）；`-mx0..9` 级别透传；原生密码三态分离；条目安全复用共享判定；压缩用"条目名走 argv 分批"（p7zip 16.02 是 `Utf16=off` 构建，读 UTF-8 listfile 的中文名会失败） |
 | 0.11.0 | RAR 解压（只读） | 新增 RAR 格式包（`server/plugins/formats/rar/`）：**只解压不生成**（闭源商业算法，`create()`/`estimate()` 显式拒绝）；解压走外部 `unrar`（优先）/`7z`（兜底），二进制缺失时置灰并给安装建议；rar4/rar5、多卷、加密包（`MISSING_PASSWORD` / `BAD_PASSWORD` / `ARCHIVE_CORRUPTED` 三态分离）；外部程序先解到中转目录，再经共享条目判定（zip-slip / 绝对路径 / 符号链接 / 不覆盖）搬入目标目录；进度按文件级降级上报 |
 | 0.10.1 | 硬链接预检提示 | 预检按 `dev + ino` 归组统计硬链接（跨分区同 `ino` 不误判、黑名单跳过项不计入、嵌套选择不重复计数）；所选格式不保留硬链接且多存占比 ≥10% 时在压缩抽屉提示「预计产出 / 换 TAR 只存一份省多少」，tar 家族给正向说明；纯提示不阻断、不改空间判定与删除逻辑 |
 | 0.10.0 | 能力插件 + 压缩密码 | 新增「能力插件」扩展点：格式插件用 `capabilities` 声明能力、能力插件按目录自注册、加密算法可继续追加；落地压缩包密码（AES-256 / ZipCrypto），含压完同密码自测、明文三通道脱敏（API / `tasks.json` / 日志）、删除前复核密码可解；解压侧支持加密包（AES-256 与 ZipCrypto 走 7z 解包 + 白名单搬移，缺密码 / 密码错 / 包损坏三态区分） |

package/bin/zipcalm.js

@@ -95,7 +95,7 @@ export function lanAddress() {
 /**
  * 首次运行引导：数据目录里没有 config.json 时，生成一份**带随机口令**的最小配置。
  *
- * 为什么必须做：仓库里那份 config.json 是 gitignore 的运行态文件（含本机口令），**不会进 npm 包**；
+ * 为什么必须做：仓库里那份 config.json 是 gitignore 的运行态文件（含运行机器的口令），**不会进 npm 包**；
  * 而配置校验要求 auth.password 或 auth.passwordHash 二选一，缺了就启动失败。
  * 这里给新用户生成随机口令并打印一次 —— 比内置默认口令安全（不会所有人都是 admin/zipcalm）。
  *

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "zipcalm",
-  "version": "1.0.1",
+  "version": "1.0.3",
+  "description": "跑在 NAS 上的网页版文件管理与压缩工具：浏览、压缩、解压、按内容去重，含任务队列与性能看板",
   "private": false,
   "type": "module",
   "engines": {
@@ -9,9 +10,11 @@
   "scripts": {
     "dev": "vite --config web/vite.config.js",
     "build": "node scripts/check-drift.js && vite build --config web/vite.config.js",
+    "build:web": "node scripts/build-web.mjs",
     "preview": "vite preview --config web/vite.config.js",
     "start": "node server/boot.js",
-    "check:drift": "node scripts/check-drift.js"
+    "check:drift": "node scripts/check-drift.js",
+    "prepublishOnly": "npm run build:web"
   },
   "bin": {
     "zipcalm": "bin/zipcalm.js"
@@ -24,7 +27,6 @@
     "README.md",
     "LICENSE"
   ],
-  "prepublishOnly": "npm run build",
   "dependencies": {
     "@fastify/cookie": "^11.1.3",
     "@fastify/static": "^10.1.6",
@@ -38,6 +40,7 @@
     "node-unrar-js": "2.0.2",
     "pinia": "2.3.1",
     "pretty-bytes": "6.1.0",
+    "sys-id": "0.1.0",
     "tar": "^7.5.1",
     "unzipper": "0.12.5",
     "uplot": "^1.6.32",
@@ -45,15 +48,14 @@
     "vue-router": "4.6.4"
   },
   "devDependencies": {
-    "vite": "^5",
-    "@vitejs/plugin-vue": "^5"
+    "@vitejs/plugin-vue": "6.0.10",
+    "vite": "8.3.5"
   },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/EIGHTfs/ZipCalm.git"
   },
-  "license": "MIT",
-  "author": "EIGHTfs",
   "keywords": [
     "nas",
     "compression",
@@ -62,5 +64,9 @@
     "zstd",
     "synology",
     "self-hosted"
-  ]
+  ],
+  "author": "EIGHTfs",
+  "overrides": {
+    "glob": "^14.0.3"
+  }
 }

package/server/core/auth/password.js

@@ -1,7 +1,7 @@
 // 密码哈希（scrypt，Node 内置，零依赖）
 //
 // 为什么不用明文比较、也不引 bcrypt：NAS 上不想再引原生编译依赖（项目原则：优先成熟库，但
-// 这里的"成熟库"bcrypt/argon2 都要原生编译，在本机 noexec/NFS 环境下风险高）。
+// 这里的"成熟库"bcrypt/argon2 都要原生编译，在 noexec 挂载等受限环境下风险高）。
 // Node 内置 scrypt 属标准方案，格式自带参数，便于将来升级参数而不破坏老哈希。
 //
 // 存储格式：scrypt$N$r$p$<salt-base64>$<hash-base64>

package/server/core/engineRunner.js

@@ -1,7 +1,7 @@
 // 外部引擎统一执行入口（**所有** 走外部程序/WASM 的格式插件都必须经这里）
 //
 // 为什么要有这一层（而不是各插件自己 spawn）：
-//   限核、超时硬杀、全局串行是**部署环境约束**（本机只有 3 核，跑满会触发宿主"系统 CPU 过载"保护，
+//   限核、超时硬杀、全局串行是**部署环境约束**（CPU 核数少的机器上跑满会触发宿主"系统 CPU 过载"保护，
 //   实测已造成过一次 503），不是某个格式的特性。散在各插件里 → 每加一个格式就漏一次；
 //   各插件各有一把串行锁时，7z 任务与 RAR 任务还能同时跑，一起把 CPU 打满。
 //
@@ -12,7 +12,7 @@
 //   ① 应用层线程数：7z 原生 `-mmt=N`（产物 md5 与线程数无关，实测一致）。
 //      但 **unrar 没有线程参数、7z WASM 库内固定 3 线程**，所以这一层不能兜底，只能锦上添花。
 //   ② OS 级绑核：Linux `taskset -c <list>`（实测可把 Cpus_allowed_list 收到指定核）；
-//      Windows 可用 PowerShell 启动后设 `ProcessorAffinity`（**本机无 Windows，未实测**）；
+//      Windows 可用 PowerShell 启动后设 `ProcessorAffinity`（**当前环境无 Windows，未实测**）；
 //      **macOS 没有可用绑核手段**（taskpolicy 只调 QoS、cpuset 是 FreeBSD 的）→ 如实跳过。
 //   ③ 优先级：Linux/macOS `nice -n 10`；Windows `PriorityClass = Idle`。
 //
@@ -174,7 +174,7 @@ export function detectStrategy(probe = {}) {
  *   - Linux 的 `taskset`/`nice` 是 exec 直通，退出码就是引擎的退出码 ✅
  *   - Windows 的 `cmd /c start /wait` **不保证透传子进程退出码**（start 返回的是自身结果），
  *     所以这里**不用 start**，改用 PowerShell：`Start-Process -Wait -PassThru` 后读 `ExitCode` 并 `exit`，
- *     这样拿到的才是引擎的退出码。⚠️ 该分支未在真机验证（本机只有 Linux），已在 docs/17 登记。
+ *     这样拿到的才是引擎的退出码。⚠️ 该分支未在真机验证（开发环境只有 Linux），已在 docs/17 登记。
  *
  * @param {{command: string, args: string[]}} spec
  * @param {{strategy?: object, cores?: number, cpuList?: string, mask?: string}} [context]

package/server/core/fs/platformProfile.js

@@ -0,0 +1,167 @@
+// 平台画像：系统判断 + 侧栏模式 + 显示文案 + 根发现策略的**唯一入口**
+//
+// 为什么单独抽一个文件：这三件事原本散在四处知识里 ——
+//   ① roots.js 的两个枚举（PLATFORMS / SIDEBAR_MODES）
+//   ② roots.js 的 detectPlatform()（群晖特征文件常量也在这里）
+//   ③ roots.js 的 sidebarModeOf() 与 listRoots() 里的 if/else（决定根从哪来）
+//   ④ 前端 Sidebar.vue 里写死的「模式 → 标题」映射
+// 结果是「同一台机器该显示什么」由四处各自回答，加一个平台要改四个地方，必然漂移。
+//
+// 收敛后的规则：任何「这是什么系统 → 侧栏怎么显示 → 根从哪来」的判断，
+// **只允许**由 resolvePlatformProfile() 回答；其余模块（含前端）只消费它的返回值。
+//
+// 分工（识别层 / 表现层）：
+//   - **识别层**由 `sys-id` 提供（它判断"这是什么系统"，返回大写身份如 Synology / Linux）；
+//   - **表现层**（身份 → 侧栏模式 / 标题 / 根发现策略）是本项目的资产，留在下面的画像表里。
+// 换识别实现只动 detectPlatform 内部，画像表与所有调用方不变。
+
+import fs from 'node:fs';
+
+import { detectPlatform as detectSysIdPlatform } from 'sys-id';
+
+/** 平台常量（将来接入独立探测包时，这张表由包的规则数据取代） */
+export const PLATFORMS = Object.freeze({ SYNOLOGY: 'synology', WINDOWS: 'windows', POSIX: 'posix' });
+
+/** 侧栏模式：B = 列卷（默认）；C = 列共享文件夹（群晖） */
+export const SIDEBAR_MODES = Object.freeze({ VOLUMES: 'B', SHARES: 'C' });
+
+/** 群晖特征文件（docs/16 §2.1 实测依据） */
+const SYNOLOGY_MARKER = '/etc/synoinfo.conf'; // dsh-skip-sensitive
+
+/** 系统目录前缀：@appdata / @eaDir / #recycle 等不是用户数据目录 */
+const DEFAULT_SYSTEM_DIR_PREFIXES = Object.freeze(['@', '#']);
+
+/**
+ * 平台画像表：一个平台一行，决定它在界面上长什么样、根从哪来。
+ *
+ * 每个字段的用途：
+ *   mode              侧栏模式（B = 卷 / C = 共享）
+ *   volumeLabel       侧栏标题 —— 由后端下发，前端不再自己判断
+ *   rootsStrategy     根发现策略：`shares` 扫共享 / `volumes` 扫卷与挂载点
+ *   systemDirPrefixes 扫描时要排除的系统目录前缀
+ *   volumePattern     卷目录名的匹配规则
+ *
+ * 加平台 = 在这张表加一行 + 在 PLATFORMS 加一个值（等独立包接入后，连这一步都省掉）。
+ */
+export const PLATFORM_PROFILE = Object.freeze({
+  [PLATFORMS.SYNOLOGY]: Object.freeze({
+    mode: SIDEBAR_MODES.SHARES,
+    volumeLabel: '位置',
+    rootsStrategy: 'shares',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+  [PLATFORMS.WINDOWS]: Object.freeze({
+    mode: SIDEBAR_MODES.VOLUMES,
+    volumeLabel: '存储卷',
+    rootsStrategy: 'volumes',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+  [PLATFORMS.POSIX]: Object.freeze({
+    mode: SIDEBAR_MODES.VOLUMES,
+    volumeLabel: '存储卷',
+    rootsStrategy: 'volumes',
+    systemDirPrefixes: DEFAULT_SYSTEM_DIR_PREFIXES,
+    volumePattern: /^\/volume\d+$/,
+  }),
+});
+
+/** 未知平台一律回落 POSIX 画像：宁可显示成普通 Linux，也不能白屏 */
+const FALLBACK_PROFILE = PLATFORM_PROFILE[PLATFORMS.POSIX];
+
+/**
+ * 本项目小写强制值 → sys-id 身份（大写）。
+ * `posix` 落到 `Linux` 身份：本项目用它表示「非群晖、非 Windows」的通用表现。
+ */
+const FORCE_ENV_TO_IDENTITY = Object.freeze({
+  [PLATFORMS.SYNOLOGY]: 'Synology',
+  [PLATFORMS.WINDOWS]: 'Windows',
+  [PLATFORMS.POSIX]: 'Linux',
+});
+
+/**
+ * sys-id 身份 → 本项目枚举。
+ * 只有群晖与 Windows 需要区别对待；其余身份（Linux/macOS/fnOS/Unknown/未来新增）都是 posix。
+ */
+const IDENTITY_TO_PLATFORM = Object.freeze({
+  Synology: PLATFORMS.SYNOLOGY,
+  Windows: PLATFORMS.WINDOWS,
+});
+
+/**
+ * 平台探测：把识别工作交给 sys-id，本文件只维护「身份 → 本项目枚举」的映射。
+ *
+ * 三条与既有契约相关的处理（都不能省）：
+ *   1. 身份大写、本项目枚举小写 —— 只有 Synology / Windows 有专属枚举，
+ *      其余身份（Linux / macOS / fnOS / Unknown / 将来新增的平台）一律落到 posix，
+ *      因为界面只需要区分「群晖（列共享）/ Windows / 其他（列卷）」三种表现；
+ *   2. 强制值方向相反 —— 本项目环境变量是小写，sys-id 的 force 要大写身份，
+ *      `posix` 对应 sys-id 的 `Linux` 身份；不在映射表里的值**不传 force**，走正常探测；
+ *   3. sys-id 对非法 force 会抛错，而本项目既有契约是「非法强制值回落真实探测、不抛错」，
+ *      所以必须 try/catch 兜住。
+ *
+ * 保留最后一层本地兜底：sys-id 自身异常（规则目录缺失等）时不能让整个页面挂掉。
+ *
+ * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
+ */
+export function detectPlatform({ env = process.env, existsSync = fs.existsSync } = {}) {
+  const forced = env.ZIPCALM_FORCE_PLATFORM;
+  const forcedIdentity = FORCE_ENV_TO_IDENTITY[forced];
+  // sys-id 返回 { <身份>: {...} }，识别场景下只有一个键
+  const identify = (force) => Object.keys(detectSysIdPlatform([], {
+    env,
+    existsSync,
+    ...(force ? { force } : {}),
+  }))[0];
+
+  try {
+    return IDENTITY_TO_PLATFORM[identify(forcedIdentity)] || PLATFORMS.POSIX;
+  } catch {
+    // 强制值不可用（sys-id 认为非法）或识别过程出错：**不抛错**，按无 force 重探一次
+    try {
+      return IDENTITY_TO_PLATFORM[identify(undefined)] || PLATFORMS.POSIX;
+    } catch {
+      return detectPlatformLocally(existsSync);
+    }
+  }
+}
+
+/** 最后兜底：sys-id 完全不可用时的最小识别（保证不抛错、不白屏） */
+function detectPlatformLocally(existsSync) {
+  try {
+    if (existsSync(SYNOLOGY_MARKER)) return PLATFORMS.SYNOLOGY;
+  } catch {
+    // 探测失败按「不是群晖」处理
+  }
+  return process.platform === 'win32' ? PLATFORMS.WINDOWS : PLATFORMS.POSIX;
+}
+
+/**
+ * 平台 → 侧栏模式。
+ * 保留这个导出是为了不破坏既有调用方；**内部已改走画像表**，不再单独写一遍判断。
+ */
+export function sidebarModeOf(platform) {
+  return (PLATFORM_PROFILE[platform] || FALLBACK_PROFILE).mode;
+}
+
+/**
+ * **唯一入口**：一次给出「平台 + 该平台在界面上的一切表现」。
+ *
+ * 调用方拿到后不要再自己判断平台 —— 需要什么字段就用返回体里的：
+ *   const { platform, mode, volumeLabel, rootsStrategy, systemDirPrefixes, volumePattern } = resolvePlatformProfile();
+ *
+ * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
+ */
+export function resolvePlatformProfile({ env = process.env, existsSync = fs.existsSync } = {}) {
+  const platform = detectPlatform({ env, existsSync });
+  const profile = PLATFORM_PROFILE[platform] || FALLBACK_PROFILE;
+  return {
+    platform,
+    mode: profile.mode,
+    volumeLabel: profile.volumeLabel,
+    rootsStrategy: profile.rootsStrategy,
+    systemDirPrefixes: profile.systemDirPrefixes,
+    volumePattern: profile.volumePattern,
+  };
+}

package/server/core/fs/roots.js

@@ -1,58 +1,40 @@
-// 存储根发现（docs/16）：平台探测 → 侧栏模式 → 卷/共享列表
+// 存储根发现（docs/16）：按平台画像决定根从哪来
 //
 // 心智模型（docs/16 §一）：本项目的「根」不是文件系统 `/`，而是**可配置的存储根**。
 // NAS 用户想的是"照片在哪个共享"，桌面用户想的是"先看卷"——所以两套数据源、同一个形状：
 //   B 模式（非群晖）：卷 / 挂载点（/volume1、/mnt/data）
 //   C 模式（群晖）：  /volumeN 下的共享文件夹（排除 @ / # 开头的系统目录）
 //
+// **平台判断不在本文件**：`PLATFORMS` / `SIDEBAR_MODES` / `detectPlatform` / `sidebarModeOf`
+// 全部由 `platformProfile.js` 提供（本文件只做 re-export 兼容既有调用方）。
+// 本文件只负责「拿到画像后怎么扫根」。
+//
 // 所有失败都降级：扫不到就空列表、statfs 失败就容量 null —— 列卷失败绝不能让文件页打不开。
 
-import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 
 import { ERROR_CODES, apiError } from '../../lib/errors.js';
+import {
+  PLATFORMS,
+  SIDEBAR_MODES,
+  detectPlatform,
+  resolvePlatformProfile,
+  sidebarModeOf,
+} from './platformProfile.js';
+
+// 兼容导出：既有调用方/测试脚本仍从 roots.js 取这些名字，签名与语义保持不变
+export { PLATFORMS, SIDEBAR_MODES, detectPlatform, sidebarModeOf };
 
-/** 平台常量（将来加厂商在这里加一个值即可） */
-export const PLATFORMS = Object.freeze({ SYNOLOGY: 'synology', WINDOWS: 'windows', POSIX: 'posix' });
-/** 侧栏模式：B = 列卷（默认）；C = 列共享文件夹（群晖） */
-export const SIDEBAR_MODES = Object.freeze({ VOLUMES: 'B', SHARES: 'C' });
 /** 默认根在列表里的固定 id */
 export const DEFAULT_ROOT_ID = 'default';
 
-/** 群晖特征文件（docs/16 §2.1 实测依据） */
-const SYNOLOGY_MARKER = '/etc/synoinfo.conf';
-/** 群晖系统目录前缀：@appdata / @eaDir / #recycle 等不是共享 */
-const SYSTEM_DIR_PREFIX = /^[@#]/;
 /** B 模式的挂载点形态：/mnt/<name>、/media/<name>（只认一级，不认子目录） */
 const MOUNT_POINT_ONE_LEVEL = /^\/(mnt|media)\/[^/]+$/;
-/** 群晖卷名规则：/volume1 /volume2 ... */
-const SYNOLOGY_VOLUME = /^\/volume\d+$/;
 
 const statfsOf = (target) => fsp.statfs(target);
 const readdirOf = (target) => fsp.readdir(target, { withFileTypes: true });
 
-/**
- * 平台探测：环境变量覆盖优先（测试必需），其次群晖特征文件，最后按 Node platform 归类。
- * @param {{env?: object, existsSync?: (p: string) => boolean}} [options]
- */
-export function detectPlatform({ env = process.env, existsSync = fs.existsSync } = {}) {
-  const forced = env.ZIPCALM_FORCE_PLATFORM;
-  if (forced === PLATFORMS.SYNOLOGY || forced === PLATFORMS.POSIX || forced === PLATFORMS.WINDOWS) return forced;
-  try {
-    if (existsSync(SYNOLOGY_MARKER)) return PLATFORMS.SYNOLOGY;
-  } catch {
-    // 探测失败按"不是群晖"处理：回退 B 模式，不能因为探测异常让整个页面挂掉
-  }
-  if (process.platform === 'win32') return PLATFORMS.WINDOWS;
-  return PLATFORMS.POSIX;
-}
-
-/** 平台 → 侧栏模式（未知/将来厂商：默认 B，绝不白屏） */
-export function sidebarModeOf(platform) {
-  return platform === PLATFORMS.SYNOLOGY ? SIDEBAR_MODES.SHARES : SIDEBAR_MODES.VOLUMES;
-}
-
 /** 容量（statfs）；拿不到就两项都 null —— 契约要求降级不报错 */
 export async function rootStats(absPath) {
   try {
@@ -90,35 +72,38 @@ async function readMountPoints() {
   }
 }
 
+/** 顶层卷目录（/volumeN）—— 匹配规则由画像表提供，避免本文件另写一份 */
+async function listVolumeRoots(profile) {
+  const found = [];
+  for (const dirName of await listSubdirs('/')) {
+    const absPath = `/${dirName}`;
+    if (profile.volumePattern.test(absPath)) found.push(absPath);
+  }
+  return found.sort();
+}
+
 /**
  * B 模式：自动发现卷/挂载点。
- * 规则：/volumeN + /proc/mounts 里的 /mnt|/media 挂载点（去重，按路径排序）。
+ * 规则：画像表认可的 /volumeN + /proc/mounts 里的 /mnt|/media 挂载点（去重，按路径排序）。
  * 为什么不全用 /proc/mounts：容器里它会列出一堆伪文件系统（proc/sysfs/tmpfs），对用户无意义。
  */
-async function discoverVolumeDirs() {
-  const found = new Set();
-  for (const dirName of await listSubdirs('/')) {
-    if (/^volume\d+$/.test(dirName)) found.add(`/${dirName}`);
-  }
+async function discoverVolumeDirs(profile) {
+  const found = new Set(await listVolumeRoots(profile));
   // 只认"真正挂载了的"一级目录：/mnt/data、/media/usb 这种。
   // 不能拿 /mnt/* 的**子目录**当卷 —— 很多机器 /mnt 本身就是一个挂载点，里面全是普通目录（实测踩过）。
   for (const mountPoint of await readMountPoints()) {
     if (MOUNT_POINT_ONE_LEVEL.test(mountPoint)) found.add(mountPoint);
-    if (SYNOLOGY_VOLUME.test(mountPoint)) found.add(mountPoint);
+    if (profile.volumePattern.test(mountPoint)) found.add(mountPoint);
   }
   return [...found].sort();
 }
 
-/** C 模式：/volumeN 下的共享文件夹（排除 @ / # 系统目录） */
-async function discoverShares() {
-  const volumes = [];
-  for (const dirName of await listSubdirs('/')) {
-    if (/^volume\d+$/.test(dirName)) volumes.push(`/${dirName}`);
-  }
+/** C 模式：/volumeN 下的共享文件夹（排除画像表里的系统目录前缀，以及点开头的噪音目录） */
+async function discoverShares(profile) {
   const shares = [];
-  for (const volumeAbs of volumes.sort()) {
+  for (const volumeAbs of await listVolumeRoots(profile)) {
     for (const name of await listSubdirs(volumeAbs)) {
-      if (SYSTEM_DIR_PREFIX.test(name)) continue;
+      if (profile.systemDirPrefixes.some((prefix) => name.startsWith(prefix))) continue;
       // 点开头的目录（.pnpm-store / .git / .Trash …）对用户是噪音：
       // DSM 的共享文件夹本来就不会以点开头，列出来只会让列表变脏。
       if (name.startsWith('.')) continue;
@@ -131,14 +116,15 @@ async function discoverShares() {
 /**
  * 构造根列表。
  * - 配置了 storage.roots → 直接用（两种模式都用它；显式配置优先于自动发现）
- * - C 模式且没配置 → 扫共享；扫不到任何共享 → 回退列出默认根（避免侧栏空白）
- * - B 模式且没配置 → 扫卷；扫不到 → 只列默认根
+ * - rootsStrategy=shares 且没配置 → 扫共享；扫不到任何共享 → 回退列出默认根（避免侧栏空白）
+ * - rootsStrategy=volumes 且没配置 → 扫卷；扫不到 → 只列默认根
  * - ZIPCALM_SHOW_APP_ROOT=1 → 任何模式都额外列出默认根（标注「应用数据」）
+ *
+ * 返回体除根列表外还带 `volumeLabel`（侧栏标题由后端下发，前端不再自己判断平台）。
  * @param {{storage: object, env?: object}} options
  */
 export async function listRoots({ storage, env = process.env }) {
-  const platform = detectPlatform({ env });
-  const mode = sidebarModeOf(platform);
+  const profile = resolvePlatformProfile({ env });
   const configured = Array.isArray(storage.roots) && storage.roots.length > 0
     ? storage.roots.map((root) => ({ id: root.id, label: root.label || root.id, path: root.path }))
     : null;
@@ -147,11 +133,11 @@ export async function listRoots({ storage, env = process.env }) {
   let roots;
   if (configured) {
     roots = configured;
-  } else if (mode === SIDEBAR_MODES.SHARES) {
-    const shares = await discoverShares();
+  } else if (profile.rootsStrategy === 'shares') {
+    const shares = await discoverShares(profile);
     roots = shares.length > 0 ? shares : [defaultRoot];
   } else {
-    const volumes = await discoverVolumeDirs();
+    const volumes = await discoverVolumeDirs(profile);
     roots = volumes.length > 0
       ? volumes.map((volumePath) => ({ id: volumePath.replace(/^\/+/, ''), label: path.basename(volumePath), path: volumePath }))
       : [defaultRoot];
@@ -163,7 +149,14 @@ export async function listRoots({ storage, env = process.env }) {
   }
 
   const withStats = await Promise.all(roots.map(async (root) => ({ ...root, ...(await rootStats(root.path)) })));
-  return { platform, mode, roots: withStats, canSwitch: withStats.length > 1 };
+  return {
+    platform: profile.platform,
+    mode: profile.mode,
+    // 侧栏标题的唯一来源：平台画像 → 后端下发 → 前端只渲染
+    volumeLabel: profile.volumeLabel,
+    roots: withStats,
+    canSwitch: withStats.length > 1,
+  };
 }
 
 /**

package/server/plugins/capabilities/password/index.js

@@ -104,7 +104,7 @@ export default {
     // 统一走 7z 试解：
     // unzipper 只有 ZipCrypto 的解密实现，AES-256 包（compressionMethod=99）会被它
     // 当成普通 inflate 解读 → 报「inflate 失败/坏数据」或 BAD_PASSWORD，属**假阴性**。
-    // 7-Zip 两种加密都能读，且本机与 NAS 上通常都有；探测不到时明确报错，不静默放行。
+    // 7-Zip 两种加密都能读，且本地环境与 NAS 上通常都有；探测不到时明确报错，不静默放行。
     return verifyWith7z(archivePath, params.password);
   },
 

package/server/plugins/formats/rar/index.js

@@ -314,7 +314,7 @@ export default {
    *
    * 为什么必须由本插件提供、而不是让编排层统一用 7z：
    * p7zip 16.02 读不了加密 RAR5（实测报 `Can not open the file as archive`），
-   * 而本机 `unrar 5.70` 可以。工具能力按格式不同，这个知识属于插件自己。
+   * 而 `unrar 5.70` 可以（实测）。工具能力按格式不同，这个知识属于插件自己。
    *
    * @param {string} archivePath
    * @param {string} password

package/server/plugins/formats/rar/unrar.js

@@ -8,7 +8,7 @@
 // - 缺密码与错密码在 unrar 侧**同为 exit 11 + 同一句提示**，无法从输出区分 —— 只能由调用方
 //   根据"我们有没有传密码"来判定 MISSING_PASSWORD / BAD_PASSWORD（三态口径见 P4）
 // - 损坏包 exit 1（"Unexpected end of archive" / "Total errors: N"）
-// - p7zip 16.02 对 rar5 返回 exit 2（本机实测），所以 **unrar 是唯一可靠后端**，7z 仅作兜底
+// - p7zip 16.02 对 rar5 返回 exit 2（实测），所以 **unrar 是唯一可靠后端**，7z 仅作兜底
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';

package/server/plugins/formats/sevenzip/engine.js

@@ -1,6 +1,6 @@
 // 7z 外部引擎封装（三级回退：系统 7z/7za → WASM 引擎 → 不可用）
 //
-// 为什么先探测系统二进制：本机 `/bin/7z`（p7zip 16.02）零新增依赖、零加载开销，
+// 为什么先探测系统二进制：系统 `/bin/7z`（p7zip 16.02）零新增依赖、零加载开销，
 // 只有部署机上没有 7z 时才需要 WASM 兜底（WASM 引擎需额外依赖，见 docs/18 §附四）。
 //
 // 实测事实（p7zip 16.02，本项目验证环境）：
@@ -52,7 +52,7 @@ export async function makeLocalWorkDir(prefix) {
 /**
  * 把本地盘上的文件搬到目标路径（可能是 CIFS 网络盘）。
  *
- * **不能用 `fs.copyFile`**：本机 CIFS 挂载上它必报 `EPERM: operation not permitted, copyfile`
+ * **不能用 `fs.copyFile`**：CIFS 挂载上它必报 `EPERM: operation not permitted, copyfile`
  * （实测 copyFile / COPYFILE_EXCL 都失败，而 `readFile+writeFile` 与流式 pipeline 都成功）。
  * 这里用流式管道：内存占用与文件大小无关，适合大压缩包。
  */
@@ -61,7 +61,7 @@ export async function copyLocalToTarget(sourcePath, targetPath) {
 }
 
 // CPU 纪律（绑核「总核数 − 1」+ nice + 全局串行）统一由 `server/core/engineRunner.js` 提供，与 7z 共用同一把锁。
-// 这是部署环境约束（本机 3 核、跑满会触发宿主保护），不是 7z 私有实现，RAR 的 js 引擎同样要用。
+// 这是部署环境约束（CPU 核数少的机器上跑满可能影响系统响应），不是 7z 私有实现，RAR 的 js 引擎同样要用。
 
 /** 探测结果缓存（60s，与格式注册表的可用性缓存同频） */
 const PROBE_TTL_MS = 60 * 1000;

package/server/plugins/formats/sevenzip/index.js

@@ -1,7 +1,7 @@
 // 7z 格式包（**双向**：可压缩、可解压）
 //
 // 引擎：三级回退链（见 engine.js 与 docs/18 §附四）——
-//   ① 系统 7z / 7za（本机 p7zip 16.02）→ 默认走这条，零新增依赖
+//   ① 系统 7z / 7za（如 p7zip 16.02）→ 默认走这条，零新增依赖
 //   ② WASM 引擎（js7z-tools，MT）→ **尚未接入调用适配**（依赖需额外安装，见 docs/17 D-7）
 //   ③ 都没有 → available=false + unavailableReason 说明
 //
@@ -287,7 +287,7 @@ async function create(ctx) {
   const outputPath = localWorkDir ? path.join(localWorkDir, path.basename(ctx.tempPath)) : ctx.tempPath;
 
   // 逐个源、分批把条目名当**命令行参数**传给 7z（cwd = 源的父目录，条目名即"源名/子路径"）。
-  // 为什么不用 `-i@listfile`：本机 p7zip 16.02 是 `Utf16=off` 构建，读 UTF-8 listfile 里的中文名会报
+  // 为什么不用 `-i@listfile`：p7zip 16.02 是 `Utf16=off` 构建，读 UTF-8 listfile 里的中文名会报
   // `????: No more files`（实测），而中文名走 argv 是正常的。分批是为了避免参数过长撞 ARG_MAX。
   const MAX_ARGS_CHARS = 60000;
   for (const group of plan.perSource) {

package/shared/app-version.js

@@ -4,4 +4,4 @@
 // "接口报的版本与界面显示的版本不一致"这种最难查的漂移（审计的 duplicate-constant-def 会命中）。
 // 放置位置：项目根的 shared/ —— web 通过 vite 别名 @shared 引入，server 用相对路径引入。
 
-export const APP_VERSION = '1.0.1';
+export const APP_VERSION = '1.0.3';