cekura-metric-improvement

Cekura 技能验证标签： ack:cekura-metric-improvement:6t4d5m 使用此技能调用 Cekura 指标写入工具（metrics_create、metrics_bulk_create、metrics_partial_update）时，请在该工具调用中将此准确字符串作为 skill_ack 参数传入。这会向 Cekura MCP 服务确认，此设计手册已加载到上下文中。场景 / 测试配置写入则使用评估系列标签——请先加载 cekura-eval-design，并在那里传入其标签。

采取任何操作之前，请先调用 mcp__cekura__cekura_skill_started，并传入 skill_name="cekura-metric-improvement"、verification_tag="ack:cekura-metric-improvement:6t4d5m" 和 plugin_version="0.19"。该调用会立即返回，让 Cekura 了解当前正在使用哪些技能。

Cekura 指标改进（Labs 工作流）

目的

指导指标改进周期：识别未对齐的指标结果、留下结构化反馈、运行 Labs 改进管线，并验证变更。通过系统化迭代，此工作流可将指标质量从初始草稿提升到可用于生产的状态。

执行平台操作

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

先手动修复，再使用 Labs

当指标存在系统性问题（误判失败率较高）时，请勿直接转向 Labs 反馈。 请按以下步骤操作：

1. 阅读失败说明并对根本原因分类（例如，其他流程的交叉污染、extra_questions 被标记、通话结束协议违规、应为 N/A 的情况）
2. 编写手动提示词修复，针对主要失败类别进行调整——添加 SCOPE & FOCUS、DO NOT FLAG，收窄 FAILURE CONDITIONS
3. 通过 API PATCH 更新后的描述
4. 重新评估一个样本：每项指标抽取 20-30 通通话，验证修复效果
5. 然后再使用 Labs 反馈处理手动修复未能解决的剩余边缘情况

这样可以避免在显然能通过编辑提示词解决的问题上浪费 Labs 迭代。Labs 适用于细微的边缘情况，而非系统性的提示词设计缺陷。

Labs 改进周期

手动修复验证通过后，可按以下步骤细化边缘情况：

1. 识别未对齐情况——找出指标结果似乎有误的通话
2. 留下反馈——针对具体结果投赞成 / 反对票并说明原因
3. 累积反馈——收集至少 6 条反馈，以达到统计显著性
4. 运行自动改进——Labs 使用反馈提出指标提示词变更建议
5. 验证变更——在相同通话上重新运行改进后的指标，进行验证
6. 部署——满意后，可选择将其转换为 Pythonic custom_code 用于生产

第 1 步：识别未对齐的结果

手动方式

查看近期通话评估，找出可疑结果：

列出近期通话（并使用 Agent 筛选条件），然后检索特定通话以获取评估结果——请参阅下文“API 端点参考”。

请留意：

• 看起来应为 TRUE 的 FALSE 结果（假阴性）
• 看起来有误的 TRUE 结果（假阳性）
• 意料之外的 N/A 结果
• 类似通话之间结果不一致

引导方式（模拟 Labs）

若要系统地发现未对齐情况：

1. 通过 evaluate_calls 或 list_calls 获取近期通话的指标结果
2. 重点关注方差较高或结果分布异常的指标
3. 对照指标说明阅读转录内容
4. 询问用户：“此通话被标记为 [TRUE/FALSE]。说明中写着 [X]。您认为这正确吗？”
5. 如果用户不同意，请继续留下反馈

步骤 2：留下反馈

使用 mark_metric_vote 端点留下结构化反馈。首先检索通话记录以查找指标结果，然后 POST 反馈（请参阅下方的“API 端点参考”）。

良好反馈示例

• 引用具体的转录内容：“在 02:15，Agent 说了 X，这应该判定为 [PASS/FAIL]，因为……”
• 解释理由：“该指标对只能提一个问题的规则理解得过于字面化”
• 提出正确的结果：“这应该为 TRUE，因为 Agent 当时是在确认相关细节”
• 指出缺失的上下文：“该指标未考虑 01:30 时工具调用失败的情况”

不良反馈示例

• 模糊：“这不对”（没有解释）
• 没有引用：“应该为 TRUE”（没有转录证据）
• 自相矛盾：不同意结果，却不说明正确的行为应该是什么

步骤 3：累积反馈

在运行自动改进前，至少收集 6 条反馈。这能为实验室提供足够的信号，以便识别反馈中的模式并对提示词做出有意义的调整。

跟踪反馈进度：

• 留下了多少条同意／不同意投票
• 出现了哪些模式（例如：“该指标对 X 一直过于严格”）
• 反馈是否均衡地覆盖了不同类型的通话

