Go to file

zackeryyy wang afbbb1fbb0 refactor: 重构现代化命令管理为基于配置文件的安全方案

🎯 解决问题:
- 避免推荐用户系统中不存在的工具
- 防止因缺失工具导致的命令执行失败
- 提供更安全、更灵活的现代化命令管理

🔧 主要改进:
- 新增 ai_shell/modern_commands.toml 配置文件
- 智能检测系统中已安装的现代化工具
- 只推荐实际可用的工具，安全回退到原始命令
- 完整的工具描述、分类和安装提示

📦 配置文件特性:
- 28 个命令映射配置
- 20 个工具描述说明
- 8 个工具分类组织
- 6 个详细安装提示

🛠️ 新增管理工具:
- scripts/manage_modern_commands.py 配置管理脚本
- 支持验证、列表、安装建议等功能
- 完整的配置状态检查和报告

🔍 用户体验优化:
- ai --config 显示详细的工具状态
- 区分已启用、保持原样、未安装的工具
- 提供具体的安装命令和说明
- 支持环境变量和配置文件自定义

🛡️ 安全保障:
- 绝不推荐不存在的工具
- 优雅降级到原始命令
- 保持完全向后兼容性

📋 技术实现:
- 添加 tomli 依赖支持 TOML 解析
- 重构配置加载逻辑
- 智能工具检测和状态管理
- 完善的错误处理和回退机制

2025-07-12 22:44:31 +08:00

ai_shell

refactor: 重构现代化命令管理为基于配置文件的安全方案

2025-07-12 22:44:31 +08:00

scripts

refactor: 重构现代化命令管理为基于配置文件的安全方案

2025-07-12 22:44:31 +08:00

.env.example

feat: 新增现代化命令替代功能 v0.2.0

2025-07-12 22:32:09 +08:00

.gitignore

Initial commit: AI Shell v0.1.0

2025-07-12 22:06:15 +08:00

Makefile

fix: correct version extraction in Makefile status command

2025-07-12 22:11:16 +08:00

pyproject.toml

refactor: 重构现代化命令管理为基于配置文件的安全方案

2025-07-12 22:44:31 +08:00

quick_upgrade.sh

Initial commit: AI Shell v0.1.0

2025-07-12 22:06:15 +08:00

README.md

docs: 重构 README.md，整合所有说明文档

2025-07-12 22:19:03 +08:00

README重构完成总结.md

feat: 新增现代化命令替代功能 v0.2.0

2025-07-12 22:32:09 +08:00

uv.lock

refactor: 重构现代化命令管理为基于配置文件的安全方案

2025-07-12 22:44:31 +08:00

uv.toml

Initial commit: AI Shell v0.1.0

2025-07-12 22:06:15 +08:00

基于配置文件的现代化命令管理完成总结.md

refactor: 重构现代化命令管理为基于配置文件的安全方案

2025-07-12 22:44:31 +08:00

现代化命令替代功能说明.md

feat: 新增现代化命令替代功能 v0.2.0

2025-07-12 22:32:09 +08:00

README.md

AI Shell

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

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

✨ 主要特性

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

🚀 快速开始

安装

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

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

# 全局安装
uv tool install .

基本使用

# 英文示例
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

📦 安装说明

系统要求

Python 3.12+
UV 包管理器 (安装指南)

方法一：从源码安装（推荐）

# 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

方法二：快速安装

# 直接从仓库安装
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

验证安装

# 检查 ai 命令是否可用
which ai

# 测试基本功能
ai --version
ai --config
ai "echo hello world"

卸载

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 文件（推荐）

# 复制配置模板
cp .env.example .env

# 编辑配置文件
vim .env

.env 文件内容示例：

# 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

方法二：使用环境变量

# 临时设置
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

配置优先级

配置系统按以下优先级加载配置：

环境变量（最高优先级）
当前目录的 .env 文件
包目录的 .env 文件
~/.ai-shell/.env 文件
默认值（最低优先级）

查看当前配置

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

💡 使用示例

基础命令

# 文件操作
ai "列出当前目录的所有文件"
ai "显示文件详细信息"
ai "查找名称包含 config 的文件"
ai "删除所有 .tmp 文件"
ai "复制 file.txt 到 backup 目录"

# 系统信息
ai "显示磁盘使用情况"
ai "查看内存使用情况"
ai "显示当前运行的进程"
ai "查看系统负载"

# 网络操作
ai "测试网络连接到 google.com"
ai "显示网络接口信息"
ai "查看端口 8080 是否被占用"

# 文本处理
ai "在文件中搜索包含 error 的行"
ai "统计文件行数"
ai "替换文件中的文本"

英文示例

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"

高级用法

# 复杂操作
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 取消执行

配置和帮助

# 查看版本信息
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        # 发布脚本

开发环境设置

# 克隆仓库
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"

可用的开发命令

# 查看所有可用命令
make help

# 查看项目状态
make status

# 构建包
make build

# 安装到全局
make install

# 运行测试
make test

