PostHog 前端 QA 证据输出与报告规范从截图采集到 PR 评论的完整管线【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇指南围绕 PostHog 仓库内qa-frontend技能的核心收尾阶段——evidence-and-output.md 展开系统讲解前端浏览器 QA 跑完之后的三件事如何安全地上传证据hogli pr:upload-image/hogli pr:upload-video、如何产出机器可解析的findings.json与QA-VERDICT产物、以及如何渲染出符合模板的 PR 评论与本地报告并最终通过审批门推送修复提交。读完你将掌握一条可复制的证据治理流程采集 → 审查 → 上传 → 渲染 → 审批推送并理解其背后的源码实现与安全护栏。一、整体定位QA 循环的最终阶段qa-frontend是 PostHog 仓库内置的前端/浏览器 QA 技能入口见 SKILL.md运行在两种模式下PR 模式针对某个 PRURL/编号/分支执行浏览器 QA可上传证据、在审批后发布一条 PR 评论并推送修复。本地模式针对当前分支与未提交改动执行 QA只写本地报告绝不上传、评论或推送。本文档evidence-and-output.md是该技能在 QA loop 完成、结论尘埃落定之后 才加载的参考文件负责证据上传、机器产物findings.jsonQA-VERDICT、报告渲染与推送审批四个环节。它与其他参考文件构成完整闭环safety-rules.md硬性审批门与推送策略本指南中的审批均来自它的定义pr-comment-template.mdPR 评论与本地报告的统一模板browser-mcp-patterns.md浏览器执行、控制台排查与证据采集的具体模式cleanup.md报告写完后对 checkout、浏览器会话、栈与生成文件的清理。二、证据上传hogli pr:upload-image与pr:upload-video2.1 基本规则上传是PR 模式专属行为且可选。任何文件离开开发者机器之前必须先获得用户的显式批准本地模式永远不上传证据。上传使用仓库自带的hogli pr:upload-image命令它把文件推送到公开的PostHog/pr-assets仓库并为每个文件打印一行alt形式的 Markdown可直接粘贴进 PR 评论。2.2 命令与参数# 上传图片png/jpg/jpeg/gif/webp最大 10 MB含动画演示卷轴 frontend-qa.webp hogli pr:upload-image --yes \ .qa-frontend/runs/run-id/frontend-qa.webp \ .qa-frontend/runs/run-id/screenshot.annotated.png # 上传演示视频mp4/webm同样 10 MB 上限与 --yes 审批门 hogli pr:upload-video --yes --label demo video \ .qa-frontend/runs/run-id/frontend-qa.mp4源码级细节upload_image.py明确了参数与限制允许的图片扩展名png、jpg、jpeg、gif、webp不含 svg——因为raw.githubusercontent.com会以text/plain提供 SVGGitHub 无法内联渲染10 MB 上限与 GitHub 对图片/GIF 附件的内置上限一致--alt指定图片的 Markdown alt 文本--pr可显式指定关联的 PR 编号默认取当前分支的 open PR--yes隐藏参数是审批门的落点第一次不带--yes运行只会打印公开性与永久性的警告并停止什么都不上传。--yes代表用户已批准这一组确切的文件绝不能在对话中出现该批准之前传入。视频命令upload_video.py只接受mp4与webm用--label指定链接文本打印的是普通label链接行。由于 GitHub 对 raw 托管的视频不渲染播放器该链接是点击下载式的若想要行内播放器仍需开发者手动把文件拖进评论编辑器。2.3 存储实现为什么 URL 是 SHA 固定且永久的pr:upload-image/pr:upload-video共用一个存储层 pr_assets.py。其核心设计对象键YYYY/MM/uuid4.extUTC 时间随机命名避免冲突按日期分目录便于浏览与清理make_key单次签名提交所有文件打包进一次提交通过 GitHubGraphQLcreateCommitOnBranchmutation提交而非 REST contents API——因为该仓库要求签名提交GraphQL 路径由 GitHub 用自己的密钥签名REST 路径以调用者身份未签名提交会被 ruleset 拒绝见模块 docstringURL 固定返回的 URL 形如https://raw.githubusercontent.com/PostHog/pr-assets/oid/path钉死在提交 SHA 上因此即使文件之后被移动或删除URL 依然持续服务——这正是一旦上传便无法收回的根本原因并发容错mutation 携带expectedHeadOid若并发提交先落地则报STALE_DATA代码会重读分支头重试最多 5 次_MAX_ATTEMPTS安全校验validate拒绝符号链接防止screenshot.png指向.env之类的敏感文件被上传、拒绝不支持的扩展名、拒绝超限文件认证从GH_TOKEN/GITHUB_TOKEN或gh auth token获取 token只需要对 PostHog 组织仓库有写权限开发者日常的gh登录即可无需额外密钥。token 缺失或权限不足时给出明确报错见_denied_message提示gh auth refresh -s repo或配置带reposcope 的 PAT。2.4 上传前必须做的证据审查上传是公开且永久的披露行为命令每次运行都会打印警告PUBLIC_WARNING常量。因此在请求上传批准之前必须像发布那样检查最终证据每张图必须让读者不重放浏览器会话就能理解其对应的 PASS/FAIL/SKIP/NEEDS INTENT 行。如果图片只显示页头、hero、空壳或设置状态而真正的证明在折叠线以下或小到不可读则不要上传应重新截图、通过浏览器定位滚动裁剪或先做更清晰的标注静态图。只挑人可读的证据frontend-qa.webp仅在生成且确认可读时、1–3 张与结论或 PASS 叙事匹配的关键标注截图。不传.md快照、console.log或每张编号截图。不泄露敏感信息只上传不含密钥、私有客户数据或无关本地上下文的已审查证据。对刻意造的数据补充说明当截图使用了技术上有效但不易自解释的测试数据边界邮箱语法、编码 URL、时区边界、合成计费状态时在报告的证据或覆盖行附近加一句解释。2.5 在可信目录运行上传命令PR 模式下工作树持有的是 PR 的代码./bin/hogli会执行 PR 的代码因此上传命令必须从可信的树运行绝不能从 PR checkout 运行。正确做法是先恢复原分支上传和评论本来就在 QA 循环之后发生或从另一个处于自己分支的独立 checkout 调用 hogli。2.6 上传失败的处理如果命令失败无 token、无组织访问权限、网络问题不要自写上传器也不要在 PR 评论中暴露本地文件系统路径记录evidence captured locally; upload failed or was skipped证据已本地采集上传失败或已跳过并继续。绝不让上传失败阻塞整个运行。本地报告仍可引用本地相对路径。PR 评论中要逐字使用命令打印的 Markdown 行不要重建或编辑 URL见 pr-comment-template.md 的 Evidence URLs 一节URL 是 SHA 固定的raw.githubusercontent.com/PostHog/pr-assets地址禁止重构、缩短或修改上传失败时回退到本地路径并追加(upload failed)。三、必需产物findings.json与QA-VERDICT每次运行在渲染任何面向用户的内容之前必须写出两个产物.qa-frontend/runs/run-id/findings.json——结构化的 findings 数组PR 评论和本地报告都是这个文件的渲染结果stdout 第一行输出QA-VERDICT: verdict——让外层编排器无需解析 Markdown 就能 grep 状态。verdict 词与模板pr-comment-template.md中的完全一致PASS、FIXED、FAIL、NEEDS-INTENT、REPORT-ONLY。fork PR 与仅评论的运行使用REPORT-ONLY并携带reasontoken。示例QA-VERDICT: PASS QA-VERDICT: FIXED findings1 fixes1 QA-VERDICT: FAIL findings3 fixes0 coverage_gaps2 QA-VERDICT: NEEDS-INTENT ambiguities1 QA-VERDICT: REPORT-ONLY findings1 reasonforkfindings.json的 schema{ id: sha1(targetstep)[:12], kind: finding|coverage_gap|needs_intent, severity: high|medium|low, confidence: high|medium, target: /route, step: user-visible step, expected: expected outcome, actual: actual outcome, evidence: [uploaded url or local path], status: new|fix-applied|suggested-patch|skipped|needs-intent, fix_commit: sha or null, question: intent question for needs_intent entries }字段语义要点id由sha1(targetstep)截取前 12 位生成保证相同目标与步骤的 finding 可稳定去重coverage_gap条目记录 QA 循环无法执行的路由或文件它们必须作为 PR 评论测试计划表中的可见行出现而不是页脚备注needs_intent条目记录观察到、但无法确立预期结果的行为本地模式在条件允许时应先问用户再定稿PR 模式应把这类条目显式渲染出来而不是把运行称作干净的 PASS。QA 循环中确认的 finding 是上述 schema 的严格子集渲染时会补上id、kind、confidence、status、fix_commit被清洗过的控制台摘录留在运行笔记中只引用在报告正文不放进findings.json。四、渲染PR 评论与本地报告4.1 渲染前的强制动作重读模板在撰写评论或本地报告之前重新阅读 pr-comment-template.md不要凭记忆即兴发挥。持续记录运行笔记整个运行过程中把创建或依赖的每项设置追加到.qa-frontend/runs/run-id/run-notes.md与所有其他产物同一目录栈选择、工作区与登录、org/计划状态、创建或播种的数据、flag/主题覆盖、降级进程。报告必需的 Setup 章节就是从这些笔记渲染的——它是读者决定是否信任每个 PASS 的依据。发布前完整性检查渲染后的报告必须满足——第一行是## PostHog QA Frontend Report第二行是匹配模板的 verdict 行最后一行是subPostHog QA Frontend Report/sub。缺少任何一项就重新读模板再渲染。4.2 PR 模式评论规则PR 模式在显式批准后为每次完成的运行发布一条 PR 评论按结果分型干净运行PASS verdict 覆盖表有把握的修复已推送的修复摘要 findings 与证据低置信度或 fork PR带复现步骤与建议补丁的 findings预期行为不明确NEEDS-INTENT verdict 可见的 intent 行前端目标有缺口显式的 coverage-gap 行。任何推送之前先用只读的gh api可达性检查验证评论路径不要创建临时桩评论。若评论连通性失败跳过推送、把最终评论 Markdown 打印到 stdout 然后停止。4.3 本地模式报告规则本地模式把渲染报告写到 stdout 和.qa-frontend/runs/run-id/report.md使用同一模板但省略上传步骤证据只以本地路径引用作为相对于报告文件的可点击 Markdown 链接参见模板中的 local-report links 规则如before可在编辑器预览中内联渲染demo reel可点击打开不调用gh api、gh pr comment或任何推送。五、推送审批门修复提交如何落地PR 模式、同仓库 PR、且至少有一个高置信度修复提交时才适用自动推送如果$ARGUMENTS中设置了AUTO_PUSH_FIXES直接进入推送步骤。自动推送同时也意味着对修复摘要 PR 评论的批准——没有披露修复的评论就绝不推送修复评论发不出去就不推送。人工确认否则在修复循环完成且复验通过后停下来在对话中询问用户Apply fix commit(s) sha-list to the PR branch? (y/n)。等待明确的 yes / y / push 或类似确认。no / n / 沉默 不推送。此时输出带本地提交 SHA 的评论草稿并注明用户可以手动推送。普通非强制推送PR_HEAD_REF$(gh pr view $PR_REF --json headRefName --jq .headRefName) test -n $PR_HEAD_REF GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null \ git push origin $PR_HEAD_REF安全语义同时见 safety-rules.md 的 Push Policy绝不 force-push。推送命名的是本地 PR 分支而非HEAD因此无论当前 checkout 的是哪个分支都正确修复提交叠加在 checkout 出的 PR head 之上所以如果非快进被拒绝说明运行期间远端移动了不要重试、不要 fetch-and-force直接发布报告说明存在本地修复提交但因 PR 分支已变化而未推送推送与修复提交相关的 git 操作都导出GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null因为本仓库的.husky/hooks 是 PR 控制的代码裸执行会运行攻击者可控制的 hook详见 SKILL.md 的 Checkout 一节。5.1 证据卫生为什么修复提交只能按路径暂存证据文件统一放在.qa-frontend/runs/run-id/下且保持未提交状态。永远不要 stage 或 commit.qa-frontend/下的任何内容在技能合并之前创建的 PR 分支上该目录未被 gitignore若使用git add -A、git add .或git commit -a批量暂存会把本地栈截图混入修复提交并在推送时公开绕过证据上传审批门。因此必须只按精确路径暂存修复文件并在每次提交前检查git diff --cached --name-only。六、从采集到产出的完整链路源码视角把本指南与兄弟参考文件串起来得到完整的证据生命周期采集browser-mcp-patterns.md用浏览器 MCPPlaywright MCP 是仓库内的已知范例导航、快照、交互、断言 UI 状态、截图、收集控制台/网络信号每个候选问题必须通过一次复现重试才能成为 finding否则记为INTERMITTENT覆盖行并保留首次失败的证据标注与卷轴用 annotate-evidence.pyuv run python复用仓库已有 Pillow 依赖不安装新包、不用 ffmpeg为关键帧加 caption bar 与 PASS/FAIL/INFO 芯片、为 finding 加高亮框并把 2–5 帧合成为慢速动画 WebPfrontend-qa.webp宽度上限 1200px3–5 帧的 1200px 截图卷轴通常远小于 200 KB录制演示视频默认在 QA 循环结束后用浏览器工具原生录制 cursor-overlay.js 注入可见光标重跑关键流程再转码为 H.264 MP4--trim-start用 ffmpeg 输出定位保证帧级精确且只用uv run python ... video子命令转码发布前用fps1,tile5x2的接触表contact sheet验证每步 caption 顺序与最终 finding 状态结构化产物findings.json本指南第三节 schema 第一行QA-VERDICT: ...渲染与发布按 pr-comment-template.md 渲染PR 模式在审批后经hogli pr:upload-image上传并发布单条评论含 banner、verdict 行、覆盖表、Setup、可选 Effort saved、findings、Needs intent、建议补丁、Before/After 并排对比目标约 10k 字符、55k 字符时截断 per-finding 复现细节本地模式只写 stdout 与report.md推送与清理走第五节审批门推送随后按 cleanup.md 恢复原分支、关闭浏览器会话、恢复主题与 feature-flag 覆盖、必要时移除hogli.yaml中自动生成的 phrocs 配置、清理 gitignore 缺失分支上的运行目录移出仓库到$TMPDIR/qa-frontend-runs/。6.1 评论发布前的清洗Scrubbing无论走哪条发布路径发布前都要清洗控制台摘录中的bearer token、query-string token、cookie、CSRF 值、疑似密钥、凭据标签附近的长编码值。绝不包含 GitHub token 或 raw 上传响应体若复制hogli pr:upload-image的输出只取 stdout 中的alt行。来自被测应用的 UI 字符串问题标题、标签、错误文本会插值进代码围栏必须剥离反引号与控制字符并截断超长内容防止恶意或倒霉的字符串闭合围栏向评论注入 Markdown。本地栈截图仅在小且安全时嵌入输出中不要使用 em dash—一律用普通连字符-或改写句子。七、结语qa-frontend的证据与输出规范把浏览器 QA 跑完这个模糊的中间态收敛成三条硬性产出——findings.json、QA-VERDICT与符合模板的报告——并用公开且永久的上传语义、逐字引用的 SHA 固定 URL、先审批后--yes的确认门、以及无披露评论不推送的联动约束把证据治理从口头约定变成了可审计的流程。对于任何要复刻类似浏览器 QA 管线的团队这套模式机器可解析产物 模板化渲染 双重审批门 精确暂存卫生本身就是一份可直接借鉴的工程蓝本。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PostHog 前端 QA 证据输出与报告规范：从截图采集到 PR 评论的完整管线
PostHog 前端 QA 证据输出与报告规范从截图采集到 PR 评论的完整管线【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本篇指南围绕 PostHog 仓库内qa-frontend技能的核心收尾阶段——evidence-and-output.md 展开系统讲解前端浏览器 QA 跑完之后的三件事如何安全地上传证据hogli pr:upload-image/hogli pr:upload-video、如何产出机器可解析的findings.json与QA-VERDICT产物、以及如何渲染出符合模板的 PR 评论与本地报告并最终通过审批门推送修复提交。读完你将掌握一条可复制的证据治理流程采集 → 审查 → 上传 → 渲染 → 审批推送并理解其背后的源码实现与安全护栏。一、整体定位QA 循环的最终阶段qa-frontend是 PostHog 仓库内置的前端/浏览器 QA 技能入口见 SKILL.md运行在两种模式下PR 模式针对某个 PRURL/编号/分支执行浏览器 QA可上传证据、在审批后发布一条 PR 评论并推送修复。本地模式针对当前分支与未提交改动执行 QA只写本地报告绝不上传、评论或推送。本文档evidence-and-output.md是该技能在 QA loop 完成、结论尘埃落定之后 才加载的参考文件负责证据上传、机器产物findings.jsonQA-VERDICT、报告渲染与推送审批四个环节。它与其他参考文件构成完整闭环safety-rules.md硬性审批门与推送策略本指南中的审批均来自它的定义pr-comment-template.mdPR 评论与本地报告的统一模板browser-mcp-patterns.md浏览器执行、控制台排查与证据采集的具体模式cleanup.md报告写完后对 checkout、浏览器会话、栈与生成文件的清理。二、证据上传hogli pr:upload-image与pr:upload-video2.1 基本规则上传是PR 模式专属行为且可选。任何文件离开开发者机器之前必须先获得用户的显式批准本地模式永远不上传证据。上传使用仓库自带的hogli pr:upload-image命令它把文件推送到公开的PostHog/pr-assets仓库并为每个文件打印一行alt形式的 Markdown可直接粘贴进 PR 评论。2.2 命令与参数# 上传图片png/jpg/jpeg/gif/webp最大 10 MB含动画演示卷轴 frontend-qa.webp hogli pr:upload-image --yes \ .qa-frontend/runs/run-id/frontend-qa.webp \ .qa-frontend/runs/run-id/screenshot.annotated.png # 上传演示视频mp4/webm同样 10 MB 上限与 --yes 审批门 hogli pr:upload-video --yes --label demo video \ .qa-frontend/runs/run-id/frontend-qa.mp4源码级细节upload_image.py明确了参数与限制允许的图片扩展名png、jpg、jpeg、gif、webp不含 svg——因为raw.githubusercontent.com会以text/plain提供 SVGGitHub 无法内联渲染10 MB 上限与 GitHub 对图片/GIF 附件的内置上限一致--alt指定图片的 Markdown alt 文本--pr可显式指定关联的 PR 编号默认取当前分支的 open PR--yes隐藏参数是审批门的落点第一次不带--yes运行只会打印公开性与永久性的警告并停止什么都不上传。--yes代表用户已批准这一组确切的文件绝不能在对话中出现该批准之前传入。视频命令upload_video.py只接受mp4与webm用--label指定链接文本打印的是普通label链接行。由于 GitHub 对 raw 托管的视频不渲染播放器该链接是点击下载式的若想要行内播放器仍需开发者手动把文件拖进评论编辑器。2.3 存储实现为什么 URL 是 SHA 固定且永久的pr:upload-image/pr:upload-video共用一个存储层 pr_assets.py。其核心设计对象键YYYY/MM/uuid4.extUTC 时间随机命名避免冲突按日期分目录便于浏览与清理make_key单次签名提交所有文件打包进一次提交通过 GitHubGraphQLcreateCommitOnBranchmutation提交而非 REST contents API——因为该仓库要求签名提交GraphQL 路径由 GitHub 用自己的密钥签名REST 路径以调用者身份未签名提交会被 ruleset 拒绝见模块 docstringURL 固定返回的 URL 形如https://raw.githubusercontent.com/PostHog/pr-assets/oid/path钉死在提交 SHA 上因此即使文件之后被移动或删除URL 依然持续服务——这正是一旦上传便无法收回的根本原因并发容错mutation 携带expectedHeadOid若并发提交先落地则报STALE_DATA代码会重读分支头重试最多 5 次_MAX_ATTEMPTS安全校验validate拒绝符号链接防止screenshot.png指向.env之类的敏感文件被上传、拒绝不支持的扩展名、拒绝超限文件认证从GH_TOKEN/GITHUB_TOKEN或gh auth token获取 token只需要对 PostHog 组织仓库有写权限开发者日常的gh登录即可无需额外密钥。token 缺失或权限不足时给出明确报错见_denied_message提示gh auth refresh -s repo或配置带reposcope 的 PAT。2.4 上传前必须做的证据审查上传是公开且永久的披露行为命令每次运行都会打印警告PUBLIC_WARNING常量。因此在请求上传批准之前必须像发布那样检查最终证据每张图必须让读者不重放浏览器会话就能理解其对应的 PASS/FAIL/SKIP/NEEDS INTENT 行。如果图片只显示页头、hero、空壳或设置状态而真正的证明在折叠线以下或小到不可读则不要上传应重新截图、通过浏览器定位滚动裁剪或先做更清晰的标注静态图。只挑人可读的证据frontend-qa.webp仅在生成且确认可读时、1–3 张与结论或 PASS 叙事匹配的关键标注截图。不传.md快照、console.log或每张编号截图。不泄露敏感信息只上传不含密钥、私有客户数据或无关本地上下文的已审查证据。对刻意造的数据补充说明当截图使用了技术上有效但不易自解释的测试数据边界邮箱语法、编码 URL、时区边界、合成计费状态时在报告的证据或覆盖行附近加一句解释。2.5 在可信目录运行上传命令PR 模式下工作树持有的是 PR 的代码./bin/hogli会执行 PR 的代码因此上传命令必须从可信的树运行绝不能从 PR checkout 运行。正确做法是先恢复原分支上传和评论本来就在 QA 循环之后发生或从另一个处于自己分支的独立 checkout 调用 hogli。2.6 上传失败的处理如果命令失败无 token、无组织访问权限、网络问题不要自写上传器也不要在 PR 评论中暴露本地文件系统路径记录evidence captured locally; upload failed or was skipped证据已本地采集上传失败或已跳过并继续。绝不让上传失败阻塞整个运行。本地报告仍可引用本地相对路径。PR 评论中要逐字使用命令打印的 Markdown 行不要重建或编辑 URL见 pr-comment-template.md 的 Evidence URLs 一节URL 是 SHA 固定的raw.githubusercontent.com/PostHog/pr-assets地址禁止重构、缩短或修改上传失败时回退到本地路径并追加(upload failed)。三、必需产物findings.json与QA-VERDICT每次运行在渲染任何面向用户的内容之前必须写出两个产物.qa-frontend/runs/run-id/findings.json——结构化的 findings 数组PR 评论和本地报告都是这个文件的渲染结果stdout 第一行输出QA-VERDICT: verdict——让外层编排器无需解析 Markdown 就能 grep 状态。verdict 词与模板pr-comment-template.md中的完全一致PASS、FIXED、FAIL、NEEDS-INTENT、REPORT-ONLY。fork PR 与仅评论的运行使用REPORT-ONLY并携带reasontoken。示例QA-VERDICT: PASS QA-VERDICT: FIXED findings1 fixes1 QA-VERDICT: FAIL findings3 fixes0 coverage_gaps2 QA-VERDICT: NEEDS-INTENT ambiguities1 QA-VERDICT: REPORT-ONLY findings1 reasonforkfindings.json的 schema{ id: sha1(targetstep)[:12], kind: finding|coverage_gap|needs_intent, severity: high|medium|low, confidence: high|medium, target: /route, step: user-visible step, expected: expected outcome, actual: actual outcome, evidence: [uploaded url or local path], status: new|fix-applied|suggested-patch|skipped|needs-intent, fix_commit: sha or null, question: intent question for needs_intent entries }字段语义要点id由sha1(targetstep)截取前 12 位生成保证相同目标与步骤的 finding 可稳定去重coverage_gap条目记录 QA 循环无法执行的路由或文件它们必须作为 PR 评论测试计划表中的可见行出现而不是页脚备注needs_intent条目记录观察到、但无法确立预期结果的行为本地模式在条件允许时应先问用户再定稿PR 模式应把这类条目显式渲染出来而不是把运行称作干净的 PASS。QA 循环中确认的 finding 是上述 schema 的严格子集渲染时会补上id、kind、confidence、status、fix_commit被清洗过的控制台摘录留在运行笔记中只引用在报告正文不放进findings.json。四、渲染PR 评论与本地报告4.1 渲染前的强制动作重读模板在撰写评论或本地报告之前重新阅读 pr-comment-template.md不要凭记忆即兴发挥。持续记录运行笔记整个运行过程中把创建或依赖的每项设置追加到.qa-frontend/runs/run-id/run-notes.md与所有其他产物同一目录栈选择、工作区与登录、org/计划状态、创建或播种的数据、flag/主题覆盖、降级进程。报告必需的 Setup 章节就是从这些笔记渲染的——它是读者决定是否信任每个 PASS 的依据。发布前完整性检查渲染后的报告必须满足——第一行是## PostHog QA Frontend Report第二行是匹配模板的 verdict 行最后一行是subPostHog QA Frontend Report/sub。缺少任何一项就重新读模板再渲染。4.2 PR 模式评论规则PR 模式在显式批准后为每次完成的运行发布一条 PR 评论按结果分型干净运行PASS verdict 覆盖表有把握的修复已推送的修复摘要 findings 与证据低置信度或 fork PR带复现步骤与建议补丁的 findings预期行为不明确NEEDS-INTENT verdict 可见的 intent 行前端目标有缺口显式的 coverage-gap 行。任何推送之前先用只读的gh api可达性检查验证评论路径不要创建临时桩评论。若评论连通性失败跳过推送、把最终评论 Markdown 打印到 stdout 然后停止。4.3 本地模式报告规则本地模式把渲染报告写到 stdout 和.qa-frontend/runs/run-id/report.md使用同一模板但省略上传步骤证据只以本地路径引用作为相对于报告文件的可点击 Markdown 链接参见模板中的 local-report links 规则如before可在编辑器预览中内联渲染demo reel可点击打开不调用gh api、gh pr comment或任何推送。五、推送审批门修复提交如何落地PR 模式、同仓库 PR、且至少有一个高置信度修复提交时才适用自动推送如果$ARGUMENTS中设置了AUTO_PUSH_FIXES直接进入推送步骤。自动推送同时也意味着对修复摘要 PR 评论的批准——没有披露修复的评论就绝不推送修复评论发不出去就不推送。人工确认否则在修复循环完成且复验通过后停下来在对话中询问用户Apply fix commit(s) sha-list to the PR branch? (y/n)。等待明确的 yes / y / push 或类似确认。no / n / 沉默 不推送。此时输出带本地提交 SHA 的评论草稿并注明用户可以手动推送。普通非强制推送PR_HEAD_REF$(gh pr view $PR_REF --json headRefName --jq .headRefName) test -n $PR_HEAD_REF GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null \ git push origin $PR_HEAD_REF安全语义同时见 safety-rules.md 的 Push Policy绝不 force-push。推送命名的是本地 PR 分支而非HEAD因此无论当前 checkout 的是哪个分支都正确修复提交叠加在 checkout 出的 PR head 之上所以如果非快进被拒绝说明运行期间远端移动了不要重试、不要 fetch-and-force直接发布报告说明存在本地修复提交但因 PR 分支已变化而未推送推送与修复提交相关的 git 操作都导出GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null因为本仓库的.husky/hooks 是 PR 控制的代码裸执行会运行攻击者可控制的 hook详见 SKILL.md 的 Checkout 一节。5.1 证据卫生为什么修复提交只能按路径暂存证据文件统一放在.qa-frontend/runs/run-id/下且保持未提交状态。永远不要 stage 或 commit.qa-frontend/下的任何内容在技能合并之前创建的 PR 分支上该目录未被 gitignore若使用git add -A、git add .或git commit -a批量暂存会把本地栈截图混入修复提交并在推送时公开绕过证据上传审批门。因此必须只按精确路径暂存修复文件并在每次提交前检查git diff --cached --name-only。六、从采集到产出的完整链路源码视角把本指南与兄弟参考文件串起来得到完整的证据生命周期采集browser-mcp-patterns.md用浏览器 MCPPlaywright MCP 是仓库内的已知范例导航、快照、交互、断言 UI 状态、截图、收集控制台/网络信号每个候选问题必须通过一次复现重试才能成为 finding否则记为INTERMITTENT覆盖行并保留首次失败的证据标注与卷轴用 annotate-evidence.pyuv run python复用仓库已有 Pillow 依赖不安装新包、不用 ffmpeg为关键帧加 caption bar 与 PASS/FAIL/INFO 芯片、为 finding 加高亮框并把 2–5 帧合成为慢速动画 WebPfrontend-qa.webp宽度上限 1200px3–5 帧的 1200px 截图卷轴通常远小于 200 KB录制演示视频默认在 QA 循环结束后用浏览器工具原生录制 cursor-overlay.js 注入可见光标重跑关键流程再转码为 H.264 MP4--trim-start用 ffmpeg 输出定位保证帧级精确且只用uv run python ... video子命令转码发布前用fps1,tile5x2的接触表contact sheet验证每步 caption 顺序与最终 finding 状态结构化产物findings.json本指南第三节 schema 第一行QA-VERDICT: ...渲染与发布按 pr-comment-template.md 渲染PR 模式在审批后经hogli pr:upload-image上传并发布单条评论含 banner、verdict 行、覆盖表、Setup、可选 Effort saved、findings、Needs intent、建议补丁、Before/After 并排对比目标约 10k 字符、55k 字符时截断 per-finding 复现细节本地模式只写 stdout 与report.md推送与清理走第五节审批门推送随后按 cleanup.md 恢复原分支、关闭浏览器会话、恢复主题与 feature-flag 覆盖、必要时移除hogli.yaml中自动生成的 phrocs 配置、清理 gitignore 缺失分支上的运行目录移出仓库到$TMPDIR/qa-frontend-runs/。6.1 评论发布前的清洗Scrubbing无论走哪条发布路径发布前都要清洗控制台摘录中的bearer token、query-string token、cookie、CSRF 值、疑似密钥、凭据标签附近的长编码值。绝不包含 GitHub token 或 raw 上传响应体若复制hogli pr:upload-image的输出只取 stdout 中的alt行。来自被测应用的 UI 字符串问题标题、标签、错误文本会插值进代码围栏必须剥离反引号与控制字符并截断超长内容防止恶意或倒霉的字符串闭合围栏向评论注入 Markdown。本地栈截图仅在小且安全时嵌入输出中不要使用 em dash—一律用普通连字符-或改写句子。七、结语qa-frontend的证据与输出规范把浏览器 QA 跑完这个模糊的中间态收敛成三条硬性产出——findings.json、QA-VERDICT与符合模板的报告——并用公开且永久的上传语义、逐字引用的 SHA 固定 URL、先审批后--yes的确认门、以及无披露评论不推送的联动约束把证据治理从口头约定变成了可审计的流程。对于任何要复刻类似浏览器 QA 管线的团队这套模式机器可解析产物 模板化渲染 双重审批门 精确暂存卫生本身就是一份可直接借鉴的工程蓝本。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考