assist/推送脚本使用说明.md

# TSP智能助手 - 推送脚本使用说明

## 📁 脚本文件说明

### 1. `auto_push.bat` - 智能自动推送脚本
**功能**: 完整的Git推送流程，包含状态检查、确认、提交和推送
**特点**: 
- 显示详细的Git状态
- **智能分析markdown文件修改**
- **自动生成语义化提交信息**
- 用户确认机制（支持编辑提交信息）
- 错误处理和状态反馈

**智能提交信息生成**:
- `fix:` - 修复问题（检测到"修复"、"解决"、"问题"、"错误"）
- `feat:` - 新增功能（检测到"功能"、"新增"、"添加"、"实现"）
- `perf:` - 性能优化（检测到"优化"、"性能"、"改进"、"提升"）
- `docs:` - 文档更新（默认类型）

**使用方法**:
```bash
# 直接运行（智能生成提交信息）
auto_push.bat

# 交互选项：
# y - 使用生成的提交信息
# n - 手动输入提交信息  
# e - 编辑生成的提交信息
```

### 2. `auto_push.ps1` - PowerShell高级版本
**功能**: 功能最全面的推送脚本，支持参数和高级功能
**特点**:
- 彩色输出和美观的界面
- 支持命令行参数
- 智能提交信息生成
- 详细的统计信息
- 错误处理和回滚

**使用方法**:
```powershell
# 基本使用
.\auto_push.ps1

# 指定提交信息
.\auto_push.ps1 "feat: 添加新功能"

# 强制推送（跳过确认）
.\auto_push.ps1 -NoConfirm

# 强制推送并指定信息
.\auto_push.ps1 "紧急修复" -Force -NoConfirm
```

### 3. `quick_push.bat` - 智能快速推送脚本
**功能**: 最简单的推送方式，适合日常快速提交
**特点**:
- 一键推送
- **智能分析markdown文件并生成提交信息**
- **自动识别提交类型**
- 最小化交互
- 支持自定义提交信息

**使用方法**:
```bash
# 智能生成提交信息（推荐）
quick_push.bat

# 指定自定义提交信息
quick_push.bat "修复bug"
```

## 🧠 智能功能详解

### 自动内容分析
脚本会自动检测修改的markdown文件，并提取以下信息：
- **文档标题**：提取 `# 标题` 格式的内容
- **问题描述**：识别包含"问题"、"错误"等关键词的内容
- **解决方案**：识别包含"解决"、"修复"等关键词的内容
- **功能描述**：识别包含"功能"、"新增"等关键词的内容

### 提交类型识别
根据markdown文件内容，自动识别提交类型：

| 关键词 | 提交类型 | 示例 |
|--------|----------|------|
| 修复、解决、问题、错误 | `fix:` | `fix: 飞书权限问题修复` |
| 功能、新增、添加、实现 | `feat:` | `feat: 新增AI建议功能` |
| 优化、性能、改进、提升 | `perf:` | `perf: 优化图表渲染性能` |
| 其他 | `docs:` | `docs: 更新文档记录` |

### 示例工作流
```markdown
# 飞书权限问题修复

## 问题描述
AI建议无法写入飞书表格，出现403权限错误。

## 解决方案
1. 检查飞书应用权限配置
2. 添加必要的读写权限
```

**生成的提交信息**: `fix: 飞书权限问题修复`

## 🚀 推荐使用场景

### 日常开发
```bash
# 快速提交日常更改
quick_push.bat "日常更新"
```

### 功能开发
```bash
# 使用PowerShell版本，获得最佳体验
.\auto_push.ps1 "feat: 添加用户管理功能"
```

### 紧急修复
```bash
# 快速修复
quick_push.bat "hotfix: 修复登录问题"
```

### 团队协作
```bash
# 使用标准版本，确保流程规范
auto_push.bat
```

## ⚙️ 脚本特性对比

| 特性 | quick_push.bat | auto_push.bat | auto_push.ps1 |
|------|----------------|---------------|---------------|
| 执行速度 | ⚡ 最快 | 🐌 中等 | 🐌 中等 |
| 用户交互 | 最少 | 中等 | 最多 |
| 错误处理 | 基础 | 完整 | 完整 |
| 状态显示 | 基础 | 详细 | 最详细 |
| 参数支持 | 基础 | 无 | 完整 |
| 彩色输出 | 无 | 无 | ✅ |
| 统计信息 | 无 | 基础 | 详细 |
| **智能提交信息** | ✅ | ✅ | ❌ |
| **Markdown分析** | ✅ | ✅ | ❌ |
| **提交类型识别** | ✅ | ✅ | ❌ |

## 🔧 自定义配置

### 修改默认提交信息格式
编辑 `auto_push.bat` 第25行：
```batch
set commit_msg=feat: 自动提交 - %date% %time%
```

### 修改远程分支
编辑所有脚本中的 `origin main` 为你的分支：
```batch
git push origin your-branch
```

### 添加预提交检查
在 `auto_push.ps1` 中添加检查函数：
```powershell
function Test-PreCommit {
    # 运行测试
    python -m pytest
    # 代码格式化检查
    python -m black --check .
    # 类型检查
    python -m mypy .
}
```

## 🛠️ 故障排除

### 常见问题

1. **"nothing to commit, working tree clean" 错误**
   ```
   原因: 工作区没有未提交的更改
   解决: 脚本已自动检测并跳过推送，这是正常行为
   ```

2. **推送失败 (Push failed)**
   ```
   可能原因:
   - 网络连接问题
   - 远程仓库权限不足
   - 分支冲突
   - 需要先拉取远程更改
   
   解决方案:
   1. 检查网络连接
   2. 运行: git pull origin main
   3. 重新运行推送脚本
   ```

3. **PowerShell执行策略错误**
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   ```

4. **Git认证失败**
   ```bash
   # 检查远程仓库配置
   git remote -v
   
   # 重新设置认证
   git config --global credential.helper store
   ```

5. **编码问题**
   ```bash
   # 确保控制台支持UTF-8
   chcp 65001
   ```

6. **重复使用脚本报错**
   ```
   原因: 工作区已干净，无需再次推送
   解决: 脚本已优化，会自动检测并跳过
   ```

### 错误代码说明

- `退出代码 0`: 成功
- `退出代码 1`: Git操作失败
- `退出代码 2`: 用户取消操作

## 📝 最佳实践

1. **提交前检查**: 使用 `auto_push.ps1` 查看详细状态
2. **提交信息规范**: 使用 `feat:`, `fix:`, `docs:` 等前缀
3. **定期推送**: 避免长时间不推送导致冲突
4. **分支管理**: 在功能分支开发，合并到主分支

## 🎯 示例工作流

```bash
# 1. 开发功能
# ... 编写代码 ...

# 2. 快速推送
quick_push.bat "feat: 添加AI建议功能"

# 3. 或者详细推送
.\auto_push.ps1 "feat: 添加AI建议功能
- 实现语义相似度计算
- 优化前端UI显示
- 添加配置化阈值"
```

---

**提示**: 建议将脚本文件添加到项目根目录，并设置适当的执行权限。对于团队使用，建议统一使用 `auto_push.ps1` 以确保流程一致性。