portal/docs/superpowers/specs/2026-06-14-perplexity-pack-research-tooling-design.md

Дизайн: интеграция «Perplexity Pack» (off-phase research-tooling)

Дата: 2026-06-14 Тип: off-phase tooling integration (research-канал MCP) Статус: проектируется

Цель

Завести в тулчейн Лидерры новый off-phase слой research-tooling — три MCP-сервера breadth-first веб-разведки (perplexity, exa, firecrawl), сейчас присутствующие только в ветке worktree-perplexity-pack (main не затронут, в нормативке не формализованы). Назначение слоя — разведка широты на крупных/абстрактных задачах: актуальные практики, регуляторика, фич-разведка конкурентов, deep-research с цитатами. Интеграция доводится по обкатанному паттерну off-phase (как A8 infosec, C1 marketing): провенанс-вет → перенос конфигурации в main → формализация в нормативке → обновление реестра узлов и маршрутизации тулчейна.

[
  {"id":"vc1","kind":"EXTRACTED","ref":".mcp.json","anchor":"\"$schema\": \"https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.json\""},
  {"id":"vc2","kind":"EXTRACTED","ref":"docs/routing-off-phase.md","anchor":"<!-- auto:routing-table:begin -->"},
  {"id":"vc3","kind":"EXTRACTED","ref":"docs/security/infosec-vet.md","anchor":"Провенанс-вет внешних инструментов A8 infosec-tooling"},
  {"id":"vc4","kind":"EXTRACTED","ref":"tools/cost-pricing.mjs","anchor":"export const PRICING = Object.freeze("}
]

Состав пака

Контракт. Слой состоит из трёх MCP-серверов, каждый — отдельный узел реестра:

• perplexity (@perplexity-ai/mcp-server) — ранжированный веб-ответ + sonar: perplexity_search (web search ranked) / perplexity_ask (sonar-pro, real-time) / perplexity_research (sonar-deep-research, цитаты) / perplexity_reason (sonar-reasoning-pro). Назначение: получить ответ-с-источниками, а не сырой список.
• exa (exa-mcp-server) — нейро/семантический поиск: web_search_exa (находит концептуально близкое, что keyword-поиск пропускает) / web_fetch_exa (страница по URL). Назначение: обнаружение источников по смыслу.
• firecrawl (firecrawl-mcp) — глубокое чтение и обход: firecrawl_scrape / batch_scrape / map / search / crawl / extract + firecrawl_agent (автономный web-research) + firecrawl_agent_status. Назначение: прочитать страницу целиком, обойти сайт, извлечь структурированное.

