pp-google-trends

Google Trends — Printing Press CLI

前置条件：安装 CLI

此技能使用 google-trends-pp-cli 二进制文件。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install google-trends --cli-only
   

2. 验证：google-trends-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、离线等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会将程序安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请改为将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/marketing/google-trends/cmd/google-trends-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续执行技能命令。

pytrends——事实上的标准 Python 封装库——已于 2025 年 4 月归档，而 Google Trends 会以极具侵略性且难以预测的方式限制匿名访问。此 CLI 内置重试和退避机制，完整涵盖从探索到 Widget 的整个流程，并将每次查询缓存在本地，让历史数据不断累积，而非逐渐消失；它还能回答实时网站无法回答的问题：三周前有哪些趋势、从上次检查以来发生了哪些变化，以及哪些相关词确实值得整理成内容简报。

何时使用此 CLI

使用此 CLI 进行程序化的 Google Trends 研究：获取随时间变化的兴趣度数据、进行多关键词和跨地区比较、发现相关查询和上升趋势以规划内容，以及通过本地缓存跟踪趋势话题的变化。若你需要 Google Trends 自带界面会丢弃的历史数据，或要自动化过去需要手动编写 pytrends 脚本完成的工作，此工具正合适。

不适用场景

请勿在以下场景使用此 CLI：

• 请勿使用此 CLI 查询绝对搜索量——Google Trends 只提供 0–100 的相对兴趣度，不提供实际查询次数。
• 请勿使用此 CLI 大规模实时（亚小时级）监控趋势——API 严格的速率限制会使高频轮询不可靠。
• 请勿使用此 CLI 获取经过身份验证的、类似 Google Ads Keyword Planner 的搜索量数据——这需要单独的 Google Ads 账户和 API，而非 Trends。

独特功能

其他任何用于此 API 的工具都不具备这些功能。

可不断累积的本地状态

• trends trending at — 查看过去某个特定日期和地区的趋势话题。Google Trends 自带的实时界面无法回答这个问题。

  当你需要还原过去某一天的趋势，而不是抓取无法显示任何历史趋势快照的实时网站时，请使用此功能。

  google-trends-pp-cli trends trending at --date 2026-06-15 --geo US --agent
  

• trends history search — 离线全文搜索你曾同步过的所有相关词和趋势话题结果。

  如果你想确认几周前跟踪的某个词是否曾作为相关词或趋势话题出现，可使用此功能，无需重新查询受速率限制的实时 API。

  google-trends-pp-cli trends history search "electric vehicle" --table related --agent
  

• trends changes — 查看自上次同步以来，某个关键词的相关词和兴趣度分数具体发生了哪些变化。

  如果你需要精确了解上周以来新增了什么，而不是再次目测图表，请使用此功能。

  google-trends-pp-cli trends changes coffee --since 7d --agent
  

• trends opportunities — 按上升势头与父主题增长的乘积为关键词的相关词和上升词排名，优先呈现最佳内容创意。

  如果你需要按发展势头排序的内容创意候选清单，而非原始的相关查询列表，请使用此功能。

  google-trends-pp-cli trends opportunities "meal prep" --agent
  

计算洞察

• trends seasonality — 根据缓存的历史数据，计算某个关键词的月均值、峰值月份和季节性强度评分。

  使用此工具可根据缓存的历史数据检测关键词的季节性模式，而不必手动查看图表。

  google-trends-pp-cli trends seasonality "pumpkin spice" --geo US --agent
  

• trends geo-gap — 对两个关键词关注度差异最大的地区进行排名，而不是提供需要手动比较的各地区原始值。

  使用此工具可获取两个关键词之间地区差异最大的排名列表，而非各地区的原始对比数据。

  google-trends-pp-cli trends geo-gap nike adidas --resolution REGION --agent
  

可访问性缓解

• trends stale — 列出本地数据最近未刷新的已跟踪关键词，方便你在触及速率限制前确定需要重新同步的内容。

  批量重新同步前，请先检查此项，以便仅刷新确实过期的数据，因为已确认此 API 的速率限制容易触发。

  google-trends-pp-cli trends stale --older-than 14d --agent
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。正常 API 调用无需常驻浏览器进程。

发现信号

此 CLI 根据浏览器观察到的流量上下文生成。

