add-google-analytics

添加 Google Analytics

为每个项目配置一个生产环境 GA4 媒体资源和 Web 数据流，然后添加标准网页浏览量和增强型衡量功能。使用共享的无密钥服务账号；绝不创建或下载服务账号密钥。

不可妥协的安全规则

• 从试运行计划开始。执行任何变更前，先请求一次明确确认。
• 即使工作树有未提交的更改，也可以执行计划和验证。应用变更要求 Git 工作树干净。
• 不要暂存、丢弃、提交、推送或部署应用代码。
• 不要删除 Analytics 资源或已收集的数据。
• 不要与现有 Analytics 并行安装。停止操作并说明发现的问题。
• 如果 Next.js 两种路由器、多个包管理器、多个 GA 资源或多个生产环境 URL 都有可能适用，不要猜测。
• 如果严格的内容安全策略（CSP）影响集成目标或全局响应，停止操作，并提出针对项目且能处理 nonce/hash 的更改方案。如果 CSP 仅作用于集成目标之外的文档，则需要明确审查边界，而非停止整个项目。绝不要添加 unsafe-inline 或宽泛的来源。
• 绝不要声称项目规模可免除隐私法律要求。此工作流会在没有同意门槛的情况下加载 Analytics；请在计划中说明这一点。
• 不要将凭据和令牌放入代码仓库、输出、Shell 参数或日志。衡量 ID 和 GA 资源 ID 是公开元数据，不是机密。

支持的目标

• Next.js App Router 和 Pages Router
• 纯静态 HTML 和基于 Vite 的原生 JavaScript
• 使用 Jinja 模板的 Flask 应用

对于不支持的框架，拒绝操作，不要自行变通。不要升级 Next.js 或更改路由架构。

1. 检查

先阅读仓库指南。从项目根目录运行：

node <skill-dir>/scripts/inspect-project.mjs .

检查器发现阻碍项时会以 2 退出；其 JSON 仍是计划的输入。另请检查部署配置以及所有需要修改的文件。

确认：

• 只有一个受支持的目标（或明确指定的 Next.js 路由器），
• 只有一个锁文件/包管理器，
• 不存在现有 GA 标签、衡量 ID 或 @next/third-parties/google，
• 没有影响集成目标或全局响应的 CSP，
• 对目标之外任何路由范围 CSP 的排除项都经过明确审查，
• 有便于阅读的资源名称，
• 已明确确认规范生产环境 URL，
• 完整列出源文件目标，
• 是否已关联 Vercel。

对于 Flask/Jinja，请遵循 {% extends %} 关系，优先选择层级最高的共享基础模板。列出未被其覆盖的独立模板。对于静态多页面网站，列出每个已部署的第一方 HTML 入口，并排除生成内容/供应商输出。

2. 准备完整的试运行计划

个人默认值应放在 ~/.config/add-google-analytics/config.json；项目状态应放在受版本控制的 .ga4.json 文件中。绝不要将个人默认值放入技能仓库。

计划必须展示：

• GCP 配额项目以及所需的无密钥服务账号设置，
• 所选 Analytics 账号，
• 资源名称、规范 URL、America/Toronto/CAD 默认值或覆盖值，
• 一个生产环境 Web 数据流，
• 14 个月的事件和用户数据保留期，并在活动时重置，
• 已启用增强型衡量功能，包括基于历史记录的页面变化跟踪，
• 已停用 Google Signals，并确认不存在广告产品关联，
• 精确的源文件/依赖项更改，
• 仅限生产环境的部署配置，
• 验证和浏览器检查命令，
• 按字段列出的 .ga4.json 内容（创建前 ID 未知），包括适配器、目标以及任何经过审查的 CSP 路径排除项，
• 无需同意门槛即可立即加载 Analytics，
• 不提交、不推送、不部署到生产环境。

请用户对这份完整计划进行一次明确确认。确认后，除不可避免的 Google 账号访问界面操作和新发现的冲突外，自主继续执行。

3. 一次性引导无密钥访问

检查辅助工具和本地配置：

node <skill-dir>/scripts/ga4-admin.mjs doctor

如果缺少配置，在计划获批后运行：

node <skill-dir>/scripts/ga4-admin.mjs bootstrap \
  --quota-project <project> \
  --time-zone America/Toronto \
  --currency CAD \
  --confirmed

