ratel-langfuse-integrate

/ratel-langfuse-integrate — 为 Agent 接入 Langfuse 覆盖范围和仪表板

像 Ratel 团队一样，将 Langfuse 接入客户的代码库，并规划仪表板，以证明它物有所值。一个技能，分为两部分：埋点接入（追踪应放在哪里、如何命名、如何设置）和仪表板构建规格（应构建哪些看板，包含哪些具体组件）。交付内容是计划。不要修改 Agent 代码，也不要调用 Langfuse API——客户会通过点击 Langfuse UI 来构建仪表板，这是有意为之。

这是可观测性流程中的 Langfuse 分支。通用技能 /ratel-observability-assessment 以供应商中立的方式决定应捕获什么、哪些仪表板重要，并检测供应商。当供应商为 Langfuse 时，它会将任务交给此技能，把计划转化为具体的 Langfuse 原语。后续跟进技能是 /ratel-langfuse-analyze：在追踪数据开始流入后，它会读取本计划产生的实时数据。

理念：追踪思维模型，而非调用图

常见的失败模式是“将每个函数都包装成一个 span”。这样生成的追踪虽然符合代码的调用图，却无法告诉你 Agent 试图做什么。当 Langfuse 追踪的结构符合一次交互的概念结构时，最有用：

• 追踪 = 一个对外有意义的工作单元（一次聊天交互、一个任务、一个 webhook）。如果一个请求包含多个 Agent 交互，就不应是“一次 HTTP 请求”；如果一次交互包含多次模型调用，就不应是“一次模型调用”。
• 观察项 = Agent 在该工作单元中执行的一个步骤。子 Agent 调用、工具调用、模型调用、检索步骤。嵌套时应体现委派关系，而非源文件布局。
• 会话 = 通过 session_id 关联的一组相关追踪。通常是用户对话、Agent 运行 ID 或任务关联 ID。

完整的原理仅在 ../ratel-observability-assessment/references/instrumentation-philosophy.md 中说明。词汇的 Langfuse 专属映射——即哪个通用概念对应哪个 Langfuse 原语、类型和键——详见 references/langfuse-mapping.md。

为什么要分成两组仪表板

此技能的仪表板部分始终会构建两组看板，因为合作初创公司希望从同一批数据中看到两种不同的故事：

1. “Ratel 正在推动指标改善”（Ratel 价值组）——Token 支出下降、检索质量提升、“找不到工具”错误减少、每个会话的成本降低。这些指标可以证明合作的价值。仅在已接入或计划接入 Ratel 时纳入。
2. “我们的 Agent 运行健康”（Agent 健康组）——延迟百分位数、各工具的错误率、会话放弃率、评分分布。无论是否使用 Ratel 都有用；它们能帮助客户自己的工程师发现自身的问题，从而建立信任。

只包含 Ratel 仪表板会显得像在推销；只包含 Agent 健康仪表板则像是忘了我们来这里的目的。只要涉及 Ratel，就应同时纳入两组。

工作流程

步骤 0 — 阅读上游可观测性评估（优先输入）

查找 <repo>/.ratel/ratel-observability-assessment.md——这是 /ratel-observability-assessment 的交付物。如果文件存在，它就是优先输入：读取其中检测到的技术栈、拓扑结构、供应商中立的插桩策略和推荐的仪表板列表。确认检测到的供应商是 Langfuse；如果文件写的是 LangSmith（或其他供应商），则停止并告知用户这是 Langfuse 技能——他们需要使用匹配的 *-integrate 技能。

如果文件存在，可以跳过步骤 1–2 中繁重的检测，直接进入渲染：直接使用其中的技术栈和拓扑结构，然后转到步骤 3。

如果文件不存在，不要直接拒绝。自行快速检测技术栈和供应商（步骤 1–2），并像构建仪表板需要统一术语一样，先询问几个问题，而不是拒绝：

1. 一轮聊天 / 一项任务的规范 Trace 名称是什么？
2. 正在使用（或计划使用）哪些 env、stack 和 agent_version 标签值？
3. Ratel 是否已通过任何方式进行插桩（网关、SDK 或计划中）？

