botrun-horse 2.29.2 → 2.30.0

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

@@ -0,0 +1,1093 @@
+---
+name: GitHub技能
+description: GitHub Repository 完整 CRUD 與 Git 工作流程助理。當使用者輸入本技能的完整名稱（「GitHub技能」），即代表要求 AI 載入並啟動本技能。當使用者說「GitHub」、「github」、「GitHub技能」、「clone」、「git」、「repo」、「repository」、「commit」、「push」、「branch」、「merge」、「PR」、「pull request」、「diff」、「stash」、「checkout」、「檢索」、「查找」、「搜尋 repo」、「搜尋 github」、「github 搜尋」、「github 檢索」、「找會議」、「會議記錄」、「列出檔案」、「檔案樹」、「讀取檔案」、「寫入檔案」、「刪除檔案」、「移動檔案」或詢問已連結 Repository 中的程式碼、會議、文件時使用。支援完整 Git 工作流程：Clone、Sync、Branch、Checkout、Merge、Stash、Diff、Commit、Push、Pull Request 建立/列表/檢視/合併，以及檔案 CRUD 操作。【強制觸發詞】：github、GitHub、GitHub技能、github技能。(v2.0.0)
+allowed-tools: Bash,Read,Grep,Glob,Edit
+bashAllowedPaths:
+  - "/tmp/$USER_ID/github/"
+---
+
+# GitHub 技能（v2.0.0）
+
+## 核心原則
+
+> **重要**：本技能配備 `Bash`, `Read`, `Grep`, `Glob`, `Edit` 內建工具。
+> 環境變數 `$USER_ID` 和 `$OFFICIAL_SKILLS_DIR` 由系統自動注入。
+>
+> **路徑限制**：所有操作只能在 `/tmp/$USER_ID/github/` 目錄內進行（本地 SSD，速度極快）。
+
+---
+
+## 🎯 快速指令總覽
+
+### 基本操作
+
+| 功能 | 指令 |
+|------|------|
+| 📁 列出 Repos | `github-list.mjs` |
+| ⬇️ Clone | `github-clone.mjs` |
+| 🔄 Sync | `github-sync.mjs` |
+| 📋 列出檔案樹 | `github-list-tree.mjs` |
+| 🔍 搜尋內容 | `github-search.mjs` |
+
+### 檔案 CRUD 操作
+
+| 功能 | 指令 |
+|------|------|
+| 📖 讀取檔案 | `github-read.mjs` |
+| ✏️ 寫入/建立檔案 | `github-write.mjs` |
+| 🗑️ 刪除檔案 | `github-delete-file.mjs` |
+| 📦 移動/重新命名 | `github-move.mjs` |
+
+### Git 工作流程
+
+| 功能 | 指令 |
+|------|------|
+| 🌿 建立分支 | `github-branch.mjs` |
+| 🔀 切換分支 | `github-checkout.mjs` |
+| 📋 列出分支 | `github-branches.mjs` |
+| 🗑️ 刪除分支 | `github-delete-branch.mjs` |
+| 📊 檢視差異 | `github-diff.mjs` |
+| 🔀 合併分支 | `github-merge.mjs` |
+| 📦 Stash 暫存 | `github-stash.mjs` |
+| 💾 Commit | `github-commit.mjs` |
+| ⬆️ Push | `github-push.mjs` |
+
+### Pull Request 操作
+
+| 功能 | 指令 |
+|------|------|
+| ➕ 建立 PR | `github-pr-create.mjs` |
+| 📋 列出 PR | `github-pr-list.mjs` |
+| 👁️ 檢視 PR | `github-pr-view.mjs` |
+| ✅ 合併 PR | `github-pr-merge.mjs` |
+
+---
+
+## 📋 列出檔案樹（github-list-tree.mjs）
+
+**用途**：列出 Repository 的完整檔案結構
+
+### 基本用法
+
+```bash
+# 列出所有 repos 的檔案樹
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list-tree.mjs --userId "$USER_ID"
+
+# 列出特定 repo 的檔案樹
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list-tree.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name"
+
+# 只列出特定類型檔案（例如 markdown）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list-tree.mjs \
+  --userId "$USER_ID" \
+  --glob "*.md"
+
+# 限制搜尋深度（預設 10）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list-tree.mjs \
+  --userId "$USER_ID" \
+  --depth 3
+
+# 輸出樹狀文字格式
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list-tree.mjs \
+  --userId "$USER_ID" \
+  --format tree
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID（自動注入 `$USER_ID`） |
+| `--repo` | ❌ | 指定 Repository（例如 `owner/repo`） |
+| `--glob` | ❌ | 檔案類型過濾（例如 `*.md`, `*.js`） |
+| `--depth` | ❌ | 最大搜尋深度（預設 10） |
+| `--format` | ❌ | 輸出格式：`json`（預設）或 `tree` |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "totalFiles": 42,
+  "totalDirectories": 8,
+  "results": [
+    {
+      "repo": "owner/repo",
+      "localPath": "/tmp/{userId}/github/owner/repo",
+      "files": [
+        { "type": "directory", "name": "docs", "path": "docs", "depth": 0 },
+        { "type": "file", "name": "README.md", "path": "docs/README.md", "size": 1234, "sizeHuman": "1.2KB" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 🔍 搜尋內容（github-search.mjs）
+
+**用途**：在 Repository 中搜尋關鍵字（類似 `rg -C`）
+
+### 基本用法
+
+```bash
+# 基本搜尋
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-search.mjs \
+  --userId "$USER_ID" \
+  --query "會議"
+
+# 搜尋特定 repo
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-search.mjs \
+  --userId "$USER_ID" \
+  --query "API" \
+  --repo "timeless-bowen"
+
+# 只搜尋 markdown 檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-search.mjs \
+  --userId "$USER_ID" \
+  --query "function" \
+  --glob "*.md"
+
+# 顯示上下文（類似 rg -C 3）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-search.mjs \
+  --userId "$USER_ID" \
+  --query "會議" \
+  --context 3
+
+# 多種檔案類型
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-search.mjs \
+  --userId "$USER_ID" \
+  --query "TODO" \
+  --glob "*.md,*.txt,*.js"
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--query` | ✅ | 搜尋關鍵字 |
+| `--repo` | ❌ | 指定 Repository |
+| `--glob` | ❌ | 檔案類型過濾（支援逗號分隔多種） |
+| `--context` | ❌ | 顯示上下文行數（類似 `rg -C`） |
+| `--ignoreCase` | ❌ | 不區分大小寫（預設 true） |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "query": "會議",
+  "totalMatches": 15,
+  "totalFilesScanned": 42,
+  "results": [
+    {
+      "repo": "owner/repo",
+      "localPath": "/tmp/{userId}/github/owner/repo",
+      "matchCount": 5,
+      "files": [
+        {
+          "file": "docs/會議記錄/2026-01-27.md",
+          "matches": [
+            { "line": 10, "content": "## 會議主題：產品規劃" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 使用 --context 的輸出
+
+```json
+{
+  "matches": [
+    {
+      "line": 10,
+      "content": "## 會議主題：產品規劃",
+      "context": [
+        { "lineNumber": 8, "content": "", "isMatch": false },
+        { "lineNumber": 9, "content": "---", "isMatch": false },
+        { "lineNumber": 10, "content": "## 會議主題：產品規劃", "isMatch": true },
+        { "lineNumber": 11, "content": "", "isMatch": false },
+        { "lineNumber": 12, "content": "### 出席人員", "isMatch": false }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 📖 讀取檔案（github-read.mjs）
+
+**用途**：安全地讀取 Repository 中的檔案內容
+
+### 基本用法
+
+```bash
+# 讀取完整檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-read.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "README.md"
+
+# 讀取特定行範圍
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-read.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "src/index.ts" \
+  --start 10 \
+  --end 50
+
+# 讀取深層目錄的檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-read.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "docs/guide/getting-started.md"
+
+# 純文字輸出（不包含 JSON metadata）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-read.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "README.md" \
+  --format raw
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱（例如 `owner/repo`） |
+| `--file` | ✅ | 檔案路徑（相對於 repo 根目錄） |
+| `--start` | ❌ | 起始行號（預設 1） |
+| `--end` | ❌ | 結束行號（預設全部） |
+| `--format` | ❌ | 輸出格式：`json`（預設）或 `raw` |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "file": "README.md",
+  "fileType": "markdown",
+  "fileSize": 2048,
+  "fileSizeHuman": "2.0KB",
+  "totalLines": 100,
+  "startLine": 1,
+  "endLine": 100,
+  "linesReturned": 100,
+  "modifiedAt": "2026-01-31T03:00:00.000Z",
+  "content": "# Project Title\n\nDescription...",
+  "hasMoreBefore": false,
+  "hasMoreAfter": false
+}
+```
+
+### 安全限制
+
+- ❌ 禁止路徑遍歷（`../`）
+- ❌ 禁止絕對路徑
+- ❌ 最大檔案大小：10MB
+- ❌ 最大行數：5000 行
+- ✅ 只能存取使用者自己的 GitHub 目錄
+
+---
+
+## 📁 列出 Repos（github-list.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-list.mjs --userId "$USER_ID"
+```
+
+**輸出範例：**
+```json
+{
+  "success": true,
+  "repos": [
+    {
+      "repoFullName": "owner/repo",
+      "localPath": "/tmp/user123/github/owner/repo",
+      "currentBranch": "main",
+      "isCloned": true
+    }
+  ],
+  "clonedCount": 1,
+  "needsClone": [],
+  "needsCloneCount": 0
+}
+```
+
+---
+
+## ⬇️ Clone Repository（github-clone.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-clone.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name"
+```
+
+---
+
+## 🔄 Sync（github-sync.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-sync.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name"
+```
+
+---
+
+## 🌿 建立分支（github-branch.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-branch.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name" \
+  --branch "feature/new-feature"
+```
+
+---
+
+## 💾 Commit（github-commit.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-commit.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name" \
+  --message "feat: add new feature"
+```
+
+---
+
+## ⬆️ Push（github-push.mjs）
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-push.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo-name"
+```
+
+---
+
+## ✏️ 寫入/建立檔案（github-write.mjs）
+
+**用途**：建立新檔案或更新現有檔案內容
+
+### 基本用法
+
+```bash
+# 建立新檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-write.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "docs/new-file.md" \
+  --content "# New Document\n\nContent here..."
+
+# 覆蓋現有檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-write.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "README.md" \
+  --content "# Updated README\n\nNew content..."
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱（例如 `owner/repo`） |
+| `--file` | ✅ | 檔案路徑（相對於 repo 根目錄） |
+| `--content` | ✅ | 檔案內容 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "file": "docs/new-file.md",
+  "action": "created",
+  "message": "File 'docs/new-file.md' created successfully"
+}
+```
+
+---
+
+## 🗑️ 刪除檔案（github-delete-file.mjs）
+
+**用途**：刪除 Repository 中的檔案
+
+### 基本用法
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-delete-file.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --file "docs/old-file.md"
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--file` | ✅ | 要刪除的檔案路徑 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "file": "docs/old-file.md",
+  "message": "File 'docs/old-file.md' deleted successfully"
+}
+```
+
+---
+
+## 📦 移動/重新命名檔案（github-move.mjs）
+
+**用途**：移動或重新命名檔案
+
+### 基本用法
+
+```bash
+# 重新命名檔案
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-move.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --source "old-name.md" \
+  --destination "new-name.md"
+
+# 移動檔案到不同目錄
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-move.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --source "file.md" \
+  --destination "docs/file.md"
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--source` | ✅ | 原始檔案路徑 |
+| `--destination` | ✅ | 目標檔案路徑 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "source": "old-name.md",
+  "destination": "new-name.md",
+  "message": "File moved from 'old-name.md' to 'new-name.md'"
+}
+```
+
+---
+
+## 📊 檢視差異（github-diff.mjs）
+
+**用途**：檢視工作目錄或分支間的差異
+
+### 基本用法
+
+```bash
+# 檢視工作目錄與 HEAD 的差異
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-diff.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo"
+
+# 檢視已暫存的變更
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-diff.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --staged
+
+# 比較兩個分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-diff.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --base "main" \
+  --compare "feature-branch"
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--staged` | ❌ | 只顯示已暫存的變更 |
+| `--base` | ❌ | 基準分支（用於比較） |
+| `--compare` | ❌ | 比較分支 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "files": [
+    {
+      "file": "src/index.ts",
+      "status": "modified",
+      "additions": 10,
+      "deletions": 5
+    }
+  ],
+  "summary": {
+    "filesChanged": 3,
+    "insertions": 25,
+    "deletions": 12
+  }
+}
+```
+
+---
+
+## 📋 列出分支（github-branches.mjs）
+
+**用途**：列出 Repository 的所有分支
+
+### 基本用法
+
+```bash
+# 列出本地分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-branches.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo"
+
+# 包含遠端分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-branches.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --all
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--all` | ❌ | 包含遠端分支 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "currentBranch": "main",
+  "branches": [
+    { "name": "main", "isCurrent": true, "isRemote": false },
+    { "name": "develop", "isCurrent": false, "isRemote": false },
+    { "name": "origin/main", "isCurrent": false, "isRemote": true }
+  ]
+}
+```
+
+---
+
+## 🔀 切換分支（github-checkout.mjs）
+
+**用途**：切換到指定分支
+
+### 基本用法
+
+```bash
+# 切換到現有分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-checkout.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --branch "develop"
+
+# 建立並切換到新分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-checkout.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --branch "feature/new-feature" \
+  --create
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--branch` | ✅ | 目標分支名稱 |
+| `--create` | ❌ | 如果分支不存在則建立 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "branch": "develop",
+  "previousBranch": "main",
+  "message": "Switched to branch 'develop'"
+}
+```
+
+---
+
+## 🗑️ 刪除分支（github-delete-branch.mjs）
+
+**用途**：刪除本地分支
+
+### 基本用法
+
+```bash
+# 刪除分支（安全模式，未合併會失敗）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-delete-branch.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --branch "feature/old-feature"
+
+# 強制刪除（即使未合併）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-delete-branch.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --branch "feature/old-feature" \
+  --force
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--branch` | ✅ | 要刪除的分支名稱 |
+| `--force` | ❌ | 強制刪除（即使未合併） |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "branch": "feature/old-feature",
+  "message": "Branch 'feature/old-feature' deleted successfully"
+}
+```
+
+---
+
+## 🔀 合併分支（github-merge.mjs）
+
+**用途**：將指定分支合併到當前分支
+
+### 基本用法
+
+```bash
+# 合併分支
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-merge.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --branch "feature/new-feature"
+
+# 放棄合併（發生衝突時）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-merge.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --abort
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--branch` | ❌ | 要合併的分支（與 --abort 二選一） |
+| `--abort` | ❌ | 放棄當前合併 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "merged": true,
+  "message": "Merged branch 'feature/new-feature' into 'main'"
+}
+```
+
+### 衝突時的輸出
+
+```json
+{
+  "success": false,
+  "hasConflicts": true,
+  "conflictedFiles": ["src/index.ts", "README.md"],
+  "message": "Merge conflict detected. Resolve conflicts and commit, or use --abort"
+}
+```
+
+---
+
+## 📦 Stash 暫存（github-stash.mjs）
+
+**用途**：暫存工作目錄的變更
+
+### 基本用法
+
+```bash
+# 暫存變更
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-stash.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --action save \
+  --message "WIP: feature implementation"
+
+# 恢復最新的暫存
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-stash.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --action pop
+
+# 列出所有暫存
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-stash.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --action list
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--action` | ✅ | 操作類型：`save`、`pop`、`list` |
+| `--message` | ❌ | 暫存訊息（僅用於 save） |
+
+### 輸出範例（list）
+
+```json
+{
+  "success": true,
+  "repo": "owner/repo",
+  "stashes": [
+    {
+      "index": 0,
+      "message": "WIP: feature implementation",
+      "branch": "feature/new-feature"
+    }
+  ]
+}
+```
+
+---
+
+## ➕ 建立 Pull Request（github-pr-create.mjs）
+
+**用途**：建立新的 Pull Request
+
+### 基本用法
+
+```bash
+# 建立 PR
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-create.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --title "feat: Add new feature" \
+  --head "feature/new-feature" \
+  --base "main" \
+  --body "## Summary\n\n- Added new feature\n- Updated tests"
+
+# 建立 Draft PR
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-create.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --title "WIP: New feature" \
+  --head "feature/wip" \
+  --base "main" \
+  --draft
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--title` | ✅ | PR 標題 |
+| `--head` | ✅ | 來源分支 |
+| `--base` | ✅ | 目標分支 |
+| `--body` | ❌ | PR 描述 |
+| `--draft` | ❌ | 建立為 Draft PR |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "number": 42,
+  "title": "feat: Add new feature",
+  "htmlUrl": "https://github.com/owner/repo/pull/42",
+  "head": "feature/new-feature",
+  "base": "main",
+  "message": "Pull request #42 created successfully"
+}
+```
+
+---
+
+## 📋 列出 Pull Requests（github-pr-list.mjs）
+
+**用途**：列出 Repository 的 Pull Requests
+
+### 基本用法
+
+```bash
+# 列出開啟的 PR
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-list.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo"
+
+# 列出所有 PR（包含已關閉）
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-list.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --state all
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--state` | ❌ | 狀態篩選：`open`（預設）、`closed`、`all` |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "state": "open",
+  "pullRequests": [
+    {
+      "number": 42,
+      "title": "feat: Add new feature",
+      "state": "open",
+      "user": "contributor",
+      "head": "feature/new-feature",
+      "base": "main",
+      "createdAt": "2026-01-31T10:00:00Z"
+    }
+  ],
+  "totalCount": 1
+}
+```
+
+---
+
+## 👁️ 檢視 Pull Request（github-pr-view.mjs）
+
+**用途**：檢視特定 Pull Request 的詳細資訊
+
+### 基本用法
+
+```bash
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-view.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --number 42
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--number` | ✅ | PR 編號 |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "number": 42,
+  "title": "feat: Add new feature",
+  "state": "open",
+  "user": "contributor",
+  "body": "## Summary\n\n- Added new feature\n- Updated tests",
+  "head": "feature/new-feature",
+  "base": "main",
+  "mergeable": true,
+  "createdAt": "2026-01-31T10:00:00Z",
+  "updatedAt": "2026-01-31T12:00:00Z"
+}
+```
+
+---
+
+## ✅ 合併 Pull Request（github-pr-merge.mjs）
+
+**用途**：合併 Pull Request
+
+### 基本用法
+
+```bash
+# 使用預設 merge commit
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-merge.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --number 42
+
+# 使用 squash merge
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-merge.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --number 42 \
+  --method squash
+
+# 使用 rebase merge
+node $OFFICIAL_SKILLS_DIR/GitHub技能/scripts/github-pr-merge.mjs \
+  --userId "$USER_ID" \
+  --repo "owner/repo" \
+  --number 42 \
+  --method rebase
+```
+
+### 參數說明
+
+| 參數 | 必填 | 說明 |
+|------|------|------|
+| `--userId` | ✅ | 使用者 ID |
+| `--repo` | ✅ | Repository 名稱 |
+| `--number` | ✅ | PR 編號 |
+| `--method` | ❌ | 合併方式：`merge`（預設）、`squash`、`rebase` |
+
+### 輸出範例
+
+```json
+{
+  "success": true,
+  "pullNumber": 42,
+  "mergeMethod": "squash",
+  "sha": "abc123def456...",
+  "message": "Pull request #42 merged successfully"
+}
+```
+
+---
+
+## 🎯 使用情境對照表
+
+### 基本操作
+
+| 使用者意圖 | 執行腳本 |
+|-----------|---------|
+| 「列出 repos」「有哪些 repo」 | `github-list.mjs` |
+| 「clone xxx」「下載 xxx」 | `github-clone.mjs --repo "xxx"` |
+| 「同步」「pull」「更新」 | `github-sync.mjs` |
+| 「列出所有檔案」「檔案樹」「有哪些檔案」 | `github-list-tree.mjs` |
+| 「搜尋 xxx」「找 xxx」「github 檢索」 | `github-search.mjs --query "xxx"` |
+
+### 檔案 CRUD 操作
+
+| 使用者意圖 | 執行腳本 |
+|-----------|---------|
+| 「讀取 xxx 檔案」「打開 xxx」「查看 xxx」 | `github-read.mjs --file "xxx"` |
+| 「建立檔案」「寫入檔案」「新增 xxx」 | `github-write.mjs --file "xxx" --content "..."` |
+| 「刪除檔案」「移除 xxx」 | `github-delete-file.mjs --file "xxx"` |
+| 「移動檔案」「重新命名」「改名」 | `github-move.mjs --source "a" --destination "b"` |
+
+### Git 工作流程
+
+| 使用者意圖 | 執行腳本 |
+|-----------|---------|
+| 「建立分支」「新分支」 | `github-branch.mjs` |
+| 「切換分支」「checkout」 | `github-checkout.mjs --branch "xxx"` |
+| 「列出分支」「有哪些 branch」 | `github-branches.mjs` |
+| 「刪除分支」 | `github-delete-branch.mjs --branch "xxx"` |
+| 「看差異」「diff」「改了什麼」 | `github-diff.mjs` |
+| 「合併」「merge」 | `github-merge.mjs --branch "xxx"` |
+| 「暫存」「stash」 | `github-stash.mjs --action save` |
+| 「恢復暫存」「stash pop」 | `github-stash.mjs --action pop` |
+| 「commit」「提交」 | `github-commit.mjs` |
+| 「push」「推送」 | `github-push.mjs` |
+
+### Pull Request 操作
+
+| 使用者意圖 | 執行腳本 |
+|-----------|---------|
+| 「建立 PR」「開 PR」「發 pull request」 | `github-pr-create.mjs --title "..." --head "..." --base "..."` |
+| 「列出 PR」「有哪些 PR」 | `github-pr-list.mjs` |
+| 「看 PR」「檢視 PR #xxx」 | `github-pr-view.mjs --number xxx` |
+| 「合併 PR」「merge PR」 | `github-pr-merge.mjs --number xxx` |
+
+---
+
+## 🛡️ 安全設計
+
+所有腳本都有以下安全限制：
+
+1. **路徑隔離**：只能存取 `/tmp/{userId}/github/` 目錄（本地 SSD）
+2. **SKILL.md bashAllowedPaths**：Claude Agent SDK 層級阻擋，任何 bash 指令都被限制在允許路徑內
+3. **路徑遍歷防護**：禁止 `../` 等路徑遍歷，多層驗證
+4. **userId 驗證**：只接受英數字（Firebase User ID 格式）
+5. **檔案大小限制**：讀取限制 10MB，搜尋跳過超過 5MB 的檔案
+6. **結果數量限制**：搜尋最多 100 筆結果，列表最多 1000 個檔案
+7. **自動清除**：Cloud Run 重啟後 /tmp 自動清空，資安友好
+
+---
+
+## ⚠️ 錯誤處理
+
+| 錯誤訊息 | 原因 | 解決方案 |
+|---------|------|---------|
+| `No GitHub repositories found` | 未 Clone 任何 repo 或 Cloud Run 重啟後需重新 sync | 先執行 `github-clone.mjs` 或 `github-sync.mjs` |
+| `Repository "xxx" not found` | 指定的 repo 不存在 | 檢查名稱或先 Clone |
+| `File "xxx" not found` | 檔案不存在 | 使用 `github-list-tree.mjs` 確認路徑 |
+| `Path traversal detected` | 嘗試存取不允許的路徑 | 使用相對路徑，不要用 `../` |
+| `File too large` | 檔案超過大小限制 | 使用 `--start` 和 `--end` 讀取部分 |
+| `Invalid userId format` | userId 格式錯誤 | 使用 `$USER_ID` 環境變數 |
+| `Access denied` | 嘗試存取 /tmp/{userId}/github/ 以外的路徑 | 只能存取自己的 GitHub 目錄 |
+
+---
+
+## 📂 本地目錄結構
+
+```
+/tmp/{userId}/github/
+├── {owner}/                   # GitHub owner（組織或個人）
+│   └── {repo}/                # Repository 名稱
+│       ├── .git/              # Git 目錄
+│       ├── src/               # 原始碼
+│       ├── docs/              # 文件
+│       └── ...
+```
+
+### 效能優勢
+
+使用 `/tmp`（本地 SSD）取代 GCS FUSE：
+
+| 操作 | GCS FUSE | /tmp SSD | 改善 |
+|------|----------|----------|------|
+| 列出檔案 | 3-10 秒 | < 50 ms | **60-200x** |
+| 全文搜尋 | 10-60 秒 | < 500 ms | **20-120x** |
+| 讀取檔案 | 1-3 秒 | < 10 ms | **100-300x** |