From e32c159f35e1cbf8508f673e26ca34dfee5deb97 Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Fri, 3 Apr 2026 09:39:32 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=85=B3=E9=97=AD=E8=87=AA=E5=8A=A8?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/auto-updater.md | 312 +++++++++++++++++++++++++++++++++++++++++++ src/utils/config.ts | 4 + 2 files changed, 316 insertions(+) create mode 100644 docs/auto-updater.md diff --git a/docs/auto-updater.md b/docs/auto-updater.md new file mode 100644 index 0000000..1567794 --- /dev/null +++ b/docs/auto-updater.md @@ -0,0 +1,312 @@ +# 自动更新机制 + +## 概述 + +Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。 + +--- + +## 安装类型与更新策略 + +更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测： + +| 安装类型 | 更新策略 | 自动安装？ | +|---|---|---| +| `native` | 从 GCS/Artifactory 下载二进制文件，通过符号链接激活 | 是（静默） | +| `npm-global` | `npm install -g` / `bun install -g` | 是（静默） | +| `npm-local` | `npm install` 到 `~/.claude/local/` | 是（静默） | +| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） | +| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 | + +### 策略路由 + +`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件： + +- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接） +- `package-manager` → `PackageManagerAutoUpdater`（仅通知） +- 其他 → `AutoUpdater`（基于 JS/npm） + +--- + +## 后台自动更新循环 + +三个更新组件共享相同的轮询模式： + +```typescript +useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟 +``` + +组件挂载时（即启动时）也会执行一次检查。 + +### 前置检查门控 + +任何更新尝试之前，系统会依次检查： + +1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`） + - `NODE_ENV === 'development'` + - 设置了 `DISABLE_AUTOUPDATER` 环境变量 + - 仅限必要流量模式 + - `config.autoUpdates === false`（native 安装的保护模式除外） +2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本 +3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级 + +### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`） + +1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()` +2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory） +3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测） +4. 将版本化二进制文件存储到 XDG 目录 +5. 更新符号链接（`~/.local/bin/claude` → 新版本二进制文件） +6. 保留最近 2 个版本，清理旧版本 +7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络） + +### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`） + +1. 调用 `getLatestVersion()` 获取当前 npm dist-tag +2. 通过 semver `gte()` 比较版本 +3. 根据安装类型路由到本地或全局安装 +4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新 + +### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`） + +每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令： + +- macOS: `brew upgrade claude-code` +- Windows: `winget upgrade Anthropic.ClaudeCode` +- Alpine: `apk upgrade claude-code` + +--- + +## 启动版本门控 + +`src/utils/autoUpdater.ts:70` — `assertMinVersion()` + +从 `src/main.tsx:1775` 在启动时调用： + +```typescript +void assertMinVersion(); +``` + +1. 从 GrowthBook 动态配置获取 `tengu_version_config` +2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新 +3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动 + +--- + +## 手动 CLI 命令 + +### `claude update` / `claude upgrade` + +**文件**: `src/cli/update.ts` + +完整流程： +1. 运行 `getDoctorDiagnostic()` 检查系统健康状态 +2. 检查是否存在多个安装及配置不一致 +3. 根据安装类型路由： + - `development` → 报错（"开发版本不支持自动更新"） + - `package-manager` → 打印对应操作系统的更新命令 + - `native` → 使用原生安装器的 `updateLatest()` + - `npm-local` → 在 `~/.claude/local/` 执行 `npm install` + - `npm-global` → 执行 `npm install -g`（含权限检查） +4. 报告当前版本、最新版本、成功/失败状态 + +### `claude rollback [target]`（仅限内部） + +回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。 + +### `claude install [target]` + +安装或重新安装原生构建版本。接受可选的版本目标参数。 + +### `claude doctor` + +检查自动更新器的健康状态，报告状态、权限和配置信息。 + +--- + +## 原生安装器架构 + +**文件**: `src/utils/nativeInstaller/installer.ts` + +### 二进制文件存储布局 + +``` +~/.local/share/claude-code/ +├── versions/ # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...) +├── staging/ # 临时下载暂存区 +└── locks/ # 基于 PID 和 mtime 的锁文件 + +~/.local/bin/claude # 指向当前版本二进制文件的符号链接 +``` + +Windows 系统使用文件复制而非符号链接。 + +### 核心操作 + +| 函数 | 说明 | +|---|---| +| `updateLatest()` | 核心更新流程：最大版本上限 → 跳过检查 → 加锁 → 下载 → 安装 → 更新符号链接 | +| `installLatest()` | Singleflight 包装版本，防止重复的进行中安装 | +| `cleanupOldVersions()` | 保留最近 2 个版本，清理过期的暂存区和临时文件 | +| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 | +| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 | + +### 下载与校验 + +**文件**: `src/utils/nativeInstaller/download.ts` + +1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户） +2. 下载二进制文件并跟踪进度 +3. SHA256 校验和验证 +4. 60 秒卡顿检测（中止停滞的下载） +5. 失败时自动重试 3 次 + +--- + +## 文件锁机制 + +**文件**: `src/utils/autoUpdater.ts:176-268` + +防止并发更新进程破坏安装： + +- 锁文件：`~/.claude/update.lock`（或等效路径） +- 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取 +- 进程将其 PID 写入锁文件 +- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用 + +--- + +## 配置 + +### 设置项 + +**文件**: `src/utils/settings/types.ts` + +| 设置项 | 类型 | 说明 | +|---|---|---| +| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 | +| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 | + +### 全局配置 + +**文件**: `src/utils/config.ts:191-193` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） | +| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 | + +### 配置迁移 + +**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts` + +一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。 + +--- + +## 更新通知去重 + +**文件**: `src/hooks/useUpdateNotification.ts` + +React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。 + +--- + +## 更新日志 + +**文件**: `src/utils/releaseNotes.ts` + +1. 从 `src/setup.ts:387` 在每次启动时调用 +2. 从 GitHub 获取 changelog +3. 缓存到 `~/.claude/cache/changelog.md` +4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志 +5. 使用 semver 比较确定需要展示哪些日志 + +--- + +## 版本比较 + +**文件**: `src/utils/semver.ts` + +- 提供 `gt()`、`gte()`、`lt()`、`lte()`、`satisfies()`、`order()` +- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍） +- 在 Node.js 环境下回退到 npm `semver` 包 + +--- + +## 分析事件 + +所有更新相关的遥测数据使用 `tengu_` 前缀的事件： + +| 类别 | 事件 | +|---|---| +| 版本检查 | `tengu_version_check_success`、`tengu_version_check_failure` | +| JS 自动更新器 | `tengu_auto_updater_start/success/fail/up_to_date/lock_contention` | +| 原生自动更新器 | `tengu_native_auto_updater_start/success/fail` | +| 原生更新 | `tengu_native_update_complete/skipped_max_version/skipped_minimum_version` | +| 锁机制 | `tengu_version_lock_acquired/failed`、`tengu_native_update_lock_failed` | +| 二进制下载 | `tengu_binary_download_attempt/success/failure`、`tengu_binary_manifest_fetch_failure` | +| 清理 | `tengu_native_version_cleanup`、`tengu_native_staging_cleanup`、`tengu_native_stale_locks_cleanup` | +| 安装 | `tengu_native_install_package_success/failure`、`tengu_native_install_binary_success/failure` | +| 手动更新 | `tengu_update_check` | +| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` | + +--- + +## 关键文件索引 + +| 文件 | 职责 | +|---|---| +| `src/utils/autoUpdater.ts` | 核心逻辑：版本检查、npm 安装、文件锁、最低/最高版本门控 | +| `src/cli/update.ts` | `claude update` 命令处理 | +| `src/utils/nativeInstaller/installer.ts` | 原生二进制安装器：下载、版本管理、符号链接、清理 | +| `src/utils/nativeInstaller/download.ts` | 从 GCS/Artifactory 下载二进制文件并校验 | +| `src/utils/localInstaller.ts` | 本地安装器（`~/.claude/local/`）基于 npm | +| `src/components/AutoUpdaterWrapper.tsx` | 基于安装类型的策略路由 | +| `src/components/AutoUpdater.tsx` | JS/npm 后台自动更新器（30 分钟间隔） | +| `src/components/NativeAutoUpdater.tsx` | 原生二进制后台自动更新器（30 分钟间隔） | +| `src/components/PackageManagerAutoUpdater.tsx` | 包管理器通知（30 分钟，仅展示） | +| `src/hooks/useUpdateNotification.ts` | 按 semver 去重更新通知 | +| `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 | +| `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） | +| `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 | +| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 | +| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 | +| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 | + +--- + +## 流程图 + +``` +启动阶段 + ├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动 + ├── migrateAutoUpdatesToSettings() → 一次性配置迁移 + └── checkForReleaseNotes() → 展示新版本的更新日志 + +REPL 运行中（每 30 分钟） + ├── AutoUpdaterWrapper 检测安装类型 + │ + ├── native → NativeAutoUpdater + │ ├── 从 GCS/Artifactory 获取版本 + │ ├── 检查最大版本上限（服务端控制） + │ ├── 检查 minimumVersion 设置（跳过） + │ ├── acquireLock() + │ ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试） + │ ├── 安装到 versions/ 目录 + │ ├── 更新符号链接 + │ └── cleanupOldVersions()（保留 2 个版本） + │ + ├── npm-global/local → AutoUpdater + │ ├── 从 npm registry 获取最新版本 + │ ├── semver 版本比较 + │ ├── acquireLock() + │ └── npm install -g / 本地安装 + │ + └── package-manager → PackageManagerAutoUpdater + ├── 从 GCS 获取版本 + └── 显示 "Run: brew upgrade ..."（不自动安装） + +手动操作 + └── claude update → 完整诊断 + 安装编排 +``` diff --git a/src/utils/config.ts b/src/utils/config.ts index eecbf0c..ea2d3cb 100644 --- a/src/utils/config.ts +++ b/src/utils/config.ts @@ -1736,6 +1736,10 @@ export function getAutoUpdaterDisabledReason(): AutoUpdaterDisabledReason | null if (process.env.NODE_ENV === 'development') { return { type: 'development' } } + // 本项目默认关闭自动更新；通过 ENABLE_AUTOUPDATER=1 显式开启 + if (!isEnvTruthy(process.env.ENABLE_AUTOUPDATER)) { + return { type: 'config' } + } if (isEnvTruthy(process.env.DISABLE_AUTOUPDATER)) { return { type: 'env', envVar: 'DISABLE_AUTOUPDATER' } }