ratel-langfuse-analyze

/ratel-langfuse-analyze — 读取实时追踪记录，提出修复建议

从 Langfuse MCP 服务拉取汇总数据和异常追踪记录，与已知 Agent 故障模式目录进行模式匹配，并撰写一份客户本周即可着手处理的发现报告。分为两组输出：Ratel 相关机会（可以集成或深化 Ratel 的地方）以及一般性易见成效（任何人都能修复的问题）。

一般性发现不是凑数的——它们是我们赢得信任的方式。如果顾问总是只推荐自己的产品，看起来就像销售人员。我们不是这样。

优质输出的标准

符合以下条件的发现才算优质：

1. 至少引用一个追踪 ID或已保存的筛选 URL，方便客户自行核实。
2. 说明应该怎么做，而不只是指出问题。含糊的发现（“错误率很高”）会浪费合作伙伴的时间。
3. 用一句话说明修复为何重要，让客户的 PM 看得懂。
4. 标注为 Ratel 或 generic。混在一起会掩盖价值所在。
5. 如果发现与 Ratel 相关，要引用能解决问题的 Ratel 版本（当前：v0.1.6 系列；未来：从 ratel-observability-assessment/references/ratel-value-map.md 获取）。

以下情况说明发现质量不佳：

• 只是复述仪表板内容（“p95 延迟为 4.2s”）。仪表板已经显示了这些信息。
• 使用“可能可以改进”或“也许值得调查”等模糊措辞。要么是发现，要么不是。
• 为了凑数而编造。

工作流

第 1 步 — 验证 MCP 是否可用

确认 Langfuse MCP 服务已注册且可访问：

# Inspect Claude Code's MCP config OR use the ratel-mcp gateway's search_capabilities
# to confirm Langfuse tools are present.

如果无法访问，立即失败：

未检测到 Langfuse MCP 服务。请先运行 /ratel-langfuse-integrate（或按照其设置部分手动接入）。

没有 MCP 访问权限时不要继续。没有实时数据，这项技能毫无用处。

第 2 步 — 确定时间范围

询问用户（或接受调用时提供的参数）：

• 时间范围（默认：过去 24 小时或最近 100 条追踪记录，以较少者为准）。
• 可选筛选条件（user_id、session_id、trace_name、env）。
• 可选的 Ratel 功能标记组（例如，feature_flag=tool_pool=ratel）——运行 A/B 合作项目时很有用。

在聊天中说明选定的范围，让客户知道分析了哪些数据。

第 3 步 — 拉取汇总数据

使用 references/mcp-query-patterns.md 中的查询，按顺序拉取：

1. 时间范围内的追踪记录数、p50/p95/p99 延迟、总成本和错误率。
2. 按延迟、成本和 observation 数量排序的前 10 条追踪记录。
3. 调用次数最多的前 10 个工具，以及出错次数最多的前 10 个工具。
4. 当前使用的所有评分名称对应的评分分布。
5. 按 feature_flag 划分的数据（如果设置了任何功能标记标签）。

这为后续分析提供基础，也会揭示简单但重要的发现（例如“80% 的追踪记录缺少 session_id”——通过一次汇总查询即可发现）。

第 4 步 — 深入检查异常值

获取以下记录的完整追踪内容：

• 最慢的一条追踪记录。
• 成本最高的一条追踪记录。
• “每条追踪记录的错误数”排名靠前的一条记录。
• 评分最低的会话（如果存在评分）。
• 从典型延迟区间随机选取两条追踪记录作为对照。

阅读输入和输出。不要只看结构——要了解 Agent 实际做了什么。最有价值的发现来自阅读对话记录。

第 5 步 — 对照发现目录进行模式匹配

打开 ../ratel-observability-assessment/references/finding-catalog.md（与 ratel-langsmith-analyze 共用的中立目录）。逐一检查每种模式：客户发出的数据是否符合其检测启发式？如果符合，就使用该模式的模板生成一条发现。

不要不加判断地逐一检查目录——如果系统中没有 Ratel，就跳过整个 Ratel 部分。如果没有评分，就跳过与评分相关的模式。目录是筛选工具，不是检查清单。

第 6 步 — 生成发现

每项发现都遵循以下模板：

### F<N>. <one-line title>

- **Severity**: high | medium | low
- **Category**: ratel | generic
- **Evidence**: trace ids / filter URL / aggregate value
- **Why this matters**: <one sentence>
- **Recommended action**: <concrete next step the customer can take this week>
- **Solved by Ratel?**: <no | yes, v0.1.X — feature name> (only for ratel category)

严重性标准：

• high — 影响超过 10% 的流量，或存在会导致仪表板无法正常工作的任何数据质量问题。
• medium — 影响有意义的一部分，但并非关键。
• low — 已观察到，但影响较小；值得提及一次。

在每个类别（ratel、通用）内按严重性从高到低对发现分组。每个类别最多列出 10 项发现，以确保报告具有可操作性。超过 10 项时，写上“（还有 N 项发现已归入后续批次）”，并将其余内容收录到附录中。

第 7 步 — 撰写报告

输出到 <repo>/.ratel/langfuse-analysis-<YYYY-MM-DD>.md。报告会逐次累积（每次运行生成一份），不要覆盖以前的报告。该目录应与 /ratel-langfuse-integrate 写入的目录相同。

结构：

# Langfuse analysis — <date>

## Scope
- Window: <range>
- Filters: <list>
- Traces analysed: <n>
- Findings: <n total>, <n ratel>, <n generic>

## Aggregates at a glance
<3-5 bullets with the headline numbers>

## Findings — Ratel-flavored
<F1, F2, ... in severity order>

## Findings — Generic
<G1, G2, ... in severity order>

## Honest skip (if applicable)
<see honest skip path below>

## Appendix — raw query results
<the aggregates from step 3, formatted as tables>

在聊天中直接打印排名前 3 的发现（跨两个类别，按严重性从高到低），并各用一行概述。告知用户其余内容所在的文件路径。

诚实跳过的情况

如果数据确实很干净——错误率低于 1%、没有延迟异常值、没有缺少会话 ID 的问题、没有评分回退、没有工具漂移——则撰写一份简短报告说明这一点：

本周没有值得采取行动的发现。已分析 条追踪记录，时间范围为 ；总体健康状况在正常范围内。若流量增长超过 ，或部署了新的 Agent 版本，可以考虑再次运行分析。

这不代表失败——这本身就是一种有价值的信号。合作伙伴信任那些会在无事可做时如实告知的顾问。不要凭空捏造发现。 一份充斥噪声的报告，就足以让客户永远忽视之后的报告。

同样，如果流量太少，无法得出结论（时间范围内少于约 20 条追踪记录），也要如实说明：

时间范围内只有 条追踪记录。请在客户下一次有流量的版本发布或下一轮测试活动后重新运行。已附上汇总数据供参考，但未得出任何发现。

参考文件

• ../ratel-observability-assessment/references/finding-catalog.md — 权威的、与供应商无关的检测模式、建议修复方案和 Ratel 映射目录；与 ratel-langsmith-analyze 共用
• references/mcp-query-patterns.md — 经过验证的 Langfuse MCP 查询形式（汇总、深入分析、样本）；特定于 Langfuse，仅在本地使用