botrun-horse 2.29.2 → 2.30.0

package/botrun-c/design/google-drive/05-test-plan.md

@@ -0,0 +1,507 @@
+# 測試計劃
+
+## 測試策略
+
+遵循 BDD/TDD 原則，採用金字塔測試架構：
+
+```
+        /\
+       /E2E\        Playwright 端對端測試
+      /______\
+     /  整合  \      API + Service 整合測試
+    /__________\
+   /    單元    \    Service 函數單元測試
+  /______________\
+```
+
+## 測試工具
+
+| 層級 | 工具 | 說明 |
+|------|------|------|
+| 單元測試 | Vitest | 快速、ESM 原生支援 |
+| 整合測試 | Vitest + supertest | API 端點測試 |
+| E2E 測試 | Playwright MCP | 瀏覽器自動化 |
+
+## 測試檔案結構
+
+```
+api/src/
+├── services/
+│   ├── __tests__/
+│   │   ├── gdrive-client.test.ts
+│   │   ├── gdrive-cache-manager.test.ts
+│   │   ├── gdrive-converter.test.ts
+│   │   └── gdrive-index.test.ts
+│   └── ...
+├── routes/
+│   └── __tests__/
+│       └── gdrive.test.ts
+
+web/
+├── components/gdrive/
+│   └── __tests__/
+│       ├── gdrive-selector.test.tsx
+│       ├── gdrive-add-dialog.test.tsx
+│       └── gdrive-folder-list.test.tsx
+└── hooks/
+    └── __tests__/
+        ├── useGdriveFolders.test.ts
+        └── useGdriveSync.test.ts
+
+tests/
+└── e2e/
+    └── gdrive.spec.ts    # Playwright E2E 測試
+```
+
+---
+
+## 單元測試案例
+
+### gdrive-client.mjs
+
+```typescript
+// api/src/services/__tests__/gdrive-client.test.ts
+
+describe('GdriveClient', () => {
+  describe('parseUrl', () => {
+    it('should parse standard folder URL', () => {
+      const url = 'https://drive.google.com/drive/folders/1abc123';
+      const result = parseUrl(url);
+      expect(result.folderId).toBe('1abc123');
+      expect(result.type).toBe('folder');
+    });
+
+    it('should parse shared folder URL', () => {
+      const url = 'https://drive.google.com/drive/folders/1abc123?usp=sharing';
+      const result = parseUrl(url);
+      expect(result.folderId).toBe('1abc123');
+    });
+
+    it('should parse file URL', () => {
+      const url = 'https://drive.google.com/file/d/1xyz789/view';
+      const result = parseUrl(url);
+      expect(result.fileId).toBe('1xyz789');
+      expect(result.type).toBe('file');
+    });
+
+    it('should throw on invalid URL', () => {
+      expect(() => parseUrl('https://example.com'))
+        .toThrow('Invalid Google Drive URL');
+    });
+  });
+
+  describe('listFiles', () => {
+    it('should list files in public folder', async () => {
+      const files = await listFiles('public-folder-id', 'public');
+      expect(files).toBeInstanceOf(Array);
+      expect(files[0]).toHaveProperty('id');
+      expect(files[0]).toHaveProperty('name');
+      expect(files[0]).toHaveProperty('mimeType');
+    });
+
+    it('should list files with service account', async () => {
+      const files = await listFiles('private-folder-id', 'service-account');
+      expect(files).toBeInstanceOf(Array);
+    });
+
+    it('should throw on access denied', async () => {
+      await expect(listFiles('no-access-folder'))
+        .rejects.toThrow('ACCESS_DENIED');
+    });
+  });
+
+  describe('downloadFile', () => {
+    it('should download file to specified path', async () => {
+      const result = await downloadFile('file-id', '/tmp/test.pdf');
+      expect(result.path).toBe('/tmp/test.pdf');
+      expect(result.size).toBeGreaterThan(0);
+    });
+  });
+});
+```
+
+### gdrive-cache-manager.mjs
+
+```typescript
+// api/src/services/__tests__/gdrive-cache-manager.test.ts
+
+describe('GdriveCacheManager', () => {
+  describe('needsSync', () => {
+    it('should return true for new folder', async () => {
+      const result = await needsSync('new-folder-id');
+      expect(result).toBe(true);
+    });
+
+    it('should return false if no changes', async () => {
+      // 模擬已同步的資料夾
+      await syncFolder('folder-id');
+      const result = await needsSync('folder-id');
+      expect(result).toBe(false);
+    });
+
+    it('should return true if files modified', async () => {
+      // 模擬檔案變更
+      await mockFileModified('folder-id', 'file-1');
+      const result = await needsSync('folder-id');
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('syncFolder', () => {
+    it('should download new files', async () => {
+      const result = await syncFolder('folder-id');
+      expect(result.filesUpdated).toBeGreaterThan(0);
+    });
+
+    it('should skip unchanged files', async () => {
+      await syncFolder('folder-id');
+      const result = await syncFolder('folder-id');
+      expect(result.filesSkipped).toBeGreaterThan(0);
+      expect(result.filesUpdated).toBe(0);
+    });
+
+    it('should delete removed files', async () => {
+      await syncFolder('folder-id');
+      await mockFileDeleted('folder-id', 'file-1');
+      const result = await syncFolder('folder-id');
+      expect(result.filesDeleted).toBe(1);
+    });
+  });
+
+  describe('clearCache', () => {
+    it('should remove all cached files for folder', async () => {
+      await syncFolder('folder-id');
+      await clearCache('folder-id');
+      const exists = await cacheExists('folder-id');
+      expect(exists).toBe(false);
+    });
+  });
+});
+```
+
+### gdrive-converter.mjs
+
+```typescript
+// api/src/services/__tests__/gdrive-converter.test.ts
+
+describe('GdriveConverter', () => {
+  describe('convertToMarkdown', () => {
+    it('should convert PDF to markdown', async () => {
+      const result = await convertToMarkdown('/tmp/test.pdf');
+      expect(result.path).toEndWith('.md');
+      expect(result.content).toContain('文字內容');
+    });
+
+    it('should convert DOCX to markdown', async () => {
+      const result = await convertToMarkdown('/tmp/test.docx');
+      expect(result.path).toEndWith('.md');
+    });
+
+    it('should extract ZIP contents', async () => {
+      const result = await convertToMarkdown('/tmp/archive.zip');
+      expect(result.extractedFiles).toBeInstanceOf(Array);
+    });
+
+    it('should keep TXT/MD as-is', async () => {
+      const result = await convertToMarkdown('/tmp/readme.md');
+      expect(result.converted).toBe(false);
+    });
+  });
+});
+```
+
+---
+
+## 整合測試案例
+
+### API Routes
+
+```typescript
+// api/src/routes/__tests__/gdrive.test.ts
+
+import { app } from '../../index.js';
+import request from 'supertest';
+
+describe('GET /api/gdrive/folders', () => {
+  it('should return empty list for new user', async () => {
+    const res = await request(app)
+      .get('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token');
+
+    expect(res.status).toBe(200);
+    expect(res.body.success).toBe(true);
+    expect(res.body.folders).toEqual([]);
+  });
+
+  it('should return folders list', async () => {
+    // 先新增資料夾
+    await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({ url: 'https://drive.google.com/drive/folders/test' });
+
+    const res = await request(app)
+      .get('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token');
+
+    expect(res.body.folders.length).toBe(1);
+  });
+});
+
+describe('POST /api/gdrive/folders', () => {
+  it('should add public folder', async () => {
+    const res = await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({
+        url: 'https://drive.google.com/drive/folders/public-folder',
+        type: 'public',
+        alias: '測試資料夾'
+      });
+
+    expect(res.status).toBe(201);
+    expect(res.body.folder.alias).toBe('測試資料夾');
+  });
+
+  it('should reject invalid URL', async () => {
+    const res = await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({ url: 'https://example.com' });
+
+    expect(res.status).toBe(400);
+    expect(res.body.code).toBe('INVALID_URL');
+  });
+
+  it('should reject duplicate folder', async () => {
+    const url = 'https://drive.google.com/drive/folders/dup-test';
+
+    await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({ url });
+
+    const res = await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({ url });
+
+    expect(res.status).toBe(409);
+    expect(res.body.code).toBe('FOLDER_EXISTS');
+  });
+});
+
+describe('POST /api/gdrive/sync', () => {
+  it('should sync all folders', async () => {
+    const res = await request(app)
+      .post('/api/gdrive/sync')
+      .set('Authorization', 'Bearer test-token')
+      .send({});
+
+    expect(res.status).toBe(200);
+    expect(res.body.success).toBe(true);
+  });
+
+  it('should sync specific folders', async () => {
+    const res = await request(app)
+      .post('/api/gdrive/sync')
+      .set('Authorization', 'Bearer test-token')
+      .send({ folderIds: ['folder-1', 'folder-2'] });
+
+    expect(res.status).toBe(200);
+    expect(res.body.results.length).toBe(2);
+  });
+});
+
+describe('DELETE /api/gdrive/folders/:id', () => {
+  it('should delete folder and cache', async () => {
+    // 先新增
+    await request(app)
+      .post('/api/gdrive/folders')
+      .set('Authorization', 'Bearer test-token')
+      .send({ url: 'https://drive.google.com/drive/folders/to-delete' });
+
+    // 刪除
+    const res = await request(app)
+      .delete('/api/gdrive/folders/to-delete')
+      .set('Authorization', 'Bearer test-token');
+
+    expect(res.status).toBe(200);
+    expect(res.body.deletedCache).toBe(true);
+  });
+});
+```
+
+---
+
+## E2E 測試案例 (Playwright)
+
+```typescript
+// tests/e2e/gdrive.spec.ts
+
+import { test, expect } from '@playwright/test';
+
+test.describe('Google Drive Integration', () => {
+  test.beforeEach(async ({ page }) => {
+    // 登入
+    await page.goto('/');
+    await page.click('[data-testid="login-button"]');
+    // ... 登入流程
+  });
+
+  test('should show empty state for new user', async ({ page }) => {
+    await page.click('[data-testid="gdrive-selector"]');
+    await expect(page.locator('text=目前沒有已同步的資料夾')).toBeVisible();
+  });
+
+  test('should add new folder', async ({ page }) => {
+    // 開啟選單
+    await page.click('[data-testid="gdrive-selector"]');
+    await page.click('[data-testid="gdrive-add-button"]');
+
+    // 填寫表單
+    await page.fill('[data-testid="gdrive-url-input"]',
+      'https://drive.google.com/drive/folders/test-folder');
+    await page.fill('[data-testid="gdrive-alias-input"]', '測試資料夾');
+
+    // 提交
+    await page.click('[data-testid="gdrive-add-submit"]');
+
+    // 驗證
+    await expect(page.locator('text=測試資料夾')).toBeVisible();
+  });
+
+  test('should sync folder', async ({ page }) => {
+    // 新增資料夾
+    // ...
+
+    // 點擊同步
+    await page.click('[data-testid="gdrive-sync-button"]');
+
+    // 等待同步完成
+    await expect(page.locator('[data-testid="sync-status"]'))
+      .toHaveText('已同步', { timeout: 30000 });
+  });
+
+  test('should search in Drive content', async ({ page }) => {
+    // 確保有已同步的資料夾
+    // ...
+
+    // 輸入問題
+    await page.fill('[data-testid="chat-input"]',
+      'Google Drive 裡有什麼檔案？');
+    await page.click('[data-testid="chat-submit"]');
+
+    // 驗證回應
+    await expect(page.locator('[data-testid="chat-message"]').last())
+      .toContainText('資料夾', { timeout: 30000 });
+  });
+
+  test('should delete folder', async ({ page }) => {
+    // 新增資料夾
+    // ...
+
+    // 開啟選單
+    await page.click('[data-testid="gdrive-selector"]');
+
+    // 點擊刪除
+    await page.click('[data-testid="gdrive-folder-menu"]');
+    await page.click('text=刪除');
+
+    // 確認刪除
+    await page.click('[data-testid="confirm-delete"]');
+
+    // 驗證
+    await expect(page.locator('text=測試資料夾')).not.toBeVisible();
+  });
+
+  test('should remember history', async ({ page }) => {
+    // 新增並刪除資料夾
+    // ...
+
+    // 開啟新增對話框
+    await page.click('[data-testid="gdrive-add-button"]');
+
+    // 檢查歷史記錄
+    await expect(page.locator('[data-testid="gdrive-history-item"]'))
+      .toHaveCount(1);
+  });
+});
+
+test.describe('Mobile', () => {
+  test.use({ viewport: { width: 375, height: 812 } });
+
+  test('should show drawer on mobile', async ({ page }) => {
+    await page.goto('/');
+
+    // 點擊觸發器
+    await page.click('[data-testid="gdrive-mobile-trigger"]');
+
+    // 驗證抽屜
+    await expect(page.locator('[data-testid="gdrive-drawer"]')).toBeVisible();
+  });
+});
+```
+
+---
+
+## 執行測試
+
+```bash
+# 單元測試
+pnpm test:unit
+
+# 整合測試
+pnpm test:integration
+
+# E2E 測試（需要先啟動 server）
+sh/server.sh &  # 啟動 API server
+sh/client.sh &  # 啟動前端
+pnpm test:e2e
+
+# 全部測試
+pnpm test
+```
+
+## CI/CD 整合
+
+```yaml
+# .github/workflows/test.yml
+name: Test
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run unit tests
+        run: pnpm test:unit
+
+      - name: Run integration tests
+        run: pnpm test:integration
+
+      - name: Install Playwright
+        run: pnpm exec playwright install
+
+      - name: Run E2E tests
+        run: pnpm test:e2e
+```
+
+## 測試覆蓋率目標
+
+| 層級 | 覆蓋率目標 |
+|------|-----------|
+| 單元測試 | > 80% |
+| 整合測試 | > 70% |
+| E2E 測試 | 關鍵流程 100% |

