Hyperresearch: как заставить Claude Code проверять цитаты и вести исследовательский архив

Hyperresearch — открытый Python-пакет, который пытается это исправить. Он заставляет Claude Code работать как агент глубокого исследования: конвейер из 16 шагов, постоянный архив со всем прочитанным и набор проверок, которые не дают отчёту выйти, если его цитаты разваливаются. Репозиторий лежит по адресу https://github.com/jordan-gibbs/hyperresearch, а сам пакет можно поставить из PyPI. Ниже — как его запускать и какие две настройки решают, будет первый прогон полезным или разочарует.

Три привычки, которых он избегает

Основную работу делают три архитектурных решения, и каждое отвечает на сбой, знакомый вам по другим исследовательским агентам. Они же объясняют, за что вы платите временем ожидания.

Починка лучше перегенерации. Когда черновик отчёта готов, агентам, которые с ним работают, на уровне allowlist в Claude Code оставлены только права на чтение и правку. Патчер и финальный аудитор физически не могут написать новый черновик. Попросите обычную модель перегенерировать документ на 20 000 слов после критики, и вы дадите ей тысячи шансов незаметно изменить или выбросить установленный факт. Здесь замечание критика либо укладывается в маленькую точечную правку, либо поднимается как структурный сбой. Документ не может тихо перекроить сам себя.

Повтор — не подтверждение. Если один пресс-релиз перепечатали пятьдесят изданий, некалиброванный агент видит подавляющий консенсус. Чтобы с этим бороться, аудит независимости группирует почти одинаковые копии по сходству содержания, а затем делит вес на всю группу. Пять перепечаток одного релиза в итоге весят как один источник.

Исходный вопрос всегда на виду. Ваш точный промпт один раз записывается в файл query.md, и каждый следующий шаг и каждый порождённый субагент перечитывает его. Многоагентные конвейеры дрейфуют, и к девятому шагу тема может превратиться в более простую родственницу того, о чём вы спрашивали. Закрепить текст и перечитывать его — тупое решение, которое работает.

В долгосрочной перспективе больше всего, возможно, окупится архив. Каждая страница, PDF и рабочая заметка попадают в поисковое хранилище из markdown-файлов и SQLite внутри папки проекта. Следующий запуск в той же папке сначала просматривает то, что уже есть, и только потом что-то скачивает, так что исследование накапливается, а не исчезает.

Установка без разочарования

Установка — это две команды, запущенные в каталоге проекта, где должен жить архив:

cd your-project
pip install hyperresearch && hyperresearch install

После этого наберите /hyperresearch <your question> (ваш вопрос) в Claude Code. Поддерживается Python от 3.11 до 3.13. Если у вас 3.14, которая пока не поддерживается, сначала создайте окружение на 3.13 через pyenv install 3.13 или uv venv -p 3.13.

Следующий момент документация упоминает один раз, и большинство его пролистывает. Веб-провайдер по умолчанию — builtin, простой HTTP-запрос вообще без поиска. У него нет лишних зависимостей, но конвейер настраивали не под него. Если после запуска по умолчанию корпус источников кажется жидким, причина в этом.

Решение — дополнение crawl4ai:

pip install "hyperresearch[crawl4ai]"

Затем выберите его в .hyperresearch/config.toml:

[web]
provider = "crawl4ai"

Так загрузка переходит на headless-браузер с обходом защиты от ботов, а заодно появляются извлечение текста из PDF и браузерная полоса эскалации. Если есть ключи, поддерживаются Exa и Tavily. Parallel не требует аккаунта, но умеет только искать, а массовые загрузки откатываются к одному URL за раз, так что он лучше всего работает как дополнение.

Ещё один выбор при установке. Установка на проект не засоряет посторонние сессии Claude Code. Глобальная (hyperresearch install --global) делает команду доступной везде ценой примерно пятнадцати строк в системном напоминании каждой сессии. Начните с установки на проект.

Выберите уровень, прежде чем сжечь три часа

Каждый запуск попадает на один из трёх уровней. Его выбирает шаг 1, который классифицирует запрос, не спрашивая вас.

• light выполняет пять шагов из шестнадцати примерно за 30–40 минут и подходит для ограниченных фактических вопросов, обзоров и сравнений.
• full используется по умолчанию и запускает всё: состязательных критиков, проверку цитат и прочее. Рассчитывайте примерно на 1,5–2,5 часа.
• dissertation включается, только если об этом прямо просит промпт. Работа делится на 4–10 глав, опирается на 300–450 источников и даёт от 25 000 до 80 000 слов, а занимает примерно 4–8 часов.

Пропускайте full, когда хватило бы хорошего поиска и двадцати минут чтения. Классификатор разумный, но формулировка промпта его подталкивает, и просьба о «comprehensive analysis» («всестороннем анализе») может стоить двух часов, которые тратить было незачем.

