doc_id: API-202606-004 feature_id: FEAT-202606-006-agent-semantic-interaction type: api title: Agent 语义交互与命令治理接口说明 status: reviewing owner: 医梦研发团队 created_at: 2026-06-29 updated_at: 2026-07-01 reviewers:

后端负责人
终端负责人
FastGPT 联调负责人 related_docs:
PRD-202606-002
ODS-202606-002
DDS-202606-004
ADR-202606-001 related_modules:
emoon-openplatform
emoon-ai-agent
emoon-ai-command tags:
OpenAPI v2
SSE
Interaction
Command ---

Agent 语义交互与命令治理接口说明

契约位置

OpenAPI: docs/api/openapi/医梦AI中台开放平台接口-v2.openapi.yaml
OpenAPI 版本: 2.0.0
基础路径: /api/v2

OpenAPI 是请求、响应和错误 Schema 的权威来源。本文说明联调语义和调用约束。

破坏性变更

v2 替代 v1.2 中的链式卡片语义：

v1.2	v2
`card_created`	信息展示使用 `presentation`；命令确认使用 `command_prepared`
`nextCard`	删除，由 TaskState 和 interaction 推进
`/cards/{id}/actions/{action}`	删除，改为命令确认/拒绝接口
模型返回 `cardKey/cardData`	后端基于 ResultSnapshot 生成 Presentation
卡片点击承载所有动作	选择回到 Agent interaction；副作用进入 Command

本次不提供 v1/v2 双轨兼容。

接口列表

方法	路径	说明	状态
`POST`	`/api/v2/agent/chat/stream`	文本或 interaction 的 SSE 入口	reviewing
`GET`	`/api/v2/conversations/{conversationId}/turns/{turnId}`	断线恢复本轮语义结果	reviewing
`POST`	`/api/v2/commands/{commandId}/confirm`	确认后端已准备的命令	reviewing
`POST`	`/api/v2/commands/{commandId}/reject`	拒绝命令	reviewing
`GET`	`/api/v2/commands/{commandId}`	查询命令状态	reviewing

不存在公开的 POST /commands/prepare。命令只能由后端根据 TaskState 内部创建。

鉴权

沿用平台 Bearer Token 或 HMAC 鉴权。所有接口必须同时验证：

X-Emoon-Project-Id；
X-Emoon-Partner-Id（合作方调用时）；
X-Emoon-Trace-Id；
命令确认/拒绝的 X-Emoon-Idempotency-Key。

终端提交的 conversationId、resultRef 和 commandId 不能作为授权依据。服务端必须检查租户、项目、患者绑定、会话、任务和终端权限。

对话请求

请求必须且只能在 message 与 interaction 中选择一种。

文本示例：

{
  "conversationId": "conv_001",
  "deviceId": "EMOON-KIOSK-001",
  "message": {
    "text": "我想挂明天呼吸科主任医师的号"
  }
}

交互示例：

{
  "conversationId": "conv_001",
  "deviceId": "EMOON-KIOSK-001",
  "interaction": {
    "interactionType": "SELECT_CANDIDATE",
    "resultRef": "result_001",
    "resultVersion": 1,
    "candidateId": "slot_001",
    "clientActionId": "act_client_001"
  }
}

终端不得提交 journeyState、TaskState、风险等级、命令类型或 HIS 参数。

SSE 事件

事件	说明	是否必须
`message_delta`	自然语言增量	有文本时
`semantic_result`	本轮权威语义结果	是
`presentation`	可选无状态展示	否
`task_updated`	服务端 TaskState 摘要变化	有变化时
`command_prepared`	命令已准备，可能等待确认	有命令时
`command_completed`	命令完成或失败	有执行结果时
`error`	本轮错误	失败时
`completed`	本轮流结束	是

示例：

event: message_delta
data: {"turnId":"turn_001","text":"明天呼吸科有 3 位主任医师可预约。"}

event: semantic_result
data: {"turnId":"turn_001","task":{"taskId":"task_001","status":"ACTIVE"},"resultRefs":[{"resultRef":"result_001","version":1,"resultType":"APPOINTMENT_SLOT_CANDIDATES"}]}

event: presentation
data: {"presentationId":"prs_001","viewModelType":"AppointmentSlotCandidates","resultRef":"result_001","resultVersion":1,"payload":{"groups":[]}}

event: completed
data: {"conversationId":"conv_001","turnId":"turn_001"}

presentation 可能晚于 semantic_result，也可能完全不出现。

semantic_result 的最小字段只有 turnId 和 answer。task、resultRefs 和 availableActions 均为可选；风险和确认要求放在具体 Action/Command 中。

Presentation 不由 FastGPT 指定。后端根据 ResultType、终端能力和简单场景策略决定是否生成，并使用代码内版本化的领域 ViewModel。MVP 不接受终端或模型上传模板 Schema。

FastGPT 只读工具目录

FastGPT 使用的工具不是通过本接口由终端传入。后端从 MCP Tool Registry 生成 ToolCatalog，只保留当前 tenant/project/agent/scene 授权的 READ_ONLY 工具。

每个工具定义至少包含：

name / description / inputSchema / timeoutMs / riskLevel / dataClassification

FastGPT Adapter 负责将 ToolCatalog 映射到目标版本支持的 MCP ToolSet、HTTP ToolSet 或 Workflow 工具节点。写工具不会进入 ToolCatalog。

命令确认

请求：

{
  "commandVersion": 1,
  "confirmation": {
    "channel": "CARD",
    "explicit": true
  }
}

要求：

commandId 必须由此前 command_prepared 事件产生；
命令未过期且仍为 AWAITING_CONFIRMATION；
commandVersion 和 taskVersion 必须匹配；
确认主体与患者/医护绑定一致；
相同幂等键重复请求返回首次结果。

终端不能覆盖命令摘要、金额、号源、患者或风险等级。

错误码

错误码	HTTP	含义	处理建议
`INVALID_INTERACTION`	400	interaction 字段不完整	修正请求
`RESULT_EXPIRED`	409	候选结果已过期	重新查询
`RESULT_VERSION_CONFLICT`	409	候选版本不匹配	获取最新结果
`CANDIDATE_NOT_FOUND`	404	候选不存在或不可见	重新查询
`COMMAND_NOT_FOUND`	404	命令不存在或无权访问	不得重试其他 ID
`COMMAND_VERSION_CONFLICT`	409	命令版本冲突	查询命令状态
`COMMAND_EXPIRED`	409	命令过期	回到 Agent 重新准备
`COMMAND_ALREADY_TERMINAL`	409	命令已完成/失败/拒绝	查询最终结果
`COMMAND_STATE_UNKNOWN`	503	下游写状态未知	禁止重复确认，转查询/人工
`TOOL_UNAVAILABLE`	503	MCP/HIS 不可用	查询可有限重试，写操作查状态
`FORBIDDEN_SCOPE`	403	租户/项目/患者/终端越权	重新鉴权，不得降级绕过

幂等与重试

对话 interaction 使用 clientActionId 防止终端重复点击。
命令确认和拒绝必须携带 X-Emoon-Idempotency-Key。
查询失败可有限重试。
写命令超时不得直接重试；先 GET /commands/{commandId}。
UNKNOWN 状态只能由下游幂等状态查询或人工核验收敛。

联调记录

日期	参与方	结论
2026-06-29	产品/架构讨论	形成 v2 reviewing 契约，尚未开始联调

接口说明.md 7.0 KB History Raw