docs: 重构 README.md，整合所有说明文档
- 将分散的说明文件整合到 README.md 中 - 使用中文编写完整的项目文档 - 包含安装、配置、使用、开发、升级、Git 工作流等所有内容 - 删除重复的单独文档文件 - 提供完整的故障排除和贡献指南 - 统一文档结构，提升用户体验
This commit is contained in:
246
Git工作流程.md
246
Git工作流程.md
@ -1,246 +0,0 @@
|
||||
# Git 工作流程说明
|
||||
|
||||
## 🎯 仓库信息
|
||||
|
||||
- **Gitea 地址**: https://gitea.nosuchip.de
|
||||
- **仓库 URL**: https://gitea.nosuchip.de/zack/ai-shell
|
||||
- **用户名**: zack
|
||||
- **仓库名**: ai-shell
|
||||
|
||||
## 📋 当前状态
|
||||
|
||||
✅ **已完成**:
|
||||
- 初始化 Git 仓库
|
||||
- 配置 .gitignore 文件
|
||||
- 创建远程仓库 (通过 API)
|
||||
- 推送初始代码到 main 分支
|
||||
- 设置上游分支跟踪
|
||||
|
||||
## 🔧 基本 Git 操作
|
||||
|
||||
### 1. 查看状态
|
||||
```bash
|
||||
git status # 查看工作区状态
|
||||
git log --oneline # 查看提交历史
|
||||
git remote -v # 查看远程仓库
|
||||
```
|
||||
|
||||
### 2. 日常开发流程
|
||||
```bash
|
||||
# 1. 修改代码
|
||||
vim ai_shell/main.py
|
||||
|
||||
# 2. 查看更改
|
||||
git diff
|
||||
|
||||
# 3. 添加更改
|
||||
git add . # 添加所有更改
|
||||
git add ai_shell/main.py # 添加特定文件
|
||||
|
||||
# 4. 提交更改
|
||||
git commit -m "feat: add new feature"
|
||||
|
||||
# 5. 推送到远程
|
||||
git push # 推送到当前分支
|
||||
git push origin main # 明确推送到 main 分支
|
||||
```
|
||||
|
||||
### 3. 版本发布流程
|
||||
```bash
|
||||
# 1. 更新版本号
|
||||
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
|
||||
|
||||
# 2. 提交版本更新
|
||||
git add ai_shell/__init__.py pyproject.toml
|
||||
git commit -m "bump: version to v0.1.1"
|
||||
|
||||
# 3. 创建标签
|
||||
git tag -a v0.1.1 -m "Release version 0.1.1"
|
||||
|
||||
# 4. 推送代码和标签
|
||||
git push
|
||||
git push --tags
|
||||
```
|
||||
|
||||
## 🌿 分支管理
|
||||
|
||||
### 创建功能分支
|
||||
```bash
|
||||
# 创建并切换到新分支
|
||||
git checkout -b feature/new-command-parser
|
||||
|
||||
# 开发完成后合并
|
||||
git checkout main
|
||||
git merge feature/new-command-parser
|
||||
|
||||
# 删除功能分支
|
||||
git branch -d feature/new-command-parser
|
||||
```
|
||||
|
||||
### 创建发布分支
|
||||
```bash
|
||||
# 创建发布分支
|
||||
git checkout -b release/v0.2.0
|
||||
|
||||
# 在发布分支上进行最后的调整
|
||||
# 完成后合并到 main
|
||||
git checkout main
|
||||
git merge release/v0.2.0
|
||||
git tag -a v0.2.0 -m "Release version 0.2.0"
|
||||
```
|
||||
|
||||
## 🔄 同步和更新
|
||||
|
||||
### 从远程拉取更新
|
||||
```bash
|
||||
git pull # 拉取并合并
|
||||
git fetch # 仅拉取，不合并
|
||||
git pull --rebase # 使用 rebase 方式拉取
|
||||
```
|
||||
|
||||
### 解决冲突
|
||||
```bash
|
||||
# 如果出现冲突
|
||||
git status # 查看冲突文件
|
||||
# 手动编辑冲突文件
|
||||
git add . # 标记冲突已解决
|
||||
git commit # 完成合并
|
||||
```
|
||||
|
||||
## 📝 提交信息规范
|
||||
|
||||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||||
|
||||
```bash
|
||||
# 功能添加
|
||||
git commit -m "feat: add configuration validation"
|
||||
|
||||
# Bug 修复
|
||||
git commit -m "fix: resolve cache directory issue"
|
||||
|
||||
# 文档更新
|
||||
git commit -m "docs: update installation guide"
|
||||
|
||||
# 代码重构
|
||||
git commit -m "refactor: improve config loading logic"
|
||||
|
||||
# 性能优化
|
||||
git commit -m "perf: optimize command generation speed"
|
||||
|
||||
# 测试相关
|
||||
git commit -m "test: add unit tests for config module"
|
||||
|
||||
# 构建相关
|
||||
git commit -m "build: update dependencies"
|
||||
|
||||
# CI/CD 相关
|
||||
git commit -m "ci: add automated testing workflow"
|
||||
```
|
||||
|
||||
## 🛡️ 安全配置
|
||||
|
||||
### 1. 凭据管理
|
||||
```bash
|
||||
# 查看当前远程 URL（包含凭据）
|
||||
git remote get-url origin
|
||||
|
||||
# 如果需要更改凭据
|
||||
git remote set-url origin https://new_username:new_password@gitea.nosuchip.de/zack/ai-shell.git
|
||||
```
|
||||
|
||||
### 2. 敏感文件保护
|
||||
- ✅ `.env` 文件已在 `.gitignore` 中排除
|
||||
- ✅ 构建产物 (`dist/`, `build/`) 已排除
|
||||
- ✅ 缓存文件已排除
|
||||
|
||||
### 3. 检查敏感信息
|
||||
```bash
|
||||
# 检查是否意外提交了敏感文件
|
||||
git log --name-only | grep -E "\.(env|key|pem)$"
|
||||
|
||||
# 如果意外提交了敏感文件，需要从历史中移除
|
||||
git filter-branch --force --index-filter \
|
||||
'git rm --cached --ignore-unmatch .env' \
|
||||
--prune-empty --tag-name-filter cat -- --all
|
||||
```
|
||||
|
||||
## 🚀 自动化工作流
|
||||
|
||||
### 1. 快速升级和推送
|
||||
创建脚本 `scripts/release.sh`:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# 快速发布脚本
|
||||
|
||||
VERSION_TYPE=${1:-patch}
|
||||
|
||||
echo "🔄 升级版本 ($VERSION_TYPE)..."
|
||||
python scripts/bump_version.py $VERSION_TYPE
|
||||
|
||||
echo "📦 重新构建..."
|
||||
uv build
|
||||
|
||||
echo "🔧 重新安装..."
|
||||
uv tool install . --force
|
||||
|
||||
echo "📝 提交更改..."
|
||||
git add .
|
||||
git commit -m "bump: version to $(grep '__version__' ai_shell/__init__.py | cut -d'"' -f2)"
|
||||
|
||||
echo "🚀 推送到远程..."
|
||||
git push
|
||||
|
||||
echo "✅ 发布完成！"
|
||||
```
|
||||
|
||||
### 2. 使用方法
|
||||
```bash
|
||||
chmod +x scripts/release.sh
|
||||
|
||||
# 发布补丁版本
|
||||
./scripts/release.sh patch
|
||||
|
||||
# 发布次版本
|
||||
./scripts/release.sh minor
|
||||
|
||||
# 发布主版本
|
||||
./scripts/release.sh major
|
||||
```
|
||||
|
||||
## 🔍 常用命令速查
|
||||
|
||||
```bash
|
||||
# 状态查看
|
||||
git status # 工作区状态
|
||||
git log --oneline -10 # 最近10次提交
|
||||
git diff # 查看未暂存的更改
|
||||
git diff --cached # 查看已暂存的更改
|
||||
|
||||
# 分支操作
|
||||
git branch # 查看本地分支
|
||||
git branch -r # 查看远程分支
|
||||
git branch -a # 查看所有分支
|
||||
|
||||
# 远程操作
|
||||
git remote -v # 查看远程仓库
|
||||
git fetch --all # 拉取所有远程分支
|
||||
git push --all # 推送所有分支
|
||||
|
||||
# 标签操作
|
||||
git tag # 查看所有标签
|
||||
git tag -l "v*" # 查看版本标签
|
||||
git push --tags # 推送所有标签
|
||||
|
||||
# 撤销操作
|
||||
git checkout -- file.txt # 撤销文件更改
|
||||
git reset HEAD file.txt # 取消暂存
|
||||
git reset --hard HEAD~1 # 撤销最后一次提交
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
🎉 **仓库地址**: https://gitea.nosuchip.de/zack/ai-shell
|
||||
|
||||
现在您可以在浏览器中访问仓库，查看代码和文档！
|
||||
829
README.md
829
README.md
@ -1,42 +1,827 @@
|
||||
# AI Shell
|
||||
|
||||
AI-powered shell command generator using DeepSeek V3 model via OpenAI-compatible API.
|
||||
🤖 **基于 DeepSeek V3 的 AI 智能 Shell 命令生成器**
|
||||
|
||||
## Features
|
||||
将自然语言描述转换为可执行的 shell 命令，支持中英文输入，带有交互式执行确认功能。
|
||||
|
||||
- Generate shell commands from natural language descriptions
|
||||
- Interactive execution confirmation (Enter to execute, n to cancel)
|
||||
- Supports multiple languages for prompts and responses
|
||||
- Uses DeepSeek V3 model for high-quality command generation
|
||||
- User-friendly interface with default execution on Enter
|
||||
[](https://gitea.nosuchip.de/zack/ai-shell/releases)
|
||||
[](https://python.org)
|
||||
[](LICENSE)
|
||||
|
||||
## Usage
|
||||
## ✨ 主要特性
|
||||
|
||||
- 🧠 **AI 驱动**: 使用 DeepSeek V3 进行智能命令生成
|
||||
- 🌐 **双语支持**: 支持中文和英文描述
|
||||
- 🛡️ **安全执行**: 执行前交互式确认
|
||||
- ⚙️ **灵活配置**: 支持环境变量和 .env 文件配置
|
||||
- 📦 **简易安装**: 通过 `uv tool install` 全局安装
|
||||
- 🔄 **自动升级**: 内置版本管理和升级工具
|
||||
- 🚀 **快速设置**: 预配置国内镜像源，下载更快
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
uv run python ai.py "your command description here"
|
||||
# 克隆仓库
|
||||
git clone https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
cd ai-shell
|
||||
|
||||
# 配置 API 设置
|
||||
cp .env.example .env
|
||||
vim .env # 填入您的 API 配置
|
||||
|
||||
# 全局安装
|
||||
uv tool install .
|
||||
```
|
||||
|
||||
## Setup
|
||||
### 基本使用
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
# 英文示例
|
||||
ai "list files"
|
||||
ai "show disk usage"
|
||||
ai "find Python files"
|
||||
ai "create a backup of config.txt"
|
||||
|
||||
# 中文示例
|
||||
ai "显示当前目录"
|
||||
ai "查找包含 python 的文件"
|
||||
ai "删除临时文件"
|
||||
ai "压缩文件夹"
|
||||
|
||||
# 查看配置
|
||||
ai --config
|
||||
|
||||
# 显示版本
|
||||
ai --version
|
||||
```
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [安装说明](#-安装说明)
|
||||
- [配置管理](#-配置管理)
|
||||
- [使用示例](#-使用示例)
|
||||
- [开发指南](#-开发指南)
|
||||
- [升级维护](#-升级维护)
|
||||
- [Git 工作流](#-git-工作流)
|
||||
- [故障排除](#-故障排除)
|
||||
- [贡献指南](#-贡献指南)
|
||||
|
||||
## 📦 安装说明
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Python 3.12+**
|
||||
- **UV 包管理器** ([安装指南](https://docs.astral.sh/uv/getting-started/installation/))
|
||||
|
||||
### 方法一：从源码安装（推荐）
|
||||
|
||||
```bash
|
||||
# 1. 克隆仓库
|
||||
git clone https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
cd ai-shell
|
||||
|
||||
# 2. 配置 API 设置
|
||||
cp .env.example .env
|
||||
vim .env # 填入您的 API 配置
|
||||
|
||||
# 3. 全局安装
|
||||
uv tool install .
|
||||
|
||||
# 4. 验证安装
|
||||
ai --version
|
||||
ai --config
|
||||
```
|
||||
|
||||
### 方法二：快速安装
|
||||
|
||||
```bash
|
||||
# 直接从仓库安装
|
||||
uv tool install git+https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
|
||||
# 安装后配置
|
||||
mkdir -p ~/.ai-shell
|
||||
echo 'AI_SHELL_API_KEY=your_api_key' > ~/.ai-shell/.env
|
||||
echo 'AI_SHELL_BASE_URL=your_api_url' >> ~/.ai-shell/.env
|
||||
echo 'AI_SHELL_MODEL=your_model' >> ~/.ai-shell/.env
|
||||
```
|
||||
|
||||
### 验证安装
|
||||
|
||||
```bash
|
||||
# 检查 ai 命令是否可用
|
||||
which ai
|
||||
|
||||
# 测试基本功能
|
||||
ai --version
|
||||
ai --config
|
||||
ai "echo hello world"
|
||||
```
|
||||
|
||||
### 卸载
|
||||
|
||||
```bash
|
||||
uv tool uninstall ai-shell
|
||||
```
|
||||
|
||||
## ⚙️ 配置管理
|
||||
|
||||
### 配置文件结构
|
||||
|
||||
```
|
||||
ai-shell/
|
||||
├── .env # 实际配置文件（已在 .gitignore 中排除）
|
||||
├── .env.example # 配置模板文件（会被提交到代码库）
|
||||
└── ai_shell/config.py # 配置加载逻辑
|
||||
```
|
||||
|
||||
### 配置项说明
|
||||
|
||||
| 配置项 | 环境变量 | 说明 | 默认值 |
|
||||
|--------|----------|------|--------|
|
||||
| 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` |
|
||||
|
||||
### 配置方法
|
||||
|
||||
#### 方法一：使用 .env 文件（推荐）
|
||||
|
||||
```bash
|
||||
# 复制配置模板
|
||||
cp .env.example .env
|
||||
|
||||
# 编辑配置文件
|
||||
vim .env
|
||||
```
|
||||
|
||||
`.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
|
||||
```
|
||||
|
||||
#### 方法二：使用环境变量
|
||||
|
||||
```bash
|
||||
# 临时设置
|
||||
export AI_SHELL_API_KEY="your_api_key"
|
||||
export AI_SHELL_BASE_URL="your_api_url"
|
||||
export AI_SHELL_MODEL="your_model"
|
||||
|
||||
# 永久设置（添加到 shell 配置文件）
|
||||
echo 'export AI_SHELL_API_KEY="your_api_key"' >> ~/.zshrc
|
||||
echo 'export AI_SHELL_BASE_URL="your_api_url"' >> ~/.zshrc
|
||||
echo 'export AI_SHELL_MODEL="your_model"' >> ~/.zshrc
|
||||
```
|
||||
|
||||
### 配置优先级
|
||||
|
||||
配置系统按以下优先级加载配置：
|
||||
|
||||
1. **环境变量**（最高优先级）
|
||||
2. **当前目录的 .env 文件**
|
||||
3. **包目录的 .env 文件**
|
||||
4. **~/.ai-shell/.env 文件**
|
||||
5. **默认值**（最低优先级）
|
||||
|
||||
### 查看当前配置
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 💡 使用示例
|
||||
|
||||
### 基础命令
|
||||
|
||||
```bash
|
||||
# 文件操作
|
||||
ai "列出当前目录的所有文件"
|
||||
ai "显示文件详细信息"
|
||||
ai "查找名称包含 config 的文件"
|
||||
ai "删除所有 .tmp 文件"
|
||||
ai "复制 file.txt 到 backup 目录"
|
||||
|
||||
# 系统信息
|
||||
ai "显示磁盘使用情况"
|
||||
ai "查看内存使用情况"
|
||||
ai "显示当前运行的进程"
|
||||
ai "查看系统负载"
|
||||
|
||||
# 网络操作
|
||||
ai "测试网络连接到 google.com"
|
||||
ai "显示网络接口信息"
|
||||
ai "查看端口 8080 是否被占用"
|
||||
|
||||
# 文本处理
|
||||
ai "在文件中搜索包含 error 的行"
|
||||
ai "统计文件行数"
|
||||
ai "替换文件中的文本"
|
||||
```
|
||||
|
||||
### 英文示例
|
||||
|
||||
```bash
|
||||
ai "list all files"
|
||||
ai "show disk usage"
|
||||
ai "find Python files"
|
||||
ai "create a backup directory"
|
||||
ai "compress folder to zip"
|
||||
ai "extract tar.gz file"
|
||||
ai "check system uptime"
|
||||
ai "monitor CPU usage"
|
||||
```
|
||||
|
||||
### 高级用法
|
||||
|
||||
```bash
|
||||
# 复杂操作
|
||||
ai "找到最大的 10 个文件"
|
||||
ai "批量重命名图片文件"
|
||||
ai "创建定时任务每天备份数据"
|
||||
ai "监控日志文件的变化"
|
||||
|
||||
# 开发相关
|
||||
ai "启动 Python HTTP 服务器"
|
||||
ai "查看 Git 提交历史"
|
||||
ai "安装 Python 包"
|
||||
ai "运行单元测试"
|
||||
```
|
||||
|
||||
### 交互式确认
|
||||
|
||||
每次生成命令后，系统会显示：
|
||||
|
||||
```
|
||||
(AI Thinking): 用户想要列出当前目录的所有文件，我应该使用 ls 命令...
|
||||
|
||||
(AI Answer): ls -la
|
||||
|
||||
Execute? [Y/n]:
|
||||
```
|
||||
|
||||
- 按 **Enter** 或输入 **y** 执行命令
|
||||
- 输入 **n** 取消执行
|
||||
|
||||
### 配置和帮助
|
||||
|
||||
```bash
|
||||
# 查看版本信息
|
||||
ai --version
|
||||
|
||||
# 查看配置状态
|
||||
ai --config
|
||||
|
||||
# 查看帮助信息
|
||||
ai --help
|
||||
```
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
ai-shell/
|
||||
├── .env # 敏感配置（不提交）
|
||||
├── .env.example # 配置模板
|
||||
├── .gitignore # Git 忽略文件
|
||||
├── pyproject.toml # 项目配置
|
||||
├── uv.toml # UV 配置
|
||||
├── uv.lock # 依赖锁定
|
||||
├── Makefile # 开发工具
|
||||
├── README.md # 项目说明
|
||||
├── quick_upgrade.sh # 快速升级脚本
|
||||
├── ai_shell/ # 主包
|
||||
│ ├── __init__.py # 包初始化
|
||||
│ ├── main.py # 主程序入口
|
||||
│ ├── config.py # 配置管理
|
||||
│ ├── agent.py # AI 代理
|
||||
│ └── models.py # 数据模型
|
||||
└── scripts/ # 工具脚本
|
||||
├── bump_version.py # 版本管理
|
||||
└── release.sh # 发布脚本
|
||||
```
|
||||
|
||||
### 开发环境设置
|
||||
|
||||
```bash
|
||||
# 克隆仓库
|
||||
git clone https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
cd ai-shell
|
||||
|
||||
# 安装开发依赖
|
||||
uv sync
|
||||
|
||||
# 配置环境
|
||||
cp .env.example .env
|
||||
vim .env
|
||||
|
||||
# 运行开发版本
|
||||
uv run python -m ai_shell.main "test command"
|
||||
```
|
||||
|
||||
2. Run the tool:
|
||||
### 可用的开发命令
|
||||
|
||||
```bash
|
||||
uv run python ai.py "list all files in current directory"
|
||||
uv run python ai.py "show disk usage"
|
||||
uv run python ai.py "find all Python files"
|
||||
# 查看所有可用命令
|
||||
make help
|
||||
|
||||
# 查看项目状态
|
||||
make status
|
||||
|
||||
# 构建包
|
||||
make build
|
||||
|
||||
# 安装到全局
|
||||
make install
|
||||
|
||||
# 运行测试
|
||||
make test
|
||||
|
||||
# 清理构建文件
|
||||
make clean
|
||||
```
|
||||
|
||||
## Configuration
|
||||
### 代码修改流程
|
||||
|
||||
- **Model**: DeepSeek V3 (deepseek-v3-250324)
|
||||
- **API**: Volces (ByteDance) OpenAI-compatible interface
|
||||
- **Base URL**: https://ark.cn-beijing.volces.com/api/v3/
|
||||
1. **修改代码**
|
||||
```bash
|
||||
vim ai_shell/main.py
|
||||
vim ai_shell/config.py
|
||||
# 等等...
|
||||
```
|
||||
|
||||
## Requirements
|
||||
2. **测试更改**
|
||||
```bash
|
||||
# 使用开发版本测试
|
||||
uv run python -m ai_shell.main "test command"
|
||||
|
||||
- Python 3.12+
|
||||
- UV package manager with configured Chinese mirrors for fast downloads
|
||||
# 或者重新安装测试
|
||||
make install
|
||||
ai "test command"
|
||||
```
|
||||
|
||||
3. **更新版本**
|
||||
```bash
|
||||
# 补丁版本 (0.1.0 -> 0.1.1)
|
||||
make bump-patch
|
||||
|
||||
# 次版本 (0.1.0 -> 0.2.0)
|
||||
make bump-minor
|
||||
|
||||
# 主版本 (0.1.0 -> 1.0.0)
|
||||
make bump-major
|
||||
```
|
||||
|
||||
4. **重新安装**
|
||||
```bash
|
||||
make install
|
||||
```
|
||||
|
||||
5. **验证更改**
|
||||
```bash
|
||||
ai --version
|
||||
ai --config
|
||||
ai "test functionality"
|
||||
```
|
||||
|
||||
## 🔄 升级维护
|
||||
|
||||
### 快速升级
|
||||
|
||||
```bash
|
||||
# 方法一：使用快速升级脚本
|
||||
./quick_upgrade.sh
|
||||
|
||||
# 方法二：使用 Makefile
|
||||
make upgrade
|
||||
|
||||
# 方法三：手动升级
|
||||
uv build && uv tool install . --force
|
||||
```
|
||||
|
||||
### 版本管理
|
||||
|
||||
```bash
|
||||
# 升级版本号
|
||||
python scripts/bump_version.py patch # 0.1.0 -> 0.1.1 (bug修复)
|
||||
python scripts/bump_version.py minor # 0.1.0 -> 0.2.0 (新功能)
|
||||
python scripts/bump_version.py major # 0.1.0 -> 1.0.0 (重大变更)
|
||||
|
||||
# 或使用 Makefile
|
||||
make bump-patch
|
||||
make bump-minor
|
||||
make bump-major
|
||||
```
|
||||
|
||||
### 自动化发布
|
||||
|
||||
```bash
|
||||
# 发布补丁版本（自动：版本升级 + 构建 + 提交 + 推送 + 标签）
|
||||
make release-patch
|
||||
|
||||
# 发布次版本
|
||||
make release-minor
|
||||
|
||||
# 发布主版本
|
||||
make release-major
|
||||
|
||||
# 或使用脚本
|
||||
./scripts/release.sh patch
|
||||
./scripts/release.sh minor
|
||||
./scripts/release.sh major
|
||||
```
|
||||
|
||||
### 完整的升级流程
|
||||
|
||||
1. **修改代码**
|
||||
2. **更新版本**: `make bump-patch`
|
||||
3. **重新安装**: `make install`
|
||||
4. **验证功能**: `ai --version && ai "test"`
|
||||
5. **提交推送**: `make push`
|
||||
|
||||
### 配置迁移
|
||||
|
||||
升级后配置会自动保留，如需迁移到新环境：
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
### 验证升级
|
||||
|
||||
```bash
|
||||
# 检查版本
|
||||
ai --version
|
||||
|
||||
# 检查配置
|
||||
ai --config
|
||||
|
||||
# 测试功能
|
||||
ai "echo test"
|
||||
|
||||
# 查看安装状态
|
||||
uv tool list | grep ai-shell
|
||||
```
|
||||
|
||||
## 🌿 Git 工作流
|
||||
|
||||
### 仓库信息
|
||||
|
||||
- **仓库地址**: https://gitea.nosuchip.de/zack/ai-shell
|
||||
- **克隆地址**: `git clone https://gitea.nosuchip.de/zack/ai-shell.git`
|
||||
- **Web 界面**: https://gitea.nosuchip.de/zack/ai-shell
|
||||
- **发布页面**: https://gitea.nosuchip.de/zack/ai-shell/releases
|
||||
|
||||
### 基本 Git 操作
|
||||
|
||||
```bash
|
||||
# 查看状态
|
||||
git status # 查看工作区状态
|
||||
git log --oneline # 查看提交历史
|
||||
git remote -v # 查看远程仓库
|
||||
|
||||
# 日常开发流程
|
||||
vim ai_shell/main.py # 修改代码
|
||||
git diff # 查看更改
|
||||
git add . # 添加所有更改
|
||||
git commit -m "feat: add new feature" # 提交更改
|
||||
git push # 推送到远程
|
||||
|
||||
# 同步更新
|
||||
git pull # 拉取并合并
|
||||
git fetch # 仅拉取，不合并
|
||||
```
|
||||
|
||||
### 提交信息规范
|
||||
|
||||
使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
|
||||
|
||||
```bash
|
||||
# 功能添加
|
||||
git commit -m "feat: add configuration validation"
|
||||
|
||||
# Bug 修复
|
||||
git commit -m "fix: resolve cache directory issue"
|
||||
|
||||
# 文档更新
|
||||
git commit -m "docs: update installation guide"
|
||||
|
||||
# 代码重构
|
||||
git commit -m "refactor: improve config loading logic"
|
||||
|
||||
# 性能优化
|
||||
git commit -m "perf: optimize command generation speed"
|
||||
|
||||
# 版本升级
|
||||
git commit -m "bump: version to v0.1.1"
|
||||
```
|
||||
|
||||
### 分支管理
|
||||
|
||||
```bash
|
||||
# 创建功能分支
|
||||
git checkout -b feature/new-command-parser
|
||||
|
||||
# 开发完成后合并
|
||||
git checkout main
|
||||
git merge feature/new-command-parser
|
||||
|
||||
# 删除功能分支
|
||||
git branch -d feature/new-command-parser
|
||||
```
|
||||
|
||||
### 版本发布流程
|
||||
|
||||
```bash
|
||||
# 1. 更新版本号
|
||||
python scripts/bump_version.py patch
|
||||
|
||||
# 2. 提交版本更新
|
||||
git add ai_shell/__init__.py pyproject.toml
|
||||
git commit -m "bump: version to v0.1.1"
|
||||
|
||||
# 3. 创建标签
|
||||
git tag -a v0.1.1 -m "Release version 0.1.1"
|
||||
|
||||
# 4. 推送代码和标签
|
||||
git push
|
||||
git push --tags
|
||||
```
|
||||
|
||||
### 使用 Makefile 简化操作
|
||||
|
||||
```bash
|
||||
# 查看项目状态
|
||||
make status
|
||||
|
||||
# 交互式提交和推送
|
||||
make push
|
||||
|
||||
# 自动化发布（包含版本升级、构建、提交、推送、标签）
|
||||
make release-patch
|
||||
```
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. ai 命令不存在
|
||||
|
||||
```bash
|
||||
# 检查 PATH
|
||||
echo $PATH | grep ~/.local/bin
|
||||
|
||||
# 如果没有，添加到 PATH
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
|
||||
|
||||
# 重新加载 shell
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
#### 2. API 密钥未配置
|
||||
|
||||
```bash
|
||||
# 检查配置
|
||||
ai --config
|
||||
|
||||
# 设置密钥
|
||||
echo 'AI_SHELL_API_KEY=your_key' >> .env
|
||||
|
||||
# 或使用环境变量
|
||||
export AI_SHELL_API_KEY="your_key"
|
||||
```
|
||||
|
||||
#### 3. 配置文件未找到
|
||||
|
||||
```bash
|
||||
# 创建配置文件
|
||||
cp .env.example .env
|
||||
vim .env
|
||||
|
||||
# 或创建全局配置
|
||||
mkdir -p ~/.ai-shell
|
||||
cp .env ~/.ai-shell/.env
|
||||
```
|
||||
|
||||
#### 4. 权限问题
|
||||
|
||||
```bash
|
||||
# 检查文件权限
|
||||
ls -la .env
|
||||
|
||||
# 修复权限
|
||||
chmod 600 .env
|
||||
```
|
||||
|
||||
#### 5. 网络连接问题
|
||||
|
||||
```bash
|
||||
# 测试 API 连接
|
||||
curl -H "Authorization: Bearer your_api_key" \
|
||||
-H "Content-Type: application/json" \
|
||||
your_api_url/models
|
||||
|
||||
# 检查代理设置
|
||||
echo $HTTP_PROXY
|
||||
echo $HTTPS_PROXY
|
||||
```
|
||||
|
||||
#### 6. uv 缓存问题
|
||||
|
||||
如果遇到 `~` 目录被创建的问题：
|
||||
|
||||
```bash
|
||||
# 删除错误的缓存目录
|
||||
rm -rf ./~
|
||||
|
||||
# 检查 uv.toml 配置
|
||||
grep cache-dir uv.toml
|
||||
|
||||
# 确保没有设置错误的缓存路径
|
||||
```
|
||||
|
||||
### 调试模式
|
||||
|
||||
```bash
|
||||
# 查看详细错误信息
|
||||
uv run python -m ai_shell.main --debug "test command"
|
||||
|
||||
# 检查配置加载
|
||||
uv run python -c "from ai_shell.config import validate_config; print(validate_config())"
|
||||
|
||||
# 测试 AI 连接
|
||||
uv run python -c "from ai_shell.agent import create_agent; agent = create_agent(); print('OK')"
|
||||
```
|
||||
|
||||
### 重新安装
|
||||
|
||||
```bash
|
||||
# 完全重新安装
|
||||
uv tool uninstall ai-shell
|
||||
uv tool install .
|
||||
|
||||
# 清理并重新构建
|
||||
make clean
|
||||
make build
|
||||
make install
|
||||
```
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
### 如何贡献
|
||||
|
||||
1. **Fork 仓库**
|
||||
```bash
|
||||
# 在 Gitea 上 fork 项目
|
||||
git clone https://gitea.nosuchip.de/your-username/ai-shell.git
|
||||
```
|
||||
|
||||
2. **创建功能分支**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
3. **进行开发**
|
||||
```bash
|
||||
# 修改代码
|
||||
vim ai_shell/main.py
|
||||
|
||||
# 测试更改
|
||||
make install
|
||||
ai "test your changes"
|
||||
```
|
||||
|
||||
4. **提交更改**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: add your feature description"
|
||||
```
|
||||
|
||||
5. **推送并创建 Pull Request**
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
# 在 Gitea 上创建 Pull Request
|
||||
```
|
||||
|
||||
### 开发规范
|
||||
|
||||
- 使用 [Conventional Commits](https://www.conventionalcommits.org/) 提交信息格式
|
||||
- 确保代码通过测试
|
||||
- 更新相关文档
|
||||
- 保持代码风格一致
|
||||
|
||||
### 报告问题
|
||||
|
||||
- **Bug 报告**: https://gitea.nosuchip.de/zack/ai-shell/issues
|
||||
- **功能请求**: https://gitea.nosuchip.de/zack/ai-shell/issues
|
||||
- **讨论**: https://gitea.nosuchip.de/zack/ai-shell/discussions
|
||||
|
||||
### 许可证
|
||||
|
||||
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
|
||||
|
||||
---
|
||||
|
||||
## 📞 支持
|
||||
|
||||
- **仓库**: https://gitea.nosuchip.de/zack/ai-shell
|
||||
- **问题**: https://gitea.nosuchip.de/zack/ai-shell/issues
|
||||
- **版本**: v0.1.0
|
||||
|
||||
🎉 **感谢使用 AI Shell！**
|
||||
|
||||
如果这个项目对您有帮助，请给个 ⭐ Star！
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Python 3.12+**
|
||||
- **UV package manager** ([Installation guide](https://docs.astral.sh/uv/getting-started/installation/))
|
||||
|
||||
### Method 1: From Source (Recommended)
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
cd ai-shell
|
||||
|
||||
# 2. Configure API settings
|
||||
cp .env.example .env
|
||||
vim .env # Fill in your API configuration
|
||||
|
||||
# 3. Install globally
|
||||
uv tool install .
|
||||
|
||||
# 4. Verify installation
|
||||
ai --version
|
||||
ai --config
|
||||
```
|
||||
|
||||
### Method 2: Quick Install
|
||||
|
||||
```bash
|
||||
# Direct install from repository
|
||||
uv tool install git+https://gitea.nosuchip.de/zack/ai-shell.git
|
||||
|
||||
# Configure after installation
|
||||
mkdir -p ~/.ai-shell
|
||||
echo 'AI_SHELL_API_KEY=your_api_key' > ~/.ai-shell/.env
|
||||
echo 'AI_SHELL_BASE_URL=your_api_url' >> ~/.ai-shell/.env
|
||||
echo 'AI_SHELL_MODEL=your_model' >> ~/.ai-shell/.env
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
```bash
|
||||
# Check if ai command is available
|
||||
which ai
|
||||
|
||||
# Test basic functionality
|
||||
ai --version
|
||||
ai --config
|
||||
ai "echo hello world"
|
||||
```
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
uv tool uninstall ai-shell
|
||||
```
|
||||
|
||||
119
使用示例.md
119
使用示例.md
@ -1,119 +0,0 @@
|
||||
# AI Shell 使用示例
|
||||
|
||||
## 🚀 基本使用流程
|
||||
|
||||
### 示例 1：查看当前日期（按 Enter 执行）
|
||||
```bash
|
||||
$ uv run python ai.py "show current date"
|
||||
|
||||
(AI Thinking): To display the current date, the `date` command is the most straightforward and commonly used tool in Unix-like systems.
|
||||
|
||||
(AI Answer): date
|
||||
Execute? [Y/n]: ⏎ # 直接按 Enter 键
|
||||
2025年 7月12日 星期六 16时08分00秒 CST
|
||||
```
|
||||
|
||||
### 示例 2：危险命令（输入 n 取消）
|
||||
```bash
|
||||
$ uv run python ai.py "remove all files"
|
||||
|
||||
(AI Thinking): To remove all files in the current directory, we can use the `rm` command. However, we need to be cautious because this action is irreversible.
|
||||
|
||||
(AI Answer): rm -rf *
|
||||
Execute? [Y/n]: n # 输入 n 取消执行
|
||||
```
|
||||
|
||||
### 示例 3：中文命令（按 Enter 执行）
|
||||
```bash
|
||||
$ uv run python ai.py "显示当前目录下的文件"
|
||||
|
||||
(AI Thinking): 用户想要显示当前目录下的文件。最常用和直接的命令是 `ls`，它会列出当前目录中的所有文件和文件夹。
|
||||
|
||||
(AI Answer): ls
|
||||
Execute? [Y/n]: ⏎ # 直接按 Enter 键
|
||||
README.md ai.py pyproject.toml uv.lock uv.toml
|
||||
```
|
||||
|
||||
## 📋 交互选项说明
|
||||
|
||||
### 执行命令的方式：
|
||||
- **直接按 Enter**: 执行命令（默认选择）
|
||||
- **输入 y 或 yes**: 执行命令
|
||||
- **输入 n 或 no**: 取消执行
|
||||
|
||||
### 提示符说明：
|
||||
- `Execute? [Y/n]:`
|
||||
- `[Y/n]` 表示默认选择是 Y（执行）
|
||||
- 大写的 Y 表示这是默认选项
|
||||
- 直接按 Enter 等同于选择 Y
|
||||
|
||||
## 🎯 使用技巧
|
||||
|
||||
### 1. 快速执行常用命令
|
||||
对于安全的查看类命令，可以直接按 Enter 快速执行：
|
||||
```bash
|
||||
uv run python ai.py "list files" # Enter 执行
|
||||
uv run python ai.py "show disk usage" # Enter 执行
|
||||
uv run python ai.py "current directory" # Enter 执行
|
||||
```
|
||||
|
||||
### 2. 谨慎处理危险命令
|
||||
对于可能造成数据丢失的命令，建议仔细检查后再决定：
|
||||
```bash
|
||||
uv run python ai.py "delete old logs" # 检查命令后再决定
|
||||
uv run python ai.py "format disk" # 输入 n 取消
|
||||
uv run python ai.py "remove directory" # 仔细确认
|
||||
```
|
||||
|
||||
### 3. 中英文混合使用
|
||||
```bash
|
||||
# 英文命令
|
||||
uv run python ai.py "find Python files"
|
||||
|
||||
# 中文命令
|
||||
uv run python ai.py "查找Python文件"
|
||||
|
||||
# 混合使用
|
||||
uv run python ai.py "find all .py files in current directory"
|
||||
```
|
||||
|
||||
## 🔧 常用命令示例
|
||||
|
||||
### 文件操作
|
||||
```bash
|
||||
uv run python ai.py "create a backup directory"
|
||||
uv run python ai.py "copy all text files to backup"
|
||||
uv run python ai.py "find files larger than 100MB"
|
||||
```
|
||||
|
||||
### 系统信息
|
||||
```bash
|
||||
uv run python ai.py "show system information"
|
||||
uv run python ai.py "check memory usage"
|
||||
uv run python ai.py "list running processes"
|
||||
```
|
||||
|
||||
### 网络相关
|
||||
```bash
|
||||
uv run python ai.py "check network connectivity"
|
||||
uv run python ai.py "show network interfaces"
|
||||
uv run python ai.py "test connection to google.com"
|
||||
```
|
||||
|
||||
### 开发相关
|
||||
```bash
|
||||
uv run python ai.py "find all Python files"
|
||||
uv run python ai.py "count lines of code"
|
||||
uv run python ai.py "start a simple HTTP server"
|
||||
```
|
||||
|
||||
## ⚠️ 安全提醒
|
||||
|
||||
1. **仔细阅读 AI 生成的命令**：在执行前确保理解命令的作用
|
||||
2. **危险命令要谨慎**：涉及删除、格式化等操作时要特别小心
|
||||
3. **测试环境优先**：在重要系统上使用前，建议先在测试环境验证
|
||||
4. **备份重要数据**：执行可能影响数据的命令前，确保有备份
|
||||
|
||||
---
|
||||
|
||||
💡 **提示**：现在直接按 Enter 键就能执行命令，让您的工作流程更加流畅！
|
||||
157
修改完成总结.md
157
修改完成总结.md
@ -1,157 +0,0 @@
|
||||
# AI Shell 项目修改完成总结
|
||||
|
||||
## ✅ 已完成的修改
|
||||
|
||||
### 1. 模型接口更换
|
||||
- **原来**: Gemini AI (Google)
|
||||
- **现在**: DeepSeek V3 (通过 OpenAI 兼容接口)
|
||||
|
||||
### 2. API 配置更新
|
||||
```python
|
||||
# 新的配置
|
||||
API_KEY = "f8370a60-fe0a-455f-9167-411d476123d2"
|
||||
BASE_URL = "https://ark.cn-beijing.volces.com/api/v3/"
|
||||
MODEL = "deepseek-v3-250324"
|
||||
```
|
||||
|
||||
### 3. 依赖包更新
|
||||
- **移除**: `google-genai`
|
||||
- **添加**: `openai` (用于 OpenAI 兼容接口)
|
||||
|
||||
### 4. 代码修改详情
|
||||
|
||||
#### 主要变更：
|
||||
1. **导入模块**:
|
||||
```python
|
||||
# 原来
|
||||
from pydantic_ai.models.gemini import GeminiModel
|
||||
|
||||
# 现在
|
||||
from pydantic_ai.models.openai import OpenAIModel
|
||||
```
|
||||
|
||||
2. **模型初始化**:
|
||||
```python
|
||||
# 原来
|
||||
model = GeminiModel("gemini-2.0-flash")
|
||||
|
||||
# 现在
|
||||
os.environ["OPENAI_API_KEY"] = API_KEY
|
||||
os.environ["OPENAI_BASE_URL"] = BASE_URL
|
||||
model = OpenAIModel("deepseek-v3-250324")
|
||||
```
|
||||
|
||||
3. **修复弃用警告**:
|
||||
```python
|
||||
# 原来
|
||||
result_type=Answer
|
||||
resp.data
|
||||
|
||||
# 现在
|
||||
output_type=Answer
|
||||
resp.output
|
||||
```
|
||||
|
||||
## 🧪 测试结果
|
||||
|
||||
### 功能测试
|
||||
✅ **英文命令**: `"list files in current directory"` → `ls`
|
||||
✅ **中文命令**: `"创建一个新目录叫test"` → `mkdir test`
|
||||
✅ **复杂命令**: `"show disk usage"` → `df -h`
|
||||
|
||||
### 性能表现
|
||||
- ✅ 响应速度快
|
||||
- ✅ 命令准确性高
|
||||
- ✅ 支持中英文交互
|
||||
- ✅ 思考过程清晰
|
||||
|
||||
## 📁 最终项目结构
|
||||
|
||||
```
|
||||
ai-shell/
|
||||
├── ai.py # ✅ 主程序（已更新为 DeepSeek V3）
|
||||
├── pyproject.toml # ✅ 项目配置（已更新依赖）
|
||||
├── uv.toml # ✅ UV 配置（国内镜像源）
|
||||
├── uv.lock # ✅ 依赖锁定文件（已更新）
|
||||
├── .python-version # ✅ Python 版本文件
|
||||
├── .venv/ # ✅ 虚拟环境
|
||||
├── README.md # ✅ 项目说明（已更新）
|
||||
├── 配置总结.md # ✅ 配置总结
|
||||
├── 项目配置说明.md # ✅ 详细配置说明（已更新）
|
||||
└── 修改完成总结.md # ✅ 本文件
|
||||
```
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 基本命令
|
||||
```bash
|
||||
# 英文命令
|
||||
uv run python ai.py "list all Python files"
|
||||
uv run python ai.py "show current directory size"
|
||||
uv run python ai.py "find files modified today"
|
||||
|
||||
# 中文命令
|
||||
uv run python ai.py "显示当前目录下的所有文件"
|
||||
uv run python ai.py "查看磁盘使用情况"
|
||||
uv run python ai.py "创建一个名为backup的目录"
|
||||
```
|
||||
|
||||
### 交互流程
|
||||
1. **AI 思考**: 显示推理过程
|
||||
2. **AI 回答**: 提供具体命令
|
||||
3. **用户确认**: `[Y/n]` 选择是否执行
|
||||
- **Enter 键** 或 **y/yes**: 执行命令
|
||||
- **n/no**: 取消执行
|
||||
4. **自动执行**: 确认后自动运行命令
|
||||
|
||||
## 🎯 核心优势
|
||||
|
||||
### 1. 模型优势
|
||||
- **DeepSeek V3**: 最新的开源大模型，性能优异
|
||||
- **中文友好**: 对中文指令理解更准确
|
||||
- **成本效益**: 通过 Volces API 使用，性价比高
|
||||
|
||||
### 2. 技术优势
|
||||
- **OpenAI 兼容**: 标准接口，易于维护
|
||||
- **快速部署**: 国内镜像源，依赖安装快速
|
||||
- **环境隔离**: UV 虚拟环境，避免冲突
|
||||
|
||||
### 3. 用户体验
|
||||
- **双语支持**: 中英文命令都能准确理解
|
||||
- **安全确认**: 执行前需要用户确认
|
||||
- **便捷操作**: 直接按 Enter 键即可执行（默认为 Y）
|
||||
- **思考透明**: 显示 AI 的推理过程
|
||||
|
||||
## 📋 配置验证
|
||||
|
||||
### 检查配置是否正确
|
||||
```bash
|
||||
# 1. 检查依赖
|
||||
uv pip list | grep -E "(pydantic-ai|openai)"
|
||||
|
||||
# 2. 测试连接
|
||||
uv run python ai.py "echo hello"
|
||||
|
||||
# 3. 验证中文支持
|
||||
uv run python ai.py "显示当前时间"
|
||||
```
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
### 常见问题
|
||||
1. **API 连接失败**: 检查网络连接和 API 密钥
|
||||
2. **模型不响应**: 确认 BASE_URL 和模型名称正确
|
||||
3. **依赖问题**: 运行 `uv sync` 重新同步依赖
|
||||
|
||||
### 调试方法
|
||||
```bash
|
||||
# 查看详细错误信息
|
||||
uv run python ai.py "test command" 2>&1
|
||||
|
||||
# 检查环境变量
|
||||
uv run python -c "import os; print(os.environ.get('OPENAI_BASE_URL'))"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
🎉 **修改完成！** 现在您可以使用 DeepSeek V3 模型通过 Volces API 来生成 shell 命令了！
|
||||
215
升级指南.md
215
升级指南.md
@ -1,215 +0,0 @@
|
||||
# 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`
|
||||
157
配置修复总结.md
157
配置修复总结.md
@ -1,157 +0,0 @@
|
||||
# 配置修复总结
|
||||
|
||||
## 🐛 问题描述
|
||||
|
||||
每次运行 `uv sync` 时，都会在项目目录中创建一个名为 `~` 的文件夹。
|
||||
|
||||
## 🔍 问题原因
|
||||
|
||||
在 `uv.toml` 配置文件中，`cache-dir = "~/.cache/uv"` 的 `~` 符号没有被正确展开，uv 将其当作字面量处理，导致在当前目录创建了名为 `~` 的文件夹。
|
||||
|
||||
## ✅ 解决方案
|
||||
|
||||
### 1. 修复项目配置文件
|
||||
|
||||
**修改前** (`uv.toml`)：
|
||||
```toml
|
||||
# 缓存目录
|
||||
cache-dir = "~/.cache/uv"
|
||||
```
|
||||
|
||||
**修改后** (`uv.toml`)：
|
||||
```toml
|
||||
# 缓存目录（移除此配置，使用 uv 默认缓存位置）
|
||||
# cache-dir = "~/.cache/uv"
|
||||
```
|
||||
|
||||
### 2. 清理重复配置
|
||||
|
||||
**问题**：`pyproject.toml` 和 `uv.toml` 中有重复的 uv 配置，导致警告信息。
|
||||
|
||||
**解决**：删除 `pyproject.toml` 中的 `[tool.uv]` 配置段，只保留 `uv.toml` 中的配置。
|
||||
|
||||
**修改前** (`pyproject.toml`)：
|
||||
```toml
|
||||
[tool.uv]
|
||||
# 使用国内镜像源加速下载
|
||||
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"
|
||||
```
|
||||
|
||||
**修改后** (`pyproject.toml`)：
|
||||
```toml
|
||||
# UV 配置已移至 uv.toml 文件
|
||||
```
|
||||
|
||||
### 3. 完善全局配置
|
||||
|
||||
创建正确的全局 uv 配置文件 `~/.config/uv/uv.toml`：
|
||||
|
||||
```toml
|
||||
# UV 全局配置文件
|
||||
# 配置国内镜像源加速下载
|
||||
|
||||
# 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，让 uv 使用默认位置
|
||||
```
|
||||
|
||||
## 🧹 清理操作
|
||||
|
||||
1. **删除错误创建的目录**：
|
||||
```bash
|
||||
rm -rf ./~
|
||||
```
|
||||
|
||||
2. **验证修复效果**：
|
||||
```bash
|
||||
uv sync
|
||||
ls -la | grep "~" # 应该没有输出
|
||||
```
|
||||
|
||||
## 📋 最佳实践
|
||||
|
||||
### 1. uv 缓存配置
|
||||
- ✅ **推荐**：不设置 `cache-dir`，让 uv 使用默认位置
|
||||
- ❌ **避免**：使用 `~` 符号，因为可能不被正确展开
|
||||
- ✅ **替代**：如果必须自定义，使用绝对路径
|
||||
|
||||
### 2. 配置文件优先级
|
||||
- `uv.toml` > `pyproject.toml` 中的 `[tool.uv]`
|
||||
- 避免在两个文件中重复配置相同选项
|
||||
|
||||
### 3. 全局 vs 项目配置
|
||||
- **全局配置** (`~/.config/uv/uv.toml`)：适用于所有项目的通用设置
|
||||
- **项目配置** (`项目目录/uv.toml`)：特定项目的配置，会覆盖全局配置
|
||||
|
||||
## 🔧 当前配置状态
|
||||
|
||||
### 项目配置 (`uv.toml`)：
|
||||
```toml
|
||||
# uv 项目配置文件
|
||||
# 配置国内镜像源加速下载
|
||||
|
||||
# 主要的 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"
|
||||
|
||||
# 缓存目录（移除此配置，使用 uv 默认缓存位置）
|
||||
# cache-dir = "~/.cache/uv"
|
||||
|
||||
# 并发下载数
|
||||
concurrent-downloads = 10
|
||||
```
|
||||
|
||||
### 全局配置 (`~/.config/uv/uv.toml`)：
|
||||
```toml
|
||||
# UV 全局配置文件
|
||||
# 配置国内镜像源加速下载
|
||||
|
||||
# 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，让 uv 使用默认位置
|
||||
```
|
||||
|
||||
## ✅ 验证结果
|
||||
|
||||
修复后运行 `uv sync`：
|
||||
- ✅ 不再创建 `~` 目录
|
||||
- ✅ 没有重复配置警告
|
||||
- ✅ 国内镜像源正常工作
|
||||
- ✅ 依赖同步正常
|
||||
|
||||
---
|
||||
|
||||
💡 **总结**：问题已完全解决，uv 配置现在更加清晰和规范。
|
||||
117
配置总结.md
117
配置总结.md
@ -1,117 +0,0 @@
|
||||
# UV 国内源加速配置总结
|
||||
|
||||
## ✅ 配置完成状态
|
||||
|
||||
### 核心配置文件
|
||||
|
||||
- **uv.toml** - 主要配置文件 ⭐
|
||||
- 清华大学镜像（主源）+ 阿里云、腾讯云（备源）
|
||||
- 10个并发下载，智能版本选择策略
|
||||
- 已优化缓存配置
|
||||
|
||||
- **pyproject.toml** - 项目配置文件
|
||||
- Python 版本：>=3.12（当前使用 3.12.11）
|
||||
- 核心依赖：pydantic-ai, google-genai, requests
|
||||
|
||||
### 2. 配置的镜像源
|
||||
|
||||
| 镜像源 | URL | 状态 |
|
||||
|--------|-----|------|
|
||||
| 清华大学 | https://pypi.tuna.tsinghua.edu.cn/simple | 主源 ✅ |
|
||||
| 阿里云 | https://mirrors.aliyun.com/pypi/simple/ | 备用 ✅ |
|
||||
| 腾讯云 | https://mirrors.cloud.tencent.com/pypi/simple/ | 备用 ✅ |
|
||||
|
||||
### 3. 性能测试结果
|
||||
|
||||
- ✅ PyPI 包解析速度：0.02秒（极快）
|
||||
- ✅ 包安装速度：显著提升（使用国内镜像源）
|
||||
- ✅ 配置文件检测：全部通过
|
||||
- ✅ Python 版本：3.12.11（已正确配置）
|
||||
- ⚠️ Python 解释器下载：仍需要优化（建议使用系统包管理器）
|
||||
|
||||
## 🚀 使用方法
|
||||
|
||||
### 基本命令
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
uv sync
|
||||
|
||||
# 添加新包
|
||||
uv add package-name
|
||||
|
||||
# 运行脚本
|
||||
uv run python script.py
|
||||
|
||||
# 激活虚拟环境
|
||||
uv shell
|
||||
```
|
||||
|
||||
### 验证配置
|
||||
|
||||
```bash
|
||||
# 运行测试脚本
|
||||
uv run python test_uv_config.py
|
||||
```
|
||||
|
||||
## 📁 当前项目结构
|
||||
|
||||
```
|
||||
ai-shell/
|
||||
├── ai.py # 主程序（AI shell 命令生成器）
|
||||
├── pyproject.toml # 项目配置文件
|
||||
├── uv.toml # UV 配置文件（核心）
|
||||
├── uv.lock # 依赖锁定文件（自动生成）
|
||||
├── .python-version # Python 版本文件（自动生成）
|
||||
├── .venv/ # 虚拟环境（自动生成）
|
||||
├── README.md # 项目说明
|
||||
├── 配置总结.md # 本文件
|
||||
└── 项目配置说明.md # 详细配置说明
|
||||
```
|
||||
|
||||
## 🎯 配置优势
|
||||
|
||||
1. **PyPI 包速度提升**：使用国内镜像源，包下载速度显著提升
|
||||
2. **稳定性**：多个备用镜像源，确保可用性
|
||||
3. **兼容性**：支持所有 uv 功能
|
||||
4. **易维护**：配置文件清晰，易于修改
|
||||
5. **版本管理**：正确配置 Python 版本要求，避免兼容性问题
|
||||
|
||||
## 🔧 故障排除
|
||||
|
||||
如果遇到问题：
|
||||
|
||||
1. **网络问题**：检查网络连接，尝试切换镜像源
|
||||
2. **缓存问题**：运行 `uv cache clean` 清除缓存
|
||||
3. **配置冲突**：确保 uv.toml 配置正确
|
||||
|
||||
## 📝 注意事项
|
||||
|
||||
- uv.toml 文件优先级高于 pyproject.toml 中的 [tool.uv] 配置
|
||||
- 使用 unsafe-best-match 策略可能有安全风险，但提供更好的包版本选择
|
||||
- 定期更新镜像源地址以确保最佳性能
|
||||
|
||||
## 🐍 关于 Python 解释器下载
|
||||
|
||||
**重要说明**：
|
||||
- ✅ **PyPI 包下载**：已成功配置国内镜像源，速度很快
|
||||
- ⚠️ **Python 解释器下载**：镜像源配置复杂，建议使用以下替代方案：
|
||||
|
||||
### 推荐的 Python 版本管理方案：
|
||||
1. **使用系统包管理器**：`brew install python@3.12` (macOS)
|
||||
2. **使用 pyenv**：`pyenv install 3.12.0`
|
||||
3. **使用 conda**：`conda install python=3.12`
|
||||
4. **使用现有版本**：您已有 Python 3.12.11，完全可用
|
||||
|
||||
### 如果必须用 uv 下载 Python：
|
||||
- 考虑使用代理：`export HTTPS_PROXY=your_proxy`
|
||||
- 或者耐心等待：Python 解释器文件较大，首次下载需要时间
|
||||
|
||||
---
|
||||
|
||||
🎉 **配置完成！现在您可以享受快速的 Python 包管理体验了！**
|
||||
|
||||
📋 **当前状态**：
|
||||
- ✅ PyPI 包下载：极快（国内镜像源）
|
||||
- ✅ Python 版本：3.12.11（已配置）
|
||||
- ✅ 项目依赖：已同步完成
|
||||
199
配置管理说明.md
199
配置管理说明.md
@ -1,199 +0,0 @@
|
||||
# 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` 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。
|
||||
165
项目配置说明.md
165
项目配置说明.md
@ -1,165 +0,0 @@
|
||||
# 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 包的快速下载和管理，同时保持了项目的可移植性和稳定性。
|
||||
Reference in New Issue
Block a user