# AI 對話分析算法規格

## 概述
定義 Drama Ling 應用中 AI 對話分析系統的具體實現方案，包含語法、語用、口說三維度評分邏輯。

## 核心評分維度

基於 UI_LevelResult_ScoreSummary.png 的實際設計，採用三維對話評估指標顯示：

### 三維對話評估系統
**目標**: 提供清楚的學習反饋，觸發對應成就獎勵

#### 三維對話評分指標
- [ ] **語法評分**: 評估語法正確性
  - 所有對話皆正確時即為完美表現，若有藉由錯誤訂正功能將全部錯誤訂正完畢，則一樣給予完美表現
  - 獲得完美表現則過關獎勵雙倍
  - 過關獎勵: +1 鑽石 + 10 XP

- [ ] **語用分析**: 評估內容理解和表達適切性(只建議，不評分) 

- [ ] **口說評分**: 評估口說表達的自然度和流暢性
  - 評分標準：
    - 🗣️ **發音評分 (Pronunciation)**: 音素準確度、尾音收口、鼻音共鳴
    - ✅ **完整度評分 (Completeness)**: 句子完整性、遺漏詞彙檢測  
    - 📈 **流暢度評分 (Fluency)**: 語速自然度、停頓合理性
    - 🎶 **韻律評分 (Prosody)**: 語調變化、重音位置、節奏感
    - 🎯 **準確度評分 (Accuracy)**: 整體表達精準度
  - 分數標準
    - 96~100：完美
    - 81~95：優秀
    - 71~80：尚可
    - 0~70：不合格
  - 過關獎勵：
    - 96~100：+3 鑽石 + 30 XP
    - 81~95：+2 鑽石 + 20 XP
    - 71~80：+1 鑽石 + 10 XP
    - 0~70：時光卷
  - **詳細評分顯示範例**:
    ```
    📊 Speaking Score
    
    【Sentence】91.9分：
    Please make sure you have all the necessary documents before submitting your application.
    
    🗣️ Pronunciation：91.9
    📈 Fluency：97
    🎶 Prosody：83.3
    ✅ Completeness：100
    🎯 Accuracy：96
    
    【單字需要加強❌】
    application ⭐⭐：
    🟡 n
    
    【建議改善】
    • 🔚 尾音收口明確（-m, -n, -l, -k, -t），避免吞音。
    🎯 針對音素練習：n
    🤧 鼻音（m/n/ŋ）：軟顎下放，確保鼻腔共鳴與口型到位。
    ```

#### 技術實現方案
- [ ] **AI 模型選擇**: 待決定 (GPT-4/Claude/自建模型)
- [ ] **即時分析**: 目標響應時間 < 2秒
- [ ] **成就觸發機制**: 於遊戲結束時，自動檢測並發放對應獎勵

## AI 對話分析功能

### 即時分析機制 *(更新基於最新規格)*
基於最新規格的詳細分析系統：

- [ ] **每句話即時分析**: 用戶說出的每句話都進行即時判斷
  - 語法正確性分析（即時顯示於對話功能欄）
  - 口說評分（即時顯示於對話功能欄）
  - 任務完成狀態檢測
  - 指定詞彙使用檢測
- [ ] **每句話點擊後分析**：用戶說出的每句話，點擊後才觸發
  - 語用建議(當用戶點擊對話查看語用建議，則生成當前對話相對於整體對話的語用建議)
- [ ] **即時成功通知**: 當用戶提及詞彙或完成任務時立即回饋
- [ ] **三維度結算評分**: 對話結束後的綜合評分
  - 語法錯誤率：整個劇本對話語法錯誤清單
  - 語用建議：整個劇本對話的語用建議
  - 口說整體的平均分數

## 情境對話核心系統

### 雙重通關條件檢測 *(新增核心功能)*
基於最新規格的結構化通關機制：

#### 劇情任務識別系統
- [ ] **任務目標解析**: 
  - 解析每個劇本的具體劇情任務要求
  - 識別對話中的關鍵情節完成點
  - 例如："預約餐廳" → 檢測是否包含預約相關對話元素

- [ ] **任務進度追蹤**:
  - 即時監控劇情任務的完成狀態
  - 分析用戶對話是否達成情節目標
  - 觸發即時成功通知機制

