dsh-clean-desktop-shell 0.1.3 → 0.1.4

package/README.en.md

@@ -31,22 +31,22 @@ Key differences from other desktop clients in the ecosystem:
 
 ## Install
 
-> **Status**: plugin-market install (Option 2) is under construction, expected live early tomorrow. **Only Option 1 (the installer) is currently available.**
-
-**Option 1: download the installer from Releases (recommended for end users — the only full desktop-app install)**
+**Option 1: download the installer from Releases (for a standalone desktop app)**
 
 - 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.
 
-**Option 2: register as a DSH plugin (developers/power users only) — ⚠️ this command does NOT install any desktop app**
+**Option 2: install as a DSH plugin (DSH ecosystem users)**
 
 ```sh
 dsh plugin --profile web add dsh-clean-desktop-shell
 ```
 
-> **Important**: Option 2 only "registers" the shell into your DSH profile. **No desktop app appears on your machine** — no installer, no desktop icon, no tray. It is meant for developers who want the shell mounted in the DSH ecosystem (reuses your web profile config, future settings integration). **For a double-clickable desktop app, use Option 1** (or run the source with `npm run dev`).
+Restart `dsh web` and the desktop shell window **opens automatically** (the first run prepares the Electron runtime over the network, ~1-2 minutes).
+
+> Option 2 gives you a shell that launches alongside DSH: the window is spawned by the plugin when `dsh web` starts, with **no standalone installer / desktop icon**. For a double-clickable app with a desktop shortcut and auto-update, use Option 1. The core window experience is identical either way.
 
 > The shell needs a reachable `dsh web` service (local or configured remote address). See Usage.
 
@@ -145,6 +145,17 @@ npm run pack    # package NSIS (Win) / DMG (mac)
 
 ## Changelog
 
+### 0.1.4
+- Branch 2 (plugin-market distribution) is now live: `dsh plugin add` →
+  restart `dsh web` → the desktop shell opens automatically. The Electron
+  runtime is self-provisioned by the plugin (local reuse / network-aware
+  source selection).
+- Desktop shortcut: first-run prompt + one-click "create desktop shortcut"
+  in the tray (both the installer and plugin forms).
+- Icons: Windows taskbar and macOS Dock show the whale icon in bare-runtime
+  (plugin) mode.
+- Auto-launch (login item) removed — both forms are now fully manual.
+
 ### 0.1.2
 - Windows auto-update: tray "check for updates" now downloads in the
   background with progress and installs on restart (electron-updater);

package/README.md

@@ -31,22 +31,22 @@
 
 ## 安装
 
-> **状态提示**：插件形式安装（方式二）施工中，预计今日凌晨上线。**当前仅支持方式一安装包安装**。
-
-**方式一：从 Release 下载安装包（推荐普通用户，唯一完整的桌面应用安装方式）**
+**方式一：从 Release 下载安装包（想要独立桌面应用的用户）**
 
 - Windows：下载 `DSH-Clean-Desktop-Shell-Setup-<版本>.exe`
 - macOS：下载 `DSH-Clean-Desktop-Shell-<版本>.dmg`（Intel）或 `-arm64.dmg`（Apple Silicon）
 
 安装包会**自动创建桌面快捷方式**，并提供系统托盘等完整桌面体验。首次运行 Windows 安装包可能触发 SmartScreen 警告——**这是未签名程序的正常现象，不是病毒**，见下方「Windows SmartScreen 警告说明」。
 
-**方式二：作为 DSH 插件注册（仅开发者/高级用户）——⚠️ 这个命令不会安装任何桌面应用**
+**方式二：作为 DSH 插件安装（DSH 生态用户）**
 
 ```sh
 dsh plugin --profile web add dsh-clean-desktop-shell
 ```
 