Второй рычаг — регистр, и он выводится из глагола в промпте. «Teach me X» («научи меня X») даёт обучающее объяснение. «What does the field around X look like» («как выглядит область вокруг X») даёт карту без вердикта. Вариант по умолчанию, analyze, строит оценочную аргументацию, а advocate защищает один названный вами тезис. Назовите регистр прямо, и ваша инструкция победит догадку.

Работает это потому, что критики следуют регистру, а не воюют с ним. В режиме survey диалектический критик возражает против несправедливой подачи конкурирующих взглядов и не давит в сторону вердикта, а финальный аудитор не трогает ваши оговорки. В режиме advocate проверки становятся строже. Проверка цитат и финальный шлюз не прогибаются никогда, и это правильно: верификация не должна ослабевать оттого, что вам хотелось тона помягче.

Объём настраивается отдельно от тона, через профили, которые задают целевое число источников и бюджет глубины:

hyperresearch profile list           # what's available, what's active
hyperresearch profile use premier    # 100-130 sources, doubled depth budget
hyperresearch profile use full       # back to the 55-80 baseline

Перед долгим запуском ограничьте и расходы:

hyperresearch run init --budget 50

При превышении лимита запуск блокируется, а не раздувается. Лимит ограничивает оценочные расходы в пересчёте на API, а не буквальный счёт, так что используйте его в первые прогоны, пока не поймёте, сколько стоит запуск premier.

Настройка, которая меняет качество источников

Если по теме есть настоящая научная литература, запрашивайте научные базы раньше открытого веба. Веб-поиск возвращает людей, которые обсуждают работу, а научный поиск возвращает саму работу.

hpr scholar search "GLP-1 cardiovascular outcomes" -j
hpr scholar sources    # what's wired up, what each one covers

Сейчас один запрос охватывает семь источников. Библиографию и открытый доступ дают Crossref, OpenAlex, CORE и DOAB. Помимо статей, поиск идёт по зарегистрированным исследованиям в ClinicalTrials.gov, корпоративной отчётности в SEC EDGAR и экономическим рядам из FRED. Результаты объединяются по DOI, а если его нет — по нормализованным названиям. В README их восемь, потому что там указан и RePEc, хотя его API искать не умеет. Объединённый список помечает каждое попадание по типу, так что испытания, которые так и не стали статьями, отчётность SEC и данные ФРС не путаются с журнальными статьями.

Теперь сама настройка — настоящий контактный email:

export HYPERRESEARCH_CONTACT_EMAIL="you@example.com"

У этого одного значения два эффекта. Оно переводит вас в «вежливые» пулы OpenAlex и Crossref, где лимиты запросов гораздо мягче, чем для анонимных клиентов. И его требуют условия Unpaywall — первого сервиса, к которому обращается конвейер в поисках копий в открытом доступе.

Если email пустой, используется только Europe PMC, а он покрывает биомедицину и ничего за пределами своего открытого подмножества. Если email задан, при пейволе агент сначала идёт в Unpaywall, а за ним в очереди стоят Europe PMC и CORE: ищется легальная бесплатная копия, чей полный текст заменяет в заметке аннотацию. От этого зависит, будет ли ваш архив набит заглушками на 1 500 символов или настоящими статьями.

Укажите то же значение в разделе [scholar] конфига:

[scholar]
oa_recovery = true
contact_email = "you@example.com"
oa_min_full_text_chars = 6000
oa_prefer_published = true

Обратите внимание на oa_prefer_published, который тихо делает здесь важную работу. Когда опубликованной открытой копии нет, Unpaywall может вернуть принятую рукопись или отправленный препринт, и ни то ни другое не равно версии записи.

Читайте результат так, будто отвечаете за него

Когда срабатывает восстановление из открытого доступа, поле source: заметки по-прежнему показывает запрошенный вами URL, хотя текст мог прийти из другого места. Инструмент отмечает это в четырёх местах: баннер в начале заметки, поля frontmatter oa_url, oa_source, oa_version и oa_license, JSON-блок oa из hpr note show <id> --json, где есть body_is_not_from_source: true, и упоминание в самом выводе загрузки.

Перед тем как что-то цитировать, проверьте oa_version. Если там acceptedVersion или submittedVersion, сверьте цитату с опубликованной статьёй.

Есть случай посложнее. Источник, который вообще не удаётся прочитать, например из-за 403 или стены логина, проходит через тот же поиск, и вся заметка строится по копии из открытого доступа. Такие заметки помечаются oa_recovery_kind: rescued и nothing_from_source: true, а баннер признаёт, что исходный URL так и не открылся. Верьте ему: название, авторы и текст — всё взято из замены. Если вам лучше не иметь заметки вовсе, чем получить собранную по подмене, задайте oa_rescue_blocked = false.

