迁移机制

每次启动 Claude Code 时，它可能会默默地修复过时的设置、重新映射已弃用的模型别名、在文件之间移动字段或重新显示 UI 对话框 - 所有这些都在您看到第一个提示之前进行。 这是 迁移系统：一组小型但精确设计的一次性函数，在内部运行 runMigrations() in main.tsx.

Claude Code 中的迁移是 不是数据库架构迁移。 没有迁移表，没有回滚，也没有运行器框架。 相反，每个迁移函数在设计上都是幂等的——它会检测自己的前置/后置条件，如果工作已经完成，则立即退出。 整个集合在每次启动时运行，并受到单个版本号的保护，一旦应用了所有迁移，该版本号就会短路整个块。

所有同步迁移都包含在定义于的单个函数中 main.tsx。 在指挥官期间被称为 preAction hook — 加载配置后，REPL 启动之前。

// main.tsx — line 323
// @[MODEL LAUNCH]: Consider any migrations you may need for model strings.
// See migrateSonnet1mToSonnet45.ts for an example.

// Bump this when adding a new sync migration so existing users re-run the set.
const CURRENT_MIGRATION_VERSION = 11;

function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings();
    migrateBypassPermissionsAcceptedToSettings();
    migrateEnableAllProjectMcpServersToSettings();
    resetProToOpusDefault();
    migrateSonnet1mToSonnet45();
    migrateLegacyOpusToCurrent();
    migrateSonnet45ToSonnet46();
    migrateOpusToOpus1m();
    migrateReplBridgeEnabledToRemoteControlAtStartup();
    if (feature('TRANSCRIPT_CLASSIFIER')) {
      resetAutoModeOptInForDefaultOffer();
    }
    if ("external" === 'ant') {   // internal Anthropic builds only
      migrateFennecToOpus();
    }
    // Stamp the version so we skip next time
    saveGlobalConfig(prev => prev.migrationVersion === CURRENT_MIGRATION_VERSION
      ? prev
      : { ...prev, migrationVersion: CURRENT_MIGRATION_VERSION });
  }

  // Async migration — fire-and-forget, non-blocking
  migrateChangelogFromConfig().catch(() => {});
}

这里有三个突出的设计决策：

1. 版本门： migrationVersion 存储在 ~/.claude.json。 一旦等于 CURRENT_MIGRATION_VERSION，整个同步块被跳过——避免 11 个冗余 saveGlobalConfig 每次启动时都会进行锁定+重新读取循环。
2. 版本碰撞规则： 该评论明确指出——每当添加新的同步迁移时都会改变常量，以便现有用户重新运行全套。
3. 异步分离： migrateChangelogFromConfig 是异步的并且涉及文件 I/O，因此它在同步块之后运行即发即弃。

目前有 11 个同步迁移函数和 1 个异步迁移函数。 这是每个文件的用途、幂等性机制以及它涉及的配置存储。

每次迁移都必须能够安全地多次调用。 代码库中出现了两种模式：

模式 A — GlobalConfig 中的完成标志

当迁移需要运行一次但“已完成”状态从数据中不是不言而喻时使用（例如 resetProToOpusDefault, migrateSonnet1mToSonnet45）。 布尔值或时间戳被写入 ~/.claude.json 并在函数顶部进行检查。

// migrateSonnet1mToSonnet45.ts — completion flag pattern
export function migrateSonnet1mToSonnet45(): void {
  const config = getGlobalConfig()
  if (config.sonnet1m45MigrationComplete) {
    return  // already done — exit immediately
  }

  const model = getSettingsForSource('userSettings')?.model
  if (model === 'sonnet[1m]') {
    updateSettingsForSource('userSettings', {
      model: 'sonnet-4-5-20250929[1m]',
    })
  }

  saveGlobalConfig(current => ({
    ...current,
    sonnet1m45MigrationComplete: true,
  }))
}

模式 B——自幂等（数据不言自明）

当迁移条件是对当前值的直接检查时使用 - 如果数据已经迁移，则检查简单地返回 false 并且不写入任何内容（例如所有模型别名迁移）。 读取和写入相同的设置源（userSettings) 是这种模式的关键 - 中的注释 migrateLegacyOpusToCurrent.ts explains: “读取和写入相同的源可以在没有完成标志的情况下保持幂等性，并且避免为仅将其固定在一个项目中的用户默默地将‘opus’提升为全局默认值。”

