cekura-predefined-metrics

Cekura 技能验证标签： ack:cekura-predefined-metrics:2k7b3x 调用此技能中的 Cekura 指标写入工具（metrics_create、metrics_bulk_create、metrics_partial_update）时，请在该工具调用中将此确切字符串作为 skill_ack 参数传入。这样可向 Cekura MCP 服务确认此设计手册已加载到上下文中。场景／测试配置文件的写入改用 eval 系列标签——请先加载 cekura-eval-design，并在相应调用中传入该标签。

执行任何操作前，请调用 mcp__cekura__cekura_skill_started，并传入 skill_name="cekura-predefined-metrics"、verification_tag="ack:cekura-predefined-metrics:2k7b3x" 和 plugin_version="0.19"。此调用会立即返回，并让 Cekura 知道当前正在使用哪些技能。

Cekura 预定义指标

用途

预定义指标是 Cekura 内置的评估器，可直接启用到任何 Agent 上，无需编写提示词。它们涵盖准确性、对话质量、客户体验和语音质量等最常见的质量维度。使用此技能可决定启用哪些预定义指标以及如何配置。

执行平台操作

此技能建议在 Cekura 上创建、列出、更新或评估内容时，优先使用可用的平台工具，而不是描述 API 调用或控制面板操作步骤。在安装了 Cekura 插件的 Claude Code 中，这些工具会自动配置，并为你处理身份验证、参数验证和错误处理。只有在当前会话没有可用工具时，才改用直接 API 端点或控制面板操作说明。

核心术语

• 主 Agent：正在接受测试的客户端 AI 语音 Agent
• 测试 Agent：Cekura 的模拟来电者，用于测试主 Agent
• 预定义指标：Cekura 提供的内置评估器，无需提示词，通过 code 标识
• 自定义指标：用户编写的指标，带有自定义提示词或 custom_code（参见 cekura-metric-design）
• 模拟测试：使用 Cekura 测试 Agent 测试主 Agent 的运行（目录中的 Sim 列）
• 可观测性：通过 Agent 流转的真实生产通话（目录中的 Obs 列）
• 项目级开关：为整个项目启用模拟测试或可观测性中的某项预定义指标
• 评估器关联：将指标添加到特定测试场景；指标要在该评估器上触发，就必须进行此操作

预定义指标与自定义指标

请先启用预定义指标。它们无需提示词工程，开箱即用地涵盖最常见的质量维度。只有在以下情况下才使用自定义指标：

• 需要评估特定于业务的工作流（预订流程、升级处理协议等）
• 需要根据特定系统提示词检查 Agent 行为
• 需要将多个信号合并为一个分数

其他情况下，预定义指标能更快地提供可靠、一致的结果。

预定义指标工作流

1. 浏览目录 — 使用下面的四张目录表，找出候选指标。按 Sim/Obs 可用性、成本和所需约束进行筛选。
2. 选择初始指标集 — 从下面的 Baseline 开始。如需更全面的覆盖，请参阅 references/selection-by-use-case.md，查看针对不同 Agent 类型（预订、催收、支持、医疗保健、语音质量调查）的推荐指标集。
3. 在项目级别启用 — 为模拟运行启用该指标（或为可观测性启用，两者是独立开关）。如果不执行此操作，即使将指标附加到评估器也不会生效。
4. 添加到各个评估器 — 将指标附加到特定测试场景，以便在运行该场景时触发。
5. 按需配置 — 有六项指标需要或支持配置（静音阈值、掉线/主题节点列表、拼写类别、发音音素）。完整的负载示例请参阅 references/configuration-guide.md。
6. 运行验证 — 执行一小批测试并检查结果。如果结果异常，请先查看下面的 常见问题，再考虑使用自定义指标。

完整的 API 端点（列表、切换、附加、配置、重新评估）请参阅 references/api-reference.md。

启用预定义指标

必须完成两个步骤——缺少任一步骤，指标都不会触发：

