# AI 對話分析算法規格

## 概述
定義 Drama Ling 應用中 AI 對話分析系統的具體實現方案，整合語法評分與共用的口說評分、語用分析模組。

## 共用模組引用

本規格依賴以下共用模組，請參閱對應規格文件：

- **[口說評分系統](./speaking-evaluation-specs.md)** - 五維度口說表達評估
- **[語用分析系統](./pragmatic-analysis-specs.md)** - 六維語用標準建議系統

## 核心評分維度

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

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

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

- [ ] **口說評分**: 評估口說表現的自然度和流暢性
  - 詳細規格請參閱 → **[口說評分系統規格](./speaking-evaluation-specs.md)**
  
- [ ] **語用分析**: 評估內容理解和表達適切性(只建議，不評分) 
  - 詳細規格請參閱 → **[語用分析系統規格](./pragmatic-analysis-specs.md)**

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

## AI 對話分析功能

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

- [ ] **每句話即時分析**: 用戶說出的每句話都進行即時判斷
  - 語法正確性分析（即時顯示於對話功能欄）
  - 口說評分（即時顯示於對話功能欄）→ 使用 [口說評分系統](./speaking-evaluation-specs.md)
  - 任務完成狀態檢測
  - 指定詞彙使用檢測

- [ ] **即時成功通知**: 當用戶提及詞彙或完成任務時立即回饋

## 情境對話核心系統

### 情境對話通關檢測系統 *(核心功能)*
基於最新規格的結構化通關和評分機制：

#### 劇情任務識別系統

##### 意圖表達任務機制
每個劇本包含多個**情境意圖表達任務**，玩家需要在對話中適切地表達出指定意圖：

**三級完成標準**：
- 🔴 **未完成** (0%) - 完全沒有表達該意圖
- 🟡 **部分完成** (50%) - 有表達意圖但不夠清楚或完整
- 🟢 **完美完成** (100%) - 清楚、自然地表達了該意圖

**⭐ 任務星獲得條件**：當劇本中**所有意圖任務都達到完美完成**時獲得任務星

##### 技術實現
- [ ] **任務目標解析**: 
  - 解析每個劇本的具體意圖表達要求
  - 定義每個意圖的完成判定標準
  - 例如："預約餐廳" → 必須包含時間、人數、聯絡方式等要素

- [ ] **意圖完成度評估**:
  - AI即時分析用戶對話是否達成意圖目標
  - 按三級標準評估完成程度 (未完成/部分完成/完美完成)
  - 即時顯示任務進度給用戶參考

- [ ] **任務進度追蹤及即時反饋機制**:
  - 即時監控所有意圖任務的完成狀態
  - 當任務達成時觸發即時成功通知
  - 記錄每個任務的完成品質評分

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

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

### 回覆卡關輔助系統

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

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

#### 任務輔助功能 (免費)
- [ ] **劇情任務範例**:
  - 點擊任務提示按鈕後，先跳出警示，確認後即顯示一句範例
  - 說明「這樣說可以完成任務」
  - 當任務已完成時不顯示此按鈕
  - 完全免費，不消耗任何道具
  - 使用後，當前任務將不會獲得「⭐ 任務星」

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

### 中翻英輔助功能
- [ ] **Google翻譯整合**: 直接將使用者的中文以Google翻譯轉譯成英文 (訂閱用戶)
- [ ] **情境翻譯優化**: AI分析對話情境後調整翻譯結果 (進階用戶)
  - 根據角色身份調整語氣 (正式/非正式/友善/專業)
  - 考慮文化背景提供更自然的表達方式
  - 修正直譯問題，提供更符合英語習慣的說法
  - 例如：「不好意思」→ 商務場合「I apologize」vs 日常「Sorry」

### 語音處理系統
- [ ] **語音轉文字**: 以語音輸入為主，文字輸入為輔的對話方式
- [ ] **中文檢測**: 當用戶講中文或輸入中文時，角色表示聽不懂
- [ ] **語音品質檢測**: 如果聽不到聲音，顯示「抱歉，好像沒有聲音，請重新錄製」
- [ ] **口說表現分析**: 整合 [口說評分系統](./speaking-evaluation-specs.md) 進行分析

## 闖關學習系統整合 *(重構為四關線性闖關)*

本AI算法系統整合到 [線性闖關學習系統](./progressive-stage-system.md) 的四關架構中。

### 四關AI算法支援

#### 第1關：詞彙學習 (Vocabulary Learning)
基於詞彙認知的AI輔助學習機制：

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

#### 第2關：詞彙熟悉 (Vocabulary Mastery)
基於語境應用的AI練習系統：

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

#### 第2+關：口說練習特別關卡 (Speaking Practice Bonus)  
基於 [口說評分系統](./speaking-evaluation-specs.md) 的付費訓練關卡：

**關卡機制**：
- [ ] **付費模式**: 消耗5鑽石開始遊戲
- [ ] **特別機制**: 唯一可跳過的關卡，不影響主線闖關進度
- [ ] **關卡流程**: 逐一展示詞彙例句，用戶需朗讀每個例句
- [ ] **五維即時評分**: 發音/流暢度/韻律/完整度/準確度即時評估

