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