- [ ] **情節完整性驗證**:
  - 確保對話內容符合劇情邏輯
  - 檢驗任務完成的合理性和連貫性
  - 防止虛假完成的判定

#### 指定詞彙檢測系統
- [ ] **詞彙識別引擎**:
  - 精準識別用戶是否使用指定的關鍵詞彙
  - 支援詞彙的不同變化形式（單複數、時態等）
  - 處理同義詞和相關變體的檢測

- [ ] **語境相關性分析**:
  - 確保詞彙使用符合對話情境
  - 避免機械性插入詞彙的誤判
  - 驗證詞彙使用的自然度和適當性

- [ ] **即時反饋機制**:
  - 使用詞彙時立即觸發成功通知
  - 提供詞彙使用品質的評分
  - 記錄詞彙掌握程度的學習數據

### 回覆卡關輔助系統 *(更新基於最新規格)*

#### 回覆協助功能 (消耗寶石)
**觸發時機**: 用戶在扮演角色遇到卡關，不知道該講什麼或怎麼講時

**三層引導內容**:
- [ ] **對方意圖分析**: 根據對話室中最後一句話，分析對方說這句話的意圖
- [ ] **回應思緒引導**: 分析用戶聽到這句話的反應及可能的回覆方向
- [ ] **回覆範例生成**: 生成一句具體的回覆範例

#### 免費輔助功能
- [ ] **劇情任務範例**:
  - 點擊任務提示按鈕後顯示一句範例
  - 說明「這樣說可以完成任務」
  - 當任務已完成時不顯示此按鈕
  - 完全免費，不消耗任何道具

- [ ] **指定詞彙範例**:
  - 展示指定詞彙的正確使用方式
  - 提供詞彙在不同語境下的使用示例
  - 包含詞彙變化形式的學習支援

### 中翻英輔助功能 *(更新基於最新規格)*
- [ ] **Google翻譯整合**: 直接將使用者的中文以Google翻譯轉譯成英文
- [ ] **即時翻譯服務**: 在對話過程中提供即時的中翻英支援
- [ ] **翻譯品質優化**: 針對對話情境調整翻譯結果的適切性
- [ ] **學習引導**: 協助用戶從依賴翻譯逐步過渡到獨立表達

### 語音處理系統 *(新增基於最新規格)*
- [ ] **語音轉文字**: 以語音輸入為主，文字輸入為輔的對話方式
- [ ] **中文檢測**: 當用戶講中文或輸入中文時，角色表示聽不懂
- [ ] **語音品質檢測**: 如果聽不到聲音，顯示「抱歉，好像沒有聲音，請重新錄製」
- [ ] **表達流暢度分析**: 使用Speakace等第三方平台分析精準度、流利度、韻律

## 詞彙學習系統 *(新增功能模組)*

### 詞彙學習關卡系統
基於最新規格的結構化詞彙學習機制：

#### 詞彙認識關卡
- [ ] **詞彙展示功能**:
  - 顯示詞彙本身、詞義、例句和示意圖
  - 協助用戶初步記住詞彙的核心資訊
  - 為後續考題做準備
- [ ] **詞彙選擇題**:
  - 根據示意圖選出正確的英文詞彙
  - 4選1的單選題形式
  - 答錯時，將題目並在最後重新測試
- [ ] **通關機制**: 所有詞彙題目都答對才算通關，直接獲得三顆星

#### 詞彙熟悉關卡  
- [ ] **例句重組功能**:
  - 從單字選取區點選組出示意圖的原句
  - 訓練詞彙在語境中的使用能力
  - 強化語法結構理解
- [ ] **詞彙配對功能**:
  - 左邊示意圖與右邊詞彙進行配對
  - 全部配對正確才算完成
  - 提升詞彙識別和記憶連結
- [ ] **通關機制**: 所有配對和重組正確才算通關，直接獲得三顆星

