Langfuse 仓库 Agent 协作指南与工程工作流解析从 CLAUDE.md 看开源 LLM 平台的开发规范【免费下载链接】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/langfuseLangfuse 是开源的 LLM 工程平台用于开发、监控、评估和调试 AI 应用。本文以仓库根目录的 CLAUDE.md与 .agents/AGENTS.md 内容一致属于兼容性符号链接为核心骨架系统拆解 Langfuse 仓库的架构布局、核心开发命令、本地数据检查手段、种子数据 CLI、质量验证体系以及生成文件管理规范。读完本文你将掌握如何在该仓库中高效地安装依赖、启动开发环境、构造可复现的测试数据、跑通全套质量检查并理解这套面向 Agent 与人类工程师双服务对象的协作约定为何如此设计。一、文档定位CLAUDE.md 为何存在根目录 CLAUDE.md 不是一份普通的 README而是仓库的Agent 指南Agent Guidelines其开头即自述Langfuse 是一个用于开发、监控、评估和调试 AI 应用的开源 LLM 工程平台。值得特别注意的是它的文件组织机制见 Shared Agent Setup 章节.agents/AGENTS.md是唯一的权威根指南canonical root guide根目录的AGENTS.md是指向.agents/AGENTS.md的符号链接根目录的CLAUDE.md则是指向AGENTS.md的兼容性符号链接。这一机制由 scripts/agents/sync-agent-shims.mjs 实现该脚本会扫描仓库中所有包含AGENTS.md的目录为每个目录生成同级的CLAUDE.md符号链接让 Claude 在读取该目录内文件时能自动加载包级本地指南package-local guidance。同时脚本还会根据 .agents/config.json 生成.claude/settings.json、.mcp.json、.cursor/mcp.json、.vscode/mcp.json等各类工具链的配置文件。修改 skills 或 AGENTS.md 之后必须运行pnpm run agents:sync # 同步符号链接与生成配置 pnpm run agents:check # 校验同步结果含路径失效检查文档明确规定agent 指南只写进AGENTS.md绝不写进CLAUDE.md后者是被生成的符号链接并且指南应放在最窄的、拥有该主题的 AGENTS.md中以便只有在需要时才加载进上下文。这也是为什么 packages/shared/scripts/seeder/AGENTS.md、.agents/ARCHITECTURE_PRINCIPLES.md 等文件分散存在于树中的原因——它们各自只负责自己的领域。二、先识别服务对象外部贡献者与维护者CLAUDE.md 的第一个章节 Who You Are Working For 强调一个核心理念这个仓库服务两类人他们拿到的是仓库的两半工作前必须先判断清楚且绝不静默猜测never guess silently。判断依据不是面试而是配置读取~/.config/langfuse/me.md如果该文件不存在则由langfuse-onboardingskill位于 .agents/skills/langfuse-onboarding/第 1 步指明。在 Cursor Cloud 环境中判断依据是运行所有者cursor-cloudrun-info加团队名册而非gh api …permissions——因为 Cloud 的 GitHub token 是只读集成即使维护者也会报告push: false桌面端则仍使用gh api user再读取.permissions.push。两类对象的差异直接决定协作方式外部贡献者outside contributor拿到的是代码与 CONTRIBUTING.md——如何构建、检查要求是什么、如何发起 Pull Request。不涉及内部追踪器、手册或工作节奏因为他们无法打开这些内容。维护者maintainer除了上述内容还会得到一个承载组织上下文的助手。文档期望这个助手能回答我今天该做什么——依据来自追踪器而非记忆linear-work-rhythmskill了解团队其他成员的工作动态在设计某个界面之前提醒同事上周刚重构过该流程拿到一个链接追踪器工单、PR、Slack 链接、截图就能接手推进而不是反问该用哪个 skill主动、简短地提示组织层面逾期的事项未写的更新、挂在Merged却无文档决策的 issue、已悄然过期的项目目标日期主动提出实现方案而不是被动等待指令。此外文档给出了一条重要的沟通准则保持简短Keep it short——维护者通常正在处理任务一段需要跳读的段落还不如两句能被读完的话。三、仓库架构与依赖方向CLAUDE.md 用一棵目录树概括了仓库的顶层结构这是理解整个代码库的起点langfuse/ |- web/ # Next.js app (UI tRPC public REST) |- worker/ # Queue consumers and background processing |- packages/shared/ # Shared domain, DB, queue contracts, repositories |- ee/ # Enterprise package consumed by web |- generated/ # Generated API clients (do not hand-edit) |- fern/ # API definition sources - scripts/ # Repo scripts其中generated/目录在当前仓库中未包含属于生成物见后文其余目录均为实际存在。各包之间的依赖方向是单向且严格受控的web→langfuse/shared、langfuse/eeworker→langfuse/sharedlangfuse/ee→langfuse/sharedlangfuse/shared→ 不导入web、worker或ee中的任何内容这意味着packages/shared是整个依赖图的最底层所有跨包复用逻辑都必须下沉到它内部。文档还标注了几个高信号的共享入口点队列契约队列 payload 的 schema 与队列名契约由 packages/shared/src/server/queues.ts 统一持有领域模型packages/shared/src/domain/下的observations.ts、traces.ts、scores.tsPostgres schemapackages/shared/prisma/schema.prismaClickHouse 迁移模板位于 packages/shared/clickhouse/migrations/含 90 个 SQL 迁移文件。更深层的设计意图记录在 .agents/ARCHITECTURE_PRINCIPLES.mdUnderlying Architecture Principles它明确 Langfuse 的架构应面向大规模、探索式的可观测性基于宽结构化事件数据将 observation 作为首要分析单元trace 只是关联 observation 的相关句柄偏好宽事件wide, richly attributed events而不是碎片化的 metrics/logs/traces保留高基数上下文让用户能按任意维度切片、分组、过滤和调试未知问题倾向不可变/追加式事件记录避免读时去重带来的隐藏查询成本围绕列式访问模式设计存储与查询路径窄字段选择、时间受限扫描、有效排序键、数据剪枝API 契约需要具备规模感知必要时强制时间窗口、暴露字段选择、使用游标分页避免默认扫描全量历史。这些原则为实际编写代码时的取舍是否新增 join、是否新增指标、是否读取大字段提供了决策框架。四、核心开发命令安装、开发与测试CLAUDE.md 的 Core Commands 章节给出了一套以 pnpm turbo 为底座的标准工作流实测命令均与根目录 package.json 中的 scripts 一致用途命令安装依赖pnpm install全量开发所有包pnpm run dev仅开发 webpnpm run dev:web仅开发 workerpnpm run dev:worker全量 Lintpnpm run lint全量类型检查pnpm run typecheck/pnpm tc构建检查pnpm run build:check完整构建pnpm run build安装 Playwright Chromiumpnpm run playwright:install运行单个测试文件是日常开发中最常用的操作。vitest 按文件名参数过滤且不同包有各自的过滤命令web 服务端测试pnpm --filter web run test fileweb 客户端测试pnpm --filter web run test-client fileworker 测试pnpm --filter worker run test fileshared 测试pnpm --filter langfuse/shared run test file这与仓库的测试命名约定呼应web 下既有*.servertest.ts如web/src/__e2e__/api.servertest.ts也有*.clienttest.ts/*.clienttest.tsx如web/src/utils/numbers.clienttest.ts而 worker 使用*.test.ts如worker/src/__tests__/evalService.test.ts。另外两条工具链约定值得注意不要通过./node_modules/.bin/*调用 Node 安装的二进制一律经由pnpm运行在 shell 命令中始终为文件路径加引号或对路径密集的命令使用noglob以避免 zsh 通配符展开在处理动态 Next.js 路由时出问题不要新增或扩大 ESLint disable 注释或配置覆盖除非用户明确批准具体规则与范围。五、本地开发环境与数据检查开发基础设施由 docker-compose.dev.yml 定义。它实际编排了五个服务每个都带健康检查与可覆盖的端口/凭据变量服务镜像默认端口绑定 HOST_IP默认 127.0.0.1默认凭据ClickHouseclickhouse/clickhouse-server:25.12HTTP 8123 / Native 9000用户clickhouse/ 密码clickhousePostgrespostgres:175432用户/密码/库均为postgresRedisredis:7.2.46379密码myredissecret--requirepassmaxmemory-policy noevictionMinIOchainguard/minioAPI 9090 / 控制台 9091minio/miniosecretflociworker-tests profilefloci/floci:1.5.17-compat4566—其中 ClickHouse 25.12 是 Langfuse v4 的最低版本events 表依赖 25.x 的全文索引/enable_full_text_index所有开发与 CI 部署模式都锁定同一版本。启动/停止命令在根 package.json 中也有对应脚本pnpm run infra:dev:updocker compose -f ./docker-compose.dev.yml up -d --wait与pnpm run infra:dev:down。CLAUDE.md 的 Local Data Inspection 章节给出了直接连接本地数据库做只读检查的三个命令支持${VAR:-default}形式的变量覆盖用于理解既有测试数据# Postgres PGPASSWORD${POSTGRES_PASSWORD:-postgres} psql -h ${HOST_IP:-127.0.0.1} -p ${POSTGRES_HOST_PORT:-5432} -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-postgres} # ClickHouse clickhouse client --host ${HOST_IP:-127.0.0.1} --port ${CLICKHOUSE_NATIVE_PORT:-9000} --user ${CLICKHOUSE_USER:-clickhouse} --password ${CLICKHOUSE_PASSWORD:-clickhouse} --database default # Redis REDISCLI_AUTH${REDIS_AUTH:-myredissecret} redis-cli -h ${HOST_IP:-127.0.0.1} -p ${REDIS_HOST_PORT:-6379}如果连接失败应检查 docker-compose.dev.yml 中的本地覆盖变量并确认服务在运行。文档同时强调优先只读查询需要构造前端测试状态时继续使用种子 CLI 而非临时插入。六、种子数据 CLI用pnpm run seed构造可复现测试数据这是仓库最有特色的工程实践之一。CLAUDE.md 规定用种子 CLI 预填本地测试数据pnpm run seed -- list列出场景运行结果会打印 UI 深链接绝不使用临时脚本或裸 ClickHouse 插入。packages/shared/scripts/seeder/AGENTS.md 对这套 CLI 做了完整展开入口是 cli.ts对应 shared 包的seed:scenario脚本配套 doctor.ts栈健康检查并打印修复命令、seed-postgres.ts、seed-clickhouse.ts 以及scenarios/目录每个场景一个文件共享rng.ts、payload.ts、event-mirror.ts、verify.ts。常用场景命令示例均带--v4走 v4 events 路径pnpm run seed -- doctor # 检查开发栈逐条打印失败项的修复命令 pnpm run seed -- list # 列出所有场景与参数--json 输出机器可读结果 pnpm run seed -- trace-tree --observations 5000 --breadth 500 --v4 pnpm run seed -- deep-chain --v4 # 单链 1401 个顺序 generation布局压力测试 pnpm run seed -- agent-graph --v4 # 图密集 trace350 个 observation 产生约 1350 条节点连接 pnpm run seed -- timeline-shapes --v4 # 一打小 trace每种时间线形态一个重试退避、人工等待、扇出、慢工具、in-flight… pnpm run seed -- many-traces --count 100000 --days 14 pnpm run seed -- outlier-traffic --days 90 # 带成本/延迟/token 离群点的昼夜流量 pnpm run seed -- session-shapes --shape media # 携带 langfuseMedia:... 引用的消息需要 MinIO每次运行的最后一行 stdout 是一个 JSON 摘要包含traceIds、sessionIds、counts、verifiedClickHouse 回读校验和linksUI 深链接--dry-run可只预测数量不写数据--json抑制进度输出。该指南还规定了种子场景的工程约束属于可验证的实现事实场景名、flag 名、JSON 摘要键是公开契约只能增量演进不得重命名或删除场景必须确定性随机性取自Rng由--seed播种id 由--id-prefix派生绝不调用Math.random落入 ClickHouse ORDER BY 键的值时间戳、v3 的type、events 的start_time不能来自顺序随机流或墙钟须用utcDayStartMs()锚定时间、用无状态的jitter(seed, index, max)做逐行变化否则无关 flag 改变随机流消耗位置会导致重跑时静默重复行每个场景用 ClickHouse 回读验证写入并大声报错不允许客户数据、机密或需要模型提供商密钥的 fixture。如果某个 bug 依赖特定数据形态文档的建议是先问pnpm run seed能否在本地预填该形态不能则考虑扩展种子场景并说明为何 seed 无法表达。七、质量验证体系证据优先检查必须真实执行CLAUDE.md 的 Verification 章节确立了一套按风险分层、以证据收尾的验证文化每项检查都要引用其摘要行如 turbo 的Tasks: 8 successful, 8 total或 vitest 的Tests 12 passed (12)说明跳过了哪些检查及原因绝不把未经验证的工作报告为完成也绝不以未完成状态收尾。按变更范围的检查矩阵web/**pnpm run lint 定向 web 测试worker/**pnpm run lint 定向 worker 测试packages/shared/**非 schemapnpm run lint 一个定向 web 检查 一个定向 worker 检查packages/shared/prisma/**或packages/shared/clickhouse/**pnpm run lintpnpm run db:generate 定向 web/worker 回归公共 API 契约web/src/pages/api/public/、web/src/features/public-api/types/ 或 fern/apis/pnpm run lint 定向服务端 API 测试 Fern 更新/重新生成 pnpm run openapi:check跨包重构pnpm run lintpnpm run typecheck 受影响包的定向测试。几个关键的陷阱提醒这些是其他项目很少写明的实操经验通过不代表执行过lint和typecheck是 turbo 缓存任务且 worktree 共享同一份缓存通过结果可能只是另一分支的重放。必须同时引用Cached:行要强制真实执行用pnpm exec turbo run lint --force--no-cache只停止写入不强制执行。warning 即失败web、worker、packages/shared、ee四个包都以--max-warnings 0运行 eslint一个 warning 就会让分支失败。langfuse/shared解析的是构建后的dist根pnpm run typecheck会通过 turbo 的typecheck.dependsOn含^build自动先构建 shared但pnpm --filterweb run typecheck不会。在 worktree 间切换分支后必须执行pnpm --filtershared run db:generate pnpm --filtershared run build否则 typecheck 会基于上一个分支的源码报告。knip 是必需检查pnpm exec knip是 CI 的pipeline.yml中必需的一步但它没有对应的 package.json script极易只在本地漏跑web/**、packages/shared/**、worker/**下未使用的文件和导出都会导致其失败。没有检查会真正加载页面渲染变更只有在有人真正看过之后才算验证。只有当你确实不确定时才驱动浏览器可能回流布局、携带状态的流程、无法预判的交互小改动且信心高时给出 URL 让开发者自己扫一眼更快。关键原则是提供不等于推诿静默跳过才是——要明确说出你没检查什么。客户端 bundle 健全性CI 对每个生产 web 构建运行pnpm run scan:client-bundle见 scripts/scan-client-bundle.mjs扫描被压缩器删除的绑定SWC dropped-binding 类会以运行时ReferenceError形态出现dev 构建和类型检查都发现不了以及泄漏进浏览器 chunk 的 Node 全局裸require、process、Buffer等。失败时脚本头部的注释会说明规范修复方式。测试策略测试的价值在于钉住没人注意就可能回归的行为如果唯一可断言的只是复述 diff 本身间距值就是那个值、标签就是那个文本这个测试就没有意义应当跳过并一句话说明原因。bug 修复需要测试时先写最小的失败测试并确认它在修复前的行为上确实失败再改生产代码新的测试只在覆盖不同 adapter、契约或执行路径时才添加并优先扩展最接近的既有测试套件而不是新建孤立测试。八、生成文件管理与 API 契约CLAUDE.md 的 Generated Files 章节划定了一条红线不得手工编辑生成物或构建产物包括generated/*web/.next/*web/.next-check/**/dist/*packages/shared/prisma/generated/*公共 API 契约的变更必须更新 fern/apis/ 中的 Fern 源并重新生成输出绝不手工编辑generated/**。这也解释了 fern/ 目录的定位——它是 API 定义的事实来源source of truth包含client、organizations、server三套 API 定义其中server下就有 39 个 YAML 定义文件生成物则落在web/public/generated/api/、web/public/generated/api-client/、web/public/generated/organizations-api/等处。相关校验命令是pnpm run openapi:check导出后再执行 scripts/openapi/assert-generated-current.sh 断言生成结果与当前仓库一致。九、Cursor Cloud 与 PR 工作流对于在 Cursor Cloud 中运行 agent 的场景CLAUDE.md 提供了专门的说明Cursor Cloud specific instructions身份识别以cursor-cloudrun-info的owningUserName/owningUserEmail加名册为准仓库 postinstall 与 Cloud 启动通常会先用LINEAR_API_KEY恢复~/.config/langfuse/me.md。忽略git configcursoragentcursor.com与 Cloudgh的.permissions.pushLinear 访问优先用已授权的 MCP否则用LINEAR_API_KEY或LINEAR_TOKEN/LINEAR_API_TOKEN做真实读取。Cloud 中交互式mcp_auth不可用都不行时让用户把LINEAR_API_KEY作为 Cursor Cloud secret 添加后重新运行本次运行看不到之后添加的 secret启动整套源码构建栈必须通过bash scripts/agents/start-cursor-cloud.sh不要在 3000/3030 端口再启动第二个 web 或 worker 进程修改 web/worker 生产代码后浏览器验收前需重跑该脚本。之所以不用 Compose 直接启动是因为工作区.env含面向宿主机的localhost服务 URL不能用于插值容器服务配置预览部署每个 PR 通过 GitHub Actions 自动构建一个一次性全栈预览pr-N.preview.langfuse.com无需自行拉起用langfuse-previewsskill 读取/调试如用kubectl读预览的 web/worker 错误日志预览通常周一至周五 08:00–24:00Europe/Berlin运行。本地验证通过后应开可评审的 PR非 draft用合成数据测试预览部署并给 PR 打上cursor标签分支命名使用 Linear 的 git 分支名lfe-XXXX-short-title绝不创建cursor/分支评审留言PR 打开后在最后一个评论里写评审者应质疑什么那些可疑的部分而不是 changelog用户可见的改动要把修复证据放进评论与 PR 正文。上下文交接Context Handover也是文档强调的两个易跳过但代价高昂的时刻改动既有功能前先沿 commit、承载它们的 PR、head 分支名工作项 id 所在处回溯到工作项与先前的 agent 上下文命令见.agents/skills/pr-stack-workflow/skill请求评审或合并前先把决策、反复、人的引导与陷阱留存在工作项上——合并后就没有后来。对应工具是linear-context-handover与linear-planningskills 以及规定 agent 可向追踪器写什么、如何标记的linear-agent-writes。十、工程纪律小结纵观整个 CLAUDE.md可以提炼出 Langfuse 仓库几条贯穿始终的工程纪律一切以 AGENTS.md 为源CLAUDE.md 只是生成的兼容层指南按领域下沉到最窄的目录依赖方向单向受控packages/shared是唯一可被 web/worker/ee 共同依赖的底座测试数据一律走 seed CLI确定性、可回读校验、输出 UI 深链接验证以证据收尾警惕 turbo 缓存导致的假通过warning 即失败生成物一律不手改API 契约以 Fern 源为准区分服务对象外部贡献者与维护者拿到的是同一仓库的两半协作方式完全不同。对于希望在 Langfuse 仓库中做开发或贡献的工程师与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考