WEB_GROWTH
Web 搜索与行为采集运行说明
Section titled “Web 搜索与行为采集运行说明”本机只读采集工具,可手动运行或由独立 SEO 自反馈任务调用;采集器不修改 Google 权限或线上产品。当前定时配置见 SEO_FEEDBACK_RUNBOOK.md。
| 资源 | 固定目标 |
|---|---|
| Web | https://web.yomiya.cc/ |
| GA 属性 | 552033117,DailyJapanese-Web |
| Web 数据流 | 15522999439 |
| Google Tag | G-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。
node product/YomiyaProductAnalytics/engineering/yomiya-service-analytics/scripts/collect-web-growth.mjs doctornode product/YomiyaProductAnalytics/engineering/yomiya-service-analytics/scripts/collect-web-growth.mjs collectnode 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 和逐来源状态。
日期、维度与增量
Section titled “日期、维度与增量”- 默认末日为 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 行为; 只能做聚合页面比较,不能推出某个搜索词用户的学习转化率。
隐私、缺失与产物
Section titled “隐私、缺失与产物”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,不覆盖上一份完整产物。浏览器不用保持登录。
验收与后续复跑
Section titled “验收与后续复跑”doctor验证实际属性、测量 ID、数据流、权限、Sitemap、首页 SSR 标记。- 控制台确认品牌账号为已验证所有者,GA 关联目标资源与数据流,发布两个搜索报表。
- 真实浏览线上页面并开始学习,核对 Google Tag 请求、Realtime/DebugView 与 SPA
page_view。处理完成后再用collect读回相关日期;窗口截止规则仍然生效。 例如collect --end 2026-10-02后检查reports.ga.current.daily_events中date=20261002的page_view与learning_start。低样本数值仍抑制,未返回行继续标为待数据,不补零。 collect后validate,比较同一窗口重复运行的维度键和计数,核对近 7 天覆盖刷新。- Search Console 暂无数据时,分别记录“链路通过”和“搜索数据待积累”。
doctor 从原始首页 <head> 检查标记恰好一份且属于配置中的品牌 token,
同时检查线上测量配置。Realtime 支持的维度组合与 Core 不同;真实操作验收采用
eventName、streamId 与 eventCount,固定生产数据流。测试过程只保存事件存在性与
脱敏 Google Tag 请求,不保存客户端标识,也不把少量实时测试数值作为业务表现发布。
采集器不进行用户级匹配、iOS 安装归因或内容发布。独立的 SEO 自反馈层处理每周采集、月度证据筛选与 PR 草案、28 天观察;普通周仅保存本机记录,合并和发布仍由人工完成。
本次实施记录
Section titled “本次实施记录”2026-10-02 至 10-03 的实际账号配置、发布、真实事件与数据验收见 WEB_GROWTH_ACCEPTANCE.md。
品牌所有权、只读 API 与 GA 关联已通过;Search Console 集合为 Published to all,两个搜索报表已核验可打开。搜索表现为 pending_data,
本次真实学习的标准报表读回为 pending_processing。当前独立快照与有效来源指针
已生成,没有将待出数标为完整数据就绪。
竞品关键词研究接入
Section titled “竞品关键词研究接入”2026-10-03 增加独立的本机竞品导入、校验和报告入口,复用本工程的来源、缺失与 聚合边界;本节不改变 GA/GSC 采集命令或数据口径。研究范围为 US 英语和 TW 繁中 Google,免费工具获取受限时保留公开全球样本与缺口,不替代自身真实搜索词。
运行方式见 COMPETITOR_KEYWORDS.md,首批候选与页面优化 建议见 COMPETITOR_OPPORTUNITIES.md,验收见 COMPETITOR_KEYWORDS_ACCEPTANCE.md。首版历史记录保留;当前 #1722 已发布,独立本机定时层与六语言研究见 SEO_FEEDBACK_RUNBOOK.md。
- Search Console 所有权验证
- GA Search Console 关联与数据处理延迟
- Search Console 权限
- Search Analytics 查询限制与日期口径
- GA Core 报表兼容检查
国家映射来源与 SHA 在 scripts/lib/country-codes.json,许可证在
scripts/lib/country-codes.LICENSE。采集时不联网下载映射表。
Google 自然测量与当前集成
Section titled “Google 自然测量与当前集成”新增 google_organic_landing、google_organic_learning、google_organic_landing_learning 固定来源/媒介 google / organic;学习报表同时过滤 learning_start。落地学习启动为按会话入口归属的事件数,不是去重用户转化。既有全渠道报告继续独立保存。2026-10-03 新窗口、真实事件和发布验收见 SEO_FEEDBACK_ACCEPTANCE.md;本文更早快照与控制台记录保留历史边界。