Langfuse Prompt Mutations：Prompts 服务端变更操作层的设计与源码解析

Langfuse Prompt MutationsPrompts 服务端变更操作层的设计与源码解析【免费下载链接】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 开源项目中Prompts提示词功能涉及版本管理、标签label漂移、Redis 缓存、事件溯源与依赖图解析等复杂逻辑直接调用 Prisma 很容易绕过这些约束、破坏数据一致性。本篇文章围绕web/src/features/prompts/server/actions/README.md定义的Prompt Mutations变更操作层讲解其禁止直接 Prisma 调用、统一走专用函数的工程规则与五大设计动因并结合createPrompt、updatePrompts、getPromptByName、getPromptsMeta等核心函数的真实源码深入剖析缓存失效、事件溯源、标签管理、名称校验与事务安全的落地实现。读完本文你将掌握 Langfuse Prompts 模块写入路径的完整调用链并能直接对照源码理解其并发安全与一致性保障机制。一、Prompt Mutations 是什么一条禁止直接 Prisma的工程规则web/src/features/prompts/server/actions/README.md是 Prompts 服务端写入逻辑的行为守则全文开宗明义地定义了一条硬性规则Always use functions in this directory. Never use direct Prisma calls.即凡是涉及 Prompt 的创建、更新、删除、读取等数据变更都必须使用server/actions/目录下的封装函数禁止在业务代码里直接调用 Prisma 操作prompts表。这条规则不是教条而是因为每次 Prompt 变更都牵动多条一致性链条只有收敛到单一入口才能统一处理。从目录结构看变更操作层实际包含以下文件actions 目录文件职责createPrompt.ts创建新 Prompt 版本同时实现duplicatePrompt、duplicateFolderupdatePrompts.ts更新 Prompt 标签label/元数据getPromptByName.ts按名称可选 version/label获取走缓存getPromptsMeta.ts分页列出项目内所有 Prompt 的元信息deletePrompt.ts删除指定版本含依赖保护与latest标签重挂它们依赖同目录外的辅助模块promptChangeEventSourcing.ts事件溯源、utils/updatePromptLabels.ts标签迁移、utils/updatePromptTags.ts标签 tags 同步、utils/checkHasProtectedLabels.ts、utils/authorizePromptRequest.ts鉴权以及共享包中的PromptService缓存与依赖图解析与校验 Schema。二、五大设计动因为什么每次变更都要过一遍函数层README 明确列出了这些函数必须处理的问题这正是禁止直接 Prisma的根本原因Cache invalidation缓存失效每次 Prompt 变更后必须使 Redis 缓存失效否则客户端会读到旧版本。Event sourcing事件溯源变更要通过promptChangeEventSourcing()记录为事件供审计与 analytics如 Webhook使用。Label management标签管理需要把production、latest等标签在版本间搬移——同一标签在同一名称下必须唯一。Validation校验Prompt 名称校验、变量提取、依赖解析等。Transaction safety事务安全多个关联数据库操作新增版本、写依赖、迁移标签、同步 tags必须按正确顺序放入同一事务。下面逐一结合源码展开。2.1 缓存失效以缓存纪元轮换实现全项目级失效所有变更函数在事务提交后都会调用promptService.invalidateCache({ projectId })例如createPrompt在事务成功后显式执行await promptService.invalidateCache({ projectId });值得注意的设计细节是deletePrompt.ts中的注释Rotate cache epoch only after successful commit.即只在事务成功提交后才轮换缓存纪元cache epoch。这种先落库、后失效的顺序保证了即使缓存失效操作本身失败此时仅打日志、不抛错数据库也已持久化不会出现缓存清了但数据没写进去的脏状态。读取路径getPromptByName则通过PromptService(prisma, redis, recordIncrement)走缓存查询形成写路径失效、读路径命中的完整闭环。2.2 事件溯源异步队列化失败不阻断主流程promptChangeEventSourcing.ts把每次变更包装成EntityChangeJob事件推入EntityChangeQueue源码const event { timestamp: new Date(), id: v4(), name: QueueJobs.EntityChangeJob, payload: { entityType: prompt-version, projectId: promptData.projectId, promptId: promptData.id, action, // created | updated | ... prompt: { ...promptData, prompt: jsonSchemaNullable.parse(...), config: jsonSchemaNullable.parse(...) }, ...(user ? { user } : {}), }, }; await EntityChangeQueue.getInstance()?.add(QueueName.EntityChangeQueue, event);调用方使用Promise.allSettled批量发布事件并且对单个事件失败只记 error 日志、不抛出——例如createPrompt中const eventResults await Promise.allSettled(eventPromises); for (const result of eventResults) { if (result.status rejected) { logger.error(Failed to publish prompt change event ..., result.reason); } }注释给出了明确意图一旦事务提交成功副作用副作用如 Webhook 事件失败不能把已持久化的 Prompt 报为失败否则调用方会重复创建新版本。这是典型的主流程与副作用解耦设计。三、createPrompt创建 Prompt 版本的主流程createPrompt()源码是变更层最核心的函数其签名如下export const createPrompt async ({ projectId, name, prompt, type PromptType.Text, labels [], config, createdBy, prisma, tags, commitMessage, user, }: CreatePromptParams) { ... }整个流程可以拆解为七个关键步骤3.1 类型一致性检查先查出该名称下最新的版本const latestPrompt await prisma.prompt.findFirst({ where: { projectId, name }, orderBy: [{ version: desc }], }); if (latestPrompt latestPrompt.type ! type) { throw new InvalidRequestError( Previous versions have different prompt type. Create a new prompt with a different name., ); }同一名称的 Prompt 版本必须保持同一类型Text / Chat避免同名不同型造成消费端解析混乱。3.2 变量与占位符命名冲突检查对于 Chat 类型type PromptType.Chat且prompt为数组会提取每条消息内容中的变量extractVariables与占位符extractPlaceholderNames若存在交集则拒绝创建const conflictingNames variables.filter((v) placeholders.includes(v)); if (conflictingNames.length 0) { throw new InvalidRequestError( Cannot create prompt, variables and placeholders must be unique, the following are not: ${conflictingNames.join(, )}, ); }3.3 标签与 tags 的默认行为新版本总是被标记为latestconst finalLabels [...labels, LATEST_PROMPT_LABEL]源码注释明确Newly created prompts are always labeled as latest。tags 继承若未显式传入 tags则沿用最新版本的 tagsconst finalTags [...new Set(tags ?? latestPrompt?.tags ?? [])]。3.4 依赖图解析通过parsePromptDependencyTags(prompt)解析 Prompt 内容中的langfusePrompt:...引用标签再调用PromptService.buildAndResolvePromptGraph构建依赖图解析失败会包装成InvalidRequestError抛出含具体错误信息确保引用的子 Prompt 存在且可解析。3.5 单事务内完成多写操作事务中按顺序组装了多种写操作prisma.prompt.create创建新版本version 为latestPrompt.version 1首个版本为 1为每个依赖创建promptDependency记录version 依赖写childVersionlabel 依赖写childLabel若带标签则调用removeLabelsFromPreviousPromptVersions把相同标签从旧版本上移除标签唯一性若 tags 发生变化则调用updatePromptTagsOnAllVersions把所有版本的 tags 同步为新值。其中第 3 步的标签迁移逻辑在 utils/updatePromptLabels.ts 中实现查出所有带目标标签的旧版本逐一生成prompt.update从 labels 数组中过滤掉待移除标签并返回被触碰的版本 id 列表供后续事件发布使用。3.6 并发冲突兜底整个事务包裹在try/catch中专门识别 Prisma 的P2002唯一约束冲突并核对冲突列是否为project_id name versionconst isPromptVersionConflict (error: unknown): boolean { if (!(error instanceof Prisma.PrismaClientKnownRequestError) || error.code ! P2002) return false; const target error.meta?.target; return Array.isArray(target) [project_id, name, version].every((c) target.includes(c)); };命中后抛出LangfuseConflictError提示A prompt version was created concurrently. Please retry.——这是对并发创建同名同版本场景的显式兜底。3.7 提交后副作用失效缓存 发布事件事务成功后依次执行缓存失效失败仅记日志和事件发布对createdPrompt发created事件对所有被触碰的旧版本发updated事件。3.8 补充能力duplicatePrompt 与 duplicateFolder同一文件还实现了两个批量复制能力duplicatePrompt支持单版本复制isSingleVersion为 true 时复制为新的 v1或整名称复制所有版本依赖全部复制旧 id 到新 id 通过oldToNewIdMap映射依赖关系同步重建复制后同样执行缓存失效并逐个发布created事件。duplicateFolder按sourcePath/前缀查找整个文件夹下的 Prompt含嵌套子目录复制到targetPath并支持rewritePromptReferences参数把内容中的依赖引用标签一并改写为新名称借助escapeSqlLikePattern做 LIKE 模式转义。若开启引用改写但只复制最新版本isSingleVersion会先校验被引用的依赖在目标文件夹中存在等价版本否则抛出明确的InvalidRequestError。四、updatePrompts标签更新的并发安全实现updatePrompt()源码专门处理标签更新其并发安全设计极具参考价值。4.1 行级锁SELECT ... FOR UPDATE函数在事务内先用原生 SQL 锁定目标行SELECT * FROM prompts WHERE project_id ${projectId} AND name ${promptName} AND version ${promptVersion} FOR UPDATE -- Important! This will lock the row for concurrent updates注释直白地强调这会把行锁住以应对并发更新。锁住后标签的读取-修改-写回labels: { set: ... }在并发场景下不会互相覆盖。4.2 标签移除的依赖保护更新后的标签集是new Set([...newLabels, ...prompt.labels])只增不减但代码仍保留了一道防御性检查若某标签确实被移除了会查询prompt_dependencies表中以child_label引用它的依赖一旦发现存在依赖就抛出错误并列出具体依赖者throw new InvalidRequestError( Other prompts are depending on the prompt label you are trying to remove:\n\n${dependencyMessages}\n\nPlease delete the dependent prompts first., );这保证了被其他 Prompt 按 label 引用的标签不可移除的引用完整性。4.3 标签唯一性与事件发布随后同样调用removeLabelsFromPreviousPromptVersions将新标签从旧版本剥离保证同一名称下标签唯一在同一事务内完成移除旧标签 更新目标版本。提交后执行缓存失效并对所有被触碰的版本发布updated事件。源码注释还特别说明由于该函数只处理标签变更、内容不变Webhook 无需 before 状态因此事件中 before 传undefined。五、读取路径getPromptByName 与 getPromptsMetaREADME 将getPromptByName()和getPromptsMeta()也纳入本目录统一管理二者的共同点是读取也必须经过统一封装缓存、默认标签、鉴权。5.1 getPromptByNameversion/label 二选一默认 productiongetPromptByName.ts 的逻辑非常清晰version与label同时传入直接抛InvalidRequestError(Cannot specify both version and label)传了version就按版本精确取传了label就按标签取什么都没传默认取PRODUCTION_LABELproduction——这是 Langfuse 保证线上稳定版本语义的关键默认值。函数签名中的resolve参数控制是否解析依赖为false时返回未解析的原始 Prompt不展开langfusePrompt:...引用为true默认时返回已解析完整内容的版本。5.2 getPromptsMeta聚合查询 稳定分页getPromptsMeta.ts 使用单条 SQL 完成按名称聚合各版本的元信息查询array_agg(DISTINCT p.version)汇总版本号数组array_agg(DISTINCT label) FILTER (WHERE label IS NOT NULL)汇总标签并用COALESCE(..., {}::text[])保证无标签时返回空数组MAX(p.updated_at)作为lastUpdatedAt子查询latest按version DESC取最新版本的type与config。分页采用ORDER BY p.name ... LIMIT ${limit} OFFSET ${limit * (page - 1)}并单独执行COUNT(DISTINCT p.name)计算总页数。响应同时返回meta与pagination两个同构字段源码注释说明这是为兼容最初发布/v2/prompts时不符合 API 规范的结构而保留的关联 issue #2068属于向后兼容的刻意设计。过滤条件通过统一的tableColumnsToSqlFilterAndPrefix(filters, promptsTableCols, prompts)生成支持name等值、version数字等值、label数组 any-of、tag数组 any-of、fromUpdatedAt/toUpdatedAt时间区间等筛选。六、deletePrompt删除时的依赖保护与 latest 重挂虽然 README 函数清单未列出但 deletePrompt.ts 与createPrompt等同样位于变更操作层其一致性逻辑值得补充说明依赖检查查询prompt_dependencies中所有以该名称为child_name的依赖再结合本次删除的版本号集合与删除后仍存在的版本计算真正会断裂的依赖——删除指定版本时若该版本被引用则阻断删除按 label 引用的版本时若删除后没有任何剩余版本保留该标签则阻断。阻断时同样抛出带依赖清单的InvalidRequestError。latest 重挂如果删除的版本中带latest标签且删除后没有任何剩余版本带latest则把latest自动重新附着到剩余的最高版本上保持latest 始终存在的不变量。先提交、后失效deleteMany成功后才调用promptService.invalidateCache({ projectId })轮换缓存纪元。七、名称与标签校验规则从常量到 SchemaREADME 将校验规则指向 packages/shared/src/features/prompts/validation.ts该 Schema 被 API、tRPC 与客户端三端共用是名称合法性的唯一事实来源。7.1 PromptNameSchema 的三层约束export const PromptNameSchema withFolderPathValidation( StringNoHTMLNonEmpty.regex( PROMPT_NAME_PIPE_RESTRICTION_REGEX, // /^[^|]*$/ PROMPT_NAME_PIPE_RESTRICTION_ERROR, // Prompt name cannot contain | character ), ).refine( (name) !(RESERVED_PROMPT_NAMES as readonly string[]).includes(name), { error: (issue) Prompt name cannot be ${issue.input} }, );管道符限制名称不能包含|常量PROMPT_NAME_PIPE_RESTRICTION_REGEX /^[^|]*$/原因注释为pipe character is used for prompt composition——|是 Prompt 组合引用语法的保留字符文件夹路径校验通过withFolderPathValidation约束/用法不允许以/开头或结尾、不允许连续//见测试保留名称拦截精确命中保留名时拒绝但作为文件夹段或叶子段时仍允许例如metrics/foo、folder/new均合法详见validation.test.ts中的分组断言。7.2 保留名称清单packages/shared/src/features/prompts/constants.ts中定义了保留名称export const RESERVED_PROMPT_NAMES [new, metrics, prompt-detail] as const;原因是这些名称对应/prompts/[[...folder]]catch-all 路由下的静态页面new、metrics、prompt-detailNext.js 静态路由优先于 catch-all 解析同名 Prompt 的链接会错误渲染到静态页。因此只拦截精确单段名称不误伤folder/metrics这类正常路径。7.3 标签与长度约束同一文件还定义了其他关键常量常量值说明PRODUCTION_LABELproduction生产标签读取默认值LATEST_PROMPT_LABELlatest最新版本标签新建即自动附加PROMPT_NAME_MAX_LENGTH255名称最大长度COMMIT_MESSAGE_MAX_LENGTH500提交说明最大长度PROMPT_LABEL_MAX_LENGTH36标签最大长度PROMPT_LABEL_REGEX/^[a-z0-9_\-.]$/标签必须为小写字母数字可含_、-、.7.4 测试佐证validation.test.ts 用 vitest 参数化用例逐一验证了上述规则保留名称含首尾空白 trim 后的变体一律拒绝${name}/foo与folder/${name}一律放行a|b、/a、a/、a//b、空字符串全部拒绝合法名称my-prompt、metrics-v2、folder/sub-folder/prompt全部通过并 trim 空白。这些用例既是规则的回归保护也是理解 Schema 行为最直接的注释。八、实践建议与注意事项结合上述源码分析对 Langfuse Prompts 模块的二次开发或运维可提炼出以下要点新增任何 Prompt 数据操作都必须落在actions/目录否则会绕过缓存失效读旧数据、事件溯源Webhook 丢失与标签唯一性约束直接破坏一致性。这是 README 中最核心、不可妥协的纪律。写操作优先考虑事务 行锁updatePrompt的SELECT ... FOR UPDATE是标签并发更新的正确姿势createPrompt则依赖唯一约束冲突检测P2002 列核对兜底并发创建。标签是可移动的指针latest、production语义由标签承载任何创建、更新、删除操作都必须维护标签唯一 latest 始终存在两个不变量。副作用与主流程解耦缓存失效与事件发布均在事务提交后进行且失败只记日志不抛错避免数据已写入却报错导致的重复写入。名称即路由命名时要避开new、metrics、prompt-detail三个保留名且不能含|文件夹式命名如folder/sub-folder/prompt受支持但注意version、label二选一查询的 API 语义。总结web/src/features/prompts/server/actions/README.md用极简的文字定义了一套高一致性的 Prompt 变更工程规范。从源码看这套规范背后是Redis 缓存纪元轮换、EntityChangeQueue 异步事件溯源、标签唯一性迁移、FOR UPDATE行锁、依赖图解析与唯一约束冲突兜底六个机制的协同工作。理解为什么禁止直接 Prisma 调用这个问题就等于理解了 Langfuse Prompts 在并发、缓存与审计三个维度上的全部设计取舍。对于希望深入 Langfuse 源码或在其上构建 Prompt 管理能力的开发者actions/目录连同packages/shared/src/features/prompts/下的校验与常量定义是最值得精读的入口。【免费下载链接】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），仅供参考