# 配置与迁移系统

Claude Code 使用 Zod 进行配置模式验证，并通过迁移系统处理配置版本升级。

## 目录结构

```
src/
├── schemas/           # Zod 配置模式定义
├── migrations/        # 配置迁移脚本
└── utils/settings/   # 设置管理系统
    ├── settings.ts    # 设置管理核心
    ├── validation.ts  # 验证逻辑
    ├── changeDetector.ts  # 变更检测
    ├── applySettingsChange.ts  # 变更应用
    ├── permissionValidation.ts  # 权限规则验证
    ├── toolValidationConfig.ts  # 工具验证配置
    ├── types.ts      # 类型定义
    ├── constants.ts  # 常量
    ├── mdm/          # 移动设备管理
    └── settingsCache.ts  # 设置缓存
```

## 1. 配置模式 (schemas/)

### 1.1 主模式文件
**文件**: `src/schemas/hooks.ts` (7884行)

使用 Zod 定义所有配置项的验证模式。

### 1.2 核心模式示例

```typescript
// 基础设置模式
const baseSettingsSchema = z.object({
  // 模型配置
  model: z.string(),
  maxTokens: z.number().optional(),

  // UI 设置
  theme: z.enum(['dark', 'light', 'system']),
  fontSize: z.number().min(8).max(24),

  // 权限设置
  allowPermissions: z.boolean(),
  permissionRules: z.array(permissionRuleSchema).optional(),
})

// MCP 服务器配置
const mcpServerSchema = z.object({
  name: z.string(),
  command: z.string(),
  args: z.array(z.string()).optional(),
  env: z.record(z.string()).optional(),
})
```

## 2. 设置管理 (utils/settings/)

### 2.1 设置核心 (settings.ts)

**文件**: `src/utils/settings/settings.ts` (~32KB)

**主要函数**:

| 函数 | 用途 |
|------|------|
| `getSettings()` | 获取当前设置 |
| `updateSettings(partial)` | 更新设置 |
| `resetSettings()` | 重置为默认值 |
| `loadManagedFileSettings()` | 加载托管配置文件 |
| `parseSettingsFile(path)` | 解析设置文件 |

**设置加载优先级** (从低到高):
1. 默认值
2. 托管设置文件 (`managed-settings.json`)
3. 托管设置 Drop-in 目录 (`managed-settings.d/*.json`)
4. 用户设置文件 (`~/.claude/settings.json`)

**托管设置系统**:
```typescript
// 加载托管文件设置
export function loadManagedFileSettings(): {
  settings: SettingsJson | null
  errors: ValidationError[]
} {
  // 1. 加载 managed-settings.json (基础)
  // 2. 按字母顺序加载 managed-settings.d/*.json (覆盖)
}
```

### 2.2 变更检测 (changeDetector.ts)

**文件**: `src/utils/settings/changeDetector.ts` (~16KB)

检测设置变更并触发相应的处理逻辑。

**主要功能**:
- 检测设置项的变化
- 生成变更事件
- 防止循环依赖

### 2.3 变更应用 (applySettingsChange.ts)

**文件**: `src/utils/settings/applySettingsChange.ts`

应用设置变更到运行时系统。

```typescript
// 示例：应用主题变更
async function applyThemeChange(theme: Theme): Promise<void> {
  // 1. 更新渲染器主题
  // 2. 通知所有订阅者
  // 3. 持久化到磁盘
}
```

### 2.4 验证 (validation.ts)

**文件**: `src/utils/settings/validation.ts` (~8KB)

**主要函数**:

| 函数 | 用途 |
|------|------|
| `validateSettings(settings)` | 验证完整设置 |
| `validateSetting(key, value)` | 验证单个设置 |
| `formatZodError(error)` | 格式化 Zod 错误 |
| `filterInvalidPermissionRules(rules)` | 过滤无效权限规则 |

**验证流程**:
```typescript
export function validateSettings(
  settings: unknown
): SettingsWithErrors {
  const result = SettingsSchema.safeParse(settings)

  if (result.success) {
    return { settings: result.data, errors: [] }
  }

  // 转换 Zod 错误为友好格式
  return {
    settings: null,
    errors: formatZodError(result.error)
  }
}
```

### 2.5 权限验证 (permissionValidation.ts)

**文件**: `src/utils/settings/permissionValidation.ts` (~8.5KB)

验证权限规则的有效性。

**权限规则结构**:
```typescript
interface PermissionRule {
  tool: string              // 工具名称
  path?: string             // 路径模式
  deny?: boolean            // 拒绝还是允许
  reason?: string           // 原因说明
}
```

**验证规则**:
1. 工具名称必须有效
2. 路径模式必须是有效的 glob 或正则
3. 冲突规则被拒绝

### 2.6 工具验证配置 (toolValidationConfig.ts)

**文件**: `src/utils/settings/toolValidationConfig.ts`

配置哪些工具需要验证或可以直接执行。

```typescript
// 免验证工具
const bypassValidationTools = [
  'Read',
  'BackgroundRead',
  'TodoWrite',
  'NotebookEdit',
]

// 需要路径验证的工具
const pathValidationTools = [
  'Bash',
  'Write',
  'Edit',
  'Read',
]
```

### 2.7 MDM 配置 (mdm/)

**目录**: `src/utils/settings/mdm/`

支持移动设备管理 (Mobile Device Management) 配置。

```
mdm/
└── settings.ts    # MDM 设置加载
```

