docs: 重构 README.md，整合所有说明文档
- 将分散的说明文件整合到 README.md 中 - 使用中文编写完整的项目文档 - 包含安装、配置、使用、开发、升级、Git 工作流等所有内容 - 删除重复的单独文档文件 - 提供完整的故障排除和贡献指南 - 统一文档结构，提升用户体验
This commit is contained in:
831
README.md
831
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"
|
||||
```
|
||||
|
||||
### 可用的开发命令
|
||||
|
||||
```bash
|
||||
# 查看所有可用命令
|
||||
make help
|
||||
|
||||
# 查看项目状态
|
||||
make status
|
||||
|
||||
# 构建包
|
||||
make build
|
||||
|
||||
# 安装到全局
|
||||
make install
|
||||
|
||||
# 运行测试
|
||||
make test
|
||||
|
||||
# 清理构建文件
|
||||
make clean
|
||||
```
|
||||
|
||||
### 代码修改流程
|
||||
|
||||
1. **修改代码**
|
||||
```bash
|
||||
uv sync
|
||||
vim ai_shell/main.py
|
||||
vim ai_shell/config.py
|
||||
# 等等...
|
||||
```
|
||||
|
||||
2. Run the tool:
|
||||
2. **测试更改**
|
||||
```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"
|
||||
# 使用开发版本测试
|
||||
uv run python -m ai_shell.main "test command"
|
||||
|
||||
# 或者重新安装测试
|
||||
make install
|
||||
ai "test command"
|
||||
```
|
||||
|
||||
## Configuration
|
||||
3. **更新版本**
|
||||
```bash
|
||||
# 补丁版本 (0.1.0 -> 0.1.1)
|
||||
make bump-patch
|
||||
|
||||
- **Model**: DeepSeek V3 (deepseek-v3-250324)
|
||||
- **API**: Volces (ByteDance) OpenAI-compatible interface
|
||||
- **Base URL**: https://ark.cn-beijing.volces.com/api/v3/
|
||||
# 次版本 (0.1.0 -> 0.2.0)
|
||||
make bump-minor
|
||||
|
||||
## Requirements
|
||||
# 主版本 (0.1.0 -> 1.0.0)
|
||||
make bump-major
|
||||
```
|
||||
|
||||
- Python 3.12+
|
||||
- UV package manager with configured Chinese mirrors for fast downloads
|
||||
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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user