emoon-backend/docs/initiatives/FEAT-202606-001-unified-entry-client/对外接口联调基准.md

---

doc_id: API-202606-002 feature_id: FEAT-202606-001-unified-entry-client type: api title: 医梦 AI 中台对外接口设计文档 v1.2 status: approved owner: 医梦研发团队 created_at: 2026-06-03 updated_at: 2026-06-03 reviewers: [] related_docs:

• PRD-202605-001
• ODS-202606-001 related_modules:
• emoon-openplatform
• emoon-ai-agent
• emoon-ai-card
• emoon-ai-mcp
• emoon-ai-device tags:
• 对外接口
• 联调基准
• OpenAPI ---

医梦 AI 中台对外接口设计文档 v1.2｜正式联调基准版

文档定位：厂商对接接口全貌 + MVP 可落地接口契约说明
适用对象：HIS/EMR/LIS/PACS/叫号/支付厂商、机器人厂商、自助机/导诊屏/诊室屏/大屏厂商、四诊仪厂商、迪耐克/鸿蒙病房互通方、医院信息科、医梦内部研发与测试
OpenAPI 文件：docs/api/openapi/医梦AI中台开放平台接口-v1.2.openapi.yaml（文件名沿用 v1.2，info.version 为 1.2.3） 版本：v1.2.3 生成时间：2026-06-03 18:00

---

0. 本版结论

本版不是把接口无限做大，而是把接口分成三层：

优先级	定位	研发策略	是否建议春节前稳定
P0	厂商联调前必须稳定的最小闭环	必须进入 OpenAPI；请求/响应 schema 要相对完整	是
P1	第一轮试点上线增强能力	先进入接口规划和 OpenAPI，占位或局部实现	视项目节奏
P2	生产运营、商业闭环、区域化能力	规划全貌，避免未来重构；不承诺春节前完成	否

本版在 v1.1 基础上采纳本轮审查中合理的问题，形成正式联调基准版：补充文件删除幂等、文件上传幂等语义、clientFileId、sha256、retentionPolicy、住院设备映射边界、工具风险等级、/meter/events 查询范围收敛，并将 FHIR 可选映射从主 OpenAPI YAML 移出，避免厂商误解为当前交付承诺。

2026-05-31 补充统一入口客户端口径：本次不新增 P0 URL，而是收敛终端调用白名单、AgentRouter/TaskState 内部职责和前后端工程边界。OpenAPI YAML 文件名沿用 v1.2，info.version 当时升级为 1.2.1，并将 AgentChatRequest.agentId 改为可选以支持后端路由。

2026-06-03 根据空海医院会议补充“动线 + 感知”口径：本次仍不新增 P0 URL，只在现有场景、设备事件和对话接口中增加可选 perceptionContext、服务端返回 journeyState、perceptionCapabilities、journeyPolicy，用于支撑“同一设备、不同用户、不同动线阶段展示不同智能体服务”。P0 只做扫码/NFC/刷卡/人工确认和服务区域级事件，不承诺全院无感定位、连续轨迹、自动签到、自动缴费。

2026-06-03 交叉 review 后修正：journeyState 只允许服务端返回，客户端请求不得传入；journey_updated 作为 P0 SSE 事件，避免前端从 task_updated/card_created 反推动线阶段。

v1.2 相比 v1.1 的关键修正

修正项	处理方式	影响
文件删除幂等	DELETE /files/{fileId} 增加 X-Emoon-Idempotency-Key，重复删除返回首次结果或已删除状态	防止敏感文件删除操作重试时审计不一致
文件上传幂等	FileUploadRequest 增加 clientFileId、sha256、source、retentionPolicy	支撑舌诊、面诊、报告、音频等文件的安全上传与重复上传识别
住院设备边界	DeviceContext 增加 managementMode、externalSystem、externalDeviceId	区分医梦直管门诊设备与迪耐克/鸿蒙病房映射设备
动线与感知	AgentChatRequest 增加可选 perceptionContext，响应和 SSE 返回 journeyState，DeviceSceneData 增加 perceptionCapabilities/journeyPolicy	支撑服务找人和同设备差异化能力，但不扩大 P0 URL 面
工具风险等级	ToolInvokeRequest / ToolCatalogItem 增加 riskLevel	明确查询、敏感查询、业务写入、财务动作、医疗正式写入的不同控制要求
计量查询收敛	/meter/events P0 只支持 billingEpisodeId / traceId 精确查询	防止普通厂商误以为可查询完整项目账单或全量成本明细
FHIR 降噪	/fhir/{resourceType}/$translate 从主 YAML 移除，仅保留为远期可选规划	避免 HIS 厂商误解医梦当前要提供完整 FHIR 网关

关键取舍：

