# MateClaw Desktop UI 热更新设计

## 背景

当前 `mateclaw-desktop` 的运行链路不是“Electron 直接加载 `mateclaw-ui`”，而是：

1. Electron 启动并显示本地 Splash。
2. Electron 用内置 JRE 启动 `mateclaw-server.jar`。
3. `mateclaw-ui` 已提前构建到 `mateclaw-server/src/main/resources/static`。
4. `BrowserWindow` 最终加载 `http://localhost:{动态端口}`（由主进程在启动时随机选取）。

这意味着：

- 现在的 UI 资源和后端 JAR 强绑定。
- 任何 `mateclaw-ui` 改动，都要重新打包 `mateclaw-server.jar`，再跟着桌面安装包一起发布。
- 现有 `electron-updater` 只能做“整包升级”，不能做“仅 UI 升级”。

因此这里要解决的问题，不是开发态 HMR，而是生产态 OTA：让 `mateclaw-ui` 可以脱离桌面安装包独立更新。

## 目标

- 支持 `mateclaw-ui` 独立于 `mateclaw-desktop` 发布。
- UI 更新不要求用户下载新的桌面安装包。
- 保持当前本地 `localhost` 架构，不把桌面应用直接改成远程网站壳子。
- 更新失败可回滚到内置 UI。
- 不影响现有 `electron-updater` 的整包升级能力。

## 非目标

- 第一阶段不做后端 JAR 热更新。
- 第一阶段不允许 UI 任意突破当前后端 API 边界。
- 第一阶段不替换现有 Electron Splash / 自动升级通道。

## 现状约束

### 1. UI 当前被打进 Spring Boot JAR

`mateclaw-ui` 构建输出目录目前是：

- `../mateclaw-server/src/main/resources/static`

也就是 UI 构建产物直接进入后端静态资源目录，最终随 JAR 发布。

### 2. Desktop 最终加载的是后端地址

`mateclaw-desktop` 主窗口业务页当前加载：

- `http://localhost:{动态端口}`（端口由 Electron 主进程在启动时随机分配）

所以 UI 热更新不能只改 Electron `dist`，必须让后端在运行时能切换静态资源来源。

### 3. 现有整包升级已存在

桌面端已经接入 `electron-updater`，并通过 GitHub Releases 发布整包升级。

因此新方案应当与它并存：

- Shell / JRE / JAR 升级：继续走 `electron-updater`
- 纯前端升级：新增 UI OTA 通道

## 方案结论

推荐采用：

**方案 A：外置 UI Bundle + 本地优先加载 + Manifest 驱动的 OTA 更新**

核心思路：

1. `mateclaw-ui` 产出独立的静态包（zip）。
2. `mateclaw-desktop` 在启动时检查 UI 更新 Manifest。
3. 下载并校验新的 UI 包后，解压到 `userData/ui-bundles/<version>/`。
4. Electron 启动后端时，通过环境变量把“当前启用的 UI 目录”传给 Spring Boot。
5. Spring Boot 优先从外部目录提供静态资源；若外部目录不存在或损坏，则回退到 JAR 内置 `classpath:/static/`。
6. UI 更新完成后刷新窗口即可生效，无需安装新桌面包。

这是对当前架构改动最小、兼容性最强的路径。

## 为什么不选其他方案

### 方案 B：Electron 直接加载远程站点

不推荐作为主方案。

缺点：

- 桌面应用退化成网站壳子，离线能力明显变差。
- 安全面更大，远程页面注入风险更高。
- 当前路由是 `history` 模式，本地与远程混用会增加协议、资源路径和鉴权处理复杂度。
- 对现有 `localhost + Spring Boot` 架构破坏过大。

### 方案 C：把 UI 更新继续塞进 JAR 差分包

不满足目标。

原因：

- UI 仍与后端耦合。
- 每次 UI 变更都要重新发 JAR 和桌面安装包。
- 无法做到真正的“仅 UI 热更新”。

## 目标架构

```text
Electron Shell
├── Splash UI（本地 dist）
├── UI Update Manager（新增）
├── Bundled JRE
├── mateclaw-server.jar
└── BrowserWindow → http://localhost:{动态端口}
                     ├── 优先读取 userData/ui-bundles/current/
                     └── fallback 到 classpath:/static/
```

运行时目录建议：

```text
~/Library/Application Support/MateClaw/        # macOS 示例
├── data/
├── ui-bundles/
│   ├── current.json
│   ├── 1.0.3+20260405/
│   │   ├── index.html
│   │   ├── assets/...
│   │   └── meta.json
│   └── 1.0.4+20260410/
└── logs/
```

## 关键设计

### 1. UI 包格式

每个 UI 发布产物建议包含：

- `index.html`
- `assets/*`
- `logo/*`
- `icons/*`
- `meta.json`

`meta.json` 示例：

```json
{
  "uiVersion": "1.0.4",
  "buildId": "20260410.1",
  "minDesktopVersion": "1.0.0",
  "minServerApiVersion": "1.0",
  "maxServerApiVersion": "1.x",
  "sha256": "..."
}
```

