docs: 恢复分支开发模式 - AI 不切换分支,默认多AI协作,经验沉淀不标注AI身份
This commit is contained in:
SpecialX
@@ -1,38 +1,52 @@
|
||||
# 多 AI 协作开发指南（Multi-AI Collaboration Guide）
|
||||
|
||||
> 版本：2.0
|
||||
> 版本：2.1
|
||||
> 日期：2026-07-10
|
||||
> 适用范围：Edu 微服务项目多 Agent 并行开发
|
||||
> 状态：v2.1 — 恢复分支开发模式，AI 不切换分支（分支由人类决策者维护）
|
||||
> 适用范围：Edu 微服务项目多 Agent 并行开发（默认多 AI 协作）
|
||||
> 关联文档：[Git 工作流](./git-workflow.md)、[项目规则](../../.trae/rules/project_rules.md)、[004 架构影响地图](../architecture/004_architecture_impact_map.md)、[CODEOWNERS](../../.github/CODEOWNERS)、[AI 分配方案](../architecture/ai-allocation.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 总体模式
|
||||
|
||||
### 1.1 角色定义
|
||||
### 1.1 默认多 AI 协作
|
||||
|
||||
| 角色 | 职责 | 数量 | 备注 |
|
||||
| ----------------------------- | -------------------------------------------- | ---- | ------------------- |
|
||||
| **协调 AI（Coordinator AI）** | 契约管理、交叉审查、冲突仲裁、发布 | 1 | 不直接写业务代码 |
|
||||
| **开发 AI（Dev AI）** | 按模块分工写代码、直接 push main | N | 每个负责 1-2 个模块 |
|
||||
| **人类决策者（Human）** | 架构决策、Breaking Change 审批、最终发布确认 | 1 | 只在关键节点介入 |
|
||||
本项目所有 AI 工作**默认按多 AI 协作模式**进行，即使某个任务只由单个 AI 执行，也遵循本指南的模块边界、契约先行、经验沉淀等约束，以便随时插入新 AI 或并行启动多 AI。
|
||||
|
||||
### 1.2 角色定义
|
||||
|
||||
| 角色 | 职责 | 数量 | 备注 |
|
||||
| ----------------------------- | ----------------------------------------------------------- | ---- | -------------------------- |
|
||||
| **协调 AI（Coordinator AI）** | 契约管理、交叉审查、冲突仲裁、跨模块协调 | 1 | 不直接写业务代码 |
|
||||
| **开发 AI（Dev AI）** | 按模块分工写代码，在分配的分支上提交 | N | 每个负责 1-2 个模块 |
|
||||
| **人类决策者（Human）** | 创建/合并分支、架构决策、Breaking Change 审批、最终发布确认 | 1 | 唯一拥有分支管理权限的角色 |
|
||||
|
||||
> SRE AI 负责 `infra/`，可由协调 AI 兼任或独立设置。
|
||||
|
||||
### 1.2 工作流总览（直接 push main，无分支无 PR）
|
||||
### 1.3 工作流总览（分支开发，AI 不切换分支）
|
||||
|
||||
```
|
||||
开发 AI-A (classes模块) 开发 AI-B (iam模块) 协调 AI
|
||||
│ │ │
|
||||
│ 1.git pull --rebase main │ 1.git pull --rebase main│
|
||||
│ 2.本地校验+提交 │ 2.本地校验+提交 │
|
||||
│ 3.直接 push main │ 3.直接 push main │
|
||||
│ │ │ 4.CI 自动校验
|
||||
│ │ │ 5.事后审查 commit
|
||||
│ │ │ 6.问题→revert/后续commit
|
||||
人类决策者 开发 AI-A (classes 分支) 开发 AI-B (iam 分支) 协调 AI
|
||||
│ 1.为每个任务创建分支 │ │ │
|
||||
│ 2.分配分支给对应 AI │ │ │
|
||||
│ ──────────────────────────────────►│ │ │
|
||||
│ │ 3.在分配分支上开发 │ │
|
||||
│ │ 4.本地校验 │ │
|
||||
│ │ 5.git add → commit │ │
|
||||
│ │ 6.通知人类合并 │ │
|
||||
│ ◄───────────────────────────────────│ │ │
|
||||
│ 7.人类审查 + 合并分支到 main │ │ │
|
||||
│ 8.CI 自动校验（main 触发） │ │ │
|
||||
│ │ │ │ 9.事后审查 commit
|
||||
```
|
||||
|
||||
> 因 Gitea 问题，**不再使用特性分支与 PR**。所有变更直接 `git push origin main`。Git 操作细节见 [Git 工作流](./git-workflow.md) §1-§4。
|
||||
**关键原则**：
|
||||
|
||||
- **分支由人类决策者创建与合并**，AI 不执行任何分支切换/创建/合并命令
|
||||
- AI 的操作止步于 `git commit`，之后**通知人类合并**
|
||||
- 默认多 AI 协作，多 AI 在各自分支并行，路径隔离避免冲突
|
||||
- Git 操作细节见 [Git 工作流](./git-workflow.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -101,14 +115,16 @@
|
||||
| ai07 | teacher-portal、student-portal、parent-portal、admin-portal | TS |
|
||||
| coord | shared-proto、shared-*、infra/、docs/、CI/CD | — |
|
||||
|
||||
> AI 标识仅用于模块分工与协调沟通，**不写入 commit message、不标注在经验沉淀文档中**（见 §3.2、§9.3）。
|
||||
|
||||
### 2.5 分工原则
|
||||
|
||||
1. **单一负责制**：每个模块只有一个 AI 负责，避免并行修改同一文件
|
||||
2. **同语言内聚**：一个 AI 负责多个同语言服务，降低学习成本
|
||||
3. **契约集中管理**：`shared-proto` 由 coord 维护，开发 AI 只读引用
|
||||
4. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序依次直接 push（见 §5）
|
||||
4. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序各自在分支完成，人类按顺序合并（见 §5）
|
||||
5. **基础设施独立**：`infra/` 由 coord（或 SRE AI）专门负责
|
||||
6. **物理路径隔离**：目录级别隔离，多 AI 直接 push main 几乎零文件冲突
|
||||
6. **物理路径隔离**：目录级别隔离，多 AI 在各自分支并行几乎零文件冲突
|
||||
|
||||
### 2.6 架构设计外包三阶段
|
||||
|
||||
@@ -170,15 +186,23 @@
|
||||
|
||||
---
|
||||
|
||||
## 3. 直接 push main 规则
|
||||
## 3. 分支开发规则
|
||||
|
||||
> Git 操作详细规范见 [Git 工作流](./git-workflow.md)。本节仅列多 AI 协作相关要点。
|
||||
|
||||
### 3.1 提交前必做
|
||||
### 3.1 分支由人类决策者维护（强制）
|
||||
|
||||
- **分支创建**：人类决策者为每个任务/模块创建分支并分配给对应 AI
|
||||
- **分支合并**：人类决策者负责审查分支并合并到 `main`
|
||||
- **AI 禁止执行任何分支管理命令**（见 §3.4 禁止命令清单）
|
||||
|
||||
AI 接到任务后，**假设人类已为自己分配好当前工作分支**，AI 只需在该分支上工作，不需要（也不允许）切换分支。
|
||||
|
||||
### 3.2 AI 提交流程（止步于 commit）
|
||||
|
||||
```bash
|
||||
# 1. 同步最新 main
|
||||
git pull --rebase origin main
|
||||
# 1. 确认当前分支（人类已分配，AI 不切换）
|
||||
git branch --show-current
|
||||
|
||||
# 2. 本地校验（强制，按语言）
|
||||
pnpm run lint && pnpm run typecheck # TS
|
||||
@@ -190,54 +214,91 @@ git add services/<my-service>/...
|
||||
git commit -m "feat(<scope>): <subject>"
|
||||
```
|
||||
|
||||
### 3.2 AI 身份标注（强制）
|
||||
提交完成后，AI **通知人类决策者合并**：
|
||||
|
||||
每个 commit message body 末尾必须追加（用于追溯，不再有 PR 描述）：
|
||||
> "已完成 [模块] 的 [任务]，分支 [branch-name] 上的 commit [sha] 已就绪，请审查并合并到 main。"
|
||||
|
||||
> **commit message 不再要求标注 AI 身份**。追溯通过分支名 + commit history + CODEOWNERS 完成。详见 §9.3。
|
||||
|
||||
### 3.3 commit message 规范
|
||||
|
||||
- 遵循 Conventional Commits：`feat(scope): subject`
|
||||
- body 描述变更原因与影响
|
||||
- **不追加 AI-Agent / Coord 等身份字段**（经验沉淀不标注 AI 身份，见 §9.3）
|
||||
- 末尾不强制附加任何签名
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
---
|
||||
feat(classes): 新增班级分页查询
|
||||
|
||||
AI-Agent: <ai-id> (<负责模块>)
|
||||
Coord: <协调 AI ai-id>
|
||||
- GET /api/v1/classes 支持 page、size 参数
|
||||
- 响应增加 total、hasMore 字段
|
||||
- 单测覆盖分页逻辑
|
||||
```
|
||||
|
||||
> 不再有 Branch 字段（不使用分支）。详见 project_rules §14.6。
|
||||
### 3.4 AI 禁止命令清单（强制）
|
||||
|
||||
### 3.3 推送
|
||||
以下命令**仅人类决策者可执行，AI 严禁执行**：
|
||||
|
||||
```bash
|
||||
# push 前再次同步（避免冲突）
|
||||
git pull --rebase origin main
|
||||
| 命令 | 用途 | 允许执行者 |
|
||||
| ------------------------------- | --------------- | ---------------------------------- |
|
||||
| `git checkout -b <branch>` | 创建新分支 | **人类决策者** |
|
||||
| `git switch <branch>` | 切换分支 | **人类决策者** |
|
||||
| `git switch -c <branch>` | 创建并切换分支 | **人类决策者** |
|
||||
| `git branch <branch>` | 创建分支 | **人类决策者** |
|
||||
| `git branch -d/-D <branch>` | 删除分支 | **人类决策者** |
|
||||
| `git merge <branch>` | 合并分支 | **人类决策者** |
|
||||
| `git push origin main` | 推送到 main | **人类决策者** |
|
||||
| `git push --force-with-lease` | 强制推送 | **人类决策者**（仅事故） |
|
||||
| `git rebase` | 变基 | **人类决策者**（AI 不主动 rebase） |
|
||||
| `git revert` 后 `git push main` | 回滚后推送 main | **人类决策者** |
|
||||
|
||||
# 直接 push main
|
||||
git push origin main
|
||||
```
|
||||
AI 允许执行的 Git 命令：
|
||||
|
||||
- `git status`、`git diff`、`git log` — 查看状态
|
||||
- `git branch --show-current` — 查看当前分支名
|
||||
- `git add`、`git commit` — 暂存与提交（仅在当前分配分支）
|
||||
- `git pull`（仅拉取当前分支远程更新，不切换分支）
|
||||
|
||||
### 3.5 通知人类合并的时机
|
||||
|
||||
AI 在以下情况必须通知人类决策者合并：
|
||||
|
||||
1. 单个任务完成，commit 已就绪
|
||||
2. 跨模块变更的某一层完成（见 §5）
|
||||
3. 修复了阻塞下游的问题
|
||||
4. 紧急 hotfix 提交完成
|
||||
|
||||
通知内容包含：分支名、commit SHA、变更摘要、是否阻塞下游。
|
||||
|
||||
---
|
||||
|
||||
## 4. 事后 Code Review
|
||||
|
||||
> 不再使用 PR 前置 review。代码审查改为事后追溯。详见 [Git 工作流](./git-workflow.md) §4。
|
||||
> 代码审查基于分支 commit history 进行。详见 [Git 工作流](./git-workflow.md) §4。
|
||||
|
||||
### 4.1 review 责任人
|
||||
|
||||
由 `.github/CODEOWNERS` 确定模块归属（CODEOWNERS 不再用于自动分配 PR reviewer，改为 commit 追溯依据）：
|
||||
由 `.github/CODEOWNERS` 确定模块归属（CODEOWNERS 用于分支审查与追溯依据）：
|
||||
|
||||
- 模块 owner 负责事后审查涉及自己模块的 commit
|
||||
- 跨模块变更由协调 AI 事后审查
|
||||
- 基础设施变更由 SRE 事后审查
|
||||
- 模块 owner 负责审查涉及自己模块的分支
|
||||
- 跨模块变更由协调 AI 审查
|
||||
- 基础设施变更由 SRE 审查
|
||||
- 人类决策者负责最终合并决策
|
||||
|
||||
### 4.2 review 依据
|
||||
|
||||
- 分支 commit history（`git log main..<branch>` 查看分支新增 commit）
|
||||
- commit message（Conventional Commits 格式）
|
||||
- commit diff（`git log -p` 或平台 commit 视图）
|
||||
- AI 身份标注（commit body 末尾 `AI-Agent:` 字段）
|
||||
- 分支与 main 的 diff（`git diff main...<branch>`）
|
||||
|
||||
### 4.3 问题处理
|
||||
|
||||
- **小问题**：后续 commit 修正
|
||||
- **严重问题**：`git revert <commit>` + `git push origin main`（CI 自动重新部署）
|
||||
- **架构冲突**：由协调 AI 仲裁保留方案，通过 revert + 新 commit 修正
|
||||
- **小问题**：在分支上后续 commit 修正，再次通知人类合并
|
||||
- **严重问题**：人类决策者拒绝合并，AI 在分支上 `git revert <commit>` 后重新通知
|
||||
- **架构冲突**：由协调 AI 仲裁保留方案，分支上 revert + 新 commit 修正
|
||||
- **已合并到 main 的问题**：人类决策者在 main 上 revert，AI 不直接操作 main
|
||||
|
||||
---
|
||||
|
||||
@@ -245,7 +306,7 @@ git push origin main
|
||||
|
||||
### 5.1 变更拆分原则
|
||||
|
||||
修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）：
|
||||
修改涉及多模块时，各 AI 在各自分支完成开发，**人类决策者按依赖顺序依次合并**（避免下游编译失败）：
|
||||
|
||||
```
|
||||
原始任务：classes 服务新增"班级导入"功能
|
||||
@@ -256,25 +317,34 @@ git push origin main
|
||||
4. teacher-portal 前端上传按钮
|
||||
```
|
||||
|
||||
### 5.2 提交顺序（强制）
|
||||
### 5.2 分支与合并顺序（强制）
|
||||
|
||||
| 顺序 | commit | scope | 负责人 | 依赖 |
|
||||
| ---- | ----------------------------------------------- | -------------- | --------- | ---- |
|
||||
| 1 | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto | 协调 AI | 无 |
|
||||
| 2 | `feat(classes): 实现班级批量导入` | classes | 开发 AI-A | 1 |
|
||||
| 3 | `feat(api-gateway): 新增 import 路由` | api-gateway | 开发 AI-B | 2 |
|
||||
| 4 | `feat(teacher-portal): 新增班级导入按钮` | teacher-portal | 开发 AI-C | 3 |
|
||||
| 顺序 | commit | scope | 负责人 | 所在分支 | 合并依赖 |
|
||||
| ---- | ----------------------------------------------- | -------------- | --------- | --------------------- | -------- |
|
||||
| 1 | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto | 协调 AI | `feat/proto-import` | 无 |
|
||||
| 2 | `feat(classes): 实现班级批量导入` | classes | 开发 AI-A | `feat/classes-import` | 1 已合并 |
|
||||
| 3 | `feat(api-gateway): 新增 import 路由` | api-gateway | 开发 AI-B | `feat/gw-import` | 2 已合并 |
|
||||
| 4 | `feat(teacher-portal): 新增班级导入按钮` | teacher-portal | 开发 AI-C | `feat/portal-import` | 3 已合并 |
|
||||
|
||||
> 每提交一层并 push 后，再开发下一层。协调 AI 负责监督顺序，避免越级提交导致下游构建失败。
|
||||
> 各 AI 可并行在自己分支开发（基于 main 最新状态），但**人类决策者按顺序合并**：合并第 1 层后，第 2 层 AI 需 `git pull` 同步 main 更新，再通知人类合并。协调 AI 负责监督顺序，避免越级合并导致下游构建失败。
|
||||
|
||||
### 5.3 Breaking Change 流程
|
||||
### 5.3 并行开发与顺序合并的协调
|
||||
|
||||
1. 协调 AI 在 issue 中列出跨模块变更清单与依赖顺序
|
||||
2. 各 AI 基于当前 main 创建分支（由人类决策者创建并分配）
|
||||
3. 各 AI 独立开发，完成后在各自分支 commit
|
||||
4. 人类决策者按依赖顺序逐个合并，每合并一层通知下游 AI 同步
|
||||
5. 下游 AI `git pull` 同步 main 后，确认自己分支可正常构建，再通知人类合并
|
||||
|
||||
### 5.4 Breaking Change 流程
|
||||
|
||||
涉及 Breaking Change（proto 字段删除、API 签名变更）：
|
||||
|
||||
1. **人类决策者审批**：在 issue 中讨论，获批准后才开发
|
||||
2. **版本号升级**：proto 加 `v2` 后缀，服务同时支持 v1/v2 过渡期
|
||||
3. **迁移文档**：更新 `MIGRATION_GUIDE.md`
|
||||
4. **协调 AI 通知所有相关 AI**：在 commit 评论或 issue 中列出影响范围
|
||||
4. **协调 AI 通知所有相关 AI**：在 issue 中列出影响范围
|
||||
5. **分支合并需人类决策者二次确认**：Breaking Change 分支合并前必须人类决策者签字
|
||||
|
||||
---
|
||||
|
||||
@@ -282,64 +352,62 @@ git push origin main
|
||||
|
||||
### 6.1 启动并行任务
|
||||
|
||||
人类决策者分配任务给多个 AI：
|
||||
人类决策者为每个任务创建分支并分配给多个 AI：
|
||||
|
||||
```
|
||||
任务 1：classes 服务新增分页查询 → 开发 AI-A (ai01)
|
||||
任务 2：api-gateway 新增限流规则 → 开发 AI-B (ai02)
|
||||
任务 3：teacher-portal 优化班级列表 → 开发 AI-C (ai03)
|
||||
任务 1：classes 服务新增分页查询 → 分支 feat/classes-page → 开发 AI-A
|
||||
任务 2：api-gateway 新增限流规则 → 分支 feat/gw-ratelimit → 开发 AI-B
|
||||
任务 3：teacher-portal 优化班级列表 → 分支 feat/portal-classlist → 开发 AI-C
|
||||
```
|
||||
|
||||
### 6.2 并行执行（路径隔离，直接 push main）
|
||||
### 6.2 并行执行（路径隔离，各自分支）
|
||||
|
||||
每个 AI 在自己目录内工作，互不干扰：
|
||||
每个 AI 在自己分支上、自己目录内工作，互不干扰：
|
||||
|
||||
```bash
|
||||
# AI-A（只改 services/classes/）
|
||||
git pull --rebase origin main
|
||||
# AI-A（在分支 feat/classes-page 上，只改 services/classes/）
|
||||
git branch --show-current # 确认在分配的分支
|
||||
# 编辑 services/classes/...
|
||||
pnpm --filter @edu/classes-service lint && typecheck
|
||||
git add services/classes/
|
||||
git commit -m "feat(classes): 新增班级分页查询
|
||||
|
||||
---
|
||||
- GET /api/v1/classes 支持 page、size 参数
|
||||
- 响应增加 total、hasMore 字段"
|
||||
# 通知人类决策者合并 feat/classes-page
|
||||
|
||||
AI-Agent: ai01 (classes)
|
||||
Coord: coord"
|
||||
git push origin main
|
||||
|
||||
# AI-B（同时，只改 services/api-gateway/）
|
||||
git pull --rebase origin main
|
||||
# AI-B（同时，在分支 feat/gw-ratelimit 上，只改 services/api-gateway/）
|
||||
git branch --show-current
|
||||
# 编辑 services/api-gateway/...
|
||||
git add services/api-gateway/
|
||||
git commit -m "feat(api-gateway): 新增 IP 级限流规则
|
||||
|
||||
---
|
||||
|
||||
AI-Agent: ai02 (api-gateway)
|
||||
Coord: coord"
|
||||
git push origin main
|
||||
git commit -m "feat(api-gateway): 新增 IP 级限流规则"
|
||||
# 通知人类决策者合并 feat/gw-ratelimit
|
||||
```
|
||||
|
||||
### 6.3 冲突预防
|
||||
|
||||
1. **契约先行**：proto 变更先 push，再 push 依赖它的服务
|
||||
2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 issue/commit 评论 @ 所有关联模块 AI
|
||||
3. **频繁同步**：每天至少 `git pull --rebase origin main` 一次，避免长期分叉
|
||||
1. **契约先行**：proto 变更先合并到 main，再合并依赖它的服务分支
|
||||
2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 issue 评论 @ 所有关联模块 AI
|
||||
3. **频繁同步**：人类决策者合并后，下游 AI `git pull` 同步 main 到自己分支（或人类决策者 rebase 分支后再合并）
|
||||
4. **物理路径隔离**：各 AI 只改自己目录，`pnpm-lock.yaml` 是唯一可能冲突的共享文件
|
||||
|
||||
### 6.4 pnpm-lock.yaml 冲突处理
|
||||
|
||||
若分支合并时 `pnpm-lock.yaml` 冲突，由**人类决策者**在合并过程中解决：
|
||||
|
||||
```bash
|
||||
git pull --rebase origin main
|
||||
# 人类决策者执行（AI 不执行 merge）
|
||||
git merge feat/<branch>
|
||||
# 若 pnpm-lock.yaml 冲突：
|
||||
git checkout --theirs pnpm-lock.yaml
|
||||
pnpm install
|
||||
git add pnpm-lock.yaml
|
||||
git rebase --continue
|
||||
git commit
|
||||
git push origin main
|
||||
```
|
||||
|
||||
> AI 若发现自己分支的 `pnpm-lock.yaml` 与 main 不一致，应在自己分支上 `pnpm install` 重新生成并 commit，再通知人类合并。
|
||||
|
||||
---
|
||||
|
||||
## 7. 完整工作流示例
|
||||
@@ -347,61 +415,71 @@ git push origin main
|
||||
### 场景：开发 AI-A 为 classes 新增分页查询
|
||||
|
||||
```bash
|
||||
# ============ 人类决策者 ============
|
||||
# 1. 基于 main 创建分支并分配给 AI-A
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b feat/classes-page
|
||||
# 通知 AI-A：请在 feat/classes-page 分支上工作
|
||||
|
||||
# ============ 开发 AI-A ============
|
||||
|
||||
# 1. 同步 main
|
||||
git pull --rebase origin main
|
||||
# 2. 确认当前分支（人类已分配，AI 不切换）
|
||||
git branch --show-current # 应显示 feat/classes-page
|
||||
|
||||
# 2. 开发（只改 services/classes/）
|
||||
# 3. 开发（只改 services/classes/）
|
||||
# 编辑 services/classes/src/classes/classes.controller.ts
|
||||
# 编辑 services/classes/src/classes/classes.service.ts
|
||||
# 编辑 services/classes/src/classes/classes.repository.ts
|
||||
|
||||
# 3. 本地校验
|
||||
# 4. 本地校验
|
||||
pnpm --filter @edu/classes-service lint
|
||||
pnpm --filter @edu/classes-service typecheck
|
||||
pnpm --filter @edu/classes-service test
|
||||
|
||||
# 4. 架构扫描（若新增了导出函数/路由）
|
||||
# 5. 架构扫描（若新增了导出函数/路由）
|
||||
pnpm run arch:scan
|
||||
|
||||
# 5. 提交
|
||||
# 6. 提交（不标注 AI 身份）
|
||||
git add services/classes/
|
||||
git commit -m "feat(classes): 新增班级分页查询
|
||||
|
||||
- GET /api/v1/classes 支持 page、size 参数
|
||||
- 响应增加 total、hasMore 字段
|
||||
- 单测覆盖分页逻辑
|
||||
- 单测覆盖分页逻辑"
|
||||
|
||||
---
|
||||
# 7. 通知人类决策者合并
|
||||
# "已完成 classes 分页查询，分支 feat/classes-page，commit <sha>，请审查合并"
|
||||
|
||||
AI-Agent: ai01 (classes)
|
||||
Coord: coord"
|
||||
# ============ 人类决策者 ============
|
||||
|
||||
# 6. push 前同步 + 直接 push main
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
# 8. 审查分支
|
||||
git log main..feat/classes-page --oneline
|
||||
git diff main...feat/classes-page
|
||||
|
||||
# ============ 协调 AI（事后） ============
|
||||
# 9. 合并到 main（AI 不执行此步）
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git merge feat/classes-page
|
||||
git push origin main # CI 自动触发 quality + deploy
|
||||
|
||||
# 7. 收到 push 通知，事后审查 commit
|
||||
# ============ 协调 AI（事后审查） ============
|
||||
|
||||
# 10. 收到合并通知，审查 main 上新 commit
|
||||
git pull origin main
|
||||
git log -p -1
|
||||
# 若需修改，评论要求开发 AI-A 后续 commit 修正
|
||||
# 若严重问题，git revert + 通知 AI-A
|
||||
# 若需修改，评论要求开发 AI-A 在新分支上后续 commit 修正
|
||||
# 若严重问题，由人类决策者在 main 上 git revert
|
||||
|
||||
# ============ 开发 AI-A（若需修正） ============
|
||||
|
||||
# 8. 后续 commit 修正
|
||||
git pull --rebase origin main
|
||||
# 11. 等待人类决策者为修正任务创建新分支并分配
|
||||
# 在新分支上后续 commit 修正
|
||||
git branch --show-current # 确认在新分配的分支
|
||||
# 编辑修复...
|
||||
git add services/classes/
|
||||
git commit -m "fix(classes): 修复分页 total 计算错误
|
||||
|
||||
---
|
||||
|
||||
AI-Agent: ai01 (classes)
|
||||
Coord: coord"
|
||||
git push origin main
|
||||
git commit -m "fix(classes): 修复分页 total 计算错误"
|
||||
# 通知人类决策者合并新分支
|
||||
```
|
||||
|
||||
---
|
||||
@@ -410,22 +488,24 @@ git push origin main
|
||||
|
||||
### 8.1 多 AI 修改同一文件冲突
|
||||
|
||||
**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖，后 push 的被拒绝。
|
||||
**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖，合并到 main 时冲突。
|
||||
|
||||
**解决**：
|
||||
**解决**：由**人类决策者**在合并第二个分支时解决冲突：
|
||||
|
||||
```bash
|
||||
# 后 push 的 AI 执行
|
||||
git pull --rebase origin main
|
||||
# 人类决策者执行（AI 不执行 merge）
|
||||
git merge feat/<branch-B>
|
||||
# 解决 package.json 冲突（保留两边依赖）
|
||||
git add package.json
|
||||
git rebase --continue
|
||||
git commit
|
||||
git push origin main
|
||||
```
|
||||
|
||||
AI 若预判会冲突，应提前在 issue 中与对方 AI 协调，或拆分共享文件变更到不同 commit。
|
||||
|
||||
### 8.2 CI 失败但本地通过
|
||||
|
||||
**场景**：开发 AI 本地 lint 通过，CI 报错。
|
||||
**场景**：开发 AI 本地 lint 通过，合并到 main 后 CI 报错。
|
||||
|
||||
**排查**：
|
||||
|
||||
@@ -433,18 +513,14 @@ git push origin main
|
||||
2. 检查 `pnpm-lock.yaml` 是否最新（`pnpm install --frozen-lockfile`）
|
||||
3. 检查环境变量是否齐全（`.env` vs CI secrets）
|
||||
|
||||
**修复后**：
|
||||
**修复后**：AI 在新分支上修复，再次通知人类合并：
|
||||
|
||||
```bash
|
||||
git pull --rebase origin main
|
||||
# AI 在新分配的分支上
|
||||
git branch --show-current
|
||||
git add <fixed-files>
|
||||
git commit -m "fix(classes): 修复 CI lint 失败
|
||||
|
||||
---
|
||||
|
||||
AI-Agent: ai01 (classes)
|
||||
Coord: coord"
|
||||
git push origin main
|
||||
git commit -m "fix(classes): 修复 CI lint 失败"
|
||||
# 通知人类决策者合并
|
||||
```
|
||||
|
||||
### 8.3 husky pre-commit hook 失败
|
||||
@@ -461,54 +537,60 @@ git push origin main
|
||||
|
||||
### 8.4 proto 变更导致下游编译失败
|
||||
|
||||
**场景**：shared-proto push 后，classes 服务 `buf generate` 报错。
|
||||
**场景**：shared-proto 分支合并到 main 后，classes 服务 `buf generate` 报错。
|
||||
|
||||
**解决**：
|
||||
|
||||
1. 协调 AI push proto 变更前，在 commit 评论或 issue 中通知所有依赖服务的 AI
|
||||
2. 下游 AI `git pull --rebase origin main` 后重新 `buf generate`
|
||||
3. 更新生成代码并提交：
|
||||
1. 协调 AI 的 proto 分支合并前，在 issue 评论中通知所有依赖服务的 AI
|
||||
2. proto 分支合并到 main 后，下游 AI 在自己分支上 `git pull` 同步 main
|
||||
3. 下游 AI 重新生成代码并提交：
|
||||
|
||||
```bash
|
||||
git pull --rebase origin main
|
||||
# 下游 AI 在自己分支上
|
||||
git pull origin main # 同步 main 最新（含 proto 变更）
|
||||
pnpm run proto:generate
|
||||
git add packages/shared-proto/gen/
|
||||
git commit -m "chore(shared-proto): 重新生成 TS 类型
|
||||
|
||||
---
|
||||
|
||||
AI-Agent: ai01 (classes)
|
||||
Coord: coord"
|
||||
git push origin main
|
||||
git commit -m "chore(shared-proto): 重新生成 TS 类型"
|
||||
# 通知人类决策者合并
|
||||
```
|
||||
|
||||
### 8.5 误推错误代码到 main
|
||||
### 8.5 误合并错误代码到 main
|
||||
|
||||
**场景**：开发 AI push 了有问题的代码。
|
||||
**场景**：人类决策者合并了有问题的分支到 main。
|
||||
|
||||
**修复**：
|
||||
**修复**（由**人类决策者**执行）：
|
||||
|
||||
```bash
|
||||
# 1. 确认误推的 commit
|
||||
# 1. 确认误合并的 commit
|
||||
git log --oneline -5
|
||||
|
||||
# 2. 拉取最新 main
|
||||
git pull --rebase origin main
|
||||
|
||||
# 3. revert 误推 commit
|
||||
# 2. 在 main 上 revert
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git revert <commit-sha>
|
||||
|
||||
# 4. push 回滚 commit（CI 自动重新部署）
|
||||
git push origin main
|
||||
git push origin main # CI 自动重新部署
|
||||
```
|
||||
|
||||
> 严重事故时，协调 AI 可用 `workflow_dispatch` 指定稳定 `commit_sha` 回滚部署（见 project_rules §15.5）。
|
||||
AI 发现误合并问题后，应**通知人类决策者**执行 revert，不自行操作 main。
|
||||
|
||||
### 8.6 AI 身份冲突（同名 AI）
|
||||
> 严重事故时，协调 AI 可建议人类决策者用 `workflow_dispatch` 指定稳定 `commit_sha` 回滚部署（见 project_rules §15.5）。
|
||||
|
||||
**场景**：两个 AI 都叫 "ai01"，commit 标注混淆。
|
||||
### 8.6 AI 误切分支怎么办
|
||||
|
||||
**预防**：每个 AI 启动前分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。同名 AI 复用时，**禁止阅读前任同名 AI 的工作日志**（见 §2.1），只依据当前模块文档与 004 架构图工作。
|
||||
**场景**：AI 误执行了 `git checkout -b` 或 `git switch` 创建/切换了分支。
|
||||
|
||||
**处理**：
|
||||
|
||||
1. AI 立即停止操作，不在此分支上 commit
|
||||
2. 通知人类决策者：误创建了分支 `<branch-name>`，请处理
|
||||
3. 由人类决策者决定是否删除误创建的分支、是否将 AI 切回正确分支
|
||||
4. AI 在 issue 中记录此次违规，避免再犯
|
||||
|
||||
### 8.7 同名 AI 复用问题
|
||||
|
||||
**场景**：两个 AI 都叫 "ai01"，分工混淆。
|
||||
|
||||
**预防**：每个 AI 启动前由人类决策者分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。同名 AI 复用时，**禁止阅读前任同名 AI 的工作日志**（见 §2.1），只依据当前模块文档与 004 架构图工作。AI 标识不写入 commit，避免历史 commit 混淆。
|
||||
|
||||
---
|
||||
|
||||
@@ -516,12 +598,13 @@ git push origin main
|
||||
|
||||
### 9.1 通信渠道
|
||||
|
||||
| 场景 | 方式 |
|
||||
| ----------- | --------------------------------- |
|
||||
| 事后 review | commit 评论（`@ai01 请修正 xxx`） |
|
||||
| 任务分配 | Issue（`@ai01 负责实现 xxx`） |
|
||||
| 紧急通知 | commit 评论 + issue @ 相关人员 |
|
||||
| 架构讨论 | Issue 标签 `discussion` |
|
||||
| 场景 | 方式 |
|
||||
| ----------- | ------------------------------------------------ |
|
||||
| 任务分配 | Issue（指定 AI、模块、分支名） |
|
||||
| 合并请求 | AI 完成后通知人类决策者（issue 评论 / 即时通讯） |
|
||||
| 事后 review | commit 评论（指出问题、要求修正） |
|
||||
| 紧急通知 | issue + commit 评论 @ 相关人员 |
|
||||
| 架构讨论 | Issue 标签 `discussion` |
|
||||
|
||||
### 9.2 commit 评论规范
|
||||
|
||||
@@ -536,21 +619,24 @@ git push origin main
|
||||
|
||||
### 建议
|
||||
- 考虑抽取分页逻辑到 shared-ts
|
||||
|
||||
---
|
||||
|
||||
协调 AI（coord）
|
||||
```
|
||||
|
||||
### 9.3 经验沉淀（不写跨模块日志）
|
||||
> 评论不标注 AI 身份签名（如"协调 AI"字样），通过 CODEOWNERS 与分支归属自然体现审查者角色。
|
||||
|
||||
> **禁止**在 `docs/troubleshooting/known-issues.md` 写跨模块"工作经验日志/流水账"。
|
||||
### 9.3 经验沉淀（不写工作日志，不标注 AI 身份）
|
||||
|
||||
- 模块内的经验沉淀到**自己模块的 README/文档**
|
||||
- known-issues 只保留索引式"场景→技术"映射（见 project_rules §9）
|
||||
- 新发现的"场景→技术"映射提炼到 known-issues 对应**模块分区**（一行索引，不写流水）
|
||||
> **核心原则**：经验沉淀只记录"场景→技术/规则"映射，**不记录工作日志、不标注 AI 身份**。
|
||||
|
||||
> 新 AI 不应被前任同名 AI 的流水记录误导。known-issues 是速查手册，不是日记。
|
||||
**强制约束**：
|
||||
|
||||
1. **禁止在 `docs/troubleshooting/known-issues.md` 写跨模块"工作经验日志/流水账"**
|
||||
2. **禁止在 commit message、review 评论、经验沉淀文档中出现 AI 身份标识**（如 `ai01`、`ai02`、`coord`、`AI-Agent:` 字段等）
|
||||
3. **禁止在模块 README/文档中标注"由哪个 AI 编写/修改"**
|
||||
4. 模块内的经验沉淀到**自己模块的 README/文档**，只写技术内容
|
||||
5. known-issues 只保留索引式"场景→技术"映射（见 project_rules §9）
|
||||
6. 新发现的"场景→技术"映射提炼到 known-issues 对应**模块分区**（一行索引，不写流水）
|
||||
|
||||
> 新 AI 不应被前任同名 AI 的流水记录误导，也不应通过 AI 标识追溯"谁写的"——代码归属通过 CODEOWNERS 与 git blame 自然体现。known-issues 是速查手册，不是日记。
|
||||
|
||||
---
|
||||
|
||||
@@ -558,18 +644,22 @@ git push origin main
|
||||
|
||||
### 10.1 main 分支保护
|
||||
|
||||
- **直接 push main**：所有 AI 直接 push，不阻塞
|
||||
- **禁止 force push**：开发 AI 无权，仅协调 AI 在事故时 `git push --force-with-lease origin main`
|
||||
- **pre-commit / commit-msg / pre-push hook**：强制校验（见 git-workflow.md §3.4）
|
||||
- **CI 校验**：push main 后 CI 自动跑 quality + deploy（见 project_rules §15）
|
||||
- **main 只接收人类决策者的合并**：AI 不直接 push main
|
||||
- **分支保护**：main 禁止 force push，仅人类决策者可合并分支
|
||||
- **pre-commit / commit-msg hook**：在 AI 本地 commit 时强制校验（见 git-workflow.md §3.4）
|
||||
- **CI 校验**：人类决策者合并到 main 后 CI 自动跑 quality + deploy（见 project_rules §15）
|
||||
- **禁止 AI force push**：任何分支都禁止 AI 执行 `git push --force`
|
||||
|
||||
### 10.2 AI 账号权限
|
||||
|
||||
| 角色 | 直接 push main | 修改他人模块 | force push main |
|
||||
| ------- | -------------- | ----------------------------- | --------------- |
|
||||
| 开发 AI | ✅ | ❌ | ❌ |
|
||||
| 协调 AI | ✅ | ✅（shared-proto/infra/docs） | ⚠️（仅事故） |
|
||||
| SRE AI | ✅（infra） | ✅（仅 infra） | ⚠️（仅事故） |
|
||||
| 角色 | 切换/创建/合并分支 | 直接 push main | 修改他人模块 | force push 任何分支 |
|
||||
| ---------- | ------------------ | -------------- | ----------------------------- | -------------------------------- |
|
||||
| 开发 AI | ❌ | ❌ | ❌ | ❌ |
|
||||
| 协调 AI | ❌ | ❌ | ✅（shared-proto/infra/docs） | ❌ |
|
||||
| SRE AI | ❌ | ❌ | ✅（仅 infra） | ❌ |
|
||||
| 人类决策者 | ✅ | ✅（通过合并） | ✅（审批后） | ⚠️（仅事故，--force-with-lease） |
|
||||
|
||||
> 所有 AI 角色均**无分支管理权限**。AI 只在自己被分配的分支上 `git add` → `git commit`，之后通知人类合并。
|
||||
|
||||
### 10.3 敏感文件保护
|
||||
|
||||
@@ -581,29 +671,40 @@ git push origin main
|
||||
- `.github/workflows/`（CI 配置）
|
||||
- `.trae/rules/project_rules.md`（项目规则）
|
||||
|
||||
AI 修改这些文件后，必须在通知人类合并时**显式说明**修改了敏感文件，等待人类决策者额外审批。
|
||||
|
||||
---
|
||||
|
||||
## 11. 发布流程
|
||||
|
||||
> 不再使用 tag 发布与 release 分支。发布由 push main 触发 CI 自动部署。详见 [Git 工作流](./git-workflow.md) §7。
|
||||
> 发布由**人类决策者合并分支到 main**触发 CI 自动部署。详见 [Git 工作流](./git-workflow.md) §7。
|
||||
|
||||
### 11.1 版本号规则
|
||||
|
||||
- 平台版本：`v{阶段}.{迭代}.{patch}`（仅记录，不打 git tag）
|
||||
- 服务版本：`{service}:{semver}`（每服务 VERSION 文件）
|
||||
|
||||
### 11.2 发布步骤（CI 自动）
|
||||
### 11.2 发布步骤（人类决策者触发 CI）
|
||||
|
||||
```bash
|
||||
# 开发 AI 直接 push main → CI 自动触发 quality + deploy
|
||||
git push origin main
|
||||
# 人类决策者执行（AI 不执行）
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git merge feat/<branch> # 合并已审查的分支
|
||||
git push origin main # CI 自动触发 quality + deploy
|
||||
|
||||
# 回滚（紧急）
|
||||
# 回滚（紧急，人类决策者执行）
|
||||
git revert <bad-commit>
|
||||
git push origin main
|
||||
# 或协调 AI 用 workflow_dispatch 指定稳定 commit_sha
|
||||
# 或用 workflow_dispatch 指定稳定 commit_sha
|
||||
```
|
||||
|
||||
### 11.3 AI 在发布流程中的角色
|
||||
|
||||
- AI 完成分支开发与本地校验后，通知人类决策者合并
|
||||
- AI 不直接触发发布（不 push main）
|
||||
- AI 监控 CI 结果（若 CI 失败，在新分支上修复并通知人类合并）
|
||||
|
||||
---
|
||||
|
||||
## 12. 快速参考卡
|
||||
@@ -611,47 +712,69 @@ git push origin main
|
||||
### 开发 AI 日常工作流
|
||||
|
||||
```bash
|
||||
# 同步 main
|
||||
git pull --rebase origin main
|
||||
# 1. 确认当前分支（人类已分配，AI 不切换）
|
||||
git branch --show-current
|
||||
|
||||
# 开发 → 校验 → 提交（只改自己模块目录）
|
||||
# 2. 开发 → 校验 → 提交（只改自己模块目录）
|
||||
pnpm run lint && pnpm run typecheck
|
||||
git add services/<my-service>/
|
||||
git commit -m "feat(<scope>): <subject>
|
||||
git commit -m "feat(<scope>): <subject>"
|
||||
|
||||
---
|
||||
# 3. 通知人类决策者合并
|
||||
# "分支 <branch>，commit <sha>，请审查合并"
|
||||
|
||||
AI-Agent: <ai-id> (<module>)
|
||||
Coord: coord"
|
||||
|
||||
# push 前同步 + 直接 push main
|
||||
git pull --rebase origin main
|
||||
git push origin main
|
||||
|
||||
# 等待事后 review，问题用后续 commit 或 git revert 修正
|
||||
# 4. 等待人类合并；若需修复 review 问题，在同一分支后续 commit
|
||||
# 修复后再次通知人类合并
|
||||
```
|
||||
|
||||
**禁止执行**（人类决策者操作）：
|
||||
|
||||
- `git checkout -b` / `git switch` / `git branch` — 创建/切换分支
|
||||
- `git merge` — 合并分支
|
||||
- `git push origin main` — 推送到 main
|
||||
- `git push --force` / `--force-with-lease` — 强制推送
|
||||
|
||||
### 协调 AI 日常工作流
|
||||
|
||||
```bash
|
||||
# 查看最新 commit
|
||||
git pull --rebase origin main
|
||||
# 查看最新合并到 main 的 commit
|
||||
git pull origin main
|
||||
git log --oneline -10
|
||||
|
||||
# 事后审查 commit
|
||||
# 事后审查 main 上新合并的 commit
|
||||
git log -p -1
|
||||
# 评论要求修正，或严重问题 git revert
|
||||
# 评论要求修正，或通知人类决策者 revert
|
||||
|
||||
# 紧急回滚部署
|
||||
# 紧急回滚部署（建议人类决策者执行）
|
||||
# workflow_dispatch 指定 commit_sha（见 project_rules §15.5）
|
||||
```
|
||||
|
||||
### 人类决策者日常工作流
|
||||
|
||||
```bash
|
||||
# 为任务创建分支并分配给 AI
|
||||
git checkout main && git pull origin main
|
||||
git checkout -b feat/<task-name>
|
||||
# 通知对应 AI：在 feat/<task-name> 上工作
|
||||
|
||||
# AI 通知合并后，审查并合并
|
||||
git log main..feat/<task-name> --oneline
|
||||
git diff main...feat/<task-name>
|
||||
git checkout main
|
||||
git merge feat/<task-name>
|
||||
git push origin main # CI 自动触发
|
||||
|
||||
# 删除已合并分支
|
||||
git branch -d feat/<task-name>
|
||||
git push origin --delete feat/<task-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 相关文档
|
||||
|
||||
- [AI 分配方案](../architecture/ai-allocation.md) — 架构设计外包 AI 分配与三阶段流程
|
||||
- [Git 工作流](./git-workflow.md) — 提交规范、直接 push main、事后 review、CODEOWNERS
|
||||
- [Git 工作流](./git-workflow.md) — 提交规范、分支管理、事后 review、CODEOWNERS
|
||||
- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
|
||||
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束（§10 按需阅读架构、§14 多 AI 协作）
|
||||
- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 模块与依赖关系
|
||||
@@ -662,7 +785,8 @@ git log -p -1
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1.0 | 2026-07-08 | 基线发布：角色定义、分支策略、PR 流程、审核合并、跨模块变更、通信约定 |
|
||||
| 2.0 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：全面改为直接 push main；新增 §2.1 严格模块边界（禁止阅读他人模块文档与历史日志）；新增 §2.2 架构按需阅读（模块开发只读模块架构）；§4 改为事后 review；§5 跨模块变更改为依次直接 push；移除原 §3 分支命名/§5 PR 流程/§6 审核合并/§10 分支冲突等章节；§9.3 禁止跨模块工作日志 |
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1.0 | 2026-07-08 | 基线发布：角色定义、分支策略、PR 流程、审核合并、跨模块变更、通信约定 |
|
||||
| 2.0 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：全面改为直接 push main；新增 §2.1 严格模块边界（禁止阅读他人模块文档与历史日志）；新增 §2.2 架构按需阅读（模块开发只读模块架构）；§4 改为事后 review；§5 跨模块变更改为依次直接 push；移除原 §3 分支命名/§5 PR 流程/§6 审核合并/§10 分支冲突等章节；§9.3 禁止跨模块工作日志 |
|
||||
| 2.1 | 2026-07-10 | 恢复分支开发模式，关键变化：分支由人类决策者创建/合并，AI 禁止执行 `git checkout -b`/`git switch`/`git branch`/`git merge`/`git push origin main`；§3 改为"分支开发规则"，新增禁止命令清单；AI 提交流程止步于 `git commit`，之后通知人类合并；移除 commit message 的 AI 身份标注要求（§3.2、§9.3）；§4 review 依据改为分支 commit history；§5 跨模块变更改为各自分支完成、人类按顺序合并；§6 多 AI 并行改为各 AI 在各自分支、路径隔离；§7/§8 更新为分支模式示例与问题；§10 权限表更新（所有 AI 无分支管理权限）；§11 发布改为人类合并分支触发 CI；§12 快速参考卡更新 |
|
||||
|
||||
Reference in New Issue
Block a user