From 6051f84a65bc3b729c94eef1cd8306fe7af0231e Mon Sep 17 00:00:00 2001 From: SpecialX <47072643+wangxiner55@users.noreply.github.com> Date: Fri, 10 Jul 2026 13:46:47 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=81=A2=E5=A4=8D=E5=88=86=E6=94=AF?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E6=A8=A1=E5=BC=8F=20-=20AI=20=E4=B8=8D?= =?UTF-8?q?=E5=88=87=E6=8D=A2=E5=88=86=E6=94=AF,=E9=BB=98=E8=AE=A4?= =?UTF-8?q?=E5=A4=9AAI=E5=8D=8F=E4=BD=9C,=E7=BB=8F=E9=AA=8C=E6=B2=89?= =?UTF-8?q?=E6=B7=80=E4=B8=8D=E6=A0=87=E6=B3=A8AI=E8=BA=AB=E4=BB=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .trae/rules/project_rules.md | 88 ++-- docs/architecture/ai-allocation.md | 46 +- docs/standards/git-workflow.md | 252 ++++++----- docs/standards/multi-ai-collaboration.md | 538 ++++++++++++++--------- docs/troubleshooting/known-issues.md | 5 +- 5 files changed, 557 insertions(+), 372 deletions(-) diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md index ccf6091..11bbaca 100644 --- a/.trae/rules/project_rules.md +++ b/.trae/rules/project_rules.md @@ -246,13 +246,17 @@ services/[service]/src/ ## 8. Git 工作流 -- **分支策略**：trunk-based，直接提交到 `main` 分支（因 Gitea 问题，**不再使用特性分支/发布分支/hotfix 分支，不再使用 PR 流程**） -- **提交方式**：所有变更直接 `git push origin main`；禁止 `git checkout -b` 创建任何分支 -- **提交前同步**：`git pull --rebase origin main` 拉取最新，解决冲突后再 push +- **分支策略**：分支开发。**人类决策者手动维护分支**（创建分支、合并到 main），AI 不得自行切换/创建/合并分支 +- **AI 分支约束（强制）**： + - 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`） - **commit-msg hook**：commitlint 校验格式 -- **禁止 force push**：除非显式要求并通知团队 -- **回滚**：`git revert ` + `git push origin main`，不使用分支回滚 +- **回滚**：由人类在 main 上 `git revert `，不使用分支回滚 +- **默认多 AI 协作**：所有工作默认按多 AI 合作模式进行（见 §14），每个 AI 在各自分支独立工作 --- @@ -289,7 +293,9 @@ services/[service]/src/ - **去重**：同类问题在原条目补充，不重复创建 - **引用架构规则**：架构分层、模块结构等规则引用 004 和本规则文件，不重复 - **只读自己模块分区**：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：经验沉淀（强制，不可跳过） -1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志） +1. 若发现新的"场景→技术"映射 → 提炼到 `docs/troubleshooting/known-issues.md` 对应**模块分区**（索引式一行，不写流水日志，**不标注 AI 身份**） 2. 若发现新的架构决策 → 更新 004 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 协作规范 -> 详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。 +> **默认多 AI 协作**：所有 AI 工作默认按多 AI 合作模式进行。详细流程见 [多 AI 协作指南](../../docs/standards/multi-ai-collaboration.md)，本节为强制约束摘要。 ### 14.1 角色与权限 -| 角色 | 职责 | 直接 push main | 修改他人模块 | force push main | -| -------------------------- | ---------------------------------------- | -------------- | ----------------------------- | --------------- | -| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ✅（shared-proto/infra/docs） | ⚠️（仅事故） | -| **开发 AI（Dev）** | 按模块分工写代码、直接 push main | ✅ | ❌ | ❌ | -| **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ✅（仅 infra） | ⚠️（仅事故） | -| **人类决策者** | 架构决策、Breaking Change 审批、发布确认 | — | — | — | +| 角色 | 职责 | 在分支提交 | 合并到 main | force push main | +| -------------------------- | -------------------------------------------------------- | ----------- | ------------------------- | --------------- | +| **协调 AI（Coordinator）** | 契约管理、交叉审查、冲突仲裁、发布 | ✅ | ❌（由人类合并） | ⚠️（仅事故） | +| **开发 AI（Dev）** | 按模块分工写代码、在分支提交 | ✅ | ❌ | ❌ | +| **SRE AI** | `infra/` 维护、部署 | ✅（infra） | ❌（由人类合并） | ⚠️（仅事故） | +| **人类决策者** | 架构决策、分支管理、合并、Breaking Change 审批、发布确认 | — | ✅（手动合并分支到 main） | ⚠️（仅事故） | -> 不再使用特性分支与 PR。所有变更直接 `git push origin main`。代码审查改为事后追溯（通过 commit message + commit history），不在 push 前阻塞。 +> AI 在分配的分支上提交，**不自行合并到 main**。合并由人类决策者负责。 ### 14.2 模块单一负责制与模块边界（强制） @@ -399,17 +405,18 @@ services/[service]/src/ - `shared-proto`、`shared-tokens`、`docs/` 由协调 AI 维护，开发 AI 只读引用 - `infra/` 由 SRE AI 专门负责，业务 AI 不直接修改 -### 14.3 直接 push main 规则（强制） +### 14.3 分支开发规则（强制） -1. **禁止创建分支**：不使用 `git checkout -b`、`git branch` 创建任何特性/发布/hotfix 分支 -2. **直接 push main**：所有变更 `git add` → `git commit` → `git pull --rebase origin main` → `git push origin main` -3. **提交前校验**：push 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python） -4. **提交信息规范**：遵循 Conventional Commits（见 §7），commit message 末尾标注 AI 身份（见 §14.6） -5. **不阻塞审查**：push 不等待 review，问题通过事后 commit revert 或后续 commit 修正 +1. **分支由人类创建**：人类决策者为每个任务/模块创建分支并分配给 AI，AI 不得自行创建分支 +2. **AI 禁止切换分支**：AI 不得执行 `git checkout -b`、`git switch`、`git branch` 等分支创建/切换命令 +3. **AI 禁止合并/推送 main**：`git merge`、`git push origin main` 由人类决策者执行，AI 只提交到当前分支 +4. **AI 提交流程**：`git add ` → `git commit -m "(): "` → 通知人类合并 +5. **提交前校验**：commit 前必须本地通过 `pnpm run lint` + `pnpm run typecheck`（TS）/ `go vet ./...`（Go）/ `ruff check src/`（Python） +6. **提交信息规范**：遵循 Conventional Commits（见 §7） ### 14.4 跨模块变更顺序（强制） -修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）： +修改涉及多模块时，按依赖顺序依次在各模块分支完成，由人类决策者按顺序合并到 main： 1. `shared-proto`（proto 契约） 2. 业务服务（classes / iam / core-edu 等） @@ -417,26 +424,20 @@ services/[service]/src/ 4. BFF（teacher-bff 等） 5. 微前端（teacher-portal 等） -> 每提交一层并 push 后，再开发下一层。协调 AI 负责监督顺序，避免越级提交导致下游构建失败。 +> 每合并一层到 main 后，再合并下一层。协调 AI 负责监督顺序，避免越级合并导致下游构建失败。 ### 14.5 冲突处理规则 -- **push 冲突**：`git pull --rebase origin main` 解决冲突后重新 `git push origin main` -- **架构冲突**：由协调 AI 仲裁保留方案，通过 commit revert + 新 commit 修正 +- **分支冲突**：由人类决策者在合并时解决，或通知 AI 在分支上 `git rebase` 最新 main 后重新提交 +- **架构冲突**：由协调 AI 仲裁保留方案，通过新 commit 修正 - **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `--force-with-lease` -### 14.6 AI 身份标注（强制） +### 14.6 经验沉淀规则（强制） -每个 commit message body 末尾必须追加（用于追溯，不再有 PR 描述）： - -```text ---- - -AI-Agent: (<负责模块>) -Coord: <协调 AI ai-id> -``` - -> 不再有 Branch 字段（不使用分支）。每个 AI 的经验沉淀到自己模块的 README/文档，**禁止**在 known-issues.md 写跨模块工作日志。 +- **不记录工作日志**：AI 不在 known-issues.md 或任何文档中写"工作经验日志/流水账" +- **只做经验沉淀**：遇到新的"场景→技术"映射，以索引式一行记录到 known-issues 对应模块分区 +- **不标注 AI 身份**：经验沉淀记录**不得出现 AI 标识**（如 ai01/ai02/coord 等），避免新同名 AI 误读 +- **模块内经验**：模块内的经验沉淀到各自服务 README/文档，同样不标注 AI 身份 ### 14.7 敏感文件保护 @@ -469,14 +470,15 @@ Coord: <协调 AI ai-id> | **quality-proto** | ✅ | buf lint + buf breaking | 失败阻断 | | **deploy** | 串行 | docker compose up --build + 健康检查 | 失败阻断 | -> 不再使用 PR。所有质量检查与部署在 push main 时触发。 +> 质量检查在分支推送时触发，部署仅在合并到 main 时触发。 ### 15.3 触发条件 -| 事件 | 触发阶段 | 触发条件 | -| ----------------- | ------------------------------------------------------- | -------------------------------- | -| push 到 main | quality-ts + quality-go + quality-proto（并行）+ deploy | 每次 push main 自动 | -| workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 | +| 事件 | 触发阶段 | 触发条件 | +| ----------------- | ----------------------------------------------- | -------------------------------- | +| 分支 push / PR | quality-ts + quality-go + quality-proto（并行） | 分支推送自动 | +| push 到 main | 上述全部 + deploy | 合并后自动 | +| workflow_dispatch | 上述全部 + deploy | 手动触发，支持 `commit_sha` 回滚 | > **不再支持 tag 发布**：no-push 模式下不用 `git tag v*` 触发。版本管理通过 commit SHA 追溯。 diff --git a/docs/architecture/ai-allocation.md b/docs/architecture/ai-allocation.md index 2bff7b5..7e3ca25 100644 --- a/docs/architecture/ai-allocation.md +++ b/docs/architecture/ai-allocation.md @@ -1,13 +1,15 @@ # AI 分配方案与架构设计外包流程 -> 版本：1.0 -> 日期：2026-07-09 -> 适用范围：Edu 微服务项目模块架构设计外包阶段 +> 版本：1.1 +> 日期：2026-07-10 +> 适用范围：Edu 微服务项目（架构设计外包三阶段已实施，进入持续开发阶段） > 关联文档：[多 AI 协作指南](../standards/multi-ai-collaboration.md)、[004 架构影响地图](./004_architecture_impact_map.md)、[待开发功能路线图](./roadmap/pending-features.md) +> +> **状态说明**：架构设计外包三阶段（模块理解 → 模块架构设计 → 按图实施）已实施完成，各模块设计文档见 `services//docs/` 与 `apps//docs/`。当前进入持续开发阶段，所有 AI 工作默认按多 AI 协作模式进行。 --- -## 1. 外包总流程：三阶段 +## 1. 外包总流程：三阶段（已实施） ``` 阶段 1：模块理解 阶段 2：模块架构设计 阶段 3：按图实施 @@ -21,6 +23,8 @@ 交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图 ``` +> **三阶段已实施完成**。阶段 1 产出见各模块 `docs/01-understanding.md`，阶段 2 产出见各模块 `docs/02-architecture-design.md`，阶段 3 持续进行中。 + **阶段 1 目标**：每个 AI 读懂自己负责的模块在架构中的位置、边界、契约（按需阅读，见 §4）。 **阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。 **阶段 3 目标**：按设计文档写代码，coord 定期巡检一致性。 @@ -103,11 +107,11 @@ ### 4.1 全员必读（所有 AI，无论模块开发还是全局工作） -| 顺序 | 文档 | 说明 | -| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、直接 push main） | -| 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） | +| 顺序 | 文档 | 说明 | +| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | +| 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、分支开发） | +| 2 | [coding-standards.md](../standards/coding-standards.md) | 多语言编码标准 | +| 3 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | 多 AI 协作指南（§2.1 严格模块边界、§2.2 按需阅读、§3 分支开发规则） | ### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现） @@ -367,38 +371,48 @@ coord 收到全部 7 份设计文档后，执行以下审查： ## 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） - `packages/shared-proto/` 仅 coord 修改，其他 AI 只读 - `docs/`、`.trae/`、`infra/`、`.github/` 仅 coord 修改 ### 9.2 唯一冲突文件处理 -`pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时： +`pnpm-lock.yaml` 是唯一可能多 AI 同时修改的文件，冲突时由**人类决策者**在合并时解决： ```bash -git pull origin main --rebase +# 人类决策者操作（AI 不执行） +git checkout main +git merge # 冲突时： -git checkout --theirs pnpm-lock.yaml # 取远程版本 +git checkout --theirs pnpm-lock.yaml # 取分支版本 pnpm install # 重新生成 git add pnpm-lock.yaml -git rebase --continue +git commit ``` ### 9.3 提交规范 ```bash -# 每个 AI 在自己的服务目录内工作 +# 每个 AI 在自己的服务目录内工作（在分配的分支上） git add services//... git commit -m "docs(): 模块架构设计文档" # 或 git commit -m "docs(): 阶段1理解确认书" +# 完成后通知人类决策者合并 ``` +> **不标注 AI 身份**：commit message 不追加 `AI-Agent:` 等身份字段，经验沉淀不出现 AI 标识。 + ### 9.4 proto 变更流程 任何 AI 需要新增/修改 proto： diff --git a/docs/standards/git-workflow.md b/docs/standards/git-workflow.md index 9bc43ef..18c80c9 100644 --- a/docs/standards/git-workflow.md +++ b/docs/standards/git-workflow.md @@ -1,8 +1,8 @@ # Edu Git 工作流规范 -> 版本：1.2 +> 版本：1.3 > 日期：2026-07-10 -> 状态：基线发布（v1.2：移除分支/PR 流程，改为直接 push main） +> 状态：v1.3：恢复分支开发模式，AI 不切换分支 > 适用范围：Edu 多语言 monorepo（pnpm workspace + go.work + pyproject.toml） > 关联文档： > @@ -15,7 +15,7 @@ ## 目录 -1. [主干开发（直接 push main）](#一主干开发直接-push-main) +1. [分支开发](#一分支开发) 2. [Conventional Commits 规范](#二conventional-commits-规范) 3. [commitlint + husky 配置](#三commitlint--husky-配置) 4. [事后 Code Review](#四事后-code-review) @@ -27,57 +27,91 @@ --- -## 一、主干开发（直接 push main） +## 一、分支开发 ### 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` 分支始终保持可发布状态 -- 所有变更直接 push main，**禁止 `git checkout -b` 创建任何分支** -- push 前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook） -- push 前 `git pull --rebase origin main` 同步最新 +- `main` 分支始终保持可发布状态，**只有人类决策者能向 main 合并** +- 人类决策者为每个任务/模块创建分支并分配给对应 AI +- AI 只在当前分配的分支上工作，**不切换、不创建、不合并分支** +- AI 完成提交后通知人类决策者合并，**不自行 push main** +- 提交前本地通过 lint + typecheck + test + build（见 §3.4 pre-push hook） - 通过特性开关（Feature Flag）控制未完成功能的暴露 -- 代码审查改为事后追溯（见 §4），不在 push 前阻塞 +- 代码审查改为事后追溯（见 §4），不在合并前阻塞 +- 默认多 AI 协作，每个模块单一负责制 -### 1.2 提交流程 +### 1.2 AI 提交流程 + +AI 只在当前分配的分支上执行 `git add` → `git commit`，完成后**通知人类决策者合并**，不推送 main。 ```bash -# 1. 同步最新 main -git pull --rebase origin main - -# 2. 本地校验（强制） +# 1. 本地校验（强制） pnpm run lint # TS 服务 pnpm run typecheck # TS 服务 cd services/api-gateway && go vet ./... && go build ./... # Go 服务 ruff check src/ # Python 服务 -# 3. 提交（遵循 Conventional Commits，见 §2） +# 2. 提交（遵循 Conventional Commits，见 §2） git add git commit -m "feat(): " -# 4. push 前再次同步（避免冲突） -git pull --rebase origin main - -# 5. 直接 push main -git push origin main +# 3. 通知人类决策者合并 +# AI 不执行 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` -- **架构冲突**：由协调 AI 仲裁，通过 `git revert` + 新 commit 修正 -- **禁止 `git push --force` 到 main**：仅协调 AI 在事故时可 `git push --force-with-lease origin main` +### 1.3 人类合并流程 -### 1.4 main 分支保护 +人类决策者负责将分支合并到 `main`，合并时机与策略由人类决策者判断。 -- 禁止 force push（仅协调 AI 在事故时操作） +```bash +# 人类决策者操作（AI 不执行） +# 1. 同步最新 main +git checkout main +git pull origin main + +# 2. 合并分支（由人类决策者选择策略） +git merge # 或 git merge --no-ff + +# 3. 推送 main（触发 CI 部署） +git push origin main + +# 4. （可选）删除已合并分支 +git branch -d +``` + +**合并策略建议**： + +- 一般任务：`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） -- 不再要求 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 完整清单 @@ -355,27 +389,29 @@ module.exports = { ## 四、事后 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 流程 ```mermaid flowchart TD - A[开发 AI 本地校验] --> B[直接 push main] - B --> C[CI 自动检查] - C --> D{CI 通过?} - D -->|否| E[git revert + 修复后重新 push] - D -->|是| F[模块 owner 事后审查 commit] - F --> G{审查通过?} - G -->|有问题| H[后续 commit 修正或 revert] - G -->|通过| I[review 完成] + A[开发 AI 本地校验] --> B[分支上 git add + git commit] + B --> C[通知人类决策者合并] + C --> D[人类决策者合并到 main] + D --> E[CI 自动检查] + E --> F{CI 通过?} + F -->|否| G[人类 git revert + 修复后重新合并] + F -->|是| H[模块 owner 事后审查分支 commit] + H --> I{审查通过?} + I -->|有问题| J[后续 commit 修正或 revert] + I -->|通过| K[review 完成] ``` **review 依据**： - commit message（Conventional Commits 格式，见 §2） +- 分支 commit history（通过 `git log` 或平台分支/合并视图追溯） - commit diff（通过 `git log -p` 或平台 commit 视图） -- AI 身份标注（commit body 末尾的 `AI-Agent:` 字段，见 project_rules §14.6） ### 4.2 Code Review 清单 @@ -414,14 +450,14 @@ flowchart TD **实际生效文件**：仓库根 `.github/CODEOWNERS`。 -> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：commit 涉及某路径时，对应 owner 负责事后 review。 +> 不再用于自动分配 PR reviewer（无 PR 流程），CODEOWNERS 保留作为**模块归属追溯依据**：分支合并涉及某路径时，对应 owner 负责事后 review。 **设计原则**： - 每个模块至少 1 名 owner，核心模块 2 名 - 跨模块变更（如 proto 契约、arch.db、project_rules）由架构组事后 review - 基础设施变更（K8s/Helm/backup）由 SRE 事后 review -- owner 名单变更通过直接 commit 更新，由架构组确认 +- owner 名单变更通过分支提交更新，由架构组确认后人类决策者合并 **模块 Owner 分配矩阵**： @@ -449,7 +485,7 @@ flowchart TD **CODEOWNERS 文件维护规则**： 1. 新增服务/包时，必须同步更新 `.github/CODEOWNERS` -2. owner 变更（人员调动）由架构组确认后直接 commit 更新 +2. owner 变更（人员调动）由架构组确认后通过分支提交更新 3. CODEOWNERS 与本节表格保持同步，单一事实源为 `.github/CODEOWNERS` 文件 --- @@ -458,19 +494,19 @@ flowchart TD ### 5.1 文档同步矩阵 -| 代码变更类型 | 需同步的文档 | 同步时机 | -| --------------------- | -------------------------------------------- | --------- | -| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | PR 内同步 | -| 新增/删除模块 | 服务 README + `arch:scan` | PR 内同步 | -| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 | -| 修改函数签名 | `pnpm run arch:scan` | 提交前 | -| 修改权限点 | `project_rules.md` + 权限文档 | PR 内同步 | -| 新增/删除数据库表 | 架构文档 + 服务 README | PR 内同步 | -| 新增/删除路由 | 服务 README + OpenAPI | PR 内同步 | -| 修改模块间依赖 | `arch:scan` + 架构文档 | PR 内同步 | -| 新增 protobuf message | `proto/` README + `arch:scan` | PR 内同步 | -| 新增 Kafka topic | 架构文档 + 服务 README | PR 内同步 | -| 遇到新问题/经验 | `known-issues.md` | PR 内同步 | +| 代码变更类型 | 需同步的文档 | 同步时机 | +| --------------------- | -------------------------------------------- | ---------- | +| 新增/删除服务 | `001_architecture_overview.md` + 服务 README | 分支内同步 | +| 新增/删除模块 | 服务 README + `arch:scan` | 分支内同步 | +| 新增/删除导出函数 | `pnpm run arch:scan` | 提交前 | +| 修改函数签名 | `pnpm run arch:scan` | 提交前 | +| 修改权限点 | `project_rules.md` + 权限文档 | 分支内同步 | +| 新增/删除数据库表 | 架构文档 + 服务 README | 分支内同步 | +| 新增/删除路由 | 服务 README + OpenAPI | 分支内同步 | +| 修改模块间依赖 | `arch:scan` + 架构文档 | 分支内同步 | +| 新增 protobuf message | `proto/` README + `arch:scan` | 分支内同步 | +| 新增 Kafka topic | 架构文档 + 服务 README | 分支内同步 | +| 遇到新问题/经验 | `known-issues.md` | 分支内同步 | ### 5.2 arch.db 同步规则 @@ -551,6 +587,7 @@ git commit -m "feat(identity): 实现用户注册接口" - 不写代码示例和错误示范 - 同类问题在原条目补充，不重复创建 - **不设"工作经验日志"区**：模块内经验沉淀在各自服务 README，known-issues 只保留索引式场景→技术映射（见 project_rules §9） +- **经验沉淀不标注 AI 身份**：AI 只做经验沉淀（场景→技术映射），不记录工作日志，不标注 AI 身份 --- @@ -601,7 +638,7 @@ git commit -m "build(contracts): 重新生成 proto 代码" - 依赖升级使用 `build(deps):` 类型 - 必须说明升级原因（安全、功能、兼容性） - 安全漏洞修复必须包含 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 版本号体系 @@ -671,20 +708,22 @@ git commit -m "feat(notification): 适配 UserRegistered v2 事件" ```mermaid flowchart TD - A[开发 AI 本地校验通过] --> B[直接 push main] - B --> C[CI 自动触发 quality + deploy] - C --> D{CI 通过?} - D -->|否| E[git revert + 修复后重新 push] - E --> B - D -->|是| F[部署至目标环境] - F --> G[健康检查轮询 /healthz] - G --> H{健康?} - H -->|否| I[输出容器日志 + 紧急回滚 §8] - H -->|是| J[发布完成] - J --> K[更新 CHANGELOG.md] + A[开发 AI 本地校验通过] --> B[分支上 git add + git commit] + B --> C[通知人类决策者合并] + C --> D[人类决策者合并到 main] + D --> E[CI 自动触发 quality + deploy] + E --> F{CI 通过?} + F -->|否| G[人类 git revert + 修复后重新合并] + G --> D + F -->|是| H[部署至目标环境] + H --> I[健康检查轮询 /healthz] + I --> J{健康?} + 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 格式 @@ -735,32 +774,36 @@ flowchart TD ### 8.1 回滚策略 -| 场景 | 回滚方式 | 耗时 | -| -------------- | ----------------------------------------- | ---------- | -| 代码缺陷 | `git revert` + push main 触发 CI 重新部署 | 5-10 分钟 | -| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 | -| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 | -| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 | -| 全站故障 | `workflow_dispatch` 指定稳定 `commit_sha` | 10-30 分钟 | +| 场景 | 回滚方式 | 耗时 | +| -------------- | --------------------------------------------------- | ---------- | +| 代码缺陷 | 人类在 main 上 `git revert` + push 触发 CI 重新部署 | 5-10 分钟 | +| 镜像问题 | `kubectl rollout undo` | 1-2 分钟 | +| 数据库迁移问题 | 执行迁移 down 脚本 | 5-30 分钟 | +| 配置错误 | 回滚 ConfigMap/Secret | 1-2 分钟 | +| 全站故障 | `workflow_dispatch` 指定稳定 `commit_sha` | 10-30 分钟 | ### 8.2 代码回滚 -> 不再创建 hotfix 分支。直接在 main 上 `git revert` 后 push，CI 自动重新部署。 +> 不创建 hotfix 分支。**由人类决策者在 main 上 `git revert` 后 push**，CI 自动重新部署。AI 不参与 main 上的回滚推送操作。 ```bash +# 人类决策者操作（AI 不执行 push main） # 1. 确认要回滚的 commit git log --oneline -10 -# 2. 拉取最新 main -git pull --rebase origin main +# 2. 切换到 main 并拉取最新 +git checkout main +git pull origin main # 3. 回滚指定 commit（生成反向 commit） git revert -# 4. 直接 push main（CI 自动触发重新部署） +# 4. push main（CI 自动触发重新部署） git push origin main ``` +> 修复型回滚也可通过新分支提交修复后由人类决策者合并，具体方式由人类决策者判断。 + ### 8.3 K8s 部署回滚 ```bash @@ -843,31 +886,32 @@ pnpm --filter identity run migrate:down -- --to ## 九、附录：CICD 与 Edu Git 工作流差异 -| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） | -| --------------------- | -------------------------------- | ----------------------------------------------------------------- | -| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） | -| 分支策略 | trunk-based | trunk-based，**直接 push main，无分支无 PR** | -| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） | -| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） | -| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） | -| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过 commit history 追溯） | -| 合并策略 | Squash Merge | **直接 push main**（无合并操作） | -| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） | -| 发布粒度 | 整体发布 | 按服务独立发布 | -| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） | -| 回滚粒度 | 整体回滚 | 按服务回滚 | -| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 | -| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） | -| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） | -| 紧急回滚 | `git revert` + 重新部署 | `git revert` + push main 触发 CI，或 `workflow_dispatch` 指定 SHA | -| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 | +| 维度 | CICD（Next.js 单应用） | Edu（微服务 monorepo） | +| --------------------- | -------------------------------- | --------------------------------------------------------------------------- | +| 仓库结构 | 单一 Next.js 应用 | 多语言 monorepo（pnpm + go.work + uv） | +| 分支策略 | trunk-based | **分支开发，AI 不切换分支，人类维护** | +| 提交规范 | Conventional Commits | Conventional Commits（沿用，scope 扩展至服务/包） | +| scope 范围 | 模块名（如 `exams`、`homework`） | 服务/包名（如 `iam`、`api-gateway`、`shared-proto`） | +| commitlint scope-enum | 35 个模块 | 26 个 scope（含服务/包/工具/平台级，与 `.commitlintrc.js` 同步） | +| 代码审查 | PR Reviewer 1 人 | **事后 review**（无 PR，通过分支 commit history 追溯） | +| 合并策略 | Squash Merge | **人类决策者手动合并分支到 main**（AI 不合并） | +| 版本号 | 单一应用版本 | 双层（平台版本 + 服务独立版本，仅记录不打 tag） | +| 发布粒度 | 整体发布 | 按服务独立发布 | +| Docker 镜像 | 单一镜像 | 每服务一镜像（no-push 本地构建，见 project_rules §15） | +| 回滚粒度 | 整体回滚 | 按服务回滚 | +| 数据库迁移 | Drizzle 单库 | 每服务独立库 + 独立迁移 | +| 文档同步 | `npm run arch:scan` | `pnpm run arch:scan`（多语言扫描） | +| CI 检查 | lint + tsc + test | lint + typecheck + test（按语言分别执行） | +| 紧急回滚 | `git revert` + 重新部署 | 人类在 main 上 `git revert` + push 触发 CI，或 `workflow_dispatch` 指定 SHA | +| 事故复盘 | known-issues.md | `incidents/` 目录独立记录 | --- ## 变更记录 -| 版本 | 日期 | 变更内容 | -| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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.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.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.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 身份 | diff --git a/docs/standards/multi-ai-collaboration.md b/docs/standards/multi-ai-collaboration.md index d4432c1..64a5f1d 100644 --- a/docs/standards/multi-ai-collaboration.md +++ b/docs/standards/multi-ai-collaboration.md @@ -1,38 +1,52 @@ # 多 AI 协作开发指南（Multi-AI Collaboration Guide） -> 版本：2.0 +> 版本：2.1 > 日期：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) --- ## 1. 总体模式 -### 1.1 角色定义 +### 1.1 默认多 AI 协作 -| 角色 | 职责 | 数量 | 备注 | -| ----------------------------- | -------------------------------------------- | ---- | ------------------- | -| **协调 AI（Coordinator AI）** | 契约管理、交叉审查、冲突仲裁、发布 | 1 | 不直接写业务代码 | -| **开发 AI（Dev AI）** | 按模块分工写代码、直接 push main | N | 每个负责 1-2 个模块 | -| **人类决策者（Human）** | 架构决策、Breaking Change 审批、最终发布确认 | 1 | 只在关键节点介入 | +本项目所有 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.2 工作流总览（直接 push main，无分支无 PR） +### 1.3 工作流总览（分支开发，AI 不切换分支） ``` -开发 AI-A (classes模块) 开发 AI-B (iam模块) 协调 AI - │ │ │ - │ 1.git pull --rebase main │ 1.git pull --rebase main│ - │ 2.本地校验+提交 │ 2.本地校验+提交 │ - │ 3.直接 push main │ 3.直接 push main │ - │ │ │ 4.CI 自动校验 - │ │ │ 5.事后审查 commit - │ │ │ 6.问题→revert/后续commit +人类决策者 开发 AI-A (classes 分支) 开发 AI-B (iam 分支) 协调 AI + │ 1.为每个任务创建分支 │ │ │ + │ 2.分配分支给对应 AI │ │ │ + │ ──────────────────────────────────►│ │ │ + │ │ 3.在分配分支上开发 │ │ + │ │ 4.本地校验 │ │ + │ │ 5.git add → 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 | | 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. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序依次直接 push（见 §5） +4. **跨模块变更拆分**：需要修改多个模块时，按依赖顺序各自在分支完成，人类按顺序合并（见 §5） 5. **基础设施独立**：`infra/` 由 coord（或 SRE AI）专门负责 -6. **物理路径隔离**：目录级别隔离，多 AI 直接 push main 几乎零文件冲突 +6. **物理路径隔离**：目录级别隔离，多 AI 在各自分支并行几乎零文件冲突 ### 2.6 架构设计外包三阶段 @@ -170,15 +186,23 @@ --- -## 3. 直接 push main 规则 +## 3. 分支开发规则 > Git 操作详细规范见 [Git 工作流](./git-workflow.md)。本节仅列多 AI 协作相关要点。 -### 3.1 提交前必做 +### 3.1 分支由人类决策者维护（强制） + +- **分支创建**：人类决策者为每个任务/模块创建分支并分配给对应 AI +- **分支合并**：人类决策者负责审查分支并合并到 `main` +- **AI 禁止执行任何分支管理命令**（见 §3.4 禁止命令清单） + +AI 接到任务后，**假设人类已为自己分配好当前工作分支**，AI 只需在该分支上工作，不需要（也不允许）切换分支。 + +### 3.2 AI 提交流程（止步于 commit） ```bash -# 1. 同步最新 main -git pull --rebase origin main +# 1. 确认当前分支（人类已分配，AI 不切换） +git branch --show-current # 2. 本地校验（强制，按语言） pnpm run lint && pnpm run typecheck # TS @@ -190,54 +214,91 @@ git add services//... git commit -m "feat(): " ``` -### 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 ---- +feat(classes): 新增班级分页查询 -AI-Agent: (<负责模块>) -Coord: <协调 AI ai-id> +- GET /api/v1/classes 支持 page、size 参数 +- 响应增加 total、hasMore 字段 +- 单测覆盖分页逻辑 ``` -> 不再有 Branch 字段（不使用分支）。详见 project_rules §14.6。 +### 3.4 AI 禁止命令清单（强制） -### 3.3 推送 +以下命令**仅人类决策者可执行，AI 严禁执行**： -```bash -# push 前再次同步（避免冲突） -git pull --rebase origin main +| 命令 | 用途 | 允许执行者 | +| ------------------------------- | --------------- | ---------------------------------- | +| `git checkout -b ` | 创建新分支 | **人类决策者** | +| `git switch ` | 切换分支 | **人类决策者** | +| `git switch -c ` | 创建并切换分支 | **人类决策者** | +| `git branch ` | 创建分支 | **人类决策者** | +| `git branch -d/-D ` | 删除分支 | **人类决策者** | +| `git merge ` | 合并分支 | **人类决策者** | +| `git push origin main` | 推送到 main | **人类决策者** | +| `git push --force-with-lease` | 强制推送 | **人类决策者**（仅事故） | +| `git rebase` | 变基 | **人类决策者**（AI 不主动 rebase） | +| `git revert` 后 `git push main` | 回滚后推送 main | **人类决策者** | -# 直接 push main -git push origin 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 -> 不再使用 PR 前置 review。代码审查改为事后追溯。详见 [Git 工作流](./git-workflow.md) §4。 +> 代码审查基于分支 commit history 进行。详见 [Git 工作流](./git-workflow.md) §4。 ### 4.1 review 责任人 -由 `.github/CODEOWNERS` 确定模块归属（CODEOWNERS 不再用于自动分配 PR reviewer，改为 commit 追溯依据）： +由 `.github/CODEOWNERS` 确定模块归属（CODEOWNERS 用于分支审查与追溯依据）： -- 模块 owner 负责事后审查涉及自己模块的 commit -- 跨模块变更由协调 AI 事后审查 -- 基础设施变更由 SRE 事后审查 +- 模块 owner 负责审查涉及自己模块的分支 +- 跨模块变更由协调 AI 审查 +- 基础设施变更由 SRE 审查 +- 人类决策者负责最终合并决策 ### 4.2 review 依据 +- 分支 commit history（`git log main..` 查看分支新增 commit） - commit message（Conventional Commits 格式） -- commit diff（`git log -p` 或平台 commit 视图） -- AI 身份标注（commit body 末尾 `AI-Agent:` 字段） +- 分支与 main 的 diff（`git diff main...`） ### 4.3 问题处理 -- **小问题**：后续 commit 修正 -- **严重问题**：`git revert ` + `git push origin main`（CI 自动重新部署） -- **架构冲突**：由协调 AI 仲裁保留方案，通过 revert + 新 commit 修正 +- **小问题**：在分支上后续 commit 修正，再次通知人类合并 +- **严重问题**：人类决策者拒绝合并，AI 在分支上 `git revert ` 后重新通知 +- **架构冲突**：由协调 AI 仲裁保留方案，分支上 revert + 新 commit 修正 +- **已合并到 main 的问题**：人类决策者在 main 上 revert，AI 不直接操作 main --- @@ -245,7 +306,7 @@ git push origin main ### 5.1 变更拆分原则 -修改涉及多模块时，按依赖顺序**依次直接 push main**（不拆 PR，按顺序提交避免下游编译失败）： +修改涉及多模块时，各 AI 在各自分支完成开发，**人类决策者按依赖顺序依次合并**（避免下游编译失败）： ``` 原始任务：classes 服务新增"班级导入"功能 @@ -256,25 +317,34 @@ git push origin main 4. teacher-portal 前端上传按钮 ``` -### 5.2 提交顺序（强制） +### 5.2 分支与合并顺序（强制） -| 顺序 | commit | scope | 负责人 | 依赖 | -| ---- | ----------------------------------------------- | -------------- | --------- | ---- | -| 1 | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto | 协调 AI | 无 | -| 2 | `feat(classes): 实现班级批量导入` | classes | 开发 AI-A | 1 | -| 3 | `feat(api-gateway): 新增 import 路由` | api-gateway | 开发 AI-B | 2 | -| 4 | `feat(teacher-portal): 新增班级导入按钮` | teacher-portal | 开发 AI-C | 3 | +| 顺序 | 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 已合并 | -> 每提交一层并 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 签名变更）： 1. **人类决策者审批**：在 issue 中讨论，获批准后才开发 2. **版本号升级**：proto 加 `v2` 后缀，服务同时支持 v1/v2 过渡期 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 启动并行任务 -人类决策者分配任务给多个 AI： +人类决策者为每个任务创建分支并分配给多个 AI： ``` -任务 1：classes 服务新增分页查询 → 开发 AI-A (ai01) -任务 2：api-gateway 新增限流规则 → 开发 AI-B (ai02) -任务 3：teacher-portal 优化班级列表 → 开发 AI-C (ai03) +任务 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 并行执行（路径隔离，直接 push main） +### 6.2 并行执行（路径隔离，各自分支） -每个 AI 在自己目录内工作，互不干扰： +每个 AI 在自己分支上、自己目录内工作，互不干扰： ```bash -# AI-A（只改 services/classes/） -git pull --rebase origin main +# 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-Agent: ai01 (classes) -Coord: coord" -git push origin main - -# AI-B（同时，只改 services/api-gateway/） -git pull --rebase origin main +# 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 级限流规则 - ---- - -AI-Agent: ai02 (api-gateway) -Coord: coord" -git push origin main +git commit -m "feat(api-gateway): 新增 IP 级限流规则" +# 通知人类决策者合并 feat/gw-ratelimit ``` ### 6.3 冲突预防 -1. **契约先行**：proto 变更先 push，再 push 依赖它的服务 -2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 issue/commit 评论 @ 所有关联模块 AI -3. **频繁同步**：每天至少 `git pull --rebase origin main` 一次，避免长期分叉 +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 -git pull --rebase origin main +# 人类决策者执行（AI 不执行 merge） +git merge feat/ # 若 pnpm-lock.yaml 冲突： git checkout --theirs pnpm-lock.yaml pnpm install git add pnpm-lock.yaml -git rebase --continue +git commit git push origin main ``` +> AI 若发现自己分支的 `pnpm-lock.yaml` 与 main 不一致，应在自己分支上 `pnpm install` 重新生成并 commit，再通知人类合并。 + --- ## 7. 完整工作流示例 @@ -347,61 +415,71 @@ git push origin main ### 场景：开发 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 ============ -# 1. 同步 main -git pull --rebase origin main +# 2. 确认当前分支（人类已分配，AI 不切换） +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.service.ts # 编辑 services/classes/src/classes/classes.repository.ts -# 3. 本地校验 +# 4. 本地校验 pnpm --filter @edu/classes-service lint pnpm --filter @edu/classes-service typecheck pnpm --filter @edu/classes-service test -# 4. 架构扫描（若新增了导出函数/路由） +# 5. 架构扫描（若新增了导出函数/路由） pnpm run arch:scan -# 5. 提交 +# 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 ，请审查合并" -AI-Agent: ai01 (classes) -Coord: coord" +# ============ 人类决策者 ============ -# 6. push 前同步 + 直接 push main -git pull --rebase origin main -git push origin main +# 8. 审查分支 +git log main..feat/classes-page --oneline +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 -# 若需修改，评论要求开发 AI-A 后续 commit 修正 -# 若严重问题，git revert + 通知 AI-A +# 若需修改，评论要求开发 AI-A 在新分支上后续 commit 修正 +# 若严重问题，由人类决策者在 main 上 git revert # ============ 开发 AI-A（若需修正） ============ -# 8. 后续 commit 修正 -git pull --rebase origin main +# 11. 等待人类决策者为修正任务创建新分支并分配 +# 在新分支上后续 commit 修正 +git branch --show-current # 确认在新分配的分支 # 编辑修复... git add services/classes/ -git commit -m "fix(classes): 修复分页 total 计算错误 - ---- - -AI-Agent: ai01 (classes) -Coord: coord" -git push origin main +git commit -m "fix(classes): 修复分页 total 计算错误" +# 通知人类决策者合并新分支 ``` --- @@ -410,22 +488,24 @@ git push origin main ### 8.1 多 AI 修改同一文件冲突 -**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖，后 push 的被拒绝。 +**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖，合并到 main 时冲突。 -**解决**： +**解决**：由**人类决策者**在合并第二个分支时解决冲突： ```bash -# 后 push 的 AI 执行 -git pull --rebase origin main +# 人类决策者执行（AI 不执行 merge） +git merge feat/ # 解决 package.json 冲突（保留两边依赖） git add package.json -git rebase --continue +git commit git push origin main ``` +AI 若预判会冲突，应提前在 issue 中与对方 AI 协调，或拆分共享文件变更到不同 commit。 + ### 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`） 3. 检查环境变量是否齐全（`.env` vs CI secrets） -**修复后**： +**修复后**：AI 在新分支上修复，再次通知人类合并： ```bash -git pull --rebase origin main +# AI 在新分配的分支上 +git branch --show-current git add -git commit -m "fix(classes): 修复 CI lint 失败 - ---- - -AI-Agent: ai01 (classes) -Coord: coord" -git push origin main +git commit -m "fix(classes): 修复 CI lint 失败" +# 通知人类决策者合并 ``` ### 8.3 husky pre-commit hook 失败 @@ -461,54 +537,60 @@ git push origin main ### 8.4 proto 变更导致下游编译失败 -**场景**：shared-proto push 后，classes 服务 `buf generate` 报错。 +**场景**：shared-proto 分支合并到 main 后，classes 服务 `buf generate` 报错。 **解决**： -1. 协调 AI push proto 变更前，在 commit 评论或 issue 中通知所有依赖服务的 AI -2. 下游 AI `git pull --rebase origin main` 后重新 `buf generate` -3. 更新生成代码并提交： +1. 协调 AI 的 proto 分支合并前，在 issue 评论中通知所有依赖服务的 AI +2. proto 分支合并到 main 后，下游 AI 在自己分支上 `git pull` 同步 main +3. 下游 AI 重新生成代码并提交： ```bash -git pull --rebase origin main +# 下游 AI 在自己分支上 +git pull origin main # 同步 main 最新（含 proto 变更） pnpm run proto:generate git add packages/shared-proto/gen/ -git commit -m "chore(shared-proto): 重新生成 TS 类型 - ---- - -AI-Agent: ai01 (classes) -Coord: coord" -git push origin main +git commit -m "chore(shared-proto): 重新生成 TS 类型" +# 通知人类决策者合并 ``` -### 8.5 误推错误代码到 main +### 8.5 误合并错误代码到 main -**场景**：开发 AI push 了有问题的代码。 +**场景**：人类决策者合并了有问题的分支到 main。 -**修复**： +**修复**（由**人类决策者**执行）： ```bash -# 1. 确认误推的 commit +# 1. 确认误合并的 commit git log --oneline -5 -# 2. 拉取最新 main -git pull --rebase origin main - -# 3. revert 误推 commit +# 2. 在 main 上 revert +git checkout main +git pull origin main git revert - -# 4. push 回滚 commit（CI 自动重新部署） -git push origin main +git push origin main # CI 自动重新部署 ``` -> 严重事故时，协调 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. 通知人类决策者：误创建了分支 ``，请处理 +3. 由人类决策者决定是否删除误创建的分支、是否将 AI 切回正确分支 +4. AI 在 issue 中记录此次违规，避免再犯 + +### 8.7 同名 AI 复用问题 + +**场景**：两个 AI 都叫 "ai01"，分工混淆。 + +**预防**：每个 AI 启动前由人类决策者分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。同名 AI 复用时，**禁止阅读前任同名 AI 的工作日志**（见 §2.1），只依据当前模块文档与 004 架构图工作。AI 标识不写入 commit，避免历史 commit 混淆。 --- @@ -516,12 +598,13 @@ git push origin main ### 9.1 通信渠道 -| 场景 | 方式 | -| ----------- | --------------------------------- | -| 事后 review | commit 评论（`@ai01 请修正 xxx`） | -| 任务分配 | Issue（`@ai01 负责实现 xxx`） | -| 紧急通知 | commit 评论 + issue @ 相关人员 | -| 架构讨论 | Issue 标签 `discussion` | +| 场景 | 方式 | +| ----------- | ------------------------------------------------ | +| 任务分配 | Issue（指定 AI、模块、分支名） | +| 合并请求 | AI 完成后通知人类决策者（issue 评论 / 即时通讯） | +| 事后 review | commit 评论（指出问题、要求修正） | +| 紧急通知 | issue + commit 评论 @ 相关人员 | +| 架构讨论 | Issue 标签 `discussion` | ### 9.2 commit 评论规范 @@ -536,21 +619,24 @@ git push origin main ### 建议 - 考虑抽取分页逻辑到 shared-ts - ---- - -协调 AI（coord） ``` -### 9.3 经验沉淀（不写跨模块日志） +> 评论不标注 AI 身份签名（如"协调 AI"字样），通过 CODEOWNERS 与分支归属自然体现审查者角色。 -> **禁止**在 `docs/troubleshooting/known-issues.md` 写跨模块"工作经验日志/流水账"。 +### 9.3 经验沉淀（不写工作日志，不标注 AI 身份） -- 模块内的经验沉淀到**自己模块的 README/文档** -- known-issues 只保留索引式"场景→技术"映射（见 project_rules §9） -- 新发现的"场景→技术"映射提炼到 known-issues 对应**模块分区**（一行索引，不写流水） +> **核心原则**：经验沉淀只记录"场景→技术/规则"映射，**不记录工作日志、不标注 AI 身份**。 -> 新 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 分支保护 -- **直接 push main**：所有 AI 直接 push，不阻塞 -- **禁止 force push**：开发 AI 无权，仅协调 AI 在事故时 `git push --force-with-lease origin main` -- **pre-commit / commit-msg / pre-push hook**：强制校验（见 git-workflow.md §3.4） -- **CI 校验**：push main 后 CI 自动跑 quality + deploy（见 project_rules §15） +- **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 main | -| ------- | -------------- | ----------------------------- | --------------- | -| 开发 AI | ✅ | ❌ | ❌ | -| 协调 AI | ✅ | ✅（shared-proto/infra/docs） | ⚠️（仅事故） | -| SRE AI | ✅（infra） | ✅（仅 infra） | ⚠️（仅事故） | +| 角色 | 切换/创建/合并分支 | 直接 push main | 修改他人模块 | force push 任何分支 | +| ---------- | ------------------ | -------------- | ----------------------------- | -------------------------------- | +| 开发 AI | ❌ | ❌ | ❌ | ❌ | +| 协调 AI | ❌ | ❌ | ✅（shared-proto/infra/docs） | ❌ | +| SRE AI | ❌ | ❌ | ✅（仅 infra） | ❌ | +| 人类决策者 | ✅ | ✅（通过合并） | ✅（审批后） | ⚠️（仅事故，--force-with-lease） | + +> 所有 AI 角色均**无分支管理权限**。AI 只在自己被分配的分支上 `git add` → `git commit`，之后通知人类合并。 ### 10.3 敏感文件保护 @@ -581,29 +671,40 @@ git push origin main - `.github/workflows/`（CI 配置） - `.trae/rules/project_rules.md`（项目规则） +AI 修改这些文件后，必须在通知人类合并时**显式说明**修改了敏感文件，等待人类决策者额外审批。 + --- ## 11. 发布流程 -> 不再使用 tag 发布与 release 分支。发布由 push main 触发 CI 自动部署。详见 [Git 工作流](./git-workflow.md) §7。 +> 发布由**人类决策者合并分支到 main**触发 CI 自动部署。详见 [Git 工作流](./git-workflow.md) §7。 ### 11.1 版本号规则 - 平台版本：`v{阶段}.{迭代}.{patch}`（仅记录，不打 git tag） - 服务版本：`{service}:{semver}`（每服务 VERSION 文件） -### 11.2 发布步骤（CI 自动） +### 11.2 发布步骤（人类决策者触发 CI） ```bash -# 开发 AI 直接 push main → CI 自动触发 quality + deploy -git push origin main +# 人类决策者执行（AI 不执行） +git checkout main +git pull origin main +git merge feat/ # 合并已审查的分支 +git push origin main # CI 自动触发 quality + deploy -# 回滚（紧急） +# 回滚（紧急，人类决策者执行） git revert git push origin main -# 或协调 AI 用 workflow_dispatch 指定稳定 commit_sha +# 或用 workflow_dispatch 指定稳定 commit_sha ``` +### 11.3 AI 在发布流程中的角色 + +- AI 完成分支开发与本地校验后，通知人类决策者合并 +- AI 不直接触发发布（不 push main） +- AI 监控 CI 结果（若 CI 失败，在新分支上修复并通知人类合并） + --- ## 12. 快速参考卡 @@ -611,47 +712,69 @@ git push origin main ### 开发 AI 日常工作流 ```bash -# 同步 main -git pull --rebase origin main +# 1. 确认当前分支（人类已分配，AI 不切换） +git branch --show-current -# 开发 → 校验 → 提交（只改自己模块目录） +# 2. 开发 → 校验 → 提交（只改自己模块目录） pnpm run lint && pnpm run typecheck git add services// -git commit -m "feat(): +git commit -m "feat(): " ---- +# 3. 通知人类决策者合并 +# "分支 ，commit ，请审查合并" -AI-Agent: () -Coord: coord" - -# push 前同步 + 直接 push main -git pull --rebase origin main -git push origin main - -# 等待事后 review，问题用后续 commit 或 git revert 修正 +# 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 -# 查看最新 commit -git pull --rebase origin main +# 查看最新合并到 main 的 commit +git pull origin main git log --oneline -10 -# 事后审查 commit +# 事后审查 main 上新合并的 commit git log -p -1 -# 评论要求修正，或严重问题 git revert +# 评论要求修正，或通知人类决策者 revert -# 紧急回滚部署 +# 紧急回滚部署（建议人类决策者执行） # workflow_dispatch 指定 commit_sha（见 project_rules §15.5） ``` +### 人类决策者日常工作流 + +```bash +# 为任务创建分支并分配给 AI +git checkout main && git pull origin main +git checkout -b feat/ +# 通知对应 AI：在 feat/ 上工作 + +# AI 通知合并后，审查并合并 +git log main..feat/ --oneline +git diff main...feat/ +git checkout main +git merge feat/ +git push origin main # CI 自动触发 + +# 删除已合并分支 +git branch -d feat/ +git push origin --delete feat/ +``` + --- ## 13. 相关文档 - [AI 分配方案](../architecture/ai-allocation.md) — 架构设计外包 AI 分配与三阶段流程 -- [Git 工作流](./git-workflow.md) — 提交规范、直接 push main、事后 review、CODEOWNERS +- [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) — 模块与依赖关系 @@ -662,7 +785,8 @@ git log -p -1 ## 变更记录 -| 版本 | 日期 | 变更内容 | -| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 禁止跨模块工作日志 | +| 版本 | 日期 | 变更内容 | +| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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 快速参考卡更新 | diff --git a/docs/troubleshooting/known-issues.md b/docs/troubleshooting/known-issues.md index 6b6432f..7ad1651 100644 --- a/docs/troubleshooting/known-issues.md +++ b/docs/troubleshooting/known-issues.md @@ -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) -> **AI 查阅时只读自己负责模块的分区（§二 对应小节），禁止读其他 AI 模块分区**，避免被历史记录或他人方案误导。模块内经验沉淀在各自服务 README。 +> **AI 查阅时只读自己负责模块的分区（§二 对应小节），禁止读其他 AI 模块分区**，避免被历史记录或他人方案误导。 +> **经验沉淀不标注 AI 身份**：所有记录只写"场景→技术/规则"映射，不得出现 AI 标识（如 ai01/ai02/coord 等），避免新同名 AI 将前任记录误认为当前事实。模块内经验沉淀在各自服务 README。 ---