# 功能规格说明: 配置预设与批量管理

**功能分支**: `003-preset-management`
**创建日期**: 2026-03-05
**状态**: 草稿
**输入**: 用户描述: "配置预设与批量管理系统

## 功能概述
为 AgentSwitch 添加配置预设和工作流管理功能，支持保存命名配置组合、批量操作工具配置，以及配置的导入导出。

## 核心用户故事

### 1. 配置预设管理
- 创建命名配置预设（如 development、production）
- 预设包含多个工具到模型的映射关系（如 claude-code → glm, codex → gpt-4）
- 列出所有可用预设及其配置详情
- 应用预设到所有工具或指定工具
- 更新预设中的单个工具配置
- 删除不需要的预设
- 验证预设（检查模型配置是否存在、工具是否已安装）

### 2. 批量操作
- 批量切换：一次性将所有工具（或指定工具列表）切换到同一模型
- 批量验证：检查所有工具的当前配置状态
- 批量状态查看：汇总显示所有工具的配置情况

### 3. 配置导入导出
- 导出单个预设或所有预设为 JSON 文件（用于团队分享和多机器迁移）
- 导入预设文件，支持合并或覆盖策略
- 导出当前所有工具的活跃配置
- 导入配置时自动验证格式和检查模型依赖

## 主要价值
1. 减少重复操作：无需每次执行多次 switch 命令
2. 配置可分享：团队成员可以共享预设配置
3. 工作流支持：为不同项目或环境预设不同配置组合
4. 安全操作：批量操作前自动备份，失败可回滚"

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

## 用户场景与测试

### 用户故事 1 - 配置预设管理 (优先级: P1)

用户希望保存常用的工具配置组合，以便快速恢复和切换。例如，开发环境中使用 GLM 模型，生产环境中使用 GPT-4 模型。

**为什么是此优先级**: 这是核心功能，直接影响用户日常使用效率。预设管理让用户能够保存、恢复和组织配置，解决了需要多次执行 switch 命令的痛点。

**独立测试**: 可以通过创建预设、列出预设、应用预设、删除预设等操作完全测试，提供完整的配置管理价值。

**验收场景**:

1. **给定** 用户已配置多个工具使用不同模型，**当** 用户创建名为 "development" 的预设并包含当前工具配置，**则** 系统保存预设并返回成功确认
2. **给定** 用户已创建多个预设，**当** 用户执行列出预设命令，**则** 系统显示所有预设名称、描述和包含的工具配置映射
3. **给定** 用户已存在 "development" 预设，**当** 用户应用该预设，**则** 系统将预设中的模型配置应用到对应工具并显示应用结果
4. **给定** 用户需要调整预设，**当** 用户更新预设中某个工具的模型配置，**则** 系统保存更新后的预设并返回成功确认
5. **给定** 用户不再需要某个预设，**当** 用户删除该预设，**则** 系统移除预设并返回成功确认

---

### 用户故事 2 - 批量操作 (优先级: P2)

用户需要一次性对多个工具执行相同操作，例如将所有工具切换到同一个模型，或检查所有工具的配置状态。

**为什么是此优先级**: 批量操作提供了效率提升，但在没有预设管理的情况下也能工作。它是对现有 switch 命令的增强。

**独立测试**: 可以通过批量切换、批量验证、批量状态查看等操作完全测试，提供批量管理工具配置的价值。

**验收场景**:

1. **给定** 用户有多个工具正在使用不同模型，**当** 用户执行批量切换命令指定目标模型，**则** 系统将所有工具切换到该模型并显示每个工具的切换结果
2. **给定** 用户只想切换部分工具，**当** 用户执行批量切换命令并指定工具列表和目标模型，**则** 系统仅切换指定工具并显示结果
3. **给定** 用户已配置多个工具，**当** 用户执行批量验证命令，**则** 系统检查每个工具的配置状态并显示验证结果汇总
4. **给定** 用户需要查看所有工具的当前配置，**当** 用户执行批量状态命令，**则** 系统显示所有工具及其当前使用的模型

