From 51cc93d408f14226c2628df4efd63cf04c7541f7 Mon Sep 17 00:00:00 2001 From: zackeryyy wang Date: Sat, 12 Jul 2025 22:19:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=20README.md=EF=BC=8C?= =?UTF-8?q?=E6=95=B4=E5=90=88=E6=89=80=E6=9C=89=E8=AF=B4=E6=98=8E=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将分散的说明文件整合到 README.md 中 - 使用中文编写完整的项目文档 - 包含安装、配置、使用、开发、升级、Git 工作流等所有内容 - 删除重复的单独文档文件 - 提供完整的故障排除和贡献指南 - 统一文档结构，提升用户体验 --- Git工作流程.md | 246 -------------- README.md | 831 ++++++++++++++++++++++++++++++++++++++++++++++-- 使用示例.md | 119 ------- 修改完成总结.md | 157 --------- 升级指南.md | 215 ------------- 配置修复总结.md | 157 --------- 配置总结.md | 117 ------- 配置管理说明.md | 199 ------------ 项目配置说明.md | 165 ---------- 9 files changed, 808 insertions(+), 1398 deletions(-) delete mode 100644 Git工作流程.md delete mode 100644 使用示例.md delete mode 100644 修改完成总结.md delete mode 100644 升级指南.md delete mode 100644 配置修复总结.md delete mode 100644 配置总结.md delete mode 100644 配置管理说明.md delete mode 100644 项目配置说明.md diff --git a/Git工作流程.md b/Git工作流程.md deleted file mode 100644 index d4ed4ce..0000000 --- a/Git工作流程.md +++ /dev/null @@ -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 - -现在您可以在浏览器中访问仓库，查看代码和文档！ diff --git a/README.md b/README.md index 3b35aee..9f5e170 100644 --- a/README.md +++ b/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://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) -## 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 +``` diff --git a/使用示例.md b/使用示例.md deleted file mode 100644 index a0b105d..0000000 --- a/使用示例.md +++ /dev/null @@ -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 键就能执行命令，让您的工作流程更加流畅！ diff --git a/修改完成总结.md b/修改完成总结.md deleted file mode 100644 index 96a5e13..0000000 --- a/修改完成总结.md +++ /dev/null @@ -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 命令了！ diff --git a/升级指南.md b/升级指南.md deleted file mode 100644 index a60b861..0000000 --- a/升级指南.md +++ /dev/null @@ -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` diff --git a/配置修复总结.md b/配置修复总结.md deleted file mode 100644 index 426a631..0000000 --- a/配置修复总结.md +++ /dev/null @@ -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 配置现在更加清晰和规范。 diff --git a/配置总结.md b/配置总结.md deleted file mode 100644 index e9d4b3f..0000000 --- a/配置总结.md +++ /dev/null @@ -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（已配置） -- ✅ 项目依赖：已同步完成 diff --git a/配置管理说明.md b/配置管理说明.md deleted file mode 100644 index 0e60421..0000000 --- a/配置管理说明.md +++ /dev/null @@ -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` 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。 diff --git a/项目配置说明.md b/项目配置说明.md deleted file mode 100644 index 033e279..0000000 --- a/项目配置说明.md +++ /dev/null @@ -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 包的快速下载和管理，同时保持了项目的可移植性和稳定性。