跳转到内容

WEB_GROWTH

本机只读采集工具,可手动运行或由独立 SEO 自反馈任务调用;采集器不修改 Google 权限或线上产品。当前定时配置见 SEO_FEEDBACK_RUNBOOK.md。

资源固定目标
Webhttps://web.yomiya.cc/
GA 属性552033117,DailyJapanese-Web
Web 数据流15522999439
Google TagG-SWRX5BWVTS
GA 时区从 Admin API 读取,当前 America/Los_Angeles
Search Console同域名的网址前缀资源;日期按其原生太平洋时区
品牌管理账号yomiya.app@gmail.com;已核对 GA Administrator 与 Search Console 已验证所有者
采集服务账号ga4-slack-reporter@yomiya-8f5f2.iam.gserviceaccount.com;GA Viewer,Search Console Restricted
GCP 项目yomiya-8f5f2;GA Data、GA Admin、Search Console API

Google 控制台配置状态以本机 doctor.json 与验收证据为准;此表描述目标范围, 不能单独作为验证、授权或关联已经完成的证明。

服务账号凭证保存在 ~/.config/yomiya/ga4-readonly.json,必须为 0600。 工具只申请 analytics.readonly 和 webmasters.readonly;拒绝 PATCH、DELETE、 非白名单 POST 和其他 API 域名。OAuth Token 只留在内存中。

本次 Google 连通由本机已有的 Clash Verge TUN 与持久化路由提供;复跑时需保持该网络路径可用,先用 doctor 核对连接与权限。

从保存本次提交的 Root checkout 运行,Node 22 或更新版本,无需安装 npm 依赖。当前专用 checkout 为 /Users/cc/Documents/root-remote/.worktrees/seo-six-locales。

Terminal window
node product/YomiyaProductAnalytics/engineering/yomiya-service-analytics/scripts/collect-web-growth.mjs doctor
node product/YomiyaProductAnalytics/engineering/yomiya-service-analytics/scripts/collect-web-growth.mjs collect
node product/YomiyaProductAnalytics/engineering/yomiya-service-analytics/scripts/collect-web-growth.mjs validate

可选参数:--config /absolute/path/config.json,collect --end YYYY-MM-DD, validate --run /absolute/path/run-directory。默认配置在 ~/.config/yomiya/web-growth.json;缺少默认配置时仍可使用固定目标默认值。 显式提供的配置文件缺失会失败。输出默认写入:

~/Library/Application Support/YomiyaAnalytics/web-growth/

配置字段为 propertyId、measurementId、host、siteUrl、credentialsPath、 outputDir、timeoutMs、publicSitemapTimeoutMs、maxPages、siteVerificationToken(公开 HTML 标记)。 Google API 单次超时默认 15 秒,公共 Sitemap XML 默认 45 秒。controlPlane 和 liveEventTest 记录控制台 与真实操作验收的人工证据;API 可读不等于所有权、关联或发布验收已经完成。

退出码:0 为命令检查通过或完整数据采集,2 为部分结果或搜索数据待积累, 1 为执行/产物校验失败。必须同时阅读 acceptance 和逐来源状态。

  • 默认末日为 GA 属性当日减两天,避开近期处理延迟。首次读取最近 56 天, 分别查询最近 28 天与前 28 天。显式日期也必须早于该保守截止日。
  • 所有 GA 报表同时过滤 Web streamId 和 hostName。先读取 Metadata, 再检查所请求字段的兼容性。用户数由完整窗口单独查询;不相加每日或分组用户数。
  • GA 采集渠道、来源/媒介、国家、设备、浏览器语言、落地页、页面、事件, 及学习启动。daily_events 另按 date × eventName 保存页面浏览与学习事件,供处理后核对测试日期。learning_start 是开始学习;不能视为有效学习或 iOS 安装。 route_locale 从页面路由派生,与浏览器语言分开保存。
  • Search Console 只采集 type=web、dataState=final。分别保留站点汇总、 搜索词 × 页面 × 国家 × 设备,以及页面 × 国家 × 设备,记录分页和截断。 隐藏搜索词与 API top-row 限制意味着搜索词行合计不等于站点总量。
  • 56 天日级缓存按日期覆盖;重跑只刷新近 7 天及此前失败/缺失的日期。 28 天完整窗口报表每次重新读取以维持用户去重口径。历史 pending_data 日期也重读,避免将空结果永久冻结。历史窗口不得叠加。
  • 页面 × 国家 × 设备对照先把 GSC 三字母国家码通过随工具保存的 Unicode CLDR 表映射为 GA 两字母国家码,并统一设备大小写。对照采用所有渠道的 Web 行为; 只能做聚合页面比较,不能推出某个搜索词用户的学习转化率。

