From 0f5f740e962c89456bffdaadeaaef5b9712c6c93 Mon Sep 17 00:00:00 2001
From: zackeryyy wang <zackeryyy@outlook.com>
Date: Sat, 12 Jul 2025 22:10:18 +0800
Subject: [PATCH] feat: add Git workflow and release automation

- Add comprehensive Git workflow documentation
- Create automated release script (scripts/release.sh)
- Enhance Makefile with Git operations and release commands
- Add version tagging and remote push automation
- Include project status checking and validation
- Support for patch/minor/major release workflows
---
 Git工作流程.md     | 246 +++++++++++++++++++++++++++++++++++++++++++++
 Makefile           |  52 +++++++++-
 scripts/release.sh |  94 +++++++++++++++++
 3 files changed, 391 insertions(+), 1 deletion(-)
 create mode 100644 Git工作流程.md
 create mode 100755 scripts/release.sh

diff --git a/Git工作流程.md b/Git工作流程.md
new file mode 100644
index 0000000..d4ed4ce
--- /dev/null
+++ b/Git工作流程.md
@@ -0,0 +1,246 @@
+# 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/Makefile b/Makefile
index 51dfa60..faa8f78 100644
--- a/Makefile
+++ b/Makefile
@@ -1,17 +1,29 @@
-.PHONY: help install upgrade uninstall build clean test bump-patch bump-minor bump-major
+.PHONY: help install upgrade uninstall build clean test bump-patch bump-minor bump-major release-patch release-minor release-major status push
 
 help:
 	@echo "AI Shell Development Commands:"
 	@echo ""
+	@echo "📦 Package Management:"
 	@echo "  install      - Install AI Shell globally using uv tool"
 	@echo "  upgrade      - Upgrade existing AI Shell installation"
 	@echo "  uninstall    - Uninstall AI Shell"
 	@echo "  build        - Build the package"
 	@echo "  clean        - Clean build artifacts"
 	@echo "  test         - Test the installation"
+	@echo ""
+	@echo "🔢 Version Management:"
 	@echo "  bump-patch   - Bump patch version (0.1.0 -> 0.1.1)"
 	@echo "  bump-minor   - Bump minor version (0.1.0 -> 0.2.0)"
 	@echo "  bump-major   - Bump major version (0.1.0 -> 1.0.0)"
+	@echo ""
+	@echo "🚀 Release Management:"
+	@echo "  release-patch - Release patch version (bump + build + commit + push)"
+	@echo "  release-minor - Release minor version (bump + build + commit + push)"
+	@echo "  release-major - Release major version (bump + build + commit + push)"
+	@echo ""
+	@echo "📋 Git Operations:"
+	@echo "  status       - Show git status and project info"
+	@echo "  push         - Push current changes to remote"
 
 install:
 	@echo "🚀 Installing AI Shell..."
@@ -62,3 +74,41 @@ bump-major:
 	@echo "📈 Bumping major version..."
 	@python scripts/bump_version.py major
 	@echo "✅ Version bumped"
