botrun-horse 2.29.2 → 2.30.0

package/botrun-c/.claude/skills/docx-to-markdown/scripts/convert_docx.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "pypandoc_binary>=1.13",
+# ]
+# ///
+"""
+DOCX 轉 Markdown 處理器
+將 DOCX 文件轉換為 Markdown 格式，支援批次處理多個檔案。
+
+使用方式：
+# 單一檔案
+uv run convert_docx.py --input document.docx --output output/
+
+# 多個檔案
+uv run convert_docx.py --input a.docx b.docx c.docx --output output/
+
+# 整個目錄
+uv run convert_docx.py --input documents/ --output output/
+"""
+
+import argparse
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import pypandoc
+
+
+def log_message(message: str) -> None:
+    """記錄處理訊息"""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    print(f"[{timestamp}] {message}")
+
+
+def convert_docx_to_markdown(input_path: Path, output_path: Path) -> None:
+    """
+    將單個 DOCX 檔案轉換為 Markdown
+
+    Args:
+        input_path: 輸入 DOCX 檔案路徑
+        output_path: 輸出 Markdown 檔案路徑
+    """
+    log_message(f"轉換: {input_path.name}")
+
+    # 確保輸出目錄存在
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 使用 pypandoc 轉換，使用 markdown_strict 避免奇怪的格式
+    pypandoc.convert_file(
+        str(input_path),
+        'markdown_strict',
+        outputfile=str(output_path),
+        extra_args=['--wrap=none']  # 不自動換行
+    )
+
+    log_message(f"  已輸出: {output_path}")
+
+
+def collect_docx_files(input_paths: list) -> list:
+    """
+    收集所有要處理的 DOCX 檔案
+
+    Args:
+        input_paths: 輸入路徑列表（可以是檔案或目錄）
+
+    Returns:
+        DOCX 檔案路徑列表
+    """
+    docx_files = []
+
+    for input_path in input_paths:
+        if input_path.is_file():
+            if input_path.suffix.lower() == '.docx':
+                docx_files.append(input_path)
+            else:
+                log_message(f"跳過非 DOCX 檔案: {input_path.name}")
+        elif input_path.is_dir():
+            # 掃描目錄下的所有 DOCX
+            found = sorted(input_path.glob("*.docx"))
+            log_message(f"在目錄 '{input_path}' 找到 {len(found)} 個 DOCX")
+            docx_files.extend(found)
+        else:
+            log_message(f"警告：路徑不存在 '{input_path}'")
+
+    return docx_files
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="DOCX 轉 Markdown 處理器：將 DOCX 文件轉換為 Markdown 格式"
+    )
+    parser.add_argument(
+        "--input", "-i",
+        type=Path,
+        nargs='+',
+        required=True,
+        help="輸入 DOCX 檔案或目錄（可指定多個）"
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        required=True,
+        help="輸出目錄"
+    )
+
+    args = parser.parse_args()
+
+    # 收集所有 DOCX 檔案
+    docx_files = collect_docx_files(args.input)
+
+    if not docx_files:
+        print("錯誤：找不到任何 DOCX 檔案")
+        sys.exit(1)
+
+    # 確保輸出目錄存在
+    output_dir = args.output
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # 顯示處理資訊
+    print("=" * 60)
+    print("DOCX 轉 Markdown 處理器")
+    print("=" * 60)
+    log_message(f"找到 {len(docx_files)} 個 DOCX 檔案")
+    log_message(f"輸出目錄: {output_dir}")
+    print("-" * 60)
+
+    # 批次處理所有 DOCX
+    success_count = 0
+    error_count = 0
+    results_summary = []
+
+    for idx, docx_file in enumerate(docx_files, 1):
+        print(f"\n[{idx}/{len(docx_files)}] 處理: {docx_file.name}")
+        print("-" * 40)
+
+        # 輸出檔案路徑（根據 DOCX 檔名自動產生）
+        output_md = output_dir / f"{docx_file.stem}.md"
+
+        try:
+            # 轉換 DOCX
+            convert_docx_to_markdown(docx_file, output_md)
+
+            success_count += 1
+            results_summary.append({
+                'file': docx_file.name,
+                'status': 'success',
+                'output': output_md.name
+            })
+
+        except Exception as e:
+            error_count += 1
+            results_summary.append({
+                'file': docx_file.name,
+                'status': 'error',
+                'error': str(e)
+            })
+            log_message(f"錯誤：{e}")
+
+    # 顯示總結
+    print("\n" + "=" * 60)
+    print("批次處理完成")
+    print("=" * 60)
+    log_message(f"成功: {success_count} 個")
+    log_message(f"失敗: {error_count} 個")
+    print("-" * 60)
+
+    for item in results_summary:
+        status_icon = "✓" if item['status'] == 'success' else "✗"
+        if item['status'] == 'success':
+            print(f"  {status_icon} {item['file']} → {item['output']}")
+        else:
+            print(f"  {status_icon} {item['file']} - {item['error']}")
+
+    print("=" * 60)
+
+    if error_count > 0:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/botrun-c/.claude/skills/gcp-coord-ml-ocr/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: gcp-coord-ml-ocr
+description: 使用 GCP 上架設的座標感知機器學習 OCR API 將 PDF 或圖片轉換為文字 JSON
+allowed-tools: Bash
+---
+
+# GCP 座標感知 ML OCR - 圖片/PDF 轉文字
+
+使用部署在 GCP 上的座標感知機器學習 OCR API 進行文字辨識，支援 PDF 和圖片輸入。
+
+## 功能特色
+
+- 支援 PDF 和圖片輸入（JPEG, PNG, BMP, TIFF）
+- PDF 自動轉換為多張圖片處理
+- 非同步 API 自動等待處理完成
+- 多頁結果整合為單一 JSON
+- 轉出的圖片保留供後續使用
+
+## 使用方式
+
+```bash
+uv run $OFFICIAL_SKILLS_DIR/gcp-coord-ml-ocr/scripts/ocr_processor.py \
+  --input <PDF_OR_IMAGE_PATH> \
+  --output <OUTPUT_JSON_PATH>
+```
+
+### 參數說明
+
+| 參數 | 縮寫 | 必填 | 說明 |
+|------|------|------|------|
+| `--input` | `-i` | 是 | 輸入 PDF 或圖片路徑 |
+| `--output` | `-o` | 是 | 輸出 JSON 檔案路徑 |
+| `--md` | | 否 | 同時輸出 Markdown 檔案（與 JSON 同名，副檔名為 .md） |
+
+### 範例
+
+**處理 PDF：**
+```bash
+uv run .claude/skills/gcp-coord-ml-ocr/scripts/ocr_processor.py \
+  -i data/test_cases/001/0.申請表.pdf \
+  -o data/test_results/001/0.申請表.json
+```
+
+**處理圖片：**
+```bash
+uv run .claude/skills/gcp-coord-ml-ocr/scripts/ocr_processor.py \
+  -i data/images/document.jpg \
+  -o data/output/document.json
+```
+
+**處理圖片並輸出 Markdown：**
+```bash
+uv run .claude/skills/gcp-coord-ml-ocr/scripts/ocr_processor.py \
+  -i data/images/document.jpg \
+  -o data/output/document.json \
+  --md
+```
+
+## 路徑規則
+
+| 輸入路徑包含 | 輸出目錄 |
+|-------------|---------|
+| `data/test_cases` | `data/test_results/{案例編號}/` |
+| 其他 | `data/2_產出結果/{專案}/` |
+
+## 輸出檔案
+
+處理完成後會產生：
+
+```
+data/test_results/001/
+├── 0.申請表.json           # OCR 結果 JSON
+└── [img]0.申請表/          # PDF 轉出的圖片（保留）
+    ├── 0.申請表_page_1.jpg
+    ├── 0.申請表_page_2.jpg
+    └── 0.申請表_page_3.jpg
+```
+
+## 輸出 JSON 結構
+
+```json
+{
+  "source_file": "申請表.pdf",
+  "file_type": "pdf",
+  "total_pages": 3,
+  "processed_at": "2026-01-13T12:00:00Z",
+  "pages": [
+    {
+      "page": 1,
+      "image_file": "申請表_page_1.jpg",
+      "ocr_result": {
+        "status": "succeeded",
+        "text": "頁面純文字內容...",
+        "lines": [
+          {
+            "text": "辨識的文字行...",
+            "boundingBox": [x1, y1, x2, y2, ...]
+          }
+        ]
+      }
+    }
+  ],
+  "full_text": "所有頁面合併的純文字"
+}
+```
+
+## API 說明
+
+使用座標感知 ML OCR API（非同步）：
+- **端點**: `https://app.botrun.ai/azure-ocr-api`
+- **提交**: POST `/vision/v3.2/read/analyze`
+- **取得結果**: GET `/vision/v3.2/read/analyzeResults/{operation-id}`
+- **等待機制**: 最多 4 次輪詢，每次間隔 15 秒
+
+## 支援的檔案格式
+
+| 格式 | 副檔名 |
+|------|--------|
+| PDF | .pdf |
+| JPEG | .jpg, .jpeg |
+| PNG | .png |
+| BMP | .bmp |
+| TIFF | .tiff, .tif |
+
+## 環境需求
+
+- Python 3.8+
+- 網路連線（需存取 API）
+- 使用 `uv run` 執行（自動安裝依賴）
+
+---
+
+*Version: 1.1.0*

