ai-shell/升级指南.md

# 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`