Git Workflow - Git 工作流专家

核心理念

良好的 Git 实践 是团队协作的基础：

┌─────────────────────────────────────────────────────────┐
│  规范提交 → 清晰历史 → 易于回溯 → 高效协作              │
└─────────────────────────────────────────────────────────┘

核心原则：

• ✅ 提交历史即文档
• ✅ 原子提交，单一职责
• ✅ 清晰的可追溯性
• ✅ 易于 Code Review

---

何时使用本技能

在以下场景时激活：

• 需要 Git 提交（commit）
• 创建 Pull Request / Merge Request
• 代码分支管理
• 版本发布
• 提到"git"、"提交"、"分支"、"PR"

---

Conventional Commits 规范

提交格式

<type>(<scope>): <subject>

<body>

<footer>

Type 类型

Type	说明	示例
feat	新功能	feat(auth): add OAuth2 login
fix	Bug 修复	fix(api): resolve timeout issue
docs	文档变更	docs(readme): update installation
style	代码格式	style(lint): fix indentation
refactor	重构	refactor(utils): extract validator
perf	性能优化	perf(db): add query index
test	测试相关	test(user): add login tests
chore	构建/工具	chore(deps): upgrade to v2.0
revert	回滚提交	revert: feat(auth)

提交示例

# 简单提交
feat(auth): add JWT token validation

# 完整提交
feat(payment): integrate Stripe payment gateway

使用 Stripe API 实现信用卡支付处理。
增加用于更新支付状态的 webhook 处理。

- Add Stripe client initialization
- Implement payment intent creation
- Add webhook endpoint for status updates
- Handle payment success/failure scenarios

Closes #123
Related #456

---

提交最佳实践

1. 原子提交原则

# ❌ 不好的做法：一次提交多个变更
git commit -m "feat: add user feature and fix bugs and update docs"

# ✅ 好的做法：每个提交一个职责
git commit -m "feat(user): add registration"
git commit -m "fix(auth): resolve session timeout"
git commit -m "docs(readme): update examples"

2. 提交大小控制

类型	行数变化	建议
小型	< 100 行	✅ 理想
中型	100-400 行	⚠️ 可接受
大型	> 400 行	❌ 应拆分

3. 提交信息质量

# ❌ 不好的提交信息
git commit -m "update"
git commit -m "fix bug"
git commit -m "wip"

# ✅ 好的提交信息
git commit -m "fix(auth): resolve JWT validation error"
git commit -m "feat(api): add rate limiting middleware"
git commit -m "docs(guide): explain authentication flow"

---

分支管理策略

分支命名规范

