DEMO-AGENT/docs/需求分析/2.scenarios模块需求分析.md

Scenarios 模块需求分析

1. 模块定位

apps.scenarios 模块在当前代码中承担“场景列表展示与配置读取”职责。在本题重构后，它不应继续被理解为“多类题型模板市场”，而应升级为：

注册申报资料审核任务配置中心

也就是说，系统仍然可以保留配置化入口，但配置的对象不再是“知识问答、工单助手、财务审核”等通用 Agent，而是围绕注册申报业务拆分的若干子任务或工作模式。

2. 重构目标

本模块需要完成以下目标：

1. 把当前项目首页从“通用 Demo 场景列表”重构为“注册申报任务入口页”。
2. 用配置化方式定义不同审核任务的目标、输入、输出和可调用能力。
3. 支撑后续 Demo 演示时快速切换不同任务视角，而不是频繁改代码。
4. 保持与 agent_core 的边界清晰，即场景模块只定义任务，不实现任务逻辑。

结合新增公告材料，场景模块还应承担“法规流程类型选择器”的角色，避免把注册申报、变更备案、延续注册三类任务混成一个入口。

3. 为什么本题仍然需要场景模块

虽然本题更像一个垂直系统，但场景模块依然有价值，原因有三：

1. 题面本身包含多个不同子任务：目录汇总、完整性检查、信息提取、回填、一致性核查、风险预警。
2. 复试演示通常需要分步骤展示，若所有能力都硬塞在一个入口，会让页面和结果过于拥挤。
3. 后续需求方很可能会提出“只想先看资料齐套性”“只想看字段抽取”这类细分诉求，配置化任务入口比写死流程更灵活。

4. 建议的场景体系

4.1 不建议继续使用通用题型命名

现有 knowledge_qa、ticket_assistant、risk_audit 等命名与本题关联度太弱。首版建议替换为以下业务导向任务：

1. registration_overview 注册资料总览助手

2. registration_completeness_check 法规完整性核查助手

3. registration_field_extraction 产品关键信息抽取与回填助手

4. registration_consistency_review 跨文档一致性核查助手

5. registration_risk_report 合规风险预警助手

首版仍建议以 registration_* 作为主任务族，但应在配置语义上预留后续扩展族，例如：

• change_registration_*
• renewal_registration_*

4.2 是否需要多个场景还是一个总场景

建议首版保留“一个主场景 + 若干子任务配置”的思路：

• 页面上可以展示多个任务入口。
• 底层可共享同一个项目资料池和统一字段池。
• Demo 演示时可以先点“完整性检查”，再点“一致性核查”，展示系统分工明确。

5. 场景配置应包含的内容

每个任务配置文件建议至少包含以下信息：

5.1 基础标识

• id
• name
• description
• icon 或展示标签
• sort_order

5.2 任务目标

• 当前任务处理什么问题
• 适用输入资料范围
• 输出结果形式

例如，完整性检查任务的目标可以表述为：

根据 NMPA 注册申报资料要求，对当前项目资料包进行章节点齐套性检查、缺失项识别和待补清单生成。

5.3 输入约束

• 是否依赖已上传文件
• 是否依赖已入库文本
• 是否需要指定资料章节点
• 是否允许只针对选中文档执行

5.4 规则和工具绑定

• 需要的规则集
• 允许调用的工具列表
• 是否启用 RAG
• 是否启用统一字段池

5.5 输出模板

• 结构化结果类型
• 页面展示字段
• 是否生成报告
• 是否触发审计日志

6. 页面层需求

6.1 首页需要表达的内容

首页不应只展示“这是几个 YAML 场景”，而应展示当前系统已支持的注册审核任务。建议每个任务卡片至少包含：

• 任务名称
• 任务目标
• 典型输入
• 典型输出
• 依赖资料条件
• 当前是否可执行

6.2 可执行状态判断

场景模块应能给出任务是否可执行的判定。例如：

• 未上传任何资料：完整性检查可执行，但只会提示无资料。
• 已上传未入库：目录汇总可执行，RAG 相关任务应提示需先入库。
• 规则文件缺失：完整性检查场景显示不可执行或部分能力不可用。

这类状态说明非常适合复试演示，因为它体现了系统不是“死调用大模型”，而是有明确任务前置条件。

7. 配置驱动的业务能力

7.1 目录汇总任务

该任务侧重：

• 扫描文件夹
• 统计文件数、页数、章节点
• 生成目录总览表

配置上需要指定：

• 可读取的资料范围
• 输出字段，如文件名、文件类型、所属章节、页数、状态

7.2 完整性核查任务

该任务侧重：

• 读取法规模板
• 比对当前资料是否齐套
• 识别缺失文件、错放文件、待人工确认项

结合公告附件包，该任务还应明确区分三层依据：

1. 注册申报资料要求及说明
2. 批准证明文件格式要求
3. 安全和性能基本原则清单

配置上需要指定：

• 对应法规规则版本
• 缺失项风险等级策略
• 默认输出清单字段

7.3 字段抽取任务

该任务侧重：

