dramaling-app/docs/02_design/ai-algorithm-specs.md

# AI 對話分析算法規格

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

## 核心評分維度

基於 UI_LevelResult_ScoreSummary.png 的實際設計，採用簡化的三維評分顯示：

### 簡化評分系統
**目標**: 提供清楚的學習反饋，觸發對應成就獎勵

#### 三項評分指標
- [ ] **語法評分**: 評估語法正確性
  - 達到優秀標準時觸發「完美語法」成就
  - 獎勵: +10 鑽石 + 10 閃電能量

- [ ] **語意評分**: 評估內容理解和表達適切性  
  - 作為整體表現參考
  - 不單獨觸發特定成就

- [ ] **流暢度評分**: 評估表達的自然度和流暢性
  - 達到優秀標準時觸發「表達流利」成就
  - 獎勵: +10 鑽石 + 10 閃電能量

#### 技術實現方案
- [ ] **AI 模型選擇**: 待決定 (GPT-4/Claude/自建模型)
- [ ] **評分閾值設定**: 定義「優秀」標準的具體分數
- [ ] **即時分析**: 目標響應時間 < 2秒
- [ ] **成就觸發機制**: 自動檢測並發放對應獎勵

## AI 對話分析功能

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

- [ ] **每句話即時分析**: 用戶說出的每句話都進行即時判斷
  - 語法正確性分析（即時顯示於對話功能欄）
  - 任務完成狀態檢測
  - 指定詞彙使用檢測
- [ ] **即時成功通知**: 當用戶提及詞彙或完成任務時立即回饋
- [ ] **三維度結算評分**: 對話結束後的綜合評分
  - 對話語意合適分數（滿分100，>60為合格）
  - 語法錯誤率（必須=0，所有句子都正確或訂正後正確）
  - 表達流暢平均分數（滿分100，>60為合格）

## 情境對話核心系統

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### 詞彙內容設計標準
基於劇本的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複習

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

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

## 限時對話系統 *(新增功能)*

### 300秒倒數計時機制
基於最新規格的時間管理系統：

#### 時間控制引擎
- [ ] **精準計時系統**:
  - 300秒（5分鐘）的精確倒數計時
  - 支援暫停和恢復功能（特殊情況下）
  - 時間剩餘的視覺化顯示

- [ ] **時間壓力分析**:
  - 分析時間壓力對用戶表現的影響
  - 記錄不同時間段的對話品質變化
  - 優化時間分配的學習建議

- [ ] **結算觸發機制**:
  - 時間歸零自動觸發結算
  - 支援用戶主動點擊「結算表現」
  - 確保數據完整保存和分析

#### 時間效率優化
- [ ] **進度加權評分**:
  - 基於完成時間給予額外評分
  - 鼓勵高效但準確的對話完成
  - 平衡速度與品質的評分機制

- [ ] **時間管理指導**:
  - 提供時間分配的策略建議
  - 分析用戶的時間使用模式
  - 協助提升對話效率

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

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

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

#### 表現評分系統
- [ ] **評分標準** (每合格一項獲得一顆星):
  1. **對話語意合適分數 > 60** (滿分100)
     - 根據上下文一致性進行評分
     - 語境適應性評估
     - 意圖匹配度分析
  2. **語法錯誤率 = 0**
     - 用戶說的每句話經過語法判定都正確
     - 或者訂正後都正確亦可
  3. **表達流暢平均分數 > 60** (滿分100)
     - 用戶說的每句話都會有流暢度分數
     - 所有分數平均即為表達流暢平均分數

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

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

### 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日  
**負責人**: 待分配  
**審查週期**: 每兩週檢討一次