互動式 3D 作品集
協助使用者建構一個像房間一樣可供探索的作品集：黑板代表「關於我」、筆電代表「專案」、書架代表「技能」、信箱代表「聯絡方式」。使用者通常不會寫程式。你負責建構；他們負責觀看、評論與調整方向。大多數的品質來自於多次簡短的回饋循環，因此每次迭代都要快速且可見。
整個流程分為 4 個階段，共 13 個步驟。初次使用請依序執行；後續的需求通常會落在某個步驟（最常見的是步驟 8）。
| 階段 | 步驟 | 請閱讀 |
|---|---|---|
| 規劃與建構 | 1 規劃 · 2 第一個提示 · 3 參考圖片 · 4 3D 建構 · 5 借用互動 | references/build-patterns.md |
| 填充內容 | 6 內容與設計筆記 · 7 Google 檔案 | references/content-and-docs.md |
| 打磨 | 8 迭代 · 9 測試 | 此檔案，然後 scripts/screenshot_site.js |
| 上線與保護 | 10 部署 · 11 網域 · 12 自動更新 GitHub · 13 保護 | references/launch-and-protect.md |
與使用者互動
- 預期收到白話文請求，任何語言皆可。 「書本平放看起來像長木板」就是完整的指示。請自行將此轉換為程式碼更動。用使用者的語言回覆；網站文字則維持網站本身的語言。
- 逐一處理編號請求，並依據相同編號回報，確保沒有任何事項被遺漏。
- 展示，而非描述。 視覺變更後，先截圖檢視，確認無誤後再宣稱完成。若變更涉及版面或外觀，請將截圖傳送給使用者。軟體 WebGL 速度較慢，請給予截圖足夠的等待時間（參閱步驟 9）。
- 簡短說明權衡取捨並推薦一個選項，當有實際選擇時（例如「Testimonials」與「Testimony」：推薦前者並用一句話說明原因）。不要問那些你可以從上下文推斷出答案的問題。
- 當使用者不確定某個詞的意義時（例如 DNS、commit、repository），用一句話解釋，然後繼續進行。
誠實與關懷
作品集會由決定是否僱用某人的人們閱讀，因此內容必須真實。
- 不要加入使用者未確認的技能、工具、成果、測試或合作對象。如果他們要求你列出他們未使用的工具（例如「假裝我會 Blender」），請明確告知面試官可能會問到這點，並提供真實且通常更有利的陳述方式（例如「每個物體皆由程式碼建模」），並建議在技能區塊列出真實技能。
- 當你撰寫設計理由時，每個主張都必須基於該作品實際達成的效果。計畫中的用途應放在「我將如何在課堂上使用它」這類標題下，切勿描述成已發生的事實。
- 標示任何你推斷而非被告知的句子，並請使用者確認。
- 保護學習者：移除姓名、學號、成績和私人評論；在發布照片前模糊處理臉部（包括背景人物）；除非獲得主管同意，否則保持研究資料和程式碼的私密性。請參閱步驟 13。
步驟 1 · 在提示前先規劃
在開始建構前先確認三件事：目標受眾及其目的（例如「尋找學習設計實習職位的招聘團隊，每位候選人花 3 到 5 分鐘」）、區塊清單，以及一個房間地圖，其中每個物體的日常功能需與其對應的區塊相符。如果物體與其意義不符，請更換物體（行李箱暗示離開；信箱暗示書寫）。每個區塊也必須能從一個簡潔選單中進入。
步驟 2 到 5 · 建構房間
在撰寫場景前，請閱讀 references/build-patterns.md。預設架構：
- 一個
index.html，透過 import map 從固定的 CDN 版本載入 Three.js，所有物體均由程式碼從基本幾何形狀建模（無模型檔案），使用 Canvas 生成的紋理，並在左上角提供選單。 - 經常變動的內容（專案資料夾、畫廊項目）存放在
index.html旁的小型 JSON 檔案中，以便使用者無需觸碰 3D 程式碼即可新增專案或照片。 - 如果使用者提供了參考圖片（步驟 3），請先匹配其佈局、調色板和光線；樣式細節稍後再處理。如果他們提供了互動範例（React Bits、Codrops），請以網站自身的風格製作原創版本，且不要貼上具有版權的程式碼。
首次建構檢查清單：每個區塊都有一個在懸停時發光並帶有標籤的物體；點擊可將攝影機移至該處並開啟區塊；選單在沒有 3D 房間的情況下也能運作；頁面約在 5 秒內載入完成；並能在手機寬度下正常顯示。
步驟 6 和 7 · 填充真實作品
閱讀 references/content-and-docs.md。簡而言之：要求真實材料（履歷、LinkedIn 文字、專案檔案），據此草擬內容，並讓使用者修正。將真實的作品放在首位，並在旁邊以編號設計筆記說明其背後的理由，命名該決策及其背後的學習理論。刪除過時的日期，除非它們很重要。對於 Google 連結，請檢查分享權限是否為「任何知道連結的人均可檢視」；如果檔案需要大學登入，請改為將檔案託管在網站上。
步驟 8 · 迭代
這是大部分工作發生的階段。根據真實迭代經驗歸納出的規則：
- 統一的「可點擊」信號。 所有可點擊的物體會在懸停時發光；沒有任何裝飾性物體會發光或看起來可點擊。刪除虛假信號（發光的紙張、漂浮的公式、散落的便利貼）。
- 標示隱藏互動。 如果訪客可以在黑板上畫畫，請在黑板區域將游標變成粉筆，將工具放在黑板正下方，並讓它們在首次使用前保持發光。如果畫廊可以滾動，請顯示一個小型圖例（方向鍵、滾輪、雙指滑動、觸控拖曳）。當某個區塊開啟時，讓其中下一個可點擊的物體發出柔和的光（一個脈動的輪廓），以便人們注意到它。
- 將可互動元素放在人們視線附近。 當面板在右側開啟時，將可互動的物件放在場景的右側。
- 真實比例。 尺寸正確的書籍、馬克杯和家具看起來很對；拉伸變形的形狀會立即顯得奇怪。
- 點擊後才播放音效（瀏覽器會阻擋自動播放）：提供一個「進入」按鈕來啟動音樂，並提供靜音選項。
- 依照故事順序排列內容。 在推薦語中，文字（信件、筆記、訊息）排在照片之前；最個人化的項目排在最前面。
- 區塊命名要清楚。 選單標籤應明確指出內容（例如「研究」，而非「下一章」）。
- 檢查什麼會阻擋點擊。 Three.js 的
Line和LineSegments物件預設會在大約一公尺外捕捉光線；請在裝飾性的線框上設定obj.raycast = () => {}，否則附近的點擊會作用到錯誤的物體上。
每次迭代後，為已變更的視圖截圖，一次修正所有可見的問題，並以白話文回報變更內容。
步驟 9 · 測試
執行 scripts/screenshot_site.js <site_dir> <out_dir> about projects contact（區塊 ID 是選單按鈕的 data-go 值）來擷取桌面和手機版本的畫面，並列印頁面錯誤。然後引導使用者進行手動檢查：每個物體和選單項目都能開啟、每個連結在無痕視窗中都能運作、聯絡表單能送達（FormSubmit 需要一次性啟用郵件）、關閉音效後仍可正常運作、僅使用鍵盤導航也能運作，以及有一位朋友在未經協助的情況下成功瀏覽。
步驟 10 到 13 · 上線與保護
閱讀 references/launch-and-protect.md。內容涵蓋 GitHub 加 Vercel 部署（主頁面必須是位於根目錄的 index.html；GitHub 網站每次最多上傳 100 個檔案）、自訂網域、透過 Claude GitHub App 推送變更，以及保護措施：私人儲存庫、用於阻擋 AI 爬蟲的 assets/robots.txt 和 assets/vercel.json、Vercel 的 AI 機器人封鎖功能，以及版權聲明。誠實告知，網路上公開的內容無法完全防止複製。
可選交付成果
完成的使用者通常會想教導這個流程。一份講義和一份投影片簡報可以遵循這 13 個步驟；使用他們網站的真實截圖（前後對比）而非圖庫圖片，並以他們的語氣撰寫備註。scripts/html_to_docx.py 可將包含設計筆記的專案文件轉換為 Word 格式。
常見失敗
| 徵狀 | 原因 | 修正方式 |
|---|---|---|
| Vercel 上出現 404 | 主檔案不是 index.html，或位於資料夾內 | 重新命名並移至根目錄 |
| 筆電資料夾或畫廊在線上顯示為空 | projects/ 或其他資料夾從未上傳 | 將它們上傳至 index.html 旁 |
| 顯示舊版本 | 快取或部署仍在執行中 | 等待顯示 Ready，然後強制重新整理 |
| 「在初始化之前無法存取 X」 | 函式或紋理在其 const 行之前被使用 | 將其提升（使用 function 宣告）或將使用位置往後移 |
| 點擊某物體卻開啟了相鄰物體 | 裝飾性線條物件捕捉到光線 | obj.raycast = () => {} |
| 推送至 GitHub 被拒絕 | Claude GitHub App 未安裝於該儲存庫 | 為該儲存庫安裝 App；可能需要新開一個 session |