1. 在项目级别启用 — 为模拟运行启用该指标
2. 添加到各个评估器 — 将指标附加到特定测试场景

使用 GET /test_framework/v1/predefined-metrics/ 获取可用预定义指标的完整列表及其 ID。将预定义指标的 code 字段传入 Agent 的指标集。

---

目录：准确性

指标	输出	成本	Sim	Obs	备注
预期结果	0–100 分	免费	✓	—	需要在评估器上设置 expected_outcome_prompt。评估 Agent 实现了多少场景目标。否则，运行结果只会根据通话是否完成判定通过或失败。仅评估转录文本——无法评估语音特征（语气、发音、语音质量）。编写提示词时，请将说话方称为 “main agent” 和 “testing agent”，不要使用 “user”、“assistant”、“bot” 或 “AI”。
幻觉	True/False	0.6 积分	✓	✓	将 Agent 的回复与知识库进行比较，以检测缺乏依据的说法。
模拟工具调用准确率	0–100 分	免费	✓	—	评估是否使用正确的输入调用了正确的模拟工具。需要在 Agent 上配置模拟工具。
相关性	True/False	0.2 积分	✓	✓	检查 Agent 的回复是否回应了所提问题。标记跑题或推诿的回复。
回复一致性	True/False	0.2 积分	✓	✓	检测矛盾——Agent 重复信息时出错，或与先前的陈述相矛盾。
工具调用成功	True/False	免费	✓	✓	检查任意工具调用结果中是否包含“Error”或“failed”。需要配置提供商集成（助手 ID + API 密钥），以便工具调用数据出现在转录文本中。
转录准确率	0–100 分	模拟免费 / 生产通话日志每分钟 1 积分	✓	—	对生产通话日志使用两种转录模型；对运行结果与真实值进行比较。需要音频。 生产通话日志评估成本较高，请谨慎使用。
语音信箱检测	True/False	0.2 积分	✓	✓	检测通话是否接通语音信箱或自动应答系统。Beta 版。

---

目录：对话质量

指标	输出	成本	Sim	Obs	备注
AI 打断用户	次数	免费	✓	✓	统计 Agent 打断用户的次数。可观测性需要使用立体声音频，并为不同说话者提供独立声道。
主 Agent 适时结束通话	是/否	0.2 credits	✓	✓	检查 Agent 是否过早结束通话，以及用户的问题是否得到解决。
测试 Agent 适时结束通话	是/否	0.2 credits	✓	✓	检查用户（测试 Agent）是否突然结束通话——这可能表明体验不佳或问题尚未解决。
检测对话中的静默	是/否	免费	✓	✓	如果双方都超过 silence_duration 秒没有说话，则返回 False。默认值：10s。可配置。
基础设施问题	是/否	免费	✓	✓	如果主 Agent 静默超过 infra_issues_timeout 秒，则返回 False。默认值：10s。可配置。与“检测对话中的静默”不同，此指标仅针对 Agent。
打断评分	0–100 分	免费	✓	✓	持续评估 Agent 打断用户的频率。分数越高 = 打断越少 = 表现越好。
延迟（毫秒）	平均值（毫秒）	免费	✓	✓	平均响应延迟。还会报告 P25/P50/P75/P90/P95/P99 百分位数。低于 2000ms 视为良好。
用户打断后停止时间（毫秒）	毫秒	免费	✓	✓	从用户打断到 Agent 停止说话所需的时间。时间越短 = 响应越及时。
不必要的重复次数	次数	0.2 credits	✓	✓	统计 Agent 不必要地重复自己的次数。
不必要的重复评分	0–100 分	免费	✓	✓	持续评估重复表达的质量。分数越高 = 表达越简洁 = 表现越好。跟踪趋势时，优先使用此指标，而不是次数指标。
用户打断 AI	次数	免费	✓	✓	统计客户打断 Agent 的次数。次数较多可能表明用户感到沮丧或轮流发言体验不佳。