1. 不直接暴露 Dify Key：所有 AI 调用统一走 OpenPlatform。
2. 普通设备厂商不得直接调用 /tools/{toolName}/invoke：设备只能走设备接口、智能体接口、卡片动作接口。
3. 写操作必须幂等：挂号、签到、缴费、卡片动作、HIS 写接口必须带 X-Emoon-Idempotency-Key。
4. 文件先上传后引用：舌诊、面诊、报告解读等多模态场景先调用 /files/upload 获得 fileId，再传入 /agent/chat。
5. 设备上下文进入每次关键调用：deviceContext 进入 chat、card action、device event、meter event。
6. P0 能真实联调，P1/P2 先给全貌：防止接口规划缺口导致未来返工。

0.1 v1.2.3 统一入口客户端补充口径

主题	接口口径	原因
终端调用白名单	机器人、自助机、导诊屏、诊室屏等统一入口客户端只允许调用 Device、/agent/chat/stream、Conversation、File、Card、Device Event、Device Command 相关接口	保持终端轻量，避免终端绕过中台审计和计量
/agent/chat	保留为同步对话、服务端联调和不支持 SSE 的受控调用；统一入口客户端默认使用 /agent/chat/stream	医院终端需要流式反馈和卡片事件，SSE 更适合 P0 体验
TaskStateService	不新增公共 /tasks P0 接口；taskId、taskType、taskStatus 通过 SSE 事件、会话查询和卡片实例返回	减少接口面，避免第一期多维护一组状态查询 API
AgentRouter	作为 emoon-ai-agent 内部能力，不对外暴露路由接口	外部厂商只关心结果，不应依赖医梦内部路由规则
舌诊底层接口	终端只能走 /files/upload + /agent/chat/stream + /cards/{id}/actions/{name}，不得直连舌诊 SDK/API	舌象图片属于敏感医疗数据，必须统一文件审计和工具审计
HIS Mock/Real Adapter	Mock 阶段和真实阶段对终端接口不变，差异只在后端 HospitalAdapter 配置	便于 MVP 先联调，后续替换真实 HIS 不改终端
前后端工程边界	后端能力仍在 AI 中台统一工程；前端/移动端另起 emoon-terminal-client	符合团队资源现状，避免一个仓库混合终端构建、后端模块和 Demo 服务
动线/感知字段	perceptionContext 是终端上报的最近一次感知事实，journeyState 只由后端结合 HIS/叫号/任务状态推导后返回	前端不得传入或自行判断已签到、可缴费、可挂号成功
设备能力差异	/devices/{deviceId}/scene 返回 allowedAgents/allowedCards/perceptionCapabilities/journeyPolicy	同一设备面向患者、医护、访客和不同动线阶段时能力不同

0.2 本接口边界的行业依据

依据	对接口设计的约束
东软 5G 智慧医院公开方案强调统一信息平台集成各子系统	医梦接口只做 AI 入口、设备场景和受控工具，不把自己设计成完整 HIS/EMR 替代品
华为智慧病房/医疗物联网公开方案强调物联网平台和多协议设备接入	住院 IoMT、床头屏、护理白板优先通过外部病房/物联平台事件接入，不让医梦接口承担原始设备接入责任
科大讯飞智慧医疗公开资料强调 AI 嵌入医生现有流程和辅助决策	高风险医疗动作必须通过 Card Action 和人工确认，不开放“自动诊断/自动处方”接口
Dify 官方已有 Workflow 版本控制能力	接口层不暴露 Dify 内部发布 API，医梦只维护 Agent 配置、版本映射和输出归一
《个人信息保护法》对医疗健康、行踪轨迹等敏感个人信息有严格要求	文件、位置、设备事件和服务找人接口必须最小化采集、可审计、可降级

---

1. 接口设计边界

1.1 医梦中台对外开放的不是“数据库接口”

对外接口只开放业务能力和设备能力，不开放内部表结构。厂商不应关心医梦内部使用 Dify、MCP、Card Runtime、Metering 还是其他实现。

外部厂商 -> OpenPlatform API -> 鉴权/限流/幂等/审计 -> Agent/Card/Device/Tool -> 医院系统或设备

1.2 三类厂商的接入边界

厂商类型	推荐接入方式	禁止事项
机器人/自助机/屏幕厂商	Device API + Agent API + Card Action API	不直接调用 HIS Tool，不直接持有 Dify Key
HIS/EMR/LIS/PACS/叫号/支付厂商	Tool API + Webhook/Event API	不直接参与 AI 会话编排，不绕过医梦审计链路
四诊仪/专用设备厂商	Device API + File API + Agent/Card API	不把原始敏感图像暴露给非授权系统

---

2. 全量接口规划：按优先级分类

P0 接口清单

