botrun-horse 2.29.2 → 2.30.0

package/botrun-c/.claude/skills/nchc-transcribe/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: nchc-transcribe
+description: 使用國網中心 (NCHC) TAIDE Whisper API 進行語音轉文字，內建三層 Fallback 機制（NCHC → Spot VM → Cloud Run）
+allowed-tools: Bash
+---
+
+# NCHC Whisper 語音轉錄工具
+
+使用國網中心 (NCHC) TAIDE Whisper API 進行語音轉文字。內建三層 Fallback 機制確保高可用性。
+
+## Fallback 機制
+
+```
+音訊檔案
+    │
+    ▼
+┌─────────────────────────────┐
+│ 1. NCHC Whisper (TAIDE API) │  ← 主要服務（最多 4 次嘗試）
+│    model: Breeze-ASR-25     │
+└─────────────────────────────┘
+    │ 失敗
+    ▼
+┌─────────────────────────────┐
+│ 2. Spot VM Whisper          │  ← Fallback 1（最多 4 次嘗試）
+│    + OpenCC 簡→繁轉換       │
+└─────────────────────────────┘
+    │ 失敗
+    ▼
+┌─────────────────────────────┐
+│ 3. Cloud Run Whisper        │  ← Fallback 2（最多 4 次嘗試）
+│    + OpenCC 簡→繁轉換       │
+└─────────────────────────────┘
+```
+
+每層使用指數退避 + Jitter 重試策略（1s, 2s, 4s + random jitter）。
+
+## 使用方式
+
+```bash
+uv run $OFFICIAL_SKILLS_DIR/nchc-transcribe/scripts/transcribe.py \
+  --input <AUDIO_FILE> \
+  [--output <OUTPUT_FILE>] \
+  [--model <MODEL>] \
+  [--json]
+```
+
+### 參數說明
+
+| 參數 | 縮寫 | 必填 | 說明 |
+|------|------|------|------|
+| `--input` | `-i` | 是 | 輸入音訊檔案路徑 |
+| `--output` | `-o` | 否 | 輸出文字檔案路徑（預設輸出到 stdout） |
+| `--model` | `-m` | 否 | NCHC Whisper 模型（預設: whisper-Breeze-ASR-25） |
+| `--json` | | 否 | 輸出 JSON 格式（含 metadata） |
+
+### 範例
+
+**基本轉錄（輸出到 stdout）：**
+```bash
+uv run $OFFICIAL_SKILLS_DIR/nchc-transcribe/scripts/transcribe.py \
+  -i recording.webm
+```
+
+**轉錄並儲存到檔案：**
+```bash
+uv run $OFFICIAL_SKILLS_DIR/nchc-transcribe/scripts/transcribe.py \
+  -i recording.mp3 \
+  -o output/transcript.txt
+```
+
+**使用 Large-V3 模型並輸出 JSON：**
+```bash
+uv run $OFFICIAL_SKILLS_DIR/nchc-transcribe/scripts/transcribe.py \
+  -i meeting.m4a \
+  -o output/transcript.json \
+  --model Whisper-Large-V3 \
+  --json
+```
+
+## 支援的音訊格式
+
+| 格式 | 副檔名 |
+|------|--------|
+| WebM | .webm |
+| MP3 | .mp3 |
+| MP4 | .mp4 |
+| M4A | .m4a |
+| WAV | .wav |
+| OGG | .ogg |
+| Opus | .opus |
+| AAC | .aac |
+| FLAC | .flac |
+
+## 支援的模型
+
+| 模型 | 說明 |
+|------|------|
+| `whisper-Breeze-ASR-25`（預設）| NCHC Breeze ASR 2025 模型 |
+| `Whisper-Large-V3` | OpenAI Whisper Large V3 模型 |
+
+## 輸出 JSON 結構
+
+使用 `--json` 時輸出：
+
+```json
+{
+  "success": true,
+  "text": "轉錄文字...",
+  "model": "whisper-Breeze-ASR-25",
+  "file": "recording.webm",
+  "file_size": 1234567,
+  "elapsed_seconds": 12.34,
+  "processed_at": "2026-02-09T12:00:00"
+}
+```
+
+## 環境需求
+
+- Python 3.8+
+- 網路連線（需存取 NCHC / GCP API）
+- 使用 `uv run` 執行（自動安裝依賴）
+
+## 依賴套件
+
+腳本使用 PEP 723 inline script metadata，`uv run` 會自動安裝：
+- `requests>=2.28.0`
+- `opencc-python-reimplemented>=0.1.7`
+
+---
+
+*Version: 1.0.0*