-> **重要**：方式二只是把壳"登记"进 DSH profile，**你的电脑上不会多出任何桌面应用**——没有安装包、没有桌面图标、没有系统托盘。它只用于开发者把壳挂进 DSH 生态（复用 web profile 配置、供未来设置集成）。**想要可双击使用的桌面应用，请用方式一**（或源码 `npm run dev` 运行）。
+重启 `dsh web` 后，桌面壳窗口会**自动弹出**（首次运行需联网准备 Electron 运行时，约 1-2 分钟）。
+
+> 方式二得到的是"随 DSH 启动的桌面壳"：窗口由插件在 `dsh web` 启动时自动拉起，**不产生独立安装包 / 桌面图标**。想要可双击启动、带桌面快捷方式和自动更新的独立应用，请用方式一。两种方式的核心窗口体验一致。
 
 > 桌面壳需要本机有可用的 `dsh web` 服务（或配置的远程地址）。见下方「使用」。
 
@@ -144,6 +144,12 @@ npm run pack    # 打包 NSIS (Win) / DMG (mac)
 
 ## 更新历史
 
+### 0.1.4
+- 分支二（插件市场分发）正式可用：`dsh plugin add` 装插件 → 重启 `dsh web` → 桌面壳自动弹出；Electron 运行时由插件自管理（本地复用 / 按网络环境自动选源下载）。
+- 桌面快捷方式：首次启动询问创建 + 托盘「创建桌面快捷方式」一键添加（安装包与插件两种形态均支持）。
+- 图标：Windows 任务栏 / macOS Dock 均显示鲸鱼图标（裸运行时场景）。
+- 移除开机自启（两种形态统一为纯手动启动）。
+
 ### 0.1.2
 - Windows 自动更新：托盘「检查更新」改为后台下载 + 进度显示 + 重启安装（electron-updater）；macOS 仍为手动下载。
 - 移除启动时自动拉起后端（改纯手动，与「关闭后端」不冲突）。

package/electron/aumid.js

@@ -0,0 +1,17 @@
+import { app } from 'electron'
+
+/**
+ * AppUserModelID, shared by main (process-level), window (taskbar button)
+ * and shortcut (Start-menu .lnk) so the three always agree.
+ *
+ * Why plugin mode gets its own ID: Windows caches the taskbar button icon
+ * per AUMID. If the plugin shell reuses the installer's ID that ever ran
+ * with Electron's default icon (an early dev launch / an old build), the
+ * taskbar keeps showing that stale icon — no window `icon`, `setAppDetails`
+ * or exe patch can override the cache. A distinct ID makes Windows treat it
+ * as a brand-new app and re-read the icon. It also keeps the plugin shell
+ * from merging with an installed copy on the same machine.
+ */
+export const APP_USER_MODEL_ID = app.isPackaged
+  ? 'com.icather.dsh-clean-desktop-shell'
+  : 'com.icather.dsh-clean-desktop-shell.plugin'

package/electron/main.js

@@ -8,20 +8,39 @@
  *
  * The main window is a pure shell — all backend controls live in the tray.
  */
-import { app, BrowserWindow, dialog } from 'electron'
+import { app, BrowserWindow, dialog, nativeImage } from 'electron'
+import { fileURLToPath } from 'node:url'
 import { createMainWindow, reloadWindow } from './window.js'
 import { createTray, refreshTrayMenu } from './tray.js'
 import { loadConfig, saveConfig } from './config.js'
 import { detect } from './service.js'
 import { setupAutoUpdater } from './update.js'
-import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut } from './shortcut.js'
+import { shortcutSupported, hasDesktopShortcut, createDesktopShortcut, ensureStartMenuShortcut } from './shortcut.js'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 const isMac = process.platform === 'darwin'
 
 // Windows: pin the AppUserModelId so the taskbar shows our whale icon
-// instead of the generic Electron icon.
+// instead of the generic Electron icon. Plugin mode uses a distinct ID
+// (see aumid.js) so Windows re-reads the icon instead of serving a
+// stale per-AUMID cached one.
 if (process.platform === 'win32') {
-  app.setAppUserModelId('com.icather.dsh-clean-desktop-shell')
+  app.setAppUserModelId(APP_USER_MODEL_ID)
+}
+
+// macOS: a bare runtime has no .app bundle (no icon resource), so set the
+// Dock icon at runtime. Unlike Windows there is no per-AUMID taskbar cache
+// here — app.dock.setIcon applies directly. Packaged builds already carry
+// the icon in their bundle, so skip those.
+if (isMac && !app.isPackaged) {
+  try {
+    const dockIcon = nativeImage.createFromPath(
+      fileURLToPath(new URL('../build/icon.png', import.meta.url)),
+    )
+    if (!dockIcon.isEmpty()) app.dock.setIcon(dockIcon)
+  } catch {
+    // non-fatal: keep the default icon
+  }
 }
 
 // Uniform userData across both distribution branches (installer vs
