dsh-version-status 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# dsh-version-status
+
+> DeepSeek Harness (DSH) 版本检测与更新提醒插件：在 Web GUI 侧边栏常驻显示当前版本与更新徽标，检测到新版本时亮起提示，点击展开详情面板并提供一键复制升级命令。
+
+## 🌟 核心特性
+
+1. **版本精准比对（SemVer 2.0.0）**：
+   - 完整支持主版本、次版本、补丁版本以及先行版本号（Pre-release 如 `rc.1`, `beta.2`）的精准比较规则。
+   - 正确识别正式版高于 rc 版（如 `0.1.2` > `0.1.2-rc.1`）、升级补丁版（如 `0.1.3` > `0.1.2-rc.1`）。
+
+2. **双端协同架构（Host / Client 分工）**：
+   - **Host 端（Node.js / Cordis）**：实现多级本地版本获取（argv 回溯 -> npm/pnpm 全局目录 -> CLI 兜底）、国内镜像与官方 npm registry 双源竞速探测（带 3.5s 超时与内存缓存防雪崩），暴露 `GET /api/dsh-version` 接口。
+   - **Client 端（Web 前端）**：注入 `sidebar.footer.action` 侧边栏底部胶囊，支持宽/窄模式自适应；注入 `shell.overlay` 弹层卡片，提供版本状态、更新日志外链与一键复制升级指令。
+
+3. **网络弹性与离线容灾**：
+   - 超时严格限制在 3.5 秒内，离线或断网情况下不卡死 Web 界面，平滑降级并保留错误提示。
+   - 内置 15 分钟 TTL 内存缓存，避免频繁穿透请求 npm。
+   - 支持 `?force=1` 强制穿透刷新。
+
+4. **便捷调试与测试（Mock 支持）**：
+   - 接口支持 `?mockLatest=0.1.3` 查询参数或 `DSH_MOCK_LATEST_VERSION` 环境变量，方便测试验证有新版本时的 UI 交互与复制功能。
+
+---
+
+## 📦 目录结构
+
+```text
+dsh-update-notifier/
+├── cordis.patch.yml       # Cordis 服务插槽补丁
+├── package.json           # 模块配置与 exports 映射
+├── README.md              # 插件说明文档
+├── src/
+│   ├── index.js           # Host 端服务与版本比对逻辑
+│   └── client.js          # Client 端侧边栏胶囊与弹窗组件
+└── test/
+    └── index.test.js      # 自动化单元测试套件
+```
+
+---
+
+## 🚀 安装与启用
+
+### 方式一：本地链接开发测试（推荐）
+
+在 DSH 的 Web profile 目录下添加软链或直接安装：
+
+```sh
+# 1. 注册本地插件至 web profile
+dsh plugin --profile web add ./output/20260907-dsh-update-notifier/dsh-update-notifier
+
+# 2. 重启 dsh web 实例生效
+dsh web
+```
+
+### 方式二：npm 官方包安装（待发布后）
+
+```sh
+dsh plugin --profile web add dsh-version-status
+```
+
+---
+
+## 🔌 Host 端 HTTP 接口规范
+
+### `GET /api/dsh-version`（或别名 `/api/dsh-update/status`）
+
+#### 请求参数（Query）
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `force` | boolean | 否 | 传 `1` 时穿透 15 分钟缓存，立即重走 npm registry 探测 |
+| `mockLatest` | string | 否 | 用于测试模拟，例如 `?mockLatest=0.1.3` 强制指定最新版本号 |
+
+#### 响应示例（无新版本）
+```json
+{
+  "ok": true,
+  "currentVersion": "0.1.2-rc.1",
+  "latestVersion": "0.1.2-rc.1",
+  "updateAvailable": false,
+  "hasUpdate": false,
+  "hasError": false,
+  "errorMessage": null,
+  "checkedAt": 1757234400000,
+  "checkedAtIso": "2026-09-07T08:50:00.000Z",
+  "sources": {
+    "local": "global-npm-win",
+    "registry": "https://registry.npmmirror.com/@deepseek-ai%2fdsh/latest"
+  },
+  "upgradeCommand": "npm install -g @deepseek-ai/dsh@latest",
+  "upgradeCommands": {
+    "npm": "npm install -g @deepseek-ai/dsh@latest",
+    "pnpm": "pnpm add -g @deepseek-ai/dsh@latest",
+    "yarn": "yarn global add @deepseek-ai/dsh@latest"
+  },
+  "releaseUrl": "https://github.com/deepseek-ai/deepseek-harness/releases",
+  "changelogUrl": "https://github.com/deepseek-ai/deepseek-harness/releases"
+}
+```
+
+#### 响应示例（发现新版本）
+```json
+{
+  "ok": true,
+  "currentVersion": "0.1.2-rc.1",
+  "latestVersion": "0.1.3",
+  "updateAvailable": true,
+  "hasUpdate": true,
+  "hasError": false,
+  "errorMessage": null,
+  "checkedAt": 1757234400000,
+  "checkedAtIso": "2026-09-07T08:50:00.000Z",
+  "upgradeCommand": "npm install -g @deepseek-ai/dsh@latest",
+  "upgradeCommands": {
+    "npm": "npm install -g @deepseek-ai/dsh@latest",
+    "pnpm": "pnpm add -g @deepseek-ai/dsh@latest",
+    "yarn": "yarn global add @deepseek-ai/dsh@latest"
+  },
+  "releaseUrl": "https://github.com/deepseek-ai/deepseek-harness/releases"
+}
+```
+
+---
+
+## 🧪 运行单元测试与校验
+
+```sh
+cd output/20260907-dsh-update-notifier/dsh-update-notifier
+
+# 运行全量沙箱内联测试套件（包含 SemVer 比对、本地探测、Registry 双源拉取、离线降级与 Client 槽位/剪贴板降级测试）
+npm test
+# 或直接运行：
+node test/run-in-process.js
+```
+
+---
+
+## 🛡️ 健壮性与安全设计审查
+
+1. **零阻塞启动与渲染**：
+   - 本地版本探测采用纯文件系统（`package.json` 静态解析）+ 进程命令行递归回溯，不发起耗时慢速进程调用。
+   - npm 探测严格限制在 3.5 秒以内，双端竞速超时后静默降级，不阻塞 WebServer 启动或 Web 客户端首次渲染。
+   - 断网或镜像源不可达时，自动返回当前本地版本并标记 `hasError: true`，UI 保持稳定呈现，无未捕获异常。
+
+2. **剪贴板多重兼容兜底**：
+   - 优先使用现代 `navigator.clipboard.writeText` 异步接口；
+   - 在非 HTTPS/远程 IP 局域网访问或权限受限环境自动向下平滑降级至 `document.execCommand('copy')`；
+   - 复制成功后提供 2 秒「已复制 ✓」视觉反馈与样式高亮。
+
+3. **严格 SemVer 2.0.0 规范**：
+   - 核心数字主版本、次版本、补丁版本数值比对；
+   - 先行版本号（pre-release 如 `rc.1`）支持数字段与标识符分段比对（`0.1.2-rc.10` > `0.1.2-rc.1`）；
+   - 正式版本高于先行版本（`0.1.2` > `0.1.2-rc.1`）；
+   - 构建元数据（build metadata 如 `+build.1`）遵循规范不参与优先级判定。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-version-status bundle patch: adds the host version notifier service.
+# The client half joins the browser graph automatically because package.json declares
+# dsh.client and exports "./client".
+- insert:
+    - id: version-status
+      name: dsh-version-status

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "dsh-version-status",
+  "version": "0.1.0",
+  "description": "DSH core version monitor & upgrade helper: sidebar status badge, npm release checker, and one-click update command",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "update-notifier",
+    "version-checker",
+    "upgrade-helper"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node test/run-in-process.js"
+  }
+}