此操作仅启用 analyticsadmin.googleapis.com 和 iamcredentials.googleapis.com，创建或复用 analytics-automation@<project>.iam.gserviceaccount.com，向活跃的 gcloud 用户授予该服务账号的 roles/iam.serviceAccountTokenCreator 角色，并向该服务账号授予配额项目的 roles/serviceusage.serviceUsageConsumer 角色。后者用于归属 Analytics API 配额；它不会授予对其他项目资源的访问权限。

IAM 更改可能需要约一分钟才能生效。辅助工具仅针对预期的 getAccessToken 和 serviceusage.services.use 传播失败，使用有界指数退避进行重试。不要扩大重试范围，将真实的 Analytics 授权失败也纳入其中。

用户必须在 Google Analytics「账号访问权限管理」中将打印出的服务账号邮箱添加为 编辑者。不要请求管理员权限。然后列出可访问的账号：

node <skill-dir>/scripts/ga4-admin.mjs accounts

首次使用时要求用户明确选择账号，将其写入本地配置，并在之后的运行中显示默认账号：

node <skill-dir>/scripts/ga4-admin.mjs set-account --account accounts/<id>

4. 配置前先核对

运行实时 API 计划：

node <skill-dir>/scripts/ga4-admin.mjs plan \
  --property-name '<name>' \
  --url '<canonical-production-url>'

如果发现名称或规范 URL 匹配的对象，请停止。说明候选对象，并要求用户明确批准后再传入 --adopt-property properties/<id>。绝不自动创建重复对象。

计划获批后，进行配置或核对：

node <skill-dir>/scripts/ga4-admin.mjs apply \
  --property-name '<name>' \
  --url '<canonical-production-url>' \
  --confirmed

获批后采用现有对象时，追加 --adopt-property properties/<id>。辅助工具会在获取数据流后立即写入 .ga4.json，以便在部分操作失败时能够以幂等方式修复。

检查源代码后，向 .ga4.json 添加非机密集成元数据：adapter、源 target、excludedPaths，以及在存在排除项时设置 cspBoundaryReviewed: true。未经明确批准，绝不要标记边界已审核。

5. 集成项目

完整阅读 references/integrations.md，并使用匹配的适配器。

适用于所有适配器的规则：

• 仅跟踪生产环境。
• 每个渲染页面恰好添加一个标签。
• 使用 .ga4.json 中的 Measurement ID。
• 不添加自定义业务事件。
• 保留项目的格式和惯例。
• 不要重命名或重新用于其他用途的现有应用代码“analytics”；GA 埋点应单独处理。

对于已关联的 Vercel 项目，仅通过 Vercel CLI 为 生产环境设置 NEXT_PUBLIC_GA_MEASUREMENT_ID。先检查现有变量；绝不要将其添加到预览或开发环境。不要触发部署。

对于不受支持的托管平台，完成源代码集成，但要准确报告仍需进行的部署配置。

6. 验证与核实

在可用时，运行仓库自身的格式化程序／检查模式、类型检查、lint、测试和生产构建。使用检测到的包管理器；绝不要创建其他锁文件。

核实实时 Analytics 配置：

node <skill-dir>/scripts/ga4-admin.mjs verify

然后按照集成参考中的双构建浏览器流程操作：验证不含生产环境变量的构建不会发出 GA 请求；在构建时提供生产环境变量后重新构建；模拟收集端点并返回 204，同时允许 gtag.js 加载；核实初始页面浏览和客户端导航页面浏览均正常，且没有重复记录。对于 apply/repair，必须进行浏览器级请求核实。

之后如有单独请求进行部署后核实，可以检查线上网站。安装期间不要等待 GA 报告；数据摄取存在延迟。

仅计划模式

如果用户只要求制定计划，则运行检查，以及现有配置允许的任何只读实时 API 计划。不要引导 IAM 配置、启用 API、创建 GA 资源、编辑文件或更改 Vercel。允许工作区存在未提交的更改。清楚列出阻碍事项和下一步安全操作。

修复模式

当 .ga4.json 存在时，plan 和 apply 会协调所引用的线上媒体资源，而不是创建另一个资源。仅修复缺失或存在偏差的非破坏性设置以及来源／部署集成。验证广告产品链接不存在。如果采用的媒体资源已有关联链接，则报告这些链接并停止；绝不删除或替换资源来修复偏差。