ratel-langsmith-analyze

/ratel-langsmith-analyze — 读取实时运行记录并提出修复方案

从 LangSmith MCP 服务（或作为备用方案的 langsmith SDK）获取聚合数据和异常运行记录，与已知 Agent 故障模式目录进行模式匹配，并编写一份客户本周即可采取行动的发现报告。分为两组输出：Ratel 相关机会（我们可以集成或深化 Ratel 的领域）和一般的易着手改进项（任何人都可以修复）。

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

LangSmith 的数据模型是 项目 → 追踪 → 运行树。追踪是一个根运行及其子运行树；每个运行的 run_type 为 chain、llm、tool、retriever、parser、prompt 或 embedding。会话／对话通过设置在运行上的 thread_id／session_id 元数据键来传递。请牢记此模型：Langfuse 意义上的“追踪”在这里对应根运行，“观测”对应子运行。

好的输出应是什么样

一条发现符合以下条件才算好：

1. 至少引用一个运行 ID或追踪 ID，或一个已保存的筛选 URL／筛选字符串，以便客户自行验证。
2. 说明要做什么，而不只是指出问题。模糊的发现（“错误率很高”）会浪费合作伙伴的时间。
3. 用一句客户的 PM 看得懂的话，说明此修复为何重要。
4. 标记为 Ratel 或 generic。将两者混在一起会掩盖价值主张。
5. 如果是 Ratel 相关发现，要注明可解决该问题的 Ratel 版本——从共享文件 ratel-value-map.md 中获取概念信号 → 版本映射（与供应商无关的事实来源；当前基线为 v0.1.6 系列）。

以下情况属于差的发现：

• 只是复述仪表板上的内容（“p50 延迟为 4.2s”）。LangSmith 的 Monitor 选项卡已经显示了这些信息。
• 使用“可能有所改进”或“或许值得调查”之类的限定语。要么这是一个发现，要么就不是。
• 为了凑数而编造。

工作流

第 1 步 — 验证 MCP 是否可用（或改用 SDK）

确认可以访问 LangSmith 读取接口。有两种 MCP 选项和一种 SDK 备用方案：

# Preferred: confirm LangSmith MCP tools are present.
# Via the Ratel gateway: search_capabilities(query="langsmith runs traces threads datasets")
# Or inspect Claude Code's MCP config for one of:
#   - the Remote MCP (OAuth):      https://api.smith.langchain.com/mcp
#     (EU region: https://eu.api.smith.langchain.com/mcp; self-hosted: <host>/api/mcp, LangSmith v0.15+)
#   - the standalone server:       langsmith-mcp-server (uvx / PyPI; LANGSMITH-API-KEY header)

如果无法访问任何 LangSmith MCP 服务，请立即终止：

未检测到 LangSmith MCP 服务。请先运行 /ratel-langsmith-integrate，注册远程 MCP（https://api.smith.langchain.com/mcp，OAuth）或独立的 langsmith-mcp-server，然后重新运行此技能。

SDK 备用方案（离线／无 MCP）。 如果无法注册 MCP，但可以获取 LANGSMITH_API_KEY 和项目名称，则可以直接使用 langsmith Python SDK 进行分析——通过 Bash 调用 Client.list_runs(...)、read_run(run_id, load_child_runs=True) 和运行统计。两种访问方式的查询形式都在 references/query-patterns.md 中。如果使用 SDK 方式，请在报告标题中注明（数据相同，只有访问方式不同）。

没有上述任一方式时，不要继续。没有实时数据，此技能就毫无用处。

第 2 步 — 确定时间范围

询问用户（或接受调用参数）：

• 时间范围（默认：过去 24 小时或最近 100 个根运行，取较小者）。
• 项目——LangSmith 按项目划分运行；必须知道要读取哪个 project_name。
• 可选筛选条件（thread_id／session_id、运行 name、run_type、tags、环境元数据）。
• 可选的 Ratel 功能标志分组，用于聚焦分析（例如，feature_flag／tool_pool 元数据值或标签）——在进行 A/B 合作时很有用。

在聊天中显示所选范围，让客户知道分析了哪些内容。

步骤 3 — 提取聚合数据

按照顺序使用 references/query-patterns.md 中的查询提取数据：

1. 在统计时间窗口内，统计根运行数量、延迟 p50/p99、总 Token 数/成本和错误率（对 is_root 运行执行 run-stats）。
2. 按延迟、Token 数/成本、子运行数量，分别列出排名前 10 的根运行。
3. 列出调用次数最多的 10 个工具（run_type = "tool"）和出错最多的 10 个运行（error = true）。
4. 针对正在使用的反馈键，统计反馈分数分布。
5. 如果设置了 feature_flag（或 tool_pool）标签/元数据键，则按其拆分数据。

