name: scenario-design
description: 设计Agent评测场景的统一配置文件(unified_scenario_design.yaml)。当需要创建新评测场景、设计需求模板、提升样本难度时使用此技能。这是init阶段最核心的工作，决定了样本质量和难度。

场景设计指南

Overview

场景设计是评测框架的init阶段核心工作，产出unified_scenario_design.yaml作为后续所有环节的输入。

核心原则：难度来自真实业务复杂性，而非人为刁难；可验证是底线。

Agent能力评测体系（9个核心能力）

场景设计的最终目标是全方位评测LLM Agent在实际落地中的必备能力。每个场景应至少测试其中2-3个能力：

设计方法与能力的映射

场景设计时的能力覆盖检查

设计场景时，建议在YAML中增加tested_capabilities字段标注测试的能力：

tested_capabilities:
  - capability: "Prompt遵循"
    测试方式: "复杂业务规则中的条件判断和优先级处理"
  - capability: "Tool Use"
    测试方式: "正确选择工具和构造参数以完成状态更新"
  - capability: "多源信息融合"
    测试方式: "从多个实体中提取信息并做出决策"

五种设计方法

根据场景特点选择合适的设计方法（可组合使用）：

推荐组合：多轮变更 + 信息洋葱 + 复杂规则

详细指南：references/scenario_design_patterns.md

YAML核心结构

scenario_name: "场景名称"
sub_scenario_type: "子场景类型"
description: "场景描述"

runtime_config:           # 时间基准
  system_time: "2025-07-16T10:00:00Z"

entities:                 # 实体定义
  主实体:
    attributes: {...}
    relationships: [...]

business_rules:           # 业务规则
  rule_X:
    trigger_conditions: {...}
    required_actions: [...]
    success_criteria: [...]
    sample_generation:
      query_templates: [...]
      data_variations: [...]

完整模板：references/scenario_template.yaml

关键概念：Entity vs 外部知识

Entity（实体）的定义

Entity 是样本合成时的变量，分为两类：

1. Query 变量：出现在用户需求中的可变参数
2. 例如：用户指定的题材、目标受众、集数要求

3. 这些会直接影响 query 的生成

4. Environment 变量：环境中的可变数据

5. 例如：不同的订单记录、不同的用户数据池
6. 这些是 Agent 可以查询的背景信息

不应该作为 Entity 的：
- ❌ 领域知识（如"都市甜宠短剧的创作原则"）→ 应该放在 Skill 文档中，作为可查询的知识
- ❌ 固定的格式规范 → 应该放在 format_specifications 中
- ❌ 通用的业务规则 → 应该放在 business_rules 或 BusinessRules.md 中

决策树：这个信息应该放在哪里？

Q1: 这个信息在不同样本之间会变化吗？
    ├─ YES → 继续 Q2
    └─ NO  → 不是 Entity（考虑 Skill/Format/BusinessRules）

Q2: 变化的内容是用户需求的一部分还是环境背景？
    ├─ 用户需求 → Query Variable Entity
    └─ 环境背景 → Environment Variable Entity

Q3: 这个信息是原始数据还是规则/知识？
    ├─ 原始数据 → Environment Entity (在 environment 或 datapool 中)
    └─ 规则/知识 → Skill Entity (可查询的领域知识)

示例：短剧创作场景

正确的 Entity 设计：

entities:
  genre_skill:  # Skill Entity（领域知识）
    type: "knowledge_base"
    description: "题材相关的创作指南"
    attributes:
      genre_type: string    # 变量：都市甜宠、古装权谋等
      skill_file: file      # 指向 datapool 中的 skill 文档

不正确的设计：

# ❌ 错误示例1：把 Skill 内容直接写在 Entity 中
entities:
  genre_rules:
    attributes:
      sweet_romance_rules: "甜宠剧的钩子必须包含..."  # 错误：这是固定知识

# ❌ 错误示例2：把格式规范当作 Entity
entities:
  topic_brief:
    attributes:
      format: "钩子长度15-50字"  # 错误：这是格式约束，应该在 format_specifications 中

Business Rules 设计原则

三个核心判断标准

