# 功能规格说明: 用户体验优化与高级功能

**功能分支**: `004-ux-optimization`
**创建日期**: 2026-03-10
**状态**: 草稿
**输入**: 用户描述: "创建 Spec 004: 用户体验优化与高级功能

功能概述：
为 AgentSwitch 添加全面的用户体验优化和高级功能，包括：

1. **交互式配置向导**
   - 提供友好的 CLI 交互式向导，引导新用户完成初始化配置
   - 支持模型配置的交互式添加（逐步输入 base_url、api_key、model_id）
   - 工具自动检测和配置引导
   - 配置验证和实时反馈

2. **自动发现已安装工具**
   - 自动检测系统中已安装的 Code Agent 工具（Claude Code、Codex、Gemini CLI、Qwen CLI、Grok CLI 等）
   - 显示每个工具的安装状态和配置文件路径
   - 支持工具配置的健康检查
   - 自动识别工具的配置文件格式和位置

3. **Shell 自动补全**
   - 为 Bash、Zsh、Fish 提供 Shell 自动补全脚本
   - 支持命令、子命令、参数的智能补全
   - 支持动态补全（已配置的模型名称、已安装的工具名称、预设名称等）
   - 提供补全脚本安装命令

4. **配置同步 (Git)**
   - 支持将配置目录初始化为 Git 仓库
   - 提供配置的版本控制和变更历史
   - 支持推送到远程 Git 仓库（GitHub/GitLab/自建）
   - 支持从远程仓库拉取配置更新
   - 提供配置冲突解决策略
   - 敏感信息（API Key）的加密存储

主要价值：
- 降低新用户的使用门槛，提供友好的首次使用体验
- 减少手动配置的工作量，提高配置准确性
- 提升日常使用的效率（自动补全）
- 支持多机器配置共享和团队协作
- 配置的版本控制和安全性保证"

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

## 功能概述

为 AgentSwitch 添加全面的用户体验优化和高级功能，包括交互式配置向导、自动工具发现、Shell 自动补全和 Git 配置同步，以降低使用门槛、提升操作效率并支持多机器配置共享。

## 用户场景与测试

### 用户故事 1 - 交互式配置向导 (优先级: P1)

新用户首次使用 AgentSwitch 时，需要一个友好的引导流程来完成初始化配置，而不是通过命令行参数记忆各种配置选项。交互式向导将逐步引导用户完成模型配置的添加，提供实时验证和友好的错误提示。

**为什么是此优先级**: 这是降低新用户使用门槛的关键功能。交互式向导直接影响用户的第一印象和采用率，是用户能否成功开始使用 AgentSwitch 的决定性因素。

**独立测试**: 可以通过全新安装 AgentSwitch 并运行向导命令来完全测试，提供从零到完成首个配置的完整用户体验价值。

**验收场景**:

1. **给定** 用户首次安装 AgentSwitch 且没有任何配置，**当** 用户运行 `asw init` 或 `asw wizard` 命令，**则** 系统显示欢迎信息并开始配置向导流程
2. **给定** 用户在向导中，**当** 系统提示输入模型配置信息（名称、Base URL、API Key、Model ID），**则** 用户可以逐步输入每个字段并获得实时格式验证反馈
3. **给定** 用户输入了无效的 URL 格式，**当** 用户离开该输入字段，**则** 系统立即显示错误提示并要求重新输入
4. **给定** 用户输入了有效的 API Key，**当** 系统验证该字段，**则** 系统显示掩码后的 Key（如 `sk-***abc123`）以确认输入正确
5. **给定** 用户完成所有必填字段的输入，**当** 用户确认保存，**则** 系统创建配置文件并显示成功消息和后续操作建议
6. **给定** 用户在向导过程中想要取消，**当** 用户选择退出选项，**则** 系统提示是否保存已输入的信息或完全退出

---

### 用户故事 2 - 自动发现已安装工具 (优先级: P1)

用户希望知道系统中已安装哪些 Code Agent 工具，以及它们的配置状态，而无需手动检查每个工具的安装位置和配置文件。系统应自动检测并列出所有已安装工具及其配置文件路径和健康状态。

**为什么是此优先级**: 这是提升用户体验的核心功能。自动发现减少了用户手动查找和验证工具的工作量，同时为其他功能（如配置切换）提供必要的基础信息。

**独立测试**: 可以通过在已知安装了某些工具的系统上运行发现命令来完全测试，提供准确的工具检测和状态报告价值。

**验收场景**:

