用途：调用 Yandex Cloud Search API v2 解析 Yandex 搜索结果，返回排名、标题、URL、短摘要与页面信息上下文（smart snippets）。信息上下文默认开启，一次查询即可得到足够作答的页面片段，无需再自行抓取页面。
主要能力：同步搜索脚本 web_search_sync.sh 支持单条或按文件批量查询，支持 --no-snippets 仅取位置与链接；异步批量脚本 web_search_async.sh 支持大量查询提交与轮询，可 --resume 断点续跑，但不返回信息上下文；regions_tree.sh 列出常用区域 ID，search_region.sh 按名称查区域 ID，iam_token_get.sh 生成/校验 IAM 令牌并缓存。
必要用法：需 Yandex Cloud 服务账号，角色 search-api.webSearch.user，支持 IAM JSON 密钥或服务账号 API 密钥（auth.mode: "api_key"，配置 YANDEX_AI_API_KEY）。搜索前须确定区域 ID。示例：bash scripts/web_search_sync.sh --query "..." --region-id 225；批量：bash scripts/web_search_sync.sh --file queries.txt --region-id 225。
结果与输出：保存于 cache/results/<hash>.md（含页面片段）、<hash>.json（解析结果）、<hash>.raw（原始响应）。脚本不将长文本打印到 stdout，避免沙箱输出缓冲溢出；应读取缓存包文件。
限制：信息上下文仅同步模式且仅 SEARCH_TYPE_RU 返回；文档数最多 20；异步模式无信息上下文。定价按请求计费，具体价格以官方文档为准。
适用场景：需要基于 Yandex 实际页面内容作答、核查排名或按区域批量搜索，且已具备 Yandex Cloud 服务账号的环境。