用途
本技能用于查询和分析 Google Trends 关键词搜索兴趣数据，帮助用户了解某个关键词的搜索热度如何随时间、地区变化。适用于趋势方向分析、季节性峰值检测、区域市场调研和新兴趋势追踪等场景。
核心概念
Google Trends 提供归一化的搜索兴趣数据（0-100 分制），反映某搜索词相对于所选地区和时段内峰值热度的受欢迎程度。100 代表峰值热度，50 表示热度为峰值的一半，0 表示数据不足。
语言规则：关键词必须使用目标国家的语言。例如美国用英文关键词，德国用德文，日本用日文。若用户提供的关键词语言不符，需先翻译再查询。
参数
- keyword（字符串，必填）：要分析的搜索关键词，最长 100 字符，须为目标国家语言。
- region（字符串，选填）：国家/地区代码，默认 US。
- dayRangeStart（字符串，选填）：时间范围起始日期，格式 YYYY-MM-DD，2004 年起。
- dayRangeEnd（字符串，选填）：时间范围结束日期，格式 YYYY-MM-DD，2004 年起。
当同时提供 dayRangeStart 和 dayRangeEnd 时，自定义时间范围优先。
支持的地区
US（美国）、GB（英国）、JP（日本）、CA（加拿大）、MX（墨西哥）、DE（德国）、FR（法国）、IT（意大利）、ES（西班牙）、NL（荷兰）、AU（澳大利亚）、SG（新加坡）、AE（阿联酋）、BR（巴西）、IN（印度）、TR（土耳其）、PL（波兰）、SE（瑞典）。默认地区为 US，用户未指定时使用 US。
使用方式
本工具调用 LinkFox 工具网关 API，调用约定、请求参数和响应结构见 references/api.md，也可直接执行 scripts/google_trends_keyword.py 运行查询。
构建查询的原则：使用正确语言；明确地区；用日期范围做聚焦分析；关键词保持简洁。
调用示例：
- 基础关键词趋势（默认地区与时间）：{"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"}
展示规则
用表格或趋势曲线清晰呈现数据，包含峰值、低谷和显著变化等关键数据点；说明 0-100 归一化量表的含义；指出季节性模式、突增或持续增长/下降；当响应包含 chartOption 时，说明可视化数据可用并描述趋势形态；查询失败时说明原因并建议调整（如检查拼写、更换日期范围、确认关键词语言）。
适用场景
适用于：关键词在 Google 上的热度查询、趋势方向判断、季节性峰值检测、跨月热度对比、区域趋势检查、历史趋势分析、节假日/事件驱动分析。
不适用于：Google Ads 关键词规划或出价/CPC 数据、绝对搜索量、社交媒体热门话题、亚马逊专属搜索词数据、网站流量分析、搜索引擎结果页关键词排名。
边界判断：当用户说“关键词研究”或“市场趋势分析”且具体涉及 Google 视角下随时间变化的搜索兴趣热度时适用；若需要绝对流量数字、广告指标或电商平台专属数据则不适用。
限制
- 不支持二次 SQL 处理：结果非结构化，无法输入动态查询工具做二次分析。
- 归一化数值：趋势值为相对值（0-100），非绝对搜索量。
- 数据可用性：数据自 2004 年起，但非常冷门的词可能数据稀疏。
- 单次单关键词：每次 API 调用处理一个关键词，多关键词对比需分别调用后比较。
- 语言要求：关键词须匹配目标地区语言才能获得准确结果。
反馈与大响应处理
当功能与实际行为不符、结果与用户意图不符、用户表达不满或赞扬、或有可改进之处时，通过 Feedback API 自动检测并上报反馈，不打断用户流程。
为避免溢出智能体上下文，可将响应持久化到磁盘并仅提取所需字段：
python scripts/response_io.py run --script scripts/google_trends_keyword.py --out-dir <DIR> '<params>' python scripts/response_io.py read <file> --fields "<paths>" # 或 --path "<JMESPath>"
--out-dir 应选在 git 工作树之外（如 Unix 的 /tmp/...、Windows 的 %TEMP%/...）。持久化响应可能含 PII、定价或认证敏感数据，请勿提交。文件不会自动删除，任务完成后请清理。run 将完整响应写入文件，仅输出 schema 预览和文件路径；read 投影特定字段，支持 --limit/--offset 切片和 --format json|jsonl|csv|table 输出。
当响应字段多、含批量/分页结果、含长文本字段或输出需跨后续步骤复用时，优先使用该模式；小型单次响应可直接调用主脚本。注意预览是截断的 schema 加样本，非完整数据，任何字段级决策须通过 read 从持久化文件读取。