1. **给定** 系统中安装了 Claude Code 和 Codex，**当** 用户运行 `asw doctor` 或 `asw detect` 命令，**则** 系统显示已安装工具列表及其配置文件路径
2. **给定** 系统中检测到工具，**当** 系统分析工具配置文件，**则** 系统显示每个工具的配置健康状态（正常/配置缺失/格式错误）
3. **给定** 某个工具的配置文件损坏或不可读，**当** 系统尝试读取配置，**则** 系统显示错误信息和可能的修复建议
4. **给定** 系统中没有检测到任何工具，**当** 用户运行发现命令，**则** 系统显示友好的提示信息并列出支持的工具列表及安装建议
5. **给定** 用户想要刷新工具状态，**当** 用户运行发现命令，**则** 系统重新扫描系统并更新工具状态缓存
6. **给定** 工具配置文件使用了非标准路径，**当** 系统扫描系统，**则** 系统尝试在常见位置查找配置文件并报告找到的路径

---

### 用户故事 3 - Shell 自动补全 (优先级: P2)

日常使用 AgentSwitch 时，用户希望能够快速输入命令而无需记忆所有命令选项和名称。Shell 自动补全应提供命令、子命令、参数、模型名称、工具名称等的智能补全，显著提升命令行操作效率。

**为什么是此优先级**: 这是提升日常使用效率的重要功能。虽然不影响核心功能，但自动补全能够显著减少用户输入错误和记忆负担，改善整体使用体验。

**独立测试**: 可以通过安装补全脚本并在不同 Shell 中测试补全功能来完全测试，提供智能命令补全和输入效率提升价值。

**验收场景**:

1. **给定** 用户使用 Bash Shell，**当** 用户运行 `asw completion install bash` 命令，**则** 系统生成并安装 Bash 补全脚本到适当位置
2. **给定** 补全脚本已安装，**当** 用户输入 `asw ` 并按 Tab 键，**则** 系统显示所有可用子命令（model、agent、switch、preset、batch 等）
3. **给定** 用户输入 `asw model ` 并按 Tab 键，**当** 系统触发补全，**则** 系统显示 model 子命令的所有操作（add、list、remove、edit）
4. **给定** 用户输入 `asw switch ` 并按 Tab 键，**当** 系统触发补全，**则** 系统显示已检测到的工具名称列表
5. **给定** 用户输入 `asw switch claude-code ` 并按 Tab 键，**当** 系统触发补全，**则** 系统显示已配置的模型名称列表
6. **给定** 用户使用 Zsh 或 Fish Shell，**当** 用户运行相应的安装命令，**则** 系统生成适配该 Shell 的补全脚本
7. **给定** 用户想要卸载补全脚本，**当** 用户运行 `asw completion uninstall` 命令，**则** 系统移除已安装的补全脚本

---

### 用户故事 4 - 配置同步 (Git) (优先级: P2)

用户在多台机器上使用 AgentSwitch，希望能够方便地同步配置而不需要手动复制文件。Git 同步功能应允许用户将配置目录初始化为 Git 仓库，推送到远程仓库，并在其他机器上拉取配置。

**为什么是此优先级**: 这是多机器使用场景的核心需求。虽然不影响单机使用，但对于在多台设备上工作的用户来说，这是必不可少的协作和便利功能。

**独立测试**: 可以通过创建 Git 仓库、推送到远程、在另一台机器拉取的完整流程来完全测试，提供配置版本控制和多机同步价值。

**验收场景**:

1. **给定** 用户已有 AgentSwitch 配置，**当** 用户运行 `asw sync init` 命令，**则** 系统将配置目录初始化为 Git 仓库并创建初始提交
2. **给定** Git 仓库已初始化，**当** 用户运行 `asw sync remote add <url>` 命令，**则** 系统添加远程仓库地址
3. **给定** 远程仓库已配置，**当** 用户运行 `asw sync push` 命令，**则** 系统提交本地更改并推送到远程仓库
4. **给定** 用户在另一台机器上，**当** 用户运行 `asw sync pull` 命令，**则** 系统从远程仓库拉取配置更新
5. **给定** 配置文件中包含 API Key 等敏感信息，**当** 系统准备提交到 Git，**则** 系统自动加密敏感信息或使用 git-crypt 进行保护
6. **给定** 本地配置与远程配置有冲突，**当** 用户运行同步命令，**则** 系统检测冲突并提供解决策略（保留本地/使用远程/手动合并）
7. **给定** 用户想要查看同步状态，**当** 用户运行 `asw sync status` 命令，**则** 系统显示本地与远程的差异和同步状态
8. **给定** 用户想要配置加密，**当** 用户首次初始化同步，**则** 系统提示设置加密密码或使用 GPG 密钥

