Initial commit: AI Shell v0.1.0

- 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
2025-07-12 22:06:15 +08:00
commit 644071850a
21 changed files with 3252 additions and 0 deletions
--- a/配置管理说明.md
+++ b/配置管理说明.md
@ -0,0 +1,199 @@
+# 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` 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。