# 功能规格说明: AgentSwitch Agent 工具适配器系统

**功能分支**: `002-agent-adapter`
**创建日期**: 2026-02-28
**状态**: 草稿
**输入**: 用户描述: "AgentSwitch Agent 工具适配器系统：实现 Claude Code/Codex/Gemini CLI 的配置集成与切换功能"

**⚠️ 重要提示**: 根据 AgentSwitch 项目宪章，本文档必须使用中文编写。

## Clarifications

### Session 2026-02-28

- Q: 当工具已安装但配置文件不存在时，系统应该采取什么行为？ → A: 创建默认配置文件并应用模型配置
- Q: 当多个进程同时尝试修改同一个工具的配置文件时，系统应该采用什么文件锁机制？ → A: 使用文件锁（flock）进行互斥
- Q: 系统应该保留多少个备份文件？ → A: 每个工具最多保留 10 个备份
- Q: 当某个工具不支持完整的 OpenAI API 参数（如不支持 custom_headers）时，系统应该如何处理这些不兼容的字段？ → A: 忽略不兼容字段并警告用户
- Q: 当工具的配置文件是符号链接时，系统应该如何处理？ → A: 跟随符号链接并修改实际文件
- Q: 当配置文件只有只读权限时，系统应该如何处理？ → A: 报错并提供修复命令
- Q: 当磁盘空间不足以创建备份时，系统应该如何处理？ → A: 报错并提示清理磁盘空间
- Q: 当备份文件或原配置文件损坏（无法解析）时，系统应该如何处理？ → A: 报错并提示手动恢复或重建
- Q: 当工具使用环境变量覆盖配置文件设置时，系统应该如何检测和提示？ → A: 修改配置文件并提示环境变量可能覆盖设置
- Q: 当同一工具有多个版本且配置格式不同时，适配器应该如何识别和处理？ → A: 适配器自动检测版本并使用对应的解析策略

## 用户场景与测试

### 用户故事 1 - 自动检测已安装的 Code Agent 工具 (优先级: P1) 🎯 MVP

作为开发者，我希望系统能够自动检测我机器上已安装的 Code Agent 工具（如 Claude Code、Codex、Gemini CLI），以便我能够快速了解哪些工具可以立即使用 AgentSwitch 进行配置管理，而无需手动查找和输入工具路径。

**为什么是此优先级**: 这是适配器系统的基础功能。没有自动检测，用户需要手动提供每个工具的配置路径，这将大大增加使用复杂度。自动检测是提供"开箱即用"体验的关键前提。

**独立测试**: 可以通过执行检测命令（如 `asw agent detect`）来测试自动发现功能，验证系统能够正确识别已安装的工具、未安装的工具，并为每个工具提供清晰的安装状态和配置路径信息。

**验收场景**:

1. **给定** 系统上已安装 Claude Code，**当** 执行 `asw agent detect` 命令，**则** 在检测结果中显示 "Claude Code: ✓ 已安装" 并提供其配置文件路径（如 `~/.claude/config.json`）
2. **给定** 系统上未安装 Codex，**当** 执行检测命令，**则** 显示 "Codex: ✗ 未安装" 并提供安装建议
3. **给定** 系统上同时安装了多个工具，**当** 执行检测命令，**则** 列出所有支持的工具及其安装状态，每个工具占一行，包含工具名称、状态图标、配置路径（如果已安装）
4. **给定** 配置文件路径非标准或被自定义，**当** 执行检测命令，**则** 能够通过环境变量或常见安装位置搜索找到配置文件，或提示用户手动指定路径
5. **给定** 工具可执行文件存在但配置文件缺失，**当** 执行检测命令，**则** 显示 "工具已安装但配置文件不存在，将在首次切换时创建"

---

### 用户故事 2 - 配置文件自动备份与恢复 (优先级: P1) 🎯 MVP

作为开发者，我希望在修改任何 Code Agent 工具的配置文件之前，系统能够自动创建备份，以便在配置出错或不满意时可以快速恢复到原始状态，避免手动备份的繁琐和遗忘风险。

**为什么是此优先级**: 这是配置切换功能的安全保障。没有自动备份，任何配置修改都可能破坏用户的现有配置，导致不可逆的损失。自动备份消除了用户尝试不同模型配置的后顾之忧。

**独立测试**: 可以通过完整的切换流程测试：执行切换命令触发自动备份 → 验证备份文件创建 → 修改配置 → 执行恢复命令 → 验证配置恢复到原始状态。

