# 多 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 快速参考卡更新 |