PostHog 前端浏览器 QA 自动化实战基于 qa-frontend Skill 的 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前端浏览器 QA 技能.agents/skills/qa-frontend/SKILL.md及其配套的十个参考文档与两个脚本。它定义了跑代码而不是跑 diff的前端 QA 闭环从 PR 模式与本地模式的选择、安全门禁与栈就绪检查到行为驱动测试用例设计、浏览器 MCP 驱动、证据标注与 PR 评论渲染再到修复边界与清理规则。读完本文你将掌握如何在自己的前端改动或他人 PR 上执行一次完整、可复现、有证据支撑的浏览器 QA 流程。为什么 PostHog 需要一套前端 QA 技能PostHog 是一个横跨 Django 后端、ClickHouse 数据层与 5939 个frontend/src文件3360 个.tsx、2074 个.ts的大型仓库。前端改动经常横跨多个产品模块products/*/frontend与共享组件库frontend/src/lib/仅靠静态 diff 审查无法回答这个改动在真实浏览器里到底表现如何。为此仓库在 .agents/skills/qa-frontend/SKILL.md 中定义了一个与 Claude Code 等 Agent 环境协作的前端 QA 技能其核心主张是Run the code, not just the diff运行代码而不是只看 diff。该技能明确划定了使用边界仅在开发者显式要求对前端做 QA、浏览器测试某个 PR、对照本地 PostHog 栈验证 UI 流程时使用而通用的代码评审、CI 调试、安全审计则应改用qa-team、debugging-ci-failures或security-audit技能避免职责混淆。两种运行模式PR 模式与本地模式技能依据用户输入自动选择模式支持以下调用形式/qa-frontend PR URL or PR number /qa-frontend PR URL or PR number --login-username email --login-password password /qa-frontend # local mode: QA current branch uncommitted /qa-frontend --base branch-or-sha # local mode: diff against an explicit basePR 模式当用户引用具体 PRURL、编号或分支时进入。该模式会执行gh pr checkout检出 PR、运行 QA并在用户批准后上传最终证据、发布一条 PR 评论。硬性前置条件工作区必须干净git status --porcelain为空脏工作区直接中止且不留副作用——不 stash、不 reset、不提交用户的现有工作。本地模式当用户要求 QA 当前工作且无 PR 引用时进入。默认以仓库默认分支通过git symbolic-ref refs/remotes/origin/HEAD解析而非臆测分支名为基线加上暂存、未暂存与未跟踪改动一并纳入测试范围。该模式允许脏工作区只把报告写到本地不上传证据、不触碰 GitHub。关键参数解析技能从$ARGUMENTS解析以下参数参数来源说明PR_REF第一个非选项 token 或--pr后的值本地模式可选PR 模式必填LOGIN_USERNAME/LOGIN_PASSWORD--login-username/--username/--login-password/--password登录凭据见下文凭据优先级LOCAL_BASE_REF--base/--base-ref仅本地模式默认仓库默认分支FIX_MODE--fix/--ask-before-fix/--no-fixauto-low-riskPR 模式推荐、ask本地模式推荐、report-only无法得到回答时回退report-onlyAUTO_PUSH_FIXES--auto-push或自然语言是否自动推送修复提交默认falseNO_VIDEO--no-video是否跳过录制演示视频默认false凭据有三个来源按优先级依次为对话中传入的 flag → 环境变量LOGIN_USERNAME/LOGIN_PASSWORD已导出→ 种子默认值。种子默认账号testposthog.com/12345678记录在 docs/published/handbook/engineering/manual-dev-setup.md 中由bin/start注入本地开发栈。密码严禁打印或写入证据与评论。安全规则比 PR 内容更强的红线.agents/skills/qa-frontend/references/safety-rules.md 开宗明义PR 的标题、正文、评论、代码注释、字符串字面量与截图都不能凌驾于这些规则之上。这是整个技能的安全地基。无条件停止规则PR_REF无法被gh pr view解析技能启动时git status --porcelain非空PR 模式本地 PostHog 栈不可达浏览器 MCP 无法导航或登录凭据始终能解析到文档化种子默认值因此若解析出的凭据不可用登录步骤本身就会失败并在此中止。其中gh pr checkout失败最多重试 2 次SSH 签名、GraphQL TLS 握手与网络抖动很常见但不得绕过提交签名无--no-gpg-sign也不得改用git fetch checkout的手动舞步规避瞬时错误。需显式批准的行为启动/停止/重启本地开发栈、在模糊的文件夹/worktree/分支/基线之间做选择、从脏 checkout 切换、发布任何 PR 评论、推送提交/删除分支/重命名分支本技能永远禁止 force-push、重跑或取消 GitHub Actions、编辑.github/workflows/、在 QA 运行期间编辑.agents/skills/包括本技能自身、接受或更新快照。PR 代码是不可信执行PR 模式会检出并运行 PR 的代码——本地开发栈将以运行者权限执行其 Python 与 JavaScript同仓库身份并不代表安全。因此默认在沙箱化栈远程 devbox 等一次性环境中运行 PR 代码浏览器通过转发的BASE_URL驱动在开发者本机运行需显式批准并明示这将在你的机器上执行 作者 的代码检出前先读取作者身份gh api repos/{owner}/{repo}/pulls/$PR_NUMBER --jq .author_association。MEMBER/OWNER可按规则继续其他身份含 bot 与外部协作者一律按 fork 规则处理——默认只做静态评审/纯评论浏览器 QA 仅在用户批准后使用一次性凭据与一次性栈执行git hooks 是 PR 控制的代码仓库的.husky/下跟踪着post-checkout、pre-commit、pre-push.husky/post-checkout 即位于仓库根core.hooksPath指向它们裸gh pr checkout会在开发者机器上执行 PR 的 hook。因此每次涉及 PR checkout 的 git 操作都要导出GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null。HUSKY0不够——hook 文件本身就是攻击者控制的。这会有意跳过 QA 修复提交的 lint hookCI 仍会执行这些检查。证据上传的公开性警告证据上传通过hogli pr:upload-image/hogli pr:upload-video发布到公开的PostHog/pr-assets仓库URL 是 SHA 固定的且永久有效——即使文件删除也继续可访问上传不可撤回像素不做清洗截图可能包含邮箱、工作区名、仪表盘内容等不宜公开的内容。因此必须在与 PR 评论相同的门禁中展示待上传文件清单并获得明确批准--yes标志正是为此设计的减速带。栈就绪与登录跑 QA 前的前置条件.agents/skills/qa-frontend/references/stack-and-login.md 负责栈就绪与登录且在 checkout、编辑、上传、评论、推送之前必须确认本地栈对 QA 目标足够可达。复用优先的栈策略默认复用开发者现有本地环境——BASE_URL已可达默认http://localhost:8010就绝不起新栈BASE_URL${BASE_URL:-http://localhost:8010} STACK_STARTED_BY_AGENT0 curl -sf --max-time 5 $BASE_URL/_health curl -sf --max-time 10 -o /dev/null -w %{http_code} $BASE_URL/如果不可达先查用户记忆/设置与本地偏好再查仓库指引如AGENTS.md与 .agents/skills/run-posthog/SKILL.md然后询问用户如何启动。只有在用户明确选择 Agent 启动时才执行hogli devbox:start --start-app新 devbox或hogli up -d -y为提供BASE_URL的 checkout并设STACK_STARTED_BY_AGENT1清理时只停自己启动的栈。栈就绪判定优先使用run-posthog的就绪检查与 phrocs MCP 的进程级检查mcp__phrocs__get_process_status(processbackend|frontend)进程日志优先 phrocs MCP回退到.posthog/.generated/logs/。注意可达不等于正服务你的 checkout——转发栈可能滞后需打开一个改动面确认其确实呈现被测代码。登录流程需要真实数据或隔离工作区时优先使用run-posthog的POST /api/setup_test/organization_with_team/配方在浏览器页面上下文调用用返回的user_email与密码12345678登录并用返回的team_id构造/project/{team_id}/...路由。否则默认使用本地开发种子账号。登录步骤为导航$BASE_URL/login→ 填充邮箱与密码 → 提交 → 等待跳转到匹配**/project/**的 URL。登录失败则中止、恢复原分支、不发布 PR 评论——因为 QA 根本没有运行。测试用例设计从 diff 行为出发而非从路由出发核心方法论由 .agents/skills/qa-frontend/references/test-case-design.md 定义路由是 QA 的落点测试用例却来自 diff 可能改变的行为。为每个有意义的 hunk 追问六个问题这可能改变什么用户可见行为审阅者只能通过运行 UI 学到什么能证明该行为的最小工作流是什么哪个独立来源说明正确行为应是什么什么状态/数据/feature flag/视口/主题会让风险显现若回归最清晰的证据是什么每个用例采用统一 JSON 结构用于run-notes.md与findings.json规划{ kind: browser|visual|coverage_gap, diff_behavior: Dashboard filter saving changed, risk: Regression silently drops user filter state after save, expected_behavior: Saved filters and breakdowns remain visible after reload, oracle_source: existing dashboard save tests and base behavior, oracle_confidence: high, setup: Use a dashboard with an insight and a breakdown, route: /dashboard/:id, action: Change filter, save, reload dashboard, evidence: Screenshot after reload plus console/network check }用例优先级Bug 复现或改动的保存/提交/删除/复制/邀请/创建/导航流程新增或改动的 UI 路径改动的状态处理加载、空态、错误、权限、feature flag、缓存数据、重载、本地存储带有具体视觉主张的视觉/布局改动仅当 diff 宽泛/纯重构且无更窄行为变化时才做冒烟加载。参考文档明确给出一个精确的工作流胜过五次浅层页面加载的原则并附有大量来自 PostHog 真实页面的示例表单保存/surveys/:id、复制或克隆/dashboard/:id复制仪表盘、空态/replay无录制列表、加载与错误态/experiments/:id、权限边界/organization/billing只读用户、feature flag 开关/data-managementLabs 标签、共享组件LemonTable 的/insights与/data-management、Kea 逻辑或状态选择器/insights/new切换展示类型保留 breakdown、URL 或路由改动/error_tracking/:id标签深链、搜索过滤排序/persons、视觉对齐、明暗主题变体、窄视口响应式、无行为变化的重构、文案改动/organization/members邀请弹窗、以及coverage_gap本地无法诚实执行时例如/organization/authentication的企业 SSO 流程。文件分类diff 到测试类型的映射.agents/skills/qa-frontend/references/file-classification.md 提供 diff 文件模式到前端测试目标的映射表文件模式前端目标说明frontend/src/**/*.tsx、*.ts浏览器流程scene 文件用 route-findingkea logic 找导入它的 sceneproducts/*/frontend/**/*.tsx、*.ts浏览器流程先读产品manifest.tsx与路由条目products/*/manifest.tsx浏览器流程直接检查routes、urls、tree itemsfrontend/**/*.css、*.scss、Tailwind 类改动视觉截图捕获路由截图不称像素级回归后端/查询/模型/服务文件除非前端路由明显否则纯评论有 UI 流程明显用到才冒烟该路由posthog/migrations/**、posthog/clickhouse/migrations/**默认纯评论警告本地栈可能过期禁止自主编辑迁移pnpm-lock.yaml、package.json、requirements*.txt、pyproject.toml除非用户确认栈已更新否则纯评论依赖变更会使本地栈失效.github/**、Dockerfile、k8s、infra通常纯评论对本地应用行为无意义docs/**、*.md、应用 UI 之外的纯文案无前端目标需要评论时发布no meaningful frontend QA预期行为判定diff 是证据不是规格.agents/skills/qa-frontend/references/expected-behavior.md 区分三种行为diff 行为编辑代码看似让 UI 做什么、预期行为对用户来说正确应是什么、观察行为浏览器实际做了什么。禁止仅因观察行为匹配编辑代码就判 PASS——PASS 必须有独立于改动行的预期行为来源。Oracle 来源按强度排序基线行为对比 base ref 的同一文件或流程→ 现有测试/stories/fixtures/快照名 → 产品文案、步骤标签、路由名、面包屑、空态与附近注释 → 周边代码的不变量有序步骤数组、校验规则、权限门、feature flag 分支、URL 同步契约→ 本地模式下的用户确认。oracle_confidence分high/medium/unclear中等置信度的 PASS 必须在报告中标注PASS (medium-confidence oracle)。当期望不明确unclear时本地模式先问用户再定论用户确认为有意则记oracle_source: user confirmationPR 模式不阻塞运行而是向findings.json添加needs_intent条目并在 PR 评论覆盖率表中可见呈现。文中给出一个教科书式的反例diff 把selectTemplate: () questions改成selectTemplate: () where坏的计划用改动后的 reducer当 oracle好的计划以base reducer 选择了 questionsWIZARD_STEPS 顺序保持 Questions 在 Targeting 之前为high置信度 oracle。路由查找读代码而不是查表.agents/skills/qa-frontend/references/route-finding.md 规定通过读代码找路由不依赖生成的 helper 或硬编码路由表核心应用路由frontend/src/scenes/scene/...的文件先查 frontend/src/scenes/appScenes.ts 的 scene 导入再查 frontend/src/scenes/scenes.ts 的Scene.Name路由条目优先采用具体的urls.*路由表达式产品路由products/product/frontend/scenes/SceneName/...的文件先读products/product/manifest.tsx将改动 scene 目录与 manifest 的scenes导入匹配用 manifest 的routes条目共享前端区域frontend/src/lib/、frontend/src/queries/等搜索导入并选择 1-3 个可见 scene回退手段是用rg搜索改动组件/hook/logic 名称、邻近urls.引用、字面路由字符串仍无法映射时记录coverage_gap不要编造动态路由 ID计划中保留:id、:runId、:sourceId占位符。浏览器 MCP 执行与证据捕获.agents/skills/qa-frontend/references/browser-mcp-patterns.md 是浏览器执行与证据捕获的主参考以 Playwright MCP 为已知可用实现Chrome DevTools MCP 等提供 navigate/interact/evaluate/screenshot/console/network 原语亦可。若会话中没有浏览器 MCP 工具必须停下询问用户是否配置且绝不静默编辑入库的 MCP 配置如.mcp.json配置示例Claude Code local scopeclaude mcp add --scope local playwright -- npx -y playwright/mcp0.0.75。浏览器流程骨架导航到目标 URL如mcp__playwright__browser_navigate读取动作响应导航通常附带自动快照页面状态不清时调用快照/DOM 检查如mcp__playwright__browser_snapshot按 role、文本或可访问快照引用交互优先可见控件而非 CSS 选择器每次有意义动作后对 UI 状态断言文本变化、toast、表格行、弹窗状态、URL 变化在.qa-frontend/runs/run-id/下截图读取页面的 error 级控制台消息与网络失败。证明优先的截图每张截图都要能证明其支撑的覆盖行截图前先确定能证明通过/失败的精确文本、控件、表格行、图表、toast 或表单状态等待该证明元素出现、必要时滚动入视口、带足上下文再截。长页面/落地页假设首屏只是背景必须滚动到改动区域截后必须检查文件证明被裁掉、被横幅遮挡、太小或满是导航框架就要重截。控制台与网络信号分流收集页面初始加载的基线控制台快照改动动作后再对比——只有目标交互后出现或明确属于被测端点的错误才相关预先存在的第三方噪音且不影响改动流程可忽略。关键纪律把本地栈噪音与PR 引入错误区分开——打分任何控制台输出前先通过 phrocs MCP 查进程状态backend、frontend、以及错误暗示的进程如capture、feature-flags、temporal-worker、mcp。文档列出常见可折减模式capture系列进程停止时/decide等端点 502、posthog-node(CDP) 或temporal-worker宕机时 invocations/hog 流 500、feature-flags/flags-consumer停止时 404 等。折减错误必须在 run notes 与 PR 评论中显式说明All console errors traced to capture process being stopped on this machine静默吞掉输出会侵蚀报告可信度。可复现性一个重试是必须的候选问题必须通过一次可复现重试重置局部页面状态 → 重跑同一动作序列 → 捕获新证据 → 确认同样的预期-实际不匹配。若只失败一次而重试通过可再跑一次不报为确认发现但也不隐藏——单列INTERMITTENT覆盖行、保留首次失败证据、在 run notes 中描述观察。主题切换的正确姿势仓库主题由 kea 状态直接驱动 CSS 变量没有运行时darkclass 或data-theme/data-color-mode属性因此document.documentElement.classList.add(dark)、data-theme属性、window.getKeaContext()与单独emulateMedia({colorScheme:dark})都无效。正确做法是从已认证页面上下文 PATCH 用户的theme_mode;async () { const csrf document.cookie.match(/csrftoken([^;])/)?.[1] const r await fetch(/api/users/me/, { method: PATCH, headers: { Content-Type: application/json, X-CSRFToken: csrf }, body: JSON.stringify({ theme_mode: dark }), // or light / system }) return { status: r.status, theme_mode: (await r.json()).theme_mode } }用getComputedStyle(document.body).backgroundColor验证生效dark 约rgb(19, 19, 22)light 约rgb(243, 244, 240)跑完恢复原theme_mode通常为light。数据播种与 feature flag 覆盖数据播种diff 行为依赖的数据形态如显示 X 计数在全新本地栈不存在时需要播种最小数据。Postgres 端surveys、dashboards、cohorts 等 app 模型通过flox activate -- bash -c uv run python manage.py shell PY ... PY走 Django ORM 保持模型不变量ClickHouse 端events、person properties、session recordings、LLM spans优先用posthog/test/与posthog/clickhouse/下的工厂工具只有无工厂覆盖时才裸写INSERT INTO ... VALUES (...)。纪律种最小集合、加可识别标记、播种后重载 scene 断言 UI 反映数据、在 run notes 与 PR 评论What was tested行注明默认不删除播种行。feature flag 覆盖flag 门控的新 UI 若种子用户未开启从已认证页面上下文调用posthog.featureFlags.overrideFeatureFlags({ flags: { my-flag-key: true } })多元 flag 传变体名清除传false导航后验证门控 UI 出现循环结束清除覆盖。证据命名与标注证据统一存放于.qa-frontend/runs/run-id/且保持未提交采用稳定可读命名.qa-frontend/runs/run-id/001-login.png .qa-frontend/runs/run-id/011-save-click-failure.png .qa-frontend/runs/run-id/011-save-click-failure.annotated.png .qa-frontend/runs/run-id/frontend-qa.webp .qa-frontend/runs/run-id/console-errors.json关键帧用 .agents/skills/qa-frontend/scripts/annotate-evidence.py 标注截图下方加说明条步骤说明 PASS/FAIL/INFO chip发现加高亮框圈住关键元素。高亮框坐标来自getBoundingClientRect()CSS 像素配合--viewport-width适配 HiDPIuv run python skill_dir/scripts/annotate-evidence.py annotate \ --input $RUN_DIR/011-save-click-failure.png \ --caption Clicked Save - no toast, no network call \ --step 3 --status fail \ --highlight 840,220,320,88 --viewport-width 1280由于浏览器通过元素引用驱动截图里永远没有可见光标——交互帧用--click X,Y绘制带点击环的光标--click用于交互、--highlight用于结果区域两者同一元素是冗余。该脚本仅依赖仓库已有的 Pillow 依赖通过uv run python从可信 checkout而非 PR checkoutuv run会解析该树依赖运行不得安装新包或用ffmpeg。演示动画与录制演示WebP 演示卷捕获两张以上截图后取 2-5 个标注关键帧拼接为慢速动画 WebPanimate子命令--frame path:msWebP 在 1200px 宽度限制、混合高度补边下 3-5 帧通常远低于 200 KB。每个状态变化帧前必须由前一帧的--click标记解释原因发现帧给更多屏显时间上传前先检查可读性模糊则回退到静态 PNG。录制的演示通行默认视频输出QA 循环稳定后默认补跑一次演示通行——开启录制并用 .agents/skills/qa-frontend/scripts/cursor-overlay.js 注入可见光标暴露window.__qaCursor.glide/ripple/caption纯视觉层pointer-events: none每次导航后须重注入整段流程作为一个连续批次脚本化以避免镜头间死区随后用annotate-evidence.py video将 WebM 转码为 H.264 MP4--trim-start采用 ffmpeg 输出 seek 以保证帧精确绝不用输入 seek。跳过条件只有三种且必须记录设置了NO_VIDEO、浏览器工具无法录制、ffmpeg缺失。发布前用ffmpeg -vf fps1,scale420:-1,tile5x2渲染帧联系表核验字幕与动作。注意 GitHub 对 raw-hosted 视频只提供下载链接不渲染播放器——MP4 只能从本地报告链接PR 模式下经hogli pr:upload-video上传后给出下载链接。修复循环刻意收窄的自主修复.agents/skills/qa-frontend/SKILL.md 的 Fix Loop 章节强调自主修复刻意收窄report-only不编辑ask每次修复前询问auto-low-risk只在全部护栏内应用。期望不明、修复主要是回退 PR 自身改动、或修复需要产品意图时改为报告而非编辑。修复护栏编辑前阅读相关改动文件与邻近源码用栈轨迹、控制台消息与路由映射选择最小修复不浏览无关区域禁止自主编辑auth、权限、SQL/HogQL 构造、迁移、workflow 文件、skill 文件——这些发现路由到 comment-only修复只能触碰 PR 原始文件列表PR 模式或改动文件集本地模式内的文件越界即回退修复并转 comment-only修复与 PR 自身 hunk 重叠超 50% 行时回退并转 comment-only修复后重跑确切失败的 MCP 序列自信修复的标准原失败步骤成功 受影响页面无新 error 级控制台消息 无护栏触发。提交纪律PR 模式中自信修复可本地提交但暂不推送。只按精确路径暂存修复文件禁用git add -A、git add .、git commit -a——本技能合入前创建的 PR 分支上.qa-frontend/未加入 gitignore批量添加会把本地栈截图带进修复提交并随 push 发布绕过证据上传门禁git add exact files changed by the fix git diff --cached --name-only # only the intended product files, nothing under .qa-frontend/ git commit -m fix(scope): finding-derived description使用 conventional commit消息公开安全且不含归属信息。每次调用外层循环上限 3 个自信修复提交之后发现的发现一律 comment-only。修复验证失败立即回退把发现作为建议补丁留在最终评论中。本地模式默认ask批准的编辑保持未暂存仅报告改动文件与验证结果。证据、裁决工件与输出渲染.agents/skills/qa-frontend/references/evidence-and-output.md 规定 QA 循环结束后、渲染任何面向用户内容之前的行为。证据上传仅 PR 模式上传可选且必须显式批准。使用仓库自带上传器hogli pr:upload-imagepng/jpg/gif/webp上限 10 MB含动画 WebP与hogli pr:upload-videomp4/webm同样 10 MB 与--yes门禁。上传是公开且永久的先向用户展示精确上传清单并请求批准只选面向人的证据frontend-qa.webp与 1-3 张匹配发现/叙述的标注截图不传.md快照、console.log或每张编号截图。首次不带--yes运行只打印警告不传任何内容。上传命令从可信树运行绝不在 PR checkout 中运行./bin/hogli会执行 PR 代码失败不阻塞运行注明evidence captured locally; upload failed or was skipped即可。必需工件每次运行在渲染任何内容前写两个工件.qa-frontend/runs/run-id/findings.json——结构化发现数组PR 评论与本地报告都是它的渲染stdout 首行QA-VERDICT: verdict供外部编排器 grepQA-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模式{ 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 }coverage_gap与needs_intent条目必须作为 PR 评论测试计划表格的可见行而非页脚注。整个运行过程中要把每项 setup 事实栈选择、工作区与登录、org/plan 状态、创建/播种的数据、flag/主题覆盖、退化进程追加到.qa-frontend/runs/run-id/run-notes.md——报告必需的 Setup 节由它渲染。PR 评论与本地报告渲染前必须重读 .agents/skills/qa-frontend/references/pr-comment-template.md。模板结构为首行## PostHog QA Frontend Report→ 裁决行PASS/FIXED/FAIL/NEEDS-INTENT/REPORT-ONLY含通过数、耗时与被测 commit→ 一行 blockquote TL;DR → Coverage 表 → Setup 节 →可选Effort saved → 发现节。发现体按顺序含六个块标题、severity 条████████░░ HIGH/█████░░░░░ MEDIUM/██░░░░░░░░ LOW、文件与组件引用、Fix diff、Failing stepurl/action/expected/got、Evidence。clean 运行也要发一条评论fork/纯评论运行裁决REPORT-ONLY并附reasontoken。长度预算约 10k 字符超 55k 时保留 banner、裁决行、Coverage 表与发现表并截断单发现复现细节。发布前清洗bearer token、query-string token、cookie、CSRF 值、秘密样键、凭据标签附近的长编码值从被测应用取来的 UI 字符串要剥离反引号与控制字符、截断超长值防止恶意字符串闭合代码围栏注入 markdown所有输出禁用 em dash—改用普通连字符。本地模式使用同一模板但省略上传步骤、证据仅以相对报告文件的本地路径引用before内联渲染、demo reel可点击不调用gh api/gh pr comment/任何 push。可视改动或自动修复循环落地时用 HTML table 渲染 Before/After 并排对比且必须同视口、同 scene、同滚动位置、同数据形态。推送批准门禁仅 PR 模式、同仓库 PR、至少一个自信修复提交时触发AUTO_PUSH_FIXES已设置则直接推送自动推送同时隐含批准修复摘要评论——绝不推送没有披露修复的评论否则询问用户Apply fix commit(s) to the PR branch? (y/n)。推送永远是非 force 的按分支名而非HEAD推送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非快进拒绝意味着远程在运行期间被移动不重试、不 fetch-and-force报告说明本地存在未推送的修复提交。运行身份与清理运行目录运行开始、捕获日志或证据前一次性创建运行目录RUN_IDlocal-$(date %Y%m%d-%H%M%S) # local mode PR_NUMBER$(gh pr view $PR_REF --json number --jq .number) # PR mode: resolve the RUN_IDpr${PR_NUMBER}-$(date %Y%m%d-%H%M%S) # number from any PR ref RUN_DIR.qa-frontend/runs/$RUN_ID mkdir -p $RUN_DIR$RUN_DIR已存在时追加短后缀如-2或短 head SHA它承载每张截图、GIF、日志、findings.json、run notes 与报告路径。清理规则.agents/skills/qa-frontend/references/cleanup.md 在报告写完、任何已批准的 PR 评论/上传/推送处理完成后加载也适用于每次提前退出——checkout 发生、浏览器会话打开或生成式本地配置出现后的任何中止路径都必须执行清理。具体规则Checkout切分支前先移除 Agent 生成的本地配置 hunk已修改的跟踪文件会跨git checkout悄悄落到开发者自己的分支上PR 模式总是尝试git checkout $original_branchdetached HEAD 时用 preflight 记录的 SHA绝不空参保留运行目录供调试但注意.qa-frontend/未 gitignore 时它会弄脏树阻塞下一次 PR 模式的 clean-tree 门禁——移出仓库如$TMPDIR/qa-frontend-runs/并告知用户确认git status --porcelain干净未推送的本地修复提交用git log pr-branch --not origin/pr-branch列出并在报告中提及。Overrides若设置了主题或 feature flag 覆盖关闭浏览器会话前恢复theme 回原值、overrideFeatureFlags(false)。Browser Session报告写完后结束浏览器自动化会话close-page/context/browser/end-session防止陈旧 Chromium 阻塞后续 QA不关闭用户可见的浏览器窗口陈旧 headless 进程需先获批准再杀仅针对 Agent 启动的进程命令行标记如ms-playwright、mcp-chrome-、remote-debugging-pipe、playwright-mcp。StackSTACK_STARTED_BY_AGENT1时只停 Agent 启动的栈如bin/hogli down -y用户自己启动的栈未经明确批准不得停。Generated Local Fileshogli自动向hogli.yaml添加本地phrocs命令时清理只移除该生成 hunk不将其作为 QA 运行的一部分提交。与内置 /run 和 /verify 的关系SKILL.md 明确指出Claude Code 自带的/run与/verify技能与本技能是组合而非竞争关系栈启动与登录委托给仓库的run-posthog项目技能内置/run发现的同一个本地模式是验证的前端分支——当/verify面向本仓库前端改动时以本地模式运行qa-frontend就是验证本身而非替代品。.agents/skills/run-posthog/SKILL.md 的启动路径hogli dev:setup→hogli up -d -y→hogli services:ready -y→hogli wait -y正是 qa-frontend 复用栈的核心来源。结语一条从 diff 到证据的完整 QA 闭环qa-frontend技能把前端改动要浏览器里跑过才算数这一原则落地为一套可执行协议模式选择PR/本地→ 安全门禁干净树、不可信代码、fork 规则、上传公开性→ 栈就绪与登录 → 行为驱动用例设计oracle 独立于 diff→ 浏览器 MCP 执行快照、控制台分流、可复现重试、主题/flag/数据准备→ 证据标注与演示卷/视频 → 收窄修复循环 → 裁决工件与模板化输出 → 推送门禁与清理。其精髓在于diff 只是证据不是规格PASS 必须来自独立 oracle每个结论都要有浏览器证据兜底每次修复都要能通过重试验证。这套方法论对任何需要在真实浏览器中验证前端改动的工程团队都具有直接的借鉴价值。【免费下载链接】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），仅供参考