Конвенция разделения (anti-overlap). Хотя все три умеют «веб-поиск», их роли не пересекаются по слою: perplexity — ранжированный ответ; exa — семантическое обнаружение; firecrawl — глубокое чтение/обход. Граница закрепляется в ADR ({#D6}).

Крайний случай. Состав финализируется ПОСЛЕ провенанс-вета ({#D2}): любой сервер с неприемлемым провенансом исключается из пака, остальные интегрируются как есть.

Провенанс-вет

Контракт. Перед формализацией каждого из трёх пакетов выполняется обязательный провенанс-вет по методологии существующего docs/security/infosec-vet.md:

1. README + ключевые исходники через GitHub API (gh api) и WebFetch — факты, не память.
2. Поля на каждый пакет: владелец/организация, лицензия, звёзды, активность коммитов, дата последнего релиза, что инструмент исполняет (сетевые вызовы, телеметрия, аутентификация), куда уходит трафик.
3. Вердикт: ПРИНЯТ / ОТКЛОНЁН с зафиксированной причиной.

Артефакты. Новый docs/security/research-vet.md (вет-док, единственный авторитетный источник «какой репозиторий/версию ставить») + docs/research/README.md (дом раздела, как docs/ml/ и docs/marketing/).

Крайний случай. Платные API (sonar-*, exa, firecrawl): ключи PERPLEXITY_API_KEY / EXA_API_KEY / FIRECRAWL_API_KEY живут ТОЛЬКО в пользовательском окружении и никогда не попадают в репозиторий (правило секретов проекта; gitleaks).

Критерий. Вет-док завершён со статусом ЗАВЕРШЁН и таблицей вердиктов на все три пакета; пакеты с вердиктом ОТКЛОНЁН не попадают в перенос ({#D3}).

Перенос конфигурации

Контракт. Перенос аддитивный: в .mcp.json (main) добавляются ровно три блока mcpServers (perplexity, exa, firecrawl) — по образцу уже присутствующих блоков sentry/openapi (поля command/args/env/comment). Существующие блоки не трогаются.

Конвенция. Каждый блок несёт env с ключом через ${VAR}-подстановку (ключ — из пользовательского окружения, не из файла) и comment с назначением, источником пакета, статусом и пином.

Постура активации. Active: блоки в main, ключи уже в пользовательском окружении; при отсутствии ключа сервер обязан падать gracefully (как sentry), не ломая сессию.

Крайний случай / риск. Bulk-load большого числа MCP-инструментов исторически давал API-ошибку и ронял субагентов; +3 сервера увеличивают суммарное число инструментов. Митигация: механизм deferred-tools (загрузка схем по запросу) + явная пометка риска в comment и в дом-README, чтобы при массовом субагент-прогоне учитывать.

Критерий. В main .mcp.json присутствуют три валидных блока; JSON валиден по объявленной $schema.

Реестр инструментов

Контракт. В docs/Tooling_v8_3.md Прил. Н заводится новая (20-я) off-phase подкатегория research-tooling с тремя узлами: #87 perplexity, #88 exa, #89 firecrawl. Каждый узел получает 9-атрибутный блок по шаблону §0.1 (как у существующих off-phase узлов).

Конвенция счётчиков. §0 «КАНОН СЧЁТЧИКОВ» — единственный источник числовых счётчиков; счётчик off-phase узлов поднимается 86→89. CLAUDE.md числа не дублирует, а ссылается на этот канон.

Критерий. Три §4.x-блока добавлены; §0-счётчик согласован; cross-ref-версии Прил. Н подняты согласованно с остальной нормативкой ({#D5}).

Нормативная синхронизация

Контракт. Через канал claude-md-management синхронизируются четыре нормативных документа (атомарным version-bump-набором, как требует cross-ref-checker):

• CLAUDE.md — §3.3 +3 строки оперативной карты, §0 cross-refs (Pravila/PSR/Tooling), §6 +абзац интеграции, §9 +запись, версия шапки.
• Pravila_raboty_Claude_v1_1.md — §13.2 +абзац «Off-phase research-tooling», версия.
• Plugin_stack_rules_v1.md — R10.1 Блок 3 (MCP-серверы) +3 строки, R15.6 +research-tooling, версия.
• Tooling Прил. Н — см. {#D4}.

Конвенция. Все четыре файла несут согласованные cross-ref-строки друг на друга с поднятыми версиями; §0/footer-счётчики берутся из канона Tooling Прил. Н §0.

Критерий. cross-ref-checker и l1-watcher не показывают дрейфа после правок.

Границы (ADR-019)

Контракт. Новый ADR (следующий свободный номер; в плане подтверждается фактически) закрепляет границы research-tooling против смежных узлов, чтобы не было дублей:

• vs context7 (#60) — context7 для документации библиотек/SDK; research-tooling для открытого веба, практик, регуляторики, конкурентов.
• vs openapi (#47) — openapi для нашего REST API; research-tooling для внешних источников.
• vs Boost (#10) — Boost для Laravel-экосистемы; research-tooling для веба.
• vs Sentry (#34) / Redis (#35) — runtime-факты прод-системы; research-tooling — внешние знания.
• vs graphify (#86) — graphify по внутреннему графу проекта; research-tooling — наружу.
• vs GitHub MCP (#3) — GitHub для репо-операций; research-tooling — открытый веб.

Внутренние границы. perplexity (ранжированный ответ) / exa (семантическое обнаружение) / firecrawl (глубокое чтение+обход) — слои из {#D1}.

Конвенция. ADR в формате adr-kit (Status / Context / Decision / Consequences / Enforcement), проходит adr-judge (lefthook job 9) без --llm.

Критерий. ADR принят, adr-judge зелёный.

Маршрутизация и карта

Контракт. «Мозг» подхватывает три новых узла через единый источник — docs/registry/nodes.yaml:

• В nodes.yaml добавляются три карточки узлов (#87/#88/#89) с subcategory: research-tooling и triggers.classification: "research".
• Из nodes.yaml авто-регенерируются: routing-таблица в docs/routing-off-phase.md (блок между auto:routing-table:begin/end) и карта классификаций (registry-to-classification-map.mjs).
• В docs/routing-off-phase.md добавляется каноническая связка L17 research chain: brainstorming → perplexity (ask/research) → exa (discovery) → firecrawl (deep-read).
• docs/automation-graph.html — три новых узла (NODE_META baseline + NODE_SECTION).
• tools/registry-load.test.mjs — счётчики фикстур поднимаются под новое число узлов.

Конвенция. Карточки узлов следуют форме существующих off-phase узлов реестра; авто-генерируемые блоки правятся только генератором, не вручную.

Крайний случай. Новая классификация research не должна перехватывать задачи, покрытые analysis/knowledge_graph_query/planning; разграничение — через ADR ({#D6}).

Критерий. Регенерированные routing-таблица и карта классификаций содержат research-узлы; registry-load.test.mjs зелёный.

Критерий приёмки

Контракт. Интеграция считается доделанной, когда:

1. Провенанс-вет завершён, состав пака финализирован ({#D2}).
2. Три блока в main .mcp.json, JSON валиден ({#D3}).
3. Реестр + нормативка синхронизированы без дрейфа cross-ref ({#D4}, {#D5}).
4. ADR принят, adr-judge зелёный ({#D6}).
5. nodes.yaml + регенерация + карта обновлены, registry-load.test.mjs зелёный ({#D7}).
6. Регрессия инструментов зелёная: одиночная команда npx vitest run --root app --config vitest.config.tools.mjs (база 3928 passed + 2 skip, не ниже после правок фикстур).
7. Live-smoke трёх серверов ПОСЛЕ переноса в main и перезапуска: по одному вызову на сервер (perplexity_ask / web_search_exa / firecrawl_scrape) возвращает осмысленный ответ — подтверждает живость и ключи.

Конвенция. Доказательства — фактический вывод команд, не утверждения.

Конвенция заголовков и версий

Контракт. Версии и даты ведутся единообразно:

• Дата во всех новых/правленых заголовках — 2026-06-14.
• Version-bump четырёх нормативных файлов — атомарным набором с согласованными cross-ref-строками (см. {#D5}).
• §9 CLAUDE.md и changelog получают по записи с указанием: app-фича/нет, затронуты ли §0 cross-refs, через какой канал внесено.
• Новые узлы нумеруются строго после последнего существующего (#86) → #87/#88/#89.

Критерий. Заголовки и счётчики согласованы; нет «TBD»/«TODO»/полупустых разделов.