Edu/docs/standards/multi-ai-collaboration.md

# 多 AI 协作开发指南（Multi-AI Collaboration Guide）

> 版本：1.0
> 日期：2026-07-08
> 适用范围：Edu 微服务项目多 Agent 并行开发
> 关联文档：[Git 工作流](./git-workflow.md)、[项目规则](../../.trae/rules/project_rules.md)、[004 架构影响地图](../architecture/004_architecture_impact_map.md)、[CODEOWNERS](../../.github/CODEOWNERS)

---

## 1. 总体模式

### 1.1 角色定义

| 角色                          | 职责                                         | 数量 | 备注                |
| ----------------------------- | -------------------------------------------- | ---- | ------------------- |
| **协调 AI（Coordinator AI）** | PR 审核、合并、冲突仲裁、分支管理、发布      | 1    | 不直接写业务代码    |
| **开发 AI（Dev AI）**         | 按模块分工，写代码、提 PR                    | N    | 每个负责 1-2 个模块 |
| **人类决策者（Human）**       | 架构决策、Breaking Change 审批、最终发布确认 | 1    | 只在关键节点介入    |

### 1.2 工作流总览

```
开发 AI-A (classes模块)        开发 AI-B (iam模块)         协调 AI
     │                              │                        │
     │ 1.拉取最新 main              │ 1.拉取最新 main          │
     │ 2.创建特性分支               │ 2.创建特性分支            │
     │ 3.开发+提交                  │ 3.开发+提交              │
     │ 4.推送+创建 PR               │ 4.推送+创建 PR            │
     │──────────────────────────────────────────────────────→│
     │                              │                        │ 5.CI校验
     │                              │                        │ 6.代码审核
     │                              │                        │ 7.合并到 main
     │                              │                        │ 8.通知开发 AI 同步
     │←─────────────────────────────────────────────────────│
     │ 9.拉取最新 main              │                        │
```

---

## 2. 模块分工矩阵

### 2.1 模块清单与 AI 分配

每个 AI 负责一个"限界上下文"，避免跨模块修改导致冲突。

| 模块           | scope            | 路径                      | 负责阶段 | 建议 AI 数   |
| -------------- | ---------------- | ------------------------- | -------- | ------------ |
| api-gateway    | `api-gateway`    | `services/api-gateway/`   | P1       | 1            |
| classes        | `classes`        | `services/classes/`       | P1       | 1            |
| teacher-portal | `teacher-portal` | `apps/teacher-portal/`    | P1-P2    | 1            |
| iam            | `iam`            | `services/iam/`           | P2       | 1            |
| teacher-bff    | `teacher-bff`    | `services/teacher-bff/`   | P2       | 1            |
| core-edu       | `core-edu`       | `services/core-edu/`      | P3       | 1            |
| content        | `content`        | `services/content/`       | P4       | 1            |
| data-ana       | `data-ana`       | `services/data-ana/`      | P4       | 1            |
| msg            | `msg`            | `services/msg/`           | P5       | 1            |
| ai             | `ai`             | `services/ai/`            | P5       | 1            |
| push-gateway   | `push-gateway`   | `services/push-gateway/`  | P5       | 1            |
| shared-proto   | `shared-proto`   | `packages/shared-proto/`  | 跨阶段   | 协调 AI 维护 |
| shared-tokens  | `shared-tokens`  | `packages/shared-tokens/` | 跨阶段   | 协调 AI 维护 |
| infra          | `infra`          | `infra/`                  | 跨阶段   | 1 (SRE AI)   |
| docs           | `docs`           | `docs/`                   | 跨阶段   | 协调 AI 维护 |

### 2.2 分工原则

1. **单一负责制**：每个模块只有一个 AI 负责，避免并行修改同一文件
2. **契约集中管理**：`shared-proto` 由协调 AI 维护，开发 AI 只读引用
3. **跨模块变更拆分**：需要修改多个模块时，拆成多个 PR，按依赖顺序合并
4. **基础设施独立**：`infra/` 由 SRE AI 专门负责，业务 AI 不直接修改

---

## 3. 分支策略

### 3.1 分支命名规范

