Головна сторінка Огляд Довідка
Увійти
WangKang
/
emoon-backend
1
0
Відгалуження 0
Файли Проблеми 0 Запити на злиття 0 Wiki
Гілка: master
Гілки Теги
emoon-backend
/
docs
/
initiatives
/
FEAT-202606-006-agent-semantic-interaction
/
需求文档.md

需求文档.md 12 KB
Постійне посилання Історія Запис

doc_id: PRD-202606-002 feature_id: FEAT-202606-006-agent-semantic-interaction type: prd title: Agent 语义交互与命令治理需求文档 status: reviewing owner: 医梦研发团队 created_at: 2026-06-29 updated_at: 2026-07-01 reviewers:

  • 产品负责人
  • 业务负责人
  • 架构负责人 related_docs:
  • INT-202606-001
  • PRD-202606-001 related_modules:
  • emoon-openplatform
  • emoon-ai-agent
  • emoon-ai-card
  • emoon-ai-mcp
  • emoon-system tags:
  • Agent First
  • SemanticResponse
  • Command Runtime
  • FastGPT ---

Agent 语义交互与命令治理需求文档

背景

现有挂号演示以“科室卡 → 医生卡 → 时段卡 → 确认卡 → 成功卡”为主线。 它适合验证 Card Runtime、动作幂等和 HIS Mock，但不适合作为真实 Agent 的通用设计方法。

患者自然语言通常已包含多个业务约束。系统应围绕目标、约束、任务状态和工具结果推进， 而不是要求患者重新走一遍卡片页面流程。卡片仍有价值，但其价值应限定为可选展示、 低成本交互和高风险命令确认，而不是业务流程骨架。

目标

  1. 查询、筛选、解释和替代推荐由任务状态与只读 MCP 工具驱动。
  2. 文本/语音为完整表达通道，展示卡片为可选增强且不得阻塞回答。
  3. FastGPT 只负责推理、自然语言生成和只读工具规划。
  4. 业务写操作由医梦后端确定性 Command Runtime 执行。
  5. 所有终端基于统一语义响应适配不同表现形式。
  6. 以挂号 Agent 验证完整链路，并形成可复用的中台协议。

实施优先级

本专题属于平台级协议改造，必须先于批量业务智能体建设完成。原因不是所有智能体在旧中台上都 无法运行，而是旧协议会迫使每个新智能体把 Card Schema 当作模型输出契约和流程骨架，智能体越多， 后续迁移工作流、后端编排、终端适配和测试的成本越高。

本轮实施必须完成中台公共能力和挂号纵向样板，不以继续扩展旧卡片链换取短期业务数量。 挂号样板用于证明新协议能够覆盖完整查询、替代推荐、选择、锁号、确认和挂号，不代表继续采用 固定的“科室卡 → 医生卡 → 时段卡”流程。

非目标

  • 本文档评审阶段不开发代码、SQL、迁移脚本或终端页面；评审通过后按迁移方案进入实施。
  • 首期不支持 Dify、自研引擎和多引擎切换。
  • 不允许 FastGPT 直接调用锁号、挂号、支付、取消等写工具。
  • 不建设万能动态卡片 Schema 或第三方卡片市场。
  • 不支持新旧卡片协议双轨和生产历史数据转换。
  • 不在本专题完整实现缴费、报告解读、舌诊等其他 Agent。

用户和场景

场景一：信息充分的直接查询

患者说“我想挂明天呼吸科主任医师的号”。系统直接提取科室、日期和职称， 调用只读 MCP 查询可用号源，并返回完整文本；终端支持时可追加无状态号源展示。

场景二：无精确结果时的替代推荐

精确条件无结果时，系统按受控策略查询：

相邻日期同科室同职称
→ 同日同科室相邻职称
→ 其他院区

替代方案只能推荐，不能自动改变患者条件或执行交易。

场景三：自然语言或点击选择

“选第二个”和点击候选项进入同一个 interaction 处理链路，均解析为 resultRef + resultVersion + candidateId，不得只依赖展示序号。

场景四：锁号与挂号

患者明确选择号源可授权短期锁号。锁号前必须重新校验实时号源。 最终挂号、支付或取消等 L2 动作必须二次确认。

场景五：展示降级

