botrun-horse 2.29.2 → 2.30.0

package/botrun-c/prototypes/web-search/stage-2-agent-sdk-websearch.js

@@ -0,0 +1,265 @@
+/**
+ * 階段 2：Claude Agent SDK + Vertex AI + WebSearch
+ *
+ * 目標：
+ * - 使用本案現有的 Claude Agent SDK + Vertex AI 配置
+ * - 透過環境變數 ANTHROPIC_CUSTOM_HEADERS 啟用 WebSearch
+ * - 驗證多輪對話中是否能使用 WebSearch
+ *
+ * 關鍵發現：
+ * - ANTHROPIC_CUSTOM_HEADERS="anthropic-beta: web-search-2025-03-05"
+ * - 透過 Options.env 傳遞給 SDK
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+const RESULTS_DIR = join(process.cwd(), 'results');
+mkdirSync(RESULTS_DIR, { recursive: true });
+
+console.log('🧪 階段 2：Claude Agent SDK + Vertex AI + WebSearch');
+console.log('='.repeat(60));
+
+async function testAgentSDKWithWebSearch() {
+  const logs = [];
+
+  function log(msg) {
+    console.log(msg);
+    logs.push(`[${new Date().toISOString()}] ${msg}`);
+  }
+
+  try {
+    // 檢查環境變數
+    log('\n📋 Step 1: 檢查環境變數');
+    const projectId = process.env.GOOGLE_CLOUD_PROJECT;
+    const region = 'asia-east1';  // 台灣端點
+
+    if (!projectId) {
+      throw new Error('請設定 GOOGLE_CLOUD_PROJECT 環境變數');
+    }
+
+    log(`✅ Project ID: ${projectId}`);
+    log(`✅ Region: ${region}`);
+
+    // 工作目錄
+    const workingDir = join(tmpdir(), 'claude-agent-websearch-test');
+    mkdirSync(workingDir, { recursive: true });
+    log(`✅ Working directory: ${workingDir}`);
+
+    // 設定 Vertex AI 環境變數 + WebSearch Beta Header
+    log('\n📋 Step 2: 設定 Vertex AI + WebSearch 環境變數');
+    const sdkEnv = {
+      ...process.env,
+      // Vertex AI 配置
+      ANTHROPIC_VERTEX_PROJECT_ID: projectId,
+      CLOUD_ML_REGION: region,
+      // ✨ 關鍵：WebSearch beta header
+      ANTHROPIC_CUSTOM_HEADERS: 'anthropic-beta: web-search-2025-03-05',
+    };
+
+    log('✅ ANTHROPIC_VERTEX_PROJECT_ID:', sdkEnv.ANTHROPIC_VERTEX_PROJECT_ID);
+    log('✅ CLOUD_ML_REGION:', sdkEnv.CLOUD_ML_REGION);
+    log('✅ ANTHROPIC_CUSTOM_HEADERS:', sdkEnv.ANTHROPIC_CUSTOM_HEADERS);
+
+    // 配置 Claude Agent SDK
+    log('\n📋 Step 3: 配置 Claude Agent SDK');
+    const options = {
+      model: 'claude-haiku-4-5',  // ⚠️ 台灣端點只支援 claude-haiku-4-5（非完整版本號）
+      cwd: workingDir,
+      env: sdkEnv,  // ← 傳遞包含 ANTHROPIC_CUSTOM_HEADERS 的環境變數
+      allowedTools: ['Read', 'WebFetch', 'WebSearch'],  // 加入 WebSearch
+      disallowedTools: ['Bash', 'Glob', 'Write', 'Edit', 'Grep'],
+      permissionMode: 'bypassPermissions',
+      includePartialMessages: true,
+      systemPrompt: `你是台灣的 AI 助理。
+當使用者詢問需要最新資訊的問題時，你應該主動使用 WebSearch 工具搜尋。
+請用繁體中文回應。`,
+    };
+
+    log(`✅ Model: ${options.model}`);
+    log(`✅ Allowed tools: ${options.allowedTools.join(', ')}`);
+    log('✅ System prompt 已設定');
+    log(`✅ Env keys: ${Object.keys(sdkEnv).filter(k => k.includes('ANTHROPIC') || k.includes('VERTEX') || k.includes('CLOUD')).join(', ')}`);
+
+    // 測試搜尋查詢
+    log('\n📋 Step 4: 測試搜尋查詢');
+    log('   - 問題：台灣今天發生了什麼重要新聞？');
+    log('   - 預期：Claude 會使用 WebSearch 工具');
+
+    async function* generateMessages() {
+      yield {
+        type: 'user',
+        message: {
+          role: 'user',
+          content: '台灣今天發生了什麼重要新聞？請使用網路搜尋功能查詢最新資訊。',
+        },
+        parent_tool_use_id: null,
+        session_id: 'test-websearch-session',
+      };
+    }
+
+    const startTime = Date.now();
+    let eventCount = 0;
+    let toolUseEvents = [];
+    let textResponse = '';
+
+    log('\n📡 開始接收事件流...\n');
+
+    for await (const msg of query({ prompt: generateMessages(), options })) {
+      eventCount++;
+      const eventType = msg.type;
+      const eventSubtype = msg.subtype || 'none';
+
+      log(`Event ${eventCount}: ${eventType} (${eventSubtype})`);
+
+      // 記錄工具使用
+      if (msg.type === 'assistant' && Array.isArray(msg.message.content)) {
+        for (const block of msg.message.content) {
+          if (block.type === 'tool_use') {
+            const toolInfo = {
+              id: block.id,
+              name: block.name,
+              input: block.input,
+            };
+            toolUseEvents.push(toolInfo);
+            log(`   🔧 Tool Use: ${block.name}`);
+            log(`      ID: ${block.id}`);
+            log(`      Input: ${JSON.stringify(block.input, null, 2)}`);
+          }
+        }
+      }
+
+      // 收集文字回應
+      if (msg.type === 'stream_event' && msg.event.type === 'content_block_delta' &&
+          msg.event.delta.type === 'text_delta') {
+        textResponse += msg.event.delta.text;
+      }
+
+      // 結束
+      if (msg.type === 'result' && msg.subtype === 'success') {
+        log('\n✅ 對話完成');
+      }
+    }
+
+    const duration = Date.now() - startTime;
+
+    // 分析結果
+    log('\n' + '='.repeat(60));
+    log('📊 測試結果分析');
+    log('='.repeat(60));
+    log(`⏱️  執行時間: ${duration}ms`);
+    log(`📦 總事件數: ${eventCount}`);
+    log(`🔧 工具使用次數: ${toolUseEvents.length}`);
+
+    if (toolUseEvents.length > 0) {
+      log('\n✅ Claude 使用了工具！');
+      toolUseEvents.forEach((tool, i) => {
+        log(`\n工具 ${i + 1}:`);
+        log(`  - Name: ${tool.name}`);
+        log(`  - ID: ${tool.id}`);
+        log(`  - Input: ${JSON.stringify(tool.input, null, 2)}`);
+      });
+
+      // 檢查是否有 WebSearch
+      const hasWebSearch = toolUseEvents.some(t => t.name === 'WebSearch' || t.name === 'web_search');
+      if (hasWebSearch) {
+        log('\n🎉 成功！Claude 使用了 WebSearch 工具！');
+      } else {
+        log('\n⚠️  Claude 使用了工具，但不是 WebSearch');
+        log(`   使用的工具: ${toolUseEvents.map(t => t.name).join(', ')}`);
+      }
+    } else {
+      log('\n⚠️  Claude 沒有使用任何工具');
+    }
+
+    // 顯示文字回應（最重要！）
+    if (textResponse) {
+      log('\n📝 Claude 的完整回應：');
+      log('='.repeat(60));
+      log(textResponse);
+      log('='.repeat(60));
+      log(`\n回應總長度: ${textResponse.length} 字元`);
+    } else {
+      log('\n⚠️  沒有收集到文字回應');
+    }
+
+    // 最終結果
+    const hasWebSearch = toolUseEvents.some(t => t.name === 'WebSearch' || t.name === 'web_search');
+    if (hasWebSearch && textResponse) {
+      log('\n' + '='.repeat(60));
+      log('✅ 階段 2 測試通過！');
+      log('   - Vertex AI + Claude Agent SDK 整合成功');
+      log('   - WebSearch 工具可正常使用');
+      log('   - 台灣端點（asia-east1）運作正常');
+      log('   - 成功取得新聞內容');
+      log('='.repeat(60));
+
+      return {
+        success: true,
+        hasWebSearch: true,
+        toolUseCount: toolUseEvents.length,
+        tools: toolUseEvents,
+        duration,
+        eventCount,
+        textResponse,
+      };
+    }
+
+    log('\n' + '='.repeat(60));
+    log('⚠️  階段 2 測試結果不如預期');
+    log('   - WebSearch 工具未被使用');
+    log('   - 可能原因：');
+    log('     1. Vertex AI 不支援 WebSearch（需 Google 確認）');
+    log('     2. ANTHROPIC_CUSTOM_HEADERS 格式錯誤');
+    log('     3. Claude Agent SDK 不支援此 header');
+    log('='.repeat(60));
+
+    return {
+      success: false,
+      hasWebSearch: false,
+      toolUseCount: toolUseEvents.length,
+      tools: toolUseEvents,
+      duration,
+      eventCount,
+      textResponse: textResponse.substring(0, 500),
+    };
+
+  } catch (error) {
+    log('\n❌ 錯誤：' + error.message);
+    log('錯誤類型：' + error.constructor.name);
+    log('堆疊：' + error.stack);
+
+    log('\n' + '='.repeat(60));
+    log('❌ 階段 2 測試失敗！');
+    log('='.repeat(60));
+
+    return {
+      success: false,
+      error: error.message,
+      stack: error.stack,
+    };
+  } finally {
+    // 寫入日誌
+    const logFile = join(RESULTS_DIR, 'stage-2-agent-sdk-websearch.log');
+    writeFileSync(logFile, logs.join('\n'), 'utf-8');
+    console.log(`\n💾 日誌已儲存: ${logFile}`);
+  }
+}
+
+// 執行測試
+testAgentSDKWithWebSearch()
+  .then(result => {
+    if (result.success && result.hasWebSearch) {
+      console.log('\n🎉 成功！所有測試通過！');
+      process.exit(0);
+    } else {
+      console.log('\n⚠️  測試未達預期，請查看日誌了解詳情');
+      process.exit(2);
+    }
+  })
+  .catch(error => {
+    console.error('未預期錯誤:', error);
+    process.exit(1);
+  });

package/botrun-c/runtime-scripts/env-detect.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+
+###############################################################################
+# env-detect.sh - 環境偵測與路徑設定
+#
+# 自動偵測執行環境 (Docker vs Local) 並設定正確的路徑變數
+# 所有 pipeline 腳本都應該 source 這個檔案
+###############################################################################
+
+# 🔍 自動偵測執行環境
+if [ -f /.dockerenv ]; then
+  # Docker 環境
+  export IS_DOCKER=true
+  export PROJECT_ROOT="/app"
+else
+  # Local 環境 - 動態計算專案根目錄
+  # 從 runtime-scripts/env-detect.sh 往上一層到專案根目錄
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  export PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+  export IS_DOCKER=false
+fi
+
+# 🎯 設定常用路徑
+if [ "$IS_DOCKER" = true ]; then
+  # Docker 環境: src 直接在 /app 下
+  export API_DIR="$PROJECT_ROOT"
+  export SRC_DIR="$PROJECT_ROOT/src"
+else
+  # Local 環境: 有 api/ 子目錄
+  export API_DIR="$PROJECT_ROOT/api"
+  export SRC_DIR="$PROJECT_ROOT/api/src"
+fi
+
+export DATA_DIR="$PROJECT_ROOT/data"
+export KEYS_DIR="$PROJECT_ROOT/keys"
+
+# 📝 Debug 訊息 (可選,設定 DEBUG=1 時顯示)
+if [ "${DEBUG:-0}" = "1" ]; then
+  echo "========================================="
+  echo "🔍 Environment Detection"
+  echo "========================================="
+  echo "IS_DOCKER:    $IS_DOCKER"
+  echo "PROJECT_ROOT: $PROJECT_ROOT"
+  echo "API_DIR:      $API_DIR"
+  echo "SRC_DIR:      $SRC_DIR"
+  echo "DATA_DIR:     $DATA_DIR"
+  echo "========================================="
+  echo ""
+fi
+
+# ✅ 驗證必要目錄存在
+if [ ! -d "$PROJECT_ROOT" ]; then
+  echo "❌ Error: PROJECT_ROOT does not exist: $PROJECT_ROOT"
+  exit 1
+fi
+
+if [ ! -d "$SRC_DIR" ]; then
+  echo "❌ Error: SRC_DIR does not exist: $SRC_DIR"
+  echo "   Expected: $SRC_DIR"
+  echo "   IS_DOCKER: $IS_DOCKER"
+  echo "   This script expects to be run from the project structure:"
+  echo "   PROJECT_ROOT/sh/env-detect.sh"
+  exit 1
+fi

package/botrun-c/scripts/github-collaborator-manager.sh

@@ -0,0 +1,297 @@
+#!/bin/bash
+# ============================================
+# GitHub Collaborator 管理工具 (API 版本)
+# ============================================
+# 使用方式:
+#   export GITHUB_TOKEN="ghp_your_token_here"
+#   ./github-collaborator-manager.sh <command> [args...]
+#
+# 作者: bohachu
+# 日期: 2025-10-20
+# ============================================
+
+set -e
+
+# ==================== 配置 ====================
+OWNER="bohachu"  # ⚠️ 修改為你的 GitHub 帳號
+GITHUB_TOKEN="${GITHUB_TOKEN:-}"
+API_BASE="https://api.github.com"
+
+# ==================== 顏色輸出 ====================
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+log_info() {
+  echo -e "${BLUE}ℹ️  $1${NC}"
+}
+
+log_success() {
+  echo -e "${GREEN}✅ $1${NC}"
+}
+
+log_warning() {
+  echo -e "${YELLOW}⚠️  $1${NC}"
+}
+
+log_error() {
+  echo -e "${RED}❌ $1${NC}" >&2
+}
+
+# ==================== 檢查 Token ====================
+check_token() {
+  if [ -z "$GITHUB_TOKEN" ]; then
+    log_error "請設定 GITHUB_TOKEN 環境變數"
+    echo ""
+    echo "範例:"
+    echo "  export GITHUB_TOKEN='ghp_your_token_here'"
+    echo ""
+    echo "或使用 .env 檔案:"
+    echo "  echo 'GITHUB_TOKEN=ghp_your_token_here' > .env"
+    echo "  source .env"
+    exit 1
+  fi
+}
+
+# ==================== API 呼叫 ====================
+gh_api() {
+  local method="$1"
+  local endpoint="$2"
+  local data="${3:-}"
+
+  local curl_args=(
+    -s
+    -X "$method"
+    -H "Authorization: token $GITHUB_TOKEN"
+    -H "Accept: application/vnd.github.v3+json"
+    "$API_BASE$endpoint"
+  )
+
+  if [ -n "$data" ]; then
+    curl_args+=(-d "$data")
+  fi
+
+  curl "${curl_args[@]}"
+}
+
+# ==================== 命令實作 ====================
+
+# 列出所有 repo
+cmd_list_repos() {
+  log_info "列出 $OWNER 的所有 repo..."
+  gh_api GET "/users/$OWNER/repos?per_page=100" | jq -r '.[] | "\(.name) (\(.private | if . then "private" else "public" end))"'
+}
+
+# 列出某個 repo 的 collaborator
+cmd_list_collaborators() {
+  local repo="$1"
+  if [ -z "$repo" ]; then
+    log_error "請指定 repo 名稱"
+    exit 1
+  fi
+
+  log_info "列出 $OWNER/$repo 的 collaborators..."
+  gh_api GET "/repos/$OWNER/$repo/collaborators" | jq -r '.[] | "  - \(.login) (權限: \(.permissions | to_entries[] | select(.value == true) | .key | gsub("push"; "write") | gsub("admin"; "admin") | gsub("pull"; "read")))"'
+}
+
+# 新增 collaborator
+cmd_add_collaborator() {
+  local repo="$1"
+  local username="$2"
+  local permission="${3:-push}"  # pull, push, admin
+
+  if [ -z "$repo" ] || [ -z "$username" ]; then
+    log_error "使用方式: add <repo> <username> [permission]"
+    exit 1
+  fi
+
+  log_info "新增 $username 到 $OWNER/$repo (權限: $permission)..."
+
+  local response=$(gh_api PUT "/repos/$OWNER/$repo/collaborators/$username" "{\"permission\":\"$permission\"}")
+
+  # 檢查回應
+  if echo "$response" | jq -e '.message' > /dev/null 2>&1; then
+    local message=$(echo "$response" | jq -r '.message')
+    if [[ "$message" == *"Validation Failed"* ]] || [[ "$message" == *"Not Found"* ]]; then
+      log_error "新增失敗: $message"
+      exit 1
+    fi
+  fi
+
+  log_success "成功邀請 $username！（對方需要接受邀請）"
+}
+
+# 移除 collaborator
+cmd_remove_collaborator() {
+  local repo="$1"
+  local username="$2"
+
+  if [ -z "$repo" ] || [ -z "$username" ]; then
+    log_error "使用方式: remove <repo> <username>"
+    exit 1
+  fi
+
+  log_warning "確定要移除 $username 從 $OWNER/$repo？ (y/N)"
+  read -r confirm
+  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+    log_info "已取消"
+    exit 0
+  fi
+
+  log_info "移除 $username 從 $OWNER/$repo..."
+  gh_api DELETE "/repos/$OWNER/$repo/collaborators/$username"
+  log_success "成功移除 $username"
+}
+
+# 批次新增 collaborator 到多個 repo
+cmd_batch_add() {
+  local username="$1"
+  local permission="${2:-push}"
+
+  if [ -z "$username" ]; then
+    log_error "使用方式: batch-add <username> [permission]"
+    exit 1
+  fi
+
+  log_warning "將 $username 新增到所有 repo？ (y/N)"
+  read -r confirm
+  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+    log_info "已取消"
+    exit 0
+  fi
+
+  local repos=$(gh_api GET "/users/$OWNER/repos?per_page=100" | jq -r '.[].name')
+
+  for repo in $repos; do
+    log_info "處理 $repo..."
+    cmd_add_collaborator "$repo" "$username" "$permission" || log_warning "跳過 $repo"
+  done
+
+  log_success "批次新增完成"
+}
+
+# 檢查 Token 有效性
+cmd_verify_token() {
+  log_info "驗證 GitHub Token..."
+  local response=$(gh_api GET "/user")
+
+  if echo "$response" | jq -e '.login' > /dev/null 2>&1; then
+    local login=$(echo "$response" | jq -r '.login')
+    log_success "Token 有效！目前登入為: $login"
+  else
+    log_error "Token 無效或已過期"
+    echo "$response" | jq '.'
+    exit 1
+  fi
+}
+
+# 列出所有 repo 的 collaborator（完整報告）
+cmd_report_all() {
+  log_info "生成完整 Collaborator 報告..."
+  echo ""
+  echo "=========================================="
+  echo "GitHub Collaborator 報告"
+  echo "Owner: $OWNER"
+  echo "時間: $(date)"
+  echo "=========================================="
+  echo ""
+
+  local repos=$(gh_api GET "/users/$OWNER/repos?per_page=100" | jq -r '.[].name')
+
+  for repo in $repos; do
+    echo "🔹 $repo"
+    gh_api GET "/repos/$OWNER/$repo/collaborators" | jq -r '.[] | "    - \(.login) (\(.permissions | to_entries[] | select(.value == true) | .key))"' || echo "    (無法存取)"
+    echo ""
+  done
+}
+
+# ==================== 使用說明 ====================
+show_usage() {
+  cat << EOF
+📚 GitHub Collaborator 管理工具
+
+使用方式:
+  export GITHUB_TOKEN="ghp_your_token_here"
+  ./github-collaborator-manager.sh <command> [args...]
+
+命令:
+  verify                              驗證 Token 是否有效
+  list-repos                          列出所有 repo
+  list <repo>                         列出某個 repo 的 collaborator
+  add <repo> <username> [permission]  新增 collaborator (權限: pull, push, admin)
+  remove <repo> <username>            移除 collaborator
+  batch-add <username> [permission]   批次新增到所有 repo
+  report                              生成完整報告
+
+範例:
+  # 驗證 Token
+  ./github-collaborator-manager.sh verify
+
+  # 列出所有 repo
+  ./github-collaborator-manager.sh list-repos
+
+  # 列出某個 repo 的 collaborator
+  ./github-collaborator-manager.sh list my-repo
+
+  # 新增 collaborator (預設 push 權限)
+  ./github-collaborator-manager.sh add my-repo alice
+
+  # 新增 collaborator (admin 權限)
+  ./github-collaborator-manager.sh add my-repo bob admin
+
+  # 移除 collaborator
+  ./github-collaborator-manager.sh remove my-repo alice
+
+  # 批次新增到所有 repo
+  ./github-collaborator-manager.sh batch-add charlie push
+
+  # 生成完整報告
+  ./github-collaborator-manager.sh report
+
+權限說明:
+  pull  = 唯讀 (可以 clone、pull)
+  push  = 讀寫 (可以 push、merge PR)
+  admin = 管理員 (可以修改設定、刪除 repo)
+
+環境變數:
+  GITHUB_TOKEN  - GitHub Personal Access Token (必須)
+
+注意事項:
+  - Token 需要 'repo' 權限
+  - 新增 collaborator 後，對方需要接受邀請
+  - admin 權限請謹慎使用
+EOF
+}
+
+# ==================== Main ====================
+check_token
+
+case "${1:-}" in
+  verify)
+    cmd_verify_token
+    ;;
+  list-repos)
+    cmd_list_repos
+    ;;
+  list)
+    cmd_list_collaborators "$2"
+    ;;
+  add)
+    cmd_add_collaborator "$2" "$3" "${4:-push}"
+    ;;
+  remove)
+    cmd_remove_collaborator "$2" "$3"
+    ;;
+  batch-add)
+    cmd_batch_add "$2" "${3:-push}"
+    ;;
+  report)
+    cmd_report_all
+    ;;
+  *)
+    show_usage
+    exit 1
+    ;;
+esac