emoon-backend/docs/adr/ADR-202606-001-semantic-response-command-runtime.md

---

doc_id: ADR-202606-001 feature_id: FEAT-202606-006-agent-semantic-interaction type: adr title: 从卡片流程迁移到语义响应与命令治理 status: reviewing owner: 医梦研发团队 created_at: 2026-06-29 updated_at: 2026-07-01 reviewers:

• 架构负责人
• 后端负责人
• 终端负责人 related_docs:
• PRD-202606-002
• ODS-202606-002
• DDS-202606-004 related_modules:
• emoon-openplatform
• emoon-ai-agent
• emoon-ai-card
• emoon-ai-mcp tags:
• ADR
• SemanticResponse
• Command Runtime
• Card Runtime supersedes:
• API-202606-001 ---

从卡片流程迁移到语义响应与命令治理

状态

Reviewing

上下文

现有挂号方案以科室卡、医生卡和时段卡依次推进任务。模型直接生成 cardKey/cardData， Card Runtime 使用 nextCard 形成流程。该方案验证了演示闭环，但产生了以下问题：

• UI Schema 反向约束模型推理和业务异常处理；
• 用户已表达的信息仍被卡片流程重复询问；
• 信息展示、候选选择和 HIS 写操作使用同一动作抽象；
• 卡片渲染失败会影响业务回答；
• 外部引擎输出结构能够间接控制任务状态和写操作。

当前没有生产 Agent 和需要保留的生产卡片实例，因此最终发布可以单次切换； 开发过程仍应分阶段验证核心假设，旧演示链在切换前保持可用。

决策驱动因素

• 查询和推荐必须保持自然语言与工具规划的灵活性；
• 医疗写操作必须具备确定性、实时复核、确认、幂等和审计；
• 多终端需要共享业务语义，但不应共享同一种 UI；
• FastGPT 是首期引擎，但不能成为医疗业务事实源；
• 新架构应消除模型与最终卡片 JSON 的直接耦合。

考虑的方案

方案一：继续强化卡片链

为更多异常路径增加卡片类型和 nextCard 分支。

• 优点：复用当前实现，演示路径直观。
• 缺点：Schema 和分支持续膨胀，仍由表现层控制业务。

方案二：完全取消卡片与确定性运行时

所有查询和写操作均由模型通过 MCP 自由调用。

• 优点：模型灵活，开发表面简单。
• 缺点：无法满足医疗写操作的身份、风险、确认、幂等和审计要求。

方案三：语义响应、无状态展示与命令治理分离

查询由 TaskState、FastGPT 和只读 MCP 驱动；后端生成 SemanticResponse； 展示是无状态投影；副作用由独立 Command Runtime 执行。

• 优点：兼顾灵活查询与确定性交易，多终端可独立适配。
• 缺点：需要升级接口、模块、表结构和终端处理模型。

决策

采用方案三，并做以下强制约束：

1. TaskState 是流程唯一事实源，卡片不再是流程节点。
2. FastGPT 只使用只读 MCP 工具，不直接执行医疗写操作。
3. 模型输出为自然语言流与 Tool/Function Call；SemanticResponse 仅是后端生成的薄传输 DTO。
4. 信息展示无状态，不创建实例；展示失败不影响回答。
5. 副作用进入 Command Runtime，并按 L0-L3 风险等级处理。
6. 命令只能由后端准备，终端只能确认、拒绝或查询。
7. emoon-ai-card 在实施阶段重命名为 emoon-ai-command。
8. v2 API 删除 nextCard 和通用 card_created 语义。
9. 不提供生产运行期新旧协议双轨；开发按能力验证、查询链、命令链分阶段完成，最后单次切换。
10. 本决策作为后续智能体的前置架构基线；在新架构验收完成前，不按旧链式 Card 模式扩展 生产业务智能体。
11. 后续智能体先定义目标、TaskState、只读工具和 Command，再按终端需要增加可选 Card； Card 不得成为流程节点、状态事实、模型强制输出协议或唯一交互通道。

后果

正向

• Agent 可以跳过已知槽位并覆盖异常、回退和替代推荐。
• 文本、语音和卡片共享同一可信结果，不再互相制约。
• 写操作的安全性不依赖模型遵守 Prompt。
• 模块名称、接口和数据模型直接表达业务职责。
• FastGPT 可替换性保留在 Adapter 边界，不进入业务事实层。

负向

• 最终切换仍需要同步替换现有演示链路、终端和 SQL。
• 需要新增 ResultSnapshot 和 Command Runtime；响应组装与展示决策保持为 Agent 内部薄能力。
• 终端需要实现新的 interaction、presentation 和 command 事件。

风险与缓解

• 迁移遗漏旧卡片语义：通过仓库全文检索和架构测试清单验收。
• FastGPT 工具能力不满足：实施前能力探测；不满足时限制为文本只读问答。
• 命令模型过度复杂：首期只完整实现挂号纵向样板。

迁移原则

采用分阶段开发与验收、最终单次切换，不迁移旧卡片实例数据。具体步骤见 DES-202606-003。

相关决策

• ODS-202606-001：AI 未来医院总体架构。
• DDS-202606-002：FastGPT 接入边界。
• API-202606-001：旧挂号卡片接口契约，本 ADR 决定替代其链式语义。