PostHog 前端 QA 实战指南开发堆栈就绪检查Stack Readiness与登录Login流程【免费下载链接】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技能链的核心参考文档 stack-and-login.md 为骨架系统讲解在进行浏览器前端 QABrowser QA前如何判断本地 PostHog 开发堆栈是否可用、何时以及如何启动堆栈以及如何安全地登录测试账号与准备隔离测试工作区。读完本篇你将掌握一整套可复制的堆栈复用 → 健康检查 → 审批启动 → 登录鉴权流程并理解其背后的仓库源码与安全边界可直接应用于 PR 模式与本地模式的 PostHog 前端回归验证。背景stack-and-login 在 QA 流程中的角色PostHog 仓库在 .agents/skills/qa-frontend/SKILL.md 中定义了一套完整的仓库内前端 QA 技能/qa-frontend它运行在一个有界的前端 QA 循环里支持两种模式PR 模式用户提供 PR 引用URL、编号或分支技能检出 PR 后执行 QA经批准后上传证据并发布 PR 评论要求工作树干净。本地模式针对当前检出内容与未提交改动进行 QA报告只写本地不上传、不评论、不推送允许脏工作树。无论哪种模式进入 Checkout、Diff 分析、浏览器执行之前都必须先通过堆栈就绪与登录这道门。这正是 stack-and-login.md 的职责它全权负责BASE_URL、STACK_STARTED_BY_AGENT、对仓库内run-posthog技能的委托、phrocs 进程检查、启动审批规则以及登录/测试工作区的处理。SKILL.md 明确要求Do not checkout, edit, upload, comment, or push until it confirms the local PostHog stack is reachable enough for the planned QA target——未通过就绪检查前一切后续动作都被禁止。一、堆栈就绪Stack Readiness1.1 环境变量基线BASE_URL 与 STACK_STARTED_BY_AGENT在开始任何检查之前先设置两个关键环境变量BASE_URL${BASE_URL:-http://localhost:8010} STACK_STARTED_BY_AGENT0BASE_URL是浏览器 QA 实际访问的入口。默认值http://localhost:8010是 PostHog 开发堆栈的 Envoy 风格代理地址它把/static/*反代到 Vite开发服务器实际运行在:8234其余流量反代给 Django因此浏览器始终浏览 8010 端口直接访问 Vite 的 8234 端口会因无索引路由而 404详见 .agents/skills/run-posthog/SKILL.md 的 Gotchas 一节。STACK_STARTED_BY_AGENT是一个归属标记只有当你Agent获得用户批准并实际启动了堆栈时才置为1其核心约束是只允许停止自己启动的那个堆栈且只能在清理阶段或获得用户批准后进行。1.2 核心原则复用用户现有堆栈文档强调的第一条原则是默认复用用户已有的环境不要因为你要跑 QA 就去启动、重启或替换开发堆栈。动作顺序是先检查BASE_URL处 PostHog 是否已经可达若可达直接继续不要启动、重启、替换或等待另一个堆栈若不可达再考虑启动流程见 1.5 启动审批。这一原则与 .agents/skills/qa-frontend/references/safety-rules.md 中的Local Stack Control章节一致BASE_URL已可达时禁止另起炉灶且启动、停止、重启本地 PostHog 开发堆栈本身属于必须获得当前会话内明确批准explicit approval的动作。1.3 模式差异PR 模式与本地模式的堆栈要求堆栈选择还取决于运行模式PR 模式优先让 PR 的代码在开发者机器之外执行——例如通过远程 devbox 提供BASE_URL转发端口仓库的setting-up-devbox技能覆盖了如何配置一个 devbox。因为 PR 模式会在本地堆栈上执行 PR 作者的代码Python 与 JavaScript等于以运行者权限运行他人的代码若要在开发者自己机器上跑 PR 代码必须取得 safety-rules.md 中描述的显式批准并明确告知这将在你的机器上执行 作者 的代码。本地模式测试的是开发者自己的代码没有上述门槛。另外仓库内还存在 git hook 风险PostHog 跟踪.husky/post-checkout、pre-commit、pre-push且core.hooksPath指向它们。因此 PR 模式检出时必须导出GIT_CONFIG_COUNT1 GIT_CONFIG_KEY_0core.hooksPath GIT_CONFIG_VALUE_0/dev/null防止检出时执行 PR 控制的 hook见 SKILL.md 的 Checkout 章节。当仓库内存在 .agents/skills/run-posthog/SKILL.md 时以它的当前就绪检查、phrocs 进程指引和setup_test/登录配方为唯一事实来源source of truthstack-and-login 参考文档只额外附加 QA 专属约束用户堆栈可用就复用、启动/重启 PostHog 前先询问、只停止自己启动的堆栈。1.4 可达性检查curl 探测与 phrocs MCP 进程检查对BASE_URL执行两条最小健康检查命令curl -sf --max-time 5 $BASE_URL/_health curl -sf --max-time 10 -o /dev/null -w %{http_code} $BASE_URL/第一条探测/_health端点-f让 HTTP 错误直接表现为命令失败--max-time 5限制超时为 5 秒第二条对根路径发起请求只输出 HTTP 状态码期望 200 或 302。若两条检查显示应用可达就直接继续不再折腾其他堆栈。若失败则使用可用的本地健康检查手段例如当 phrocs 已在运行时调用其 MCP 工具mcp__phrocs__get_process_status(processbackend)mcp__phrocs__get_process_status(processfrontend)在 .agents/skills/run-posthog/SKILL.md 中还有更完整的就绪条readiness barsbackend与frontend是 UI QA 的硬性门槛hard gates只有目标路由还需要mcp、feature-flags、nodejs、capture或ingestion等单元时才追加检查。对于 HogQL 支撑的场景insights、dashboards、web analytics以及POST /api/setup_test/...还额外要求migrate-clickhouse进程显示status:done exit_code:0。1.5 目标路由就绪比全栈健康更重要文档给出了一个关键判断可达不等于在服务你的检出内容。BASE_URL可能是转发到远程堆栈如 Coder devbox的地址而转发堆栈可能滞后于或偏离本地工作树。因此在开始针对 diff 的验证或变更状态登录、主题切换、种子数据之前必须确认堆栈确实在运行被测代码打开一个被改动过的界面、确认改动已呈现若堆栈同步有延迟则短暂重试。数据播种seeding也必须对准浏览器实际对话的那个堆栈——本地执行manage.py shell写的是本地数据库当BASE_URL转发到远程堆栈时这显然是错误的目标。播种应在提供BASE_URL的堆栈上进行否则就记录一个 coverage gap。对浏览器 QA 而言目标路由就绪是比本地全栈绿灯更强的证据改动后的 UI 能加载、分支/SHA 或其他 diff 内标记与在测代码一致、路由关键 API 可用。无关的降级单元记入run-notes.md即可不必为了一个可用目标路由去追逐全栈健康。1.6 启动流程与审批门槛当 PostHog 不可达时顺序如下先查用户记忆/设置与本地偏好再查仓库指引及AGENTS.md等邻近文档中推荐的启动方式在启动 PostHog 之前询问用户希望如何处理若目录与命令都很明确可以提出具体的启动路径建议包括是交互式还是后台运行但要明确标注这是待确认的推断若目录、命令、BASE_URL或启动方式不明确则直接询问用户希望在哪里、以何种方式运行堆栈或是否改用其他BASE_URL在聊天中提问并停止等待用户回答。沙箱升级提示、命令批准对话框或已被批准的指令前缀都不等于工作流批准——它们只在你选定 agent 托管启动后才授权某条命令执行。若用户批准 agent 托管启动则优先使用仓库常规的后台堆栈对新/已停止的 devbox 用hogli devbox:start --start-app对服务BASE_URL的检出目录用hogli up -d -y。hogli dev:*系列仅用于理解不清晰的路由依赖。运行已批准的启动路径并设置STACK_STARTED_BY_AGENT1。若命令因 shell 缺少仓库依赖或全局命令不在PATH上而失败遵循仓库对同一启动意图的指引例如仓库本地包装脚本或flox这类环境包装器并宣告这一回退。在切换检出、目录、启动模式、删除锁文件或启动不同堆栈之前再次询问。无头headlessAgent 会话中避免交互式终端 UI除非用户明确要求。只停止自己启动的堆栈且仅在清理阶段或用户批准后进行。启动之后重复run-posthog的应用可达性检查若该技能不可用则用 1.4 的最小检查并查询相关进程状态backend、frontend以及与改动表面直接相关的进程例如测试 MCP 改动时的mcp。只有应用可达且所需进程集就绪才允许继续backend 或 frontend 未就绪时必须在检出、编辑、上传、评论或推送之前停止。日志获取的优先级优先使用 phrocs MCP 日志——mcp__phrocs__get_process_logs(processbackend)与mcp__phrocs__get_process_logs(processfrontend)仅当 phrocs MCP 不可用时回退到仓库本地日志目录.posthog/.generated/logs/。二、登录Login2.1 两条登录路径setup_test 隔离工作区 vs 种子默认账号文档给出两条登录路径按需选择路径 A需要真实数据或隔离工作区时使用run-posthog的POST /api/setup_test/organization_with_team/配方。在浏览器页面上下文中调用它然后用返回的user_email与固定密码12345678从页面上下文登录构造路由时使用返回的team_id/project/{team_id}/...。文档强调这是前端 QA 的准备工作不是独立的后端/API 测试。路径 B不需要专用工作区时默认使用公开的 PostHog 本地开发种子账号testposthog.com/12345678。这两个凭据记录在 docs/published/handbook/engineering/manual-dev-setup.mdThe first time you run the app, you can log in with a test account: usertestposthog.compwd12345678由bin/start播种。它们只存在于以该方式播种的开发堆栈上笔记本堆栈或个人 devbox因此回退到它们是安全的。2.2 源码佐证setup_test 端点的实现与门槛setup_test端点的实现位于 posthog/api/playwright_setup.py它是一个仅接受POST的 DRF 视图permission_classes([AllowAny])通过test_name路由参数从posthog.test.playwright_setup_functions中注册的PLAYWRIGHT_SETUP_FUNCTIONS字典里选取对应的 setup 函数。关键安全门槛在第 20-28 行test_modes ( getattr(settings, TEST, False), getattr(settings, DEBUG, False), getattr(settings, CI, False), getattr(settings, E2E_TESTING, False), ) if not any(test_modes): raise Http404()即该端点仅在 TEST / DEBUG / CI / E2E_TESTING 任一模式下可用本地开发默认满足DEBUGTrue因此可用生产式配置下会直接 404。请求体经 pydanticinput_model校验后调用 setup 函数成功返回{success: True, test_name: ..., result: ...}异常则返回 500 与错误描述。这与 .agents/skills/run-posthog/SKILL.md 中Gated onDEBUGTrue | E2E_TESTING | CI | TEST的描述完全对应。run-posthog技能给出了完整的浏览器 MCP 配方.agents/skills/run-posthog/SKILL.md 的 Drive the UI for /verify 一节此处摘要关键步骤// 1. 在页面上下文中创建隔离工作区每次调用使用随机邮箱密码固定 12345678 const r await fetch(/api/setup_test/organization_with_team/, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ data: { skip_onboarding: true } }), }) const { result } await r.json() // result: { user_email, team_id, personal_api_key, organization_id, ... } // 2. 仍在页面上下文中执行登录保证 Django 的 CSRF 中间件拿到正确 cookie const r await fetch(/api/login/, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ email: workspace.user_email, password: 12345678 }), }) // 200 已登录403 不在页面上下文400 工作区并未真正创建该用户其中第二步必须在页面上下文中运行——直接curl -X POST /api/login/会因 CSRF 返回 403run-posthog的 Gotchas 明确记录会话登录必须在页面内执行使 cookie 与 CSRF token 正常流转非浏览器 API 调用则应改用setup_test返回的personal_api_key作为Authorization: Bearer keytoken 认证无 CSRF 问题。2.3 凭据来源与优先级qa-frontend技能在 Preconditions 阶段.agents/skills/qa-frontend/SKILL.md从$ARGUMENTS解析--login-username/--username与--login-password/--password到LOGIN_USERNAME/LOGIN_PASSWORD。解析之后若仍未设置再应用种子默认值LOGIN_USERNAME${LOGIN_USERNAME:-testposthog.com} LOGIN_PASSWORD${LOGIN_PASSWORD:-12345678}由此形成三种凭据来源按优先级排列chat 参数调用时显式传入的--login-username/--login-password环境变量shell 中已导出的LOGIN_USERNAME/LOGIN_PASSWORD种子默认值testposthog.com/12345678。文档特别说明不需要_OVERRIDE/_EFFECTIVE这类间接层而fork 规则fork-rule的运行完全忽略上述优先级一律只使用一次性throwaway凭据详见 safety-rules.md 的 Fork PRs 章节——因为 fork 的代码可能窃取密码、浏览器会话、CSRF token 或本地数据任何 fork PR 的浏览器 QA 都应假设密码与会话可能泄露。2.4 密码安全与用户可见输出两条铁律绝不打印密码对 chat 提供的凭据在面向用户的输出中只称login override provided已提供登录覆盖。LOGIN_PASSWORD不得打印、记录或包含进证据与评论SKILL.md Preconditions 同样重申Do not print, log, or includeLOGIN_PASSWORDin evidence or comments。2.5 浏览器 MCP 登录的五个步骤使用浏览器 MCP/工具时按如下顺序完成登录导航到$BASE_URL/login若使用setup_test先在页面内执行 run-posthog 的 setup 与登录 fetch再导航到返回team_id对应的路由否则用生效的登录值填写邮箱与密码提交表单等待登录后的 URL 匹配**/project/**——这是登录成功的关键信号因为 PostHog 登录成功后会跳转到项目作用域路由。2.6 登录失败的处理若登录失败或两个生效登录值任一缺失中止整个流程、恢复原分支、不发布 PR 评论——因为 QA 实际上没有运行发布评论会给出误导性结论。这与 SKILL.md 中Never print passwords or include credentials in evidence. If login fails, abort before posting a PR comment because QA did not run一致。三、常见故障与排查线索结合实际堆栈经验虽然 stack-and-login 文档本身聚焦就绪与登录仓库内 .agents/skills/run-posthog/SKILL.md 沉淀了与之直接相关的常见故障可作为登录/就绪失败时的排查地图migrate-clickhouse冷启动崩溃hogli up -d时与migrate-postgres并行启动存在竞态Postgres 未就绪时崩溃。这是POST /api/setup_test/...与 HogQL 场景的硬前置但不是/run的前置。修复序列等migrate-postgres显示status:done后重启崩溃的迁移单元mcp__phrocs__toggle_process是外科手术式工具但在共享堆栈上被 auto-mode 拦截时回退到phrocs stop hogli up -d全量重启或直接python manage.py migrate_clickhouse——需先set -a; source .env.services; set a使CLICKHOUSE_DATABASEposthog。POST /api/login/返回 400invalid_credentials你登录的用户并非setup_test工作区真正创建的用户通常是 ClickHouse 崩溃导致。检查 setup_test 调用的响应若其 500先修 ClickHouse。POST /api/setup_test/organization_with_team/返回 404DEBUG、E2E_TESTING、CI、TEST全部为假。本地开发默认DEBUGTrue若未设置通常是.env.local缺失或DJANGO_SETTINGS_MODULE指向了类生产配置。POST /api/setup_test/organization_with_team/返回 500Table posthog.person does not existmigrate-clickhouse启动时崩溃见第一条。页面内fetch(/api/login/)返回 403调用未发生在页面上下文例如用了page.request.post而非page.evaluate。必须用evaluate_script/browser_evaluate使调用源于页面内。hogli up -d报Another instance of bin/start is already running上一次运行未清理用 phrocs 状态确认无残留后删除bin/start.lock重试。浏览器控制台的 CSP 警告与 401登录前的正常现象——preflight/login 页面会尝试拉取/api/projects/current、/api/users/me/与 PostHog.js 远程配置在注册前均返回 401。四、流程总结一张就绪-登录决策表阶段判定条件动作设置基线无BASE_URL${BASE_URL:-http://localhost:8010}STACK_STARTED_BY_AGENT0复用检查curl/_health与/均成功直接继续不启动/重启/替换堆栈复用失败curl 失败用 phrocsget_process_statusbackend/frontend补充判断仍不可达进程检查未就绪查用户偏好 → 查仓库指引/AGENTS.md → 询问用户启动方式并等待答复获批启动用户批准运行hogli devbox:start --start-app或hogli up -d -ySTACK_STARTED_BY_AGENT1启动后复检重跑可达性 进程检查仅当应用可达且所需进程集就绪才继续否则在 checkout/编辑/评论/推送前停止登录路径 A需要隔离数据页面上下文调POST /api/setup_test/organization_with_team/用返回邮箱 12345678登录team_id构造路由登录路径 B无需隔离数据testposthog.com/12345678种子默认登录验证地址匹配**/project/**视为成功失败则中止、恢复分支、不发 PR 评论这套流程的核心设计思想可以概括为三点最小干预能复用就不新建、显式批准启动/重启/推送等高影响动作必须对话内确认、证据优先目标路由可用的局部证据优于全栈绿灯的粗粒度判断。对于任何需要在 PostHog 仓库上执行浏览器前端 QA 的开发者或 Agent先跑通堆栈就绪 → 登录这两步是后续所有测试用例设计、证据采集与报告产出的可靠前提。【免费下载链接】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），仅供参考