---
url: /wave-agent/specs/commands/update-command.md
description: '`wave update` 检查并安装最新版：支持 npm/pnpm/yarn、npmmirror 镜像回退与 Windows 分离进程后台更新'
---

# 功能规格说明：更新命令

**创建日期**：2026-03-31

## 用户场景与测试 *（必填）*

### 用户故事：检查更新（优先级：P1）

作为用户，我希望能够检查 WAVE Code 是否有新版本可用，以便我可以保持最新的功能和错误修复。

**为什么是这个优先级**：这是功能的核心。它允许用户知道何时可用更新。

**独立测试**：可以通过运行 `wave update` 并验证它正确识别当前版本和 npm 注册表上的最新版本来测试。

**验收场景**：

1. **假设**当前版本是 `0.11.6`，npm 上的最新版本是 `0.11.6`，**当**用户运行 `wave update` 时，**则**系统通知用户 WAVE Code 已是最新。
2. **假设**当前版本是 `0.11.5`，npm 上的最新版本是 `0.11.6`，**当**用户运行 `wave update` 时，**则**系统通知用户有新版本可用。

***

### 用户故事：执行更新（优先级：P1）

作为用户，我希望工具使用适当的包管理器自动更新到最新版本，这样我就不必手动运行安装命令。

**为什么是这个优先级**：这为用户提供无缝的更新体验。

**独立测试**：可以在有更新可用时运行 `wave update` 并验证它执行正确的更新命令（如 `npm install -g wave-code@latest`）来测试。

**验收场景**：

1. **假设**有新版本可用且工具通过 `npm` 安装，**当**用户运行 `wave update` 时，**则**系统执行 `npm install -g wave-code@latest --registry=https://registry.npmmirror.com`。
2. **假设**有新版本可用且工具通过 `pnpm` 安装，**当**用户运行 `wave update` 时，**则**系统执行 `pnpm add -g wave-code@latest --registry=https://registry.npmmirror.com`。
3. **假设**有新版本可用且工具通过 `yarn` 安装，**当**用户运行 `wave update` 时，**则**系统执行 `yarn global add wave-code@latest --registry=https://registry.npmmirror.com`。

***

### 用户故事：走 npm 国内镜像加速（优先级：P2）

作为国内用户，我希望 `wave update` 的版本查询与安装都走 npm 国内镜像，以便更新不会因为直连 `registry.npmjs.org` 而缓慢或超时。

**为什么是这个优先级**：内置运行时依赖（rg / sharp）的下载以及文档里的安装说明都已统一走 npmmirror，`wave update` 是唯一仍直连官方源的路径。官方源在国内更新一个包可能需要数分钟甚至失败，而这是用户主动触发的、必须成功的操作。

**独立测试**：运行 `wave update`，验证版本查询发往镜像、安装命令带 `--registry=https://registry.npmmirror.com`；再模拟镜像不可达，验证版本查询回退到官方源。

**验收场景**：

1. **假设**用户运行 `wave update`，**当**系统查询最新版本时，**则**请求发往 `https://registry.npmmirror.com/wave-code/latest`。
2. **假设**镜像不可达（网络不可达、超时或响应无法解析），**当**系统查询最新版本时，**则**静默回退到官方源 `https://registry.npmjs.org/wave-code/latest`，且随后的安装也使用回退命中的那个源（只连得上官方源的机器，改用镜像安装会以同样原因失败）。
3. **假设**两个源都不可达，**当**系统查询最新版本时，**则**报错退出，且不执行任何安装命令。
4. **假设**用户在 Windows 上运行 `wave update` 且走后台执行，**当**分离子进程执行安装时，**则**命令同样附带镜像 registry 参数（与前台更新一致）。

***

### 用户故事：Windows 后台执行更新（优先级：P1）

作为 Windows 用户，我希望 `wave update` 不会因为当前进程占用全局 bin 文件而失败，以便更新可以顺利完成。

**为什么是这个优先级**：Windows 上 cmd.exe 执行 `wave.cmd` 时会保持文件句柄（不允许 rename/delete），若正在运行的 wave 进程直接同步执行 `npm install -g`，npm 覆盖 bin 文件（如 `%APPDATA%\npm\wave.cmd`）时会报 EPERM/EBUSY，导致更新失败。

**独立测试**：在 Windows 上从运行中的 wave 进程发起有更新的 `wave update`，验证当前进程先退出，随后独立的分离进程完成安装，bin 文件被成功覆盖。

**验收场景**：

1. **假设**用户在 Windows 上运行 `wave update` 且有新版本可用，**当**命令执行更新时，**则**系统提示更新将在后台完成，立即退出当前进程，并由一个分离（detached）子进程在短暂延迟后执行安装命令。
2. **假设**更新正在后台执行，**当**用户看到提示后重新打开 wave 时，**则**新版本已生效。

***

### 边界情况

* **网络不可用怎么办？** 系统应该优雅地处理错误并通知用户无法检查更新（镜像与官方源都不可达时才报错）。
* **更新命令失败（如权限问题）怎么办？** 系统应该通知用户失败原因并提供手动运行的命令（含镜像 registry 参数，与实际执行的命令一致；可能需要 `sudo`，Windows 上可能需要先关闭 wave 再运行）。
* **工具未全局安装怎么办？** 系统仍应尝试检测包管理器并执行更新，或在无法做到时提供说明。