cekura-metric-design

Cekura 技能验证标签： ack:cekura-metric-design:6n2q5r 从此技能调用 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-metric-design"、verification_tag="ack:cekura-metric-design:6n2q5r" 和 plugin_version="0.19"。该调用会立即返回，并让 Cekura 知道当前正在使用哪些技能。

Cekura 指标设计

目的

指导创建有效的 Cekura 指标，以准确评估 AI 语音 Agent 的通话质量。指标通过根据定义的标准评估转录文本，事后衡量通话质量。每项指标针对需要逐通电话跟踪的特定工作流或 KPI。

执行平台操作

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

核心术语

• 主 Agent：正在接受测试的客户端 AI 语音 Agent
• 测试 Agent：Cekura 的模拟来电者，用于测试主 Agent
• 指标：通话后对转录文本进行评分的评估
• 评估器／场景：模拟来电者的测试用例（属于另一个概念，详见 cekura-eval-design 技能）

指标创建工作流

每次都请遵循此工作流。跳过步骤（尤其是第 2 步）会导致指标遗漏边缘情况。

1. 收集上下文 — 了解客户端的用例和关注点，并获取带有预期结果的示例对话 ID
2. 获取真实转录文本 — 从 Cekura API 中提取 3-5 条真实的 transcript_json 记录。研究其中出现的角色（Main Agent、User、Function Call、Function Call Result）、可用的时间戳、工具调用的结构，以及实际对话的流程。不查看真实数据就编写指标，会遗漏边缘情况。
3. 确定信号 — 转录文本中的哪个具体内容表明通过或未通过？是工具调用、时间戳间隔、短语，还是行为模式？
4. 编写提示词 — 以真实转录文本的实际形式为依据，使用经过验证的结构（见下文）
5. 部署并测试 — 通过 API 创建指标，在示例对话上运行，并与预期结果比较
6. 迭代 — 根据结果调整提示词，重新运行并重复，直到指标在所有样本上的表现都符合预期。至少计划一次迭代——首次运行会暴露衡量方面的问题。

指标类型

llm_judge（首选默认项）

由大模型根据通话转录文本评估 description 字段中的提示词。优先选择 llm_judge，而不是 custom_code。 对于“客观”检查（如时间戳、是否存在工具调用），custom_code 似乎很有吸引力，但实际使用中往往很脆弱。语音 AI 转录文本的时间信息并不规整——Agent 可能在工具调用链中途转接，后台任务可能在语音恢复后才完成，时间戳也可能重叠。大模型阅读转录文本时可以自然地处理这些细微情况。请用自然语言而不是代码来表达衡量标准。

**重要：**评估提示词应放在 description 字段中，而不是 prompt 字段。

custom_code（Lambda 上的 Python）

custom_code 字段中的 Python 代码。可访问 data 字典、evaluate_basic_metric() 和上游指标结果。仅在确实需要编程逻辑时使用。

仅在以下情况下使用：

• 根据上游指标结果进行判断（data.get("Exact Metric Name")）
• 从 Agent 描述中提取部分内容（Python 风格的模式）
• 根据条件使用不同提示词进行多次 LLM 调用
• 在调用 LLM 前，将结果短路为 N/A

指标演进路径

从 llm_judge 开始，以便快速迭代。提示词经过验证（通过实验室/反馈）后，将其转换为使用部分提取的 custom_code，用于生产环境。Cekura 允许指标同时具有 description（llm_judge 提示词）和 custom_code——可切换生效类型。这意味着可以通过实验室优化 LLM 提示词，然后让 custom_code 版本使用同一提示词，并有针对性地提取上下文。

评估类型

评估类型	输出	用途
binary	TRUE/FALSE	通过/失败检查——流程合规性、软技能/质量评估
enum	定义值中的字符串	分类任务
numeric	浮点分数	评分任务
continuous_qualitative	连续分数	连续质量评估

LLM 评审提示词结构

经过验证的结构有两种。完整模板请参阅 references/prompt-patterns.md。

结构 A：分节式（最适合多标准指标）

1. 范围与重点——此指标仅评估什么，以及应忽略什么
2. 不要标记——常见的误报：看起来像失败、但对本指标而言并非失败的行为模式
3. 输入——仅包含相关模板变量
4. 各部分——带有通过/失败示例的编号评估标准
5. 失败条件（仅限以下情况）——构成失败的范围狭窄、明确封闭的列表
6. 安全保障说明——优先遵循本意而非字面规则的情况
7. 输出说明——返回格式、失败时的时间戳

结构 B：叙述式（最适合行为/时序指标）