模块	主要厂商/对象	方法	路径	接口	说明
通用平台	全部厂商	POST	/auth/token	获取短期访问 Token	厂商使用 client_credentials 获取 accessToken；也可用于服务端系统对接。
通用平台	全部厂商	GET	/health	平台健康检查	用于联调前探活，不返回敏感配置。
通用平台	全部厂商	GET	/capabilities	查询项目已开通能力	让厂商知道当前项目可调用哪些 Agent、工具、设备能力和计费策略。
智能体与会话	受控服务端/不支持 SSE 的终端	POST	/agent/chat	智能体同步对话	首轮 conversationId 可为空，平台自动创建会话并返回；统一入口客户端默认不使用该接口。
智能体与会话	机器人/自助机/导诊屏/诊室屏	POST	/agent/chat/stream	智能体流式对话 SSE	POST + SSE；必须支持断线后按 conversationId 查询最终消息、任务状态和卡片。
智能体与会话	终端厂商/患者端/医生端	POST	/conversations	创建会话	可选预创建；chat 不传 conversationId 时自动创建。
智能体与会话	终端厂商/患者端/医生端	GET	/conversations/{conversationId}	查询会话详情	用于断线恢复、历史状态恢复。
智能体与会话	终端厂商/患者端/医生端	GET	/conversations/{conversationId}/messages	查询会话消息	用于 SSE 断线后的最终文本和卡片恢复。
文件与多模态	四诊仪/自助机/患者端/医生端	POST	/files/upload	上传图片/音频/文档	舌诊、面诊、报告解读等场景先上传文件，chat 只传 fileId。
文件与多模态	四诊仪/自助机/患者端/医生端	GET	/files/{fileId}	查询文件元数据	只返回元数据和受控访问状态，不默认返回公开 URL。
设备接入	机器人/自助机/大屏/诊室屏	POST	/devices/register	设备注册或激活	设备拿到 deviceId、deviceSecret、准入等级、默认场景。
设备接入	机器人/自助机/大屏/诊室屏	POST	/devices/{deviceId}/heartbeat	设备心跳	上报在线状态、版本、当前场景、错误摘要。
设备接入	机器人/自助机/大屏/诊室屏	GET	/devices/{deviceId}/scene	获取设备场景配置	返回 UI 模板、Agent 绑定、工具权限、设备能力开关。
设备接入	机器人/自助机/大屏/诊室屏	POST	/devices/{deviceId}/events	上报设备事件	扫码、打印、读卡、靠近、导航完成、异常等事件。
设备接入	机器人/自助机/大屏/诊室屏	GET	/devices/{deviceId}/commands/poll	轮询待执行命令	MVP 采用轮询，避免设备厂商必须开放公网回调。
设备接入	机器人/自助机/大屏/诊室屏	POST	/devices/{deviceId}/commands/{commandId}/ack	设备命令回执	设备执行命令后回报 success/failed。
卡片动作	终端厂商/HIS适配方	GET	/cards/{cardInstanceId}	查询卡片实例	用于卡片恢复、状态查询、历史审计。
卡片动作	终端厂商/HIS适配方	POST	/cards/{cardInstanceId}/actions/{actionName}	执行卡片动作	挂号、签到、建档、确认病历等确定性动作统一走卡片动作。
受控工具	HIS/EMR/LIS/PACS/叫号/支付适配方	POST	/tools/{toolName}/invoke	调用院内系统工具	仅开放给受控系统适配方；普通设备厂商不得直接调用。
计量与运营	医院信息科/医梦运营	GET	/usage/summary	查询基础用量汇总	春节前先做项目/设备/智能体/场景维度基础统计。
计量与运营	医院信息科/医梦运营	GET	/meter/events	查询计量事件	用于排障、能力值流水追踪，P0 只读。

P1 接口清单

模块	主要厂商/对象	方法	路径	接口	说明
智能体与会话	终端厂商/患者端/医生端	GET	/conversations	查询会话列表	患者端历史咨询、医生端历史 AI 交互。
智能体目录	终端厂商/运营后台	GET	/agents	查询可用智能体列表	让终端动态展示可用能力。
智能体目录	终端厂商/运营后台	GET	/agents/{agentId}	查询智能体详情	返回 Agent 名称、场景、输入能力、输出卡片类型。
设备治理	设备厂商/医梦运营	GET	/devices	查询设备列表	设备运维、授权、在线率统计。
设备治理	设备厂商/医梦运营	GET	/devices/{deviceId}	查询设备详情	设备能力、版本、位置、场景绑定。
设备治理	医梦运营/设备厂商	PATCH	/devices/{deviceId}/scene	更新设备场景绑定	灰度切换 UI 模板和 Agent 绑定。
设备治理	医梦运营/设备厂商	GET	/devices/{deviceId}/events	查询设备事件	定位设备问题和事件回放。
Webhook	HIS/叫号/机器人/设备厂商	POST	/webhooks	注册 Webhook	第三方系统回调事件订阅。
Webhook	HIS/叫号/机器人/设备厂商	GET	/webhooks	查询 Webhook 列表	运营和联调管理。
Webhook	HIS/叫号/机器人/设备厂商	DELETE	/webhooks/{webhookId}	删除 Webhook	关闭事件订阅。
事件接入	HIS/叫号/迪耐克/病房系统	POST	/events/ingest	接收外部系统业务事件	挂号成功、叫号变更、护理预警等外部事件接入。
受控工具	HIS/EMR/LIS/PACS/叫号/支付适配方	GET	/tools/catalog	查询授权工具目录	让受控适配方知道当前项目可调用工具和 schema。
设备授权	医院信息科/医梦运营	GET	/licenses/devices	查询设备授权状态	设备授权、入口客户端授权和运维服务统计。

