lik b386dc469f fix: 健康档案更新摊平嵌套对象避免 Mongo 路径冲突
$set 同时出现 profile 与 profile.pinyin 会触发路径冲突,
整块覆盖嵌套对象又绕开 pre("save") 丢拼音字段;
pickFields 支持 flatten 递归摊平后按点号路径写入
2026-11-08 12:00:25 +08:00
2026-11-05 16:31:51 +08:00
2026-11-05 16:31:51 +08:00
2026-09-13 11:40:42 +08:00
2026-11-05 16:31:51 +08:00
2026-05-25 12:46:14 +08:00

api-health

陪诊小程序的后端服务(Koa + 原生 WebSocket + MongoDB),除订单/档案等业务接口外, 还提供 AI 陪诊助手与语音转写 / 图像识别两类多模态输入能力。

npm install
npm run dev     # nodemon index.js,HTTP 9004 / WS 9005
npm test        # node --test test/*.test.js

语音与图像识别

设计参考 xagent 的设备数据通道(asr.js / asr_dashscope.js / ocr.js / ocr_qwen.js), 保留了「识别与投递解耦」的会话契约。语音有两条传输方式:

  • 实时分片(默认):走聊天 WebSocket 的 asr_start / asr_chunk / asr_stop, 中间结果经 asr_partial 逐字回显,定稿经 asr_final 返回。
  • HTTP base64 整段上传(兜底):/health/ai/asr 用于分片缺失(如开发者工具)或实时链路失败的场景。

共同约定:

  • 识别只产出文本,服务端不投递、不落库;客户端把文本回填输入框,由用户点发送键后再走原聊天链路(WS chat)。
  • 音频 / 图片只在本轮请求内存中存在,不落盘、日志不记录正文。
  • 默认只做转写:语音用 fun-asr-realtime,图片用 qwen-vl-ocr;是否进一步解读由 agent 的提示词决定。
  • 接口必须登录(token 或 Authorization: Bearer <token>),按用户限流 20 次/分钟。

实时语音识别(WS /chat)

上行帧(客户端 → 服务端):

帧 字段 说明
asr_start id / token / format? / sampleRate? / channels? 声明一轮识别,鉴权与限流都在这一步
asr_chunk id / audio(base64 分片) 每帧一个录音分片,单帧 ≤ 128KB,整轮 ≤ 8MB
asr_stop id 结束推流并取定稿
asr_cancel id 放弃本轮(页面隐藏、录音中断)

下行帧(服务端 → 客户端,type 为下列值,id 与上行 asr_start 的 id 对应):

帧 content 说明
asr_partial 当前累计文本 中间结果,客户端实时回填输入框
asr_final 定稿文本(可能为空串) 结束后返回,客户端提示重录或留在输入框
asr_error 可读错误文案 客户端改用整段接口兜底

同一连接上同时只保留一轮识别;asr_start 会中止上一轮,连接关闭时也会 abort。

POST /health/ai/asr

请求体(JSON,上限 20MB,解码后音频 ≤ 10MB):

字段 类型 必填 说明
audio string 是 base64 或 data:audio/mpeg;base64,...
format string 否 mp3(默认)/ aac / wav / pcm / pcm16
sampleRate number 否 8000 / 16000(默认)/ 24000 / 48000
channels number 否 仅支持 1
curl -s http://localhost:9004/health/ai/asr \
  -H "Content-Type: application/json" -H "token: <token>" \
  -d '{"audio":"<base64>","format":"mp3"}'
# => { "code": 0, "msg": "操作成功", "data": { "text": "我明天想带老人去复查" }, "ts": ... }

POST /health/ai/ocr

请求体(JSON,上限 20MB,解码后图片 ≤ 8MB):