package/src/client.js

@@ -0,0 +1,757 @@
+/**
+ * dsh-update-notifier — Client half (Web GUI).
+ *
+ * Hand-written __ModuleLoader__ bundle, zero build step.
+ * Slots:
+ *   - sidebar.footer.action : Pill capsule in sidebar footer (status light, version text, update badge)
+ *   - shell.overlay         : Floating detail panel (version diff, one-click upgrade commands, changelog link)
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-version-status',
+  factory: (require) => {
+    const module = { exports: {} }
+    const exports = module.exports
+    const React = require('react')
+    const h = React.createElement
+    const { useEffect, useState, useRef, useSyncExternalStore } = React
+
+    // ---------- Styles & Animations ----------
+    const CSS = `
+      div[class*="footerActions"] {
+        display: flex !important;
+        flex-direction: column !important;
+        gap: 4px !important;
+        width: 100% !important;
+      }
+      @keyframes dshUpdateFadeSlideUp {
+        from { opacity: 0; transform: translateY(8px) scale(0.98); }
+        to { opacity: 1; transform: translateY(0) scale(1); }
+      }
+      @keyframes dshUpdateFadeSlideDown {
+        from { opacity: 1; transform: translateY(0) scale(1); }
+        to { opacity: 0; transform: translateY(8px) scale(0.98); }
+      }
+      @keyframes dshUpdatePulse {
+        0% { box-shadow: 0 0 0 0 rgba(245, 158, 11, 0.55); }
+        70% { box-shadow: 0 0 0 6px rgba(245, 158, 11, 0); }
+        100% { box-shadow: 0 0 0 0 rgba(245, 158, 11, 0); }
+      }
+      @keyframes dshUpdateSpin {
+        to { transform: rotate(360deg); }
+      }
+      .dsh-update-panel-enter {
+        animation: dshUpdateFadeSlideUp 0.18s cubic-bezier(0.16, 1, 0.3, 1) both;
+      }
+      .dsh-update-panel-exit {
+        animation: dshUpdateFadeSlideDown 0.14s ease-in both;
+        pointer-events: none !important;
+      }
+      .dsh-update-dot-pulse {
+        animation: dshUpdatePulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+      }
+      .dsh-update-spin {
+        display: inline-block;
+        animation: dshUpdateSpin 0.9s linear infinite;
+      }
+      .dsh-update-btn {
+        transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease, transform 0.1s ease;
+      }
+      .dsh-update-btn:hover:not(:disabled) {
+        background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,0.08)) !important;
+      }
+      .dsh-update-btn:active:not(:disabled) {
+        transform: scale(0.97);
+      }
+      .dsh-update-pill:hover {
+        background: var(--dsw-alias-interactive-bg-hover, rgba(255, 255, 255, 0.06)) !important;
+        border-color: var(--dsw-alias-border-l2, rgba(255, 255, 255, 0.15)) !important;
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .dsh-update-panel-enter, .dsh-update-panel-exit, .dsh-update-dot-pulse, .dsh-update-spin {
+          animation: none !important;
+        }
+      }
+    `
+
+    // ---------- Theme Tokens ----------
+    const T = {
+      bg: 'var(--dsw-alias-bg-layer-2, #18181b)',
+      well: 'var(--dsw-alias-bg-layer-1, #27272a)',
+      border: 'var(--dsw-alias-border-l1, rgba(255, 255, 255, 0.1))',
+      border2: 'var(--dsw-alias-border-l2, rgba(255, 255, 255, 0.18))',
+      label: 'var(--dsw-alias-label-primary, #f4f4f5)',
+      secondary: 'var(--dsw-alias-label-secondary, #a1a1aa)',
+      brand: 'var(--dsw-alias-brand-primary, #3b82f6)',
+      ok: 'var(--dsw-alias-state-success-primary, #10b981)',
+      warn: 'var(--dsw-alias-state-warn-primary, #f59e0b)',
+      err: 'var(--dsw-alias-state-error-primary, #ef4444)',
+    }
+
+    // ---------- Global Store ----------
+    const store = {
+      state: {
+        open: false,
+        phase: 'closed', // 'closed' | 'open' | 'closing'
+        loading: false,
+        copiedKey: null,
+        selectedTab: 'npm', // 'npm' | 'pnpm' | 'yarn'
+        status: {
+          ok: true,
+          currentVersion: '...',
+          latestVersion: '...',
+          updateAvailable: false,
+          hasUpdate: false,
+          hasError: false,
+          errorMessage: null,
+          checkedAt: 0,
+          upgradeCommand: 'npm install -g @deepseek-ai/dsh@latest',
+          upgradeCommands: {
+            npm: 'npm install -g @deepseek-ai/dsh@latest',
+            pnpm: 'pnpm add -g @deepseek-ai/dsh@latest',
+            yarn: 'yarn global add @deepseek-ai/dsh@latest'
+          },
+          releaseUrl: 'https://github.com/deepseek-ai/deepseek-harness/releases'
+        }
+      },
+      listeners: new Set(),
+      set(patch) {
+        store.state = { ...store.state, ...patch }
+        for (const fn of store.listeners) fn()
+      },
+      subscribe(fn) {
+        store.listeners.add(fn)
+        return () => store.listeners.delete(fn)
+      }
+    }
+
+    function useStore() {
+      return useSyncExternalStore(store.subscribe, () => store.state)
+    }
+
+    // ---------- API Call ----------
+    async function fetchUpdateStatus(force = false) {
+      store.set({ loading: true })
+      try {
+        const url = `/api/dsh-version${force ? '?force=1' : ''}`
+        const res = await fetch(url, {
+          headers: { accept: 'application/json' },
+          cache: 'no-store'
+        })
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        const data = await res.json()
+        if (data && data.ok) {
+          store.set({ status: data, loading: false })
+        } else {
+          store.set({ loading: false })
+        }
+      } catch (err) {
+        store.set({
+          loading: false,
+          status: {
+            ...store.state.status,
+            hasError: true,
+            errorMessage: err.message || '网络检查异常'
+          }
+        })
+      }
+    }
+
+    // ---------- Helpers ----------
+    async function copyToClipboard(text, key) {
+      let copied = false
+      if (navigator?.clipboard?.writeText) {
+        try {
+          await navigator.clipboard.writeText(text)
+          copied = true
+        } catch (err) {
+          // Clipboard API rejected (e.g. non-secure HTTP context or lack of permission), fall through
+        }
+      }
+      if (!copied) {
+        try {
+          const ta = document.createElement('textarea')
+          ta.value = text
+          ta.style.position = 'fixed'
+          ta.style.opacity = '0'
+          document.body.appendChild(ta)
+          ta.select()
+          copied = document.execCommand('copy')
+          document.body.removeChild(ta)
+        } catch (e) {
+          console.error('Failed to copy command via fallback:', e)
+        }
+      }
+      if (copied) {
+        store.set({ copiedKey: key })
+        setTimeout(() => {
+          if (store.state.copiedKey === key) {
+            store.set({ copiedKey: null })
+          }
+        }, 2000)
+      }
+    }
+
+    function toggleOpen() {
+      const s = store.state
+      if (s.phase === 'open') {
+        store.set({ phase: 'closing' })
+        setTimeout(() => {
+          store.set({ open: false, phase: 'closed' })
+        }, 150)
+      } else {
+        store.set({ open: true, phase: 'open' })
+        // If not checked yet, fetch status
+        if (!s.status.checkedAt) {
+          fetchUpdateStatus(false)
+        }
+      }
+    }
+
+    function closePanel() {
+      if (store.state.phase === 'open') {
+        store.set({ phase: 'closing' })
+        setTimeout(() => {
+          store.set({ open: false, phase: 'closed' })
+        }, 150)
+      }
+    }
+
+    function formatTime(timestamp) {
+      if (!timestamp) return '未检测'
+      const d = new Date(timestamp)
+      const now = Date.now()
+      const diffSec = Math.floor((now - timestamp) / 1000)
+      if (diffSec < 60) return '刚刚'
+      if (diffSec < 3600) return `${Math.floor(diffSec / 60)} 分钟前`
+      const h = String(d.getHours()).padStart(2, '0')
+      const m = String(d.getMinutes()).padStart(2, '0')
+      return `今日 ${h}:${m}`
+    }
+
+    // ---------- SVG Icons ----------
+    const Icons = {
+      rocket: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 14, height: 14, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('path', { d: 'M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09z' }),
+          h('path', { d: 'm12 15-3-3a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.35 22.35 0 0 1-4 2z' }),
+          h('path', { d: 'M9 12H4s.55-3.03 2-4c1.62-1.08 5 0 5 0' }),
+          h('path', { d: 'M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5' })
+        ),
+      copy: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 13, height: 13, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('rect', { x: 9, y: 9, width: 13, height: 13, rx: 2, ry: 2 }),
+          h('path', { d: 'M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1' })
+        ),
+      check: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 13, height: 13, fill: 'none', stroke: 'currentColor', strokeWidth: 2.5, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('polyline', { points: '20 6 9 17 4 12' })
+        ),
+      refresh: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 13, height: 13, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('path', { d: 'M21.5 2v6h-6M21.34 15.57a10 10 0 1 1-.57-8.38l5.67-5.67' })
+        ),
+      external: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 12, height: 12, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('path', { d: 'M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6' }),
+          h('polyline', { points: '15 3 21 3 21 9' }),
+          h('line', { x1: 10, y1: 14, x2: 21, y2: 3 })
+        ),
+      close: () =>
+        h('svg', { viewBox: '0 0 24 24', width: 14, height: 14, fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' },
+          h('line', { x1: 18, y1: 6, x2: 6, y2: 18 }),
+          h('line', { x1: 6, y1: 6, x2: 18, y2: 18 })
+        )
+    }
+
+    // ---------- Component: Footer Capsule Entry ----------
+    function FooterEntry(props) {
+      const state = useStore()
+      const { wide } = props
+      const st = state.status
+      const hasUpdate = st.updateAvailable || st.hasUpdate
+      const isFolded = wide === false
+
+      // On mount: fetch initial status if not yet loaded
+      useEffect(() => {
+        if (!st.checkedAt) {
+          fetchUpdateStatus(false)
+        }
+      }, [])
+
+      // Indicator color & pulse
+      const dotColor = state.loading
+        ? T.brand
+        : hasUpdate
+          ? T.warn
+          : st.hasError
+            ? T.err
+            : T.ok
+
+      const tooltip = hasUpdate
+        ? `发现新版本: v${st.latestVersion} (当前 v${st.currentVersion})，点击查看升级`
+        : `DSH v${st.currentVersion} (已是最新)`
+
+      // Folded Rail (Compact Icon) Mode
+      if (isFolded) {
+        return h(
+          'button',
+          {
+            className: 'dsh-update-btn',
+            onClick: toggleOpen,
+            title: tooltip,
+            style: {
+              width: 32,
+              height: 32,
+              borderRadius: 8,
+              border: `1px solid ${hasUpdate ? T.warn : T.border}`,
+              background: hasUpdate ? 'rgba(245, 158, 11, 0.12)' : 'transparent',
+              color: hasUpdate ? T.warn : T.label,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              cursor: 'pointer',
+              position: 'relative',
+              margin: '0 auto',
+              padding: 0,
+            }
+          },
+          [
+            hasUpdate ? h(Icons.rocket) : h('span', {
+              style: {
+                width: 7,
+                height: 7,
+                borderRadius: '50%',
+                background: dotColor,
+                display: 'inline-block',
+              }
+            }),
+            hasUpdate ? h('span', {
+              className: 'dsh-update-dot-pulse',
+              style: {
+                position: 'absolute',
+                top: 4,
+                right: 4,
+                width: 6,
+                height: 6,
+                borderRadius: '50%',
+                background: T.warn,
+              }
+            }) : null
+          ]
+        )
+      }
+
+      // Expanded Sidebar (Full Pill Capsule) Mode
+      return h(
+        'div',
+        {
+          className: 'dsh-update-pill dsh-update-btn',
+          onClick: toggleOpen,
+          title: tooltip,
+          style: {
+            display: 'flex',
+            alignItems: 'center',
+            height: 28,
+            width: '100%',
+            padding: '0 8px',
+            borderRadius: 7,
+            border: `1px solid ${hasUpdate ? 'rgba(245, 158, 11, 0.4)' : T.border}`,
+            background: hasUpdate ? 'rgba(245, 158, 11, 0.08)' : 'transparent',
+            cursor: 'pointer',
+            fontSize: 11,
+            userSelect: 'none',
+            boxSizing: 'border-box',
+          }
+        },
+        [
+          // Dot or spinner
+          state.loading
+            ? h('span', {
+                className: 'dsh-update-spin',
+                style: {
+                  width: 8,
+                  height: 8,
+                  borderRadius: '50%',
+                  border: `2px solid ${T.brand}`,
+                  borderTopColor: 'transparent',
+                  marginRight: 7,
+                  flexShrink: 0
+                }
+              })
+            : h('span', {
+                className: hasUpdate ? 'dsh-update-dot-pulse' : '',
+                style: {
+                  width: 7,
+                  height: 7,
+                  borderRadius: '50%',
+                  background: dotColor,
+                  marginRight: 7,
+                  flexShrink: 0
+                }
+              }),
+
+          // Version text
+          h('span', {
+            style: {
+              color: hasUpdate ? T.label : T.secondary,
+              fontWeight: hasUpdate ? 600 : 400,
+              whiteSpace: 'nowrap',
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              flex: 1
+            }
+          }, hasUpdate ? `有新版 v${st.latestVersion}` : `DSH v${st.currentVersion}`),
+
+          // Right badge
+          hasUpdate
+            ? h('span', {
+                style: {
+                  fontSize: 9,
+                  fontWeight: 700,
+                  color: '#fff',
+                  background: T.warn,
+                  padding: '1px 5px',
+                  borderRadius: 4,
+                  marginLeft: 4,
+                  flexShrink: 0,
+                  letterSpacing: '0.3px'
+                }
+              }, 'UPGRADE')
+            : h('span', {
+                style: {
+                  fontSize: 10,
+                  color: T.secondary,
+                  opacity: 0.6,
+                  marginLeft: 4,
+                  flexShrink: 0
+                }
+              }, '✓')
+        ]
+      )
+    }
+
+    // ---------- Component: Overlay Panel ----------
+    function OverlayPanel() {
+      const state = useStore()
+      const panelRef = useRef(null)
+      const { phase, status: st, copiedKey, selectedTab, loading } = state
+      const hasUpdate = st.updateAvailable || st.hasUpdate
+
+      // Close on clicking outside
+      useEffect(() => {
+        if (phase !== 'open') return
+        function handleOutside(e) {
+          if (panelRef.current && !panelRef.current.contains(e.target)) {
+            // Check if clicked element was the footer entry trigger
+            const trigger = document.querySelector('.dsh-update-pill, .dsh-update-btn')
+            if (trigger && trigger.contains(e.target)) return
+            closePanel()
+          }
+        }
+        window.addEventListener('mousedown', handleOutside)
+        return () => window.removeEventListener('mousedown', handleOutside)
+      }, [phase])
+
+      if (phase === 'closed') return null
+
+      const tabs = ['npm', 'pnpm', 'yarn']
+      const activeCommand = (st.upgradeCommands && st.upgradeCommands[selectedTab]) || st.upgradeCommand
+
+      return h(
+        'div',
+        {
+          ref: panelRef,
+          className: phase === 'closing' ? 'dsh-update-panel-exit' : 'dsh-update-panel-enter',
+          style: {
+            position: 'fixed',
+            left: 12,
+            bottom: 54,
+            width: 360,
+            maxWidth: 'calc(100vw - 24px)',
+            background: T.bg,
+            border: `1px solid ${T.border}`,
+            borderRadius: 14,
+            boxShadow: '0 12px 36px rgba(0, 0, 0, 0.45)',
+            display: 'flex',
+            flexDirection: 'column',
+            overflow: 'hidden',
+            pointerEvents: phase === 'closing' ? 'none' : 'auto',
+            zIndex: 70,
+            fontSize: 12,
+            lineHeight: 1.4,
+          }
+        },
+        [
+          // Header
+          h('div', {
+            style: {
+              display: 'flex',
+              alignItems: 'center',
+              padding: '12px 14px',
+              borderBottom: `1px solid ${T.border}`,
+              background: 'rgba(255, 255, 255, 0.02)'
+            }
+          }, [
+            h('span', { style: { display: 'flex', alignItems: 'center', gap: 6, fontWeight: 600, color: T.label } }, [
+              h(Icons.rocket),
+              'DSH 版本检测'
+            ]),
+            // Status Tag
+            h('span', {
+              style: {
+                marginLeft: 8,
+                fontSize: 10,
+                padding: '2px 6px',
+                borderRadius: 4,
+                background: hasUpdate ? 'rgba(245, 158, 11, 0.15)' : 'rgba(16, 185, 129, 0.15)',
+                color: hasUpdate ? T.warn : T.ok,
+                fontWeight: 500,
+              }
+            }, hasUpdate ? '发现新版本' : '已是最新'),
+
+            // Close button
+            h('button', {
+              className: 'dsh-update-btn',
+              onClick: closePanel,
+              title: '关闭',
+              style: {
+                marginLeft: 'auto',
+                border: 'none',
+                background: 'transparent',
+                color: T.secondary,
+                cursor: 'pointer',
+                padding: '3px',
+                borderRadius: 4,
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center'
+              }
+            }, h(Icons.close))
+          ]),
+
+          // Body Content
+          h('div', { style: { padding: '14px', display: 'flex', flexDirection: 'column', gap: 12 } }, [
+            // Version Comparison Card
+            h('div', {
+              style: {
+                background: T.well,
+                border: `1px solid ${T.border}`,
+                borderRadius: 10,
+                padding: '12px',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 8
+              }
+            }, [
+              h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } }, [
+                // Local version box
+                h('div', { style: { display: 'flex', flexDirection: 'column' } }, [
+                  h('span', { style: { fontSize: 10, color: T.secondary } }, '当前本地版本'),
+                  h('span', { style: { fontSize: 13, fontWeight: 600, color: T.label, fontFamily: 'monospace' } }, `v${st.currentVersion}`)
+                ]),
+
+                // Arrow
+                h('span', { style: { fontSize: 14, color: hasUpdate ? T.warn : T.secondary, opacity: 0.8 } }, '➔'),
+
+                // Latest version box
+                h('div', { style: { display: 'flex', flexDirection: 'column', alignItems: 'flex-end' } }, [
+                  h('span', { style: { fontSize: 10, color: T.secondary } }, 'npm 最新版本'),
+                  h('span', {
+                    style: {
+                      fontSize: 13,
+                      fontWeight: 600,
+                      color: hasUpdate ? T.warn : T.ok,
+                      fontFamily: 'monospace'
+                    }
+                  }, `v${st.latestVersion}`)
+                ])
+              ]),
+
+              // Comparison note
+              h('div', {
+                style: {
+                  fontSize: 11,
+                  color: hasUpdate ? T.warn : T.secondary,
+                  borderTop: `1px dashed ${T.border}`,
+                  paddingTop: 8,
+                  marginTop: 2,
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'space-between'
+                }
+              }, [
+                h('span', null, hasUpdate ? '★ 建议升级以体验最新能力与修复' : '✓ 运行良好，无需更新'),
+                h('span', { style: { fontSize: 10, color: T.secondary, opacity: 0.75 } }, formatTime(st.checkedAt))
+              ])
+            ]),
+
+            // One-Click Upgrade Command Section
+            h('div', { style: { display: 'flex', flexDirection: 'column', gap: 6 } }, [
+              h('div', { style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } }, [
+                h('span', { style: { fontSize: 11, fontWeight: 500, color: T.label } }, '升级命令（一键复制）：'),
+                // Package Manager Tabs
+                h('div', { style: { display: 'flex', gap: 4 } }, tabs.map(tab =>
+                  h('button', {
+                    key: tab,
+                    className: 'dsh-update-btn',
+                    onClick: () => store.set({ selectedTab: tab }),
+                    style: {
+                      border: 'none',
+                      background: selectedTab === tab ? T.brand : 'rgba(255,255,255,0.06)',
+                      color: selectedTab === tab ? '#fff' : T.secondary,
+                      fontSize: 10,
+                      padding: '2px 7px',
+                      borderRadius: 4,
+                      cursor: 'pointer',
+                      fontWeight: selectedTab === tab ? 600 : 400
+                    }
+                  }, tab)
+                ))
+              ]),
+
+              // Code Box with Copy Button
+              h('div', {
+                style: {
+                  background: 'rgba(0,0,0,0.3)',
+                  border: `1px solid ${T.border}`,
+                  borderRadius: 8,
+                  padding: '8px 10px',
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 8,
+                  boxSizing: 'border-box'
+                }
+              }, [
+                h('code', {
+                  style: {
+                    flex: 1,
+                    fontFamily: 'Consolas, Menlo, monospace',
+                    fontSize: 11,
+                    color: T.label,
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    userSelect: 'all'
+                  }
+                }, activeCommand),
+
+                // Copy Action Button
+                h('button', {
+                  className: 'dsh-update-btn',
+                  onClick: () => copyToClipboard(activeCommand, selectedTab),
+                  style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 4,
+                    flexShrink: 0,
+                    border: `1px solid ${copiedKey === selectedTab ? T.ok : T.border2}`,
+                    background: copiedKey === selectedTab ? 'rgba(16, 185, 129, 0.15)' : 'rgba(255, 255, 255, 0.08)',
+                    color: copiedKey === selectedTab ? T.ok : T.label,
+                    borderRadius: 6,
+                    padding: '4px 8px',
+                    fontSize: 10,
+                    fontWeight: 500,
+                    cursor: 'pointer'
+                  }
+                }, [
+                  copiedKey === selectedTab ? h(Icons.check) : h(Icons.copy),
+                  copiedKey === selectedTab ? '已复制 ✓' : '复制'
+                ])
+              ])
+            ])
+          ]),
+
+          // Ops Footer Bar
+          h('div', {
+            style: {
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              padding: '10px 14px',
+              borderTop: `1px solid ${T.border}`,
+              background: 'rgba(255, 255, 255, 0.02)'
+            }
+          }, [
+            // Changelog Link
+            h('a', {
+              href: st.releaseUrl || 'https://github.com/deepseek-ai/deepseek-harness/releases',
+              target: '_blank',
+              rel: 'noopener noreferrer',
+              style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 4,
+                color: T.brand,
+                textDecoration: 'none',
+                fontSize: 11
+              }
+            }, [
+              '更新日志',
+              h(Icons.external)
+            ]),
+
+            // Check Now Button
+            h('button', {
+              className: 'dsh-update-btn',
+              disabled: loading,
+              onClick: () => fetchUpdateStatus(true),
+              style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 5,
+                border: `1px solid ${T.border2}`,
+                background: 'rgba(255, 255, 255, 0.05)',
+                color: T.label,
+                padding: '4px 10px',
+                borderRadius: 6,
+                fontSize: 11,
+                cursor: loading ? 'default' : 'pointer'
+              }
+            }, [
+              loading
+                ? h('span', { className: 'dsh-update-spin' }, h(Icons.refresh))
+                : h(Icons.refresh),
+              loading ? '检查中...' : '检查更新'
+            ])
+          ])
+        ]
+      )
+    }
+
+    // ---------- Plugin Apply Entrypoint ----------
+    function apply(ctx) {
+      // 1. Inject Stylesheet into Document Head
+      ctx.effect(() => {
+        const el = document.createElement('style')
+        el.id = 'dsh-update-notifier-styles'
+        el.textContent = CSS
+        document.head.appendChild(el)
+        return () => el.remove()
+      })
+
+      // 2. Register Sidebar Footer Action Capsule
+      ctx.effect(() =>
+        ctx.slots.inject('sidebar.footer.action', () =>
+          ctx.slots.register(
+            { name: 'sidebar.footer.action', id: 'dsh-update-notifier', order: 20 },
+            (props) => h(FooterEntry, props)
+          )
+        )
+      )
+
+      // 3. Register Shell Overlay Floating Panel
+      ctx.effect(() =>
+        ctx.slots.inject('shell.overlay', () =>
+          ctx.slots.register(
+            { name: 'shell.overlay', id: 'dsh-update-panel', order: 20 },
+            () => h(OverlayPanel)
+          )
+        )
+      )
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots']
+    return module.exports
+  }
+})

package/src/index.js

@@ -0,0 +1,415 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { execSync } from 'node:child_process'
+
+export const name = 'update-notifier'
+export const inject = ['webServer']
+
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+const DEFAULT_CACHE_TTL_MS = 15 * 60 * 1000 // 15 minutes
+const REQUEST_TIMEOUT_MS = 3500
+
+export const REGISTRY_ENDPOINTS = [
+  'https://registry.npmmirror.com/@deepseek-ai%2fdsh/latest',
+  'https://registry.npmjs.org/@deepseek-ai%2fdsh/latest'
+]
+
+export const DEFAULT_RELEASE_URL = 'https://github.com/deepseek-ai/deepseek-harness/releases'
+
+/**
+ * Parse a semver string into structured components.
+ * Supports standard semver 2.0: major.minor.patch[-prerelease][+build]
+ * @param {string} v
+ */
+export function parseSemver(v) {
+  if (!v || typeof v !== 'string') return null
+  const cleaned = v.trim().replace(/^[vV]/, '')
+  const match = cleaned.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/)
+  if (!match) return null
+
+  return {
+    raw: v,
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+    prerelease: match[4] ? match[4].split('.') : [],
+    build: match[5] ? match[5].split('.') : []
+  }
+}
+
+/**
+ * Compare two semver strings according to SemVer 2.0.0 rules.
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {number} 1 if v1 > v2, -1 if v1 < v2, 0 if v1 === v2
+ */
+export function compareSemver(v1, v2) {
+  const s1 = parseSemver(v1)
+  const s2 = parseSemver(v2)
+
+  if (!s1 || !s2) {
+    if (s1 && !s2) return 1
+    if (!s1 && s2) return -1
+    return String(v1).localeCompare(String(v2))
+  }
+
+  if (s1.major !== s2.major) return s1.major > s2.major ? 1 : -1
+  if (s1.minor !== s2.minor) return s1.minor > s2.minor ? 1 : -1
+  if (s1.patch !== s2.patch) return s1.patch > s2.patch ? 1 : -1
+
+  // Core versions match, compare prereleases
+  const p1 = s1.prerelease
+  const p2 = s2.prerelease
+
+  // Normal version has higher precedence than prerelease version
+  if (p1.length === 0 && p2.length > 0) return 1
+  if (p1.length > 0 && p2.length === 0) return -1
+  if (p1.length === 0 && p2.length === 0) return 0
+
+  // Compare prerelease identifiers left to right
+  const maxLen = Math.max(p1.length, p2.length)
+  for (let i = 0; i < maxLen; i++) {
+    const id1 = p1[i]
+    const id2 = p2[i]
+
+    if (id1 === undefined) return -1 // smaller set of prerelease identifiers
+    if (id2 === undefined) return 1
+    if (id1 === id2) continue
+
+    const isNum1 = /^\d+$/.test(id1)
+    const isNum2 = /^\d+$/.test(id2)
+
+    if (isNum1 && isNum2) {
+      const n1 = parseInt(id1, 10)
+      const n2 = parseInt(id2, 10)
+      if (n1 !== n2) return n1 > n2 ? 1 : -1
+      continue
+    }
+
+    // Numeric identifiers have lower precedence than non-numeric
+    if (isNum1 && !isNum2) return -1
+    if (!isNum1 && isNum2) return 1
+
+    // Both non-numeric: lexical comparison
+    const cmp = id1.localeCompare(id2)
+    if (cmp !== 0) return cmp > 0 ? 1 : -1
+  }
+
+  return 0
+}
+
+/**
+ * Safely reads and parses package.json if it exists at target directory.
+ * @param {string} dir
+ */
+function readPackageJsonVersion(dir) {
+  try {
+    const file = path.join(dir, 'package.json')
+    if (!fs.existsSync(file)) return null
+    const content = fs.readFileSync(file, 'utf8')
+    const pkg = JSON.parse(content)
+    if (pkg.name === DSH_PACKAGE && typeof pkg.version === 'string') {
+      return { version: pkg.version, path: file }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Multi-tier detection of current local DSH version.
+ * @returns {{ version: string, source: string, packagePath?: string }}
+ */
+export function detectLocalVersion() {
+  // Tier 1: Traverse upwards from process.argv[1] (typically .../dsh/lib/bin.js)
+  if (process.argv[1]) {
+    try {
+      let cur = path.resolve(path.dirname(process.argv[1]))
+      for (let i = 0; i < 6; i++) {
+        const res = readPackageJsonVersion(cur)
+        if (res) {
+          return { version: res.version, source: 'process-argv', packagePath: res.path }
+        }
+        const parent = path.dirname(cur)
+        if (parent === cur) break
+        cur = parent
+      }
+    } catch {}
+  }
+
+  // Tier 2: Check Windows global npm directory
+  if (process.env.APPDATA) {
+    const winGlobal = path.join(process.env.APPDATA, 'npm', 'node_modules', '@deepseek-ai', 'dsh')
+    const res = readPackageJsonVersion(winGlobal)
+    if (res) {
+      return { version: res.version, source: 'global-npm-win', packagePath: res.path }
+    }
+  }
+
+  // Tier 3: Check global pnpm directories
+  if (process.env.LOCALAPPDATA) {
+    const pnpmGlobal = path.join(process.env.LOCALAPPDATA, 'pnpm', 'global', '5', 'node_modules', '@deepseek-ai', 'dsh')
+    const res = readPackageJsonVersion(pnpmGlobal)
+    if (res) {
+      return { version: res.version, source: 'global-pnpm-win', packagePath: res.path }
+    }
+  }
+
+  // Tier 4: Check standard Unix / macOS paths
+  const unixPaths = [
+    '/usr/local/lib/node_modules/@deepseek-ai/dsh',
+    '/usr/lib/node_modules/@deepseek-ai/dsh'
+  ]
+  for (const up of unixPaths) {
+    const res = readPackageJsonVersion(up)
+    if (res) {
+      return { version: res.version, source: 'global-unix', packagePath: res.path }
+    }
+  }
+
+  // Tier 5: Fallback to running CLI `dsh --version`
+  try {
+    const stdout = execSync('dsh --version', { encoding: 'utf8', timeout: 2500, stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (stdout) {
+      const parsed = stdout.replace(/^[vV]/, '').split(/\s+/)[0]
+      if (parseSemver(parsed)) {
+        return { version: parsed, source: 'cli-exec' }
+      }
+    }
+  } catch {}
+
+  // Tier 6: Default fallback
+  return { version: '0.1.2-rc.1', source: 'fallback-default' }
+}
+
+/**
+ * Fetch the latest version from npm registry endpoints with dual-source fallback.
+ * @param {object} [options]
+ * @param {string[]} [options.endpoints]
+ * @param {number} [options.timeout]
+ * @returns {Promise<{ version: string, registryUrl: string }>}
+ */
+export async function fetchLatestVersion(options = {}) {
+  const endpoints = options.endpoints || REGISTRY_ENDPOINTS
+  const timeout = options.timeout || REQUEST_TIMEOUT_MS
+  let lastError = null
+
+  for (const url of endpoints) {
+    try {
+      const res = await fetch(url, {
+        headers: {
+          accept: 'application/json',
+          'user-agent': 'dsh-update-notifier/0.1.0'
+        },
+        signal: AbortSignal.timeout(timeout)
+      })
+
+      if (!res.ok) {
+        lastError = new Error(`Registry HTTP ${res.status}: ${res.statusText} (${url})`)
+        continue
+      }
+
+      const data = await res.json()
+      if (data && typeof data.version === 'string') {
+        return {
+          version: data.version.trim(),
+          registryUrl: url
+        }
+      }
+      lastError = new Error(`Invalid registry response payload from ${url}`)
+    } catch (err) {
+      lastError = err
+    }
+  }
+
+  throw lastError || new Error('Failed to fetch latest version from all registry endpoints')
+}
+
+/**
+ * Service class managing version checks, caching, and response assembly.
+ */
+export class VersionService {
+  constructor(options = {}) {
+    this.cacheTtlMs = options.cacheTtlMs || DEFAULT_CACHE_TTL_MS
+    this.cachedStatus = null
+    this.inFlightPromise = null
+  }
+
+  /**
+   * Builds update status, utilizing cache unless force is specified.
+   * @param {object} [opts]
+   * @param {boolean} [opts.force]
+   * @param {string} [opts.mockLatest]
+   */
+  async getStatus(opts = {}) {
+    const { force = false, mockLatest } = opts
+    const now = Date.now()
+
+    // If mockLatest is provided, build instant synthetic result for testing
+    if (mockLatest) {
+      const local = detectLocalVersion()
+      const isAvailable = compareSemver(mockLatest, local.version) > 0
+      return this._formatResponse({
+        currentVersion: local.version,
+        latestVersion: mockLatest,
+        updateAvailable: isAvailable,
+        hasError: false,
+        errorMessage: null,
+        checkedAt: now,
+        sources: {
+          local: local.source,
+          registry: 'mock-override'
+        }
+      })
+    }
+
+    // Return unexpired cache if available and not forced
+    if (!force && this.cachedStatus && (now - this.cachedStatus.checkedAt < this.cacheTtlMs)) {
+      return this.cachedStatus
+    }
+
+    // Reuse in-flight fetch if multiple requests arrive simultaneously
+    if (this.inFlightPromise) {
+      return this.inFlightPromise
+    }
+
+    this.inFlightPromise = (async () => {
+      const local = detectLocalVersion()
+      let latestVersion = null
+      let registryUrl = null
+      let hasError = false
+      let errorMessage = null
+
+      try {
+        const remote = await fetchLatestVersion()
+        latestVersion = remote.version
+        registryUrl = remote.registryUrl
+      } catch (err) {
+        hasError = true
+        errorMessage = err instanceof Error ? err.message : String(err)
+
+        // If we have stale cache, preserve its latestVersion while noting error
+        if (this.cachedStatus && this.cachedStatus.latestVersion) {
+          latestVersion = this.cachedStatus.latestVersion
+          registryUrl = this.cachedStatus.sources?.registry || 'stale-cache'
+        }
+      }
+
+      const effectiveLatest = latestVersion || local.version
+      const updateAvailable = latestVersion ? compareSemver(latestVersion, local.version) > 0 : false
+
+      const result = this._formatResponse({
+        currentVersion: local.version,
+        latestVersion: effectiveLatest,
+        updateAvailable,
+        hasError,
+        errorMessage,
+        checkedAt: Date.now(),
+        sources: {
+          local: local.source,
+          registry: registryUrl || 'none'
+        }
+      })
+
+      if (!hasError || !this.cachedStatus) {
+        this.cachedStatus = result
+      }
+      return result
+    })().finally(() => {
+      this.inFlightPromise = null
+    })
+
+    return this.inFlightPromise
+  }
+
+  _formatResponse(data) {
+    const upgradeCommands = {
+      npm: 'npm install -g @deepseek-ai/dsh@latest',
+      pnpm: 'pnpm add -g @deepseek-ai/dsh@latest',
+      yarn: 'yarn global add @deepseek-ai/dsh@latest'
+    }
+
+    return {
+      ok: true,
+      currentVersion: data.currentVersion,
+      latestVersion: data.latestVersion,
+      updateAvailable: data.updateAvailable,
+      hasUpdate: data.updateAvailable,
+      hasError: data.hasError,
+      errorMessage: data.errorMessage,
+      checkedAt: data.checkedAt,
+      checkedAtIso: new Date(data.checkedAt).toISOString(),
+      sources: data.sources,
+      upgradeCommand: upgradeCommands.npm,
+      upgradeCommands,
+      releaseUrl: DEFAULT_RELEASE_URL,
+      changelogUrl: DEFAULT_RELEASE_URL
+    }
+  }
+}
+
+/**
+ * Send JSON HTTP response with no-store cache control.
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {any} body
+ */
+export function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store'
+  })
+  res.end(JSON.stringify(body, null, 2))
+}
+
+/**
+ * Cordis plugin apply entrypoint.
+ * Registers WebServer routes:
+ *   - GET /api/dsh-version
+ *   - GET /api/dsh-update/status
+ */
+export function apply(ctx) {
+  const service = new VersionService()
+
+  async function handleStatusRequest(req, res) {
+    if (req.method !== 'GET') {
+      return sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: 'GET only' } })
+    }
+
+    try {
+      const url = new URL(req.url || '/', 'http://localhost')
+      const force = url.searchParams.has('force') || url.searchParams.has('refresh')
+      const mockLatest = url.searchParams.get('mockLatest') || process.env.DSH_MOCK_LATEST_VERSION || undefined
+
+      const status = await service.getStatus({ force, mockLatest })
+      sendJson(res, 200, status)
+    } catch (err) {
+      sendJson(res, 500, {
+        ok: false,
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: err instanceof Error ? err.message : String(err)
+        }
+      })
+    }
+  }
+
+  // 1. Register GET /api/dsh-version (Primary contract)
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/api/dsh-version',
+      handler: handleStatusRequest
+    })
+  )
+
+  // 2. Register GET /api/dsh-update/status (Alias for compatibility)
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/api/dsh-update/status',
+      handler: handleStatusRequest
+    })
+  )
+}