# 仓库协作者用 AI 分析 PR 与合并标准流程

## 用途

本文件用于给仓库协作者自己电脑上的 AI 一个固定、完整、可重复执行的 PR 处理流程。

执行本流程时，AI 必须同时把下面三份根目录文档作为审查依据一起阅读：

- [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md)
- [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md)
- [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)

下次只要告诉 AI：

- 本仓库根目录
- 要处理的 PR 编号
- 是否只分析，还是分析后需要继续合并

再把本文件提供给 AI，AI 就必须按本文件执行，不能自行脑补流程。

## 仓库硬性规则

1. 任何结论都不能猜，必须基于真实命令输出、真实 diff、真实代码上下文。
2. 优先使用当前环境可直接执行的 `gh`、`git` 命令；如果命令不存在、认证失败、权限不足，必须立刻明确告知用户并停止，不能假装已经操作成功。
3. 本仓库自动处理的唯一目标分支是 `dev`。AI 不得把其他作者的 PR 直接作为自动流程合并到 `master`。
4. 任何分支判断都必须以实时 `gh pr view` 返回的 `baseRefName` 为准，不能只信用户口述、PR 标题或截图描述。
5. 如果 PR 当前目标分支是 `master`，AI 必须先自动把它改到 `dev`，然后重新拉取 PR 元数据与 diff，再继续分析。
6. 如果 PR 当前目标分支既不是 `dev` 也不是 `master`，AI 不得擅自改到别的分支，必须停止并告诉用户当前自动流程只支持 `dev`。
7. 如果把 `master` 转到 `dev` 时发现同一个来源仓库 + 来源分支已经存在另一个指向 `dev` 的打开 PR，AI 不得继续硬转，不得继续自动合并，必须先反馈重复 PR 问题。
8. 用户当前工作区可能是脏的，不能直接在当前工作区切分支、切换分支、硬合并。需要使用临时 `worktree`。
9. 如果合并后需要本地修复，优先删除无用旧逻辑，避免继续堆积陈旧代码。
10. 默认不编译测试。处理完成后提醒用户自行测试。
11. 任何 GitHub 评论、回复、感谢留言发出后，AI 都必须立即再读一遍线上实际内容，确认正文不是乱码、不是 `?`、不是编码异常；如果发现异常，必须立刻修正后再继续后续流程。
12. 如果流程执行过程中，PR 的实时目标分支被别人改掉，或者不再是 `dev`，AI 必须停止当前合并流程，重新拉取信息后再决定下一步。
13. 进入“阶段 2：分析与审查”时，AI 必须先给当前 PR 添加 `审查中` 标签，并在开始正式审查前确认该标签已经在线上生效。
14. 审查结束后，AI 必须根据实际结论把 PR 标签从 `审查中` 切换为 `完成` 或 `等待修改`，并同时把受理人设置为自己；在确认线上状态已更新前，不允许声称审查已完成。
15. 审查时必须检查该 PR 是否遵守 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)，不能只检查功能是否可用。
16. 如果 PR 功能本身没问题，但明显违反开发规范，例如：
   - 把大段逻辑重新堆回主文件
   - 没补测试或破坏测试边界
   - 没同步文档
   - 破坏共享步骤定义/注册表
   - 引入可见乱码
   则也必须判定为“需要修改后再继续”，不能直接给出可合并结论。

## 输入要求

AI 至少要拿到下面这些输入：

- `PR 编号`
- `仓库路径`
- 本次目标：`只分析` / `分析后需要继续合并`
- 如果需要继续合并：是否允许 AI 直接本地修复冲突和问题

补充要求：

- 如果 AI 不能从当前仓库自动识别 `OWNER/REPO`，则用户还需要补充提供。
- 本流程默认允许 AI 在检测到 `master` 为目标分支时，直接远程改成 `dev`；如果用户明确禁止任何远程修改，则本流程不适用。

## 总流程

### 阶段 1：准备、目标分支校正与信息拉取

AI 必须先执行下面这些动作，不能跳步：

