用途
yandex-webmaster 用于通过 Yandex Webmaster API v4 管理网站，覆盖索引分析、搜索查询、重新抓取、链接检查、站点地图与订阅源管理等任务，并提供对 Alice / Share of Voice 页面的抓取分析。
主要能力
- 网站管理：列出网站、查看站点信息与所有者、添加网站、进行验证。
- 站点统计：获取概览（SQI、页面、问题）、SQI 历史、实时诊断。
- 搜索查询：热门查询、查询历史、扩展分析（POST）。
- 索引：索引历史与样本、重要 URL、全部页面导出。
- 收录情况：搜索引擎中的页面、出现/消失事件历史与样本。
- 重新抓取：提交 URL、查询状态、列表与配额。
- 链接：内部死链、外部链接的样本与历史。
- 站点地图：列出、用户列表、信息、添加、调整重抓次数、重抓。
- 订阅源与 PRO：管理 YML 订阅源，PRO SERP 导出的日期、限额、启动与状态。
- 区域：区域查询。
- Alice / Share of Voice：通过 SSR 抓取获取 SoV 时间线、竞争对手、站点有无覆盖的查询；无公开 API，需在 config/.env 中设置 SESSION_ID cookie。
使用方式
脚本调用通用格式：
bash scripts/<script>.sh --host <domain> [--action <action>] [params...]
工作流要求：先获取网站列表 bash scripts/hosts.sh，再向用户确认目标站点，然后按任务运行相应报告。--host 与 hosts.sh --search 支持完整西里尔域名（如 хорошие-данные.рф）或 URL，域名会通过 python3 自动转为 IDNA，拉丁字母与现成 xn-- 名称无需 Python。
配置
需要 YANDEX_WEBMASTER_TOKEN（config/.env），Scope 为 webmaster:hostinfo + webmaster:verify。Alice 的 Share of Voice 另需 SESSION_ID。说明见 config/README.md 与 references/ALICE_EFFICIENCY.md。
缓存与限制
- 缓存优先：网站列表与 user_id 长期缓存，报告按 host+params 键缓存；诊断、配额、状态始终实时。
- stdout 限制 30 行，完整数据写入 TSV/文件，可通过 grep/rg 检索。
- 不执行破坏性操作，只读取与添加。
- API 限制：Query Analytics 每域名 10000 请求/小时；脚本自动处理 429（Retry-After ≤ 60s 重试，否则失败）；站点数上限 1703/账号；订阅源上限 5000/站点、50/批次；导出最多 100 个日期+URL 组合。