yandex-search-api

yandex-search-api

通过 Yandex Cloud Search API v2 解析 Yandex SERP（同步 + 异步）。

信息上下文（智能摘要）

Search API 返回的不只是链接和一两句话的摘要，还会提供约 500 个 token 的已找到页面片段——内容与查询相关，并包含文档中的引文。信息已经足以回答问题，无需自行处理页面。

这正是将此技能安装到 Agent 中的原因：一次查询就足以得到答案，而不只是链接列表。

默认启用，无需单独的脚本：

bash scripts/web_search_sync.sh --query "как считается НДС для УСН в 2026" --region-id 225

文本不会打印到响应中，而是写入 cache/results/<hash>.md；stdout 中则会按每个文档一行输出索引。接下来从文件中读取结果包：需要全部内容时读取完整文件，只需一个来源时则使用 grep。为了获取已在结果包中的文本而重复搜索同一短语，只会浪费金钱。

以下三个限制会影响命令的选择：

• 仅限同步模式。 web_search_async.sh 不会返回信息上下文。
• 仅限 SEARCH_TYPE_RU。 使用其他搜索类型时，技能仍会执行查询，但不会返回信息上下文，并会说明这一点。
• 最多 20 个文档。 不能请求更多：当 --results 超过 20 时，API 返回的不是 20 个，而是少一半，价格却相同。技能会自动限制数量。
• 费用更高。 每 1000 次查询需 1 500 ₽，普通同步搜索则为 488 ₽。

如果只需要排名和域名，请使用 --no-snippets（或在配置中设置 search.smart_snippets.enabled: false）。

详情、响应格式、调试和错误排查： references/SMART_SNIPPETS.md。

配置

需要使用具有 search-api.webSearch.user 角色的 Yandex Cloud 服务账号。 支持通过已授权的 JSON 密钥使用 IAM，以及服务账号 API 密钥。 两种方式的分步配置说明：config/README.md。

现有 IAM 配置无需更改即可继续使用。使用 API 密钥时，请在 config.json 中设置 auth.mode: "api_key"，并在 config/.env 中设置 YANDEX_AI_API_KEY。

工作流

停止！开始任何搜索前：

1. 确定地区：

   • 如果用户指定了城市/地区，请自动查找 ID：

     bash scripts/search_region.sh --name "Казань"
     

   • 如果无法从上下文判断地区，请询问并等待答复：

     "要搜索哪个地区？
     - 全俄罗斯（默认）
     - 莫斯科
     - 具体城市（哪个？）"
     

     在用户答复前不要继续！
   • 将获得的名称传给 search_region.sh --name "..."，即可获得 ID
   • 遇到歧义时（莫斯科市还是莫斯科州），请向用户确认

2. 搜索模式从 config.json → search.mode 中读取（默认为 sync）。 不要询问，使用配置中的值。 例外：如果需要信息上下文，模式必须为 sync，搜索类型必须为 SEARCH_TYPE_RU；异步 API 和其他搜索库不提供这些内容。

3. 验证配置：确认已设置 yandex_cloud_folder_id 和相应的凭据（auth.mode 字段为可选）。不要打印密钥或令牌。

4. 执行搜索，使用获取到的地区 ID

5. 展示结果：有 snippets 时，读取 cache/results/<hash>.md 并据此回答，同时引用来源；没有 snippets 时，展示排名、标题、 URL 和摘要

脚本

iam_token_get.sh

从服务账号密钥生成或验证 IAM 令牌。仅当 auth.mode 为 iam 时需要。

bash scripts/iam_token_get.sh

令牌会缓存到 cache/iam_token.json，并在过期时自动刷新。

web_search_sync.sh

同步搜索 — 每次查询一个，立即返回结果。 唯一支持智能摘要的模式。

# Single query — с выдержками страниц
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213

# Только позиции и ссылки, без выдержек
bash scripts/web_search_sync.sh \
  --query "купить дымоход" \
  --region-id 213 \
  --no-snippets