• 从说明书、申请表、产品列表等材料提取产品名称、靶标、适用范围、规格、储存条件、性能信息等
• 形成统一字段池
• 将产品名称、检测靶标、适用范围、储存条件、性能指标等核心信息自动填入注册申报表格或对照清单

配置上需要指定：

• 目标字段 schema
• 字段来源优先级
• 是否允许 LLM 兜底抽取
• 注册申报表格 / 对照清单的字段映射关系
• 是否生成 Word 输出和导出入口

7.4 一致性核查任务

该任务侧重：

• 比对统一字段池中的冲突项
• 输出冲突来源、冲突内容和处理建议

配置上需要指定：

• 必须完全一致的字段
• 默认按完全一致处理的字段
• 风险分级规则

7.5 风险预警任务

该任务侧重：

• 汇总前述各任务结果
• 形成综合风险清单
• 给出整改建议和优先级

配置上需要指定：

• 风险合并策略
• 高中低风险判定口径
• 责任归属字段
• 飞书通知目标字段

7.6 法规依据展示任务或结果区

基于新增公告材料，建议在任务配置中增加法规依据展示能力，至少能让系统说明：

1. 当前任务对应的是哪类法规流程。
2. 使用了哪份资料要求说明。
3. 使用了哪份格式要求或批准证明文件模板。

8. 与原始材料对应的任务设计要点

8.1 要能体现“资料结构化目录”的任务价值

CH1.2 监管信息目录.docx 已经给出一个非常适合 Demo 的目录样例，场景模块应支持把“监管目录核对”配置成单独任务，而不是只能在自由聊天中触发。

结合新增公告材料，这个任务还应能够说明当前目录核对所引用的是“资料要求说明”而不是任意自由目录。

8.2 要能体现“跨文档冲突识别”的任务价值

当前材料中的产品名称冲突非常典型，但结合最新确认，系统目标是通用试剂盒注册审核智能体，而不是只围绕某一个固定产品。因此，一致性核查任务应强调：

1. 先界定审核范围，再执行严格一致性检查。
2. 对同一审核范围内的字段按完全一致规则比对。
3. 对疑似混档资料单独输出风险提示。

8.3 要能体现“历史申报沟通说明”的任务价值

CH1.9 所反映的历史受理、撤回、替换临床机构等内容，适合在风险预警任务中作为“历史事项复核”子项展示。

8.4 要为飞书接入预留并实现任务入口语义

结合当前确认结果，场景模块建议为飞书访问统一维护任务标识和简短描述，便于后续：

1. 在飞书机器人中按任务 ID 触发。
2. 在飞书侧展示任务摘要和结果链接。
3. 将“通知责任人”与任务类型建立映射。
4. 支持群聊机器人中的任务选择与结果查看。

如果后续采用飞书开放平台的 Agent 接入路线，还应确保这些任务标识可以映射到飞书消息指令、评论触发或会话菜单项。

9. 场景模块与其他模块的边界

9.1 与 Chat 模块的边界

场景模块定义任务卡片和执行入口，Chat 模块负责用户进入任务后的具体交互与结果展示。

9.2 与 Documents 模块的边界

场景模块不负责解析文档，只负责声明“当前任务依赖哪些资料和结构化资产”。

9.3 与 Agent Core 的边界

场景模块定义任务目标、输出模板、可用工具和规则集；Agent Core 负责真正执行审核与抽取。

10. 建议的配置文件组织方式

建议将当前 configs/ 目录从“题型模板”调整为“注册任务配置”，例如：

configs/
  registration_overview.yaml
  registration_completeness_check.yaml
  registration_field_extraction.yaml
  registration_consistency_review.yaml
  registration_risk_report.yaml

如果后续希望再进一步清晰化，也可以拆分为：

configs/registration/
  overview.yaml
  completeness.yaml
  extraction.yaml
  consistency.yaml
  risk_report.yaml

但首版不必为了目录优雅而过度重构。

11. 首版验收要求

本模块完成后，应达到以下效果：

1. 首页展示的任务名称、描述和本题业务强相关。
2. 每个任务的输入前提、输出类型和所依赖规则清晰可见。
3. 任务配置变更主要通过 YAML 完成，不需要频繁改 Python 代码。
4. 至少能清楚区分“目录汇总、完整性检查、字段抽取、一致性核查、风险预警”五类任务。
5. 字段抽取任务必须能表达“抽取核心信息并自动填入注册申报表格或对照清单”的输出目标。

12. 当前代码基线下的重构建议

12.1 建议保留

• 通过配置文件驱动场景展示的思路
• 场景读取失败时对首页做容错提示的机制

12.2 建议替换

1. 将“适用题型”文案替换为“任务适用资料/适用阶段”。
2. 将当前通用场景命名替换为注册审核任务命名。
3. 增加任务前置条件和执行依赖展示。
4. 增加“是否依赖字段池”“是否依赖法规模板”等配置位。

13. 本模块在复试讲解中的价值

如果场景模块重构到位，复试时可以很自然地说明：

1. 为什么不是把所有能力塞进一个聊天机器人。
2. 为什么用配置驱动的任务入口更适合监管审核场景。
3. 如何在不推翻现有系统结构的情况下，快速从通用 Demo 切换到具体业务题。

这会直接增强整套系统的“工程化思维”观感。