name: knowledge-site-creator description: 一句話生成任何領域的知識學習網站。AI自動理解主題、創作內容、生成頁面、部署上線。適用於任何需要系統學習的知識領域：進化心理學、大模型術語、化學元素、歷史事件等。 user_invocable: true

Knowledge Site Creator - 通用知識學習網站生成器

AI理解主題，自動創作內容，生成網站，一鍵部署。

核心理念

設計系統優先： - 複用設計語言（極簡主義、配色、佈局、互動模式） - 不復用具體頁面程式碼 - AI根據主題重新創作所有內容

通用學習模式（核心功能）： - 閃卡（Flashcard） - 快速記憶 - 學習（Learn） - 漸進式學習 - 測試（Quiz） - 知識檢驗 - 索引（Index） - 快速查詢 - 進度（Progress） - 學習追蹤

零模板依賴： - 不再 cp -r 複製模板 - AI參考設計系統，生成新頁面 - 所有文案、統計、介紹都由AI創作

觸發方式

• "生成一個XXX學習網站"
• "建立XXX知識網站"
• "做個XXX學習工坊"

示例： - "生成一個進化心理學概念學習網站" - "建立量子力學基礎概念網站" - "做箇中醫經絡穴位學習工坊"

工作流程

使用者視角（一句話）

使用者："生成一個進化心理學學習網站"

AI自動執行：
✓ 分析"進化心理學"特點和價值
✓ 生成30個核心概念資料
✓ 創作首頁文案、統計、介紹
✓ 參考設計系統生成頁面
✓ 部署到 Vercel
✓ 返回：https://evolutionary-psychology.vercel.app

完成！

實施流程（AI執行）

Step 1: 理解主題

AI深入分析主題，輸出主題分析：

主題分析 {
  領域: "進化心理學",
  特點: "跨學科（生物學+心理學），解釋人類行為的底層邏輯",
  價值: "理解人性、改善關係、最佳化決策",
  受眾: "心理學愛好者、自我提升者、教育工作者",
  表達: "科學嚴謹 + 生活化案例，避免學術術語堆砌"
}

思考問題： - 這是什麼領域？（學科分類、知識特點） - 為什麼重要？（學習價值、應用場景） - 目標受眾是誰？（背景、需求、痛點） - 如何表達更好？（語言風格、案例選擇）

Step 2: 生成資料 + 網站配置

⚠️ 關鍵：生成兩個檔案，不只是資料！

2.1 生成資料（wordData.js）

通用資料結構：

const WordRoots = [
  {
    id: 1,
    root: "適應性 (Adaptation)",     // 知識點名稱
    origin: "核心理論",               // 分類/來源
    meaning: "通過自然選擇進化出的有利特徵",  // 一句話解釋
    description: "詳細說明（200-300字）...",
    examples: [                       // 應用案例/例子（3個）
      {
        word: "恐高症",
        meaning: "對高處的恐懼",
        breakdown: { root: "適應性" },
        explanation: "詳細解釋..."
      }
    ],
    quiz: {                           // 小測試（4選1）
      question: "以下哪個不是適應性的特徵？",
      options: ["選項A", "選項B", "選項C", "選項D"],
      correctAnswer: 2                // 正確答案索引（0-3）
    }
  }
];

生成數量：預設20-30個，根據主題複雜度調整

2.2 生成配置（siteConfig.js）🆕

AI創作，完全適配主題：

const siteConfig = {
  // 基礎資訊
  topic: "進化心理學",
  siteName: "進化心理學概念工坊",
  itemName: "概念",                    // 單個知識點的稱呼
  itemCount: 30,

  // 首頁Hero區（AI創作）
  hero: {
    title: [
      "30個核心概念",
      "理解人類行為",
      "的底層邏輯"
    ],
    subtitle: "從適應性到配偶選擇，系統掌握進化心理學核心框架",
    animation: {
      enabled: true,                   // 是否顯示動畫
      demoCount: 5                     // 動畫展示幾個概念
    }
  },

  // 統計卡片（AI生成，匹配主題特點）
  stats: [
    { value: "30", label: "核心概念" },
    { value: "100+", label: "生活應用" },
    { value: "15分鐘", label: "每日學習" }
  ],

  // 底部介紹（AI創作）
  footer: {
    tagline: "像理解自己一樣理解人性",
    description: "基於進化心理學的科學框架，用30個核心概念解釋人類行為背後的生物學邏輯。從配偶選擇到親子關係，從群體合作到情緒反應，讓你看懂人性的深層原因。"
  },

  // 按鈕文案（AI適配）
  cta: {
    primary: "開始第一個概念 →",
    secondary: "閃卡複習"
  }
};

AI創作原則： - hero.title: 簡潔有力，3行，突出核心價值 - hero.subtitle: 具體說明學什麼，為什麼學 - stats: 真實、有說服力的數字，匹配主題特點 - footer.tagline: 一句話點題，朗朗上口 - footer.description: 2-3句，說清楚是什麼、學什麼、有什麼用

