playwright_demo/EXTENSION_SETUP_GUIDE.md

医生端语音自动填表 - 浏览器扩展使用指南

📋 概述

这是一个基于浏览器扩展的医疗语音自动填表解决方案，通过以下流程实现：

1. 语音识别：使用浏览器内置 Web Speech API 将语音转为文字
2. 信息提取：调用后端千问大模型服务，从对话中提取结构化医疗信息
3. 自动填表：自动填写到 HIS 系统的表单字段中

---

🚀 快速开始

第一步：启动后端服务

# 在项目根目录启动服务
cd /Users/destiny/dev/emoon/demos/playwright_demo
mvn spring-boot:run

服务启动后，访问 http://localhost:8080 确认服务正常运行。

第二步：安装浏览器扩展

Chrome/Edge 浏览器安装步骤：

1. 打开扩展管理页面

   • Chrome: 访问 chrome://extensions/
   • Edge: 访问 edge://extensions/

2. 开启开发者模式

   • 点击右上角的 "开发者模式" 开关

3. 加载扩展

   • 点击 "加载已解压的扩展程序"
   • 选择扩展目录：/Users/destiny/dev/emoon/demos/playwright_demo/medical-voice-extension

4. 确认安装成功

   • 扩展列表中出现 "医生语音助手"
   • 浏览器工具栏出现扩展图标

Firefox 浏览器安装步骤：

1. 打开扩展管理页面

   • 访问 about:debugging#/runtime/this-firefox

2. 加载临时扩展

   • 点击 "临时载入附加组件"
   • 选择扩展目录中的 manifest.json 文件

第三步：配置扩展（可选）

如果需要修改后端服务地址，编辑扩展配置：

1. 打开文件：medical-voice-extension/content.js

2. 修改配置：

   const CONFIG = {
   BACKEND_URL: 'http://localhost:8080',  // 修改为你的后端地址
   API_ENDPOINT: '/api/extract'
   };
   

---

🎯 使用方法

方式1：在演示页面测试

1. 访问演示页面：http://localhost:8080/
2. 页面右下角会出现 "🎤 语音输入" 按钮
3. 点击按钮，开始说话（例如："患者张三，35岁，男，咳嗽发烧3天"）
4. 停止说话后，系统自动识别语音并填写表单

方式2：在真实 HIS 系统使用

1. 打开医院的 HIS 系统页面
2. 页面右下角会出现 "🎤 语音输入" 按钮
3. 点击按钮并说出医患对话内容
4. 系统自动提取医疗信息并填写到对应字段

示例对话：

医生：您好，请报一下您的姓名和年龄。
患者：我叫张三，今年35岁，男性。
医生：您今天来是因为什么不舒服？
患者：我咳嗽、发烧已经3天了，还伴有咽痛。

---

🔧 工作原理

技术架构

┌─────────────────────────────────────────────────┐
│              浏览器环境                           │
├─────────────────────────────────────────────────┤
│  ┌──────────┐      ┌──────────────┐            │
│  │ HIS页面   │  ↔   │ 浏览器扩展    │            │
│  │ (表单)    │      │ (content.js) │            │
│  └──────────┘      └──────────────┘            │
│       ↑                    ↕                    │
│       │              ┌──────────────┐            │
│       │              │ Web Speech   │            │
│       │              │ API (语音)    │            │
│       │              └──────────────┘            │
│       │                    ↕                    │
│       └────────────→│ 后端服务     │            │
│                      │ (千问大模型) │            │
│                      └──────────────┘            │
└─────────────────────────────────────────────────┘

数据流转

1. 语音识别阶段

   • 用户点击 "语音输入" 按钮
   • 浏览器调用 Web Speech API
   • 实时将语音转换为文字

2. 信息提取阶段

   • 扩展将识别的文字发送到后端服务
   • 后端调用千问大模型进行结构化提取
   • 返回 JSON 格式的医疗信息

3. 表单填写阶段

   • 扩展接收结构化数据
   • 智能匹配表单字段（支持ID、Name、Placeholder、Label）
   • 自动填写并触发 change 事件

---

📝 支持的医疗字段

扩展可以自动识别并填写以下字段：