---

### 用户故事 3 - 配置导入导出 (优先级: P3)

用户需要在团队之间共享配置，或在多台机器之间迁移配置。通过导入导出功能，用户可以分享预设配置和当前活跃配置。

**为什么是此优先级**: 导入导出是增强功能，提升了工具的协作性和可移植性，但在本地使用场景下不是必需的。

**独立测试**: 可以通过导出预设、导出当前配置、导入预设、导入当前配置等操作完全测试，提供配置分享和迁移的价值。

**验收场景**:

1. **给定** 用户已创建多个预设，**当** 用户导出单个预设到文件，**则** 系统生成包含预设配置的标准格式文件
2. **给定** 用户已创建多个预设，**当** 用户导出所有预设到文件，**则** 系统生成包含所有预设和模型配置的标准格式文件
3. **给定** 用户已配置多个工具，**当** 用户导出当前活跃配置，**则** 系统生成包含当前所有工具模型映射的标准格式文件
4. **给定** 用户有一个导出的预设文件，**当** 用户导入该文件，**则** 系统解析文件、验证格式、检查模型依赖并创建预设
5. **给定** 用户导入预设时已存在同名预设，**当** 用户使用合并选项导入，**则** 系统合并配置而不覆盖现有预设
6. **给定** 用户导入预设时已存在同名预设，**当** 用户使用覆盖选项导入，**则** 系统替换现有预设

---

### 边界情况

- 当预设中引用的模型配置不存在时会发生什么？
  - 系统在创建预设时验证模型配置存在性，如果模型不存在则返回错误
  - 在应用预设前验证模型配置，如果模型已删除则提示用户并跳过该工具

- 当预设中引用的工具未安装时会发生什么？
  - 系统在应用预设时检测工具安装状态，未安装的工具跳过并显示警告

- 当批量操作中部分工具失败时会发生什么？
  - 系统继续执行其他工具的操作，最后汇总显示成功和失败的工具列表
  - 对于已成功的工具，操作生效；对于失败的工具，保持原状态

- 当导入的配置文件格式不正确时会发生什么？
  - 系统在导入前验证文件格式，如果格式错误则返回具体错误信息且不影响现有配置

- 当导入的配置文件中包含不存在的模型配置时会发生什么？
  - 系统检查模型配置依赖，如果模型不存在则提示用户并询问是否继续导入（跳过依赖项）

- 当应用预设时某个工具的配置文件损坏或不可访问时会发生什么？
  - 系统跳过该工具并记录错误，继续处理其他工具，最后汇总显示结果

## 需求

### 功能性需求

- **FR-001**: 系统 MUST 允许用户创建命名配置预设，包含多个工具到模型的映射关系
- **FR-002**: 系统 MUST 允许用户为预设添加描述和标签
- **FR-003**: 系统 MUST 在创建预设时验证所有引用的模型配置存在
- **FR-004**: 系统 MUST 允许用户列出所有已创建的预设及其详细信息
- **FR-005**: 系统 MUST 允许用户应用预设到所有工具或指定工具列表
- **FR-006**: 系统 MUST 在应用预设前自动备份每个工具的当前配置
- **FR-007**: 系统 MUST 在应用预设失败时自动回滚到备份配置
- **FR-008**: 系统 MUST 允许用户更新预设中单个工具的模型配置
- **FR-009**: 系统 MUST 允许用户删除不需要的预设
- **FR-010**: 系统 MUST 允许用户验证预设（检查模型配置存在性和工具安装状态）
- **FR-011**: 系统 MUST 允许用户批量切换所有工具或指定工具列表到同一模型
- **FR-012**: 系统 MUST 在批量切换时并发执行操作以提高效率
- **FR-013**: 系统 MUST 允许用户批量验证所有工具的配置状态
- **FR-014**: 系统 MUST 允许用户批量查看所有工具的当前配置
- **FR-015**: 系统 MUST 允许用户导出单个预设或所有预设为标准格式文件
- **FR-016**: 系统 MUST 允许用户导出当前所有工具的活跃配置为标准格式文件
- **FR-017**: 系统 MUST 在导出文件中包含版本信息和导出时间戳
- **FR-018**: 系统 MUST 允许用户从标准格式文件导入预设
- **FR-019**: 系统 MUST 在导入前验证文件格式和模型配置依赖
- **FR-020**: 系统 MUST 支持合并和覆盖两种导入策略
- **FR-021**: 系统 MUST 在导入失败时不影响现有配置
- **FR-022**: 系统 MUST 在批量操作失败时继续执行其他工具的操作
- **FR-023**: 系统 MUST 在批量操作后汇总显示成功和失败的工具列表