类型	格式	示例
功能	feature/*	feature/user-auth
修复	bugfix/*	bugfix/login-timeout
热修复	hotfix/*	hotfix/security-patch
发布	release/*	release/v1.2.0
实验	experiment/*	experiment/new-ui

分支工作流

main (生产)
  ↑
  ├── release/v1.2.0 (发布准备)
  │     ↑
  │     ├── feature/user-auth (功能开发)
  │     ├── feature/payment-api (功能开发)
  │     └── bugfix/login-issue (Bug 修复)
  │
  └── hotfix/security-patch (紧急修复)

分支最佳实践

# 1. 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feature/user-auth

# 2. 开发并提交
git add .
git commit -m "feat(auth): add login endpoint"

# 3. 同步上游变更
git fetch origin main
git rebase origin/main

# 4. 推送到远程
git push origin feature/user-auth

# 5. 创建 Pull Request
# (通过 GitHub/GitLab 界面)

---

Pull Request 最佳实践

PR 标题格式

与 Conventional Commits 保持一致：

feat(auth): add OAuth2 login support

fix(api): resolve timeout issue

docs(readme): update installation guide

PR 描述模板

## 📝 变更类型
- [x] ✨ feat 新功能
- [ ] 🐛 fix Bug修复
- [ ] ♻️  refactor 重构
- [ ] 📚 docs 文档
- [ ] 💄 style 代码格式
- [ ] ⚡ perf 性能优化
- [ ] ✅ test 测试
- [ ] 🔧 chore 构建/工具

## 🎯 变更说明
<!-- 简要描述这个 PR 的目的和实现方式 -->

这个 PR 实现了用户认证功能，包括：
- JWT token 生成和验证
- 登录/登出端点
- 中间件保护路由

## 🔄 变更内容
<!-- 列出主要的文件变更 -->

- `src/auth/login.py` - 登录逻辑
- `src/auth/middleware.py` - 认证中间件
- `tests/test_auth.py` - 测试用例

## 🧪 测试
<!-- 描述测试情况 -->

- [x] 添加了单元测试
- [x] 添加了集成测试
- [x] 手动测试通过
- [ ] 性能测试通过

## ✅ 检查清单
<!-- 完成前确认 -->

- [x] 代码符合团队规范
- [x] 自我审查完成
- [x] 注释充分且准确
- [x] 文档已更新
- [x] 测试覆盖充分
- [x] 无合并冲突

## 📸 截图/演示
<!-- 如果适用，添加截图或 GIF -->

![登录界面](screenshots/login.png)

## 🔗 相关链接
- Closes #123
- Related #456
- Depends on #789

## ⚠️ 注意事项
<!-- 审查者需要注意的事项 -->

需要特别注意 JWT secret 的配置，已在 .env.example 中说明。

PR 审查响应

## 审查反馈

### 需要修改
- [ ] 安全问题：SQL 注入风险 (user_service.py:45)
- [ ] 性能问题：N+1 查询 (api.py:78)

### 建议改进
- [ ] 命名：`d()` → `double_value()` (utils.py:12)
- [ ] 注释：补充复杂逻辑说明 (payment.py:34)

### LGTM（附带建议）
- [ ] 可以合并，但建议后续优化

---

Git Hooks 自动化

提交前钩子

#!/bin/bash
# .git/hooks/pre-commit

# 运行 linter
npm run lint
if [ $? -ne 0 ]; then
    echo "❌ Lint failed, please fix before committing"
    exit 1
fi

# 运行测试
npm test
if [ $? -ne 0 ]; then
    echo "❌ Tests failed, please fix before committing"
    exit 1
fi

echo "✅ Pre-commit checks passed"

提交消息钩子

#!/bin/bash
# .git/hooks/commit-msg

# 验证提交信息格式
commit_regex='^(feat|fix|docs|style|refactor|perf|test|chore|revert)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "❌ Invalid commit message format"
    echo "✅ Expected format: <type>(<scope>): <subject>"
    exit 1
fi

echo "✅ Commit message format valid"

---

常见操作

修改最后一次提交

# 添加遗漏的文件
git add forgotten_file.py

# 修改提交信息
git commit --amend

# 修改提交内容但不改信息
git commit --amend --no-edit

撤销提交

# 撤销最后一次提交（保留变更）
git reset --soft HEAD~1

# 撤销最后一次提交（丢弃变更）
git reset --hard HEAD~1

# 撤销多次提交
git reset --soft HEAD~3

交互式变基

# 变基最近 3 个提交
git rebase -i HEAD~3

# 命令：
# pick  - 保留提交
# reword - 修改提交信息
# edit - 编辑提交
# squash - 合并到前一个提交
# drop - 删除提交

解决合并冲突

# 1. 开始变基
git rebase origin/main

# 2. 遇到冲突时
git status  # 查看冲突文件

# 3. 手动解决冲突
# 编辑冲突文件，删除 <<<<<<< ======= >>>>>>> 标记

# 4. 标记冲突已解决
git add <resolved-files>

# 5. 继续变基
git rebase --continue

# 6. 如果需要放弃
git rebase --abort

---

验证清单

提交或 PR 前，检查：

• 提交信息符合 Conventional Commits 规范
• 每个提交职责单一
• 提交大小合理（< 400 行）
• 分支命名符合规范
• 无敏感信息泄露
• 关联 Issue/PR
• 代码已通过测试
• 文档已更新

---

相关参考

• Git 工作流规范
• Conventional Commits

约束

<!-- BEGIN COMMON CONSTRAINTS --> <!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 --> <!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护；每个 SKILL.md 的 ## 约束 必须逐字同步本块，不得在副本中改写公共规则。

• 任务需要落盘时，使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录；共享材料放入 shared/，Skill 专属材料放入该 Skill 的 input/、output/、log/。
• 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
• 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
• 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
• 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
• Skill 版本唯一记录在自身 config.yaml:skill_info.version；公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
• bensz-collect-bugs 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. --> <!-- END COMMON CONSTRAINTS -->