xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 恢复分支开发模式 - AI 不切换分支,默认多AI协作,经验沉淀不标注AI身份

Browse Source
This commit is contained in:
SpecialX
2026-07-10 13:46:47 +08:00
parent f15912c7ee
commit 6051f84a65
5 changed files with 557 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
.trae/rules/project_rules.md
View File

@@ -246,13 +246,17 @@ services/[service]/src/
## 8. Git 工作流 ## 8. Git 工作流
- **分支策略**：trunk-based，直接提交到 `main` 分支（因 Gitea 问题，**不再使用特性分支/发布分支/hotfix 分支，不再使用 PR 流程**） - **分支策略**：分支开发。**人类决策者手动维护分支**（创建分支、合并到 main），AI 不得自行切换/创建/合并分支
- **提交方式**：所有变更直接 `git push origin main`；禁止 `git checkout -b` 创建任何分支 - **AI 分支约束（强制）**：
- **提交前同步**：`git pull --rebase origin main` 拉取最新，解决冲突后再 push - AI 只在人类分配的当前分支上工作
- **禁止** `git checkout -b`、`git switch`、`git branch` 创建或切换分支
- **禁止** `git merge`、`git push origin main`（合并与推送 main 由人类负责）
- AI 完成工作后 `git add` + `git commit` 提交到当前分支，通知人类合并
- **提交前校验**：commit 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
- **pre-commit hook**：`lint-staged` 自动修复 + 校验（见 `lint-staged.config.js`） - **pre-commit hook**：`lint-staged` 自动修复 + 校验（见 `lint-staged.config.js`）
- **commit-msg hook**：commitlint 校验格式 - **commit-msg hook**：commitlint 校验格式
- **禁止 force push**：除非显式要求并通知团队 - **回滚**：由人类在 main 上 `git revert <commit>`，不使用分支回滚
- **回滚**：`git revert <commit>` + `git push origin main`，不使用分支回滚 - **默认多 AI 协作**：所有工作默认按多 AI 合作模式进行（见 §14），每个 AI 在各自分支独立工作
--- ---
@@ -289,7 +293,9 @@ services/[service]/src/
- **去重**：同类问题在原条目补充，不重复创建 - **去重**：同类问题在原条目补充，不重复创建
- **引用架构规则**：架构分层、模块结构等规则引用 004 和本规则文件，不重复 - **引用架构规则**：架构分层、模块结构等规则引用 004 和本规则文件，不重复
- **只读自己模块分区**：AI 查阅 known-issues 时只读自己负责模块的分区，禁止读其他 AI 模块的分区（避免被历史记录误导） - **只读自己模块分区**：AI 查阅 known-issues 时只读自己负责模块的分区，禁止读其他 AI 模块的分区（避免被历史记录误导）
- **禁止流水日志**：known-issues 不再设"工作经验日志"区，不写跨模块流水账；模块内的经验沉淀在各自模块的 README/文档中 - **禁止工作日志**：known-issues 不设"工作经验日志"区，不写流水账、不写"做了什么/学到什么"
- **经验沉淀不标注 AI 身份**：所有经验记录只写"场景→技术/规则"映射，**不得出现 AI 标识（如 ai01/ai02/coord 等）**，避免新同名 AI 将前任记录误认为当前事实
- **模块内经验**：模块内的经验沉淀在各自模块的 README/文档中，同样不标注 AI 身份
--- ---
@@ -321,12 +327,12 @@ services/[service]/src/
### 阶段 3：经验沉淀（强制，不可跳过） ### 阶段 3：经验沉淀（强制，不可跳过）
1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志） 1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志，**不标注 AI 身份**）
2. 若发现新的架构决策 → 更新 004 2. 若发现新的架构决策 → 更新 004
3. 若代码结构变化 → `pnpm run arch:scan` 确认 arch.db 已更新 3. 若代码结构变化 → `pnpm run arch:scan` 确认 arch.db 已更新
4. 模块内的经验沉淀到**自己模块的 README/文档**，不污染全局 known-issues 4. 模块内的经验沉淀到**自己模块的 README/文档**，不污染全局 known-issues，同样不标注 AI 身份
> **禁止**在 known-issues.md 写跨模块"工作经验日志/流水账"。known-issues 是索引式速查手册，只保留场景→技术映射。新 AI 不应被前任同名 AI 的流水记录误导。 > **禁止**在 known-issues.md 写"工作经验日志/流水账"。known-issues 是索引式速查手册，只保留场景→技术映射，**不出现任何 AI 标识**。
--- ---
@@ -377,18 +383,18 @@ services/[service]/src/
## 14. 多 AI 协作规范 ## 14. 多 AI 协作规范
> 详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。 > **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行。详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。
### 14.1 角色与权限 ### 14.1 角色与权限
| 角色 | 职责 | 直接 push main | 修改他人模块 | force push main | | 角色 | 职责 | 在分支提交 | 合并到 main | force push main |
| -------------------------- | ---------------------------------------- | -------------- | ----------------------------- | --------------- | | -------------------------- | -------------------------------------------------------- | ----------- | ------------------------- | --------------- |
| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ✅（shared-proto/infra/docs） | ⚠️（仅事故） | | **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ❌（由人类合并） | ⚠️（仅事故） |
| **开发 AI（Dev）** | 按模块分工写代码、直接 push main | ✅ | ❌ | ❌ | | **开发 AI（Dev）** | 按模块分工写代码、在分支提交 | ✅ | ❌ | ❌ |
| **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ✅（仅 infra） | ⚠️（仅事故） | | **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ❌（由人类合并） | ⚠️（仅事故） |
| **人类决策者** | 架构决策、Breaking Change 审批、发布确认 | — | — | — | | **人类决策者** | 架构决策、分支管理、合并、Breaking Change 审批、发布确认 | — | ✅（手动合并分支到 main） | ⚠️（仅事故） |
> 不再使用特性分支与 PR。所有变更直接 `git push origin main`。代码审查改为事后追溯（通过 commit message + commit history），不在 push 前阻塞。 > AI 在分配的分支上提交，**不自行合并到 main**。合并由人类决策者负责。
### 14.2 模块单一负责制与模块边界（强制） ### 14.2 模块单一负责制与模块边界（强制）
@@ -399,17 +405,18 @@ services/[service]/src/
- `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用 - `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用
- `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改 - `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
### 14.3 直接 push main 规则（强制） ### 14.3 分支开发规则（强制）
1. **禁止创建分支**：不使用 `git checkout -b`、`git branch` 创建任何特性/发布/hotfix 分支 1. **分支由人类创建**：人类决策者为每个任务/模块创建分支并分配给 AI，AI 不得自行创建分支
2. **直接 push main**：所有变更 `git add` → `git commit` → `git pull --rebase origin main` → `git push origin main` 2. **AI 禁止切换分支**：AI 不得执行 `git checkout -b`、`git switch`、`git branch` 等分支创建/切换命令
3. **提交前校验**：push 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python） 3. **AI 禁止合并/推送 main**：`git merge`、`git push origin main` 由人类决策者执行，AI 只提交到当前分支
4. **提交信息规范**：遵循 Conventional Commits（见 §7），commit message 末尾标注 AI 身份（见 §14.6） 4. **AI 提交流程**：`git add <files>` → `git commit -m "<type>(<scope>): <subject>"` → 通知人类合并
5. **不阻塞审查**：push 不等待 review，问题通过事后 commit revert 或后续 commit 修正 5. **提交前校验**：commit 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python）
6. **提交信息规范**：遵循 Conventional Commits（见 §7）
### 14.4 跨模块变更顺序（强制） ### 14.4 跨模块变更顺序（强制）
修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）： 修改涉及多模块时，按依赖顺序依次在各模块分支完成，由人类决策者按顺序合并到 main：
1. `shared-proto`（proto 契约） 1. `shared-proto`（proto 契约）
2. 业务服务（classes / iam / core-edu 等） 2. 业务服务（classes / iam / core-edu 等）
@@ -417,26 +424,20 @@ services/[service]/src/
4. BFF（teacher-bff 等） 4. BFF（teacher-bff 等）
5. 微前端（teacher-portal 等） 5. 微前端（teacher-portal 等）
> 每提交一层并 push 后，再开发下一层。协调 AI 负责监督顺序，避免越级提交导致下游构建失败。 > 每合并一层到 main 后，再合并下一层。协调 AI 负责监督顺序，避免越级合并导致下游构建失败。
### 14.5 冲突处理规则 ### 14.5 冲突处理规则
- **push 冲突**：`git pull --rebase origin main` 解决冲突后重新 `git push origin main` - **分支冲突**：由人类决策者在合并时解决，或通知 AI 在分支上 `git rebase` 最新 main 后重新提交
- **架构冲突**：由协调 AI 仲裁保留方案，通过 commit revert + 新 commit 修正 - **架构冲突**：由协调 AI 仲裁保留方案，通过新 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `--force-with-lease` - **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `--force-with-lease`
### 14.6 AI 身份标注（强制） ### 14.6 经验沉淀规则（强制）
每个 commit message body 末尾必须追加（用于追溯，不再有 PR 描述）： - **不记录工作日志**：AI 不在 known-issues.md 或任何文档中写"工作经验日志/流水账"
- **只做经验沉淀**：遇到新的"场景→技术"映射，以索引式一行记录到 known-issues 对应模块分区
```text - **不标注 AI 身份**：经验沉淀记录**不得出现 AI 标识**（如 ai01/ai02/coord 等），避免新同名 AI 误读
--- - **模块内经验**：模块内的经验沉淀到各自服务 README/文档，同样不标注 AI 身份
AI-Agent: <ai-id> (<负责模块>)
Coord: <协调 AI ai-id>
```
> 不再有 Branch 字段（不使用分支）。每个 AI 的经验沉淀到自己模块的 README/文档，**禁止**在 known-issues.md 写跨模块工作日志。
### 14.7 敏感文件保护 ### 14.7 敏感文件保护
@@ -469,13 +470,14 @@ Coord: <协调 AI ai-id>
| **quality-proto** | ✅ | buf lint + buf breaking | 失败阻断 | | **quality-proto** | ✅ | buf lint + buf breaking | 失败阻断 |
| **deploy** | 串行 | docker compose up --build + 健康检查 | 失败阻断 | | **deploy** | 串行 | docker compose up --build + 健康检查 | 失败阻断 |
> 不再使用 PR。所有质量检查与部署在 push main 时触发。 > 质量检查在分支推送时触发，部署仅在合并到 main 时触发。
### 15.3 触发条件 ### 15.3 触发条件
| 事件 | 触发阶段 | 触发条件 | | 事件 | 触发阶段 | 触发条件 |
| ----------------- | ------------------------------------------------------- | -------------------------------- | | ----------------- | ----------------------------------------------- | -------------------------------- |
| push 到 main | quality-ts + quality-go + quality-proto（并行）+ deploy | 每次 push main 自动 | | 分支 push / PR | quality-ts + quality-go + quality-proto（并行） | 分支推送自动 |
| push 到 main | 上述全部 + deploy | 合并后自动 |
| workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 | | workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 |
> **不再支持 tag 发布**：no-push 模式下不用 `git tag v*` 触发。版本管理通过 commit SHA 追溯。 > **不再支持 tag 发布**：no-push 模式下不用 `git tag v*` 触发。版本管理通过 commit SHA 追溯。

