yandex-webmaster

yandex-webmaster

使用 Yandex Webmaster API v4。管理网站、分析索引情况、查看搜索查询、重新抓取页面、管理链接和 Feed。

Config

需要在 config/.env 中设置 YANDEX_WEBMASTER_TOKEN。 Scope：webmaster:hostinfo + webmaster:verify。 说明：config/README.md。

对于 alice.sh（Share of Voice，无公开 API），还需要 SESSION_ID — 浏览器中的 Cookie。详情见 config/README.md 和 references/ALICE_EFFICIENCY.md。

Philosophy

1. 缓存优先 — 网站列表和 user_id 会长期缓存。报告按 host+params 键缓存。诊断、配额和状态始终实时获取。
2. 上下文窗口整洁 — stdout 限制为 30 行。完整数据写入 TSV/文件。可通过 grep/rg 搜索缓存。
3. Host 解析 — 所有脚本都接受 --host <domain>（在缓存的 hosts.tsv 中搜索）或 --host-id <id>（直接指定 ID）。首次调用 hosts.sh 时会自动缓存网站列表。
4. 不执行破坏性操作 — 此技能不会删除网站、站点地图和 Feed。仅支持读取和添加。

Workflow

停！进行任何分析之前：

1. 获取网站列表：

   bash scripts/hosts.sh
   

2. 询问用户（如果无法从上下文中明确网站）：

   "О каком сайте идёт речь?
   Укажите домен или host_id из списка."
   

   要搜索缓存：

   bash scripts/hosts.sh --search "example"
   

   --host 和 hosts.sh --search 接受完整的西里尔字母域名 （例如，хорошие-данные.рф）或网站 URL（https://хорошие-данные.рф/）。 系统会使用 python3 自动将域名转换为 IDNA；URL 的协议和端口会保留。拉丁字母和现成的 xn--… 名称无需 Python。 不支持搜索西里尔字母名称中的任意片段： 请指定完整域名。缓存和结果中会保留原始 ASCII 地址 和 Yandex 的 host_id。

3. 获取网站摘要：

   bash scripts/summary.sh --host example.com
   

4. 根据用户的任务运行所需报告。

Scripts

通用调用模式：

bash scripts/<script>.sh --host <domain> [--action <action>] [params...]

网站管理

Script	Description	Key params
hosts.sh	网站列表	--search "text"、--no-cache
host_info.sh	网站信息 + 所有者	—
add_site.sh	添加网站	--url <url>
verify.sh	网站验证	--action get|start、--method DNS|HTML_FILE|META_TAG

网站统计

Script	Description	Key params
summary.sh	摘要：SQI、页面、问题	—
sqi_history.sh	SQI 历史	--date-from、--date-to
diagnostics.sh	网站问题（实时）	—

搜索查询

Script	Description	Key params
popular_queries.sh	热门查询	--order-by、--device、--limit
queries_history.sh	查询历史	--query-id（可选）、--device
query_analytics.sh	扩展分析（POST）	--text-indicator、--filter-*、--region-ids

索引

Script	Description	Key params
indexing.sh	索引历史/样本	--action history|samples
important_urls.sh	重要 URL	--action list|history、--url
archive_export.sh	导出所有页面	--action start|status、--task-id

搜索中的页面

Script	Description	Key params
insearch.sh	搜索结果中的页面	--action history|samples
search_events.sh	收录/移除情况	--action history|samples

重新抓取

Script	Description	Key params
recrawl.sh	重新抓取 URL	--action submit|status|list|quota、--url、--task-id

链接

Script	Description	Key params
internal_links.sh	失效的内部链接	--action samples|history、--indicator
external_links.sh	外部链接	--action samples|history

Сайтмапы

Script	Description	Key params
sitemaps.sh	Управление сайтмапами	--action list|user-list|info|add|recrawl-limit|recrawl

Alice / Share of Voice (SSR scraping)

Script	Description	Key params
alice.sh	Эффективность в Алисе: SoV timeline, конкуренты, запросы где сайт есть/нет	--action summary|sov|competitors|with-site|without-site|fetch, --no-cache

⚠ Нет публичного API — данные парсятся из window._initData HTML-страницы. Для загрузки нужен SESSION_ID cookie в config/.env. Корректный кеш используется 24 часа без загрузки страницы; --no-cache и --action fetch обновляют его принудительно. Если обновление не удалось, команда завершается с ошибкой, сохраняя прежний JSON. Диагностика и повторы: references/ALICE_EFFICIENCY.md.

Фиды и PRO

Script	Description	Key params
feeds.sh	YML-фиды	--action list|add|change|add-status, --type, --region-ids
search_export.sh	PRO SERP экспорт	--action dates|limits|start|status
regions.sh	Справочник регионов	--filter "москва"

Общие параметры

Param	Description
--host <domain>	Домен/URL сайта (поиск по hosts.tsv)
--host-id <id>	Прямой host_id (формат: http:example.com:80)
--action <act>	Подкоманда скрипта
--date-from	Начало периода YYYY-MM-DD (history: default 90 дней назад)
--date-to	Конец периода YYYY-MM-DD
--limit N	Число записей
--offset N	Смещение
--no-cache	Пропустить кеш

Кеш-стратегия

Кеш в cache/:

• user_id.txt — ID пользователя (permanent)
• hosts.json + hosts.tsv — список сайтов (permanent, инвалидируется при add/verify)
• host_*/queries/*.tsv — результаты запросов (session, hash-keyed)
• host_*/indexing/*.tsv — данные индексации (session)
• host_*/insearch/*.tsv — данные о поиске (session)
• host_*/links/*.tsv — данные о ссылках (session)
• host_*/alice/init.json — проверенный объект Alice, общий для всех действий alice.sh, срок кеша — 24 часа
• host_*/alice/raw.html — последний полностью полученный HTML для диагностики, без истории версий
• Диагностика, квоты, статусы переобхода — не кешируются (always live)

Расширенные сценарии

• Добавление и верификация сайтов
• Поисковые запросы и аналитика
• Управление сайтмапами
• Статистика сайта и индексация
• Страницы в поиске
• Переобход страниц
• Битые внутренние ссылки
• Внешние ссылки
• YML-фиды
• PRO SERP экспорт
• Alice / Share of Voice (scraping)
• Расписание врачей (спецификация)

Лимиты API

• Query Analytics: 10 000 запросов/час на домен
• Скрипты автоматически обрабатывают 429 (Retry-After ≤ 60s → retry, иначе fail)
• Лимит сайтов: 1703 на аккаунт
• Лимит фидов: 5000 на сайт, 50 в batch
• Лимит export: макс. 100 комбинаций дат+URL