# 06 · AI 协作协议

> **目标**:让任意 AI 工具都按同一套上下文、规则和闭环工作,避免换工具/换会话就丢上下文。
> **核心**:下面第 1 节的「六步交付流程 + 确认门」是 AI 必须严格遵守的主干,**每到一个确认门必须停下,向人类汇报并等待确认,不得自行越过**。

---

## 1. 六步交付流程(必须逐步确认)★ 主干

AI 驱动开发分为固定六步。**每一步都有一个「✋ 确认门」**:AI 完成该步动作后,先汇报结果,等人类确认/操作后才进入下一步。绝不一口气从头跑到尾。

```text
① 建仓+配Secrets → ② 开feature分支 → ③ 本地模块化开发(逐模块汇报)
     → ④ 本地CI自检(AI执行) → ⑤ 触发PR(CI在PR复检) → ⑥ 人工审核→合并→CD自动部署
   ✋确认1            ✋确认2          ✋确认3(每个模块)
                    ✋确认4           ✋确认5            ✋确认6(审核+部署结果)
```

### 第①步 · 建仓 + 配 Secrets

- **AI 动作**:用 `gh` 创建 GitHub 仓库;`main` 只放最小引导提交(`.gitignore`/占位 README),**不在 main 上做真实开发**。
- **✋ 确认门 1**:AI 报出仓库地址后,**必须提示人类去配置 GitHub Secrets**(新仓库默认为空,不配 CD 必失败):
  - `SSH_PRIVATE_KEY` / `SSH_HOST` / `SSH_USER`(见 `05` 第 5 节)。
  - AI 停下,**等人类确认「Secrets 已配置」**再继续(可用 `gh secret list` 核对)。

### 第②步 · 开 feature 分支

- **AI 动作**:从最新 `main` 切出 `feature/<issue>-<desc>` 分支(类型见 `04`);**严禁直接在 main 上开发**。
- **✋ 确认门 2**:报出分支名,确认后进入开发。

### 第③步 · 本地模块化开发 + 进度汇报

- **AI 动作**:按 `00` 目录地图**一个模块一个模块**实现,每个模块同步写测试;每完成一个模块:
  - 更新 `PROGRESS.md`(已完成/下一步)。
  - 向人类**汇报该模块进度**(做了什么、关键决定、是否有坑)。
- **✋ 确认门 3(每个模块)**:每个模块完成后汇报并确认,再做下一个模块。避免一次性写完全部再回头返工。

### 第④步 · 本地 CI 自检(由 AI 执行)

- **AI 动作**:到「需要 CI」的节点,**AI 主动确认并亲自执行**本地门禁(具备终端权限时):
  - `ruff format --check .` + `ruff check .`
  - `pytest --cov --cov-fail-under=80`
  - 项目特有门禁(如模型 `--check-auc`)
  - **本地不强制 `docker build`**(交给 CI;见 `05` 第 2 节)。
- **✋ 确认门 4**:汇报自检结果(覆盖率、指标);**全绿才进入下一步**,红则就地修复后重跑。

### 第⑤步 · 触发 PR(CI 在 PR 上复检)

- **AI 动作**:`git push` 分支后,**AI 主动 `gh pr create`** 发起 PR(用本人账号);PR 事件触发 CI 在云端再跑一遍同样门禁 + `docker build`。
- **✋ 确认门 5**:报出 PR 链接与 CI 状态(`gh run watch`);CI 绿才推进到审核。

### 第⑥步 · 人工审核 → 合并(人类) → CD 自动部署

- **✋ AI 在此硬停**:AI 发起 PR、汇报 CI 绿之后**就停下**,**不得自己合并**。合并是人类的动作。
- **人类动作**:**PR 必须由人工 Review**;审核通过后**由人类在网页点 Merge 或人工运行 `gh pr merge`**。
- **分支默认保留**:合并不加 `--delete-branch`,除非人类明确要求删除。
- **AI 动作(合并发生后)**:CD 自动触发(SSH→同步→构建→运行→健康检查;端口自愈见 `05`);AI 盯流水线。
- **✋ 确认门 6**:汇报部署结果——**最终落地端口、`/health` 结果、访问地址**;失败则读日志定位根因,修复后回到第②步走一个新分支/PR。

> 一句话:**建仓我做、Secrets 你配;分支我开(默认保留);模块我逐个写并汇报;本地 CI 我跑;PR 我发;
> 审核与合并都由你做,我绝不替你按 Merge;合并后 CD 自动跑,我盯结果。**

---

## 2. AI 开工前必须读

每次新会话,AI 必须按顺序读:

1. `standards/README.md`
2. `standards/00-project-context.md`
3. `standards/01-requirements.md`
4. `standards/PROGRESS.md`
5. `standards/02`~`06`

然后向人类复述:

```text
我理解当前项目是:...
当前阶段是(对应六步流程第几步):...
下一步应该做:...
我将遵守的关键约束是:...
```

---

## 3. 人给 AI 的标准开场 prompt

```prompt
请先读取 standards/README.md,并按顺序读取 00/01/PROGRESS 与 02~06。
读完后先复述你对项目、当前进度(对应 06 的六步流程第几步)、下一步的理解。
然后严格按 06 的「六步交付流程 + 确认门」推进:
- 每到一个确认门必须停下汇报并等我确认,不要一口气跑完。
- 建仓后提示我配置 Secrets;从 main 开 feature 分支,不直接改 main。
- 逐模块开发并汇报;本地 CI 由你执行(本地不强制 docker);CI 绿后你主动发 PR。
- 发完 PR 你就停下,**不要自己合并**;PR 由我审核并由我合并,合并后 CD 自动跑,你盯结果并汇报端口与健康检查。
- 分支默认保留,不要加 --delete-branch,除非我明确要求删。
```

---

## 4. AI 写代码边界

AI 可以:

- 新增/修改代码、测试、CI/CD 配置。
- 在具备终端权限时运行本地测试、lint、构建命令,并根据日志修复。
- 创建仓库、开分支、发起 PR(用本人账号)。
- 更新 `00/01/PROGRESS`;根据真实故障更新 `02~06`(须说明原因)。

AI 不可以:

- 硬编码密钥。
- 绕过 CI 或跳过测试。
- 明明能执行命令,却只让学生手动跑本地测试。
- 为了“看起来通过”删除测试或降低门槛。
- **越过任何确认门**(尤其:未提示配 Secrets 就推进 CD;未经确认大规模重构)。
- **自行合并任何 PR**——合并是人类的专属动作,AI 只发起 PR 并汇报,绝不替人按 Merge。
- 合并时默认 `--delete-branch` 删分支——**默认保留分支**,除非人类明确要求删除。
- 直接把项目特有内容写进通用规范,除非它已沉淀为可复用规则。

---

## 5. 故障反哺铁律

CI/CD 一旦真实跑出问题,修完代码还不算结束,必须同步完成三件事:

1. 写回 `PROGRESS.md`:现象、根因、修复、验证结果。
2. 如是通用规则,写进 `02~06` 对应标准。
3. 更新学生会照着操作的 README/课件/脚本。

判断标准:

```text
换一个学生、换一个 AI 工具,只读 standards + README,是否能避开这次坑并复现?
```

如果不能,说明闭环未完成。

---

## 6. 会话结束 prompt

```prompt
本次会话结束。请更新 standards/PROGRESS.md:
1. 当前状态(对应六步流程第几步)
2. 已完成事项
3. 下一步 TODO
4. 新增 ADR
5. 新增 GOTCHAS
保持时间倒序、简洁、可接力。
```