opik-explain

Explain — 对 Opik 追踪进行根因分析，并在代码中找到依据

完成标准： 针对指定追踪（或模式）给出有依据的根因，关联到具体的证据跨度，并配上且仅配一个建议的下一步操作。“有依据”是指解释要指出出错或异常的跨度，并将其与产生它的代码或数据联系起来，而不是复述追踪内容。如果无法获取或读取目标，应在遇到第一个实际阻碍时停止，并返回一个具体的下一步操作。追踪转储不等于解释。

操作：调查真实追踪数据，结合代码仓库进行推理，基于证据确定一个最可能的根因——不修改任何代码。 此技能按设计仅用于读取。

输入

入口是 /opik-explain <trace-id>（单条追踪）或 /opik-explain <describe the behavior>（要查找并解释的模式）。推断其余信息；将以下内容视为可选覆盖项：

• 项目名称（默认：从配置或代码仓库推断）· 模式的时间范围（默认：最近）· 用于对比的已知正常追踪。

仅在遇到真正无法推断的阻碍时提问（参见阻碍）。

激活——唯一范围内的工作

1. 确定目标

• 追踪 ID（UUID 格式）：解释这条追踪。
• 行为/模式（“更改提示词后出现幻觉”“响应变慢”）：查找匹配的集合（如下），然后解释其共同原因。
• 确认 Opik 可访问：如果 ~/.opik.config 存在或已设置 OPIK_API_KEY，则使用它。否则 → 阻碍（“运行 opik configure，然后重新运行”）。

2. 获取追踪和跨度——优先使用 MCP，SDK 作为回退

检查托管的 Opik MCP 是否已连接，并优先使用；未连接时回退到 SDK 脚本。

• MCP 已连接： 使用 MCP read 追踪，并 list/read 其跨度。
• MCP 未连接： 回退到 SDK。

无论使用哪种方式，都要读取每个跨度的输入/输出/错误/持续时间。

import opik
client = opik.Opik()

tid = "<trace_id>"
trace = client.get_trace_content(tid)       # TracePublic: exposes project_id, input, output, error info — NOT project_name (accessing .project_name raises)
project = client.rest_client.projects.get_project_by_id(trace.project_id).name
spans = client.search_spans(project_name=project, trace_id=tid)   # spans come from a SEPARATE call, not from the trace object
# ALWAYS pass project_name: without it the SDK searches the configured default project, which
# returns an empty list (or a 404 if that project doesn't exist) even for a valid trace id.
# Reconstruct the tree via each span's parent_span_id (the root span has none).
# Your anchor is the first span that errored, returned wrong output, or dominates the duration.

对于模式，按项目范围获取匹配的集合，然后查找其中共同的出错跨度。使用 MCP 时，一次 list 调用即可在服务端完成筛选和排序——filters 是 OQL 字符串，sort 的格式为 "<field> [asc|desc]"，since 接受 "1h" / "7d"：

list(entity_type="trace", project_name="<project>", since="7d",
     filters="error_info is_not_empty", sort="start_time desc")        # error traces
list(entity_type="trace", project_name="<project>", since="7d",
     sort="duration desc")                                             # slow traces (duration in ms)
list(entity_type="trace", project_name="<project>", since="7d",
     filters="feedback_scores.hallucination > 0.5")                    # low-scored traces
list(entity_type="span",  project_name="<project>", since="7d",
     filters='name = "<span name>" AND error_info is_not_empty')       # the shared failing span, across traces

应用的筛选条件会回显在第一行；如果筛选条件被拒绝，返回内容会说明如何修正（schema("list.trace") 是完整的字段参考）。不使用 MCP 时，SDK 也采用相同的语法：

traces = client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")

追踪是异步的；如果刚刚生成了追踪，请等待几秒，并确认已执行刷新。

3. 分析根因

编码 Agent 会基于获取的数据并结合代码仓库进行根因分析——它拥有通用推理器所缺少的一项关键要素：代码。无论追踪来自 MCP 还是 SDK，分析方式都相同：找到锚点跨度（错误/错误输出/延迟主因），读取其输入和输出，并将其与代码关联起来（在代码仓库中 grep 跨度名称/函数），然后结合证据跨度说明最可能的单一根因。优先选择证据充分的一个原因，而不是列出一系列可能性。

