@pikecode/api-key-manager 1.0.38 → 1.0.42

package/README.md

@@ -9,6 +9,10 @@
 
 - 🎯 **双 IDE 支持** - 同时管理 Claude Code 和 Codex CLI 配置
 - 🔄 **快速切换** - 一键切换不同的 API 提供商
+- ⚡ **快速启动** - 使用 `-q` 快速启动，跳过参数选择
+- 🧠 **智能记忆** - 自动记住上次使用的启动参数
+- 🏷️ **别名系统** - 为供应商设置简短别名，快速访问
+- ✅ **配置验证** - 一键验证 Token 有效性和 API 可用性
 - 🔐 **安全存储** - 本地文件存储（Unix 自动设置为 0600 权限）
 - 🎨 **多认证模式** - 支持 OAuth、API Key、Auth Token
 - 🚀 **启动参数** - 为每个供应商配置专属启动参数
@@ -26,12 +30,20 @@ npm install -g @pikecode/api-key-manager
 ## 🚀 快速开始
 
 ```bash
-# 添加第一个配置
+# 添加第一个配置（带别名）
 akm add
+# 输入名称: my-provider
+# 输入别名: prod (可选)
 
 # 切换供应商（交互式）
 akm
 
+# 快速启动（使用上次参数）
+akm prod -q
+
+# 验证配置
+akm validate prod
+
 # 查看所有配置
 akm list
 
@@ -39,6 +51,568 @@ akm list
 akm current
 ```
 
