作品集設計

此技能為任何人重新打造一套特定的作品集設計。設計是固定的且已調校完畢。你的工作是收集對方的素材，以合適的語氣撰寫文案，產生網站，確認其正常運作，並在對方同意後上線。

所有內容皆位於此技能資料夾中：

路徑	說明
`template/assets/`	網站的 CSS、JavaScript 模組、字型和第三方函式庫（GSAP、Lenis）。永遠不要為個人編輯：建置時會複製並套用主題。
`scripts/build.mjs`	將 `portfolio.json` 轉換為完成的靜態網站。Node 18+，無依賴項。
`scripts/prepare_photos.py`	裁剪人像（去除背景）並將關於照片裁切成方形。
`scripts/discover_github.mjs`	列出 GitHub 使用者的公開儲存庫，包含 README 標語和橫幅圖片，以便挑選專案。
`scripts/snapshot_github.mjs`	儲存存檔中使用的公開儲存庫列表。
`scripts/render_images.py`	渲染分享卡片（`og.jpg`）和觸控圖示。
`scripts/serve.py`	用於本機預覽已建置網站的伺服器。
`scripts/qa/run_all.py`	瀏覽器品質檢查。建置完成前必須通過此檢查。
`examples/portfolio.example.json`	一個虛構人物的完整設定檔，包含預留位置圖片。
`reference/``	設定檔結構、訪談腳本、設計系統、文案規則、品質檢查、部署指南。

在下列指令中，scripts/... 指的是此技能資料夾（執行時請使用絕對路徑），而 portfolio/... 則是指使用者在其工作目錄中的專案資料夾。

在撰寫設定檔之前，請先閱讀 reference/config-schema.md；在撰寫任何文案之前，請先閱讀 reference/copywriting.md。

基本規則

未經明確同意，不得公開任何內容。 在使用者核准特定步驟之前，不得執行 git push、部署或建立儲存庫。本機建置和預覽則沒有問題。
隱私。 僅使用公開的 GitHub 資料（兩個 GitHub 腳本均有目的地呼叫未經驗證的 API）。在存檔上線之前，請顯示將會顯示的公開儲存庫列表，並詢問哪些要隱藏。除非使用者要求，否則切勿在頁面上放置電話號碼、街道地址或私人儲存庫。
他們的照片屬於他們。 在專案資料夾內處理副本。除了他們核准的網站之外，請勿上傳到任何地方。
設計即是產品。 不要因為使用者提出模糊的要求就增加區塊、更換字型或重新設計元件。請調整內容、主題預設、吉祥物和文案。如果他們想要結構性的變更，請先告知費用並取得確認。
文案是「寫」出來的，不是「填」進去的。 他們的筆記是原始素材。以他們的語氣起草每一行，遵守長度限制，並在建置最終版本之前展示給他們看。

工作流程

1. 檢查工具鏈

node --version          # 18 或更新版本
python --version        # 3.10 或更新版本
python -m pip install playwright pillow numpy
python -m playwright install chromium

人像去背需要執行 python -m pip install "rembg[cpu]"（首次執行會下載約 1 GB 的模型）。如果無法執行，請要求使用者提供已具有透明背景的人像，並使用 --no-cutout 參數。

與使用者協商專案資料夾的名稱（預設為目前目錄下的 ./portfolio/）。目錄結構如下：

portfolio/
  portfolio.json      # 你撰寫的設定檔
  photos/             # 他們的原始照片（絕不會以原始狀態發布）
  work/               # 專案橫幅和截圖
  site/               # 建置輸出：此資料夾即為將要部署的內容

2. 訪談

請遵循 reference/interview.md。訪談分為十個簡短的回合，並對每個具有合理選項的選擇（主題、吉祥物、要重點介紹的儲存庫、要在英雄區塊放置哪些連結）使用 AskUserQuestion。自由形式的素材（個人簡介、專案描述）則以純文字方式詢問。一次只問一個回合，如果他們不想寫，可以主動提出代筆。

領域，依序為：

身分：全名、他們使用的別名或暱稱、簡短的職稱、電子郵件、城市和國家（即時時鐘的時區）、使用的語言。
照片：一張頭肩人像（英雄區塊的鏤空人像），以及一張可用於「關於我」區塊的選用照片。
連結：他們想要列出的所有個人檔案；從中挑選兩到四個放在英雄列。
英雄區塊與關於我：用一句話介紹他們在做什麼，然後用兩個簡短段落描述他們的工作方式。
他們建構的內容：四種工作類型，每種一個詞，附上一行描述和一個懸停動畫（例如：agents、automation、context、launch、code、data、design）。
專案：最多六個重點專案和最多三個 side quests。首先執行 discover_github.mjs 並提出候選項目。
存檔：是否顯示所有公開儲存庫，以及哪些要隱藏。
技術棧：分組的工具列表，以及將成為球池中球體的 12 到 24 個工具。
流程、聯絡方式、跑馬燈：三個流程步驟、聯絡方式行、兩個滾動跑馬燈。
外觀與額外項目：主題預設、吉祥物（名稱、語氣或關閉）、網站 URL 以及託管位置。

3. 收集專案素材

node scripts/discover_github.mjs --user <github-user> --out portfolio/discovery.json
node scripts/discover_github.mjs --user <github-user> --out portfolio/discovery.json --download portfolio/work --repos RepoA,RepoB

第一次執行會列出公開儲存庫，包含它們的 README 標語、圖片和即時連結。第二次執行會儲存每個所選儲存庫的第一張 README 圖片。每個重點專案至少需要一張預覽圖片。好的來源依序為：README 橫幅、即時應用程式的截圖（使用 Playwright 以 1600x900 解析度擷取）、以 examples/assets/*.svg 風格產生的橫幅。檢查每張圖片：螢幕截圖中不得有機密資訊、不得模糊、寬高比為寬格式（16:9 或接近）。

4. 準備照片

python scripts/prepare_photos.py --portrait portfolio/photos/portrait.jpg \
  --about portfolio/photos/about.jpg --about-gray --out portfolio/photos/out

開啟結果並檢查。鏤空人像必須邊緣乾淨、沒有透明破洞，且頭部靠近上方。如果關於照片對人物臉部的裁切不佳，請使用 --about-focus x,y（圖片水平和垂直方向 0 到 1 的分數）重新執行。將設定檔中的 person.photos.portrait 和 .about 指向 out/ 中的檔案。

5. 撰寫設定檔並建置

撰寫 portfolio/portfolio.json（結構請參考 reference/config-schema.md；可用的範例請參考 examples/portfolio.example.json）。其中的路徑是相對於該設定檔檔案的路徑。接著執行：

node scripts/build.mjs --config portfolio/portfolio.json --out portfolio/site
node scripts/snapshot_github.mjs --user <github-user> --site portfolio/site   # 僅在啟用存檔時執行
python scripts/render_images.py --site portfolio/site

當缺少必要欄位時，建置過程會以清晰的訊息停止。關於未知圖示的警告意味著該球體會以文字形式顯示其名稱；請從 data/simple-icons.json 中選取一個 slug，或將它留空。

6. 預覽

在背景啟動網站伺服器，並將網址提供給使用者：

python scripts/serve.py --site portfolio/site --port 4321

請使用此伺服器，而非 python -m http.server：後者在頁面一次請求大量檔案時會中斷連線，導致隨機的品質驗證失敗。此伺服器也會傳送無快取標頭（重新建置後重新整理即可看到變更），並為未知路徑提供 404.html（如同 GitHub Pages 的行為）。

7. 品質檢查

python scripts/qa/run_all.py --url http://127.0.0.1:4321/ --out portfolio/qa

所有檢查都必須通過（reference/quality-gates.md 說明了每一項檢查以及如何修復常見的失敗）。然後親自檢視 portfolio/qa/shots/ 中的螢幕截圖，逐個區塊、桌面版和手機版。自動化檢查可以捕捉碰撞和溢出；你的眼睛則可以捕捉到尷尬的斷行、不佳的圖片以及語意不順的文案。修復、重新建置、重新執行。在部署前至少執行一次 --full。

8. 與使用者一起審查

帶領他們瀏覽預覽畫面：英雄區塊、關於我、項目列、專案、存檔、球池、流程、聯絡方式、吉祥物聊天。收集修改意見，將它們套用到設定檔中（而非已建置的檔案），重新建置並重新執行品質驗證。

9. 部署（僅在獲得明確同意後）

遵循 reference/deploy.md：GitHub Pages（使用者網站或專案網站）、自訂網域以及重要的 Cloudflare 設定。部署完成後，執行即時檢查：

python scripts/qa/run_all.py --url https://their-domain/ --only smoke,live --out portfolio/qa-live

如果「電子郵件未被改寫」檢查失敗，表示 Cloudflare 的電子郵件地址混淆功能已啟用，破壞了「讓我們談談」環節；修復方法請參考 reference/deploy.md。

後續修改

編輯 portfolio.json，重新建置，重新執行品質驗證，重新部署。每次建置都會為每個資產加上新的 ?v= 版本字串，因此瀏覽器和 CDN 會直接套用變更，無需手動清除快取。

個人作品集網站設計