展示生成或渲染失败时，系统继续返回完整文本或语音。确认界面失败时可改用文本/语音确认， 但不能降低身份、实时校验、幂等和审计要求。

需求范围

FR-01 任务状态

  • TaskStateService 是任务状态唯一事实源。
  • 模型只能提交约束更新建议；服务端验证后写入。
  • 模型不得直接推进“已锁号、已挂号、已支付”等确定性状态。
  • 同一会话只允许一个前台可变更任务；插入问答不改变任务。

FR-02 查询与工具规划

  • 读操作允许 FastGPT 根据任务状态灵活规划。
  • FastGPT 只获得最小化的只读 MCP 工具集合。
  • 查询结果必须形成短期 ResultSnapshot，绑定租户、患者和会话。
  • 替代推荐策略可按医院配置，但不能擅自执行。

FR-03 语义响应

SemanticResponse 只是终端传输 DTO，不是新的流程引擎或持久化领域对象。最小响应只要求：

  • answer；
  • turnId。

task、resultRefs 和 availableActions 按本轮实际结果可选返回。风险和确认要求属于具体 Action/Command，不在响应根节点重复表达。Presentation 使用独立 SSE 事件，不通过 presentationHints 预告。

模型输出采用“自然语言流 + Tool/Function Call”双通道，不要求模型一次性生成完整 JSON。 应用服务只做薄组装，不引入通用规则编排或二次推理。

FR-04 无状态展示

  • PresentationPolicy 根据终端能力、结果数量、数据完整度、动作风险和用户偏好决定展示。
  • 信息展示不创建 CardInstance。
  • 展示使用通用布局原语与领域 ViewModel 的混合模型。
  • 模板不得定义 MCP 工具、命令顺序或任务状态迁移。
  • 挂号样板期 ViewModel Schema 和转换器由代码版本管理，不建设动态模板 DSL 或模板数据库。

FR-05 交互

  • 无状态展示点击作为 interaction 重新提交到 Agent 对话入口。
  • 自然语言选择与点击选择共用解析、版本校验和权限校验。
  • 过期或版本不匹配的候选集必须重新查询。

FR-06 命令治理

  • Command Runtime 负责命令准备、确认、拒绝、执行、幂等、过期和审计。
  • 命令只能由医梦后端创建，终端不能构造命令参数。
  • 终端只允许确认、拒绝和查询命令。
  • 写操作超时必须先查询幂等状态，禁止盲目重试。

FR-07 风险分级

等级 类型 规则 示例
L0 只读查询 不进入 Command Runtime 查科室、医生、号源
L1 可逆临时动作 明确交互即授权 短期锁号
L2 不可逆或收费动作 必须二次确认 挂号、支付、取消
L3 医疗高风险动作 必须人工或医护确认 诊断、处方类动作

风险等级由平台注册配置固定，模型和租户均不能降低。

FR-08 FastGPT 边界

  • 首期只正式支持 FastGPT。
  • 不支持可靠 Tool/Function Call 的引擎不得绑定业务命令。
  • FastGPT 不直接连接 HIS，不直接生成最终 cardData，不决定风险等级或确认要求。
  • Dify、自研 AgentEngine 和多引擎适配列为后续需求。

FR-09 只读工具目录

  • 医梦后端从 MCP Tool Registry 构建 FastGPT 可见的 ToolCatalog。
  • ToolCatalog 必须经过租户、项目、Agent 和场景权限过滤，且只包含 READ_ONLY 工具。
  • 每个工具向 FastGPT 暴露稳定名称、说明、JSON Schema、超时和数据敏感级别。
  • FastGPT 不自行发现或枚举内部写工具；实际接入形态由 FastGPT 能力验证决定。
  • 工具参数先通过后端 Schema 和业务规则校验，再进入 MCP。

FR-10 可观测性

每次处理必须关联：

conversationId / taskId / turnId / traceId
resultRef / resultVersion / commandId / toolCallId / presentationId

系统应能回放用户输入、模型建议、后端采纳、工具结果、展示内容、用户确认和命令结果。

FR-11 后续智能体设计基线