P2 接口清单

P2 是远期规划能力，不进入春节前门诊主交付。FHIR 可选映射已从主 OpenAPI YAML 移除，仅在医院已有 FHIR 网关且项目合同明确要求时，另行提供独立 emoon-ai-fhir-future.openapi.yaml。

模块	主要厂商/对象	方法	路径	接口	说明
伙伴与准入	医梦运营/合作厂商	POST	/partners	创建合作方接入档案	正式厂商准入、scope、密钥、设备类型绑定。
伙伴与准入	医梦运营/合作厂商	GET	/partners/{partnerId}	查询合作方档案	合规、联调、授权审计。
合同与套餐	医院/医梦商务运营	GET	/contracts	查询合同与套餐	对接合同、套餐、能力值包。
账户与额度	医院/医梦商务运营	GET	/credit/accounts	查询能力值账户	主账户、科室账户、区域账户。
账户与额度	医梦内部系统	POST	/credit/accounts/{accountId}/freeze	冻结能力值	高成本任务预冻结，通常不对外开放。
账户与额度	医梦内部系统	POST	/credit/accounts/{accountId}/settle	结算能力值	由计量账本驱动，通常不对外开放。
账单结算	医院/医梦商务运营	GET	/billing/invoices	查询账单	月账单、超量账单、科室分摊。
运营报表	医院/医梦运营	GET	/operation/reports	查询运营报告	用量、设备、智能体、科室、成本和质量指标。
审计合规	信息科/医梦运维	GET	/audit/logs	查询审计日志	敏感操作、工具调用、卡片动作、设备事件。

---

3. 全量接口规划：按厂商分类

全部厂商

建议接入接口
POST /auth/token
GET /health
GET /capabilities

机器人厂商

建议接入接口
POST /devices/register
POST /devices/{deviceId}/heartbeat
GET /devices/{deviceId}/scene
POST /devices/{deviceId}/events
GET /devices/{deviceId}/commands/poll
POST /devices/{deviceId}/commands/{commandId}/ack
POST /agent/chat/stream

自助机/导诊屏/大屏/诊室屏厂商

建议接入接口
POST /devices/register
POST /devices/{deviceId}/heartbeat
GET /devices/{deviceId}/scene
POST /devices/{deviceId}/events
GET /cards/{cardInstanceId}
POST /cards/{cardInstanceId}/actions/{actionName}
POST /agent/chat/stream

HIS/EMR/LIS/PACS/叫号/支付厂商

建议接入接口
POST /tools/{toolName}/invoke
GET /tools/catalog
POST /webhooks
POST /events/ingest
GET /meter/events

四诊仪厂商

建议接入接口
POST /devices/register
POST /devices/{deviceId}/heartbeat
POST /files/upload
POST /agent/chat/stream
GET /cards/{cardInstanceId}
POST /cards/{cardInstanceId}/actions/{actionName}

迪耐克/鸿蒙病房/住院互通方

建议接入接口
POST /events/ingest
POST /devices/register（仅映射终端）
POST /devices/{deviceId}/events（仅标准业务事件，不做硬件心跳主责）
POST /agent/chat/stream（仅明确需要 AI 嵌入时使用）
GET /tools/catalog

医院信息科/运营方

建议接入接口
GET /usage/summary
GET /meter/events
GET /licenses/devices
GET /operation/reports
GET /audit/logs

---

4. 通用规范

4.1 Base URL 与版本

环境	Base URL
沙箱	https://sandbox-api.emoon-ai.com/api/v1
医院私有化	https://api.{hospital}.emoon.local/api/v1

版本策略：

规则	说明
URL 版本	破坏性变更升级 /api/v2
非破坏性变更	新增可选字段、返回新增字段，不升级 URL
枚举扩展	厂商必须能忽略未知枚举或降级处理
废弃策略	生产接口废弃前至少提前通知，具体周期写入合同或联调协议

4.2 鉴权方式

本版保留两种鉴权。MVP 阶段可以先稳定 Bearer Token，P0 高风险写操作逐步增加 HMAC。

鉴权	适用对象	Header
Bearer Token	HIS 厂商、后台系统、受控服务器端	Authorization: Bearer <access_token>
HMAC 签名	自助机、机器人、设备侧高风险调用	Authorization: EMOON-HMAC <access_key> + 签名头

HMAC 必要请求头：

Header	必填	说明
X-Emoon-Project-Id	是	项目/医院标识
X-Emoon-Partner-Id	是	合作方标识
X-Emoon-Timestamp	是	Unix 毫秒时间戳，默认允许 ±300 秒
X-Emoon-Nonce	是	随机串，防重放
X-Emoon-Signature	HMAC 模式必填	HMAC-SHA256 签名
X-Emoon-Trace-Id	建议	链路排障 ID
X-Emoon-Idempotency-Key	写接口必填	幂等键
X-Emoon-Device-Id	设备调用建议	设备上下文兜底

