name: checker-implementation
description: 实现Agent评测场景的检查器(Checkers)。当需要验证Agent行为是否正确、设计评测检查点时使用此技能。基于独立脚本模式。

Checker实现指南

验证优先级（必须遵循）

框架：独立脚本模式

开源版checker是独立的Python脚本，通过CLI参数运行。

基本结构

#!/usr/bin/env python3
import json
import argparse

def perform_check(bench_data, result_data, model_name, api_base, api_key):
    """主检查函数"""
    check_result = {
        "overall_result": "Success",  # Success / Failure / Error
        "check_details": {},
        "check_list_count": 0,
    }

    check_list = bench_data.get("check_list", [])

    for i, item in enumerate(check_list):
        check_type = item.get("check_type")
        # 根据check_type调用相应检查器
        ...

    return check_result

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--bench", required=True)
    parser.add_argument("--result", required=True)
    parser.add_argument("--model", required=True)
    parser.add_argument("--base-url", required=True)
    parser.add_argument("--api-key", required=True)
    parser.add_argument("--output", default="check_result.json")
    args = parser.parse_args()

    # 加载数据、执行检查、保存结果
    ...

if __name__ == "__main__":
    main()

Checker 类型的职责分层

分层原则：避免重复校验

示例：选题简报的三层校验

第一层：结构校验（json_schema）

check_list:
  - check_type: "json_schema_validation"
    params:
      file_path: "outputs/topic_brief.json"
      schema_path: "specs/topic_brief_schema.json"
    description: "验证选题简报的 JSON 结构完整性"

第二层：业务规则校验（entity_attribute_equals）

  - check_type: "string_length_in_range"
    params:
      file_path: "outputs/topic_brief.json"
      field: "hook"
      min_length: 15
      max_length: 50
    description: "验证钩子长度符合 skill 要求"

第三层：语义质量校验（semantic）

  - check_type: "semantic_quality_check"
    params:
      file_path: "outputs/topic_brief.json"
      field: "hook"
      criteria: "钩子是否体现了核心冲突和悬念"
      use_llm_judge: true
    description: "验证钩子的创意质量"

避免重复校验的决策树

这个检查点应该用什么 Checker？
    │
    ├─ Q1: 检查的是 JSON 结构吗（字段存在、类型正确）？
    │   └─ YES → json_schema
    │
    ├─ Q2: 检查的是数值/长度/格式等业务规则吗？
    │   └─ YES → entity_attribute_equals 或 specialized checker
    │
    └─ Q3: 检查的是语义质量、创意水平、合理性吗？
        └─ YES → semantic_check_with_llm

可用check_type速查

⚠️ 设计原则：优先复用成熟Checker

核心原则：优先使用下表中已有的成熟checker类型，必要时再设计新的。

为什么优先复用：
- ✅ 已有checker经过多场景验证，稳定可靠
- ✅ 减少重复开发，提高效率
- ✅ 保持验证逻辑的一致性
- ✅ 降低维护成本

何时添加新checker：
- 现有checker无法满足验证需求
- 验证逻辑在多个场景中复用（至少2-3个场景）
- 新checker提供显著的可读性或可维护性提升

成熟的Checker类型

check_item格式

// 环境状态验证
{
  "check_type": "entity_attribute_equals",
  "params": {
    "entity_type": "orders",
    "target_id": "order_001",
    "attribute_key": "status",
    "expected_value": "completed"
  },
  "description": "订单状态应为已完成"
}

// 工具调用验证
{
  "check_type": "tool_called_with_params",
  "params": {
    "tool_name": "adjust_order_fee",
    "expected_params": {
      "order_guid": "order_001",
      "new_fee": 5.0
    }
  }
}

// Response语义检查（使用LLM）
{
  "check_type": "response_contains_keywords",
  "params": {
    "expected_keywords": ["费用已调整", "订单"],
    "use_llm_judge": true
  }
}

// 调用顺序验证
{
  "check_type": "prerequisite_check_performed",
  "params": {
    "prerequisite_tool": "get_user_info",
    "business_tool": "issue_coupon",
    "related_entity_id": "user_uuid"
  }
}

检查结果格式

def create_check_item_result(conclusion, reason, details):
    """单个检查项结果"""
    return {
        "检查结论": conclusion,  # 合格 / 不合格 / 跳过
        "原因": reason,
        "详情": details
    }

# 示例
{
    "检查结论": "合格",
    "原因": "属性值匹配",
    "详情": "订单 order_001 的 status = 'completed'，符合期望"
}

总体结果格式

{
  "check_version": "scenario_v1.0",
  "check_timestamp": 1704067200,
  "overall_result": "Success",
  "check_list_count": 3,
  "check_details": {
    "检查项1": {"检查结论": "合格", ...},
    "检查项2": {"检查结论": "合格", ...},
    "检查项3": {"检查结论": "不合格", ...}
  },
  "completion_status": "completed",
  "error_reason": "失败项: 检查项3"
}

CLI调用方式

python checker.py \
  --bench sample.json \
  --result result.json \
  --model deepseek-v3 \
  --base-url https://api.deepseek.com/v1 \
  --api-key sk-xxx \
  --output check_result.json \
  --work-dir ./env_data

设计检查清单

• [ ] 优先使用环境状态验证（entity_attribute_equals）
• [ ] 工具调用验证仅用于：顺序验证、无状态动作
• [ ] expected_params使用字典格式，Agent决策参数用null通配
• [ ] 语义检查使用use_llm_judge: true
• [ ] 返回统一格式：{检查结论, 原因, 详情}

Reference Files

完整实现参考：mcp-benchmark/release/scenarios/*/checker.py