refactor(updater, ui): 优化更新流程、移除冗余状态管理

- 重构更新器，移除状态缓存，优化检查流程，改为每次启动时重新检测。
- 优化预览版提示逻辑和界面样式，增加版本号和提示信息的视觉区分。
- 移除`useElectronAPI` Hook，简化 Electron API 访问，直接使用 `window.electronAPI`。
- 调整 Release Notes 生成逻辑，修复检出代码问题，获取完整 git 历史和所有 tags。
- 优化版本忽略功能，`useUpdater`改为单例模式，支持预览版过滤。
- 移除build:parallel脚本中的build:desktop-only任务。

docs(dev): 更新桌面端自动更新系统设计文档

- 新增系统设计文档，描述自动更新系统的架构和界面布局。
- 补充 electron-updater 版本号说明，推荐使用 SemVer 2.0.0 标准。

Author: linshenkx

.github/workflows/release.yml

@@ -17,6 +17,9 @@ jobs:
     steps:
       - name: 检出代码
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 获取完整的git历史
+          fetch-tags: true  # 确保获取所有tags
 
       - name: 安装 pnpm
         uses: pnpm/action-setup@v2
@@ -141,6 +144,9 @@ jobs:
     steps:
       - name: 检出代码
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 获取完整的git历史
+          fetch-tags: true  # 确保获取所有tags
 
       - name: 安装 pnpm
         uses: pnpm/action-setup@v2
@@ -257,6 +263,9 @@ jobs:
     steps:
       - name: 检出代码
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 获取完整的git历史
+          fetch-tags: true  # 确保获取所有tags
 
       - name: 安装 pnpm
         uses: pnpm/action-setup@v2
@@ -376,6 +385,9 @@ jobs:
     steps:
       - name: 检出代码
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 获取完整的git历史
+          fetch-tags: true  # 确保获取所有tags
 
       - name: 获取版本号和类型
         id: version
@@ -430,35 +442,63 @@ jobs:
       - name: 生成 Release Notes
         id: release_notes
         run: |
-          # 获取上一个tag
-          PREVIOUS_TAG=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -2 | tail -1)
+          # 获取当前tag
           CURRENT_TAG=${{ steps.version.outputs.version }}
-
-          echo "Previous tag: $PREVIOUS_TAG"
           echo "Current tag: $CURRENT_TAG"
 