```
<type>/<scope>-<task-id>-<ai-id>
```

| 字段      | 说明                                        | 示例             |
| --------- | ------------------------------------------- | ---------------- |
| `type`    | feat / fix / refactor / docs / chore / test | `feat`           |
| `scope`   | 模块名（见 §2.1）                           | `classes`        |
| `task-id` | 任务简短描述（kebab-case）                  | `add-pagination` |
| `ai-id`   | AI 标识符（避免多 AI 同名冲突）             | `ai01`           |

**完整示例**：

- `feat/classes-add-pagination-ai01`
- `fix/api-gateway-redirect-loop-ai02`
- `docs/git-workflow-update-coord`

### 3.2 分支生命周期

1. **创建**：从最新 `main` 拉取：`git checkout main && git pull && git checkout -b feat/classes-xxx-ai01`
2. **开发**：在特性分支上提交（遵循 Conventional Commits）
3. **推送**：`git push -u origin feat/classes-xxx-ai01`
4. **合并后删除**：PR 合并后，删除本地与远程特性分支

> 特性分支寿命 ≤ 3 天（见 git-workflow.md §1）。超期需 rebase 最新 main。

### 3.3 多 AI 分支隔离规则

- **禁止多 AI 共用同一分支**
- **禁止直接 push 到 `main`**（由协调 AI 通过 PR 合并）
- **跨模块变更**：各自在模块分支开发，最后由协调 AI 按依赖顺序合并

---

## 4. 推送与提交流程

### 4.1 提交规范（Conventional Commits）

```bash
git commit -m "feat(classes): 新增班级分页查询"
git commit -m "fix(api-gateway): 修复尾斜杠重定向循环"
git commit -m "docs(standards): 更新多AI协作文档"
```

**scope 必须匹配 `.commitlintrc.js` 的 scope-enum**（26 项，见 git-workflow.md §3.3）。

### 4.2 标准推送流程

开发 AI 执行：

```bash
# 1. 确认在正确的特性分支
git branch --show-current
# 输出：feat/classes-add-pagination-ai01

# 2. 拉取最新 main（rebase 保持线性）
git fetch origin
git rebase origin/main

# 3. 解决冲突（如有）
# 编辑冲突文件 → git add → git rebase --continue

# 4. 本地校验（强制，见 project_rules §7）
pnpm run lint        # TS 服务
pnpm run typecheck   # TS 服务
cd services/api-gateway && go vet ./... && go build ./...  # Go 服务

# 5. 推送
git push -u origin feat/classes-add-pagination-ai01

# 6. 创建 PR（见 §5）
```

### 4.3 多 AI 推送冲突处理

当多个 AI 的 PR 修改了同一文件（如 `package.json`、`004_architecture_impact_map.md`）：

1. **先合并的 PR 正常合并**
2. **后合并的 PR 需 rebase**：
   ```bash
   git fetch origin
   git rebase origin/main
   # 解决冲突
   git push --force-with-lease  # 安全强推（仅自己的分支）
   ```
3. **协调 AI 仲裁**：若冲突涉及架构决策，由协调 AI 决定保留方案

> **禁止 `git push --force` 到 main 或他人分支**。只允许 `--force-with-lease` 到自己的特性分支。

---

## 5. PR 流程

### 5.1 创建 PR

推送后，开发 AI 通过 Git 平台（GitHub/Gitea）创建 PR：

```bash
# 使用 gh CLI（GitHub）
gh pr create \
  --title "feat(classes): 新增班级分页查询" \
  --body "## 变更说明
- 新增 GET /api/v1/classes?page=&size= 分页参数
- 响应增加 total/hasMore 字段

## 变更类型
- [x] feat（新功能）

## 影响范围
- [x] classes 服务

## 测试
- [x] 单元测试通过
- [x] 本地联调验证

## 校验
- [x] pnpm run lint
- [x] pnpm run typecheck
" \
  --base main \
  --head feat/classes-add-pagination-ai01
```

### 5.2 PR 标题规范

PR 标题必须与首个 commit 的 subject 一致（Squash Merge 时自动取首个 commit）：

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

**示例**：

