Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Read [PR checks and merge process](https://github.com/VisActor/VBI/blob/main/CON
- [ ] Ran relevant unit tests and full official-baseline comparison for product/dependency/case changes, or explained documentation-only applicability. Self-comparison is not a two-sided pass.
- [ ] Described expected visual changes and regression coverage; retained execution errors and blockers.

Photo needs maintainer review. Report-only/completed is not an all-Photo pass; approval is tied to the current commit and never automatically merges or updates baselines.
Photo needs maintainer review; report-only/completed is not an all-Photo pass. Approve is an audit record and the Bot never merges. When Photo selection is explicitly enabled, only the saved pre-merge selection can update baselines after manual merge; other PRs retain their existing mode.

⚠️ Please check all items below before requesting a reviewing. ⚠️

Expand Down
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE/pr_cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@
- [ ] 产品/依赖/用例变更已完成相关单测及默认全量基线比较;纯文档说明不适用。自比较不能代替双侧通过。
- [ ] 已说明预期视觉变化及新增/修改的回归用例;执行错误和阻断如实保留。

Photo由维护者人工核查,report-only/流程完成不等于Photo全通过;批准绑定当前提交,不自动Merge或更新基准。
Photo 由维护者人工核查,report-only/流程完成不等于 Photo 全通过;Approve 仅作审计,Bot 不自动 Merge。仅明确启用图文选择的 PR 可在人工合入后按合入前保存的修订更新所选基准,其他 PR 保持原模式。

⚠️ 在提交 PR 之前,请检查一下内容. ⚠️

Expand Down
32 changes: 18 additions & 14 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,23 +58,27 @@ Passing all three checks or reaching completed does not mean every Photo test pa

### Status and next action

| Summary status | Action |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Queued / running | Wait for the current stage; no result is not a pass |
| Changes or investigation needed | Fix the issue, add coverage or provide verifiable evidence |
| Blocked | Read the action item; ask maintainers about permissions, services or recovery |
| Awaiting approval | Maintainer checks all three results and manually reviews Photo for the current revision |
| Awaiting merge | A valid current-commit approval was recognized; a maintainer merges manually |
| Merged / baseline processing | Wait for cleanup; skipping automatic baseline updates is expected in report-only mode |
| Completed | Workflow cleanup finished; original Photo differences and errors remain |
| Superseded / closed without merge | Read the new revision's result, or treat the PR as unmerged; neither implies a baseline update |

A new head or comparison base requires version checks and necessary reruns. Old results cannot prove the new revision passed; a new commit needs its own valid approval. If a summary is missing, check repository, target, creation time, draft status and changed paths before contacting maintainers.
| Summary status | Action |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Queued / running | Wait for the current stage; no result is not a pass |
| Changes or investigation needed | Fix the issue, add coverage or provide verifiable evidence |
| Blocked | Read the action item; ask maintainers about permissions, services or recovery |
| Awaiting approval | Maintainer checks all three results and manually reviews Photo for the current revision |
| Awaiting merge | The three recommendations are complete; inspect Photo and any saved selection, then merge manually subject to repository rules |
| Merged / baseline processing | Check selected-baseline results when selection is enabled; otherwise automatic updates remain skipped |
| Completed | Workflow cleanup finished; original Photo differences and errors remain |
| Superseded / closed without merge | Read the new revision's result, or treat the PR as unmerged; neither implies a baseline update |

A new head or comparison base requires version checks and necessary reruns. Old results cannot prove the new revision passed; verify current results and any saved Photo selection again for each new commit. If a summary is missing, check repository, target, creation time, draft status and changed paths before contacting maintainers.

### Approval, merge and recovery

The workflow recognizes a valid GitHub Approve from a repository Maintain/Admin user for the **current commit**, including their manual Photo verification. The Bot never approves or merges. GitHub protection rules and other checks still apply; the workflow does not add required Checks or change branch protection.
GitHub Approve is an audit record in this workflow. Maintainers may merge manually after checking CR, unit tests, Playwright and Photo for the current commit. GitHub branch protection and repository review requirements still apply. The Bot does not change those rules, approve, or merge.

Automatic Photo difference assessment and baseline updates are paused. Approve/Merge does not authorize automatic adoption of screenshots. Early merge does not turn incomplete or failed checks into passes. Shared baseline changes require separate explicit authorization, administrator review and a new verification; retain original reports.
For PRs explicitly enabled for Photo selection, BugServer shows the current images and short explanations. New candidates are selected by default. Inspect each item, deselect any baseline that should stay unchanged, and save successfully before merging. The server's saved revision is authoritative; an unsaved draft has no effect. Default selection does not overwrite a saved manual choice.

After merge, only the selected baselines in that revision are updated. Unselected items stay unchanged. Writes still verify the frozen commit, three checks, merged content, save time and original baseline. Stale versions, post-merge selections and conflicts are not silently accepted. Ask maintainers to resume the original task after a timeout or partial success; do not dispatch another batch or change request IDs.

Photo remains report-only. An unavailable selection list, including more than 20 differences, incomplete explanations or execution errors, adds no merge gate and does not update baselines. PRs without this capability retain their existing mode. Baseline updates do not rewrite the original Photo report, and completed does not mean Photo passed.

For help, provide the PR, current SHA, Review/CI links and a public-safe error description. Do not edit managed summaries or hidden markers, repeatedly reopen PRs, delete state, change request IDs or dispatch duplicate batches. Maintainers recover the original task. Stop test servers, browsers and child processes you started when finished.
32 changes: 18 additions & 14 deletions CONTRIBUTING.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,23 +58,27 @@ pnpm run typecheck

### PR 状态与下一步

| 摘要状态 | 应采取的行动 |
| ------------------------ | ---------------------------------------------------- |
| 等待执行/执行中 | 等待当前阶段,不把暂无结果当通过 |
| 存在待修复或待调查项 | 阅读问题,修复代码、补用例或提供可验证证据 |
| 流程受阻 | 查看具体待办;权限、服务或任务恢复问题交由维护者处理 |
| 等待人工批准 | 维护者核对当前版本的三项结果,并人工核查 Photo |
| 等待人工合入 | 当前提交的有效批准已识别,由维护者人工 Merge |
| 已合入/核对基准阶段 | 等待收尾;report-only 下跳过自动基准更新是预期行为 |
| 流程已完成 | 表示流程收尾,不改写原 Photo 差异或错误 |
| 被新版本替代/未合入关闭 | 前者查看新版本结果,后者不表示已合入或基准已更新 |

推送新提交或 base 变化后重新核对版本并执行必要检查;旧结果不能证明新版本通过,新提交需要对应的有效批准。缺少摘要时先检查同仓、目标、创建时间、Draft和路径范围,再联系维护者。
| 摘要状态 | 应采取的行动 |
| ------------------------ | --------------------------------------------------------------------- |
| 等待执行/执行中 | 等待当前阶段,不把暂无结果当通过 |
| 存在待修复或待调查项 | 阅读问题,修复代码、补用例或提供可验证证据 |
| 流程受阻 | 查看具体待办;权限、服务或任务恢复问题交由维护者处理 |
| 等待人工批准 | 维护者核对当前版本的三项结果,并人工核查 Photo |
| 等待人工合入 | 三项建议已完成,维护者核查 Photo 与可用保存修订后按仓库规则手动 Merge |
| 已合入/核对基准阶段 | 已启用图文选择时核对所选基准处理结果;未启用时仍跳过自动更新 |
| 流程已完成 | 表示流程收尾,不改写原 Photo 差异或错误 |
| 被新版本替代/未合入关闭 | 前者查看新版本结果,后者不表示已合入或基准已更新 |

推送新提交或 base 变化后重新核对版本并执行必要检查;旧结果不能证明新版本通过,新提交须重新核对结果及可用的 Photo 保存修订。缺少摘要时先检查同仓、目标、创建时间、Draft和路径范围,再联系维护者。

### 批准、合入和异常恢复

工作流识别具有仓库 Maintain/Admin 权限的维护者对**当前提交**作出的有效 GitHub Approve,该批准同时表示已人工核查 Photo。Bot 不自动 Approve/Merge;GitHub 分支保护和其他检查仍适用,工作流不新增强制 Checks 或修改仓库规则。
工作流中的 GitHub Approve 仅作审计;维护者核对当前提交的 CR、单测、Playwright 和 Photo 后,可以直接手动 Merge。GitHub 分支保护或仓库评审要求仍然适用,Bot 不会修改这些规则,也不会代为 Approve 或 Merge。

@visactor-review-bot visactor-review-bot Bot Nov 11, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 同步可选批准后的状态与版本操作指引

对已启用图文选择、且仓库规则允许直接合入的 PR,这里允许维护者核查后不作 Approve 就 Merge;但同页状态表仍写“等待人工合入”须识别当前提交的有效批准,第 72 行仍写新提交需要有效批准,英文版也保留相同要求。维护者按状态表处理时会继续等待或请求一次不再必要的批准,也无法据此判断当前版本何时可合入。请为可选批准的 PR 明确状态与新提交处理方式,并同步两种语言的操作指引。


已确认修复 (4019e28): 已复查原触发条件:允许不作 GitHub Approve 而手动合入的流程下,中英文状态表的“等待人工合入”现均要求核对三项建议、Photo 和保存修订,不再要求识别当前提交的有效批准;两版新提交指引也改为重新核对当前结果与保存修订。原先会让维护者继续等待批准的文档冲突已消失,仓库评审规则的适用边界仍被保留。


Photo 自动差异评估及标准图自动更新暂停。Approve/Merge 不授权自动采用测试图;提前合入不会使未完成或失败的检查变为通过。新增/修改共享基准需管理员另行获得明确授权、人工核查并安排复验,原报告保留。
对已明确启用图文选择的 PR,BugServer 展示当前版本的图片和短说明,新候选默认全选。维护者应逐项核查;需要保留旧基准的项目取消选择,并在合入前保存成功。以服务端显示的保存修订为准,未保存草稿不生效;已保存的人工选择不会被默认全选覆盖。

合入后只更新该修订已选的基准,未选项不变。写入前仍核对冻结提交、三项检查、实际合入内容、保存时间及原基准;旧版本、合入后补选或冲突不能自动补认。请求超时或部分成功时联系维护者按原任务恢复,不重新派发或更换请求 ID。

@visactor-review-bot visactor-review-bot Bot Nov 11, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 为图文选择模式更新仍要求手工写入基准的指南

已启用图文选择的 PR 在合入前保存修订后,这里明确说工作流只更新所选基准;但同仓 packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md 第 29–33 行仍无条件要求管理员另行取得授权、手工更新并安排新的 Photo 复验,还写明“工作流不自动建立或更新基准”;PR 模板也写“不自动…更新基准”。维护者从视觉指南进入该流程时可能在工作流写入后重复操作共享基准,或将正常更新误判为不应发生。请给旧流程及模板增加图文选择模式的适用边界,说明何时仍需人工处理。


已确认修复 (4019e28): 已复查原触发条件及从视觉指南和 PR 模板进入的调用路径:用例协作指南现把启用图文选择时的已保存修订更新,与未启用或无可用清单时的人工流程明确分开,并说明结果未知时不得另行手工重复写入;中英文模板和视觉指南也写明图文选择适用边界。原先会引导维护者对已自动处理的共享基准再走人工更新的无条件要求已消失。


Photo 始终 report-only。没有可用选择清单(例如差异超过20项、解释未完成或执行错误)不新增合入门禁,也不自动更新基准。未启用图文选择的 PR 保持原模式。基准更新不会改写原 Photo 报告,流程 completed 不等于 Photo 全部通过。

请求帮助时提供 PR、当前 SHA、Review/CI 链接和可公开的错误说明。不要编辑 Bot 受管摘要或隐藏标记,不通过反复开关 PR、删除状态、换请求 ID 或另派批次绕过去重;由维护者回读和恢复原任务。结束时停止本次启动的测试服务、浏览器和子进程。
6 changes: 5 additions & 1 deletion packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,11 @@ Photo保持report-only:差异、缺基准、错误、未完成状态如实保

## 5. 首次基准与后续更新

新case缺基准时先核对本轮执行成功、目标状态和测试图正确;缺图、执行错误和未完成结果不能采用。Approve/Merge不授权自动采用图片,工作流不自动建立或更新基准。
新case缺基准时先核对本轮执行成功、目标状态和测试图正确;缺图、执行错误和未完成结果不能采用。

对明确启用图文选择的 PR,先在 BugServer 核对当前冻结版本的图片、短说明及服务端保存修订;新候选默认全选,改选必须在合入前保存成功。维护者按仓库规则手动 Merge 后,工作流核验版本、三项建议、合入内容和原基准,只处理已选项,未选项不变。Approve 仅作审计,不代替图片核查;更新失败、部分成功或结果未知时联系维护者按原任务恢复,不另行手工重复写入。

未启用图文选择或没有可用清单时,Approve/Merge 本身不授权自动采用图片,仍按以下人工流程处理。

具有基准写权限的管理员另行取得本次更新授权,核对准确产品、case/interaction、报告及task,读取现有标准引用后按平台支持的条件更新执行;只在明确无基准时使用“无基准”条件,不能把未知当空或无条件覆盖。结果未知保留原请求标识与输入,回读恢复,不换ID。

Expand Down
2 changes: 2 additions & 0 deletions packages/vseed/__tests__/visual/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,5 @@ Bot只在无网络隔离中使用 --offline 和逐侧准备的依赖。根pnpm-l
`.vseed-visual/runs/<run-id>/index.html` 展示三图,`agent-summary.md` 和 `summary.json` 保存问题、两侧SHA及范围;构建日志、两侧Playwright报告和失败trace用于定位。整体复制报告目录以保留相对链接,不提交运行产物。

正常、异常和Ctrl+C后检查本轮浏览器、HTTP服务、子进程和基线worktree已退出。SIGKILL/断电后先核对 `git worktree list` 和 `.vseed-visual/running.lock/owner.json` 的归属及进程状态,再由维护者处理本轮残留,不能盲删锁或他人资源。

图文选择已启用的 PR 按贡献指南核查并保存当前修订后手动 Merge,Approve 可选。仅合入前保存的所选基准可更新,未选项和原报告保持;该能力不改变上述全量视觉比较要求。
Loading