@@ -130,6 +149,14 @@ if (!gotLock) {
     // Windows: wire the auto-updater (downloads new installers silently).
     setupAutoUpdater()
 
+    // Windows: ensure the AUMID-carrying Start-menu shortcut exists so the
+    // taskbar button shows our icon (see shortcut.js). Best-effort.
+    try {
+      ensureStartMenuShortcut()
+    } catch {
+      // non-fatal
+    }
+
     // First run: offer a desktop shortcut (never nags twice).
     ensureShortcut().catch(() => {})
 

package/electron/shortcut.js

@@ -5,20 +5,44 @@
  *  - first-run prompt in main.js ("create a desktop shortcut?")
  *  - the tray "create desktop shortcut" item (always available)
  *
- * Only meaningful for packaged apps — in dev mode there is no stable
- * executable to point the shortcut at, so the feature is disabled there.
+ * Works in both distribution branches:
+ *  - installer (packaged): targets the installed exe, no arguments
+ *  - plugin-market (bare runtime): targets the provisioned electron.exe
+ *    with the plugin's electron/main.js as its argument
+ *
+ * Pure dev mode (npm run dev from a checkout) has no stable executable,
+ * so the feature stays disabled there.
  */
-import { app } from 'electron'
+import { app, shell } from 'electron'
 import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 const isWin = process.platform === 'win32'
 const SHORTCUT_NAME = 'DSH Clean Desktop Shell.lnk'
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+const ICON_ICO = join(PKG_ROOT, 'build', 'icon.ico')
+
+/**
+ * Plugin-market mode: the host half spawns a bare electron runtime with the
+ * plugin's electron/main.js as its entry. process.execPath is the runtime
+ * electron.exe; process.argv[1] is the entry script (packaged installers
+ * have no such argument).
+ */
+function pluginArgs() {
+  if (app.isPackaged) return []
+  const entry = process.argv[1]
+  if (entry && /\.js$/i.test(entry)) return [entry]
+  return []
+}
 
-/** Shortcuts are a Windows packaged-app feature. */
+/** Shortcuts need a stable executable — supported when packaged or in
+ *  plugin mode (where the runtime path is fixed under DSH_HOME). */
 export function shortcutSupported() {
-  return isWin && app.isPackaged
+  return isWin && (app.isPackaged || pluginArgs().length > 0)
 }
 
 function ps(str) {
@@ -59,14 +83,48 @@ export async function hasDesktopShortcut() {
 export async function createDesktopShortcut() {
   if (!shortcutSupported()) return false
   const target = process.execPath
+  const args = pluginArgs()
   const lnk = join(homedir(), 'Desktop', SHORTCUT_NAME)
+  // Plugin mode: point the shortcut at the runtime exe + main.js argument.
+  // WScript needs the path double-quoted inside the Arguments string.
+  const argPart = args.length
+    ? `; $s.Arguments = ${ps(`"${args[0]}"`)}; `
+    : ''
+  // Plugin-mode exe has no custom icon resource — point the shortcut at the
+  // bundled .ico when present (packaged installers use the exe itself).
+  const iconLoc = existsSync(ICON_ICO) ? ICON_ICO : `${target},0`
   const script =
     `$ws = New-Object -ComObject WScript.Shell; ` +
     `$s = $ws.CreateShortcut(${ps(lnk)}); ` +
     `$s.TargetPath = ${ps(target)}; ` +
+    argPart +
     `$s.WorkingDirectory = ${ps(dirname(target))}; ` +
-    `$s.IconLocation = ${ps(`${target},0`)}; ` +
+    `$s.IconLocation = ${ps(iconLoc)}; ` +
     `$s.Save()`
   const out = await runPs(script)
   return out !== null
 }
+
+/**
+ * Ensure a Start-menu shortcut carrying the AppUserModelID. This is what
+ * makes the taskbar button show our icon: Windows matches a running
+ * window's AUMID to a shortcut's icon (bare runtime electron.exe has no
+ * icon resource of its own). Idempotent — the shortcut is only created
+ * when missing.
+ */
+export function ensureStartMenuShortcut() {
+  if (!isWin || !shortcutSupported()) return false
+  const lnkDir = join(
+    process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'),
+    'Microsoft', 'Windows', 'Start Menu', 'Programs',
+  )
+  const lnk = join(lnkDir, SHORTCUT_NAME)
+  const args = pluginArgs()
+  return shell.writeShortcutLink(lnk, 'create', {
+    target: process.execPath,
+    args: args.length ? args.join(' ') : undefined,
+    icon: existsSync(ICON_ICO) ? ICON_ICO : undefined,
+    iconIndex: 0,
+    appUserModelId: APP_USER_MODEL_ID,
+  })
+}

package/electron/window.js

@@ -15,16 +15,26 @@
  *    window flips back to the offline screen instead of showing a stale page
  *    that suggests the app is still alive.
  */
-import { BrowserWindow, ipcMain } from 'electron'
+import { app, BrowserWindow, ipcMain } from 'electron'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { probe, onStatusChange, detect } from './service.js'
 import { startBackendWithProgress, chooseBackendFolder } from './tray.js'
+import { APP_USER_MODEL_ID } from './aumid.js'
 
 export const WINDOWS_TITLEBAR_HEIGHT = 32
 
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const PRELOAD_PATH = fileURLToPath(new URL('./preload.js', import.meta.url))
+// Windows taskbar follows the window icon only when it is an .ico; a png
+// covers the title bar / alt-tab but not the taskbar button. In plugin
+// mode there is no exe icon resource, so prefer the bundled .ico.
+const TASKBAR_ICO = join(PKG_ROOT, 'build', 'icon.ico')
 // Black-whale app icon (matches the DSH web favicon).
-const ICON_PATH = fileURLToPath(new URL('../build/icon.png', import.meta.url))
+const ICON_PATH = existsSync(TASKBAR_ICO)
+  ? TASKBAR_ICO
+  : fileURLToPath(new URL('../build/icon.png', import.meta.url))
 // Local fallback page shown while the backend is down.
 const ERROR_PAGE = fileURLToPath(new URL('./error.html', import.meta.url))
 
@@ -189,6 +199,15 @@ export function createMainWindow({ target }) {
   // Linux / other: keep the native frame.
 
   const win = new BrowserWindow(options)
+  // Windows taskbar button: bare runtime electron.exe has no custom icon,
+  // so pin the button to our .ico via setAppDetails (appId must match the
+  // app-level AppUserModelId set in main.js, else the options are ignored).
+  if (process.platform === 'win32' && existsSync(TASKBAR_ICO)) {
+    win.setAppDetails({
+      appId: APP_USER_MODEL_ID,
+      appIconPath: TASKBAR_ICO,
+    })
+  }
   windowTargets.set(win.id, target)
   win.loadURL(target).catch(() => startReconnect(win, target))
 

package/lib/client.js

@@ -1,10 +1,19 @@
 /**
  * dsh-clean-desktop-shell — client half (web browser bundle).
  *
- * Registers a settings row so the shell's target URL / material options
- * are editable from Settings → General. This is a minimal placeholder:
- * real UI wiring lands with the Electron shell work.
+ * The shell is a standalone Electron window; it injects nothing into the
+ * dsh web UI. This client module exists only to satisfy the client-modules
+ * loader contract — a bundle's client entry must register itself via
+ * `window.__ModuleLoader__.load({ id, factory })`, otherwise dsh reports
+ * "loaded without registering … via __ModuleLoader__.load".
  */
-export function apply() {
-  // placeholder: settings-row wiring arrives with the shell implementation
-}
+window.__ModuleLoader__.load({
+  id: 'dsh-clean-desktop-shell',
+  factory: () => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    exports.apply = () => {};
+    return module.exports;
+  },
+});

package/lib/index.js

@@ -30,6 +30,7 @@ import {
   renameSync,
   rmSync,
   symlinkSync,
+  writeFileSync,
 } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -42,22 +43,31 @@ const EXE_NAME = isWin ? 'electron.exe' : 'electron'
 const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
 const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
 
+// cordis registers the plugin by this name — bundles without an explicit
+// `name` export are silently skipped by the dsh loader.
+export const name = 'dsh-clean-desktop-shell'
+
 // Disable auto-launch with DSH_SHELL_AUTO_LAUNCH=0.
 const AUTO_LAUNCH = process.env.DSH_SHELL_AUTO_LAUNCH !== '0'
 
 let launched = false
 
 export function apply(ctx) {
-  ctx.on('ready', async () => {
-    ctx.logger.info('[clean-desktop-shell] mounted (host half)')
-    if (!AUTO_LAUNCH) return
+  ctx.logger.info('[clean-desktop-shell] mounted (host half)')
+  if (!AUTO_LAUNCH) return
+  // The dsh bundle loader calls apply() during early boot, but the cordis
+  // 'ready' event never fires for bundle plugins (dshmarket / agent-teams
+  // use ctx.inject or run inline instead). Launch directly: the shell is a
+  // separate process with its own offline screen + auto-reconnect, so an
+  // early launch is safe — it shows the offline page until 3080 answers.
+  ;(async () => {
     try {
       const exe = await ensureRuntime(ctx)
       launchShell(exe, ctx)
     } catch (err) {
       ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
     }
-  })
+  })()
 }
 
 // ---------- electron runtime provisioning ----------
@@ -93,6 +103,7 @@ async function ensureRuntime(ctx) {
   // 1) Already provisioned for this version?
   if (existsSync(exe)) {
     cleanupOldVersions(root, dir)
+    await patchExeIcon(ctx, exe, root).catch(() => {})
     return exe
   }
 
@@ -118,9 +129,55 @@ async function ensureRuntime(ctx) {
   }
   cleanupOldVersions(root, dir)
   ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
+  await patchExeIcon(ctx, exe, root).catch(() => {})
   return exe
 }
 
+/**
+ * Patch the runtime electron.exe's icon resource so the Windows taskbar
+ * shows our whale icon. A bare runtime exe ships Electron's default icon
+ * and — as documented — no runtime API (BrowserWindow icon, setAppDetails,
+ * AUMID shortcuts) can change the taskbar button: it reads the exe's icon
+ * resource. rcedit (electron team's official tool) rewrites it in place.
+ *
+ * Best-effort: icon patching must never block the shell from launching.
+ * Idempotent: a marker file next to the exe records success; a re-provisioned
+ * (new version) exe has no marker and gets patched again.
+ */
+async function patchExeIcon(ctx, exe, root) {
+  if (!isWin) return
+  const ico = join(PKG_ROOT, 'build', 'icon.ico')
+  if (!existsSync(ico)) return
+  const marker = `${exe}.whale-icon`
+  if (existsSync(marker)) return
+
+  // rcedit is a single self-contained exe, cached next to the runtimes.
+  const rcedit = join(root, 'rcedit-x64.exe')
+  if (!existsSync(rcedit)) {
+    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+    if (!(await fetchFile(url, rcedit))) {
+      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      return
+    }
+  }
+
+  const child = spawn(rcedit, [exe, '--set-icon', ico], {
+    windowsHide: true,
+    stdio: 'ignore',
+  })
+  const ok = await new Promise((resolve) => {
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+  if (ok) {
+    writeFileSync(marker, String(Date.now()), 'utf8')
+    ctx.logger.info('[clean-desktop-shell] taskbar icon patched (rcedit)')
+  } else {
+    ctx.logger.warn('[clean-desktop-shell] rcedit patch failed — taskbar icon stays default')
+  }
+}
+
 async function downloadRuntime(ctx, version, root, dir) {
   const tmpZip = join(root, `.electron-${version}.zip.tmp`)
   rmSync(tmpZip, { force: true })
@@ -143,33 +200,59 @@ async function downloadRuntime(ctx, version, root, dir) {
         rmSync(inner, { recursive: true, force: true })
       }
     }
+    // Failed download — drop the partial file so a later run starts clean.
+    rmSync(tmpZip, { force: true })
   }
   throw new Error('electron download failed from all sources')
 }
 
-/** Probe GitHub; reachable → official releases, else the npmmirror mirror. */
+/**
+ * Pick the download source by racing a HEAD probe against each candidate
+ * (direct connection, 3s each). The fastest reachable source goes first —
+ * this naturally prefers the domestic npmmirror mirror on CN networks,
+ * the official GitHub source on international/well-proxied networks, and
+ * never wastes a full download on a dead source.
+ */
 async function runtimeUrls(version) {
-  const official = `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}`
-  const mirror = `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}`
-  try {
-    const ctrl = new AbortController()
-    const timer = setTimeout(() => ctrl.abort(), 3000)
-    const res = await fetch('https://github.com', { signal: ctrl.signal, method: 'HEAD' })
-    clearTimeout(timer)
-    if (res.status < 500) return [official, mirror]
-  } catch {
-    // unreachable — mirror first
+  const candidates = [
+    { name: 'github', url: `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}` },
+    { name: 'npmmirror', url: `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}` },
+  ]
+  const results = await Promise.all(
+    candidates.map(async (c) => {
+      const t0 = Date.now()
+      try {
+        const ctrl = new AbortController()
+        const timer = setTimeout(() => ctrl.abort(), 3000)
+        const res = await fetch(c.url, { signal: ctrl.signal, method: 'HEAD' })
+        clearTimeout(timer)
+        if (res.status < 500) return { ...c, ms: Date.now() - t0 }
+      } catch {
+        // unreachable — drop
+      }
+      return null
+    }),
+  )
+  const ok = results.filter(Boolean).sort((a, b) => a.ms - b.ms)
+  if (ok.length === 0) {
+    // Probes all failed (offline?) — still try both, mirror first (cheap).
+    return [candidates[1].url, candidates[0].url]
   }
-  return [mirror, official]
+  const rest = candidates.map((c) => c.url).filter((u) => u !== ok[0].url)
+  return [ok[0].url, ...rest]
 }
 
 function fetchFile(url, dest) {
   return new Promise((resolve) => {
     // curl is available on Windows 10+; streams to disk, honors proxy env.
-    const child = spawn('curl', ['-L', '--fail', '--silent', '--show-error', '-o', dest, url], {
-      windowsHide: true,
-      stdio: 'ignore',
-    })
+    // --max-time keeps a stalled download from hanging forever (a proxy
+    // stall previously left a half-written .zip.tmp and blocked the shell
+    // launch); --retry 2 rides out transient failures.
+    const child = spawn(
+      'curl',
+      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', '600', '-o', dest, url],
+      { windowsHide: true, stdio: 'ignore' },
+    )
     child.on('error', () => resolve(false))
     child.on('exit', (code) => resolve(code === 0))
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-clean-desktop-shell",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Clean desktop shell for DeepSeek Harness (DSH) as a DSH plugin — reuses your web profile, tray/single-instance/auto-launch, zero visual changes. DSH 插件形态的纯净桌面壳：复用现有 web profile，托盘管理后端，零视觉改造。",
   "type": "module",
   "main": "lib/index.js",
@@ -10,6 +10,7 @@
     "src/",
     "scripts/",
     "build/icon.png",
+    "build/icon.ico",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",

package/src/client/client.js

@@ -1,10 +1,19 @@
 /**
  * dsh-clean-desktop-shell — client half (web browser bundle).
  *
- * Registers a settings row so the shell's target URL / material options
- * are editable from Settings → General. This is a minimal placeholder:
- * real UI wiring lands with the Electron shell work.
+ * The shell is a standalone Electron window; it injects nothing into the
+ * dsh web UI. This client module exists only to satisfy the client-modules
+ * loader contract — a bundle's client entry must register itself via
+ * `window.__ModuleLoader__.load({ id, factory })`, otherwise dsh reports
+ * "loaded without registering … via __ModuleLoader__.load".
  */
-export function apply() {
-  // placeholder: settings-row wiring arrives with the shell implementation
-}
+window.__ModuleLoader__.load({
+  id: 'dsh-clean-desktop-shell',
+  factory: () => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    exports.apply = () => {};
+    return module.exports;
+  },
+});

package/src/host/index.js

@@ -30,6 +30,7 @@ import {
   renameSync,
   rmSync,
   symlinkSync,
+  writeFileSync,
 } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -42,22 +43,31 @@ const EXE_NAME = isWin ? 'electron.exe' : 'electron'
 const ARCH = process.arch === 'arm64' ? 'arm64' : 'x64'
 const PLATFORM = isWin ? 'win32' : process.platform === 'darwin' ? 'darwin' : 'linux'
 
+// cordis registers the plugin by this name — bundles without an explicit
+// `name` export are silently skipped by the dsh loader.
+export const name = 'dsh-clean-desktop-shell'
+
 // Disable auto-launch with DSH_SHELL_AUTO_LAUNCH=0.
 const AUTO_LAUNCH = process.env.DSH_SHELL_AUTO_LAUNCH !== '0'
 
 let launched = false
 
 export function apply(ctx) {
-  ctx.on('ready', async () => {
-    ctx.logger.info('[clean-desktop-shell] mounted (host half)')
-    if (!AUTO_LAUNCH) return
+  ctx.logger.info('[clean-desktop-shell] mounted (host half)')
+  if (!AUTO_LAUNCH) return
+  // The dsh bundle loader calls apply() during early boot, but the cordis
+  // 'ready' event never fires for bundle plugins (dshmarket / agent-teams
+  // use ctx.inject or run inline instead). Launch directly: the shell is a
+  // separate process with its own offline screen + auto-reconnect, so an
+  // early launch is safe — it shows the offline page until 3080 answers.
+  ;(async () => {
     try {
       const exe = await ensureRuntime(ctx)
       launchShell(exe, ctx)
     } catch (err) {
       ctx.logger.warn(`[clean-desktop-shell] shell launch failed: ${err?.message ?? err}`)
     }
-  })
+  })()
 }
 
 // ---------- electron runtime provisioning ----------
@@ -93,6 +103,7 @@ async function ensureRuntime(ctx) {
   // 1) Already provisioned for this version?
   if (existsSync(exe)) {
     cleanupOldVersions(root, dir)
+    await patchExeIcon(ctx, exe, root).catch(() => {})
     return exe
   }
 
@@ -118,9 +129,55 @@ async function ensureRuntime(ctx) {
   }
   cleanupOldVersions(root, dir)
   ctx.logger.info(`[clean-desktop-shell] electron runtime ${version} ready at ${dir}`)
+  await patchExeIcon(ctx, exe, root).catch(() => {})
   return exe
 }
 
+/**
+ * Patch the runtime electron.exe's icon resource so the Windows taskbar
+ * shows our whale icon. A bare runtime exe ships Electron's default icon
+ * and — as documented — no runtime API (BrowserWindow icon, setAppDetails,
+ * AUMID shortcuts) can change the taskbar button: it reads the exe's icon
+ * resource. rcedit (electron team's official tool) rewrites it in place.
+ *
+ * Best-effort: icon patching must never block the shell from launching.
+ * Idempotent: a marker file next to the exe records success; a re-provisioned
+ * (new version) exe has no marker and gets patched again.
+ */
+async function patchExeIcon(ctx, exe, root) {
+  if (!isWin) return
+  const ico = join(PKG_ROOT, 'build', 'icon.ico')
+  if (!existsSync(ico)) return
+  const marker = `${exe}.whale-icon`
+  if (existsSync(marker)) return
+
+  // rcedit is a single self-contained exe, cached next to the runtimes.
+  const rcedit = join(root, 'rcedit-x64.exe')
+  if (!existsSync(rcedit)) {
+    const url = 'https://github.com/electron/rcedit/releases/download/v2.0.0/rcedit-x64.exe'
+    ctx.logger.info('[clean-desktop-shell] downloading rcedit for icon patching')
+    if (!(await fetchFile(url, rcedit))) {
+      ctx.logger.warn('[clean-desktop-shell] rcedit download failed — taskbar icon stays default')
+      return
+    }
+  }
+
+  const child = spawn(rcedit, [exe, '--set-icon', ico], {
+    windowsHide: true,
+    stdio: 'ignore',
+  })
+  const ok = await new Promise((resolve) => {
+    child.on('error', () => resolve(false))
+    child.on('exit', (code) => resolve(code === 0))
+  })
+  if (ok) {
+    writeFileSync(marker, String(Date.now()), 'utf8')
+    ctx.logger.info('[clean-desktop-shell] taskbar icon patched (rcedit)')
+  } else {
+    ctx.logger.warn('[clean-desktop-shell] rcedit patch failed — taskbar icon stays default')
+  }
+}
+
 async function downloadRuntime(ctx, version, root, dir) {
   const tmpZip = join(root, `.electron-${version}.zip.tmp`)
   rmSync(tmpZip, { force: true })
@@ -143,33 +200,59 @@ async function downloadRuntime(ctx, version, root, dir) {
         rmSync(inner, { recursive: true, force: true })
       }
     }
+    // Failed download — drop the partial file so a later run starts clean.
+    rmSync(tmpZip, { force: true })
   }
   throw new Error('electron download failed from all sources')
 }
 
-/** Probe GitHub; reachable → official releases, else the npmmirror mirror. */
+/**
+ * Pick the download source by racing a HEAD probe against each candidate
+ * (direct connection, 3s each). The fastest reachable source goes first —
+ * this naturally prefers the domestic npmmirror mirror on CN networks,
+ * the official GitHub source on international/well-proxied networks, and
+ * never wastes a full download on a dead source.
+ */
 async function runtimeUrls(version) {
-  const official = `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}`
-  const mirror = `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}`
-  try {
-    const ctrl = new AbortController()
-    const timer = setTimeout(() => ctrl.abort(), 3000)
-    const res = await fetch('https://github.com', { signal: ctrl.signal, method: 'HEAD' })
-    clearTimeout(timer)
-    if (res.status < 500) return [official, mirror]
-  } catch {
-    // unreachable — mirror first
+  const candidates = [
+    { name: 'github', url: `https://github.com/electron/electron/releases/download/v${version}/${zipName(version)}` },
+    { name: 'npmmirror', url: `https://npmmirror.com/mirrors/electron/${version}/${zipName(version)}` },
+  ]
+  const results = await Promise.all(
+    candidates.map(async (c) => {
+      const t0 = Date.now()
+      try {
+        const ctrl = new AbortController()
+        const timer = setTimeout(() => ctrl.abort(), 3000)
+        const res = await fetch(c.url, { signal: ctrl.signal, method: 'HEAD' })
+        clearTimeout(timer)
+        if (res.status < 500) return { ...c, ms: Date.now() - t0 }
+      } catch {
+        // unreachable — drop
+      }
+      return null
+    }),
+  )
+  const ok = results.filter(Boolean).sort((a, b) => a.ms - b.ms)
+  if (ok.length === 0) {
+    // Probes all failed (offline?) — still try both, mirror first (cheap).
+    return [candidates[1].url, candidates[0].url]
   }
-  return [mirror, official]
+  const rest = candidates.map((c) => c.url).filter((u) => u !== ok[0].url)
+  return [ok[0].url, ...rest]
 }
 
 function fetchFile(url, dest) {
   return new Promise((resolve) => {
     // curl is available on Windows 10+; streams to disk, honors proxy env.
-    const child = spawn('curl', ['-L', '--fail', '--silent', '--show-error', '-o', dest, url], {
-      windowsHide: true,
-      stdio: 'ignore',
-    })
+    // --max-time keeps a stalled download from hanging forever (a proxy
+    // stall previously left a half-written .zip.tmp and blocked the shell
+    // launch); --retry 2 rides out transient failures.
+    const child = spawn(
+      'curl',
+      ['-L', '--fail', '--silent', '--show-error', '--retry', '2', '--max-time', '600', '-o', dest, url],
+      { windowsHide: true, stdio: 'ignore' },
+    )
     child.on('error', () => resolve(false))
     child.on('exit', (code) => resolve(code === 0))
   })

package/version.txt

@@ -1 +1 @@
-0.1.3
+0.1.4