dsh-clean-desktop-shell 0.1.5 → 0.1.7

package/CONTRIBUTORS.md

@@ -0,0 +1,19 @@
+# Contributors
+
+This project welcomes contributions — especially around platforms that the
+maintainer does not use daily.
+
+## Author
+
+- **Icather** — Windows side, plugin architecture, backend lifecycle, CI setup.
+
+## Looking for help
+
+- **macOS maintainer / co-developer**: validate the .dmg install flow,
+  test Apple Silicon + Intel builds, set up code signing + notarization,
+  and ideally add a launch-at-login menu item in the tray.
+- **Linux maintainer**: validate the runtime provisioning and tray behavior
+  on major distributions.
+
+If you open a PR or verified issue that moves macOS support forward, add your
+name here.

package/README.en.md

@@ -11,8 +11,11 @@ Does exactly one thing: wraps your already-configured DSH Web in a clean native
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-0078D6?logo=windows&logoColor=white)](https://github.com/Icather/dsh-clean-desktop-shell)
 [![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Icather/dsh-clean-desktop-shell?color=blue)](https://github.com/Icather/dsh-clean-desktop-shell/releases/latest)
-[![DSH](https://img.shields.io/badge/DeepSeek_Harness-rc.7-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH](https://img.shields.io/badge/DeepSeek_Harness-0.1.1--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 [![Contributors](https://img.shields.io/github/contributors/Icather/dsh-clean-desktop-shell?color=blueviolet)](https://github.com/Icather/dsh-clean-desktop-shell/graphs/contributors)
+[![npm downloads](https://img.shields.io/npm/dt/dsh-clean-desktop-shell?logo=npm&color=cb3837&label=npm%20downloads)](https://www.npmjs.com/package/dsh-clean-desktop-shell)
+[![Installs](https://img.shields.io/github/downloads/Icather/dsh-clean-desktop-shell/total?logo=github&color=2ea043&label=installs)](https://github.com/Icather/dsh-clean-desktop-shell/releases)
+[![Clones](https://img.shields.io/badge/clones-139%20%2F%2014d-8957E5?logo=github&label=clones)](https://github.com/Icather/dsh-clean-desktop-shell)
 
 </div>
 
@@ -27,7 +30,25 @@ Key differences from other desktop clients in the ecosystem:
 | **Form** | Standalone Electron app with its own profile | **DSH plugin** mounted into your existing profile |
 | **Profile** | New `desktop` profile, plugins/config must be reinstalled | **Reuses your web profile**, zero migration |
 | **Visual changes** | Custom title bar / frosted glass etc. | **None** — pure window shell |
-| **Upstream** | Pinned version | **Tracks rc.7** |
+| **Upstream** | Pinned version | **Tracks 0.1.1-rc.2** |
+
+## Highlights
+
+**① One-click launch — like double-clicking a normal desktop app**
+
+No terminal, no commands. **Double-click the desktop shortcut and the DSH window opens instantly**, just like launching any normal app:
+
+- The installer creates the desktop shortcut automatically; the plugin form asks on first run, plus a one-click "create desktop shortcut" in the tray
+- Shows immediately on double-click — never waits for the backend
+- Single instance: a second double-click just focuses the existing window
+
+**② Live backend monitoring · quick manual start/stop**
+
+The tray **shows the backend state in real time** (running / starting / stopped / error) with one-click controls:
+
+- **Live monitoring**: the window keeps probing the backend; the moment it is killed, crashes or is stopped, the window flips to the offline screen — a stale page never fakes "still alive"
+- **Auto-reconnect**: the instant the backend recovers, the window reloads the real page by itself
+- **Quick start/stop**: one-click start / restart / stop from the tray (with progress dialogs); "stop backend" really shuts the service down on 3080, including externally started instances
 
 ## Usage
 
@@ -48,6 +69,29 @@ Key differences from other desktop clients in the ecosystem:
 - The instant the backend stops (tray stop, kill or crash) the window flips back to the offline screen — a stale page never fakes "still alive"
 - The offline screen has self-service buttons: reload / start backend / auto-detect backend / set backend install folder
 
+## macOS status (v0.1.7 important note)
+
+v0.1.7 fixes the plugin-mode bug where the shell could not locate `Electron.app`
+on macOS, which caused the window to fail silently on Mac.
+
+However, **the maintainer does not currently have a Mac** to verify the
+following in person:
+
+- **The .dmg is unsigned and un-notarized**: Apple requires a yearly Developer
+  Program membership ($99/yr) for code signing + notarization. The first time you
+  open the app from the .dmg, Gatekeeper will likely say the app is "damaged"
+  or "cannot be verified".
+  - Workaround: run `xattr -cr "/Applications/DSH Clean Desktop Shell.app"`,
+    then right-click the app and choose Open.
+  - Long-term fix: a Mac co-maintainer with an Apple Developer account can help
+    set up signed + notarized builds.
+- Post-extract executable bits and quarantine extended attributes can only be
+  confirmed on real hardware.
+
+If you have a Mac and want to co-maintain macOS support (test the .dmg, set up
+signing, or add a launch-at-login tray item), PRs and verified issues are very
+welcome. You will be added to [CONTRIBUTORS.md](./CONTRIBUTORS.md).
+
 ## Install
 
 **Option 1: download the installer from Releases (for a standalone desktop app)**
@@ -55,7 +99,13 @@ Key differences from other desktop clients in the ecosystem:
 - Windows: `DSH-Clean-Desktop-Shell-Setup-<version>.exe`
 - macOS: `DSH-Clean-Desktop-Shell-<version>.dmg` (Intel) or `-arm64.dmg` (Apple Silicon)
 
-The installer **creates a desktop shortcut automatically** and provides the full desktop experience (tray). The first time you run the Windows installer you may see a SmartScreen warning — **this is normal for unsigned programs, not a virus**, see "Windows SmartScreen warning" below.
+The installer **creates a desktop shortcut automatically** and provides the full desktop experience (tray).
+
+- **Windows**: the first time you run the installer you may see a SmartScreen
+  warning — **this is normal for unsigned programs, not a virus**, see
+  "Windows SmartScreen warning" below.
+- **macOS**: the .dmg is unsigned / un-notarized and may trigger Gatekeeper.
+  See "macOS status" above.
 
 **Option 2: install as a DSH plugin (DSH ecosystem users)**
 
@@ -149,6 +199,14 @@ npm run pack    # package NSIS (Win) / DMG (mac)
 
 ## Changelog
 
+### 0.1.6
+- Fixed "check for updates" reporting the Electron runtime version in plugin mode.
+
+### 0.1.5
+- Refactored the plugin host half into focused modules.
+- Completed package.json metadata (repository / homepage / bugs); dropped a stale auto-launch field.
+- README: usage before install, architecture reflects the two forms, platform matrix top-level.
+
 ### 0.1.4
 - Branch 2 (plugin-market distribution) is now live: `dsh plugin add` →
   restart `dsh web` → the desktop shell opens automatically. The Electron

package/README.md

@@ -11,8 +11,11 @@
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-0078D6?logo=windows&logoColor=white)](https://github.com/Icather/dsh-clean-desktop-shell)
 [![License](https://img.shields.io/badge/License-MIT-22c55e)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Icather/dsh-clean-desktop-shell?color=blue)](https://github.com/Icather/dsh-clean-desktop-shell/releases/latest)
-[![DSH](https://img.shields.io/badge/DeepSeek_Harness-rc.7-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
+[![DSH](https://img.shields.io/badge/DeepSeek_Harness-0.1.1--rc.2-4D6BFE)](https://github.com/deepseek-ai/deepseek-harness)
 [![Contributors](https://img.shields.io/github/contributors/Icather/dsh-clean-desktop-shell?color=blueviolet)](https://github.com/Icather/dsh-clean-desktop-shell/graphs/contributors)
+[![npm downloads](https://img.shields.io/npm/dt/dsh-clean-desktop-shell?logo=npm&color=cb3837&label=npm%20downloads)](https://www.npmjs.com/package/dsh-clean-desktop-shell)
+[![Installs](https://img.shields.io/github/downloads/Icather/dsh-clean-desktop-shell/total?logo=github&color=2ea043&label=installs)](https://github.com/Icather/dsh-clean-desktop-shell/releases)
+[![Clones](https://img.shields.io/badge/clones-139%20%2F%2014d-8957E5?logo=github&label=clones)](https://github.com/Icather/dsh-clean-desktop-shell)
 
 </div>
 
@@ -27,7 +30,25 @@
 | **形态** | 独立 Electron 应用，自带独立 profile | **DSH 插件**，挂载进现有 profile |
 | **Profile** | 新建 desktop profile，插件/配置要重装 | **复用现有 web profile**，零迁移 |
 | **视觉改造** | 自绘标题栏 / 毛玻璃等 | **零改造**，纯净窗口壳 |
-| **跟随上游** | 固定版本 | **跟随 rc.7** |
+| **跟随上游** | 固定版本 | **跟随 0.1.1-rc.2** |
+
+## 核心亮点
+
+**① 像双击桌面应用一样，一键启动 DSH**
+
+不用开终端、不用记命令。**双击桌面快捷方式，DSH 窗口立刻弹出**，和启动任何一个普通软件一样自然：
+
+- 安装包自动创建桌面快捷方式；插件形态首次运行询问 + 托盘「创建桌面快捷方式」一键补建
+- 双击即出窗——窗口不等后端、不做启动等待
+- 单实例：重复双击只聚焦已有窗口，绝不重复开壳
+
+**② 后端活性实时监测 · 快捷手动自主启停**
+
+托盘**实时显示后端状态**（运行中 / 启动中 / 未运行 / 错误），一键启停：
+
+- **活性监测**：窗口持续探测后端；后端一旦被杀、崩溃或手动关闭，窗口立刻切到离线页，绝不停在旧页面假装还活着
+- **自动重连**：后端恢复的一刻，窗口自动加载回真实页面，无需手动刷新
+- **快捷启停**：托盘右键一键启动 / 重启 / 关闭后端（带进度弹窗）；「关闭后端」真正停掉 3080 端口上的服务，含外部启动的实例
 
 ## 使用
 
@@ -48,6 +69,19 @@
 - 后端关闭 / 被杀的一刻，窗口立刻切回离线页——不会停在旧页面假装还活着
 - 离线页内置快捷按钮：重新加载 / 启动后端 / 自动探测后端 / 设置后端安装文件夹
 
+## macOS 状态（v0.1.7 重要说明）
+
+v0.1.7 修复了插件形态在 macOS 上无法定位 `Electron.app` 路径的问题（该 bug 导致窗口在 Mac 上完全静默失败）。
+
+但**当前开发者没有 Mac 实机**，以下事项仍然依赖 Mac 用户验证/贡献：
+
+- **.dmg 安装包未签名、未公证**：Apple 要求年度开发者计划（$99/年）才能给安装包签名+公证。首次打开 .dmg 里的应用，很可能提示「已损坏，无法打开」或「无法验证开发者」。这不是应用本身损坏，是 Gatekeeper 拦截了未签名应用。
+  - 临时解决：`xattr -cr "/Applications/DSH Clean Desktop Shell.app"`，然后右键 → 打开。
+  - 长期解决：需要一位有 Apple Developer 账号的 Mac 合作者协助签名/公证，或长期把 .dmg 安装体验写为「需要右键打开 / 执行 xattr」。
+- **Electron.app 解压后的可执行位、quarantine 扩展属性等**只有真机能确认行为是否完全正确。
+
+诚挚邀请有 Mac 环境、愿意一起打磨的同学参与：能帮忙验证安装流程、补充签名配置、或者把开机自启/登录项做进 Electron 托盘，欢迎直接提 PR 或在 Issue 里 @ 我，我会把你加入 [CONTRIBUTORS.md](./CONTRIBUTORS.md)。
+
 ## 安装
 
 **方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
@@ -55,7 +89,12 @@
 - Windows：下载 `DSH-Clean-Desktop-Shell-Setup-<版本>.exe`
 - macOS：下载 `DSH-Clean-Desktop-Shell-<版本>.dmg`（Intel）或 `-arm64.dmg`（Apple Silicon）
 
-安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。首次运行 Windows 安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
+安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。
+
+- **Windows**：首次运行安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
+- **macOS**：.dmg 未签名/未公证，首次打开可能触发 Gatekeeper。见上方「macOS 状态」。
+
+
 
 **方式二：作为 DSH 插件安装（DSH 生态用户）**
 
@@ -150,6 +189,14 @@ npm run pack    # 打包 NSIS (Win) / DMG (mac)
 
 ## 更新历史
 
+### 0.1.6
+- 修复插件形态下「检查更新」误报 Electron 运行时版本号的问题。
+
+### 0.1.5
+- 插件 host 侧重构为聚焦模块。
+- 补全 package.json 元数据（repository / homepage / bugs），清理遗留的开机自启字段。
+- README 调整：使用前置、架构反映两种形态、平台矩阵置顶。
+
 ### 0.1.4
 - 分支二（插件市场分发）正式可用：`dsh plugin add` 装插件 → 重启 `dsh web` → 桌面壳自动弹出；Electron 运行时由插件自管理（本地复用 / 按网络环境自动选源下载）。
 - 桌面快捷方式：首次启动询问创建 + 托盘「创建桌面快捷方式」一键添加（安装包与插件两种形态均支持）。

package/electron/tray.js

@@ -25,8 +25,12 @@ import { shortcutSupported, createDesktopShortcut } from './shortcut.js'
 const trayIconPath = join(
   fileURLToPath(new URL('.', import.meta.url)),
   'assets',
-  process.platform === 'win32' ? 'tray-16.png' : 'tray-32.png',
+  process.platform === 'win32' ? 'tray-16.png' : 'trayTemplate.png',
 )
+// macOS: the filename must end in "Template" (e.g. trayTemplate.png) and
+// Electron will automatically pick trayTemplate@2x.png on Retina.
+// The image itself must be a black silhouette + alpha channel so it
+// inverts correctly in both light and dark menu bars.
 
 let trayInstance = null
 let handlers = null
@@ -61,9 +65,11 @@ export function refreshTrayMenu() {
       label: '刷新窗口',
       click: onReload,
     },
+    // Windows-only: desktop .lnk shortcut. Hidden on other platforms instead of
+    // disabled so the menu stays relevant to the OS it is running on.
     {
       label: '创建桌面快捷方式',
-      enabled: shortcutSupported(),
+      visible: shortcutSupported(),
       click: async () => {
         const ok = await createDesktopShortcut()
         if (ok) {

package/electron/update.js

@@ -10,11 +10,27 @@
  * this project does not have yet).
  */
 import { app, shell, dialog } from 'electron'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { showProgress, setProgress, closeProgress } from './progress.js'
+import { loadConfig } from './config.js'
 
 const REPO_URL = 'https://github.com/Icather/dsh-clean-desktop-shell'
 const RELEASES_API = 'https://api.github.com/repos/Icather/dsh-clean-desktop-shell/releases/latest'
 
+// Plugin (bare-runtime) mode has no app bundle, so app.getVersion() returns
+// the Electron runtime version (e.g. 33.4.11). Read the plugin's own version
+// from its package.json instead.
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const PKG_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version
+  } catch {
+    return null
+  }
+})()
+
 let autoUpdater = null
 let updaterPromise = null
 
@@ -111,17 +127,20 @@ export async function checkForUpdatesAuto() {
 
   // Manual path (macOS / dev mode): compare versions, offer GitHub page.
   const r = await checkForUpdate()
+  const isPlugin = !app.isPackaged
   if (r.hasUpdate) {
     const choice = dialog.showMessageBoxSync({
       type: 'info',
       title: '发现新版本',
       message: `当前版本 ${r.current}，最新版本 ${r.latest}。`,
-      detail: 'macOS 自动更新需要代码签名，当前请前往 GitHub Releases 手动下载。',
-      buttons: ['前往下载', '取消'],
+      detail: isPlugin
+        ? '插件形态请到 DSH 网页的「设置 → 插件市场 → 已安装」里点「更新」，完成后按提示重启即可生效。'
+        : 'macOS 自动更新需要代码签名，当前请前往 GitHub Releases 手动下载。',
+      buttons: isPlugin ? ['打开 DSH 网页', '稍后'] : ['前往下载', '取消'],
       defaultId: 0,
       cancelId: 1,
     })
-    if (choice === 0) openUrl(r.url)
+    if (choice === 0) openUrl(isPlugin ? loadConfig().targetUrl : r.url)
   } else if (r.latest) {
     dialog.showMessageBoxSync({
       type: 'info',
@@ -144,6 +163,15 @@ function parseVersion(v) {
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null
 }
 
+/**
+ * Current app version. Packaged builds carry it in the exe; a bare runtime
+ * (plugin mode) must read the plugin package.json — app.getVersion() would
+ * report the Electron runtime version there.
+ */
+function currentVersion() {
+  return app.isPackaged ? app.getVersion() : PKG_VERSION || app.getVersion()
+}
+
 /** True when a is strictly newer than b. */
 function isNewer(a, b) {
   if (!a || !b) return false
@@ -158,7 +186,7 @@ function isNewer(a, b) {
  * @returns {{ hasUpdate: boolean, latest?: string, current: string, url: string }}
  */
 export async function checkForUpdate() {
-  const current = app.getVersion()
+  const current = currentVersion()
   let latest = null
   let tag = null
   let url = REPO_URL

package/lib/common.js

@@ -12,11 +12,42 @@ import { fileURLToPath } from 'node:url'
 export const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 export const MAIN_JS = join(PKG_ROOT, 'electron', 'main.js')
 export const isWin = process.platform === 'win32'
-export const EXE_NAME = isWin ? 'electron.exe' : 'electron'
+export const isMac = process.platform === 'darwin'
 export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
-export const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+export const PLATFORM = isWin ? 'win32' : isMac ? 'darwin' : 'linux'
+
+/**
+ * Electron binary path *relative to the extracted runtime dir*.
+ *
+ * The three upstream archives do not share a layout — only darwin ships an
+ * app bundle, and it is the one case with no top-level executable:
+ *   win32  → electron.exe
+ *   linux  → electron
+ *   darwin → Electron.app/Contents/MacOS/Electron
+ *
+ * Authoritative source: the `electron` package's own install.js, which writes
+ * exactly this relative path into path.txt for `require('electron')`.
+ */
+export const EXE_RELPATH = isWin
+  ? 'electron.exe'
+  : isMac
+    ? join('Electron.app', 'Contents', 'MacOS', 'Electron')
+    : 'electron'
+
+/** First path segment of EXE_RELPATH — what a successful extract must leave behind. */
+export const EXE_TOP = isWin ? 'electron.exe' : isMac ? 'Electron.app' : 'electron'
+
+/** DSH home, honouring DSH_HOME the same way dsh-home-paths does. */
+export function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
 
 /** Where the self-provisioned runtimes live (shared with icon.js). */
 export function runtimeRoot() {
-  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'desktop-shell-runtime')
+  return join(dshHome(), 'desktop-shell-runtime')
+}
+
+/** Launch diagnostics land here — the only thing a headless user can send us. */
+export function launchLogPath() {
+  return join(dshHome(), 'desktop-shell-launch.log')
 }

package/lib/index.js

@@ -9,7 +9,8 @@
  * icon.js (Windows taskbar icon).
  */
 import { spawn } from 'node:child_process'
-import { PKG_ROOT, MAIN_JS } from './common.js'
+import { appendFileSync } from 'node:fs'
+import { PKG_ROOT, MAIN_JS, dshHome, runtimeRoot, launchLogPath } from './common.js'
 import { ensureRuntime } from './runtime.js'
 import { patchExeIcon } from './icon.js'
 
@@ -36,11 +37,50 @@ export function apply(ctx) {
       await patchExeIcon(ctx, exe).catch(() => {})
       launchShell(exe, ctx)
     } catch (err) {
-      ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
+      reportLaunchFailure(ctx, err)
     }
   })()
 }
 
+/**
+ * A provisioning failure used to vanish into ctx.logger — invisible to
+ * anyone who is not already tailing the DSH log. That is precisely how the
+ * macOS launch bug survived several releases: there was no window, no error
+ * dialog, and nothing on disk to send back.
+ *
+ * Write a diagnostics file next to the runtime and name it in the warning,
+ * so a user on an untested platform can hand us something actionable.
+ */
+function reportLaunchFailure(ctx, err) {
+  const message = err?.message ?? String(err)
+  ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${message}`)
+
+  const logPath = launchLogPath()
+  const body = [
+    `time:     ${new Date().toISOString()}`,
+    `platform: ${process.platform} (${process.arch})`,
+    `node:     ${process.version}`,
+    `dsh home: ${dshHome()}`,
+    `runtime:  ${runtimeRoot()}`,
+    `entry:    ${MAIN_JS}`,
+    `error:    ${message}`,
+    '',
+    'Things worth checking:',
+    '  - first launch downloads the Electron runtime; a blocked network fails here',
+    '  - set DSH_SHELL_ELECTRON_DIR to an electron package to skip the download',
+    '  - macOS binary: <runtime>/electron-v<ver>/Electron.app/Contents/MacOS/Electron',
+    '  - macOS: unsandboxed extractors may drop the executable bit (chmod +x)',
+    '',
+  ].join('\n')
+
+  try {
+    appendFileSync(logPath, body + '\n')
+    ctx.logger.warn(`[clean-desktop-shell] diagnostics written to ${logPath}`)
+  } catch {
+    // Nothing else a headless host process can do.
+  }
+}
+
 function launchShell(exe, ctx) {
   if (launched) return
   const child = spawn(exe, [MAIN_JS], {

package/lib/runtime.js

@@ -23,8 +23,17 @@ import {
   rmSync,
   symlinkSync,
 } from 'node:fs'
-import { join } from 'node:path'
-import { PKG_ROOT, EXE_NAME, ARCH, PLATFORM, runtimeRoot } from './common.js'
+import { basename, join } from 'node:path'
+import {
+  PKG_ROOT,
+  EXE_RELPATH,
+  EXE_TOP,
+  ARCH,
+  PLATFORM,
+  isWin,
+  isMac,
+  runtimeRoot,
+} from './common.js'
 
 function electronVersion() {
   try {
@@ -49,18 +58,19 @@ export async function ensureRuntime(ctx) {
   if (!version) throw new Error('desktopShell.electronVersion missing in package.json')
   const root = runtimeRoot()
   const dir = versionDir(root, version)
-  const exe = join(dir, EXE_NAME)
+  const exe = join(dir, EXE_RELPATH)
 
   // 1) Already provisioned for this version?
   if (existsSync(exe)) {
     cleanupOldVersions(root, dir)
+    if (!isWin) await ensureExecutable(ctx, exe)
     return exe
   }
 
   // 2) Local reuse: DSH_SHELL_ELECTRON_DIR → link/copy its dist/ (fast).
   const localSrc = process.env.DSH_SHELL_ELECTRON_DIR
   if (localSrc) {
-    const srcExe = join(localSrc, 'dist', EXE_NAME)
+    const srcExe = join(localSrc, 'dist', EXE_RELPATH)
     if (existsSync(srcExe) && provisionLocalDist(localSrc, dir)) {
       ctx.logger.info(`[clean-desktop-shell] reused electron runtime from ${localSrc}`)
     }
@@ -73,43 +83,130 @@ export async function ensureRuntime(ctx) {
   }
 
   if (!existsSync(exe)) {
+    // Name the exact path we expected. Without it a user on an untested
+    // platform has nothing to report back (this failure used to be silent).
     throw new Error(
-      'electron runtime provisioning failed — check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
+      `electron runtime provisioning failed — expected binary at ${exe} ` +
+        `(platform=${PLATFORM} arch=${ARCH}, layout differs per platform); ` +
+        'check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
     )
   }
   cleanupOldVersions(root, dir)
+  if (!isWin) await ensureExecutable(ctx, exe)
   ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
   return exe
 }
 
+/**
+ * Zip extraction does not reliably restore the executable bit — bsdtar
+ * (Windows tar.exe, macOS /usr/bin/tar) in particular drops it — and a
+ * non-executable binary fails later with a bare EACCES on spawn. Guarantee
+ * it instead of trusting the extractor.
+ */
+function ensureExecutable(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('chmod', ['+x', target], { stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        ctx.logger.warn(`[clean-desktop-shell] chmod +x failed (exit ${code}) on ${target}`)
+      }
+      resolve(code === 0)
+    })
+  })
+}
+
 async function downloadRuntime(ctx, version, root, dir) {
   const tmpZip = join(root, `.electron-${version}.zip.tmp`)
   rmSync(tmpZip, { force: true })
   const urls = await runtimeUrls(version)
+  const innerName = zipName(version).replace(/\.zip$/, '')
+
   for (const url of urls) {
     ctx.logger.info(`[clean-desktop-shell] downloading electron ${version} from ${url}`)
-    if (await fetchFile(url, tmpZip)) {
-      // Zip extracts to an inner dir named like the zip basename.
-      const inner = join(root, zipName(version).replace(/\.zip$/, ''))
-      try {
-        await extractZip(tmpZip, root)
-        if (existsSync(join(inner, EXE_NAME)) && inner !== dir) {
-          rmSync(dir, { recursive: true, force: true })
-          renameSync(inner, dir)
-        }
-        rmSync(tmpZip, { force: true })
-        return
-      } catch (err) {
-        ctx.logger.warn(`[clean-desktop-shell] extract failed: ${err?.message ?? err}`)
-        rmSync(inner, { recursive: true, force: true })
-      }
+    if (!(await fetchFile(url, tmpZip))) {
+      // Failed download — drop the partial file so a later run starts clean.
+      rmSync(tmpZip, { force: true })
+      continue
     }
-    // Failed download — drop the partial file so a later run starts clean.
+
+    // Extract into a scratch dir, never into the shared runtime root: a
+    // half-extracted zip there would be indistinguishable from a real
+    // runtime, and the sibling electron-v* dirs must not be disturbed.
+    const scratch = join(root, `.extract-${version}-${Date.now()}`)
+    const ok = await extractZip(ctx, tmpZip, scratch)
     rmSync(tmpZip, { force: true })
+    if (!ok) {
+      ctx.logger.warn(`[clean-desktop-shell] no extractor succeeded for ${url}`)
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    // Both archive layouts exist in the wild: some Electron zips wrap
+    // everything in a dir named after the zip, others (notably darwin, whose
+    // payload is Electron.app/) unpack flat into the destination. Detect
+    // rather than assume — the old code assumed the wrapper and silently
+    // produced nothing on macOS.
+    const payload = findPayload(scratch, join(scratch, innerName))
+    if (!payload) {
+      ctx.logger.warn(
+        `[clean-desktop-shell] unexpected archive layout: no ${EXE_TOP} under ${scratch}`,
+      )
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    movePayloadInto(dir, payload)
+    rmSync(scratch, { recursive: true, force: true })
+    if (isMac) await clearQuarantine(ctx, join(dir, EXE_TOP))
+    return
   }
   throw new Error('electron download failed from all sources')
 }
 
+/** The dir that directly holds the electron payload right after extraction. */
+function findPayload(scratch, wrapper) {
+  if (existsSync(join(wrapper, EXE_TOP))) return wrapper
+  if (existsSync(join(scratch, EXE_TOP))) return scratch
+  return null
+}
+
+function movePayloadInto(dir, payload) {
+  rmSync(dir, { recursive: true, force: true })
+  renameSync(payload, dir)
+}
+
+/**
+ * macOS: a bundle carrying com.apple.quarantine is refused by Gatekeeper with
+ * the infamous "已损坏，无法打开" dialog. We download with curl (which does
+ * not set the attribute), but archive members themselves can carry it, so
+ * clear it once right after extraction rather than debugging it per user.
+ */
+function clearQuarantine(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('xattr', ['-cr', target], { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      ctx.logger.info(
+        code === 0
+          ? `[clean-desktop-shell] cleared extended attributes on ${target}`
+          : `[clean-desktop-shell] xattr cleanup skipped (exit ${code})`,
+      )
+      resolve(code === 0)
+    })
+  })
+}
+
 /**
  * Pick the download source by racing a HEAD probe against each candidate
  * (direct connection, 3s each). The fastest reachable source goes first —
@@ -162,21 +259,81 @@ function fetchFile(url, dest) {
   })
 }
 
-function extractZip(zipPath, dest) {
-  // Windows ships bsdtar (tar.exe) which reads zip; fall back to
-  // PowerShell Expand-Archive if needed.
-  const child = spawn('tar', ['-xf', zipPath, '-C', dest], { windowsHide: true, stdio: 'ignore' })
-  return new Promise((resolve, reject) => {
-    child.on('error', reject)
-    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`tar exit ${code}`))))
+/**
+ * Extract a zip using whatever the platform actually provides.
+ *
+ * The archives are ordinary zips, but the readers differ:
+ *   - Windows: bsdtar ships as tar.exe and reads zip; Expand-Archive is the
+ *     fallback for hardened images where tar is unavailable.
+ *   - macOS:   ditto -xk is Apple's own extractor and preserves the symlinks
+ *              inside Electron.app; unzip next; bsdtar last.
+ *   - Linux:   unzip, then tar.
+ *
+ * Success is decided by the caller (findPayload), not by the exit code — a
+ * zip can unpack "successfully" into a layout nobody expects.
+ */
+function extractZip(ctx, zipPath, dest) {
+  const strategies = isWin
+    ? [
+        { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        {
+          cmd: 'powershell',
+          args: [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Expand-Archive -LiteralPath '${zipPath.replace(/'/g, "''")}' -DestinationPath '${dest.replace(/'/g, "''")}' -Force`,
+          ],
+        },
+      ]
+    : isMac
+      ? [
+          { cmd: 'ditto', args: ['-xk', zipPath, dest] },
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+      : [
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+
+  return (async () => {
+    mkdirSync(dest, { recursive: true })
+    for (const s of strategies) {
+      const ok = await runExtractor(s.cmd, s.args)
+      if (ok) {
+        ctx.logger.info(`[clean-desktop-shell] extracted with ${s.cmd}`)
+        return true
+      }
+      ctx.logger.warn(`[clean-desktop-shell] extractor unavailable or failed: ${s.cmd}`)
+    }
+    return false
+  })()
+}
+
+function runExtractor(cmd, args) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(cmd, args, { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
   })
 }
 
-/** Remove version dirs older than the current one (dead weight). */
+/**
+ * Drop version dirs older than the current one (dead weight), plus any
+ * scratch dir a crashed extraction left behind.
+ */
 function cleanupOldVersions(root, currentDir) {
   try {
     for (const entry of readdirSync(root)) {
-      if (!entry.startsWith('electron-v')) continue
+      const isStaleRuntime = entry.startsWith('electron-v')
+      const isScratch = entry.startsWith('.extract-') || entry.startsWith('.electron-')
+      if (!isStaleRuntime && !isScratch) continue
       const full = join(root, entry)
       if (full === currentDir) continue
       rmSync(full, { recursive: true, force: true })
@@ -187,11 +344,15 @@ function cleanupOldVersions(root, currentDir) {
 }
 
 /**
- * Provision a local electron package's dist/ as the version dir itself,
- * so the layout matches a downloaded runtime: <dir>/electron(.exe) at the
- * version-dir root. Windows: junction (zero-copy, instant) — a 269MB
- * recursive cpSync can be killed by sandbox/AV on large trees, so only
- * fall back to a copy.
+ * Provision a local electron package's dist/ as the version dir itself, so
+ * the layout matches a downloaded runtime: <dir>/<EXE_RELPATH> at the
+ * version-dir root (on macOS that is <dir>/Electron.app/Contents/MacOS/Electron).
+ *
+ * Windows: junction (zero-copy, instant) — a 269MB recursive cpSync can be
+ * killed by sandbox/AV on large trees, so only fall back to a copy.
+ * macOS/Linux: a symlink to dist/ would work too, but a bare .app reached
+ * through a symlink is a common source of Gatekeeper/entitlement surprises,
+ * so always copy there.
  */
 function provisionLocalDist(srcPkg, destDir) {
   if (process.platform === 'win32') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-clean-desktop-shell",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Clean desktop shell for DeepSeek Harness (DSH) as a DSH plugin — wraps your web profile in a native window, tray-managed backend, offline auto-reconnect, zero visual changes. DSH 插件形态的纯净桌面壳：复用现有 web profile，托盘管理后端，零视觉改造。",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
+    "CONTRIBUTORS.md",
     "LICENSE",
     "version.txt"
   ],
@@ -32,7 +33,7 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "check": "node --check lib/index.js",
+    "check": "node --check lib/index.js && node scripts/selftest-runtime.mjs",
     "dev": "electron electron/main.js",
     "icons": "node scripts/gen-icons.mjs",
     "pack": "electron-builder --win nsis",
@@ -97,7 +98,8 @@
       "target": [
         "dmg"
       ],
-      "category": "public.app-category.developer-tools"
+      "category": "public.app-category.developer-tools",
+      "icon": "build/icon.png"
     },
     "nsis": {
       "oneClick": true,

package/scripts/selftest-runtime.mjs

@@ -0,0 +1,90 @@
+/**
+ * Self-check for the Electron runtime path logic.
+ *
+ * Guards the macOS launch bug: Electron's three archives have three
+ * different layouts, and only darwin ships an app bundle with no top-level
+ * binary. This fakes each platform and each archive layout, then asserts
+ * join(versionDir, EXE_RELPATH) resolves to a real file — the exact
+ * condition ensureRuntime() checks before spawning the shell.
+ *
+ * Run: node scripts/selftest-runtime.mjs
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+import { pathToFileURL } from 'node:url'
+
+// Layouts as Electron actually ships them (authoritative mapping lives in
+// the `electron` package's own install.js, which writes path.txt):
+//   win32  → <dir>/electron.exe
+//   linux  → <dir>/electron
+//   darwin → <dir>/Electron.app/Contents/MacOS/Electron
+const LAYOUTS = {
+  win32: ['electron.exe', 'resources/placeholder'],
+  linux: ['electron', 'resources/placeholder'],
+  darwin: [
+    'Electron.app/Contents/MacOS/Electron',
+    'Electron.app/Contents/Info.plist',
+  ],
+}
+
+let failures = 0
+
+function check(label, cond) {
+  console.log(`  ${cond ? 'ok  ' : 'FAIL'} ${label}`)
+  if (!cond) failures++
+}
+
+/** Materialise an extracted-archive tree under dir. */
+function buildLayout(dir, entries) {
+  for (const rel of entries) {
+    const full = join(dir, ...rel.split('/').map((s) => s.split('\\').join(sep)))
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, 'binary')
+  }
+}
+
+async function forPlatform(platform) {
+  Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+  // Cache-bust so the module re-evaluates its platform-derived constants.
+  const { EXE_RELPATH, EXE_TOP } = await import(
+    `${pathToFileURL(join(process.cwd(), 'lib', 'common.js')).href}?p=${platform}`
+  )
+
+  const root = mkdtempSync(join(tmpdir(), `dsh-shell-${platform}-`))
+  const dir = join(root, 'electron-v33.4.11')
+  console.log(`\n[${platform}]`)
+  try {
+    buildLayout(dir, LAYOUTS[platform])
+    const exe = join(dir, EXE_RELPATH)
+
+    check(`EXE_TOP = ${EXE_TOP}`, typeof EXE_TOP === 'string' && EXE_TOP.length > 0)
+    check(`binary resolves: ${EXE_RELPATH}`, existsSync(exe))
+    check('resolved path lives inside the version dir', exe.startsWith(dir))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+// Regression guard: prove the pre-fix constant was broken on darwin, so this
+// test would actually have caught the bug rather than just passing forever.
+async function regression() {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-shell-legacy-'))
+  const dir = join(root, 'electron-v33.4.11')
+  console.log('\n[regression: pre-fix darwin behaviour]')
+  try {
+    buildLayout(dir, LAYOUTS.darwin)
+    const legacyExe = 'electron' // what EXE_NAME used to be on every non-Windows platform
+    check(`legacy join(dir, 'electron') is absent — the bug`, !existsSync(join(dir, legacyExe)))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+await regression()
+for (const p of ['win32', 'linux', 'darwin']) {
+  await forPlatform(p)
+}
+
+console.log(`\n${failures === 0 ? 'PASS' : `FAIL (${failures} check(s))`}`)
+process.exit(failures === 0 ? 0 : 1)

package/src/host/common.js

@@ -12,11 +12,42 @@ import { fileURLToPath } from 'node:url'
 export const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 export const MAIN_JS = join(PKG_ROOT, 'electron', 'main.js')
 export const isWin = process.platform === 'win32'
-export const EXE_NAME = isWin ? 'electron.exe' : 'electron'
+export const isMac = process.platform === 'darwin'
 export const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
-export const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
+export const PLATFORM = isWin ? 'win32' : isMac ? 'darwin' : 'linux'
+
+/**
+ * Electron binary path *relative to the extracted runtime dir*.
+ *
+ * The three upstream archives do not share a layout — only darwin ships an
+ * app bundle, and it is the one case with no top-level executable:
+ *   win32  → electron.exe
+ *   linux  → electron
+ *   darwin → Electron.app/Contents/MacOS/Electron
+ *
+ * Authoritative source: the `electron` package's own install.js, which writes
+ * exactly this relative path into path.txt for `require('electron')`.
+ */
+export const EXE_RELPATH = isWin
+  ? 'electron.exe'
+  : isMac
+    ? join('Electron.app', 'Contents', 'MacOS', 'Electron')
+    : 'electron'
+
+/** First path segment of EXE_RELPATH — what a successful extract must leave behind. */
+export const EXE_TOP = isWin ? 'electron.exe' : isMac ? 'Electron.app' : 'electron'
+
+/** DSH home, honouring DSH_HOME the same way dsh-home-paths does. */
+export function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), '.dsh')
+}
 
 /** Where the self-provisioned runtimes live (shared with icon.js). */
 export function runtimeRoot() {
-  return join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'desktop-shell-runtime')
+  return join(dshHome(), 'desktop-shell-runtime')
+}
+
+/** Launch diagnostics land here — the only thing a headless user can send us. */
+export function launchLogPath() {
+  return join(dshHome(), 'desktop-shell-launch.log')
 }

package/src/host/index.js

@@ -9,7 +9,8 @@
  * icon.js (Windows taskbar icon).
  */
 import { spawn } from 'node:child_process'
-import { PKG_ROOT, MAIN_JS } from './common.js'
+import { appendFileSync } from 'node:fs'
+import { PKG_ROOT, MAIN_JS, dshHome, runtimeRoot, launchLogPath } from './common.js'
 import { ensureRuntime } from './runtime.js'
 import { patchExeIcon } from './icon.js'
 
@@ -36,11 +37,50 @@ export function apply(ctx) {
       await patchExeIcon(ctx, exe).catch(() => {})
       launchShell(exe, ctx)
     } catch (err) {
-      ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
+      reportLaunchFailure(ctx, err)
     }
   })()
 }
 
+/**
+ * A provisioning failure used to vanish into ctx.logger — invisible to
+ * anyone who is not already tailing the DSH log. That is precisely how the
+ * macOS launch bug survived several releases: there was no window, no error
+ * dialog, and nothing on disk to send back.
+ *
+ * Write a diagnostics file next to the runtime and name it in the warning,
+ * so a user on an untested platform can hand us something actionable.
+ */
+function reportLaunchFailure(ctx, err) {
+  const message = err?.message ?? String(err)
+  ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${message}`)
+
+  const logPath = launchLogPath()
+  const body = [
+    `time:     ${new Date().toISOString()}`,
+    `platform: ${process.platform} (${process.arch})`,
+    `node:     ${process.version}`,
+    `dsh home: ${dshHome()}`,
+    `runtime:  ${runtimeRoot()}`,
+    `entry:    ${MAIN_JS}`,
+    `error:    ${message}`,
+    '',
+    'Things worth checking:',
+    '  - first launch downloads the Electron runtime; a blocked network fails here',
+    '  - set DSH_SHELL_ELECTRON_DIR to an electron package to skip the download',
+    '  - macOS binary: <runtime>/electron-v<ver>/Electron.app/Contents/MacOS/Electron',
+    '  - macOS: unsandboxed extractors may drop the executable bit (chmod +x)',
+    '',
+  ].join('\n')
+
+  try {
+    appendFileSync(logPath, body + '\n')
+    ctx.logger.warn(`[clean-desktop-shell] diagnostics written to ${logPath}`)
+  } catch {
+    // Nothing else a headless host process can do.
+  }
+}
+
 function launchShell(exe, ctx) {
   if (launched) return
   const child = spawn(exe, [MAIN_JS], {

package/src/host/runtime.js

@@ -23,8 +23,17 @@ import {
   rmSync,
   symlinkSync,
 } from 'node:fs'
-import { join } from 'node:path'
-import { PKG_ROOT, EXE_NAME, ARCH, PLATFORM, runtimeRoot } from './common.js'
+import { basename, join } from 'node:path'
+import {
+  PKG_ROOT,
+  EXE_RELPATH,
+  EXE_TOP,
+  ARCH,
+  PLATFORM,
+  isWin,
+  isMac,
+  runtimeRoot,
+} from './common.js'
 
 function electronVersion() {
   try {
@@ -49,18 +58,19 @@ export async function ensureRuntime(ctx) {
   if (!version) throw new Error('desktopShell.electronVersion missing in package.json')
   const root = runtimeRoot()
   const dir = versionDir(root, version)
-  const exe = join(dir, EXE_NAME)
+  const exe = join(dir, EXE_RELPATH)
 
   // 1) Already provisioned for this version?
   if (existsSync(exe)) {
     cleanupOldVersions(root, dir)
+    if (!isWin) await ensureExecutable(ctx, exe)
     return exe
   }
 
   // 2) Local reuse: DSH_SHELL_ELECTRON_DIR → link/copy its dist/ (fast).
   const localSrc = process.env.DSH_SHELL_ELECTRON_DIR
   if (localSrc) {
-    const srcExe = join(localSrc, 'dist', EXE_NAME)
+    const srcExe = join(localSrc, 'dist', EXE_RELPATH)
     if (existsSync(srcExe) && provisionLocalDist(localSrc, dir)) {
       ctx.logger.info(`[clean-desktop-shell] reused electron runtime from ${localSrc}`)
     }
@@ -73,43 +83,130 @@ export async function ensureRuntime(ctx) {
   }
 
   if (!existsSync(exe)) {
+    // Name the exact path we expected. Without it a user on an untested
+    // platform has nothing to report back (this failure used to be silent).
     throw new Error(
-      'electron runtime provisioning failed — check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
+      `electron runtime provisioning failed — expected binary at ${exe} ` +
+        `(platform=${PLATFORM} arch=${ARCH}, layout differs per platform); ` +
+        'check network, or point DSH_SHELL_ELECTRON_DIR at an electron package',
     )
   }
   cleanupOldVersions(root, dir)
+  if (!isWin) await ensureExecutable(ctx, exe)
   ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
   return exe
 }
 
+/**
+ * Zip extraction does not reliably restore the executable bit — bsdtar
+ * (Windows tar.exe, macOS /usr/bin/tar) in particular drops it — and a
+ * non-executable binary fails later with a bare EACCES on spawn. Guarantee
+ * it instead of trusting the extractor.
+ */
+function ensureExecutable(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('chmod', ['+x', target], { stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      if (code !== 0) {
+        ctx.logger.warn(`[clean-desktop-shell] chmod +x failed (exit ${code}) on ${target}`)
+      }
+      resolve(code === 0)
+    })
+  })
+}
+
 async function downloadRuntime(ctx, version, root, dir) {
   const tmpZip = join(root, `.electron-${version}.zip.tmp`)
   rmSync(tmpZip, { force: true })
   const urls = await runtimeUrls(version)
+  const innerName = zipName(version).replace(/\.zip$/, '')
+
   for (const url of urls) {
     ctx.logger.info(`[clean-desktop-shell] downloading electron ${version} from ${url}`)
-    if (await fetchFile(url, tmpZip)) {
-      // Zip extracts to an inner dir named like the zip basename.
-      const inner = join(root, zipName(version).replace(/\.zip$/, ''))
-      try {
-        await extractZip(tmpZip, root)
-        if (existsSync(join(inner, EXE_NAME)) && inner !== dir) {
-          rmSync(dir, { recursive: true, force: true })
-          renameSync(inner, dir)
-        }
-        rmSync(tmpZip, { force: true })
-        return
-      } catch (err) {
-        ctx.logger.warn(`[clean-desktop-shell] extract failed: ${err?.message ?? err}`)
-        rmSync(inner, { recursive: true, force: true })
-      }
+    if (!(await fetchFile(url, tmpZip))) {
+      // Failed download — drop the partial file so a later run starts clean.
+      rmSync(tmpZip, { force: true })
+      continue
     }
-    // Failed download — drop the partial file so a later run starts clean.
+
+    // Extract into a scratch dir, never into the shared runtime root: a
+    // half-extracted zip there would be indistinguishable from a real
+    // runtime, and the sibling electron-v* dirs must not be disturbed.
+    const scratch = join(root, `.extract-${version}-${Date.now()}`)
+    const ok = await extractZip(ctx, tmpZip, scratch)
     rmSync(tmpZip, { force: true })
+    if (!ok) {
+      ctx.logger.warn(`[clean-desktop-shell] no extractor succeeded for ${url}`)
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    // Both archive layouts exist in the wild: some Electron zips wrap
+    // everything in a dir named after the zip, others (notably darwin, whose
+    // payload is Electron.app/) unpack flat into the destination. Detect
+    // rather than assume — the old code assumed the wrapper and silently
+    // produced nothing on macOS.
+    const payload = findPayload(scratch, join(scratch, innerName))
+    if (!payload) {
+      ctx.logger.warn(
+        `[clean-desktop-shell] unexpected archive layout: no ${EXE_TOP} under ${scratch}`,
+      )
+      rmSync(scratch, { recursive: true, force: true })
+      continue
+    }
+
+    movePayloadInto(dir, payload)
+    rmSync(scratch, { recursive: true, force: true })
+    if (isMac) await clearQuarantine(ctx, join(dir, EXE_TOP))
+    return
   }
   throw new Error('electron download failed from all sources')
 }
 
+/** The dir that directly holds the electron payload right after extraction. */
+function findPayload(scratch, wrapper) {
+  if (existsSync(join(wrapper, EXE_TOP))) return wrapper
+  if (existsSync(join(scratch, EXE_TOP))) return scratch
+  return null
+}
+
+function movePayloadInto(dir, payload) {
+  rmSync(dir, { recursive: true, force: true })
+  renameSync(payload, dir)
+}
+
+/**
+ * macOS: a bundle carrying com.apple.quarantine is refused by Gatekeeper with
+ * the infamous "已损坏，无法打开" dialog. We download with curl (which does
+ * not set the attribute), but archive members themselves can carry it, so
+ * clear it once right after extraction rather than debugging it per user.
+ */
+function clearQuarantine(ctx, target) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('xattr', ['-cr', target], { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => {
+      ctx.logger.info(
+        code === 0
+          ? `[clean-desktop-shell] cleared extended attributes on ${target}`
+          : `[clean-desktop-shell] xattr cleanup skipped (exit ${code})`,
+      )
+      resolve(code === 0)
+    })
+  })
+}
+
 /**
  * Pick the download source by racing a HEAD probe against each candidate
  * (direct connection, 3s each). The fastest reachable source goes first —
@@ -162,21 +259,81 @@ function fetchFile(url, dest) {
   })
 }
 
-function extractZip(zipPath, dest) {
-  // Windows ships bsdtar (tar.exe) which reads zip; fall back to
-  // PowerShell Expand-Archive if needed.
-  const child = spawn('tar', ['-xf', zipPath, '-C', dest], { windowsHide: true, stdio: 'ignore' })
-  return new Promise((resolve, reject) => {
-    child.on('error', reject)
-    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`tar exit ${code}`))))
+/**
+ * Extract a zip using whatever the platform actually provides.
+ *
+ * The archives are ordinary zips, but the readers differ:
+ *   - Windows: bsdtar ships as tar.exe and reads zip; Expand-Archive is the
+ *     fallback for hardened images where tar is unavailable.
+ *   - macOS:   ditto -xk is Apple's own extractor and preserves the symlinks
+ *              inside Electron.app; unzip next; bsdtar last.
+ *   - Linux:   unzip, then tar.
+ *
+ * Success is decided by the caller (findPayload), not by the exit code — a
+ * zip can unpack "successfully" into a layout nobody expects.
+ */
+function extractZip(ctx, zipPath, dest) {
+  const strategies = isWin
+    ? [
+        { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        {
+          cmd: 'powershell',
+          args: [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            `Expand-Archive -LiteralPath '${zipPath.replace(/'/g, "''")}' -DestinationPath '${dest.replace(/'/g, "''")}' -Force`,
+          ],
+        },
+      ]
+    : isMac
+      ? [
+          { cmd: 'ditto', args: ['-xk', zipPath, dest] },
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+      : [
+          { cmd: 'unzip', args: ['-q', '-o', zipPath, '-d', dest] },
+          { cmd: 'tar', args: ['-xf', zipPath, '-C', dest] },
+        ]
+
+  return (async () => {
+    mkdirSync(dest, { recursive: true })
+    for (const s of strategies) {
+      const ok = await runExtractor(s.cmd, s.args)
+      if (ok) {
+        ctx.logger.info(`[clean-desktop-shell] extracted with ${s.cmd}`)
+        return true
+      }
+      ctx.logger.warn(`[clean-desktop-shell] extractor unavailable or failed: ${s.cmd}`)
+    }
+    return false
+  })()
+}
+
+function runExtractor(cmd, args) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(cmd, args, { windowsHide: true, stdio: 'ignore' })
+    } catch {
+      return resolve(false)
+    }
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
   })
 }
 
-/** Remove version dirs older than the current one (dead weight). */
+/**
+ * Drop version dirs older than the current one (dead weight), plus any
+ * scratch dir a crashed extraction left behind.
+ */
 function cleanupOldVersions(root, currentDir) {
   try {
     for (const entry of readdirSync(root)) {
-      if (!entry.startsWith('electron-v')) continue
+      const isStaleRuntime = entry.startsWith('electron-v')
+      const isScratch = entry.startsWith('.extract-') || entry.startsWith('.electron-')
+      if (!isStaleRuntime && !isScratch) continue
       const full = join(root, entry)
       if (full === currentDir) continue
       rmSync(full, { recursive: true, force: true })
@@ -187,11 +344,15 @@ function cleanupOldVersions(root, currentDir) {
 }
 
 /**
- * Provision a local electron package's dist/ as the version dir itself,
- * so the layout matches a downloaded runtime: <dir>/electron(.exe) at the
- * version-dir root. Windows: junction (zero-copy, instant) — a 269MB
- * recursive cpSync can be killed by sandbox/AV on large trees, so only
- * fall back to a copy.
+ * Provision a local electron package's dist/ as the version dir itself, so
+ * the layout matches a downloaded runtime: <dir>/<EXE_RELPATH> at the
+ * version-dir root (on macOS that is <dir>/Electron.app/Contents/MacOS/Electron).
+ *
+ * Windows: junction (zero-copy, instant) — a 269MB recursive cpSync can be
+ * killed by sandbox/AV on large trees, so only fall back to a copy.
+ * macOS/Linux: a symlink to dist/ would work too, but a bare .app reached
+ * through a symlink is a common source of Gatekeeper/entitlement surprises,
+ * so always copy there.
  */
 function provisionLocalDist(srcPkg, destDir) {
   if (process.platform === 'win32') {

package/version.txt

@@ -1 +1 @@
-0.1.5
+0.1.7