**验收场景**:

1. **给定** Claude Code 有现有配置文件，**当** 执行 `asw switch claude-code glm` 命令，**则** 在修改配置前自动创建备份文件（如 `~/.agentswitch/backups/claude-code-20260228-143022.config.json.bak`）并显示 "已备份原配置到 [备份路径]"
2. **给定** 备份文件已存在，**当** 再次执行切换命令，**则** 创建新的备份文件而不覆盖旧备份（使用时间戳区分），保留多次备份历史
3. **给定** 配置切换后出现问题，**当** 执行 `asw backup restore claude-code --backup 20260228-143022` 命令，**则** 将指定备份的配置内容恢复到工具的配置文件中，并显示 "配置已恢复到 2026-02-28 14:30:22 的版本"
4. **给定** 执行 `asw backup list` 命令，**当** 查询备份历史，**则** 显示所有工具的备份列表，每个备份包含工具名称、备份时间、备份文件路径
5. **给定** 备份文件损坏或丢失，**当** 尝试恢复备份，**则** 输出红色错误信息 "无法读取备份文件，文件可能已损坏或被删除" 并以非零退出码退出
6. **给定** 执行 `asw backup clean --older-than 7d` 命令，**当** 清理旧备份，**则** 删除 7 天前的所有备份文件并显示 "已清理 N 个旧备份文件"
7. **给定** 某个工具已有 10 个备份文件，**当** 再次执行切换命令创建新备份，**则** 自动删除最旧的备份文件以保持总数不超过 10 个，并显示 "已删除最旧备份，当前保留 10 个备份"

---

### 用户故事 3 - 模型配置一键切换 (优先级: P1) 🎯 MVP

作为开发者，我希望通过一个简单的命令就能将指定的 Code Agent 工具切换到不同的模型提供商，以便快速在不同模型（如 GLM-4、MiniMax、DeepSeek）间切换，而无需手动编辑每个工具的配置文件。

**为什么是此优先级**: 这是 AgentSwitch 的核心价值主张。一键切换是用户最常使用的功能，它将繁琐的手动配置编辑过程简化为单一命令，极大提升开发效率。

**独立测试**: 可以通过完整的切换场景测试：添加多个模型配置 → 执行切换命令 → 验证工具配置文件已更新 → 验证工具使用新模型配置 → 执行另一切换 → 验证再次切换成功。

**验收场景**:

1. **给定** 已添加名为 "glm" 的模型配置，**当** 执行 `asw switch claude-code glm` 命令，**则** 修改 Claude Code 的配置文件以使用 glm 模型的 API 配置（base_url、api_key、model_id），并显示绿色成功信息 "✓ Claude Code 已切换到 glm 模型"
2. **给定** 执行切换命令，**当** 配置文件修改成功，**则** 更新 `~/.agentswitch/config.toml` 中的 `active_models` 映射，记录 "claude-code = glm"
3. **给定** 模型配置不存在，**当** 执行 `asw switch codex unknown-model` 命令，**则** 输出红色错误信息 "✗ 错误: 模型配置 'unknown-model' 不存在" 并提示使用 `asw model list` 查看可用模型
4. **给定** Agent 工具未安装，**当** 执行切换命令，**则** 输出红色错误信息 "✗ 错误: 未检测到 Claude Code 安装" 并提供安装建议
5. **给定** Agent 工具已安装但配置文件不存在，**当** 执行切换命令，**则** 系统使用工具的默认配置模板创建配置文件并应用模型配置，显示 "已创建配置文件并应用 glm 模型"
6. **给定** 切换命令成功执行，**当** 查看工具配置文件内容，**则** 确认配置文件中的 API 端点、密钥、模型 ID 与指定的模型配置一致
7. **给定** 配置文件包含其他自定义设置（如温度、最大令牌数），**当** 执行切换命令，**则** 仅替换 API 相关配置（base_url、api_key、model_id），保留其他自定义设置不变
8. **给定** 模型配置包含工具不支持的字段（如 custom_headers），**当** 执行切换命令，**则** 忽略不兼容字段完成切换，并在成功信息后显示黄色警告 "⚠ 警告: 以下字段未被应用: custom_headers"

---

### 用户故事 4 - 查看当前配置状态 (优先级: P2)

作为开发者，我希望能够快速查看所有 Code Agent 工具当前正在使用的模型配置，以便了解整个开发环境的模型使用情况，而不需要逐个检查每个工具的配置文件。

