Langfuse 前端浏览器审查工作流：面向 AI Agent 的用户可见变更验收与回归检查-开发者社区

Langfuse 前端浏览器审查工作流：面向 AI Agent 的用户可见变更验收与回归检查

【免费下载链接】langfuse🪢 Open source AI engineering platform: LLM evals, observability, metrics, prompt management, playground, datasets. Integrates with OpenTelemetry, LangChain, OpenAI SDK, LiteLLM, and more. 🍊YC W23项目地址: https://gitcode.com/GitHub_Trending/la/langfuse

本指南完整解读 Langfuse 仓库中frontend-browser-review技能：当一次改动影响用户在浏览器中看到或操作的内容时，如何通过浏览器自动化（Cursor Cloud 计算机使用或 Playwright MCP）驱动真实页面完成验收、回归检查与最终签署（signoff）。读完本文，你将掌握该工作流的触发条件、测试数据预填充、七步审查循环、输出期望与人工交接约定，并能结合仓库源码理解每一步背后的命令与实现。

技能定位：什么算"用户可见的前端变更"

该技能被设计为 Langfuse 前端改动签署前共享的浏览器审查流程。它的使用场景非常明确：当变更影响 UI 行为、布局、样式、导航或浏览器可见的回归，且需要在签署（signoff）前用可用的浏览器自动化进行确认时，就应使用此技能。仓库web/AGENTS.md也将其列为前端功能开发流程的一环："在签署前，使用 Playwright MCP 服务器在真实浏览器中审查受影响的用户流程"。

具体而言，需要驱动浏览器审查的情形包括：

导航或页面流程的变更，或任何跨步骤携带状态的改动；
布局或响应式行为，可能在未知方式下发生回流（reflow）的改动；
缺陷修复，且失败模式是在浏览器中可见的；
对大量用户可见工作的最终签署。

核心判断标准是"结果不确定"——当你无法可靠预测改动的视觉效果时，就需要真实浏览器验证。

何时改用人工交接：小改动的"两步交接"约定

技能明确反对对一切改动一律执行自动化。对于小型、自包含、你有信心的视觉改动，不需要自动化通过：间距调整、颜色 token、标签文本、图标替换这类改动，正确的做法是：

明确说明——告诉开发者你改了什么、以及你没有检查什么及原因，让选择透明可见，便于对方推翻；
趁人在场时交接——交接（handoff）是转交动作，不是结束回合的方式。如果旁边没有人能查看，而改动又是用户可见的，那就自己检查。

交接时交付的具体信息包括：改动的精确 URL（本地端口或 PR 预览地址pr-<N>.preview.langfuse.com），让开发者自己花两秒钟查看；一张截图放在 PR 中即可充当证据。这条约定背后是效率权衡：让开发者确认一个你本就知道的结果，等待成本高于他们亲自查看的成本。

审查前先预填充测试数据：seed CLI

大多数流程只有面对有意义的真实数据才可审查。打开浏览器之前，需要用 seed CLI 预填充流程所需的数据——仓库seed-test-data技能维护了一张"需求→命令"对照表，SKILL 中给出的是浏览器审查最常用的四类场景：

# 复杂观测树（v3 + v4 事件） pnpm run seed -- trace-tree --observations 5000 --v4 # 重负载会话视图 pnpm run seed -- long-session --traces 300 # 列表/筛选性能 pnpm run seed -- many-traces --count 100000 # 栈行为异常时先跑诊断 pnpm run seed -- doctor

几个关键约定：

每次运行都会打印 UI 深链（deep links）——打开这些链接而不是手动导航；
禁止手写 seed 脚本或裸 ClickHouse 插入——seed CLI 统一处理环境加载、预检、ClickHouse/Postgres 写入、回读校验，并输出机器可读的 JSON 摘要（最后一行 stdout）；
--dry-run可预测写入量而不落数据，--json抑制进度日志；
默认--seed为 42，确定性生成：相同种子与参数产生相同 id，时间戳锚定当前 UTC 日。

从源码看，seed CLI 位于packages/shared/scripts/seeder/目录：cli.ts是入口引导（在导入src/server前预检环境变量），doctor.ts实现栈检查（Postgres、迁移、项目、ClickHouse 及其表与内存压力、Redis、MinIO、web 应用），每个失败项都附带精确的修复命令。所有场景都做 ClickHouseuniqExact回读校验，任何键不符即非零退出。设计动机记录在packages/shared/scripts/seeder/README.md：编码 Agent 和开发者都曾被临时 ts-node 脚本和 Docker/ClickHouse 调试循环所困，CLI 将其收敛为一行命令，并保证种子数据具备瀑布式时间包含、真实 prompt 外键、确定性重跑等"像生产数据一样"的完整性。

