FlowPilot/docs/仓库协作者AI分析PR与合并标准流程.md

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

用途

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

下次只要告诉 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 必须停止当前合并流程，重新拉取信息后再决定下一步。

输入要求

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

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

补充要求：

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

总流程

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

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

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

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

3. 先根据实时 baseRefName 处理目标分支：

   • 如果 baseRefName = dev：继续下一步。
   • 如果 baseRefName = master：先执行“自动转到 dev”流程，再继续下一步。
   • 如果 baseRefName 既不是 dev 也不是 master：立即停止，并向用户反馈“当前自动流程只支持 dev”。

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

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，则执行：

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

4. 改完目标分支后，必须重新执行一次 PR 元数据拉取，确认新的 baseRefName = dev。

5. 在重新确认 baseRefName = dev 之前，不允许继续分析旧 diff，不允许继续合并。

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

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

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

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

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

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

阶段 2：分析与审查

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

1. 不能只看 PR 描述，必须结合真实 diff 和仓库现有代码上下文一起分析。
2. 如果阶段 1 发生过 master -> dev 自动转向，分析时只能基于转向后的最新 diff，不得继续引用转向前的 diff 结论。
3. 对于高风险文件，必须继续读取改动函数周边逻辑，确认消息流、状态流、配置项、回调流程、页面跳转流程是否一致。
4. 必须分析并输出：
   • 这个 PR 改了什么
   • 这些改动是否合理
   • 是否存在 bug / 风险 / 逻辑冲突
   • PR 当前是否可直接合并，例如 mergeable、mergeStateStatus
5. 如果发现问题，结论必须按严重级别排序，优先写真正会影响功能、合并或后续维护的问题。
6. 如果没有发现明确问题，也要说明剩余风险，例如：
   • 未运行测试
   • 需要人工验证真实业务接口
   • 当前仅完成静态分析
7. 在准备进入后续合并步骤前，必须再拉取一次实时 PR 元数据，确认：
   • PR 仍然是打开状态
   • PR 不是 draft
   • baseRefName 仍然是 dev

分析后评论规则

有问题时

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

（自动回复）AI分析结果（不一定完全正确，请仓库协作者确认无问题后再继续）：

<这里写正式评论内容>

要求：

1. 第一行必须完全使用上面的标题，不能改字。
2. 标题下方必须空一行，再写正文。
3. 正文内容要直接写问题，不要再套娃解释“下面是分析结果”。
4. 评论内容必须基于实际检查到的问题，不能编。
5. 评论发出后，必须立刻回读该评论的线上正文，确认不是乱码；如果有乱码，必须先修正评论，再继续后续动作。

没问题时

如果没有发现明确问题：

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

带问题继续合并的规则

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

• 不等待 PR 作者修复
• 由当前 AI 直接本地处理冲突和问题
• 处理完成后继续合并

则必须进入下面的流程。

阶段 3：临时工作区合并

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

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

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>-merge origin/dev

进入临时目录后再执行：

git merge --no-ff --no-commit origin/pr-<PR_NUMBER>

处理规则：

1. 如果阶段 1 发生过 master -> dev 自动转向，本阶段必须以 dev 为唯一合并基准，不允许再回到 master 做本地吸收。
2. 如果出现冲突，先解决冲突，再继续检查相关联逻辑。
3. 不能只消掉冲突标记就结束，必须继续看是否有设计冲突、状态字段不一致、调用链断裂、配置项名不一致、回调逻辑互相打架的问题。
4. 如果 PR 本身逻辑有 bug，而用户又明确要求继续合并，AI 需要直接在本地修正。
5. 修正时要清理无用旧代码，避免留下史山。
6. 如果改了 SQL，按仓库规则同步本地 MySQL xzs。

阶段 4：本地修复后的自检清单

完成临时合并与本地修复后，必须自检下面这些项目：

1. git status 中不能再有未处理冲突。
2. 相关文件中不能残留冲突标记。
3. 新旧逻辑之间不能出现字段名、消息名、步骤编号、状态名不一致。
4. 需要检查与本次功能直接相关的上下游代码，不能只改当前冲突文件。
5. 要重新查看最终 diff，确认本地修复没有引入明显回归。
6. 要重新拉取一次实时 PR 元数据，确认该 PR 的 baseRefName 仍然是 dev；如果不是，停止后续合并并先反馈用户。
7. 默认不编译测试，最后提醒用户自行测试。

合并提交信息规则

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

• merge branch xxx
• merge pr #19
• 合并某某分支

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

提交信息要求

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

推荐格式

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

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

示例

feat: support SUB2API mode for OAuth generation and callback handling

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

最终合并与收尾

如果本地已经解决该 PR 的内容，并且最终代码已经进入 dev 分支，则继续执行下面动作。

1. 感谢作者

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

注意：

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

示例：

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

2. 自动关闭 PR

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

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

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

3. 评论编码复检

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

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

用户侧最终反馈要求

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

1. 做了哪些真实动作
2. PR 原始目标分支是否是 master
3. 是否已经执行 master -> dev 自动转向
4. 是否发现重复的 dev PR
5. 是否发现问题
6. 是否已经发了 PR 评论
7. 是否已经本地合并并修复
8. 是否已经关闭 PR
9. 如果改了代码但没跑测试，要明确提醒用户测试

给 AI 的一句话执行要求

拿到本文件后，AI 必须按“先真实读取 PR 元数据，先校正目标分支，再拉取最新 diff 做分析，再按用户要求决定是否进入临时合并修复，最后重写提交信息并在完成后感谢作者、关闭 PR”的顺序执行，不能跳步，不能猜，不能偷懒。