ai-shell/README.md

# AI Shell

🤖 **基于 DeepSeek V3 的 AI 智能 Shell 命令生成器**

将自然语言描述转换为可执行的 shell 命令，支持中英文输入，带有交互式执行确认功能。

[![版本](https://img.shields.io/badge/版本-0.1.0-blue.svg)](https://gitea.nosuchip.de/zack/ai-shell/releases)
[![Python](https://img.shields.io/badge/python-3.12+-green.svg)](https://python.org)
[![许可证](https://img.shields.io/badge/许可证-MIT-blue.svg)](LICENSE)

## ✨ 主要特性

- 🧠 **AI 驱动**: 使用 DeepSeek V3 进行智能命令生成
- 🌐 **双语支持**: 支持中文和英文描述
- 🛡️ **安全执行**: 执行前交互式确认
- ⚙️ **灵活配置**: 支持环境变量和 .env 文件配置
- 📦 **简易安装**: 通过 `uv tool install` 全局安装
- 🔄 **自动升级**: 内置版本管理和升级工具
- 🚀 **快速设置**: 预配置国内镜像源，下载更快

## 🚀 快速开始

### 安装

```bash
# 克隆仓库
git clone https://gitea.nosuchip.de/zack/ai-shell.git
cd ai-shell

# 配置 API 设置
cp .env.example .env
vim .env  # 填入您的 API 配置

# 全局安装
uv tool install .
```

### 基本使用

```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
   vim ai_shell/main.py
   vim ai_shell/config.py
   # 等等...
   ```

2. **测试更改**
   ```bash
   # 使用开发版本测试
   uv run python -m ai_shell.main "test command"

   # 或者重新安装测试
   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
```