Migrations

Migrations 模块包含 11 个迁移脚本，管理 Claude Code 跨版本升级时的配置兼容性。迁移场景包括：模型别名演进（Fennec→Opus、Sonnet 4.5→4.6 等模型代际切换）、设置项迁移（autoUpdates、bypassPermissions 等从旧格式迁移到新 settings 系统）、用户偏好重置（Pro 用户默认模型切换、autoMode 重新确认）。每个迁移脚本是幂等的、条件触发的，并通过 analytics 记录迁移事件。

职责与设计理念

职责说明

配置迁移引擎，管理模型别名、设置项和用户偏好的版本演进

设计理念

迁移即演进——每个迁移脚本是一次"时间旅行"，将旧世界的状态安全地带到新世界。幂等性是迁移的第一法则，条件触发避免误伤。

架构决策

为什么迁移脚本必须是幂等的？

所有迁移脚本可安全重复执行

用户可能在迁移过程中中断（如 ctrl+c），下次启动时迁移会重新执行。幂等性保证重复执行不会产生副作用（如重复写入配置）。每个迁移先检查前置条件，不满足则直接返回。

文件清单

文件名	用途
migrateSonnet45ToSonnet46.ts	模型迁移：Sonnet 4.5 → 4.6 别名切换
migrateFennecToOpus.ts	模型迁移：Fennec 代号 → Opus 正式名
migrateAutoUpdatesToSettings.ts	设置迁移：自动更新配置迁移到新 settings 系统
migrateBypassPermissionsAcceptedToSettings.ts	设置迁移：权限绕过配置迁移
migrateReplBridgeEnabledToRemoteControlAtStartup.ts	设置迁移：REPL 桥接配置重命名
resetAutoModeOptInForDefaultOffer.ts	偏好重置：自动模式确认状态重置

使用场景

Claude Code 版本升级后首次启动

自动执行所有待运行的迁移脚本，静默完成配置兼容性调整

Anthropic 发布新模型

迁移脚本将用户的旧模型别名自动切换到新模型，无需手动操作

依赖关系

Bootstrap — 全局状态容器与会话生命周期管理，维护运行时的单一真相源

关键代码片段

条件触发的模型迁移

export function migrateSonnet45ToSonnet46(): void {
  // 三重守卫：API 提供商 + 订阅类型 + 当前模型
  if (getAPIProvider() !== 'firstParty') return
  if (!isProSubscriber() && !isMaxSubscriber()) return

  const model = getSettingsForSource('userSettings')?.model
  if (model !== 'claude-sonnet-4-5-20250929') return

  // 幂等迁移：显式版本号 → 别名
  updateSettingsForSource('userSettings', { model: 'sonnet' })

  if (config.numStartups > 1) {
    saveGlobalConfig(c => ({
      ...c, sonnet45To46MigrationTimestamp: Date.now()
    }))
  }
  logEvent('tengu_sonnet45_to_46_migration', { from_model: model })
}

三重守卫（API 提供商 + 订阅类型 + 当前模型）确保迁移精准触发

技术笔记

edge-case

新用户跳过通知

numStartups > 1 检查区分新用户和老用户。新用户（首次启动）不需要看到"模型已迁移"的通知，因为他们没有旧模型的心智模型。