场景模块详细设计

1. 模块目标

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

2. 职责边界

负责：

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

不负责：

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

3. 场景配置结构

必填结构：

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. 场景加载流程

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

为了便于复试修改，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. 服务函数设计

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 获取完整配置。

3.3 KiB Raw Blame History Unescape Escape