说明：

- `uiVersion`：前端语义版本。
- `buildId`：构建批次，便于排查。
- `minDesktopVersion`：限制旧 Electron shell。
- `minServerApiVersion` / `maxServerApiVersion`：约束 UI 与当前后端 API 兼容性。

### 2. 更新 Manifest

桌面端不直接猜测最新版本，而是请求一个 Manifest。

建议格式：

```json
{
  "channel": "stable",
  "latest": {
    "uiVersion": "1.0.4",
    "buildId": "20260410.1",
    "url": "https://download.example.com/mateclaw/ui/1.0.4/ui-bundle.zip",
    "sha256": "..."
  },
  "minimumDesktopVersion": "1.0.0",
  "compatibleServerApi": "1.x",
  "signature": "base64..."
}
```

Manifest 最好放在稳定的静态地址，不要依赖 GitHub API 动态查询 release 列表。

发布源建议优先级：

1. 自有 CDN / OSS / COS / R2
2. GitHub Releases 直链

如果主要用户在国内，建议不要把 GitHub 当唯一源。

### 3. Spring Boot 静态资源加载改造

需要在 `mateclaw-server` 中新增静态资源优先级：

1. 外部目录 `file:${mateclaw.ui.dir}/`
2. 内置资源 `classpath:/static/`

实现建议：

- 新增配置项 `mateclaw.ui.dir`
- 在 `WebMvcConfigurer` 中注册资源处理器
- 对 `/assets/**`、`/icons/**`、`/logo/**`、`/favicon.ico`、`/index.html` 和 SPA 路由统一转发
- 当外部目录不存在时自动回退内置资源

这样 BrowserWindow 仍然访问 `http://localhost:{动态端口}`，但内容已经可由外置 UI 包覆盖。

### 4. Electron 侧 UI Update Manager

新增一个独立的 UI 更新管理器，职责：

1. 读取当前启用 UI 版本。
2. 拉取远程 Manifest。
3. 判定兼容性。
4. 下载 zip。
5. 校验 `sha256` 与签名。
6. 解压到临时目录。
7. 原子切换 `current.json` 或 `current` 软链接。
8. 通知渲染层“有可用 UI 更新”或“更新已完成”。

建议时机：

- 启动后 3 到 10 秒后台检查
- 用户手动点击“检查前端更新”
- 设置页允许切换更新通道（stable / beta）

### 5. 激活策略

建议采用“两阶段激活”：

#### 启动前已下载完成

- Electron 在启动 Java 前先解析当前 UI 指针
- 将 `MATECLAW_UI_DIR` 注入到 Java 进程环境变量
- 本次启动直接加载新 UI

#### 运行中下载完成

- 下载成功后先不杀后端
- 标记“下次重启生效”是最稳妥方案
- 若要做到即时生效，可尝试：
  - 切换 `current` 指针
  - 通知前端 `window.location.reload()`

第一阶段推荐：

**下载后提示“重启应用以应用前端更新”**

原因是：

- 简化缓存一致性问题
- 避免运行态资源引用一半新一半旧
- 降低与长连接、SSE、登录态的耦合风险

### 6. 回滚策略

至少支持三层回退：

1. 下载失败：保持当前 UI
2. 解压或校验失败：丢弃新包，保持当前 UI
3. 新 UI 启动异常：回退到上一版本 UI，最差回退到 JAR 内置 UI

建议机制：

- `current.json` 记录当前版本、上一版本、状态
- UI 启动成功后，通过 preload IPC 上报“本次版本已健康启动”；如果后续选择 REST 方案，可新增 `/api/v1/system/ui/boot-ok`（当前源码尚未提供该端点）
- 若启动后短时间内崩溃或白屏，下次启动自动回滚上一版本

### 7. 安全要求

UI 热更新本质上是在本地执行新的前端资源，必须做完整校验。

最低要求：

- HTTPS 下载
- `sha256` 校验
- Manifest 签名校验

推荐增加：

- 使用 Ed25519 公钥验签
- 公钥随桌面端内置
- 不允许跳过签名校验加载生产更新包

否则该通道会成为远程代码注入入口。

### 8. 缓存与资源路径

需要处理几个细节：

- `index.html` 不应长缓存
- `assets/*` 可使用内容 hash 长缓存
- 外部 UI 包目录最好按版本隔离
- `current` 只做版本指针，不直接覆盖旧目录

这和 Vite 的产物模式天然兼容。

### 9. 版本兼容规则

建议明确一条产品规则：

- 只涉及 UI 表现、交互、文案、前端容错的变更，可以走 UI OTA
- 需要新增/修改后端 API、数据库结构、JRE 资源、Electron 权限能力的变更，必须走桌面整包升级

否则很容易出现：

- UI 已升级
- 本地 JAR 太旧
- 页面调用了不存在的 API

所以 Manifest 中必须带兼容约束。

## 发布链路设计

### 当前链路

