# AI Shell 配置管理说明

## 🔐 敏感配置管理

### 1. 使用 .env 文件

项目现在使用 `.env` 文件来管理敏感配置，确保 API 密钥等信息不会被意外提交到代码库。

#### 配置文件结构：
```
ai-shell/
├── .env                 # 实际配置文件（已在 .gitignore 中排除）
├── .env.example         # 配置模板文件（会被提交到代码库）
└── ai_shell/config.py   # 配置加载逻辑
```

### 2. 配置文件内容

#### `.env` 文件（实际配置）：
```bash
# AI Shell 配置文件
AI_SHELL_API_KEY=f8370a60-fe0a-455f-9167-411d476123d2
AI_SHELL_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/
AI_SHELL_MODEL=deepseek-v3-250324

# 可选配置
AI_SHELL_TIMEOUT=30
AI_SHELL_MAX_RETRIES=3
```

#### `.env.example` 文件（模板）：
```bash
# AI Shell 配置文件模板
AI_SHELL_API_KEY=your_api_key_here
AI_SHELL_BASE_URL=https://your-api-endpoint.com/v3/
AI_SHELL_MODEL=your_model_name

# 可选配置
AI_SHELL_TIMEOUT=30
AI_SHELL_MAX_RETRIES=3
```

## 🔧 配置加载优先级

配置系统按以下优先级加载配置：

1. **环境变量**（最高优先级）
2. **当前目录的 .env 文件**
3. **包目录的 .env 文件**
4. **~/.ai-shell/.env 文件**
5. **默认值**（最低优先级）

## 📋 配置项说明

| 配置项 | 环境变量 | 说明 | 默认值 |
|--------|----------|------|--------|
| API Key | `AI_SHELL_API_KEY` | API 密钥（必填） | 无 |
| Base URL | `AI_SHELL_BASE_URL` | API 基础 URL | `https://api.openai.com/v1/` |
| Model | `AI_SHELL_MODEL` | 模型名称 | `gpt-3.5-turbo` |
| Timeout | `AI_SHELL_TIMEOUT` | 请求超时时间（秒） | `30` |
| Max Retries | `AI_SHELL_MAX_RETRIES` | 最大重试次数 | `3` |

## 🚀 使用方法

### 1. 查看当前配置
```bash
ai --config
```

输出示例：
```
AI Shell Configuration:
  Model: deepseek-v3-250324
  Base URL: https://ark.cn-beijing.volces.com/api/v3/
  API Key: f8370a60...123d2
  Timeout: 30s
  Max Retries: 3

Configuration Status: ✅ Valid

Configuration Sources (in priority order):
  1. Environment variables
  2. .env file in current directory
  3. .env file in package directory
  4. ~/.ai-shell/.env file
  5. Default values
```

### 2. 修改配置

#### 方法 1：编辑 .env 文件
```bash
# 编辑项目目录中的 .env 文件
vim .env

# 或创建全局配置
mkdir -p ~/.ai-shell
cp .env ~/.ai-shell/.env
vim ~/.ai-shell/.env
```

#### 方法 2：使用环境变量
```bash
# 临时设置
export AI_SHELL_API_KEY="new_api_key"
export AI_SHELL_MODEL="gpt-4"

# 永久设置（添加到 shell 配置文件）
echo 'export AI_SHELL_API_KEY="new_api_key"' >> ~/.zshrc
```

### 3. 配置验证

程序启动时会自动验证配置：

```bash
ai "test command"
```

如果配置无效，会显示错误信息：
```
❌ Configuration error: API key not configured.
Please set AI_SHELL_API_KEY in .env file or environment variable.
Run 'ai --config' to see current configuration.
```

## 🔄 升级后的配置管理

### 升级流程：
1. **修改代码**
2. **更新版本**: `python scripts/bump_version.py patch`
3. **重新安装**: `uv build && uv tool install . --force`
4. **配置自动保留**：`.env` 文件不会被覆盖

### 配置迁移：
如果需要迁移配置到新环境：
```bash
# 复制配置文件
cp .env /path/to/new/environment/

# 或设置环境变量
export AI_SHELL_API_KEY="your_key"
export AI_SHELL_BASE_URL="your_url"
export AI_SHELL_MODEL="your_model"
```

## 🛡️ 安全最佳实践

### 1. 保护 .env 文件
- ✅ `.env` 文件已在 `.gitignore` 中排除
- ✅ 不要将 `.env` 文件提交到代码库
- ✅ 使用 `.env.example` 作为模板

### 2. API 密钥管理
- 🔐 定期轮换 API 密钥
- 🔐 不要在代码中硬编码密钥
- 🔐 使用环境变量或配置文件

### 3. 权限控制
```bash
# 设置 .env 文件权限（仅所有者可读写）
chmod 600 .env

# 检查权限
ls -la .env
```

## 🔍 故障排除

### 常见问题：

1. **API 密钥未配置**
   ```bash
   # 检查配置
   ai --config
   
   # 设置密钥
   echo 'AI_SHELL_API_KEY=your_key' >> .env
   ```

2. **配置文件未找到**
   ```bash
   # 创建配置文件
   cp .env.example .env
   vim .env
   ```

3. **权限问题**
   ```bash
   # 检查文件权限
   ls -la .env
   
   # 修复权限
   chmod 600 .env
   ```

---

💡 **总结**：现在 AI Shell 使用 `.env` 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。