Perplexity Search

perplexity-search

Работа с Perplexity API на 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. Все остальные переменные опциональны. Подробности: 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. 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

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

Взаимоисключающие комбинации (--recency вместе с явными датами, смешанные allow/deny домены) отклоняются до похода в API — деньги не тратятся.

Кто исполняет запрос

Приоритет: флаг > .env > собственный дефолт скрипта.

• задан --preset или --model — берётся он;
• иначе, если в config/.env заданы PPLX_PRESET / PPLX_MODEL, — берутся они;
• иначе работает дефолт скрипта: ask.sh → medium, research.sh → high, fetch_url.sh → low.

Скрипт со своим дефолтом никогда не перебивает то, что вы указали в .env, — иначе research.sh тихо считал бы деньги по другой модели.

Кеш

cache/
├── index.tsv              # created_at, script, key, query, path — для grep
├── search/<key>.json      # сырой ответ
├── search/<key>.tsv       # таблица результатов
├── search/<key>.txt       # сниппеты целиком
├── ask/<key>.{json,md}    # ответ + источники
├── research/<key>.{json,md,id}
└── fetch/<key>.{json,md}

Никогда не читай .json целиком — там весь ответ API. Работай через cache_grep.sh, а точечно — Read по file:line из его вывода.

Свежесть

Кеш нужен, чтобы не платить дважды за один и тот же вопрос внутри сессии, а не чтобы законсервировать ответ. Поэтому:

• переиспользуется только запись моложе TTL; шапка всегда показывает возраст (=== Perplexity Search (cache, 12m old): ... ===);
• --recency — это сигнал «вопрос про свежее», и он сокращает окно переиспользования: hour → максимум 5 минут, day → максимум час, week → максимум сутки. Явный --cache-ttl сильнее — он не урезается;
• если фактура могла измениться (релиз, курс, новость, цены) — --no-cache;
• research.sh держит отчёты сутки, потому что каждый прогон стоит минуты и доллары. Для быстро меняющейся темы ставь --no-cache или --recency.

Артефакты в cache/ живут вечно — истекает только право отдать их вместо нового запроса. Прошлые прогоны всегда доступны через find_latest.sh и cache_grep.sh.

Ограничения

• Search API: максимум 5 запросов в массиве, 20 результатов, 20 доменов в фильтре, 50 query units/s. Мультизапрос тарифицируется как один запрос, но лимит расходует по единице на строку.
• search_domain_filter — allowlist или denylist, смешивать нельзя.
• --recency и явные даты одновременно не работают.
• Модели anthropic/* требуют max_output_tokens — скрипты подставляют 8192.
• 429 не тарифицируется; скрипты уважают Retry-After и делают до PPLX_MAX_RETRIES попыток.
• Sonar Chat Completions (/chat/completions) считается legacy — скилл ходит в Agent API (/v1/agent).

Детали API, схемы ответов и рецепты: references/API_REFERENCE.md.

Тесты

sh scripts/tests/run.sh

Оффлайн, без сети и ключа: разбор .env, сборка тел запросов, рендер ответов из фикстур, CLI-контракт. Тест HTTP-слоя поднимает mock на loopback и сам себя пропускает там, где песочница не даёт открыть сокет.