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,165 @@
+# AI Shell 项目配置说明
+
+## 📁 项目结构
+
+```
+ai-shell/
+├── ai.py                    # 主程序文件
+├── pyproject.toml          # 项目配置文件
+├── uv.toml                 # UV 包管理器配置文件
+├── uv.lock                 # 依赖锁定文件（自动生成）
+├── .python-version         # Python 版本固定文件（自动生成）
+├── .venv/                  # 虚拟环境目录（自动生成）
+├── README.md               # 项目说明文档
+├── 配置总结.md             # 配置总结文档
+└── 项目配置说明.md         # 本文件
+```
+
+## 🔧 核心配置文件详解
+
+### 1. `ai.py` - 主程序文件
+**作用**：AI 驱动的 shell 命令生成器
+**功能**：
+- 使用 Gemini AI 模型生成 shell 命令
+- 支持多语言提示和响应
+- 交互式执行确认
+
+**关键配置**：
+```python
+# OpenAI 兼容接口配置
+API_KEY = "f8370a60-fe0a-455f-9167-411d476123d2"
+BASE_URL = "https://ark.cn-beijing.volces.com/api/v3/"
+
+# 使用 DeepSeek V3 模型
+model = OpenAIModel("deepseek-v3-250324")
+```
+
+### 2. `pyproject.toml` - 项目配置文件
+**作用**：定义项目元数据和依赖关系
+**内容解析**：
+```toml
+[project]
+name = "ai-shell"                    # 项目名称
+version = "0.1.0"                    # 版本号
+description = "AI-powered shell command generator"  # 项目描述
+requires-python = ">=3.12"          # Python 版本要求
+dependencies = [                     # 项目依赖
+    "pydantic-ai",                   # AI 框架
+    "openai",                        # OpenAI 兼容 API 客户端
+    "requests>=2.32.4",              # HTTP 请求库
+]
+```
+
+### 3. `uv.toml` - UV 包管理器配置文件 ⭐
+**作用**：配置 UV 包管理器的行为和镜像源
+**重要性**：这是加速包下载的核心配置文件
+
+**详细配置解析**：
+```toml
+# PyPI 镜像源配置
+index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"  # 主镜像源（清华大学）
+extra-index-url = [                                      # 备用镜像源
+    "https://mirrors.aliyun.com/pypi/simple/",          # 阿里云镜像
+    "https://mirrors.cloud.tencent.com/pypi/simple/",   # 腾讯云镜像
+]
+
+# 性能优化配置
+index-strategy = "unsafe-best-match"  # 允许从所有镜像源选择最佳版本
+concurrent-downloads = 10             # 并发下载数量
+cache-dir = "~/.cache/uv"            # 缓存目录
+
+# Python 解释器镜像源（已注释，使用默认源）
+# python-install-mirror = "镜像源URL"
+```
+
+### 4. `uv.lock` - 依赖锁定文件（自动生成）
+**作用**：锁定所有依赖的精确版本
+**特点**：
+- 自动生成，不需要手动编辑
+- 确保在不同环境中安装相同版本的依赖
+- 包含所有传递依赖的版本信息
+
+### 5. `.python-version` - Python 版本固定文件（自动生成）
+**作用**：指定项目使用的 Python 版本
+**内容**：`3.12`
+**用途**：确保项目在正确的 Python 版本下运行
+
+### 6. `.venv/` - 虚拟环境目录（自动生成）
+**作用**：隔离的 Python 环境
+**包含**：
+- 项目特定的 Python 解释器
+- 安装的所有依赖包
+- 环境配置文件
+
+## 🚀 配置优势
+
+### 1. 国内镜像源加速
+- **主源**：清华大学镜像（教育网友好）
+- **备源**：阿里云、腾讯云（商业网络友好）
+- **效果**：包下载速度从几十秒降到秒级
+
+### 2. 智能版本选择
+- `index-strategy = "unsafe-best-match"`
+- 从所有镜像源中选择最佳版本
+- 避免版本冲突和依赖问题
+
+### 3. 性能优化
+- 10 个并发下载
+- 本地缓存机制
+- 快速依赖解析
+
+## 📋 使用指南
+
+### 基本命令
+```bash
+# 安装/更新依赖
+uv sync
+
+# 添加新依赖
+uv add package-name
+
+# 运行程序
+uv run python ai.py "your command description"
+
+# 激活虚拟环境
+uv shell
+```
+
+### 环境管理
+```bash
+# 查看 Python 版本
+uv python pin
+
+# 查看已安装包
+uv pip list
+
+# 清理缓存
+uv cache clean
+```
+
+## ⚠️ 注意事项
+
+1. **配置优先级**：`uv.toml` > `pyproject.toml` 中的 `[tool.uv]` 配置
+2. **镜像源策略**：使用 `unsafe-best-match` 可能有安全风险，但提供更好的包选择
+3. **Python 解释器**：下载新 Python 版本仍然较慢，建议使用系统包管理器
+4. **API 配置**：已内置 Volces (ByteDance) API 配置，使用 DeepSeek V3 模型
+
+## 🔍 故障排除
+
+### 常见问题
+1. **包下载慢**：检查网络连接，尝试切换镜像源
+2. **版本冲突**：运行 `uv sync` 重新解析依赖
+3. **缓存问题**：运行 `uv cache clean` 清理缓存
+
+### 验证配置
+```bash
+# 测试依赖解析速度
+time uv sync --dry-run
+
+# 检查镜像源连通性
+curl -I https://pypi.tuna.tsinghua.edu.cn/simple/
+```
+
+---
+
+🎯 **总结**：这个配置实现了 Python 包的快速下载和管理，同时保持了项目的可移植性和稳定性。