Communitygithub.com

HybridAIOne/hybridclaw

執行生產級 Google Analytics 4 Data API 報告,支援閘道注入的 Bearer 驗證、安全的請求審查、流量來源、到達頁面、時間序列、收入、工作階段和關鍵事件報告。

hybridclaw 是什麼?

此技能 (GA4) 專為在 HybridClaw 平台上執行生產級 Google Analytics 4 (GA4) 報告而設計。它透過一個統一的閘道合約,支援委派用戶 OAuth 和服務帳戶 JWT 兩種驗證模式,無需向 AI 模型暴露任何令牌或私鑰,從而確保安全性。技能的核心功能包括將自然語言分析請求翻譯成結構化的 GA4 Data API JSON 負載、在執行前審查請求、以及運行各種常見報告,如流量來源細分、到達頁面分析、每日趨勢、收入、工作階段和關鍵事件。它還內建了一個包含 25 個場景的評估套件,用於驗證提示詞的準確性與邊界情況。此技能嚴格唯讀,不會執行任何 Admin API 變更或屬性設定修改。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/HybridAIOne/hybridclaw/tree/HEAD/skills/ga4

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

GA4

使用此技能進行 Google Analytics 4 報告,透過 Google Analytics Data API:工作階段、關鍵事件、收入、流量來源細分、到達頁面細分、時間序列查詢、臨機分析讀取、儀表板、排程報告、ETL 和監控。

範圍

  • 為已設定的資源執行 GA4 runReport 請求
  • 將常見的英文分析師請求轉換為可審查的 Data API 負載
  • 在執行前審查 GA4 請求 JSON
  • 建立流量來源、管道群組、到達頁面、每日趨勢、收入、工作階段、使用者和關鍵事件報告
  • 透過相同的閘道 Bearer 代碼合約,支援委派用戶 OAuth 和服務帳戶驗證
  • 將驗證模式選擇保留在租戶/執行階段設定中,而非提示詞邏輯
  • 透過正常的 HybridClaw UsageTotals 測量技能執行成本

預設工作流程

  1. 除非使用者已提供 GA4 Data API 請求 JSON,否則先從 report-plan 開始處理自然語言請求。
  2. 在進行即時呼叫之前,使用 review-request 審查產生的或使用者提供的請求 JSON。
  3. 對於 HybridClaw 內部的即時 GA4 API 呼叫,在可用時直接使用 http_request。將輔助工具產生的 httpRequest 物件傳遞給該工具。
  4. 當 http_request 不可用時,使用輔助工具進行離線規劃/審查以及透過閘道代理的執行:
    python3 skills/ga4/scripts/ga4.py ...
    
  5. 將此技能中的所有 GA4 操作視為唯讀。請勿嘗試 Admin API 變更、資源存取權限變更、關鍵事件變更或標籤變更。

驗證合約

此技能支援兩種驗證模式,且不會向模型暴露令牌或私鑰:

  • 透過 Bearer 金鑰代碼的委派用戶 OAuth
  • 透過閘道的 Google 服務帳戶 JWT Bearer 交換

租戶設定決定使用哪種模式。

預設委派用戶 OAuth 代碼:

hybridclaw auth login google \
  --client-id "<google-oauth-client-id>" \
  --client-secret "<google-oauth-client-secret>" \
  --account [email protected] \
  --scopes "https://www.googleapis.com/auth/analytics.readonly"

hybridclaw auth status google

對於委派 OAuth,使用預設的 bearerSecretName: "GOOGLE_WORKSPACE_CLI_TOKEN" 或 google-oauth URL 驗證路由。

對於服務帳戶自動化,將服務帳戶的 client_email 和 PEM private_key 儲存為加密的執行階段密鑰。閘道會讀取這些命名密鑰,在伺服器端簽署 JWT 斷言,將其交換為短期的 Google 存取令牌,並將該令牌注入 GA4 請求。

按此順序設定或更新這些密鑰:

  1. 瀏覽器管理員:開啟作用中 HybridClaw 管理員 URL,網址結尾為 /admin/secrets。
  2. 瀏覽器 /chat 或 TUI 備用方案: /secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>" 和 /secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>"。
  3. 本地主控台備用方案:
hybridclaw secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"
hybridclaw secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY '<pem-private-key>'

請勿將 OAuth 存取令牌、重新整理令牌、服務帳戶私鑰或下載的 JSON 金鑰檔案貼到提示詞中。實際憑證保留在 HybridClaw 密鑰執行階段中,並由閘道在伺服器端使用。

可選的儲存預設值使用相同的設定順序:瀏覽器管理員位於 /admin/secrets,然後在瀏覽器 /chat 或 TUI 中使用 /secret set,最後是本地主控台備用方案。

hybridclaw secret set GA4_PROPERTY_ID "<numeric-property-id>"
hybridclaw secret set GA4_BEARER_SECRET_NAME "GOOGLE_WORKSPACE_CLI_TOKEN"

對於無人值守的服務帳戶作業,在租戶執行階段中設定環境預設值:

GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY

指令合約

從自然語言規劃報告:

python3 skills/ga4/scripts/ga4.py --format json report-plan \
  "Show me last week's organic conversions vs the prior week"

為已規劃或手寫的請求建立 http_request 負載:

python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"date"}],"metrics":[{"name":"sessions"}],"limit":25}'

透過閘道輔助路徑執行報告:

python3 skills/ga4/scripts/ga4.py --format json run-report 123456789 \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'

透過選擇儲存的服務帳戶密鑰名稱來使用服務帳戶驗證:

python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
  --google-service-account-email-secret GA4_SERVICE_ACCOUNT_EMAIL \
  --google-service-account-private-key-secret GA4_SERVICE_ACCOUNT_PRIVATE_KEY \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'

離線審查請求 JSON:

python3 skills/ga4/scripts/ga4.py --format json review-request \
  '{"dateRanges":[{"startDate":"30daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"landingPagePlusQueryString"}],"metrics":[{"name":"sessions"},{"name":"totalRevenue"}],"limit":25}'

產出分析師查詢提示詞範本負載:

python3 skills/ga4/scripts/ga4.py --format json prompt-template \
  "Daily sessions and revenue for the last 30 days"

執行內建評估套件:

python3 skills/ga4/scripts/ga4.py --format json eval-scenarios

運作規則

  • 使用數值型 GA4 資源 ID。接受 properties/<id> 輸入,但在 API 呼叫前將其標準化。
  • 除非使用者明確要求自訂事件指標,否則使用 keyEvents 進行轉換類型的報告。
  • 在引入自訂維度之前,優先使用 sessionDefaultChannelGroup、sessionSourceMedium、landingPagePlusQueryString 和 date 進行常見的生產細分。
  • 包含行數限制。臨機報告預設為 25,僅在使用者要求匯出或 ETL 大小的結果時才增加。
  • 當請求提到某個季度但未指定年份時,要求使用者澄清。
  • 請勿在此技能中新增 Admin API 寫入操作。單獨的管理技能需要明確的核准層級和邊界測試。

評估套件

內建情境涵蓋 25 個代表性的分析師請求,範圍包括工作階段、關鍵事件、收入、流量來源、到達頁面、時間序列、比較、電子商務、地理、裝置以及安全性/澄清案例。

相關技能