Langfuse In-App Agent 同步机制：Skills 目录与 System Prompt 的同步脚本实战指南

Langfuse In-App Agent 同步机制Skills 目录与 System Prompt 的同步脚本实战指南【免费下载链接】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 开源仓库中scripts/in-app-agent/目录下的同步工具链系统讲解两条核心同步链路基于repo/langfuse-skills包的 Skill 目录同步sync/sync:check以及基于sync-prompt.sh的 In-App Agent 系统提示词System Prompt跨云区域同步。读完本文你将掌握 Langfuse 中技能目录与托管提示词的完整同步流程、种子数据写入原理、公共 API 手动同步与生产环境校验方法能够直接复用于自己的 Langfuse 部署与二次开发。一、同步机制总览Agent 运行时需要什么Langfuse 的 In-App Agent应用内 AI 助手Langfuse Assistant运行时依赖两类可更新资产Langfuse Skills 技能目录一组面向 Coding Agent如 Claude、Codex的 Markdown 技能文档随上游langfuse/skills仓库演进需要定期同步到本仓库的生成产物中系统提示词System Prompt定义 Agent 身份、行为规则、工具使用偏好、权限边界与数据作用域的模板文本以 Langfuse 托管 Prompt版本化、可打标签的形式供 Agent 在运行时加载。这两条链路的维护脚本与文档全部位于 scripts/in-app-agent/README.md其中 Skill 同步由repo/langfuse-skills包内的脚本实现Prompt 同步则分为本地种子数据写入与跨云区域手动同步两条路径。下面分别展开。二、Skill 同步将上游技能目录固化进仓库2.1 技能目录的存放位置通用 Langfuse 技能目录及其同步脚本位于repo/langfuse-skills包内即 packages/langfuse-skills。该包的核心结构如下src/index.js/src/index.d.ts对外导出LANGFUSE_SKILLS只读数组每个元素为{ name, description, instructions }三元组src/generated/skills.js由同步脚本自动生成的技能目录文件头明确标注generated ... Do not edit it manuallyscripts/sync-skills.mjs同步脚本本体package.json定义了sync与sync:check两个 npm script。2.2 触发同步与校验执行同步拉取上游并覆写生成文件pnpm --filter repo/langfuse-skills run sync执行校验仅比对生成文件与上游是否一致不修改任何文件pnpm --filter repo/langfuse-skills run sync:check两个命令分别对应 package.json 中的sync: node scripts/sync-skills.mjs与sync:check: node scripts/sync-skills.mjs --check。在 CI 或提交前校验中sync:check常被用作生成产物是否与上游漂移的门禁一旦本地生成文件与上游不一致脚本会以非零退出码失败并报错Generated skill catalog differs from upstream或Generated skill catalog is missing。2.3 同步脚本的底层逻辑从 scripts/sync-skills.mjs 的源码可以看到完整的数据流确定数据源通过 GitHub API 拉取langfuse/skills仓库中skills/langfuse/references目录下的 Markdown 文件列表分支通过环境变量LANGFUSE_SKILLS_REF控制默认main若设置了GITHUB_TOKEN环境变量请求会附带 Bearer Token 以提升 API 配额解析每个技能文件parseSkill函数解析 Markdown 的 frontmatter要求存在name与description字段支持单引号包裹值的剥离frontmatter 之后的正文作为instructions三者构成一个完整的技能条目渲染生成模块将技能数组序列化后用 Prettierbabel parser格式化写入 src/generated/skills.js文件头自动标注生成来源提醒开发者勿手改--check模式读取已存在的生成文件并与期望内容逐字节比对不一致或文件缺失即抛错退出一致则打印Generated Langfuse skills are in sync: ...并列出技能名。从生成的技能目录可见当前包含langfuse-ci-cd、langfuse-cli、langfuse-dataset-construction、langfuse-error-analysis、langfuse-observability、langfuse-judge-calibration、langfuse-prompt-engineering、langfuse-prompt-migration、langfuse-sdk-upgrade、langfuse-setting-up-evals、langfuse-skill-feedback等技能覆盖 CI/CD 门禁、CLI 参考、数据集构建、错误分析、可观测性、评测搭建等 Coding Agent 高频任务。2.4 技能目录如何被 Agent 运行时消费同步进仓库的技能目录并不是摆设而是被 In-App Agent 运行时直接装载。见 worker/src/features/in-app-agent/runtime/skills.tsimport { createSkill } from mastra/core/skills; import { LANGFUSE_SKILLS } from repo/langfuse-skills; export const LANGFUSE_IN_APP_AGENT_SKILLS LANGFUSE_SKILLS.map((skill) createSkill(skill), );即运行时通过 Mastra 的createSkill将目录中的每个技能包装为可被 Agent 调用的 Skill 工具。因此sync命令的本质是把上游技能的最新内容同步为运行时可直接消费的仓库产物保持这条链路畅通Agent 才能始终使用最新的技能指令。三、Prompt 同步System Prompt 的种子写入3.1 提示词模板的规范位置In-App Agent 的规范系统提示词位于 packages/shared/src/in-app-agent/server/systemPrompt.ts导出的常量为IN_APP_AGENT_SYSTEM_PROMPT_TEMPLATE。这是一个带 XML 标签分区的模板包含以下语义区块区块职责identityAgent 身份You are an assistant called Langfuse Assistantbehavioral_rules行为守则不确定时直说、回答前先检索 Langfuse 文档、不评价自身行为、简洁克制等tools工具偏好优先使用 Langfuse MCP 工具、用 docs 工具查文档、按需选用 Langfuse skillscode_generation代码生成边界推荐引导用户使用自有环境的 Coding Agentdata_scope数据作用域默认排除内部环境占位符{{sidebarHiddenEnvironments}}data_model数据模型traces/observations 关系、指标聚合位置permissions权限边界涉及变更的工具需用户显式确认user_navigation页面导航建议占位符{{redirectToolName}}{{sandboxFilesystem}}沙箱文件系统上下文占位符源码注释还揭示了一个关键设计时钟、用户与屏幕上下文是按每次模型调用追加的不编译进模板从而避免使工具 系统提示的缓存前缀失效。模板中的{{sidebarHiddenEnvironments}}、{{redirectToolName}}、{{sandboxFilesystem}}均为运行时注入的占位变量。3.2 本地 Seeder 如何写入提示词本地 Postgres 种子脚本会导入上述模板模块并在种子项目中创建名为in-app-agent-system-prompt的文本类型 Prompt。核心逻辑位于 seed-postgres.ts 的upsertInAppAgentSystemPrompt函数项目种子项目 ID 为7a88fb47-b4e2-43b8-a06c-a5ce950dc53a名称与类型name: in-app-agent-system-prompttype: text标签labels: [production, latest]即生产可用 最新版本双标签运行时可按标签稳定取用版本version: 1使用 Prisma 的prompt.upsert按projectId name version唯一键写入首次创建后续更新则刷新prompt内容与标签。这意味着本地开发环境与 PR 预览环境无需手动操作即可获得与生产一致的 Agent 系统提示词。四、手动同步跨云区域发布 System Prompt4.1 适用场景与前置条件当需要在 Langfuse Cloud 各区域EU / US / JP / HIPAA通过公共 API 创建该提示词时使用 scripts/in-app-agent/sync-prompt.sh。其关键语义是幂等新增版本如果某个区域已存在同名 Prompt同一次 API 调用会改为新增一个版本而不是覆盖历史版本从而保留完整的版本演进记录。运行脚本前需要为所有目标云区域设置项目凭据公钥 私钥逐一导出环境变量export LANGFUSE_AI_FEATURES_EU_PUBLIC_KEYpk-lf-... export LANGFUSE_AI_FEATURES_EU_SECRET_KEYsk-lf-... export LANGFUSE_AI_FEATURES_US_PUBLIC_KEYpk-lf-... export LANGFUSE_AI_FEATURES_US_SECRET_KEYsk-lf-... export LANGFUSE_AI_FEATURES_JP_PUBLIC_KEYpk-lf-... export LANGFUSE_AI_FEATURES_JP_SECRET_KEYsk-lf-... export LANGFUSE_AI_FEATURES_HIPAA_PUBLIC_KEYpk-lf-... export LANGFUSE_AI_FEATURES_HIPAA_SECRET_KEYsk-lf-... ./scripts/in-app-agent/sync-prompt.sh也可以把上述 export 语句移入.env文件在子 shell 中加载后运行避免污染当前 shell 环境(source .env; ./sync-prompt.sh)脚本假设curl与jq已安装且位于PATH中两者分别承担 HTTP 请求与 JSON 构建。4.2 脚本执行流程源码级拆解对照 sync-prompt.sh 源码脚本的核心流程如下定位模板文件脚本基于自身路径反推仓库根目录读取packages/shared/src/in-app-agent/server/systemPrompt.ts若文件缺失立即报错退出set -euo pipefail保证任何一步失败即中止加载提示词内容模板是纯可擦除 TypeScriptplain erasable TS脚本借助 Node 原生的类型擦除能力直接import()该.ts模块无需构建步骤取IN_APP_AGENT_SYSTEM_PROMPT_TEMPLATE导出值作为提示词正文构建请求体用jq -n构造 POST 请求 JSON{ name: in-app-agent-system-prompt, type: text, prompt: 模板正文, labels: [production, latest], commitMessage: Sync in-app agent system prompt }预检阶段Preflight脚本定义区域矩阵REGIONS(STAGING EU US JP HIPAA)与对应BASE_URLSstaging.langfuse.com、cloud.langfuse.com、us.cloud.langfuse.com、jp.cloud.langfuse.com、hipaa.cloud.langfuse.com。对每个区域检查对应公钥/私钥环境变量是否已设置缺失则记录预检错误用curl --user 公钥:私钥发起对${BASE_URL}/api/public/v2/prompts/${PROMPT_NAME}的访问探测仅当返回 200存在或 404不存在才视为通过其余状态码如 401/403记录为预检错误若存在任何预检错误脚本打印Preflight failed; no regions synced.并整体退出保证要么全部通过要么一个都不同步逐区域确认并同步预检全部通过后脚本对每个区域执行read -r -p交互式确认Create or add a new version of in-app-agent-system-prompt in REGION (BASE_URL)? [y/N]只有输入y/yes才继续确认后向${BASE_URL}/api/public/v2/prompts发送POSTBasic Auth Content-Type: application/json--fail让任何非 2xx 响应直接导致脚本失败汇总结果脚本统计SYNCED_REGIONS数组最终打印Synced in-app-agent-system-prompt to regions: EU US ...若全部跳过则输出No regions synced.。值得强调的是先预检、后确认的两段式设计预检阶段不会写任何数据只验证凭据有效性、网络可达性与区域配置避免在确认前因凭据错误而部分写入真正的写入发生在用户逐区域确认之后防止误操作。五、同步结果的验证同步完成后可用 Langfuse CLI 拉取指定标签的 Prompt 进行验证。以 EU 区域为例LANGFUSE_PUBLIC_KEY$LANGFUSE_AI_FEATURES_EU_PUBLIC_KEY \ LANGFUSE_SECRET_KEY$LANGFUSE_AI_FEATURES_EU_SECRET_KEY \ LANGFUSE_BASE_URLhttps://cloud.langfuse.com \ langfuse api prompts get in-app-agent-system-prompt --label production校验其他区域时将三个环境变量替换为对应区域的公钥、私钥与 Base URL 即可区域Base URLEUhttps://cloud.langfuse.comUShttps://us.cloud.langfuse.comJPhttps://jp.cloud.langfuse.comHIPAAhttps://hipaa.cloud.langfuse.com该命令通过--label production拉取生产标签下的当前版本可确认远端 Prompt 内容与 systemPrompt.ts 模板保持一致——这正是源码注释中强调的约束保持模板与托管 Prompt 同步因为生产运行时从 Prompt 管理加载提示词而本地开发与种子数据使用该模板。六、日常维护清单综合上述链路In-App Agent 资产的日常维护可归结为三个动作技能目录更新上游langfuse/skills有更新时执行pnpm --filter repo/langfuse-skills run sync重新生成 skills.js 并提交CI 中用sync:check防止漂移提示词模板更新修改 systemPrompt.ts 后本地开发由 Seeder 自动 upsert见 seed-postgres.ts云端各区域则通过 sync-prompt.sh 手动发布新版本发布后校验用langfuse api prompts get ... --label production逐区域核对生产标签下的 Prompt 内容与版本。通过模板单一来源Single Source of Truth 生成产物 托管 Prompt三层结构Langfuse 既保证了 Agent 运行时资产的版本可控与可回滚每次同步生成新版本而非覆盖又让本地开发、预览环境与多区域云环境之间的资产保持一致这正是 scripts/in-app-agent/README.md 所描述的同步体系的核心价值。【免费下载链接】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），仅供参考