字段名	中文名称	示例值
patientName	患者姓名	张三
patientAge	年龄	35
patientGender	性别	男
patientPhone	联系电话	13800138000
chiefComplaint	主诉	咳嗽、发烧伴咽痛3天
presentIllness	现病史	3天前受凉后出现发烧
pastHistory	既往史	高血压病史5年
allergyHistory	过敏史	对青霉素过敏
symptoms	症状列表	["咳嗽", "发烧", "咽痛"]
visitType	就诊类型	门诊

---

🎨 字段匹配规则

扩展使用多种策略智能匹配表单字段：

1. 通过 ID 匹配

   • 支持多种命名格式：patientName, patient_name, xingming 等

2. 通过 Name 属性匹配

   • 查找 input/select/textarea 的 name 属性

3. 通过 Placeholder 匹配

   • 查找包含字段名的占位符文本

4. 通过 Label 文本匹配

   • 查找 label 标签的文本内容

5. 通过 XPath 定位

   • 作为最后的兜底方案

示例：

<!-- 以下方式都可以被识别 -->
<input id="patientName" />
<input name="patient_name" />
<input placeholder="请输入患者姓名" />
<label for="name">患者姓名</label><input id="name" />

---

🐛 常见问题

1. 扩展按钮没有出现

解决方法：

• 刷新页面（某些页面需要完全重新加载）
• 检查扩展是否已启用（chrome://extensions/）
• 打开浏览器控制台查看错误信息

2. 语音识别不工作

解决方法：

• 确保使用 Chrome/Edge/Safari（Firefox 需要额外配置）
• 检查麦克风权限是否已授予
• 确认浏览器支持 Web Speech API

3. 表单没有自动填写

解决方法：

• 打开浏览器控制台查看日志
• 检查后端服务是否正常启动
• 查看是否有 CORS 跨域错误

4. 字段识别不准确

解决方法：

• 手动检查表单字段的 ID/Name/Label
• 根据实际情况修改 content.js 中的字段映射配置
• 联系开发人员定制字段匹配规则

---

🔒 安全说明

1. 数据隐私

   • 语音识别在浏览器本地完成，不上传到云端
   • 医疗信息仅发送到内网部署的后端服务
   • 不会保存任何患者数据

2. 网络安全

   • 建议使用 HTTPS 协议访问后端服务
   • 后端服务已配置 CORS 跨域支持
   • 生产环境建议添加身份认证机制

---

📊 浏览器兼容性

浏览器	语音识别	扩展支持	推荐度
Chrome	✅	✅	⭐⭐⭐⭐⭐
Edge	✅	✅	⭐⭐⭐⭐⭐
Safari	✅	⚠️	⭐⭐⭐⭐
Firefox	❌	✅	⭐⭐

注意： Firefox 不支持 Web Speech API，需要额外部署本地语音识别服务。

---

🎓 进阶配置

自定义字段映射

如果 HIS 系统使用特殊的字段命名，可以修改扩展配置：

// 编辑 content.js
const fieldMappings = {
  patientName: [
    'patientName',
    'name',
    'patient_name',
    'xingming',
    '姓名',
    'hzm'  // 添加 HIS 系统的特殊字段名
  ],
  // ... 其他字段
};

调整录音超时时间

recognition.lang = 'zh-CN';
recognition.continuous = false;
recognition.interimResults = false;
recognition.maxAlternatives = 1;
// 可选：添加超时配置

修改按钮样式

const BUTTON_STYLE = {
  position: 'fixed',
  bottom: '100px',
  right: '30px',
  backgroundColor: '#4CAF50',  // 修改按钮颜色
  padding: '15px 20px',
  // ... 其他样式
};

---

📞 技术支持

如果遇到问题，请：

1. 查看浏览器控制台的错误日志
2. 确认后端服务正常运行（访问 http://localhost:8080）
3. 检查扩展是否正确加载

---

📄 许可证

MIT License

---

🎯 总结

使用流程：

1. 启动后端服务 (mvn spring-boot:run)
2. 安装浏览器扩展
3. 打开 HIS 系统页面
4. 点击语音按钮说话
5. 系统自动填写表单

技术优势：

• ✅ 无需修改 HIS 系统代码
• ✅ 支持多种浏览器
• ✅ 完全离线运行（内网部署）
• ✅ 智能字段匹配
• ✅ 实时语音识别