推荐签名串：

HTTP_METHOD + "
" +
PATH_WITH_QUERY + "
" +
X-Emoon-Timestamp + "
" +
X-Emoon-Nonce + "
" +
SHA256_HEX(request_body)

4.3 Scope 与高风险接口

Scope	能力
agent:invoke	调用智能体
device:write	设备注册、心跳、事件上报
card:action	执行卡片动作
file:write	文件上传
tool:read	调用查询类院内工具
tool:write	调用写类院内工具，高风险，仅受控适配方
usage:read	查询用量和计量事件
webhook:manage	管理 Webhook

/tools/{toolName}/invoke 必须有 tool:read 或 tool:write，并且只允许受控系统适配方调用。普通设备厂商不得直接调用。

4.4 幂等

所有产生业务事实的接口必须支持 X-Emoon-Idempotency-Key。

接口类型	幂等键建议
对话请求	projectId + resolvedAgentId/routeKey + clientMessageId；统一入口客户端未传 agentId 时由后端路由结果补齐
设备事件	projectId + deviceId + eventType + eventId
卡片动作	projectId + cardInstanceId + actionName + clientActionId
Tool 写操作	projectId + toolName + businessKey
文件上传	projectId + sha256 + clientFileId

重复请求规则：

1. 同幂等键、同请求摘要、首次成功：返回第一次结果。
2. 同幂等键、不同请求摘要：返回 IDEMPOTENCY_CONFLICT。
3. 首次处理中：返回处理中状态或让客户端稍后查询。
4. HIS 写操作状态不明：先查询最终状态，禁止直接重复写。

4.5 统一响应

成功响应：

{
  "code": "OK",
  "message": "success",
  "traceId": "trace_001",
  "requestId": "req_001",
  "data": {}
}

错误响应：

{
  "code": "INVALID_PARAM",
  "message": "参数错误",
  "details": {
    "field": "deviceContext.deviceId",
    "reason": "deviceId is required"
  },
  "traceId": "trace_001",
  "requestId": "req_001"
}

常见错误码：

错误码	含义
AUTH_INVALID_TOKEN	Token 无效或过期
AUTH_SIGNATURE_INVALID	HMAC 签名错误
AUTH_TIMESTAMP_EXPIRED	时间戳过期
PERMISSION_DENIED	Scope 或项目授权不足
RATE_LIMIT_EXCEEDED	触发限流
IDEMPOTENCY_CONFLICT	同一幂等键请求内容不一致
DEVICE_NOT_REGISTERED	设备未注册或未激活
CARD_EXPIRED	卡片已过期
TOOL_FORBIDDEN	工具未授权或调用方无权限
HIS_TIMEOUT	院内系统超时
BILLING_QUOTA_EXCEEDED	额度不足或超限

---

5. P0 接口详细设计

5.1 智能体对话接口

POST /agent/chat

请求要点：

字段	说明
agentId	对外智能体 ID；统一入口客户端可为空，由后端 AgentRouter 根据设备、场景、任务状态和输入内容决定
conversationId	可为空；为空时平台自动创建并返回
user	用户上下文，预留 patientId/visitId/encounterId/authorizationId
deviceContext	设备上下文，设备调用必须传
perceptionContext	可选。终端最近一次感知事实，如扫码、NFC、刷卡、服务区域事件；服务端仍以授权和院内系统状态为准
message	文本、图片、音频、文件引用；多模态内容使用 fileId
billingContext	场景和计量上下文

journeyState 只存在于响应、SSE 和查询结果中。客户端请求不得传入该对象；即使通过 inputs 扩展字段伪造，P0 服务端也必须完全忽略，并以服务端事实重新推导。

5.2 文件上传接口

POST /files/upload

MVP 只处理：

• 舌象/面象图片；
• 报告图片或 PDF；
• 诊间音频片段可后置。

要求：

1. 文件必须鉴权上传。
2. 平台返回 fileId，后续 Agent 调用只传 fileId。
3. 不默认返回可公开访问 URL。
4. 原图、报告、面部图片按敏感数据处理。

文件上传幂等规则：

字段 / Header	说明
X-Emoon-Idempotency-Key	正式联调建议必传。推荐值：projectId + partnerId + clientFileId。
clientFileId	厂商侧文件唯一 ID；同一文件重试上传时保持不变。
sha256	文件摘要，用于完整性校验和重复文件识别。
source	文件来源：患者端、自助机、机器人、四诊仪、医生站、病区终端、第三方系统等。
retentionPolicy	文件保存策略：transient、episode、medical_record、audit_only。

文件上传降级幂等规则：如果 clientFileId 缺失，平台可降级使用 projectId + partnerId + sha256 + purpose + user.visitId 识别重复上传；但正式厂商接入仍应提供 clientFileId。

DELETE /files/{fileId} 删除或作废文件时也应传 X-Emoon-Idempotency-Key。同一文件重复删除返回首次删除结果或当前已删除状态，不重复产生业务副作用。

