botrun-horse 2.31.0 → 2.35.0

package/botrun-c/prototypes/taiwan-haiku/test-vertex-direct.ts

@@ -1,83 +0,0 @@
-/**
- * 直接測試 Vertex AI SDK（不透過 Agent SDK）
- */
-import 'dotenv/config';
-import { AnthropicVertex } from '@anthropic-ai/vertex-sdk';
-
-async function main() {
-  console.log('🚀 直接測試 Vertex AI SDK');
-  console.log('='.repeat(60));
-
-  console.log('\n📝 環境配置：');
-  console.log(`  GOOGLE_CLOUD_PROJECT: ${process.env.GOOGLE_CLOUD_PROJECT}`);
-  console.log(`  CLOUD_ML_REGION: ${process.env.CLOUD_ML_REGION}`);
-  console.log(`  ANTHROPIC_VERTEX_PROJECT_ID: ${process.env.ANTHROPIC_VERTEX_PROJECT_ID}`);
-
-  // 只測試 Haiku 4.5（使用正確的 ID 格式，無版本後綴）
-  const model = { name: 'Haiku 4.5', id: 'claude-haiku-4-5' };
-
-  // 只使用台灣區域
-  const region = 'asia-east1';
-
-  console.log(`\n${'='.repeat(60)}`);
-  console.log(`🧪 測試：${model.name} @ ${region}`);
-  console.log('='.repeat(60));
-
-  try {
-    console.log('\n🔧 初始化 AnthropicVertex client...');
-    const client = new AnthropicVertex({
-      region,
-      projectId: process.env.GOOGLE_CLOUD_PROJECT!,
-    });
-
-    console.log('✅ Client 初始化成功');
-
-    console.log('\n📤 發送測試訊息...');
-    const startTime = Date.now();
-
-    const response = await client.messages.create({
-      model: model.id,
-      max_tokens: 1024,
-      messages: [
-        {
-          role: 'user',
-          content: 'Hello! 請用繁體中文簡短回答：你是誰？',
-        },
-      ],
-    });
-
-    const duration = Date.now() - startTime;
-
-    console.log('\n📥 收到回應：');
-    console.log('='.repeat(60));
-    console.log(response.content[0].type === 'text' ? response.content[0].text : '(非文字回應)');
-    console.log('='.repeat(60));
-
-    console.log('\n📊 測試結果：');
-    console.log(`  ✅ 模型：${response.model}`);
-    console.log(`  ✅ 執行時間：${duration}ms`);
-    console.log(`  ✅ Token 使用：input=${response.usage.input_tokens}, output=${response.usage.output_tokens}`);
-    console.log(`  ✅ 區域：${region}`);
-    console.log(`  ✅ Stop Reason：${response.stop_reason}`);
-
-    console.log(`\n✅ 台灣 Vertex AI ${model.name} 測試成功！`);
-    console.log('🎉 雛形驗證完成！');
-
-  } catch (error) {
-    console.error(`\n❌ 測試失敗：`);
-    console.error(error);
-
-    if (error instanceof Error) {
-      console.error('\n錯誤詳情：');
-      console.error(`  名稱：${error.name}`);
-      console.error(`  訊息：${error.message}`);
-      if ((error as any).status) {
-        console.error(`  HTTP Status：${(error as any).status}`);
-      }
-    }
-
-    process.exit(1);
-  }
-}
-
-main().catch(console.error);