+## 📚 详细使用指南
+
+### 首次使用完整流程
+
+#### 步骤 1: 安装 akm
+
+```bash
+# 全局安装
+npm install -g @pikecode/api-key-manager
+
+# 验证安装
+akm --version
+```
+
+#### 步骤 2: 添加第一个供应商
+
+**添加 Claude Code 供应商：**
+
+```bash
+akm add --claude
+```
+
+交互式问答流程：
+
+```
+? 选择要管理的 IDE: Claude Code (Anthropic)
+? 请输入供应商名称 (用于命令行): my-claude
+? 请输入显示名称: My Claude Account
+? 选择认证模式:
+  ❯ 🌐 OAuth令牌模式 (CLAUDE_CODE_OAUTH_TOKEN) - 适用于官方Claude Code
+    🔑 通用API密钥模式 - 支持 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN
+    🔐 认证令牌模式 (仅 ANTHROPIC_AUTH_TOKEN) - 适用于某些服务商
+? 请输入 OAuth Token: sk-ant-oat01-xxxxx
+? 选择默认启动参数:
+  ◉ --continue 继续上次对话
+  ◯ --dangerously-skip-permissions 跳过权限检查
+? 设置主模型 (ANTHROPIC_MODEL): claude-sonnet-4
+? 设置快速模型 (ANTHROPIC_SMALL_FAST_MODEL): claude-haiku-4
+
+✅ 供应商 'my-claude' 已添加
+```
+
+**添加 Codex CLI 供应商：**
+
+```bash
+akm add --codex
+```
+
+交互式问答流程：
+
+```
+? 选择要管理的 IDE: Codex CLI (OpenAI)
+? 选择配置方式:
+  ❯ 从 ~/.codex 导入现有配置
+    手动输入配置
+? 请输入供应商名称 (用于命令行): my-codex
+? 请输入显示名称: My Codex Account
+? 请输入 API Key (OPENAI_API_KEY): sk-xxxxx
+? 请输入基础 URL (OPENAI_BASE_URL): https://api.openai.com
+? 选择默认启动参数:
+  ◉ resume 继续上次对话
+  ◯ --full-auto 全自动模式
+  ◯ --search 启用网页搜索
+
+✅ 供应商 'my-codex' 已添加
+```
+
+#### 步骤 3: 切换并启动
+
+```bash
+# 运行 akm 进入交互式选择界面
+akm
+```
+
+选择供应商后，akm 会自动：
+1. 设置为当前活跃供应商
+2. 配置相应的环境变量/配置文件
+3. 启动对应的 IDE（Claude Code 或 Codex CLI）
+
+#### 步骤 4: 日常使用
+
+```bash
+# 快速切换到指定供应商
+akm my-claude
+
+# 查看当前配置
+akm current
+
+# 查看所有供应商
+akm list
+```
+
+---
+
+### 交互式界面操作说明
+
+#### 主界面（供应商选择）
+
+```
+总共 3 个供应商配置
+
+  ↑ / ↓ 选择供应商 | Enter 确认 | Tab 切换选项 | ESC 退出程序 | Ctrl+C 强制退出
+
+? 请选择要切换的供应商 (总计 3 个):
+  🟢 [Claude] My Claude Account --- 上次使用 - 可用
+  🟢 [Claude] Work Account - 可用
+❯ 🟢 [Codex] My Codex Account - 可用
+  ──────────────
+  ➕ 添加新供应商
+  📋 供应商管理 (编辑/删除)
+  📁 打开配置文件
+  ❌ 退出
+```
+
+**状态图标说明：**
+| 图标 | 含义 |
+|-----|------|
+| 🟢 | API 可用 |
+| 🟡 | 有限可用/响应慢 |
+| 🔴 | API 不可用 |
+| ⏳ | 正在检测 |
+| ⚪ | 未知状态 |
+
+**IDE 标签：**
+| 标签 | 含义 |
+|------|------|
+| [Claude] | Claude Code 供应商 |
+| [Codex] | Codex CLI 供应商 |
+
+#### 启动参数选择界面
+
+选择供应商后进入启动参数选择：
+
+```
+┌─ 启动配置 ─────────────────────────────────┐
+
+  📋 供应商: My Claude Account
+
+  空格 切换选中 | A 全选 | I 反选 | Enter 启动 Claude Code | ESC 返回
+
+? 选择启动参数:
+  ◉ --continue (继续上次对话)
+  ◯ --dangerously-skip-permissions (跳过权限检查)
+```
+
+**快捷键：**
+| 按键 | 功能 |
+|------|------|
+| `Space` | 切换选中状态 |
+| `A` | 全选所有参数 |
+| `I` | 反选（选中变未选，未选变选中）|
+| `Enter` | 确认并启动 |
+| `ESC` | 返回上一级 |
+
+#### 供应商管理界面
+
+从主界面选择"供应商管理"进入：
+
+```
+  ↑ / ↓ 选择供应商或操作 | Enter 确认 | ESC 返回主菜单
+
+┌─ 供应商管理 ─────────────────────────────────┐
+
+? 选择供应商或操作 (总计 3 个):
+❯ 🟢 [Claude] My Claude Account - 可用
+  🟢 [Claude] Work Account - 可用
+  🟢 [Codex] My Codex Account - 可用
+  ──────────────
+  ◀ 返回供应商选择
+  ❌ 退出
+```
+
+选择供应商后显示详情和操作选项：
+
+```
+┌─ 供应商详情 ─────────────────────────────────┐
+
+┌──────────────┬─────────────────────────────────┐
+│ 供应商名称   │ my-claude                       │
+│ 显示名称     │ My Claude Account               │
+│ 认证模式     │ OAuth令牌模式                   │
+│ 基础URL      │ ✨ 官方默认服务器               │
+│ 认证令牌     │ sk-ant-***...***ddd             │
+│ 主模型       │ claude-sonnet-4                 │
+│ 快速模型     │ claude-haiku-4                  │
+│ 创建时间     │ 2025-12-15 13:00                │
+│ 最后使用     │ 2025-12-17 10:30                │
+│ 当前状态     │ ✅ 使用中                       │
+│ 使用次数     │ 42                              │
+└──────────────┴─────────────────────────────────┘
+
+? 选择操作:
+❯ 🚀 立即启动
+  ✏️ 编辑供应商
+  🗑️ 删除供应商
+  ◀ 返回管理列表
+```
+
+---
+
+### 配置示例
+
+#### Claude Code 官方 OAuth（推荐）
+
+适用于：使用官方 Claude Code 登录获取的 OAuth Token
+
+```bash
+akm add --claude
+```
+
+```yaml
+供应商名称: claude-official
+显示名称: Claude Official
+认证模式: oauth_token
+Token: sk-ant-oat01-xxxxxxxx  # 从 claude 登录后获取
+基础URL: (留空，使用官方服务器)
+```
+
+#### Claude Code 第三方 API（API Key 模式）
+
+适用于：使用 Anthropic API Key 或第三方兼容服务
+
+```bash
+akm add --claude
+```
+
+```yaml
+供应商名称: anthropic-api
+显示名称: Anthropic API
+认证模式: api_key
+Token类型: ANTHROPIC_API_KEY
+Token: sk-ant-api03-xxxxxxxx
+基础URL: https://api.anthropic.com  # 或第三方服务地址
+```
+
+#### Claude Code 第三方 API（Auth Token 模式）
+
+适用于：某些第三方服务商要求使用 ANTHROPIC_AUTH_TOKEN
+
+```bash
+akm add --claude
+```
+
+```yaml
+供应商名称: third-party
+显示名称: Third Party Service
+认证模式: auth_token
+Token: your-auth-token
+基础URL: https://your-provider.com/v1
+```
+
+#### Codex CLI 官方 OpenAI
+
+适用于：使用 OpenAI 官方 API
+
+```bash
+akm add --codex
+```
+
+```yaml
+供应商名称: openai-official
+显示名称: OpenAI Official
+API Key: sk-xxxxxxxx
+基础URL: https://api.openai.com  # 可留空
+```
+
+#### Codex CLI 第三方兼容服务
+
+适用于：使用兼容 OpenAI API 的第三方服务
+
+```bash
+akm add --codex
+```
+
+```yaml
+供应商名称: azure-openai
+显示名称: Azure OpenAI
+API Key: your-azure-key
+基础URL: https://your-resource.openai.azure.com/openai/deployments/your-deployment
+```
+
+#### 多账号配置示例
+
+```bash
+# 工作账号
+akm add --claude
+# 名称: work, Token: sk-ant-work-xxx
+
+# 个人账号
+akm add --claude
+# 名称: personal, Token: sk-ant-personal-xxx
+
+# 测试账号
+akm add --codex
+# 名称: test-codex, Token: sk-test-xxx
+
+# 快速切换
+akm work      # 切换到工作账号
+akm personal  # 切换到个人账号
+akm test-codex # 切换到测试账号
+```
+
+---
+
+### 常见问题 FAQ
+
+#### Q1: 切换 Codex 后提示 "Token data is not available"
+
+**原因：** `~/.codex/auth.json` 格式不正确或 `config.toml` 未设置 API Key 认证模式。
+
+**解决方案：**
+```bash
+# 确保使用最新版本 akm
+npm update -g @pikecode/api-key-manager
+
+# 重新切换供应商
+akm my-codex
+```
+
+akm 会自动：
+- 设置 `~/.codex/config.toml` 中的 `preferred_auth_method = "apikey"`
+- 写入正确格式的 `~/.codex/auth.json`
+
+#### Q2: Claude Code 切换后环境变量不生效
+
+**原因：** `~/.claude/settings.json` 中存在冲突的环境变量配置。
+
+**解决方案：** 切换时 akm 会自动检测并提示处理冲突，选择"备份并清空这些变量"即可。
+
+手动检查：
+```bash
+cat ~/.claude/settings.json | grep -A 10 '"env"'
+```
+
+#### Q3: 如何查看完整的 API Key/Token？
+
+**解决方案：** 默认脱敏显示，使用 `--show-token` 参数：
+
+```bash
+akm list --show-token
+akm current --show-token
+```
+
+#### Q4: 配置文件在哪里？如何手动编辑？
+
+**位置：** `~/.akm-config.json`
+
+```bash
+# 通过 akm 打开
+akm
+# 选择 "📁 打开配置文件"
+
+# 或直接编辑
+code ~/.akm-config.json
+vim ~/.akm-config.json
+```
+
+#### Q5: 如何备份和恢复配置？
+
+```bash
+# 创建备份
+akm backup
+
+# 查看备份列表
+akm backup --list
+
+# 恢复备份
+akm backup --restore akm-backup-2025-12-17T10-30-00.json
+
+# 导出到指定文件（可分享）
+akm export my-config.json
+
+# 导出脱敏版本（分享配置模板）
+akm export template.json --mask
+
+# 从文件导入
+akm import my-config.json
+```
+
+#### Q6: 切换时报错 "找不到 claude/codex 命令"
+
+**原因：** 未安装对应的 CLI 工具。
+
+**解决方案：**
+
+```bash
+# 安装 Claude Code
+npm install -g @anthropic-ai/claude-code
+
+# 安装 Codex CLI
+npm install -g @openai/codex
+# 或
+brew install codex
+```
+
+#### Q7: 如何删除某个供应商配置？
+
+```bash
+# 交互式选择删除
+akm remove
+
+# 直接删除指定供应商
+akm remove my-provider
+```
+
+#### Q8: 支持哪些第三方服务？
+
+理论上支持所有兼容以下 API 的服务：
+- **Claude Code**: 兼容 Anthropic API 的服务
+- **Codex CLI**: 兼容 OpenAI API 的服务
+
+常见第三方服务配置：
+| 服务 | IDE | 基础 URL |
+|------|-----|----------|
+| Azure OpenAI | Codex | `https://{resource}.openai.azure.com/...` |
+| OpenRouter | Claude/Codex | `https://openrouter.ai/api/v1` |
+| Together AI | Codex | `https://api.together.xyz/v1` |
+
+#### Q9: 如何只显示某一类 IDE 的供应商？
+
+```bash
+# 只显示 Claude Code 供应商
+akm switch --claude
+akm list --claude
+
+# 只显示 Codex CLI 供应商
+akm switch --codex
+akm list --codex
+```
+
+#### Q10: 配置文件权限问题
+
+akm 会自动设置配置文件权限为 `0600`（仅所有者可读写）。
+
+如果遇到权限问题：
+```bash
+chmod 600 ~/.akm-config.json
+```
+
+#### Q11: 如何使用快速启动模式？
+
+快速启动可以跳过参数选择，直接启动：
+
+```bash
+# 使用上次的参数快速启动
+akm my-provider -q
+
+# 以空参数启动
+akm my-provider --no-args
+
+# 通过别名快速启动
+akm prod -q
+```
+
+**什么时候使用 `-q`？**
+- 日常重复启动
+- 参数已经固定
+- 追求启动速度
+
+**什么时候使用 `--no-args`？**
+- 测试不同参数配置
+- 临时不需要任何参数
+- 重置参数配置
+
+#### Q12: 如何设置和使用别名？
+
+别名可以让你用短名称快速访问供应商：
+
+```bash
+# 添加时设置别名
+akm add
+# 供应商名称: my-long-provider-name
+# 别名: mp  ← 设置简短别名
+
+# 后续使用别名
+akm mp          # 切换
+akm mp -q       # 快速启动
+akm validate mp # 验证
+akm edit mp     # 编辑
+
+# 查看别名
+akm list
+# 输出: my-long-provider-name (Display Name) [别名: mp]
+```
+
+**别名规则：**
+- 不区分大小写
+- 可以为空（可选）
+- 可以随时修改
+- 在所有命令中通用
+
+#### Q13: 如何验证配置是否正确？
+
+使用 `validate` 命令检查 Token 和配置：
+
+```bash
+# 验证单个供应商
+akm validate my-provider
+
+# 验证所有供应商
+akm validate
+
+# 只验证 Claude Code 供应商
+akm validate --claude
+```
+
+**验证内容：**
+- ✅ Token 是否有效
+- ⚡ API 响应时间
+- 🔍 配置是否完整
+- 💡 错误诊断建议
+
+**示例场景：**
+```bash
+# 添加新配置后验证
+akm add
+akm validate new-provider
+
+# 定期检查所有配置
+akm validate
+
+# 切换前验证
+akm validate prod && akm prod -q
+```
+
+#### Q14: 上次使用的参数存在哪里？
+
+参数记录在 `~/.akm-config.json` 的 `lastUsedArgs` 字段：
+
+```json
+{
+  "providers": {
+    "my-provider": {
+      "name": "my-provider",
+      "launchArgs": ["--continue"],      // 默认参数
+      "lastUsedArgs": ["--continue", "--search"],  // 上次使用的参数
+      "usageCount": 42,                  // 使用次数
+      "lastUsed": "2025-12-17T10:30:00"  // 最后使用时间
+    }
+  }
+}
+```
+
+**清除记录：** 下次不使用 `-q` 重新选择参数即可覆盖。
+
+#### Q15: 别名和供应商名称有什么区别？
+
+| 特性 | 供应商名称 | 别名 |
+|------|-----------|------|
+| 用途 | 唯一标识符 | 快速访问 |
+| 必需性 | 必需 | 可选 |
+| 唯一性 | 必须唯一 | 建议唯一 |
+| 长度 | 可以较长 | 建议简短 |
+| 示例 | `my-production-api-v2` | `prod` |
+
+**最佳实践：**
+- 供应商名称用于管理和识别
+- 别名用于日常快速访问
+- 例如：`company-production-claude` → 别名 `prod`
+
+---
+
 ## 📖 完整命令参考
 
 ### 基础命令