在 YAML 的 business_rules 中放入规则前，必须满足以下三个条件：

1. 通用性检查：这个规则是否适用于所有题材/所有样本？
2. ✅ 例如："选题简报必须包含钩子、价值主张、关键元素"

3. ❌ 例如："甜宠剧的钩子要体现甜蜜感" → 应该放在题材 Skill 中

4. 必要性检查：Agent 看不到这个规则会无法完成任务吗？

5. ✅ 例如："角色卡必须包含8个维度"（格式要求）

6. ❌ 例如："应该先创建选题再设计角色" → Agent 可以自主规划

7. 不可推理性检查：Agent 通过常识或上下文无法推理出这个规则吗？

8. ✅ 例如:"集数默认为3，除非用户明确指定" → 必须明确告知
9. ❌ 例如："短剧需要有故事情节" → 常识，不需要写

放入 business_rules 的典型内容

不应该放入 business_rules 的内容

决策流程图

这条规则应该放在 business_rules 中吗？
    │
    ├─ Q1: 是否适用所有题材/样本？
    │   └─ NO → 放入题材 Skill 或 user_need_template
    │
    ├─ Q2: Agent 看不到会无法完成任务吗？
    │   └─ NO → 不需要放（Agent 可自主决策）
    │
    ├─ Q3: 这是格式细节（JSON 结构）吗？
    │   └─ YES → 放入 format_specifications.json
    │
    └─ 三个条件都满足 → 可以放入 business_rules

格式规范的分离原则

建议将详细的格式规范独立到 format_specifications 中：

Before (不推荐)：

business_rules:
  rule_topic_format:
    description: "选题简报格式要求"
    constraints:
      - "钩子长度15-50字"
      - "必须包含核心元素、冲突和价值主张"
      - "JSON 格式：{hook: string, elements: [...], ...}"

After (推荐)：

# YAML 中只保留高层描述
business_rules:
  rule_topic_format:
    description: "选题简报必须符合 format_specifications 中的 topic_brief_schema"

# 详细格式规范放在独立文档
format_specifications:
  - spec_name: "topic_brief_schema"
    file_path: "datapool/specs/topic_brief_format.json"
    description: "选题简报的完整格式规范（JSON Schema）"

优势：
1. Business Rules 保持简洁，只描述"必须遵守什么规范"
2. 格式细节结构化，便于 Checker 验证
3. Agent 可以通过文件读取获取详细规范（像 Skill 一样）

约束力度设计

在统一配置中定义业务规则时，约束的表达力度直接影响Agent的执行效果。

强制性 vs 条件性表达

核心原则：目标明确时用强制性，有选择时用条件性

❌ 弱表达（有解释余地）：
- "如果用户明确指定X，则执行Y"
- "建议遵循Z原则"
- "尽量完成W"

✅ 强表达（直接传达目标）：
- "必须完成用户指定的所有X"
- "所有Y必须包含Z字段"
- "禁止在W情况下执行V"

判断标准：
- 如果这是check_item要验证的核心目标 → 用强制性
- 如果Agent需要根据情况判断 → 用条件性
- 如果是辅助建议 → 可以用建议性

应用示例：明确优先级

当场景涉及多种选择时，明确优先级能避免Agent困惑：

交互方式优先级：

business_rules:
  checkpoint_confirmation:
    rule: |
      交互方式优先级：
      - 优先通过Human In The Loop性质的工具与用户进行交互
      - 仅当工具无法支持所需的交互类型时，才在对话回复中直接询问用户

数据源优先级：

business_rules:
  data_source_priority:
    rule: |
      数据源优先级：
      1. 优先使用用户明确提供的数据
      2. 当用户未提供时，查询系统记录
      3. 仅当两者都无时，使用默认值

设计意图：
- 通过优先级排序，让Agent在多选项时有明确依据
- 避免Agent在交互方式、数据来源等方面产生困惑
- 确保关键业务目标（如用户指定的集数）不被弱化表达

环境隔离设计（重要）

执行机制：每个样本在独立临时目录中执行，由executor自动创建和清理。