**为什么是此优先级**: 这是可视化和透明度功能。虽然不是核心切换流程的必要部分，但它提供了全局视图，帮助用户管理和理解当前的配置状态，是多工具环境下的重要辅助功能。

**独立测试**: 可以通过执行状态命令来测试：配置多个工具的不同模型 → 执行状态命令 → 验证输出清晰显示每个工具的当前模型、配置路径、最后切换时间。

**验收场景**:

1. **给定** 多个工具已配置不同的模型，**当** 执行 `asw status` 命令，**则** 以表格形式显示所有工具的当前配置状态，包含工具名称、当前使用的模型、配置文件路径、最后切换时间
2. **给定** 某个工具尚未执行过切换，**当** 查看状态，**则** 显示 "未配置" 或 "使用默认配置"
3. **给定** 工具已切换模型，**当** 查看状态，**则** 显示模型名称、API 基础 URL（掩码处理 API Key）、模型 ID
4. **给定** 没有任何工具配置，**当** 执行 `asw status` 命令，**则** 输出黄色提示信息 "暂无任何工具配置，使用 'asw switch <agent> <model>' 开始配置"

---

### 用户故事 5 - Agent 工具适配器扩展 (优先级: P3)

作为开发者或贡献者，我希望能够轻松添加对新 Code Agent 工具的支持，以便社区能够扩展 AgentSwitch 的功能，覆盖更多新兴的代码助手工具。

**为什么是此优先级**: 这是可扩展性功能。虽然前三个适配器（Claude Code、Codex、Gemini CLI）覆盖了主流工具，但可扩展性设计确保了项目的长期发展和社区参与。

**独立测试**: 可以通过实现一个新的适配器来测试：创建适配器结构体 → 实现 AgentAdapter trait → 注册到系统中 → 执行检测和切换命令 → 验证新工具被正确识别和配置。

**验收场景**:

1. **给定** 定义新的适配器结构体，**当** 实现 AgentAdapter trait 的所有必需方法（detect、backup、apply、restore、current_model），**则** 适配器能够被系统自动识别并用于对应的工具
2. **给定** 新适配器已实现，**当** 执行 `asw agent detect` 命令，**则** 新工具出现在检测结果中
3. **给定** 新适配器已实现，**当** 执行 `asw switch <new-tool> <model>` 命令，**则** 能够成功切换该工具的模型配置
4. **给定** 适配器配置文件路径查找失败，**当** 实现 detect 方法，**则** 返回清晰的错误信息，提示用户如何手动指定路径

---

### 边界情况

- **配置文件格式差异**: 当不同工具使用不同的配置文件格式（JSON、TOML、YAML）时，系统如何正确解析和修改？
- **配置文件不存在**: ✅ 已澄清 - 当工具已安装但配置文件尚未创建时，系统使用工具的默认配置模板创建新配置文件并应用模型配置
- **配置文件权限问题**: ✅ 已澄清 - 当配置文件只有只读权限时，系统输出红色错误信息并提供修复命令（如 `chmod 644 <文件路径>`），帮助用户解决权限问题
- **并发切换**: ✅ 已澄清 - 当多个进程同时尝试修改同一个工具的配置时，系统使用文件锁（flock）进行互斥以避免冲突
- **备份空间不足**: ✅ 已澄清 - 当磁盘空间不足以创建备份时，系统输出红色错误信息并提示用户清理磁盘空间或使用 `asw backup clean` 命令清理旧备份，优先保证数据安全
- **部分字段支持**: ✅ 已澄清 - 当某个工具不支持完整的 OpenAI API 参数（如不支持 custom_headers）时，系统忽略不兼容字段并警告用户哪些字段未被应用
- **配置文件损坏**: ✅ 已澄清 - 当备份文件或原配置文件损坏（无法解析）时，系统输出红色错误信息并提示用户手动恢复或重建配置，避免自动恢复可能导致的数据二次损坏
- **环境变量覆盖**: ✅ 已澄清 - 当工具使用环境变量覆盖配置文件设置时，系统仍修改配置文件但在切换完成后显示黄色警告，提示环境变量可能覆盖配置文件设置，建议用户检查相关环境变量（如 OPENAI_API_KEY、API_BASE_URL）
- **符号链接配置**: ✅ 已澄清 - 当配置文件是符号链接时，系统跟随符号链接并修改实际文件，保持与工具行为一致
- **工具版本差异**: 当同一工具有多个版本且配置格式不同时，适配器如何识别并处理？

