135 lines
3.3 KiB
Markdown
135 lines
3.3 KiB
Markdown
# 场景模块详细设计
|
||
|
||
## 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` 获取完整配置。
|