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

Scenarios 模块需求分析

1. 模块定位

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

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

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

需要特别说明的是：最新版原型已经把顶层导航收敛为 审核智能体 / 资料包 / 知识库 / 处理历史，因此 apps.scenarios 不再承担“首页大卡片导航中心”的产品角色，而是退回为 Agent 工作台中的任务模板与流程节点配置中心。

2. 重构目标

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

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

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

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 是否需要多个场景还是一个总场景

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

• 顶层页面不再展示多个独立业务页面，而是在 审核智能体 中展示多个任务模板与节点入口。
• 底层可共享同一个项目资料池和统一字段池。
• Demo 演示时可以先触发“目录汇总”，再继续执行“完整性检查”“一致性核查”，展示 Agent 沿节点推进。

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. 使用了哪份格式要求或批准证明文件模板。

但该能力不应再通过单独一级“法规依据页”承载，而应：

1. 作为知识库中的法规资料被维护。
2. 在对话结果中以 RAG 命中依据卡片返回。
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. 字段抽取任务必须能表达“抽取核心信息并自动填入注册申报表格或对照清单”的输出目标。
6. 任务配置能够驱动会话中的节点式执行和右侧状态卡实时更新。

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

12.1 建议保留

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

12.2 建议替换

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

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

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

1. 为什么虽然以对话为核心，但仍然保留配置化任务模板和节点编排。
2. 为什么用配置驱动的任务入口更适合监管审核场景。
3. 如何在不推翻现有系统结构的情况下，快速从通用 Demo 切换到具体业务题。

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