隔代共學 AI 媒合系統 — Hackathon DEMO Skeleton

這個專案骨架是為了 新竹市赤土崎多功能館「隔代共學 AI 媒合系統」 黑客松 DEMO 設計：

• 🎨 前端：frontend/ — 靜態 HTML / CSS / JS，包含：
  • Hero 區塊（赤土崎 3D 場景嵌入位子）
  • 「價值流程」敘事區塊
  • 以 Puter.js + Gemini 3 Pro 實作的 Pitch Coach 區塊
  • 可自動呼叫圖片 API 的「情境圖像自動配圖」區塊
• 🧠 AI / 工具：
  • server/ — Node + TypeScript：
    • /api/images：代理呼叫 Pexels API 做圖片搜尋（前端使用）
    • /mcp：同一個程式同時作為 MCP 伺服器，提供 search_images 工具給 Claude Code
• 🧩 Claude 整合：
  • CLAUDE.md：給 Claude Code 的專案說明與偏好
  • skills/tw-frontend-intergen/SKILL.md：在地化的前端設計 Skill，可打包成 zip 上傳到 Claude Skills

---

目標

1. 讓評審一眼看懂：誰被服務、AI 做什麼、落地在哪裡（赤土崎館）
2. 在 DEMO 畫面中，同時看到：
   • 有「哇」感的 3D / 動畫（預留 Spline / Rive 嵌入位置）
   • 清楚的服務流程與價值主張
   • 真的有在跑的 LLM（Gemini 3 Pro 幫你寫 Pitch / 文字）

---

快速啟動

1. 啟動影像搜尋 + MCP 伺服器

cd server
npm install
cp .env.example .env  # 填入你的 Pexels API key
npm run dev

• 伺服器預設在 http://localhost:3000
  • GET /api/images?q=...：回傳 { images: [...] }
  • POST /mcp：MCP HTTP endpoint

將伺服器加入 Claude Code 的 MCP 設定：

claude mcp add --transport http hsinchu-images http://localhost:3000/mcp

2. 開啟前端 DEMO

前端是純靜態檔案，任何靜態 server 都可以，例如：

cd frontend
python -m http.server 4173
# 或用你喜歡的 dev server

然後瀏覽 http://localhost:4173。

---

Pexels API 設定

1. 前往 Pexels 開發者頁申請免費 API key（用於非商業 demo 足夠）。
2. 把 key 寫入 server/.env 的 PEXELS_API_KEY。
3. Demo 會自動在頁面顯示「Photos from Pexels」作為授權標示。

⚠️ 真實上線時，請不要把 API key 放在前端程式碼中，本專案骨架已將呼叫放在後端 server/。

---

Claude Skills 使用方式（前端設計最佳實踐）

1. 將 skills/tw-frontend-intergen 資料夾獨立壓成一個 zip（例如 tw-frontend-intergen.zip）。

2. 到 claude.ai → Settings → Skills → 上傳這個 zip。

3. 在 Claude Code 中工作時，只要你提到：

   • 「調整前端 UI」
   • 「改 hero 區 layout」
   • 「幫我美化赤土崎 demo 頁」

   Claude 會自動考慮這個 Skill，並依照其中的在地化設計準則（台灣字型、色彩、Layout）來改 code。

---

專案結構概覽

intergen-hsinchu-hackathon/
├─ README.md                 # 本說明檔
├─ CLAUDE.md                 # 給 Claude Code 的專案說明
├─ frontend/
│  ├─ index.html             # DEMO 主頁（含 Puter.js, Spline 位置）
│  ├─ styles.css             # 主題配色、排版、元件樣式
│  └─ main.js                # 圖片自動配圖 + Gemini Pitch Coach
├─ server/
│  ├─ package.json
│  ├─ tsconfig.json
│  ├─ .env.example
│  └─ src/
│     └─ server.ts           # Express + MCP + Pexels 圖片搜尋
└─ skills/
   └─ tw-frontend-intergen/
      └─ SKILL.md            # 為本專案打造的前端設計 Skill

你可以直接在這個資料夾跑 claude code .,把它當成黑客松專案的起點來擴充。

---

測試

本專案採用 TDD (測試驅動開發) 和 Boy Scout Rule 原則,確保程式碼品質。

執行後端測試

cd server

# 執行所有測試(一次性)
npm test

# 執行測試並監聽變更(開發模式)
npm run test:watch

# 執行測試並產生覆蓋率報告
npm run test:coverage

# 執行測試並開啟 UI 介面
npm run test:ui

測試架構

• 單元測試: src/__tests__/imageSearch.test.ts

  • 測試圖片搜尋邏輯、查詢處理、錯誤處理
  • 測試資料對映、URL 建構等核心功能

• 整合測試: src/__tests__/api.test.ts

  • 測試 /api/images HTTP 端點
  • 測試 CORS 設定
  • 測試錯誤回應格式

測試原則

1. TDD: 先寫測試再寫實作,確保功能正確性
2. Boy Scout Rule: 讓程式碼比發現時更乾淨
3. Small CLs: 小步驟提交,每次只改一件事

CI/CD 注意事項

在 CI 環境中執行測試時:

• 測試設計為可在無 Pexels API key 的環境下執行
• API 測試會檢查 200 或 500 狀態碼,兩者皆可接受
• 建議在 CI 中設定 PEXELS_API_KEY 環境變數以測試完整功能

---

開發指南

錯誤處理

• 前端 (main.js, admin.js):

  • 包含 getUserFriendlyErrorMessage() 工具函數
  • 自動判斷網路錯誤、伺服器錯誤等情況
  • 提供使用者友善的錯誤訊息

• 後端 (server.ts):

  • 完整的型別定義 (TypeScript strict mode)
  • Try-catch 錯誤處理覆蓋所有 API 端點
  • 結構化的錯誤回應格式

程式碼品質

• TypeScript strict mode 啟用
• 完整的型別定義,避免 any
• 錯誤處理一致性
• 清楚的註解與文件

---

部署檢查清單

在正式展示前,請確認:

• Pexels API key 已設定於 server/.env
• 後端伺服器正常啟動於 http://localhost:3000
• 前端可正常存取後端 /api/images 端點
• Puter.js 已正常載入 (Gemini 3 Pro 功能)
• 所有測試通過 (npm test)
• (選配) Spline 3D 場景 URL 已更新
• (選配) Rive 動畫檔案已放置於 frontend/assets/rive/