1. 检查当前仓库状态：
   - `git status --short --branch`
   - `git remote -v`
2. 拉取 PR 元数据：

```powershell
gh pr view <PR_NUMBER> --repo <OWNER/REPO> --json number,title,body,author,baseRefName,headRefName,headRepository,headRepositoryOwner,changedFiles,additions,deletions,commits,files,labels,assignees,isDraft,mergeStateStatus,mergeable,state,url
```

3. 先根据实时 `baseRefName` 处理目标分支：
   - 如果 `baseRefName = dev`：继续下一步。
   - 如果 `baseRefName = master`：先执行“自动转到 `dev`”流程，再继续下一步。
   - 如果 `baseRefName` 既不是 `dev` 也不是 `master`：立即停止，并向用户反馈“当前自动流程只支持 `dev`”。

4. 当 `baseRefName = master` 时，必须执行下面的自动转分支流程：

```powershell
gh api --method GET repos/<OWNER/REPO>/pulls -f state=open -f head='<HEAD_OWNER>:<HEAD_REF>' -f base='dev' -f per_page='100'
```

处理规则：

1. 先从上一步 PR 元数据中读取真实的 `HEAD_OWNER` 与 `HEAD_REF`，不能猜。
2. 如果查询结果中已经存在 `number != <PR_NUMBER>` 的打开 PR，则视为“重复的 dev PR”：
   - 不再执行转分支
   - 不再继续自动分析旧 diff
   - 先反馈给当前用户，必要时再给 PR 留言说明
3. 如果不存在重复的 dev PR，则执行：

```powershell
gh pr edit <PR_NUMBER> --base dev --repo <OWNER/REPO>
```

4. 改完目标分支后，必须重新执行一次 PR 元数据拉取，确认新的 `baseRefName = dev`。
5. 在重新确认 `baseRefName = dev` 之前，不允许继续分析旧 diff，不允许继续合并。

5. 只有在目标分支已经确认是 `dev` 后，才能拉取 PR diff：

```powershell
gh pr diff <PR_NUMBER> --repo <OWNER/REPO>
```

6. 拉取目标分支与 PR 头：

```powershell
git fetch origin dev
git fetch origin pull/<PR_NUMBER>/head:refs/remotes/origin/pr-<PR_NUMBER>
```

7. 如果需要稳定查看行号、文件内容、避免污染当前工作区，创建临时 `worktree`：

```powershell
$TempWorktree = '<临时目录>'
git worktree add --detach $TempWorktree origin/pr-<PR_NUMBER>
```

### 阶段 2：分析与审查

AI 分析时，必须完整执行下面这些要求：

1. 审查一开始必须先执行：

```powershell
gh pr edit <PR_NUMBER> --add-label "审查中" --repo <OWNER/REPO>
```

补充要求：

   - 打标后必须立刻重新读取一次实时 PR 元数据，确认 `labels` 中已经出现 `审查中`。
   - 如果仓库里没有 `审查中` 标签、当前账号无权限打标，或者命令执行失败，必须立刻告知用户，不能假装已经开始审查。
2. 不能只看 PR 描述，必须结合真实 diff 和仓库现有代码上下文一起分析。
3. 如果阶段 1 发生过 `master -> dev` 自动转向，分析时只能基于转向后的最新 diff，不得继续引用转向前的 diff 结论。
4. 对于高风险文件，必须继续读取改动函数周边逻辑，确认消息流、状态流、配置项、回调流程、页面跳转流程是否一致。
5. 必须分析并输出：
   - 这个 PR 改了什么
   - 这些改动是否合理
   - 是否存在 bug / 风险 / 逻辑冲突
   - PR 当前是否可直接合并，例如 `mergeable`、`mergeStateStatus`
   - 是否遵守项目开发规范
6. 如果发现问题，结论必须按严重级别排序，优先写真正会影响功能、合并或后续维护的问题。
7. 如果没有发现明确问题，也要说明剩余风险，例如：
   - 未运行测试
   - 需要人工验证真实业务接口
   - 当前仅完成静态分析