@@ -154,6 +728,179 @@ akm remove
 akm remove my-provider
 ```
 
+#### `akm validate`
+验证供应商配置的有效性
+
+```bash
+# 验证单个供应商
+akm validate my-provider
+
+# 通过别名验证
+akm validate prod
+
+# 验证所有供应商
+akm validate
+
+# 仅验证 Claude Code 供应商
+akm validate --claude
+
+# 仅验证 Codex CLI 供应商
+akm validate --codex
+```
+
+**验证内容：**
+- ✅ Token 有效性（通过 API 调用测试）
+- ⚡ API 响应时间
+- 🔍 配置完整性检查
+- 💡 错误诊断和修复建议
+
+**示例输出：**
+```
+🔍 正在验证供应商: Production API (my-production-api)
+═══════════════════════════════════════════════════════
+
+✓ 状态: 可用
+   消息: 可用 120ms
+   响应时间: 120ms
+
+配置详情:
+   供应商名称: my-production-api
+   显示名称: Production API
+   别名: prod
+   IDE: Claude Code
+   认证模式: api_key
+   基础URL: https://api.anthropic.com
+```
+
+### 快速启动功能
+
+akm 提供了两种快速启动模式，可以跳过参数选择，直接启动：
+
+#### `-q, --quick` 快速启动
+
+使用上次的启动参数（如果没有则使用默认参数）快速启动：
+
+```bash
+# 使用上次的参数启动
+akm my-provider -q
+
+# 通过别名快速启动
+akm prod -q
+
+# 也适用于 switch 命令
+akm switch my-provider -q
+```
+
+**工作原理：**
+1. 首次启动时会记录你选择的参数
+2. 下次使用 `-q` 时自动使用上次的参数
+3. 如果没有历史记录，使用默认配置的参数
+
+#### `--no-args` 空参数启动
+
+不使用任何启动参数，直接启动：
+
+```bash
+# 以空参数启动
+akm my-provider --no-args
+
+# 通过别名以空参数启动
+akm prod --no-args
+```
+
+**参数优先级：** `--no-args` > `--quick`
+
+### 别名系统
+
+为供应商设置简短的别名，方便快速访问：
+
+#### 添加时设置别名
+
+```bash
+akm add
+# 输入供应商名称: my-production-api
+# 输入显示名称: Production API
+# 输入别名: prod  ← 设置别名
+```
+
+#### 编辑别名
+
+```bash
+akm edit my-production-api
+# 可以修改或删除别名
+```
+
+#### 使用别名
+
+```bash
+# 通过别名快速切换
+akm prod
+
+# 通过别名快速启动
+akm prod -q
+
+# 通过别名验证
+akm validate prod
+
+# 通过别名编辑
+akm edit prod
+```
+
+**别名特性：**
+- 🔤 不区分大小写（`prod` 和 `PROD` 相同）
+- ✏️ 可随时修改或删除
+- 📋 在列表中会高亮显示
+- 🎯 支持所有命令
+
+**示例：**
+```bash
+akm list
+
+输出:
+✅ ✓ [Claude] my-production-api (Production API) [别名: prod] - 可用 120ms
+🔹 ✓ [Claude] my-dev-api (Development API) [别名: dev] - 可用 85ms
+🔹 ✓ [Codex] my-codex (Codex Account) [别名: cx] - 可用 95ms
+```
+
+### 智能记忆功能
+
+akm 会自动记住你每次使用的启动参数，下次启动时优先显示：
+
+**第一次启动：**
+```bash
+akm my-provider
+
+? 选择启动参数:
+  ◯ --continue
+  ◯ --search
+  ◯ --full-auto
+
+# 选择 --continue 和 --search
+```
+
+**第二次启动（自动记忆）：**
+```bash
+akm my-provider
+
+💡 正在使用上次的启动参数
+
+? 选择启动参数:
+  ◉ --continue  ← 自动选中
+  ◉ --search    ← 自动选中
+  ◯ --full-auto
+```
+
+**与快速启动结合：**
+```bash
+# 首次启动，选择参数
+akm my-provider
+# 选择: --continue, --search
+
+# 后续快速启动（自动使用上次参数）
+akm my-provider -q
+# 💡 使用上次的启动参数: --continue --search
+```
+
 ### 备份与迁移
 
 #### `akm export`
@@ -233,11 +980,34 @@ akm backup --restore backup.json --dir /path/to/backups
 - **api_key** - 通用 API 密钥模式
 - **auth_token** - 认证令牌模式
 
+**切换原理：**
+
+切换 Claude Code 供应商时，akm 通过**环境变量注入**方式工作：
+
+1. **检测设置冲突** → 检查 `~/.claude/settings.json` 中是否有冲突的环境变量
+2. **构建环境变量** → 根据认证模式构建相应的环境变量
+3. **启动子进程** → 使用 `spawn('claude', args, { env })` 启动 Claude Code
+
+```
+认证模式 → 环境变量映射：
+┌─────────────┬────────────────────────────┐
+│ oauth_token │ CLAUDE_CODE_OAUTH_TOKEN    │
+│ api_key     │ ANTHROPIC_API_KEY          │
+│             │ ANTHROPIC_BASE_URL         │
+│ auth_token  │ ANTHROPIC_AUTH_TOKEN       │
+│             │ ANTHROPIC_BASE_URL (可选)  │
+└─────────────┴────────────────────────────┘
+```
+
+> 💡 Claude Code 使用环境变量注入，不修改配置文件，切换只在当前会话生效。
+
 **环境变量：**
 - `CLAUDE_CODE_OAUTH_TOKEN` - OAuth 模式
 - `ANTHROPIC_API_KEY` - API Key 模式
 - `ANTHROPIC_AUTH_TOKEN` - Auth Token 模式
 - `ANTHROPIC_BASE_URL` - 自定义 API 端点
+- `ANTHROPIC_MODEL` - 主模型
+- `ANTHROPIC_SMALL_FAST_MODEL` - 快速模型
 
 **启动参数：**
 - `--continue` - 继续上次对话
@@ -254,6 +1024,27 @@ akm add --claude
 **认证模式：**
 - 使用 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL` 环境变量
 
