SuperAPI AI 工具集

opik-explain

智能体与模型

查看项目

更新于 10-15 20:14

技能介绍

用途:对指定的 Opik trace(或一类行为模式)做根因分析,输出有依据的解释。所谓“有依据”指解释要指出异常/失败的具体 span,并把它关联到产生该结果的代码或数据,而不是复述 trace。

主要能力:入口为 /opik-explain <trace-id>(单条 trace)或 /opik-explain <描述行为>(模式)。可推断项目名、时间窗口、对照的已知正常 trace 等可选覆盖项。先确认 Opik 可达(存在 ~/.opik.config 或设置了 OPIK_API_KEY),再获取 trace 与 spans:优先使用已连接的托管 Opik MCP,否则回退 SDK 脚本。读取每个 span 的输入/输出/错误/耗时,定位锚点 span(首个报错、输出错误或耗时占主导者),结合仓库代码给出单一最可能的根因及证据 span。

使用方式:MCP 路径用 list 工具按 OQL 过滤与排序,例如 list(entity_type="trace", project_name="<project>", since="7d", filters="error_info is_not_empty", sort="start_time desc");无 MCP 时用 SDK,如 client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")。注意 search_spans 必须传 project_name,否则会搜索默认项目而返回空;TracePublic 不含 project_name,需用 project_id 查项目名。

输出:面向用户给出简短根因、可点击的 Opik UI 证据链接和恰好一个下一步;底层结构含 status、target、root_cause、evidence、next_step、reasoner。

限制:该技能只读,不修改代码;遇到无法获取目标等阻塞时停在最早阻塞点并给出一个下一步。若未安装 opik 技能,应说明并参考 https://www.comet.com/docs/opik/。