拿到答案后继续。基于猜测术语构建的仪表板看起来正确，实际切换维度时却会出错。

步骤 1 — 检测技术栈

（如果上游评估已注明技术栈，则跳过。）读取清单文件，识别语言和框架。根据技术栈选择相应参考资料，了解特定模式。

# TypeScript / Node detection
test -f package.json && cat package.json | jq -r '.dependencies // {}, .devDependencies // {} | keys[]' | sort -u

# Python detection
test -f pyproject.toml && cat pyproject.toml | grep -A 200 '^\[' || true
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

将依赖映射到以下某个技术栈配置：

清单中的信号	技术栈	参考资料
ai、@ai-sdk/*	Vercel AI SDK	references/stack-vercel-ai-sdk.md
@mastra/core、直接调用 openai / @anthropic-ai/sdk 的手写循环	TypeScript 通用	references/stack-typescript-generic.md
langfuse + openai / anthropic / langchain / llama_index	Python 通用	references/stack-python-generic.md
langgraph、crewai、agno、autogen	Python Agentic	references/stack-python-agentic.md

如果信号有重叠（例如，既有 LangGraph supervisor，也在内部直接调用 OpenAI），则以 Agentic 参考资料为主，并在计划中注明混合技术栈的提示。

如果完全找不到 Agent 的入口（没有 LLM 客户端导入、Agent 框架或模型调用），请使用诚实跳过路径。

步骤 2 — 梳理 Agent 的拓扑结构

（如果上游评估已包含拓扑图，则跳过 / 复用。）启动一个 Explore Agent（非常小的代码库也可以直接自行梳理），并引用文件路径，回答以下四个问题：

1. 一轮对话从哪里开始？——入口点：HTTP 处理程序、CLI 子命令、队列消费者、聊天平台 Webhook。session_id 就从这里开始。
2. Agent 单元有哪些？——supervisor 函数、子 Agent 工厂、按角色划分的循环。任何接收用户消息并返回响应的单元，都属于 Agent 单元。这些单元将成为 Trace 边界。
3. 工具在哪里定义和调用？——工具注册表（tools: [...]）、@tool 装饰器、MCP 服务接线。每个工具都需要呈现为类型为 tool 的 observation（Langfuse v4）。
4. 子 Agent 在哪里将控制权移交给其他子 Agent？——supervisor → worker、并行扇出、图节点转换。这些位置需要使用 propagate_attributes()（或框架等效机制），确保会话 / 用户 / 标签上下文跨边界保留。

在计划中用一个简短的拓扑图（ASCII 或 Mermaid）记录这些信息。无需面面俱到——只要能让客户在实施过程中对照一张完整图示即可。

步骤 3 — 呈现 Langfuse 命名／映射表

阅读 references/langfuse-mapping.md，并将其应用到拓扑中：

• 每个有外部意义的单元使用一个 trace 名称（chat-turn、summarize-thread、nightly-research-job）。
• 每个角色使用一个 observation 名称（supervisor、research-agent、writer-agent），每个工具使用一个 observation 名称（tool.<tool-id>）；将模型调用记录为 llm.<model-shortname> generations。
• 在 trace 上设置 session_id 和 user_id，尽早设置并向下传递（propagate_attributes(...)）。
• Tags：堆栈标识符、环境（dev／staging／prod）、Agent 版本，以及适用时的功能标志分组。
• Metadata 键：使用一组小而统一的键，以便仪表板进行透视 — agent_role、tool_id、model_id、prompt_version、user_tier、gateway_origin（存在 Ratel 时）。

计划应在一张表格中列出引入的每个名称／tag／metadata 键，供客户粘贴到共享文档中，并引用 references/langfuse-mapping.md。仪表板规范（步骤 5）和 /ratel-langfuse-analyze 都会读取此表；如果缺少此表，它们就无法运行。该映射会将供应商中立的约定映射到 Langfuse 原语，详见 ../ratel-observability-assessment/references/semantic-conventions.md — 请勿重新推导这些规则。

步骤 4 — 说明逐文件的埋点变更

对于每个需要接线的文件，请引用堆栈参考中的相应模式（references/stack-*.md），不要重新推导。每项应包含：文件路径、需要包装的内容、使用的 observation 类型（span／tool／generation），以及根据步骤 3 的表格附加的名称／tags／metadata。

步骤 5 — 规划仪表板（两组）

打开 references/langfuse-value-map.md、../ratel-observability-assessment/references/general-agent-dashboards.md 和 references/widget-cheatsheet.md。选出符合该客户实际埋点情况的子集。

默认选择：

• Ratel 价值组（仅当已部署或即将部署 Ratel 时）：Token Cost & Savings、Retrieval Quality、Gateway Origin Split、Upstream Health、Skill Retrieval Health（随 v0.1.6 系列发布的技能）。仅当客户使用具备该功能的 Ratel 预发布版本，或已明确承诺采用该功能时，才添加有条件的路线图项目（例如 v0.1.9 的 Suggestion Adoption）。名称和组件规格见 references/langfuse-value-map.md。
• Agent 健康组：Latency & Cost Overview、Error Surface、Tool Usage、Session Quality、Model & Prompt Drift。见 ../ratel-observability-assessment/references/general-agent-dashboards.md。

每个仪表板章节按以下顺序编写：

1. 名称 — 简短、以行动为导向（Token Cost & Savings，而不是 Dashboard 1）。
2. 重要性 — 用一段通俗英文说明其重要性；客户的 PM 应能判断它是否适合自己。
3. 必需数据 — 所依赖的跟踪名称、观察类型、标签和元数据键。第 3 步表格中缺少的任何内容，都是此处要列出的待办阻塞项。
4. 组件 — 对每个组件，填写 references/widget-cheatsheet.md 中的五个字段：数据来源（traces / observations / scores）；指标；聚合方式；维度；筛选条件；以及可视化方式。
5. 透视 / 下钻 — 说明仪表板显示异常时应点击什么，以及下钻入口所在位置（仪表板建好后，客户可粘贴一次的已保存跟踪筛选 URL）。
6. 路线图脚注（仅适用于 Ratel 仪表板）— 如果仪表板能从尚未发布的 Ratel 功能中受益，请注明功能名称和目标版本。沿用 ../ratel-observability-assessment/references/ratel-value-map.md 中的版本映射，确保内容保持最新。

如果支撑数据尚未埋点，就删除相应仪表板。宁可跳过，也不要造假。

步骤 6 — 确定 Ratel 感知型钩子（仅当已部署或即将部署 Ratel 时）

检查清单中的任意位置是否出现 @ratel-ai/sdk、Python ratel-ai 包、ratel-ai-core 或 ratel-mcp / @ratel-ai/mcp-server 包。如果有，或者客户承诺在本次合作中引入 Ratel，请阅读 references/ratel-hooks.md，并在计划中添加一个章节，涵盖：

• 将每个 Ratel 跟踪事件映射到 Langfuse 观察项（search → 名为 ratel.search_capabilities、观察类型为 tool 的观察项，skill_search → ratel.skill_search，get_skill_content → ratel.get_skill_content，InvokeStart/InvokeEnd → 名为 ratel.invoke_tool、观察类型为 tool 的观察项，等等）。名称已在 references/langfuse-value-map.md 中预留。
• 每个观察项所需的元数据：gateway_origin（direct 与 agent）、top_k、hit_count、replace_mode、最高匹配项的分数、延迟。
• “前 / 后”标注策略，以便客户在接入 Ratel 后运行 A/B 对比（feature_flag 标签划分就是 A/B 对比的入口）。

如果未部署 Ratel，且没有引入计划，请完全跳过本章节。不要在客户拥有的文档中预先塞入 Ratel 的销售话术——保持计划真实。

第 7 步 — 编写计划

将计划写入 <repo>/.ratel/ratel-langfuse-integrate.md（如果 .ratel/ 目录不存在，则创建该目录；如果仓库已采用不同的文档规范，则请用户确认路径）。

计划必须按以下顺序包含：

1. 摘要 — 用一段话说明：检测到的技术栈、Agent 拓扑、已完成的埋点（如有）、本计划新增的内容（接线 + 仪表板），以及每组仪表板的数量。
2. 设置 — SDK 安装命令、环境变量、Langfuse MCP 服务注册步骤（适用于客户的 Claude Code / Cursor），以及一段可粘贴并验证的可用“hello trace”代码片段。
3. 拓扑 — 第 2 步中的图示。
4. Langfuse 命名／映射表 — 第 3 步中的表格，并引用 references/langfuse-mapping.md。
5. 逐文件埋点改动 — 第 4 步中的内容，并引用对应的 references/stack-*.md。
6. 仪表板构建规格 — 第 5 步中的两组（Ratel-value + agent-health），并引用 references/langfuse-value-map.md、../ratel-observability-assessment/references/general-agent-dashboards.md 和 references/widget-cheatsheet.md。
7. Ratel 钩子（按条件决定，依据第 6 步），并引用 references/ratel-hooks.md。
8. 验证清单 — 从 references/verification-checklist.md 复制：客户完成埋点后可勾选的六个项目。
9. 暂不纳入范围 — 客户采用路线图中 v<X.Y.Z> 版本的 Ratel 功能后才会添加的仪表板；以及需要目前尚无数据的仪表板。

在聊天中直接打印目录——章节列表，以及编号的仪表板列表，每项附上一句“为何重要”的说明——并告知用户文件路径。不要在聊天中粘贴完整计划正文或完整的组件规格；文件才是交付物。

告诉用户，追踪记录开始流入后，下一步是运行 /ratel-langfuse-analyze，读取实时数据并提出修复建议。

诚实跳过路径

以下情况需要跳过——立即停止并说明原因；绝不要捏造交付物：

1. 未检测到 Agent 入口。 如果第 1 步之后仍找不到任何 LLM 客户端导入、Agent 循环或模型调用，则停止。不要编写计划。告诉用户：

   未检测到 Agent 入口 — 仅检查了 <files looked at>。如果此代码库中的 Agent 代码位于非标准位置，请告诉我位置，我会重新检查。

   在非 Agent 代码库中强行制定埋点计划，只会产生无用文档并损害合作伙伴的信任。

2. 没有对应参考资料的技术栈（例如 Ruby、Go 或小众框架）。仍然要生成计划，但需将特定于技术栈的章节标注为“参考 Python 通用参考资料类比编写”，并询问用户是否要启动后续工作来编写新的参考资料。不要假装有把握。

3. 客户只想要 Ratel-value 仪表板，且没有使用 Ratel。 Ratel 仪表板至少需要接通网关路径。建议先进行小规模 Ratel 试点（仅接入网关约需半天），再设计依赖于它的仪表板。不要把 Ratel 钩子塞进未使用 Ratel 的 Agent 中——改为呈现 agent-health 组，并注明 Ratel-value 组因尚未采用 Ratel 而受阻。

4. 需要埋点／仪表板，但还没有实时数据。 生成计划，但将每个仪表板标记为“受阻：无数据 — 首批生产流量到达后重新评估”。空仪表板会打击团队士气。

参考文件

• references/stack-vercel-ai-sdk.md
• references/stack-typescript-generic.md
• references/stack-python-generic.md
• references/stack-python-agentic.md
• references/langfuse-mapping.md — 通用语义约定在 Langfuse 中的呈现方式
• references/langfuse-value-map.md — Ratel 观测名称 + Ratel 值仪表板小组件规格
• references/ratel-hooks.md — Ratel 事件 → Langfuse 观测
• references/widget-cheatsheet.md — Langfuse v4 小组件术语
• references/verification-checklist.md

共享的、与供应商无关的参考资料（由 /ratel-observability-assessment 管理，通过链接引用，不重复）：

• ../ratel-observability-assessment/references/instrumentation-philosophy.md
• ../ratel-observability-assessment/references/semantic-conventions.md
• ../ratel-observability-assessment/references/general-agent-dashboards.md
• ../ratel-observability-assessment/references/ratel-value-map.md