---

### 边界情况

- 当配置向导被中断（用户按 Ctrl+C 或关闭终端）时会发生什么？
  - 系统保存已输入的信息到临时文件，下次启动向导时询问是否恢复
  - 提供选项部分保存或完全放弃当前进度

- 当工具检测失败（权限不足或文件损坏）时会发生什么？
  - 系统显示详细的错误信息和可能的解决方案
  - 将该工具标记为"检测失败"而不是"未安装"，并在下次重试

- 当用户安装补全脚本到非标准 Shell 配置路径时会发生什么？
  - 系统检测常见的 Shell 配置文件位置（.bashrc、.zshrc、config.fish）
  - 如果找不到配置文件，提示用户手动添加脚本路径

- 当 Git 同步时远程仓库不可访问时会发生什么？
  - 系统显示友好的错误信息（网络错误、认证失败、仓库不存在）
  - 保留本地更改并允许稍后重试

- 当配置同步时检测到敏感信息未加密时会发生什么？
  - 系统警告用户敏感信息可能暴露
  - 提供选项：自动加密、继续提交（风险提示）、取消操作

- 当 Shell 补全数据库过时（新增了模型或工具）时会发生什么？
  - 系统在每次命令触发时动态生成补全列表，无需手动更新
  - 提供命令重新生成补全脚本以优化性能

- 当用户在没有 Git 的系统上尝试初始化同步时会发生什么？
  - 系统检测 Git 是否安装，如未安装则提示用户安装 Git
  - 提供替代方案：手动导出/导入配置文件

- 当配置向导在非交互式环境（如脚本）中运行时会发生什么？
  - 系统检测是否为交互式终端，如果不是则退出并显示错误信息
  - 提供非交互式配置模式作为替代方案

## 需求

### 功能性需求

#### 交互式配置向导
- **FR-001**: 系统 MUST 提供交互式命令行向导，引导新用户完成初始化配置
- **FR-002**: 系统 MUST 在向导中逐步收集模型配置信息（名称、Base URL、API Key、Model ID）
- **FR-003**: 系统 MUST 在用户输入每个字段时提供实时格式验证（URL 格式、必填字段）
- **FR-004**: 系统 MUST 在显示 API Key 时使用掩码格式（如 `sk-***abc123`）以保护敏感信息
- **FR-005**: 系统 MUST 在用户完成配置后创建配置文件并显示成功消息
- **FR-006**: 系统 MUST 允许用户在向导过程中取消并选择保存或放弃已输入的信息
- **FR-007**: 系统 MUST 在检测到非交互式环境时显示友好的错误信息和替代方案

#### 自动发现已安装工具
- **FR-008**: 系统 MUST 自动检测系统中已安装的 Code Agent 工具
- **FR-009**: 系统 MUST 显示每个已安装工具的名称、版本和配置文件路径
- **FR-010**: 系统 MUST 分析每个工具配置文件的健康状态（正常/配置缺失/格式错误）
- **FR-011**: 系统 MUST 在工具配置文件损坏时显示详细的错误信息和修复建议
- **FR-012**: 系统 MUST 在未检测到任何工具时显示友好的提示和支持的工具列表
- **FR-013**: 系统 MUST 在常见位置查找工具配置文件，包括标准路径和非标准路径
- **FR-014**: 系统 MUST 提供命令刷新工具状态缓存

#### Shell 自动补全
- **FR-015**: 系统 MUST 为 Bash、Zsh、Fish Shell 生成自动补全脚本
- **FR-016**: 系统 MUST 支持命令和子命令的智能补全
- **FR-017**: 系统 MUST 支持参数的智能补全（如模型名称、工具名称、预设名称）
- **FR-018**: 系统 MUST 动态生成补全列表以反映最新的配置状态
- **FR-019**: 系统 MUST 提供命令安装补全脚本到适当位置
- **FR-020**: 系统 MUST 提供命令卸载已安装的补全脚本
- **FR-021**: 系统 MUST 在找不到 Shell 配置文件时提示用户手动添加脚本路径

