/perplexity-search

name: perplexity-search
description: |
  Поиск и ресёрч через Perplexity API: сырая выдача (Search API),
  ответ с цитатами (Agent API), deep research в фоне, чтение страниц.
  Cache-first: крупные результаты уходят в cache/ и читаются грепом.
  Triggers: perplexity, перплексити, perplexity search, sonar api,
  найди в интернете, поищи в сети, web search, свежая информация,
  deep research, глубокое исследование, ответ с источниками,
  прочитай страницу, fetch url, что пишут про.

perplexity-search

Работа с [Perplexity API](https://docs.perplexity.ai) на POSIX-shell. Четыре режима: сырая выдача, ответ с цитатами, длинный ресёрч в фоне, извлечение страниц.

Перед запуском

Директория установленного плагина обычно read-only, а скрипты пишут в `cache/`. Создай рабочую копию и работай из неё:

sh scripts/prepare_runtime.sh
cd /home/claude/perplexity-search

`prepare_runtime.sh` копирует скилл и нормализует `config/.env` (закавычивает значения с пробелами). Содержимое `.env` не выводи в ответ — при ошибках настройки называй только имена переменных.

Config

Нужен `PERPLEXITY_API_KEY` в `config/.env`:

cp config/.env.example config/.env

Ключ — на [perplexity.ai/account/api](https://www.perplexity.ai/account/api). Все остальные переменные опциональны. Подробности: [config/README.md](config/README.md).

Philosophy

1. **Кеш ограничен по возрасту, а не только по ключу** — ключ (тело запроса) решает, *какая* запись подходит; TTL решает, можно ли её ещё отдавать. По умолчанию 900 c, для `research.sh` — сутки. Ничего старше не переиспользуется. Возраст всегда печатается в шапке (`cache, 12m old`), чтобы несвежий ответ было видно. `--no-cache` — живой запрос, `--cache-ttl` — своя граница. 2. **Context window hygiene** — stdout ограничен `PPLX_PRINT_LIMIT` (30 строк). Полные сниппеты, ответы и сырой JSON лежат в `cache/` и читаются через `cache_grep.sh` или Read по нужному смещению. 3. **Правильный инструмент под задачу** — сначала дешёвый `search.sh` ($5/1000 запросов), синтез моделью только когда он реально нужен. 4. **Проверяемые ответы** — у каждого ответа `ask.sh`/`research.sh` в отчёте есть список источников с датами и сниппетами.

Выбор скрипта

| Нужно | Скрипт | Цена | |---|---|---| | ссылки и цитаты со страниц, дальше думаю сам | `search.sh` | $5 / 1000 запросов | | готовый ответ с источниками | `ask.sh` | токены модели + $0.0025 за поиск | | многошаговое исследование, отчёт на страницы | `research.sh` | минуты и заметные деньги | | содержимое конкретных URL | `fetch_url.sh` | токены + $0.00025 за URL | | «я это уже искал?» | `find_latest.sh`, `cache_grep.sh` | бесплатно |

По умолчанию бери `search.sh`. `research.sh` запускай только когда пользователь явно просит глубокое исследование.

Workflow

Сырая выдача

# один запрос
sh scripts/search.sh --query "изменения в NDS 2026" --max-results 10

# до 5 углов темы в одном оплаченном запросе
sh scripts/search.sh \
  --query "AI regulation EU 2026" \
  --query "AI Act enforcement timeline" \
  --query "AI Act penalties companies"

# только свежее и только из нужных доменов
sh scripts/search.sh --query "postgres 19 release" --recency week \
  --domains "postgresql.org,news.ycombinator.com"

# без форумов
sh scripts/search.sh --query "лучший ноутбук для разработки" --domains "-reddit.com,-quora.com"

stdout — таблица `n / date / domain / title / url`. Сниппеты целиком лежат в `cache/search/<key>.txt`; читай их грепом, а не целиком.

Ответ с цитатами

sh scripts/ask.sh --query "что изменилось в Claude Code за последний месяц"

# дешевле и быстрее
sh scripts/ask.sh --query "курс ЦБ на сегодня" --preset fast

# ответ строго по схеме
sh scripts/ask.sh --query "топ-5 CRM для малого бизнеса" --schema schema.json

Полный отчёт (ответ + источники + сниппеты) — в `cache/ask/<key>.md`.

Глубокий ресёрч

# фоновый запуск с ожиданием
sh scripts/research.sh --query "рынок EV-зарядок в РФ: игроки, объёмы, барьеры" \
  --preset high --timeout 1800

# отправить и не ждать
sh scripts/research.sh --query "..." --no-wait
sh scripts/research.sh --resume resp_abc123

Run продолжается на стороне Perplexity даже если скрипт перестал ждать — `--resume` подхватывает его по id.

Повторный одинаковый запрос не запускает второй прогон: скрипт находит id уже отправленного (`cache/research/<key>.id`), проверяет его статус и подхватывает, если тот ещё выполняется или уже готов. Новый прогон стартует только если предыдущий завершился неудачей или вы явно попросили `--no-cache`.

Чтение страниц

sh scripts/fetch_url.sh --url "https://example.com/pricing"
sh scripts/fetch_url.sh --url "https://a.com/post" --url "https://b.com/post" \
  --query "сравни выводы двух статей"

Работа с кешем

# что я уже спрашивал
sh scripts/find_latest.sh --script ask --match "claude"

# поиск по накопленным результатам вместо нового запроса
sh scripts/cache_grep.sh "rate limit" --type search --context 2
sh scripts/cache_grep.sh "GDPR" --files

Scripts

sh scripts/<script>.sh [params]     # у каждого есть --help

| Script | Endpoint | Описание | |---|---|---| | `search.sh` | `POST /search` | ранжированная выдача со сниппетами | | `ask.sh` | `POST /v1/agent` | синтезированный ответ с источниками | | `research.sh` | `POST /v1/agent` + polling | длинный ресёрч в фоне, `--resume` | | `fetch_url.sh` | `POST /v1/agent` | содержимое конкретных URL (`fetch_url`) | | `find_latest.sh` | — | прошлые запуски из `cache/index.tsv` | | `cache_grep.sh` | — | греп по накопленным результатам | | `prepare_runtime.sh` | — | рабочая копия скилла в writable-директории |

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

| Param | Где | Default | Значения | |---|---|---|---| | `--query`, `-q` | все | — | запрос; в `search.sh` повторяется до 5 раз | | `--recency` | поиск | — | `hour`, `day`, `week`, `month`, `year` | | `--after` / `--before` | поиск | — | `YYYY-MM-DD` или `MM/DD/YYYY` | |