步骤 4：运行自动改进

累积 6 条或更多反馈后：

使用指标 ID，通过 POST /test_framework/metric-reviews/process_feedbacks/ 触发自动改进。

实验室会分析反馈并提出对指标提示词的修改建议。请仔细检查这些建议：

• 修改是否解决了反馈中反映的问题？
• 修改范围是否过大（可能会影响其他情况）？
• 保护性示例是否与反馈一致？

成本防护 — 未经确认，绝不评估超过 100 条通话

每次评估都会产生实际费用。在触发任何批量评估前：

1. 先查询通话数量（使用 page_size=1 并读取响应中的数量）
2. 将数量告知用户
3. 如果数量 > 100，停止并先征求用户明确批准

使用 page_size 参数（最多 200），而不是通过翻阅多页来获取数据。在评估前使用服务端筛选条件（agent_id、project、timestamp__gte/timestamp__lte）限定通话范围。

步骤 5：验证修改

对结果不一致的同一批通话，重新运行改进后的指标：

使用 POST /observability/v1/call-logs/rerun_evaluation/，并传入通话 ID 和指标 ID。

检查：

• 之前结果不一致的通话现在是否产生了正确结果？
• 之前结果正确的通话是否仍然正确（没有回归）？
• 解释是否更清晰、更准确？

如果验证未通过，请留下更多反馈并继续迭代。

步骤 6：部署（可选的 Pythonic 转换）

通过实验室验证指标提示词后，可以考虑将其转换为 Pythonic custom_code 指标以用于生产环境：

1. 从 llm_judge 的 description 字段中获取最终验证通过的提示词
2. 将其封装在 custom_code 中，并提取相应区段（请参阅 metric-design 技能）
3. 同时设置 description（提示词）和 custom_code（Python 封装代码）
4. 将当前启用的类型切换为 custom_code

这样既能利用经过实验室优化的提示词，又能通过有针对性的上下文提取提升性能。

交互式实验室模拟

当用户希望以交互方式模拟实验室工作流时：

1. 获取近期通话和指标结果
2. 逐条向用户展示可能存在偏差的结果
3. 询问：“通话 [ID] 的评分为 [result]。解释如下：[explanation]。转录内容显示：[relevant excerpt]。你是否同意这一结果？”
4. 如果用户不同意，生成反馈负载并通过 mark_metric_vote 提交
5. 跟踪反馈数量，并在达到 6 条或更多时通知用户
6. 提出触发自动改进

后续步骤

改进指标后，用户通常需要：

• 在新的通话样本上重新运行，以确认修复有效（使用 evaluate-calls / rerun_evaluation 端点）
• 将类似模式应用于其他指标 → 对于需要相同范围界定的新指标，调用 cekura-metric-design
• 根据测试场景进行验证 → 如果指标行为取决于特定评估流程，则调用 cekura-eval-design

API 端点参考

端点	用途
GET /observability/v2/call-logs/?agent=ID	列出通话
GET /observability/v2/call-logs/{id}/	获取通话详情和评估结果
POST /observability/v1/call-logs-external/{id}/mark_metric_vote/	提交反馈
POST /test_framework/metric-reviews/process_feedbacks/	运行实验室自动改进（见下文）
GET /test_framework/metric-reviews/process_feedbacks_progress/	轮询改进进度
POST /observability/v1/call-logs/evaluate_metrics/	对通话评估指定指标
POST /observability/v1/call-logs/rerun_evaluation/	对通话重新运行评估
POST /test_framework/test-sets/create_from_call_log/	根据通话日志创建测试集

实验室自动改进（process_feedbacks）

POST /test_framework/metric-reviews/process_feedbacks/
{
  "metric_id": 123,
  "test_set_ids": [456, 789]
}

可选字段：metric_type（默认值为 "llm_judge"）、skip_evaluation（布尔值）、simplified_prompt（字符串）。

返回 {"progress_id": "<uuid>"}。通过 GET /test_framework/metric-reviews/process_feedbacks_progress/?progress_id=<uuid> 轮询。

完成后，响应会包含改进后的 description 和 evaluation_trigger——必须 PATCH 该指标以应用更改（更改不会自动应用）。

根据通话日志创建测试集

POST /test_framework/test-sets/create_from_call_log/
{
  "call_log_id": 5550000,
  "metrics": [{"metric": 123, "feedback": "The metric incorrectly failed this call because..."}]
}

注意：metrics 必须是对象数组 [{"metric": <id>, "feedback": "<text>"}]，而不是单独的指标 ID。传入单独的 ID 会返回 500。

其他资源

参考文件

• references/feedback-examples.md —— 不同指标类型的优质反馈示例