用途
本技能用于查询和分析 Google Trends 关键词搜索热度数据，帮助用户了解某个关键词在不同地区、不同时间段内的受欢迎程度变化。适用于关键词热度查询、趋势方向判断、季节性高峰识别、区域市场调研和历史趋势分析等场景。
主要能力
- 按关键词查询 Google Trends 搜索兴趣趋势。
- 支持指定国家/地区，默认使用美国（US）。
- 支持自定义时间范围（dayRangeStart、dayRangeEnd，格式 YYYY-MM-DD，从 2004 年起）。当同时提供起止日期时，自定义时间范围优先。
- 返回 0-100 归一化搜索兴趣值：100 表示所选范围内峰值热度，50 表示峰值的一半，0 表示数据不足。
- 支持的区域：US、GB、JP、CA、MX、DE、FR、IT、ES、NL、AU、SG、AE、BR、IN、TR、PL、SE。
参数
- keyword（字符串，必填）：要分析的搜索关键词，最长 100 字符，必须使用目标国家的语言。
- region（字符串，选填）：国家/地区代码，默认 US。
- dayRangeStart（字符串，选填）：时间范围起始日期，格式 YYYY-MM-DD，从 2004 年起。
- dayRangeEnd（字符串，选填）：时间范围结束日期，格式 YYYY-MM-DD，从 2004 年起。
使用方式
- API 端点：POST /googleTrend/getTrendByKeys，完整参数、响应与错误码见 references/api.md。
- Python 脚本：python scripts/google_trends_keyword.py '<JSON 参数>' [--inline]。
- 成本约束：本工具消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24 小时本地缓存。失败或空结果不得自动更换关键词、翻页或连续试探；需要继续检索时应先向用户说明会产生额外消耗。
输出策略（脚本默认行为）
- 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-google-trend-get-trend-by-keys-<timestamp>.json；<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错。
- 响应体不超过 8 KB 时，落盘后把完整 JSON 打印到 stdout。
- 响应体大于 8 KB 时，落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度加前 3 条样本）。
- 加 --inline 可强制全量打印到 stdout，同样落盘。
- 建议先看摘要判断是否足够，需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 json 文件中按需抽取，避免整份 JSON 进入上下文。
使用示例
- 基础查询：{"keyword": "wireless charger"}
- 指定地区：{"keyword": "Ladekabel", "region": "DE"}
- 自定义日期：{"keyword": "christmas gifts", "region": "US", "dayRangeStart": "2024-09-01", "dayRangeEnd": "2025-01-31"}
- 跨年对比：{"keyword": "sunscreen", "region": "AU", "dayRangeStart": "2023-01-01", "dayRangeEnd": "2025-12-31"}
- 区域市场调研：{"keyword": "yoga mat", "region": "GB"}
- 新兴趋势检测：{"keyword": "AI glasses", "region": "US", "dayRangeStart": "2024-01-01", "dayRangeEnd": "2025-12-31"}
适用场景
用户询问某关键词在 Google 上的热度、趋势方向、季节性高峰、区域热度差异，或某个时间段内的历史趋势时适用。当用户提到“关键词研究”或“市场趋势分析”，且具体指向 Google 视角下的搜索兴趣随时间变化时，也适用。
限制
- 数据为相对值（0-100 归一化），不是绝对搜索量。
- 数据从 2004 年起可用，但非常冷门的词可能数据稀疏。
- 每次 API 调用只处理一个关键词；需要多关键词对比时应分别调用再比较结果。
- 关键词必须使用目标地区的语言，否则结果可能不准确；如用户提供的关键词语言不对，应先翻译再查询。
- 不适用于 Google Ads 关键词规划或竞价/CPC 数据、绝对搜索量、社交媒体热榜（Twitter/X、TikTok 等）、亚马逊搜索词数据、网站流量分析、搜索引擎结果页关键词排名等需求。
- 数据分析时从保存的响应中读取 trendInfoForKeys[].trendValues[]，保留 timeRange 和诸如 "<1" 的值，不要转换为零；_dataQuery_executeDynamicQuery 查询的是存储在 SLS 中的 Linkfox 会话数据，不是任意 JSON 文件，仅在所需存储数据映射存在时使用。
认证与算力
如未配置 API Key（LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY）、响应 401 或 402、或提示算力或余额不足时，可参考 references/onboarding.md 处理。本技能消耗 6 算力，用户会因算力消耗而支付费用；当需要高频调用或用户对算力消耗预期不足时，应提醒用户并由用户决定是否继续。