#### 詞彙口說關卡  
- 這關如果要玩，是要消耗5鑽石，
- 一一秀出詞彙例句，用戶要念出例句，系統會進行口說評分
- 
- [ ] **口說評分**: 評估口說表達的自然度和流暢性
  - 評分標準：整體評分 = 發音評分 & 完整度評分 & 流暢度評分
    - 發音評分
    - 完整度評分
    - 流暢度評分
  - 分數標準
    - 96~100：完美
    - 81~95：優秀
    - 71~80：尚可
    - 0~70：不合格
  - 過關獎勵：
    - 96~100：+3 鑽石 + 30 XP
    - 81~95：+2 鑽石 + 20 XP
    - 71~80：+1 鑽石 + 10 XP
    - 0~70：時光卷

#### 詞彙內容設計標準
基於劇本的5詞彙組合設計：
- [ ] **詞彙組合**: 每個劇本包含5個詞彙
  - 3個常用單字
  - 1個常用片語  
  - 1個常用俚語
- [ ] **詞彙範例結構**:
  - 買菜小冒險: market, vegetables, price + "ask for a discount" + "a steal"
  - 遲到的咖啡約會: coffee, late, apologize + "run into traffic" + "my bad"
  - 失而復得的手機: phone, lost, find + "look around for" + "lucky break"

### 間隔複習系統 *(Spaced Repetition)*
基於遺忘曲線的智慧複習機制：

#### 複習清單管理
- [ ] **自動加入機制**:
  - 詞彙認識、詞彙熟悉、對話訓練通關後自動加入詞彙
  - 避免重複加入已存在的詞彙
  - 維護個人化的複習詞彙庫
- [ ] **複習時機計算**:
  - 下次複習時間 = 當日 + (2^複習次數)
  - 首次加入當日即為第一次複習時間
  - 例如：3/4學習 → 3/6複習 → 3/10複習 → 3/18複習

#### 每日複習排程
- [ ] **待複習詞彙判定**:
  - 複習日期為當日或已過期的詞彙
  - 未準時複習的詞彙持續標記為待複習
  - 延遲複習時重新計算下次複習時間
- [ ] **複習關卡執行**:
  - 以「詞彙熟悉」關卡形式進行複習
  - 答錯題目複製到當前最後一題
  - 直到所有題目都答對才完成複習

#### 進度保存機制
- [ ] **中途離開處理**:
  - 保留用戶當前複習進度和狀態
  - 再次進入時繼續上次未完成的複習
  - 給予已完成部分的經驗值獎勵
- [ ] **完成獎勵機制**:
  - 複習完成後給予經驗值獎勵
  - 更新詞彙複習次數和下次複習時間
  - 強化學習動機和持續性

## 關卡結算與訂正系統 *(新增基於最新規格)*

### 關卡表現結算
**觸發時機**: 當劇本時間用完或用戶主動點選離開劇本時

#### 過關判斷標準
- [ ] **雙重完成檢查**:
  - 是否所有任務都已完成
  - 是否所有指定詞彙都已提及