## 需求

### 功能性需求

#### Agent 工具检测 (FR-001 至 FR-005)

- **FR-001**: 系统 MUST 支持检测以下 Code Agent 工具的安装状态：Claude Code、Codex、Gemini CLI
- **FR-002**: 系统 MUST 在检测时查找工具的配置文件路径（`~/.claude/config.json`、`~/.codex/config.toml`、`~/.gemini-cli/config.yaml` 或其他常见路径）
- **FR-003**: 系统 MUST 通过检查可执行文件是否存在（在 PATH 中或常见安装位置）来判断工具是否已安装
- **FR-004**: 系统 MUST 提供命令（`asw agent detect`）列出所有支持的工具及其安装状态
- **FR-005**: 系统 MUST 在检测结果中显示每个工具的名称、状态图标（✓/✗）、配置文件路径（如果已安装）

#### 配置文件备份与恢复 (FR-006 至 FR-012)

- **FR-006**: 系统 MUST 在修改任何工具配置文件前自动创建备份
- **FR-007**: 系统 MUST 使用时间戳命名备份文件（格式：`<tool-name>-<YYYYMMDD-HHMMSS>.config.<ext>.bak`）
- **FR-008**: 系统 MUST 将备份文件存储在 `~/.agentswitch/backups/` 目录
- **FR-009**: 系统 MUST 在创建备份前检查磁盘可用空间，不足时输出红色错误信息并提示用户清理磁盘空间或使用 `asw backup clean` 命令，不执行配置修改操作
- **FR-010**: 系统 MUST 为每个工具最多保留 10 个备份文件，超过限制时自动删除最旧的备份
- **FR-011**: 系统 MUST 支持列出所有备份（`asw backup list`），显示工具名称、备份时间、备份文件路径
- **FR-012**: 系统 MUST 支持恢复指定备份到原配置文件（`asw backup restore <agent> --backup <timestamp>`）
- **FR-013**: 系统 MUST 支持清理旧备份（`asw backup clean --older-than <duration>`），支持时间单位（d=天、w=周、m=月）
- **FR-014**: 系统 MUST 在备份或恢复失败时输出清晰的错误信息并以非零退出码退出

#### 模型配置切换 (FR-015 至 FR-024)

- **FR-015**: 系统 MUST 提供切换命令（`asw switch <agent> <model>`）将指定工具切换到指定模型配置
- **FR-016**: 系统 MUST 在切换前验证指定的模型配置是否存在于 `~/.agentswitch/config.toml` 中
- **FR-017**: 系统 MUST 在切换前自动备份工具的当前配置文件
- **FR-018**: 系统 MUST 根据工具的配置文件格式（JSON/TOML/YAML）正确解析和修改配置
- **FR-019**: 系统 MUST 在修改配置文件时替换 API 相关字段（base_url、api_key、model_id）并保留其他自定义设置
- **FR-020**: 系统 MUST 在工具不支持某些 OpenAI API 参数时忽略这些不兼容字段，并在切换完成后显示黄色警告信息列出未被应用的字段
- **FR-021**: 系统 MUST 在检测到可能覆盖配置文件的环境变量（如 OPENAI_API_KEY、API_BASE_URL）时，在切换完成后显示黄色警告，提示用户检查相关环境变量以确保配置生效
- **FR-022**: 系统 MUST 在切换成功后更新 `~/.agentswitch/config.toml` 中的 `active_models` 映射
- **FR-023**: 系统 MUST 在切换成功后输出绿色成功信息，显示工具名称和模型名称
- **FR-024**: 系统 MUST 在模型配置不存在时输出红色错误信息并提示可用模型
- **FR-025**: 系统 MUST 在工具未安装时输出红色错误信息并提供安装建议，在配置文件不存在时使用默认配置模板创建新配置文件并应用模型配置

#### 当前配置状态查看 (FR-026 至 FR-029)

- **FR-026**: 系统 MUST 在修改配置文件时使用文件锁（flock）确保多进程并发访问时的互斥，防止数据损坏
- **FR-027**: 系统 MUST 保证配置文件修改的原子性（要么完全成功，要么保持原状）
- **FR-028**: 系统 MUST 提供状态命令（`asw status`）显示所有工具的当前配置状态
- **FR-029**: 系统 MUST 在状态输出中显示工具名称、当前使用的模型名称、配置文件路径、最后切换时间

#### 适配器接口设计 (FR-030 至 FR-039)