# 清理构建文件
make clean

代码修改流程

修改代码

vim ai_shell/main.py
vim ai_shell/config.py
# 等等...

测试更改

# 使用开发版本测试
uv run python -m ai_shell.main "test command"

# 或者重新安装测试
make install
ai "test command"

更新版本

# 补丁版本 (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

重新安装
```
make install
```

验证更改

ai --version
ai --config
ai "test functionality"

🔄 升级维护

快速升级

# 方法一：使用快速升级脚本
./quick_upgrade.sh

# 方法二：使用 Makefile
make upgrade

# 方法三：手动升级
uv build && uv tool install . --force

版本管理

# 升级版本号
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

自动化发布

# 发布补丁版本（自动：版本升级 + 构建 + 提交 + 推送 + 标签）
make release-patch

# 发布次版本
make release-minor

# 发布主版本
make release-major

# 或使用脚本
./scripts/release.sh patch
./scripts/release.sh minor
./scripts/release.sh major

完整的升级流程

修改代码
更新版本: make bump-patch
重新安装: make install
验证功能: ai --version && ai "test"
提交推送: make push

配置迁移

升级后配置会自动保留，如需迁移到新环境：

# 复制配置文件
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"

验证升级

# 检查版本
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 操作

# 查看状态
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 规范：

# 功能添加
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"

分支管理

# 创建功能分支
git checkout -b feature/new-command-parser

# 开发完成后合并
git checkout main
git merge feature/new-command-parser

# 删除功能分支
git branch -d feature/new-command-parser

版本发布流程

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

# 查看项目状态
make status

# 交互式提交和推送
make push

# 自动化发布（包含版本升级、构建、提交、推送、标签）
make release-patch

🔧 故障排除

常见问题

1. ai 命令不存在

# 检查 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 密钥未配置

# 检查配置
ai --config

# 设置密钥
echo 'AI_SHELL_API_KEY=your_key' >> .env

# 或使用环境变量
export AI_SHELL_API_KEY="your_key"

3. 配置文件未找到

# 创建配置文件
cp .env.example .env
vim .env

# 或创建全局配置
mkdir -p ~/.ai-shell
cp .env ~/.ai-shell/.env

4. 权限问题

# 检查文件权限
ls -la .env

# 修复权限
chmod 600 .env

5. 网络连接问题

# 测试 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 缓存问题

如果遇到 ~ 目录被创建的问题：

# 删除错误的缓存目录
rm -rf ./~

# 检查 uv.toml 配置
grep cache-dir uv.toml

# 确保没有设置错误的缓存路径

调试模式

# 查看详细错误信息
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')"

重新安装

# 完全重新安装
uv tool uninstall ai-shell
uv tool install .

# 清理并重新构建
make clean
make build
make install

🤝 贡献指南

如何贡献

Fork 仓库

# 在 Gitea 上 fork 项目
git clone https://gitea.nosuchip.de/your-username/ai-shell.git

创建功能分支

git checkout -b feature/your-feature-name

进行开发

# 修改代码
vim ai_shell/main.py

# 测试更改
make install
ai "test your changes"

提交更改

git add .
git commit -m "feat: add your feature description"

推送并创建 Pull Request

git push origin feature/your-feature-name
# 在 Gitea 上创建 Pull Request

开发规范

使用 Conventional Commits 提交信息格式
确保代码通过测试
更新相关文档
保持代码风格一致

报告问题

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 文件。

📞 支持

仓库: 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)

Method 1: From Source (Recommended)

# 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

# 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

# Check if ai command is available
which ai

# Test basic functionality
ai --version
ai --config
ai "echo hello world"

Uninstall

uv tool uninstall ai-shell

README.md Unescape Escape

AI Shell

✨ 主要特性

🚀 快速开始

安装

基本使用

📋 目录

📦 安装说明

系统要求

方法一：从源码安装（推荐）

方法二：快速安装

验证安装

卸载

⚙️ 配置管理

配置文件结构

配置项说明

配置方法

方法一：使用 .env 文件（推荐）

方法二：使用环境变量

配置优先级

查看当前配置

💡 使用示例

基础命令

英文示例

高级用法

交互式确认

配置和帮助

🛠️ 开发指南

项目结构

开发环境设置

可用的开发命令

代码修改流程

🔄 升级维护

快速升级

版本管理

自动化发布

完整的升级流程

配置迁移

验证升级

🌿 Git 工作流

仓库信息

基本 Git 操作

提交信息规范

分支管理

版本发布流程

使用 Makefile 简化操作

🔧 故障排除

常见问题

1. ai 命令不存在

2. API 密钥未配置

3. 配置文件未找到

4. 权限问题

5. 网络连接问题

6. uv 缓存问题

调试模式

重新安装

🤝 贡献指南

如何贡献

开发规范

报告问题

许可证

📞 支持

📦 Installation

Prerequisites

Method 1: From Source (Recommended)

Method 2: Quick Install

Verify Installation

Uninstall

README.md