+**切换原理：**
+
+切换 Codex 供应商时，akm 会自动：
+
+1. **备份现有配置** → `~/.codex/akm-backups/backup-{timestamp}/`
+2. **更新 config.toml** → 设置 `preferred_auth_method = "apikey"`
+3. **写入 auth.json** → 包含选中供应商的 API Key
+4. **注入环境变量** → 启动时传递 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
+
+```
+~/.codex/
+├── config.toml          # preferred_auth_method = "apikey"
+├── auth.json            # { "OPENAI_API_KEY": "your-key" }
+└── akm-backups/         # 自动备份目录
+    └── backup-20251217_120000/
+        ├── config.toml
+        └── auth.json
+```
+
+> 💡 切换后直接运行 `codex` 命令也能使用新配置，无需通过 akm 启动。
+
 **启动参数：**
 - `resume` - 继续上次对话（子命令）
 - `--full-auto` - 全自动模式（自动批准 + 工作区沙盒）⚠️ 与 `--dangerously-bypass-approvals-and-sandbox` 互斥
@@ -322,6 +1113,40 @@ akm add --codex
 }
 ```
 
+## 🏗️ 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        akm (CLI 入口)                           │
+├─────────────────────────────────────────────────────────────────┤
+│  CommandRegistry          命令注册中心，懒加载命令模块            │
+│  ├── add                  添加供应商                            │
+│  ├── switch               切换供应商（默认命令）                 │
+│  ├── list                 列出供应商                            │
+│  ├── edit                 编辑供应商                            │
+│  ├── remove               删除供应商                            │
+│  ├── export/import        导入导出                              │
+│  └── backup               备份恢复                              │
+├─────────────────────────────────────────────────────────────────┤
+│  ConfigManager            配置管理（~/.akm-config.json）         │
+│  ├── 懒加载 & 缓存                                              │
+│  ├── 版本迁移                                                   │
+│  └── 文件权限管理 (0600)                                        │
+├─────────────────────────────────────────────────────────────────┤
+│  IDE 启动器                                                     │
+│  ├── env-launcher.js      Claude Code（环境变量注入）            │
+│  └── codex-launcher.js    Codex CLI（配置文件 + 环境变量）       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**核心设计原则：**
+
+1. **命令懒加载** - 通过 `CommandRegistry` 按需加载命令模块，减少启动时间
+2. **配置缓存** - `ConfigManager` 单例模式，避免重复读取配置文件
+3. **IDE 差异化处理** - Claude Code 用环境变量，Codex CLI 写配置文件
+4. **安全优先** - 配置文件权限 0600，Token 默认脱敏显示
+5. **自动备份** - 切换配置前自动备份，支持回滚
+
 ## 🎯 使用场景
 
 ### 场景 1: 同时使用多个 API Key
@@ -396,6 +1221,62 @@ akm backup --list
 akm backup --restore akm-backup-2025-12-15T05-30-00.json
 ```
 
