docs(docs): 新增本地启动/多AI协作/CI-CD 使用手册

- local-dev-runbook.md: 8 章本地启动手册（环境依赖/端口分配/开发模式/生产模式/裸机运行/常见问题） - multi-ai-collaboration.md: 15 章多AI协作文档（角色定义/模块分工/分支策略/PR流程/审核合并/跨模块变更） - cicd-runbook.md: 10 章 CI/CD 使用手册（架构总览/一次性配置/日常使用/镜像管理/部署验证/回滚） - README.md: 文档清单新增三个 runbook 链接
2026-07-08 15:14:30 +08:00
parent 3b88e9cca5
commit d19285a977
4 changed files with 1516 additions and 0 deletions
--- a/docs/standards/multi-ai-collaboration.md
+++ b/docs/standards/multi-ai-collaboration.md
@@ -0,0 +1,735 @@
+# 多 AI 协作开发指南（Multi-AI Collaboration Guide）
+
+> 版本：1.0
+> 日期：2026-07-08
+> 适用范围：Edu 微服务项目多 Agent 并行开发
+> 关联文档：[Git 工作流](./git-workflow.md)、[项目规则](../../.trae/rules/project_rules.md)、[004 架构影响地图](../architecture/004_architecture_impact_map.md)、[CODEOWNERS](../../.github/CODEOWNERS)
+
+---
+
+## 1. 总体模式
+
+### 1.1 角色定义
+
+| 角色                          | 职责                                         | 数量 | 备注                |
+| ----------------------------- | -------------------------------------------- | ---- | ------------------- |
+| **协调 AI（Coordinator AI）** | PR 审核、合并、冲突仲裁、分支管理、发布      | 1    | 不直接写业务代码    |
+| **开发 AI（Dev AI）**         | 按模块分工，写代码、提 PR                    | N    | 每个负责 1-2 个模块 |
+| **人类决策者（Human）**       | 架构决策、Breaking Change 审批、最终发布确认 | 1    | 只在关键节点介入    |
+
+### 1.2 工作流总览
+
+```
+开发 AI-A (classes模块)        开发 AI-B (iam模块)         协调 AI
+     │                              │                        │
+     │ 1.拉取最新 main              │ 1.拉取最新 main          │
+     │ 2.创建特性分支               │ 2.创建特性分支            │
+     │ 3.开发+提交                  │ 3.开发+提交              │
+     │ 4.推送+创建 PR               │ 4.推送+创建 PR            │
+     │──────────────────────────────────────────────────────→│
+     │                              │                        │ 5.CI校验
+     │                              │                        │ 6.代码审核
+     │                              │                        │ 7.合并到 main
+     │                              │                        │ 8.通知开发 AI 同步
+     │←─────────────────────────────────────────────────────│
+     │ 9.拉取最新 main              │                        │
+```
+
+---
+
+## 2. 模块分工矩阵
+
+### 2.1 模块清单与 AI 分配
+
+每个 AI 负责一个"限界上下文"，避免跨模块修改导致冲突。
+
+| 模块           | scope            | 路径                      | 负责阶段 | 建议 AI 数   |
+| -------------- | ---------------- | ------------------------- | -------- | ------------ |
+| api-gateway    | `api-gateway`    | `services/api-gateway/`   | P1       | 1            |
+| classes        | `classes`        | `services/classes/`       | P1       | 1            |
+| teacher-portal | `teacher-portal` | `apps/teacher-portal/`    | P1-P2    | 1            |
+| iam            | `iam`            | `services/iam/`           | P2       | 1            |
+| teacher-bff    | `teacher-bff`    | `services/teacher-bff/`   | P2       | 1            |
+| core-edu       | `core-edu`       | `services/core-edu/`      | P3       | 1            |
+| content        | `content`        | `services/content/`       | P4       | 1            |
+| data-ana       | `data-ana`       | `services/data-ana/`      | P4       | 1            |
+| msg            | `msg`            | `services/msg/`           | P5       | 1            |
+| ai             | `ai`             | `services/ai/`            | P5       | 1            |
+| push-gateway   | `push-gateway`   | `services/push-gateway/`  | P5       | 1            |
+| shared-proto   | `shared-proto`   | `packages/shared-proto/`  | 跨阶段   | 协调 AI 维护 |
+| shared-tokens  | `shared-tokens`  | `packages/shared-tokens/` | 跨阶段   | 协调 AI 维护 |
+| infra          | `infra`          | `infra/`                  | 跨阶段   | 1 (SRE AI)   |
+| docs           | `docs`           | `docs/`                   | 跨阶段   | 协调 AI 维护 |
+
+### 2.2 分工原则
+
+1. **单一负责制**：每个模块只有一个 AI 负责，避免并行修改同一文件
+2. **契约集中管理**：`shared-proto` 由协调 AI 维护，开发 AI 只读引用
+3. **跨模块变更拆分**：需要修改多个模块时，拆成多个 PR，按依赖顺序合并
+4. **基础设施独立**：`infra/` 由 SRE AI 专门负责，业务 AI 不直接修改
+
+---
+
+## 3. 分支策略
+
+### 3.1 分支命名规范
+
+```
+<type>/<scope>-<task-id>-<ai-id>
+```
+
+| 字段      | 说明                                        | 示例             |
+| --------- | ------------------------------------------- | ---------------- |
+| `type`    | feat / fix / refactor / docs / chore / test | `feat`           |
+| `scope`   | 模块名（见 §2.1）                           | `classes`        |
+| `task-id` | 任务简短描述（kebab-case）                  | `add-pagination` |
+| `ai-id`   | AI 标识符（避免多 AI 同名冲突）             | `ai01`           |
+
+**完整示例**：
+
+- `feat/classes-add-pagination-ai01`
+- `fix/api-gateway-redirect-loop-ai02`
+- `docs/git-workflow-update-coord`
+
+### 3.2 分支生命周期
+
+1. **创建**：从最新 `main` 拉取：`git checkout main && git pull && git checkout -b feat/classes-xxx-ai01`
+2. **开发**：在特性分支上提交（遵循 Conventional Commits）
+3. **推送**：`git push -u origin feat/classes-xxx-ai01`
+4. **合并后删除**：PR 合并后，删除本地与远程特性分支
+
+> 特性分支寿命 ≤ 3 天（见 git-workflow.md §1）。超期需 rebase 最新 main。
+
+### 3.3 多 AI 分支隔离规则
+
+- **禁止多 AI 共用同一分支**
+- **禁止直接 push 到 `main`**（由协调 AI 通过 PR 合并）
+- **跨模块变更**：各自在模块分支开发，最后由协调 AI 按依赖顺序合并
+
+---
+
+## 4. 推送与提交流程
+
+### 4.1 提交规范（Conventional Commits）
+
+```bash
+git commit -m "feat(classes): 新增班级分页查询"
+git commit -m "fix(api-gateway): 修复尾斜杠重定向循环"
+git commit -m "docs(standards): 更新多AI协作文档"
+```
+
+**scope 必须匹配 `.commitlintrc.js` 的 scope-enum**（26 项，见 git-workflow.md §3.3）。
+
+### 4.2 标准推送流程
+
+开发 AI 执行：
+
+```bash
+# 1. 确认在正确的特性分支
+git branch --show-current
+# 输出：feat/classes-add-pagination-ai01
+
+# 2. 拉取最新 main（rebase 保持线性）
+git fetch origin
+git rebase origin/main
+
+# 3. 解决冲突（如有）
+# 编辑冲突文件 → git add → git rebase --continue
+
+# 4. 本地校验（强制，见 project_rules §7）
+pnpm run lint        # TS 服务
+pnpm run typecheck   # TS 服务
+cd services/api-gateway && go vet ./... && go build ./...  # Go 服务
+
+# 5. 推送
+git push -u origin feat/classes-add-pagination-ai01
+
+# 6. 创建 PR（见 §5）
+```
+
+### 4.3 多 AI 推送冲突处理
+
+当多个 AI 的 PR 修改了同一文件（如 `package.json`、`004_architecture_impact_map.md`）：
+
+1. **先合并的 PR 正常合并**
+2. **后合并的 PR 需 rebase**：
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   # 解决冲突
+   git push --force-with-lease  # 安全强推（仅自己的分支）
+   ```
+3. **协调 AI 仲裁**：若冲突涉及架构决策，由协调 AI 决定保留方案
+
+> **禁止 `git push --force` 到 main 或他人分支**。只允许 `--force-with-lease` 到自己的特性分支。
+
+---
+
+## 5. PR 流程
+
+### 5.1 创建 PR
+
+推送后，开发 AI 通过 Git 平台（GitHub/Gitea）创建 PR：
+
+```bash
+# 使用 gh CLI（GitHub）
+gh pr create \
+  --title "feat(classes): 新增班级分页查询" \
+  --body "## 变更说明
+- 新增 GET /api/v1/classes?page=&size= 分页参数
+- 响应增加 total/hasMore 字段
+
+## 变更类型
+- [x] feat（新功能）
+
+## 影响范围
+- [x] classes 服务
+
+## 测试
+- [x] 单元测试通过
+- [x] 本地联调验证
+
+## 校验
+- [x] pnpm run lint
+- [x] pnpm run typecheck
+" \
+  --base main \
+  --head feat/classes-add-pagination-ai01
+```
+
+### 5.2 PR 标题规范
+
+PR 标题必须与首个 commit 的 subject 一致（Squash Merge 时自动取首个 commit）：
+
+```
+<type>(<scope>): <subject>
+```
+
+**示例**：
+
+- `feat(classes): 新增班级分页查询`
+- `fix(api-gateway): 修复尾斜杠重定向循环`
+
+### 5.3 PR 模板
+
+使用 `.github/pull_request_template.md`（已存在）。必填项：
+
+- 变更说明
+- 变更类型
+- 影响范围
+- 测试情况
+- 按语言校验结果
+- 文档同步（arch:scan、CODEOWNERS）
+
+### 5.4 PR 标注 AI 身份
+
+在 PR 描述末尾追加（用于统计与审计）：
+
+```markdown
+---
+
+**AI Agent**: ai01 (classes-module)
+**Branch**: feat/classes-add-pagination-ai01
+**Coordinator**: coord-ai
+```
+
+---
+
+## 6. 代码审核与合并
+
+### 6.1 Reviewer 分配
+
+由 `.github/CODEOWNERS` 自动分配：
+
+| 模块         | 自动 Reviewer           | 实际映射 |
+| ------------ | ----------------------- | -------- |
+| classes      | `@edu-platform/classes` | 协调 AI  |
+| api-gateway  | `@edu-platform/gateway` | 协调 AI  |
+| shared-proto | `@edu-platform/arch`    | 协调 AI  |
+| infra        | `@edu-platform/sre`     | SRE AI   |
+
+> 当前 `@edu-platform/*` 为占位符。多 AI 场景下，协调 AI 账号加入对应 team 即可自动收到 review 请求。
+
+### 6.2 审核 checklist
+
+协调 AI 审核 PR 时检查：
+
+- [ ] **Commit 格式**：符合 Conventional Commits
+- [ ] **Scope 正确**：scope 与修改的模块一致
+- [ ] **架构合规**：无跨层依赖、无直接访问他人 DB
+- [ ] **权限校验**：Controller 有 `@RequirePermission()`
+- [ ] **设计令牌**：无硬编码颜色/字体（project_rules §3.10）
+- [ ] **ESM 规则**：相对 import 带 `.js` 后缀（TS 服务）
+- [ ] **契约同步**：proto 变更已同步 shared-proto
+- [ ] **文档同步**：arch.db 已更新、004 已同步（如涉及）
+- [ ] **CI 通过**：lint / typecheck / go vet / ruff 全绿
+- [ ] **测试覆盖**：关键逻辑有单测
+
+### 6.3 合并策略
+
+| 策略                     | 适用场景                             | 操作                   |
+| ------------------------ | ------------------------------------ | ---------------------- |
+| **Squash Merge**（默认） | 单 commit 或多个小 commit 合并为一个 | `gh pr merge --squash` |
+| **Rebase Merge**         | 多个有意义的 commit 需保留历史       | `gh pr merge --rebase` |
+| **Merge Commit**（禁止） | —                                    | 不允许                 |
+
+> 项目规则 git-workflow.md §1.4：**禁止 Merge Commit**，保持 main 历史线性。
+
+### 6.4 合并流程（协调 AI 执行）
+
+```bash
+# 1. 确认 CI 通过
+gh pr checks <PR-NUMBER>
+
+# 2. 确认 review 通过（CODEOWNERS 已 approve）
+gh pr view <PR-NUMBER> --json reviews
+
+# 3. Squash 合并（删除源分支）
+gh pr merge <PR-NUMBER> --squash --delete-branch
+
+# 4. 通知开发 AI 同步本地 main
+# （通过 commit message 或 issue 评论）
+```
+
+### 6.5 合并后同步
+
+开发 AI 收到合并通知后：
+
+```bash
+# 切回 main
+git checkout main
+
+# 拉取最新（含已合并的 PR）
+git pull origin main
+
+# 删除本地特性分支
+git branch -d feat/classes-add-pagination-ai01
+
+# 开始下一个任务：从最新 main 拉新分支
+git checkout -b feat/classes-next-task-ai01
+```
+
+---
+
+## 7. 多 AI 并行开发流程
+
+### 7.1 启动并行任务
+
+人类决策者分配任务给多个 AI：
+
+```
+任务 1：classes 服务新增分页查询      → 开发 AI-A (ai01)
+任务 2：api-gateway 新增限流规则      → 开发 AI-B (ai02)
+任务 3：teacher-portal 优化班级列表   → 开发 AI-C (ai03)
+```
+
+### 7.2 并行执行
+
+每个 AI 独立工作，互不干扰：
+
+```bash
+# AI-A
+git checkout -b feat/classes-add-pagination-ai01
+# ... 开发 ...
+git push -u origin feat/classes-add-pagination-ai01
+gh pr create --title "feat(classes): 新增班级分页查询" ...
+
+# AI-B（同时）
+git checkout -b feat/api-gateway-rate-limit-ai02
+# ... 开发 ...
+git push -u origin feat/api-gateway-rate-limit-ai02
+gh pr create --title "feat(api-gateway): 新增 IP 级限流规则" ...
+
+# AI-C（同时）
+git checkout -b feat/teacher-portal-class-list-ux-ai03
+# ... 开发 ...
+```
+
+### 7.3 顺序合并（有依赖时）
+
+若 PR 间有依赖（如 AI-C 依赖 AI-A 的接口），协调 AI 按顺序合并：
+
+1. 合并 AI-A 的 PR（classes 分页接口）
+2. AI-C rebase 最新 main，解决冲突，更新 PR
+3. 合并 AI-C 的 PR（前端调用新接口）
+
+### 7.4 冲突预防
+
+1. **契约先行**：proto 变更先合并，再合并依赖它的服务
+2. **通知机制**：修改 `shared-proto/` 或 `004_architecture_impact_map.md` 时，在 PR 描述 @ 所有关联模块 AI
+3. **频繁同步**：每天至少 `git pull origin main` 一次，避免长期分叉
+
+---
+
+## 8. 跨模块变更流程
+
+### 8.1 变更拆分原则
+
+修改涉及多模块时，按依赖顺序拆成多个 PR：
+
+```
+原始任务：classes 服务新增"班级导入"功能
+涉及：
+  1. shared-proto 新增 ImportClassesRequest message
+  2. classes 服务实现 import 接口
+  3. api-gateway 路由 /api/v1/classes/import
+  4. teacher-portal 前端上传按钮
+```
+
+### 8.2 拆分与合并顺序
+
+| 顺序 | PR                                              | scope          | 负责人    | 依赖 |
+| ---- | ----------------------------------------------- | -------------- | --------- | ---- |
+| 1    | `feat(shared-proto): 新增 ImportClassesRequest` | shared-proto   | 协调 AI   | 无   |
+| 2    | `feat(classes): 实现班级批量导入`               | classes        | 开发 AI-A | PR-1 |
+| 3    | `feat(api-gateway): 新增 import 路由`           | api-gateway    | 开发 AI-B | PR-2 |
+| 4    | `feat(teacher-portal): 新增班级导入按钮`        | teacher-portal | 开发 AI-C | PR-3 |
+
+协调 AI 按顺序合并，每合并一个，后续 PR 的开发 AI rebase 最新 main。
+
+### 8.3 Breaking Change 流程
+
+涉及 Breaking Change（proto 字段删除、API 签名变更）：
+
+1. **人类决策者审批**：在 issue 中讨论，获批准后才开发
+2. **版本号升级**：proto 加 `v2` 后缀，服务同时支持 v1/v2 过渡期
+3. **迁移文档**：更新 `MIGRATION_GUIDE.md`
+4. **协调 AI 通知所有相关 AI**：在 PR 描述中列出影响范围
+
+---
+
+## 9. 完整工作流示例
+
+### 9.1 场景：开发 AI-A 为 classes 新增分页查询
+
+```bash
+# ============ 开发 AI-A ============
+
+# 1. 同步 main
+git checkout main
+git pull origin main
+
+# 2. 创建特性分支
+git checkout -b feat/classes-add-pagination-ai01
+
+# 3. 开发
+# 编辑 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. 提交
+git add services/classes/
+git commit -m "feat(classes): 新增班级分页查询
+
+- GET /api/v1/classes 支持 page、size 参数
+- 响应增加 total、hasMore 字段
+- 单测覆盖分页逻辑"
+
+# 7. 推送
+git push -u origin feat/classes-add-pagination-ai01
+
+# 8. 创建 PR
+gh pr create \
+  --title "feat(classes): 新增班级分页查询" \
+  --body "..." \
+  --base main
+
+# ============ 协调 AI ============
+
+# 9. 收到 PR 通知，审核
+gh pr view <PR-NUMBER>
+gh pr checks <PR-NUMBER>
+
+# 10. 代码审核（见 §6.2 checklist）
+# 若需修改，评论要求开发 AI-A 修改
+
+# 11. 合并
+gh pr merge <PR-NUMBER> --squash --delete-branch
+
+# 12. 通知开发 AI-A
+# 评论："已合并，请同步本地 main"
+
+# ============ 开发 AI-A ============
+
+# 13. 同步
+git checkout main
+git pull origin main
+git branch -d feat/classes-add-pagination-ai01
+```
+
+---
+
+## 10. 常见问题与解决方案
+
+### 10.1 多 AI 修改同一文件冲突
+
+**场景**：AI-A 和 AI-B 都修改了 `package.json` 添加依赖。
+
+**解决**：
+
+1. AI-A 的 PR 先合并
+2. AI-B 执行：
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   # 解决 package.json 冲突（保留两边依赖）
+   git add package.json
+   git rebase --continue
+   git push --force-with-lease
+   ```
+3. 协调 AI 重新审核
+
+### 10.2 CI 失败但本地通过
+
+**场景**：开发 AI 本地 lint 通过，CI 报错。
+
+**排查**：
+
+1. 检查 Node/Go/pnpm 版本是否一致（见 local-dev-runbook §1）
+2. 检查 `pnpm-lock.yaml` 是否最新（`pnpm install --frozen-lockfile`）
+3. 检查环境变量是否齐全（`.env` vs CI secrets）
+
+**修复后**：
+
+```bash
+git add <fixed-files>
+git commit -m "fix(classes): 修复 CI lint 失败"
+git push
+```
+
+### 10.3 husky pre-commit hook 失败
+
+**场景**：commit 时 hook 报错（lint-staged、commitlint）。
+
+**排查**：
+
+1. commitlint：检查 commit message 格式（type 小写、scope 在 enum 内、subject 不大写开头）
+2. lint-staged：检查暂存文件是否通过 ESLint/gofmt
+3. husky 9 Windows bug：若 pre-push hook "Bad file descriptor"，见 known-issues
+
+**修复**：修正后重新 `git commit`，不要用 `--no-verify` 跳过。
+
+### 10.4 proto 变更导致下游编译失败
+
+**场景**：shared-proto 合并后，classes 服务 `buf generate` 报错。
+
+**解决**：
+
+1. 协调 AI 合并 proto PR 前，先在 PR 评论中通知所有依赖服务的 AI
+2. 下游 AI 在自己的分支 rebase 最新 main 后重新 `buf generate`
+3. 更新生成代码并提交：
+   ```bash
+   git add packages/shared-proto/gen/
+   git commit -m "chore(shared-proto): 重新生成 TS 类型"
+   ```
+
+### 10.5 分支长期未合并（超 3 天）
+
+**场景**：特性分支超过 3 天未合并。
+
+**处理**：
+
+1. rebase 最新 main：`git rebase origin/main`
+2. 解决冲突后 `git push --force-with-lease`
+3. 若仍无法合并，协调 AI 介入评估是否拆分 PR
+
+### 10.6 误推到 main
+
+**场景**：开发 AI 误将 commit 推到 main。
+
+**修复**（协调 AI 执行）：
+
+```bash
+# 1. 确认误推的 commit
+git log origin/main -5
+
+# 2. 回退（保留误推 commit 到临时分支）
+git checkout origin/main -b temp/backup-mispush
+git checkout main
+git reset --hard origin/main~1  # 回退 1 个 commit
+
+# 3. 强推（仅协调 AI 有权限）
+git push --force-with-lease origin main
+
+# 4. 通知开发 AI 从 temp 分支重新提 PR
+```
+
+> **禁止开发 AI 自行 force push main**。只有协调 AI 有权操作。
+
+### 10.7 AI 身份冲突（同名分支）
+
+**场景**：两个 AI 都叫 "ai01"，创建了同名分支。
+
+**预防**：每个 AI 启动前分配唯一 `ai-id`（如 `ai01`、`ai02`、`coord`）。
+
+**修复**：后启动的 AI 重命名分支：
+
+```bash
+git branch -m feat/classes-xxx-ai01 feat/classes-xxx-ai01b
+git push -u origin feat/classes-xxx-ai01b
+```
+
+---
+
+## 11. AI 协作通信约定
+
+### 11.1 通信渠道
+
+| 场景     | 方式                          |
+| -------- | ----------------------------- |
+| PR 审核  | PR 评论（`@ai01 请修改 xxx`） |
+| 任务分配 | Issue（`@ai01 负责实现 xxx`） |
+| 紧急通知 | PR 评论 + @ 相关人员          |
+| 架构讨论 | Issue 标签 `discussion`       |
+
+### 11.2 PR 评论规范
+
+协调 AI 审核评论格式：
+
+```
+## 审核结果：需修改 / 通过 / 拒绝
+
+### 需修改项
+1. [classes.controller.ts:42] 缺少 @RequirePermission() 装饰器
+2. [classes.service.ts:88] 返回值未标注 Promise<T>
+
+### 建议
+- 考虑抽取分页逻辑到 shared-ts
+
+---
+协调 AI（coord）
+```
+
+### 11.3 AI 工作日志
+
+每个 AI 完成任务后，在 `docs/troubleshooting/known-issues.md` "工作经验日志"区追加（project_rules §9.3）：
+
+```markdown
+| 日期             | 模块    | 做了什么 + 学到什么                             |
+| ---------------- | ------- | ----------------------------------------------- |
+| 2026-07-08 14:00 | classes | 实现分页查询，学到 Drizzle 的 limit/offset 用法 |
+```
+
+---
+
+## 12. 安全与权限
+
+### 12.1 分支保护规则（main）
+
+- **禁止直接 push**：必须通过 PR
+- **必须 PR review**：至少 1 人（CODEOWNERS 自动分配）
+- **必须 CI 通过**：lint / typecheck / build
+- **禁止 force push**：开发 AI 无权，仅协调 AI 在事故时操作
+
+### 12.2 AI 账号权限
+
+| 角色    | push 特性分支 | 创建 PR | 合并 PR     | push main | force push main |
+| ------- | ------------- | ------- | ----------- | --------- | --------------- |
+| 开发 AI | ✅            | ✅      | ❌          | ❌        | ❌              |
+| 协调 AI | ✅            | ✅      | ✅          | ❌        | ⚠️（仅事故）    |
+| SRE AI  | ✅（infra）   | ✅      | ✅（infra） | ❌        | ⚠️（仅事故）    |
+
+### 12.3 敏感文件保护
+
+以下文件修改需人类决策者额外审批：
+
+- `.env`、`.env.example`（密钥相关）
+- `infra/security/secrets.example.env`
+- `infra/k8s/`（生产部署）
+- `.github/workflows/`（CI 配置）
+
+---
+
+## 13. 发布流程
+
+### 13.1 版本号规则（见 git-workflow.md §7）
+
+- 平台版本：`v{阶段}.{迭代}.{patch}`（如 `v1.2.0`）
+- 服务版本：`{service}:{semver}`（如 `classes:1.0.1`）
+
+### 13.2 发布步骤（协调 AI 执行）
+
+```bash
+# 1. 确认 main 稳定（CI 全绿）
+gh run list --branch main --limit 5
+
+# 2. 打 tag
+git tag -a v1.2.0 -m "P1 阶段第 2 次迭代发布"
+git push origin v1.2.0
+
+# 3. 触发 CI 构建镜像
+# （CI 由 tag push 触发，见 .github/workflows/）
+
+# 4. 人类决策者确认部署到生产
+```
+
+### 13.3 回滚（见 git-workflow.md §8）
+
+```bash
+# K8s 回滚
+kubectl rollout undo deployment/api-gateway -n edu-system
+
+# Git 回退（紧急）
+git revert <bad-commit>
+git push origin main
+```
+
+---
+
+## 14. 快速参考卡
+
+### 开发 AI 日常工作流
+
+```bash
+# 拉新分支
+git checkout main && git pull && git checkout -b feat/<scope>-<task>-<ai-id>
+
+# 开发 → 校验 → 提交
+pnpm run lint && pnpm run typecheck
+git add . && git commit -m "feat(<scope>): <subject>"
+
+# 推送 → 创建 PR
+git push -u origin feat/<scope>-<task>-<ai-id>
+gh pr create --title "feat(<scope>): <subject>" --body "..."
+
+# 等待审核 → 修改 → 重新推送
+# （协调 AI 合并后）
+git checkout main && git pull && git branch -d feat/<scope>-<task>-<ai-id>
+```
+
+### 协调 AI 日常工作流
+
+```bash
+# 查看待审核 PR
+gh pr list --state open --reviewer @edu-platform/arch
+
+# 审核
+gh pr view <PR-NUMBER>
+gh pr checks <PR-NUMBER>
+
+# 合并
+gh pr merge <PR-NUMBER> --squash --delete-branch
+
+# 发布
+git tag -a v<version> -m "..." && git push origin v<version>
+```
+
+---
+
+## 15. 相关文档
+
+- [Git 工作流](./git-workflow.md) — 提交规范、分支策略、CODEOWNERS
+- [本地启动手册](./local-dev-runbook.md) — 手动启动服务
+- [项目规则](../../.trae/rules/project_rules.md) — 强制约束
+- [004 架构影响地图](../architecture/004_architecture_impact_map.md) — 模块与依赖关系
+- [CODEOWNERS](../../.github/CODEOWNERS) — Reviewer 自动分配
+- [PR 模板](../../.github/pull_request_template.md) — PR 必填项
+- [known-issues](../troubleshooting/known-issues.md) — 已知问题速查