+
+release-patch:
+	@echo "🚀 Releasing patch version..."
+	@./scripts/release.sh patch
+
+release-minor:
+	@echo "🚀 Releasing minor version..."
+	@./scripts/release.sh minor
+
+release-major:
+	@echo "🚀 Releasing major version..."
+	@./scripts/release.sh major
+
+status:
+	@echo "📋 AI Shell Project Status:"
+	@echo ""
+	@echo "📁 Project Info:"
+	@echo "  Directory: $(PWD)"
+	@echo "  Version: $(shell grep '__version__' ai_shell/__init__.py | cut -d'\"' -f2)"
+	@echo ""
+	@echo "🔧 Git Status:"
+	@git status --short || echo "  Not a git repository"
+	@echo ""
+	@echo "📦 Package Status:"
+	@echo "  Built: $(shell [ -f dist/*.whl ] && echo 'Yes' || echo 'No')"
+	@echo "  Installed: $(shell uv tool list | grep -q ai-shell && echo 'Yes' || echo 'No')"
+	@echo ""
+	@echo "🌐 Remote Repository:"
+	@git remote get-url origin 2>/dev/null | sed 's/:[^@]*@/:***@/' || echo "  No remote configured"
+
+push:
+	@echo "🚀 Pushing to remote repository..."
+	@git add .
+	@git status --short
+	@read -p "Continue with commit and push? [y/N]: " confirm && [ "$$confirm" = "y" ] || exit 1
+	@read -p "Enter commit message: " message && git commit -m "$$message"
+	@git push
+	@echo "✅ Push completed!"
diff --git a/scripts/release.sh b/scripts/release.sh
new file mode 100755
index 0000000..5c88282
--- /dev/null
+++ b/scripts/release.sh
@@ -0,0 +1,94 @@
+#!/bin/bash
+# AI Shell 自动发布脚本
+
+set -e
+
+VERSION_TYPE=${1:-patch}
+
+echo "🚀 AI Shell 自动发布流程开始..."
+echo "版本类型: $VERSION_TYPE"
+
+# 检查是否在项目根目录
+if [ ! -f "pyproject.toml" ]; then
+    echo "❌ 请在 ai-shell 项目根目录中运行此脚本"
+    exit 1
+fi
+
+# 检查工作区是否干净
+if [ -n "$(git status --porcelain)" ]; then
+    echo "❌ 工作区有未提交的更改，请先提交或暂存"
+    git status --short
+    exit 1
+fi
+
+# 获取当前版本
+CURRENT_VERSION=$(grep '__version__' ai_shell/__init__.py | cut -d'"' -f2)
+echo "当前版本: $CURRENT_VERSION"
+
+# 升级版本
+echo "📈 升级版本..."
+python scripts/bump_version.py $VERSION_TYPE
+
+# 获取新版本
+NEW_VERSION=$(grep '__version__' ai_shell/__init__.py | cut -d'"' -f2)
+echo "新版本: $NEW_VERSION"
+
+# 重新构建
+echo "📦 重新构建..."
+uv build
+
+# 重新安装
+echo "🔧 重新安装..."
+uv tool install . --force
+
+# 验证安装
+echo "🧪 验证安装..."
+if command -v ai &> /dev/null; then
+    INSTALLED_VERSION=$(ai --version 2>/dev/null | grep -o 'v[0-9]\+\.[0-9]\+\.[0-9]\+' | sed 's/v//' || echo "unknown")
+    if [ "$INSTALLED_VERSION" = "$NEW_VERSION" ]; then
+        echo "✅ 安装验证成功: $INSTALLED_VERSION"
+    else
+        echo "⚠️ 版本不匹配: 期望 $NEW_VERSION, 实际 $INSTALLED_VERSION"
+    fi
+else
+    echo "⚠️ ai 命令未找到，可能需要重新加载 shell"
+fi
+
+# 提交更改
+echo "📝 提交更改..."
+git add .
+git commit -m "bump: version to v$NEW_VERSION
+
+- Update version from $CURRENT_VERSION to $NEW_VERSION
+- Rebuild package and update dependencies
+- Ready for release"
+
+# 创建标签
+echo "🏷️ 创建版本标签..."
+git tag -a "v$NEW_VERSION" -m "Release version $NEW_VERSION
+
+Changes in this release:
+- Version bump from $CURRENT_VERSION to $NEW_VERSION
+- Package rebuild and dependency updates"
+
+# 推送到远程
+echo "🚀 推送到远程仓库..."
+git push
+git push --tags
+
+echo ""
+echo "✅ 发布完成！"
+echo ""
+echo "📋 发布信息:"
+echo "  版本: v$NEW_VERSION"
+echo "  标签: v$NEW_VERSION"
+echo "  仓库: https://gitea.nosuchip.de/zack/ai-shell"
+echo ""
+echo "🔗 查看发布:"
+echo "  代码: https://gitea.nosuchip.de/zack/ai-shell/src/tag/v$NEW_VERSION"
+echo "  标签: https://gitea.nosuchip.de/zack/ai-shell/releases/tag/v$NEW_VERSION"
+echo ""
+echo "🧪 测试新版本:"
+echo "  ai --version"
+echo "  ai --config"
+echo "  ai \"echo test\""