docs(desktop): document archive tool failure diagnostics

apps/desktop/packaging/README.i18n.yaml

@@ -24,8 +24,8 @@
   en: 5b4f0f80a117f202
   zh: ff05be196c181087
 /desktop-packaging/windows-actions-packaging:
-  en: 7bd0f4aa899a7295
-  zh: a27c75934844123d
+  en: 96ad794fcdd65653
+  zh: 302c869400d621e3
 /desktop-packaging/macos-self-hosted-packaging:
   en: 08619f0e26782636
   zh: 7c236cbe46be4a47

apps/desktop/packaging/README.md

@@ -117,6 +117,8 @@ All Windows packaging modes, including test and unsigned, require the repository
 
 Open the completed run in Actions and download its Artifacts from the independent `upload-artifact` job. Installer names use the original `package_run_attempt`; diagnostic names use the current `run_attempt`. If archival fails after packaging succeeds, rerun only `upload-artifact` to reuse the retained installers. `windows-x64-signed-<version>-<run_id>-<package_run_attempt>.zip` and `windows-x64-unsigned-<version>-<run_id>-<package_run_attempt>.zip` contain the corresponding EXE; `windows-package-logs-<run_id>-<run_attempt>` contains packaging diagnostics. Installer ZIPs record each retained copy’s modification time as local time in the DOS field and absolute time in the Unix field; this is not a guarantee of the original build time. The upload steps are `Retain installers for the selected mode` and `Retain packaging diagnostics`; their step durations and timestamped logs show upload time. These artifacts are not a Release or download-site publication.
 
+The archival job creates a store-mode ZIP with system bsdtar: `%SystemRoot%\System32\tar.exe` on Windows (`SystemRoot` is required), or `/usr/bin/tar` on macOS. `invalid ZIP output settings` rejects missing or invalid archive name, retained directory, temporary directory or output-file settings before file verification. `ZIP creation failed with <tar>` identifies the failed archive tool; inspect its stderr, tool availability and free space in `RUNNER_TEMP`. If packaging succeeded, fix the archival prerequisite and rerun only `upload-artifact` using the retained installers.
+
 For cache measurements, `cache_namespace` selects a retained subdirectory for both dependency stores and upstream downloads; leave it empty for normal shared caches. Use a new name for a cold sample and repeat that name for warm samples. Names contain 1–64 lowercase letters, digits or hyphens, start with a letter or digit, and cannot be Windows device names. This does not reset the separate signature cache or OS file cache; report those states and Job start-to-completion time alongside phase timings and artifact size. Before dependency installation, the workflow records the Node version, available CPU parallelism, logical CPU count, and total/free memory.
 
 The dependency-install and packaging steps normalize their own shell to normal CPU, I/O and memory priority before launching children. The priority helper is copied from the exact workflow commit into a run-specific temporary directory, independently of the selected product source. A missing helper stops CI setup; unavailable priority adjustment emits a warning and marks scheduling unsuitable for performance comparison, but does not stop packaging. This does not modify the runner task or other processes. Version, preset and retained-artifact adapters remain tied to product source and its formats.

apps/desktop/packaging/README.zh.md

@@ -117,6 +117,8 @@ runner 的受监督启动和恢复见 [Windows runner 机器准备](../windows-s
 
 在 Actions 打开完成的运行，下载独立 `upload-artifact` job 生成的 Artifacts。安装包名称使用原构建的 `package_run_attempt`，诊断名称使用当前 `run_attempt`。打包成功但归档失败时，仅重跑 `upload-artifact` 以复用保留的安装包。`windows-x64-signed-<version>-<run_id>-<package_run_attempt>.zip` 与 `windows-x64-unsigned-<version>-<run_id>-<package_run_attempt>.zip` 包含对应 EXE；`windows-package-logs-<run_id>-<run_attempt>` 包含打包诊断。安装包 ZIP 用 DOS 字段的本地时间和 Unix 字段的绝对时间记录各留存副本的修改时间，不保证是原始构建时间。上传步骤名为 `Retain installers for the selected mode` 和 `Retain packaging diagnostics`；步骤耗时与带时间戳的日志显示上传用时。这些产物不等于发布 Release 或下载站内容。
 
+归档 job 使用系统 bsdtar 创建 store 模式 ZIP：Windows 为 `%SystemRoot%\System32\tar.exe`（必须设置 `SystemRoot`），macOS 为 `/usr/bin/tar`。`invalid ZIP output settings` 表示归档名称、保留目录、临时目录或输出文件设置缺失或无效，会在校验文件前拒绝。`ZIP creation failed with <tar>` 指明失败的归档工具；检查其 stderr、工具是否可用，以及 `RUNNER_TEMP` 剩余空间。若打包已成功，修复归档前置条件后仅重跑 `upload-artifact`，复用保留的安装包。
+
 测量缓存时，`cache_namespace` 为两个依赖 store 和上游下载选择保留的子目录；留空使用正常共享缓存。新名称用于冷缓存采样，再次使用同名用于热缓存采样。名称由 1–64 个小写字母、数字或连字符组成，以字母或数字开头，且不能为 Windows 设备名。这不会重置独立的签名缓存或操作系统文件缓存；应将其状态、Job 开始至完成的总耗时与阶段耗时和产物体积一并报告。workflow 在依赖安装前记录 Node 版本、可用 CPU 并行数、逻辑 CPU 数及总内存和空闲内存。
 
 依赖安装和打包步骤在启动子进程前，将自身 shell 的 CPU、I/O 和内存优先级调整为普通值。优先级辅助脚本从 workflow 的精确提交复制到本轮临时目录，与选中的产品源码分离。缺失辅助脚本会终止 CI 准备；无法调整优先级时明确告警并标记调度条件不适合性能对比，但继续打包。这不会修改 runner 任务或其他进程。版本、preset 和产物留存适配器仍跟随产品源码及其格式。

apps/desktop/scripts/archive-desktop-ci.ts

@@ -30,7 +30,7 @@ if (process.argv[1] !== undefined && resolve(process.argv[1]) === import.meta.fi
     const { DESKTOP_ARCHIVE_NAME: name, DESKTOP_RETAINED_DIRECTORY: directory, RUNNER_TEMP: temp, GITHUB_OUTPUT: output } = process.env
     if (!name || !/^[a-zA-Z0-9][a-zA-Z0-9.+_-]*\.zip$/u.test(name) || !directory || !temp || !output) throw new Error('desktop archival: invalid ZIP output settings')
     const files = await verifyDesktopArchive(process.env)
-    // archive:false uploads use the file basename; keep it equal to the workflow's overwrite name.
+    // archive: false uses the file basename; keep it equal to the upload step's name used for overwrite deletion.
     const path = join(await mkdtemp(join(temp, 'desktop-archive-')), name)
     const windows = process.platform === 'win32'
     if (windows && !process.env.SystemRoot) throw new Error('desktop archival: SystemRoot is required to locate Windows bsdtar')