# Scenarios 模块需求文档

## 1. 模块定位

Scenarios 模块负责管理业务 Agent 场景，是整个平台快速适配未知复试题的核心入口。

场景定义需要尽量配置化，避免把具体业务逻辑写死在 Django View 或 Agent Core 中。

## 2. 模块目标

- 读取预置场景配置。
- 展示可用业务 Agent 列表。
- 提供场景详情。
- 为 Chat 模块提供当前场景的完整配置。
- 支持后续扩展为 Django Admin 可编辑场景。

## 3. 职责边界

### 3.1 负责

- 场景模板定义。
- 场景配置文件读取。
- 场景元信息展示。
- 场景启用/禁用状态。
- 场景与文档、审计日志的关联关系。

### 3.2 不负责

- 不执行 Agent 对话。
- 不直接处理 RAG 检索。
- 不直接调用工具。
- 不直接调用大模型。
- 不解析结构化输出。

## 4. 场景模板需求

V1 预置 5 类场景模板：

| 模板 ID | 模板名称 | 适用题型 |
|---|---|---|
| `knowledge_qa` | 知识库问答助手 | SOP、制度、客服知识库、内部文档问答 |
| `document_review` | 文档审核助手 | 合同审核、制度审核、材料合规检查 |
| `ticket_assistant` | 工单处理助手 | 客服工单、售后工单、运维工单 |
| `quality_analysis` | 质量异常分析助手 | 生产质量、缺陷分析、原因定位 |
| `risk_audit` | 风险审核助手 | 财务审核、采购审核、报销审核、合同风险 |

## 5. 场景配置字段

场景配置文件建议使用 YAML。

必填字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | string | 场景唯一标识 |
| `name` | string | 场景名称 |
| `description` | string | 场景说明 |
| `agent.role` | string | Agent 角色 |
| `agent.goal` | string | Agent 目标 |
| `agent.instructions` | list[string] | Agent 指令 |
| `rag.enabled` | boolean | 是否启用 RAG |
| `tools` | list[string] | 可用工具列表 |
| `output.type` | string | 输出模板类型 |
| `audit.enabled` | boolean | 是否记录审计 |

示例：

```yaml
id: document_review
name: 文档审核助手
description: 检查合同、制度或 SOP 中的风险点和缺失项

agent:
  role: 文档审核专家
  goal: 根据审核规则和知识库内容输出结构化审核意见
  instructions:
    - 只基于用户提供文档和知识库进行判断
    - 不确定的问题必须标记为需人工复核
    - 输出必须包含风险等级和修改建议

rag:
  enabled: true
  collection: document_review
  top_k: 5

tools:
  - check_required_fields

output:
  type: document_review_report

audit:
  enabled: true
```

## 6. 页面需求

### 6.1 场景列表页

路径：`/`

展示内容：

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

### 6.2 场景详情页 可选

路径：`/scenarios/<scenario_id>/`

展示内容：

- Agent 角色。
- Agent 目标。
- RAG 是否启用。
- 可用工具列表。
- 输出模板类型。

V1 可以不做独立详情页，在对话页展示当前场景摘要即可。

## 7. 服务接口需求

Scenarios 模块至少需要提供以下服务函数：

```text
list_scenarios() -> list[ScenarioConfig]
get_scenario(scenario_id: str) -> ScenarioConfig
validate_scenario(config: dict) -> ValidationResult
```

## 8. 验收标准

- 首页可以展示 5 个预置场景。
- 点击场景可以进入对应对话页。
- 场景配置来自配置文件，而不是硬编码在 View 中。
- 缺失必填字段时能给出明确错误。
- Chat 模块可以根据 `scenario_id` 获取完整场景配置。