#### 配置同步 (Git)
- **FR-022**: 系统 MUST 支持将配置目录初始化为 Git 仓库
- **FR-023**: 系统 MUST 支持添加和管理远程 Git 仓库地址
- **FR-024**: 系统 MUST 支持提交本地配置更改并推送到远程仓库
- **FR-025**: 系统 MUST 支持从远程仓库拉取配置更新
- **FR-026**: 系统 MUST 在提交前自动检测并加密敏感信息（API Key）
- **FR-027**: 系统 MUST 在同步冲突时提供解决策略（保留本地/使用远程/手动合并）
- **FR-028**: 系统 MUST 显示本地与远程配置的差异和同步状态
- **FR-029**: 系统 MUST 在远程仓库不可访问时显示友好的错误信息
- **FR-030**: 系统 MUST 在 Git 未安装时提示用户安装 Git 或提供替代方案

### 关键实体

- **向导状态 (WizardState)**: 代表配置向导的当前进度，包含已完成的步骤、已输入的信息、临时保存的数据
- **工具检测报告 (ToolDetectionReport)**: 代表工具自动检测的结果，包含已安装工具列表、每个工具的状态、配置文件路径、错误信息
- **补全配置 (CompletionConfig)**: 代表 Shell 补全的配置信息，包含 Shell 类型、安装路径、补全脚本内容
- **同步状态 (SyncState)**: 代表 Git 同步的当前状态，包含本地分支、远程仓库、差异、冲突、加密状态

## 成功标准

### 可衡量的结果

- **SC-001**: 新用户可以在 5 分钟内通过配置向导完成首个模型配置的添加（包含输入验证和保存）
- **SC-002**: 工具自动检测在 3 秒内完成扫描并显示所有已安装工具及其状态
- **SC-003**: Shell 补全在用户按 Tab 键后 200ms 内显示补全建议
- **SC-004**: 配置同步在 10 秒内完成推送或拉取操作（包含 10 个预设和 5 个模型配置）
- **SC-005**: 85% 的新用户在第一次使用时能够通过向导成功完成配置（通过用户测试验证）
- **SC-006**: Shell 补全减少用户命令输入错误率 60%（通过对比使用前后错误率）
- **SC-007**: 配置同步的敏感信息加密覆盖率达到 100%（所有 API Key 在提交前都经过加密）
- **SC-008**: 工具检测准确率达到 95% 以上（已安装工具能被正确识别）
- **SC-009**: 用户在使用自动补全后，命令输入速度提升 40%（通过测量输入时间）
- **SC-010**: 配置同步冲突解决成功率达到 90%（用户能够成功解决冲突并完成同步）

## 假设与约束

### 假设

- 用户使用主流的 Linux 发行版或 macOS（Shell 配置文件在标准位置）
- 用户有基本的命令行操作经验，但可能不熟悉 AgentSwitch 的具体命令
- 用户希望在多台机器间同步配置，并且有使用 Git 的基本经验
- 用户的系统支持标准的终端输入输出交互
- 用户有足够的权限修改自己的配置文件和目录

### 约束

- 交互式向导只能在交互式终端中运行，不支持非交互式环境
- Shell 补全功能仅支持 Bash、Zsh、Fish 三种主流 Shell
- Git 同步功能依赖系统已安装 Git 命令
- 工具检测功能仅能检测已知的 Code Agent 工具（Claude Code、Codex、Gemini CLI 等）
- 配置加密使用对称加密或 git-crypt，需要用户管理加密密钥

## 依赖与风险

### 依赖

- 现有的 ModelConfig 存储系统（Spec 001）
- 现有的 AgentAdapter 系统（Spec 002）
- 现有的配置预设管理（Spec 003）
- 终端交互库（用于实现交互式向导）
- Git 命令行工具（用于配置同步）
- Shell 配置文件（用于安装补全脚本）

### 风险

- **风险 1**: 用户可能不熟悉 Git 操作，导致同步功能使用困难
  - 缓解措施：提供详细的错误提示和操作指南，简化 Git 操作流程

- **风险 2**: 不同 Shell 的配置文件位置可能不统一
  - 缓解措施：检测多个常见的配置文件位置，提供手动安装选项

- **风险 3**: 工具检测可能误报或漏报已安装的工具
  - 缓解措施：使用多种检测方法（命令存在性、配置文件存在性），提供手动刷新选项

- **风险 4**: 敏感信息加密可能增加使用复杂度
  - 缓解措施：使用透明加密，尽可能减少用户操作，提供清晰的加密状态提示

- **风险 5**: 交互式向导可能在某些终端环境中显示异常
  - 缓解措施：检测终端能力，在功能受限时提供简化版本或回退到非交互式模式

## 待确认问题

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