package/botrun-c/.claude/skills/gcp-coord-ml-ocr/scripts/ocr_processor.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+#     "requests>=2.28.0",
+#     "pdf2image>=1.17.0",
+#     "Pillow>=10.0.0",
+# ]
+# ///
+"""
+GCP 座標感知 ML OCR Processor
+使用 GCP 上架設的座標感知機器學習 OCR API 將 PDF 或圖片轉換為文字 JSON
+
+使用方式：
+uv run ocr_processor.py --input <PDF_OR_IMAGE_PATH> --output <OUTPUT_JSON_PATH>
+"""
+
+import argparse
+import json
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+import requests
+
+# API 設定
+API_BASE = "https://app.botrun.ai/azure-ocr-api"
+ANALYZE_ENDPOINT = f"{API_BASE}/vision/v3.2/read/analyze"
+RESULTS_ENDPOINT = f"{API_BASE}/vision/v3.2/read/analyzeResults"
+
+# Polling 設定
+MAX_POLL_RETRIES = 4
+POLL_WAIT_SECONDS = 15
+
+# 支援的檔案格式
+IMAGE_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.tif'}
+PDF_EXTENSIONS = {'.pdf'}
+
+
+def log_message(message: str) -> None:
+    """記錄處理訊息"""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    print(f"[{timestamp}] {message}")
+
+
+def is_pdf(file_path: Path) -> bool:
+    """判斷是否為 PDF 檔案"""
+    return file_path.suffix.lower() in PDF_EXTENSIONS
+
+
+def is_image(file_path: Path) -> bool:
+    """判斷是否為圖片檔案"""
+    return file_path.suffix.lower() in IMAGE_EXTENSIONS
+
+
+def pdf_to_images(pdf_path: Path, output_dir: Path, dpi: int = 300, quality: int = 95) -> list:
+    """
+    將 PDF 轉換為多張圖片
+
+    Args:
+        pdf_path: PDF 檔案路徑
+        output_dir: 輸出目錄
+        dpi: 圖片解析度
+        quality: JPEG 品質
+
+    Returns:
+        輸出圖片路徑列表
+    """
+    from pdf2image import convert_from_path
+
+    log_message(f"開始轉換 PDF: {pdf_path.name}")
+
+    # 創建輸出目錄
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # 轉換 PDF 為圖片
+    pages = convert_from_path(pdf_path, dpi=dpi)
+    total_pages = len(pages)
+    log_message(f"PDF 共 {total_pages} 頁")
+
+    output_files = []
+    for i, page in enumerate(pages, 1):
+        output_path = output_dir / f"{pdf_path.stem}_page_{i}.jpg"
+        page.save(output_path, 'JPEG', quality=quality)
+        output_files.append(output_path)
+        log_message(f"  已保存第 {i} 頁: {output_path.name}")
+
+    return output_files
+
+
+def submit_ocr_request(image_path: Path) -> str:
+    """
+    提交 OCR 請求
+
+    Args:
+        image_path: 圖片檔案路徑
+
+    Returns:
+        operation_id
+    """
+    log_message(f"提交 OCR 請求: {image_path.name}")
+
+    with open(image_path, 'rb') as f:
+        image_data = f.read()
+
+    response = requests.post(
+        ANALYZE_ENDPOINT,
+        headers={'Content-Type': 'application/octet-stream'},
+        data=image_data
+    )
+
+    if response.status_code != 202:
+        raise RuntimeError(f"OCR 請求失敗: {response.status_code} - {response.text}")
+
+    # 從 header 取得 operation-location
+    operation_location = response.headers.get('operation-location', '')
+
+    if not operation_location:
+        raise RuntimeError("無法取得 operation-location")
+
+    # 從 URL 中提取 operation_id
+    operation_id = operation_location.split('/')[-1]
+    log_message(f"  Operation ID: {operation_id}")
+
+    return operation_id
+
+
+def poll_ocr_result(operation_id: str) -> dict:
+    """
+    輪詢 OCR 結果
+
+    Args:
+        operation_id: 操作 ID
+
+    Returns:
+        OCR 結果
+    """
+    result_url = f"{RESULTS_ENDPOINT}/{operation_id}"
+
+    for attempt in range(1, MAX_POLL_RETRIES + 1):
+        log_message(f"  輪詢結果 (第 {attempt}/{MAX_POLL_RETRIES} 次)...")
+
+        response = requests.get(result_url)
+
+        if response.status_code != 200:
+            raise RuntimeError(f"取得結果失敗: {response.status_code} - {response.text}")
+
+        result = response.json()
+        status = result.get('status', '')
+
+        if status == 'succeeded':
+            log_message(f"  OCR 處理完成")
+            return result
+        elif status == 'failed':
+            raise RuntimeError(f"OCR 處理失敗: {result}")
+        else:
+            # running 或 notStarted
+            if attempt < MAX_POLL_RETRIES:
+                log_message(f"  狀態: {status}，等待 {POLL_WAIT_SECONDS} 秒...")
+                time.sleep(POLL_WAIT_SECONDS)
+
+    raise TimeoutError(f"OCR 處理超時，已等待 {MAX_POLL_RETRIES * POLL_WAIT_SECONDS} 秒")
+
+
+def process_ocr_result(ocr_result: dict) -> dict:
+    """
+    處理 OCR 結果，提取文字和行資訊
+
+    Args:
+        ocr_result: 座標感知 ML OCR API 返回的結果
+
+    Returns:
+        處理後的結果
+    """
+    analyze_result = ocr_result.get('analyzeResult', {})
+    read_results = analyze_result.get('readResults', [])
+
+    lines = []
+    text_parts = []
+
+    for read_result in read_results:
+        for line in read_result.get('lines', []):
+            line_text = line.get('text', '')
+            bounding_box = line.get('boundingBox', [])
+
+            lines.append({
+                'text': line_text,
+                'boundingBox': bounding_box
+            })
+            text_parts.append(line_text)
+
+    return {
+        'status': ocr_result.get('status', ''),
+        'text': '\n'.join(text_parts),
+        'lines': lines
+    }
+
+
+def ocr_image(image_path: Path) -> dict:
+    """
+    對單張圖片進行 OCR
+
+    Args:
+        image_path: 圖片路徑
+
+    Returns:
+        OCR 結果
+    """
+    # 提交請求
+    operation_id = submit_ocr_request(image_path)
+
+    # 等待一下再開始輪詢
+    time.sleep(2)
+
+    # 輪詢結果
+    raw_result = poll_ocr_result(operation_id)
+
+    # 處理結果
+    return process_ocr_result(raw_result)
+
+
+def get_output_image_dir(output_path: Path, source_name: str) -> Path:
+    """
+    根據輸出路徑取得圖片輸出目錄
+
+    Args:
+        output_path: JSON 輸出路徑
+        source_name: 原始檔案名稱（不含副檔名）
+
+    Returns:
+        圖片輸出目錄
+    """
+    return output_path.parent / f"[img]{source_name}"
+
+
+def process_file(input_path: Path, output_path: Path) -> dict:
+    """
+    處理輸入檔案（PDF 或圖片）
+
+    Args:
+        input_path: 輸入檔案路徑
+        output_path: 輸出 JSON 路徑
+
+    Returns:
+        處理結果
+    """
+    source_name = input_path.stem
+
+    result = {
+        'source_file': input_path.name,
+        'file_type': 'pdf' if is_pdf(input_path) else 'image',
+        'total_pages': 0,
+        'processed_at': datetime.now().isoformat(),
+        'pages': [],
+        'full_text': ''
+    }
+
+    image_files = []
+
+    if is_pdf(input_path):
+        # PDF: 先轉換為圖片
+        image_dir = get_output_image_dir(output_path, source_name)
+        image_files = pdf_to_images(input_path, image_dir)
+    elif is_image(input_path):
+        # 圖片: 直接使用
+        image_files = [input_path]
+    else:
+        raise ValueError(f"不支援的檔案格式: {input_path.suffix}")
+
+    result['total_pages'] = len(image_files)
+
+    # 對每張圖片進行 OCR
+    all_texts = []
+
+    for i, image_file in enumerate(image_files, 1):
+        log_message(f"處理第 {i}/{len(image_files)} 頁...")
+
+        ocr_result = ocr_image(image_file)
+
+        page_result = {
+            'page': i,
+            'image_file': image_file.name,
+            'ocr_result': ocr_result
+        }
+
+        result['pages'].append(page_result)
+        all_texts.append(ocr_result.get('text', ''))
+
+    # 合併所有頁面文字
+    result['full_text'] = '\n\n'.join(all_texts)
+
+    return result
+
+
+def save_result(result: dict, output_path: Path, output_md: bool = False) -> None:
+    """儲存結果到 JSON 檔案，可選輸出 Markdown 檔案"""
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 儲存 JSON 檔案
+    with open(output_path, 'w', encoding='utf-8') as f:
+        json.dump(result, f, ensure_ascii=False, indent=2)
+
+    log_message(f"JSON 已儲存至: {output_path}")
+
+    # 若指定 --md，同時輸出 Markdown 檔案
+    if output_md:
+        md_path = output_path.with_suffix('.md')
+        full_text = result.get('full_text', '')
+
+        with open(md_path, 'w', encoding='utf-8') as f:
+            f.write(full_text)
+
+        log_message(f"Markdown 已儲存至: {md_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="使用 GCP 座標感知 ML OCR API 將 PDF 或圖片轉換為文字 JSON"
+    )
+    parser.add_argument(
+        "--input", "-i",
+        type=Path,
+        required=True,
+        help="輸入 PDF 或圖片路徑"
+    )
+    parser.add_argument(
+        "--output", "-o",
+        type=Path,
+        required=True,
+        help="輸出 JSON 檔案路徑"
+    )
+    parser.add_argument(
+        "--md",
+        action="store_true",
+        help="同時輸出 Markdown 檔案（與 JSON 同名，副檔名為 .md）"
+    )
+
+    args = parser.parse_args()
+
+    # 驗證輸入檔案
+    if not args.input.exists():
+        print(f"錯誤：檔案不存在 '{args.input}'")
+        sys.exit(1)
+
+    if not args.input.is_file():
+        print(f"錯誤：'{args.input}' 不是檔案")
+        sys.exit(1)
+
+    if not (is_pdf(args.input) or is_image(args.input)):
+        print(f"錯誤：不支援的檔案格式 '{args.input.suffix}'")
+        print(f"支援的格式：PDF, JPEG, PNG, BMP, TIFF")
+        sys.exit(1)
+
+    # 顯示處理資訊
+    print("=" * 60)
+    print("GCP 座標感知 ML OCR Processor")
+    print("=" * 60)
+    log_message(f"輸入檔案: {args.input}")
+    log_message(f"輸出路徑: {args.output}")
+    log_message(f"檔案類型: {'PDF' if is_pdf(args.input) else '圖片'}")
+    print("-" * 60)
+
+    try:
+        # 處理檔案
+        result = process_file(args.input, args.output)
+
+        # 儲存結果
+        save_result(result, args.output, output_md=args.md)
+
+        print("-" * 60)
+        log_message(f"處理完成！共 {result['total_pages']} 頁")
+        print("=" * 60)
+
+    except Exception as e:
+        print(f"\n錯誤：{e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()