# Batch from file — по строке на запрос в stdout, пак на каждый запрос
bash scripts/web_search_sync.sh \
  --file queries.txt \
  --region-id 225

参数	必需	默认值	取值
--query, -q	是*	-	搜索文本
--file, -f	是*	-	包含查询的文件（每行一个）
--region-id, -r	否	来自配置（225）	地区 ID
--results, -n	否	启用摘要时为 20，否则取自配置（10）	启用摘要时上限为 20；未启用时为 1-100
--page, -p	否	0	页码
--search-type	否	SEARCH_TYPE_RU	SEARCH_TYPE_RU / SEARCH_TYPE_TR / SEARCH_TYPE_COM / SEARCH_TYPE_KK / SEARCH_TYPE_BE / SEARCH_TYPE_UZ
--family-mode	否	FAMILY_MODE_MODERATE	FAMILY_MODE_NONE / FAMILY_MODE_MODERATE / FAMILY_MODE_STRICT
--snippets	否	启用	请求页面摘录
--no-snippets	否	-	仅返回链接和简短摘要

* 必须提供 --query 或 --file。

结果保存至 cache/results/<hash>.md（包含摘录的文档包）、 cache/results/<hash>.json（已解析）和 cache/results/<hash>.raw — 原始 响应正文：包含信息上下文时为 JSON，不包含时为 XML。

web_search_async.sh

异步批量搜索 — 提交多个查询，轮询获取结果。

# Submit batch and wait
bash scripts/web_search_async.sh \
  --file queries.txt \
  --region-id 213

# Resume after timeout/interrupt
bash scripts/web_search_async.sh --resume

参数	必需	默认值	取值
--file, -f	是	-	包含查询的文件
--region-id, -r	否	来自配置（225）	地区 ID
--poll-interval	否	10	轮询间隔（分钟）
--max-wait	否	120	超时前的最长等待时间（分钟）
--resume	否	-	继续轮询待处理操作

异步工作流：

1. 脚本将所有查询作为异步操作提交
2. 每隔 poll_interval 分钟轮询一次，检查是否完成
3. 下载并解析已完成的结果
4. 超过 max_wait 时：打印摘要和恢复命令
5. 使用 --resume 重启时：从 cache/ops/ 继续，不会重复执行

给 Agent 的说明： 异步执行可能需要几分钟到几小时。 脚本会自动处理轮询。如果超时， 请使用 --resume 重新运行以继续。

异步模式下无法获取信息上下文 — 仅返回链接和简短摘要。需要页面片段时，请使用 web_search_sync.sh --file。 不过，async 的费用约为同步模式的 1/16，约为信息上下文的 1/50。

regions_tree.sh

显示常用地区 ID。

bash scripts/regions_tree.sh

search_region.sh

按名称查找地区 ID。

bash scripts/search_region.sh --name "Казань"

输出格式

每条搜索结果包含：

• position — 在搜索结果页中的排名
• title — 页面标题
• url — 页面 URL
• snippet — 文本摘要（最多 300 个字符）
• domain — 网站域名
• extract — 信息上下文：页面片段；若没有则为空字符串

结果缓存在 cache/results/：

• <hash>.md — 文档包：每个文档的标题、URL 和信息上下文
• <hash>.raw — 原始响应正文：普通结果为 XML，信息上下文为 JSON （格式由服务端决定）
• <hash>.json — 已解析的 JSON 数组，两种情况均使用统一格式

<hash> 是查询文本的 md5 前 12 个字符。

不要将信息上下文打印到 stdout。 20 个文档、每个约 500 个 token，无法放入沙盒输出缓冲区，脚本会静默失败。脚本只打印索引，文本通过 Read/grep 从文档包中读取。

测试

离线测试：无需网络，也无需服务账号。

sh scripts/tests/run.sh

测试会检查请求正文的构建、两种响应格式（XML 和 JSON）的解析、文档包渲染以及 CLI 参数解析。无需付费，也可以手动查看请求正文：