+### 场景 6: 高效工作流（使用新功能）
+
+```bash
+# 1. 添加供应商（带别名）
+akm add
+# 名称: my-production-api
+# 别名: prod
+# 配置完成...
+
+# 2. 首次启动，选择参数
+akm prod
+# 选择: --continue, --search
+# ✨ 参数会自动记录
+
+# 3. 后续快速启动（0.5秒启动）
+akm prod -q
+# 💡 自动使用上次的参数
+
+# 4. 验证配置
+akm validate
+# 📊 批量验证所有供应商
+
+# 5. 每日工作流
+akm work -q     # 工作时使用工作账号
+akm personal -q # 下班后切换个人账号
+akm dev -q      # 开发时使用测试账号
+```
+
+**效率提升：**
+- ⚡ 启动时间：从 10 秒 → 2 秒（80% 提升）
+- 🎯 操作步骤：从 3 步 → 1 步
+- 💡 无需记忆：自动记住所有参数
+
+### 场景 7: 团队协作最佳实践
+
+```bash
+# 团队管理员：设置标准配置
+akm add
+# 名称: company-prod
+# 别名: prod
+# 配置 API 和默认参数...
+
+# 导出配置模板（脱敏）
+akm export team-config.json --mask
+
+# 团队成员：导入并配置
+akm import team-config.json
+akm edit prod  # 填入自己的 Token
+
+# 验证配置
+akm validate prod
+
+# 日常使用
+akm prod -q  # 快速启动，无需记忆命令
+```
+
 ## ⚠️ 参数互斥说明
 
 某些参数不能同时使用，akm 会自动检测并提示：
