793 lines
36 KiB
Markdown
793 lines
36 KiB
Markdown
# 多 AI 协作开发指南（Multi-AI Collaboration Guide）
|
||
|
||
> 版本：2.1
|
||
> 日期：2026-07-10
|
||
> 状态：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 默认多 AI 协作
|
||
|
||
本项目所有 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.3 工作流总览（分支开发，AI 不切换分支）
|
||
|
||
```
|
||
人类决策者 开发 AI-A (classes 分支) 开发 AI-B (iam 分支) 协调 AI
|
||
│ 1.为每个任务创建分支 │ │ │
|
||
│ 2.分配分支给对应 AI │ │ │
|
||
│ ──────────────────────────────────►│ │ │
|
||
│ │ 3.在分配分支上开发 │ │
|
||
│ │ 4.本地校验 │ │
|
||
│ │ 5.git add → commit │ │
|
||
│ │ 6.通知人类合并 │ │
|
||
│ ◄───────────────────────────────────│ │ │
|
||
│ 7.人类审查 + 合并分支到 main │ │ │
|
||
│ 8.CI 自动校验（main 触发） │ │ │
|
||
│ │ │ │ 9.事后审查 commit
|
||
```
|
||
|
||
**关键原则**：
|
||
|
||
- **分支由人类决策者创建与合并**，AI 不执行任何分支切换/创建/合并命令
|
||
- AI 的操作止步于 `git commit`，之后**通知人类合并**
|
||
- 默认多 AI 协作，多 AI 在各自分支并行，路径隔离避免冲突
|
||
- Git 操作细节见 [Git 工作流](./git-workflow.md)
|
||
|
||
---
|
||
|
||
## 2. 模块分工与边界
|
||
|
||
### 2.1 严格模块边界（强制）
|
||
|
||
> **核心原则**：每个 AI 只修改自己负责的目录，只读自己模块的文档，不越界阅读他人模块的内部实现与历史记录。
|
||
|
||
1. **修改边界**：AI 只能修改自己负责的 `services/<my-service>/` 或 `apps/<my-app>/` 目录，禁止越界修改他人模块源码
|
||
2. **阅读边界**：AI 阅读文档时只读自己模块的 README/设计文档/known-issues 分区，**禁止阅读其他 AI 模块的内部文档和历史工作日志**（避免被前任同名 AI 的过时方案/审计结果误导）
|
||
3. **契约边界**：需要确认跨模块协同时，只读对方的对外接口（proto message / API 端点 / Kafka 事件 schema），不读对方内部实现
|
||
4. **单一负责制**：每个模块（限界上下文）只有一个 AI 负责，禁止并行修改同一模块
|
||
|
||
### 2.2 架构文档按需阅读（强制）
|
||
|
||
> **不再要求所有 AI 通读全部架构文档**。按工作范围按需阅读：
|
||
|
||
| 工作类型 | 必读文档 |
|
||
| ------------------ | ----------------------------------------------------------------------- |
|
||
| **模块开发** | 自己模块的 README + 004 对应模块章节 + project_rules + coding-standards |
|
||
| **全局工作** | （协调 AI/SRE）004 全文 + project_rules 全文 + 所有服务 README 概览 |
|
||
| **跨模块契约** | shared-proto 相关 proto + 上下游模块的对外接口（API/事件） |
|
||
| **功能开发强依赖** | 涉及的架构章节必须读，不读不写 |
|
||
| **文档书写** | 待写文档涉及的架构章节必须读 |
|
||
|
||
> 模块开发不需要读全部 7 份全局文档。只在"功能开发/文档书写等强依赖场景"才必须读对应架构。
|
||
|
||
### 2.3 模块完整清单
|
||
|
||
| 类别 | 服务名 | scope | 路径 | 阶段 | 语言 |
|
||
| ---- | -------------- | ---------------- | ------------------------ | ------ | -------- |
|
||
| 网关 | api-gateway | `api-gateway` | `services/api-gateway/` | P1 | Go |
|
||
| 网关 | push-gateway | `push-gateway` | `services/push-gateway/` | P5 | Go |
|
||
| BFF | teacher-bff | `teacher-bff` | `services/teacher-bff/` | P2 | TS |
|
||
| BFF | student-bff | `student-bff` | `services/student-bff/` | P3 | TS |
|
||
| BFF | parent-bff | `parent-bff` | `services/parent-bff/` | P4 | TS |
|
||
| 业务 | iam | `iam` | `services/iam/` | P2 | TS |
|
||
| 业务 | core-edu | `core-edu` | `services/core-edu/` | P3 | TS |
|
||
| 业务 | content | `content` | `services/content/` | P4 | TS |
|
||
| 业务 | msg | `msg` | `services/msg/` | P5 | TS |
|
||
| 业务 | data-ana | `data-ana` | `services/data-ana/` | P4 | Python |
|
||
| 业务 | ai | `ai` | `services/ai/` | P5 | Python |
|
||
| 前端 | teacher-portal | `teacher-portal` | `apps/teacher-portal/` | P2 | TS |
|
||
| 前端 | student-portal | `student-portal` | `apps/student-portal/` | P3 | TS |
|
||
| 前端 | parent-portal | `parent-portal` | `apps/parent-portal/` | P4 | TS |
|
||
| 前端 | admin-portal | `admin-portal` | `apps/admin-portal/` | P6 | TS |
|
||
| 共享 | shared-proto | `shared-proto` | `packages/shared-proto/` | 跨阶段 | protobuf |
|
||
| 共享 | shared-ts | `shared-ts` | `packages/shared-ts/` | 跨阶段 | TS |
|
||
| 共享 | shared-go | `shared-go` | `packages/shared-go/` | 跨阶段 | Go |
|
||
| 共享 | shared-py | `shared-py` | `packages/shared-py/` | 跨阶段 | Python |
|
||
| 基础 | infra | `infra` | `infra/` | 跨阶段 | — |
|
||
|
||
### 2.4 当前阶段 AI 分配（7 AI + 1 coord）
|
||
|
||
详见 [AI 分配方案](../architecture/ai-allocation.md#3-ai-分配方案7-ai--1-coord)。摘要如下：
|
||
|
||
| AI | 服务 | 语言 |
|
||
| ----- | ----------------------------------------------------------- | ------ |
|
||
| ai01 | api-gateway、push-gateway | Go |
|
||
| ai02 | iam | TS |
|
||
| ai03 | teacher-bff、core-edu | TS |
|
||
| ai04 | student-bff、parent-bff | TS |
|
||
| ai05 | content、msg | TS |
|
||
| ai06 | data-ana、ai | Python |
|
||
| 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. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序各自在分支完成，人类按顺序合并（见 §5）
|
||
5. **基础设施独立**：`infra/` 由 coord（或 SRE AI）专门负责
|
||
6. **物理路径隔离**：目录级别隔离，多 AI 在各自分支并行几乎零文件冲突
|
||
|
||
### 2.6 架构设计外包三阶段
|
||
|
||
当前项目处于**架构设计外包阶段**，所有 AI 需先完成设计再动手写代码。完整文档见 [AI 分配方案](../architecture/ai-allocation.md)。简述如下：
|
||
|
||
```
|
||
阶段 1：按需理解 → 交付"理解确认书"（只读自己模块相关架构）
|
||
阶段 2：模块架构设计 → 交付"模块架构设计文档"，coord 交叉审查
|
||
阶段 3：按图实施 → 按设计文档写代码，coord 定期巡检一致性
|
||
```
|
||
|
||
**阶段 1 交付物模板**：
|
||
|
||
```markdown
|
||
## 模块理解确认书 — [模块名]
|
||
|
||
### 1. 我在架构中的位置
|
||
|
||
- 层级 / 上下游 / 通信方式
|
||
|
||
### 2. 我的限界上下文
|
||
|
||
- 聚合/实体 / 业务领域（D1-D6）/ 边界外
|
||
|
||
### 3. 我与外部的契约
|
||
|
||
- proto message / API/事件 / 错误码前缀
|
||
|
||
### 4. 我的技术栈
|
||
|
||
### 5. 我的阶段归属（P1-P6）
|
||
|
||
### 6. 黄金模板对齐清单（对照 classes 服务）
|
||
```
|
||
|
||
**阶段 2 交付物模板**：
|
||
|
||
```markdown
|
||
## 模块架构设计文档 — [模块名]
|
||
|
||
### 1. 模块内部分层图
|
||
|
||
### 2. 领域模型（聚合根/实体/值对象）
|
||
|
||
### 3. 数据模型（表/schema/索引/读写分离）
|
||
|
||
### 4. API 设计（端点/权限/请求响应）
|
||
|
||
### 5. 事件设计（发布/消费/Topic）
|
||
|
||
### 6. 横切关注点（权限/错误/可观测/健康/优雅关闭）
|
||
|
||
### 7. 与其他模块的交互点（契约清单）
|
||
|
||
### 8. 风险与假设
|
||
```
|
||
|
||
**coord 交叉审查**：收到全部 7 份设计文档后，检查接口一致性、端口冲突、Topic 重复、错误码重叠、黄金模板对齐。
|
||
|
||
---
|
||
|
||
## 3. 分支开发规则
|
||
|
||
> Git 操作详细规范见 [Git 工作流](./git-workflow.md)。本节仅列多 AI 协作相关要点。
|
||
|
||
### 3.1 分支由人类决策者维护（强制）
|
||
|
||
- **分支创建**：人类决策者为每个任务/模块创建分支并分配给对应 AI
|
||
- **分支合并**：人类决策者负责审查分支并合并到 `main`
|
||
- **AI 禁止执行任何分支管理命令**（见 §3.4 禁止命令清单）
|
||
|
||
AI 接到任务后，**假设人类已为自己分配好当前工作分支**，AI 只需在该分支上工作，不需要（也不允许）切换分支。
|
||
|
||
### 3.2 AI 提交流程（止步于 commit）
|
||
|
||
```bash
|
||
# 1. 确认当前分支（人类已分配，AI 不切换）
|
||
git branch --show-current
|
||
|
||
# 2. 本地校验（强制，按语言）
|
||
pnpm run lint && pnpm run typecheck # TS
|
||
go vet ./... && go build ./... # Go
|
||
ruff check src/ # Python
|
||
|
||
# 3. 提交（Conventional Commits，见 git-workflow.md §2）
|
||
git add services/<my-service>/...
|
||
git commit -m "feat(<scope>): <subject>"
|
||
```
|
||
|
||
提交完成后，AI **通知人类决策者合并**：
|
||
|
||
> "已完成 [模块] 的 [任务]，分支 [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): 新增班级分页查询
|
||
|
||
- GET /api/v1/classes 支持 page、size 参数
|
||
- 响应增加 total、hasMore 字段
|
||
- 单测覆盖分页逻辑
|
||
```
|
||
|
||
### 3.4 AI 禁止命令清单（强制）
|
||
|
||
以下命令**仅人类决策者可执行，AI 严禁执行**：
|
||
|
||
| 命令 | 用途 | 允许执行者 |
|
||
| ------------------------------- | --------------- | ---------------------------------- |
|
||
| `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 | **人类决策者** |
|
||
|
||
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
|
||
|
||
> 代码审查基于分支 commit history 进行。详见 [Git 工作流](./git-workflow.md) §4。
|
||
|
||
### 4.1 review 责任人
|
||
|
||
由 `.github/CODEOWNERS` 确定模块归属（CODEOWNERS 用于分支审查与追溯依据）：
|
||
|
||
- 模块 owner 负责审查涉及自己模块的分支
|
||
- 跨模块变更由协调 AI 审查
|
||
- 基础设施变更由 SRE 审查
|
||
- 人类决策者负责最终合并决策
|
||
|
||
### 4.2 review 依据
|
||
|
||
- 分支 commit history（`git log main..<branch>` 查看分支新增 commit）
|
||
- commit message（Conventional Commits 格式）
|
||
- 分支与 main 的 diff（`git diff main...<branch>`）
|
||
|
||
### 4.3 问题处理
|
||
|
||
- **小问题**：在分支上后续 commit 修正，再次通知人类合并
|
||
- **严重问题**：人类决策者拒绝合并，AI 在分支上 `git revert <commit>` 后重新通知
|
||
- **架构冲突**：由协调 AI 仲裁保留方案，分支上 revert + 新 commit 修正
|
||
- **已合并到 main 的问题**：人类决策者在 main 上 revert，AI 不直接操作 main
|
||
|
||
---
|
||
|
||
## 5. 跨模块变更流程
|
||
|
||
### 5.1 变更拆分原则
|
||
|
||
修改涉及多模块时，各 AI 在各自分支完成开发，**人类决策者按依赖顺序依次合并**（避免下游编译失败）：
|
||
|
||
```
|
||
原始任务：classes 服务新增"班级导入"功能
|
||
涉及：
|
||
1. shared-proto 新增 ImportClassesRequest message
|
||
2. classes 服务实现 import 接口
|
||
3. api-gateway 路由 /api/v1/classes/import
|
||
4. teacher-portal 前端上传按钮
|
||
```
|
||
|
||
### 5.2 分支与合并顺序（强制）
|
||
|
||
| 顺序 | 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 已合并 |
|
||
|
||
> 各 AI 可并行在自己分支开发（基于 main 最新状态），但**人类决策者按顺序合并**：合并第 1 层后，第 2 层 AI 需 `git pull` 同步 main 更新，再通知人类合并。协调 AI 负责监督顺序，避免越级合并导致下游构建失败。
|
||
|
||
### 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**：在 issue 中列出影响范围
|
||
5. **分支合并需人类决策者二次确认**：Breaking Change 分支合并前必须人类决策者签字
|
||
|
||
---
|
||
|
||
## 6. 多 AI 并行开发流程
|
||
|
||
### 6.1 启动并行任务
|
||
|
||
人类决策者为每个任务创建分支并分配给多个 AI：
|
||
|
||
```
|
||
任务 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 并行执行（路径隔离，各自分支）
|
||
|
||
每个 AI 在自己分支上、自己目录内工作，互不干扰：
|
||
|
||
```bash
|
||
# 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-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 级限流规则"
|
||
# 通知人类决策者合并 feat/gw-ratelimit
|
||
```
|
||
|
||
### 6.3 冲突预防
|
||
|
||
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
|
||
# 人类决策者执行（AI 不执行 merge）
|
||
git merge feat/<branch>
|
||
# 若 pnpm-lock.yaml 冲突：
|
||
git checkout --theirs pnpm-lock.yaml
|
||
pnpm install
|
||
git add pnpm-lock.yaml
|
||
git commit
|
||
git push origin main
|
||
```
|
||
|
||
> AI 若发现自己分支的 `pnpm-lock.yaml` 与 main 不一致，应在自己分支上 `pnpm install` 重新生成并 commit，再通知人类合并。
|
||
|
||
---
|
||
|
||
## 7. 完整工作流示例
|
||
|
||
### 场景：开发 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 ============
|
||
|
||
# 2. 确认当前分支（人类已分配，AI 不切换）
|
||
git branch --show-current # 应显示 feat/classes-page
|
||
|
||
# 3. 开发（只改 services/classes/）
|
||
# 编辑 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. 提交（不标注 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>，请审查合并"
|
||
|
||
# ============ 人类决策者 ============
|
||
|
||
# 8. 审查分支
|
||
git log main..feat/classes-page --oneline
|
||
git diff main...feat/classes-page
|
||
|
||
# 9. 合并到 main（AI 不执行此步）
|
||
git checkout main
|
||
git pull origin main
|
||
git merge feat/classes-page
|
||
git push origin main # CI 自动触发 quality + deploy
|
||
|
||
# ============ 协调 AI（事后审查） ============
|
||
|
||
# 10. 收到合并通知，审查 main 上新 commit
|
||
git pull origin main
|
||
git log -p -1
|
||
# 若需修改，评论要求开发 AI-A 在新分支上后续 commit 修正
|
||
# 若严重问题，由人类决策者在 main 上 git revert
|
||
|
||
# ============ 开发 AI-A（若需修正） ============
|
||
|
||
# 11. 等待人类决策者为修正任务创建新分支并分配
|
||
# 在新分支上后续 commit 修正
|
||
git branch --show-current # 确认在新分配的分支
|
||
# 编辑修复...
|
||
git add services/classes/
|
||
git commit -m "fix(classes): 修复分页 total 计算错误"
|
||
# 通知人类决策者合并新分支
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题与解决方案
|
||
|
||
### 8.1 多 AI 修改同一文件冲突
|
||
|
||
**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖，合并到 main 时冲突。
|
||
|
||
**解决**：由**人类决策者**在合并第二个分支时解决冲突：
|
||
|
||
```bash
|
||
# 人类决策者执行（AI 不执行 merge）
|
||
git merge feat/<branch-B>
|
||
# 解决 package.json 冲突（保留两边依赖）
|
||
git add package.json
|
||
git commit
|
||
git push origin main
|
||
```
|
||
|
||
AI 若预判会冲突，应提前在 issue 中与对方 AI 协调，或拆分共享文件变更到不同 commit。
|
||
|
||
### 8.2 CI 失败但本地通过
|
||
|
||
**场景**：开发 AI 本地 lint 通过，合并到 main 后 CI 报错。
|
||
|
||
**排查**：
|
||
|
||
1. 检查 Node/Go/pnpm 版本是否一致（见 local-dev-runbook §1）
|
||
2. 检查 `pnpm-lock.yaml` 是否最新（`pnpm install --frozen-lockfile`）
|
||
3. 检查环境变量是否齐全（`.env` vs CI secrets）
|
||
|
||
**修复后**：AI 在新分支上修复，再次通知人类合并：
|
||
|
||
```bash
|
||
# AI 在新分配的分支上
|
||
git branch --show-current
|
||
git add <fixed-files>
|
||
git commit -m "fix(classes): 修复 CI lint 失败"
|
||
# 通知人类决策者合并
|
||
```
|
||
|
||
### 8.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` 跳过。
|
||
|
||
### 8.4 proto 变更导致下游编译失败
|
||
|
||
**场景**：shared-proto 分支合并到 main 后，classes 服务 `buf generate` 报错。
|
||
|
||
**解决**：
|
||
|
||
1. 协调 AI 的 proto 分支合并前，在 issue 评论中通知所有依赖服务的 AI
|
||
2. proto 分支合并到 main 后，下游 AI 在自己分支上 `git pull` 同步 main
|
||
3. 下游 AI 重新生成代码并提交：
|
||
|
||
```bash
|
||
# 下游 AI 在自己分支上
|
||
git pull origin main # 同步 main 最新（含 proto 变更）
|
||
pnpm run proto:generate
|
||
git add packages/shared-proto/gen/
|
||
git commit -m "chore(shared-proto): 重新生成 TS 类型"
|
||
# 通知人类决策者合并
|
||
```
|
||
|
||
### 8.5 误合并错误代码到 main
|
||
|
||
**场景**：人类决策者合并了有问题的分支到 main。
|
||
|
||
**修复**（由**人类决策者**执行）：
|
||
|
||
```bash
|
||
# 1. 确认误合并的 commit
|
||
git log --oneline -5
|
||
|
||
# 2. 在 main 上 revert
|
||
git checkout main
|
||
git pull origin main
|
||
git revert <commit-sha>
|
||
git push origin main # CI 自动重新部署
|
||
```
|
||
|
||
AI 发现误合并问题后，应**通知人类决策者**执行 revert，不自行操作 main。
|
||
|
||
> 严重事故时，协调 AI 可建议人类决策者用 `workflow_dispatch` 指定稳定 `commit_sha` 回滚部署（见 project_rules §15.5）。
|
||
|
||
### 8.6 AI 误切分支怎么办
|
||
|
||
**场景**：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 混淆。
|
||
|
||
---
|
||
|
||
## 9. AI 协作通信约定
|
||
|
||
### 9.1 通信渠道
|
||
|
||
| 场景 | 方式 |
|
||
| ----------- | ------------------------------------------------ |
|
||
| 任务分配 | Issue（指定 AI、模块、分支名） |
|
||
| 合并请求 | AI 完成后通知人类决策者（issue 评论 / 即时通讯） |
|
||
| 事后 review | commit 评论（指出问题、要求修正） |
|
||
| 紧急通知 | issue + commit 评论 @ 相关人员 |
|
||
| 架构讨论 | Issue 标签 `discussion` |
|
||
|
||
### 9.2 commit 评论规范
|
||
|
||
协调 AI 事后审查评论格式：
|
||
|
||
```
|
||
## 审查结果：需修正 / 通过 / 回滚
|
||
|
||
### 需修正项
|
||
1. [classes.controller.ts:42] 缺少 @RequirePermission() 装饰器
|
||
2. [classes.service.ts:88] 返回值未标注 Promise<T>
|
||
|
||
### 建议
|
||
- 考虑抽取分页逻辑到 shared-ts
|
||
```
|
||
|
||
> 评论不标注 AI 身份签名（如"协调 AI"字样），通过 CODEOWNERS 与分支归属自然体现审查者角色。
|
||
|
||
### 9.3 经验沉淀（不写工作日志，不标注 AI 身份）
|
||
|
||
> **核心原则**：经验沉淀只记录"场景→技术/规则"映射，**不记录工作日志、不标注 AI 身份**。
|
||
|
||
**强制约束**：
|
||
|
||
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 是速查手册，不是日记。
|
||
|
||
---
|
||
|
||
## 10. 安全与权限
|
||
|
||
### 10.1 main 分支保护
|
||
|
||
- **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 任何分支 |
|
||
| ---------- | ------------------ | -------------- | ----------------------------- | -------------------------------- |
|
||
| 开发 AI | ❌ | ❌ | ❌ | ❌ |
|
||
| 协调 AI | ❌ | ❌ | ✅（shared-proto/infra/docs） | ❌ |
|
||
| SRE AI | ❌ | ❌ | ✅（仅 infra） | ❌ |
|
||
| 人类决策者 | ✅ | ✅（通过合并） | ✅（审批后） | ⚠️（仅事故，--force-with-lease） |
|
||
|
||
> 所有 AI 角色均**无分支管理权限**。AI 只在自己被分配的分支上 `git add` → `git commit`，之后通知人类合并。
|
||
|
||
### 10.3 敏感文件保护
|
||
|
||
以下文件修改需人类决策者额外审批：
|
||
|
||
- `.env`、`.env.example`（密钥相关）
|
||
- `infra/security/secrets.example.env`
|
||
- `infra/k8s/`（生产部署）
|
||
- `.github/workflows/`（CI 配置）
|
||
- `.trae/rules/project_rules.md`（项目规则）
|
||
|
||
AI 修改这些文件后，必须在通知人类合并时**显式说明**修改了敏感文件，等待人类决策者额外审批。
|
||
|
||
---
|
||
|
||
## 11. 发布流程
|
||
|
||
> 发布由**人类决策者合并分支到 main**触发 CI 自动部署。详见 [Git 工作流](./git-workflow.md) §7。
|
||
|
||
### 11.1 版本号规则
|
||
|
||
- 平台版本：`v{阶段}.{迭代}.{patch}`（仅记录，不打 git tag）
|
||
- 服务版本：`{service}:{semver}`（每服务 VERSION 文件）
|
||
|
||
### 11.2 发布步骤（人类决策者触发 CI）
|
||
|
||
```bash
|
||
# 人类决策者执行（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
|
||
# 或用 workflow_dispatch 指定稳定 commit_sha
|
||
```
|
||
|
||
### 11.3 AI 在发布流程中的角色
|
||
|
||
- AI 完成分支开发与本地校验后，通知人类决策者合并
|
||
- AI 不直接触发发布（不 push main）
|
||
- AI 监控 CI 结果（若 CI 失败，在新分支上修复并通知人类合并）
|
||
|
||
---
|
||
|
||
## 12. 快速参考卡
|
||
|
||
### 开发 AI 日常工作流
|
||
|
||
```bash
|
||
# 1. 确认当前分支（人类已分配，AI 不切换）
|
||
git branch --show-current
|
||
|
||
# 2. 开发 → 校验 → 提交（只改自己模块目录）
|
||
pnpm run lint && pnpm run typecheck
|
||
git add services/<my-service>/
|
||
git commit -m "feat(<scope>): <subject>"
|
||
|
||
# 3. 通知人类决策者合并
|
||
# "分支 <branch>，commit <sha>，请审查合并"
|
||
|
||
# 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
|
||
# 查看最新合并到 main 的 commit
|
||
git pull origin main
|
||
git log --oneline -10
|
||
|
||
# 事后审查 main 上新合并的 commit
|
||
git log -p -1
|
||
# 评论要求修正，或通知人类决策者 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) — 提交规范、分支管理、事后 review、CODEOWNERS
|
||
- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
|
||
- [项目规则](../../.trae/rules/project_rules.md) — 强制约束（§10 按需阅读架构、§14 多 AI 协作）
|
||
- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 模块与依赖关系
|
||
- [CODEOWNERS](../../.github/CODEOWNERS) — 模块归属追溯
|
||
- [known-issues](../troubleshooting/known-issues.md) — 已知问题速查（索引式，不写工作日志）
|
||
|
||
---
|
||
|
||
## 变更记录
|
||
|
||
| 版本 | 日期 | 变更内容 |
|
||
| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| 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 快速参考卡更新 |
|