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 常常不一樣，要動手測才知道。
這個主題下的文章
5 篇 · 最新到最舊Meta Ads MCP 怎麼接 Claude Desktop？實際 URL 是 mcp.meta.com 不是 mcp.facebook.com
Meta Ads MCP 在 2026-04-29 開放 open beta，正確 connector URL 是 https://mcp.meta.com/ads（不是流傳的 mcp.facebook.com/ads）。透過 Meta Business OAuth 授權後系統會 provision 專屬 URL（mcp.meta.com/ads/<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、\\' 輸出成 \'）。