URL 落盘前去除查询串和 fragment。认证、分享、导入详情和未确认公开的动态内容 ID 不落盘;其移除行数单独记录。公开工具入口和数值内容路径可保留。动态内容仅在生产 Sitemap 的明确公开路径中保留 UUID,并把已知 /news/、/app/news/ 历史入口归到 对应的 /content/ canonical。工具读取一个公开语言子 Sitemap 及其明确列出的 hreflang alternate;目录缓存 6 小时,不把它称为完整公共页面清单。目录读取失败时 继续保守地移除未经确认的 ID,记录来源、摘要、状态和覆盖限制。GA 小于 5 用户的分组 保留维度与抑制标记,数值为 null。URL 规范化产生重复 GA 维度时不相加 估算用户,而是标记碰撞并将指标置空。GSC 对重复规范化维度重算 CTR 与 展示量加权排名。CSV 会转义公式前缀,空数据文件保留报表字段表头。

每次采集生成独立 runs/<run-id>/:

  • aggregate.json:逐来源、逐报表、分页、阈值、时区与对照结果。
  • public-content-paths.json:本轮采用的公开内容路径证据,纳入清单摘要校验。
  • GA/GSC CSV 和页面国家设备对照 CSV。
  • report.md:28 天汇总、来源和验收状态。
  • manifest.json:窗口、状态、行数、覆盖限制、文件大小与 SHA-256。
  • validation.json:完整性、敏感信息、过滤目标、重复行和缺失编码检查。

空 Search Console 成功响应标记为 pending_data,不填零。权限失败、API 未启用、 网络错误或分页截断分开标记。查询失败最多重试三次(仅网络、429、5xx)。 完成校验后才更新有效快照指针:latest.json 只指向全部来源可用的完整结果, latest-ga.json 和 latest-gsc.json 指向各自有效结果;失败或部分结果只更新 latest-attempt.json,不覆盖上一份完整产物。浏览器不用保持登录。

  1. doctor 验证实际属性、测量 ID、数据流、权限、Sitemap、首页 SSR 标记。
  2. 控制台确认品牌账号为已验证所有者,GA 关联目标资源与数据流,发布两个搜索报表。
  3. 真实浏览线上页面并开始学习,核对 Google Tag 请求、Realtime/DebugView 与 SPA page_view。处理完成后再用 collect 读回相关日期;窗口截止规则仍然生效。 例如 collect --end 2026-10-02 后检查 reports.ga.current.daily_events 中 date=20261002 的 page_view 与 learning_start。低样本数值仍抑制,未返回行继续标为待数据,不补零。
  4. collect 后 validate,比较同一窗口重复运行的维度键和计数,核对近 7 天覆盖刷新。
  5. Search Console 暂无数据时,分别记录“链路通过”和“搜索数据待积累”。

doctor 从原始首页 <head> 检查标记恰好一份且属于配置中的品牌 token, 同时检查线上测量配置。Realtime 支持的维度组合与 Core 不同;真实操作验收采用 eventName、streamId 与 eventCount,固定生产数据流。测试过程只保存事件存在性与 脱敏 Google Tag 请求,不保存客户端标识,也不把少量实时测试数值作为业务表现发布。

采集器不进行用户级匹配、iOS 安装归因或内容发布。独立的 SEO 自反馈层处理每周采集、月度证据筛选与 PR 草案、28 天观察;普通周仅保存本机记录,合并和发布仍由人工完成。

2026-10-02 至 10-03 的实际账号配置、发布、真实事件与数据验收见 WEB_GROWTH_ACCEPTANCE.md。 品牌所有权、只读 API 与 GA 关联已通过;Search Console 集合为 Published to all,两个搜索报表已核验可打开。搜索表现为 pending_data, 本次真实学习的标准报表读回为 pending_processing。当前独立快照与有效来源指针 已生成,没有将待出数标为完整数据就绪。

2026-10-03 增加独立的本机竞品导入、校验和报告入口,复用本工程的来源、缺失与 聚合边界;本节不改变 GA/GSC 采集命令或数据口径。研究范围为 US 英语和 TW 繁中 Google,免费工具获取受限时保留公开全球样本与缺口,不替代自身真实搜索词。

运行方式见 COMPETITOR_KEYWORDS.md,首批候选与页面优化 建议见 COMPETITOR_OPPORTUNITIES.md,验收见 COMPETITOR_KEYWORDS_ACCEPTANCE.md。首版历史记录保留;当前 #1722 已发布,独立本机定时层与六语言研究见 SEO_FEEDBACK_RUNBOOK.md。

国家映射来源与 SHA 在 scripts/lib/country-codes.json,许可证在 scripts/lib/country-codes.LICENSE。采集时不联网下载映射表。

新增 google_organic_landing、google_organic_learning、google_organic_landing_learning 固定来源/媒介 google / organic;学习报表同时过滤 learning_start。落地学习启动为按会话入口归属的事件数,不是去重用户转化。既有全渠道报告继续独立保存。2026-10-03 新窗口、真实事件和发布验收见 SEO_FEEDBACK_ACCEPTANCE.md;本文更早快照与控制台记录保留历史边界。