4. 报告

返回根因、作为可点击 Opik UI 链接的证据跨度（Opik 输出的追踪重定向 URL，例如 .../session/redirect/...?trace_id=THE_ID——绝不能只提供裸 ID），以及一个下一步操作（参见输出）。如果修复方案显而易见，将其作为下一步操作说明；不要实施修复（此技能不会修改代码——下一步应交由 opik-instrument/opik-test 或开发者处理）。

阻碍

遇到最早出现的阻碍时停止，并返回且仅返回一个下一步操作：

• “运行 opik configure，然后重新运行 /opik-explain <trace-id>。”
• “在项目 <name> 中找不到追踪 <id>——请确认 ID 和项目，然后重新运行。”
• “此环境无法访问 Opik——请在 UI 中打开追踪并粘贴其错误/输出，或在已配置 Opik 的环境中运行。”
• “你想让我解释哪种行为？请提供追踪 ID，或描述出现了什么问题。”

输出

**面向用户：**一条简短的说明 — 用一到两句话说明根本原因，提供可点击的 Opik UI 链接作为证据跨度（名称 + 每项证据的重要性），并给出唯一的下一步。不要输出原始追踪记录，也不要输出 JSON。

底层内容（用于撰写回复 / 评估），无论是 MCP 路径还是 SDK 路径生成，都使用同一种结构：

• status：explained | blocked | not_found
• target：trace_id + trace_url（Opik UI 链接；对于某种模式，使用抽样得到的 trace_ids + trace_urls）
• root_cause：一条有依据的陈述
• evidence：spans（每项包含：name、type、可用时提供 trace_url 深层链接，以及它为何构成证据）
• next_step：恰好一项
• reasoner：agent（编码 Agent 根据追踪数据和代码库分析根本原因）

不变量：explained 必须包含 root_cause 和至少一个证据跨度；blocked / not_found 必须恰好包含一个 next_step；所有路径都不得更改代码库。

示例

单条追踪 — 工具失败。 /opik-explain 019fd8a7-...。获取追踪记录和跨度；retrieve（tool）跨度返回了空结果，随后 llm 跨度产生了幻觉。在代码库中打开 retrieve()：查询过滤器有误。根本原因 = 检索过滤器；证据 = 向 llm 跨度提供输入的空 tool 跨度；下一步 =“修正 retrieve() 中的过滤器（或运行 /opik-test 测试）”。→ explained。

模式 — 响应变慢。 /opik-explain why responses got slow this week。运行 list('trace', since="7d", sort="duration desc")（或在不使用 MCP 时运行 search_traces）查找最慢的追踪记录；每条记录中相同的外部 tool 跨度都占据了主要耗时。根本原因 = 该调用的延迟；证据 = N 条追踪记录中共同出现的慢跨度；下一步 =“为它添加超时 / 缓存”。→ explained。

受阻 — id 无效。 /opik-explain 123。get_trace_content 未找到任何内容。→ not_found：“项目 X 中没有追踪记录 123 — 请确认 id / 项目并重新运行。”（未触及代码。）

反模式

只倾倒跨度树却不说明原因；不读取锚点跨度的输入 / 输出就猜测原因；罗列五种可能性，而不是证据最充分的一种原因；返回不可点击的跨度 / 追踪 id，而不是 Opik UI 链接；编辑代码（此技能用于解释；由 opik-instrument / opik-test 或开发者进行更改）；对 TracePublic 调用 .project_name（会报错 — 请使用 project_id）；调用 search_spans(trace_id=…) 却不传入 project_name（这会在默认项目中搜索，结果为空）。

参考资料

SDK 和可观测性详情请参阅与此技能一同安装的 opik 技能。直接读取文件 — 路径相对于此文件：../opik/SKILL.md（搜索追踪记录 — MCP list 工具与 search_traces 共用的 OQL 过滤语法）、../opik/references/production.md（search_traces、错误 / 延迟 / 成本分析）、../opik/references/tracing-python.md（SDK 读取 API）、../opik/references/observability.md（跨度类型模型）。如果宿主以不同方式组织技能文件，请找到 opik 技能的 references/ 目录。

如果未安装 opik 技能，请在报告中说明，并使用 https://www.comet.com/docs/opik/，不要凭记忆作答。