字段 类型 必填 说明
image string 是 base64 或 data URL
mime string 否 image/jpeg(默认)/ image/png / image/webp
width / height number 否 像素尺寸,仅用于让模型判断清晰度
kind string 否 首版固定 auto,服务端按内容自行判断报告类型
curl -s http://localhost:9004/health/ai/ocr \
  -H "Content-Type: application/json" -H "token: <token>" \
  -d '{"image":"<base64>","mime":"image/jpeg"}'

返回的 data.text 是可直接投喂给 agent 的可读文本,段落包括【图像识别】【原文转写】 【结构化要点】(full 模式才有解读段)【图像质量】【说明】,末尾带免责说明。

profile: transcribe(默认)只传图片、不附加提示词:qwen-vl-ocr 自带逐行转写模板, 附加系统提示或 JSON 契约会把原文压成摘要、表格列还会粘连,因此【原文转写】段必须是 模型原生输出的完整原文;文档类型与标题由服务端按文本关键词兜底判断。

原生转写用制表符 / 多空格 / 全角空格对齐列,直接展示会被 markdown 折叠成一串, 因此服务端会把连续的分列块转成 markdown 表格(列数不足补空列,超出并进最后一列), 其余行独立成段保留换行。小程序与 Taro 端都按 markdown 渲染即可。

小程序把识别文本以 WS format 帧投递({ type: "format", content, id, token, ts }): 服务端只把原文并入会话上下文,并按分片原样回显给客户端展示,不再让模型二次改写。 识别结果通常有几百到上千字,模型改写会按咨询提示词压缩成 1-3 句,还会被输出护栏的 400 字上限截断,长报告必然丢行;原文投递既完整,也省一次生成。

错误码

业务码统一走响应体 code(HTTP 恒 200),同时写入 X-Biz-Code 响应头:

code 场景
400 参数缺失 / base64 非法 / 格式或采样率不支持 / 超出大小上限 / 未识别到内容
401 未登录或 token 失效
403 无权限
502 供应商识别失败(错误详情只进日志)
503 识别服务未配置(缺密钥 / 缺少 endpoint)

配置

识别配置位于 conf.json 的 agent.media 段,密钥支持直接写 apiKey,或通过 apiKeyEnv 指向环境变量(.env 由 dotenv 加载):

"media": {
  "audio": { "rate": 16000, "channels": 1 },
  "asr": {
    "provider": "dashscope",
    "endpoint": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "model": "fun-asr-realtime",
    "apiKeyEnv": "ASR_KEY"
  },
  "image": { "mimes": ["image/jpeg", "image/png", "image/webp"] },
  "ocr": {
    "provider": "qwen",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "model": "qwen-vl-ocr",
    "profile": "transcribe",
    "apiKeyEnv": "ASR_KEY",
    "requestTimeoutMs": 60000,
    "disclaimer": "本内容为图像文字识别结果,不构成诊断意见,请以医生诊断与医院报告为准。"
  },
  "limits": { "maxAudioBytes": 10485760, "maxImageBytes": 8388608 }
}
  • 密钥变量名与参考项目 xagent 一致:ASR_KEY;取值顺序为 apiKey → apiKeyEnv → ASR_KEY → DASHSCOPE_API_KEY(后两者兜底,便于两个项目共用同一把 key)。
  • provider: "qwen" 走 OpenAI 兼容 chat/completions;配置 endpoint(http/https)可换成自建 OCR 服务; 也可在代码里给 createOcrSession({ recognize }) 注入本地 PaddleOCR 等实现。
  • provider: "dashscope" 走实时 ASR;不配 provider 而给 endpoint 为 ws/wss 时同样按实时处理; 传 transcribe 或 http endpoint 则走批式。
  • profile: "full" 才会要求模型输出解读字段;涉及诊断结论的能力不默认开启。
  • 密钥为空时两个接口直接回 503「服务暂不可用」,不会发起外部请求。

目录