42
docs/architecture/ai-allocation.md
View File

@@ -1,13 +1,15 @@
# AI 分配方案与架构设计外包流程 # AI 分配方案与架构设计外包流程
> 版本：1.0 > 版本：1.1
> 日期：2026-07-09 > 日期：2026-07-10
> 适用范围：Edu 微服务项目模块架构设计外包阶段 > 适用范围：Edu 微服务项目（架构设计外包三阶段已实施，进入持续开发阶段）
> 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md) > 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md)
>
> **状态说明**：架构设计外包三阶段（模块理解 → 模块架构设计 → 按图实施）已实施完成，各模块设计文档见 `services/<service>/docs/` 与 `apps/<app>/docs/`。当前进入持续开发阶段，所有 AI 工作默认按多 AI 协作模式进行。
--- ---
## 1. 外包总流程：三阶段 ## 1. 外包总流程：三阶段（已实施）
``` ```
阶段 1：模块理解 阶段 2：模块架构设计 阶段 3：按图实施 阶段 1：模块理解 阶段 2：模块架构设计 阶段 3：按图实施
@@ -21,6 +23,8 @@
交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图 交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图
``` ```
> **三阶段已实施完成**。阶段 1 产出见各模块 `docs/01-understanding.md`，阶段 2 产出见各模块 `docs/02-architecture-design.md`，阶段 3 持续进行中。
**阶段 1 目标**：每个 AI 读懂自己负责的模块在架构中的位置、边界、契约（按需阅读，见 §4）。 **阶段 1 目标**：每个 AI 读懂自己负责的模块在架构中的位置、边界、契约（按需阅读，见 §4）。
**阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。 **阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。
**阶段 3 目标**：按设计文档写代码，coord 定期巡检一致性。 **阶段 3 目标**：按设计文档写代码，coord 定期巡检一致性。
@@ -104,10 +108,10 @@
### 4.1 全员必读（所有 AI，无论模块开发还是全局工作） ### 4.1 全员必读（所有 AI，无论模块开发还是全局工作）
| 顺序 | 文档 | 说明 | | 顺序 | 文档 | 说明 |
| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ | | ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、直接 push main） | | 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、分支开发） |
| 2 | [coding-standards.md](../standards/coding-standards.md) | 多语言编码标准 | | 2 | [coding-standards.md](../standards/coding-standards.md) | 多语言编码标准 |
| 3 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | 多 AI 协作指南（§2.1 严格模块边界、§2.2 按需阅读、§3 直接 push main） | | 3 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | 多 AI 协作指南（§2.1 严格模块边界、§2.2 按需阅读、§3 分支开发规则） |
### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现） ### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现）
@@ -367,38 +371,48 @@ coord 收到全部 7 份设计文档后，执行以下审查：
## 9. 协作规则 ## 9. 协作规则
### 9.1 单仓库并行开发 > **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行，详见 [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md)。
当前阶段采用**单仓库直接 push main**模式，不经过 PR： ### 9.1 分支并行开发
采用**分支开发**模式，人类决策者维护分支：
- 人类决策者为每个任务/模块创建分支并分配给 AI
- **AI 禁止** `git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`
- AI 在分配的分支上 `git add` → `git commit` 提交，完成后通知人类合并
- 每个 AI 只能修改自己负责的目录（见 §3.2） - 每个 AI 只能修改自己负责的目录（见 §3.2）
- `packages/shared-proto/` 仅 coord 修改，其他 AI 只读 - `packages/shared-proto/` 仅 coord 修改，其他 AI 只读
- `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改 - `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改
### 9.2 唯一冲突文件处理 ### 9.2 唯一冲突文件处理
`pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时： `pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时由**人类决策者**在合并时解决：
```bash ```bash
git pull origin main --rebase # 人类决策者操作（AI 不执行）
git checkout main
git merge <branch>
# 冲突时： # 冲突时：
git checkout --theirs pnpm-lock.yaml # 取远程版本 git checkout --theirs pnpm-lock.yaml # 取分支版本
pnpm install # 重新生成 pnpm install # 重新生成
git add pnpm-lock.yaml git add pnpm-lock.yaml
git rebase --continue git commit
``` ```
### 9.3 提交规范 ### 9.3 提交规范
```bash ```bash
# 每个 AI 在自己的服务目录内工作 # 每个 AI 在自己的服务目录内工作（在分配的分支上）
git add services/<service>/... git add services/<service>/...
git commit -m "docs(<service>): 模块架构设计文档" git commit -m "docs(<service>): 模块架构设计文档"
# 或 # 或
git commit -m "docs(<service>): 阶段1理解确认书" git commit -m "docs(<service>): 阶段1理解确认书"
# 完成后通知人类决策者合并
``` ```
> **不标注 AI 身份**：commit message 不追加 `AI-Agent:` 等身份字段，经验沉淀不出现 AI 标识。
### 9.4 proto 变更流程 ### 9.4 proto 变更流程
任何 AI 需要新增/修改 proto： 任何 AI 需要新增/修改 proto：

