Communitygithub.com

HybridAIOne/hybridclaw

运行生产级 Google Analytics 4 Data API 报表,支持网关注入的 Bearer 认证、安全请求审查、流量来源、着陆页、时间序列、收入、会话和关键事件报告。

hybridclaw 是什么?

该技能专为 Google Analytics 4 (GA4) 报告设计,通过 Google Analytics Data API 提供全面的数据访问能力。它能处理会话、关键事件、收入、流量来源细分、着陆页细分、时间序列查询、临时分析师读取、仪表板、定时报告、ETL 和监控等场景。支持委托用户 OAuth 和服务账户认证两种模式,所有凭证安全存储在 HybridClaw 运行时中,避免暴露给模型。核心工作流程包括:先用自然语言规划报告、审查生成的请求 JSON、再通过网关代理执行 live 调用,整个过程保持只读,不涉及 Admin API 变更。该技能内置了 25 个评估场景,覆盖常见分析请求,并强制要求默认行限制和维度选择最佳实践,确保生产环境的稳定性和安全性。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

GA4

使用此技能通过 Google Analytics Data API 进行 Google Analytics 4 报告:会话、关键事件、收入、流量来源细分、着陆页细分、时间序列查询、临时分析师读取、仪表板、定时报告、ETL 和监控。

范围

  • 为已配置的媒体资源运行 GA4 runReport 请求
  • 将常见的英文分析师请求转换为可审查的 Data API 负载
  • 在执行前审查 GA4 请求 JSON
  • 构建流量来源、渠道分组、着陆页、每日趋势、收入、会话、用户和关键事件报告
  • 通过相同的网关 Bearer 处理合约支持委托用户 OAuth 和服务账户认证
  • 将认证模式选择保留在租户/运行时配置中,而不是提示逻辑中
  • 通过正常的 HybridClaw UsageTotals 计量技能运行成本

默认工作流

  1. 从 report-plan 开始处理自然语言请求,除非用户已经提供了 GA4 Data API 请求 JSON。
  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. 浏览器管理界面:打开以 /admin/secrets 结尾的活跃 HybridClaw 管理地址。
  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 \
  "显示我上周的自然转化量与上周的比较"

为规划或手写的请求构建 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 \
  "最近30天的每日会话和收入"

运行捆绑的评估套件:

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 个具有代表性的分析师请求,涉及会话、关键事件、收入、流量来源、着陆页、时间序列、比较、电子商务、地理、设备以及安全/澄清案例。

相关技能