5.3 设备接入三步握手

设备启动 -> /devices/register -> /devices/{deviceId}/scene -> /agent/chat/stream 或 /cards/actions
                    -> 定时 /devices/{deviceId}/heartbeat
                    -> 有事件时 /devices/{deviceId}/events

设备管理边界：

管理模式	说明	典型设备
emoon_managed	由医梦统一入口客户端和 Device Registry 管理，包含注册、心跳、场景、事件、版本和基础状态。	导诊屏、自助机、门诊机器人、诊室屏、叫号/候诊屏
partner_managed	由合作设备厂商管理硬件与驱动，医梦通过标准 API/SDK 接入能力。	第三方机器人、四诊仪、专用采集设备
mapped_external	由外部体系管理，医梦仅记录映射关系和 AI 事件互通。	迪耐克/鸿蒙病房床头屏、护理白板、护士 PDA、病区机器人

门诊设备原则上进入医梦 Device Registry；住院侧设备类型仅表示 AI 能力映射对象，不代表医梦承担住院硬件注册、心跳、升级和故障主责。

设备事件 MVP 类型：

eventType	说明
QR_SCANNED	扫码完成
CARD_READ	身份证/医保卡读取
PRINT_COMPLETED	打印成功
PRINT_FAILED	打印失败
NEARBY_DETECTED	近场检测到患者或临时授权令牌
NAVIGATION_STARTED	机器人开始导航
NAVIGATION_COMPLETED	机器人导航完成
DEVICE_ERROR	设备异常
TOUCH_INTERACTION	触控、点击、语音交互摘要
CUSTOM	厂商扩展事件，P0 只能承载联调所需的非敏感摘要

eventPayload 按 eventType 校验必要字段，不强制所有事件使用同一个扁平结构：

eventType	必要 eventPayload	说明
QR_SCANNED	qrType、visitId 或临时授权 token	身份/就诊绑定
CARD_READ	cardType	不允许上传完整身份证号、医保卡号
NEARBY_DETECTED	zoneCode、level	只表示进入服务区域，不表示已签到
TOUCH_INTERACTION	screen、action	用户主动触发摘要
CUSTOM	项目约定字段	仅用于联调扩展，正式上线前需进入白名单

NEARBY_DETECTED 推荐 eventPayload：

{
  "eventType": "NEARBY_DETECTED",
  "eventId": "evt_001",
  "occurredAt": "2026-05-29T10:00:00+08:00",
  "eventPayload": {
    "subject": {
      "type": "temporary_token",
      "value": "tmp_nearby_token_xxx"
    },
    "signal": {
      "type": "ble",
      "rssi": -65,
      "confidence": 0.82
    },
    "areaCode": "OPD_2F_ROOM_201_DOOR"
  }
}

注意：不要让设备直接上报身份证号、手机号等敏感信息。服务找人只保存“到达诊室门口服务区域”的必要事件，不保存连续轨迹。设备事件只形成感知事实，不能自动触发签到、缴费、挂号等高风险业务动作，必须由后端结合身份授权、HIS/叫号状态和患者确认后生成卡片。

5.4 卡片动作接口

POST /cards/{'{cardInstanceId}'}/actions/{'{actionName}'}

卡片动作必须传：

字段	说明
clientActionId	客户端动作 ID，参与幂等
operator	操作者，患者/医生/护士/系统
deviceContext	动作发生在哪个设备、什么位置
payload	动作业务参数
confirm	是否已由用户或医护确认

卡片动作原则：

1. 前端不直接调用 HIS。
2. 卡片动作先校验卡片状态、权限、幂等和有效期。
3. 需要写 HIS 时由 AgentActionOrchestrator 承接业务编排，CardActionService 做状态校验和快照，再进入 MCP Tool Server。
4. 医疗高风险动作必须人工确认。

5.5 受控工具接口

POST /tools/{'{toolName}'}/invoke

工具接口只对以下对象开放：

• 医梦 MCP Tool Server；
• HIS/EMR/LIS/PACS/叫号/支付等系统适配方；
• 医梦内部可信服务。

普通设备厂商、机器人厂商、自助机厂商默认不开放。

工具命名建议：

工具域	示例
HIS 基础	his.queryDepartments、his.queryDoctors
排班号源	his.querySchedules、his.lockSchedule、his.releaseSchedule
挂号	his.createRegistration、his.cancelRegistration
叫号签到	queue.checkIn、queue.queryStatus
EMR	emr.createDraft、emr.queryRecord
LIS/PACS	lis.queryReports、pacs.queryImages
支付	payment.createOrder、payment.queryStatus

工具风险等级：

风险等级	工具类型	控制要求
L1_QUERY	查询科室、医生、院区、FAQ	可自动调用，记录审计。
L2_SENSITIVE_READ	查询患者、报告、费用、处方摘要	需要患者授权、医护身份或项目授权。
L3_BUSINESS_WRITE	锁号、签到、建档、挂号	必须幂等、用户确认、卡片动作审计。
L4_FINANCIAL_ACTION	支付、退费、补缴	强确认、支付系统回调、财务审计。
L5_MEDICAL_WRITE	EMR 正式写回、医嘱、处方	医生确认、医院系统签名、全链路审计。