YSA_DRY_RUN=1 bash scripts/web_search_sync.sh --query "тест"

常用地区 ID

地区	ID
俄罗斯	225
莫斯科	213
莫斯科及莫斯科州	1
圣彼得堡	2
叶卡捷琳堡	54
新西伯利亚	65
喀山	43

运行 bash scripts/regions_tree.sh 查看完整列表。

Pricing

Тарификация — за один запрос. Цены за 1000 запросов, с НДС:

Тип запроса	₽
Дневные синхронные	488
Ночные синхронные (00:00–07:59 UTC+3)	366
Дневные отложенные (async)	30,5
Запросы инфоконтекста поиска в регионе RU	1 500

Инфоконтексты дороже обычного синхронного запроса примерно втрое. Если нужны только позиции по большому списку запросов — async или --no-snippets.

Актуальный прайс: https://aistudio.yandex.ru/docs/ru/search-api/pricing

Example Session

User: Разберись, как в 2026 считается НДС для УСН, и дай ответ со ссылками

Claude: [Регион из контекста не следует, но вопрос общероссийский → 225]

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Ищет с выдержками — они включены по умолчанию]
        bash scripts/web_search_sync.sh --query "НДС для УСН 2026 порядок расчёта" --region-id 225

        === Results for: НДС для УСН 2026 порядок расчёта ===
        Region: 225 | Page: 0 | Snippets: true

            #  символов  домен                     заголовок
            1      1840  nalog.gov.ru              Об изменениях в главе 26.2 НК РФ
            2      1512  consultant.ru             НДС при УСН с 2026 года
            3         0  example-blog.ru           Что изменится для упрощенцев
            ...

          Всего: 20, с выдержками: 17
          Пак:  cache/results/a1b2c3d4e5f6.md (48 KB) — читай его вместо повторного поиска

        [Читает пак и отвечает по нему, а не по заголовкам]
        Read cache/results/a1b2c3d4e5f6.md

        По порогу выручки: ...  (nalog.gov.ru)
        По ставкам: ...          (consultant.ru)

User: Найди топ выдачи яндекса по запросу "купить сэндвич дымоход" в Москве

Claude: Уточню: Москва-город или Москва и область?

User: Москва город

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Москва"
        → Москва = 213

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Задача про позиции в выдаче, содержание страниц не нужно —
         отключает инфоконтексты: дешевле втрое]
        bash scripts/web_search_sync.sh --query "купить сэндвич дымоход" \
          --region-id 213 --no-snippets

        === Results for: купить сэндвич дымоход ===
        Region: 213 | Page: 0 | Snippets: false

          1. Сэндвич-дымоходы купить в Москве — Леруа Мерлен
             https://leroymerlin.ru/...
             Широкий ассортимент сэндвич-дымоходов...

          2. Дымоходы сэндвич — купить в интернет-магазине
             https://...
             ...

          Всего: 10, с выдержками: 0
          JSON: cache/results/7f3a91c2e5d8.json
          Raw:  cache/results/7f3a91c2e5d8.raw

User: Проверь выдачу по запросам из файла queries.txt в Казани

Claude: [Находит ID региона]
        bash scripts/search_region.sh --name "Казань"
        → Казань = 43

        [Проверяет конфигурацию авторизации без вывода секрета]

        [Батч по одному запросу; в stdout — строка на запрос,
         тексты и разбор лежат в файлах]
        bash scripts/web_search_sync.sh --file queries.txt --region-id 43

          запрос                                     результаты            пак
          дымоход сэндвич цена                        20 док., выдержек 18  cache/results/a1b2c3d4e5f6.md
          купить дымоход казань                       20 док., выдержек 15  cache/results/b2c3d4e5f6a1.md
          дымоход нержавейка                          20 док., выдержек 19  cache/results/c3d4e5f6a1b2.md

        === Batch complete: 3/3 queries processed ===