Quiz Site Builder — 可攜式 Agent 技能
與使用者共同創作測驗概念,然後將商定的設計轉變為經過打磨、測試、準備好部署到 Cloudflare Pages 的網站。此技能遵循供應商中立的 Agent Skills 資料夾格式;絕不要求任何特定的 Agent 產品或供應商專用工具。務必區分 GitHub 原始碼託管 與 Cloudflare 網站部署;此技能本身的儲存庫與每個產生的測驗網站的儲存庫是分開的。
請先閱讀此部分
- 在觸碰檔案之前,先檢查使用者的工作目錄。請勿覆寫現有的專案、檔案、設定或部署。
- 在共同創作期間,提出建議而非默默地修正機制;在完整實作之前,先取得確認或接受授權:
- 人格 / 角色配對:維度 → 確定性類型/角色配對;說明平手處理方式。
- 生存 / 互動故事:有序的決策 → 追蹤狀態變數與檢查點 → 可達成的結局。
- 診斷 / 優勢:自然舒適感 + 消耗 + 高峰經驗 → 可解讀的優勢與行動建議。
- 閱讀
references/quiz-design.md以了解題目、結果與分數平衡。閱讀references/visual-and-copy.md以了解主題撰寫與設計。閱讀references/mainland-readiness.md後再選擇字型、圖片或相依套件。閱讀references/qa.md後再宣告完成。當被要求部署時,閱讀references/publishing.md了解 透過 GitHub 的 Cloudflare Pages。 - 在獲得批准的開發階段,從頭開始:將完整的
assets/starter/複製到一個全新的網站目錄中;絕不直接修改可重複使用的起始模板。起始模板包含 3 個範例測驗、一個型別化計分引擎、響應式視圖與結果分享。在編輯元件之前,先自訂src/data/*.json。 - 預設不收費。除非使用者要求,否則絕不引入付款、卡密、Cloudflare Workers、身分驗證、D1 或 KV。如果要求存取碼,請閱讀
references/access-codes-optional.md並引導使用者採用安全的架構;請勿默默地實作它或部署需要付費的服務。
預設模式:使用者參與共創
預設採用共同創作模式,即使初始要求是「製作網站」或列出開發任務。首先,釐清創意方向;不要立即產生完整的題庫、複製起始模板或建置完整網站。重複使用使用者已提供的選擇,而不是再次詢問。允許檢查現有檔案並準備有範圍的提案。
依序經歷這三個階段,通常每個回覆一個階段。每個階段提供具體的建議,並且總共最多詢問 1-2 個關鍵問題;不要重複已經回答過的問題。在所有 Agent 上使用一般對話;絕不要求使用選擇表單。
- 探索創意 — 針對使用者主題提供 2-3 個有實質差異的角度,每個角度包含一個吸引點、目標受眾和獨特的體驗。偏好一個獨特的玩家張力以及一個令人難忘、可真誠分享的結果,而不是未經證實的病毒式傳播聲明。如果使用者明確要求不同數量(例如五個點子),請尊重該要求,而不是強迫給出 2-3 個。推薦其中一個並解釋原因。詢問要開發哪個角度,最多再提出一個能實質改變概念的問題。
- 設計機制 — 以白話文呈現提議的演算法(狀態/維度、選擇如何影響它們、檢查點/平手處理方式以及結局如何被選取)、結果類型與差異,以及 2-3 個完整的範例題目,包含選項與權衡說明。推薦一個符合已確認角度的機制;詢問是否採用它或改變關鍵權衡。樣本是提案,不是完整的題庫。
- 確定風格 — 提供 2-3 個具體的視覺方向,包含色板、字型、手機流程和 3:4 分享卡片處理方式;推薦其中一個。展示一個具代表性的結果報告草稿,包含標題、解讀、優勢、代價與建議。詢問視覺選擇以及最終核准整合後的設計,最多兩個問題。在使用者確認設計或明確授權其餘決定之前,不要開始完整開發。
在每個階段結束時,顯示一個簡潔的 決策記錄:已確認的選擇、仍待確認的 AI 建議,以及剩餘的決定。將已授權/跳過的選擇記錄為「AI決定」或「跳過,採用建議」,絕不記錄為使用者選擇的偏好。在對話中保留此記錄;在核准後,將其儲存到產生網站的 docs/DESIGN.md。當使用者修改某個決定時,更新記錄並僅重新審視受實質影響的提案,而非所有階段。
在每個階段,使用者可以修改、跳過它,或要求 AI 決定。「跳過這一步」僅授權該階段:記錄建議的預設值並繼續到下一個階段。「你決定剩下的」授權所有剩餘的選擇:簡短記錄所選的設計並繼續進行實作。沉默或時間流逝不代表核准。當需要輸入時,停留在相關階段;不要將未回應視為允許繼續建置。
一鍵生成模式 / 一鍵生成
當使用者說「直接做」、「一鍵生成」、「你來決定」,或明確要求跳過所有設計討論並立即建置時,切換到一鍵生成模式以處理當前請求。說明所選的預設值,並在沒有三個對話關卡的情況下自主進行內容、邏輯、UI、驗證和本地預覽。現有的使用者限制仍然適用。使用者可以隨時切換回共同創作模式。明確的先前設計核准也允許自主開發,無需重複這些階段。
設計核准或一鍵生成模式授權所要求的開發與除錯,但不包括不相關的外部操作。保持所要求的僅限本機的界限;GitHub 發布和 Cloudflare 部署仍然需要使用者的意圖和可用的授權。
端到端工作流程
1. 將使用者的想法轉換為可用的產品規格
在共同創作模式下,完成上述三個階段,並在實作前整合他們的決策記錄。在一鍵生成模式下,選擇並簡短說明這些預設值,無需等待。包含一句話吸引點、目標受眾、題目數量(預設約 10–16 題)、結果類別、機制、權衡、主題/顏色方向、手機流程和分享卡片構想。如果未指定,預設為免費、匿名、靜態網站,進度儲存在本地。不要再詢問已確認的選擇;在共同創作模式下,將提議的預設值標記為待接受或授權。切勿將娛樂性人格測試描述為科學診斷。
2. 在設計核准或授權後,先撰寫測驗內容與邏輯,再處理 UI
自主提供完整的題庫,而非佔位用的樣本,並實作/除錯已核准的網站,無需詢問例行性技術決策。使用敘事性問題,並提供看似合理但不顯而易見的選項。保持 src/data/*.json 為權威性的測驗資料。對於每個人格/診斷選項,僅引用已宣告的軸線。對於生存測驗,danger 和 influence 必須是有限的整數狀態效果,事件必須有序,並且多個結局必須可實際達成。測試通往失敗和成功的路徑;防止「總是選擇最安全答案」的漏洞。對於已授權的媒體/具名作品,將可驗證的情節事實與虛構情境分開。在聲稱真實時間線之前,諮詢可靠來源或使用者提供的參考資料;如果無法取得,說明差距並提出一個原創的替代方案供使用者選擇。不要將要求製作一個具名作品視為複製其圖片、對話或宣傳素材的許可。檢查使用權利,且不要捏造精確的情節時間線。
3. 建置美觀、且考量中國大陸環境的靜態 UI
從起始模板開始,預設使用 Vite + React + TypeScript,且 base: '/' 以相容於 Cloudflare Pages。保留以下功能:一次一題的檢視、進度條、返回、繼續、重新開始、鍵盤支援、320px 以上的手機尺寸、分享連結預覽以及 3:4 分享卡片匯出。避免在執行時期依賴 Google Fonts、遠端圖片 CDN、第三方腳本/SDK、海外 API 和客戶端分析。將靜態資產打包;使用安全的系統字型備援方案。永遠不要提交金鑰或將 API 秘密放在前端程式碼中。確保結果是確定性的。預設不加入付款或卡密。
4. 驗證功能與中國大陸環境的相容性
執行下列指令,並視需要調整路徑:
python3 <skill-root>/scripts/validate_quizzes.py <網站>/src/data
python3 <skill-root>/scripts/audit_mainland_assets.py <網站>
cd <網站>
npm install
npm test
npm run build
然後手動驗證:介紹畫面、前進與後退、重新整理/繼續、多個結果路徑、分享 PNG/URL、手機版面配置和對比度。參閱 references/qa.md。不要聲稱您沒有實際執行過的檢查項目。未在實際的中國大陸網路上測試過,不要聲稱中國大陸可存取性。
5. 引導上線 — 將程式碼發布到 GitHub,並用 Cloudflare Pages 部署網站
在本地預覽之後,以白話文說明 GitHub 儲存程式碼,而 Cloudflare Pages 讓網站可線上存取;當工具無法執行這些操作時,引導使用者操作帳號或儀表板步驟。尊重僅限本機的要求,並且在已獲得授權的地方不要重複要求授權。遵循 references/publishing.md。預設路由:為產生的網站建立一個獨立的 GitHub 儲存庫 → Cloudflare Pages 的 Connect to Git → Vite/React npm run build / dist / production main → 部署 → 設定自訂網域以利推廣 → 在聲明就緒前,先從中國大陸網路測試 HTTPS / 載入。起始模板中的 GitHub Action 僅用於檢查;Cloudflare 的 Git 整合負責處理部署。
如果使用者想要將此技能本身發布到 GitHub,請分開發布這個跨 Agent 技能儲存庫。未經使用者意圖和可用授權,切勿建立帳號、購買網域、連接儲存庫、推送或部署。如果無法取得授權,請提供可操作的指令和儀表板步驟,而不是虛假的「已發布」聲明。Cloudflare Pages 標準全球方案無法保證中國大陸連線能力;如果硬性要求未通過測試,請建議合規的中國大陸託管選項 / ICP 備案(視情況而定)。不要將 Cloudflare 的 Enterprise China Network 與免費的 Pages 混淆。
產品原則
AI 負責拓展創意的可能性,使用者負責決定作品的獨特性,AI 負責把決定變成現實。除非經授權,否則創意選擇屬於使用者;例行性技術執行屬於 Agent。狹義的授權,例如「配色你來決定」,僅適用於該項決定,不適用於所有剩餘階段。
核心不變量
- 準確的演算法,具有可達成且可區分的結果;除非要求,否則沒有隨機結果。
- 不虛假宣稱臨床有效性;不做出籠統的「中國可存取」承諾。
- 未經要求,不加入後端、登入、追蹤、付款、卡密或敏感資料收集。
- 分享程式碼不等於部署。新的測驗網站應有自己的儲存庫和網域。
- 僅限前端程式碼的鎖定並不安全。如果要求存取碼閘門,建議使用伺服器端驗證並處理機密結果;保持其選擇性。
- 遵循使用者現有的品牌、視覺、事實和選擇。
呼叫範例
- 「用 quiz-site-builder 和我共創一個宮廷生存測試,先給我幾個創意切口。」
- 「直接做一個 10 題原創宮廷生存測試,本地預覽,不部署。」(一鍵生成)
- 「用 $quiz-site-builder 幫我做國風人格測試,六衡分析、器物人格、手機端,並部署到 Cloudflare Pages。」
- 「做 10 題原創宮廷生存測試,分支結局、3:4 結果卡,發布到 GitHub 後由 Cloudflare 自動上線。」
- 「幫我把測試網站準備給國內用戶用,不依賴國外字型或 CDN,教我綁定自訂網域並檢查存取。」
- 「我暫時不需要收費或卡密,只告訴我之後怎麼擴展卡密。」
跨 Agent 執行規則
- 所有指令路徑,例如
references/quiz-design.md和assets/starter/,都是相對於包含此SKILL.md的資料夾(<skill-root>),絕不指向寫死的 Codex 目錄。 - 使用目前主機 Agent 實際提供的檔案操作、shell 和瀏覽器功能;不要假設存在
apply_patch、Codex 工具或特定的 MCP 伺服器。當某個工具不存在時,提供可攜帶的指令或手動步驟,並清楚標記未完成的步驟。 - 專案的原始碼真相是
skills/quiz-site-builder/。切勿將技能邏輯重複製作或分支到特定於供應商的副本中。適配器安裝僅複製同一個資料夾。 - Codex 調用可能使用
$quiz-site-builder;WorkBuddy、Claude Code、CodeBuddy Code 和其他 Agent 可能使用技能選擇器或一般語言。在 Codex 之外,不要要求使用$語法。 - 不要僅僅因為 Agent 匯入了此技能,就聲稱它支援某個功能。在執行部署步驟之前,請確認本機檔案存取、Python、Node/npm、Git 以及驗證能力。
- WorkBuddy 匯入使用一個 zip 壓縮檔,其資料夾根目錄為
quiz-site-builder/SKILL.md。WorkBuddy 應從該資料夾載入references/、scripts/和assets/。如果主機沙箱阻止執行腳本,請說明限制並仍然產生靜態網站程式碼。
主機相關的部署限制
無論 Agent 為何:GitHub 儲存原始碼,Cloudflare Pages 是預設的部署目標;在使用者可以授權的地方使用 Cloudflare Git 整合。選擇性的卡密架構僅為指導原則;切勿默默加入付費牆、付款或包含秘密的前端檢查。中國大陸的存取需要實際的網路測試,且無法由標準的 Cloudflare Pages 或自訂網域保證。