医梦患者智能服务门户 P0 开发与联调接手指引

对外名称：医梦患者智能服务门户

内部代号：Adjutant（副官）

适用版本：P0 / 单医院移动端 Web Demo

更新日期：2026-07-27

1. 接手者先读什么

建议按以下顺序阅读：

项目根目录 README：启动方式和工程入口。
本文：当前实现、代码边界和联调顺序。
P0 产品与交互文档集：产品定位、入口、流程和验收原则。
产品定义、信息架构和核心交互流程。
实施边界与验收和客户端总交互流程。
最后阅读 src/portal/，再决定联调代码落点。

2. 产品定位与 P0 边界

本项目不是智能体聊天窗口集合，也不是完整互联网医院。它是部署给单家医院、面向患者的智能服务门户。

P0 只验证三项能力：

能力	患者主流程	P0 执行方式
智能分诊挂号	表达需求 → 连续补槽 → 风险筛查 → 查询号源 → 确认挂号	Mock HIS / Mock MCP
检验检查报告解读	上传报告 → 识别分析 → 结构化解读 → 风险提醒	Mock Report MCP
中医舌诊	体质问答 → 上传舌象 → 分析 → 综合结果	后续接现有舌诊 MCP

P0 的明确限制：

单医院，不做跨院数据。
不做登录、实名认证和家庭代办，默认固定 Mock 患者本人。
不接真实 HIS、LIS、EMR，不执行真实挂号或支付。
服务目录可展示更多智能体，但只有三项 P0 能力可点击。
结果和医疗提示均为演示内容，不能用于真实诊断或处置。
交付形态是适配移动端的 Web 系统，不按原生 iOS/Android 应用实现。

虽然 P0 只有本人，后续接口仍应预留 operatorId 和 subjectPatientId，避免 P1 支持家庭代办时重构数据归属。

3. 这几天已经完成的工作

3.1 产品与交互

对外名称统一为“医梦患者智能服务门户”，内部代号为 Adjutant。
固定“首页、服务、健康记录、我的”四个一级入口。
首页吸收“患者状态与待办”，服务中心采用“一级目录 + 二级阶段”的双层目录。
统一助手和三个服务入口最终进入独立任务，不建立微信式智能体会话列表。
核心交互确定为“语音优先、文字可编辑、图片可上传、智能体连续补槽”。
每次智能体回复后，在输入区上方给出一条可点击的推荐回答。
结果以业务记录回看，不只保存在聊天上下文中。

3.2 原型

prototype/adjutant-mobile/ 保存已通过视觉走查的 React 原型，是当前正式前端的设计参考，不是联调运行入口。

原型已经覆盖：

首页状态与待办。
智能体目录和禁用状态。
三智能体对话式任务流程。
移动 Web 语音、文字、拍照/上传输入区。
推荐回答、结构化结果、风险分流和 Mock 标识。

3.3 正式 Vue 前端

根工程已从旧桌面三栏终端切换为移动端门户：

src/App.vue 挂载 src/portal/PortalApp.vue。
src/portal/pages/ 实现首页、服务、健康记录、我的。
src/portal/components/AgentConversation.vue 实现三个 P0 演示流程。
src/portal/catalog.ts 保存智能体目录；仅配置 mode 的三项能力可进入。
src/portal/state/portalStore.ts 管理一级页面和当前智能体。
src/portal/portal.css 实现最大宽度 430px 的移动 Web 页面。
单元测试和 Playwright 测试覆盖入口、流程和移动/桌面预览布局。

4. 工程结构与职责

src/
├── portal/                 # 当前 P0 正式门户
│   ├── components/         # 导航、消息、输入区和智能体会话
│   ├── pages/              # 四个一级页面
│   ├── state/              # 当前门户的轻量状态
│   ├── catalog.ts          # 医院智能体目录
│   ├── types.ts
│   └── portal.css
├── api/                    # 既有 API、HMAC、SSE、卡片 Mock
├── cards/                  # 既有挂号卡片
├── chat/                   # 既有桌面对话组件
├── layouts/                # 既有桌面终端布局
├── state/terminalStore.ts  # 既有终端任务状态
└── theme/tokens.css        # 全局视觉令牌