MVP 阶段建议优先开放 L1_QUERY 和少量 L3_BUSINESS_WRITE。L4_FINANCIAL_ACTION 与 L5_MEDICAL_WRITE 不建议春节前作为通用厂商接口开放。

---

6. SSE 流式接口

POST /agent/chat/stream

Header：

Accept: text/event-stream
Content-Type: application/json

事件类型：

事件	优先级	说明
message_delta	P0	文本增量
message_completed	P0	文本完成，返回 messageId/conversationId
card_created	P0	平台已创建卡片实例，前端可渲染
task_updated	P0	任务状态变更，返回 taskId/taskType/currentStep/status
journey_updated	P0	动线阶段变更，返回 stageCode/nextAction/source；前端动线区必须以该事件或响应中的 journeyState 为准
error	P0	流式错误
usage_reported	P1	本次调用用量或能力值事件，仅展示用途，不作为账本唯一来源

断线恢复：

1. 客户端记录 conversationId 和最后收到的 eventId。
2. 断线后调用 GET /conversations/{'{conversationId}'}/messages 查询最终消息、任务状态、动线状态和卡片。
3. 卡片实例以 GET /cards/{'{cardInstanceId}'} 为准。

---

7. Webhook 与外部事件

7.1 Webhook 签名

第三方回调医梦或医梦回调第三方，都应使用签名头：

Header	说明
X-Emoon-Webhook-Event-Id	事件唯一 ID
X-Emoon-Webhook-Timestamp	Unix 毫秒时间戳
X-Emoon-Webhook-Nonce	随机串
X-Emoon-Webhook-Signature	HMAC-SHA256 签名

重试策略建议：

项	建议
单次超时	5 秒
重试间隔	1min / 5min / 30min / 2h
最大重试	5 次
成功条件	HTTP 2xx
幂等键	eventId

7.2 外部事件接入

POST /events/ingest 用于 HIS、叫号、迪耐克/病房系统等向医梦上报业务事件，例如：

eventType	来源
registration_created	HIS
registration_cancelled	HIS
queue_status_changed	叫号系统
checkin_completed	签到系统
report_available	LIS/PACS
ward_alert_created	迪耐克/病房系统
nursing_task_closed	护理系统

---

8. 限流、计量和计费

8.1 限流不是计费

限流用于保护系统，计费用于商业结算。限流命中不代表扣费，调用成功也不一定直接扣费，必须根据 chargePolicy 和计量账本判断。

限流响应头建议：

Header	说明
X-RateLimit-Limit	当前窗口额度
X-RateLimit-Remaining	剩余额度
X-RateLimit-Reset	重置时间
Retry-After	建议重试秒数

8.2 计量事件

标准计量事件包含：

• projectId
• partnerId
• agentId，Router 决定场景时由后端补齐最终命中的 Agent ID
• deviceId
• scenarioCode
• billingEpisodeId
• sourceType
• sourceId
• meterItem
• rawQuantity
• credits
• chargePolicy

chargePolicy 枚举：

值	说明
customer_charge	客户能力值扣费
license_covered	设备授权覆盖
bundle_included	服务包包含
internal_cost	只记内部成本
no_charge	不计费，仅审计

/meter/events 查询范围：

阶段	支持范围	不支持范围
P0	按 billingEpisodeId 或 traceId 做精确查询，用于联调排障和计量核验	不开放项目级、设备级、时间范围、成本明细和完整账单查询给普通厂商
P1	医院信息科和医梦运营可按项目、智能体、设备做基础汇总	不直接替代正式月账单
P2	进入账单、分摊、运营报告和区域能力池	需合同、权限、审计体系同步成熟

正式账单查询不使用 /meter/events，后续由 /billing/invoices 或账单中心接口承接。

---

9. MVP 实施建议

9.1 P0 开发顺序

1. 通用鉴权、HMAC Header、错误响应、幂等键。
2. /devices/register + /heartbeat + /scene，让统一入口客户端能先启动和拿到场景。
3. /agent/chat/stream + /conversations/{'{id}'} + /conversations/{'{id}'}/messages，统一入口客户端默认走 SSE。
4. AgentRouter 和 TaskStateService 先作为 emoon-ai-agent 内部能力实现，不新增公共 /tasks P0 API。
5. /files/upload + /files/{'{fileId}'} + DELETE /files/{'{fileId}'} 幂等删除。
6. /cards/{'{id}'} + /cards/{'{id}'}/actions/{'{actionName}'}，卡片动作由 Agent 编排链路推进状态和工具调用。
7. /tools/{'{toolName}'}/invoke 只接查询类 HIS 工具和显式 Mock 写工具，普通终端不可直接调用。
8. /devices/{'{deviceId}'}/events + /commands/poll + /commands/{'{commandId}'}/ack，先支撑机器人导航、扫码、打印、异常事件。
9. /meter/events 只按 billingEpisodeId / traceId 精确查询 + 计量事件落库。

