术语表

这里收录本书使用的核心术语。它们不是产品术语的完整集合，而是阅读当前 repo 架构时最常遇到的词。

术语	含义
monorepo	一个仓库内包含多个应用和包，Langfuse 通过 pnpm workspace 和 Turborepo 组织。
workspace package	被 pnpm-workspace.yaml 纳入管理的包，例如 web、worker、packages/shared、docs。
dependency direction	包之间允许的 import 方向。Langfuse 的关键规则是 shared 不反向依赖 web、worker、ee。
contract	跨模块或跨进程必须共同遵守的输入输出约定，例如 Zod schema、队列 payload、API schema。
abstraction	把变化封装到稳定接口后的结构，例如 repository、query builder、procedure、queue producer。
tRPC	Web UI 调用服务端业务逻辑的类型安全 RPC 层。
Public API	面向外部 SDK/API client 的 REST API surface。
ingestion	接收 trace、observation、score、event 等写入数据的链路。
observation	Langfuse 中的运行事实节点，例如 span、generation、tool、retriever。多个 observation 通过 traceId 和父子关系组成一棵 trace tree。
trace	一次请求、agent 运行或工作流的相关性边界，用 traceId 聚合一组 observation。
session	多轮对话或长期流程的聚合边界，一般包含多条 trace。
score	统一评价结果，可以挂到 trace、observation、session 或 dataset run。
score config	score 的 schema 和约束，例如 data type、numeric 范围、categorical categories。
evaluator	产生 score 的评价方法，当前 repo 中主要由 EvalTemplate、JobConfiguration 和 JobExecution 组合实现。
dataset	可重复运行的测试材料集合。
dataset item	dataset 中的单个测试样本，包含 input、expected output、metadata 和可选的线上来源 trace/observation。
dataset run	当前 repo 中承载 experiment run 语义的对象，表示对一个 dataset 的一次运行。
dataset run item	一个 dataset item 在一次 dataset run 中的运行结果，连接 dataset item、trace 和可选 observation。
BullMQ	基于 Redis 的队列系统，用来连接请求侧生产者和 worker 消费者。
QueueName	队列名称枚举，属于跨进程契约。
QueueJobs	队列 job 名称和 payload 的契约集合。
Zod schema	运行时校验和 TypeScript 类型推断共同使用的 schema。
Prisma	Postgres schema、client 和迁移相关工具。
ClickHouse	面向高吞吐分析查询的列式存储，承载 tracing/event 类明细数据。
Postgres	面向事务一致性的关系型存储，承载项目、组织、用户、配置等元数据。
Redis	队列和缓存基础设施。
S3/blob	大对象或批量事件暂存层，常用于避免请求或队列 payload 过大。
repository	封装数据访问的服务端抽象，让调用方不直接关心具体 SQL 或存储细节。
query builder	把筛选、排序、分页等高层条件转换成 ClickHouse SQL 的抽象。
FilterState	UI 和查询层共享的筛选状态结构。
Search Bar grammar	搜索栏文本语法，负责把用户输入解析成结构化 filter。
feature directory	web/src/features/* 下按业务功能聚合 UI、server helper、README 或局部类型的目录。
generated files	由工具生成的文件，例如 generated/* 和 Prisma generated client，不手工编辑。

三组容易混淆的词

contract 和 abstraction

contract 关注“双方必须一致”，abstraction 关注“调用方不必知道细节”。queues.ts 里的 job payload 是 contract；worker processor 周围的服务类是 abstraction。

web 和 frontend

web 不是纯浏览器前端。它同时包含 Next.js UI、tRPC server、Public API route、ingestion HTTP route 和一部分服务端 glue code。

shared 和 utils

packages/shared 不是随手放工具函数的地方。它是被多个运行时共同消费的契约中心，放进去的东西会抬高变更成本。