新增: 功能路线图 + 9份需求契约

- feature-roadmap.md: 现有能力盘点 + P1/P2/P3方向 + 竞品参考 - AI深度视差: 远程推理方案(服务端Depth-Anything + 客户端WebGL) - 自动升级模块文档: 设计规格/任务规划/决策记录 - 9份需求契约: 视频/颜色提取/时间段/番茄钟/播放列表/电池/网页/便签/监控
2026-05-28 19:06:39 +08:00
parent f5a473c4b8
commit cd7247d880
19 changed files with 1044 additions and 33 deletions
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/README.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/README.md
@@ -0,0 +1,24 @@
+# 自动升级模块
+
+**模块状态**：待开发
+**最后更新**：2026-05-28
+
+---
+
+## 快速导航
+
+| 类型 | 文档 | 说明 |
+|------|------|------|
+| 规划 | [任务规划.md](./任务规划.md) | 实施步骤和检查清单 |
+| 设计 | [设计文档/自动升级功能设计.md](./设计文档/自动升级功能设计.md) | 完整功能设计 |
+| 决策 | [决策记录/](./决策记录/) | 架构和设计决策 |
+| 问题 | [问题追踪/](./问题追踪/) | 待解决问题 |
+| 检查 | [核对报告/](./核对报告/) | 实现检查报告 |
+| 测试 | [测试用例/](./测试用例/) | 测试用例 |
+
+## 核心设计
+
+- **弹窗策略**：非强制 → 右下角气泡（稍后 + 立即升级），强制 → 居中弹窗（仅立即升级）
+- **架构**：主程序检查版本 → 弹窗提示 → 启动 updater.exe → 下载替换重启
+- **updater.exe**：通用升级器，参数化驱动，可复用于其他产品（u-tabs 等）
+- **商业化预留**：API 预留 tier/license 字段，升级器不含商业逻辑
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/任务规划.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/任务规划.md
@@ -0,0 +1,53 @@
+# 自动升级 — 任务规划
+
+> 创建时间：2026-05-28
+
+## 阶段一：版本基础设施
+
+- [ ] `main.go` 增加版本变量，`-ldflags` 编译注入
+- [ ] `config.go` 增加 `update_url`、`auto_check_update`、`skip_version` 字段
+- [ ] `updater.go` 实现版本检查函数 `checkUpdate()`
+
+## 阶段二：升级弹窗
+
+- [ ] `web/update.html` 升级弹窗页面（右下角气泡 + 居中弹窗两种模式）
+- [ ] Go 端创建无边框 WebView2 弹窗窗口
+- [ ] 弹窗内容渲染：版本号、更新说明、按钮
+- [ ] 根据 `force` 字段切换弹窗位置和按钮
+
+## 阶段三：升级器程序
+
+- [ ] `updater/main.go` 独立程序骨架
+- [ ] HTTP 下载安装包 + 进度日志
+- [ ] SHA256 校验
+- [ ] 备份旧版本
+- [ ] 替换 + 启动新版本
+- [ ] 启动失败自动回滚
+- [ ] 日志写入 `updater.log`
+
+## 阶段四：主程序集成
+
+- [ ] 主程序释放 updater.exe 到临时目录
+- [ ] 构造命令行参数启动 updater
+- [ ] 主程序退出
+- [ ] 托盘菜单增加"检查更新"
+
+## 阶段五：发布流程
+
+- [ ] 构建脚本同时构建 u-desktop.exe + updater.exe
+- [ ] publish 技能自动生成 version.json（版本号 + SHA256 + 下载 URL）
+- [ ] 上传 version.json 和安装包到 c.1216.top
+
+## 阶段六：验证
+
+- [ ] 手动模拟版本更新，测试弹窗流程
+- [ ] 测试 updater 下载 + 替换 + 重启
+- [ ] 测试回滚机制
+- [ ] 测试强制升级流程
+
+## 技术要点
+
+- 版本号通过 `-ldflags "-X main.version=x.x.x"` 注入
+- updater.exe 通用设计，参数化驱动，不含业务逻辑
+- 弹窗用 WebView2 无边框窗口，风格与设置窗口一致
+- version.json 放 c.1216.top，静态文件
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/决策记录/README.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/决策记录/README.md
@@ -0,0 +1,17 @@
+# 决策记录
+
+记录自动升级模块的架构和设计决策。
+
+## 格式
+
+```
+ADR-{编号} - {标题}
+  状态：提议 | 已接受 | 已废弃
+  上下文：...
+  决策：...
+  理由：...
+```
+
+## 已记录
+
+（暂无）
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/核对报告/README.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/核对报告/README.md
@@ -0,0 +1,3 @@
+# 核对报告
+
+实现过程中的检查报告。
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/测试用例/README.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/测试用例/README.md
@@ -0,0 +1,3 @@
+# 测试用例
+
+自动升级功能的测试用例。
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/设计文档/自动升级功能设计.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/设计文档/自动升级功能设计.md
@@ -0,0 +1,278 @@
+# 自动升级系统 — 实现规格
+
+> 来源：需求探索会话 2026-05-28
+> 状态：待开发
+
+---
+
+## 1. 架构总览
+
+```
+┌──────────────┐
+│  远程版本 JSON │  ← 静态文件，放 CDN / OSS
+│  version.json │
+└──────┬───────┘
+       │ HTTP GET
+       ▼
+┌──────────────────┐
+│  u-desktop.exe    │  ← 主程序
+│  · 启动时检查版本  │
+│  · 弹窗提示升级    │
+│  · 释放 updater   │
+└──────┬───────────┘
+       │ 启动进程
+       ▼
+┌──────────────────┐
+│  updater.exe      │  ← 通用升级器，参数化驱动
+│  · 下载安装包      │
+│  · SHA256 校验    │
+│  · 备份旧版本      │
+│  · 替换 + 启动    │
+│  · 失败自动回滚    │
+└──────────────────┘
+```
+
+---
+
+## 2. 主程序改动
+
+### 2.1 版本号注入
+
+`main.go` 增加版本变量，编译时注入：
+
+```go
+var version = "dev" // -ldflags "-X main.version=0.6.0"
+```
+
+`build` 脚本 / publish 技能同步更新 ldflags。
+
+### 2.2 版本检查模块
+
+新增 `updater.go`：
+
+```
+func checkUpdate() (*UpdateInfo, error)
+```
+
+- 启动时异步调用（不阻塞主流程）
+- 请求远程 `version.json`
+- 对比当前 version，返回更新信息或 nil
+
+远程 version.json 格式：
+
+```json
+{
+  "version": "0.7.0",
+  "force": false,
+  "release_notes": "· 新增视频壁纸\n· 修复全屏检测偶发失效",
+  "package": {
+    "url": "https://c.1216.top/u-desktop/u-desktop-0.7.0.zip",
+    "size": 8388608,
+    "sha256": "abc123def456..."
+  }
+}
+```
+
+version.json URL 存入 config 或硬编码默认值。
+
+### 2.3 升级弹窗
+
+用 WebView2 新建一个无边框小窗口，HTML 渲染弹窗内容。
+
+#### 弹窗策略
+
+| force 字段 | 位置 | 按钮 |
+|-----------|------|------|
+| `false` | 右下角，托盘图标上方 | [稍后] [立即升级] |
+| `true` | 屏幕居中 | [立即升级]（仅一个按钮） |
+
+#### 弹窗 HTML 结构
+
+右下角气泡（非强制）：
+
+```
+┌─────────────────────────────┐
+│  发现新版本 v0.7.0           │
+│                             │
+│  · 新增视频壁纸              │
+│  · 修复全屏检测偶发失效       │
+│                             │
+│         [稍后]  [立即升级]   │
+└─────────────────────────────┘
+```
+
+居中弹窗（强制）：
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│         发现新版本 v0.7.0            │
+│                                     │
+│  · 新增视频壁纸                     │
+│  · 修复全屏检测偶发失效             │
+│                                     │
+│  大小: 8MB  |  预计用时: ~10秒      │
+│                                     │
+│              [立即升级]              │
+└─────────────────────────────────────┘
+```
+
+#### 弹窗窗口参数
+
+| 参数 | 右下角 | 居中 |
+|------|--------|------|
+| 宽度 | 340px | 420px |
+| 高度 | auto（内容自适应） | auto |
+| 位置 | 屏幕右下角 - 边距 20px | 屏幕居中 |
+| 样式 | 无边框，圆角，毛玻璃 | 无边框，圆角，毛玻璃 |
+| 置顶 | TOPMOST | TOPMOST |
+
+### 2.4 用户点击"立即升级"
+
+1. 从自身嵌入资源释放 `updater.exe` 到临时目录（或主程序同级目录）
+2. 构造命令行参数启动 updater.exe
+3. 主程序退出
+
+```go
+exec.Command(tmpUpdaterPath,
+    "--package-url", info.Package.URL,
+    "--sha256", info.Package.SHA256,
+    "--target", selfExePath,
+    "--version", info.Version,
+    "--force", strconv.FormatBool(info.Force),
+).Start()
+// 主程序退出
+```
+
+### 2.5 托盘菜单
+
+新增菜单项："检查更新"，手动触发版本检查。
+
+---
+
+## 3. updater.exe
+
+### 3.1 职责
+
+通用升级器，不含业务逻辑，纯参数驱动。可复用于其他产品（u-tabs 等）。
+
+### 3.2 命令行参数
+
+```bash
+updater.exe \
+  --package-url <下载地址> \
+  --sha256 <SHA256校验值> \
+  --target <目标exe路径> \
+  --version <目标版本号> \
+  --force \
+  --backup-dir <备份目录，默认 target 同级 backup/>
+```
+
+### 3.3 流程
+
+```
+1. 显示进度窗口（WebView2 或控制台）
+2. HTTP GET 下载 package-url → 临时文件
+   - 显示下载进度（已下载/总大小）
+   - 支持断点续传（可选，初期不做）
+3. 计算下载文件 SHA256，与参数比对
+   - 不匹配 → 报错退出
+4. 备份当前 target → backup-dir/old-{timestamp}.exe
+5. 如果是 zip 包：解压后替换
+   如果是 exe：直接覆盖
+6. 启动新版本 target
+7. updater 退出
+
+异常处理：
+- 下载失败 → 重试 3 次，间隔 5s
+- 校验失败 → 报错，不替换
+- 启动新版本后监听 5s，新进程退出则回滚
+- 回滚：将 backup 中的旧 exe 还原
+```
+
+### 3.4 进度显示
+
+初期：无 UI，日志写 `updater.log`（`-H windowsgui` 隐藏控制台）。
+后续：可加 WebView2 进度窗口。
+
+### 3.5 日志
+
+写入 `updater.log`（与 target 同目录），包含时间戳、步骤、错误信息。
+
+---
+
+## 4. 构建 & 发布流程
+
+### 4.1 主程序构建
+
+```bash
+go build -ldflags "-H windowsgui -X main.version=0.7.0" -o u-desktop.exe
+```
+
+### 4.2 updater 构建
+
+独立 main 包，单独目录（如 `updater/`）：
+
+```bash
+cd updater && go build -ldflags "-H windowsgui" -o updater.exe
+```
+
+### 4.3 发布
+
+1. 构建 `u-desktop.exe` + `updater.exe`
+2. UPX 压缩（可选）
+3. 计算 SHA256
+4. 上传到 `c.1216.top`
+5. 更新远程 `version.json`
+6. 更新 publish 技能（自动生成 version.json + 上传）
+
+---
+
+## 5. 配置
+
+`config.go` 新增字段：
+
+```go
+type Config struct {
+    // ... 现有字段
+    UpdateURL      string `json:"update_url"`       // 版本检查 URL，默认 https://c.1216.top/u-desktop/version.json
+    AutoCheckUpdate bool  `json:"auto_check_update"` // 启动时自动检查，默认 true
+    SkipVersion    string `json:"skip_version"`      // 用户跳过的版本号
+}
+```
+
+---
+
+## 6. 目录结构
+
+```
+u-desktop/
+├── main.go          # 增加版本变量
+├── updater.go       # 新增：版本检查 + 弹窗逻辑
+├── config.go        # 增加 update 相关字段
+├── systray.go       # 托盘菜单增加"检查更新"
+├── web/
+│   ├── update.html  # 新增：升级弹窗 HTML
+│   └── ...
+├── updater/         # 新增：升级器独立目录
+│   └── main.go
+├── docs/
+│   ├── feature-roadmap.md
+│   └── auto-update-spec.md  # 本文档
+└── ...
+```
+
+---
+
+## 7. 实施顺序
+
+| 步骤 | 内容 | 依赖 |
+|------|------|------|
+| 1 | `main.go` 加版本变量，构建脚本加 ldflags | 无 |
+| 2 | `updater.go` 版本检查函数 + config 字段 | 步骤 1 |
+| 3 | 远程 `version.json` 手动创建 + 上传 | 步骤 2 |
+| 4 | 升级弹窗 `update.html` + Go 端窗口创建 | 步骤 2 |
+| 5 | 主程序释放 + 启动 updater.exe | 步骤 4 |
+| 6 | `updater/` 目录，下载 + 校验 + 替换 + 回滚 | 步骤 5 |
+| 7 | 托盘菜单"检查更新" | 步骤 2 |
+| 8 | publish 技能集成 version.json 生成 | 步骤 3 |
--- a/docs/04-功能迭代/U-DESKTOP-1.自动升级/问题追踪/README.md
+++ b/docs/04-功能迭代/U-DESKTOP-1.自动升级/问题追踪/README.md
@@ -0,0 +1,10 @@
+# 问题追踪
+
+## 目录
+
+- `待讨论/` — 需要讨论后决定的问题
+- `待实现/` — 已确定但未实现的功能点
+
+## 当前问题
+
+（暂无）