+          # 获取所有tags并调试输出
+          echo "All tags (sorted):"
+          git tag --sort=-version:refname | head -10
+
+          # 改进的上一个tag获取逻辑
+          # 1. 先尝试获取所有正式版本tag (不包含预览版)
+          STABLE_TAGS=$(git tag --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$')
+          echo "Stable tags found: $STABLE_TAGS"
+
+          # 2. 获取所有tag (包含预览版)
+          ALL_TAGS=$(git tag --sort=-version:refname)
+
+          # 3. 根据当前tag类型选择合适的比较策略
+          PREVIOUS_TAG=""
+          if [[ $CURRENT_TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            # 当前是正式版，找上一个正式版
+            PREVIOUS_TAG=$(echo "$STABLE_TAGS" | grep -v "^$CURRENT_TAG$" | head -1)
+            echo "Current is stable release, previous stable tag: $PREVIOUS_TAG"
+          else
+            # 当前是预览版，找上一个任意版本
+            PREVIOUS_TAG=$(echo "$ALL_TAGS" | grep -v "^$CURRENT_TAG$" | head -1)
+            echo "Current is prerelease, previous tag: $PREVIOUS_TAG"
+          fi
+
           # 生成commit历史（处理多行和长commit）
-          if [ -n "$PREVIOUS_TAG" ]; then
+          COMMITS=""
+          if [ -n "$PREVIOUS_TAG" ] && git rev-parse "$PREVIOUS_TAG" >/dev/null 2>&1 && git rev-parse "$CURRENT_TAG" >/dev/null 2>&1; then
+            echo "Generating commits from $PREVIOUS_TAG to $CURRENT_TAG"
             COMMITS=$(git log --pretty=format:"%s|%h" $PREVIOUS_TAG..$CURRENT_TAG | while IFS='|' read -r subject hash; do
               # 截断过长的commit message（保留前80个字符）
               if [ ${#subject} -gt 80 ]; then
                 subject="${subject:0:77}..."
               fi
-              echo "- $subject (\`$hash\`)"
+              echo "- $subject ([${hash}](https://github.com/${{ github.repository }}/commit/${hash}))"
             done)
-          else
-            COMMITS=$(git log --pretty=format:"%s|%h" $CURRENT_TAG | while IFS='|' read -r subject hash; do
+          elif git rev-parse "$CURRENT_TAG" >/dev/null 2>&1; then
+            echo "No previous tag found or invalid, showing commits for current tag"
+            COMMITS=$(git log --pretty=format:"%s|%h" --max-count=10 | while IFS='|' read -r subject hash; do
               # 截断过长的commit message（保留前80个字符）
               if [ ${#subject} -gt 80 ]; then
                 subject="${subject:0:77}..."
               fi
-              echo "- $subject (\`$hash\`)"
+              echo "- $subject ([${hash}](https://github.com/${{ github.repository }}/commit/${hash}))"
             done)
           fi
 
           # 检查是否有commits
           if [ -z "$COMMITS" ]; then
+            echo "No commits found, using fallback message"
             COMMITS="- 首次发布"
+          else
+            echo "Generated commits:"
+            echo "$COMMITS"
           fi
 
           # 限制commits数量（最多显示20个）
@@ -521,7 +561,7 @@ jobs:
           - **讨论交流**: [Discussions](https://github.com/${{ github.repository }}/discussions)
 
           ---
-          **提示**: 如果需要查看完整的提交历史，请访问 [GitHub Commits](https://github.com/\${{ github.repository }}/compare/$PREVIOUS_TAG...$CURRENT_TAG)
+          **提示**: 如果需要查看完整的提交历史，请访问项目的 [GitHub Commits](https://github.com/${{ github.repository }}/commits)
           EOF
 
           echo "Generated release notes:"

dev.md

@@ -272,6 +272,35 @@ ls packages/desktop/dist/
 - **正式版本**：`v1.0.0`, `v2.1.3` - 遵循语义化版本控制
 - **预览版本**：`v1.0.0-beta.1`, `v1.0.0-rc.1`, `v1.0.0-alpha.1`
 
+#### ⚠️ electron-updater 版本号注意事项
+
+**重要**：electron-updater 对预发布版本的处理有特殊限制，必须使用正确的版本号格式。
+
+**✅ 推荐格式（符合 SemVer 2.0.0 标准）**：
+```bash
+v1.2.6-alpha.1, v1.2.6-alpha.2, v1.2.6-alpha.3
+v1.2.6-beta.1, v1.2.6-beta.2, v1.2.6-beta.3
+v1.2.6-rc.1, v1.2.6-rc.2, v1.2.6-rc.3
+```
+
+**❌ 避免格式（可能导致 electron-updater 检测问题）**：
+```bash
+v1.2.6-alpha1, v1.2.6-alpha2, v1.2.6-alpha3
+v1.2.6-beta1, v1.2.6-beta2, v1.2.6-beta3
+v1.2.6-rc1, v1.2.6-rc2, v1.2.6-rc3
+```
+
+**问题说明**：
+- electron-updater 将预发布版本的第一部分（如 `beta2` 中的 `beta`）视为**频道标识符**
+- 使用 `beta1`, `beta2`, `beta3` 格式时，可能出现版本检测异常
+- 从 `v1.2.6-beta2` 无法正确检测到 `v1.2.6-beta3` 的更新
+- 使用点分隔格式 `beta.1`, `beta.2`, `beta.3` 可以避免此问题
+
+**最佳实践**：
+1. 始终使用点分隔的预发布版本号格式
+2. 遵循 `<version>-<stage>.<number>` 的命名规范
+3. 如果遇到版本检测问题，考虑跳过问题版本或重新发布
+
 #### 🔄 完整发布流程
 1. **开发阶段**：在 `develop` 分支开发新功能
 2. **版本准备**：在 `develop` 分支使用 `pnpm version:prepare` 更新版本号

docs/archives/007-electron-api-refactor-rollback.md

@@ -0,0 +1,188 @@
+# Electron API 重构与回滚经验记录
+
+## 📅 时间线
+- **2025-07-14**: 发现版本检查功能报错 "Failed to check versions"
+- **重构提交**: `12f6f49` - "feat(ui): 添加 Electron API Hook并重构更新管理"
+- **问题根源**: 过度抽象导致的架构复杂性和 bug
+
+## 🚨 问题描述
+
+### 症状
+```
+useUpdater.ts:224 [useUpdater] Error checking all versions: Error: Failed to check versions
+    at g (useUpdater.ts:128:15)
+```
+
+### 主进程日志正常
+```
+[DESKTOP] [2025-07-14 00:20:57] [info] Unified version check completed: { stable: '1.2.5', prerelease: '1.2.5' }
+```
+
+### 前端收到的响应
+```javascript
+{
+  currentVersion: '1.2.0',
+  stable: { hasUpdate: true, remoteVersion: '1.2.5', ... },
+  prerelease: { hasUpdate: true, remoteVersion: '1.2.5', ... }
+}
+// 但是 response.success 是 undefined
+```
+
+## 🔍 根本原因分析
+
+### 重构前（工作正常）
+```typescript
+// 简单直接
+const results = await window.electronAPI!.updater.checkAllVersions()
+```
+
+### 重构后（引入问题）
+```typescript
+// 过度抽象
+const { updater } = useElectronAPI()
+const response = await updater.checkAllVersions()
+if (!response.success) {  // response.success 是 undefined
+  throw new Error(response.error || 'Failed to check versions')
+}
+const results = response.data
+```
+
+### 问题链条
+1. **useUpdater.ts** 调用 `getElectronAPI()` 而不是 `useElectronAPI()`
+2. **getElectronAPI()** 直接返回 `window.electronAPI`，绕过了包装器
+3. **preload.js** 返回 `result.data`（直接数据）
+4. **useElectronAPI.ts** 期望 `{success, data, error}` 格式
+5. **数据格式不匹配** 导致 `response.success` 为 `undefined`
+
+## 🎯 重构的初衷 vs 实际效果
+
+### 初衷
+- 避免类型错误和 IDE 警告
+- 提供类型安全的 Electron API 访问
+
+### 实际效果
+- 引入了过度复杂的抽象层
+- 增加了调试难度
+- 创造了新的 bug
+- 维护成本大幅增加
+
+## 🔄 回滚操作记录
+
+### 1. 删除过度抽象文件
+```bash
+rm packages/ui/src/composables/useElectronAPI.ts
+```
+
+### 2. 回滚 useUpdater.ts
+- 移除 `useElectronAPI` 导入
+- 将所有 `electronUpdater` 改为 `window.electronAPI.updater`
+- 将所有 `electronShell` 改为 `window.electronAPI.shell`
+- 将所有 `electronOn/electronOff` 改为 `window.electronAPI.on/off`
+- 移除复杂的响应格式检查
+
+### 3. 简化类型定义
+```typescript
+// packages/ui/src/types/electron.d.ts
+interface UpdaterAPI {
+  checkAllVersions(): Promise<{
+    currentVersion: string
+    stable?: { remoteVersion?: string, hasUpdate?: boolean, ... }
+    prerelease?: { remoteVersion?: string, hasUpdate?: boolean, ... }
+  }>
+  installUpdate(): Promise<void>
+  ignoreVersion(version: string, versionType?: 'stable' | 'prerelease'): Promise<void>
+}
+
+interface ShellAPI {
+  openExternal(url: string): Promise<void>
+}
+```
+
+### 4. 保持 preload.js 简单
+```javascript
+checkAllVersions: async () => {
+  const result = await withTimeout(
+    ipcRenderer.invoke(IPC_EVENTS.UPDATE_CHECK_ALL_VERSIONS),
+    60000
+  );
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+  return result.data;  // 直接返回数据
+}
+```
+
+## 📚 经验教训
+
+### ❌ 过度工程化的问题
+1. **复杂度爆炸**: 为了解决简单问题引入复杂架构
+2. **调试困难**: 多层抽象使问题定位变得复杂
+3. **维护成本**: 需要维护额外的 Hook、类型定义、包装逻辑
+4. **新 bug 源**: 抽象层本身成为 bug 的来源
+
+### ✅ 正确的解决方案
+1. **简单的类型定义**: 通过完善 `electron.d.ts` 解决 IDE 警告
+2. **直接 API 调用**: 保持代码简洁明了
+3. **最小化抽象**: 只在真正需要时才引入抽象
+
+### 🎯 设计原则
+1. **KISS 原则**: Keep It Simple, Stupid
+2. **YAGNI 原则**: You Aren't Gonna Need It
+3. **优先解决核心问题**: 类型安全 ≠ 复杂抽象
+4. **渐进式改进**: 从简单开始，必要时再抽象
+
+## 🔧 最佳实践
+
+### 解决 IDE 警告的正确方法
+```typescript
+// ✅ 正确：完善类型定义
+declare global {
+  interface Window {
+    electronAPI: {
+      updater: UpdaterAPI
+      shell: ShellAPI
+      on: (event: string, callback: Function) => void
+      off: (event: string, callback: Function) => void
+    }
+  }
+}
+
+// ✅ 正确：直接使用
+const result = await window.electronAPI.updater.checkAllVersions()
+```
+
+### 避免过度抽象
+```typescript
+// ❌ 错误：不必要的包装
+const { updater } = useElectronAPI()
+const response = await updater.checkAllVersions()
+const result = response.data
+
+// ✅ 正确：直接调用
+const result = await window.electronAPI.updater.checkAllVersions()
+```
+
+## 🎉 结果
+
+### 回滚后的优势
+- **代码行数减少**: 删除了 100+ 行的包装代码
+- **调试简化**: 问题直接定位到源头
+- **类型安全**: 通过类型定义实现，无运行时开销
+- **维护简单**: 减少了抽象层的维护负担
+
+### 性能提升
+- **减少函数调用**: 直接 API 调用，无包装开销
+- **减少内存占用**: 无额外的包装对象
+- **提高可读性**: 代码意图更加明确
+
+## 💡 未来指导原则
+
+1. **先解决问题，再考虑抽象**
+2. **类型安全通过类型定义实现，而非运行时包装**
+3. **保持 API 调用的直接性和透明性**
+4. **抽象必须有明确的价值，而非为了抽象而抽象**
+5. **重构前要充分评估复杂度收益比**
+
+---
+
+**教训**: 有时候最好的重构就是不重构。简单的问题用简单的方法解决。

docs/archives/118-desktop-auto-update-system/README.md

@@ -121,9 +121,10 @@
 
 ## 📚 相关文档
 
-- [技术实现详解](./implementation.md) - 详细的技术实现和架构设计，包含深度重构的技术细节
-- [开发经验总结](./experience.md) - 可复用的技术经验和避坑指南，包含深度重构的经验教训
-- [问题修复记录](./fixes-record.md) - 完整的22个问题的发现、分析、修复过程
+- [设计文档](./design.md) - 系统架构设计、UI布局设计和交互流程设计
+- [技术实现详解](./implementation.md) - 详细的技术实现和架构设计
+- [开发经验总结](./experience.md) - 可复用的技术经验和避坑指南
+- [问题修复记录](./fixes-record.md) - 完整的问题发现、分析、修复过程
 
 ## ✅ 项目结论