package/botrun-c/design/google-drive/README.md

@@ -0,0 +1,32 @@
+# Google Drive 整合設計文件
+
+## 專案概述
+
+本專案實作 Google Drive 整合功能，讓使用者可以：
+1. 在右上角輸入 Google Drive 資料夾網址
+2. 自動同步資料夾內容到本地快取
+3. 透過 Claude Agent SDK 問答 Google Drive 內容
+4. 支援多個資料夾管理（CRUD）
+
+## 設計文件索引
+
+| 文件 | 說明 |
+|------|------|
+| [01-architecture.md](./01-architecture.md) | 系統架構設計 |
+| [02-api-design.md](./02-api-design.md) | API 端點設計 |
+| [03-frontend-design.md](./03-frontend-design.md) | 前端 UI 設計 |
+| [04-skill-design.md](./04-skill-design.md) | Skill 問答層設計 |
+| [05-test-plan.md](./05-test-plan.md) | 測試計劃 |
+
+## 技術棧
+
+- **後端**: Hono Server + Google Drive API
+- **前端**: Next.js + React + shadcn/ui
+- **儲存**: Firestore (設定) + GCS/本地 (快取)
+- **AI**: Claude Agent SDK (Vertex AI)
+
+## 開發原則
+
+- BDD/TDD: 先寫測試再寫實作
+- SOLID: 單一職責、開閉原則
+- DRY: 不重複自己