1. 范围与重点——此指标仅评估什么，以及应忽略什么
2. 不要标记——针对本指标的常见误报
3. 背景——此类通话的表现形式，以及该指标的重要性
4. 查找内容——记录稿中的具体项目（工具名称、短语、模式）
5. 失败条件（仅限以下情况）——具体失败模式的范围狭窄、明确封闭的列表
6. 细微之处——边缘情况、优先规则，以及看起来像失败但并非失败的情况
7. 输出——TRUE/FALSE/N/A，并附时间戳和依据

用真实对话示例明确说明通过与失败，是提升提示词质量最有效的做法。诸如“Agent 应及时响应”这类模糊标准会导致结果不一致。

防止跨流程影响的范围限定（使用 {{agent.description}} 时）

误判失败最常见的来源是：指标使用 {{agent.description}}，却根据不相关流程的规则判定失败（例如，紧急情况指标因预订流程规则而失败）。

三层范围限定模式：范围与重点（“仅评估 X”）、不要标记（按行为模式列出误报）、失败条件（范围狭窄的封闭列表）。

完整结构以及所有范围限定措辞必须基于概念、不得硬编码为特定 Agent 的部分名称的规则，请参阅 references/advanced-patterns.md。

可用模板变量

变量	描述
{{transcript}}	完整对话文本
{{transcript_json}}	包含时间戳的结构化对话记录
{{dynamic_variables}}	来自调用的完整自定义变量数据块
{{dynamic_variables.keyName}}	按键名指定的动态变量（推荐使用点号表示法）
{{agent.description}}	主 Agent 的系统提示词
{{metadata}}	调用元数据
{{call_end_reason}}	调用结束原因

仅包含与具体指标相关的变量。列出所有变量会增加干扰，分散评估重点。

使用 {{metadata}} 时，请指出 LLM 评判者应参考的具体元数据字段（例如：“检查 metadata.appointment_id，以验证是否已创建预约”）。

精神与字面原则

这是指标设计中最关键的概念。

Agent 描述的是主 Agent 的预期功能，但评估者不能按字面理解。应理解每条指令背后的意图，并编写能体现其精神而非字面内容的指标。

**示例：**Agent 描述写着“每次只问 1 个问题”

• **精神：**避免给来电者造成认知负担
• **字面理解（错误）：**任何包含多个问号的轮次都判定为失败
• 正确的指标行为：
  • 通过：“您是 123 Easy St 的业主吗？可以告诉我您的姓名吗？”（相关信息组合）
  • 通过：“这是新问题，还是之前的问题？”（A/B 式改述 = 单个问题）
  • 不通过：“周四可以吗？另外，您收到我们的短信了吗？”（不相关的问题）

如果不确定某条指令背后的意图，请先向用户确认，再将其编入指标。请在提示词中加入明确的保护性示例，说明哪些情况应当和不应当受到惩罚。

触发器设计

触发器类型	适用场景
"always"	适用于每次通话的指标（软技能、业务背景）
使用 llm_judge 触发器的 "custom"	条件指标（仅在检测到预约意图时触发预约流程指标）
使用 custom_code 触发器的 "custom"	需要代码实现的复杂触发逻辑
"automatic"	由 Cekura 自动判断（控制力较弱）

使用 generate_evaluation_trigger 端点（参见 references/api-reference.md），根据指标描述自动生成触发器提示词。触发器可按具体程度分层设置，例如，一个触发器在任何引导通话中触发，另一个则仅在用户遇到困难时触发。

两层 N/A 策略

触发器和指标描述在不同层级处理 N/A：

• **触发器层级的 N/A（第一道防线）：**触发器会在指标运行前排除明显不相关的通话，从而节省 LLM 成本。示例：预约流程指标的触发器会检查是否存在预约意图；如果不存在，该指标就不会触发，并输出 N/A。
• **描述层级的 N/A（复杂情况）：**指标提示词本身会处理需要结合对话记录才能判断的边缘情况。示例：通话存在预约意图（触发器触发），但来电者在流程开始前挂断——指标描述会返回 N/A，并注明“VALID_SKIP：来电者在预约开始前断开连接。”

设计触发器时应捕捉明显不适用的通话；设计指标提示词时应处理需要阅读对话记录才能判断的复杂边缘情况。

触发器提示词模板

按照先肯定、后否定的模式编写触发器：

Evaluate whether this call involves [specific scenario].

Return TRUE if ANY of these indicators are present:
- [Positive indicator 1]
- [Positive indicator 2]

Do NOT trigger if ANY of these apply:
- Call is under 30 seconds or contains no substantive interaction beyond a greeting
- Line disconnection / voicemail / outbound non-engagement
- [Specific exclusion for this metric — e.g., "Emergency-flow transfers (covered by Emergency metric)"]
- [Another exclusion]