#### 表現評分系統
- [ ] **評分標準** (每合格一項獲得一顆星):
  1. **語法錯誤率 = 0**
     - 用戶說的每句話經過語法判定都正確
     - 或者訂正後都正確亦可
  2.  **表達流暢平均分數 > 60** (滿分100)
     - 用戶說的每句話都會有流暢度分數
     - 所有分數平均即為表達流暢平均分數
  3. **對話語用評估分數 只建議不評分**  
     - 語用標準定義與用途：
       1. **日常寒暄 (Small Talk)**
          - 定義：不以傳遞實質資訊為主要目的，而是用於建立或維持社交關係的言談
          - 用途：
            - 建立對話氛圍與人際連結
            - 作為開場、轉場或緩和氣氛的策略
            - 在客服或 AI 助手中，用來提升「人性化」感
       2. **間接表達 (Indirectness)**
          - 定義：透過暗示、委婉語或迂迴方式表達意圖，避免直接衝突
          - 用途：
            - 避免冒犯，維持人際和諧
            - 展現禮貌或文化上的尊重
            - 在跨文化溝通中，辨識不同社會的表達習慣
       3. **填充語 (Fillers)**
          - 定義：非必要詞語，用來填補語流空隙、保持連續或爭取思考時間
          - 用途：
            - 提示對方「話還沒說完」
            - 增加口語自然度（模擬真實對話）
            - 作為語音辨識或對話系統的特徵，用於偵測自然口語
       4. **同理回應 (Backchanneling)**
          - 定義：聽話者以簡短語言或聲音表達注意、理解或支持，不打斷主要話輪
          - 用途：
            - 提供傾聽與理解的訊號，維持互動流暢
            - 增強情感支持與共鳴
            - 在對話系統中，提升使用者「被理解」的感受
       5. **模糊語 (Hedging)**
          - 定義：降低語氣確定性，避免過度斷言的語言策略
          - 用途：
            - 顯示謹慎，降低爭議風險
            - 表達禮貌，避免武斷或冒犯
            - 在學術或專業語境中，用來維持客觀或彈性
       6. **文化慣用語 (Idioms)**
          - 定義：文化群體中固定的表達方式，通常無法逐字翻譯
          - 用途：
            - 增加語言的自然性與文化深度
            - 強化群體認同感
            - 作為語言學習與跨文化理解的重要素材

  - **語用評分範例**：
    ```
    --- Dialogue
    
    👨(Client)：How is Mr. Davies feeling about our upcoming meeting?
    
    👨(Business Professional)：Wow, you know what he is very anxious to meet you
    
    The client is responding to the business professional's statement about Mr. Davies being anxious to meet him. He acknowledges the information and expresses his own anticipation for the meeting, maintaining a professional and engaged tone....
    
    👨(Client)：Anxious, you say? That's good to hear. I'm looking forward to it as well.
    
    --- Overall Comment 
    
    【分數】：✅ 通過
    【評論】：客戶在本次對話中展現了良好的專業溝通能力。他能夠清晰、直接地回應對方的信息，並有效使用附和語來維持對話的參與感。
    【建議】：建議客戶在未來的對話中，根據情境需要，可以考慮適度運用間接表達和模糊語，以增加語氣的彈性與委婉度，尤其是在面對敏感話題或需要更細緻溝通的場合。持續保持積極的傾聽和回應，將有助於建立更良好的互動關係。
    
    --- Intent Achievement Evaluation
    
    🌍 Scenario：
    A professional setting where a person is informing another about a third party's eagerness to meet them, possibly before an introduction or a significant meeting. The man in the suit suggests a formal context.
    
    🎯 Intent：  
    Inform about someone's eagerness to meet.
    
    🎯 是否實踐意圖：
    
    【分數】：Yes
    【評論】：客戶成功地表達了對對方所提供信息的理解，並明確傳達了他對即將到來的會議的期待。
    【建議】：意圖已完全達成，表現良好，無需改進。
    
    --- Pragmatic Evaluation
    
    😊 日常寒暄 (Small Talk)
    
    【分數】：4分
    【評論】：客戶的應答簡潔專業，直接表達了對會面的期待，符合商務情境。
    【建議】：在此情境下，客戶的表現良好，無需特別改進。如果想在開場時增加一點點寒暄，可以簡短地說 "It's a pleasure to finally connect, I hear great things."
    
    🌀 間接表達 (Indirectness)  
    
    【分數】：0分
    【評論】：客戶的回應直接且清晰，沒有使用間接表達。在此情境下，直接性是可接受的，因此此項得分0分並非表示表現不佳，而是因為間接表達在此情境中並非必要且客戶未採用。
    【建議】：如果想讓語氣更委婉或在某些情況下顯得更為謹慎，可以使用間接句型，例如 "I appreciate you sharing that. It sounds like he's quite keen, and I share that sentiment." 或 "It's certainly encouraging to hear his eagerness; I'm equally enthusiastic."
    
    🤔 填充語 (Fillers)
    
    【分數】：0分
    【評論】對話中沒有使用語氣詞。在此情境下，不使用語氣詞保持了專業和清晰度。此項得分0分，因其在本次對話中屬於非必要項目且未被使用。
    【建議】：保持清晰流暢的表達是良好的習慣。若未來在需要思考或組織語言時，可適度使用一些無害的填充詞如 "Well," 或 "You know," 來避免冷場，但應避免過度使用。例如："Well, that's good to hear. I'm looking forward to it as well."
    
    🙆 同理回應 (Backchanneling)
    
    【分數】：5分
    【評論】：客戶有效地使用了附和語 "Anxious, you say?"，這表明他專注於對話並確認了對方提供的信息，有助於維持對話的流暢性與參與感。
    【建議】：繼續保持這種積極的傾聽和回應。在其他情況下，也可以使用 "I see what you mean," "Right," 或 "Exactly," 等來表示理解和附和。
    
    🤷 模糊語 (Hedging)  
    
    【分數】：2分
    【評論】：客戶的表達比較直接，沒有使用模糊語來軟化語氣或預留彈性。在這種專業且直接的語境下，雖然直接表達沒問題，但適度的模糊語可以使語氣更溫和或為未來討論留下空間。
    【建議】：在某些情境下，尤其是在討論尚未確定的事項或表達個人看法時，適當使用模糊語（hedging）可以讓語氣更委婉，避免過於武斷。例如，可以說 "I suppose that's good to hear" 或 "I'm certainly looking forward to it as well, assuming everything goes according to plan."
     
    🐉 文化慣用語 (Idioms)
    
    【分數】：0分
    【評論】：對話中沒有使用慣用語。在正式的商務場合，避免使用過多的慣用語有助於保持溝通的清晰度，尤其是在面對不同文化背景的對話者時。此項得分0分，因其在本次對話中屬於非必要項目且未被使用。
    【建議】：在正式場合，直接清晰的表達比慣用語更受青睞。如果希望增加語言的豐富性，可以在非正式場合適度使用，但務必確保對方能理解。
    ```

