zackeryyy wang
644071850a
- AI-powered shell command generator using DeepSeek V3 - Support for natural language to shell command conversion - Secure configuration management with .env files - Package structure with uv tool installation support - Chinese and English language support - Configuration validation and error handling
200 lines
4.5 KiB
Markdown
200 lines
4.5 KiB
Markdown
# 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` 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。
|