Portfolio One Shot
目的
將真實作品的目錄轉換為可開啟、可被機器讀取且可獨立驗證的作品集，而不讓模型撰寫任何虛構的專案文案。
三個不變原則，依優先順序排列：
- 零虛構。每個顯示的事實都必須追溯到某個檔案、README 摘錄或使用者提供的值。遺漏的欄位將呈現為可見的缺口。絕不虛構專案名稱、角色、指標、客戶、引述、結果或圖片。
- 獨立驗證。在回報成功之前，先對輸出執行驗證器。先列出失敗項目，再列出通過項目。絕不將綠色清單標準作為作品集看起來很棒的證據——視覺判斷需由使用者親眼所見。
- 一條命令。
all執行掃描 → 設定 → 建置 → 驗證。出現第二條命令是缺陷，而非工作流程。
何時使用
- 使用者說「一鍵生成作品集 / 做個作品集 / 把我的項目做成作品集 / build a portfolio from this folder」。
- 使用者交給你一個包含圖片、影片或專案資料夾的目錄，並希望將它們展示出來。
- 使用者在新增或刪除作品後希望重新生成作品集。
- 使用者希望檢查現有作品集是否有遺漏的證據。
請勿在使用者想要一個含有虛構內容的裝飾性示範網站、特定藝術指導視覺風格或託管平台整合時使用。這些是不同類型的工作。在此情況下，不要默默切換到此技能的零虛構規則——請明確說出差異。
唯一命令
python scripts/portfolio.py all <SOURCE_DIR> --out <OUTPUT_DIR> --mode <case_study|gallery>
範例：
python scripts/portfolio.py all "C:/work/my-projects" --out "C:/work/portfolio-dist" --mode gallery
該命令會將 index.html、portfolio.txt、portfolio.md、projects.json、assets/、build-report.json 和 verify-report.md 寫入輸出目錄，然後列印驗證器判定結果。使用檔案呈現工具為使用者開啟 index.html。將視覺交付物放在清單首位。
在使用者編輯 projects.json 後重新建置，僅執行 build 和 verify：
python scripts/portfolio.py build <OUTPUT_DIR>/projects.json --out <OUTPUT_DIR> --mode gallery
python scripts/portfolio.py verify <OUTPUT_DIR>
工作流程
階段 0 · 決定模式，不要默默猜測
存在兩種模式是因為來源研究發現這兩個領域要求相反的東西（參見 references/content-spec.md §領域區分）。
| 模式 | 適用對象 | 文字密度 | 佈局 |
|---|---|---|---|
case_study | UX、產品、設計、工程、研究 | 長篇敘事；七個必填欄位群組 | 每個專案一個區段，圖片交錯排列 |
gallery | 遊戲美術、插畫、概念藝術、攝影、動畫 | 極少量文字；讓作品說話 | 圖片優先的網格，點擊後開啟燈箱 |
如果使用者尚未選擇，請從素材推斷，並在執行前用一句話說明推斷結果——然後讓使用者用一個詞覆寫。絕不將某個預設值硬編碼到別人的作品集中。
階段 1 · 掃描真實素材
scan 將子目錄列舉為專案。對於每個專案，它會記錄：
- 目錄名稱作為專案標題候選項（事實，而非虛構）。
- 每個圖片和影片檔案的大小、SHA-256 前綴以及像素尺寸。
README.md/project.md/about.md的第一段作為逐字summary候選項，並附帶一個_sources條目，標明檔案名稱和行號範圍。- 一個
missing清單，列出沒有檔案能提供的欄位。
副檔名未知的檔案會保留在 manifest.json 中作為 unclassified，而不是被丟棄。絕不刪除、重新命名、移動或調整原始檔案大小。僅寫入輸出目錄。
階段 2 · 建置
build 讀取 projects.json（結構定義在 references/config-schema.md 中）並呈現：
index.html— 淺色主題、響應式、系統字型堆疊、無 CDN 依賴、無花俏模板。每個<img>都帶有alt、width、height、loading="lazy"。圖片使用assets/下的相對路徑。portfolio.txt— 純文字專案摘要，適用於 ATS 解析和複製貼上到履歷中。portfolio.md— 與上述相同的資訊，以 Markdown 格式呈現，可用於 README 或電子郵件。- 一個可見的警告橫幅，明確指出有多少欄位遺漏，以便骨架絕不會被誤認為是完成的作品集。
當設定了 --embed 時，僅將小於 10 KB 的圖片內嵌為 base64，較大的圖片保持外部引用；對每個超過閾值的檔案印出警告。Base64 會使負載增加約 33%，且無法實現延遲載入——參見 references/content-spec.md §圖片政策。
階段 3 · 在回報前驗證
verify 檢查欄位完整性、圖片是否存在且可解碼、替代文字是否有意義、是否使用佔位圖主機、連結格式、HTML 結構以及純文字版本的一致性。它會寫入 verify-report.md，失敗項目在前，通過項目在後，最後是 限制 / 未驗證項目。
退出碼為 1 表示存在紅色項目。請如實回報。不要為了讓標準通過而編輯它們，不要重試失敗的生成通道，也不要隱藏限制。
如需正/負面對照測試，請執行 python scripts/portfolio.py verify <dir> --self-test——它會在記憶體中建構一個故意有問題的專案和一個完整的專案，並確認驗證器會標記前者而放行後者。如果負面對照通過了綠色，則表示驗證器有問題；請修復驗證器，而非修復測試案例。
階段 4 · 交接
首先呈現 index.html，以便使用者可以開啟它，然後是 verify-report.md，最後是 projects.json。在文字回覆中：給出判定結果、遺漏欄位的確切數量，以及下一步的唯一動作（填寫 projects.json）。不要聲稱作品集看起來不錯。當警告橫幅存在時，不要聲稱它已準備好寄出。
零虛構合約
硬性規則，全部源自 references/content-spec.md 中記錄的失敗模式：
- 絕不撰寫輸入中不存在的專案敘述、說明文字、角色、指標、成果、貢獻者姓名或客戶名稱。遺漏的欄位呈現為
[MISSING: field]——醒目可見，絕不無聲地留空，也絕不將其改寫成看似合理的句子。 - 絕不使用佔位圖主機（
picsum.photos、placehold.co、lorem、素材網址）來代替真實作品。沒有圖片的專案則呈現一個明確的空媒體區塊。 - 絕不引用沒有
_sources條目的指標。如果使用者提供了某個指標，記錄source: "user-supplied"；不要將其升級為「已驗證」。 - 絕不虛構工作室名稱、個人簡介或聯絡方式。將它們留空並列為失敗項目。
- 使用 README 時，逐字複製段落，並記錄其檔案名稱和行號範圍。不要潤飾、縮短或改寫它。
- 不要將 AI 輔助的措辭呈現為使用者自己的決策。流程和反思欄位保持空白，直到使用者提供它們。
多版本輸出
同一個 projects.json 支援針對特定目標的版本。在 build 中加入 select 的專案 ID 清單，或傳遞 --only id1,id2，以產生針對特定觀眾的版本。重新排序是設定變更，絕非自動改寫。這遵循了文件中所記錄的區分：網站用於探索，而 PDF 或簡報用於申請。
常見陷阱
- 不要從片段下判斷。在得出任何內容是完整或有問題的結論之前，請閱讀完整的 README、完整的
projects.json以及完整的驗證器報告。 - 標準通過不等於品質。綠色驗證器僅表示檔案結構健全。美學需要使用者親眼判斷。
- 不要為了讓頁面看起來完整而填補空缺。當使用者尚未提供事實時，一個明顯不完整的頁面才是正確的輸出。
- 不要碰觸個人目錄。掃描對來源目錄是唯讀操作。所有寫入動作都發生在輸出目錄中。
- 不要擴大範圍到 PDF 生成、託管或 GitHub API 存取。這些需要使用者明確決定。
- 圖片尺寸很重要。提供
width和height可以防止佈局位移。如果 Pillow 不可用，請回退到標頭解析並印出可見警告；絕不無聲降級。 - 一個資料夾就是一個專案。如果使用者的素材是扁平結構，請要求分組或使用
--flat來建立一個包含所有媒體的專案。不要虛構分組。
資源
| 路徑 | 角色 |
|---|---|
scripts/portfolio.py | 單一 CLI：scan、build、verify、all、--self-test。使用標準函式庫及可選的 Pillow。 |
references/content-spec.md | 基於研究的內容規則、領域區分、圖片政策及來源網址。在變更欄位定義或模板之前，請先載入。 |
references/config-schema.md | 完整的 projects.json 結構定義、欄位含義以及何謂來源。 |
assets/template.html | 淺色主題響應式模板，包含兩種模式。僅替換 {{TOKEN}} 佔位符；不要為了追求某種外觀而改寫 CSS。 |
assets/projects.sample.json | 一個明確標示為 DEMO 的設定檔。切勿將其作為使用者的真實作品集送出。 |