---

目录：客户体验

指标	输出	成本	Sim	Obs	备注
CSAT	0–100 分	0.2 credits	✓	✓	客户总体满意度。分数高于 70 表示满意。评估语气、配合度和问题解决情况。
退出节点	枚举	0.2 credits	—	✓	确定通话结束时所处的对话阶段。需要通过 dropoff_nodes 配置预定义阶段名称。仅用于可观测性。
情绪	枚举	0.2 credits	✓	✓	根据通话中的语气和措辞，将用户情绪分类为开心、愤怒、中性或失望。
通话主题	枚举	0.2 credits	—	✓	对通话内容进行分类（例如，账单、技术支持）。需要配置 topic_nodes。仅用于可观测性。

---

分类：语音质量

指标	输出	费用	Sim	Obs	说明
平均音高（Hz）	Hz	免费	✓	✓	通话期间主 Agent 的平均音高。可用于监控语音的一致性。
胡言乱语检测	True/False	0.3 积分/分钟	✓	✓	检测含混或不连贯的语音。需要立体声音频。 Beta 版。
逐字母发音检测	True/False	0.2 积分	✓	✓	检查 Agent 是否在适当情况下逐个拼读字母（例如，确认电话号码）。需要配置 spelling_word_types。
发音检查	0–100 分	0.2 积分	✓	✓	自定义词语准确度——将语音输出与预期音素列表进行比较。需要将 pronunciation_words 配置为音素对。 Beta 版。
语速	True/False	0.2 积分	✓	✓	检测 Agent 语速是否突然变化。仅支持英语。Beta 版。
对话占比	0.0–1.0	免费	✓	✓	Agent 说话时长与用户说话时长的比例。通常，健康范围为 0.4–0.6。可观测性需要立体声音频。
语音变化检测	True/False	0.2 积分	✓	✓	检测 Agent 的语音是否意外变化（说话者不同、语音模型问题）。Beta 版。
语音音调 + 清晰度	0–100 分	0.2 积分	✓	✓	音频质量评分——分析清晰度和抖动。分数高于 70 表示质量良好。
每分钟词数（WPM）	WPM	免费	✓	✓	主 Agent 的语速。可与平均音高和对话占比一同作为基准。

---

配置参考

某些预定义指标需要或支持配置。请将这些配置作为键值对传入指标的 configuration 对象。

指标	配置键	类型	默认值	说明
检测对话中的静默	silence_duration	int（秒）	10	任一说话者的静默阈值
基础设施问题	infra_issues_timeout	int（秒）	10	仅主 Agent 的静默阈值
流失节点	dropoff_nodes	字符串数组	必填	对话阶段名称（例如，["greeting", "verification", "booking", "closing"]）
通话主题	topic_nodes	字符串数组	必填	主题类别（例如，["billing", "technical_support", "cancellation"]）
逐字母发音	spelling_word_types	字符串数组	必填	要检查的词语类别（例如，["phone_number", "confirmation_code"]）
发音检查	pronunciation_words	对象数组	必填	音素对：[{"word": "Cekura", "phoneme": "sɛˈkjʊrə"}]

完整的负载示例（包括 IPA 提示和命名指南）请参阅 references/configuration-guide.md。

---

费用与积分速查

费用	指标
免费（0 积分）	预期结果、工具调用成功、模拟工具调用准确度、AI 打断用户、用户打断 AI、用户打断后的停止时间、延迟、检测静默、基础设施问题、打断评分、不必要重复评分、平均音高、对话占比、每分钟词数
0.2 积分/次通话	相关性、响应一致性、语音邮件检测、适当结束通话（两种）、不必要重复次数、CSAT、流失节点、情感、通话主题、逐字母发音、发音检查、语速、语音变化检测、语音音调 + 清晰度
0.6 积分/次通话	幻觉
0.3 积分/分钟	胡言乱语检测
免费（模拟）	转录准确度（仅模拟运行）
1 积分/分钟（生产通话日志）	转录准确度（生产通话日志评估）

