# Edu Git 工作流规范 > 版本：1.3 > 日期：2026-07-10 > 状态：v1.3：恢复分支开发模式，AI 不切换分支 > 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml） > 关联文档： > > - [项目规则](../../.trae/rules/project_rules.md) > - [编码规范](./coding-standards.md) > - [迁移指南](../../MIGRATION_GUIDE.md) > - [架构总览](../architecture/001_architecture_overview.md) --- ## 目录 1. [分支开发](#一分支开发) 2. [Conventional Commits 规范](#二conventional-commits-规范) 3. [commitlint + husky 配置](#三commitlint--husky-配置) 4. [事后 Code Review](#四事后-code-review) 5. [文档同步规则](#五文档同步规则) 6. [多语言 monorepo 提交规则](#六多语言-monorepo-提交规则) 7. [版本管理](#七版本管理) 8. [紧急回滚](#八紧急回滚) 9. [附录：CICD 与 Edu Git 工作流差异](#九附录cicd-与-edu-git-工作流差异) --- ## 一、分支开发 ### 1.1 模式本项目采用**分支开发**模式：**人类决策者**为每个任务/模块创建分支并分配给 AI，AI 只在当前分配的分支上工作，分支的创建、切换、合并均由人类决策者维护。 > **AI 不允许自行切换/创建/合并分支**。AI 禁止执行以下命令： > > - `git checkout -b`、`git switch`（创建/切换分支） > - `git branch`（创建分支） > - `git merge`（合并分支） > - `git push origin main`（推送主干） **核心原则**： - `main` 分支始终保持可发布状态，**只有人类决策者能向 main 合并** - 人类决策者为每个任务/模块创建分支并分配给对应 AI - AI 只在当前分配的分支上工作，**不切换、不创建、不合并分支** - AI 完成提交后通知人类决策者合并，**不自行 push main** - 提交前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook） - 通过特性开关（Feature Flag）控制未完成功能的暴露 - 代码审查改为事后追溯（见 §4），不在合并前阻塞 - 默认多 AI 协作，每个模块单一负责制 ### 1.2 AI 提交流程 AI 只在当前分配的分支上执行 `git add` → `git commit`，完成后**通知人类决策者合并**，不推送 main。 ```bash # 1. 本地校验（强制） pnpm run lint # TS 服务 pnpm run typecheck # TS 服务 cd services/api-gateway && go vet ./... && go build ./... # Go 服务 ruff check src/ # Python 服务 # 2. 提交（遵循 Conventional Commits，见 §2） git add git commit -m "feat(): " # 3. 通知人类决策者合并 # AI 不执行 git push origin main，不创建/切换/合并分支 ``` > **AI 可执行**：`git add`、`git commit`、`git status`、`git log`、`git diff`、`git pull`（仅同步当前分支）。 > > **AI 禁止执行**：`git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`、`git push --force`。 ### 1.3 人类合并流程人类决策者负责将分支合并到 `main`，合并时机与策略由人类决策者判断。 ```bash # 人类决策者操作（AI 不执行） # 1. 同步最新 main git checkout main git pull origin main # 2. 合并分支（由人类决策者选择策略） git merge # 或 git merge --no-ff # 3. 推送 main（触发 CI 部署） git push origin main # 4. （可选）删除已合并分支 git branch -d ``` **合并策略建议**： - 一般任务：`git merge --no-ff`（保留分支拓扑，便于追溯） - 紧急修复：`git merge --ff-only`（线性历史） - 大特性分支：`git merge --squash`（压缩为单 commit） ### 1.4 冲突处理 - **分支合并冲突**：由人类决策者在合并分支到 main 时解决，AI 不参与合并操作 - **架构冲突**：由协调 AI 仲裁，通知人类决策者保留方案后合并，通过后续 commit 修正 - **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`，需人类决策者确认 ### 1.5 main 分支保护 - 禁止 force push（仅协调 AI 在事故时操作，需人类决策者确认） - pre-commit / commit-msg / pre-push hook 强制校验（见 §3.4） - 不要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证 - **AI 无权直接 push main**，所有 main 变更须经人类决策者合并 --- ## 二、Conventional Commits 规范 ### 2.1 提交信息格式所有提交信息必须遵循 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/zh-hans/)： ``` ():