prototype/adjutant-mobile/  # 设计原型与视觉基准
docs/p0-mobile/             # 产品、交互、契约和验收文档
web-demos/                  # 早期业务流程参考
artifacts/                  # 产品审计和视觉 QA 证据
tests/                      # 单元与 E2E 测试

需要特别注意：

当前运行入口是根 Vue 工程，不是 prototype/adjutant-mobile/。
src/api/、src/cards/ 和 src/state/terminalStore.ts 是旧终端时期留下的可复用基础，尚未与 src/portal/ 完整整合。
不要为了复用旧代码，重新引入桌面三栏、右侧活动卡片或 1280px 最小宽度。

5. 本地启动与验证

环境要求：

Node.js 20 或更高版本。
pnpm 9 或更高版本。
Playwright Chromium（运行 E2E 时需要）。
```
pnpm install
pnpm dev
```

默认访问：

http://127.0.0.1:5173/

完整验证：

pnpm test
pnpm build

当前提交前基线：

单元测试：27 项通过。
E2E：6 项通过。
E2E 视口：390 × 844 移动 Web、1280 × 720 桌面预览。
TypeScript 类型检查和生产构建通过。

6. 三项能力的稳定编码

前端应只认识稳定的 capabilityCode，不要认识 FastGPT 应用 ID。

能力	capabilityCode	当前前端 mode
智能分诊挂号	`SMART_REGISTRATION`	`registration`
报告智能解读	`REPORT_INTERPRETATION`	`report`
中医舌诊	`TCM_TONGUE_ASSESSMENT`	`tongue`

下一步可在 src/portal/types.ts 中把 mode 与 capabilityCode 建立显式映射，再由 Gateway 解析真实执行实现。

7. 推荐的联调边界

客户端不要直接调用 FastGPT，也不要把具体 Workflow ID 写进组件。推荐调用关系：

移动 Web
→ Agent Gateway
→ 能力校验与患者上下文
→ FastGPT / Agent Runtime
→ Mock MCP 或真实 MCP
→ 标准事件和 UI 数据
→ 移动 Web

建议统一请求至少包含：

{
  "hospitalId": "HOSPITAL_DEMO",
  "operatorId": "USER_DEMO",
  "subjectPatientId": "PATIENT_DEMO",
  "relationType": "SELF",
  "capabilityCode": "SMART_REGISTRATION",
  "sessionId": "SESSION_DEMO",
  "taskId": "TASK_DEMO",
  "input": {
    "type": "TEXT",
    "content": "我头疼，帮我挂神经内科明天早上九点的专家号"
  },
  "context": {
    "channel": "MOBILE_WEB",
    "mock": true
  }
}

建议统一返回或事件包含：

traceId、taskId、sessionId。
当前任务状态和等待原因。
智能体文本消息。
已收集字段、缺失字段和下一条推荐回答。
标准 UI 数据，例如号源、报告指标、风险提示和结果摘要。
MCP 调用状态和可公开的错误信息。
是否需要人工处理或终止普通流程。

不要在浏览器日志、测试截图或公共仓库中保存真实报告原图、完整身份证号、手机号、Token 或医院生产地址。

8. 推荐联调顺序

第一步：建立 Agent Gateway 适配层

新建门户专用 API/适配层，隐藏 FastGPT 和 MCP 的具体协议。
配置开发、Mock 和医院环境地址。
统一错误、超时、取消和 traceId。
保留当前前端演示状态作为无后端降级路径。

第二步：联调智能分诊挂号

将语音转文字结果作为普通文本输入送入同一任务。
服务端返回已收集字段、缺失字段和推荐回答。
急诊红旗优先于普通挂号意图。
号源查询、选择和最终确认使用结构化数据。
任何有副作用的操作都必须再次确认，并携带幂等键。

P0 只连接 Mock HIS / Mock MCP，不得误调真实挂号接口。

第三步：联调报告解读