• 捕获覆盖范围：226 条网络记录中有 29 条 API 记录
• 协议：google_batchexecute（95% 置信度）、rpc_envelope（90% 置信度）、rest_json（75% 置信度）
• 身份验证信号：api_key — 请求头：X-Goog-Api-Key；api_key — 查询参数：key、token
• 生成提示：browser_http_transport、has_rpc_envelope、requires_protected_client、weak_schema_confidence
• 候选命令创意：create_GetAsyncData — 根据观察到的 POST /$rpc/google.internal.onegoogle.asyncdata.v1.AsyncDataService/GetAsyncData 流量推导得出。；create_batchexecute — 根据观察到的 POST //TrendsUi/data/batchexecute 流量推导得出。；create_browserinfo — 根据观察到的 POST //TrendsUi/browserinfo 流量推导得出。；create_explore — 根据观察到的 POST /trends/api/explore 流量推导得出。；create_reload — 根据观察到的 POST /recaptcha/enterprise/reload 流量推导得出。；create_startup_config — 根据观察到的 POST /v1/survey/startup_config 流量推导得出。；create_trigger_anonymous — 根据观察到的 POST /v1/survey/trigger/trigger_anonymous 流量推导得出。；create_ubd — 根据观察到的 POST /recaptcha/api2/ubd 流量推导得出。
• 注意事项：empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。；empty_payload：看似 API 的请求返回了空或 null 负载；架构置信度较低。

命令参考

trends — Google Trends 核心 explore/widget 流程。explore 和 pickers_* 可直接调用；widget_* 端点需要由先前的 explore 调用生成的令牌（通过 Priority 0/1 中手写的包装命令串联——参见 absorb 清单）。所有响应都带有 Google 的 XSSI 防护字符串 )]}', 必须在解码 JSON 前将其剥除。

• google-trends-pp-cli trends explore — 请求用于比较最多 5 个关键词的各小组件令牌。
• google-trends-pp-cli trends pickers-category — 完整的类别 ID 到名称查找树。公开访问，无需 clearance cookie。
• google-trends-pp-cli trends pickers-geo — 完整的地理代码到名称查找树（国家/地区/DMA/城市）。公开访问，无需 clearance cookie。
• google-trends-pp-cli trends widget-comparedgeo — GEO_MAP 小组件的地区兴趣数据。
• google-trends-pp-cli trends widget-multiline — TIMESERIES 小组件的随时间变化的兴趣数据。
• google-trends-pp-cli trends widget-relatedsearches — RELATED_QUERIES/RELATED_TOPICS 小组件的相关查询和相关主题（热门和飙升）。

找到合适的命令

知道自己想做什么，但不确定哪个命令能实现时，可以直接询问 CLI：

google-trends-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一项匹配；退出代码 2 表示没有可信匹配——请改用 --help 或使用更具体的查询。

示例

将一个品牌与两个竞争对手进行比较

google-trends-pp-cli trends interest nike --compare adidas,puma --geo US --timeframe "today 3-m" --json

一次调用即可在相同的 0-100 刻度上返回全部三个关键词；使用 pytrends 时，必须手动构造负载才能进行这种共享刻度比较。

根据某个主题，找出本周最佳内容创意

google-trends-pp-cli trends opportunities "home workout" --agent

按热度增长势头为飙升的相关词排序，而不是直接输出原始相关查询列表。

无需重新抓取，即可查看自上周以来的变化

google-trends-pp-cli trends changes coffee --since 7d --agent

对比最近两个本地快照——实时网站没有历史记录，因此无法回答这个问题。

获取大范围地区细分数据，并筛选出需要的字段

google-trends-pp-cli trends region coffee --resolution CITY --geo US --agent --select region_name,value

城市级细分数据会返回数十行及额外元数据；--select 可将响应精简为 Agent 通常需要的两个字段。

查看过去某个具体日期的热门趋势

google-trends-pp-cli trends trending at --date 2026-06-01 --geo US --json

这回答了实时 Trending Now 页面无法回答的问题——该页面始终只显示当前时间段。

身份验证设置

Google Trends 无需登录，也不需要 API 密钥。它通过匿名 NID cookie 进行身份验证，但首次连接时，普通 HTTP 客户端和带有 Chrome 指纹的客户端都会遭到拦截（HTTP 429）——生成期间已进行实时确认。运行一次 google-trends-pp-cli auth login --chrome，即可从已登录的 Chrome 会话导入 clearance cookie；CLI 会在需要时自动刷新。

运行 google-trends-pp-cli doctor 验证设置。

