ai-shell/升级指南.md

AI Shell 升级和更新指南

🚀 快速升级方法

方法一：直接重新安装（推荐）

# 在项目目录中
cd /path/to/ai-shell

# 重新构建并安装
uv build
uv tool install . --force

# 验证安装
ai --version

方法二：使用 uv tool upgrade

# 如果项目已发布到 PyPI
uv tool upgrade ai-shell

# 或者从本地项目升级
cd /path/to/ai-shell
uv tool upgrade ai-shell --from .

🔧 开发和版本管理

1. 修改代码后的升级流程

# 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 简化操作

# 查看所有可用命令
make help

# 升级补丁版本并重新安装
make bump-patch
make install

# 升级次版本并重新安装  
make bump-minor
make install

# 清理构建文件
make clean

# 测试安装
make test

📝 常见升级场景

场景 1：修改 API 配置

# 编辑配置文件
vim ai_shell/config.py

# 升级并重新安装
python scripts/bump_version.py patch
uv build
uv tool install . --force

场景 2：添加新功能

# 编辑主程序
vim ai_shell/main.py

# 升级次版本
python scripts/bump_version.py minor
uv build  
uv tool install . --force

场景 3：修改依赖

# 编辑依赖
vim pyproject.toml

# 同步依赖
uv sync

# 重新安装
uv build
uv tool install . --force

🔍 验证升级

检查安装状态

# 查看已安装的工具
uv tool list

# 查看版本信息
ai --version

# 查看配置
ai --config

# 测试功能
ai "echo hello"

故障排除

# 如果命令不存在，检查 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. 配置文件管理

# 查看当前配置
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"

🎯 自动化升级脚本

创建一个一键升级脚本：

#!/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\""

使用方法：

chmod +x quick_upgrade.sh
./quick_upgrade.sh

---

💡 总结：最简单的升级方法就是在项目目录中运行 uv build && uv tool install . --force