8. 在准备进入后续合并步骤前，必须再拉取一次实时 PR 元数据，确认：
   - PR 仍然是打开状态
   - PR 不是 draft
   - `baseRefName` 仍然是 `dev`
9. 审查输出中必须单独包含一节“开发规范符合性检查”，至少明确说明：
   - 是否违反 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)
   - 是否需要补测试
   - 是否需要补文档
   - 是否发现可见乱码或编码异常
   - 是否存在把逻辑重新堆回主文件的情况

## 分析后评论规则

### 有问题 / 审核不通过时

如果发现需要作者或维护者注意的问题，AI 必须自动发 PR 评论，并且评论格式必须固定如下：

```text
（自动回复）AI分析结果（不一定完全正确，请进行确认，若无问题后请评论回复）：

<这里写正式评论内容>
```

要求：

1. 第一行必须完全使用上面的标题，不能改字。
2. 标题下方必须空一行，再写正文。
3. 正文内容要直接写问题，不要再套娃解释“下面是分析结果”。
4. 评论内容必须基于实际检查到的问题，不能编。
5. 评论发出后，必须立刻回读该评论的线上正文，确认不是乱码；如果有乱码，必须先修正评论，再继续后续动作。
6. 如果问题能够明确定位到某个改动文件、代码块或行号，AI 应优先在对应文件的代码 diff / 代码附件上追加行级评论，直接指出问题和期望修改方式。
7. 如果结论是“当前不能通过审查”，AI 必须明确写出“需要修改后再继续”，不能只写模糊提醒。
8. 如果当前环境支持正式 PR review，且问题足以阻止合并，优先使用带“要求更改（Request changes）”语义的审查，而不是只留普通闲聊式评论。
9. 行级评论是对总评论的补充，不得用零散行级评论替代总评论结论。
10. 如果问题属于“开发规范不符合”，总评论中必须明确写出违反的是哪类规范，例如：
   - 模块边界不符合
   - 测试缺失
   - 文档未同步
   - 出现乱码
   - 共享步骤定义未同步

### 没问题时

如果没有发现明确问题：

1. 先把分析结果反馈给当前用户。
2. 不强制给 PR 留问题评论。
3. 是否继续合并，取决于用户命令。

## 审查完成后的状态回写规则

无论本次是“只分析”还是“分析后继续合并”，只要审查结论已经形成，AI 都必须立刻回写 PR 状态：

1. 如果本次审查结论是“可以继续处理 / 没有明确阻塞问题”，把标签改为 `完成`。
2. 如果本次审查结论是“存在问题，需要作者或维护者继续修改”，把标签改为 `等待修改`。
3. 两种情况都必须同时把受理人设置为自己。
4. 标签必须互斥，不能同时保留 `审查中`、`完成`、`等待修改` 中的多个状态标签。

### 回写命令示例

审查通过 / 可继续处理时：

```powershell
gh pr edit <PR_NUMBER> --remove-label "审查中" --remove-label "等待修改" --add-label "完成" --add-assignee "@me" --repo <OWNER/REPO>
```

需要修改后再继续时：

```powershell
gh pr edit <PR_NUMBER> --remove-label "审查中" --remove-label "完成" --add-label "等待修改" --add-assignee "@me" --repo <OWNER/REPO>
```

补充要求：

1. 回写完成后，必须立刻重新读取一次实时 PR 元数据，确认：
   - `labels` 中已经是正确的最终状态标签
   - `审查中` 已经被移除
   - 当前受理人列表中已经包含自己
2. 如果仓库里没有 `完成` / `等待修改` 标签、当前账号无权限改标签或设受理人，或者命令执行失败，必须立刻告知用户，不能假装状态已经回写成功。
3. 如果后续又因为继续修复、重新审查等原因需要重新打开审查流程，必须先按实际情况重新设置标签，不能让状态长期停留在错误值。

## 带问题继续合并的规则

如果 PR 有问题，但用户明确要求：

