botrun-horse 2.29.2 → 2.30.0

package/botrun-c/design/google-drive/04-skill-design.md

@@ -0,0 +1,384 @@
+# Skill 問答層設計
+
+## 目錄結構
+
+```
+.claude/skills/Google Drive技能/
+├── SKILL.md                      # 技能定義
+└── scripts/
+    ├── gdrive-search.mjs         # 搜尋快取內容
+    ├── gdrive-list.mjs           # 列出檔案結構
+    └── gdrive-read.mjs           # 讀取特定檔案
+```
+
+## SKILL.md
+
+```markdown
+---
+name: Google Drive技能
+description: Google Drive 問答助理。當使用者需要「查詢 Google Drive」、「搜尋雲端硬碟」、「找 Drive 裡的文件」時使用。支援多資料夾搜尋、相對路徑查詢。(v1.0.0)
+allowed-tools: Bash
+---
+
+# 📁 Google Drive 技能
+
+## 觸發條件
+
+- 使用者說「Google Drive」、「雲端硬碟」、「Drive 裡面」
+- 使用者詢問已同步資料夾中的檔案內容
+- 使用者要求搜尋特定關鍵字
+
+## 執行方式
+
+### 列出已同步的資料夾和檔案
+
+\`\`\`bash
+node $OFFICIAL_SKILLS_DIR/Google Drive技能/scripts/gdrive-list.mjs
+\`\`\`
+
+### 搜尋檔案內容
+
+\`\`\`bash
+node $OFFICIAL_SKILLS_DIR/Google Drive技能/scripts/gdrive-search.mjs "關鍵字"
+\`\`\`
+
+### 讀取特定檔案
+
+\`\`\`bash
+# 使用相對路徑
+node $OFFICIAL_SKILLS_DIR/Google Drive技能/scripts/gdrive-read.mjs "專案文件/report.md"
+
+# 使用檔案 ID
+node $OFFICIAL_SKILLS_DIR/Google Drive技能/scripts/gdrive-read.mjs --id "file123"
+\`\`\`
+
+## 輸出格式
+
+腳本輸出 Markdown 格式，方便 AI 閱讀：
+
+\`\`\`markdown
+## Google Drive 搜尋結果
+
+**關鍵字**: 專案進度
+**符合檔案**: 3 個
+
+### 專案文件/weekly-report.md
+
+> ...專案進度良好，已完成 80%...
+
+### 會議記錄/2025-12-20.md
+
+> ...討論專案進度，預計下週完成...
+\`\`\`
+
+## 快取位置
+
+- 本地開發: `./data/{userId}/gdrive-cache/`
+- Cloud Run: `/mnt/data/{userId}/gdrive-cache/`
+
+## 支援的檔案格式
+
+| 原始格式 | 轉換格式 | 說明 |
+|----------|----------|------|
+| PDF | Markdown | 文字擷取 |
+| DOCX | Markdown | 完整轉換 |
+| XLSX | JSON/CSV | 表格資料 |
+| PPTX | Markdown | 摘要文字 |
+| TXT/MD | 原始格式 | 直接讀取 |
+| ZIP | 解壓縮 | 遞迴處理 |
+
+## 注意事項
+
+- 需要先透過前端 UI 新增並同步資料夾
+- 如果找不到檔案，提示使用者檢查同步狀態
+- 大型檔案可能需要較長處理時間
+```
+
+## 腳本設計
+
+### gdrive-list.mjs
+
+列出所有已同步的資料夾和檔案。
+
+```javascript
+#!/usr/bin/env node
+/**
+ * gdrive-list.mjs - 列出已同步的 Google Drive 資料夾和檔案
+ *
+ * Usage: node gdrive-list.mjs [--folder <folderId>]
+ *
+ * Options:
+ *   --folder <id>  只列出特定資料夾
+ *
+ * Output: Markdown 格式的檔案樹
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// 取得快取根目錄
+function getCacheRoot() {
+  const userId = process.env.BOTRUN_USER_ID || 'default';
+  const isLocal = !process.env.CLOUD_RUN_SERVICE;
+  const dataRoot = process.env.DATA_ROOT || (isLocal ? './data' : '/mnt/data');
+  return join(dataRoot, userId, 'gdrive-cache');
+}
+
+// 讀取索引
+function readIndex() {
+  const indexPath = join(getCacheRoot(), '.index.json');
+  if (!existsSync(indexPath)) {
+    return { folders: [], files: [] };
+  }
+  return JSON.parse(readFileSync(indexPath, 'utf-8'));
+}
+
+// 主程式
+async function main() {
+  const index = readIndex();
+
+  if (index.folders.length === 0) {
+    console.log('## Google Drive 快取\n');
+    console.log('目前沒有已同步的資料夾。請先透過前端 UI 新增並同步資料夾。');
+    return;
+  }
+
+  console.log('## Google Drive 已同步資料夾\n');
+  console.log(`**最後更新**: ${index.lastUpdated}\n`);
+
+  for (const folder of index.folders) {
+    console.log(`### 📁 ${folder.name}`);
+    console.log(`- 檔案數: ${folder.fileCount}`);
+    console.log(`- 大小: ${folder.totalSize}`);
+    console.log('');
+
+    // 列出該資料夾的檔案
+    const folderFiles = index.files.filter(f => f.folderId === folder.id);
+    for (const file of folderFiles) {
+      console.log(`  - ${file.originalName}`);
+    }
+    console.log('');
+  }
+}
+
+main().catch(console.error);
+```
+
+### gdrive-search.mjs
+
+搜尋快取中的檔案內容。
+
+```javascript
+#!/usr/bin/env node
+/**
+ * gdrive-search.mjs - 搜尋 Google Drive 快取內容
+ *
+ * Usage: node gdrive-search.mjs <keyword> [--folder <id>] [--limit <n>]
+ *
+ * Options:
+ *   --folder <id>  限制搜尋範圍
+ *   --limit <n>    最多回傳幾個結果（預設 10）
+ *
+ * Output: Markdown 格式的搜尋結果
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, extname } from 'path';
+
+function getCacheRoot() {
+  const userId = process.env.BOTRUN_USER_ID || 'default';
+  const isLocal = !process.env.CLOUD_RUN_SERVICE;
+  const dataRoot = process.env.DATA_ROOT || (isLocal ? './data' : '/mnt/data');
+  return join(dataRoot, userId, 'gdrive-cache');
+}
+
+function searchInFile(filePath, keyword) {
+  if (!existsSync(filePath)) return null;
+
+  const content = readFileSync(filePath, 'utf-8');
+  const lowerContent = content.toLowerCase();
+  const lowerKeyword = keyword.toLowerCase();
+
+  if (!lowerContent.includes(lowerKeyword)) return null;
+
+  // 找出包含關鍵字的段落
+  const lines = content.split('\n');
+  const matches = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].toLowerCase().includes(lowerKeyword)) {
+      // 擷取上下文（前後各 2 行）
+      const start = Math.max(0, i - 2);
+      const end = Math.min(lines.length, i + 3);
+      const context = lines.slice(start, end).join('\n');
+      matches.push({
+        lineNumber: i + 1,
+        context
+      });
+    }
+  }
+
+  return matches.length > 0 ? matches : null;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const keyword = args.find(a => !a.startsWith('--'));
+
+  if (!keyword) {
+    console.log('Usage: node gdrive-search.mjs <keyword>');
+    process.exit(1);
+  }
+
+  const limit = parseInt(args.find((a, i) => args[i-1] === '--limit') || '10');
+  const cacheRoot = getCacheRoot();
+
+  if (!existsSync(cacheRoot)) {
+    console.log('## 搜尋結果\n');
+    console.log('目前沒有已同步的 Google Drive 資料夾。');
+    return;
+  }
+
+  console.log(`## Google Drive 搜尋結果\n`);
+  console.log(`**關鍵字**: ${keyword}\n`);
+
+  let resultCount = 0;
+  const folders = readdirSync(cacheRoot, { withFileTypes: true })
+    .filter(d => d.isDirectory() && !d.name.startsWith('.'));
+
+  for (const folder of folders) {
+    if (resultCount >= limit) break;
+
+    const folderPath = join(cacheRoot, folder.name);
+    const files = readdirSync(folderPath)
+      .filter(f => ['.md', '.txt', '.json'].includes(extname(f)));
+
+    for (const file of files) {
+      if (resultCount >= limit) break;
+
+      const filePath = join(folderPath, file);
+      const matches = searchInFile(filePath, keyword);
+
+      if (matches) {
+        resultCount++;
+        console.log(`### ${folder.name}/${file}\n`);
+        for (const match of matches.slice(0, 2)) {
+          console.log('```');
+          console.log(match.context);
+          console.log('```\n');
+        }
+      }
+    }
+  }
+
+  if (resultCount === 0) {
+    console.log(`找不到包含「${keyword}」的檔案。`);
+  } else {
+    console.log(`---\n共找到 ${resultCount} 個符合的檔案。`);
+  }
+}
+
+main().catch(console.error);
+```
+
+### gdrive-read.mjs
+
+讀取特定檔案內容。
+
+```javascript
+#!/usr/bin/env node
+/**
+ * gdrive-read.mjs - 讀取 Google Drive 快取中的檔案
+ *
+ * Usage: node gdrive-read.mjs <path>
+ *        node gdrive-read.mjs --id <fileId>
+ *
+ * Output: 檔案內容（Markdown 格式）
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, basename, dirname } from 'path';
+
+function getCacheRoot() {
+  const userId = process.env.BOTRUN_USER_ID || 'default';
+  const isLocal = !process.env.CLOUD_RUN_SERVICE;
+  const dataRoot = process.env.DATA_ROOT || (isLocal ? './data' : '/mnt/data');
+  return join(dataRoot, userId, 'gdrive-cache');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  let filePath;
+
+  if (args[0] === '--id') {
+    // 透過 ID 查找
+    const fileId = args[1];
+    const indexPath = join(getCacheRoot(), '.index.json');
+
+    if (!existsSync(indexPath)) {
+      console.log('找不到索引檔案。請先同步 Google Drive 資料夾。');
+      process.exit(1);
+    }
+
+    const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
+    const file = index.files.find(f => f.id === fileId);
+
+    if (!file) {
+      console.log(`找不到 ID 為 ${fileId} 的檔案。`);
+      process.exit(1);
+    }
+
+    filePath = join(getCacheRoot(), file.path);
+  } else {
+    // 使用相對路徑
+    filePath = join(getCacheRoot(), args[0]);
+  }
+
+  if (!existsSync(filePath)) {
+    console.log(`找不到檔案: ${filePath}`);
+    console.log('\n可能的原因：');
+    console.log('1. 檔案尚未同步');
+    console.log('2. 路徑錯誤');
+    console.log('\n請使用 gdrive-list.mjs 查看可用的檔案。');
+    process.exit(1);
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  const fileName = basename(filePath);
+
+  console.log(`## ${fileName}\n`);
+  console.log(content);
+}
+
+main().catch(console.error);
+```
+
+## 環境變數
+
+腳本需要以下環境變數：
+
+| 變數 | 說明 | 預設值 |
+|------|------|--------|
+| `BOTRUN_USER_ID` | 使用者 ID | `default` |
+| `DATA_ROOT` | 資料根目錄 | `./data` (本地) / `/mnt/data` (Cloud Run) |
+| `CLOUD_RUN_SERVICE` | Cloud Run 服務名稱 | - |
+
+## 與現有技能的整合
+
+Google Drive 技能可以與其他技能配合使用：
+
+1. **PDF 技能**: 如果快取中有 PDF，自動使用 PDF 技能分析
+2. **多模態閱讀技能**: 支援圖片內容分析
+3. **ripgrep 搜尋技能**: 進階全文搜尋
+
+```markdown
+# 使用範例
+
+使用者: 「Google Drive 裡的報告 PDF 說了什麼？」
+
+AI 執行：
+1. gdrive-search.mjs "報告" → 找到 report.pdf
+2. 如果是 PDF → 呼叫 PDF 技能
+3. 回答使用者問題
+```