**通關與獎勵**：
- [ ] **通關條件**: 所有詞彙例句平均分數達到70分以上
- [ ] **星級與獎勵機制**: 
  - 70-79分：1星，獲得1鑽石 + 10 XP (回收部分成本)
  - 80-89分：2星，獲得3鑽石 + 10 XP (略有虧損但有進步)
  - 90-100分：3星，獲得5鑽石 + 20 XP (獲利且大幅經驗值)
- [ ] **解鎖效果**: 通關後解鎖第3關

**AI學習支援**：
- [ ] **發音精進**: 針對特定詞彙的精確發音訓練
- [ ] **記憶強化**: 透過語音輸出深化詞彙印象
- [ ] **個性化反饋**: 每個詞彙提供詳細的發音改善建議

#### 第3關：情境對話 (Situational Dialogue)
基於AI對話分析的綜合應用關卡：

**關卡機制**：
- [ ] **免費模式**: 免費進入，失敗扣1命條
- [ ] **AI角色對話**: 與AI角色進行劇本情境對話
- [ ] **雙重任務系統**: 完成劇情意圖 + 使用前三關學習的5個指定詞彙

**通關與星級系統**：
- [ ] **基本通關**: 所有意圖任務≥50%完成 + 所有詞彙至少提及一次
- [ ] **三星評分標準**: 
  - ⭐ 任務星：所有意圖任務100%完成
  - ⭐ 語法星：語法錯誤率 = 0  
  - ⭐ 口說星：口說平均分數 > 80
- [ ] **解鎖效果**: 通關後解鎖下一劇本第1關

**AI分析支援**：
- [ ] **即時分析**: 語法、口說、任務完成三維度即時分析
- [ ] **語用建議**: 使用 [語用分析系統](./pragmatic-analysis-specs.md) 提供學習建議
- [ ] **回覆輔助**: 三層引導內容 (對方意圖分析/回應思緒引導/回覆範例生成)

### 共用詞彙設計標準
四關共用的詞彙組合設計：
- [ ] **詞彙組合**: 每個劇本包含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複習

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

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

## 情境對話關卡結算系統 *(專屬於情境對話訓練)*

### 情境對話關卡表現結算
**觸發時機**: 
 - 當劇本時間用完
 - 任務已完成後，使用者自行離開
 - 任務未完成，使用者自行離開不會觸發關卡表現結算

#### 情境對話過關判斷標準
- [ ] **基本通關條件**:
  - 所有意圖任務至少達到🟡部分完成(50%)
  - 所有指定詞彙至少被提及一次
  - **過關標準**: 完成基本對話要求，可獲得通關獎勵

- [ ] **星星獲得條件**:
  - 依據上述三星評分標準 (任務星/語法星/口說星)
  - 每顆星星獨立計算，玩家可獲得0-3顆星星

#### 情境對話表現評分系統

##### 星星獲得標準 ⭐
每達成一項條件即可獲得一顆星，最多3顆星：

- [ ] **⭐ 任務星** - **所有意圖任務完美完成**
  - 劇本中每個意圖表達任務都達到🟢完美完成(100%)
  - 玩家成功在對話中自然表達出所有指定意圖
  - **獲得條件**: 所有意圖任務完成度 = 100%

- [ ] **⭐ 語法星** - **語法錯誤率 = 0**
  - 用戶說的每句話經過語法判定都正確
  - 或者透過訂正功能將全部錯誤訂正完畢亦可
  - **獲得條件**: 完全無語法錯誤

- [ ] **⭐ 口說星** - **口說評分 > 80** (滿分100)  
  - 使用 [口說評分系統](./speaking-evaluation-specs.md) 評估
  - 計算用戶所有句子的口說平均分數
  - **獲得條件**: 口說平均分數超過80分

##### 學習建議系統 💡
不影響星星獲得，僅提供改善建議：

- [ ] **💡 語用建議** - **對話語用分析**
  - 使用 [語用分析系統](./pragmatic-analysis-specs.md) 分析
  - 提供六維語用標準的具體改善建議
  - **用途**: 幫助用戶理解更自然的溝通方式

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

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

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

#### 口說錯誤訂正
- [ ] **口說評估**: 使用 [口說評分系統](./speaking-evaluation-specs.md) 進行評估
- [ ] **口說錯誤收集**: 收集口說錯誤的句子進行訂正
- [ ] **語音重錄**: 使用語音方式重新錄製和練習
- [ ] **品質提升**: 透過重複練習提升口說表現

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

## 技術架構設計

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

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

#### 即時生成的數據 (關卡進行當下)
- [ ] **AI角色對話**: 基於劇情和用戶回應的AI動態生成
- [ ] **用戶對話**: 語音轉文字後存入資料庫
- [ ] **語法錯誤評估**: AI即時分析每句話的語法正確性
- [ ] **語意合適度評估**: AI評估對話的語境適應性
- [ ] **任務完成評估**: AI判斷劇情任務的完成狀態
- [ ] **口說分析**: 使用 [口說評分系統](./speaking-evaluation-specs.md) 分析
- [ ] **語用建議**: 使用 [語用分析系統](./pragmatic-analysis-specs.md) 生成建議
- [ ] **回覆引導**: AI生成的三層輔助內容
- [ ] **對話翻譯**: Google翻譯提供的中翻英服務

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

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

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

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

---

## 待完成任務

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

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

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

---

**最後更新**: 2025-09-11 - 重構：拆分共用模組並建立引用機制  
**版本**: 2.0 - 模組化版本：整合口說評分和語用分析共用模組  
**維護者**: Drama Ling 開發團隊