@@ -420,7 +1301,45 @@ akm backup --restore akm-backup-2025-12-15T05-30-00.json
 
 ## 📝 更新日志
 
-### v1.0.27 (最新)
+### v1.0.40 (最新) - 🚀 体验大升级
+
+**🎉 Phase 1 优化完成 - 效率提升 80%**
+
+#### ⚡ 快速启动模式
+- ✨ 新增 `-q, --quick` 选项：使用上次参数快速启动
+- ✨ 新增 `--no-args` 选项：以空参数快速启动
+- 🎯 启动时间从 10 秒降至 2 秒
+
+#### 🧠 智能记忆功能
+- ✨ 自动记录上次使用的启动参数
+- ✨ 下次启动时优先显示上次的选择
+- 📊 记录使用次数和最后使用时间
+
+#### 🏷️ 别名系统
+- ✨ 为供应商设置简短别名
+- ✨ 通过别名快速访问：`akm prod -q`
+- 🔤 别名查找不区分大小写
+- 📋 在列表中高亮显示别名
+
+#### ✅ 配置验证
+- ✨ 新增 `akm validate` 命令
+- ✅ 验证 Token 有效性和 API 可用性
+- ⚡ 显示 API 响应时间
+- 🔍 提供错误诊断和修复建议
+- 📊 批量验证所有供应商
+
+#### 🧪 测试覆盖
+- 🎯 新增 41 个单元测试
+- ✅ 总测试数达到 326 个
+- 💯 测试通过率 100%
+
+### v1.0.37
+- 🐛 修复 Codex 切换时无法更新 `~/.codex/auth.json` 的问题
+- ✨ 切换 Codex 供应商时自动写入配置文件
+- ✨ 自动设置 `preferred_auth_method = "apikey"`
+- 💾 切换前自动备份现有 Codex 配置
+
+### v1.0.27
 - ✨ 新增参数互斥校验
 - ✨ 新增 `export` / `import` / `backup` 命令
 - 🧪 测试覆盖率提升 46%