package/botrun-c/.claude/skills/nchc-transcribe/scripts/transcribe.py

@@ -0,0 +1,522 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "requests>=2.28.0",
+#     "opencc-python-reimplemented>=0.1.7",
+#     "python-dotenv>=1.0.0",
+# ]
+# ///
+"""
+NCHC Whisper 語音轉錄工具
+使用國網中心 (NCHC) TAIDE Whisper API 進行語音轉文字，
+內建三層 Fallback 機制：NCHC → Spot VM → Cloud Run
+
+使用方式：
+uv run .claude/skills/nchc-transcribe/scripts/transcribe.py --input <AUDIO_FILE> [--output <OUTPUT_FILE>] [--model <MODEL>]
+"""
+
+import argparse
+import json
+import math
+import os
+import random
+import re
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from dotenv import load_dotenv
+import opencc
+import requests
+
+# 載入專案根目錄的 .env（往上搜尋）
+load_dotenv()
+
+# ============================================================
+# API 設定（從環境變數讀取）
+# ============================================================
+
+# NCHC (國網中心) TAIDE Whisper API
+TAIDE_API_KEY = os.environ.get("TAIDE_API_KEY", "")
+TAIDE_BASE_URL = os.environ.get("TAIDE_BASE_URL", "https://portal.genai.nchc.org.tw/api/v1")
+
+# Spot VM Whisper (Fallback 1)
+WHISPER_SPOT_VM_API_URL = os.environ.get("WHISPER_SPOT_VM_API_URL", "https://whisper-gateway-2ragcuvt3q-de.a.run.app/inference")
+WHISPER_SPOT_VM_API_KEY = os.environ.get("WHISPER_SPOT_VM_API_KEY", "")
+
+# Cloud Run Whisper (Fallback 2)
+WHISPER_CLOUDRUN_URL = os.environ.get("WHISPER_CLOUDRUN_URL", "https://whisper-transcribe-2ragcuvt3q-de.a.run.app/inference")
+WHISPER_CLOUDRUN_WEBHOOK_URL = os.environ.get("WHISPER_CLOUDRUN_WEBHOOK_URL", "")
+
+# 支援的 Whisper 模型
+NCHC_WHISPER_MODELS = {
+    "BREEZE_ASR_25": "whisper-Breeze-ASR-25",
+    "LARGE_V3": "Whisper-Large-V3",
+}
+
+DEFAULT_MODEL = NCHC_WHISPER_MODELS["BREEZE_ASR_25"]
+
+# Retry 設定
+MAX_RETRIES = 3
+REQUEST_TIMEOUT = 1200  # 20 分鐘
+
+# OpenCC 簡體轉台灣繁體轉換器（延遲初始化）
+_converter = None
+
+
+def get_converter():
+    """取得 OpenCC 簡體→繁體轉換器（延遲初始化）"""
+    global _converter
+    if _converter is None:
+        _converter = opencc.OpenCC("s2twp")
+        log("OpenCC converter initialized: Simplified → Taiwan Traditional with phrases")
+    return _converter
+
+
+# ============================================================
+# 工具函數
+# ============================================================
+
+def log(message: str) -> None:
+    """記錄處理訊息"""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    print(f"[{timestamp}] {message}", file=sys.stderr)
+
+
+def detect_mime_type(file_path: Path) -> str:
+    """根據副檔名偵測 MIME type"""
+    ext = file_path.suffix.lower()
+    mime_map = {
+        ".webm": "audio/webm",
+        ".mp3": "audio/mpeg",
+        ".mp4": "video/mp4",
+        ".m4a": "audio/mp4",
+        ".wav": "audio/wav",
+        ".ogg": "audio/ogg",
+        ".opus": "audio/opus",
+        ".aac": "audio/aac",
+        ".flac": "audio/flac",
+        ".wma": "audio/x-ms-wma",
+    }
+    return mime_map.get(ext, "application/octet-stream")
+
+
+def is_retryable_error(error_message: str) -> bool:
+    """判斷是否為可重試的錯誤"""
+    # 提取 HTTP 狀態碼
+    status_match = re.search(r"error \((\d{3})\)", error_message)
+    status_code = int(status_match.group(1)) if status_match else 0
+
+    # 5xx 伺服器錯誤或網路錯誤
+    if 500 <= status_code < 600:
+        return True
+
+    retryable_keywords = [
+        "ConnectionError",
+        "Timeout",
+        "timeout",
+        "ECONNRESET",
+        "ETIMEDOUT",
+        "Connection aborted",
+        "Connection refused",
+    ]
+    return any(keyword in error_message for keyword in retryable_keywords)
+
+
+def exponential_backoff_wait(attempt: int) -> float:
+    """計算指數退避等待時間（含 Jitter）"""
+    base_wait = math.pow(2, attempt)  # 1s, 2s, 4s
+    jitter = random.random()  # 0-1s 隨機延遲
+    return base_wait + jitter
+
+
+# ============================================================
+# 轉錄服務
+# ============================================================
+
+def transcribe_with_nchc(file_path: Path, model: str = DEFAULT_MODEL) -> str:
+    """
+    使用 NCHC (國網中心) TAIDE Whisper API 進行轉錄
+
+    Args:
+        file_path: 音訊檔案路徑
+        model: Whisper 模型名稱
+
+    Returns:
+        轉錄文字
+    """
+    url = f"{TAIDE_BASE_URL}/audio/transcriptions"
+    mime_type = detect_mime_type(file_path)
+
+    log(f"[NCHC] Transcribing: {file_path.name} ({mime_type}), model: {model}")
+
+    with open(file_path, "rb") as f:
+        files = {"file": (file_path.name, f, mime_type)}
+        data = {"model": model}
+        headers = {"Authorization": f"Bearer {TAIDE_API_KEY}"}
+
+        response = requests.post(
+            url,
+            files=files,
+            data=data,
+            headers=headers,
+            timeout=REQUEST_TIMEOUT,
+        )
+
+    if not response.ok:
+        raise RuntimeError(f"NCHC Whisper API error ({response.status_code}): {response.text}")
+
+    result = response.json()
+    text = result.get("text", "")
+    log(f"[NCHC] Success: {text[:80]}...")
+    return text
+
+
+def transcribe_with_spot_vm(file_path: Path) -> str:
+    """
+    使用 Spot VM Whisper 進行轉錄（Fallback 1）
+    自動將簡體中文轉換為台灣繁體中文
+
+    Args:
+        file_path: 音訊檔案路徑
+
+    Returns:
+        轉錄文字（繁體中文）
+    """
+    mime_type = detect_mime_type(file_path)
+
+    log(f"[Spot VM] Transcribing: {file_path.name} ({mime_type})")
+
+    with open(file_path, "rb") as f:
+        files = {"file": (file_path.name, f, mime_type)}
+        data = {"response_format": "json"}
+        headers = {"Authorization": f"Bearer {WHISPER_SPOT_VM_API_KEY}"}
+
+        response = requests.post(
+            WHISPER_SPOT_VM_API_URL,
+            files=files,
+            data=data,
+            headers=headers,
+            timeout=REQUEST_TIMEOUT,
+        )
+
+    if not response.ok:
+        raise RuntimeError(f"Spot VM Whisper API error ({response.status_code}): {response.text}")
+
+    result = response.json()
+    original_text = result.get("text", "")
+
+    # 簡體轉繁體
+    converter = get_converter()
+    converted_text = converter.convert(original_text)
+
+    log(f"[Spot VM] Success (original): {original_text[:50]}...")
+    log(f"[Spot VM] Converted to Traditional: {converted_text[:50]}...")
+    return converted_text
+
+
+def transcribe_with_cloudrun(file_path: Path) -> str:
+    """
+    使用 Cloud Run Whisper 進行轉錄（Fallback 2）
+    自動將簡體中文轉換為台灣繁體中文
+
+    Args:
+        file_path: 音訊檔案路徑
+
+    Returns:
+        轉錄文字（繁體中文）
+    """
+    mime_type = detect_mime_type(file_path)
+
+    log(f"[Cloud Run] Transcribing: {file_path.name} ({mime_type})")
+
+    # 發送 Webhook 通知（非阻塞）
+    _send_webhook(file_path.name, reason="Cloud Run Whisper fallback")
+
+    with open(file_path, "rb") as f:
+        files = {"file": (file_path.name, f, mime_type)}
+        data = {"response_format": "json", "language": "zh"}
+
+        response = requests.post(
+            WHISPER_CLOUDRUN_URL,
+            files=files,
+            data=data,
+            timeout=REQUEST_TIMEOUT,
+        )
+
+    if not response.ok:
+        raise RuntimeError(f"Cloud Run Whisper API error ({response.status_code}): {response.text}")
+
+    result = response.json()
+    original_text = result.get("text", "")
+
+    # 簡體轉繁體
+    converter = get_converter()
+    converted_text = converter.convert(original_text)
+
+    log(f"[Cloud Run] Success (original): {original_text[:50]}...")
+    log(f"[Cloud Run] Converted to Traditional: {converted_text[:50]}...")
+    return converted_text
+
+
+def _send_webhook(file_name: str, segment_info: str = "", reason: str = "") -> None:
+    """發送 Google Chat Webhook 通知（非阻塞，失敗不拋錯）"""
+    if not WHISPER_CLOUDRUN_WEBHOOK_URL:
+        return
+
+    timestamp = datetime.now().isoformat()
+    message = f"⚠️ {reason}\n時間: {timestamp}\n檔案: {file_name}"
+    if segment_info:
+        message += f"\n片段: {segment_info}"
+
+    try:
+        requests.post(
+            WHISPER_CLOUDRUN_WEBHOOK_URL,
+            json={"text": message},
+            timeout=10,
+        )
+    except Exception as e:
+        log(f"[Webhook] Failed (non-blocking): {e}")
+
+
+# ============================================================
+# Fallback 機制
+# ============================================================
+
+def transcribe_with_fallback(file_path: Path, model: str = DEFAULT_MODEL) -> str:
+    """
+    三層 Fallback 轉錄機制：
+    1. NCHC Whisper（最多 4 次嘗試）
+    2. Spot VM Whisper（最多 4 次嘗試）
+    3. Cloud Run Whisper（最多 4 次嘗試）
+
+    每層使用指數退避 + Jitter 重試策略
+
+    Args:
+        file_path: 音訊檔案路徑
+        model: NCHC Whisper 模型名稱
+
+    Returns:
+        轉錄文字
+    """
+    text = None
+    last_error = None
+
+    # === 階段 1: NCHC Whisper ===
+    log(f"Stage 1: NCHC Whisper (model: {model})")
+    nchc_failed = False
+
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            log(f"[NCHC] Attempt {attempt + 1}/{MAX_RETRIES + 1}")
+            text = transcribe_with_nchc(file_path, model)
+            log(f"[NCHC] Success!")
+            break
+        except Exception as e:
+            last_error = e
+            error_message = str(e)
+            is_last = attempt == MAX_RETRIES
+
+            if not is_retryable_error(error_message):
+                log(f"[NCHC] Non-retryable error: {error_message}")
+                log(f"[NCHC] Switching to Spot VM Whisper")
+                nchc_failed = True
+                break
+
+            if is_last:
+                log(f"[NCHC] Failed after {MAX_RETRIES + 1} attempts: {error_message}")
+                log(f"[NCHC] Falling back to Spot VM Whisper")
+                nchc_failed = True
+            else:
+                wait_time = exponential_backoff_wait(attempt)
+                log(f"[NCHC] Attempt {attempt + 1} failed (retryable), retrying in {wait_time:.1f}s...")
+                time.sleep(wait_time)
+
+    # === 階段 2: Spot VM Whisper ===
+    spot_vm_failed = False
+    if nchc_failed and text is None:
+        _send_webhook(file_path.name, reason="NCHC Whisper failed, switching to Spot VM")
+
+        log(f"Stage 2: Spot VM Whisper")
+
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                log(f"[Spot VM] Attempt {attempt + 1}/{MAX_RETRIES + 1}")
+                text = transcribe_with_spot_vm(file_path)
+                log(f"[Spot VM] Success!")
+                break
+            except Exception as e:
+                last_error = e
+                error_message = str(e)
+                is_last = attempt == MAX_RETRIES
+
+                if not is_retryable_error(error_message):
+                    log(f"[Spot VM] Non-retryable error: {error_message}")
+                    log(f"[Spot VM] Switching to Cloud Run Whisper")
+                    spot_vm_failed = True
+                    break
+
+                if is_last:
+                    log(f"[Spot VM] Failed after {MAX_RETRIES + 1} attempts: {error_message}")
+                    log(f"[Spot VM] Falling back to Cloud Run Whisper")
+                    spot_vm_failed = True
+                else:
+                    wait_time = exponential_backoff_wait(attempt)
+                    log(f"[Spot VM] Attempt {attempt + 1} failed (retryable), retrying in {wait_time:.1f}s...")
+                    time.sleep(wait_time)
+
+    # === 階段 3: Cloud Run Whisper ===
+    if (spot_vm_failed or nchc_failed) and text is None:
+        _send_webhook(file_path.name, reason="Spot VM Whisper failed, switching to Cloud Run")
+
+        log(f"Stage 3: Cloud Run Whisper")
+
+        for attempt in range(MAX_RETRIES + 1):
+            try:
+                log(f"[Cloud Run] Attempt {attempt + 1}/{MAX_RETRIES + 1}")
+                text = transcribe_with_cloudrun(file_path)
+                log(f"[Cloud Run] Success!")
+                break
+            except Exception as e:
+                last_error = e
+                error_message = str(e)
+                is_last = attempt == MAX_RETRIES
+
+                if not is_retryable_error(error_message):
+                    log(f"[Cloud Run] Non-retryable error: {error_message}")
+                    break
+
+                if is_last:
+                    log(f"[Cloud Run] Failed after {MAX_RETRIES + 1} attempts: {error_message}")
+                else:
+                    wait_time = exponential_backoff_wait(attempt)
+                    log(f"[Cloud Run] Attempt {attempt + 1} failed (retryable), retrying in {wait_time:.1f}s...")
+                    time.sleep(wait_time)
+
+    # === 返回結果 ===
+    if text is not None:
+        if text == "":
+            log("No speech detected (empty transcription)")
+        return text
+    else:
+        error_msg = str(last_error) if last_error else "Unknown error"
+        raise RuntimeError(f"All transcription attempts failed (NCHC + Spot VM + Cloud Run): {error_msg}")
+
+
+# ============================================================
+# 主程式
+# ============================================================
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="NCHC Whisper 語音轉錄工具（含三層 Fallback 機制）"
+    )
+    parser.add_argument(
+        "--input", "-i",
+        type=Path,
+        required=True,
+        help="輸入音訊檔案路徑（支援 webm, mp3, mp4, m4a, wav, ogg, aac, flac）",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        default=None,
+        help="輸出文字檔案路徑（預設輸出到 stdout）",
+    )
+    parser.add_argument(
+        "--model", "-m",
+        type=str,
+        default=DEFAULT_MODEL,
+        choices=list(NCHC_WHISPER_MODELS.values()),
+        help=f"NCHC Whisper 模型（預設: {DEFAULT_MODEL}）",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="輸出 JSON 格式（含 metadata）",
+    )
+
+    args = parser.parse_args()
+
+    # 驗證輸入檔案
+    if not args.input.exists():
+        print(f"錯誤：檔案不存在 '{args.input}'", file=sys.stderr)
+        sys.exit(1)
+
+    if not args.input.is_file():
+        print(f"錯誤：'{args.input}' 不是檔案", file=sys.stderr)
+        sys.exit(1)
+
+    # 顯示處理資訊
+    file_size = args.input.stat().st_size
+    print("=" * 60, file=sys.stderr)
+    print("NCHC Whisper Transcription Tool", file=sys.stderr)
+    print("=" * 60, file=sys.stderr)
+    log(f"Input: {args.input}")
+    log(f"Size: {file_size / 1024 / 1024:.2f} MB")
+    log(f"Model: {args.model}")
+    log(f"Fallback: NCHC -> Spot VM -> Cloud Run")
+    print("-" * 60, file=sys.stderr)
+
+    start_time = time.time()
+
+    try:
+        # 執行轉錄
+        transcribed_text = transcribe_with_fallback(args.input, args.model)
+
+        elapsed = time.time() - start_time
+
+        print("-" * 60, file=sys.stderr)
+        log(f"Transcription completed in {elapsed:.1f}s")
+        log(f"Text length: {len(transcribed_text)} characters")
+        print("=" * 60, file=sys.stderr)
+
+        # 輸出結果
+        if args.json:
+            result = {
+                "success": True,
+                "text": transcribed_text,
+                "model": args.model,
+                "file": str(args.input),
+                "file_size": file_size,
+                "elapsed_seconds": round(elapsed, 2),
+                "processed_at": datetime.now().isoformat(),
+            }
+            output_text = json.dumps(result, ensure_ascii=False, indent=2)
+        else:
+            output_text = transcribed_text
+
+        if args.output:
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            with open(args.output, "w", encoding="utf-8") as f:
+                f.write(output_text)
+            log(f"Output saved to: {args.output}")
+        else:
+            print(output_text)
+
+    except Exception as e:
+        elapsed = time.time() - start_time
+        print(f"\n錯誤：{e}", file=sys.stderr)
+        log(f"Failed after {elapsed:.1f}s")
+
+        if args.json:
+            error_result = {
+                "success": False,
+                "error": str(e),
+                "file": str(args.input),
+                "elapsed_seconds": round(elapsed, 2),
+            }
+            if args.output:
+                args.output.parent.mkdir(parents=True, exist_ok=True)
+                with open(args.output, "w", encoding="utf-8") as f:
+                    json.dump(error_result, f, ensure_ascii=False, indent=2)
+            else:
+                print(json.dumps(error_result, ensure_ascii=False, indent=2))
+
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()