botrun-horse 2.30.0 → 2.34.0

package/botrun-c/specs/share-skill/design.md

@@ -1,1146 +0,0 @@
-# 技能分享功能：設計規格
-
-## 🎯 系統架構概述
-
-技能分享功能允許使用者將自己建立的技能透過簡短的分享 ID 分享給其他人，其他人可以透過輸入分享 ID 將技能 clone 到自己的技能集中。
-
-### 核心設計理念
-
-1. **確定性 Share ID**：使用 MD5(userId + skillName) 作為分享識別碼，支援智慧覆寫
-2. **Clone 而非 Reference**：匯入的技能是完整複製，使用者可自由修改
-3. **Firestore 儲存**：分享記錄儲存在 Firestore，便於管理和查詢
-4. **Shadcn UI 組件**：使用 Dialog、DropdownMenu、Input 等原生組件實現 RWD
-
----
-
-## [D-1] Share ID 設計
-
-### 設計說明
-
-**採用 MD5(userId + skillName) 作為 Share ID**，理由如下：
-
-1. **確定性（Deterministic）**：同一使用者的同一技能名稱 → 永遠產生相同的 shareId
-2. **自動覆寫**：修改技能內容後再次分享 → 自動覆寫 Firestore（無需查詢）
-3. **自動版本分支**：改變技能名稱 → 產生新的 shareId（新分享記錄）
-4. **查詢效能極佳**：使用 document ID 查詢，O(1) 時間複雜度
-5. **無需額外索引**：不需要建立 `(ownerId, skillName)` 複合索引
-
-### Share ID 生成邏輯
-
-```typescript
-// api/src/utils/share-id.ts
-import crypto from 'crypto';
-
-export function generateShareId(userId: string, skillName: string): string {
-  // MD5 完全支援 UTF-8（包含中文）
-  const content = `${userId}:${skillName}`;
-  return crypto.createHash('md5').update(content, 'utf-8').digest('hex');
-}
-
-// 範例：
-// userId = "abc123"
-// skillName = "孵化技能"
-// shareId = "7a3f8c2e1b4d9f6a5e8c3d2a1f9b7e4c"（32 字元 hex）
-```
-
-### 中文支援
-
-**問題**：中文可以做 MD5 嗎？
-**答案**：✅ 完全支援
-
-```typescript
-// Node.js crypto 模組自動處理 UTF-8 編碼
-crypto.createHash('md5').update('孵化技能', 'utf-8').digest('hex');
-// 輸出: "7a3f8c2e1b4d9f6a5e8c3d2a1f9b7e4c"
-```
-
-### 分享行為
-
-| 操作 | shareId | Firestore 行為 | 說明 |
-|------|---------|---------------|------|
-| 首次分享「技能 A」 | `md5(user:技能A)` | 建立新記錄 | `createdAt` = 當前時間 |
-| 修改內容後再分享「技能 A」 | `md5(user:技能A)` ✅ 相同 | **覆寫**現有記錄 | `createdAt` 保持不變，`updatedAt` 更新 |
-| 重新命名為「技能 B」後分享 | `md5(user:技能B)` ❌ 不同 | 建立新記錄 | 產生新的 shareId |
-
-### 優點總結
-
-1. **智慧覆寫**：技能內容更新時，分享連結不變（使用者體驗佳）
-2. **改名隔離**：技能改名視為新技能，產生新分享（合理）
-3. **效能最佳**：無需查詢「是否已分享」，直接用 MD5 當 document ID
-4. **儲存節省**：同一技能只有一筆記錄（除非改名）
-
----
-
-## [D-2] 資料結構設計
-
-### 為什麼需要 `sharedSkills` Collection？
-
-**現有技能儲存方式**：
-- 技能存放在檔案系統：`/mnt/data/{userId}/.claude/skills/{skillId}/SKILL.md`
-- 每個使用者只能存取自己的檔案（私有隔離）
-- **沒有** Firestore 的 `skills` collection
-
-**跨使用者分享的挑戰**：
-- 使用者 A 的技能檔案位於 `/mnt/data/user_A/.claude/skills/孵化技能/SKILL.md`
-- 使用者 B 無法直接存取使用者 A 的檔案系統
-- 需要一個**公開的中介儲存層**來傳遞技能內容
-
-**解決方案：Firestore `sharedSkills` Collection**
-- 作為技能內容的「公開快照」儲存
-- 任何人都可透過 shareId 讀取（無需知道原擁有者）
-- 使用者 B 讀取後 clone 到自己的 GCS 儲存空間
-
-**技能儲存架構**：
-```
-使用者 A 的技能（原始）：
-  GCS: botrun-c-uploads/user_A/.claude/skills/孵化技能/SKILL.md
-  掛載: /mnt/data/user_A/.claude/skills/孵化技能/SKILL.md
-
-分享快照（Firestore）：
-  Collection: sharedSkills
-  Document ID: md5(user_A:孵化技能)
-  Field: skillContent = "完整 SKILL.md 內容"
-
-使用者 B 匯入（clone）：
-  GCS: botrun-c-uploads/user_B/.claude/skills/孵化技能/SKILL.md
-  掛載: /mnt/data/user_B/.claude/skills/孵化技能/SKILL.md
-```
-
-### Firestore Collection: `sharedSkills`
-
-```typescript
-// sharedSkills/{shareId} where shareId = md5(userId + skillName)
-interface SharedSkill {
-  shareId: string;           // MD5 hash（即 document ID）
-  ownerId: string;           // 分享者 userId（用於審計和防濫用）
-  skillName: string;         // 技能名稱
-  skillDescription: string;  // 技能描述
-  skillIcon: string;         // 技能 icon（emoji）
-  skillContent: string;      // 完整的 SKILL.md 內容（YAML + Markdown）
-  createdAt: Timestamp;      // 首次分享時間
-  updatedAt: Timestamp;      // 最後更新時間
-}
-```
-
-**欄位用途說明**：
-- ✅ `shareId`：MD5 hash 作為 document ID，支援自動覆寫
-- ✅ `ownerId`：記錄分享者（用於審計、防濫用），但**不用於查詢**
-- ✅ `createdAt`：首次分享時間（覆寫時不變）
-- ✅ `updatedAt`：內容更新時間（每次覆寫都更新）
-
-**移除的欄位**：
-- ❌ `downloadCount`：不統計下載次數
-- ❌ `shareUrl`：現階段不使用完整 URL
-- ❌ `expiresAt`：現階段不實作過期機制
-
-### Firestore 索引
-
-```typescript
-// 單一欄位索引：shareId（作為 document ID，自動索引）
-// 無需額外建立複合索引
-```
-
----
-
-## [D-3] API 設計
-
-### 3.1 建立分享
-
-**Endpoint**: `POST /api/skills/share`
-
-**Request Body**:
-```typescript
-{
-  skillId: string;  // 要分享的技能 ID
-}
-```
-
-**Response**:
-```typescript
-{
-  success: true;
-  shareId: string;    // MD5 hash（32 字元 hex）
-}
-```
-
-**實作邏輯**:
-```typescript
-// api/src/routes/skills.ts
-import { getFirestore, FieldValue } from 'firebase-admin/firestore';
-import { generateShareId } from '../utils/share-id.js';
-
-router.post('/share', async (req, res) => {
-  const { skillId } = req.body;
-  const userId = req.user.uid;
-
-  // 1. 檢查技能是否存在且屬於使用者
-  const skillsRepo = new SkillsRepository(userId);
-  const skillExists = await skillsRepo.exists(skillId);
-
-  if (!skillExists) {
-    return res.status(404).json({
-      success: false,
-      error: '找不到此技能'
-    });
-  }
-
-  // 2. 讀取完整技能內容
-  const skillContent = await skillsRepo.getSkillContent(skillId);
-  const skillName = skillContent.metadata.name;
-
-  // 3. 生成 shareId = md5(userId + skillName)
-  const shareId = generateShareId(userId, skillName);
-
-  // 4. 檢查是否已存在（用於保留 createdAt）
-  const db = getFirestore();
-  const existingDoc = await db.collection('sharedSkills').doc(shareId).get();
-
-  // 5. 儲存到 Firestore（覆寫模式）
-  await db.collection('sharedSkills').doc(shareId).set({
-    shareId,
-    ownerId: userId,
-    skillName,
-    skillDescription: skillContent.metadata.description || '',
-    skillIcon: skillContent.metadata.icon || '🔧',
-    skillContent: skillContent.rawContent,
-    createdAt: existingDoc.exists
-      ? existingDoc.data()!.createdAt
-      : FieldValue.serverTimestamp(),
-    updatedAt: FieldValue.serverTimestamp()
-  });
-
-  return res.json({
-    success: true,
-    shareId
-  });
-});
-```
-
-### 3.2 取得分享內容（預覽用）
-
-**Endpoint**: `GET /api/skills/share/:shareId`
-
-**用途**：供前端在匯入前預覽技能資訊
-
-**Response**:
-```typescript
-{
-  success: true;
-  shareId: string;
-  skillName: string;
-  skillDescription: string;
-  skillIcon: string;
-  createdAt: string;       // ISO 8601 格式
-}
-```
-
-**實作邏輯**:
-```typescript
-router.get('/share/:shareId', async (req, res) => {
-  const { shareId } = req.params;
-
-  // 從 Firestore 取得分享記錄
-  const db = getFirestore();
-  const doc = await db.collection('sharedSkills').doc(shareId).get();
-
-  if (!doc.exists) {
-    return res.status(404).json({
-      success: false,
-      error: '找不到此分享技能'
-    });
-  }
-
-  const data = doc.data()!;
-
-  return res.json({
-    success: true,
-    shareId: data.shareId,
-    skillName: data.skillName,
-    skillDescription: data.skillDescription,
-    skillIcon: data.skillIcon,
-    createdAt: data.createdAt.toDate().toISOString()
-  });
-});
-```
-
-### 3.3 匯入分享技能
-
-**Endpoint**: `POST /api/skills/import/:shareId`
-
-**用途**：將分享的技能 clone 到使用者自己的 GCS 儲存空間
-
-**Request Body**:
-```typescript
-{
-  overwrite?: boolean;  // 可選，true = 覆寫現有技能，預設 false
-}
-```
-
-**Response**:
-```typescript
-// 成功匯入
-{
-  success: true;
-  skillId: string;    // 新建立的技能 ID
-  skillName: string;  // 技能名稱
-}
-
-// 名稱衝突（需要使用者確認）
-{
-  success: false;
-  conflict: true;
-  skillName: string;  // 衝突的技能名稱
-  error: "技能名稱已存在"
-}
-```
-
-**實作邏輯**:
-```typescript
-router.post('/import/:shareId', async (req, res) => {
-  const { shareId } = req.params;
-  const { overwrite = false } = req.body;
-  const userId = req.user.uid;
-
-  // 1. 從 Firestore 取得分享內容
-  const db = getFirestore();
-  const doc = await db.collection('sharedSkills').doc(shareId).get();
-
-  if (!doc.exists) {
-    return res.status(404).json({
-      success: false,
-      error: '找不到此分享技能'
-    });
-  }
-
-  const sharedData = doc.data()!;
-
-  // 2. 檢查名稱衝突
-  const skillsRepo = new SkillsRepository(userId);
-  const nameExists = await skillsRepo.exists(sharedData.skillName);
-
-  if (nameExists && !overwrite) {
-    // 名稱衝突，返回 conflict 狀態，讓前端顯示確認對話框
-    return res.status(409).json({
-      success: false,
-      conflict: true,
-      skillName: sharedData.skillName,
-      error: '技能名稱已存在'
-    });
-  }
-
-  // 3. 處理覆寫
-  if (nameExists && overwrite) {
-    // 使用者選擇覆寫：刪除舊技能
-    await skillsRepo.deleteSkill(sharedData.skillName);
-  }
-
-  // 4. 建立新技能（clone 完整內容到使用者的 GCS）
-  const newSkillId = sharedData.skillName.replace(/[^a-zA-Z0-9\u4e00-\u9fa5_-]/g, '-');
-  await skillsRepo.createSkill(newSkillId, sharedData.skillContent);
-
-  // 實際寫入路徑：
-  // 檔案系統: /mnt/data/{userId}/.claude/skills/{newSkillId}/SKILL.md
-  // 實際儲存: GCS bucket "botrun-c-uploads" (透過 GCS FUSE 掛載)
-
-  return res.json({
-    success: true,
-    skillId: newSkillId,
-    skillName: sharedData.skillName
-  });
-});
-```
-
----
-
-## [D-4] 前端 UI 設計
-
-### 4.0 跨平台剪貼簿支援
-
-**依賴安裝**（專案尚未安裝）：
-```bash
-pnpm add @capacitor/clipboard
-npx cap sync
-```
-
-**使用方式**：
-```typescript
-import { Clipboard } from '@capacitor/clipboard';
-
-// 複製到剪貼簿（支援 Web/iOS/Android）
-await Clipboard.write({ string: shareId });
-```
-
-**參考文件**：[Capacitor Clipboard API](https://capacitorjs.com/docs/apis/clipboard)
-
-### 4.1 分享按鈕（Share Button）
-
-在技能卡片上加入分享按鈕，點擊後顯示分享 Dialog。
-
-**位置**: `web/components/skills-manager-drawer.tsx`
-
-```tsx
-// 在 SortableSkillItem 中加入分享按鈕
-import { Share2 } from "lucide-react";
-
-function SortableSkillItem({ skill, onEdit, onDelete, onShare, isDraggable }) {
-  return (
-    <div className="flex items-start gap-3 p-4 rounded-lg border">
-      {/* ... 現有內容 ... */}
-
-      <div className="flex gap-2 shrink-0">
-        {/* 分享按鈕 - 只有使用者技能才顯示 */}
-        {skill.source === "user" && (
-          <Button
-            variant="ghost"
-            size="icon"
-            onClick={() => onShare(skill)}
-            title="分享技能"
-          >
-            <Share2 className="h-4 w-4" />
-          </Button>
-        )}
-
-        {/* 編輯/查看按鈕 */}
-        <Button variant="ghost" size="icon" onClick={() => onEdit(skill)}>
-          {skill.editable ? <Pencil /> : <Eye />}
-        </Button>
-
-        {/* 刪除按鈕 */}
-        {skill.editable && (
-          <Button variant="ghost" size="icon" onClick={() => onDelete(skill)}>
-            <Trash2 />
-          </Button>
-        )}
-      </div>
-    </div>
-  );
-}
-```
-
-### 4.2 分享 Dialog (ShareSkillDialog)
-
-**新檔案**: `web/components/share-skill-dialog.tsx`
-
-```tsx
-"use client";
-
-import { useState } from "react";
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-} from "@/components/ui/dialog";
-import { Button } from "@/components/ui/button";
-import { Input } from "@/components/ui/input";
-import { Label } from "@/components/ui/label";
-import { Copy, Check, Loader2, AlertCircle } from "lucide-react";
-import { Clipboard } from "@capacitor/clipboard";
-
-interface ShareSkillDialogProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  skillId: string;
-  skillName: string;
-}
-
-export function ShareSkillDialog({
-  open,
-  onOpenChange,
-  skillId,
-  skillName
-}: ShareSkillDialogProps) {
-  const [shareId, setShareId] = useState<string | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [copied, setCopied] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  // 生成分享連結
-  const handleCreateShare = async () => {
-    setIsLoading(true);
-    setError(null);
-    try {
-      const response = await fetch('/api/skills/share', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ skillId })
-      });
-
-      const data = await response.json();
-
-      if (!data.success) {
-        throw new Error(data.error || '建立失敗');
-      }
-
-      setShareId(data.shareId);
-    } catch (err: any) {
-      setError(err.message || '建立分享連結失敗');
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  // 複製到剪貼簿（跨平台支援）
-  const handleCopy = async () => {
-    if (!shareId) return;
-
-    try {
-      await Clipboard.write({ string: shareId });
-      setCopied(true);
-      setTimeout(() => setCopied(false), 2000);
-    } catch (err) {
-      console.error('複製失敗:', err);
-    }
-  };
-
-  return (
-    <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="sm:max-w-[500px]">
-        <DialogHeader>
-          <DialogTitle>分享技能：{skillName}</DialogTitle>
-          <DialogDescription>
-            建立分享 ID，其他人可以透過此 ID 將技能匯入到自己的技能集
-          </DialogDescription>
-        </DialogHeader>
-
-        <div className="space-y-4 py-4">
-          {!shareId ? (
-            <>
-              <Button
-                onClick={handleCreateShare}
-                disabled={isLoading}
-                className="w-full"
-              >
-                {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-                建立分享連結
-              </Button>
-
-              {/* 錯誤訊息 */}
-              {error && (
-                <div className="flex items-start gap-2 p-3 bg-destructive/10 text-destructive rounded-md text-sm">
-                  <AlertCircle className="h-4 w-4 mt-0.5 shrink-0" />
-                  <span>{error}</span>
-                </div>
-              )}
-            </>
-          ) : (
-            <div className="space-y-2">
-              <Label>分享 ID</Label>
-              <div className="flex gap-2">
-                <Input
-                  value={shareId}
-                  readOnly
-                  className="font-mono text-xs"
-                />
-                <Button
-                  variant="outline"
-                  size="sm"
-                  onClick={handleCopy}
-                  className="shrink-0"
-                >
-                  {copied ? (
-                    <>
-                      <Check className="h-4 w-4 mr-2" />
-                      已複製！
-                    </>
-                  ) : (
-                    <>
-                      <Copy className="h-4 w-4 mr-2" />
-                      複製
-                    </>
-                  )}
-                </Button>
-              </div>
-              <p className="text-sm text-muted-foreground">
-                將此 ID 分享給其他人，他們可以在「匯入分享技能」中使用
-              </p>
-            </div>
-          )}
-        </div>
-      </DialogContent>
-    </Dialog>
-  );
-}
-```
-
-**設計重點**：
-- ✅ 使用 `@capacitor/clipboard` 支援跨平台複製
-- ✅ 移除 `toast`，改用按鈕文字和 icon 變化（"複製" → "已複製！"）
-- ✅ 錯誤訊息內嵌顯示（不使用 toast）
-- ✅ MD5 hash 完整顯示（32 字元 hex），字體使用 `font-mono text-xs`
-
-### 4.3 新增技能按鈕改為 DropdownMenu
-
-**位置**: `web/components/skills-manager-drawer.tsx`
-
-```tsx
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { Plus, FileDown, ChevronDown } from "lucide-react";
-
-// 原本的單一按鈕
-// <Button onClick={onCreate}>
-//   <Plus className="h-4 w-4 mr-2" />
-//   新增技能
-// </Button>
-
-// 改為 DropdownMenu
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <Button>
-      <Plus className="h-4 w-4 mr-2" />
-      新增技能
-      <ChevronDown className="h-4 w-4 ml-2" />
-    </Button>
-  </DropdownMenuTrigger>
-  <DropdownMenuContent align="end">
-    <DropdownMenuItem onClick={onCreate}>
-      <Plus className="h-4 w-4 mr-2" />
-      建立新技能
-    </DropdownMenuItem>
-    <DropdownMenuItem onClick={() => setImportDialogOpen(true)}>
-      <FileDown className="h-4 w-4 mr-2" />
-      匯入分享技能
-    </DropdownMenuItem>
-  </DropdownMenuContent>
-</DropdownMenu>
-```
-
-### 4.4 匯入技能 Dialog (ImportSkillDialog)
-
-**新檔案**: `web/components/import-skill-dialog.tsx`
-
-```tsx
-"use client";
-
-import { useState } from "react";
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-  DialogFooter,
-} from "@/components/ui/dialog";
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogTitle,
-} from "@/components/ui/alert-dialog";
-import { Button } from "@/components/ui/button";
-import { Input } from "@/components/ui/input";
-import { Label } from "@/components/ui/label";
-import { Loader2, AlertCircle } from "lucide-react";
-
-interface ImportSkillDialogProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  onSuccess: () => void;  // 匯入成功後重新載入技能列表
-}
-
-interface SkillPreview {
-  shareId: string;
-  skillName: string;
-  skillDescription: string;
-  skillIcon: string;
-  createdAt: string;
-}
-
-export function ImportSkillDialog({
-  open,
-  onOpenChange,
-  onSuccess
-}: ImportSkillDialogProps) {
-  const [shareId, setShareId] = useState("");
-  const [isLoadingPreview, setIsLoadingPreview] = useState(false);
-  const [isImporting, setIsImporting] = useState(false);
-  const [preview, setPreview] = useState<SkillPreview | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  // 名稱衝突確認對話框狀態
-  const [showConflictDialog, setShowConflictDialog] = useState(false);
-  const [conflictSkillName, setConflictSkillName] = useState<string | null>(null);
-
-  // 預覽分享技能
-  const handlePreview = async () => {
-    if (!shareId.trim()) {
-      setError('請輸入分享 ID');
-      return;
-    }
-
-    setIsLoadingPreview(true);
-    setError(null);
-    setPreview(null);
-
-    try {
-      const response = await fetch(`/api/skills/share/${shareId.trim()}`);
-      const data = await response.json();
-
-      if (!data.success) {
-        throw new Error(data.error || '找不到此分享技能');
-      }
-
-      setPreview(data);
-    } catch (err: any) {
-      setError(err.message || '載入失敗');
-    } finally {
-      setIsLoadingPreview(false);
-    }
-  };
-
-  // 確認匯入
-  const handleImport = async (overwrite?: boolean) => {
-    setIsImporting(true);
-    setError(null);
-
-    try {
-      const response = await fetch(`/api/skills/import/${shareId.trim()}`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ overwrite })
-      });
-
-      const data = await response.json();
-
-      // 檢查名稱衝突
-      if (response.status === 409 && data.conflict) {
-        setConflictSkillName(data.skillName);
-        setShowConflictDialog(true);
-        setIsImporting(false);
-        return;
-      }
-
-      if (!data.success) {
-        throw new Error(data.error || '匯入失敗');
-      }
-
-      // 成功：關閉 Dialog 並重新載入列表
-      onOpenChange(false);
-      onSuccess();
-    } catch (err: any) {
-      setError(err.message || '匯入失敗');
-    } finally {
-      setIsImporting(false);
-    }
-  };
-
-  // 處理衝突選擇
-  const handleConflictChoice = async (choice: 'overwrite' | 'keep-both' | 'cancel') => {
-    setShowConflictDialog(false);
-
-    if (choice === 'cancel') {
-      return;
-    }
-
-    if (choice === 'overwrite') {
-      await handleImport(true);  // overwrite = true
-    } else {
-      // keep-both: 不傳 overwrite，後端自動加數字後綴
-      await handleImport(false);
-    }
-  };
-
-  return (
-    <>
-      <Dialog open={open} onOpenChange={onOpenChange}>
-        <DialogContent className="sm:max-w-[500px]">
-          <DialogHeader>
-            <DialogTitle>匯入分享技能</DialogTitle>
-            <DialogDescription>
-              輸入分享 ID 以匯入其他人分享的技能
-            </DialogDescription>
-          </DialogHeader>
-
-          <div className="space-y-4 py-4">
-            {/* 輸入分享 ID */}
-            <div className="space-y-2">
-              <Label htmlFor="shareId">分享 ID</Label>
-              <div className="flex gap-2">
-                <Input
-                  id="shareId"
-                  placeholder="貼上 32 字元的分享 ID"
-                  value={shareId}
-                  onChange={(e) => {
-                    setShareId(e.target.value);
-                    setPreview(null);
-                    setError(null);
-                  }}
-                  className="font-mono text-xs"
-                />
-                <Button
-                  variant="outline"
-                  onClick={handlePreview}
-                  disabled={isLoadingPreview || !shareId.trim()}
-                  className="shrink-0"
-                >
-                  {isLoadingPreview && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-                  預覽
-                </Button>
-              </div>
-            </div>
-
-            {/* 錯誤訊息 */}
-            {error && (
-              <div className="flex items-start gap-2 p-3 bg-destructive/10 text-destructive rounded-md text-sm">
-                <AlertCircle className="h-4 w-4 mt-0.5 shrink-0" />
-                <span>{error}</span>
-              </div>
-            )}
-
-            {/* 預覽區域 */}
-            {preview && (
-              <div className="rounded-lg border p-4 space-y-2 bg-muted/50">
-                <div className="flex items-center gap-2">
-                  <span className="text-2xl">{preview.skillIcon}</span>
-                  <h3 className="font-semibold">{preview.skillName}</h3>
-                </div>
-                <p className="text-sm text-muted-foreground">
-                  {preview.skillDescription}
-                </p>
-                <p className="text-xs text-muted-foreground">
-                  分享時間：{new Date(preview.createdAt).toLocaleDateString('zh-TW')}
-                </p>
-              </div>
-            )}
-          </div>
-
-          <DialogFooter>
-            <Button variant="outline" onClick={() => onOpenChange(false)}>
-              取消
-            </Button>
-            <Button
-              onClick={() => handleImport()}
-              disabled={!preview || isImporting}
-            >
-              {isImporting && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-              確認匯入
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-
-      {/* 名稱衝突確認對話框 */}
-      <AlertDialog open={showConflictDialog} onOpenChange={setShowConflictDialog}>
-        <AlertDialogContent>
-          <AlertDialogHeader>
-            <AlertDialogTitle>技能名稱已存在</AlertDialogTitle>
-            <AlertDialogDescription>
-              您已經有一個名為「<strong>{conflictSkillName}</strong>」的技能。請選擇如何處理：
-            </AlertDialogDescription>
-          </AlertDialogHeader>
-          <AlertDialogFooter>
-            <AlertDialogCancel onClick={() => handleConflictChoice('cancel')}>
-              取消匯入
-            </AlertDialogCancel>
-            <AlertDialogAction
-              onClick={() => handleConflictChoice('overwrite')}
-              disabled={isImporting}
-              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
-            >
-              {isImporting && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
-              覆寫現有技能
-            </AlertDialogAction>
-          </AlertDialogFooter>
-        </AlertDialogContent>
-      </AlertDialog>
-    </>
-  );
-}
-```
-
-**設計重點**：
-- ✅ 移除所有 `toast`，錯誤訊息內嵌顯示
-- ✅ 匯入成功後直接關閉 Dialog，技能列表自動重新整理（使用者會看到新技能）
-- ✅ 顯示「分享時間」（`createdAt`）
-- ✅ MD5 hash 輸入框使用 `font-mono text-xs`（32 字元）
-- ✅ 預覽卡片增加背景色區分（`bg-muted/50`）
-- ✅ **名稱衝突確認**：偵測到衝突時顯示 AlertDialog，提供兩個選項：
-  - **覆寫現有技能**（紅色按鈕，警示性）
-  - **取消匯入**
-
----
-
-## [D-5] RWD 響應式設計
-
-### Shadcn Dialog 原生 RWD 支援
-
-Shadcn 的 Dialog 組件已內建 RWD 支援（參考：https://ui.shadcn.com/docs/components/dialog）：
-
-```tsx
-// DialogContent 預設樣式已包含響應式設計
-<DialogContent className="sm:max-w-[425px]">
-  {/*
-    - Mobile: 全螢幕顯示（max-w-full）
-    - Desktop: 固定寬度 425px（sm:max-w-[425px]）
-  */}
-</DialogContent>
-```
-
-### DropdownMenu 觸控優化
-
-參考 Shadcn DropdownMenu 文件：https://ui.shadcn.com/docs/components/dropdown-menu
-
-```tsx
-// DropdownMenuContent 自動處理觸控和鍵盤導航
-<DropdownMenuContent align="end">
-  {/*
-    - 自動調整位置避免超出視窗
-    - 觸控裝置支援
-    - 鍵盤導航支援（箭頭鍵、Enter、Escape）
-  */}
-</DropdownMenuContent>
-```
-
----
-
-## [D-6] 錯誤處理與邊界情況
-
-### 6.1 Share ID 不存在
-
-```typescript
-// API Response
-{
-  success: false,
-  error: "找不到此分享技能"
-}
-
-// 前端處理：內嵌錯誤訊息（不使用 toast）
-<div className="flex items-start gap-2 p-3 bg-destructive/10 text-destructive rounded-md text-sm">
-  <AlertCircle className="h-4 w-4 mt-0.5 shrink-0" />
-  <span>找不到此分享技能</span>
-</div>
-```
-
-### 6.2 技能名稱衝突
-
-當匯入的技能名稱與現有技能重複時，顯示確認對話框讓使用者選擇：
-
-**流程**：
-1. 使用者點擊「確認匯入」
-2. 後端檢測到名稱衝突，返回 409 狀態碼和 `conflict: true`
-3. 前端顯示 AlertDialog，提供兩個選項：
-   - **覆寫現有技能**：刪除舊技能，匯入新技能（使用原始名稱）
-   - **取消匯入**：放棄匯入操作
-
-**後端處理邏輯**：
-```typescript
-// api/src/routes/skills.ts
-
-// 1. 檢測衝突
-const nameExists = await skillsRepo.exists(sharedData.skillName);
-
-if (nameExists && !overwrite) {
-  return res.status(409).json({
-    success: false,
-    conflict: true,
-    skillName: sharedData.skillName,
-    error: '技能名稱已存在'
-  });
-}
-
-// 2. 處理覆寫
-if (nameExists && overwrite) {
-  await skillsRepo.deleteSkill(sharedData.skillName);
-}
-```
-
-**前端處理邏輯**：
-```tsx
-// web/components/import-skill-dialog.tsx
-
-const handleImport = async (overwrite: boolean = false) => {
-  const response = await fetch(`/api/skills/import/${shareId}`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ overwrite })
-  });
-
-  // 檢查衝突
-  if (response.status === 409 && data.conflict) {
-    setConflictSkillName(data.skillName);
-    setShowConflictDialog(true);  // 顯示確認對話框
-    return;
-  }
-};
-
-// 使用者選擇
-const handleConflictChoice = async (choice: 'overwrite' | 'cancel') => {
-  if (choice === 'overwrite') {
-    await handleImport(true);  // 覆寫
-  }
-  // cancel: 不執行任何動作
-};
-```
-
-### 6.3 權限檢查
-
-```typescript
-// 前端：只有使用者技能（source === "user"）才顯示分享按鈕
-{skill.source === "user" && (
-  <Button onClick={() => onShare(skill)} title="分享技能">
-    <Share2 className="h-4 w-4" />
-  </Button>
-)}
-
-// 後端：檢查技能是否存在且屬於使用者
-const skillsRepo = new SkillsRepository(userId);
-const skillExists = await skillsRepo.exists(skillId);
-
-if (!skillExists) {
-  return res.status(404).json({
-    success: false,
-    error: '找不到此技能'
-  });
-}
-```
-
----
-
-## [D-7] 安全性考量
-
-### 7.1 防止 Share ID 爆破攻擊
-
-```typescript
-// Rate limiting（使用 express-rate-limit）
-import rateLimit from 'express-rate-limit';
-
-const shareLimiter = rateLimit({
-  windowMs: 15 * 60 * 1000, // 15 分鐘
-  max: 10, // 最多 10 次請求
-  message: '請求過於頻繁，請稍後再試'
-});
-
-router.get('/share/:shareId', shareLimiter, async (req, res) => {
-  // ...
-});
-```
-
-### 7.2 內容驗證
-
-```typescript
-// 匯入前驗證 SKILL.md 內容
-function validateSkillContent(content: string): boolean {
-  // 檢查是否包含惡意程式碼
-  // 檢查檔案大小限制（例如：< 1MB）
-  // 檢查 YAML frontmatter 格式
-  return true;
-}
-```
-
-### 7.3 私有技能保護
-
-```typescript
-// 使用者可選擇是否公開分享（未來功能）
-interface SharedSkill {
-  isPublic: boolean;  // 預設 true
-  allowedUsers?: string[];  // 允許存取的使用者清單（私有分享）
-}
-```
-
----
-
-## [D-8] 效能優化
-
-### 8.1 MD5 生成效能
-
-```typescript
-// Node.js crypto.createHash('md5') 效能極佳
-import crypto from 'crypto';
-const shareId = crypto.createHash('md5')
-  .update(`${userId}:${skillName}`, 'utf-8')
-  .digest('hex');  // ~5μs
-```
-
-### 8.2 Firestore 寫入優化（覆寫模式）
-
-```typescript
-// 使用確定性 shareId，直接覆寫（無需先查詢是否存在）
-const shareId = generateShareId(userId, skillName);
-
-// 僅需一次查詢（用於判斷 createdAt）
-const existingDoc = await db.collection('sharedSkills').doc(shareId).get();
-
-// 直接寫入（覆寫）
-await db.collection('sharedSkills').doc(shareId).set({...});
-```
-
-**效能優勢**：
-- ✅ 無需查詢「是否已分享過」
-- ✅ 無需處理碰撞重試邏輯
-- ✅ document ID 查詢是 Firestore 最快的查詢方式（O(1)）
-
-### 8.3 前端快取策略（未來優化）
-
-```typescript
-// 可考慮在前端快取已預覽過的分享技能
-const [previewCache, setPreviewCache] = useState<Map<string, SkillPreview>>(new Map());
-
-// 預覽前先檢查快取
-if (previewCache.has(shareId)) {
-  setPreview(previewCache.get(shareId)!);
-  return;
-}
-```
-
----
-
-## [D-9] 未來擴展功能
-
-### 9.1 技能市集（Skill Marketplace）
-
-```typescript
-// 新增欄位支援市集功能
-interface SharedSkill {
-  // ... 現有欄位 ...
-
-  // 市集功能
-  tags?: string[];           // 技能標籤（例如：["productivity", "automation"]）
-  rating?: number;           // 評分（1-5）
-  reviews?: number;          // 評論數量
-  featured?: boolean;        // 是否為精選技能
-  thumbnailUrl?: string;     // 縮圖 URL
-}
-```
-
-### 9.2 完整分享 URL
-
-```typescript
-// 支援 QR Code 和完整 URL 分享
-const shareUrl = `https://botrun.ai/skills/share/${shareId}`;
-
-// 在分享 Dialog 中顯示 QR Code
-import QRCode from 'qrcode';
-
-const qrCodeDataUrl = await QRCode.toDataURL(shareUrl);
-```
-
-### 9.3 版本控制
-
-```typescript
-// 支援技能更新和版本追蹤
-interface SharedSkill {
-  version?: string;          // 版本號（例如："1.0.0"）
-  previousVersions?: string[]; // 歷史版本的 shareId
-}
-```
-
----
-
-## 📚 參考資料
-
-- [Capacitor Clipboard API](https://capacitorjs.com/docs/apis/clipboard) - 跨平台剪貼簿官方文件
-- [Shadcn UI Dialog](https://ui.shadcn.com/docs/components/dialog) - Dialog 元件文件
-- [Shadcn UI DropdownMenu](https://ui.shadcn.com/docs/components/dropdown-menu) - DropdownMenu 元件文件
-- [Firestore Data Model](https://firebase.google.com/docs/firestore/data-model) - Firestore 資料模型
-- [Express Rate Limiting](https://www.npmjs.com/package/express-rate-limit) - API 速率限制套件
-- [Node.js crypto.createHash()](https://nodejs.org/api/crypto.html#cryptocreatehashalgorithm-options) - MD5 hash 生成 API