// migrateLegacyOpusToCurrent.ts — self-idempotent pattern
export function migrateLegacyOpusToCurrent(): void {
  if (getAPIProvider() !== 'firstParty') return
  if (!isLegacyModelRemapEnabled()) return

  const model = getSettingsForSource('userSettings')?.model
  if (
    model !== 'claude-opus-4-20250514' &&
    model !== 'claude-opus-4-1-20250805' &&
    model !== 'claude-opus-4-0' &&
    model !== 'claude-opus-4-1'
  ) {
    return  // data already clean — nothing to do
  }

  updateSettingsForSource('userSettings', { model: 'opus' })
  saveGlobalConfig(current => ({
    ...current,
    legacyOpusMigrationTimestamp: Date.now(),
  }))
  logEvent('tengu_legacy_opus_migration', { from_model: model })
}

Claude Code 具有多个按优先级顺序合并的设置源： userSettings → projectSettings → localSettings → policySettings。 迁移的范围被故意限制为仅接触 userSettings （并且偶尔 localSettings）。 几乎每个模型迁移文件中的注释都重复相同的理由：

此约束可以防止一类微妙的错误：如果迁移从 merged 设置，它可能会看到项目范围的设置并“有帮助地”将该值写入全局 userSettings，突然使每个项目的首选项成为所有地方的新默认值。

除了启动迁移功能之外， config.ts 包含一个较低级别的 migrateConfigFields() 每次配置文件运行时运行 从磁盘读取。 这处理最旧的架构更改——在当前版本化迁移系统存在之前。

// config.ts — runs on every config read
function migrateConfigFields(config: GlobalConfig): GlobalConfig {
  if (config.installMethod !== undefined) {
    return config  // already migrated
  }

  // autoUpdaterStatus is removed from the type but may exist in old configs
  const legacy = config as GlobalConfig & {
    autoUpdaterStatus?: 'migrated' | 'installed' | 'disabled' | 'enabled' | ...
  }

  switch (legacy.autoUpdaterStatus) {
    case 'migrated':  installMethod = 'local';   break
    case 'installed': installMethod = 'native';  break
    case 'disabled':  autoUpdates  = false;      break
    ...
  }

  return { ...config, installMethod, autoUpdates }
}

还有一个 removeProjectHistory() 剥离旧内联的函数 history 每次读取时项目配置中的字段 - 该字段已迁移到单独的 history.jsonl 文件，但旧的配置仍然包含该字段。

迁移是可观察到的。 大多数函数调用 logEvent() 记录 Anthropic 的遥测管道发生的情况。 这可以让团队知道何时仍在将迁移应用于野外用户以及何时可以安全地删除迁移代码。

尤其， migrateSonnet1mToSonnet45 and migrateReplBridgeEnabledToRemoteControlAtStartup 不发出分析事件——它们被认为是风险较低的内务处理。

源代码甚至包含一条注释，为未来的工程师指明了正确的方向：

现有代码库的配方：

1. Create src/migrations/myNewMigration.ts 具有单个导出函数。
2. 选择幂等策略：GlobalConfig 中的完成标志，或自幂等数据检查。
3. 只能读取和写入 userSettings (or localSettings 对于项目范围的数据）。 切勿读取合并的设置。
4. Call logEvent('tengu_my_migration_name', {...}) 与相关元数据。
5. 将主体包裹在 try/catch 中并调用 logError 需要注意的是——迁移绝不能抛出或破坏启动。
6. 将函数导入到 main.tsx 并将其添加到 if (migrationVersion !== CURRENT_MIGRATION_VERSION) block.
7. Bump CURRENT_MIGRATION_VERSION 因此现有用户重新运行更新后的设置。

// Template: src/migrations/myNewMigration.ts
import { logEvent } from '../services/analytics/index.js'
import { logError } from '../utils/log.js'
import {
  getSettingsForSource,
  updateSettingsForSource,
} from '../utils/settings/settings.js'

export function myNewMigration(): void {
  // self-idempotent guard: check if work is already done
  const model = getSettingsForSource('userSettings')?.model
  if (model !== 'old-alias') return

  try {
    updateSettingsForSource('userSettings', { model: 'new-alias' })
    logEvent('tengu_my_new_migration', {})
  } catch (error) {
    logError(new Error(`Failed to run myNewMigration: ${error}`))
  }
}