feat: backup architecture docs, source code, and scripts

docs_v1.0/AI_AGENTS/TRANSLATION/TEXT_TRANSLATION.md

@@ -0,0 +1,166 @@
+# 翻譯 Agent (Translation Agent) 設計文件
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-25 |
+| 文件版本 | V1.0 |
+| 用途 | 提供多語言文本翻譯服務 (應用於 Portal Chunk Detail) |
+
+---
+
+## 1. Agent 概覽
+
+Translation Agent 負責將系統中的非結構化文本（如 Chunk 內容、摘要、5W1H 推論結果）翻譯為使用者指定的語言。
+在 Portal 的 **Chunk Search Detail** 頁面，當使用者瀏覽不同語言的影片內容時，此 Agent 提供即時翻譯支援。
+
+### 1.1 資源註冊資訊 (Resource Registry)
+
+當 Agent 啟動時，將向 **Resource Registry** 註冊以下資訊：
+
+```json
+{
+  "resource_id": "agent_text_translation_v1",
+  "resource_type": "agent",
+  "capabilities": ["translate_text", "detect_language", "batch_translate"],
+  "category": "text_processing",
+  "config": {
+    "default_model": "gpt-4o-mini",
+    "fallback_model": "local-llama-3-8b",
+    "max_tokens": 4096,
+    "supported_languages": ["zh-TW", "en-US", "ja-JP", "ko-KR"]
+  }
+}
+```
+
+---
+
+## 2. 核心設計
+
+### 2.1 輸入格式 (Input)
+
+Agent 接收來自 Portal 或內部 API 的 JSON 請求：
+
+```json
+{
+  "text": "He walked into the room and saw a large red car.",
+  "target_language": "zh-TW",
+  "source_language": "auto", 
+  "context": {
+    "domain": "movie_subtitle",
+    "glossary": {
+      "red car": "紅色跑車" 
+    }
+  }
+}
+```
+
+- `text`: 待翻譯文本。
+- `target_language`: 目標語言 (BCP 47 格式)。
+- `context` (可選): 提供領域資訊或專有名詞對照表 (Glossary) 以提高準確度。
+
+### 2.2 輸出格式 (Output)
+
+Agent 回傳標準化 JSON：
+
+```json
+{
+  "translated_text": "他走進房間，看到一輛紅色跑車。",
+  "source_language_detected": "en-US",
+  "confidence": 0.98,
+  "usage": {
+    "input_tokens": 12,
+    "output_tokens": 15
+  }
+}
+```
+
+---
+
+## 3. Prompt 設計 (System Prompt)
+
+為了確保翻譯風格符合 Momentry Core 的專業性（如準確的影視術語），我們使用以下 System Prompt：
+
+```text
+You are a professional translator for Momentry Core, a digital asset management system specializing in video analysis.
+
+## Guidelines:
+1. **Accuracy**: Translate the meaning accurately, maintaining the original tone.
+2. **Context Awareness**: If a glossary is provided in the context, strictly follow it.
+3. **Style**: 
+   - For subtitles: Keep it concise and natural for reading.
+   - For technical terms (e.g., 5W1H, metadata): Use standard industry translations.
+4. **Format**: Preserve any JSON structure, markdown, or timestamps present in the input text. Do not translate code blocks.
+5. **Output**: Return ONLY the translated text in the requested format unless asked otherwise.
+```
+
+---
+
+## 4. API 端點設計
+
+### 4.1 單一翻譯
+
+```http
+POST /api/v1/agents/translate
+Content-Type: application/json
+X-Resource-Id: agent_text_translation_v1
+
+{
+  "text": "...",
+  "target_language": "zh-TW"
+}
+```
+
+### 4.2 批次翻譯 (Batch Translation)
+
+針對 Chunk Detail 頁面可能一次顯示多個段落，支援批次翻譯：
+
+```http
+POST /api/v1/agents/translate/batch
+Content-Type: application/json
+
+{
+  "items": [
+    { "id": "chunk_001", "text": "..." },
+    { "id": "chunk_002", "text": "..." }
+  ],
+  "target_language": "zh-TW"
+}
+```
+
+---
+
+## 5. 錯誤處理與容錯
+
+- **模型降級 (Fallback)**: 若 `gpt-4o-mini` 超時或不可用，自動切換至本地模型 `local-llama-3-8b`。
+- **Token 超長**: 若文本超過 `max_tokens`，自動進行分段翻譯 (Split & Translate)。
+- **無效語言**: 若 `target_language` 不在支援列表中，回傳 `400 Bad Request`。
+
+---
+
+## 6. Portal 整合範例 (Chunk Detail)
+
+在 Portal 的 `ChunkDetailView.vue` 中，翻譯功能的調用流程如下：
+
+1.  使用者點擊「翻譯為 繁體中文」按鈕。
+2.  Portal 發送 POST 請求至 `/api/v1/agents/translate`。
+3.  取得結果後，在不重新整理頁面的情況下更新 UI (顯示 `translated_text`)。
+
+```typescript
+// Portal 前端調用範例
+async function translateChunkText(text: string, targetLang: string) {
+  const response = await fetch('/api/v1/agents/translate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text, target_language: targetLang })
+  });
+  return response.json();
+}
+```
+
+---
+
+## 版本資訊
+
+- 版本: V1.0
+- 建立日期: 2026-04-25