Be inclusive — if there's reasonable evidence the scenario occurred, return TRUE.

**始终排除过短的通话。**不到约 30 秒的通话（挂断、拨错号码、语音留言）会导致每项指标出现误报或漏报。应在触发器层级将其排除。

触发器返回 N/A

当 evaluation_trigger: "custom" 且触发器返回 false 时，该指标会输出 N/A，不会进行评估。这意味着，即使是二元指标（True/False）也可能有三种结果：True、False 或 N/A。这是条件指标的正确行为。

关键模式

VALID_SKIP 模式

对于指标不应适用的合理偏差（工具故障、流程开始前用户挂断、来电者立即要求转接），让 LLM 返回以 "VALID_SKIP:" 开头的说明，custom_code 包装器会将其转换为 _result = None。

门控指标

通过 data.get("Exact Metric Name") 或 data["metrics"]["<slug>"]["value"] 访问上游指标结果。名称键必须与上游指标的 name 字段完全一致。可据此根据先前的分类分支执行评估逻辑。平台会先运行上游指标：字面量形式的 data["..."] 读取会被推断为前置条件，而 configuration.metric_dependencies（指标 ID 列表）则用于显式声明依赖项。如果某次通话的上游指标没有结果，门控指标会以未评分状态保存，并附带 extra.dependency_failed，且不会收费，因此示例中的 None 门控只会在预览中触发。LLM 评审指标也可以用作门控指标，在 description 中使用 {{metrics.<slug>.score}} 即可。

Pythonic 片段提取

将 Agent 描述中仅相关的片段提取出来，再传给 LLM。这样可避免无关的描述片段造成上下文偏移，并减少 token 用量。有关片段提取工具，请参阅 references/pythonic-patterns.md。

N/A 条件

首先检查指标不应适用的情形：

• 在前 1–2 轮对话中立即转接／要求人工协助
• 流程开始前来电者挂断
• 来电者不在服务范围内（打错电话、销售电话）
• 基础设施故障导致流程无法执行
• Agent 描述中缺少相关片段（针对可选工作流）

由动态变量驱动的通用指标

对于会注入每次通话的 dynamic_variables 的客户端（例如，按节点设置的系统提示词、功能标志、雇佣类型），创建可针对每次通话自适应的指标，而不是将行为硬编码。模式：每个注入的提示词变量对应一个指标。 每个指标只引用其特定的 {{dynamic_variables.promptName}}，而不引用整个数据块或 {{agent.description}}。

示例提示词结构以及在真实通话中查找动态变量的发现工作流，请参阅 references/advanced-patterns.md。

工具调用幻觉指标

对于具有详细工具定义的 Agent，构建一个指标，评估 Agent 是否在每种情况下调用了正确的工具——“行动幻觉”（错误操作）与“事实幻觉”（错误信息）。模式：从 Agent 描述中提取工具→场景映射，并将其编码为明确的失败条件（封闭列表）；不要将 API 错误／已知问题标记为失败。

完整提示词结构和 TOOL-TO-SCENARIO MAPPING 模板，请参阅 references/advanced-patterns.md。

基线指标 — 始终推荐

每个 Agent 都应至少启用以下预定义指标，用于可观测性和模拟：

指标	用途	重要性
Expected Outcome	检查 Agent 是否达成场景预期结果	若没有此指标，运行仅根据调用是否完成判定通过或失败，而不考虑结果是否正确
Infrastructure Issues	标记静默时段、连接中断、Agent 无响应	可发现 Agent 静默 10 秒以上等在通过或失败结果中无法体现的问题
Tool Call Success	监控工具调用是否成功	需要集成提供方（assistant ID 和 API 密钥），才能在转录记录中获取工具调用数据
Latency	测量响应时间	识别性能下降

必须分两步启用： 指标必须（1）在项目级别为模拟开启，（2）添加到各个评估器中。缺少任何一步都会导致指标不触发。未启用指标时，用户可能会误以为运行通过，并且必须手动检查每次运行。

模拟成本会随指标附加范围扩大。 附加到某个场景的每项指标都会在该场景的每次运行中评分；而项目中针对该指标的评分规则会决定运行的 success。如果项目将某项特定于流程的大模型指标附加到所有场景，该指标应设置一个触发条件：当流程未发生时返回 N/A，这样就不会因此向无关场景收费或判定其失败。

Expected Outcome 仅分析转录文本，无法评估音频层面的行为。 Expected Outcome 会读取对话文本，以确定 Agent 是否达成目标。它无法感知静默、中断、插话、音频丢失或其他语音通道信号。不要依赖 Expected Outcome 来发现这些问题。对于任何取决于音频流而非对话内容的情况，请使用预定义指标。