Agent 模式

在任意命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，这对控制上下文大小至关重要：

  google-trends-pp-cli trends explore --hl en-US --tz 42 --req '{}' --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求但不发送

• 便于离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 从不提示输入，所有输入均通过标志传入

• 明确重试 — 仅当已存在的创建操作应视为成功时，才使用 --idempotent

响应封装

从本地存储或 API 读取的命令会将输出封装在来源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

从 .results 解析数据，并从 .meta.source 判断数据来自实时来源还是本地。当 stdout 是终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会仅向 stderr 打印人类可读的 N results (live) 摘要；管道或 Agent 消费者以及显式指定格式的运行，stdout 都只输出纯 JSON。

路径与状态

Agent 应将 CLI 的路径解析器视为运行时契约的一部分：

• 单次调用使用 --home <dir>，或设置 GOOGLE_TRENDS_HOME=<dir>，将四种路径统一迁移到一个根目录下。

• 仅当某种特定路径必须使用不同位置时，才使用按类型设置的环境变量：GOOGLE_TRENDS_CONFIG_DIR、GOOGLE_TRENDS_DATA_DIR、GOOGLE_TRENDS_STATE_DIR、GOOGLE_TRENDS_CACHE_DIR。

• 解析顺序依次为按类型设置的环境变量、--home、GOOGLE_TRENDS_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），然后是平台默认值。

• config 存放 config.toml 和配置文件等设置。data 存放 credentials.toml、data.db、Cookie 和身份验证附属文件。state 存放持久化查询、任务和 teach.log。cache 存放可重新生成的 HTTP/缓存文件。

• 存储的密钥位于 data 目录下的 credentials.toml 中。为兼容性，也会读取旧版 config.toml 中的密钥，并在首次写入身份验证信息时将其从 config.toml 移出。

• 运行 google-trends-pp-cli doctor --fail-on warn，以显示路径和凭据位置警告。对于需要解析目录的 Agent，agent-context 会提供 schema v4 的 paths 区块。

• 对于 MCP，通过 MCP 主机配置传递迁移设置。MCP 二进制文件不会继承 CLI 标志：

  {
    "mcpServers": {
      "google-trends": {
        "command": "google-trends-pp-mcp",
        "env": {
          "GOOGLE_TRENDS_HOME": "/srv/google-trends"
        }
      }
    }
  }
  

多实例部署优先级：继承的按类型环境变量会覆盖该类型的显式 --home。使用 GOOGLE_TRENDS_HOME 或按类型设置的变量作为持久的多实例部署控制项；--home 仅用于单次调用。取消设置环境变量无法撤销迁移；清除 GOOGLE_TRENDS_HOME 前，请手动移动文件，否则 doctor 将无法找到留在原目录中的凭据。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

google-trends-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
google-trends-pp-cli feedback --stdin < notes.txt
google-trends-pp-cli feedback list --json --limit 10

条目会以 feedback.jsonl 的形式存储在解析后的 data 目录中。除非设置了 GOOGLE_TRENDS_FEEDBACK_ENDPOINT，且同时传入 --send 或设置 GOOGLE_TRENDS_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅在本地存储。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是会不断积累的部分。

输出传递

每条命令都接受 --deliver <sink>。除了 stdout 或取代 stdout，输出还会发送到指定的目标，因此 Agent 无需手动通过管道传递命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回一条结构化错误，其中列出受支持的方案。Webhook 失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置文件

配置文件是一组已保存的标志值，可在多次调用中重复使用。定时或周期性运行的 Agent 每次提供不同输入、但重复使用相同已保存标志时，可使用配置文件。

google-trends-pp-cli profile save briefing --json
google-trends-pp-cli --profile briefing trends explore --hl en-US --tz 42 --req '{}'
google-trends-pp-cli profile list --json
google-trends-pp-cli profile show briefing
google-trends-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件值；配置文件值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置文件，以便进行自检的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求受限（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 google-trends-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上方的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并带上 --agent）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/marketing/google-trends/cmd/google-trends-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add google-trends-pp-mcp -- google-trends-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which google-trends-pp-cli 如果未找到，提供安装选项（参见此技能顶部的先决条件）。
2. 将用户查询匹配到上方“独特功能”和“命令参考”中的最佳命令。
3. 使用 --agent 标志执行：

   google-trends-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，查看子命令帮助：google-trends-pp-cli <command> --help。