add_prize
ChatGPTAdd one prize to an existing lottery quiz owned by the signed-in user. Supports scratch, gacha, spin-wheel and lucky-draw; does not draw winners, deliver prizes or publish. Inputs: quizId and prize.label required; prize.description optional. Read get_quiz first for module, lotteryMode and probability mode. Spin-wheel: omit probability or set 0. Manual probability-draw adds an inactive 0% prize; use rebalance_prizes with all prizes to activate it. Automatic mode (including automatic legacy-free) requires positive integer quantity; the prize is immediately active with quantity-computed odds. Manual legacy-free and guaranteed-win add inactive 0% prizes: activate via editorUrl; MCP cannot activate them. Mixed automatic/manual prizes are rejected; only probability-draw can first be normalized with rebalance_prizes, never until-depleted. Scratch/gacha/lucky-draw: omit probability and quantity; new prizes are inactive at 0% and cannot be drawn until activated via editorUrl. Returns prizeId, active, probability, probabilitySource, optional requiresEditorActivation/warning, editorUrl and previewUrl.
add_question
ChatGPT在最後加一題。classic:choice = { txt, label };multifactor:choice = { txt, type }。
add_result
ChatGPTclassic:result = { label, description };multifactor:result = { name, label(MBTI 碼), description }。抽獎請用 add_prize。
create_quiz
ChatGPT用 draft 建立一份新測驗。一律建立成「未發布草稿」並掛在你名下。建立前先用 list_quiz_templates 看範本中心有沒有現成可改的範本,把合適的 1~3 個連同版型一起給創作者挑;創作者明確說要從零開始才跳過這步。先呼叫 get_quiz_schema(帶對應 module)取得格式,再照格式填 draft。建立前先用文字總覽(主題/結果分類/題數/版型)向創作者確認,得到同意再建立。目前 MCP 建立流程可為 classic / multifactor / measure 產生結果頁視覺版型(classic / multifactor 必經「確認」步驟,不是必套):先跟創作者確認要不要套版型 → ① list_templates 取清單、render_template_previews 展示候選給創作者挑 → ② list_templates({ templateId }) 取該版型欄位規格(fields / charBudget / fit)→ ③ classic / multifactor 填每個 category.canvaFields、measure 填每個 results[].canvaFields,遵守字數 → ④ 帶 templateSettingId 建立。創作者明確不要套版型時,經他同意後改帶 skipTemplate: true。classic / multifactor 兩者都沒帶(無 templateSettingId 也無 skipTemplate:true)會被擋下、不會建立——這道閘門逼你「問過」,不是逼你「套上」。draft 或 canvaFields 不合法會回傳逐欄位 issues,照錯誤修正後重試。要先做安全黑箱驗證可帶 validateOnly:true:會跑完整驗證但不讀寫 Firestore、不建立測驗,並回 semanticAuditPreview 核對版型相容性、主要視覺與資料視覺化語意。warnings 是非阻斷提醒、不必重試:partial 版型有區塊需到編輯器補、字數超出建議範圍(過長會在版型上截斷)、或你用了已更名的舊欄位名(已自動套到新欄位,下次請用 list_templates 回的名稱)。回傳 quizId、編輯器連結(editorUrl,創作者自己改)與預覽連結(previewUrl,不需登入即可開啟,適合轉給主管 / 客戶審核未發布草稿)。
delete_quiz
ChatGPT永久刪除一份「未發布」的草稿測驗(典型場景:換版型重建後不要的舊草稿)。已發布的測驗一律擋下(避免誤刪上線中的測驗),請創作者到編輯器的測驗列表自行刪除。刪除不可復原——呼叫前必須先向創作者明確確認過要刪哪一份(用 get_quiz 核對名稱),確認後帶 confirm:true。
diagnose
ChatGPT回報這次連線到的 MCP server 版本、git commit 與能力清單。創作者懷疑功能異常、或工具行為像是舊版(例如某個能力清單裡列出的行為沒有發生)時,先呼叫此工具確認 server 版本,不需 quizId、不會讀寫任何測驗資料。
get_quiz
ChatGPT回傳你自己某個測驗的現況與各項目的穩定 id(編輯前先看)。classic / multifactor / measure 都回結果 + 題目、每個結果的 Canva 版型 / visual 狀態與版型圖片位 audit;抽獎回獎項(prizes);measure 額外回每個選項的 score(加的分數)與每個結果的 minScore/maxScore(分數區間),供核對計分邏輯。抽獎另回 lotteryMode、整體 probabilityMode、每個獎項的 manualProbability / unlimited / probabilitySource,以及獨立的 systemFallback;也回 intro、previewUrl(不需登入的預覽連結,適合轉給主管 / 客戶審核)與 reviewCandidate(含安全附註,若有)。classic 另回 classicDraft(可直接送 update_quiz 的純文字草稿)與 classicDraftRoundTrip;若既有資料有斷掉的選項結果關聯、缺必要欄位或混用多個 Canva 版型,classicDraft 會是 null,必須依 classicDraftRoundTrip.limitations 先用定向工具修正,不可拿 results 的 HTML 直接整份覆寫。每個結果的 moduleConfig(自身覆寫,null=沒有)/ effectiveModuleConfig(母片合併後的實際值)與頂層 sharedModuleConfig(母片顯隱設定)供 update_result_modules 呼叫前核對現況。每個結果的 cta 是「該結果玩家面實際會看到的 CTA 按鈕清單」陣列(一個結果可有多顆導購按鈕,null = 這筆結果沒有自己的、整批繼承母片 sharedCta;標 inheritedFromTemplate:true 的那幾顆是母片帶下來、這筆結果沒有覆寫的),供 update_result_cta 呼叫後核對顆數與連結。僅限你自己的測驗;不回傳登入密鑰等敏感設定。宣告完成前用此工具讀回 audit(題數 / 圖片 / 版型現況)逐條驗收。
get_quiz_schema
ChatGPT回傳指定模組「建立測驗」所需的 draft 結構、欄位規則與完整範例。呼叫 create_quiz 前先用此 tool 拿對應模組的格式。可文字生成:classic / multifactor / survey / measure / quadrant-quiz / branch-quiz、抽獎(scratch/gacha/spin-wheel/lucky-draw)。其他模組(街機 / canvas / 集點 / 占卜、以及圖卡型的 swiper)會回「交棒到編輯器」說明。
list_quiz_templates
ChatGPT建立新測驗的第一步:先查範本中心有沒有現成可改的範本,再考慮從空白用 create_quiz 建立(創作者明確說要從零開始才跳過這步)。列出「範本中心」的整份測驗範本,可依 module / language / keyword 過濾。未指定 module 時只查 classic;要查其他模組必須明確指定 module。【與 list_templates 不同】這裡的範本是完整測驗(題目、結果、封面都做好),創作者「複製」就能拿到一份可改的草稿;list_templates 只是套用在結果頁的視覺樣式,兩者不要混淆。模組中文對照:心理測驗=classic、多維度測驗=multifactor、計分測驗=measure、問卷調查=survey、得分挑戰=swiper、客製圖產生器=canvas、刮刮樂抽獎=scratch、扭蛋抽獎=gacha、抽卡占卜=cartomancy(其餘 spin-wheel/lucky-draw/quadrant-quiz/branch-quiz 等 create_quiz 可建立的模組,視範本庫實際上架情況而定,不保證都有範本)。本工具唯讀,無法直接從範本建立測驗——創作者想用某範本時,把該筆的 useTemplateUrl 給他(點開會自動彈出「套用範本」視窗;previewUrl 只是預覽頁、上面沒有套用按鈕),複製完成後回來對話,用 list_quizzes 找到新測驗接手編輯。每筆帶 advancedFeatures(此範本用到的付費進階功能)——推薦時要向創作者揭露:免費方案套用後這些設定會保留但不作用(名單類則是功能運作但取得名單需付費方案),要完整使用需對應方案。每筆也帶 classification:capabilities 是從實際啟用且配置完整的結果頁區塊推導的事實與 evidence path;purposes 是固定規則推導的用途。可帶 purpose 只找特定用途並依 recommendationScore 排序。推薦理由只能引用 recommendationReasons / evidence;這不是熱門度、成效排名或語意模型,不可宣稱「最熱門」「轉換最好」。抽獎能力硬需求放 requirements,內容語意或附件硬需求放 templateRequirements;空物件都等同省略。不相容候選保留逐範本 conflicts,rejectionSummary 另按 canonical requirement 聚合。
list_quizzes
ChatGPT列出你名下的測驗(quizId / 名稱 / 模組 / 是否發布中 / 最後更新 / 編輯器連結)。想修改某個既有測驗卻不知道 quizId 時先呼叫它,再把選定的 quizId 帶進 get_quiz / update_*。onlyPublished=true 只回發布中的;module 篩特定模組。僅回你自己的測驗。
list_templates
ChatGPT列出可套用到結果頁的視覺版型(版型 = Canva 結果卡樣式)。三種模式:① 不帶參數 / 帶 language → 版型清單(每筆帶 imageCapability / fillableImageSlots / fit / titleCharBudget / extraFields / previewUrl / thumbUrl)。選型硬條件:創作者有提供結果圖 → 只挑 fillableImageSlots >= 1;最長結果名字數 ≤ titleCharBudget(否則截斷)。⚠️ fillableImageSlots(創作者的圖真的填得進去的格數)才是硬條件;hasImageSlot 只代表畫布有圖片節點,可能全是背景 / 裝飾,拿它過濾會把有圖的創作者導到填不進去的版型。② 先從清單挑出 2~6 個候選後,呼叫 render_template_previews 展示互動卡片;本工具仍保留 previewTemplateIds 的文字 / 縮圖 fallback,供不支援 widget 的 client 使用。③ 帶 templateId → 該版型完整欄位規格(fields / charBudget / slots / fit / unfillableSlots / imageFields)+ 縮圖,選定後用來填 canvaFields;imageFields 列出的圖片位用 set_image(target="template_image") 放圖。建議流程:先清單挑候選 → render_template_previews 展示縮圖給創作者選 → 選定後 templateId 取規格 → create_quiz 帶 templateSettingId。目前 MCP 建立流程可為 classic / multifactor / measure 產生 generic Canva 結果卡;measure 的額外欄位填在 results[].canvaFields。language 帶「創作者溝通的語言」:中文→zh、其他→en(泰文無專屬版型,以英文為準),除非明確指定。版型只有 zh / en 兩套。【與 list_quiz_templates 不同】這裡是「結果頁視覺樣式」;要找「整份現成測驗範本」(題目/結果/封面都做好,可直接複製)請用 list_quiz_templates。回傳的縮圖在部分對話介面不會顯示給創作者,務必把預覽圖網址一併貼給創作者。
publish_quiz
ChatGPT把一份測驗發布上架,讓公開連結能被玩家打開。只有創作者明確說要發布時才可以呼叫(例如「幫我發布」「上架吧」「可以公開了」)——發布是創作者的決定,你不可以自行判斷「做好了就發布」,也不可以在建立 / 修改測驗後順手發布。呼叫前先用 get_quiz 看 audit,把還沒完成的項目(缺封面 / 缺結果圖 / 版型假字未填 / 獎項缺圖)逐條告訴創作者,讓他知道現在發布出去長什麼樣,他仍要發布再帶 confirm:true 呼叫。被擋下時(未完成創作者問卷、方案發布數已滿)會回 blockers,把原因原樣轉述給創作者,不要重試。
rebalance_prizes
ChatGPT只支援 spin-wheel。用 get_quiz 取得全部 prizes,再把每個 prizeId 各列一次送出。每個 probability 必須介於 0 到 100;custom prizes 加上 get_quiz.systemFallback.probability 的總和必須為 100(容差 0.01)。只接受 lotteryMode=probability-draw(可為全手動或混合 choices);until-depleted、guaranteed-win、legacy-free 都會拒絕且不會隱性切換模式。systemFallback 是保留項目,不可放入 distribution;成功時只修改 custom prizes 的 probability / manualProbability,不修改 quantity / unlimited,也不修改 lotteryMode。整份分佈在同一個 Firestore transaction 中驗證並寫入,不會留下半套機率。
remove_prize
ChatGPT用 prizeId 刪一個獎項(result + 對應 choice)。不能刪到剩 0 個。spin-wheel 手動機率模式只能刪除 0% 獎項;其他獎項請先用 rebalance_prizes 將機率調整為 0。自動機率(until-depleted)模式可直接刪除,剩餘機率仍依 quantity 計算。混合自動/手動模式不支援 remove_prize;只有 probability-draw 可先用 rebalance_prizes 正規化,until-depleted 不可 rebalance。
remove_question
ChatGPT用 question id 刪一題。不能刪到剩 0 題。
remove_result
ChatGPT用 result id 刪結果。classic:仍被選項指向會被擋下(先用 update_question 改);multifactor 不受此限。都不能刪到剩 0 個。
render_template_previews
ChatGPT先用 list_templates 挑出 2 到 6 個結果頁版型候選,再帶 templateIds 顯示可比較的預覽卡片。此工具唯讀、不會套用或修改版型;選定後仍須用 list_templates({ templateId }) 取完整欄位規格。
set_image
ChatGPT統一圖片設定。target 決定設哪個位置:cover(封面)/ result(結果圖,需 resultId)/ question(題目圖,需 questionId)/ choice(選項圖,需 questionId+choiceId)/ og(分享縮圖)/ template_image(把圖放進「版型畫布內」的圖片位,需 resultId + imageField)。各 id 用 get_quiz 取得。imageUrl(server 抓取)或 imageBase64(agent 自生圖的 data URL)擇一。png/jpeg/webp/gif、上限 8MB;gif 會正確存成動圖(og 例外,社群預覽為靜態)。⚠️ result 與 template_image 是相反的兩件事:result 的上傳圖會「整張取代」版型卡(互斥,會被守門擋下需 replaceTemplateVisual 確認);template_image 則保留版型視覺,只換畫布裡那一格的圖 —— 要「版型卡上放創作者的商品圖 / 形象照」一律用 template_image。template_image 支援 classic / multifactor / measure;measure 會用 stable-ID delta 只改指定圖片位,保留其他手動排版與內容(contain 圖位會依原始槽框恢復正確比例與底板)。可填的 imageField 用 list_templates 帶 templateId 看 imageFields(fillableImageSlots >= 1 的版型才有)。
set_review_candidate
ChatGPT創作者說「這版要給主管 / 客戶看」「就用這一版送審」時,用它標記該測驗為審核候選(candidate: true),方便他有多個草稿時分清楚哪個是正式候選、哪些是測試版本。candidate: false 取消標記。可選 note 附註(例如「給行銷部主管審」),截 100 字。標記後把 previewUrl 給創作者,方便他轉交給要審核的人。
unpublish_quiz
ChatGPT把一份已發布的測驗下架,公開連結不再顯示內容。只有創作者明確說要下架時才可以呼叫(例如「先下架」「活動結束了」「暫停對外」)。已收到的填答資料不會被刪除,重新發布後同一個連結照舊可用。典型場景:輕量方案發布數已滿,創作者要換上另一份測驗。下架沒有方案限制,任何方案都可以下架自己的測驗。用戶端會依 destructiveHint 顯示核准;只有創作者核准後才可帶 confirm:true 呼叫。
update_prize
ChatGPT呼叫形狀:{ quizId, prizeId, patch:{...要改的欄位} }(要改的欄位包在 patch 物件內,不是跟 quizId/prizeId 同層)。範例:{"quizId":"q1","prizeId":"p1","patch":{"label":"新獎項名"}}。用 get_quiz 取得的 prizeId 定位,更新 label / description;spin-wheel 另可更新 quantity。更新 quantity 前必須先看 get_quiz.lotteryMode:until-depleted / guaranteed-win 只接受大於 0 的正整數,並分別維持自動機率 / 手動機率;probability-draw / legacy-free 的手動機率獎項保留既有 quantity=0(不限量)語意;自動機率有限獎項不可設為 0,避免留下無效 stored probability,也不會切換 lotteryMode。probability 必須用 rebalance_prizes 一次送出所有獎項的完整分佈,不可用單獎 update_prize 修改。scratch / gacha / lucky-draw 不支援 probability 或 quantity,傳入時會明確拒絕。description 若是 get_quiz 回讀的 HTML,只有逐字不變回填時才可連同 descriptionFormat:"html" 送出;要修改內容時只傳純文字 description。
update_question
ChatGPT呼叫形狀:{ quizId, questionId, patch:{...要改的欄位} }(要改的欄位包在 patch 物件內,不是跟 quizId/questionId 同層)。範例:{"quizId":"q1","questionId":"ques1","patch":{"title":"新題幹","choices":[{"txt":"選項A","label":"某結果"}]}}。用 get_quiz 取得的題目 id 定位,只更新那一題的 title 或 choices(整組提供)。classic:choice = { id, txt, label }(id 是 get_quiz choices[].id;choiceId 是相容別名;label 對結果);multifactor:choice = { txt, type }(type 對維度);measure:只可改題幹,或帶既有 choice id 的完整 choices 清單 { id, txt, score }。measure 不可新增 / 刪除選項;score 改動會驗證所有題目可達總分與結果級距無缺口、無重疊。
update_quiz
ChatGPT用新的 draft 就地更新你既有的 classic 測驗:只覆寫有變動的文案 / 題目 / 結果,保留發布狀態、自訂網址、登入設定、封面與顏色等控制欄位。選用 templateSettingId:對「所有結果」重套結果頁版型(會覆寫既有結果卡 cover,包含編輯器手動改過的版面);不帶則維持既有 cover 不動。套版型時每個 category 可帶 canvaFields。先用 get_quiz 看目前內容、get_quiz_schema 取得格式。僅限你自己且為 classic 的測驗。手動編輯保護:帶 templateSettingId 重套版型時,若有任一結果的版型畫布在編輯器被手動編輯過(get_quiz 的 canvaManuallyEdited=true),會被擋下;先向創作者確認要覆蓋這些手動編輯,再帶 confirmOverwrite:true 重呼叫,不可未經確認自行帶 true。整份覆寫語意:draft 未列的題目/結果/選項會被刪除,銳減會被防呆擋下需 confirmRemoval。
update_quiz_meta
ChatGPT呼叫形狀:{ quizId, patch:{ quiz_name?, intro?, meta_description?, SEO_wordings?, hash_tags? } }(要改的欄位包在 patch 物件內,不是跟 quizId 同層)。範例:{"quizId":"q1","patch":{"quiz_name":"新標題"}}。只更新測驗層級文案(quiz_name / intro / meta_description / SEO_wordings / hash_tags),不動題目與結果 / 獎項。適用所有模組(抽獎會一併同步轉盤 / 刮刮樂的標題)。只帶要改的欄位。
update_quiz_theme
ChatGPT更新測驗整體配色與字體,套用到封面、題目頁與結果頁。呼叫形狀:{ quizId, patch:{ primaryColor?, buttonTextColor?, textColor?, backgroundColor?, fontFamily?, cloudFont? } },顏色值一律 hex 色碼(如 "#0EA5E9")。primaryColor = 按鈕底色 / 強調色;buttonTextColor = 按鈕文字色;textColor = 內文文字色;backgroundColor = 整體背景色。fontFamily 只能是編輯器選單裡的固定值之一:"sans"(黑體)、"serif"(宋體)、"round"(圓體)、"kai"(楷體)、"cloud"(Google Fonts)。選 "cloud" 才能用 Google Fonts 自訂字型,此時另帶 cloudFont(Google Fonts 的字型家族名,如 "Noto Sans TC");cloudFont 只在 fontFamily 為 "cloud" 時才會生效——只給 cloudFont 而沒有把 fontFamily 設成 "cloud"(本次帶或此測驗本來就是 cloud)會被擋下並要求補上 fontFamily:"cloud"。只帶要改的欄位,未帶的保留現值。canvas 模組另支援 choiceActiveColor / choiceBackgroundColor / optionBackgroundColor(選項配色)。結果卡(Canva 版型)的卡面顏色與字體不在此範圍——那由版型本身決定。
update_result
ChatGPT呼叫形狀:{ quizId, resultId, patch:{...要改的欄位} }(要改的欄位包在 patch 物件內,不是跟 quizId/resultId 同層)。範例:{"quizId":"q1","resultId":"r1","patch":{"label":"新名稱"}}。用 get_quiz 取得的結果 id 定位,只更新那個結果。classic:patch = { label?, description?, descriptionFormat?, canvaFields? };multifactor:patch = { name?, description?, descriptionFormat?, canvaFields? }(MBTI 碼是身分、不可改);measure:patch = { label?, description?, descriptionFormat?:"html", canvaFields? };多槽 canvaFields(list_templates 的 slots>1)傳等長字串陣列,單槽仍傳字串;不支援 minScore / maxScore。抽獎請用 update_prize。descriptionFormat:"html" 只供 get_quiz 的 description 逐字不變回填;要改說明內容時不可帶此旗標,請傳純文字 description。classic / multifactor 帶 canvaFields 會重新生成該結果的版型畫布(可能覆蓋手動版面);measure 則只寫入已驗證的 stable-ID 文字 delta,保留其他手動物件、圖片與版面。三者帶 canvaFields 都要求該結果已套版型(建立時帶過 templateSettingId),否則回錯誤。canvaFields 欄位規格用 list_templates 帶 templateId 取得。手動編輯保護:若該結果的版型畫布在編輯器被手動編輯過(get_quiz 的 canvaManuallyEdited=true),帶 canvaFields 的重生會被擋下;先向創作者確認要覆蓋掉手動編輯,再帶 confirmOverwrite:true 重呼叫,不可未經確認自行帶 true。
update_result_cta
ChatGPT設定結果頁 CTA 按鈕的外部連結、文字與顏色——導購 / 導流的關鍵設定。一個結果可以放多顆按鈕(最多 4 顆,例如一個結果推薦三樣商品各一顆按鈕)。兩種模式擇一,不能同時給:① 單顆:{ quizId, resultId?, patch:{ href?, text?, bg?, color?, show? } }——只帶要改的欄位。② 多顆:{ quizId, resultId, patch:{ buttons:[{ href, text, bg?, color? }, ...] } }——buttons 是「這個結果的完整按鈕清單」,每次呼叫整批取代(原本多出來的按鈕會被刪掉),要改就重送完整清單,不要用增量的方式一顆一顆加。多顆模式的 href / text 都必填。href = 按鈕點擊後前往的完整 http(s) 網址(例如商品頁);text = 按鈕文字;bg / color = 按鈕底色 / 文字色(hex,選填,通常交給主題色即可);show=false 可隱藏按鈕。resultId 省略時套用到「所有結果」(寫入母片,之後新增的結果也繼承)——多顆模式必須帶 resultId(多顆的用例是每個結果推薦不同商品,母片會讓每個結果長出同一批按鈕)。設定後用 get_quiz 讀回每個結果的 cta(陣列)核對顆數與連結。抽獎 / canvas 模組不支援。
update_result_modules
ChatGPT開關結果頁的某些區塊(例如雷達圖、雙人分析報告、聯絡表單按鈕)——只影響顯示與否,不會刪除任何資料,之後隨時可以再打開。呼叫形狀:{ quizId, resultId?, modules:{ 區塊名: true/false/null, ... } }。resultId 省略時套用到「母片」(等同套用到所有結果,之後新增的結果也繼承這個設定);帶了則只改那一筆結果,且會蓋過母片同名設定——個別結果可以跟母片不一樣。null 會移除該筆覆寫、回到母片繼承。合法的區塊名(白名單,其餘核心呈現 / 結構性必要 / 預設恆藏區塊不開放此工具調整):downloadButton、drawing、lot、video、subtitle、leaderboard、stats、details、same、spentTime、totalScore、record、content、radarChart、dualReport、coupon、missionReturn、donate、form、cta、share、replay、logo。目前每個結果的 ownModuleConfig / effectiveModuleConfig 用 get_quiz 讀(母片的在 sharedModuleConfig),呼叫前先看過現況,避免盲改。抽獎測驗不支援(獎項頁沒有這個概念)。