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,215 @@
+# AI Shell 升级和更新指南
+
+## 🚀 快速升级方法
+
+### 方法一：直接重新安装（推荐）
+```bash
+# 在项目目录中
+cd /path/to/ai-shell
+
+# 重新构建并安装
+uv build
+uv tool install . --force
+
+# 验证安装
+ai --version
+```
+
+### 方法二：使用 uv tool upgrade
+```bash
+# 如果项目已发布到 PyPI
+uv tool upgrade ai-shell
+
+# 或者从本地项目升级
+cd /path/to/ai-shell
+uv tool upgrade ai-shell --from .
+```
+
+## 🔧 开发和版本管理
+
+### 1. 修改代码后的升级流程
+
+```bash
+# 1. 修改代码（如 ai_shell/main.py, ai_shell/config.py 等）
+
+# 2. 更新版本号
+python scripts/bump_version.py patch    # 0.1.0 -> 0.1.1
+# 或
+python scripts/bump_version.py minor    # 0.1.0 -> 0.2.0
+# 或  
+python scripts/bump_version.py major    # 0.1.0 -> 1.0.0
+
+# 3. 重新构建和安装
+uv build
+uv tool install . --force
+
+# 4. 测试新版本
+ai --version
+ai --config
+ai "test command"
+```
+
+### 2. 使用 Makefile 简化操作
+
+```bash
+# 查看所有可用命令
+make help
+
+# 升级补丁版本并重新安装
+make bump-patch
+make install
+
+# 升级次版本并重新安装  
+make bump-minor
+make install
+
+# 清理构建文件
+make clean
+
+# 测试安装
+make test
+```
+
+## 📝 常见升级场景
+
+### 场景 1：修改 API 配置
+```bash
+# 编辑配置文件
+vim ai_shell/config.py
+
+# 升级并重新安装
+python scripts/bump_version.py patch
+uv build
+uv tool install . --force
+```
+
+### 场景 2：添加新功能
+```bash
+# 编辑主程序
+vim ai_shell/main.py
+
+# 升级次版本
+python scripts/bump_version.py minor
+uv build  
+uv tool install . --force
+```
+
+### 场景 3：修改依赖
+```bash
+# 编辑依赖
+vim pyproject.toml
+
+# 同步依赖
+uv sync
+
+# 重新安装
+uv build
+uv tool install . --force
+```
+
+## 🔍 验证升级
+
+### 检查安装状态
+```bash
+# 查看已安装的工具
+uv tool list
+
+# 查看版本信息
+ai --version
+
+# 查看配置
+ai --config
+
+# 测试功能
+ai "echo hello"
+```
+
+### 故障排除
+```bash
+# 如果命令不存在，检查 PATH
+echo $PATH | grep -o ~/.local/bin
+
+# 如果 PATH 中没有 ~/.local/bin，添加到 shell 配置
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# 完全重新安装
+uv tool uninstall ai-shell
+uv tool install .
+```
+
+## 📦 版本管理最佳实践
+
+### 1. 语义化版本控制
+- **补丁版本** (0.1.0 -> 0.1.1): 修复 bug，小改动
+- **次版本** (0.1.0 -> 0.2.0): 新功能，向后兼容
+- **主版本** (0.1.0 -> 1.0.0): 重大变更，可能不兼容
+
+### 2. 升级前的检查清单
+- [ ] 代码修改完成
+- [ ] 测试功能正常
+- [ ] 更新版本号
+- [ ] 重新构建包
+- [ ] 重新安装工具
+- [ ] 验证新版本
+
+### 3. 配置文件管理
+```bash
+# 查看当前配置
+ai --config
+
+# 如果需要修改 API 配置，编辑：
+vim ai_shell/config.py
+
+# 或者使用环境变量覆盖：
+export AI_SHELL_API_KEY="new_api_key"
+export AI_SHELL_BASE_URL="new_base_url"
+export AI_SHELL_MODEL="new_model"
+```
+
+## 🎯 自动化升级脚本
+
+创建一个一键升级脚本：
+
+```bash
+#!/bin/bash
+# 保存为 quick_upgrade.sh
+
+echo "🔄 AI Shell 快速升级..."
+
+# 检查是否在项目目录
+if [ ! -f "pyproject.toml" ]; then
+    echo "❌ 请在 ai-shell 项目目录中运行此脚本"
+    exit 1
+fi
+
+# 升级补丁版本
+echo "📈 升级版本..."
+python scripts/bump_version.py patch
+
+# 重新构建
+echo "📦 重新构建..."
+uv build
+
+# 重新安装
+echo "🔧 重新安装..."
+uv tool install . --force
+
+# 验证
+echo "✅ 升级完成！"
+ai --version
+
+echo "🧪 测试命令："
+echo "ai --config"
+echo "ai \"echo test\""
+```
+
+使用方法：
+```bash
+chmod +x quick_upgrade.sh
+./quick_upgrade.sh
+```
+
+---
+
+💡 **总结**：最简单的升级方法就是在项目目录中运行 `uv build && uv tool install . --force`