botrun-horse 2.29.2 → 2.30.0

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

@@ -0,0 +1,1146 @@
+# 技能分享功能：設計規格
+
+## 🎯 系統架構概述
+
+技能分享功能允許使用者將自己建立的技能透過簡短的分享 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