📘 完整系統說明文件
醫檢師臨床溝通
情境模擬系統
以 AI 角色扮演技術模擬真實臨床溝通場景，協助醫事檢驗師學員在安全環境中練習危急值通報、跨職類溝通與爭議處理，並即時取得結構化評分回饋。
01
系統介紹
設計目標、核心功能與適用對象
本系統針對醫事檢驗師（醫檢師）的臨床溝通訓練需求設計，提供沉浸式的 AI 角色扮演對話環境。學員以「醫檢師」身份與 AI 扮演的護理師、醫師等角色進行語音或文字互動，完成後獲得結構化即時評分。教師可為每個情境自訂評分維度、配分比重與具體判斷準則。
沉浸式角色扮演
AI 持續扮演指定角色，依情境設定表現出不同態度（急躁、懷疑、激動），不中途跳脫角色。
真人語音合成
使用 Google WaveNet 神經網路 TTS，男女聲分別對應不同角色，具有自然語速與音調。
自訂評分標準
每個情境可設定 2–4 個評分維度，自訂名稱、配分比重與具體判斷準則，由 AI 對照給分。
SOP 對照機制
教師可為每個情境設定 SOP 標準，AI 會依 SOP 糾正或融入知識，強化程序訓練。
語音輸入支援
Chrome 瀏覽器可使用麥克風輸入，模擬真實電話溝通情境，語音自動轉文字後送出。
教師後台管理
密碼保護後台，可新增、編輯、複製、刪除情境，並透過 JSON 匯入匯出或雲端同步。
適用對象
👨🎓 學員
醫事檢驗學系學生、實習醫檢師、需加強溝通訓練的在職人員。使用 index.html 進行模擬練習。
👩🏫 教師 / 管理員
設計課程情境、設定評分標準的教育人員。使用 admin.html 管理所有情境設定。
02
技術架構
系統元件、資料流向與服務端點
前端（瀏覽器）
📄 index.html
學員介面
學員介面
⚙️ admin.html
教師後台
教師後台
↕
Cloudflare Workers（中繼代理）
🔀 gemini-proxy
AI 對話 + 情境 KV 存取
AI 對話 + 情境 KV 存取
🔀 google-tts-proxy
語音合成代理
語音合成代理
↕
Google Cloud 服務
🤖 Gemini 2.5 Flash
語言模型 API
語言模型 API
🔊 WaveNet TTS
神經網路語音合成
神經網路語音合成
持久化儲存
☁️ Cloudflare KV
情境資料雲端同步
情境資料雲端同步
💾 localStorage
本機快取 / 離線備援
本機快取 / 離線備援
服務端點
| 端點 | 用途 | 說明 |
|---|---|---|
| gemini-proxy.yusfish.workers.dev/gemini | AI 對話 | 代理 Gemini API，隱藏 API Key；前端直接呼叫此端點 |
| gemini-proxy.yusfish.workers.dev/scenarios | 情境資料讀寫 | GET 讀取、POST 儲存情境 JSON 至 Cloudflare KV |
| google-tts-proxy.yusfish.workers.dev | 語音合成 | 代理 Google Cloud TTS API，回傳 base64 MP3 |
資料儲存策略
優先：Cloudflare KV 雲端
教師後台儲存時同步推送至 KV，學員頁面啟動時優先從 KV 拉取最新情境，確保多裝置一致。
備援：localStorage 本機
KV 讀取失敗時降級使用本機快取，保障離線或網路不穩時仍可使用；成功讀取 KV 後自動同步本機。
03
學員操作：開始使用
從開啟頁面到選擇情境的完整步驟
建議使用 Google Chrome 瀏覽器，以確保語音輸入（Web Speech API）與語音合成功能正常運作。其他 Chromium 系瀏覽器（Edge、Brave）亦可，Safari / Firefox 部分功能受限。
步驟一：設定語言模型
頁面頂端可切換模型。建議使用 Gemini 2.5 Flash（預設）；若出現「高需求」（503）錯誤，切換至 Flash Lite。
| 模型 | 特性 | 適用情境 |
|---|---|---|
| Gemini 2.5 Flash | 高品質推理、角色扮演能力強 | 預設選項，正式練習時使用 |
| Gemini 2.5 Flash Lite | 速度較快、配額較寬 | Flash 出現 503 時切換 |
步驟二：設定語音合成（TTS）
Google WaveNet（推薦）
透過 Cloudflare Worker 代理，聲音自然逼真。
預設端點已設定，直接點「測試」確認連線。
每月前 100 萬字元免費。
預設端點已設定，直接點「測試」確認連線。
每月前 100 萬字元免費。
瀏覽器內建 TTS
不需額外設定，直接使用作業系統語音引擎。
聲音品質因裝置而異，不需網路連線。
聲音品質因裝置而異，不需網路連線。
步驟三：選擇情境並開始
1
從情境列表選擇目標情境
點選情境卡片，卡片會反白標記。情境右上角若有 📄 SOP 標籤，代表此情境已設定標準流程供 AI 對照。
2
點擊「開始模擬」
頁面切換至模擬介面，AI 自動開口說出第一句情境開場白，語音同步播放。
3
閱讀情境背景說明
畫面頂端顯示你的身份（醫檢師）、對方角色，以及情境背景說明，幫助進入狀況。
04
學員操作：進行模擬
對話輸入、語音控制與進度追蹤
輸入方式
文字輸入
在下方文字框直接打字。
Enter 鍵送出；Shift + Enter 換行。
Enter 鍵送出；Shift + Enter 換行。
語音輸入（Chrome 限定）
點擊麥克風按鈕開始錄音，再按一次停止並自動送出。
辨識中的文字即時顯示在輸入框，以 [辨識中: ...] 標示。
辨識中的文字即時顯示在輸入框，以 [辨識中: ...] 標示。
回合計數
畫面左上顯示「回合 N / M」，M 為此情境設定的總回合數（教師可設定 1–10 回合，預設 4）。右側圓點進度條顯示目前進度：
已完成的回合
目前回合
尚未到達
朗讀 AI 回應
每則 AI 回應下方有「🔊 朗讀」按鈕，點擊後 AI 角色聲音播放；播放中再點一次可停止。新回應產生時預設自動朗讀。
注意：當麥克風錄音中時，AI 朗讀會自動停止，避免語音迴授（AI 聲音被麥克風收進去）。
AI 的行為邏輯
AI 根據情境設定的以下參數調整行為：
| 參數 | 說明 | 範圍 |
|---|---|---|
| 角色強硬程度 | 控制 AI 配合度，數值越高越難搞定 | 1（好說話）→ 5（難纏） |
| 回應長度 | 控制 AI 每次回應的句數 | 1（極簡短）→ 5（詳細） |
| 語氣情緒 | 控制 AI 的情緒激動程度 | 1（平靜）→ 5（激動） |
| Temperature | 控制 AI 回應的隨機性與創意 | 0.0 → 1.0（預設 0.85） |
05
學員操作：成績評分
評分維度、等級標準與結果解讀
達到設定回合數後，系統自動進入評分流程，由另一個 Gemini 呼叫（低 temperature 0.2）分析完整對話記錄。
評分維度
溝通禮貌
/ 33 分
問候、稱謂、語氣態度、換位思考、安撫情緒的能力。
資訊準確性
/ 34 分
核對資訊完整度、說明正確性、術語使用是否精準。
專業應變
/ 33 分
面對刁難或質疑時的反應、提供解方的能力、流程掌握度。
等級標準
| 等級 | 分數 | 說明 |
|---|---|---|
| A 優 | 85 – 100 | 溝通流暢、SOP 掌握佳、能有效處理對方情緒 |
| B 良 | 70 – 84 | 基本溝通能力合格，部分環節有待加強 |
| C 及格 | 55 – 69 | 核心資訊傳達但方式有明顯缺失 |
| D 待加強 | 0 – 54 | 流程偏差明顯，建議重新複習後再練習 |
結果欄位說明
評分卡片包含：各維度分數 + 條狀圖 + 文字點評、整體建議文字、以及一句「理想開場示範」供參考。若情境有設定 SOP，評分中也會具體指出遵守或缺漏的 SOP 步驟。
06
教師後台：登入
密碼保護機制與修改方式
後台位於 admin.html，學員頁面右上角「⚙ 教師後台」連結可直接開啟。
預設密碼
系統預設密碼為 1234。首次使用請立即修改。
修改密碼
1
登入後台
在鎖定畫面輸入目前密碼，按 Enter 或點「進入後台」。
2
找到「系統設定」區塊
頁面頂端的「🔑 系統設定」卡片，填入新密碼（輸入兩次確認）。
3
點「更新密碼」
密碼儲存於 localStorage，下次開啟後台需使用新密碼。注意：每台裝置的 localStorage 是獨立的，在不同瀏覽器修改密碼不會同步。
安全提醒：密碼儲存在 localStorage（明文），僅為基礎防護，防止學員誤入後台。若需更高安全性，請在 Cloudflare Worker 層面加上認證。
07
教師後台：情境管理
新增、編輯、複製與刪除情境的完整說明
預設情境
系統內建三個示範情境，可直接使用或修改：
危急值通報被掛電話
血鉀 6.8 mmol/L，通知病房護理師時對方說「我知道了」就掛斷。測試學員是否能確保對方複誦資訊並承諾通知醫師。
醫師質疑血型報告正確性
發血前，主治醫師質疑「血型怎麼跟上次不一樣，是不是驗錯了？」測試學員能否清楚說明正逆向定型及檢體核對流程。
檢體退件 dispute
護理師送來的尿液檢體量不足，退件後護理師生氣地打電話來抗議。測試學員能否有邏輯地說明標準並給出協助方案。
情境設定欄位說明
| 欄位 | 說明 | 注意事項 |
|---|---|---|
| 圖示 | 情境代表的 emoji | 建議使用醫療相關表情符號 |
| 情境標題 | 簡短有力的標題 | 顯示於學員選擇列表 |
| 簡短描述 | 一句話說明情境 | 顯示於學員選擇列表卡片下方 |
| 回合數 | 對話總回合數 | 建議 3–6 回合，過多會稀釋難度 |
| 背景說明 | 學員看到的情境說明文字 | 交代時間、事件背景，不含角色指引 |
| 角色名稱 | AI 扮演的角色稱呼 | 顯示於聊天氣泡左上方 |
| 角色描述 | 角色的簡短性格說明 | 顯示於學員的情境頁（「對方身份」後） |
| 聲音性別 | 選擇 TTS 語音 | 女聲：cmn-TW-Wavenet-A；男聲：cmn-TW-Wavenet-B |
| AI 角色指引 | 給 AI 的 System Prompt 指示 | 學員不可見；是決定 AI 行為最關鍵的欄位 |
| Temperature | AI 回應隨機性 | 0.7–0.9 為角色扮演最佳範圍 |
新增 / 複製 / 刪除
＋ 新增情境
點擊虛線框「新增情境」，系統建立空白情境並自動展開編輯面板。
⧉ 複製情境
情境卡右上角複製按鈕，快速建立相似情境，標題自動加上「（複製）」。
🗑 刪除情境
系統至少保留一個情境，刪除需二次確認。刪除後不可還原（請先匯出備份）。
每次修改後請點選頂端「💾 儲存全部」或底部「儲存全部」按鈕，才會同步至 Cloudflare KV 雲端供學員使用。
08
教師後台：SOP 設定
標準作業程序設定與 AI 使用模式
SOP 功能讓 AI 在對話中參考標準作業程序，判斷學員是否依流程執行，並在評分時具體指出遵守或缺失。
撰寫建議
建議搭配 NotebookLM 將正式 SOP 文件轉換為精簡摘要後貼入。格式以條列式為佳，300 字以內，著重關鍵步驟而非完整法規條文。
範例 SOP（危急值通報）：
1. 確認危急值項目及數值，查核病患姓名、病歷號
2. 致電通知主治醫師或值班醫師
3. 要求對方複誦：病患姓名、病歷號、危急值項目與數值
4. 確認通報者姓名、單位、時間
5. 承諾 5 分鐘內通知主治醫師，並取得承諾
6. 完成後填寫危急值通報紀錄單並簽名
SOP 使用模式
🎯
嚴格模式
AI 主動監測學員是否按 SOP 行事。
若學員偏離，AI 會明確指出（例如：「你還沒有要求我複誦病患資料」）。
適合：初學者、熟悉流程為主要目標的課程。
若學員偏離，AI 會明確指出（例如：「你還沒有要求我複誦病患資料」）。
適合：初學者、熟悉流程為主要目標的課程。
🌊
自然模式
AI 將 SOP 作為背景知識，自然融入反應中，不主動點破偏離。
評分結束後才反映 SOP 遵守程度。
適合：進階練習、評估整合能力的課程。
評分結束後才反映 SOP 遵守程度。
適合：進階練習、評估整合能力的課程。
SOP 在對話中的注入邏輯
系統每回合都將 SOP 完整注入 System Prompt（方案 A），確保 AI 不遺忘：
// 第 1 回合：帶模式說明
【嚴格模式】：若學員在對話中未遵守以下 SOP 步驟，
請在適當時機點破或糾正...
// 第 2+ 回合：持續提醒
【SOP 提醒】請持續依照以下標準步驟來判斷學員表現：
1. 確認危急值...
2. 致電通知...
09
教師後台：自訂評分標準
評分維度、配分比重與具體判斷準則設定
每個情境在「評分設定」區塊可獨立設定 2–4 個評分維度。教師同時可透過滑桿設定配分比重，並在文字框輸入具體判斷準則，讓 AI 依據條件給分，而不是完全自行發揮。
重要：各維度的配分比重合計必須等於 100 分，後台才允許儲存。合計列會即時顯示目前總和，未達 100 時變紅字提示。
介面元件說明
| 元件 | 說明 | 限制 |
|---|---|---|
| 維度名稱 | 自由輸入此維度的名稱，顯示於學員評分結果卡 | 每個情境 2–4 個維度 |
| 配分比重滑桿 | 設定此維度的滿分，拖動滑桿快速調整 | 每個維度 5–60 分；總和需等於 100 |
| 具體判斷準則 | 條列式輸入加分項目，AI 評分時對照執行 | 選填；留空則 AI 依通用標準自行判斷 |
| ＋ 新增維度 | 新增一個評分維度（預設名稱「新維度」，比重 10 分） | 上限 4 個維度 |
| ✕ 刪除維度 | 刪除此維度（需至少保留 2 個） | 少於 3 個時刪除鈕隱藏 |
判斷準則撰寫建議
準則以條列式撰寫，每條敘述一個具體行為及其配分，讓 AI 有明確依據：
// 範例：資訊準確性（40分）的判斷準則
・報出病患姓名與病歷號 +10分
・說明危急值項目與具體數值 +10分
・要求對方複誦關鍵資料 +10分
・確認通報時間與通報者身份 +10分
注意：判斷準則的分數僅供 AI 參考，AI 仍可能依整體對話品質微調給分。若需非常精確的配分，建議搭配 SOP 嚴格模式同步使用。
預設維度
新情境與預設情境皆使用以下三個預設維度，教師可直接修改或刪除後重新設計：
溝通禮貌
33 分
問候、稱謂、語氣、同理心
資訊準確性
34 分
核對資訊完整度、術語正確性
專業應變
33 分
面對刁難的反應、提供解方能力
評分結果呈現
學員完成模擬後，評分卡依照教師設定的維度動態渲染，最多顯示 4 個維度的分數條與點評，每個維度顏色固定（紫→綠→棕→紫紅）便於辨識。舊情境若無 scoringDims 欄位，自動 fallback 回原本三維度，向下相容。
10
教師後台：匯出匯入與備份
情境資料的備份、還原與重設
匯出 JSON
將目前所有情境匯出為 JSON 檔案，檔名包含日期（如 medlab_scenarios_2025-06-01.json）。建議定期匯出作為備份。
匯入 JSON
選取先前匯出的 JSON 檔案，將完全覆蓋目前所有情境（需二次確認）。匯入後自動同步至雲端。
重設預設值
清除所有自訂情境，還原為系統內建的三個預設情境。操作不可逆，請先匯出備份。
JSON 格式說明
匯出的 JSON 為情境物件陣列，每個物件包含：
[
{
"id": 0,
"icon": "🚨",
"title": "危急值通報被掛電話",
"desc": "血鉀 6.8 mmol/L...",
"role": "急診病房護理師",
"roleDesc": "正在忙碌、略顯不耐煩",
"voiceGender": "female",
"background": "你剛完成血液常規...",
"aiPersona": "你扮演急診病房護理師...",
"hardness": 4,
"length": 2,
"emotion": 4,
"turns": 4,
"temperature": 0.85,
"sopText": "1. 確認危急值...",
"sopMode": "strict",
"scoringDims": [
{ "name": "溝通禮貌", "weight": 33, "criteria": "・有禮貌開場 +10分\n・確認身份 +10分" },
{ "name": "資訊準確性", "weight": 34, "criteria": "" },
{ "name": "專業應變", "weight": 33, "criteria": "" }
]
}
]
11
進階：AI 提示詞設計
角色指引撰寫技巧與最佳實踐
「AI 角色指引」是決定模擬品質最關鍵的設定，以下是有效撰寫的原則：
有效角色指引的結構
A
身份宣告
「你扮演…」明確宣告角色身份和當下狀態。
範例：你扮演急診病房護理師，正處理多位病患，語氣急促不耐。
範例：你扮演急診病房護理師，正處理多位病患，語氣急促不耐。
B
動機說明
說明角色為什麼這樣行動，避免 AI 變成純粹刁難。
範例：你不是蓄意刁難，但你對病患安全負責。
範例：你不是蓄意刁難，但你對病患安全負責。
C
條件觸發
明確定義「什麼情況下態度軟化」、「什麼情況下升級對抗」。
範例：除非學員明確要求對方複誦病患資料，否則不主動配合。
範例：除非學員明確要求對方複誦病患資料，否則不主動配合。
D
結束觸發（可選）
設定特定行為觸發情境結束（如掛電話）。
範例：若學員未確認便試圖結束通話，你就說「好好好」然後掛斷。
範例：若學員未確認便試圖結束通話，你就說「好好好」然後掛斷。
System Prompt 完整組成
每次 AI 呼叫的 System Prompt 由以下部分組成：
你是醫學教育角色扮演系統中的AI角色。
情境：[情境標題]
你的身份：[角色名稱]（[角色描述]）
背景：[背景說明]
角色指引：[AI 角色指引]
【AI風格設定】角色強硬程度：好說話/難纏。[長度設定]。[情緒設定]。
【SOP提醒】請持續依照以下標準步驟...[SOP內容]
規則：保持角色，繁體中文。不透露評分標準。
學員表現良好則逐漸軟化態度。
注意：由於 Gemini 沒有跨回合記憶，系統每次呼叫都會將完整對話歷史送入 contents 陣列，確保 AI 能維持一致角色。
12
進階：語音合成設定
Google WaveNet 與瀏覽器 TTS 的技術細節
Google WaveNet 語音規格
| 角色 | 語音名稱 | 語速 | 音調 | 適用情境 |
|---|---|---|---|---|
| 👩 女聲 | cmn-TW-Wavenet-A | 1.15x | +1 | 護理師（情境①③） |
| 👨 男聲 | cmn-TW-Wavenet-B | 1.1x | -2 | 醫師（情境②） |
TTS API 請求格式
POST https://google-tts-proxy.yusfish.workers.dev
{
"input": { "text": "語音合成文字" },
"voice": {
"languageCode": "cmn-TW",
"name": "cmn-TW-Wavenet-A",
"ssmlGender": "FEMALE"
},
"audioConfig": {
"audioEncoding": "MP3",
"speakingRate": 1.15,
"pitch": 1
}
}
降級機制
Google TTS 失敗時（網路問題、配額用盡）自動降級至瀏覽器內建 SpeechSynthesis API，語音品質較低但保證可用。Console 會顯示 Google TTS 失敗，降級：[錯誤訊息]。
13
進階：評分機制
評分 Prompt 設計與動態 JSON 輸出格式
評分呼叫設定
模型
與對話使用相同的 currentModel
Temperature
0.2（低隨機性，確保評分一致性）
Max Tokens
1024（足夠回傳完整 JSON + 評語）
輸出格式
純 JSON，前端用 regex 擷取 \{[\s\S]*\}
動態評分 Prompt 組成
評分 prompt 依教師設定的 scoringDims 動態組裝，每個維度的名稱、滿分、判斷準則都會注入：
你是醫學教育評核專家。請評分以下醫檢師學員溝通表現。
情境：[情境標題]
對話記錄：[完整對話]
【SOP 對照標準】（若有設定）：...
【評分維度與準則】
【維度1】溝通禮貌（滿分33分）
評分準則：・有禮貌開場 +10分 ...
【維度2】資訊準確性（滿分34分）
（由你依通用標準自行判斷給分）
請只回傳 JSON，不要 markdown：
{"dim0": 25, "dim1": 28, "dim2": 20, "total": 73,
"dim0_comment": "...", "dim1_comment": "...", "dim2_comment": "...",
"overall": "整體建議", "model_reply": "理想開場示範"}
評分 JSON 欄位說明
| 欄位 | 型別 | 說明 |
|---|---|---|
| dim0 ~ dim3 | number | 各維度得分，依 scoringDims 索引對應（最多 4 個） |
| total | number | 各維度加總，0–100 |
| dim0_comment ~ dim3_comment | string | 各維度的具體點評文字 |
| overall | string | 整體建議文字 |
| model_reply | string | 理想開場示範一句話 |
舊情境若無 scoringDims 欄位，系統自動 fallback 為預設三維度（溝通禮貌 / 資訊準確性 / 專業應變），評分 prompt 使用舊鍵名（politeness / accuracy / response），向下完全相容。
14
常見問題
使用時遇到問題的解決方式
Q：AI 回應出現「高需求」或 503 錯誤
這是 Gemini API 的流量限制。解決方式：在頁面頂端的模型選擇器切換至 Gemini 2.5 Flash Lite，重新開始模擬即可。
Q：語音無法播放
先點「測試」確認 TTS Worker 連線。若顯示失敗：(1) 確認網路正常；(2) 改用「瀏覽器內建」TTS；(3) 確認 Cloudflare Worker 正常運作。
Q：麥克風無法使用
Web Speech API 僅支援 Chrome / Edge 等 Chromium 瀏覽器，且需要 HTTPS 或 localhost 環境。確認瀏覽器已授權麥克風權限。
Q：學員頁面未顯示最新情境
情境從 Cloudflare KV 雲端讀取。確認教師後台儲存時顯示「已儲存並同步至雲端」（非「雲端同步失敗」）。學員重新整理頁面後應可取得最新版本。
Q：評分維度比重合計不等於 100 怎麼辦
後台「評分設定」區塊頂端的合計列會即時顯示目前總和。未達 100 時呈紅字。調整各維度的配分滑桿使其合計為 100，再點「💾 儲存全部」即可。
Q：評分結果失敗或格式異常
評分呼叫偶發 JSON 解析失敗（AI 輸出含 Markdown 格式）。系統已實作 regex 清理，若仍失敗可重新開始一次模擬。若持續發生，嘗試切換模型。
Q：不同電腦的後台密碼不同
密碼儲存於各裝置的 localStorage，不跨裝置同步。若需統一密碼管理，需在所有裝置手動設定相同密碼。
Q：如何完全重置系統
操作順序：後台 → 「↺ 重設預設值」清除所有情境 → 或直接匯入備份的 JSON 檔案。localStorage 的密碼需另外在各裝置清除（瀏覽器開發者工具 → Application → localStorage）。