### 結算流程系統
#### 過關流程
- [ ] **成功宣告**: 恭喜過關訊息
- [ ] **表現結算**: 顯示詳細評分和星級
- [ ] **訂正選擇**:
  - 如果點擊「立即訂正」→ 執行訂正流程 → 完成後領取訂正後獎勵
  - 如果點擊「不訂正」→ 直接領獎
- [ ] **獎勵發放**: 領取通關獎勵

#### 失敗流程
- [ ] **失敗宣告**: 顯示失敗原因
- [ ] **安慰獎勵**: 領取時光卷一張

### AI訂正系統
#### 語法錯誤訂正
- [ ] **錯誤收集**: 系統收集該劇本對話中所有語法錯誤的句子
- [ ] **依序訂正**: 讓用戶依序對每個錯誤句子進行訂正
- [ ] **進度追蹤**: 分子=訂正次數，分母=語法錯誤句數+表達不順句數
- [ ] **語音練習**: 點擊練習按鈕後播放說話動畫，再次點擊送出錄音
- [ ] **結果反饋**: 檢查完成後回饋正確或錯誤

#### 表達不順訂正
- [ ] **流暢度評估**: 針對語音輸入的精準度、流利度、韻律進行評分
- [ ] **不順句收集**: 收集表達不順的句子進行訂正
- [ ] **語音重錄**: 使用語音方式重新錄製和練習
- [ ] **品質提升**: 透過重複練習提升表達流暢度

### 技術實現重點
- [ ] **快速響應**: 優先保證系統響應速度
- [ ] **準確評估**: 確保評分的一致性和準確性
- [ ] **獎勵整合**: 與遊戲化系統無縫整合

## 技術架構設計

### 核心技術需求 *(更新基於最新規格)*
- [ ] **AI 服務選擇**: 確定主要 AI 模型供應商
- [ ] **評分算法**: 建立三維度評分的具體邏輯
- [ ] **雙重檢測引擎**: 實現劇情任務和詞彙檢測的AI系統
- [ ] **即時反饋系統**: 任務完成和詞彙使用的立即通知機制
- [ ] **回覆輔助引擎**: 實現意圖分析和回應引導的AI模型
- [ ] **語音處理整合**: 語音轉文字和Speakace流暢度分析 *(新增)*
- [ ] **翻譯服務整合**: Google翻譯API的無縫整合
- [ ] **限時系統整合**: 300秒計時和結算觸發機制
- [ ] **訂正系統AI**: 語法錯誤和表達流暢度的訂正引擎 *(新增)*
- [ ] **成就系統整合**: 自動觸發獎勵機制
- [ ] **性能優化**: 確保響應時間 < 2秒

### 數據來源架構 *(新增基於最新規格)*
#### 預先準備的數據 (事前手動生成)
- [ ] **開場對話**: 包含場景描述的4-8句開場對話
- [ ] **任務定義**: 中文描述、完成範例、範例翻譯
- [ ] **詞彙數據**: 包含翻譯、圖片、題庫等完整詞彙資料
- [ ] **劇情大綱**: 完整的劇本背景和角色設定
- [ ] **獎勵設定**: 關卡經驗值獎勵、寶石獎勷、訂正後獎勵數目