### 关键实体

- **配置预设 (Preset)**: 代表一个命名的工具配置组合，包含预设名称、描述、标签、创建时间、更新时间、以及工具到模型的映射关系
- **模型配置 (ModelConfig)**: 代表一个模型的配置信息，已在现有系统中定义
- **工具适配器 (AgentAdapter)**: 代表一个代码代理工具的配置适配器，已在现有系统中定义
- **导出包 (ExportPackage)**: 代表导出的配置文件，包含版本信息、导出时间、预设集合、模型配置集合和当前活跃配置

## 成功标准

### 可衡量的结果

- **SC-001**: 用户可以在 30 秒内创建并应用一个配置预设（包含 3 个工具）
- **SC-002**: 批量切换 5 个工具到同一模型在 10 秒内完成
- **SC-003**: 导出包含 10 个预设的配置文件在 5 秒内完成
- **SC-004**: 导入并应用包含 5 个预设的配置文件在 15 秒内完成
- **SC-005**: 90% 的用户在第一次使用时能够成功创建和应用预设（通过用户测试验证）
- **SC-006**: 配置预设功能将与执行多次 switch 命令相比减少 70% 的操作时间
- **SC-007**: 批量操作的错误恢复率达到 100%（失败工具不影响其他工具）
- **SC-008**: 导入配置的验证准确率达到 100%（所有格式错误和依赖缺失都能被检测）

## 假设与约束

### 假设

- 用户已经熟悉 AgentSwitch 的基础功能（模型配置、工具切换）
- 用户希望在不同环境（开发、测试、生产）中使用不同的工具配置
- 用户需要在团队之间共享配置，或在多台机器之间迁移配置
- 用户的机器上已安装需要配置的工具
- 用户有足够的文件系统权限来读写配置文件

### 约束

- 配置预设存储在本地文件系统
- 导出的配置文件使用标准数据交换格式以便于分享
- 批量操作的并发度受系统资源限制
- 预设名称在同一用户环境下必须唯一
- 导入配置时需要的模型配置必须已存在于系统中

## 依赖与风险

### 依赖

- 现有的 AgentAdapter 系统（Spec 002）
- 现有的 ModelConfig 存储系统
- 现有的备份管理系统
- 现有的配置文件读写机制

### 风险

- **风险 1**: 用户可能创建大量预设导致管理困难
  - 缓解措施：提供标签和描述功能，支持按标签筛选

- **风险 2**: 批量操作可能影响大量工具，出错时影响面大
  - 缓解措施：自动备份每个工具配置，失败时回滚，汇总显示结果

- **风险 3**: 导入的配置文件可能包含恶意内容
  - 缓解措施：验证文件格式，限制导入路径，不执行任意代码

- **风险 4**: 并发执行批量操作可能导致资源竞争
  - 缓解措施：使用文件锁机制，限制并发数量

## 待确认问题

无（所有功能需求已明确，可以使用行业标准和合理默认值）