- **FR-030**: 系统 MUST 在工具尚未配置时显示 "未配置" 或 "使用默认配置"
- **FR-031**: 系统 MUST 以表格形式格式化状态输出，包含列对齐和边框
- **FR-032**: 系统 MUST 定义统一的 `AgentAdapter` trait，包含以下方法：`name()`、`detect()`、`config_path()`、`backup()`、`apply()`、`restore()`、`current_model()`
- **FR-033**: 系统 MUST 在适配器中实现版本检测逻辑，自动识别工具的版本号（通过解析配置文件结构、检测关键字段或读取版本标识）
- **FR-034**: 系统 MUST 为不同版本的工具维护对应的配置解析策略，确保多版本兼容性
- **FR-035**: 系统 MUST 为 Claude Code 实现适配器，支持 JSON 格式配置文件，适配版本为 Claude Code CLI 2025-2026
- **FR-036**: 系统 MUST 为 Codex 实现适配器，支持 TOML 格式配置文件，适配版本为 v0.80.0（版本更新需重新验证兼容性）
- **FR-037**: 系统 MUST 为 Gemini CLI 实现适配器，支持 JSON 格式配置文件（⚠️ 注意：实际为 JSON 而非 YAML），适配版本为 Gemini CLI 2025-2026
- **FR-038**: 系统 MUST 在适配器的 `detect()` 方法中检查工具是否已安装
- **FR-039**: 系统 MUST 在适配器的 `backup()` 方法中创建配置文件的完整备份

#### 配置文件格式处理 (FR-040 至 FR-047)

- **FR-040**: 系统 MUST 在适配器的 `apply()` 方法中将模型配置应用到工具的配置文件
- **FR-041**: 系统 MUST 在适配器的 `restore()` 方法中将备份内容恢复到配置文件
- **FR-042**: 系统 MUST 支持 JSON 格式配置文件（Claude Code、Gemini CLI）
- **FR-043**: 系统 MUST 支持 TOML 格式配置文件（Codex）
- **FR-044**: 系统 MUST 在解析配置文件失败时输出友好的错误信息，指出文件位置和解析错误原因
- **FR-045**: 系统 MUST 在序列化配置文件时保持原有格式（缩进、排序、注释）
- **FR-046**: 系统 MUST 在配置文件不存在时根据工具的默认配置模板创建新配置文件

#### 错误处理与用户体验 (FR-048 至 FR-056)

- **FR-048**: 系统 MUST 在配置文件是符号链接时跟随链接并修改实际文件，保持与工具读取行为一致
- **FR-049**: 系统 MUST 在所有成功操作中使用绿色文本和 ✓ 前缀
- **FR-050**: 系统 MUST 在所有错误操作中使用红色文本和 ✗ 前缀
- **FR-051**: 系统 MUST 在警告信息中使用黄色文本
- **FR-052**: 系统 MUST 在所有错误信息中包含具体的失败原因和解决建议
- **FR-053**: 系统 MUST 在配置文件损坏（无法解析）时提示用户手动恢复或重建配置，并指出可用的备份文件列表，避免自动恢复导致的数据二次损坏
- **FR-054**: 系统 MUST 在配置文件权限不足时提供具体的修复命令（如 `chmod 644 <文件路径>`），帮助用户自行解决权限问题
- **FR-055**: 系统 MUST 在 API Key 显示时进行掩码处理（仅显示前 4 个字符）
- **FR-056**: 系统 MUST 在配置切换过程中显示进度信息（如 "正在备份..."、"正在应用配置..."）
- **FR-057**: 系统 MUST 在操作完成后提供下一步操作建议（如切换成功后提示 "使用 'claude-code' 命令测试新配置"）

### 关键实体

#### AgentAdapter（Agent 适配器接口）

代表一个 Code Agent 工具的适配器接口，定义了所有适配器必须实现的方法：
- **name()**: 返回工具的唯一标识符（如 "claude-code"）
- **detect()**: 检查工具是否已安装
- **config_path()**: 返回工具的配置文件路径
- **backup()**: 创建配置文件的备份
- **apply()**: 将模型配置应用到工具的配置文件
- **restore()**: 从备份恢复配置文件
- **current_model()**: 返回工具当前使用的模型配置名称

#### Backup（配置备份）

代表一个工具配置文件的备份快照：
- **agent_name**: 工具名称（如 "claude-code"）
- **timestamp**: 备份创建时间（ISO 8601 格式）
- **file_path**: 备份文件的完整路径
- **original_path**: 原配置文件的路径
- **size_bytes**: 备份文件大小（用于显示和清理判断）