/agent/chat 保留为同步接口和服务端联调工具，不作为统一入口客户端 P0 主链路。

9.2 不建议第一期实现的内容

• 完整 OAuth2/IAM；
• mTLS；
• 完整账单中心；
• 区域多院能力池；
• FHIR 网关 / FHIR Translate 主接口；
• 第三方卡片插件市场；
• 全院鸿蒙无感定位；
• 所有设备深度控制命令；
• 公共 /tasks 查询与任务编排 API；
• 终端直连 Dify、HIS Tool、舌诊底层接口或计量写接口。

9.3 统一入口客户端 P0 接口白名单

终端类型	默认允许接口	第一阶段不允许
机器人	Device 注册/心跳/场景/事件/命令轮询、/agent/chat/stream、Conversation、Card	直连 HIS Tool、直连 Dify、真实缴费、医保、退费
自助机	Device、/agent/chat/stream、Conversation、File、Card	前端写死号源、前端直接调用舌诊接口、自动完成高风险动作
导诊屏/大屏	Device、/agent/chat/stream、Conversation、Card、轻量事件	舌象采集、实名挂号、支付、医保
诊室屏/医生站插件	Device、/agent/chat/stream、Conversation、File、Card	自动诊断、自动处方、绕过医生确认

---

10. v1.1 相比 v1.0 的变更

变更	说明
新增会话接口	/conversations、/conversations/{'{id}'}、/messages
新增文件接口	/files/upload、/files/{'{fileId}'}
卡片动作增加 deviceContext	解决设备审计和设备计量归因
补 HMAC Headers	Timestamp、Nonce、Signature
补核心上下文 schema	UserContext、DeviceContext、BillingContext
补错误 details	方便厂商联调排障
补设备事件和命令 schema	支撑机器人、自助机、服务找人
补 Tool scope 说明	避免普通设备厂商误调 HIS 工具
补 Webhook 签名和重试	支撑外部事件接入
补 P0/P1/P2 全量接口目录	兼顾接口全貌和 MVP 落地

---

11. 对外发送建议

正式发给厂商时建议提供一个资料包：

医梦AI中台厂商对接资料包/
├── 对外接口联调基准.md
├── 医梦AI中台开放平台接口-v1.2.openapi.yaml
├── Postman Collection
├── HMAC签名示例-Java
├── HMAC签名示例-TypeScript
├── HIS工具接口Mock说明
├── 机器人设备接入示例
└── 设备事件与命令测试用例

当前这版已经可以作为内部评审和厂商预沟通底稿。若要发正式联调版，应再补 Postman Collection、HMAC 示例和 HIS Mock Server。

12. v1.2.3 正式联调基准结论

v1.2.3 可以作为厂商正式联调基准。它不扩大主 OpenAPI YAML 的 P0 接口面，只补充统一入口客户端的调用边界、工程归属、动线阶段和感知上下文。仍需坚持以下边界：

1. 主 YAML 只代表当前联调基准：P0/P1 是主要联调范围；P2 只做规划说明，不代表春节前承诺。
2. FHIR 不在主基线内：如医院已有 FHIR 网关，需要单独评估后另出 FHIR 映射文件。
3. 住院设备不按门诊总包处理：护理白板、床头屏、护士 PDA 等住院终端默认通过迪耐克/鸿蒙病房体系映射接入。
4. 文件和工具接口是高风险区域：文件必须有用途、来源、保存策略和幂等；工具必须有 riskLevel、scope、幂等和审计。
5. 计量查询不是账单接口：/meter/events 只用于联调排障和计量核验，正式对账以后续账单中心为准。
6. 统一入口客户端不直连底层能力：终端前端不得持有 Dify Key，不得调用 HIS Tool，不得直连舌诊底层接口，不得写计量账本。
7. 动线和感知不等于自动业务动作：终端只能上报感知事实和展示后端返回的 journeyState，签到、缴费、挂号、报告解读等动作仍必须走卡片确认、审计和幂等链路。

对外发送建议：

对象	发送内容	备注
HIS / EMR / LIS / PACS / 叫号 / 支付厂商	Markdown + v1.2 YAML + Tool 接口章节	强调 tools 受控开放和风险等级
机器人 / 自助机 / 大屏 / 诊室屏厂商	Markdown + v1.2 YAML + Device / Agent / Card 章节	强调不得直接调用 Tool
四诊仪厂商	Markdown + v1.2 YAML + File / Device / Agent 章节	强调文件上传幂等和敏感数据策略
迪耐克 / 鸿蒙病房互通方	Markdown + v1.2 YAML + Device 管理边界 / Event 章节	强调 mapped_external，不承担住院硬件主责
医院信息科	Markdown + v1.2 YAML + 鉴权 / 审计 / 计量章节	强调权限隔离、日志、计量不是账单