### 2.8 类型定义 (types.ts)

**文件**: `src/utils/settings/types.ts` (~43KB)

定义所有设置相关的类型。

```typescript
// 设置 JSON 结构
type SettingsJson = {
  // 基本设置
  model?: string
  theme?: 'dark' | 'light' | 'system'

  // MCP
  mcpServers?: Record<string, McpServerConfig>

  // 权限
  permissionRules?: PermissionRule[]

  // 实验性功能
  experimental?: Record<string, boolean>
}

// 设置来源
type SettingSource =
  | 'default'
  | 'managed'
  | 'user'

// 可编辑的设置源
type EditableSettingSource = 'user'
```

## 3. 迁移系统 (migrations/)

### 3.1 迁移文件列表

| 文件 | 用途 |
|------|------|
| `migrateAutoUpdatesToSettings.ts` | 自动更新迁移 |
| `migrateBypassPermissionsAcceptedToSettings.ts` | 绕过权限迁移 |
| `migrateEnableAllProjectMcpServersToSettings.ts` | MCP 服务器迁移 |
| `migrateFennecToOpus.ts` | Fennec → Opus 模型迁移 |
| `migrateLegacyOpusToCurrent.ts` | Legacy Opus 迁移 |
| `migrateOpusToOpus1m.ts` | Opus → Opus 1M 迁移 |
| `migrateReplBridgeEnabledToRemoteControlAtStartup.ts` | REPL 桥接迁移 |
| `migrateSonnet1mToSonnet45.ts` | Sonnet 1M → 4.5 迁移 |
| `migrateSonnet45ToSonnet46.ts` | Sonnet 4.5 → 4.6 迁移 |
| `resetAutoModeOptInForDefaultOffer.ts` | 自动模式重置 |
| `resetProToOpusDefault.ts` | Pro → Opus 默认重置 |

### 3.2 迁移示例

**migrateOpusToOpus1m.ts**:
```typescript
export function migrateOpusToOpus1m(
  oldSettings: LegacySettings
): NewSettings {
  return {
    ...oldSettings,
    model: oldSettings.model === 'opus' ? 'opus-3-5-20241120' : oldSettings.model,
  }
}
```

### 3.3 迁移执行时机

迁移在以下时机执行:
1. 应用启动时
2. 设置加载前
3. 版本检测后

## 4. 常量 (constants.ts)

**文件**: `src/utils/settings/constants.ts` (~5.5KB)

```typescript
// 设置源优先级
const SETTING_SOURCE_PRIORITY: Record<SettingSource, number> = {
  default: 0,
  managed: 50,
  user: 100,
}

// 设置路径
const SETTINGS_DIR = 'settings'
const SETTINGS_FILE = 'settings.json'
const MANAGED_SETTINGS_FILE = 'managed-settings.json'
const MANAGED_SETTINGS_DROPIN_DIR = 'managed-settings.d'

// 默认值
const DEFAULT_MODEL = 'claude-opus-4-5'
const DEFAULT_THEME = 'dark'
const DEFAULT_MAX_TOKENS = 8192
```

## 5. 缓存管理 (settingsCache.ts)

**文件**: `src/utils/settings/settingsCache.ts` (~2.4KB)

```typescript
// 缓存接口
interface SettingsCache {
  get(key: string): SettingsJson | null
  set(key: string, value: SettingsJson): void
  invalidate(key: string): void
  clear(): void
}

// 缓存策略
const CACHE_TTL = 5 * 60 * 1000  // 5 分钟
const MAX_CACHE_SIZE = 10
```

## 6. 托管设置系统详解

### 6.1 Drop-in 机制

托管设置支持 Drop-in 目录机制，允许多个配置文件按优先级合并:

```
~/.claude/settings.json           # 用户设置
/etc/claude/managed-settings.json  # 系统托管基础
/etc/claude/managed-settings.d/
  ├── 10-base.json               # 优先级 10
  ├── 20-security.json           # 优先级 20
  └── 30-otel.json               # 优先级 30
```

### 6.2 合并规则

1. 基础文件先加载
2. Drop-in 文件按文件名排序后加载
3. 后加载的文件优先级更高
4. 数组字段替换，非数组字段合并

## 7. 配置验证规则

### 7.1 路径验证

```typescript
function validatePath(path: string): boolean {
  // 禁止危险路径
  if (path.includes('..')) return false
  if (path.startsWith('/etc/')) return false
  if (path.startsWith('/sys/')) return false

  // 检查权限
  if (!canAccessPath(path)) return false

  return true
}
```

### 7.2 命令验证

```typescript
function validateCommand(command: string): boolean {
  // 白名单检查
  const allowedCommands = ['read', 'edit', 'bash']
  return allowedCommands.includes(command)
}
```

### 7.3 模型名称验证

```typescript
const VALID_MODELS = [
  'claude-opus-4-5',
  'claude-sonnet-4-6',
  'claude-opus-3-5-20241120',
  // ...
]

function validateModel(model: string): boolean {
  return VALID_MODELS.includes(model)
}
```

## 8. 内部写入标识 (internalWrites.ts)

**文件**: `src/utils/settings/internalWrites.ts`

标识由系统内部触发的设置写入，防止来自用户配置文件的覆盖。

```typescript
// 标记内部写入
export function markInternalWrite(key: string): void {
  internalWrites.add(key)
}

// 检查是否为内部写入
export function isInternalWrite(key: string): boolean {
  return internalWrites.has(key)
}
```