ai-output-validation

name	ai-output-validation
version	1
description	Ensures all AI-generated output fields have proper validation. Auto-activates on "AI 輸出", "LLM", "Gemini", "GPT", "truncate", "截斷" keywords. Lesson learned: 2026-01-08 Quick Feedback, Report, Deep Analyze truncation bugs.
allowed-tools	["Read","Grep","Bash"]
trigger_keywords	["AI 輸出","LLM","Gemini","GPT","truncate","截斷","max_tokens","字數限制","輸出驗證"]
auto_activate	true
priority	high

AI Output Validation - AI 輸出驗證

Purpose: 確保所有 AI 生成的欄位都有完整的驗證機制

Lesson Learned: 2026-01-08 三個截斷 Bug

• Quick Feedback: max_tokens=50 太小，回傳 1-3 字
• Report: 硬截斷 [:15] 切斷句子中間
• Deep Analyze: 缺少 display_text/quick_suggestion 驗證

---

核心原則

❌ 錯誤做法

# 硬截斷 - 會切斷句子
result["text"] = ai_response[:15]

# max_tokens 太小 - AI 會截斷
response = await llm.generate(max_tokens=50)  # 中文需要更多 tokens

# 沒有驗證 - 不知道是否完整
return {"message": ai_response}

✅ 正確做法

# 1. 定義限制（基於 prompt 或資料範圍）
MAX_CHARS = 15
MIN_CHARS = 7

# 2. 用 prompt 控制長度（讓 AI 自己處理）
prompt = "請用 15 字以內回應..."

# 3. 加大 max_tokens（避免 AI 被迫截斷）
response = await llm.generate(max_tokens=500)

# 4. 驗證並 fallback
if len(text) < MIN_CHARS:
    logger.warning(f"Too short: {text}")
    text = FALLBACK_MESSAGE

# 5. Log warning（不要硬截斷）
if len(text) > MAX_CHARS:
    logger.warning(f"Over limit: {len(text)} chars")

---

檢查清單

每個 AI 生成欄位必須檢查：

□ 1. 定義 min_chars - 太短時 fallback
     根據欄位用途決定最小字數
     例：鼓勵文 7 字、建議 5 字

□ 2. 定義 max_chars - 超過時 log warning
     根據 prompt 要求或 UI 限制
     例：同心圓 15 字、display 20 字

□ 3. max_tokens 足夠大 - 避免 AI 被迫截斷
     中文建議 500+（每字約 1-3 tokens）
     檢查 finish_reason != MAX_TOKENS

□ 4. 有 fallback 機制 - 太短或失敗時使用
     預設訊息列表
     random.choice(FALLBACK_MESSAGES)

□ 5. Log warning - 方便監控
     記錄實際長度
     記錄被 fallback 的情況

□ 6. 本地測試 3+ 次 - 確認 AI 實際輸出
     不要只看一次結果
     觀察變異性

---

驗證範本

# 標準 AI 輸出驗證模式
def validate_ai_output(
    text: str,
    min_chars: int,
    max_chars: int,
    fallback: str,
    field_name: str = "output"
) -> str:
    """驗證 AI 輸出，太短用 fallback，太長 log warning"""

    if len(text) < min_chars:
        logger.warning(
            f"{field_name} too short ({len(text)} chars): '{text}', "
            f"using fallback"
        )
        return fallback

    if len(text) > max_chars:
        logger.warning(
            f"{field_name} over {max_chars} chars: "
            f"{len(text)} chars - '{text[:30]}...'"
        )
        # 不要硬截斷！只 log warning

    return text

---

專案 AI 欄位參考表

API	欄位	Min	Max	來源
Quick Feedback	message	7	15	prompt 要求
Deep Analyze	display_text	4	20	prompt 要求
Deep Analyze	quick_suggestion	5	20	200句: 5-17 字
Report	encouragement	-	15	prompt 要求
Report	issue	-	-	無限制
Report	analyze	-	-	無限制
Report	suggestion	-	-	無限制

---

診斷指令

# 找出所有 AI 呼叫點
grep -rn "generate_text\|chat_completion\|_call_gemini" app/services/

# 找出所有 max_tokens 設定
grep -rn "max_tokens" app/services/

# 找出潛在的硬截斷
grep -rn "\[:.*\]" app/services/ | grep -v ".pyc"

# 檢查是否有 min/max 驗證
grep -rn "min_chars\|max_chars\|MIN_\|MAX_" app/services/

---

IMPORTANT

• 不要硬截斷 - 會切斷句子中間
• 用 prompt 控制長度 - 讓 AI 自己處理
• 加大 max_tokens - 避免 finish_reason=MAX_TOKENS
• 本地測試 3+ 次 - 觀察 AI 輸出變異
• Log warning - 方便監控異常

---

Version: 1.0 Created: 2026-01-08 Lesson From: Quick Feedback, Report, Deep Analyze truncation bugs