botrun-horse 2.29.2 → 2.30.0

package/botrun-c/.claude/skills/GoogleDrive/346/212/200/350/203/275/SKILL.md

@@ -0,0 +1,605 @@
+---
+name: GoogleDrive技能
+description: Google Drive 資料夾完整 CRUD 助理。當使用者輸入本技能的完整名稱（「GoogleDrive技能」），即代表要求 AI 載入並啟動本技能。當使用者說「Google Drive」、「雲端硬碟」、「Drive 資料夾」、「同步資料夾」、「搜尋 Drive」、「查詢文件」、「建立文件」、「更新文件」、「刪除檔案」、「版本歷史」、「還原版本」或詢問已同步資料夾中的內容時使用。支援完整 CRUD：建立、讀取、更新、刪除檔案，以及版本歷史、還原、差異比較。(v2.0.0)
+allowed-tools: Bash,Read,Grep,Glob,Edit
+bashAllowedPaths:
+  - "/tmp/$USER_ID/gdrive/"
+---
+
+# GoogleDrive 技能（v2.0.0）
+
+## ⚠️ 工具使用優先順序（必讀）
+
+> **Bash 只能執行 `node` 指令**，不能用 `ls`、`find`、`rg` 等命令！
+> 請依照以下優先順序使用工具：
+
+| 需求 | 正確做法 | ❌ 錯誤做法 |
+|------|----------|------------|
+| 列出所有檔案 | `gdrive-list.mjs`（含 files 陣列） | ~~`ls -la`~~（被阻擋） |
+| 列出特定類型檔案 | `Glob /tmp/$USER_ID/gdrive/**/*.md` | ~~`find ... -name "*.md"`~~（被阻擋） |
+| 搜尋檔案內容 | `Grep` 工具 或 `gdrive-search.mjs` | ~~`rg -C 3 "keyword"`~~（被阻擋） |
+| 讀取單一檔案 | `Read /tmp/.../file.md` | ~~`cat file.md`~~（被阻擋） |
+
+## 核心原則
+
+> **重要**：本技能配備 `Bash`, `Read`, `Grep`, `Glob` 內建工具。
+> 環境變數 `$USER_ID` 和 `$OFFICIAL_SKILLS_DIR` 由系統自動注入。
+>
+> **路徑限制**：所有操作只能在 `/tmp/$USER_ID/gdrive/` 目錄內進行（本地 SSD，速度極快）。
+>
+> **Bash 限制**：只能執行 `node` 指令，其他命令會被安全機制阻擋。
+
+---
+
+## 🎯 快速指令總覽
+
+### 📖 讀取操作（Read）
+
+| 功能 | 正確方式 |
+|------|----------|
+| 📋 列出資料夾與檔案 | `gdrive-list.mjs`（輸出含 files 陣列） |
+| 🔍 搜尋內容 | `gdrive-search.mjs` 或 `Grep` 工具 |
+| 📖 讀取檔案 | `gdrive-read.mjs` 或 `Read` 工具 |
+| 📁 列出特定類型檔案 | `Glob` 工具（例：`Glob /tmp/$USER_ID/gdrive/**/*.md`） |
+
+### ✏️ 寫入操作（Create/Update/Delete）
+
+| 功能 | 正確方式 |
+|------|----------|
+| 📝 建立新檔案 | `gdrive-create.mjs` |
+| ✏️ 更新檔案內容 | `gdrive-update.mjs` 或 `Edit` 工具 + `gdrive-sync-back.mjs` |
+| 🗑️ 刪除檔案 | `gdrive-delete.mjs` |
+| 🔄 同步本地編輯回 Drive | `gdrive-sync-back.mjs` |
+
+### 📜 版本控制
+
+| 功能 | 正確方式 |
+|------|----------|
+| 📜 查看版本歷史 | `gdrive-history.mjs` |
+| ⏪ 還原到特定版本 | `gdrive-restore.mjs` |
+| 🔍 比較版本差異 | `gdrive-diff.mjs` |
+
+---
+
+## 📋 列出已同步資料夾（gdrive-list.mjs）
+
+**用途**：列出使用者已同步的 Google Drive 資料夾
+
+### 基本用法
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-list.mjs --userId "$USER_ID"
+```
+
+### 輸出範例
+
+```json
+{
+  "userId": "abc123",
+  "cacheRoot": "/tmp/abc123/gdrive",
+  "lastUpdated": "2025-01-30T10:00:00.000Z",
+  "folders": [
+    {
+      "id": "1ABC...",
+      "name": "專案文件",
+      "alias": "工作文件",
+      "fileCount": 25,
+      "totalSize": "15.2 MB",
+      "lastSync": "2025-01-30T10:00:00.000Z",
+      "selected": true
+    }
+  ]
+}
+```
+
+---
+
+## 🔍 搜尋內容（gdrive-search.mjs）
+
+**用途**：在已同步的資料夾中搜尋關鍵字
+
+### 基本用法
+
+```bash
+# 搜尋所有選中的資料夾
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-search.mjs \
+  --userId "$USER_ID" \
+  --query "專案計畫"
+
+# 搜尋指定資料夾
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-search.mjs \
+  --userId "$USER_ID" \
+  --query "關鍵字" \
+  --folder "folderId"
+```
+
+### 輸出範例
+
+```json
+{
+  "query": "專案計畫",
+  "userId": "abc123",
+  "searchPaths": ["/tmp/abc123/gdrive/1ABC..."],
+  "totalResults": 3,
+  "results": [
+    {
+      "path": "/tmp/abc123/gdrive/1ABC.../專案規劃書.md",
+      "name": "專案規劃書.md",
+      "matches": 5,
+      "preview": "這是專案計畫的概述..."
+    }
+  ]
+}
+```
+
+---
+
+## 🔍 使用 Grep 工具搜尋
+
+**用途**：使用內建 Grep 工具進行高效搜尋（⚠️ 不要用 Bash rg 命令，會被阻擋）
+
+### 基本用法
+
+```
+# 搜尋關鍵字（使用 Grep 工具，非 Bash）
+Grep pattern="關鍵字" path="/tmp/{userId}/gdrive/"
+
+# 搜尋並顯示上下文
+Grep pattern="關鍵字" path="/tmp/{userId}/gdrive/" -C=3
+
+# 只搜尋 markdown 檔案
+Grep pattern="會議" path="/tmp/{userId}/gdrive/" glob="*.md"
+
+# 忽略大小寫
+Grep pattern="keyword" path="/tmp/{userId}/gdrive/" -i=true
+```
+
+### Grep 工具常用參數
+
+| 參數 | 說明 |
+|------|------|
+| `-C N` | 顯示前後 N 行上下文 |
+| `-i` | 忽略大小寫 |
+| `glob` | 只搜尋特定類型檔案 |
+| `output_mode` | `files_with_matches` 只列出檔案名稱 |
+
+---
+
+## 📖 讀取檔案（gdrive-read.mjs）
+
+**用途**：讀取指定檔案內容
+
+### 基本用法
+
+```bash
+# 用檔案路徑讀取
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-read.mjs \
+  --userId "$USER_ID" \
+  --file "專案規劃書.md"
+
+# 用 fileId 讀取
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-read.mjs \
+  --userId "$USER_ID" \
+  --fileId "file-id" \
+  --folderId "folder-id"
+
+# 限制讀取行數
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-read.mjs \
+  --userId "$USER_ID" \
+  --file "大檔案.md" \
+  --maxLines 100 \
+  --startLine 0
+```
+
+---
+
+## 📖 使用 Read 工具直接讀取
+
+**用途**：直接使用內建 Read 工具讀取快取檔案
+
+```
+# 直接讀取檔案（知道完整路徑時使用）
+Read /tmp/{userId}/gdrive/{folderId}/converted/檔案名稱.md
+```
+
+---
+
+## 📁 列出檔案（使用 Glob 工具）
+
+**用途**：查看資料夾結構（⚠️ 不要用 Bash `ls` 或 `find`，會被阻擋）
+
+### 使用 Glob 工具
+
+```
+# 列出所有檔案（使用 Glob 工具，非 Bash）
+Glob pattern="**/*" path="/tmp/{userId}/gdrive/"
+
+# 找所有 markdown 檔案
+Glob pattern="**/*.md" path="/tmp/{userId}/gdrive/"
+
+# 找特定資料夾的檔案
+Glob pattern="*" path="/tmp/{userId}/gdrive/{folderId}/"
+
+# 找所有 PDF 轉換後的檔案
+Glob pattern="**/converted/*.md" path="/tmp/{userId}/gdrive/"
+```
+
+### 使用 gdrive-list.mjs（推薦）
+
+`gdrive-list.mjs` 會輸出 `files` 陣列，直接列出所有檔案名稱：
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-list.mjs --userId "$USER_ID"
+```
+
+輸出範例：
+```json
+{
+  "folders": [...],
+  "files": [
+    { "name": "會議記錄.md", "folder": "專案文件", "size": "12.5 KB" }
+  ]
+}
+```
+
+---
+
+## 執行流程
+
+### 完整問答流程
+
+1. **列出資料夾** - 確認有哪些已同步的資料夾
+2. **搜尋關鍵字** - 找到相關檔案
+3. **讀取檔案** - 取得詳細內容
+4. **回答問題** - 根據內容回答使用者
+
+### 範例
+
+**使用者：** 在我的 Drive 資料夾中搜尋「專案計畫」
+
+**AI 執行：**
+
+```bash
+# Step 1：列出資料夾
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-list.mjs --userId "$USER_ID"
+
+# Step 2：搜尋關鍵字
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-search.mjs \
+  --userId "$USER_ID" \
+  --query "專案計畫"
+
+# Step 3：讀取最相關的檔案
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-read.mjs \
+  --userId "$USER_ID" \
+  --file "專案規劃書.md"
+```
+
+**或直接使用 Grep 工具：**
+
+```
+# 快速搜尋並顯示上下文（使用 Grep 工具，非 Bash）
+Grep pattern="專案計畫" path="/tmp/$USER_ID/gdrive/" -C=3
+```
+
+---
+
+## 快取目錄結構
+
+```
+/tmp/{userId}/gdrive/
+├── .index.json         # 全域索引
+├── {folderId}/         # 資料夾快取
+│   ├── .metadata.json  # 資料夾元資料
+│   ├── original/       # 原始檔案
+│   └── converted/      # 轉換後檔案（AI 友善格式）
+```
+
+---
+
+## 安全性設計
+
+1. **路徑隔離**：只能存取 `/tmp/{userId}/gdrive/` 目錄（本地 SSD）
+2. **userId 驗證**：只允許英數字（Firebase User ID 格式）
+3. **路徑遍歷防護**：自動檢測並拒絕 `..` 路徑
+4. **資料隔離**：每個使用者的資料完全隔離
+
+---
+
+## 支援的檔案格式
+
+| 原始格式 | 轉換後格式 |
+|----------|------------|
+| PDF | Markdown（文字） |
+| DOCX | Markdown |
+| XLSX/XLS | JSON |
+| PPTX | Markdown |
+| ZIP | 解壓後的檔案 |
+| TXT/MD/JSON/CSV | 原始格式 |
+
+---
+
+## 📝 建立新檔案（gdrive-create.mjs）
+
+**用途**：在 Google Drive 資料夾中建立新檔案
+
+### 基本用法
+
+```bash
+# 建立新檔案（內容直接傳入）
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-create.mjs \
+  --userId "$USER_ID" \
+  --folderId "資料夾ID" \
+  --name "新文件.md" \
+  --content "# 標題\n\n內容..."
+
+# 從本地檔案建立
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-create.mjs \
+  --userId "$USER_ID" \
+  --folderId "資料夾ID" \
+  --name "上傳檔案.txt" \
+  --file "/tmp/local-file.txt"
+
+# 覆寫已存在的檔案
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-create.mjs \
+  --userId "$USER_ID" \
+  --folderId "資料夾ID" \
+  --name "existing.md" \
+  --content "新內容" \
+  --overwrite
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "file": {
+    "id": "1ABC...",
+    "name": "新文件.md",
+    "webViewLink": "https://drive.google.com/file/d/1ABC.../view",
+    "mimeType": "text/markdown",
+    "modifiedTime": "2026-01-31T10:00:00.000Z"
+  },
+  "message": "檔案建立成功"
+}
+```
+
+---
+
+## ✏️ 更新檔案內容（gdrive-update.mjs）
+
+**用途**：更新 Google Drive 上的檔案內容
+
+### 基本用法
+
+```bash
+# 直接更新內容
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-update.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --content "# 更新後的內容"
+
+# 從本地檔案更新
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-update.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --file "/tmp/updated-content.md"
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "file": {
+    "id": "1ABC...",
+    "name": "文件.md",
+    "modifiedTime": "2026-01-31T10:30:00.000Z",
+    "revisionId": "r123"
+  },
+  "message": "檔案更新成功"
+}
+```
+
+---
+
+## 🗑️ 刪除檔案（gdrive-delete.mjs）
+
+**用途**：刪除 Google Drive 上的檔案
+
+### 基本用法
+
+```bash
+# 移到垃圾桶（預設）
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-delete.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID"
+
+# 永久刪除（不可恢復）
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-delete.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --permanent
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "permanent": false,
+  "message": "檔案已移到垃圾桶"
+}
+```
+
+---
+
+## 🔄 同步本地編輯回 Drive（gdrive-sync-back.mjs）
+
+**用途**：將使用 Edit 工具編輯的本地快取檔案同步回 Google Drive
+
+### 基本用法
+
+```bash
+# 同步指定檔案
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-sync-back.mjs \
+  --userId "$USER_ID" \
+  --file "/tmp/$USER_ID/gdrive/folderId/file.md"
+
+# 或指定 fileId
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-sync-back.mjs \
+  --userId "$USER_ID" \
+  --file "/tmp/$USER_ID/gdrive/folderId/file.md" \
+  --fileId "1ABC..."
+```
+
+### 編輯並同步的完整流程
+
+```bash
+# Step 1：使用 Edit 工具編輯本地快取檔案
+# Edit /tmp/$USER_ID/gdrive/folderId/file.md
+
+# Step 2：同步回 Google Drive
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-sync-back.mjs \
+  --userId "$USER_ID" \
+  --file "/tmp/$USER_ID/gdrive/folderId/file.md"
+```
+
+---
+
+## 📜 查看版本歷史（gdrive-history.mjs）
+
+**用途**：查看檔案的修改歷史
+
+### 基本用法
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-history.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID"
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "fileId": "1ABC...",
+  "fileName": "文件.md",
+  "mimeType": "text/markdown",
+  "totalRevisions": 3,
+  "revisions": [
+    {
+      "index": 1,
+      "revisionId": "r1",
+      "modifiedTime": "2026-01-30T10:00:00.000Z",
+      "modifiedBy": "使用者",
+      "size": "1.2 KB",
+      "keepForever": false
+    },
+    {
+      "index": 2,
+      "revisionId": "r2",
+      "modifiedTime": "2026-01-31T08:00:00.000Z",
+      "modifiedBy": "使用者",
+      "size": "1.5 KB",
+      "keepForever": false
+    }
+  ]
+}
+```
+
+---
+
+## ⏪ 還原版本（gdrive-restore.mjs）
+
+**用途**：還原檔案到之前的版本
+
+### 基本用法
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-restore.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --revisionId "r1"
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "restoredTo": "r1",
+  "newRevisionId": "r4",
+  "modifiedTime": "2026-01-31T12:00:00.000Z",
+  "message": "已還原到版本 r1"
+}
+```
+
+---
+
+## 🔍 比較版本差異（gdrive-diff.mjs）
+
+**用途**：比較兩個版本的差異
+
+### 基本用法
+
+```bash
+# 比較兩個版本
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-diff.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --v1 "r1" \
+  --v2 "r2"
+
+# 比較指定版本與最新版本
+node $OFFICIAL_SKILLS_DIR/GoogleDrive技能/scripts/gdrive-diff.mjs \
+  --userId "$USER_ID" \
+  --fileId "檔案ID" \
+  --v1 "r1"
+```
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "fileId": "1ABC...",
+  "fileName": "文件.md",
+  "v1": { "revisionId": "r1", "modifiedTime": "2026-01-30T10:00:00.000Z" },
+  "v2": { "revisionId": "r2", "modifiedTime": "2026-01-31T08:00:00.000Z" },
+  "summary": "+5 -3",
+  "additions": 5,
+  "deletions": 3,
+  "diff": "--- a/文件.md\n+++ b/文件.md\n@@ -1,3 +1,5 @@\n..."
+}
+```
+
+---
+
+## 常見問題
+
+| 錯誤訊息 | 原因 | 解決方式 |
+|----------|------|----------|
+| `No synced folders found` | 尚未同步任何資料夾 | 請先在設定中新增 Google Drive 資料夾並同步 |
+| `File not found` | 檔案路徑錯誤 | 使用 `gdrive-list.mjs` 確認資料夾 ID |
+| `Access denied` | 嘗試存取非授權路徑 | 只能存取 `/tmp/{userId}/gdrive/` 目錄 |
+| `Invalid userId format` | userId 包含非法字元 | userId 只能包含英數字 |
+| `FILE_EXISTS` | 建立檔案時名稱已存在 | 使用 `--overwrite` 參數覆寫 |
+| `PERMISSION_DENIED` | 無編輯/刪除權限 | 確認 Google Drive 資料夾的分享權限 |
+| `REVISION_NOT_FOUND` | 版本不存在 | 使用 `gdrive-history.mjs` 確認可用版本 |
+| `BINARY_FILE_NOT_SUPPORTED` | 二進位檔案不支援 diff | 二進位檔案（圖片、影片等）無法比較差異 |
+
+---
+
+## 效能優勢
+
+使用 `/tmp` SSD 路徑的效能優勢：
+
+| 操作 | GCS FUSE (`/mnt/data`) | SSD (`/tmp`) |
+|------|------------------------|--------------|
+| 讀取小檔案 | 100-500ms | 1-5ms |
+| 搜尋 (rg) | 2-10s | 0.1-0.5s |
+| 列出目錄 | 500ms-2s | 1-10ms |
+
+> 注意：Cloud Run 的 `/tmp` 是 memory-backed，效能比 GCS FUSE 快 10-100 倍。