GA4
使用此技能通过 Google Analytics Data API 进行 Google Analytics 4 报告:会话、关键事件、收入、流量来源细分、着陆页细分、时间序列查询、临时分析师读取、仪表板、定时报告、ETL 和监控。
范围
- 为已配置的媒体资源运行 GA4
runReport请求 - 将常见的英文分析师请求转换为可审查的 Data API 负载
- 在执行前审查 GA4 请求 JSON
- 构建流量来源、渠道分组、着陆页、每日趋势、收入、会话、用户和关键事件报告
- 通过相同的网关 Bearer 处理合约支持委托用户 OAuth 和服务账户认证
- 将认证模式选择保留在租户/运行时配置中,而不是提示逻辑中
- 通过正常的 HybridClaw
UsageTotals计量技能运行成本
默认工作流
- 从
report-plan开始处理自然语言请求,除非用户已经提供了 GA4 Data API 请求 JSON。 - 在实时调用前,使用
review-request审查生成的或用户提供的请求 JSON。 - 对于 HybridClaw 内的实时 GA4 API 调用,当可用时直接使用
http_request。将辅助工具发出的httpRequest对象传递给该工具。 - 使用辅助工具进行离线规划/审查,以及当
http_request不可用时通过网关代理执行:python3 skills/ga4/scripts/ga4.py ... - 将此技能中的所有 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 请求。
按以下顺序设置或更新这些密钥:
- 浏览器管理界面:打开以
/admin/secrets结尾的活跃 HybridClaw 管理地址。 - 浏览器
/chat或 TUI 回退:/secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"和/secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>"。 - 本地控制台回退:
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 个具有代表性的分析师请求,涉及会话、关键事件、收入、流量来源、着陆页、时间序列、比较、电子商务、地理、设备以及安全/澄清案例。