- 不等待 PR 作者修复
- 由当前 AI 直接修改 PR 分支代码，处理冲突和问题
- 处理完成后继续合并

则必须进入下面的流程。

### 阶段 3：临时工作区修复 PR 分支

禁止在用户当前工作区直接乱合并。

必须先创建临时 `worktree`，再在临时目录内处理 PR 分支：

```powershell
git fetch origin dev
git fetch origin pull/<PR_NUMBER>/head:refs/remotes/origin/pr-<PR_NUMBER>
git worktree add <TEMP_WORKTREE> -b pr-<PR_NUMBER>-fix origin/pr-<PR_NUMBER>
```

进入临时目录后，先把最新 `dev` 合到 PR 分支里，显式暴露冲突：

```powershell
git merge --no-ff --no-commit origin/dev
```

处理规则：

1. 如果阶段 1 发生过 `master -> dev` 自动转向，本阶段必须以 `dev` 为唯一合并基准，不允许再回到 `master` 做本地吸收。
2. 如果出现冲突，先在 PR 分支上解决冲突，再继续检查相关联逻辑。
3. 不能只消掉冲突标记就结束，必须继续看是否有设计冲突、状态字段不一致、调用链断裂、配置项名不一致、回调逻辑互相打架的问题。
4. 如果 PR 本身逻辑有 bug，而用户又明确要求继续合并，AI 需要直接修改 PR 分支代码并修正。
5. 修正完成后，必须把修改提交回 PR 分支并推送到远端；如果没有权限推送到 PR 来源分支，必须立刻停止并明确告知用户，不能假装 PR 已修好。
6. 推送完成后，必须重新拉取一次实时 PR 元数据与最新 diff，确认线上 PR 已包含本次修复，再决定是否继续合并。
7. 修正时要清理无用旧代码，避免留下史山。
8. 如果改了 SQL，按仓库规则同步本地 MySQL `xzs`。

### 阶段 4：PR 修复推送后的自检清单

完成 PR 分支修复并推送后，必须自检下面这些项目：

1. `git status` 中不能再有未处理冲突。
2. 相关文件中不能残留冲突标记。
3. 新旧逻辑之间不能出现字段名、消息名、步骤编号、状态名不一致。
4. 需要检查与本次功能直接相关的上下游代码，不能只改当前冲突文件。
5. 要重新查看最终线上 diff，确认修复后的 PR 没有引入明显回归。
6. 要重新拉取一次实时 PR 元数据，确认该 PR 的 `baseRefName` 仍然是 `dev`；如果不是，停止后续合并并先反馈用户。
7. 要确认 PR 当前已经回到可继续处理的状态，例如不再是 `draft`，且 `mergeable` / `mergeStateStatus` 没有出现新的阻塞。
8. 默认不编译测试，最后提醒用户自行测试。
9. 如果本地代修过程中涉及结构调整、功能链路变化或开发边界变化，必须同时检查并在必要时更新：
   - [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md)
   - [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md)
   - [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)

## 合并提交信息规则

如果最后决定真正合并，提交信息不能直接写：

- `merge branch xxx`
- `merge pr #19`
- `合并某某分支`

必须重新分析“最终合并结果到底做了什么”，然后重写提交信息。

这些规则同样适用于最终执行 `gh pr merge` 时使用的标题与正文。

### 提交信息要求

1. 标题必须描述最终落地功能，不是描述 Git 动作。
2. 标题要体现核心改动结果，而不是“从哪里合并过来”。
3. 正文要写清楚：
   - 这次吸收了 PR 的什么内容
   - 本地额外修复了什么冲突或 bug
   - 对哪些关键流程做了调整

### 推荐格式

```text
<type>: <最终功能或修复结果>

- 合并 PR #<PR_NUMBER> 的核心改动：<一句话概括>
- 本地补充修复：<一句话概括>
- 影响范围：<步骤/模块/页面/接口>
```

### 示例

