API / 工具整合 Debug
所有實際整合都會踩坑。這個 pillar 收錄 Gemini schema 收緊後 thinkingConfig 必須嵌進 generationConfig 內、Meta Ads MCP 真實 URL 是 mcp.meta.com、Vercel Labs skills 一行裝 36 個觸發詞衝突處理、Node.js template literal 嵌 JS 的 \n 靜默崩潰等真實坑紀錄。每篇都附完整 root cause + 修法。
這個主題的核心觀點
- #1
AI 工具 API 文件常落後，實際 schema 變更要靠錯誤訊息回推。
- #2
Silent failure 是最可怕的，必須中央化 logger 加 errStack。
- #3
官方推薦 URL 跟實際 URL 常常不一樣，要動手測才知道。
這個主題下的文章
8 篇 · 最新到最舊Meta官方Ads MCP實測9天踩的20個坑：從45萬預算事故到台灣法規牆
Meta官方Ads MCP（mcp.facebook.com/ads）能讀數據也能投放，但有兩個最貴的坑：台幣預算沒有小數單位，傳450000會把日預算變成NT$450,000；投台灣的廣告組合需要「已驗證刊登者身分」，MCP填不了這個欄位，只能在廣告管理員用複製繞過。
Meta Ads MCP 的 29 個工具是哪些？五大類拆解，電商廣告哪些真的用得到
Meta 官方 Meta Ads MCP 在 open beta 開了 29 個工具，分五大類：開／改活動 5 個、商品目錄 10 個、帳號與資產 3 個、追蹤品質診斷 4 個、成效洞察 7 個。對電商廣告主最先該用的是成效洞察跟像素／轉換 API 診斷這兩類唯讀工具，能把拉報表從 20 分鐘壓到 90 秒；寫入型（開活動、改預算）因為沒有原生人工批准機制，beta 階段不建議讓 AI 自動跑。
Meta Ads MCP 正確網址是哪個？mcp.facebook.com 和 mcp.meta.com 兩個版本都在傳
Meta Ads MCP 的接入 endpoint 目前有兩個版本在流傳：mcp.facebook.com/ads 跟 mcp.meta.com/ads。我 2026-07 重查一輪無法一槌定音，多數第三方設定教學寫 mcp.facebook.com/ads，也有資料校正成 mcp.meta.com/ads，Meta 官方公告頁沒直接列出完整字串。唯一能確定哪個對的方法，是實際在 Claude Desktop 貼上去，看哪個跳出 Meta Business OAuth 授權畫面，填錯會直接連線失敗、沒有有用的錯誤訊息。
Meta Ads MCP 怎麼接 Claude Desktop？授權範圍、29 工具、URL 兩個版本的坑
Meta Ads MCP 在 2026-04-29 開放 open beta，接入 connector URL 有兩個版本在流傳（mcp.facebook.com/ads 跟 mcp.meta.com/ads），2026-07 重查仍無法一槌定音，唯一確認法是實際貼進 Claude Desktop 看哪個跳出 OAuth 授權畫面。透過 Meta Business OAuth 授權後系統會 provision 專屬 URL（含 your-business-id），免 Meta Developer App、免 marketing API approval。但 per ad account 逐步開通、寫操作沒原生 guardrails，建議先用讀模式跑分析，寫操作走人工 Ads Manager。
Gemini 不出透明 PNG 怎麼辦？實測 N 次才搞懂的 AI 輸出三類分類法
Gemini 任何 model（含 Nano Banana / Gemini 2.5 flash image）都不會輸出 RGBA 真透明 PNG，輸出檔案是 PNG 容器但 alpha channel 永遠是 255（不透明）。我實測幾十次 prompt 變體全部失敗，最後改用 chroma key pipeline 解決：讓 Gemini 輸出純綠色背景的圖（這它能做），後製用 HSV + Floodfill 演算法把綠色去掉換成透明。
Gemini 2.5 API 突然壞掉：thinkingConfig 必須嵌在 generationConfig 內，Google 收緊 schema 後頂層被拒
Gemini 2.5 系列 REST API 的 thinkingConfig 必須嵌在 generationConfig 內，不能放在 request body 頂層。錯誤訊息「Invalid JSON payload received. Unknown name thinkingConfig: Cannot find field」就是 Google API 在 body 頂層找不到這個欄位。Google 之前寬鬆接受頂層寫法、最近收緊 schema 後一律拒絕。修法是把 thinkingConfig 移進 generationConfig 同層的物件，5 分鐘可改完。
Vercel Labs skills 實測：npx skills add 一行指令裝 36 個 agent skill，怎麼處理觸發詞衝突
Vercel Labs 的 skills 是 agent skill 的 npm 套件管理器，支援 Claude Code / Cursor / GitHub Copilot / Cline 等 18+ agent。一行指令 npx skills add <owner/repo> 就能從 GitHub 裝 skill 到本機。實測裝入 36 個外部 skill 後可直接觸發。最大風險是外部 skill description 跟本地 skill 重疊導致 Claude 選錯，要跑『觸發詞重疊地圖』比對再微調 description 畫清邊界。
Node.js template literal 嵌入 JavaScript 的地雷：\n 和 \' 會讓整個 script 靜默崩潰
Node.js template literal 裡的 \n 和 \' 等 escape 序列會被 Node.js 處理成真實字元，輸出到瀏覽器的 JavaScript 因此語法錯誤，整個 script block 靜默崩潰。症狀是 HTML 顯示正常但頁面功能完全失效，console 沒有報錯。解法是把 template literal 裡的 \ 全部雙寫（\\n 輸出成 \n、\\' 輸出成 \'）。