- `feat(classes): 新增班级分页查询`
- `fix(api-gateway): 修复尾斜杠重定向循环`

### 5.3 PR 模板

使用 `.github/pull_request_template.md`（已存在）。必填项：

- 变更说明
- 变更类型
- 影响范围
- 测试情况
- 按语言校验结果
- 文档同步（arch:scan、CODEOWNERS）

### 5.4 PR 标注 AI 身份

在 PR 描述末尾追加（用于统计与审计）：

```markdown
---

**AI Agent**: ai01 (classes-module)
**Branch**: feat/classes-add-pagination-ai01
**Coordinator**: coord-ai
```

---

## 6. 代码审核与合并

### 6.1 Reviewer 分配

由 `.github/CODEOWNERS` 自动分配：

| 模块         | 自动 Reviewer           | 实际映射 |
| ------------ | ----------------------- | -------- |
| classes      | `@edu-platform/classes` | 协调 AI  |
| api-gateway  | `@edu-platform/gateway` | 协调 AI  |
| shared-proto | `@edu-platform/arch`    | 协调 AI  |
| infra        | `@edu-platform/sre`     | SRE AI   |

> 当前 `@edu-platform/*` 为占位符。多 AI 场景下，协调 AI 账号加入对应 team 即可自动收到 review 请求。

### 6.2 审核 checklist

协调 AI 审核 PR 时检查：

- [ ] **Commit 格式**：符合 Conventional Commits
- [ ] **Scope 正确**：scope 与修改的模块一致
- [ ] **架构合规**：无跨层依赖、无直接访问他人 DB
- [ ] **权限校验**：Controller 有 `@RequirePermission()`
- [ ] **设计令牌**：无硬编码颜色/字体（project_rules §3.10）
- [ ] **ESM 规则**：相对 import 带 `.js` 后缀（TS 服务）
- [ ] **契约同步**：proto 变更已同步 shared-proto
- [ ] **文档同步**：arch.db 已更新、004 已同步（如涉及）
- [ ] **CI 通过**：lint / typecheck / go vet / ruff 全绿
- [ ] **测试覆盖**：关键逻辑有单测

### 6.3 合并策略

| 策略                     | 适用场景                             | 操作                   |
| ------------------------ | ------------------------------------ | ---------------------- |
| **Squash Merge**（默认） | 单 commit 或多个小 commit 合并为一个 | `gh pr merge --squash` |
| **Rebase Merge**         | 多个有意义的 commit 需保留历史       | `gh pr merge --rebase` |
| **Merge Commit**（禁止） | —                                    | 不允许                 |

> 项目规则 git-workflow.md §1.4：**禁止 Merge Commit**，保持 main 历史线性。

### 6.4 合并流程（协调 AI 执行）

```bash
# 1. 确认 CI 通过
gh pr checks <PR-NUMBER>

# 2. 确认 review 通过（CODEOWNERS 已 approve）
gh pr view <PR-NUMBER> --json reviews

# 3. Squash 合并（删除源分支）
gh pr merge <PR-NUMBER> --squash --delete-branch

# 4. 通知开发 AI 同步本地 main
# （通过 commit message 或 issue 评论）
```

### 6.5 合并后同步

开发 AI 收到合并通知后：

```bash
# 切回 main
git checkout main

# 拉取最新（含已合并的 PR）
git pull origin main

# 删除本地特性分支
git branch -d feat/classes-add-pagination-ai01

# 开始下一个任务：从最新 main 拉新分支
git checkout -b feat/classes-next-task-ai01
```

---

## 7. 多 AI 并行开发流程

### 7.1 启动并行任务

人类决策者分配任务给多个 AI：

```
任务 1：classes 服务新增分页查询      → 开发 AI-A (ai01)
任务 2：api-gateway 新增限流规则      → 开发 AI-B (ai02)
任务 3：teacher-portal 优化班级列表   → 开发 AI-C (ai03)
```

### 7.2 并行执行

每个 AI 独立工作，互不干扰：