Перед выпуском запускается батарея проверок. Процитированный фрагмент должен дословно встречаться в какой-нибудь заметке архива, так что выдуманная цитата — жёсткая остановка. Отозванный источник, процитированный без упоминания отзыва, — тоже жёсткая ошибка, причём проверка отзывов перепроверяет каждый процитированный DOI прямо в момент выпуска, а не в том виде, в каком он был при первой загрузке. Цифры без подтверждения помечаются.

hyperresearch run verify <tag> -j   # headings, length, citation density, cite-check resolution
hyperresearch run status -j         # step status, spend, escalation queue depth
hyperresearch run resume -j         # crashed runs pick up at the exact step

Последняя команда спасает жизнь: если запуск упал на шаге 12, он продолжится с шага 12.

Работа с архивом потом

Отчёт — это результат, а архив — это актив.

hyperresearch search "ion-trap gate fidelity" -j
hyperresearch search "quantum" --include-body -j
hyperresearch graph hubs -j          # most-connected notes
hyperresearch sources independence -j # syndication clusters
hyperresearch lint -j                # broken links, missing tags

Источник истины — markdown, а SQLite служит лишь кэшем, который можно пересобрать. Если база потеряна, hyperresearch sync восстановит индекс из файлов на диске. Держите папку в git и открывайте в любом редакторе. Ваше исследование остаётся читаемым и без инструмента, и эта переносимость значит больше любой отдельной функции.

Работает он и за пределами Claude Code. hyperresearch serve --open запускает локальный веб-интерфейс на порту 8080, а после pip install hyperresearch[mcp] команда hyperresearch mcp предоставляет тринадцать инструментов через stdio, так что Cursor или Claude Desktop могут обращаться к тому же архиву.

Ограничения и одно заявление, к которому стоит относиться осторожно

Заблокированные загрузки ставятся в очередь эскалации, а не теряются молча. Один раз запустите hyperresearch setup и войдите на свои сайты. Если установлено расширение Claude-in-Chrome, агент-загрузчик разбирает эту очередь через ваш настоящий Chrome с выполненными входами и проходит пейволы, за которые вы заплатили. CAPTCHA, 2FA и логины никогда не обрабатываются автоматически: вы получаете их все разом в одном сообщении.

Линт-шлюз ловит структурные сбои: отсутствующие каркасы, разорванные цепочки происхождения и неразобранные критические замечания. Фактическую точность он гарантировать не может, и README прямо об этом говорит. Выбор источников остаётся за агентом, а значит, направлять его по-прежнему вам.

Дальше — заявление о лидерборде. В репозитории сказано, что инструмент занимает первое место в категории RACE на DeepResearch-Bench, однако подпись под графиком честна: это прогноз по стратифицированному пилоту, замеренный своими силами и ожидающий независимой проверки. Публиковать такое разумно, а повторять как установленный факт — нет. Настоящий судья — ваши собственные запуски.

Учтите и скорость изменений. Первый релиз на PyPI датирован апрелем 2026 года, а в середине сентября 2026-го после семнадцати релизов вышла 0.11.1. Софт версии ниже 1.0, который меняется так быстро, к моменту чтения уже сдвинется, так что сверяйте любой упомянутый здесь флаг с README. Лицензия — MIT.

Первый запуск, который можно реально оценить

Не тестируйте его на незнакомой теме: вы не заметите ошибок. Выберите то, что знаете достаточно хорошо, чтобы ловить промахи, — с солидной литературой внизу и кучей пересказанных комментариев сверху. Такое сочетание вскрывает две слабости, которые по одному тексту отчёта не видны:

/hyperresearch Survey the evidence on whether remote work changes
software team productivity. Separate individual output from team-level
coordination costs, and distinguish measured studies from company
self-reports. Survey the landscape; don't argue for a position.

Формулировка здесь работает всерьёз. «Survey» («обзор») выбирает регистр, так что результат описывает область, не вынося вердикта. Два запрошенных разделения на шаге 1 превращаются в атомарные пункты чек-листа, и критик инструкций потом сверяет с ними черновик. Последнее предложение перекрывает догадку о регистре, чтобы она не зависела от одного глагола.

Для первой попытки используйте light и не оценивайте прозу. Откройте пять заметок в архиве и ответьте на четыре вопроса:

1. Были ли получены сами исследования или только статьи, которые их описывают?
2. В каких заметках полный текст, а в каких только аннотация на 1 500 символов? Для всего восстановленного посмотрите на oa_version и nothing_from_source.
3. Возьмите три утверждения из отчёта и убедитесь, что процитированная заметка действительно подтверждает каждое.
4. Выполните hyperresearch sources independence -j. Свернулись ли перепечатки в кластеры, или одинокий пресс-релиз по-прежнему считается пять раз?

Если ответы совпадают с тем, к чему вы пришли бы, сделав работу сами, более долгие запуски стоят вашего вечера. Этот тест подходит для любого исследовательского агента. Просто большинство из них не сохраняет заметки, по которым его можно провести.

Начните с репозитория: установка на проект, дополнение crawl4ai и ваш контактный email, а затем потратьте сорок минут на запуск light.