botrun-horse 2.30.0 → 2.34.0

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

@@ -1,131 +0,0 @@
----
-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

@@ -1,522 +0,0 @@
-#!/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()