七步审查循环

技能规定了标准审查循环，从启动应用到产出结论共七步：

优先使用现成的 Cursor Cloud Compose 应用；否则用pnpm run dev:web启动应用（若本地已有服务在跑则跳过）；
安装 Chromium：若机器尚未配置 Playwright，运行pnpm run playwright:install；
打开主要变更流程：使用 Cursor 计算机使用或 Playwright MCP 服务器打开受影响的流程，当流程需要种子数据时使用 seed CLI 的深链；
演练主路径：走一遍该变更影响的主要 happy path；
检查明显的视觉回归，具体清单包括：
- 布局或间距破坏；
- banner 重叠或视口锚定问题；
- 缺失的加载态、空态或错误态；
- 窄宽度下的响应式行为破坏；
页面实质变化时对照验证：检查最终 UI 状态，并与任务预期行为或现有模式对比；
会话失败排查：Playwright MCP 会话失败时检查/tmp/playwright-mcp；Cursor Cloud 下检查运行的浏览器产物与 Compose 日志。

启动与安装命令的仓库依据

上述命令直接映射到仓库脚本。根目录package.json定义：

pnpm run dev:web→turbo run dev --filter=web，即经 Turborepo 启动 web 包；
pnpm run playwright:install→pnpm --filter web exec playwright install chromium。

web包自身在web/package.json提供dev（dotenv -e ../.env -- next dev）、test:e2e（dotenv -e ../.env.test -e ../.env -- playwright test）等脚本。Playwright 配置见web/playwright.config.ts：baseURL 为http://localhost:3000，测试超时 180s、断言超时 60s、点击/填充超时 10s，截图仅在失败时保留、trace 在失败时保留；webServer在 CI 下用npm run start、本地用npm run dev，本地允许复用已有服务（reuseExistingServer: !process.env.CI）——这正是循环第 1 步"已有本地服务则跳过启动"的配置来源。

浏览器驱动方式的仓库依据

web/AGENTS.md的 "Agent browser loop" 与 "Quick Commands" 两个小节与该技能互为补充：本地 Agent 环境使用工作区playwrightMCP 服务器（来自.mcp.json、.cursor/mcp.json或.vscode/mcp.json），浏览器会话失败时检查/tmp/playwright-mcp下的 trace 与产物。注意web/AGENTS.md还记录了 E2E 与单测共享同一端口的坑：服务端测试需要 web 服务器服务于测试数据库（通过web/vitest.config.mts加载../.env.test），而pnpm run dev:web只加载.env——两者指向不同数据库，直接混用会导致测试创建的数据"找不到"。审查工作流之所以单独使用dev:web加 seed CLI，正是为了在隔离的演示数据上验证。

输出期望：五要素报告

审查结束后，报告必须包含五个要素，逐条对应技能原文：

审查了哪个流程；
主流程是否工作正常；
任何可见回归或后续风险；
若审查被阻塞——精确说明是什么阻止了浏览器验证；
人工交接场景：预览或沙箱 URL 加上精确的点击路径步骤，以及发布在 PR 上的修复证据（截图、短视频或前后对比）——而不是一长段仅供 Agent 阅读的说明，也不只是聊天里的几句话。

第五点的意图很关键：交接给人类时，证据必须沉淀到 PR 上，让评审者在异步协作中直接看到修复结果，而不是依赖对话记录。

范围边界：补充而非替代

技能在 Scope Notes 中划定了三条边界，避免被误用为通用前端编码指南：

该技能补充而非替代定向测试与 lint——它是浏览器签署工作流，不负责编码质量把关；
实现细节遵循web/AGENTS.md与各包级技能——例如前端大特性架构（frontend-large-feature-architecture）、React effect 审计（refactor-react-effects）、组件 Story 规范（storybook）等；
作为浏览器签署（browser-signoff）工作流使用，不要当作通用前端编码指南。

从仓库整体视角看，该技能是 Langfuse 前端质量闭环中的一环：web/AGENTS.md将其列入 "Package-Local Skills" 并声明"在实质性前端重构前先读这些技能"，同时前端功能开发 Playbook 的第 5 步明确要求"签署前用 Playwright MCP 在真实浏览器中审查受影响用户流程"。也就是说，浏览器审查不是可选项，而是进入签署阶段的必经关口——而本文所述的预填充数据、七步循环与五要素报告，正是这一关口被可靠、可复现地执行的标准方法。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考