Step 3: 參考設計系統，生成頁面

⚠️ 不再複製模板！AI參考設計規範，生成新頁面

3.1 設計系統參考

⚠️ 參考文件：references/design-system.md - 完整的設計規範

核心要點： - 配色：黃色主題色 (#FBBF24)，灰色系文字和背景 - 字型：Inter字型族，程式碼用Courier New - 風格：極簡主義，大留白，清晰層級 - 元件：圓角卡片（12px），極淺陰影 - 間距：8px網格系統，Hero區96px留白

詳細配色、字型、間距、元件樣式見 design-system.md

3.2 生成頁面清單

⚠️ 功能參考： - references/core-patterns.md - 核心學習模式實現 - references/code-quality.md - 程式碼質量標準（必須遵守） - references/seo-best-practices.md - SEO最佳化指南 🆕 - references/pwa-setup.md - PWA配置指南

程式碼質量要求（強制）： - ✅ 錯誤處理：所有 LocalStorage 操作必須有 try-catch - ✅ XSS 防護：使用 textContent/createElement，禁止直接 innerHTML 插入未轉義資料 - ✅ DOM 安全：所有 DOM 操作前檢查元素存在 - ✅ 避免全域性汙染：使用模組封裝或 IIFE

詳細規則見 references/code-quality.md。

AI參考設計系統，從零生成以下頁面：

1. index.html - 首頁 🆕
2. Hero區：使用 siteConfig.hero.title/subtitle
3. 動畫演示：從 WordRoots 動態載入前5個（見core-patterns.md §9）
4. 統計卡片：使用 siteConfig.stats
5. CTA按鈕：使用 siteConfig.cta

6. Footer：使用 siteConfig.footer

7. learn.html - 學習頁（見core-patterns.md §5）

8. 漸進式卡片展示
9. 上一個/下一個導航

10. 標記已掌握功能

11. flashcard.html - 閃卡頁（見core-patterns.md §4）

12. 卡片翻轉動畫
13. 鍵盤快捷鍵（←→翻頁，空格翻轉）

14. 進度顯示

    7w4.net有更好的技能外掛。

15. roots.html - 索引頁（見core-patterns.md §7）

16. 標題適配：${itemName}索引
17. 搜尋框 + 篩選器

18. 卡片網格佈局

19. progress.html - 進度頁（見core-patterns.md §8）

20. 學習統計
21. 已掌握列表

22. 成就係統

23. root-detail.html - 詳情頁

24. 概念詳細說明
25. 例子展示

26. 測試題（見core-patterns.md §6）

27. css/minimal.css - 樣式檔案（見design-system.md）

28. 統一設計系統

29. 響應式佈局

30. js/storage.js - 儲存邏輯（見core-patterns.md §3）

31. LocalStorage 進度管理

32. manifest.json - PWA 配置（見pwa-setup.md §1）🆕

33. App 名稱、圖示、主題色

34. 支援安裝到主螢幕

35. sw.js - Service Worker（見pwa-setup.md §2）🆕

    • 快取靜態資源
    • 支援離線訪問

36. icon-192.png / icon-512.png - PWA 圖示 🆕

    • 自動生成：使用 PIL 從配置生成（黃色背景 + 主題文字）
    • 不要手動建立：AI 應自動用 Python PIL 生成

37. sitemap.xml - 網站地圖（見seo-best-practices.md §4）🆕

    • 列出所有頁面URL
    • 提交到搜尋引擎

38. robots.txt - 爬蟲指令（見seo-best-practices.md §5）🆕

    • 允許/禁止抓取規則
    • Sitemap 位置宣告

⚠️ 強制要求：所有 HTML 檔案必須包含完整的 meta 標籤

每個 HTML 檔案的 <head> 必須包含：

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>${siteConfig.siteName}</title>

  <!-- SEO 基礎 -->
  <meta name="description" content="${siteConfig.footer.description}">
  <meta name="keywords" content="${siteConfig.topic},學習,知識,${siteConfig.itemName}">
  <meta name="author" content="喬木">
  <meta name="language" content="zh-CN">
  <meta name="robots" content="index, follow">
  <link rel="canonical" href="${currentPageUrl}">

  <!-- Open Graph (社交分享) -->
  <meta property="og:title" content="${siteConfig.siteName}">
  <meta property="og:description" content="${siteConfig.footer.description}">
  <meta property="og:type" content="website">
  <meta property="og:url" content="${currentPageUrl}">
  <meta property="og:image" content="${siteBaseUrl}/icon-512.png">
  <meta property="og:site_name" content="${siteConfig.siteName}">
  <meta property="og:locale" content="zh_CN">

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@vista8">
  <meta name="twitter:creator" content="@vista8">
  <meta name="twitter:title" content="${siteConfig.siteName}">
  <meta name="twitter:description" content="${siteConfig.footer.description}">
  <meta name="twitter:image" content="${siteBaseUrl}/icon-512.png">

  <!-- Favicon (簡單的 emoji data URI) -->
  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📚</text></svg>">

  <!-- PWA 支援 🆕 -->
  <link rel="manifest" href="/manifest.json">
  <meta name="theme-color" content="#FBBF24">

  <!-- iOS Safari PWA 支援 -->
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
  <meta name="apple-mobile-web-app-title" content="${siteConfig.itemName}學習">
  <link rel="apple-touch-icon" href="/icon-192.png">

  <!-- Google Fonts -->
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">

  <!-- 樣式 -->
  <link rel="stylesheet" href="css/minimal.css">
</head>

關鍵原則： - ✅ 核心學習模式（閃卡、學習、測試）保持一致 - 參考 core-patterns.md - ✅ 設計風格（配色、字型、佈局）保持一致 - 參考 design-system.md - ✅ 所有文案、標題、描述由AI根據主題創作 - ✅ 程式碼質量：必須遵守 code-quality.md 標準（錯誤處理、XSS防護、DOM安全）🆕 - ✅ PWA 支援：manifest.json + Service Worker + 圖示（離線訪問、可安裝）🆕 - ✅ SEO 最佳化：完整的 meta 標籤 + sitemap.xml + robots.txt + 結構化資料 🆕 - ✅ 語義化 HTML：正確使用 header, main, article, section 等標籤 🆕 - ✅ 移動端優先：響應式設計 + viewport meta + 快速載入（< 3秒）🆕 - ❌ 不要硬編碼特定領域的內容

Step 4: 建立專案結構

# 專案位置
mkdir -p "/Users/joe/Dropbox/code/${topic}-workshop"
cd "/Users/joe/Dropbox/code/${topic}-workshop"

# 建立目錄結構
mkdir -p js css

# 寫入資料
cat > js/wordData.js << 'EOF'
const WordRoots = [...];
EOF

# 寫入配置 🆕
cat > js/siteConfig.js << 'EOF'
const siteConfig = {...};
EOF

# 寫入頁面（AI生成的HTML）
cat > index.html << 'EOF'
[AI生成的index.html]
EOF

# 寫入其他頁面...

# 🆕 自動生成 PWA 圖示（用 PIL）
python3 << 'PYEOF'
from PIL import Image, ImageDraw, ImageFont

def create_icon(size, filename, text):
    # 建立黃色背景
    img = Image.new('RGB', (size, size), color='#FBBF24')
    draw = ImageDraw.Draw(img)

    # 嘗試使用系統字型
    try:
        font_size = int(size * 0.25)
        font = ImageFont.truetype('/System/Library/Fonts/PingFang.ttc', font_size)
    except:
        font = ImageFont.load_default()

    # 獲取文字邊界框
    bbox = draw.textbbox((0, 0), text, font=font)
    text_width = bbox[2] - bbox[0]
    text_height = bbox[3] - bbox[1]

    # 居中位置
    x = (size - text_width) / 2
    y = (size - text_height) / 2

    # 繪製文字（深灰色）
    draw.text((x, y), text, font=font, fill='#1F2937')

    # 儲存
    img.save(filename, 'PNG')

# 從主題生成圖示文字（取前2-3個字）
icon_text = "${siteConfig.itemName}"[:3]  # 例如："概念" → "概念"、"歷史知識點" → "歷史知"

# 生成兩種尺寸
create_icon(192, 'icon-192.png', icon_text)
create_icon(512, 'icon-512.png', icon_text)
print("✓ PWA 圖示生成完成")
PYEOF

Step 5: 資料驗證（強制質量檢查）

⚠️ 關鍵：AI 生成的資料必須經過完整驗證，確保質量和一致性

# ========================================
# 階段 1：基礎結構驗證
# ========================================

echo "🔍 驗證資料結構..."

# 1.1 檢查資料檔案存在且變數名正確
if ! grep -q "const WordRoots" js/wordData.js; then
  echo "❌ 錯誤：資料變數名不正確（應為 const WordRoots）"
  exit 1
fi

# 1.2 檢查配置檔案存在且變數名正確
if ! grep -q "const siteConfig" js/siteConfig.js; then
  echo "❌ 錯誤：配置檔案缺失（應為 const siteConfig）"
  exit 1
fi

# ========================================
# 階段 2：資料完整性驗證
# ========================================

echo "🔍 驗證資料完整性..."

# 2.1 使用 Node.js 進行深度驗證
node -e "
const fs = require('fs');

// 讀取資料檔案
const dataContent = fs.readFileSync('js/wordData.js', 'utf-8');
eval(dataContent);  // 載入 WordRoots

let errors = [];
let warnings = [];

// 驗證資料存在
if (typeof WordRoots === 'undefined') {
  console.error('❌ 嚴重錯誤：WordRoots 未定義');
  process.exit(1);
}

if (!Array.isArray(WordRoots) || WordRoots.length === 0) {
  console.error('❌ 嚴重錯誤：WordRoots 為空或不是陣列');
  process.exit(1);
}

console.log(\`📊 資料量：\${WordRoots.length} 個知識點\`);

// 遍歷每個知識點進行驗證
WordRoots.forEach((item, index) => {
  const itemLabel = \`Item #\${item.id || index}\`;

  // 必需欄位檢查
  if (!item.id) errors.push(\`\${itemLabel}: 缺少 id\`);
  if (!item.root || item.root.trim() === '') errors.push(\`\${itemLabel}: 缺少 root（知識點名稱）\`);
  if (!item.origin) warnings.push(\`\${itemLabel}: 缺少 origin（分類）\`);
  if (!item.meaning || item.meaning.trim() === '') errors.push(\`\${itemLabel}: 缺少 meaning（簡短解釋）\`);
  if (!item.description || item.description.trim() === '') errors.push(\`\${itemLabel}: 缺少 description（詳細說明）\`);

  // 描述長度檢查（應該詳細但不過長）
  if (item.description && item.description.length < 50) {
    warnings.push(\`\${itemLabel}: description 太短（<50字），建議擴充套件為200-300字\`);
  }
  if (item.description && item.description.length > 1000) {
    warnings.push(\`\${itemLabel}: description 太長（>1000字），建議精簡\`);
  }

  // 例子檢查
  if (!item.examples || !Array.isArray(item.examples)) {
    errors.push(\`\${itemLabel}: 缺少 examples 陣列\`);
  } else if (item.examples.length < 3) {
    errors.push(\`\${itemLabel}: examples 少於3個（當前 \${item.examples.length}）\`);
  } else {
    // 驗證每個例子的結構
    item.examples.forEach((ex, exIndex) => {
      if (!ex.word) errors.push(\`\${itemLabel}.examples[\${exIndex}]: 缺少 word\`);
      if (!ex.meaning) errors.push(\`\${itemLabel}.examples[\${exIndex}]: 缺少 meaning\`);
      if (!ex.explanation) warnings.push(\`\${itemLabel}.examples[\${exIndex}]: 缺少 explanation\`);
    });
  }

  // 測試題檢查
  if (!item.quiz) {
    warnings.push(\`\${itemLabel}: 缺少 quiz（測試題）\`);
  } else {
    if (!item.quiz.question || item.quiz.question.trim() === '') {
      errors.push(\`\${itemLabel}.quiz: 缺少 question\`);
    }
    if (!item.quiz.options || !Array.isArray(item.quiz.options)) {
      errors.push(\`\${itemLabel}.quiz: 缺少 options 陣列\`);
    } else if (item.quiz.options.length !== 4) {
      errors.push(\`\${itemLabel}.quiz: options 必須是4個（當前 \${item.quiz.options.length}）\`);
    }
    if (typeof item.quiz.correctAnswer !== 'number') {
      errors.push(\`\${itemLabel}.quiz: correctAnswer 必須是數字\`);
    } else if (item.quiz.correctAnswer < 0 || item.quiz.correctAnswer > 3) {
      errors.push(\`\${itemLabel}.quiz: correctAnswer 越界（必須是0-3，當前 \${item.quiz.correctAnswer}）\`);
    }
  }
});

// 輸出驗證結果
if (errors.length > 0) {
  console.error('\\n❌ 發現 ' + errors.length + ' 個錯誤：');
  errors.slice(0, 10).forEach(e => console.error('  - ' + e));
  if (errors.length > 10) console.error(\`  ... 還有 \${errors.length - 10} 個錯誤\`);
  process.exit(1);
}

if (warnings.length > 0) {
  console.warn('\\n⚠️  發現 ' + warnings.length + ' 個警告：');
  warnings.slice(0, 5).forEach(w => console.warn('  - ' + w));
  if (warnings.length > 5) console.warn(\`  ... 還有 \${warnings.length - 5} 個警告\`);
}

console.log('\\n✓ 資料驗證通過');
" || exit 1

# ========================================
# 階段 3：配置驗證
# ========================================

echo "🔍 驗證配置..."

node -e "
const fs = require('fs');
const configContent = fs.readFileSync('js/siteConfig.js', 'utf-8');
eval(configContent);

if (typeof siteConfig === 'undefined') {
  console.error('❌ siteConfig 未定義');
  process.exit(1);
}

// 驗證必需欄位
const required = ['topic', 'siteName', 'itemName', 'itemCount', 'hero', 'stats', 'footer', 'cta'];
const missing = required.filter(key => !siteConfig[key]);

if (missing.length > 0) {
  console.error('❌ siteConfig 缺少欄位：' + missing.join(', '));
  process.exit(1);
}

// 驗證 hero 結構
if (!siteConfig.hero.title || !Array.isArray(siteConfig.hero.title) || siteConfig.hero.title.length !== 3) {
  console.error('❌ siteConfig.hero.title 必須是3行陣列');
  process.exit(1);
}

console.log('✓ 配置驗證通過');
" || exit 1

echo ""
echo "✅ 所有驗證通過！"

Step 6: 部署（強制安全檢查）

⚠️ 關鍵：每個專案必須獨立部署，絕不共享 GitHub 倉庫

部署流程（必須嚴格按順序執行）：

# ========================================
# 階段 1：部署前安全檢查（必須執行）
# ========================================

# 1.1 檢查並移除 Git 遠端倉庫（防止關聯到其他專案的倉庫）
if git remote -v 2>/dev/null | grep -q 'origin'; then
  echo "⚠️ 警告：檢測到 Git 遠端倉庫，立即移除以避免衝突"
  git remote remove origin
  echo "✓ 已移除 Git 遠端倉庫"
fi

# 1.2 初始化本地 Git（僅本地，不推送到 GitHub）
git init
git add .
git commit -m "Initial commit: ${siteName}"

# 1.3 列出所有現有 workshop 專案（用於後續驗證）
echo "📋 現有專案列表："
ls -d /Users/joe/Dropbox/code/*-workshop 2>/dev/null | while read dir; do
  PROJECT_NAME=$(basename "$dir")
  if [ -f "$dir/.vercel/project.json" ]; then
    PROJECT_ID=$(cat "$dir/.vercel/project.json" | jq -r '.projectId' 2>/dev/null || echo "unknown")
    echo "  - $PROJECT_NAME (projectId: $PROJECT_ID)"
  fi
done

# ========================================
# 階段 2：執行部署
# ========================================

echo "🚀 開始部署到 Vercel..."
vercel --prod --yes 2>&1 | tee /tmp/vercel-deploy-${projectName}.log

DEPLOY_STATUS=$?
if [ $DEPLOY_STATUS -ne 0 ]; then
  echo "❌ 部署失敗，請檢查日誌：/tmp/vercel-deploy-${projectName}.log"
  exit 1
fi

# ========================================
# 階段 3：部署後強制驗證（必須執行）
# ========================================

echo ""
echo "🔍 部署後驗證..."

# 3.1 驗證 projectId 已生成
if [ ! -f ".vercel/project.json" ]; then
  echo "❌ 錯誤：未找到 .vercel/project.json"
  exit 1
fi

NEW_PROJECT_ID=$(cat .vercel/project.json | jq -r '.projectId')
NEW_PROJECT_NAME=$(cat .vercel/project.json | jq -r '.projectName')
echo "✓ 新專案："
echo "  名稱: $NEW_PROJECT_NAME"
echo "  ID: $NEW_PROJECT_ID"

# 3.2 提取部署 URL
DEPLOY_URL=$(grep -E "Production:|https://.*vercel.app" /tmp/vercel-deploy-${projectName}.log | grep -o "https://[^ ]*vercel.app" | head -1)
echo "✓ 部署 URL: $DEPLOY_URL"

# 3.3 驗證新網站可訪問
echo "🌐 驗證新網站..."
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$DEPLOY_URL" || echo "000")
if [ "$HTTP_STATUS" = "200" ] || [ "$HTTP_STATUS" = "304" ]; then
  echo "✓ 新網站可正常訪問 (HTTP $HTTP_STATUS)"
else
  echo "⚠️ 警告：新網站返回 HTTP $HTTP_STATUS"
fi

# 3.4 檢查其他專案是否受影響（關鍵步驟）
echo ""
echo "🔍 檢查其他專案是否受影響..."
AFFECTED_PROJECTS=0

for dir in /Users/joe/Dropbox/code/*-workshop; do
  if [ "$dir" = "/Users/joe/Dropbox/code/${projectName}" ]; then
    continue  # 跳過當前專案
  fi

  if [ -f "$dir/.vercel/project.json" ]; then
    OLD_PROJECT_NAME=$(basename "$dir")
    OLD_PROJECT_ID=$(cat "$dir/.vercel/project.json" | jq -r '.projectId' 2>/dev/null)

    # 檢查是否有相同的 projectId（這表示衝突）
    if [ "$OLD_PROJECT_ID" = "$NEW_PROJECT_ID" ]; then
      echo "❌ 嚴重錯誤：專案 $OLD_PROJECT_NAME 的 projectId 與新專案相同！"
      echo "   這意味著新專案覆蓋了舊專案，需要立即修復。"
      AFFECTED_PROJECTS=$((AFFECTED_PROJECTS + 1))
    fi
  fi
done

if [ $AFFECTED_PROJECTS -gt 0 ]; then
  echo ""
  echo "❌ 檢測到 $AFFECTED_PROJECTS 個專案受影響，部署失敗！"
  echo "   請手動檢查並修復衝突。"
  exit 1
fi

echo "✓ 所有現有專案未受影響"

# ========================================
# 階段 3.5：移動端和 SEO 驗證 🆕
# ========================================

echo ""
echo "📱 驗證移動端適配..."

# 檢查 viewport meta 標籤（移動端必需）
VIEWPORT_CHECK=$(curl -s "$DEPLOY_URL" | grep -c 'viewport')
if [ "$VIEWPORT_CHECK" -gt 0 ]; then
  echo "✓ 移動端 viewport 配置正確"
else
  echo "⚠️ 警告：缺少 viewport meta 標籤，移動端可能顯示異常"
fi

# 檢查 SEO meta 標籤
echo "🔍 驗證 SEO 配置..."
META_DESCRIPTION=$(curl -s "$DEPLOY_URL" | grep -c 'meta name="description"')
META_OG=$(curl -s "$DEPLOY_URL" | grep -c 'property="og:')

if [ "$META_DESCRIPTION" -gt 0 ]; then
  echo "✓ SEO description 已配置"
else
  echo "⚠️ 警告：缺少 SEO description"
fi

if [ "$META_OG" -gt 0 ]; then
  echo "✓ Open Graph 標籤已配置（社交分享最佳化）"
else
  echo "⚠️ 警告：缺少 Open Graph 標籤"
fi

# 模擬移動裝置訪問測試
echo "📱 模擬移動裝置訪問..."
MOBILE_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1" \
  "$DEPLOY_URL")

if [ "$MOBILE_STATUS" = "200" ] || [ "$MOBILE_STATUS" = "304" ]; then
  echo "✓ 移動端訪問正常 (HTTP $MOBILE_STATUS)"
else
  echo "⚠️ 警告：移動端訪問異常 (HTTP $MOBILE_STATUS)"
fi

# ========================================
# 階段 4：成功總結
# ========================================

echo ""
echo "✅ 部署成功！"
echo ""
echo "📊 部署資訊："
echo "  專案名稱: $NEW_PROJECT_NAME"
echo "  專案 ID: $NEW_PROJECT_ID"
echo "  部署 URL: $DEPLOY_URL"
echo "  日誌檔案: /tmp/vercel-deploy-${projectName}.log"

安全原則（必須遵守）：

1. ✅ 禁止 GitHub 關聯：預設不連線 GitHub，避免倉庫共享
2. ✅ 強制前置檢查：部署前必須移除所有 Git 遠端倉庫
3. ✅ 強制後置驗證：部署後必須檢查 projectId 唯一性
4. ✅ 衝突自動檢測：發現衝突立即報錯，不允許繼續
5. ✅ 完整日誌記錄：所有部署操作記錄到 /tmp/

如果仍然發生衝突（極端情況）：

如果驗證通過但實際仍有問題，執行緊急修復：

# 1. 立即列出所有 Vercel 專案
vercel ls

# 2. 檢查每個本地專案的部署狀態
cd /Users/joe/Dropbox/code
for dir in *-workshop; do
  echo "=== $dir ==="
  cd "$dir"
  if [ -f ".vercel/project.json" ]; then
    cat .vercel/project.json | jq -r '.projectName, .projectId'
  fi
  cd ..
done

# 3. 重新部署受影響的專案
cd /path/to/affected-project
vercel --prod --yes

# 4. 向用戶報告衝突詳情和修復結果

成功輸出模板

✅ ${siteName} 已生成並部署！

📁 專案位置：${projectPath}
🌐 網站名稱：${siteName}
📚 知識點數量：${itemCount}個
🔗 訪問連結：${deployUrl}

🎯 核心特性：
- ✅ AI創作首頁：根據主題生成標題、副標題、統計
- ✅ 動態動畫：自動從資料載入，完全適配
- ✅ 通用學習模式：閃卡、漸進學習、測試、索引
- ✅ 極簡設計：清晰的視覺層級，專注內容

🔧 下一步：
1. 開啟網站檢視效果
2. 稽核AI生成的內容
3. 配置自定義域名（Vercel後臺）

實施檢查清單

AI 執行此 skill 時，必須嚴格按順序完成：

• [ ] 1. 理解主題 - 分析領域特點、價值、受眾、表達方式
• [ ] 2. 生成資料 - 建立 wordData.js（const WordRoots）
• [ ] 3. 生成配置 🆕 - 建立 siteConfig.js（AI創作首頁文案）
• [ ] 4. 生成頁面 🆕 - 參考設計系統，從零生成HTML（不復制模板）
• [ ] 5. 建立專案 - mkdir + 寫入所有檔案
• [ ] 6. 驗證資料 - 檢查資料和配置檔案完整性
• [ ] 7. 安全部署 🔒 - 執行 Step 6 的完整部署流程（含前置檢查 + 部署 + 後置驗證）
• [ ] 8. 返回資訊 - 專案路徑 + URL + 核心特性 + 安全檢查結果

關鍵改進（相比舊版）

❌ 舊版問題

• 依賴模板複製（cp -r word-root-workshop）
• 用 sed 粗暴替換文案
• 首頁文案硬編碼，不適配主題
• 動畫示例寫死英文單詞

✅ 新版優勢

• 零模板依賴，AI從零生成頁面
• AI理解主題後創作所有文案
• 首頁完全適配主題特點
• 動畫自動從資料載入

🎯 核心理念轉變

舊版：複製 + 替換
新版：理解 + 創作

舊版：模板驅動
新版：設計系統驅動

舊版：硬編碼文案
新版：AI創作內容

注意事項

⚠️ 資料結構不變： - 仍然使用 const WordRoots 和固定欄位結構 - 這是核心學習模式（閃卡、學習、測試）的基礎

⚠️ 設計風格保持： - 極簡主義、黃色主題色、Inter字型 - 這些是品牌識別度的保證

⚠️ AI自由發揮： - 首頁文案、統計資料、介紹文本 - 根據主題特點創作，不要千篇一律

Vercel 部署最佳實踐 🆕

問題背景

Vercel 在部署時可能會自動連線 GitHub 倉庫，導致多個專案共享同一個倉庫，引發部署衝突： - 新專案覆蓋舊專案的部署 - 舊專案的 URL 失效 - GitHub 倉庫關聯混亂

解決方案

1. 預設不連線 GitHub

# 僅使用本地 Git，不推送到 GitHub
git init
git add .
git commit -m "Initial commit"
vercel --prod --yes  # 只部署，不連線 GitHub

2. 部署後驗證

# 檢查生成的 projectId 是否唯一
cat .vercel/project.json

# 應該看到類似：
# {"projectId":"prj_UNIQUE_ID_HERE",...}

3. 發現衝突時的補救

如果部署後發現舊專案受影響：

# 立即進入舊專案目錄
cd /Users/joe/Dropbox/code/舊專案名稱

# 重新部署舊專案
vercel --prod --yes

# 確認舊專案恢復正常
curl -I https://舊專案URL

故障排查清單

部署新專案後，必須檢查：

• [ ] 新專案的 .vercel/project.json 中的 projectId 是否唯一
• [ ] 新專案的 Production URL 是否可以訪問（HTTP 200）
• [ ] 舊專案（如果存在）的 URL 是否仍然可訪問
• [ ] 部署日誌中的 "Linked to" 資訊是否正確

經驗教訓（真實生產事故）

事故時間線：2026-02-25

事故描述： 1. 生成 evolutionary-psychology-workshop（進化心理學），成功部署 2. 生成 design-aesthetics-workshop（設計美學），成功部署 3. 使用者發現 word.qiaomu.ai（原詞根詞綴網站）顯示的是進化心理學內容 4. 檢查發現 word-root-workshop 專案的 Git 倉庫被進化心理學內容覆蓋

根本原因分析：

# 事故前的狀態
evolutionary-psychology-workshop → origin: https://github.com/joeseesun/word-root-workshop.git
word-root-workshop              → origin: https://github.com/joeseesun/word-root-workshop.git
                                   ↑↑↑ 兩個專案共享同一個 GitHub 倉庫

為什麼會發生： - 舊版 skill 使用 cp -r word-root-workshop 複製模板 - 複製時連 .git/ 目錄也一起復制了（包含遠端倉庫配置） - 部署時 Vercel 檢測到 Git 遠端倉庫，自動關聯 - 多個專案關聯同一個 GitHub 倉庫，後部署的覆蓋先部署的

損害範圍： - ⛔ word.qiaomu.ai（生產域名）顯示錯誤內容 - ⛔ word-root-workshop 的 Git 歷史被汙染 - ⛔ 使用者體驗受損，需要緊急修復

緊急修復步驟：

# 1. 恢復 word-root-workshop 到原始狀態
cd /Users/joe/Dropbox/code/word-root-workshop
git log --oneline  # 找到原始提交
git reset --hard 14cc7b0  # 恢復到原始詞根詞綴內容

# 2. 修復 vercel.json 配置衝突
# 移除不相容的 routes 配置

# 3. 重新部署
vercel --prod --yes

# 4. 驗證恢復
curl -sL https://word.qiaomu.ai/ | grep "詞根詞綴記憶工坊"

# 5. 清理其他專案的 Git 遠端倉庫
cd /Users/joe/Dropbox/code/evolutionary-psychology-workshop
git remote remove origin

徹底解決方案（已在 Step 6 實施）：

1. 強制前置檢查：部署前自動移除所有 Git 遠端倉庫
2. 強制後置驗證：部署後檢查 projectId 唯一性
3. 衝突自動檢測：遍歷所有專案，發現相同 projectId 立即報錯
4. 完整日誌記錄：所有部署操作記錄到 /tmp/
5. 零容忍策略：任何檢測到的衝突都不允許繼續

長期防範措施： - ✅ 廢棄模板複製機制（cp -r），改用從零生成 - ✅ 在 Step 6 中實施強制安全檢查 - ✅ 更新實施檢查清單，明確"安全部署"步驟 - ✅ 文件中增加"經驗教訓"章節，防止後人重蹈覆轍

教訓總結：

"Copy + Paste 是萬惡之源。模板驅動看似高效，實則埋下了隱患。只有從零生成（設計系統驅動），才能確保每個專案真正獨立。"

影響： - 促使 skill 從"模板驅動"徹底重構為"設計系統驅動" - 確立了"零模板依賴"的核心原則 - 建立了完善的部署安全檢查機制

批次更新機制 🔄

使用場景

當 skill 的設計系統有更新（如 CSS bug 修復、樣式改進）時，需要將更新同步到所有已部署的 workshop 專案。

典型場景： - CSS 樣式修復：修復了響應式佈局問題 - 設計改進：優化了卡片陰影、間距、配色 - 功能增強：添加了新的互動動效 - 安全更新：修復了 XSS 漏洞或其他安全問題

更新指令碼

指令碼位置：scripts/update-css.sh

使用方法：

# 1. 演練模式（僅列出將更新的專案）
bash scripts/update-css.sh --dry-run

# 2. 執行更新
bash scripts/update-css.sh

工作流程

指令碼自動執行以下步驟：

1. 掃描專案：自動掃描 /Users/joe/Dropbox/code/*-workshop
2. 智慧對比：使用 cmp 命令對比 CSS 檔案，跳過已是最新版本的專案
3. 安全備份：更新前自動備份舊 CSS 為 .backup 檔案
4. Git 提交：自動 commit CSS 變更（commit message: chore: update CSS from skill template）
5. 重新部署：呼叫 vercel --prod --yes 重新部署到生產環境
6. 失敗回滾：如果部署失敗，自動恢復備份的 CSS
7. 統計報告：輸出更新統計（成功/跳過/失敗專案數量）

使用示例

步驟 1：準備最新的 CSS

在 skill 目錄中修復或改進 templates/minimal.css：

cd /Users/joe/.claude/skills/knowledge-site-creator
# 編輯 templates/minimal.css
# 修復 bug 或改進樣式

步驟 2：預覽將更新的專案

bash scripts/update-css.sh --dry-run

輸出示例：

🔍 演練模式（不會實際更新）

📁 CSS 原始檔：/path/to/templates/minimal.css
📊 檔案大小：12345 bytes

🔍 掃描 workshop 專案...

================================================
📦 專案：evolutionary-psychology-workshop
📝 將更新：/path/to/evolutionary-psychology-workshop/css/minimal.css
📝 將重新部署到 Vercel

================================================
📦 專案：word-root-workshop
✓ 跳過：CSS 已是最新版本

================================================
📊 更新總結

  ✅ 成功更新：1 個專案
  ⚠️  跳過：1 個專案

💡 這是演練模式，沒有實際執行任何操作
   要實際執行，請執行：bash scripts/update-css.sh

步驟 3：執行批次更新

bash scripts/update-css.sh

輸出示例：

================================================
📦 專案：evolutionary-psychology-workshop
💾 已備份舊 CSS：/path/to/css/minimal.css.backup
✓ 已更新 CSS
🚀 重新部署到 Vercel...
✅ 部署成功

================================================
📊 更新總結

  ✅ 成功更新：1 個專案
  ⚠️  跳過：1 個專案

安全特性

1. 智慧跳過：自動跳過已是最新版本的專案，避免不必要的部署
2. 自動備份：更新前備份舊 CSS 為 .backup 檔案
3. 失敗回滾：部署失敗時自動恢復備份
4. Git 記錄：所有更新都有 Git commit，可追溯歷史
5. 演練模式：--dry-run 模式讓你先看看會更新什麼

注意事項

⚠️ 更新前檢查： - 確保 templates/minimal.css 已經過測試 - 使用 --dry-run 先預覽將更新的專案 - 檢查是否有專案正在被使用者訪問（避免高峰期更新）

⚠️ 更新後驗證： - 指令碼完成後，隨機抽查 2-3 個專案的網站 - 確認新樣式生效且沒有破壞佈局 - 檢查移動端顯示是否正常

⚠️ 失敗處理： - 如果某個專案部署失敗，指令碼會自動回滾該專案的 CSS - 失敗的專案不影響其他專案的更新 - 可以手動進入失敗的專案目錄，使用 vercel --prod --yes 重試

擴充套件性

未來可擴充套件的更新型別：

當前指令碼僅支援 CSS 更新，但同樣的機制可以擴充套件到： - JavaScript 檔案更新（js/storage.js 等） - HTML 模板更新（如修復 meta 標籤缺失） - 配置檔案更新（vercel.json 等） - 批次遷移（如資料結構變更）

擴充套件方法：參考 update-css.sh 建立類似指令碼，如 update-storage.sh、update-meta-tags.sh 等。

這個Skill質量紮實可靠，能一鍵生成漂亮的學習網站。文件齊全、程式碼規範、功能豐富（閃卡、測試、進度追蹤都有），還支援離線訪問和SEO最佳化。適合想快速建立知識學習站點的使用者，但目前只在Mac和Linux上能用，Windows使用者暫時無法使用。