1. `mateclaw-ui` 构建到后端 `static/`
2. Maven 打 JAR
3. Electron 打包安装包
4. GitHub Releases 发布

### 新链路

#### 桌面整包发布

继续保持现状：

1. 构建 UI
2. 打进 JAR
3. 打包桌面安装包
4. 走 `electron-updater`

#### UI 独立发布

新增：

1. `mateclaw-ui` 单独构建到临时目录
2. 生成 `meta.json`
3. 打 zip
4. 计算 `sha256`
5. 生成并发布 `ui-manifest.json`
6. 上传到 CDN / Release 资产

这样：

- 新装用户依然有 JAR 内置 UI 可用
- 老用户可在后续自动收到 UI OTA

## 推荐实施阶段

### Phase 1：基础可用

目标：

- 支持下载 UI 包
- 支持启动时优先加载外部 UI
- 支持失败回退到内置 UI
- 下载完成后“下次重启生效”

需要改动：

- `mateclaw-server`
  - 支持外部静态目录优先级
  - 提供 SPA fallback
- `mateclaw-desktop`
  - 增加 UI Update Manager
  - 增加 Manifest 拉取、下载、校验、解压、指针切换
  - 将 UI 版本信息暴露给 Splash / 设置页
- `mateclaw-ui`
  - 构建时生成 `meta.json`
  - 设置页增加当前 UI 版本展示

这是最值得先落地的一版。

### Phase 2：产品化

目标：

- 设置页支持“检查前端更新”
- 提示更新说明
- 支持 stable / beta 通道
- 支持启动失败自动回滚

### Phase 3：增强体验

目标：

- 部分场景无需整应用重启即可刷新 UI
- 支持灰度发布
- 支持按平台分发不同 UI 包

## 建议新增模块

### `mateclaw-desktop`

建议新增：

- `electron/main/ui-updater.ts`
- `electron/main/ui-runtime.ts`

职责拆分：

- `ui-updater.ts`：远程检查、下载、校验、解压、切换
- `ui-runtime.ts`：读取当前 UI 指针、提供给 Java 进程环境变量

### `mateclaw-server`

建议新增：

- `vip.mate.config.ExternalUiProperties`
- `vip.mate.config.UiResourceConfig`
- `vip.mate.system.controller.DesktopRuntimeController`

职责：

- 配置外部 UI 目录
- 注册静态资源与 SPA fallback
- 对前端暴露当前运行版本信息

### `mateclaw-ui`

建议新增：

- 构建脚本：生成 `meta.json`
- 设置页：显示
  - Desktop 版本
  - UI 版本
  - 后端版本
  - 更新通道
  - 最近检查时间

## 接口建议

桌面 preload / IPC 可以新增：

- `uiUpdater.getState()`
- `uiUpdater.check()`
- `uiUpdater.download()`
- `uiUpdater.applyOnRestart()`

后端接口建议新增（当前源码尚未提供）：

- 建议新增：`GET /api/v1/runtime/version`（当前源码尚未提供）

返回示例：

```json
{
  "desktopVersion": "1.0.0",
  "serverVersion": "1.0.0",
  "serverApiVersion": "1.0",
  "uiVersion": "1.0.4",
  "uiSource": "external"
}
```

这样前端可以明确展示当前正在跑的是哪个 UI 包。

## 风险点

### 1. 前后端版本漂移

这是最大风险。

控制手段：

- UI Manifest 增加兼容性约束
- 约定 API 破坏性变更只能走整包升级

### 2. 白屏回滚不完善

如果只做下载和切换，不做启动成功确认，坏包可能导致用户持续白屏。

所以至少要有：

- 上一版本指针
- 启动健康上报

### 3. 更新源可达性

若继续完全依赖 GitHub Releases，国内网络环境下成功率可能不稳定。

建议尽快切到稳定 CDN。

### 4. 安全边界扩大

远程前端资源可执行，签名和 hash 校验是必须项，不是可选优化。

## 最小落地建议

如果现在就开始做，建议按下面顺序推进：

1. 先改 `mateclaw-server`，让它支持“外部目录覆盖 classpath static”。
2. 再改 `mateclaw-desktop`，把 UI 包下载到 `userData/ui-bundles/`，并通过环境变量传给 Java。
3. 再补 Manifest、签名校验和版本展示。
4. 最后再做“运行中更新提示”和“自动回滚”。

## 结论

对当前 MateClaw 架构，最合适的不是把桌面端改成远程站点壳，而是：

**保留 `Electron + localhost Spring Boot` 架构，引入“外置 UI Bundle 覆盖内置 static 资源”的 OTA 机制。**

这样可以：

- 保持离线可用
- 最大限度复用现有桌面端架构
- 将 UI 发布频率从桌面整包中解耦
- 把风险控制在“前端资源替换”这一层

第一阶段建议做到：

- 启动时自动检查 UI 更新
- 后台下载
- 校验后写入外部目录
- 下次重启生效
- 失败自动回退到 JAR 内置 UI

这版最稳，也最容易在现有代码上渐进落地。