这是后续分析的基础，也能发现一些看似简单但很重要的问题（例如，“80% 的根运行缺少 thread_id”——仅凭一次聚合查询就能发现）。

步骤 4 — 深入调查异常值

获取以下运行的完整运行树：

• 延迟最高的单个根运行。
• 成本最高（Token 数最多）的单个根运行。
• “错误”列表中排名靠前的某个根运行。
• 分数最低的线程（如果存在反馈）。
• 从典型延迟区间中随机选取两个根运行作为对照。

加载子运行（使用 read_run(..., load_child_runs=True) 或 MCP 对应方式），并读取输入和输出。不要只看运行树的结构——Agent 实际执行了什么？最有价值的发现来自阅读交互记录。

步骤 5 — 对照共享发现目录匹配模式

打开共享的 finding-catalog.md（与供应商无关；由 ratel-observability-assessment 维护）。针对每种模式，检查客户发出的数据是否符合检测启发式，并将目录中的通用术语映射到 LangSmith 基元（工作单元 → 根运行，步骤 → 子运行，工具调用 → tool 运行，模型调用 → llm 运行，会话 → thread_id）。如果匹配，则使用该模式的模板生成一条发现。

不要盲目遍历目录——如果系统中没有 Ratel，则跳过整个 Ratel 部分。如果没有反馈分数，则跳过与分数相关的模式。目录是筛选器，而不是检查清单。

步骤 6 — 生成发现

每条发现都遵循此模板：

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

- **Severity**: high | medium | low
- **Category**: ratel | generic
- **Evidence**: run ids / trace ids / filter string / 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)

严重性标准：

• 高 — 影响超过 10% 的流量，或任何会导致 Monitor 标签页/自定义仪表板无法正常工作的数据质量问题。
• 中 — 影响范围较大，但不是关键依赖项。
• 低 — 已观察到，但影响较小；值得记录一次。

在每个类别（ratel、generic）中按严重性从高到低对发现分组。每个类别最多列出 10 条发现，确保报告具有可操作性。超过 10 条时，写上“（另外 N 条发现已纳入后续批次）”，并在附录中记录其余发现。

对于 Ratel 类别，使用共享的 ratel-value-map.md 将概念信号映射到 Ratel 版本。不要在此处硬编码版本声明。

步骤 7 — 编写报告

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

结构：

# LangSmith analysis — <date>

## Scope
- Project: <project_name>
- Window: <range>
- Access path: <Remote MCP | standalone MCP | langsmith SDK fallback>
- Filters: <list>
- Root runs 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>

在聊天中直接列出排名前三的发现（涵盖两个类别，按严重性从高到低），每条附上一行摘要。并告知用户其余内容的文件路径。

诚实地跳过

如果数据确实干净——错误率低于 1%，没有延迟异常值、缺少 thread_id 的问题、反馈回归或工具漂移——就写一份简短报告说明情况：

本周没有值得采取行动的发现。在 内分析了 次根运行；整体健康状况处于正常范围内。下次值得重新运行分析的时机，可能是流量超过 ，或部署了新的 Agent 版本时。

这不是失败，而是信号。合作伙伴信任那些会告诉他们没有问题需要解决的顾问。不要凭空捏造发现。 一份充斥噪声的报告会让客户从此忽略之后的所有报告。

同样，如果流量太少，无法得出结论（分析时间段内根运行次数少于约 20 次），也要如实说明：

分析时间段内只有 次根运行。请在客户下一次带来流量的版本发布／下一次测试活动后重新运行分析。已包含汇总数据供参考，但未得出任何发现。

参考文件

• references/query-patterns.md — 经过验证的 LangSmith MCP 工具查询形式，以及 langsmith SDK list_runs 过滤模式（汇总、深入分析、抽样）
• finding-catalog.md — 通用的跨供应商检测模式、建议修复方案和 Ratel 映射目录
• ratel-value-map.md — 通用的跨供应商「Ratel 何时发布什么」事实来源（概念信号 → 版本）；标记 Ratel 相关发现时请查阅

本技能在流程中的位置

追踪启用后，/ratel-langsmith-integrate 会将后续工作交给本技能。上游流程：/ratel-assessment → /ratel-observability-assessment（供应商检测 + 中立方案）→ /ratel-langsmith-integrate（具体接入 + 仪表板）→ 本技能（读取实时数据，提出修复方案）。