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 网关

关键取舍：

不直接暴露 Dify Key：所有 AI 调用统一走 OpenPlatform。
普通设备厂商不得直接调用 /tools/{toolName}/invoke：设备只能走设备接口、智能体接口、卡片动作接口。
写操作必须幂等：挂号、签到、缴费、卡片动作、HIS 写接口必须带 X-Emoon-Idempotency-Key。
文件先上传后引用：舌诊、面诊、报告解读等多模态场景先调用 /files/upload 获得 fileId，再传入 /agent/chat。
设备上下文进入每次关键调用：deviceContext 进入 chat、card action、device event、meter event。
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`

重复请求规则：

同幂等键、同请求摘要、首次成功：返回第一次结果。
同幂等键、不同请求摘要：返回 IDEMPOTENCY_CONFLICT。
首次处理中：返回处理中状态或让客户端稍后查询。
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；
诊间音频片段可后置。

要求：

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

文件上传幂等规则：

字段 / 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`	是否已由用户或医护确认

卡片动作原则：

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

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	本次调用用量或能力值事件，仅展示用途，不作为账本唯一来源

断线恢复：

客户端记录 conversationId 和最后收到的 eventId。
断线后调用 GET /conversations/{'{conversationId}'}/messages 查询最终消息、任务状态、动线状态和卡片。
卡片实例以 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 开发顺序

通用鉴权、HMAC Header、错误响应、幂等键。
/devices/register + /heartbeat + /scene，让统一入口客户端能先启动和拿到场景。
/agent/chat/stream + /conversations/{'{id}'} + /conversations/{'{id}'}/messages，统一入口客户端默认走 SSE。
AgentRouter 和 TaskStateService 先作为 emoon-ai-agent 内部能力实现，不新增公共 /tasks P0 API。
/files/upload + /files/{'{fileId}'} + DELETE /files/{'{fileId}'} 幂等删除。
/cards/{'{id}'} + /cards/{'{id}'}/actions/{'{actionName}'}，卡片动作由 Agent 编排链路推进状态和工具调用。
/tools/{'{toolName}'}/invoke 只接查询类 HIS 工具和显式 Mock 写工具，普通终端不可直接调用。
/devices/{'{deviceId}'}/events + /commands/poll + /commands/{'{commandId}'}/ack，先支撑机器人导航、扫码、打印、异常事件。
/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 接口面，只补充统一入口客户端的调用边界、工程归属、动线阶段和感知上下文。仍需坚持以下边界：

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

对外接口联调基准.md 39 KB История Директен файл