Langfuse 源码学习
面向团队的开源 LLM 工程平台：追踪、提示词、评测、数据集和调试。这不是 API 速查表，而是一条可以重复走的源码路线：每天用 30 分钟，从一个真实相对路径出发，先用类比建立直觉，再把它接回整条运行链路。
开篇 · 这是个什么项目
Langfuse 可以先想成一间AI 应用的飞行记录仪 + 实验室。它的代码不是一堆孤立文件：入口接到需求，核心对象做判断，工具或模型完成工作，状态把结果交给下一个环节。
架构全景（动起来看）
发光扫过的每一层都是一次任务可能经过的站点。不同仓库命名不同，但「接入 → 编排 → 核心能力 → 资源」的责任边界很相似。
怎么使用这份教程
每天 30 分钟
6 讲，每讲先问问题，再给本质和大白话。
真实相对路径
所有路径都从项目根目录算，不把你的机器路径写进源码引用。
先验证再推理
每页都有可复制 bash 命令；文件版本变化时以本地实际内容为准。
可迁移方法
学会从入口、数据结构、循环和扩展点读任何 AI 项目。
Turbo Monorepo 与应用边界
package.json：区分 web、worker 和 shared 三个核心包。
共享服务端入口
packages/shared/src/index.ts：认识跨 Web 与 Worker 复用的基础能力。
Web 与 Worker 启动
worker/src/index.ts：理解同步请求服务和异步后台服务的分工。
追踪领域模型
packages/shared/src/server/repositories/traces.ts：学习 trace 在产品查询层的基本形态。
Observation 查询模型
packages/shared/src/server/repositories/observations.ts：区分模型生成、工具调用等细粒度观测。
事件与会话仓储
packages/shared/src/server/repositories/events.ts：认识事件、session 与 trace 的关联。
Public Trace API
web/src/pages/api/public/traces：跟踪 SDK/用户如何访问追踪数据。
摄取服务
worker/src/services/IngestionService：理解输入事件如何被校验、转换和批处理。
摄取队列
worker/src/queues/ingestionQueue.ts：学习可靠异步摄取的生产者与消费者边界。
ClickHouse 写入器
worker/src/services/ClickhouseWriter：理解高吞吐观测数据写入分析数据库的职责。
OTel 摄取队列
worker/src/queues/otelIngestionQueue.ts：认识 OpenTelemetry 数据接入的专用流程。
tRPC 根路由
web/src/server/api/root.ts：了解 Web 前端调用后端领域能力的组织方式。
追踪表查询 API
web/src/server/api/routers/traces.ts：阅读筛选、分页和权限后的 trace 查询。
Prompt 领域服务
packages/shared/src/server/services/PromptService：理解提示词版本、缓存和服务端规则。