对话内上传图片或 PDF。
展示上传、识别、分析和结果状态。
返回结构化 Markdown 或标准结果字段。
风险提醒必须独立突出，不埋在长文本中。
OCR 失败、图片模糊和接口失败均支持重试。

第四步：联调中医舌诊

先完成体质和症候问答，再进入舌象采集。
上传图片后调用已有舌诊 MCP。
将问答证据和 MCP 结果合并为综合结果。
明确“健康参考，不能替代中医师完整辨证”。

第五步：统一任务与记录

将 AgentConversation.vue 中的本地阶段状态迁移到统一任务 Store。
支持任务中断、恢复、完成和失败。
将完成结果写入“健康记录”，而不是建立智能体聊天会话列表。

9. 交互实现不可破坏的规则

产品始终是移动端 Web，主体最大宽度为 430px；桌面只用于预览。
语音是主要交付方式，但转写内容必须可见，关键操作必须屏幕确认。
文字、语音和推荐回答最终进入同一任务输入协议。
每次智能体回复后生成一条情境相关的推荐回答。
智能体负责理解、追问和解释；列表、选择、上传和确认使用标准组件。
只有三个 P0 智能体可进入，其他目录项保持不可点击。
急诊风险识别是挂号前置安全门禁，不作为患者可点击的独立智能体。
报告和舌诊输出必须结构化展示，不返回一整屏无层次长文本。
医疗风险、Mock 状态和服务边界必须持续可见。
患者回看的是挂号、报告和评估记录，不是智能体会话列表。

10. 当前未完成事项

以下内容是接手后的实际工作，不应误认为当前已经实现：

真实语音识别和录音权限。
Agent Gateway 和 FastGPT 会话联调。
Mock MCP 的网络调用。
报告文件真实上传、OCR 和结构化解析。
现有舌诊 MCP 的真实调用。
服务端任务状态、等待恢复和审计。
健康记录持久化。
医院品牌、能力清单和接口地址的配置化。
P1 登录、实名认证、家庭成员和真实院内接口。

11. 联调验收清单

挂号

一句话包含部分或大部分挂号字段时可正确提取。
缺失医生时连续追问，不能提前查询或提交挂号。
MCP 返回医生后生成“我想挂列表第一位医生”的推荐回答。
所有字段完整后查询 Mock 号源。
患者确认前不执行 Mock 挂号。
胸痛、呼吸困难等演示红旗可停止普通流程。

报告

可在对话内选择图片或 PDF。
上传和分析过程有明确状态。
结果包含概览、风险、异常指标、联合解读和建议。
图片不清晰、格式不支持和服务失败可恢复。

舌诊

体质问答按步骤完成并可继续。
图片上传前有拍摄提示。
MCP 处理中有可理解的状态反馈。
结果同时呈现问答、舌象特征和综合建议。

通用

390px 宽度下无横向滚动、遮挡或原生设备框。
只有三项 P0 服务可点击。
返回后一级导航和目录状态合理。
失败信息不泄露内部接口、Prompt、Token 或患者敏感数据。
pnpm test 和 pnpm build 通过。

12. 提交与协作建议

一次提交只解决一类问题，例如“Gateway 适配”“挂号联调”“报告上传”。
不要同时修改原型和正式前端；只有交互决策变化时才同步原型。
新增能力前先更新 capabilityCode、输入输出契约和验收用例。
任何医院差异应进入配置或 Adapter，不要散落在 Prompt 和页面条件分支中。
保留 Mock 演示路径，确保后端暂不可用时仍能完成 P0 展示。
提交前至少执行 pnpm test 和 pnpm build。

13. 接手后的首个建议任务

先完成一个最小的 AgentGatewayClient，用同一接口支持 Mock 与远程模式，然后只替换挂号流程的本地阶段推进。

完成标准：

页面不感知 FastGPT App ID。
一条挂号会话能够接收服务端追问、缺失字段和推荐回答。
Mock 号源以结构化数据返回并可确认。
网络失败可回退到明确错误状态，不破坏当前页面。
现有测试继续通过，并新增至少一条 Gateway Mock 集成测试。

DEVELOPMENT_GUIDE.md 13 KB Historia Czysty