[PR Flow] pr-submit 增加阶段化进度和耗时遥测

[liuli195]

Parent

#89

详细背景

PR #107 中，pr-submit 在刷新 fragments 后继续执行，最终成功完成 PR #107 merge、main fast-forward 和本地分支清理。但中间耗时约 345 秒，用户侧只能等待最终结果，难以及时知道当前是在创建/更新 PR、等待 required checks、等待 official review、执行 auto-merge 还是 cleanup。

已有 #104 解决失败后的接手快照 v3，但本次暴露的是运行中的进度可见性问题：即使流程最终成功，长时间无阶段输出也会降低可控性；如果中途挂起，接手 agent 仍需要重新查状态。

产品解决方案

为 pr-submit 增加阶段化进度和耗时遥测。它不新增公开入口，不改变成功/失败权威，只让唯一默认入口在长流程中持续报告自己正在做什么。

用户视角：运行 pr-submit 时能看到稳定阶段：local fragments、PR create/update、PR Evidence、official review、required checks、ready-for-review、auto-merge、merged wait、cleanup。每个阶段显示开始、完成、耗时、当前 evidence URL 或下一次等待原因。

详细技术实现方案

1. 定义 pr-submit 阶段枚举：local_fragments、pr_upsert、evidence_refresh、official_review、required_checks、ready_for_review、auto_merge、wait_merged、cleanup。
2. 每个阶段输出一行结构化进度：阶段名、状态、耗时、当前 PR/head、关键 URL 或阻断摘要。
3. .local/pr-flow/status.json 或 [PR Flow] 接手快照 v3：统一云端失败接手接口 #104 v3 snapshot 增加运行中 current_phase / last_progress_at，失败时保留最后阶段。
4. 等待 required checks / official review 时，定期输出当前 pending context 和 target URL，避免长时间静默。
5. 成功结束时输出最终摘要：PR number、mergedAt、merge commit、main sync、branch cleanup。
6. 增加测试：成功路径阶段顺序、required checks pending 重复进度、失败时最后阶段进入接手快照、不会新增公开命令。

Acceptance criteria

• pr-submit 长流程有阶段化进度输出。
• 每个阶段记录耗时和关键 evidence URL。
• 等待 required checks / official review 时不会长时间无输出。
• 失败接手快照能看到最后停留阶段。
• 不改变 pr-submit 作为唯一默认入口。

Blocked by

#104 - 如果接手快照 v3 已实现，运行中进度应复用其字段或兼容其 checkpoint 语义。

[liuli195]

PR #112 复现记录

PR #112 的完整流程包含官方 Codex review ack 等待、required checks 等待、CI 修复重跑、merge、cleanup 和 post-merge audit。中途需要多次人工用 gh pr checks / run log / 本地状态确认当前阶段。

#113 已单独记录 post-merge PR Evidence 失败状态污染；#111 仍应覆盖运行中的阶段化进度和耗时遥测，尤其是等待 required checks / official review 时输出当前 pending context、target URL 和已等待时间。

建议维持 priority:P2：它主要影响耗时和接手效率，但不会单独改变合并规则。

[liuli195]

PR #115 / PR #116 状态可见性复现记录

详细背景

本次 #103 / #113 修复流程中，PR #115 合并后出现 post-merge PR Flow / evidence failure，随后通过 PR #116 修复。PR #116 合并后，用户仍看到类似“还有一个失败检查”的信号，需要人工再查 gh pr view --json statusCheckRollup 和 gh run list。

最终确认 PR #116 当前 required status contexts 全部为 SUCCESS，失败/取消项是历史 check run：

• PR Flow / evidence run 27047433657：CANCELLED
• PR Flow Review Status / monitor run 27047433659：CANCELLED

当前 status contexts：

• PR Flow / evidence：SUCCESS
• PR Flow / review-status：SUCCESS
• Research Governance / verify-full：SUCCESS

产品解决方案补充

#111 的阶段化进度应覆盖长流程运行中状态；另见 #117，建议最终状态摘要也复用同一阶段/检查归因口径，输出“当前阻断”和“历史诊断”两类信号。

用户视角：流程结束时应直接看到“当前 required checks 全绿；历史 cancelled/failed run 不阻断”，而不是再让用户或 agent 手动解释 GitHub rollup。

详细技术实现方案补充

建议 #111 的最终摘要增加：

