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

**Дата:** 2026-06-14
**Тип:** off-phase tooling integration (research-канал MCP)
**Статус:** проектируется
**Примечание:** повтор печати после фикса таймаута тяжёлых LLM-вызовов (судья 30с→90с); содержание идентично v2, раздел D7 нейтрализован.

## Цель

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

```verified-context-json
[
  {"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("}
]
```

## Состав пака {#D1}

**Контракт.** Слой состоит из трёх 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}): любой сервер
с неприемлемым провенансом исключается из пака, остальные интегрируются как есть.

## Провенанс-вет {#D2}

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

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

**Артефакты.** Новый `docs/research/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}).

## Перенос конфигурации {#D3}

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

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

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

**Безопасность правки.** Перед правкой `.mcp.json` снимается бэкап; после правки JSON
валидируется; при невалидном JSON — авто-откат из бэкапа (необратимого повреждения
прод-конфига не происходит). Правка аддитивная, существующие серверы не трогаются.

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

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

## Реестр инструментов {#D4}

**Контракт.** В `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}).

## Нормативная синхронизация {#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) {#D6}

**Контракт.** Новый 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` зелёный.

## Реестр узлов и таблицы соответствия {#D7}

**Контракт.** Три новых узла подхватываются из единого источника —
`docs/registry/nodes.yaml`:

- В `nodes.yaml` добавляются **три записи узлов** (#87/#88/#89) с
  `subcategory: research-tooling` и `triggers.classification: "research"`.
- Из `nodes.yaml` авто-регенерируются производные: таблица соответствия «задача →
  инструмент» в `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}).

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

## Критерий приёмки {#D8}

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

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`) возвращает
   осмысленный ответ — подтверждает живость и ключи.

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

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

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

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

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