后续智能体统一按以下顺序设计：

  1. 定义业务目标、用户约束、任务状态和完成条件；
  2. 区分只读查询工具与有副作用的业务动作；
  3. 只读查询通过 ToolCatalog 和 MCP 由 Agent 灵活规划；
  4. 有副作用的动作定义为后端 Command，并配置风险、确认、幂等和审计规则；
  5. 先保证文本/语音能够完整表达结果和完成交互；
  6. 最后根据终端能力决定是否增加无状态 Presentation/Card。

Card 允许用于候选对比、快捷选择、命令确认摘要和结果状态展示，但必须遵守：

  • 不作为 Agent 流程节点或 TaskState 事实源；
  • 不使用 nextCard、cardKey 或 Card 类型判断任务完成和状态迁移；
  • 不要求模型生成最终 cardData；
  • 不承载写命令参数、风险等级或命令执行权限；
  • 不得成为查询、选择或确认的唯一通道；
  • 生成、发送或渲染失败时不得阻塞文本/语音和 Command 主链路。

非功能需求

性能

  • 文本流不得等待无状态展示生成。
  • 展示失败或超时不影响 semantic_result 和任务状态。
  • 具体时延阈值在实施前根据现有 FastGPT、MCP 和终端环境建立基线。

安全与隐私

  • ResultSnapshot 最小化存储、短期有效并具备访问审计。
  • FastGPT 上下文不得注入完整患者资料或 HIS 原始响应。
  • 命令必须绑定租户、项目、患者、会话、任务和发起终端。
  • L2/L3 确认必须验证命令版本、有效期、确认主体和幂等键。

稳定性

  • 查询失败允许有限重试和传统入口/人工兜底。
  • 写命令状态未知时冻结重复提交并转人工核验。
  • 暂停任务中的锁号保持原有效期，到期释放，不得自动续锁。

配置

  • 医院可配置替代搜索范围、结果数量、锁号时长和展示偏好。
  • 身份校验、风险等级、幂等和最低确认规则由平台设定下限。

验收标准

  1. 给定完整挂号条件，系统不重复要求选择已知科室或职称。
  2. 精确条件无结果时，系统能返回受控替代方案且不自动改变条件。
  3. 不支持展示的终端仍能通过文本/语音完成查询和确认。
  4. FastGPT 输出格式异常时，文本回答可降级，且不会产生未校验命令。
  5. 无状态展示不创建命令或卡片实例。
  6. “选第二个”和点击第二项解析到同一个稳定 candidateId。
  7. 旧 ResultSnapshot 版本不能用于执行当前选择。
  8. 锁号前重新校验号源；最终挂号必须二次确认。
  9. 重复确认同一 commandId 和幂等键不会产生重复挂号。
  10. 命令超时后先查询状态，状态未知时不重复写 HIS。
  11. 全链路可通过 traceId 回放。
  12. OpenAPI v2 不再包含 nextCard 和通用 card_created 语义。
  13. FastGPT ToolCatalog 不包含任何写工具，且能追溯实际目录版本。
  14. SemanticResponse 最小响应只依赖 turnId + answer，可选展示失败不影响查询。
  15. FastGPT 能力验证未通过时停止后续阶段，旧演示链保持可部署但不与 v2 同时运行。
  16. 关闭全部 Presentation/Card 后，挂号查询、选择、锁号、确认和挂号仍可通过文本/语音完成。
  17. 有效运行代码不再使用 cardKey、cardData、nextCard 或 Card 类型作为任务完成和状态迁移条件。
  18. 后续智能体能够分别声明 TaskState、只读工具、Command 和可选 Presentation，不复制旧卡片链。

风险和依赖

  • FastGPT 不同部署版本的工具调用与流式事件能力需要在实施前验证。
  • HIS 对锁号、取消和幂等的支持差异需要 Adapter 层吸收。
  • 终端需要同时支持文本优先、异步展示和命令确认事件。
  • 模块与表重命名会影响现有演示代码，但当前无生产 Agent 数据，可一次性切换。
  • 开发按“能力验证 → 查询链 → 命令链 → 单次切换”推进；不要求各阶段同时建设全部概念。

变更记录

日期 变更 负责人
2026-06-29 根据卡片定位讨论创建完整需求 医梦研发团队
2026-07-01 明确本专题优先于批量智能体建设，并补充后续智能体与 Card 设计基线 医梦研发团队