Hermes/FlowPilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
FlowPilot/docs/仓库协作者AI分析PR与合并标准流程.md
T

19 KiB
Raw Permalink Blame History

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

用途

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

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

下次只要告诉 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，不能只检查功能是否可用。
  16. 如果 PR 功能本身没问题，但明显违反开发规范，例如：
  • 把大段逻辑重新堆回主文件
  • 没补测试或破坏测试边界
  • 没同步文档
  • 破坏共享步骤定义/注册表
  • 引入可见乱码 则也必须判定为“需要修改后再继续”，不能直接给出可合并结论。

输入要求

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,labels,assignees,isDraft,mergeStateStatus,mergeable,state,url

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

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

  2. 当 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>

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

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

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

gh pr diff <PR_NUMBER> --repo <OWNER/REPO>
  1. 拉取目标分支与 PR 头：
git fetch origin dev
git fetch origin pull/<PR_NUMBER>/head:refs/remotes/origin/pr-<PR_NUMBER>
  1. 如果需要稳定查看行号、文件内容、避免污染当前工作区，创建临时 worktree：
$TempWorktree = '<临时目录>'
git worktree add --detach $TempWorktree origin/pr-<PR_NUMBER>

阶段 2：分析与审查

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

  1. 审查一开始必须先执行：
gh pr edit <PR_NUMBER> --add-label "审查中" --repo <OWNER/REPO>

补充要求：

  • 打标后必须立刻重新读取一次实时 PR 元数据，确认 labels 中已经出现 审查中。
  • 如果仓库里没有 审查中 标签、当前账号无权限打标，或者命令执行失败，必须立刻告知用户，不能假装已经开始审查。
  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
  8. 审查输出中必须单独包含一节“开发规范符合性检查”，至少明确说明：
    • 是否违反 项目开发规范（AI协作）.md
    • 是否需要补测试
    • 是否需要补文档
    • 是否发现可见乱码或编码异常
    • 是否存在把逻辑重新堆回主文件的情况

分析后评论规则

有问题 / 审核不通过时

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

（自动回复）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. 标签必须互斥，不能同时保留 审查中、完成、等待修改 中的多个状态标签。

回写命令示例

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

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

需要修改后再继续时：

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 分支：

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 分支里，显式暴露冲突：

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. 如果本地代修过程中涉及结构调整、功能链路变化或开发边界变化，必须同时检查并在必要时更新：

合并提交信息规则

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

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

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

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

提交信息要求

  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 分支上的冲突 / 问题已经修好，并且复检确认该 PR 可以继续合并到 dev，则继续执行下面动作。

1. 合并 PR

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

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 等后续动作。

示例：

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

3. 自动关闭 PR

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

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”的顺序执行，不能跳步，不能猜，不能偷懒。

Reference in New Issue View Git Blame Copy Permalink