```bash
# AI-A
git checkout -b feat/classes-add-pagination-ai01
# ... 开发 ...
git push -u origin feat/classes-add-pagination-ai01
gh pr create --title "feat(classes): 新增班级分页查询" ...

# AI-B（同时）
git checkout -b feat/api-gateway-rate-limit-ai02
# ... 开发 ...
git push -u origin feat/api-gateway-rate-limit-ai02
gh pr create --title "feat(api-gateway): 新增 IP 级限流规则" ...

# AI-C（同时）
git checkout -b feat/teacher-portal-class-list-ux-ai03
# ... 开发 ...
```

### 7.3 顺序合并（有依赖时）

若 PR 间有依赖（如 AI-C 依赖 AI-A 的接口），协调 AI 按顺序合并：

1. 合并 AI-A 的 PR（classes 分页接口）
2. AI-C rebase 最新 main，解决冲突，更新 PR
3. 合并 AI-C 的 PR（前端调用新接口）

### 7.4 冲突预防

1. **契约先行**：proto 变更先合并，再合并依赖它的服务
2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 PR 描述 @ 所有关联模块 AI
3. **频繁同步**：每天至少 `git pull origin main` 一次，避免长期分叉

---

## 8. 跨模块变更流程

### 8.1 变更拆分原则

修改涉及多模块时，按依赖顺序拆成多个 PR：

```
原始任务：classes 服务新增"班级导入"功能
涉及：
  1. shared-proto 新增 ImportClassesRequest message
  2. classes 服务实现 import 接口
  3. api-gateway 路由 /api/v1/classes/import
  4. teacher-portal 前端上传按钮
```

### 8.2 拆分与合并顺序

| 顺序 | PR                                              | scope          | 负责人    | 依赖 |
| ---- | ----------------------------------------------- | -------------- | --------- | ---- |
| 1    | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto   | 协调 AI   | 无   |
| 2    | `feat(classes): 实现班级批量导入`               | classes        | 开发 AI-A | PR-1 |
| 3    | `feat(api-gateway): 新增 import 路由`           | api-gateway    | 开发 AI-B | PR-2 |
| 4    | `feat(teacher-portal): 新增班级导入按钮`        | teacher-portal | 开发 AI-C | PR-3 |

协调 AI 按顺序合并，每合并一个，后续 PR 的开发 AI rebase 最新 main。

### 8.3 Breaking Change 流程

涉及 Breaking Change（proto 字段删除、API 签名变更）：

1. **人类决策者审批**：在 issue 中讨论，获批准后才开发
2. **版本号升级**：proto 加 `v2` 后缀，服务同时支持 v1/v2 过渡期
3. **迁移文档**：更新 `MIGRATION_GUIDE.md`
4. **协调 AI 通知所有相关 AI**：在 PR 描述中列出影响范围

---

## 9. 完整工作流示例

### 9.1 场景：开发 AI-A 为 classes 新增分页查询

```bash
# ============ 开发 AI-A ============

# 1. 同步 main
git checkout main
git pull origin main

# 2. 创建特性分支
git checkout -b feat/classes-add-pagination-ai01

# 3. 开发
# 编辑 services/classes/src/classes/classes.controller.ts
# 编辑 services/classes/src/classes/classes.service.ts
# 编辑 services/classes/src/classes/classes.repository.ts

# 4. 本地校验
pnpm --filter @edu/classes-service lint
pnpm --filter @edu/classes-service typecheck
pnpm --filter @edu/classes-service test

# 5. 架构扫描（若新增了导出函数/路由）
pnpm run arch:scan

# 6. 提交
git add services/classes/
git commit -m "feat(classes): 新增班级分页查询

- GET /api/v1/classes 支持 page、size 参数
- 响应增加 total、hasMore 字段
- 单测覆盖分页逻辑"

# 7. 推送
git push -u origin feat/classes-add-pagination-ai01

# 8. 创建 PR
gh pr create \
  --title "feat(classes): 新增班级分页查询" \
  --body "..." \
  --base main

# ============ 协调 AI ============

# 9. 收到 PR 通知，审核
gh pr view <PR-NUMBER>
gh pr checks <PR-NUMBER>

# 10. 代码审核（见 §6.2 checklist）
# 若需修改，评论要求开发 AI-A 修改

# 11. 合并
gh pr merge <PR-NUMBER> --squash --delete-branch

# 12. 通知开发 AI-A
# 评论："已合并，请同步本地 main"

# ============ 开发 AI-A ============

# 13. 同步
git checkout main
git pull origin main
git branch -d feat/classes-add-pagination-ai01
```