202
docs/standards/git-workflow.md
View File

@@ -1,8 +1,8 @@
# Edu Git 工作流规范 # Edu Git 工作流规范
> 版本：1.2 > 版本：1.3
> 日期：2026-07-10 > 日期：2026-07-10
> 状态：基线发布（v1.2：移除分支/PR 流程，改为直接 push main） > 状态：v1.3：恢复分支开发模式，AI 不切换分支
> 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml） > 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml）
> 关联文档： > 关联文档：
> >
@@ -15,7 +15,7 @@
## 目录 ## 目录
1. [主干开发（直接 push main）](#一主干开发直接-push-main) 1. [分支开发](#一分支开发)
2. [Conventional Commits 规范](#二conventional-commits-规范) 2. [Conventional Commits 规范](#二conventional-commits-规范)
3. [commitlint + husky 配置](#三commitlint--husky-配置) 3. [commitlint + husky 配置](#三commitlint--husky-配置)
4. [事后 Code Review](#四事后-code-review) 4. [事后 Code Review](#四事后-code-review)
@@ -27,57 +27,91 @@
--- ---
## 一、主干开发（直接 push main） ## 一、分支开发
### 1.1 模式 ### 1.1 模式
本项目采用**主干开发**模式，所有变更**直接提交到 `main` 分支**。 本项目采用**分支开发**模式：**人类决策者**为每个任务/模块创建分支并分配给 AI，AI 只在当前分配的分支上工作，分支的创建、切换、合并均由人类决策者维护。
> 因 Gitea 问题，**不再使用特性分支、发布分支、hotfix 分支，不再使用 PR 流程**。所有变更通过 `git push origin main` 提交。 > **AI 不允许自行切换/创建/合并分支**。AI 禁止执行以下命令：
>
> - `git checkout -b`、`git switch`（创建/切换分支）
> - `git branch`（创建分支）
> - `git merge`（合并分支）
> - `git push origin main`（推送主干）
**核心原则**： **核心原则**：
- `main` 分支始终保持可发布状态 - `main` 分支始终保持可发布状态，**只有人类决策者能向 main 合并**
- 所有变更直接 push main，**禁止 `git checkout -b` 创建任何分支** - 人类决策者为每个任务/模块创建分支并分配给对应 AI
- push 前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook） - AI 只在当前分配的分支上工作，**不切换、不创建、不合并分支**
- push 前 `git pull --rebase origin main` 同步最新 - AI 完成提交后通知人类决策者合并，**不自行 push main**
- 提交前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook）
- 通过特性开关（Feature Flag）控制未完成功能的暴露 - 通过特性开关（Feature Flag）控制未完成功能的暴露
- 代码审查改为事后追溯（见 §4），不在 push 前阻塞 - 代码审查改为事后追溯（见 §4），不在合并前阻塞
- 默认多 AI 协作，每个模块单一负责制
### 1.2 提交流程 ### 1.2 AI 提交流程
AI 只在当前分配的分支上执行 `git add` → `git commit`，完成后**通知人类决策者合并**，不推送 main。
```bash ```bash
# 1. 同步最新 main # 1. 本地校验（强制）
git pull --rebase origin main
# 2. 本地校验（强制）
pnpm run lint # TS 服务 pnpm run lint # TS 服务
pnpm run typecheck # TS 服务 pnpm run typecheck # TS 服务
cd services/api-gateway && go vet ./... && go build ./... # Go 服务 cd services/api-gateway && go vet ./... && go build ./... # Go 服务
ruff check src/ # Python 服务 ruff check src/ # Python 服务
# 3. 提交（遵循 Conventional Commits，见 §2） # 2. 提交（遵循 Conventional Commits，见 §2）
git add <files> git add <files>
git commit -m "feat(<scope>): <subject>" git commit -m "feat(<scope>): <subject>"
# 4. push 前再次同步（避免冲突） # 3. 通知人类决策者合并
git pull --rebase origin main # AI 不执行 git push origin main，不创建/切换/合并分支
# 5. 直接 push main
git push origin main
``` ```
### 1.3 冲突处理 > **AI 可执行**：`git add`、`git commit`、`git status`、`git log`、`git diff`、`git pull`（仅同步当前分支）。
>
> **AI 禁止执行**：`git checkout -b`、`git switch`、`git branch`、`git merge`、`git push origin main`、`git push --force`。
- **push 被拒绝**（远端有新提交）：`git pull --rebase origin main` → 解决冲突 → `git add` → `git rebase --continue` → `git push origin main` ### 1.3 人类合并流程
- **架构冲突**：由协调 AI 仲裁，通过 `git revert` + 新 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`
### 1.4 main 分支保护 人类决策者负责将分支合并到 `main`，合并时机与策略由人类决策者判断。
- 禁止 force push（仅协调 AI 在事故时操作） ```bash
# 人类决策者操作（AI 不执行）
# 1. 同步最新 main
git checkout main
git pull origin main
# 2. 合并分支（由人类决策者选择策略）
git merge <branch-name> # 或 git merge --no-ff <branch-name>
# 3. 推送 main（触发 CI 部署）
git push origin main
# 4. （可选）删除已合并分支
git branch -d <branch-name>
```
**合并策略建议**：
- 一般任务：`git merge --no-ff`（保留分支拓扑，便于追溯）
- 紧急修复：`git merge --ff-only`（线性历史）
- 大特性分支：`git merge --squash`（压缩为单 commit）
### 1.4 冲突处理
- **分支合并冲突**：由人类决策者在合并分支到 main 时解决，AI 不参与合并操作
- **架构冲突**：由协调 AI 仲裁，通知人类决策者保留方案后合并，通过后续 commit 修正
- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main`，需人类决策者确认
### 1.5 main 分支保护
- 禁止 force push（仅协调 AI 在事故时操作，需人类决策者确认）
- pre-commit / commit-msg / pre-push hook 强制校验（见 §3.4） - pre-commit / commit-msg / pre-push hook 强制校验（见 §3.4）
- 不再要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证 - 不要求 PR review，代码质量由本地校验 + 事后 review（§4）+ CI（project_rules §15）保证
- **AI 无权直接 push main**，所有 main 变更须经人类决策者合并
--- ---
@@ -268,7 +302,7 @@ module.exports = {
}; };
``` ```
> **单一事实源**：实际生效的配置在仓库根 `.commitlintrc.js`，本节示例仅作说明。修改 scope 必须同步更新 `.commitlintrc.js` 与本节，并在 PR 中说明原因。 > **单一事实源**：实际生效的配置在仓库根 `.commitlintrc.js`，本节示例仅作说明。修改 scope 必须同步更新 `.commitlintrc.js` 与本节，并在提交时说明原因。
### 3.3 scope-enum 完整清单 ### 3.3 scope-enum 完整清单
@@ -355,27 +389,29 @@ module.exports = {
## 四、事后 Code Review ## 四、事后 Code Review
> 不再使用 PR 流程，代码审查改为**事后追溯**：变更直接 push main 后，由模块 owner 或协调 AI 通过 commit history 进行 review。问题通过后续 commit 修正或 `git revert` 回滚。 > 不再使用 PR 流程，代码审查改为**事后追溯**：AI 在分支上提交后通知人类决策者合并，人类决策者合并到 main 后由模块 owner 或协调 AI 通过分支 commit history 进行 review。问题通过后续 commit 修正或 `git revert` 回滚。
### 4.1 事后 Review 流程 ### 4.1 事后 Review 流程
```mermaid ```mermaid
flowchart TD flowchart TD
A[开发 AI 本地校验] --> B[直接 push main] A[开发 AI 本地校验] --> B[分支上 git add + git commit]
B --> C[CI 自动检查] B --> C[通知人类决策者合并]
C --> D{CI 通过?} C --> D[人类决策者合并到 main]
D -->|否| E[git revert + 修复后重新 push] D --> E[CI 自动检查]
D -->|是| F[模块 owner 事后审查 commit] E --> F{CI 通过?}
F --> G{审查通过?} F -->|否| G[人类 git revert + 修复后重新合并]
G -->|有问题| H[后续 commit 修正或 revert] F -->|是| H[模块 owner 事后审查分支 commit]
G -->|通过| I[review 完成] H --> I{审查通过?}
I -->|有问题| J[后续 commit 修正或 revert]
I -->|通过| K[review 完成]
``` ```
**review 依据**： **review 依据**：
- commit message（Conventional Commits 格式，见 §2） - commit message（Conventional Commits 格式，见 §2）
- 分支 commit history（通过 `git log` 或平台分支/合并视图追溯）
- commit diff（通过 `git log -p` 或平台 commit 视图） - commit diff（通过 `git log -p` 或平台 commit 视图）
- AI 身份标注（commit body 末尾的 `AI-Agent:` 字段，见 project_rules §14.6）
### 4.2 Code Review 清单 ### 4.2 Code Review 清单
@@ -414,14 +450,14 @@ flowchart TD
**实际生效文件**：仓库根 `.github/CODEOWNERS`。 **实际生效文件**：仓库根 `.github/CODEOWNERS`。
> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：commit 涉及某路径时，对应 owner 负责事后 review。 > 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：分支合并涉及某路径时，对应 owner 负责事后 review。
**设计原则**： **设计原则**：
- 每个模块至少 1 名 owner，核心模块 2 名 - 每个模块至少 1 名 owner，核心模块 2 名
- 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组事后 review - 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组事后 review
- 基础设施变更（K8s/Helm/backup）由 SRE 事后 review - 基础设施变更（K8s/Helm/backup）由 SRE 事后 review
- owner 名单变更通过直接 commit 更新，由架构组确认 - owner 名单变更通过分支提交更新，由架构组确认后人类决策者合并
**模块 Owner 分配矩阵**： **模块 Owner 分配矩阵**：
@@ -449,7 +485,7 @@ flowchart TD
**CODEOWNERS 文件维护规则**： **CODEOWNERS 文件维护规则**：
1. 新增服务/包时，必须同步更新 `.github/CODEOWNERS` 1. 新增服务/包时，必须同步更新 `.github/CODEOWNERS`
2. owner 变更（人员调动）由架构组确认后直接 commit 更新 2. owner 变更（人员调动）由架构组确认后通过分支提交更新
3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件 3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件
--- ---
@@ -459,18 +495,18 @@ flowchart TD
### 5.1 文档同步矩阵 ### 5.1 文档同步矩阵
| 代码变更类型 | 需同步的文档 | 同步时机 | | 代码变更类型 | 需同步的文档 | 同步时机 |
| --------------------- | -------------------------------------------- | --------- | | --------------------- | -------------------------------------------- | ---------- |
| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | PR 内同步 | | 新增/删除服务 | `001_architecture_overview.md` + 服务 README | 分支内同步 |
| 新增/删除模块 | 服务 README + `arch:scan` | PR 内同步 | | 新增/删除模块 | 服务 README + `arch:scan` | 分支内同步 |
| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 | | 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 |
| 修改函数签名 | `pnpm run arch:scan` | 提交前 | | 修改函数签名 | `pnpm run arch:scan` | 提交前 |
| 修改权限点 | `project_rules.md` + 权限文档 | PR 内同步 | | 修改权限点 | `project_rules.md` + 权限文档 | 分支内同步 |
| 新增/删除数据库表 | 架构文档 + 服务 README | PR 内同步 | | 新增/删除数据库表 | 架构文档 + 服务 README | 分支内同步 |
| 新增/删除路由 | 服务 README + OpenAPI | PR 内同步 | | 新增/删除路由 | 服务 README + OpenAPI | 分支内同步 |
| 修改模块间依赖 | `arch:scan` + 架构文档 | PR 内同步 | | 修改模块间依赖 | `arch:scan` + 架构文档 | 分支内同步 |
| 新增 protobuf message | `proto/` README + `arch:scan` | PR 内同步 | | 新增 protobuf message | `proto/` README + `arch:scan` | 分支内同步 |
| 新增 Kafka topic | 架构文档 + 服务 README | PR 内同步 | | 新增 Kafka topic | 架构文档 + 服务 README | 分支内同步 |
| 遇到新问题/经验 | `known-issues.md` | PR 内同步 | | 遇到新问题/经验 | `known-issues.md` | 分支内同步 |
### 5.2 arch.db 同步规则 ### 5.2 arch.db 同步规则
@@ -551,6 +587,7 @@ git commit -m "feat(identity): 实现用户注册接口"
- 不写代码示例和错误示范 - 不写代码示例和错误示范
- 同类问题在原条目补充，不重复创建 - 同类问题在原条目补充，不重复创建
- **不设"工作经验日志"区**：模块内经验沉淀在各自服务 README，known-issues 只保留索引式场景→技术映射（见 project_rules §9） - **不设"工作经验日志"区**：模块内经验沉淀在各自服务 README，known-issues 只保留索引式场景→技术映射（见 project_rules §9）
- **经验沉淀不标注 AI 身份**：AI 只做经验沉淀（场景→技术映射），不记录工作日志，不标注 AI 身份
--- ---
@@ -601,7 +638,7 @@ git commit -m "build(contracts): 重新生成 proto 代码"
- 依赖升级使用 `build(deps):` 类型 - 依赖升级使用 `build(deps):` 类型
- 必须说明升级原因（安全、功能、兼容性） - 必须说明升级原因（安全、功能、兼容性）
- 安全漏洞修复必须包含 CVE 编号 - 安全漏洞修复必须包含 CVE 编号
- 大版本升级需单独 PR 并完整测试 - 大版本升级需单独分支并完整测试
**示例**： **示例**：
@@ -633,7 +670,7 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
## 七、版本管理 ## 七、版本管理
> 不再使用 tag 发布与 release 分支（见 project_rules §15.3 no-push 模式）。版本通过 commit SHA 追溯，发布由 push main 触发 CI 自动部署。 > 不使用 tag 发布与 release 分支（见 project_rules §15.3 no-push 模式）。版本通过 commit SHA 追溯，发布由人类决策者合并分支到 main 后触发 CI 自动部署。
### 7.1 版本号体系 ### 7.1 版本号体系
@@ -671,20 +708,22 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件"
```mermaid ```mermaid
flowchart TD flowchart TD
A[开发 AI 本地校验通过] --> B[直接 push main] A[开发 AI 本地校验通过] --> B[分支上 git add + git commit]
B --> C[CI 自动触发 quality + deploy] B --> C[通知人类决策者合并]
C --> D{CI 通过?} C --> D[人类决策者合并到 main]
D -->|否| E[git revert + 修复后重新 push] D --> E[CI 自动触发 quality + deploy]
E --> B E --> F{CI 通过?}
D -->|是| F[部署至目标环境] F -->|否| G[人类 git revert + 修复后重新合并]
F --> G[健康检查轮询 /healthz] G --> D
G --> H{健康?} F -->|是| H[部署至目标环境]
H -->|否| I[输出容器日志 + 紧急回滚 §8] H --> I[健康检查轮询 /healthz]
H -->|是| J[发布完成] I --> J{健康?}
J --> K[更新 CHANGELOG.md] J -->|否| K[输出容器日志 + 紧急回滚 §8]
J -->|是| L[发布完成]
L --> M[更新 CHANGELOG.md]
``` ```
> 不再创建 release 分支、不再打 git tag。发布点通过 commit SHA 追溯，回滚通过 `git revert` 或 `workflow_dispatch` 指定 `commit_sha`（见 project_rules §15.4）。 > 不创建 release 分支、不打 git tag。发布点通过 commit SHA 追溯，回滚通过 `git revert` 或 `workflow_dispatch` 指定 `commit_sha`（见 project_rules §15.4）。
### 7.5 CHANGELOG 格式 ### 7.5 CHANGELOG 格式
@@ -736,8 +775,8 @@ flowchart TD
### 8.1 回滚策略 ### 8.1 回滚策略
| 场景 | 回滚方式 | 耗时 | | 场景 | 回滚方式 | 耗时 |
| -------------- | ----------------------------------------- | ---------- | | -------------- | --------------------------------------------------- | ---------- |
| 代码缺陷 | `git revert` + push main 触发 CI 重新部署 | 5-10 分钟 | | 代码缺陷 | 人类在 main 上 `git revert` + push 触发 CI 重新部署 | 5-10 分钟 |
| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 | | 镜像问题 | `kubectl rollout undo` | 1-2 分钟 |
| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 | | 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 |
| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 | | 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 |
@@ -745,22 +784,26 @@ flowchart TD
### 8.2 代码回滚 ### 8.2 代码回滚
> 不再创建 hotfix 分支。直接在 main 上 `git revert` 后 push，CI 自动重新部署。 > 不创建 hotfix 分支。**由人类决策者在 main 上 `git revert` 后 push**，CI 自动重新部署。AI 不参与 main 上的回滚推送操作。
```bash ```bash
# 人类决策者操作（AI 不执行 push main）
# 1. 确认要回滚的 commit # 1. 确认要回滚的 commit
git log --oneline -10 git log --oneline -10
# 2. 拉取最新 main # 2. 切换到 main 并拉取最新
git pull --rebase origin main git checkout main
git pull origin main
# 3. 回滚指定 commit（生成反向 commit） # 3. 回滚指定 commit（生成反向 commit）
git revert <commit-sha> git revert <commit-sha>
# 4. 直接 push main（CI 自动触发重新部署） # 4. push main（CI 自动触发重新部署）
git push origin main git push origin main
``` ```
> 修复型回滚也可通过新分支提交修复后由人类决策者合并，具体方式由人类决策者判断。
### 8.3 K8s 部署回滚 ### 8.3 K8s 部署回滚
```bash ```bash
@@ -844,14 +887,14 @@ pnpm --filter identity run migrate:down -- --to <version>
## 九、附录：CICD 与 Edu Git 工作流差异 ## 九、附录：CICD 与 Edu Git 工作流差异
| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） | | 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） |
| --------------------- | -------------------------------- | ----------------------------------------------------------------- | | --------------------- | -------------------------------- | --------------------------------------------------------------------------- |
| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） | | 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） |
| 分支策略 | trunk-based | trunk-based，**直接 push main，无分支无 PR** | | 分支策略 | trunk-based | **分支开发，AI 不切换分支，人类维护** |
| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） | | 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） |
| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） | | scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） |
| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） | | commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） |
| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过 commit history 追溯） | | 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过分支 commit history 追溯） |
| 合并策略 | Squash Merge | **直接 push main**（无合并操作） | | 合并策略 | Squash Merge | **人类决策者手动合并分支到 main**（AI 不合并） |
| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） | | 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） |
| 发布粒度 | 整体发布 | 按服务独立发布 | | 发布粒度 | 整体发布 | 按服务独立发布 |
| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） | | Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） |
@@ -859,7 +902,7 @@ pnpm --filter identity run migrate:down -- --to <version>
| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 | | 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 |
| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） | | 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） |
| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） | | CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） |
| 紧急回滚 | `git revert` + 重新部署 | `git revert` + push main 触发 CI，或 `workflow_dispatch` 指定 SHA | | 紧急回滚 | `git revert` + 重新部署 | 人类在 main 上 `git revert` + push 触发 CI，或 `workflow_dispatch` 指定 SHA |
| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 | | 事故复盘 | known-issues.md | `incidents/` 目录独立记录 |
--- ---
@@ -867,7 +910,8 @@ pnpm --filter identity run migrate:down -- --to <version>
## 变更记录 ## 变更记录
| 版本 | 日期 | 变更内容 | | 版本 | 日期 | 变更内容 |
| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.0 | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo | | 1.0 | 2026-07-07 | 基线发布，从 CICD 单应用规范迁移至微服务多语言 monorepo |
| 1.1 | 2026-07-08 | scope-enum 对齐实际服务名（identity→iam、teaching→core-edu 等）；新增 §4.7 模块 Owner 与 CODEOWNERS；husky hooks 与实际文件对齐；新增 pre-push hook 说明 | | 1.1 | 2026-07-08 | scope-enum 对齐实际服务名（identity→iam、teaching→core-edu 等）；新增 §4.7 模块 Owner 与 CODEOWNERS；husky hooks 与实际文件对齐；新增 pre-push hook 说明 |
| 1.2 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：§1 改为直接 push main（移除特性/发布/hotfix 分支命名与保护）；§4 改为事后 Code Review（移除 PR 流程/标题/模板/合并策略，保留 Code Review 清单与 CODEOWNERS 追溯）；§7 改为版本管理（移除 release 分支与 tag 发布，用 commit SHA 追溯）；§8 移除 hotfix 分支回滚，改为直接 git revert + push main；§9 更新差异表 | | 1.2 | 2026-07-10 | 因 Gitea 问题移除分支/PR 流程：§1 改为直接 push main（移除特性/发布/hotfix 分支命名与保护）；§4 改为事后 Code Review（移除 PR 流程/标题/模板/合并策略，保留 Code Review 清单与 CODEOWNERS 追溯）；§7 改为版本管理（移除 release 分支与 tag 发布，用 commit SHA 追溯）；§8 移除 hotfix 分支回滚，改为直接 git revert + push main；§9 更新差异表 |
| 1.3 | 2026-07-10 | 恢复分支开发模式（AI 不切换分支）：§1 改为分支开发（人类决策者维护分支，AI 禁止 `git checkout -b`/`git switch`/`git branch`/`git merge`/`git push origin main`，AI 只做 `git add`→`git commit`→通知人类合并）；§4 review 依据改为分支 commit history，移除 AI 身份标注；§8 回滚由人类在 main 上 `git revert`，不使用 hotfix 分支；§9 分支策略改为"分支开发，AI 不切换分支，人类维护"；§5.4 经验沉淀不标注 AI 身份 |

526
docs/standards/multi-ai-collaboration.md
View File

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

5
docs/troubleshooting/known-issues.md
View File

@@ -1,8 +1,9 @@
# 已知问题速查 # 已知问题速查
> 索引式速查手册：场景 → 技术/规则映射。不写代码示例，不写流水日志。 > 索引式速查手册：场景 → 技术/规则映射。不写代码示例，不写流水日志，不标注 AI 身份。
> 架构规则见 [../architecture/004_architecture_impact_map.md](../architecture/004_architecture_impact_map.md) 与 [../../.trae/rules/project_rules.md](../../.trae/rules/project_rules.md) > 架构规则见 [../architecture/004_architecture_impact_map.md](../architecture/004_architecture_impact_map.md) 与 [../../.trae/rules/project_rules.md](../../.trae/rules/project_rules.md)
> **AI 查阅时只读自己负责模块的分区（§二 对应小节），禁止读其他 AI 模块分区**，避免被历史记录或他人方案误导。模块内经验沉淀在各自服务 README。 > **AI 查阅时只读自己负责模块的分区（§二 对应小节），禁止读其他 AI 模块分区**，避免被历史记录或他人方案误导。
> **经验沉淀不标注 AI 身份**：所有记录只写"场景→技术/规则"映射，不得出现 AI 标识（如 ai01/ai02/coord 等），避免新同名 AI 将前任记录误认为当前事实。模块内经验沉淀在各自服务 README。
--- ---