#### 即時生成的數據 (關卡進行當下)
- [ ] **AI角色對話**: 基於劇情和用戶回應的AI動態生成
- [ ] **用戶對話**: 語音轉文字後存入資料庫
- [ ] **語法錯誤評估**: AI即時分析每句話的語法正確性
- [ ] **語意合適度評估**: AI評估對話的語境適應性
- [ ] **任務完成評估**: AI判斷劇情任務的完成狀態
- [ ] **流暢度分析**: Speakace平台分析精準度、流利度、韻律
- [ ] **回覆引導**: AI生成的三層輔助內容
- [ ] **對話翻譯**: Google翻譯提供的中翻英服務

#### 詞彙檢測系統
- [ ] **詞彙變化形式**: 資料庫儲存詞彙所有型態供模糊比對
  - 例如：eat, ate, eats, eaten
- [ ] **即時比對機制**: 每次對話結束後進行模糊比對
- [ ] **語境適配**: 確保詞彙使用的自然性和合理性

### 情境對話技術架構 *(新增)*
- [ ] **劇情解析引擎**: 理解和追蹤劇本任務的完成狀態
- [ ] **詞彙監控系統**: 即時檢測指定詞彙的使用情況
- [ ] **雙重成功判定**: 同時滿足劇情任務和詞彙要求的邏輯
- [ ] **時間管理核心**: 精確的300秒倒數計時系統

### 回覆輔助技術架構
- [ ] **意圖識別模型**: 基於context理解對方話語意圖
- [ ] **回應策略生成**: 提供多元化的回應思路建議
- [ ] **範例生成算法**: 根據使用者等級生成適當的回覆範例
- [ ] **情境適應性**: 確保建議符合對話場景和文化背景

### 基本品質控制
- [ ] **準確性測試**: 驗證評分結果的一致性
- [ ] **用戶體驗**: 確保獎勵系統運作順暢
- [ ] **資料隱私**: 基本的用戶資料保護

---

## 待完成任務

### 高優先級 *(更新基於最新規格)*
1. [ ] 建立每句話的即時分析系統（語法、任務、詞彙三重檢測）
2. [ ] 實現劇情任務完成狀態的AI檢測引擎
3. [ ] 建立指定詞彙模糊比對系統（支援詞彙變化形式）
4. [ ] 開發詞彙學習關卡系統（詞彙認識和詞彙熟悉）*(新增)*
5. [ ] 實現間隔複習算法（2^複習次數的遺忘曲線計算）*(新增)*
6. [ ] 開發即時成功通知機制（任務完成和詞彙使用立即反饋）
7. [ ] 實現三維度結算評分系統（語意60+、語法0錯、流暢60+）
8. [ ] 建立語音轉文字和中文檢測系統
9. [ ] 整合Speakace流暢度分析（精準度、流利度、韻律）
10. [ ] 開發回覆輔助的三層引導AI（意圖分析、思緒引導、範例生成）

### 中優先級
1. [ ] 建立雙重通關條件的邏輯驗證系統 *(新增)*
2. [ ] 優化時間壓力下的AI分析準確性 *(新增)*
3. [ ] 設計三類輔助工具的智能推薦機制 *(新增)*
4. [ ] 建立意圖分析模型的準確性測試
5. [ ] 優化回覆範例生成的品質控制
6. [ ] 建立評分一致性的測試機制
7. [ ] 優化與遊戲化系統的整合
8. [ ] 確保基本的資料隱私保護

### 新增功能優先級
1. [ ] 設計劇情任務的複雜度分級系統
2. [ ] 建立指定詞彙的學習進度追蹤
3. [ ] 優化限時環境下的用戶體驗
4. [ ] 設計回覆卡關的觸發時機和條件
5. [ ] 建立輔助功能使用的數據追蹤
6. [ ] 優化中翻英結果的情境適應性
7. [ ] 設計輔助功能的學習成效測量

---

**最後更新**: 2024年9月5日  
**負責人**: 待分配  
**審查週期**: 每兩週檢討一次