---

## 10. 常见问题与解决方案

### 10.1 多 AI 修改同一文件冲突

**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖。

**解决**：

1. AI-A 的 PR 先合并
2. AI-B 执行：
   ```bash
   git fetch origin
   git rebase origin/main
   # 解决 package.json 冲突（保留两边依赖）
   git add package.json
   git rebase --continue
   git push --force-with-lease
   ```
3. 协调 AI 重新审核

### 10.2 CI 失败但本地通过

**场景**：开发 AI 本地 lint 通过，CI 报错。

**排查**：

1. 检查 Node/Go/pnpm 版本是否一致（见 local-dev-runbook §1）
2. 检查 `pnpm-lock.yaml` 是否最新（`pnpm install --frozen-lockfile`）
3. 检查环境变量是否齐全（`.env` vs CI secrets）

**修复后**：

```bash
git add <fixed-files>
git commit -m "fix(classes): 修复 CI lint 失败"
git push
```

### 10.3 husky pre-commit hook 失败

**场景**：commit 时 hook 报错（lint-staged、commitlint）。

**排查**：

1. commitlint：检查 commit message 格式（type 小写、scope 在 enum 内、subject 不大写开头）
2. lint-staged：检查暂存文件是否通过 ESLint/gofmt
3. husky 9 Windows bug：若 pre-push hook "Bad file descriptor"，见 known-issues

**修复**：修正后重新 `git commit`，不要用 `--no-verify` 跳过。

### 10.4 proto 变更导致下游编译失败

**场景**：shared-proto 合并后，classes 服务 `buf generate` 报错。

**解决**：

1. 协调 AI 合并 proto PR 前，先在 PR 评论中通知所有依赖服务的 AI
2. 下游 AI 在自己的分支 rebase 最新 main 后重新 `buf generate`
3. 更新生成代码并提交：
   ```bash
   git add packages/shared-proto/gen/
   git commit -m "chore(shared-proto): 重新生成 TS 类型"
   ```

### 10.5 分支长期未合并（超 3 天）

**场景**：特性分支超过 3 天未合并。

**处理**：

1. rebase 最新 main：`git rebase origin/main`
2. 解决冲突后 `git push --force-with-lease`
3. 若仍无法合并，协调 AI 介入评估是否拆分 PR

### 10.6 误推到 main

**场景**：开发 AI 误将 commit 推到 main。

**修复**（协调 AI 执行）：

```bash
# 1. 确认误推的 commit
git log origin/main -5

# 2. 回退（保留误推 commit 到临时分支）
git checkout origin/main -b temp/backup-mispush
git checkout main
git reset --hard origin/main~1  # 回退 1 个 commit

# 3. 强推（仅协调 AI 有权限）
git push --force-with-lease origin main

# 4. 通知开发 AI 从 temp 分支重新提 PR
```

> **禁止开发 AI 自行 force push main**。只有协调 AI 有权操作。

### 10.7 AI 身份冲突（同名分支）

**场景**：两个 AI 都叫 "ai01"，创建了同名分支。

**预防**：每个 AI 启动前分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。

**修复**：后启动的 AI 重命名分支：

```bash
git branch -m feat/classes-xxx-ai01 feat/classes-xxx-ai01b
git push -u origin feat/classes-xxx-ai01b
```

---

## 11. AI 协作通信约定

### 11.1 通信渠道

| 场景     | 方式                          |
| -------- | ----------------------------- |
| PR 审核  | PR 评论（`@ai01 请修改 xxx`） |
| 任务分配 | Issue（`@ai01 负责实现 xxx`） |
| 紧急通知 | PR 评论 + @ 相关人员          |
| 架构讨论 | Issue 标签 `discussion`       |

### 11.2 PR 评论规范

协调 AI 审核评论格式：

