feat: Refactor assistant system with auto-matching and manual selection

- Refactor agents.yaml with 6 real OpenAI assistants configuration
- Change language code from zh-Hant to zh-TW throughout codebase
- Implement smart assistant matching system with scoring algorithm
- Add frontend assistant selector dropdown next to grade button
- Fix all assistant IDs to match actual OpenAI assistants
- Add check_assistants.py utility to verify assistant availability
- Support Chinese/English aliases for age groups, categories, and modes
- Filter to show only strictly matching assistants in dropdown

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

API.md

@@ -36,7 +36,7 @@ Authorization: Bearer YOUR_API_TOKEN
     {
       "key": "zh_full_edit",
       "name": "中文全文批改",
-      "language": "zh-Hant",
+      "language": "zh-TW",
       "ui": {
         "badge": "ZH",
         "color": "#1565C0"

agents.yaml

@@ -1,83 +1,204 @@
+# ============================================================
+# 📖 使用說明 - 如何新增批改機器人
+# ============================================================
+#
+# 1️⃣ 複製下面的格式新增機器人：
+#
+#    - name: "你的機器人名稱"
+#      assistant_id: "asst_xxxxxxxxxx"        # 從 OpenAI 取得的 Assistant ID
+#      language: "zh-TW"                       # zh-TW=中文, en=英文
+#      age_groups: ["國小"]                    # 可用中文或英文 key
+#      categories: ["記敘文"]                  # 可多選：["記敘文", "議論文"]
+#      grading_modes: ["全文批改"]             # 支援的批改模式
+#      temperature: 0.3                        # 0.1-1.0，越小越穩定
+#      enabled: true                           # true=啟用, false=停用
+#
+# 2️⃣ 萬用字元（處理所有選項）：
+#    age_groups: ["*"]  ← 表示所有年齡層
+#
+# 3️⃣ 多選（處理多個選項）：
+#    age_groups: ["國小", "國中"]  ← 處理國小和國中
+#    或混用中英文：["elementary", "國中"]  ← 也可以！
+#
+# 4️⃣ 修改完存檔，重啟服務即生效！
+#
+# ============================================================
+
 version: 2
-defaults:
-  model: "gpt-4"
-  temperature: 0.2
-  output_format: "markdown"
-  max_tokens: 2000
-
-agents:
-  zh_full_edit:
-    name: "小學作文批改"
-    assistant_id: "asst_MEzXFAvPbkbn85Ca1gQ7vKa9"
-    language: "zh-Hant"
+
+# ============================================================
+# 前端下拉選單選項定義
+# ============================================================
+options:
+  age_groups:
+    - key: "elementary"
+      aliases: ["國小", "小學"]
+      label: "國小"
+
+    - key: "junior_high"
+      aliases: ["國中", "初中"]
+      label: "國中"
+
+    - key: "senior_high"
+      aliases: ["高中"]
+      label: "高中"
+
+    - key: "university"
+      aliases: ["大學", "大學生"]
+      label: "大學"
+
+    - key: "working"
+      aliases: ["上班族", "職場"]
+      label: "上班族"
+
+    - key: "retired"
+      aliases: ["退休人士", "退休"]
+      label: "退休人士"
+
+  categories:
+    - key: "literature"
+      aliases: ["文學小說", "小說"]
+      label: "文學小說"
+
+    - key: "poetry"
+      aliases: ["詩集", "詩詞"]
+      label: "詩集"
+
+    - key: "psychology"
+      aliases: ["心理勵志", "勵志"]
+      label: "心理勵志"
+
+    - key: "art_design"
+      aliases: ["藝術設計", "設計"]
+      label: "藝術設計"
+
+    - key: "travel"
+      aliases: ["觀光旅遊", "旅遊"]
+      label: "觀光旅遊"
+
+    - key: "food"
+      aliases: ["美食饗宴", "美食"]
+      label: "美食饗宴"
+
+    - key: "marketing"
+      aliases: ["行銷文案", "文案"]
+      label: "行銷文案"
+
+    - key: "business"
+      aliases: ["商業理財", "理財"]
+      label: "商業理財"
+
+    - key: "humanities"
+      aliases: ["人文史地", "歷史"]
+      label: "人文史地"
+
+    - key: "science"
+      aliases: ["自然科普", "科普"]
+      label: "自然科普"
+
+    - key: "comics"
+      aliases: ["漫畫圖文", "漫畫"]
+      label: "漫畫圖文"
+
+    - key: "education"
+      aliases: ["教育學習", "教育"]
+      label: "教育學習"
+
+    - key: "lifestyle"
+      aliases: ["生活休閒", "休閒"]
+      label: "生活休閒"
+
+    - key: "creative"
+      aliases: ["創意想像", "創意"]
+      label: "創意想像"
+
+    - key: "technology"
+      aliases: ["資訊科技", "科技"]
+      label: "資訊科技"
+
+    - key: "social"
+      aliases: ["社會議題", "社會"]
+      label: "社會議題"
+
+  grading_modes:
+    - key: "full_edit"
+      aliases: ["全文批改", "完整批改"]
+      label: "全文批改"
+
+    - key: "structure_only"
+      aliases: ["結構建議", "架構建議"]
+      label: "結構建議"
+
+    - key: "grammar_only"
+      aliases: ["文法修正", "語法修正"]
+      label: "文法修正"
+
+# ============================================================
+# 批改機器人配置
+# ============================================================
+assistants:
+  # ============================================================
+  # 國小專用機器人
+  # ============================================================
+  - name: "小學作文"
+    assistant_id: "asst_uEstIWft6VV91tm9gLjpjr7n"
+    language: "zh-TW"
+    age_groups: ["國小"]
+    categories: ["*"]
+    grading_modes: ["全文批改"]
+    temperature: 0.3
+    enabled: true
+
+  # ============================================================
+  # 全文批改機器人
+  # ============================================================
+  - name: "作文練習整體回饋"
+    assistant_id: "asst_o2ikYoJqDKQHny24FjS7iyzN"
+    language: "zh-TW"
+    age_groups: ["國中", "高中", "大學", "上班族", "退休人士"]
+    categories: ["*"]
+    grading_modes: ["全文批改"]
+    temperature: 0.3
+    enabled: true
+
+  # ============================================================
+  # 結構建議機器人
+  # ============================================================
+  - name: "段落批改機器人"
+    assistant_id: "asst_7Z3PCVKqmXfruwOxnOprAMH2"
+    language: "zh-TW"
+    age_groups: ["*"]
+    categories: ["*"]
+    grading_modes: ["結構建議"]
+    temperature: 0.25
+    enabled: true
+
+  - name: "段落擴寫"
+    assistant_id: "asst_LrV6pEWdZXljI9d0VfyHKn4j"
+    language: "zh-TW"
+    age_groups: ["*"]
+    categories: ["*"]
+    grading_modes: ["結構建議"]
+    temperature: 0.3
+    enabled: false  # 先停用，避免跟段落批改衝突
+
+  # ============================================================
+  # 文法修正機器人
+  # ============================================================
+  - name: "錯別字機器人"
+    assistant_id: "asst_5PNgAr7DQl8jAVFxIUvrhG5Y"
+    language: "zh-TW"
+    age_groups: ["*"]
+    categories: ["*"]
+    grading_modes: ["文法修正"]
     temperature: 0.2
-    rubric:
-      overall_weight: 100
-      criteria:
-        - key: "structure"
-          label: "結構與段落"
-          weight: 25
-        - key: "coherence"
-          label: "論證與連貫"
-          weight: 25
-        - key: "clarity"
-          label: "表達清晰度"
-          weight: 25
-        - key: "mechanics"
-          label: "字詞/標點/語法"
-          weight: 25
-    response_contract:
-      fields:
-        - key: "summary"
-          type: "text"
-          required: true
-        - key: "inline_edits"
-          type: "richtext"
-          required: true
-        - key: "scores"
-          type: "object"
-          required: false
-        - key: "suggestions"
-          type: "list"
-          required: false
-    ui:
-      badge: "ZH"
-      color: "#1565C0"
-
-  en_edit:
-    name: "英文批改"
-    assistant_id: "asst_xxxxxxxxx_en"  # 請替換為實際的 Assistant ID
-    language: "en"
-    temperature: 0.1
-    rubric:
-      overall_weight: 100
-      criteria:
-        - key: "organization"
-          label: "Organization"
-          weight: 20
-        - key: "argumentation"
-          label: "Argumentation"
-          weight: 30
-        - key: "clarity"
-          label: "Clarity & Style"
-          weight: 25
-        - key: "mechanics"
-          label: "Grammar & Spelling"
-          weight: 25
-    response_contract:
-      fields:
-        - key: "summary"
-          type: "text"
-          required: true
-        - key: "inline_edits"
-          type: "richtext"
-          required: true
-        - key: "overall_score"
-          type: "number"
-          required: false
-        - key: "criteria_scores"
-          type: "object"
-          required: false
-    ui:
-      badge: "EN"
-      color: "#2E7D32"
+    enabled: true
+
+  - name: "句型改寫"
+    assistant_id: "asst_byI8gkZPMZZGczX1UyDpV6vh"
+    language: "zh-TW"
+    age_groups: ["*"]
+    categories: ["*"]
+    grading_modes: ["文法修正"]
+    temperature: 0.25
+    enabled: false  # 先停用，避免跟錯別字機器人衝突

backend/agents.yaml

@@ -1,83 +0,0 @@
-version: 2
-defaults:
-  model: "gpt-4"
-  temperature: 0.2
-  output_format: "markdown"
-  max_tokens: 2000
-
-agents:
-  zh_full_edit:
-    name: "小學作文批改"
-    assistant_id: "asst_MEzXFAvPbkbn85Ca1gQ7vKa9"
-    language: "zh-Hant"
-    temperature: 0.2
-    rubric:
-      overall_weight: 100
-      criteria:
-        - key: "structure"
-          label: "結構與段落"
-          weight: 25
-        - key: "coherence"
-          label: "論證與連貫"
-          weight: 25
-        - key: "clarity"
-          label: "表達清晰度"
-          weight: 25
-        - key: "mechanics"
-          label: "字詞/標點/語法"
-          weight: 25
-    response_contract:
-      fields:
-        - key: "summary"
-          type: "text"
-          required: true
-        - key: "inline_edits"
-          type: "richtext"
-          required: true
-        - key: "scores"
-          type: "object"
-          required: false
-        - key: "suggestions"
-          type: "list"
-          required: false
-    ui:
-      badge: "ZH"
-      color: "#1565C0"
-
-  en_edit:
-    name: "英文批改"
-    assistant_id: "asst_xxxxxxxxx_en"  # 請替換為實際的 Assistant ID
-    language: "en"
-    temperature: 0.1
-    rubric:
-      overall_weight: 100
-      criteria:
-        - key: "organization"
-          label: "Organization"
-          weight: 20
-        - key: "argumentation"
-          label: "Argumentation"
-          weight: 30
-        - key: "clarity"
-          label: "Clarity & Style"
-          weight: 25
-        - key: "mechanics"
-          label: "Grammar & Spelling"
-          weight: 25
-    response_contract:
-      fields:
-        - key: "summary"
-          type: "text"
-          required: true
-        - key: "inline_edits"
-          type: "richtext"
-          required: true
-        - key: "overall_score"
-          type: "number"
-          required: false
-        - key: "criteria_scores"
-          type: "object"
-          required: false
-    ui:
-      badge: "EN"
-      color: "#2E7D32"

backend/app/config/agents.py

@@ -2,103 +2,245 @@ import yaml
 from typing import Dict, Any, List, Optional
 from pathlib import Path
 from pydantic import BaseModel
+import logging
 
-class Criterion(BaseModel):
-    key: str
-    label: str
-    weight: int
+logger = logging.getLogger(__name__)
 
-class Rubric(BaseModel):
-    overall_weight: int
-    criteria: List[Criterion]
+# ============================================================
+# Pydantic Models
+# ============================================================
 
-class ResponseField(BaseModel):
+class Option(BaseModel):
     key: str
-    type: str
-    required: bool
-
-class ResponseContract(BaseModel):
-    fields: List[ResponseField]
-
-class UIConfig(BaseModel):
-    badge: str
-    color: str
+    label: str
+    aliases: Optional[List[str]] = []
 
 class Agent(BaseModel):
+    """Represents a grading assistant"""
     name: str
     assistant_id: str
     language: str
-    temperature: Optional[float] = None
-    rubric: Optional[Rubric] = None
-    response_contract: Optional[ResponseContract] = None
-    ui: Optional[UIConfig] = None
+    age_groups: List[str]  # Can include aliases or "*"
+    categories: List[str]  # Can include aliases or "*"
+    grading_modes: List[str]  # Can include aliases or "*"
+    temperature: Optional[float] = 0.2
+    enabled: Optional[bool] = True
+
+# ============================================================
+# Main Configuration Class
+# ============================================================
 
 class AgentsConfig:
-    def __init__(self, config_path: str = "agents.yaml"):
+    def __init__(self, config_path: str = "../agents.yaml"):
         self.config_path = Path(config_path)
-        self.agents: Dict[str, Agent] = {}
-        self.defaults: Dict[str, Any] = {}
-        self.version: int = 1
+        self.assistants: List[Agent] = []
+        self.options: Dict[str, List[Option]] = {}
+        self.version: int = 2
+
+        # Alias mapping: {option_type: {alias: key}}
+        self._alias_map: Dict[str, Dict[str, str]] = {}
+
         self._load_config()
-    
+
     def _load_config(self):
         """Load and parse agents.yaml configuration"""
         if not self.config_path.exists():
             raise FileNotFoundError(f"Configuration file {self.config_path} not found")
-        
+
         with open(self.config_path, 'r', encoding='utf-8') as f:
             config = yaml.safe_load(f)
-        
-        self.version = config.get('version', 1)
-        self.defaults = config.get('defaults', {})
-        
-        # Parse agents
-        for agent_key, agent_data in config.get('agents', {}).items():
-            # Merge with defaults
-            merged_data = {**self.defaults, **agent_data}
-            
-            # Parse rubric if exists
-            if 'rubric' in merged_data:
-                rubric_data = merged_data['rubric']
-                merged_data['rubric'] = Rubric(
-                    overall_weight=rubric_data['overall_weight'],
-                    criteria=[Criterion(**c) for c in rubric_data.get('criteria', [])]
-                )
-            
-            # Parse response_contract if exists
-            if 'response_contract' in merged_data:
-                contract_data = merged_data['response_contract']
-                merged_data['response_contract'] = ResponseContract(
-                    fields=[ResponseField(**f) for f in contract_data.get('fields', [])]
-                )
-            
-            # Parse UI config if exists
-            if 'ui' in merged_data:
-                merged_data['ui'] = UIConfig(**merged_data['ui'])
-            
-            self.agents[agent_key] = Agent(**merged_data)
-    
-    def get_agent(self, agent_key: str) -> Optional[Agent]:
-        """Get agent by key"""
-        return self.agents.get(agent_key)
-    
-    def list_agents(self) -> Dict[str, Dict[str, Any]]:
-        """List all available agents"""
-        result = {}
-        for key, agent in self.agents.items():
-            result[key] = {
-                "name": agent.name,
-                "language": agent.language,
-                "ui": agent.ui.model_dump() if agent.ui else None,
-                "rubric": agent.rubric.model_dump() if agent.rubric else None
+
+        self.version = config.get('version', 2)
+
+        # Parse options and build alias map
+        self._parse_options(config.get('options', {}))
+
+        # Parse assistants
+        self._parse_assistants(config.get('assistants', []))
+
+        logger.info(f"Loaded {len(self.assistants)} assistants from config")
+
+    def _parse_options(self, options_data: Dict[str, List[Dict]]):
+        """Parse options and build alias mapping"""
+        for option_type, options_list in options_data.items():
+            self.options[option_type] = []
+            self._alias_map[option_type] = {}
+
+            for opt_data in options_list:
+                option = Option(**opt_data)
+                self.options[option_type].append(option)
+
+                # Map key to itself
+                self._alias_map[option_type][option.key] = option.key
+
+                # Map all aliases to the key
+                for alias in option.aliases:
+                    self._alias_map[option_type][alias] = option.key
+
+        logger.info(f"Built alias maps: {list(self._alias_map.keys())}")
+
+    def _parse_assistants(self, assistants_data: List[Dict]):
+        """Parse assistants configuration"""
+        for assistant_data in assistants_data:
+            if not assistant_data.get('enabled', True):
+                logger.info(f"Skipping disabled assistant: {assistant_data.get('name')}")
+                continue
+
+            # Normalize age_groups, categories, grading_modes to use standard keys
+            age_groups_normalized = self._normalize_list('age_groups', assistant_data.get('age_groups', ['*']))
+            categories_normalized = self._normalize_list('categories', assistant_data.get('categories', ['*']))
+            modes_normalized = self._normalize_list('grading_modes', assistant_data.get('grading_modes', ['*']))
+
+            assistant = Agent(
+                name=assistant_data['name'],
+                assistant_id=assistant_data['assistant_id'],
+                language=assistant_data.get('language', 'zh-TW'),
+                age_groups=age_groups_normalized,
+                categories=categories_normalized,
+                grading_modes=modes_normalized,
+                temperature=assistant_data.get('temperature', 0.2),
+                enabled=assistant_data.get('enabled', True)
+            )
+            self.assistants.append(assistant)
+
+            logger.debug(f"Loaded assistant: {assistant.name} | age_groups={assistant.age_groups} | categories={assistant.categories}")
+
+    def _normalize(self, option_type: str, value: str) -> Optional[str]:
+        """
+        Normalize a value using alias map
+        Examples:
+            normalize('age_groups', '國小') -> 'elementary'
+            normalize('age_groups', 'elementary') -> 'elementary'
+            normalize('age_groups', '*') -> '*'
+        """
+        if value == '*':
+            return '*'
+
+        return self._alias_map.get(option_type, {}).get(value, value)
+
+    def _normalize_list(self, option_type: str, values: List[str]) -> List[str]:
+        """Normalize a list of values"""
+        return [self._normalize(option_type, v) for v in values]
+
+    def find_assistant(
+        self,
+        language: str = "zh-TW",
+        age_group: Optional[str] = None,
+        category: Optional[str] = None,
+        grading_mode: Optional[str] = None
+    ) -> Optional[Agent]:
+        """
+        Find matching assistant with fallback logic
+
+        Priority scoring:
+        - Exact match (100 points per field)
+        - Wildcard match (10 points per field)
+        - Language must match (or returns -1)
+
+        Examples:
+            find_assistant(language='zh-TW', age_group='國小', category='記敘文')
+            find_assistant(language='zh-TW', age_group='elementary', category='narrative')
+        """
+        # Normalize input using aliases
+        age_group_key = self._normalize('age_groups', age_group) if age_group else None
+        category_key = self._normalize('categories', category) if category else None
+        mode_key = self._normalize('grading_modes', grading_mode) if grading_mode else None
+
+        logger.info(f"Finding assistant: lang={language}, age={age_group}->{age_group_key}, cat={category}->{category_key}, mode={grading_mode}->{mode_key}")
+
+        def match_score(assistant: Agent) -> int:
+            """Calculate match score for an assistant"""
+            score = 0
+
+            # Language must match
+            if assistant.language != language:
+                return -1
+
+            # Age group matching
+            if age_group_key:
+                if age_group_key in assistant.age_groups:
+                    score += 100
+                elif '*' in assistant.age_groups:
+                    score += 10
+                else:
+                    return -1  # No match
+            elif '*' in assistant.age_groups:
+                score += 10
+
+            # Category matching
+            if category_key:
+                if category_key in assistant.categories:
+                    score += 50
+                elif '*' in assistant.categories:
+                    score += 5
+                else:
+                    return -1
+            elif '*' in assistant.categories:
+                score += 5
+
+            # Grading mode matching
+            if mode_key:
+                if mode_key in assistant.grading_modes:
+                    score += 25
+                elif '*' in assistant.grading_modes:
+                    score += 2
+                else:
+                    return -1
+            elif '*' in assistant.grading_modes:
+                score += 2
+
+            return score
+
+        # Find all valid matches
+        matches = []
+        for assistant in self.assistants:
+            score = match_score(assistant)
+            if score >= 0:
+                matches.append((score, assistant))
+                logger.debug(f"  Match: {assistant.name} (score={score})")
+
+        if not matches:
+            logger.warning(f"No assistant found for: {language}/{age_group_key}/{category_key}/{mode_key}")
+            return None
+
+        # Sort by score (highest first) and return best match
+        matches.sort(reverse=True, key=lambda x: x[0])
+        best_match = matches[0][1]
+
+        logger.info(f"✓ Selected: {best_match.name} (score={matches[0][0]})")
+        return best_match
+
+    def get_options(self) -> Dict[str, List[Dict[str, Any]]]:
+        """Get options for frontend dropdowns"""
+        return {
+            'age_groups': [{'key': opt.key, 'label': opt.label} for opt in self.options.get('age_groups', [])],
+            'categories': [{'key': opt.key, 'label': opt.label} for opt in self.options.get('categories', [])],
+            'grading_modes': [{'key': opt.key, 'label': opt.label} for opt in self.options.get('grading_modes', [])]
+        }
+
+    def list_all_assistants(self) -> List[Dict[str, Any]]:
+        """List all assistants (for debugging)"""
+        return [
+            {
+                'name': a.name,
+                'language': a.language,
+                'age_groups': a.age_groups,
+                'categories': a.categories,
+                'grading_modes': a.grading_modes,
+                'assistant_id': a.assistant_id[:20] + '...' if len(a.assistant_id) > 20 else a.assistant_id,
+                'enabled': a.enabled
             }
-        return result
+            for a in self.assistants
+        ]
+
+# ============================================================
+# Singleton Instance
+# ============================================================
 
-# Global instance
-agents_config = None
+_config = None
 
 def get_agents_config() -> AgentsConfig:
-    global agents_config
-    if agents_config is None:
-        agents_config = AgentsConfig()
-    return agents_config
+    global _config
+    if _config is None:
+        _config = AgentsConfig()
+    return _config

backend/app/models/grading.py

@@ -3,13 +3,14 @@ from typing import Optional, Dict, List, Any
 from datetime import datetime
 
 class GradeRequest(BaseModel):
-    agent_key: str = Field(..., description="Agent identifier")
     text: str = Field(..., description="Text to be graded")
-    category: Optional[str] = Field(None, description="Article category")
-    age_group: Optional[str] = Field(None, description="Age group of author")
-    language: Optional[str] = Field("zh", description="Output language (zh/en)")
+    language: str = Field("zh-TW", description="Language (zh-TW/en)")
+    age_group: Optional[str] = Field(None, description="Age group (可用中文或英文 key)")
+    category: Optional[str] = Field(None, description="Article category (可用中文或英文 key)")
+    grading_mode: Optional[str] = Field(None, description="Grading mode (可用中文或英文 key)")
+    assistant_id: Optional[str] = Field(None, description="Specific assistant ID to use (optional, overrides auto-matching)")
     options: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Additional options")
-    
+
     @validator('text')
     def validate_text(cls, v):
         if not v or not v.strip():
@@ -45,16 +46,11 @@ class JobStatus(BaseModel):
     message: Optional[str] = None
     result: Optional[GradeResult] = None
 
-class AgentInfo(BaseModel):
-    key: str
-    name: str
-    language: str
-    ui: Optional[Dict[str, Any]] = None
-    rubric: Optional[Dict[str, Any]] = None
-
-class AgentsListResponse(BaseModel):
-    version: int
-    agents: List[AgentInfo]
+class OptionsResponse(BaseModel):
+    """Response model for /api/options endpoint"""
+    age_groups: List[Dict[str, str]]
+    categories: List[Dict[str, str]]
+    grading_modes: List[Dict[str, str]]
 
 class PasswordVerifyRequest(BaseModel):
     password: str = Field(..., description="Password to verify")

backend/app/prompts/grading_prompt.py

@@ -142,10 +142,13 @@ Important Reminders:
 
 def get_grading_prompt(text: str, category: str = "", age_group: str = "", language: str = "zh") -> str:
     """Get formatted grading prompt"""
-    category_text = category if category else "一般文章" if language == "zh" else "General Article"
-    
+    # Support both "zh" and "zh-TW" for Chinese
+    is_chinese = language.startswith("zh")
+
+    category_text = category if category else "一般文章" if is_chinese else "General Article"
+
     # Build age group text
-    if language == "zh":
+    if is_chinese:
         age_text = ""
         if age_group:
             age_text = f"作者年齡層：{age_group}\n請以「{age_group}」的程度標準來評分\n"

backend/app/routers/grading.py

@@ -1,11 +1,10 @@
-from fastapi import APIRouter, HTTPException, Depends
+from fastapi import APIRouter, HTTPException
 from typing import Dict, Any
 import logging
 from app.models.grading import (
-    GradeRequest, 
-    GradeResponse, 
-    AgentsListResponse,
-    AgentInfo,
+    GradeRequest,
+    GradeResponse,
+    OptionsResponse,
     PasswordVerifyRequest,
     PasswordVerifyResponse
 )
@@ -16,74 +15,258 @@ from app.config.settings import get_settings
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["grading"])
 
-@router.get("/agents", response_model=AgentsListResponse)
-async def get_agents():
-    """Get list of available agents"""
+# ============================================================
+# Options API - 給前端取得下拉選單選項
+# ============================================================
+
+@router.get("/options", response_model=OptionsResponse)
+async def get_options():
+    """
+    Get grading options for frontend dropdowns
+
+    Returns:
+        {
+            "age_groups": [{"key": "elementary", "label": "國小 (6-12歲)"}, ...],
+            "categories": [{"key": "narrative", "label": "記敘文"}, ...],
+            "grading_modes": [{"key": "full_edit", "label": "全文批改"}, ...]
+        }
+    """
     try:
         config = get_agents_config()
-        agents_list = []
-        
-        for key, agent_data in config.list_agents().items():
-            agents_list.append(AgentInfo(
-                key=key,
-                name=agent_data["name"],
-                language=agent_data["language"],
-                ui=agent_data.get("ui"),
-                rubric=agent_data.get("rubric")
-            ))
-        
-        return AgentsListResponse(
-            version=config.version,
-            agents=agents_list
-        )
+        return OptionsResponse(**config.get_options())
+    except Exception as e:
+        logger.error(f"Error fetching options: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+# ============================================================
+# Assistants API - 除錯用，列出所有配置的助手
+# ============================================================
+
+@router.get("/assistants")
+async def list_assistants():
+    """
+    List all configured assistants (for debugging)
+
+    Returns list of assistants with their configuration
+    """
+    try:
+        config = get_agents_config()
+        return {
+            "version": config.version,
+            "count": len(config.assistants),
+            "assistants": config.list_all_assistants()
+        }
+    except Exception as e:
+        logger.error(f"Error listing assistants: {str(e)}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(e))
+
+# ============================================================
+# Find Matched Assistants API - 根據參數找出匹配的機器人
+# ============================================================
+
+@router.get("/find-assistants")
+async def find_matched_assistants(
+    language: str = "zh-TW",
+    age_group: str = None,
+    category: str = None,
+    grading_mode: str = None
+):
+    """
+    Find all assistants that match the given criteria
+
+    Query params:
+        language: Language code (zh-TW, en)
+        age_group: Age group (可用中文或英文 key)
+        category: Article category (可用中文或英文 key)
+        grading_mode: Grading mode (可用中文或英文 key)
+
+    Returns:
+        List of matched assistants with their scores
+    """
+    try:
+        config = get_agents_config()
+
+        # Normalize inputs
+        age_group_key = config._normalize('age_groups', age_group) if age_group else None
+        category_key = config._normalize('categories', category) if category else None
+        mode_key = config._normalize('grading_modes', grading_mode) if grading_mode else None
+
+        # Get all assistants with scores (including non-matching ones)
+        all_assistants = []
+        for assistant in config.assistants:
+            # Calculate match score
+            score = 0
+            is_match = True
+
+            # Language must match
+            if assistant.language != language:
+                is_match = False
+                score = -1000  # Put non-matching language at bottom
+            else:
+                # Age group matching
+                if age_group_key:
+                    if age_group_key in assistant.age_groups:
+                        score += 100
+                    elif '*' in assistant.age_groups:
+                        score += 10
+                    else:
+                        is_match = False
+                        score = -100  # Not matching, put at bottom
+                elif '*' in assistant.age_groups:
+                    score += 10
+
+                # Category matching
+                if is_match:  # Only check if still matching
+                    if category_key:
+                        if category_key in assistant.categories:
+                            score += 50
+                        elif '*' in assistant.categories:
+                            score += 5
+                        else:
+                            is_match = False
+                            score = -100
+                    elif '*' in assistant.categories:
+                        score += 5
+
+                # Grading mode matching
+                if is_match:  # Only check if still matching
+                    if mode_key:
+                        if mode_key in assistant.grading_modes:
+                            score += 25
+                        elif '*' in assistant.grading_modes:
+                            score += 2
+                        else:
+                            is_match = False
+                            score = -100
+                    elif '*' in assistant.grading_modes:
+                        score += 2
+
+            all_assistants.append({
+                "name": assistant.name,
+                "assistant_id": assistant.assistant_id,
+                "score": score,
+                "is_recommended": False,
+                "is_match": is_match
+            })
+
+        # Filter to only matching assistants
+        matching_assistants = [a for a in all_assistants if a['is_match']]
+
+        # Sort by score (highest first)
+        matching_assistants.sort(reverse=True, key=lambda x: x['score'])
+
+        # Mark the best match as recommended
+        if matching_assistants:
+            matching_assistants[0]['is_recommended'] = True
+
+        return {
+            "success": True,
+            "matches": matching_assistants,
+            "count": len(matching_assistants)
+        }
+
     except Exception as e:
-        logger.error(f"Error fetching agents: {str(e)}")
+        logger.error(f"Error finding assistants: {str(e)}", exc_info=True)
         raise HTTPException(status_code=500, detail=str(e))
 
+# ============================================================
+# Grade API - 主要批改端點
+# ============================================================
+
 @router.post("/grade", response_model=GradeResponse)
 async def grade_text(request: GradeRequest):
-    """Grade text using specified agent"""
+    """
+    Grade text using matched assistant based on parameters
+
+    Request body:
+        {
+            "text": "文章內容...",
+            "language": "zh-TW",  // 可選：zh-TW 或 en
+            "age_group": "國小",     // 可用中文或英文 key
+            "category": "記敘文",    // 可用中文或英文 key
+            "grading_mode": "全文批改"  // 可用中文或英文 key
+        }
+
+    Returns grading result from matched assistant
+    """
     try:
-        # Get agent configuration
+        logger.info(f"Grading request: language={request.language}, age_group={request.age_group}, category={request.category}, mode={request.grading_mode}, assistant_id={request.assistant_id}")
+
         config = get_agents_config()
-        agent = config.get_agent(request.agent_key)
-        
-        if not agent:
-            return GradeResponse(
-                success=False,
-                error={
-                    "code": "INVALID_AGENT",
-                    "message": f"Agent '{request.agent_key}' not found",
-                    "available_agents": list(config.agents.keys())
-                }
+
+        # If user specified assistant_id, use it directly
+        if request.assistant_id:
+            assistant = None
+            for asst in config.assistants:
+                if asst.assistant_id == request.assistant_id:
+                    assistant = asst
+                    break
+
+            if not assistant:
+                logger.warning(f"Specified assistant_id not found: {request.assistant_id}")
+                return GradeResponse(
+                    success=False,
+                    error={
+                        "code": "ASSISTANT_NOT_FOUND",
+                        "message": f"找不到指定的批改助手: {request.assistant_id}",
+                        "details": {"assistant_id": request.assistant_id}
+                    }
+                )
+            logger.info(f"Using user-selected assistant: {assistant.name} (id: {assistant.assistant_id})")
+
+        else:
+            # Auto-match assistant based on parameters
+            assistant = config.find_assistant(
+                language=request.language,
+                age_group=request.age_group,
+                category=request.category,
+                grading_mode=request.grading_mode
             )
-        
-        # Add category, age_group, and language to options if provided
+
+            if not assistant:
+                logger.warning(f"No assistant found for request: {request.model_dump()}")
+                return GradeResponse(
+                    success=False,
+                    error={
+                        "code": "ASSISTANT_NOT_FOUND",
+                        "message": "找不到符合條件的批改助手",
+                        "details": {
+                            "language": request.language,
+                            "age_group": request.age_group,
+                            "category": request.category,
+                            "grading_mode": request.grading_mode,
+                            "hint": "請檢查 agents.yaml 配置或使用 /api/assistants 查看可用助手"
+                        }
+                    }
+                )
+
+            logger.info(f"Using auto-matched assistant: {assistant.name} (id: {assistant.assistant_id})")
+
+        # Add parameters to options for prompt building
         options = request.options or {}
-        if request.category:
-            options['category'] = request.category
-        if request.age_group:
-            options['age_group'] = request.age_group
-        if request.language:
-            options['language'] = request.language
-        
+        options['category'] = request.category
+        options['age_group'] = request.age_group
+        options['language'] = request.language
+
         # Call OpenAI service
         openai_service = get_openai_service()
         result = await openai_service.grade_text(
-            agent=agent,
+            agent=assistant,
             text=request.text,
             options=options
         )
-        
+
         return GradeResponse(
             success=True,
             data={
-                "agent_key": request.agent_key,
+                "assistant_name": assistant.name,
+                "assistant_id": assistant.assistant_id,
                 "result": result.model_dump()
             }
         )
-        
+
     except ValueError as e:
+        logger.error(f"Validation error: {str(e)}")
         return GradeResponse(
             success=False,
             error={
@@ -92,22 +275,27 @@ async def grade_text(request: GradeRequest):
             }
         )
     except Exception as e:
-        logger.error(f"Error grading text: {str(e)}")
+        logger.error(f"Error grading text: {str(e)}", exc_info=True)
         return GradeResponse(
             success=False,
             error={
                 "code": "INTERNAL_ERROR",
-                "message": "An error occurred while processing your request"
+                "message": "批改過程中發生錯誤",
+                "details": str(e) if get_settings().environment == "development" else None
             }
         )
 
+# ============================================================
+# Password Verification API
+# ============================================================
+
 @router.post("/verify-password", response_model=PasswordVerifyResponse)
 async def verify_password(request: PasswordVerifyRequest):
     """Verify password for platform access"""
     try:
         settings = get_settings()
         correct_password = settings.app_password or "3030"
-        
+
         if request.password == correct_password:
             return PasswordVerifyResponse(
                 success=True,
@@ -125,7 +313,23 @@ async def verify_password(request: PasswordVerifyRequest):
             message="Password verification failed"
         )
 
+# ============================================================
+# Health Check API
+# ============================================================
+
 @router.get("/health")
 async def health_check():
     """Health check endpoint"""
-    return {"status": "healthy", "service": "AI Grading Platform"}
+    try:
+        config = get_agents_config()
+        return {
+            "status": "healthy",
+            "service": "AI Grading Platform",
+            "version": config.version,
+            "assistants_loaded": len(config.assistants)
+        }
+    except Exception as e:
+        return {
+            "status": "unhealthy",
+            "error": str(e)
+        }

backend/app/services/openai_service.py

@@ -118,7 +118,7 @@ class OpenAIService:
         Build prompt based on agent configuration
         """
         # Use the new structured grading prompt for Chinese agents
-        if agent.language == "zh-Hant":
+        if agent.language == "zh-TW":
             category = options.get('category', '')
             age_group = options.get('age_group', '')
             language = options.get('language', 'zh')

backend/check_assistants.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""檢查 agents.yaml 中配置的所有機器人是否可用"""
+
+import yaml
+import sys
+import os
+from openai import OpenAI
+
+# 讀取 .env.local
+env_file = '.env.local'
+if os.path.exists(env_file):
+    with open(env_file) as f:
+        for line in f:
+            if line.strip() and not line.startswith('#'):
+                key, value = line.strip().split('=', 1)
+                os.environ[key] = value
+
+# 讀取配置
+with open('../agents.yaml', 'r', encoding='utf-8') as f:
+    config = yaml.safe_load(f)
+
+# 獲取 API key
+api_key = os.getenv('OPENAI_API_KEY')
+
+if not api_key:
+    print("❌ 錯誤: 找不到 OPENAI_API_KEY")
+    print("   請在 .env.local 文件中設置 OPENAI_API_KEY")
+    sys.exit(1)
+
+client = OpenAI(api_key=api_key, default_headers={"OpenAI-Beta": "assistants=v2"})
+
+print("\n" + "=" * 80)
+print("檢查 agents.yaml 中的機器人")
+print("=" * 80 + "\n")
+
+valid_count = 0
+invalid_count = 0
+disabled_count = 0
+invalid_assistants = []
+
+for assistant in config['assistants']:
+    name = assistant['name']
+    assistant_id = assistant['assistant_id']
+    enabled = assistant.get('enabled', True)
+
+    if not enabled:
+        print(f"⏸️  {name}")
+        print(f"   ID: {assistant_id}")
+        print(f"   狀態: 已停用（未檢查）\n")
+        disabled_count += 1
+        continue
+
+    # 檢查啟用的機器人
+    try:
+        asst = client.beta.assistants.retrieve(assistant_id)
+        print(f"✅ {name}")
+        print(f"   ID: {assistant_id}")
+        print(f"   OpenAI 名稱: {asst.name}")
+        print(f"   Model: {asst.model}")
+        print(f"   狀態: ✅ 可用\n")
+        valid_count += 1
+    except Exception as e:
+        error_msg = str(e)
+        print(f"❌ {name}")
+        print(f"   ID: {assistant_id}")
+        print(f"   狀態: ❌ 不可用")
+        print(f"   錯誤: {error_msg[:150]}\n")
+        invalid_count += 1
+        invalid_assistants.append({
+            'name': name,
+            'id': assistant_id,
+            'error': error_msg
+        })
+
+print("=" * 80)
+print("總結")
+print("=" * 80)
+print(f"  ✅ 可用機器人: {valid_count}")
+print(f"  ❌ 不可用機器人: {invalid_count}")
+print(f"  ⏸️  已停用機器人: {disabled_count}")
+print(f"  📊 總計: {valid_count + invalid_count + disabled_count}")
+
+if invalid_assistants:
+    print("\n⚠️  需要修正的機器人：")
+    for asst in invalid_assistants:
+        print(f"   - {asst['name']} ({asst['id']})")
+        print(f"     錯誤: {asst['error'][:100]}")
+
+print("\n" + "=" * 80 + "\n")
+
+sys.exit(0 if invalid_count == 0 else 1)

frontend/src/App.tsx

@@ -1,6 +1,6 @@
 import { useState, useEffect } from 'react';
 import './App.css';
-import type { Agent, GradeResult } from './types/index';
+import type { GradeResult, Option, OptionsResponse, MatchedAssistant } from './types/index';
 import { gradingApi } from './api/grading';
 import AssistantGuide from './AssistantGuide';
 import PasswordProtection from './components/PasswordProtection';
@@ -8,52 +8,35 @@ import PasswordProtection from './components/PasswordProtection';
 function App() {
   const [isPasswordVerified, setIsPasswordVerified] = useState<boolean>(false);
   const [currentView, setCurrentView] = useState<'grading' | 'guide'>('grading');
-  const [agents, setAgents] = useState<Agent[]>([]);
-  const [selectedAgent, setSelectedAgent] = useState<string>('');
-  const [selectedCategory, setSelectedCategory] = useState<string>('1');
-  const [selectedAgeGroup, setSelectedAgeGroup] = useState<string>('國小');
-  const [selectedLanguage, setSelectedLanguage] = useState<string>('zh');
+
+  // 從 API 載入的選項
+  const [ageGroups, setAgeGroups] = useState<Option[]>([]);
+  const [categories, setCategories] = useState<Option[]>([]);
+  const [gradingModes, setGradingModes] = useState<Option[]>([]);
+
+  // 使用者選擇
+  const [selectedAgeGroup, setSelectedAgeGroup] = useState<string>('');
+  const [selectedCategory, setSelectedCategory] = useState<string>('');
+  const [selectedGradingMode, setSelectedGradingMode] = useState<string>('');
+  const [selectedLanguage, setSelectedLanguage] = useState<string>('zh-TW');
+
   const [text, setText] = useState<string>('');
   const [loading, setLoading] = useState<boolean>(false);
   const [result, setResult] = useState<GradeResult | null>(null);
   const [error, setError] = useState<string>('');
 
-  const categories = [
-    { value: '1', label: '文學小說' },
-    { value: '2', label: '詩集' },
-    { value: '3', label: '心理勵志' },
-    { value: '4', label: '藝術設計' },
-    { value: '5', label: '觀光旅遊' },
-    { value: '6', label: '美食饗宴' },
-    { value: '7', label: '行銷文案' },
-    { value: '8', label: '商業理財' },
-    { value: '9', label: '人文史地' },
-    { value: '10', label: '自然科普' },
-    { value: '11', label: '漫畫圖文' },
-    { value: '12', label: '教育學習' },
-    { value: '13', label: '生活休閒' },
-    { value: '14', label: '創意想像' },
-    { value: '15', label: '資訊科技' },
-    { value: '16', label: '社會議題' },
-  ];
-
-  const ageGroups = [
-    { value: '國小', label: '國小' },
-    { value: '國中', label: '國中' },
-    { value: '高中', label: '高中' },
-    { value: '大學', label: '大學' },
-    { value: '上班族', label: '上班族' },
-    { value: '退休人士', label: '退休人士' },
-  ];
+  // 機器人選擇
+  const [matchedAssistants, setMatchedAssistants] = useState<MatchedAssistant[]>([]);
+  const [selectedAssistantId, setSelectedAssistantId] = useState<string>('');
 
   const languages = [
-    { value: 'zh', label: '中文' },
+    { value: 'zh-TW', label: '中文' },
     { value: 'en', label: 'English' },
   ];
 
   // Translations
   const labels = {
-    zh: {
+    'zh-TW': {
       language: '語言：',
       ageGroup: '對象年齡：',
       category: '文章分類：',
@@ -78,7 +61,7 @@ function App() {
       revisedLabel: '修改：',
       reasonLabel: '原因：',
     },
-    en: {
+    'en': {
       language: 'Language:',
       ageGroup: 'Age Group:',
       category: 'Article Category:',
@@ -105,35 +88,79 @@ function App() {
     }
   };
 
-  const currentLabels = labels[selectedLanguage as 'zh' | 'en'] || labels.zh;
+  const currentLabels = labels[selectedLanguage as 'zh-TW' | 'en'] || labels['zh-TW'];
 
   useEffect(() => {
     // Check if password is already verified
     const savedPassword = sessionStorage.getItem('app_password_verified');
     if (savedPassword === 'true') {
       setIsPasswordVerified(true);
-      loadAgents();
+      loadOptions();
     }
   }, []);
 
   const handlePasswordCorrect = () => {
     setIsPasswordVerified(true);
-    loadAgents();
+    loadOptions();
   };
 
-  const loadAgents = async () => {
+  const loadOptions = async () => {
     try {
-      const agentsList = await gradingApi.getAgents();
-      setAgents(agentsList);
-      if (agentsList.length > 0) {
-        setSelectedAgent(agentsList[0].key);
+      const options: OptionsResponse = await gradingApi.getOptions();
+
+      setAgeGroups(options.age_groups || []);
+      setCategories(options.categories || []);
+      setGradingModes(options.grading_modes || []);
+
+      // 設定預設值
+      if (options.age_groups && options.age_groups.length > 0) {
+        setSelectedAgeGroup(options.age_groups[0].key);
+      }
+      if (options.categories && options.categories.length > 0) {
+        setSelectedCategory(options.categories[0].key);
+      }
+      if (options.grading_modes && options.grading_modes.length > 0) {
+        setSelectedGradingMode(options.grading_modes[0].key);
       }
     } catch (err) {
-      console.error('Failed to load agents:', err);
-      setError('無法載入批改模式');
+      console.error('Failed to load options:', err);
+      setError('無法載入選項，請重新整理頁面');
     }
   };
 
+  // 當選項改變時，自動查找匹配的機器人
+  useEffect(() => {
+    const findAssistants = async () => {
+      try {
+        const response = await gradingApi.findAssistants({
+          language: selectedLanguage,
+          age_group: selectedAgeGroup,
+          category: selectedCategory,
+          grading_mode: selectedGradingMode,
+        });
+
+        if (response.success && response.matches) {
+          setMatchedAssistants(response.matches);
+
+          // 自動選擇推薦的機器人（score最高的）
+          const recommended = response.matches.find(a => a.is_recommended);
+          if (recommended) {
+            setSelectedAssistantId(recommended.assistant_id);
+          } else if (response.matches.length > 0) {
+            setSelectedAssistantId(response.matches[0].assistant_id);
+          }
+        }
+      } catch (err) {
+        console.error('Failed to find assistants:', err);
+        // 不顯示錯誤，因為這不是關鍵功能
+      }
+    };
+
+    if (selectedAgeGroup && selectedCategory && selectedGradingMode) {
+      findAssistants();
+    }
+  }, [selectedLanguage, selectedAgeGroup, selectedCategory, selectedGradingMode]);
+
   const handleGrade = async () => {
     if (!text.trim()) {
       setError('請輸入要批改的文章');
@@ -145,19 +172,19 @@ function App() {
     setResult(null);
 
     try {
-      const categoryLabel = categories.find(c => c.value === selectedCategory)?.label || '一般文章';
       const response = await gradingApi.gradeText({
-        agent_key: selectedAgent,
         text: text,
-        category: categoryLabel,
-        age_group: selectedAgeGroup,
         language: selectedLanguage,
+        age_group: selectedAgeGroup,
+        category: selectedCategory,
+        grading_mode: selectedGradingMode,
+        assistant_id: selectedAssistantId || undefined,
       });
 
       if (response.success && response.data) {
         setResult(response.data.result);
       } else if (response.error) {
-        setError(response.error.message);
+        setError(response.error.message + (response.error.details ? `\n${JSON.stringify(response.error.details, null, 2)}` : ''));
       }
     } catch (err) {
       console.error('Grading failed:', err);
@@ -173,9 +200,6 @@ function App() {
     setError('');
   };
 
-  // 取得當前選中的 agent
-  const currentAgent = agents.find(a => a.key === selectedAgent);
-
   // Show password protection if not verified
   if (!isPasswordVerified) {
     return <PasswordProtection onPasswordCorrect={handlePasswordCorrect} />;
@@ -187,29 +211,29 @@ function App() {
         <div className="header-row-1">
           <h1>AI 批改平台</h1>
           <nav className="header-nav">
-            <button 
+            <button
               className={`nav-button ${currentView === 'grading' ? 'active' : ''}`}
               onClick={() => setCurrentView('grading')}
             >
               批改平台
             </button>
-            <button 
+            <button
               className={`nav-button ${currentView === 'guide' ? 'active' : ''}`}
               onClick={() => setCurrentView('guide')}
             >
               設定指南
             </button>
-            <a 
+            <a
               href={window.location.port === '5174' ? 'http://localhost:8001/docs' : '/docs'}
-              target="_blank" 
+              target="_blank"
               rel="noopener noreferrer"
               className="nav-link"
             >
               API 文檔
             </a>
-            <a 
-              href="https://drive.google.com/drive/folders/1jFNx3loIJtEo8CwkendtpGh6m8WMa_QH" 
-              target="_blank" 
+            <a
+              href="https://drive.google.com/drive/folders/1jFNx3loIJtEo8CwkendtpGh6m8WMa_QH"
+              target="_blank"
               rel="noopener noreferrer"
               className="nav-link course-link"
             >
@@ -243,7 +267,7 @@ function App() {
               disabled={loading}
             >
               {ageGroups.map((age) => (
-                <option key={age.value} value={age.value}>
+                <option key={age.key} value={age.key}>
                   {age.label}
                 </option>
               ))}
@@ -259,7 +283,7 @@ function App() {
               disabled={loading}
             >
               {categories.map((category) => (
-                <option key={category.value} value={category.value}>
+                <option key={category.key} value={category.key}>
                   {category.label}
                 </option>
               ))}
@@ -267,35 +291,19 @@ function App() {
           </div>
 
           <div className="header-selector">
-            <label htmlFor="agent">{currentLabels.gradingMode}</label>
+            <label htmlFor="grading-mode">{currentLabels.gradingMode}</label>
             <select
-              id="agent"
-              value={selectedAgent}
-              onChange={(e) => setSelectedAgent(e.target.value)}
+              id="grading-mode"
+              value={selectedGradingMode}
+              onChange={(e) => setSelectedGradingMode(e.target.value)}
               disabled={loading}
             >
-              {agents.map((agent) => (
-                <option key={agent.key} value={agent.key}>
-                  {agent.name}
+              {gradingModes.map((mode) => (
+                <option key={mode.key} value={mode.key}>
+                  {mode.label}
                 </option>
               ))}
             </select>
-            {currentAgent && currentAgent.ui && (
-              <span 
-                className="agent-badge" 
-                style={{ 
-                  backgroundColor: currentAgent.ui.color,
-                  marginLeft: '10px',
-                  padding: '4px 10px',
-                  borderRadius: '15px',
-                  color: 'white',
-                  fontWeight: 'bold',
-                  fontSize: '0.85rem'
-                }}
-              >
-                {currentAgent.ui.badge}
-              </span>
-            )}
           </div>
         </div>
       </header>
@@ -317,14 +325,50 @@ function App() {
           </div>
 
           <div className="action-buttons">
-            <button 
+            <button
               className="btn btn-primary"
               onClick={handleGrade}
               disabled={loading || !text.trim()}
             >
               {loading ? currentLabels.gradingButton : currentLabels.gradeButton}
             </button>
-            <button 
+
+            {/* 機器人選擇下拉選單 */}
+            {matchedAssistants.length > 0 && (
+              <select
+                className="assistant-selector"
+                value={selectedAssistantId}
+                onChange={(e) => setSelectedAssistantId(e.target.value)}
+                disabled={loading}
+                style={{
+                  padding: '10px 15px',
+                  borderRadius: '8px',
+                  border: '2px solid #E0E0E0',
+                  fontSize: '14px',
+                  fontWeight: '500',
+                  cursor: 'pointer',
+                  backgroundColor: '#fff',
+                  minWidth: '200px',
+                }}
+              >
+                {matchedAssistants.map((assistant) => (
+                  <option
+                    key={assistant.assistant_id}
+                    value={assistant.assistant_id}
+                    style={{
+                      color: assistant.is_match ? '#000' : '#999',
+                      fontStyle: assistant.is_match ? 'normal' : 'italic',
+                    }}
+                  >
+                    {assistant.is_recommended ? '⭐ ' : ''}
+                    {assistant.name}
+                    {!assistant.is_match ? ' (不太適合)' : ''}
+                  </option>
+                ))}
+              </select>
+            )}
+
+            <button
               className="btn btn-secondary"
               onClick={handleClear}
               disabled={loading}
@@ -335,7 +379,7 @@ function App() {
 
           {error && (
             <div className="error-message">
-              {error}
+              <pre style={{whiteSpace: 'pre-wrap'}}>{error}</pre>
             </div>
           )}
         </div>
@@ -347,11 +391,11 @@ function App() {
               <p>{currentLabels.loadingMessage}</p>
             </div>
           )}
-          
+
           {!loading && result && (
             <div className="result-container">
               <h2>{currentLabels.resultTitle}</h2>
-              
+
               {result.summary && (
                 <div className="result-section">
                   <h3>{currentLabels.summaryTitle}</h3>
@@ -417,7 +461,7 @@ function App() {
               {result.scores && (
                 <div className="result-section">
                   <h3>{currentLabels.scoresTitle}</h3>
-                  
+
                   {/* 評分表格 */}
                   <div className="score-table">
                     <table>
@@ -441,28 +485,43 @@ function App() {
                             if (score >= 63) return 'C';
                             return 'D';
                           };
-                          
+
                           const getExplanation = () => {
                             const suggestion = result.suggestions?.find(s => s.type === key);
                             return suggestion?.text || (selectedLanguage === 'en' ? 'Good performance' : '表現良好');
                           };
-                          
+
                           const getCriteriaName = () => {
-                            if (selectedLanguage === 'en') {
-                              if (key === 'theme_content' || key === '主題與內容') return 'Theme & Content';
-                              if (key === 'word_sentence' || key === '遣詞造句') return 'Word Choice';
-                              if (key === 'paragraph_structure' || key === '段落結構') return 'Structure';
-                              if (key === 'typo_check' || key === '錯別字檢查') return 'Spelling & Grammar';
+                            // 直接顯示 AI 回傳的 key（已經是中文 label）
+                            // 如果 key 是英文，做簡單的翻譯
+                            const translations: Record<string, string> = {
+                              // 從 rubric_templates 來的 key
+                              'content': '內容創意',
+                              'structure': '文章結構',
+                              'expression': '文字表達',
+                              'mechanics': '文字運用',
+                              'theme': '主題深度',
+                              'argumentation': '論證邏輯',
+                              'critical_thinking': '批判思考',
+                              'clarity': '表達清晰',
+                              'professionalism': '專業性',
+
+                              // 舊格式（向後相容）
+                              'theme_content': '主題與內容',
+                              'word_sentence': '遣詞造句',
+                              'paragraph_structure': '段落結構',
+                              'typo_check': '錯別字檢查',
+                            };
+
+                            // 如果已經是中文，直接返回
+                            if (/[\u4e00-\u9fa5]/.test(key)) {
                               return key;
                             }
-                            // Chinese
-                            if (key === 'theme_content' || key === '主題與內容') return '主題與內容';
-                            if (key === 'word_sentence' || key === '遣詞造句') return '遣詞造句';
-                            if (key === 'paragraph_structure' || key === '段落結構') return '段落結構';
-                            if (key === 'typo_check' || key === '錯別字檢查') return '錯別字檢查';
-                            return key;
+
+                            // 否則從翻譯表查找
+                            return translations[key] || key;
                           };
-                          
+
                           return (
                             <tr key={key}>
                               <td className="criteria-name">{getCriteriaName()}</td>
@@ -476,7 +535,7 @@ function App() {
                             <td className="criteria-name">{currentLabels.overallLabel}</td>
                             <td className="criteria-grade">
                               <span className="overall-emoji">
-                                {result.scores.overall >= 80 ? '🟢' : 
+                                {result.scores.overall >= 80 ? '🟢' :
                                  result.scores.overall >= 60 ? '🟡' : '🔴'}
                               </span>
                               <span className="overall-score-number">
@@ -503,7 +562,7 @@ function App() {
                       const original = lines.find(l => l.startsWith('原文：') || l.startsWith('Original:'))?.replace(/^(原文：|Original:)/, '') || '';
                       const corrected = lines.find(l => l.startsWith('修改：') || l.startsWith('Revised:'))?.replace(/^(修改：|Revised:)/, '') || '';
                       const reason = lines.find(l => l.startsWith('原因：') || l.startsWith('Reason:'))?.replace(/^(原因：|Reason:)/, '') || '';
-                      
+
                       return (
                         <div key={index} className="correction-item">
                           <div className="correction-header">
@@ -526,7 +585,7 @@ function App() {
                         </div>
                       );
                     })}
-                    
+
                     {result.suggestions.filter(s => s.type !== 'correction' && s.section !== 'evaluation').map((suggestion, index) => (
                       <div key={`other-${index}`} className="suggestion-item">
                         <strong>{suggestion.type}：</strong>
@@ -545,4 +604,4 @@ function App() {
   );
 }
 
-export default App;
+export default App;

frontend/src/api/grading.ts

@@ -1,5 +1,5 @@
 import axios from 'axios';
-import type { Agent, AgentsResponse, GradeRequest, GradeResponse } from '../types/index';
+import type { OptionsResponse, GradeRequest, GradeResponse, FindAssistantsResponse } from '../types/index';
 
 const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8001/api';
 
@@ -20,18 +20,48 @@ api.interceptors.request.use((config) => {
 });
 
 export const gradingApi = {
-  async getAgents(): Promise<Agent[]> {
-    const response = await api.get<AgentsResponse>('/agents');
-    return response.data.agents;
+  /**
+   * 取得前端下拉選單選項
+   */
+  async getOptions(): Promise<OptionsResponse> {
+    const response = await api.get<OptionsResponse>('/options');
+    return response.data;
   },
 
+  /**
+   * 送出批改請求
+   */
   async gradeText(request: GradeRequest): Promise<GradeResponse> {
     const response = await api.post<GradeResponse>('/grade', request);
     return response.data;
   },
 
+  /**
+   * 驗證密碼
+   */
   async verifyPassword(password: string): Promise<{success: boolean, message?: string}> {
     const response = await axios.post(`${API_BASE_URL}/verify-password`, { password });
     return response.data;
   },
+
+  /**
+   * 除錯用：查看所有配置的助手
+   */
+  async getAssistants(): Promise<any> {
+    const response = await api.get('/assistants');
+    return response.data;
+  },
+
+  /**
+   * 根據條件查找匹配的機器人
+   */
+  async findAssistants(params: {
+    language?: string;
+    age_group?: string;
+    category?: string;
+    grading_mode?: string;
+  }): Promise<FindAssistantsResponse> {
+    const response = await api.get<FindAssistantsResponse>('/find-assistants', { params });
+    return response.data;
+  },
 };

frontend/src/types/index.ts

@@ -1,30 +1,41 @@
-export type Agent = {
+// 選項定義
+export type Option = {
   key: string;
-  name: string;
-  language: string;
-  ui?: {
-    badge: string;
-    color: string;
-  };
-  rubric?: {
-    overall_weight: number;
-    criteria: Array<{
-      key: string;
-      label: string;
-      weight: number;
-    }>;
-  };
+  label: string;
+}
+
+export type OptionsResponse = {
+  age_groups: Option[];
+  categories: Option[];
+  grading_modes: Option[];
 }
 
+// 批改請求
 export type GradeRequest = {
-  agent_key: string;
   text: string;
-  category?: string;
-  age_group?: string;
   language?: string;
+  age_group?: string;
+  category?: string;
+  grading_mode?: string;
+  assistant_id?: string;  // 可選：手動指定機器人ID
   options?: Record<string, any>;
 }
 
+// 機器人匹配結果
+export type MatchedAssistant = {
+  name: string;
+  assistant_id: string;
+  score: number;
+  is_recommended: boolean;
+  is_match: boolean;
+}
+
+export type FindAssistantsResponse = {
+  success: boolean;
+  matches: MatchedAssistant[];
+  count: number;
+}
+
 export type Suggestion = {
   type: string;
   section: string;
@@ -46,16 +57,13 @@ export type GradeResult = {
 export type GradeResponse = {
   success: boolean;
   data?: {
-    agent_key: string;
+    assistant_name: string;
+    assistant_id: string;
     result: GradeResult;
   };
   error?: {
     code: string;
     message: string;
+    details?: any;
   };
-}
-
-export type AgentsResponse = {
-  version: number;
-  agents: Agent[];
 }