```text
feat: support SUB2API mode for OAuth generation and callback handling

- 合并 PR #19 的核心改动：新增 SUB2API 模式并接入 OAuth 生成与回调提交流程
- 本地补充修复：修正回调地址约束与超时重试带来的重复执行风险
- 影响范围：background orchestration、sidepanel config、sub2api content script
```

## 最终合并与收尾

如果 PR 分支上的冲突 / 问题已经修好，并且复检确认该 PR 可以继续合并到 `dev`，则继续执行下面动作。

### 1. 合并 PR

优先直接合并这个 PR，而不是只在本地偷偷吸收代码后手工关闭：

```powershell
gh pr merge <PR_NUMBER> --merge --subject "<TITLE>" --body "<BODY>" --repo <OWNER/REPO>
```

要求：

1. `--subject` 与 `--body` 必须遵守上面的“合并提交信息规则”。
2. 合并前必须再次确认 PR 仍然是打开状态、目标分支仍然是 `dev`、线上 diff 已包含你刚刚推送的修复。
3. 如果合并时发现新的冲突、状态检查阻塞或权限问题，必须停止并把真实阻塞原因反馈给用户。

### 2. 感谢作者

此时需要自动给 PR 留一条感谢评论。

注意：

1. 感谢评论不要带问题评论的固定标题。
2. 直接正常感谢即可。
3. 感谢内容要基于真实贡献，语气简洁。
4. 如果阶段 1 发生过 `master -> dev` 自动转向，感谢评论不能把最终落地分支写错，必须明确本次内容已吸收到 `dev`。
5. 感谢评论发出后，也必须立刻回读线上正文，确认不是乱码；如果有乱码，必须先修正评论，再进行关闭 PR 等后续动作。

示例：

```text
感谢贡献这次改动，核心思路和主体实现已经吸收进 dev 分支了。我这边补了一下合并过程里的冲突和相关修正，后续如果你还有类似改进也欢迎继续提交。
```

### 3. 自动关闭 PR

如果 PR 还没有因为合并而自动关闭，则感谢评论发完后，自动关闭该 PR：

```powershell
gh pr close <PR_NUMBER> --repo <OWNER/REPO>
```

如果需要，先评论再关闭，不要把感谢遗漏掉。

### 4. 评论编码复检

无论是问题评论、感谢评论，还是其他直接发到 GitHub 的回复，只要消息已经发出，AI 必须执行一次“发送后复检”：

1. 重新读取该评论/回复在线上的实际正文。
2. 检查是否存在乱码、异常问号、编码错乱、BOM 污染等问题。
3. 如果有问题，必须立即编辑修正，直到线上正文正常为止。
4. 编码复检完成前，不允许声称“评论已发送完成”。

## 用户侧最终反馈要求

AI 在对当前用户做最终反馈时，至少要说明：

1. 做了哪些真实动作
2. PR 原始目标分支是否是 `master`
3. 是否已经执行 `master -> dev` 自动转向
4. 是否发现重复的 `dev` PR
5. 是否发现问题
6. 是否已经给 PR 添加 `审查中` 标签
7. 审查完成后最终把 PR 标签改成了 `完成` 还是 `等待修改`
8. 是否已经把受理人设置为自己
9. 是否已经发了 PR 评论 / 行级代码评论
10. 是否已经要求 PR 修改后再继续
11. 是否已经修改 PR 分支并推回远端
12. 是否已经完成 PR 合并
13. 是否已经关闭 PR
14. 如果改了代码但没跑测试，要明确提醒用户测试

## 给 AI 的一句话执行要求

拿到本文件后，AI 必须按“先真实读取 PR 元数据，先校正目标分支，再拉取最新 diff，在正式审查开始时先给 PR 打上 `审查中` 标签并确认已生效；审查结束后根据实际情况把标签改成 `完成` 或 `等待修改` 并把受理人设为自己；如果审核不通过，就在对应代码附件上评论并明确要求更改；如果用户要求继续处理冲突和问题，就先修好并推回 PR 分支，再按规则合并 PR，最后感谢作者、关闭 PR”的顺序执行，不能跳步，不能猜，不能偷懒。