# 场景模块详细设计

## 1. 模块目标

Scenarios 模块是业务 Agent 的入口，负责读取和展示场景配置，并向 Chat、Documents、Agent Core 提供场景上下文。

## 2. 职责边界

负责：

- 从 `configs/*.yaml` 读取场景。
- 校验场景必填字段。
- 展示场景列表和场景摘要。
- 提供 `list_scenarios()`、`get_scenario()` 等服务。

不负责：

- 不执行 Agent。
- 不做 RAG 检索。
- 不调用工具和大模型。
- 不保存审计日志。

## 3. 场景配置结构

必填结构：

```yaml
id: knowledge_qa
name: 知识库问答助手
description: 用于 SOP、制度和内部知识库问答
applicable_questions:
  - SOP 问答
  - 制度问答

agent:
  role: 知识库问答专家
  goal: 基于知识库回答用户问题
  system_prompt: ""
  instructions:
    - 回答必须基于检索内容

rag:
  enabled: true
  collection: knowledge_qa
  top_k: 5

tools:
  - generate_action_items

output:
  type: general_answer

audit:
  enabled: true
```

`agent.system_prompt` 为可选字段。配置了非空值时，Agent Core 优先使用该字段作为系统提示词；为空或缺失时，由 `role`、`goal` 和 `instructions` 组合生成系统提示词。

`applicable_questions` 作为页面展示字段，若缺失可显示为空列表。

## 4. 场景加载流程

1. 读取 `settings.SCENARIO_CONFIG_DIR`。
2. 遍历 `.yaml` 和 `.yml` 文件。
3. 使用 YAML parser 转为 dict。
4. 调用 `validate_scenario()`。
5. 转换为 `ScenarioConfig` dataclass 或普通 dict。
6. 按文件名或配置顺序返回。

为了便于复试修改，V1 不需要强缓存；若加缓存，应提供清理方式或在 DEBUG 下禁用缓存。

## 5. 场景校验规则

必填字段：

- `id`
- `name`
- `description`
- `agent.role`
- `agent.goal`
- `agent.instructions`
- `rag.enabled`
- `tools`
- `output.type`
- `audit.enabled`

校验失败时返回包含文件名、字段路径、错误原因的结果。列表页可以跳过非法场景并展示错误摘要。

## 6. 页面设计

首页路径：`/`

展示：

- 场景名称。
- 场景描述。
- 适用题型。
- RAG 是否启用。
- 工具数量。
- 进入对话按钮。

可选详情页：`/scenarios/<scenario_id>/`。V1 可以把详情合并到 Chat 页面。

## 7. 服务函数设计

```python
def list_scenarios() -> list[ScenarioConfig]:
    """读取配置目录中的合法场景，非法场景以错误摘要返回给页面。"""

def get_scenario(scenario_id: str) -> ScenarioConfig:
    """按场景 ID 返回完整配置，找不到时抛出 ScenarioNotFound。"""

def validate_scenario(config: dict) -> ValidationResult:
    """校验必填字段、字段类型、工具名称和输出类型。"""
```

`get_scenario()` 找不到时抛出业务异常，例如 `ScenarioNotFound`，由 View 转成中文错误提示。

## 8. 异常处理

| 异常 | 处理 |
|---|---|
| 配置目录不存在 | 返回空列表和错误提示 |
| YAML 语法错误 | 标记该文件无效 |
| ID 重复 | 保留第一个，报告重复错误 |
| 必填字段缺失 | 标记该场景无效 |
| 工具不存在 | 场景仍可展示，但 Chat 执行时记录工具错误 |

## 9. 验收标准

- 首页至少展示 5 个场景。
- 场景配置来自 `configs/` 文件。
- 非法配置有明确错误，不导致首页 500。
- Chat 可通过 `scenario_id` 获取完整配置。