---

基线 — 始终启用

至少，每个 Agent 都应为模拟启用以下四项指标（其中最后三项也应为可观测性启用）：

指标	原因
Expected Outcome	如果不启用此项，运行结果只能告诉你调用是否完成，而无法判断 Agent 是否真正做对了
Infrastructure Issues	捕捉 Agent 沉默超过 10 秒的情况——这在通过/失败结果中无法体现
Tool Call Success	在集成问题影响真实用户之前及时发现
Latency	跟踪基准性能；P95/P99 能揭示平均值掩盖的异常值

如需更丰富的基线，还可添加：CSAT、Sentiment 和 Unnecessary Repetition Score。

按 Agent 类型推荐的指标组合（预订、催收、支持、医疗保健、语音质量调查），请参阅 references/selection-by-use-case.md。

---

关键限制

• 需要音频： Transcription Accuracy 和 Gibberish Detection 需要音频数据。仅文本运行不提供此类数据。
• 可观测性需要立体声： AI Interrupting User、User Interrupting AI、Talk Ratio 和 Gibberish Detection 在可观测性调用中需要包含独立说话人声道的立体声录音。
• 仅用于模拟： Transcription Accuracy、Mock Tool Call Accuracy、Expected Outcome。
• 仅用于可观测性： Dropoff Node、Topic of Call。
• 仅支持英语： Speaking Rate。
• 需要配置： Dropoff Node、Topic of Call、Letterwise Pronunciation Detection、Pronunciation Check——如果未设置相应配置键，就无法产生有意义的结果。
• 需要集成服务提供商： Tool Call Success 需要在 Cekura 上配置 Agent 的服务提供商助手 ID，这样工具调用数据才会出现在转录文本中。

---

常见陷阱

• 启用指标，却没有完成两个激活步骤（项目开关和评估器分配）——指标看似可用，实际上却不会触发
• 混用 Detect Silence 和 Infrastructure Issues——两者衡量的内容不同（前者针对双方说话人，后者仅针对 Agent）
• 期待可观测性调用提供 Transcription Accuracy——此指标仅用于模拟
• 使用 Expected Outcome 时忘记设置 expected_outcome_prompt——没有它，该指标就没有评估依据
• 使用 Expected Outcome 评估语音特征（语气、发音、语音质量）——它只能访问转录文本；音频评估应使用 Speech Quality 指标
• 在 expected_outcome_prompt 中使用“user”“assistant”“bot”或“AI”等词——始终使用“main agent”和“testing agent”，以匹配 Cekura 的转录文本标注
• 启用 Dropoff Node 或 Topic of Call，却未配置 dropoff_nodes/topic_nodes——结果将毫无意义
• 在单声道录音上使用 Gibberish Detection——此指标需要立体声音频

---

后续步骤

选择预定义指标后，用户通常需要：

• 创建或配置指标 → 调用 cekura-metric-design，创建自定义指标以补充预定义指标
• 改进表现不佳的指标 → 调用 cekura-metric-improvement，开展反馈和实验室迭代
• 将指标添加到测试场景 → 调用 cekura-eval-design，在评估器中配置指标

文档

• 预定义指标参考：https://docs.cekura.ai/documentation/key-concepts/metrics/pre-defined-metrics
• 公共文档：https://docs.cekura.ai
• 概念：https://docs.cekura.ai/documentation/key-concepts/

其他资源

参考文件（按需加载）

• references/configuration-guide.md — 每项可配置预定义指标的完整负载示例（静默阈值、掉线/主题节点列表、拼写类别、IPA 音素对）
• references/api-reference.md — 用于列出、切换、附加、配置和重新评估预定义指标的公共 API 端点，以及端到端示例流程
• references/selection-by-use-case.md — 按 Agent 类型推荐的预定义指标集：预约、催收、客户支持、医疗保健和语音质量调查