package/botrun-c/prototypes/taiwan-haiku/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
-    "outDir": "./dist",
-    "rootDir": "./",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true
-  },
-  "include": ["**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}

package/botrun-c/prototypes/web-search/FINDINGS-STAGE-1.md

@@ -1,48 +0,0 @@
-# 階段 1 發現：@anthropic-ai/vertex-sdk 套件兼容性問題
-
-## 問題現象
-
-```
-Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './core' is not defined by "exports"
-in node_modules/@anthropic-ai/sdk/package.json imported from node_modules/@anthropic-ai/vertex-sdk/client.mjs
-```
-
-## 原因分析
-
-`@anthropic-ai/vertex-sdk@0.4.3` 依賴 `@anthropic-ai/sdk@0.68.0`，但 SDK 的 package.json exports 設定不包含 `./core` 路徑。
-
-這是一個已知的套件版本兼容性問題。
-
-## 解決方案
-
-### 方案 A：改用本案現有的 Vertex AI 配置方式
-本案 `api/src/config/vertex-ai-config.ts` 已經使用環境變數設定 Vertex AI：
-
-```typescript
-export function getVertexAIEnvConfig() {
-  return {
-    ANTHROPIC_VERTEX_PROJECT_ID: process.env.GOOGLE_CLOUD_PROJECT,
-    CLOUD_ML_REGION: 'asia-east1',
-  };
-}
-```
-
-Claude Agent SDK 會自動讀取這些環境變數。
-
-### 方案 B：使用 Google Cloud Vertex AI API 直接呼叫
-使用 Google Cloud 的 REST API 直接呼叫 Claude，而不透過 Anthropic SDK。
-
-**我們選擇方案 A**，因為：
-1. 本案已經在使用這個方式
-2. Claude Agent SDK 支援 Vertex AI
-3. 不需要額外的套件依賴
-
-## 下一步
-
-跳過階段 1（純 Vertex AI SDK 測試），直接進入階段 2（使用本案現有的 Claude Agent SDK + Vertex AI 配置測試 WebSearch）。
-
-根據搜尋結果，關鍵在於：
-- 設定環境變數 `ANTHROPIC_CUSTOM_HEADERS="anthropic-beta: web-search-2025-03-05"`
-- 在 Claude Agent SDK Options 中透過 `env` 參數傳遞
-
-讓我們直接測試這個方案。

package/botrun-c/prototypes/web-search/README.md

@@ -1,46 +0,0 @@
-# Vertex AI WebSearch 雛形驗證
-
-## 目標
-驗證 Vertex AI + Haiku 4.5（台灣端點）+ WebSearch 工具的可行性，並逐步整合到 Claude Agent SDK。
-
-## 測試策略
-
-### 階段 1：Vertex AI 純 API 測試（不使用 Claude Agent SDK）
-1. **階段 1.1**：驗證 Vertex AI 基本連線（台灣端點 asia-east1）
-2. **階段 1.2**：加入 WebSearch tool definition
-3. **階段 1.3**：測試單次搜尋查詢
-
-### 階段 2：整合 Claude Agent SDK
-1. **階段 2.1**：研究如何傳遞自訂 Vertex AI client
-2. **階段 2.2**：實作並測試多輪對話 + WebSearch
-
-## 環境需求
-
-```bash
-npm install @anthropic-ai/vertex-sdk
-```
-
-環境變數：
-```bash
-ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
-CLOUD_ML_REGION=asia-east1  # 台灣端點
-```
-
-## 執行測試
-
-```bash
-# 階段 1.1：基本連線
-node stage-1.1-basic-connection.js
-
-# 階段 1.2：加入 WebSearch tool
-node stage-1.2-with-websearch.js
-
-# 階段 1.3：測試搜尋查詢
-node stage-1.3-search-query.js
-
-# 階段 2：整合 Claude Agent SDK
-node stage-2-agent-sdk.js
-```
-
-## 測試結果
-詳見各階段的 `results/` 目錄

package/botrun-c/prototypes/web-search/VERIFICATION-REPORT.md

@@ -1,310 +0,0 @@
-# Vertex AI WebSearch 雛形驗證報告
-
-**日期**：2025-11-02
-**測試者**：Claude Code
-**專案**：botrun-c
-
----
-
-## 🎯 測試目標
-
-驗證 Vertex AI + Haiku 4.5（台灣端點）+ WebSearch 工具在 Claude Agent SDK 中的可行性。
-
-## ✅ 測試結果：**成功！**
-
-### 關鍵發現
-
-**Vertex AI WebSearch 可以在 Claude Agent SDK 中正常運作！**
-
-只需要透過環境變數 `ANTHROPIC_CUSTOM_HEADERS="anthropic-beta: web-search-2025-03-05"` 即可啟用。
-
----
-
-## 📋 測試過程
-
-### 階段 1：Vertex AI 純 API 測試（已跳過）
-
-**原計畫**：使用 `@anthropic-ai/vertex-sdk` 直接測試 Vertex AI WebSearch。
-
-**遇到問題**：
-```
-Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './core' is not defined
-```
-
-**原因**：`@anthropic-ai/vertex-sdk@0.4.3` 與 `@anthropic-ai/sdk@0.68.0` 版本不兼容。
-
-**決策**：跳過階段 1，直接使用本案現有的 Claude Agent SDK + Vertex AI 配置方式。
-
----
-
-### 階段 2：Claude Agent SDK + Vertex AI + WebSearch（✅ 成功）
-
-#### 測試配置
-
-```typescript
-const sdkEnv = {
-  ...process.env,
-  // Vertex AI 配置
-  ANTHROPIC_VERTEX_PROJECT_ID: 'botrun-c',
-  CLOUD_ML_REGION: 'asia-east1',  // 台灣端點
-  // ✨ 關鍵：WebSearch beta header
-  ANTHROPIC_CUSTOM_HEADERS: 'anthropic-beta: web-search-2025-03-05',
-};
-
-const options = {
-  model: 'claude-3-5-haiku-20241022',  // 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 工具搜尋。
-請用繁體中文回應。`,
-};
-```
-
-#### 測試問題
-
-「台灣今天發生了什麼重要新聞？請使用網路搜尋功能查詢最新資訊。」
-
-#### 測試結果
-
-🎉 **Claude 主動使用了 WebSearch 工具 3 次！**
-
-```
-工具 1:
-  - Name: WebSearch
-  - Input: { "query": "台灣今日重大新聞 最新報導" }
-
-工具 2:
-  - Name: WebSearch
-  - Input: { "query": "台灣今日最新重要新聞 24小時內" }
-
-工具 3:
-  - Name: WebSearch
-  - Input: { "query": "台灣今日最新重大新聞 政治 經濟 社會 24小時內" }
-```
-
-#### 效能數據
-
-- **執行時間**：59.8 秒
-- **總事件數**：227 個
-- **工具使用次數**：3 次
-- **平台**：Vertex AI（台灣端點 asia-east1）
-- **模型**：Claude 3.5 Haiku (claude-3-5-haiku-20241022)
-
----
-
-## 🔑 關鍵成功因素
-
-### 1. 環境變數設定
-
-```bash
-ANTHROPIC_VERTEX_PROJECT_ID=botrun-c
-CLOUD_ML_REGION=asia-east1
-ANTHROPIC_CUSTOM_HEADERS=anthropic-beta: web-search-2025-03-05
-```
-
-### 2. Claude Agent SDK Options
-
-```typescript
-{
-  env: sdkEnv,  // 傳遞包含 ANTHROPIC_CUSTOM_HEADERS 的環境變數
-  allowedTools: ['WebSearch'],  // 將 WebSearch 加入白名單
-}
-```
-
-### 3. System Prompt 指引
-
-明確告訴 Claude 何時應該使用 WebSearch 工具：
-
-```
-當使用者詢問需要最新資訊的問題時，你應該主動使用 WebSearch 工具搜尋。
-```
-
----
-
-## 📊 與原本設定的差異
-
-### 目前設定（無法使用 WebSearch）
-
-```typescript
-// api/src/routes/chat.ts
-const options: Partial<Options> = {
-  model: vertexModel,
-  cwd: workingDir,
-  settingSources: ['user'],
-  allowedTools: ['Skill', 'Read', 'WebFetch', 'WebSearch'],  // ← WebSearch 在此無效
-  disallowedTools: ['Bash', 'Glob', 'Write', 'Edit', 'Grep'],
-  // ❌ 沒有設定 ANTHROPIC_CUSTOM_HEADERS
-};
-```
-
-### 修正後設定（可以使用 WebSearch）
-
-```typescript
-// api/src/routes/chat.ts
-const vertexEnv = {
-  ...getVertexAIEnvConfig(),
-  ANTHROPIC_CUSTOM_HEADERS: 'anthropic-beta: web-search-2025-03-05',  // ✅ 加入此行
-};
-
-Object.assign(process.env, vertexEnv);
-
-const options: Partial<Options> = {
-  model: vertexModel,
-  cwd: workingDir,
-  settingSources: ['user'],
-  allowedTools: ['Skill', 'Read', 'WebFetch', 'WebSearch'],  // ✅ 現在會生效
-  disallowedTools: ['Bash', 'Glob', 'Write', 'Edit', 'Grep'],
-  env: vertexEnv,  // ✅ 加入此行
-  // ... 其他設定
-};
-```
-
----
-
-## 🚀 下一步行動
-
-### 立即實作
-
-1. **修改 `api/src/config/vertex-ai-config.ts`**
-
-```typescript
-export function getVertexAIEnvConfig() {
-  return {
-    ANTHROPIC_VERTEX_PROJECT_ID: process.env.GOOGLE_CLOUD_PROJECT,
-    CLOUD_ML_REGION: 'asia-east1',
-    ANTHROPIC_CUSTOM_HEADERS: 'anthropic-beta: web-search-2025-03-05',  // ← 新增
-  };
-}
-```
-
-2. **修改 `api/src/routes/chat.ts`**
-
-```typescript
-// 第 71 行附近
-const vertexEnv = getVertexAIEnvConfig();
-Object.assign(process.env, vertexEnv);  // ← 確保這行存在
-
-const options: Partial<Options> = {
-  model: vertexModel,
-  cwd: workingDir,
-  settingSources: ['user'],
-  allowedTools: ['Skill', 'Read', 'WebFetch', 'WebSearch'],
-  disallowedTools: ['Bash', 'Glob', 'Write', 'Edit', 'Grep'],
-  permissionMode: 'bypassPermissions' as const,
-  resume: sessionId,
-  includePartialMessages: true,
-  mcpServers,
-  stderr: stderrCallback,
-  env: vertexEnv,  // ← 新增此行（重要！）
-};
-```
-
-3. **更新 System Prompt (`api/src/config/ai-prompts.ts`)**
-
-在 `getSystemPrompt()` 中加入 WebSearch 使用指引：
-
-```typescript
-export const WEBSEARCH_GUIDE = `
-<網路搜尋使用指南>
-當使用者詢問需要最新資訊的問題時（如：今天的新聞、最新消息、目前狀況等），
-你應該主動使用 WebSearch 工具搜尋網路資訊。
-
-範例觸發情境：
-- "台灣今天發生了什麼新聞？"
-- "Anthropic 最新發布的模型是什麼？"
-- "現在台北的天氣如何？"
-</網路搜尋使用指南>
-`;
-
-export function getSystemPrompt(workingDir: string = '/workspace'): string {
-  return `
-${PROMPT_SECURITY}
-${TAIWAN_STYLE}
-${WEBSEARCH_GUIDE}
-${SKILLS_USAGE_GUIDE}
-${WELCOME_MESSAGE}
-${AI_BUTTON_PROMPT}
-// ... 其他內容
-`;
-}
-```
-
-### 測試驗證
-
-完成修改後，執行：
-
-```bash
-cd /Users/40gpu/coding_projects/botrun-c/api
-SKIP_AUTH=1 npm run dev
-```
-
-然後透過前端測試：
-
-1. 詢問：「請幫我搜尋台灣今天的新聞」
-2. 觀察 Claude 是否使用 WebSearch 工具
-3. 檢查回應是否包含最新資訊
-
----
-
-## 💡 重要教訓
-
-### ✅ 做對的事
-
-1. **小步驟驗證**：從純 API 測試到 SDK 整合，逐步驗證
-2. **發現問題立即調整**：遇到 vertex-sdk 兼容性問題，立即改用本案方式
-3. **充分的 Debug Log**：每個階段都記錄詳細日誌，方便分析
-4. **參考官方文件**：Google Cloud 文件明確說明了 `anthropic-beta` header 的用法
-
-### ❌ 避免的陷阱
-
-1. **不要假設 `allowedTools: ['WebSearch']` 就夠了**
-   - 必須透過環境變數設定 `ANTHROPIC_CUSTOM_HEADERS`
-
-2. **不要忽略環境變數傳遞**
-   - `Options.env` 參數是關鍵，必須明確傳遞
-
-3. **不要依賴過時或不兼容的套件**
-   - `@anthropic-ai/vertex-sdk` 目前有兼容性問題
-   - 使用 Claude Agent SDK 的 Vertex AI 整合更穩定
-
----
-
-## 📚 參考資源
-
-1. **Google Cloud 官方文件**：
-   https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/claude/web-search
-
-2. **Claude Agent SDK GitHub Issue #10446**：
-   https://github.com/anthropics/claude-code/issues/10446
-
-3. **測試程式碼**：
-   `/Users/40gpu/coding_projects/botrun-c/prototypes/web-search/stage-2-agent-sdk-websearch.js`
-
-4. **測試日誌**：
-   `/Users/40gpu/coding_projects/botrun-c/prototypes/web-search/results/stage-2-agent-sdk-websearch.log`
-
----
-
-## 🎉 結論
-
-**Vertex AI WebSearch 在 Claude Agent SDK 中完全可行！**
-
-只需要：
-1. 設定環境變數 `ANTHROPIC_CUSTOM_HEADERS="anthropic-beta: web-search-2025-03-05"`
-2. 透過 `Options.env` 傳遞給 Claude Agent SDK
-3. 將 `WebSearch` 加入 `allowedTools`
-4. 在 System Prompt 中指引 Claude 何時使用
-
-這個方案：
-- ✅ 保留了 Vertex AI 的好處（GCP 整合、統一計費）
-- ✅ 使用台灣端點（asia-east1）
-- ✅ 完全支援 WebSearch 功能
-- ✅ 不需要額外的 MCP Server
-- ✅ 不需要切換到 Anthropic API
-
-立即實作即可讓使用者享受網路搜尋功能！