agent/infra/media/       语音 / 图像识别适配器(会话契约、供应商实现、音频容器识别)
handler/ai_media.js      两个识别接口的入参校验、错误分层与响应
routes/index.js          路由注册(/health/ai/*)
test/media.test.js       元信息白名单、base64 解码、会话生命周期、供应商请求与失败路径

目录约定:

  • 根目录只放入口与配置(index.js / app.js / websocket.js / config.js 等),不提交临时脚本。
  • 自动化测试统一放 test/*.test.js,由 npm test 执行;临时验证脚本应先转成正式测试,不要留在根目录。
  • 一次性运维 / 调试脚本放 scripts/,用完后删除;需长期保留的请在 README 中说明用途和用法。
  • Agent 共享逻辑放 agent/infra/,业务路由与处理器分别放 routes/、handler/。

客户端约定

  • 小程序录音使用 wx.getRecorderManager(),format: 'mp3'、sampleRate: 16000、numberOfChannels: 1, 并带 frameSize(单位 KB)以触发 onFrameRecorded:每帧转 base64 后按 asr_chunk 实时上传, 点麦克风结束(或满 60 秒)时发 asr_stop。
  • 两种录音格式都能实时回填:真机录的是 16k 单声道 MP3(MPEG-2 Layer III), 开发者工具录的是 WebM(Matroska)/Opus(文件名仍是 .mp3)。供应商自带的解码器对这两种容器 都不可靠(真机 mp3 实测直接报 DecodePost resample audio from 0 to 16000 failed), 因此服务端按首帧魔数识别容器后,统一用流式解码器(WebM/Opus、mp3/mpg123)转成 16bit 单声道 PCM(48k 抽取到 16k、16k 原样)再推给供应商,两种环境都能逐字出中间结果。 客户端不再判断容器,分片一律上传;只有服务端明确回 asr_error(认不出容器 / 供应商失败)时 才降级为「结束后整段转写」。首帧认不出容器时服务端先缓存至多 16KB 再判,避免误杀只有 cluster 的平台。
  • 整段识别遇到供应商偶发断流(asr socket closed / 建连超时)会自动重试一次(间隔 600ms), 避免用户白录一遍;解码/参数类错误不重试。
  • 整段音频按 300ms(压缩格式按 64KB)切片推给供应商,并在发送队列排空后才发 finish-task: 一次性把几秒 PCM 塞进 socket 会让供应商来不及消费而直接断流。
  • 实时链路在说话途中失败时客户端不弹错、不中断录音,标记为降级并继续采集;结束时用完整录音文件 (而不是失败瞬间的半截分片)整段提交 /health/ai/asr,只有整段也失败才提示用户。
  • 微信开发者工具的录音实际是 WebM(Matroska)/Opus(文件名仍是 .mp3,控制台会提示格式与移动端不同); 真机才是真正的 16k mp3。服务端按文件头识别容器后都先解码成 16bit 单声道 PCM 再交给供应商, 整段兜底的 /health/ai/asr 走同一个识别入口,因此两条链路都能正常转写。
  • 拍照 / 选图使用 wx.chooseMedia,上传前压缩到 1~2MB。图片不走确认面板:选中后立即作为一条用户消息上屏, /health/ai/ocr 返回的文本直接落成 AI 回复;图片临时路径不落 storage,重启后历史里只保留 [图片] 占位。
  • 语音识别结果实时回填输入框;再次点麦克风结束识别后直接发送(asr_final 定稿或整段兜底成功后 立即走聊天 WS),录音中可看到逐字结果,结束后不需要再点一次发送键。 语音图标本身承担开录与结束(录音中变色,再点一次结束),不弹确认浮层、不遮挡输入框; 若此时还有上一条回复在途,定稿文本会留在输入框,等回复完成后由用户点发送,不丢内容。
  • 语音与图片识别结果可能有错字,涉及数值、单位、药名、日期时由 agent 提示用户确认。
S
Description
No description provided
Readme
2.8 MiB
Languages
JavaScript 100%