mapa-calor 是做什麼的？

兩個互補的診斷工具：

部分	解答的問題	資料來源	腳本
影片	觀眾在我的廣告第幾秒離開？	Meta Graph API（僅 GET）	`scripts/retencion_videos.py`
登陸頁	訪客是否往下滑、閱讀、點擊，還是直接離開？	Microsoft Clarity Data Export API	`scripts/landing_clarity.py`
連線	所有服務是否都已連接？	兩者	`scripts/conexion.py`

腳本位於此技能的 scripts/ 資料夾中（Claude Code 會顯示為「此技能的基礎目錄」；通常是 ~/.claude/skills/mapa-calor）。在下面的指令中，$SK 代表該資料夾。請使用 python3（Windows 上使用 python）。

根據需求執行的動作

/mapa-calor 不帶參數，或是第一次執行 → 先執行 conexion，然後詢問使用者是否要執行 videos、landing 或全部。
/mapa-calor conexion → 執行 python3 "$SK/scripts/conexion.py"。如果缺少設定，請依照 README（「連接 Meta」/「連接 Clarity」章節）逐步引導。若不知道使用者的 act_：python3 "$SK/scripts/conexion.py" --cuentas。
/mapa-calor videos → 執行 python3 "$SK/scripts/retencion_videos.py"（最近 7 天，僅活躍廣告）。選項：--periodo last_14d、--desde AAAA-MM-DD --hasta AAAA-MM-DD、--todos（包含已關閉廣告）、--png mapa.png、--video archivo.mp4（顯示前 4 秒的畫面，每 0.5 秒一格）。
/mapa-calor landing → 執行 python3 "$SK/scripts/landing_clarity.py"。選項：--url /products/x、--meta（與 Meta 的連結點擊率和購物車數據交叉比對）、--solo-cache、--cuota。
/mapa-calor todo → 先執行 videos，再執行 landing 並加上 --meta，最後提供聯合診斷。
無需連線或練習用 → 任一腳本皆可加上 --entrada <檔案.json>（儲存庫的 ejemplos/ 中有範例檔案）。

查看地圖中的 3 秒 欄位：這是第 3 秒仍繼續觀看的比例。
- < 25% → 鉤子失敗。具體建議：重做前 2.5 秒。
- 25–39% → 普通。嘗試讓產品在第一幀出現的版本。
- ≥ 40% → 鉤子有效；尋找下一個流失點（腳本會標記：「鉤子之後……」）。
產品（或它解決的問題）應在第 2.5 秒之前出現。 在 0 秒就展示產品的影片留存率更高。如果使用者有影片檔案，建議使用 --video 並 查看畫面格（用圖片工具讀取），指出觀眾流失的位置畫面。
從第 0 秒到第 1 秒大幅下降在動態消息中屬於正常現象：請比較不同影片之間的數據，不要與 100% 比較。
曝光次數低於 100 次 → 不下結論。 清楚說明，且不建議暫停或優化該影片。
將留存率與銷售數據結合：好的鉤子 + 0 筆購買 → 問題可能出在登陸頁（建議執行 /mapa-calor landing）。

遺失在上方（平均滾動深度 < 21%）→ 修正第一屏：清晰的標題、產品使用照片、可見的好處與價格，無需向下滾動。如果連結點擊率 ≥ 1.5%，則代表廣告確實帶來了流量：問題在頁面本身。
摩擦（憤怒點擊 > 5%、死點擊 > 20% 或快速返回 > 25%）→ 在 Clarity 中開啟視覺化熱圖（報告中會提供連結），尋找使用者點擊但無回應的區域。
留存/價格問題（滾動深度 ≥ 30%，但每 100 次瀏覽少於 4 個購物車事件）→ 問題在於優惠或價格。
創意問題（頁面表現正常，但連結點擊率 < 1.5%）→ 更改廣告鉤子，而非頁面。
樣本過小（少於 30 次造訪）→ 不下結論。
熱圖影像（點擊位置、滾動深度）只能在 Clarity 的 Heatmaps 面板中查看。此技能僅提供數字與連結，請勿憑空編造圖片內容。

最後務必給出最多 3 個具體行動建議，按影響力排序，並說明之後要測量什麼（「3 天後再次執行 /mapa-calor videos，查看 3 秒欄位是否上升」）。

絕對不要列印、複製或儲存 token。 不要執行 echo $META_TOKEN，不要讀取 .env 檔內容，不要將 token 貼到儲存庫的檔案中。如果使用者在對話中貼上 token，請告訴他將 token 存入鑰匙圈或 ~/.mapa-calor/.env，並基於安全理由建議之後重新產生。
僅限唯讀。 此技能絕不會建立、暫停或編輯廣告。如果有人要求在 Meta 中進行更改，請說明如何在廣告管理員中操作；不要自行執行。
注意 Clarity 的配額限制（每個專案每天 10 次 API 呼叫）。 腳本已內建快取（3 小時）並限制在 8 次以內。除非使用者主動要求且了解會消耗 1 次配額，否則請勿使用 --forzar。如需重新查看相同資料，請使用 --solo-cache。若要查看已使用的次數：--cuota。
樣本過小時不下結論（影片曝光 < 100 次，登陸頁造訪 < 30 次）。
如果腳本執行失敗，請閱讀錯誤訊息（已附帶中文解決方案）並引導使用者；常見錯誤可參考 README（「常見錯誤」章節）。