1. 当前 phase 和耗时。
2. 当前 required check contexts 及 target URL。
3. 历史 failed/cancelled/superseded run 列表，标记为 diagnostic。
4. 若存在相关 [PR Flow] 区分当前 required status 和历史 check runs，消除旧失败误判 #117 final status summary，实现上复用同一个 status attribution 函数，避免进度输出和阻断判断不一致。

优先级建议

维持 priority:P2。它主要影响可见性和交接效率；当前阻断归因的 correctness 部分已单独记录在 #117，并标为 priority:P1。

[liuli195]

本次会话复现场景补充：PR #122 执行 pr-submit 时，命令运行约 487 秒，期间主要等待远端 checks / merge，终端最终只输出 cleanup 摘要。流程成功完成，但长时间等待期间缺少阶段化进度，接手者无法直接判断是在等 local stable、official review、required checks、auto-merge 还是 cleanup。

[liuli195]

PR #124 复现场景补充

本次实现 #123 / PR #124 时，第二次 pr-submit 在远端分支已 push、fragments 已生成后继续执行约 493 秒，最终成功完成 merge、main fast-forward 和 cleanup。终端在长时间等待期间没有持续阶段化输出，最后只看到 cleanup 摘要。

这次等待覆盖了 PR upsert、PR Evidence、local stable / required checks、official review / merge 等长流程阶段；接手者无法只从终端输出判断当前卡在哪个阶段。

[liuli195]

本次 PR #128 复现了这个问题的长等待场景：

• 最终 pr-submit 从更新 PR Evidence、等待 GitHub checks、触发/等待 review、auto-merge 到 cleanup，总耗时约 665 秒。
• 命令运行期间用户侧基本只能等待最终输出，难以判断当前卡在 required checks、official review、merge wait 还是 cleanup。
• 用户本轮还显式要求“没有不可抗力原因，直到所有任务完成前不要停止”，长时间无阶段输出会让接手和状态判断变困难。

这不是新的独立问题；它是本 issue 描述的“运行中进度可见性不足”的同类复现场景。

[liuli195]

本次 PR #131 复现了 pr-submit 长等待无阶段化输出场景：

• 第二次 make pr-submit TITLE="策略：兼容模拟盘缺失参数" 总耗时约 472 秒。
• 命令最终成功完成 PR 创建/更新、远端 checks、merge 和 cleanup，但运行期间缺少持续阶段输出。
• 终端最终只看到 cleanup 摘要：PR 策略：兼容模拟盘缺失参数 #131 merged、main synced、local branch deleted。
• 接手者无法仅凭运行中输出判断当时是在等待 local stable、required checks、official review、auto-merge 还是 cleanup。

这不是新的独立问题；它是本 issue 描述的运行中进度可见性不足的同类复现场景。

[liuli195]

复现补充：PR #133 本地长流程静默与命令超时

本次会话中，PR #133 第一次运行：

.\.venv\Scripts\python.exe -m scripts.research.governance.pr_flow submit --title "治理：收紧子 agent 空结果证据语义"

本地命令在约 124 秒后被外层工具超时切断。切断时 .local/pr-flow/status.json 不存在，但远端实际已经创建 PR、推送 head，并且 required checks 正在运行：

• PR：治理：收紧子 agent 空结果证据语义 #133
• head：c87d1e4360e14f433c9fca6a430169dc82648df2
• PR Flow / evidence 已成功
• Research Governance / verify-full、PR Flow Review Status / monitor 仍在运行

主 agent 需要额外手工查询：

gh pr view --json number,url,state,isDraft,headRefName,headRefOid,baseRefName,mergeStateStatus,statusCheckRollup,title
git status --short --branch
git ls-remote --heads origin codex/fix-open-p1-issues

随后第二次用更长 timeout 重跑 pr-submit，流程最终成功合并并 cleanup。

这个场景说明：即使流程本身最终正确，长时间无阶段输出会让外层 agent / 工具误判为卡死或超时，需要人工介入检查远端状态并重跑。

[liuli195]

This was generated by AI during triage.

复现补充：PR #135 pr-submit 运行期间仍缺少阶段化进度

本次 PR #135 最终执行：

.\.venv\Scripts\python.exe -m scripts.research.governance.pr_flow submit --title "启动 repo-pr-governance 守护"

命令总耗时约 139 秒，最终成功完成 PR 创建/更新、远端 checks、merge 和 cleanup。运行期间主要等待远端流程，终端直到结束才输出 cleanup 摘要：PR #135 merged、main synced、local branch deleted。

流程没有出错，但接手者在等待期间仍无法只从运行中输出判断当前处于 PR upsert、local stable、required checks、official review、auto-merge 还是 cleanup 阶段。