445 lines
8.4 KiB
Markdown
445 lines
8.4 KiB
Markdown
# Git 版本管理指南
|
|
|
|
**项目**: Funstat MCP Server
|
|
**当前版本**: v1.0.0
|
|
**最后更新**: 2025-10-26
|
|
|
|
---
|
|
|
|
## 📋 仓库信息
|
|
|
|
```bash
|
|
项目路径: /Users/lucas/chat--1003255561049
|
|
Git状态: ✅ 已初始化
|
|
分支: main
|
|
提交数: 1
|
|
标签: v1.0.0
|
|
```
|
|
|
|
---
|
|
|
|
## 🏷️ 版本标签
|
|
|
|
### v1.0.0 - 首次发布 (2025-10-26)
|
|
|
|
**核心功能**:
|
|
- ✅ 自动翻页搜索 (数据获取+285%)
|
|
- ✅ SSE传输模式
|
|
- ✅ 8个MCP工具
|
|
- ✅ 完整文档
|
|
|
|
**性能指标**:
|
|
- 翻页速度: 6秒/页
|
|
- 数据量: 890条记录
|
|
- 自动化率: 100%
|
|
|
|
**提交信息**:
|
|
```
|
|
feat: 初始提交 - Funstat MCP 服务器 v1.0.0
|
|
|
|
53 files changed, 11235 insertions(+)
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 文件结构
|
|
|
|
### 已跟踪的重要文件
|
|
|
|
```
|
|
✅ .gitignore # Git忽略规则
|
|
✅ README.md # 项目说明文档
|
|
✅ claude-code-mcp-config.json # MCP配置
|
|
|
|
✅ funstat_mcp/
|
|
✅ server.py # MCP服务器(SSE)
|
|
✅ search_with_pagination.py # 翻页搜索
|
|
✅ search_all_translation.py # 多关键词搜索
|
|
✅ test_pagination.py # 翻页测试
|
|
✅ requirements.txt # Python依赖
|
|
✅ start_sse.sh # SSE启动脚本
|
|
|
|
✅ 文档/
|
|
✅ PAGINATION_SUCCESS_REPORT.md # 翻页功能报告
|
|
✅ SSE_CONVERSION_COMPLETE.md # SSE转换文档
|
|
✅ AGENTAPI_PROXY_SETUP.md # AgentAPI配置
|
|
✅ FUNSTAT_MCP_DEPLOYMENT_REPORT.md # 部署报告
|
|
```
|
|
|
|
### 被忽略的文件
|
|
|
|
```
|
|
❌ *.session # Telegram会话文件
|
|
❌ *.session-journal # 会话日志
|
|
❌ *.txt # 数据文本文件
|
|
❌ *.json (除配置文件外) # 数据JSON文件
|
|
❌ __pycache__/ # Python缓存
|
|
❌ *.log # 日志文件
|
|
❌ .DS_Store # macOS系统文件
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 常用Git命令
|
|
|
|
### 查看状态
|
|
|
|
```bash
|
|
# 查看工作区状态
|
|
git status
|
|
|
|
# 查看提交历史
|
|
git log --oneline
|
|
|
|
# 查看详细提交历史
|
|
git log --graph --decorate --all
|
|
|
|
# 查看所有标签
|
|
git tag -l -n9
|
|
```
|
|
|
|
### 创建提交
|
|
|
|
```bash
|
|
# 添加所有更改
|
|
git add .
|
|
|
|
# 添加特定文件
|
|
git add funstat_mcp/server.py
|
|
|
|
# 提交更改
|
|
git commit -m "feat: 添加新功能"
|
|
|
|
# 使用多行提交信息
|
|
git commit -m "$(cat <<'EOF'
|
|
feat: 功能标题
|
|
|
|
详细说明...
|
|
|
|
🤖 Generated with Claude Code
|
|
Co-Authored-By: Claude <noreply@anthropic.com>
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
### 版本标签
|
|
|
|
```bash
|
|
# 创建带注释的标签
|
|
git tag -a v1.1.0 -m "版本 1.1.0 说明"
|
|
|
|
# 查看标签
|
|
git tag -l
|
|
|
|
# 查看标签详情
|
|
git show v1.0.0
|
|
|
|
# 删除标签
|
|
git tag -d v1.0.0
|
|
```
|
|
|
|
### 分支管理
|
|
|
|
```bash
|
|
# 创建分支
|
|
git branch feature/new-feature
|
|
|
|
# 切换分支
|
|
git checkout feature/new-feature
|
|
|
|
# 创建并切换
|
|
git checkout -b feature/new-feature
|
|
|
|
# 合并分支
|
|
git checkout main
|
|
git merge feature/new-feature
|
|
|
|
# 删除分支
|
|
git branch -d feature/new-feature
|
|
```
|
|
|
|
### 撤销操作
|
|
|
|
```bash
|
|
# 撤销工作区更改
|
|
git checkout -- file.py
|
|
|
|
# 撤销暂存
|
|
git reset HEAD file.py
|
|
|
|
# 修改最后一次提交
|
|
git commit --amend
|
|
|
|
# 回退到上一个提交
|
|
git reset --soft HEAD^
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 提交规范
|
|
|
|
### Commit Message 格式
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
### Type 类型
|
|
|
|
| 类型 | 说明 | 示例 |
|
|
|------|------|------|
|
|
| `feat` | 新功能 | feat: 添加自动翻页功能 |
|
|
| `fix` | Bug修复 | fix: 修复session锁定问题 |
|
|
| `docs` | 文档更新 | docs: 更新README |
|
|
| `style` | 代码格式 | style: 格式化代码 |
|
|
| `refactor` | 重构 | refactor: 优化搜索逻辑 |
|
|
| `perf` | 性能优化 | perf: 提升翻页速度 |
|
|
| `test` | 测试 | test: 添加翻页测试 |
|
|
| `chore` | 构建/工具 | chore: 更新依赖 |
|
|
|
|
### 示例
|
|
|
|
```bash
|
|
# 功能添加
|
|
git commit -m "feat: 添加多关键词搜索功能
|
|
|
|
- 支持批量搜索多个关键词
|
|
- 自动去重
|
|
- 导出JSON/TXT格式
|
|
|
|
🤖 Generated with Claude Code
|
|
Co-Authored-By: Claude <noreply@anthropic.com>"
|
|
|
|
# Bug修复
|
|
git commit -m "fix: 修复数据库锁定问题
|
|
|
|
确保同一时间只有一个进程访问session文件
|
|
|
|
Fixes #123"
|
|
|
|
# 文档更新
|
|
git commit -m "docs: 完善翻页功能文档
|
|
|
|
添加使用示例和性能指标"
|
|
```
|
|
|
|
---
|
|
|
|
## 🌿 分支策略
|
|
|
|
### 主要分支
|
|
|
|
- **main** - 稳定版本,用于发布
|
|
- **develop** - 开发分支,用于日常开发
|
|
|
|
### 功能分支
|
|
|
|
```bash
|
|
# 命名规范: feature/<功能名>
|
|
git checkout -b feature/pagination
|
|
git checkout -b feature/export-excel
|
|
git checkout -b feature/web-ui
|
|
```
|
|
|
|
### 修复分支
|
|
|
|
```bash
|
|
# 命名规范: fix/<问题描述>
|
|
git checkout -b fix/session-lock
|
|
git checkout -b fix/button-click
|
|
```
|
|
|
|
### 发布分支
|
|
|
|
```bash
|
|
# 命名规范: release/v<版本号>
|
|
git checkout -b release/v1.1.0
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 版本号规范
|
|
|
|
采用 **语义化版本** (Semantic Versioning):
|
|
|
|
```
|
|
v<major>.<minor>.<patch>
|
|
```
|
|
|
|
### 说明
|
|
|
|
- **major** - 主版本号,不兼容的API更改
|
|
- **minor** - 次版本号,向后兼容的功能新增
|
|
- **patch** - 修订号,向后兼容的问题修正
|
|
|
|
### 示例
|
|
|
|
```
|
|
v1.0.0 → v1.0.1 (Bug修复)
|
|
v1.0.1 → v1.1.0 (新功能)
|
|
v1.1.0 → v2.0.0 (重大更改)
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 开发工作流
|
|
|
|
### 1. 功能开发
|
|
|
|
```bash
|
|
# 1. 创建功能分支
|
|
git checkout -b feature/new-search-mode
|
|
|
|
# 2. 开发并提交
|
|
git add .
|
|
git commit -m "feat: 添加新搜索模式"
|
|
|
|
# 3. 测试通过后合并
|
|
git checkout main
|
|
git merge feature/new-search-mode
|
|
|
|
# 4. 打标签发布
|
|
git tag -a v1.1.0 -m "新增搜索模式"
|
|
```
|
|
|
|
### 2. Bug修复
|
|
|
|
```bash
|
|
# 1. 创建修复分支
|
|
git checkout -b fix/urgent-bug
|
|
|
|
# 2. 修复并提交
|
|
git add .
|
|
git commit -m "fix: 修复紧急bug"
|
|
|
|
# 3. 合并到主分支
|
|
git checkout main
|
|
git merge fix/urgent-bug
|
|
|
|
# 4. 打补丁版本
|
|
git tag -a v1.0.1 -m "修复bug"
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 项目统计
|
|
|
|
### 当前统计
|
|
|
|
```bash
|
|
# 查看代码统计
|
|
git ls-files | wc -l # 文件数: 53
|
|
git log --oneline | wc -l # 提交数: 1
|
|
git tag | wc -l # 标签数: 1
|
|
|
|
# 查看代码行数
|
|
git ls-files | xargs wc -l # 总行数: 11235
|
|
```
|
|
|
|
### 贡献者
|
|
|
|
```bash
|
|
# 查看贡献者列表
|
|
git shortlog -sn
|
|
|
|
# 当前贡献者:
|
|
# Lucas & Claude Code
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 最佳实践
|
|
|
|
### ✅ DO - 应该做的
|
|
|
|
1. **频繁提交** - 小步快跑,每个功能点提交一次
|
|
2. **清晰的消息** - 使用规范的commit message
|
|
3. **功能分支** - 每个功能使用独立分支
|
|
4. **测试后合并** - 确保测试通过后再合并
|
|
5. **打标签** - 每次发布都打版本标签
|
|
6. **写文档** - 重要更改更新文档
|
|
|
|
### ❌ DON'T - 不应该做的
|
|
|
|
1. ❌ 不要提交敏感信息(密钥、session文件)
|
|
2. ❌ 不要提交大文件(数据文件、日志)
|
|
3. ❌ 不要直接在main分支开发
|
|
4. ❌ 不要使用无意义的commit message
|
|
5. ❌ 不要强制推送到main分支
|
|
6. ❌ 不要忘记更新.gitignore
|
|
|
|
---
|
|
|
|
## 🔒 安全提醒
|
|
|
|
### 敏感文件保护
|
|
|
|
```bash
|
|
# 检查是否意外提交了敏感文件
|
|
git ls-files | grep -E "\.session|\.env|config_local"
|
|
|
|
# 如果意外提交,从历史中移除
|
|
git filter-branch --force --index-filter \
|
|
"git rm --cached --ignore-unmatch *.session" \
|
|
--prune-empty --tag-name-filter cat -- --all
|
|
```
|
|
|
|
### .gitignore 检查
|
|
|
|
```bash
|
|
# 确认关键文件被忽略
|
|
cat .gitignore | grep -E "session|\.env|config_local"
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 参考资源
|
|
|
|
### Git 学习资源
|
|
|
|
- [Git官方文档](https://git-scm.com/doc)
|
|
- [语义化版本](https://semver.org/lang/zh-CN/)
|
|
- [Conventional Commits](https://www.conventionalcommits.org/)
|
|
|
|
### 项目相关文档
|
|
|
|
- [README.md](README.md) - 项目说明
|
|
- [PAGINATION_SUCCESS_REPORT.md](PAGINATION_SUCCESS_REPORT.md) - 翻页功能
|
|
- [SSE_CONVERSION_COMPLETE.md](SSE_CONVERSION_COMPLETE.md) - SSE转换
|
|
|
|
---
|
|
|
|
## 🎯 快速命令参考
|
|
|
|
```bash
|
|
# 状态查看
|
|
git status # 工作区状态
|
|
git log --oneline # 提交历史
|
|
git tag -l # 标签列表
|
|
|
|
# 提交流程
|
|
git add . # 暂存所有更改
|
|
git commit -m "message" # 提交
|
|
git tag -a v1.0.0 -m "msg" # 打标签
|
|
|
|
# 分支操作
|
|
git branch # 查看分支
|
|
git checkout -b feature/xxx # 创建并切换分支
|
|
git merge feature/xxx # 合并分支
|
|
|
|
# 查看差异
|
|
git diff # 工作区 vs 暂存区
|
|
git diff --staged # 暂存区 vs 仓库
|
|
git diff HEAD # 工作区 vs 仓库
|
|
```
|
|
|
|
---
|
|
|
|
**最后更新**: 2025-10-26
|
|
**Git版本**: 2.x
|
|
**状态**: ✅ 版本管理已配置
|