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 配置，用于生成各工具的 shim
skills/：工具中立、可复用的重复性工作流实现指南（共 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"、devTerminalDescription
mcpServers：项目 MCP 服务器，当前包含三个：
- playwright（stdio 传输，npx -y @playwright/mcp@latest --isolated --save-session，以data-testid作为 test-id 属性）
- langfuse-docs（HTTP 传输，https://langfuse.com/api/mcp）
- linear（HTTP 传输，https://mcp.linear.app/mcp）
claude/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 --check（postinstall运行）只核对生成的配置文件与 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 owner（cursor-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、Role（maintainer | 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 id（LFE-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_upload+create_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/ee
worker→@langfuse/shared
@langfuse/ee→@langfuse/shared
@langfuse/shared→ 不得导入web、worker、ee

高信号的共享入口点：领域模型在packages/shared/src/domain/{observations,traces,scores}.ts；Postgres 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 + turborepo）：

pnpm 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 Chromium

vitest 以文件名参数过滤；各包 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 client（pnpm --filter=shared run db:generate+pnpm run db:generate）。

Cursor Cloud 专属指令

Cursor Cloud 通过 scripts/agents/start-cursor-cloud.sh 启动完整源码构建栈，而不是直接调用 Compose：workspace 的.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-info（owningUserName、owningUserEmail）加名册，忽略git config（cursoragent@cursor.com）与 Cloudgh的.permissions.push
Linear：MCP 已授权则直接用；否则用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 --filter=web run typecheck不会——切换 worktree 分支后要先运行pnpm --filter=shared run db:generate && pnpm --filter=shared 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"。

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

Langfuse 开源仓库的 Agent 协作指南：从身份识别到验证闭环的完整解读