QLHazyCoder
403 lines
14 KiB
Markdown
403 lines
14 KiB
Markdown
# 开发者 AI 开发与 PR 流程
|
||
|
||
请开发者们先让自己的 AI 阅读此文件。
|
||
|
||
AI 在本仓库里进行开发、整理改动、发起 PR、更新 PR、补充说明时，都必须按本文执行，不能跳步，不能猜，不能自创流程。
|
||
|
||
本文面向“开发者自己电脑上的 AI”，不是给仓库维护者批量处理别人 PR 用的，也不是版本发布流程。
|
||
|
||
## 使用前准备
|
||
|
||
在让 AI 操作 GitHub 之前，开发者本机必须先安装 GitHub CLI，并完成登录。
|
||
|
||
最低要求：
|
||
|
||
1. 本机已安装 `git`
|
||
2. 本机已安装 GitHub CLI，也就是 `gh`
|
||
3. 已完成 GitHub 登录
|
||
4. 当前账号对目标仓库至少有读取权限；如果要推分支、改 PR、合并 PR，还需要对应写权限
|
||
|
||
登录示例：
|
||
|
||
```powershell
|
||
gh auth login
|
||
```
|
||
|
||
如果 AI 检查到 `gh` 不可用，或者 `gh auth status` 显示未登录、登录到错误账号、权限不足，则必须先停止并明确告诉开发者，不准假装已经完成 GitHub 操作。
|
||
|
||
## 本文适用场景
|
||
|
||
适用于下面这些任务：
|
||
|
||
- 开发新功能
|
||
- 修复 bug
|
||
- 清理陈旧逻辑
|
||
- 整理本地提交
|
||
- 发起新的 PR
|
||
- 更新已有 PR
|
||
- 在自己的 PR 下补充说明
|
||
- 在权限允许时，把自己的 PR 合并到 `dev`
|
||
|
||
不适用于：
|
||
|
||
- 版本发布
|
||
- 直接把代码合并到 `master`
|
||
- 在没看代码上下文的前提下，靠猜测生成 PR 结论
|
||
|
||
## 仓库硬性规则
|
||
|
||
1. 任何结论都不能猜，必须基于真实命令输出、真实 diff、真实代码上下文。
|
||
2. 开发基线分支只能是 `dev`。AI 不得以 `master` 作为日常开发起点，也不得把 PR 目标分支设为 `master`。
|
||
3. 发起 PR 前，必须先同步最新远端提交，确保当前分支已经对齐最新 `origin/dev`。
|
||
4. 如果发现当前 PR 的目标分支是 `master`，AI 必须立刻改为 `dev`，然后重新检查 PR 信息。
|
||
5. 如果当前工作区有无法确认归属的脏改动，AI 必须先停下来告诉开发者，不能偷偷带进本次 PR，也不能擅自删除。
|
||
6. 开发新功能时，不要为了兼容旧逻辑而保留明显无用的陈旧代码；如果确认无其他代码依赖，应一并清理。
|
||
7. 如果旧逻辑本身设计差、实现混乱或者存在 bug，AI 需要继续检查相关调用点；在不影响其他功能的前提下，可以顺手一起修正。
|
||
8. 如果改动了 SQL 文件，必须按仓库规则同步本地 MySQL：账号 `root`，密码 `123456`，数据库 `xzs`。
|
||
9. 默认不做无关编译，但代码改动后必须按 [项目开发规范（AI协作）.md](./项目开发规范（AI协作）.md) 执行必要的定向测试与全量回归；无法执行时必须明确说明原因。
|
||
10. 如果是前端改动且需要本地启动验证，可以自行启动后完成最小验证；验证结束后要关闭占用端口，并在结果里明确说明“实际执行了什么、没有执行什么”。
|
||
11. PR 标题、PR 正文、PR 评论都用自然中文直接表达，不要写“自动回复”“AI 分析结果如下”这种固定机器人腔。
|
||
12. 没有开发者明确授权时，AI 不得擅自合并 PR、关闭 PR、删除远端分支。
|
||
13. 必须严格区分“同步 PR 分支”和“合并 PR 到 `dev`”：
|
||
- `git merge origin/dev`、`git rebase origin/dev`、把最新 `dev` 推回 PR 源分支，只是让 PR 分支吸收最新基线，不等于合并 PR。
|
||
- 只有通过 GitHub PR 合并动作，例如 `gh pr merge <PR_NUMBER> --merge`，并确认 `origin/dev` 已前进到合并提交，才算“合并到 `dev`”。
|
||
14. 如果开发者明确说“合并进 dev”“合到 dev”“通过就合”“没问题就合并”“处理完直接合并”这类表达，AI 必须执行阶段 8 的真实 PR 合并流程；不能只更新 PR 分支后声称已经合并。
|
||
|
||
## 开发者需要提供给 AI 的信息
|
||
|
||
至少提供下面这些内容：
|
||
|
||
- 仓库本地路径
|
||
- 本次要做的功能或问题描述
|
||
- 是新任务，还是继续一个已有分支/已有 PR
|
||
- 如果已经有 PR，要提供 PR 编号
|
||
- 是否允许 AI 在自己的功能分支上执行 `rebase`
|
||
- 是否允许 AI 在最后直接发起 PR
|
||
- 如果 PR 已经审完，是否允许 AI 直接合并到 `dev`
|
||
|
||
如果这些关键信息缺失，AI 不能靠猜来补。
|
||
|
||
## 标准执行顺序
|
||
|
||
### 阶段 1：环境确认与仓库现状检查
|
||
|
||
AI 开始干活前，先执行下面这些动作：
|
||
|
||
```powershell
|
||
gh --version
|
||
gh auth status
|
||
git status --short --branch
|
||
git remote -v
|
||
git branch --show-current
|
||
git fetch origin
|
||
```
|
||
|
||
要求：
|
||
|
||
1. 必须先确认 `gh` 可用且已登录。
|
||
2. 必须确认当前仓库远端是正确仓库。
|
||
3. 必须确认当前工作区是否有未提交改动。
|
||
4. 不能在没看当前分支状态的情况下直接开始写代码或直接发 PR。
|
||
|
||
### 阶段 2：先对齐最新 `dev`
|
||
|
||
#### 场景 A：这是一个新任务
|
||
|
||
如果是新任务，还没开始写代码，则必须先同步最新 `dev`：
|
||
|
||
```powershell
|
||
git switch dev
|
||
git pull --ff-only origin dev
|
||
git switch -c <feature-branch>
|
||
```
|
||
|
||
规则：
|
||
|
||
1. 新任务必须从最新 `dev` 拉出功能分支。
|
||
2. 不允许直接在 `dev` 上开发。
|
||
3. 不允许从 `master` 拉开发分支。
|
||
|
||
#### 场景 B：这是一个已有分支上的继续开发
|
||
|
||
如果开发已经在某个功能分支上进行，则不能为了同步 `dev` 直接丢本地改动。
|
||
|
||
这时至少要先执行：
|
||
|
||
```powershell
|
||
git fetch origin
|
||
git rev-list --left-right --count origin/dev...HEAD
|
||
git log --oneline HEAD..origin/dev
|
||
```
|
||
|
||
要求：
|
||
|
||
1. 必须真实判断当前分支是否已经落后于 `origin/dev`。
|
||
2. 如果当前分支落后，先继续开发可以，但在发起 PR 前必须补齐最新 `dev`。
|
||
3. 如果当前分支已经出现复杂冲突风险，AI 需要提前告诉开发者，不要拖到最后一刻再爆。
|
||
|
||
### 阶段 3：开发与本地整理
|
||
|
||
AI 开发时，必须遵守下面这些要求：
|
||
|
||
1. 先读相关代码上下文，再改代码。
|
||
2. 不能只改表面调用点，必须检查相关联的状态流、配置项、消息流、页面流程、回调流程。
|
||
3. 如果发现本次功能附近本来就有坏逻辑，而且修复不会影响其他已使用代码，可以顺手一并修正。
|
||
4. 如果为了完成新功能必须删除旧逻辑，就删除，不要为了“看起来兼容”堆陈旧代码。
|
||
5. 改完后必须自己检查：
|
||
- `git diff --stat`
|
||
- `git diff`
|
||
- 相关文件中是否残留冲突标记
|
||
- 是否混入无关改动
|
||
6. 如果改了 SQL，别忘了同步本地 MySQL `xzs`。
|
||
|
||
### 阶段 4：发起 PR 前必须再次同步最新 `dev`
|
||
|
||
这是硬规则。
|
||
|
||
无论这个分支什么时候开始开发，只要准备发起 PR，就必须再次拉取远端最新提交，并确认当前分支已经吸收了最新 `origin/dev`。
|
||
|
||
先执行：
|
||
|
||
```powershell
|
||
git fetch origin
|
||
git log --oneline HEAD..origin/dev
|
||
```
|
||
|
||
#### 如果 `origin/dev` 没有新提交
|
||
|
||
可以继续进入下一阶段。
|
||
|
||
#### 如果 `origin/dev` 有新提交
|
||
|
||
优先处理方式：
|
||
|
||
```powershell
|
||
git rebase origin/dev
|
||
```
|
||
|
||
如果开发者明确禁止改写当前分支历史，或者这个分支已经有多人共同使用，再改用：
|
||
|
||
```powershell
|
||
git merge origin/dev
|
||
```
|
||
|
||
处理规则：
|
||
|
||
1. 如果执行了 `rebase`，必须重新检查 diff，确认没有把逻辑改坏。
|
||
2. 如果执行了 `rebase` 且当前分支之前已经推到远端，后续推送时只能使用：
|
||
|
||
```powershell
|
||
git push --force-with-lease origin <feature-branch>
|
||
```
|
||
|
||
3. 不允许使用 `git push --force`。
|
||
4. 不能只把冲突标记删掉就算完，必须继续检查冲突两边的真实逻辑是否仍然一致。
|
||
|
||
### 阶段 5：提交与推送
|
||
|
||
在发起 PR 前，AI 必须先把本次改动整理干净。
|
||
|
||
至少要执行下面这些检查：
|
||
|
||
```powershell
|
||
git status --short
|
||
git diff --stat origin/dev...HEAD
|
||
git diff origin/dev...HEAD
|
||
```
|
||
|
||
要求：
|
||
|
||
1. PR 中只能包含与本次任务相关的改动。
|
||
2. 不要把临时调试代码、无关格式化、无关文件重命名、构建产物一起带进 PR。
|
||
3. 提交信息必须描述真实功能结果，不要写：
|
||
- `update`
|
||
- `fix bug`
|
||
- `merge branch`
|
||
- `修改一下`
|
||
4. 推送前要确认当前分支不是 `dev`，也不是 `master`。
|
||
|
||
推送示例：
|
||
|
||
```powershell
|
||
git push -u origin <feature-branch>
|
||
```
|
||
|
||
### 阶段 6：创建或更新 PR
|
||
|
||
PR 只能指向 `dev`。
|
||
|
||
创建 PR 时使用：
|
||
|
||
```powershell
|
||
gh pr create --base dev --head <feature-branch> --title "<PR标题>" --body-file <PR正文文件>
|
||
```
|
||
|
||
如果 PR 已经存在，则执行：
|
||
|
||
```powershell
|
||
gh pr view <PR_NUMBER> --json number,title,baseRefName,headRefName,state,isDraft,url
|
||
```
|
||
|
||
如果发现已有 PR 的目标分支不是 `dev`，必须改正：
|
||
|
||
```powershell
|
||
gh pr edit <PR_NUMBER> --base dev
|
||
```
|
||
|
||
改完后，再重新读取一次 PR 信息，确认：
|
||
|
||
- `baseRefName = dev`
|
||
- PR 仍是 open
|
||
- head 分支正确
|
||
|
||
#### PR 标题要求
|
||
|
||
1. 直接描述功能结果或修复结果。
|
||
2. 不要把标题写成 Git 动作描述。
|
||
3. 不要写空洞标题。
|
||
|
||
#### PR 正文要求
|
||
|
||
PR 正文直接写真实信息，建议结构如下：
|
||
|
||
```markdown
|
||
## 本次改动
|
||
- ...
|
||
|
||
## 风险与影响
|
||
- ...
|
||
|
||
## 测试情况
|
||
- 未运行测试，请开发者自行验证
|
||
```
|
||
|
||
说明：
|
||
|
||
1. 正文必须基于真实改动来写。
|
||
2. 不要写固定“自动回复”抬头。
|
||
3. 不要写和代码不相符的夸大表述。
|
||
|
||
### 阶段 7：PR 后续补充说明
|
||
|
||
如果 AI 需要在 PR 里补充评论、解释冲突、说明待确认点，要求如下：
|
||
|
||
1. 直接写清楚问题、原因、影响、建议。
|
||
2. 语气自然、简洁、可读。
|
||
3. 不要使用固定机器人模板。
|
||
4. 不要为了“像 AI”而加免责声明废话。
|
||
5. 评论内容必须和真实代码、真实 diff、真实冲突一致。
|
||
|
||
### 阶段 8：只有在明确授权时，才允许合并 PR
|
||
|
||
如果开发者明确要求 AI 继续合并自己的 PR，则必须先再次确认：
|
||
|
||
```powershell
|
||
gh pr view <PR_NUMBER> --json number,title,baseRefName,headRefName,state,isDraft,mergeable,mergeStateStatus,url
|
||
git fetch origin
|
||
git log --oneline HEAD..origin/dev
|
||
```
|
||
|
||
合并前必须满足：
|
||
|
||
1. PR 目标分支是 `dev`
|
||
2. PR 不是 draft
|
||
3. PR 仍然是 open
|
||
4. 当前分支已经吸收了最新 `origin/dev`
|
||
5. 没有尚未处理的明确问题
|
||
6. 开发者已经明确授权合并
|
||
|
||
如果满足以上条件，才可以执行 GitHub 合并，例如：
|
||
|
||
```powershell
|
||
gh pr merge <PR_NUMBER> --merge --delete-branch
|
||
```
|
||
|
||
注意：
|
||
|
||
1. 这一步才是“把 PR 合并到 `dev`”。把 `origin/dev` 合并到功能分支、把功能分支推回 PR、让 PR 变成可合并，都不算已经合并到 `dev`。
|
||
2. 如果不打算删除 PR 源分支，可以去掉 `--delete-branch`，但仍然必须执行 `gh pr merge`。
|
||
3. `gh pr merge` 成功后，必须立刻验证 PR 和本地 `dev`：
|
||
|
||
```powershell
|
||
gh pr view <PR_NUMBER> --json number,state,mergedAt,mergedBy,baseRefName,url,mergeCommit
|
||
git fetch origin
|
||
git switch dev
|
||
git pull --ff-only origin dev
|
||
git rev-parse HEAD origin/dev
|
||
git log --oneline -1
|
||
```
|
||
|
||
验证要求：
|
||
|
||
1. `state` 必须是 `MERGED`。
|
||
2. `baseRefName` 必须是 `dev`。
|
||
3. `mergeCommit.oid` 必须存在。
|
||
4. `git rev-parse HEAD origin/dev` 输出的两个提交必须一致。
|
||
5. 本地 `dev` 的最新提交必须是该 PR 的合并提交，或包含该 PR 合并结果的后续 `dev` 提交。
|
||
6. 如果本地有无关脏改动导致不能切回或快进 `dev`，必须明确告诉开发者“远端 PR 已合并，但本地 `dev` 尚未更新”，不能说本地也已经完成。
|
||
|
||
限制：
|
||
|
||
1. AI 只能把自己的 PR 合并到 `dev`。
|
||
2. AI 不得把任何开发分支直接合并到 `master`。
|
||
3. 如果发现 PR 目标分支是 `master`，先改成 `dev`，再重新核对是否允许继续。
|
||
|
||
## 开发清单
|
||
|
||
开发时按下面清单自检，避免漏项：
|
||
|
||
### 第 1 阶段：开始前
|
||
|
||
- `gh` 已安装且已登录
|
||
- 当前仓库正确
|
||
- 当前工作区状态已确认
|
||
- 已明确本次任务是否是新任务还是续做
|
||
|
||
### 第 2 阶段：开发前基线
|
||
|
||
- 新任务已从最新 `dev` 拉分支
|
||
- 续做任务已确认自己相对 `origin/dev` 的落后情况
|
||
- 没有误在 `master` 或 `dev` 上直接开发
|
||
|
||
### 第 3 阶段：开发中
|
||
|
||
- 代码上下文已阅读
|
||
- 相关联逻辑已检查
|
||
- 无用旧代码已清理
|
||
- SQL 改动已同步本地数据库
|
||
|
||
### 第 4 阶段：发 PR 前
|
||
|
||
- 已再次获取最新 `origin/dev`
|
||
- 已完成 `rebase` 或 `merge`
|
||
- diff 只包含本次任务改动
|
||
- 提交信息清晰
|
||
- 当前分支不是 `dev` / `master`
|
||
|
||
### 第 5 阶段：PR 与收尾
|
||
|
||
- PR 目标分支确认是 `dev`
|
||
- PR 标题和正文与真实改动一致
|
||
- 如有评论，内容为自然中文，不用固定机器人模板
|
||
- 如果未跑测试，已明确提醒开发者测试
|
||
- 如果开发者授权合并，已确认 PR 状态为 `MERGED`，且本地 `dev` 与 `origin/dev` 指向同一提交
|
||
|
||
## 最终反馈给开发者时必须说明
|
||
|
||
AI 完成后，至少要向开发者明确反馈下面这些信息：
|
||
|
||
1. 实际执行了哪些命令和动作
|
||
2. 当前分支是否已经同步最新 `origin/dev`
|
||
3. 是否创建了新 PR，或者更新了已有 PR
|
||
4. PR 编号和链接是什么
|
||
5. PR 目标分支是否确认是 `dev`
|
||
6. 是否执行了 `rebase` 或 `merge`
|
||
7. 是否改了 SQL 并同步了本地数据库
|
||
8. 是否运行过测试；如果没跑，要明确提醒开发者自行测试
|
||
9. 是否已经合并；如果已合并，要明确说明是合并到 `dev`
|
||
10. 如果已合并，必须说明 PR 状态是否为 `MERGED`、合并提交是什么、本地 `dev` 和 `origin/dev` 是否已经一致
|
||
|
||
## 一句话执行要求
|
||
|
||
AI 在本仓库里做开发与提 PR 时，必须按“先确认环境与当前工作区，再对齐最新 `dev`，再开发与整理改动，再次同步最新 `dev`，最后只向 `dev` 发起或更新 PR；只有在开发者明确授权时，才允许把自己的 PR 合并到 `dev`”的顺序执行，不能跳步，不能猜，不能偷懒。
|