Git 和 GitHub 操作 (Flutter 项目)

提供 Flutter 项目的 Git 版本控制和 GitHub 仓库管理的完整工作流。

🤖 使用子代理执行（强烈推荐）

为避免消耗主窗口上下文，所有 Git 操作应通过子代理执行

为什么使用子代理

Git 操作（尤其是提交、PR 创建）需要：

• 读取 git status、git diff、git log 输出（大量 token）
• 分析变更内容、编写提交信息（上下文推理）
• 处理完后这些中间信息不再需要保留

使用子代理的好处：

• ✅ 节省主窗口 50-80% 的上下文消耗
• ✅ 保持主对话历史简洁
• ✅ Git 操作结果简洁返回，不污染主上下文
• ✅ 多个 Git 任务可并行执行

如何触发子代理

用户请求示例（会自动触发此 skill）：

"git提交当前分支的变更"
"创建PR合并到main"
"rebase到最新main分支"
"推送代码到远程"

Claude 行为：

1. 自动使用 Task 工具 启动 general-purpose 子代理
2. 子代理在独立上下文中执行所有 Git 操作
3. 完成后向主窗口返回简洁结果（提交 hash、PR URL 等）
4. 主窗口继续保持低上下文消耗

子代理执行模板

当收到 Git 操作请求时，应该：

// ❌ 错误：直接在主窗口执行
Bash('git status')
Bash('git diff')
// ... 消耗大量主窗口 token

// ✅ 正确：启动子代理执行
Task({
  subagent_type: 'general-purpose',
  description: '提交当前分支变更',
  prompt: `
请执行以下 Git 操作：

1. 查看当前变更状态（git status、git diff）
2. 分析变更内容并编写符合规范的提交信息
3. 使用 Conventional Commits 格式创建提交
4. 添加 Claude Code 签名
5. 返回提交 hash 和摘要

遵循 .claude/skills/git-github/SKILL.md 中的规范。
  `,
})

适合子代理执行的任务

⚠️ 核心原则

禁止直接修改 main 分支！

• main 分支只能通过 PR 合并，不允许直接 push
• 合并前必须：
  1. ✅ 通过质量检测 (pnpm quality)
  2. ✅ 无冲突（已 rebase 到最新 main）
  3. ✅ PR 审核通过
• 使用 squash merge 保持提交历史整洁

分支命名规范

• main - 主分支，保持稳定可发布状态
• feature/<name> - 功能分支，如 feature/user-auth
• fix/<name> - 修复分支，如 fix/login-bug
• hotfix/<name> - 紧急修复分支
• refactor/<name> - 重构分支
• docs/<name> - 文档更新分支

Feature 分支合并流程

原则：先 rebase，后 PR，保持线性历史

完整流程

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

# 2. 开发过程中定期同步 main
git fetch origin main
git rebase origin/main

# 3. 完成开发后确保代码质量
flutter analyze
dart format .
flutter test

# 4. Rebase 到最新 main
git fetch origin main
git rebase origin/main

# 5. 解决冲突（如有）
# 编辑冲突文件后：
git add <conflicted-files>
git rebase --continue

# 6. 强制推送（rebase 后必须 force push）
git push --force-with-lease origin feature/your-feature

# 7. 创建 PR
gh pr create --base main --head feature/your-feature \
  --title "feat: 功能描述" \
  --body "$(cat <<'EOF'
## Summary
- 变更点1
- 变更点2

## Test plan
- [ ] 测试项1
- [ ] 测试项2

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

# 8. 合并前检查清单
# ✅ flutter analyze 通过
# ✅ flutter test 通过
# ✅ 已 rebase 到最新 main，无冲突
# ✅ PR 已创建并审核通过

# 9. 合并 PR（推荐 squash merge）
gh pr merge <pr-number> --squash --delete-branch

# 10. 合并后清理
git checkout main
git pull origin main

提交信息规范

格式：<type>(<scope>): <subject>

类型说明

提交示例

# 简单提交
git commit -m "feat: 添加用户登录功能"

# 带 scope
git commit -m "fix(api): 修复请求超时处理"

# 完整提交（使用 HEREDOC）
git commit -m "$(cat <<'EOF'
feat(auth): 添加 JWT token 刷新机制

- 添加 token 过期检测
- 实现自动刷新逻辑
- 更新请求拦截器

Closes #123

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

冲突解决策略

1. pubspec.yaml 冲突：保留较新的依赖版本，确保兼容性
2. pubspec.lock 冲突：选择一方后重新 flutter pub get 生成
3. 代码冲突：根据业务逻辑手动合并，保留两边有用的改动
4. 配置文件冲突：优先保留 main 分支的结构，合并 feature 的新增内容
5. 资源文件冲突：检查 assets 和图片文件，避免覆盖

PR 规范

标题格式

<type>(<scope>): <description>

示例：

• feat: 添加用户认证模块
• fix(auth): 修复登录状态丢失问题
• docs: 更新 README 安装说明

PR 内容模板

## Summary

- 简要描述变更内容（1-3 点）

## Test plan

- [ ] 验证项1
- [ ] 验证项2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

GitHub 操作 (gh CLI)

认证检查

gh auth status

创建仓库

# 创建私有仓库并推送
gh repo create <repo-name> --private --source=. --push

# 创建公开仓库
gh repo create <repo-name> --public --source=. --push

# 设置默认分支
gh repo edit --default-branch main

PR 操作

# 列出 PR
gh pr list

# 查看 PR 详情
gh pr view <pr-number>

# 查看 PR 状态（JSON 格式）
gh pr view <pr-number> --json state,mergedAt

# Squash 合并并删除分支
gh pr merge <pr-number> --squash --delete-branch

# 普通合并
gh pr merge <pr-number> --merge

# Rebase 合并
gh pr merge <pr-number> --rebase

紧急修复流程

# 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug

# 修复后直接推送并创建 PR
git push -u origin hotfix/critical-bug
gh pr create --base main --title "hotfix: 紧急修复描述"

# 合并后同步到其他开发分支
git checkout feature/xxx
git rebase main

常用命令速查

分支管理

git branch -a                    # 查看所有分支
git checkout -b feature/xxx      # 创建并切换分支
git branch -d feature/xxx        # 删除本地分支
git branch -m master main        # 重命名分支

远程操作

git remote -v                    # 查看远程仓库
git push -u origin main          # 推送并设置上游
git push --force-with-lease      # 安全强制推送
git pull --rebase origin main    # 拉取并 rebase

撤销操作

git reset --soft HEAD~1          # 撤销提交，保留更改
git reset --hard HEAD~1          # 完全撤销（慎用）
git commit --amend -m "新消息"    # 修改最近提交信息

查看历史

git log --oneline -10            # 简洁历史
git log --oneline --graph --all  # 图形化历史
git diff main..HEAD              # 查看与 main 的差异

安全提醒

• 🚫 禁止直接 push 到 main 分支 - 只能通过 PR 合并
• 🚫 禁止合并未通过质量检测的代码 - 必须先 flutter analyze 和 flutter test
• 🚫 禁止合并有冲突的 PR - 必须先 rebase 解决冲突
• 永远不要 提交敏感信息 (.env, android/key.properties, ios/*.p12 等)
• 永远不要 对 main/master 使用 --force 推送
• 永远不要 修改已推送到远程的公共分支历史
• 永远不要 提交 build/ 目录和编译产物
• 使用 --force-with-lease 代替 --force（仅限 feature 分支）
• 使用 .gitignore 排除不需要版本控制的文件（build/, .dart_tool/, *.g.dart 等）