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

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

版本：1.0 日期：2026-07-08 适用范围：Edu 微服务项目多 Agent 并行开发 关联文档：Git 工作流、项目规则、004 架构影响地图、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）

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 执行：

# 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：

   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：

# 使用 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 描述末尾追加（用于统计与审计）：

---

**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 执行）

# 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 收到合并通知后：

# 切回 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 独立工作，互不干扰：

# 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 新增分页查询

# ============ 开发 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 执行：

   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）

修复后：

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. 更新生成代码并提交：

   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 执行）：

# 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 重命名分支：

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）：

| 日期             | 模块    | 做了什么 + 学到什么                             |
| ---------------- | ------- | ----------------------------------------------- |
| 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 执行）

# 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）

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

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

---

14. 快速参考卡

开发 AI 日常工作流

# 拉新分支
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 日常工作流

# 查看待审核 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 工作流 — 提交规范、分支策略、CODEOWNERS
• 本地启动手册 — 手动启动服务
• 项目规则 — 强制约束
• 004 架构影响地图 — 模块与依赖关系
• CODEOWNERS — Reviewer 自动分配
• PR 模板 — PR 必填项
• known-issues — 已知问题速查