```
## 审核结果：需修改 / 通过 / 拒绝

### 需修改项
1. [classes.controller.ts:42] 缺少 @RequirePermission() 装饰器
2. [classes.service.ts:88] 返回值未标注 Promise<T>

### 建议
- 考虑抽取分页逻辑到 shared-ts

---
协调 AI（coord）
```

### 11.3 AI 工作日志

每个 AI 完成任务后，在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加（project_rules §9.3）：

```markdown
| 日期             | 模块    | 做了什么 + 学到什么                             |
| ---------------- | ------- | ----------------------------------------------- |
| 2026-07-08 14:00 | classes | 实现分页查询，学到 Drizzle 的 limit/offset 用法 |
```

---

## 12. 安全与权限

### 12.1 分支保护规则（main）

- **禁止直接 push**：必须通过 PR
- **必须 PR review**：至少 1 人（CODEOWNERS 自动分配）
- **必须 CI 通过**：lint / typecheck / build
- **禁止 force push**：开发 AI 无权，仅协调 AI 在事故时操作

### 12.2 AI 账号权限

| 角色    | push 特性分支 | 创建 PR | 合并 PR     | push main | force push main |
| ------- | ------------- | ------- | ----------- | --------- | --------------- |
| 开发 AI | ✅            | ✅      | ❌          | ❌        | ❌              |
| 协调 AI | ✅            | ✅      | ✅          | ❌        | ⚠️（仅事故）    |
| SRE AI  | ✅（infra）   | ✅      | ✅（infra） | ❌        | ⚠️（仅事故）    |

### 12.3 敏感文件保护

以下文件修改需人类决策者额外审批：

- `.env`、`.env.example`（密钥相关）
- `infra/security/secrets.example.env`
- `infra/k8s/`（生产部署）
- `.github/workflows/`（CI 配置）

---

## 13. 发布流程

### 13.1 版本号规则（见 git-workflow.md §7）

- 平台版本：`v{阶段}.{迭代}.{patch}`（如 `v1.2.0`）
- 服务版本：`{service}:{semver}`（如 `classes:1.0.1`）

### 13.2 发布步骤（协调 AI 执行）

```bash
# 1. 确认 main 稳定（CI 全绿）
gh run list --branch main --limit 5

# 2. 打 tag
git tag -a v1.2.0 -m "P1 阶段第 2 次迭代发布"
git push origin v1.2.0

# 3. 触发 CI 构建镜像
# （CI 由 tag push 触发，见 .github/workflows/）

# 4. 人类决策者确认部署到生产
```

### 13.3 回滚（见 git-workflow.md §8）

```bash
# K8s 回滚
kubectl rollout undo deployment/api-gateway -n edu-system

# Git 回退（紧急）
git revert <bad-commit>
git push origin main
```

---

## 14. 快速参考卡

### 开发 AI 日常工作流

```bash
# 拉新分支
git checkout main && git pull && git checkout -b feat/<scope>-<task>-<ai-id>

# 开发 → 校验 → 提交
pnpm run lint && pnpm run typecheck
git add . && git commit -m "feat(<scope>): <subject>"

# 推送 → 创建 PR
git push -u origin feat/<scope>-<task>-<ai-id>
gh pr create --title "feat(<scope>): <subject>" --body "..."

# 等待审核 → 修改 → 重新推送
# （协调 AI 合并后）
git checkout main && git pull && git branch -d feat/<scope>-<task>-<ai-id>
```

### 协调 AI 日常工作流

```bash
# 查看待审核 PR
gh pr list --state open --reviewer @edu-platform/arch

# 审核
gh pr view <PR-NUMBER>
gh pr checks <PR-NUMBER>

# 合并
gh pr merge <PR-NUMBER> --squash --delete-branch

# 发布
git tag -a v<version> -m "..." && git push origin v<version>
```

---

## 15. 相关文档

- [Git 工作流](./git-workflow.md) — 提交规范、分支策略、CODEOWNERS
- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 模块与依赖关系
- [CODEOWNERS](../../.github/CODEOWNERS) — Reviewer 自动分配
- [PR 模板](../../.github/pull_request_template.md) — PR 必填项
- [known-issues](../troubleshooting/known-issues.md) — 已知问题速查