何时需要environment字段：
- 样本需要数据文件（JSONL/JSON/CSV）、数据库（SQLite）、或配置文件

environment格式：

environment:
  - type: file          # file/db/binary/sh
    path: "data.jsonl"  # 相对路径
    content: "..."

servers.json中使用占位符：

mcpServers:
  filesystem:
    args: ["${ENV_DIR}"]  # executor自动替换为临时目录路径

需求模板设计

需求模板是样本多样性的核心，每个模板代表一种用户需求场景：

templates:
- need_template_id: LA_ANNUAL_WITH_COMPENSATORY
  description: 年假申请,调休充足优先扣除
  test_type: positive                    # positive/negative
  user_need_description: |               # 用户需求描述（用于生成query）
    你的需求：
    - 请假类型：{{leave_type_cn}}
    - 请假时间：{{leave_time_description}}
  employee_filter_conditions:            # 数据筛选条件
    - field: compensatory_leave_balance
      operator: '>='
      value: 3
  disclosure_pace: progressive           # 信息披露节奏
  validation_checks:                     # 验证点
    - check_type: create_operation_verified
      entity_type: leave_applications
      filter_conditions: {...}

详细指南：references/need_template_design.md

参数配置原则：配置化而非解析化

核心原则：在 template 中明确配置所有参数，而不是依赖运行时从 query 文本中 NLP 解析。

正确做法：在 template 中明确配置参数

templates:
- need_template_id: SD_SWEET_10_EPISODES
  description: "10集的甜宠短剧创作"

  # ✅ 明确配置参数
  parameters:
    genre: "sweet_romance"
    episode_count: 10
    target_audience: "18-34岁女性"

  # Query 模板引用这些参数
  user_need_description: |
    我想做一个都市甜宠短剧，共{episode_count}集。
    目标受众：{target_audience}

  # Checker 使用相同的参数验证
  check_list:
    - check_type: "file_count"
      params:
        directory: "outlines/"
        expected_count: 10  # 直接使用配置的值

错误做法：依赖文本解析

templates:
- need_template_id: SD_SWEET_CUSTOM
  # ❌ 错误：让 Checker 从 query 中解析集数
  user_need_description: |
    我想做一个10集的短剧

  check_list:
    - check_type: "file_count"
      params:
        directory: "outlines/"
        # ❌ 用规则从 query 提取：如果 query 包含"X集"...
        extract_from_query: "\\d+集"

参数的两种来源

1. 固定参数：在 template 配置中直接指定
   yaml parameters: episode_count: 10 # 固定值

2. 变量参数：从 entity 数据池中采样
   yaml entity_filter: genre_type: "sweet_romance" # 筛选条件

关键：无论哪种方式，参数都应该是已知的、结构化的，而不是依赖运行时从文本中 NLP 解析。

设计流程（3步）

质量快速检查

• [ ] entities覆盖所有业务实体和关键属性
• [ ] business_rules的success_criteria可客观验证
• [ ] need_templates覆盖正向/负向/边界场景
• [ ] 难度设计能有效区分不同模型能力

Reference Files

优秀案例

关键原则

1. 方法可组合 - 一个场景可以同时使用多种设计方法
2. 难度来自业务 - 真实业务复杂性，而非人为设计的陷阱
3. 可验证是底线 - 所有success_criteria必须客观可验证
4. 覆盖要全面 - 正向/负向/边界场景都要设计

可验证性设计指南（关键）

验证方式优先级

设计时的可验证性自检

设计每个check_item时问自己：

Q1: 这个检查点能通过final_state的字段值验证吗？
    → YES: 使用 entity_attribute_equals
    → NO: 继续Q2

Q2: 这个检查点是验证工具是否被调用/参数是否正确吗？
    → YES: 使用 tool_called_with_params
    → NO: 继续Q3

Q3: 这个检查点是验证Agent回复中的特定内容吗？
    → YES: 使用 response_contains_keywords (先尝试关键词匹配)
    → NO: 继续Q4

Q4: 这个检查点必须理解语义才能判断吗？
    → YES: 使用 use_llm_judge: true（最后手段）
    → NO: 重新审视检查点设计

反模式（必须避免）