#### AgentConfigState（Agent 配置状态）

代表一个工具的当前配置状态：
- **agent_name**: 工具名称
- **model_name**: 当前使用的模型配置名称（如果已配置）
- **config_path**: 配置文件路径
- **last_switched**: 最后切换时间（如果已切换）
- **is_installed**: 工具是否已安装
- **config_exists**: 配置文件是否存在

## 成功标准

### 可衡量的结果

- **SC-001**: 开发者可以在 10 秒内完成模型配置切换（从执行 `asw switch` 命令到配置文件更新完成）
- **SC-002**: 系统支持至少 3 种主流 Code Agent 工具（Claude Code、Codex、Gemini CLI）
- **SC-003**: 配置备份操作在 500ms 内完成（对于典型大小的配置文件 < 10KB）
- **SC-004**: 95% 的切换操作能够在首次尝试时成功（排除用户输入错误和外部依赖问题）
- **SC-005**: 所有配置文件修改操作 100% 保证原子性（要么完全成功，要么保持原状）
- **SC-006**: 系统能够正确识别和解析 100% 的标准配置文件格式（JSON/TOML/YAML）
- **SC-007**: 配置状态查询命令在 200ms 内返回结果
- **SC-008**: 适配器接口设计允许在不超过 100 行代码的情况下添加对新工具的支持（不包括配置文件解析逻辑）
- **SC-009**: 90% 的错误场景能够提供具体的失败原因和可执行的解决建议
- **SC-010**: 配置备份恢复操作 100% 保证数据完整性（恢复后的文件与备份文件内容一致）

## 假设与依赖

### 假设

1. 用户在类 Unix 系统（Linux、macOS）上运行该工具
2. 用户对目标 Code Agent 工具有基本了解（知道如何安装和使用）
3. 各 Code Agent 工具的配置文件路径遵循约定优于配置原则（如 `~/.tool-name/config.ext`）
4. 工具的配置文件包含标准的 OpenAI API 兼容字段（base_url、api_key、model_id 或等效字段）
5. 用户具有 `~/.agentswitch/` 目录和目标工具配置文件的读写权限
6. 各工具的配置文件格式在版本间保持向后兼容

### 依赖

1. Rust 2024 Edition 标准库
2. v0.1.0 已实现的配置管理模块（ModelConfig、AppConfig）
3. JSON 解析库（serde_json）
4. TOML 解析库（toml）
5. YAML 解析库（serde_yaml）
6. 文件操作和权限管理库
7. 时间处理库（用于备份时间戳）

## 范围外

以下功能明确不在本阶段范围：

- 配置预设（Presets）功能（保存和应用配置组合）
- 批量切换（同时切换多个工具到同一模型）
- 配置导入/导出功能
- 配置文件版本控制和自动迁移
- API Key 的加密存储（仅做文件权限保护）
- Web Dashboard 或图形界面
- 配置验证和测试连接功能（如验证 API 是否可用）
- 插件系统（动态加载适配器）
- 配置同步（通过 Git 或其他方式多机器共享）
- 性能测试模式和模型对比报告
- 交互式配置向导
- Shell 自动补全（Bash/Zsh/Fish）
- Windows 平台的差异化处理（文件路径、权限、配置位置）
- 非标准配置文件格式的支持（如 XML、INI）
- 环境变量覆盖配置文件的检测和提示
- 配置文件的差异显示（diff）
- 配置热重载（无需重启工具即可生效）

## 测试策略

### 单元测试

- 适配器接口方法测试（detect、backup、apply、restore、current_model）
- 配置文件解析和序列化测试（JSON/TOML/YAML）
- 备份文件创建和恢复测试
- 配置文件格式保留测试（缩进、排序、注释）
- 错误处理逻辑测试（文件不存在、权限不足、格式错误）

### 集成测试

- 完整的切换流程测试（检测 → 切换 → 验证 → 恢复）
- 多工具配置切换测试
- 备份清理功能测试
- 并发访问场景测试（文件锁、原子性）
- 跨工具配置一致性测试

### 端到端测试

- 首次使用场景（从检测工具到首次切换）
- 错误恢复场景（配置文件损坏、备份恢复）
- 边界条件测试（空配置文件、超长配置、特殊字符）
- 多版本工具配置格式兼容性测试
- 真实工具集成测试（在安装了真实工具的环境中测试）
