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本文围绕 Langfuse 开源仓库根目录的 .agents/AGENTS.md 展开系统讲解这个大型 LLM 可观测性项目中AI Agent 如何被配置、如何工作、如何验证、如何交接的完整规范。通过阅读本文你将理解 Langfuse 如何通过.agents/目录统一管理跨工具Claude / Cursor / Codex / VS Code的 Agent 行为掌握其身份识别机制、项目结构、核心命令、验证纪律与上下文交接流程并可直接将这套实践映射到自己的开源仓库中。Langfuse 是一个开源 LLM 工程平台用于开发、监控、评估和调试 AI 应用。随着越来越多的开发者用 Claude、Cursor、Codex 等 AI 编码助手参与贡献仓库需要一个中立、仓库自有的 Agent 行为事实源。Langfuse 的答案就是.agents/目录它以AGENTS.md为根指南通过config.json生成各工具的配置文件用 symlink 让每个工具都能发现同一份指导。一、.agents/目录Agent 行为的中立事实源根据 .agents/README.md这个目录是用于跨工具生效的 Agent 行为事实源neutral, repo-owned source of truth刻意不把长期共享的指导只放在.claude/、.codex/、.cursor/或.vscode/中。其布局为AGENTS.md共享根指令即本文主体ARCHITECTURE_PRINCIPLES.md面向大规模可观测性的架构原则config.json共享引导bootstrap与 MCP 配置用于生成各工具的 shimskills/工具中立、可复用的重复性工作流实现指南共 40 个 SKILL.md如langfuse-onboarding、linear-context-handover、pr-stack-workflow、clickhouse-best-practices等.agents/AGENTS.md是规范根指南仓库根的AGENTS.md是指向它的 symlink根CLAUDE.md又是兼容性 symlink。树中每一个AGENTS.md都会在运行pnpm run agents:sync时生成一个兄弟CLAUDE.mdsymlink目前包括web/、worker/、ee/、packages/shared/、packages/shared/scripts/seeder/这样 Claude 在打开某个目录下的文件时只加载与当前目录相关的局部指导。config.json 的四类数据.agents/config.json 包含四类数据shared跨工具默认值包括setupScript: bash scripts/agents/setup.sh、devCommand: pnpm run dev、devTerminalDescriptionmcpServers项目 MCP 服务器当前包含三个playwrightstdio 传输npx -y playwright/mcplatest --isolated --save-session以data-testid作为 test-id 属性langfuse-docsHTTP 传输https://langfuse.com/api/mcplinearHTTP 传输https://mcp.linear.app/mcpclaude/codex/cursor各工具专属的生成设置输入shim 生成机制scripts/agents/sync-agent-shims.mjs 读取.agents/config.json写出各产品要求的工具发现文件.claude/settings.json、.claude/skills/*、.cursor/mcp.json、.vscode/mcp.json、.mcp.json、.codex/config.toml、.codex/environments/environment.toml。其中.cursor/environment.json是唯一提交进仓库的生成配置Cursor 必须先读取环境契约才能运行安装脚本其余发现文件以 symlink 形式提交保证全新 clone 在pnpm install之前就有指导可用。校验分两层node scripts/agents/sync-agent-shims.mjs --checkpostinstall运行只核对生成的配置文件与 shim 是否一致pnpm run agents:check根 package.json 中定义为--check --check-paths由 lint 任务运行额外解析每个AGENTS.md引用的路径发现失效引用即失败路径校验刻意不放进postinstall否则一个文档笔误就会让pnpm i以及所有安装依赖的 CI 任务失败。二、工作对象的识别Contributor 与 Maintainer 的差异.agents/AGENTS.md开篇强调这个仓库服务于两种人他们各自拿到仓库的一半。先弄清是谁绝不默默猜测。 这是一个配置问题而非面试问题判定链条是读取~/.config/langfuse/me.md已存在则直接使用不存在则执行langfuse-onboarding第 1 步Cursor Cloud 环境下以 run ownercursor-cloud run-info加团队名册为准——而不是gh api ...permissions因为 Cloud 的 GitHub token 是只读集成即使对 maintainer 也报告push: false桌面环境使用gh api user再查.permissions.push仍无法确定时只问一次并把答案写回me.md让此后不再重复提问me.md是机器级文件位于~/.config/langfuse/me.md因为它必须同时服务langfuse、langfuse-docs和临时目录中的 Agent。其模板来自 langfuse-onboarding 技能包含 Name、Rolemaintainer | contributor、GitHub、Tracker identity、Focus、Checkouts、Connectors verified 等字段。两个铁律永不提交此文件、永不写入密钥Focus工作领域必须问本人一次因为纸面上拥有的和本季度实际负责的是两回事。身份自动恢复脚本scripts/agents/configure-langfuse-identity.sh 在仓库 postinstall 与 Cursor Cloud 启动时运行它依次探测LINEAR_API_KEY/LINEAR_TOKEN/LINEAR_API_TOKEN用 GraphQL{ viewer { name email } teams { nodes { name key } } }查询 Linear确认 viewer 属于LF团队后以umask 077写入me.md。它从不覆盖已存在的文件因此人工修正能在多次安装与 worktree 之间幸存token 只以布尔形式报告绝不打印密钥本身。外部贡献者拿到的是代码和CONTRIBUTING.md如何构建、检查要求、如何开 PR不涉及 tracker、手册或工作周——他们无法打开这些东西提及就等于描述一扇锁着的门。维护者则额外获得一个持有组织上下文的助手应承担如下职责回答今天该做什么——不是凭记忆而是查 tracker知道团队其他人在做什么同事每周发布项目更新动手设计前先检查该 surface 是否刚被同事改动并点名提醒接过链接就能跑ticket、PR、Slack 链接、截图都能读懂并提议下一步在相关时简短提示组织上到期的事务一行而不是常驻报告主动提出实现方案而不是等着被告知设计三、工作纪律如何正确地干活.agents/AGENTS.md的How To Work一节给出了具体的行为约束其中多数在仓库中能找到对应实现先识别再假设差异是可推导的见上一节只读完成任务所需的最小本地上下文保持改动范围避免无关重构把探索性/高噪音工作委派给 subagent大范围代码搜索、多文件调查、日志或测试输出筛查避免中间工具输出污染主上下文按风险匹配验证而非按是否改了东西只有能钉住无人注意就会回归的行为测试才值得存在若唯一断言只是复述 diff间距值变成了某个值、标签读起来是什么就跳过并在一行里说明原因Bug 修复要写测试时先写最小失败用例并确认它对有缺陷的行为失败再改生产代码只在不同 adapter、契约或执行路径上有增量时才添加第二个测试优先扩展最近的既有测试套件而非新建孤立常量测试优先用 seed CLI 预填本地测试数据pnpm run seed -- list列出场景运行会打印 UI 深链接绝不用 ad-hoc 脚本或裸 ClickHouse insert每个 PR 都会通过 GitHub Actions 自动构建一个可抛弃的全栈预览pr-N.preview.langfuse.com可用langfuse-previews技能含kubectl读日志调试禁用./node_modules/.bin/*直接调用一律通过pnpm运行永不把内部 ticket idLFE-1234、LFINT-1234、CLI-Q226-12或 tracker URL 写进 OSS 读者会看到的地方代码注释、commit message、PR 标题/描述、changelog、用户文档唯一例外是.agents/skills/**中的 id作为可追溯的出处和lfe-XXXX-short-title形式的 branch name永不提交密钥.env*.example必须与必需环境变量保持同步人工交接以一句 TL;DR 开头每条消息只给一到两个人工动作产品/UI 改动要给出预览 URL 和精确的点击路径测试步骤含 seed 命令或 sandbox URLhttp://localhost:3000并把修复证明截图、短视频或前后对比贴到 GitHub PR 上除非人类要求否则 PR 以可评审状态打开而非 draft对 Claude/Greptile/Codex 机器评审评论不回复、保持线程打开直到应用修复并 resolve或确信跳过并向人类说明理由后 resolve四、上下文交接让推理跨会话存活Context Handover一节指出每个任务中有两个容易跳过却代价高昂的时刻动既有功能之前先重建其历史沿 commits、承载它们的 PR、以及承载工作项标识符的 head branch name回溯到工作项及此前 Agent 留下的上下文。命令在 .agents/skills/pr-stack-workflow/references/stack-commands.md 的Recover the context before you slice中。一次已被推翻的决定不需要再次被提出在请求评审或合并之前把推理留在工作项上——决策、反复、人类如何引导、陷阱。必须在 PR 之前而非合并之后做因为之后就不存在了这套实践由linear-context-handover与linear-planning技能承载外加linear-agent-writes定义 Agent 可以往 tracker 写什么、如何标记。核心观点来自 linear-context-handover 技能Linear 是组织的长期记忆Agent 会话不是——会话结束它们推演出来的东西也随之结束。交接块必须写入 ticket 的 description并打上AI edited标签。反复reversals才是载荷先写被构建后又刻意移除的东西及原因最后再写摘要空间不够时砍摘要。两条机制防止交接内容反被破坏用patch的appendop 写入绝不要整篇重发 description全量重写会压平 Linear 存在 description 里的user/linear-comment元素且之后的 diff 无法显示附件与图片必须走prepare_attachment_uploadcreate_attachment_from_upload绝不粘贴上传 URL——Linear 的上传 URL 带签名约五分钟就过期没有 Linear 访问权限时必须明确说明、点名无法完成的步骤并把可直接粘贴的内容交还人类——绝不允许只靠代码重建历史并冒充已恢复的上下文。五、项目结构Agent 眼中的仓库地图.agents/AGENTS.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依赖方向被严格约束web→langfuse/shared、langfuse/eeworker→langfuse/sharedlangfuse/ee→langfuse/sharedlangfuse/shared→ 不得导入web、worker、ee高信号的共享入口点领域模型在packages/shared/src/domain/{observations,traces,scores}.tsPostgres schema 在packages/shared/prisma/schema.prisma队列 payload schema 与队列名契约由packages/shared/src/server/queues.ts所有ClickHouse 迁移模板在packages/shared/clickhouse/migrations/渲染为集群与非集群两套安装。架构原则的完整版在 .agents/ARCHITECTURE_PRINCIPLES.md——它以wide events为核心把 observation 作为主要分析单元倾向宽属性、高基数、不可变或追加式的事件记录围绕列式访问模式设计存储与查询路径并要求 API 契约具备规模意识强制时间窗口、字段选择、token 分页。六、核心命令速查.agents/AGENTS.md的 Core Commands 一节基于 pnpm workspace turborepopnpm install # 安装依赖 pnpm run dev # 开发全部包 pnpm run dev:web # 仅开发 web pnpm run dev:worker # 仅开发 worker pnpm run lint # 全量 lint pnpm run typecheck / pnpm tc # 全量类型检查 pnpm --filter web run test file # web 服务端测试客户端用 test-client pnpm --filter worker run test file # worker 测试 pnpm --filter langfuse/shared run test file # shared 测试 pnpm run build:check # 构建检查 pnpm run build # 完整构建 bash scripts/agents/setup.sh # 共享 Agent/worktree 引导 bash scripts/codex/maintenance.sh # worktree 维护 pnpm run playwright:install # 安装 Playwright Chromiumvitest 以文件名参数过滤各包 lint 均以--max-warnings 0运行一个 eslint warning 就会让分支失败。共享引导脚本 scripts/agents/setup.sh 依次执行corepack 启用 → 从.env.dev.example/.env.test.example复制缺失的.env/.env.test→pnpm install --frozen-lockfile→ Docker 可用时构建 in-app-agent sandbox 镜像 → 安装 Playwright Chromium → 显式生成当前 worktree 的 Prisma clientpnpm --filtershared run db:generatepnpm run db:generate。Cursor Cloud 专属指令Cursor Cloud 通过 scripts/agents/start-cursor-cloud.sh 启动完整源码构建栈而不是直接调用 Composeworkspace 的.env含有面向宿主机的localhost服务 URL绝不能用于插值容器服务配置。该脚本使用env -i从干净环境出发只显式保留 Docker 与公开构建控制变量DOCKER_HOST、DOCKER_CONTEXT、NEXT_PUBLIC_LANGFUSE_CLOUD_REGION等以--env-file /dev/null调用 Compose 启动 web、worker、PostgreSQL、ClickHouse、Redis、MinIO 六服务等待健康后以显式本机连接 URL 执行db:seed最后 curl 校验 web 健康端点:3000/api/public/health与 worker 健康端点:3030/api/health。其他 Cloud 纪律身份用cursor-cloud run-infoowningUserName、owningUserEmail加名册忽略git configcursoragentcursor.com与 Cloudgh的.permissions.pushLinearMCP 已授权则直接用否则用LINEAR_API_KEY或LINEAR_TOKEN/LINEAR_API_TOKEN做真实读取。Cloud 中交互式mcp_auth不可用需要人类在 https://cursor.com/dashboard/cloud-agents 添加LINEAR_API_KEY密钥并开启新 run——本 run 无法看到之后添加的密钥修改 web/worker 生产代码后浏览器签收前需重跑start-cursor-cloud.sh本地验证后开同仓库可评审 PR非 draft并用合成数据测试pr-N.preview.langfuse.com部署预览通常周一至周五 08:00-24:00 欧洲/柏林时间运行开 PR 后主动打上 GitHubcursor标签branch 用 Linear 命名lfe-XXXX-short-title绝不创建cursor/分支开 PR 后留一条短评论说明评审者应怀疑什么可疑的部分而不是 changelog评论只在 GitHub 会归属给 Cursor 而非人类作者时发布本地数据巡检开发用 Docker Compose 把客户端暴露在${HOST_IP:-127.0.0.1}各客户端连接命令带默认值# 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}优先只读查询前端测试状态仍用 seed CLI 创建连接失败时检查docker-compose.dev.yml的本地覆盖变量并确认服务在运行。七、验证纪律通过不代表运行过Verification 一节按改动位置规定了验证组合web/**pnpm run lint 针对性 web 测试worker/**pnpm run lint 针对性 worker 测试packages/shared/**非 schema 改动lint 一项针对性 web 检查 一项针对性 worker 检查packages/shared/prisma/**或packages/shared/clickhouse/**lint pnpm run db:generate 针对性 web/worker 回归Public API 契约web/src/pages/api/public/**、web/src/features/public-api/types/**、fern/apis/**lint 针对性服务端 API 测试 Fern 更新/再生成 pnpm run openapi:check跨包重构lint typecheck 受影响包的针对性测试客户端 bundle 健全性CI 对每个生产 web 构建运行pnpm run scan:client-bundle检测被 minifier 丢弃的绑定与泄漏进浏览器 chunk 的 Node-only 全局量失败时 scripts/scan-client-bundle.mjs 的头部说明标准修法结束回合要用证据而非声明引用每个检查的摘要行如Tasks: 8 successful, 8 total或Tests 12 passed (12)说明跳过了哪些检查及原因绝不把未验证的工作报为完成也绝不以待办工作结束。缓存的陷阱lint与typecheck是 turbo 缓存任务worktree 共享同一缓存每次运行都会打印using shared worktree cache所以一次通过可能是另一分支结果的回放。要同时引用Cached:行强制执行用pnpm exec turbo run lint --force--no-cache只是停止写入不会强制运行langfuse/shared解析到构建产物dist。根pnpm run typecheck会按turbo.json的typecheck.dependsOn: ^build自动先构建但pnpm --filterweb run typecheck不会——切换 worktree 分支后要先运行pnpm --filtershared run db:generate pnpm --filtershared run build否则 typecheck 会基于上一分支的源码报告pnpm exec knip是pipeline.yml中的必需检查但没有 package.json script容易只在本地漏跑web/**、packages/shared/**、worker/**下未使用的文件与导出都会导致它失败没有任何检查会加载页面因此渲染改动只有被人看过才算验证过真正不确定时可能重排的布局、携带状态的流程、无法预判结果的交互驱动浏览器自查改动小且可视化、信心高时说明改了什么、交出确切 URL 让开发者瞄一眼。无人可接手且改动用户可见时必须自己检查八、生成文件红线与共享 Agent 设置Do not hand-edit 清单generated/*、web/.next/*、web/.next-check/*、*/dist/*、packages/shared/prisma/generated/*。Public API 契约改动必须更新fern/apis/**的 Fern 源并重新生成绝不手改generated/**。共享 Agent 设置的维护规则写 Agent 指导只写进AGENTS.md绝不写进CLAUDE.md每个AGENTS.md经pnpm run agents:sync生成兄弟CLAUDE.mdsymlink包内指导放在最窄的AGENTS.md中只在需要时才加载进上下文创建或编辑.agents/skills/**时使用 .agents/skills/skill-creator/SKILL.md技能保持精简、渐进式披露改动 skills / AGENTS.md 后运行pnpm run agents:sync与pnpm run agents:check.claude/、.cursor/、.codex/、.vscode/、.mcp.json下的生成配置与 shim 是本地产物不是事实源编辑.agents/config.json的时机增删改共享 MCP 服务器、改共享 setup/bootstrap 命令、改默认 dev 命令或终端标签、调整 Claude/Cursor/Codex 的生成设置九、这套指南给开源维护者的启示从仓库证据看Langfuse 的 Agent 治理设计有三个可迁移的核心思想配置先于提问身份、连接器、工作领域全部可推导或一次性询问后落盘me.md把我是谁、我能访问什么从每次会话的重复猜测中剥离事实源单一、发现机制多路AGENTS.md与config.json是唯一事实源Claude/Cursor/Codex/VS Code 各自的配置文件由 scripts/agents/sync-agent-shims.mjs 生成并用--check/--check-paths两级校验保证不腐化生成物从不手改验证与交接是显式纪律按风险匹配测试、引用 turbo 缓存行、用--force强制执行以及把推理写进 Linear ticket 描述作为任务收尾的强制步骤——因为会话结束推演随之结束无论你是想为 Langfuse 做贡献的外部开发者还是在自己的仓库里为团队搭建 Agent 工作流的维护者.agents/AGENTS.md都是一份值得逐节对照的范本它既定义了Agent 该怎样对待这个代码库也定义了这个代码库该怎样对待 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），仅供参考 Langfuse 开源仓库的 Agent 协作指南：从身份识别到验证闭环的完整解读
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本文围绕 Langfuse 开源仓库根目录的 .agents/AGENTS.md 展开系统讲解这个大型 LLM 可观测性项目中AI Agent 如何被配置、如何工作、如何验证、如何交接的完整规范。通过阅读本文你将理解 Langfuse 如何通过.agents/目录统一管理跨工具Claude / Cursor / Codex / VS Code的 Agent 行为掌握其身份识别机制、项目结构、核心命令、验证纪律与上下文交接流程并可直接将这套实践映射到自己的开源仓库中。Langfuse 是一个开源 LLM 工程平台用于开发、监控、评估和调试 AI 应用。随着越来越多的开发者用 Claude、Cursor、Codex 等 AI 编码助手参与贡献仓库需要一个中立、仓库自有的 Agent 行为事实源。Langfuse 的答案就是.agents/目录它以AGENTS.md为根指南通过config.json生成各工具的配置文件用 symlink 让每个工具都能发现同一份指导。一、.agents/目录Agent 行为的中立事实源根据 .agents/README.md这个目录是用于跨工具生效的 Agent 行为事实源neutral, repo-owned source of truth刻意不把长期共享的指导只放在.claude/、.codex/、.cursor/或.vscode/中。其布局为AGENTS.md共享根指令即本文主体ARCHITECTURE_PRINCIPLES.md面向大规模可观测性的架构原则config.json共享引导bootstrap与 MCP 配置用于生成各工具的 shimskills/工具中立、可复用的重复性工作流实现指南共 40 个 SKILL.md如langfuse-onboarding、linear-context-handover、pr-stack-workflow、clickhouse-best-practices等.agents/AGENTS.md是规范根指南仓库根的AGENTS.md是指向它的 symlink根CLAUDE.md又是兼容性 symlink。树中每一个AGENTS.md都会在运行pnpm run agents:sync时生成一个兄弟CLAUDE.mdsymlink目前包括web/、worker/、ee/、packages/shared/、packages/shared/scripts/seeder/这样 Claude 在打开某个目录下的文件时只加载与当前目录相关的局部指导。config.json 的四类数据.agents/config.json 包含四类数据shared跨工具默认值包括setupScript: bash scripts/agents/setup.sh、devCommand: pnpm run dev、devTerminalDescriptionmcpServers项目 MCP 服务器当前包含三个playwrightstdio 传输npx -y playwright/mcplatest --isolated --save-session以data-testid作为 test-id 属性langfuse-docsHTTP 传输https://langfuse.com/api/mcplinearHTTP 传输https://mcp.linear.app/mcpclaude/codex/cursor各工具专属的生成设置输入shim 生成机制scripts/agents/sync-agent-shims.mjs 读取.agents/config.json写出各产品要求的工具发现文件.claude/settings.json、.claude/skills/*、.cursor/mcp.json、.vscode/mcp.json、.mcp.json、.codex/config.toml、.codex/environments/environment.toml。其中.cursor/environment.json是唯一提交进仓库的生成配置Cursor 必须先读取环境契约才能运行安装脚本其余发现文件以 symlink 形式提交保证全新 clone 在pnpm install之前就有指导可用。校验分两层node scripts/agents/sync-agent-shims.mjs --checkpostinstall运行只核对生成的配置文件与 shim 是否一致pnpm run agents:check根 package.json 中定义为--check --check-paths由 lint 任务运行额外解析每个AGENTS.md引用的路径发现失效引用即失败路径校验刻意不放进postinstall否则一个文档笔误就会让pnpm i以及所有安装依赖的 CI 任务失败。二、工作对象的识别Contributor 与 Maintainer 的差异.agents/AGENTS.md开篇强调这个仓库服务于两种人他们各自拿到仓库的一半。先弄清是谁绝不默默猜测。 这是一个配置问题而非面试问题判定链条是读取~/.config/langfuse/me.md已存在则直接使用不存在则执行langfuse-onboarding第 1 步Cursor Cloud 环境下以 run ownercursor-cloud run-info加团队名册为准——而不是gh api ...permissions因为 Cloud 的 GitHub token 是只读集成即使对 maintainer 也报告push: false桌面环境使用gh api user再查.permissions.push仍无法确定时只问一次并把答案写回me.md让此后不再重复提问me.md是机器级文件位于~/.config/langfuse/me.md因为它必须同时服务langfuse、langfuse-docs和临时目录中的 Agent。其模板来自 langfuse-onboarding 技能包含 Name、Rolemaintainer | contributor、GitHub、Tracker identity、Focus、Checkouts、Connectors verified 等字段。两个铁律永不提交此文件、永不写入密钥Focus工作领域必须问本人一次因为纸面上拥有的和本季度实际负责的是两回事。身份自动恢复脚本scripts/agents/configure-langfuse-identity.sh 在仓库 postinstall 与 Cursor Cloud 启动时运行它依次探测LINEAR_API_KEY/LINEAR_TOKEN/LINEAR_API_TOKEN用 GraphQL{ viewer { name email } teams { nodes { name key } } }查询 Linear确认 viewer 属于LF团队后以umask 077写入me.md。它从不覆盖已存在的文件因此人工修正能在多次安装与 worktree 之间幸存token 只以布尔形式报告绝不打印密钥本身。外部贡献者拿到的是代码和CONTRIBUTING.md如何构建、检查要求、如何开 PR不涉及 tracker、手册或工作周——他们无法打开这些东西提及就等于描述一扇锁着的门。维护者则额外获得一个持有组织上下文的助手应承担如下职责回答今天该做什么——不是凭记忆而是查 tracker知道团队其他人在做什么同事每周发布项目更新动手设计前先检查该 surface 是否刚被同事改动并点名提醒接过链接就能跑ticket、PR、Slack 链接、截图都能读懂并提议下一步在相关时简短提示组织上到期的事务一行而不是常驻报告主动提出实现方案而不是等着被告知设计三、工作纪律如何正确地干活.agents/AGENTS.md的How To Work一节给出了具体的行为约束其中多数在仓库中能找到对应实现先识别再假设差异是可推导的见上一节只读完成任务所需的最小本地上下文保持改动范围避免无关重构把探索性/高噪音工作委派给 subagent大范围代码搜索、多文件调查、日志或测试输出筛查避免中间工具输出污染主上下文按风险匹配验证而非按是否改了东西只有能钉住无人注意就会回归的行为测试才值得存在若唯一断言只是复述 diff间距值变成了某个值、标签读起来是什么就跳过并在一行里说明原因Bug 修复要写测试时先写最小失败用例并确认它对有缺陷的行为失败再改生产代码只在不同 adapter、契约或执行路径上有增量时才添加第二个测试优先扩展最近的既有测试套件而非新建孤立常量测试优先用 seed CLI 预填本地测试数据pnpm run seed -- list列出场景运行会打印 UI 深链接绝不用 ad-hoc 脚本或裸 ClickHouse insert每个 PR 都会通过 GitHub Actions 自动构建一个可抛弃的全栈预览pr-N.preview.langfuse.com可用langfuse-previews技能含kubectl读日志调试禁用./node_modules/.bin/*直接调用一律通过pnpm运行永不把内部 ticket idLFE-1234、LFINT-1234、CLI-Q226-12或 tracker URL 写进 OSS 读者会看到的地方代码注释、commit message、PR 标题/描述、changelog、用户文档唯一例外是.agents/skills/**中的 id作为可追溯的出处和lfe-XXXX-short-title形式的 branch name永不提交密钥.env*.example必须与必需环境变量保持同步人工交接以一句 TL;DR 开头每条消息只给一到两个人工动作产品/UI 改动要给出预览 URL 和精确的点击路径测试步骤含 seed 命令或 sandbox URLhttp://localhost:3000并把修复证明截图、短视频或前后对比贴到 GitHub PR 上除非人类要求否则 PR 以可评审状态打开而非 draft对 Claude/Greptile/Codex 机器评审评论不回复、保持线程打开直到应用修复并 resolve或确信跳过并向人类说明理由后 resolve四、上下文交接让推理跨会话存活Context Handover一节指出每个任务中有两个容易跳过却代价高昂的时刻动既有功能之前先重建其历史沿 commits、承载它们的 PR、以及承载工作项标识符的 head branch name回溯到工作项及此前 Agent 留下的上下文。命令在 .agents/skills/pr-stack-workflow/references/stack-commands.md 的Recover the context before you slice中。一次已被推翻的决定不需要再次被提出在请求评审或合并之前把推理留在工作项上——决策、反复、人类如何引导、陷阱。必须在 PR 之前而非合并之后做因为之后就不存在了这套实践由linear-context-handover与linear-planning技能承载外加linear-agent-writes定义 Agent 可以往 tracker 写什么、如何标记。核心观点来自 linear-context-handover 技能Linear 是组织的长期记忆Agent 会话不是——会话结束它们推演出来的东西也随之结束。交接块必须写入 ticket 的 description并打上AI edited标签。反复reversals才是载荷先写被构建后又刻意移除的东西及原因最后再写摘要空间不够时砍摘要。两条机制防止交接内容反被破坏用patch的appendop 写入绝不要整篇重发 description全量重写会压平 Linear 存在 description 里的user/linear-comment元素且之后的 diff 无法显示附件与图片必须走prepare_attachment_uploadcreate_attachment_from_upload绝不粘贴上传 URL——Linear 的上传 URL 带签名约五分钟就过期没有 Linear 访问权限时必须明确说明、点名无法完成的步骤并把可直接粘贴的内容交还人类——绝不允许只靠代码重建历史并冒充已恢复的上下文。五、项目结构Agent 眼中的仓库地图.agents/AGENTS.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依赖方向被严格约束web→langfuse/shared、langfuse/eeworker→langfuse/sharedlangfuse/ee→langfuse/sharedlangfuse/shared→ 不得导入web、worker、ee高信号的共享入口点领域模型在packages/shared/src/domain/{observations,traces,scores}.tsPostgres schema 在packages/shared/prisma/schema.prisma队列 payload schema 与队列名契约由packages/shared/src/server/queues.ts所有ClickHouse 迁移模板在packages/shared/clickhouse/migrations/渲染为集群与非集群两套安装。架构原则的完整版在 .agents/ARCHITECTURE_PRINCIPLES.md——它以wide events为核心把 observation 作为主要分析单元倾向宽属性、高基数、不可变或追加式的事件记录围绕列式访问模式设计存储与查询路径并要求 API 契约具备规模意识强制时间窗口、字段选择、token 分页。六、核心命令速查.agents/AGENTS.md的 Core Commands 一节基于 pnpm workspace turborepopnpm install # 安装依赖 pnpm run dev # 开发全部包 pnpm run dev:web # 仅开发 web pnpm run dev:worker # 仅开发 worker pnpm run lint # 全量 lint pnpm run typecheck / pnpm tc # 全量类型检查 pnpm --filter web run test file # web 服务端测试客户端用 test-client pnpm --filter worker run test file # worker 测试 pnpm --filter langfuse/shared run test file # shared 测试 pnpm run build:check # 构建检查 pnpm run build # 完整构建 bash scripts/agents/setup.sh # 共享 Agent/worktree 引导 bash scripts/codex/maintenance.sh # worktree 维护 pnpm run playwright:install # 安装 Playwright Chromiumvitest 以文件名参数过滤各包 lint 均以--max-warnings 0运行一个 eslint warning 就会让分支失败。共享引导脚本 scripts/agents/setup.sh 依次执行corepack 启用 → 从.env.dev.example/.env.test.example复制缺失的.env/.env.test→pnpm install --frozen-lockfile→ Docker 可用时构建 in-app-agent sandbox 镜像 → 安装 Playwright Chromium → 显式生成当前 worktree 的 Prisma clientpnpm --filtershared run db:generatepnpm run db:generate。Cursor Cloud 专属指令Cursor Cloud 通过 scripts/agents/start-cursor-cloud.sh 启动完整源码构建栈而不是直接调用 Composeworkspace 的.env含有面向宿主机的localhost服务 URL绝不能用于插值容器服务配置。该脚本使用env -i从干净环境出发只显式保留 Docker 与公开构建控制变量DOCKER_HOST、DOCKER_CONTEXT、NEXT_PUBLIC_LANGFUSE_CLOUD_REGION等以--env-file /dev/null调用 Compose 启动 web、worker、PostgreSQL、ClickHouse、Redis、MinIO 六服务等待健康后以显式本机连接 URL 执行db:seed最后 curl 校验 web 健康端点:3000/api/public/health与 worker 健康端点:3030/api/health。其他 Cloud 纪律身份用cursor-cloud run-infoowningUserName、owningUserEmail加名册忽略git configcursoragentcursor.com与 Cloudgh的.permissions.pushLinearMCP 已授权则直接用否则用LINEAR_API_KEY或LINEAR_TOKEN/LINEAR_API_TOKEN做真实读取。Cloud 中交互式mcp_auth不可用需要人类在 https://cursor.com/dashboard/cloud-agents 添加LINEAR_API_KEY密钥并开启新 run——本 run 无法看到之后添加的密钥修改 web/worker 生产代码后浏览器签收前需重跑start-cursor-cloud.sh本地验证后开同仓库可评审 PR非 draft并用合成数据测试pr-N.preview.langfuse.com部署预览通常周一至周五 08:00-24:00 欧洲/柏林时间运行开 PR 后主动打上 GitHubcursor标签branch 用 Linear 命名lfe-XXXX-short-title绝不创建cursor/分支开 PR 后留一条短评论说明评审者应怀疑什么可疑的部分而不是 changelog评论只在 GitHub 会归属给 Cursor 而非人类作者时发布本地数据巡检开发用 Docker Compose 把客户端暴露在${HOST_IP:-127.0.0.1}各客户端连接命令带默认值# 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}优先只读查询前端测试状态仍用 seed CLI 创建连接失败时检查docker-compose.dev.yml的本地覆盖变量并确认服务在运行。七、验证纪律通过不代表运行过Verification 一节按改动位置规定了验证组合web/**pnpm run lint 针对性 web 测试worker/**pnpm run lint 针对性 worker 测试packages/shared/**非 schema 改动lint 一项针对性 web 检查 一项针对性 worker 检查packages/shared/prisma/**或packages/shared/clickhouse/**lint pnpm run db:generate 针对性 web/worker 回归Public API 契约web/src/pages/api/public/**、web/src/features/public-api/types/**、fern/apis/**lint 针对性服务端 API 测试 Fern 更新/再生成 pnpm run openapi:check跨包重构lint typecheck 受影响包的针对性测试客户端 bundle 健全性CI 对每个生产 web 构建运行pnpm run scan:client-bundle检测被 minifier 丢弃的绑定与泄漏进浏览器 chunk 的 Node-only 全局量失败时 scripts/scan-client-bundle.mjs 的头部说明标准修法结束回合要用证据而非声明引用每个检查的摘要行如Tasks: 8 successful, 8 total或Tests 12 passed (12)说明跳过了哪些检查及原因绝不把未验证的工作报为完成也绝不以待办工作结束。缓存的陷阱lint与typecheck是 turbo 缓存任务worktree 共享同一缓存每次运行都会打印using shared worktree cache所以一次通过可能是另一分支结果的回放。要同时引用Cached:行强制执行用pnpm exec turbo run lint --force--no-cache只是停止写入不会强制运行langfuse/shared解析到构建产物dist。根pnpm run typecheck会按turbo.json的typecheck.dependsOn: ^build自动先构建但pnpm --filterweb run typecheck不会——切换 worktree 分支后要先运行pnpm --filtershared run db:generate pnpm --filtershared run build否则 typecheck 会基于上一分支的源码报告pnpm exec knip是pipeline.yml中的必需检查但没有 package.json script容易只在本地漏跑web/**、packages/shared/**、worker/**下未使用的文件与导出都会导致它失败没有任何检查会加载页面因此渲染改动只有被人看过才算验证过真正不确定时可能重排的布局、携带状态的流程、无法预判结果的交互驱动浏览器自查改动小且可视化、信心高时说明改了什么、交出确切 URL 让开发者瞄一眼。无人可接手且改动用户可见时必须自己检查八、生成文件红线与共享 Agent 设置Do not hand-edit 清单generated/*、web/.next/*、web/.next-check/*、*/dist/*、packages/shared/prisma/generated/*。Public API 契约改动必须更新fern/apis/**的 Fern 源并重新生成绝不手改generated/**。共享 Agent 设置的维护规则写 Agent 指导只写进AGENTS.md绝不写进CLAUDE.md每个AGENTS.md经pnpm run agents:sync生成兄弟CLAUDE.mdsymlink包内指导放在最窄的AGENTS.md中只在需要时才加载进上下文创建或编辑.agents/skills/**时使用 .agents/skills/skill-creator/SKILL.md技能保持精简、渐进式披露改动 skills / AGENTS.md 后运行pnpm run agents:sync与pnpm run agents:check.claude/、.cursor/、.codex/、.vscode/、.mcp.json下的生成配置与 shim 是本地产物不是事实源编辑.agents/config.json的时机增删改共享 MCP 服务器、改共享 setup/bootstrap 命令、改默认 dev 命令或终端标签、调整 Claude/Cursor/Codex 的生成设置九、这套指南给开源维护者的启示从仓库证据看Langfuse 的 Agent 治理设计有三个可迁移的核心思想配置先于提问身份、连接器、工作领域全部可推导或一次性询问后落盘me.md把我是谁、我能访问什么从每次会话的重复猜测中剥离事实源单一、发现机制多路AGENTS.md与config.json是唯一事实源Claude/Cursor/Codex/VS Code 各自的配置文件由 scripts/agents/sync-agent-shims.mjs 生成并用--check/--check-paths两级校验保证不腐化生成物从不手改验证与交接是显式纪律按风险匹配测试、引用 turbo 缓存行、用--force强制执行以及把推理写进 Linear ticket 描述作为任务收尾的强制步骤——因为会话结束推演随之结束无论你是想为 Langfuse 做贡献的外部开发者还是在自己的仓库里为团队搭建 Agent 工作流的维护者.agents/AGENTS.md都是一份值得逐节对照的范本它既定义了Agent 该怎样对待这个代码库也定义了这个代码库该怎样对待 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），仅供参考