package/botrun-c/dev/mcp-token-calculator/README.md

@@ -0,0 +1,92 @@
+# MCP Token Calculator
+
+計算所有 MCP Server Tool Definitions 的 token 使用量
+
+## 📦 安裝
+
+```bash
+cd dev/mcp-token-calculator
+npm install
+```
+
+## 🚀 使用方式
+
+### 1. 計算當前版本的 tokens
+
+```bash
+npm run calc
+```
+
+分析當前所有 8 個 MCP Server 的 tool definitions token 使用量
+
+### 2. 計算原始版本的 tokens
+
+```bash
+npm run calc:original
+```
+
+顯示優化前的原始 token 使用量
+
+### 3. 查看優化方案比較
+
+```bash
+npm run proposals
+```
+
+比較三種優化方案（極簡版、平衡版、關鍵字版）
+
+### 4. 驗證優化效果
+
+```bash
+npm run verify
+```
+
+驗證優化後的 token 數量和減少比例
+
+### 5. 測試 Schema 正確性
+
+```bash
+npm run test:schema
+```
+
+確保優化後的 inputSchema 結構與原版完全相同
+
+## 📊 工具說明
+
+| 腳本 | 說明 |
+|------|------|
+| `calculate-current-tokens.ts` | 計算當前版本的 tokens（主要使用） |
+| `calculate-mcp-tokens.ts` | 計算原始版本的 tokens（用於比較） |
+| `optimization-proposals.ts` | 三種優化方案比較 |
+| `verify-optimization.ts` | 驗證優化效果 |
+| `test-schema-correctness.ts` | 測試 schema 正確性 |
+
+## 📈 範例輸出
+
+```
+📊 MCP Server Tool Definitions - 當前 Token 使用量分析
+================================================================================
+
+總計 MCP Tools 數量: 8 個
+當前總 Token 使用量: 1,931 tokens
+平均每個 Tool: 241 tokens
+
+與原版比較：
+原版總 Token 使用量: 3,899 tokens
+當前總 Token 使用量: 1,931 tokens
+減少量: 1,968 tokens (50.5%)
+
+🎉 成功優化！減少了 50.5% 的 token 使用量
+```
+
+## 🎯 優化目標
+
+- ✅ 減少 token 使用量 50% 以上
+- ✅ 保持 schema 結構完全正確
+- ✅ 確保 Claude 能正確理解和調用
+- ✅ 功能完全不受影響
+
+## 📁 相關文件
+
+- 優化報告：`../../tmp/optimization-summary.md`
+- 分析報告：`../../tmp/mcp-token-analysis-report.md`