工具调用数据前提条件： 使用 Tool Call Success 和高级监控，需要在 Cekura 中配置 Agent 的提供方 assistant ID，并发送完整的调用数据。如果转录记录中缺少工具调用数据，建议用户配置其提供方集成。

输出要求

所有指标都必须要求：

• 简要说明结果（发生了什么以及原因）
• 对于失败：以 MM:SS 格式指出违规发生的具体时间戳
• 对于基于元数据的检查：引用所检查的具体元数据字段

值得推荐的常见自定义指标

除基线预定义指标外，根据不同客户端中观察到的模式，以下自定义指标也很有价值：

• 问题堆叠／信息倾倒 — Agent 在一轮中提出 3 个或更多无关问题，或倾倒大段信息。这会造成糟糕的用户体验，让来电者不堪重负。
• 工作流遵循情况 — Agent 按顺序遵循已定义的流程步骤（预约、验证、取消等）。
• 软技能 — 语气、共情、恰当的问候，以及不泄露系统内部信息。
• 业务背景准确性 — Agent 提供正确的业务信息（营业时间、地址、定价）。
• 转接／回拨处理 — Agent 在转接或安排回拨时遵循正确的流程。

操作规则

成本防护 — 未经确认，绝不评估超过 100 个调用

每次评估都会给客户端带来实际费用。在对一批调用评估指标之前，必须先查询调用数量（使用 page_size=1 并读取响应），然后向用户报告数量。如果数量 > 100，必须停止并先征求用户明确批准。使用 page_size 参数（最多 200），而不是分页；并使用服务端筛选条件（agent_id、project、timestamp__gte／timestamp__lte）限定调用范围。

先手动修复，再使用 Labs

当指标存在系统性问题（误判为失败的比率较高）时，不要直接跳到 Labs 反馈。请按以下步骤操作：

1. 阅读失败说明并归纳根本原因（例如：extra_questions、end_protocol、should_be_na）
2. 编写手动提示词修复，针对主要失败类别
3. 通过 API PATCH 更新后的描述
4. 对每项指标抽样评估 20-30 个通话，以验证修复效果
5. 然后再使用 Labs 反馈处理手动修复未能解决的边缘情况

这样可以避免将 Labs 迭代浪费在显然可以通过编辑提示词解决的问题上。

常见陷阱

• 未先阅读真实转录内容就编写指标——编写前务必获取并研究实际的 transcript_json
• 对 llm_judge，将提示词放在 prompt 字段而不是 description 字段中
• 使用已弃用的类型（basic、custom_prompt）——API 会返回 400
• 对大模型可以自然处理的检查（时间戳、工具调用检测）使用 custom_code
• 受门控的指标未与上游指标名称完全一致
• 仅相关部分适用时，仍传入完整的 Agent 描述（导致上下文偏移）
• 在 custom_code 指标中遗漏 VALID_SKIP 处理
• 条件性指标未设置 N/A 条件
• 逐字照搬 Agent 描述中的指令，而不是把握其核心意图
• 未为细致的评估标准添加保障性示例
• 在失败说明中遗漏时间戳

后续步骤

创建指标后，用户通常需要：

• 在真实通话中验证指标 → 使用 evaluate-calls 流程（参见 references/api-reference.md）
• 迭代提升准确性 → 调用 cekura-metric-improvement 运行 Labs 反馈周期
• 设计能够检验此指标的测试场景 → 调用 cekura-eval-design

文档

• 公开文档：https://docs.cekura.ai
• 适用于大模型的文档：https://docs.cekura.ai/llms.txt
• 概念：https://docs.cekura.ai/documentation/key-concepts/

完整的端点文档和字段架构请参阅 references/api-reference.md。

更多资源

参考文件（按需加载）

• references/prompt-patterns.md — 完整的 LLM judge 提示词模板及真实示例
• references/pythonic-patterns.md — 区段提取工具和 custom_code 模式
• references/advanced-patterns.md — 防止交叉污染的作用域设定、由动态变量驱动的指标、工具调用幻觉指标
• references/api-reference.md — 完整的 Cekura 指标 API 端点和架构

示例文件

• examples/llm-judge-metric.md — 完整的 llm_judge 指标示例（分区结构）
• examples/narrative-metric.md — 完整的 llm_judge 指标示例（叙述结构）
• examples/custom-code-metric.py — 包含门控和 VALID_SKIP 的完整 custom_code 指标
• examples/section-extraction-metric.py — 根据 Agent 描述限定作用域的 Pythonic 指标