Hyperresearch 是一个将 Claude Code 转化为深度研究代理的框架，它通过 16 步层级自适应流程，生成带有完整来源溯源的对抗性审查报告，并将所有研究资料存入持久的、可搜索的知识库中 。本教程将指导你完成其完整部署流程。

📦 第一步：环境准备与安装

Hyperresearch 依赖 Python 环境和 Claude Code。请确保系统满足以下要求，并拥有 Anthropic API 密钥以调用模型。

1.1 基础环境要求

  • Python 版本：3.11、3.12 或 3.13（不支持 3.14 及更高版本）。
  • 包管理工具：推荐 pip 或 uv。
  • 核心依赖：Claude Code（必须预先安装并配置好 API 密钥）。

1.2 安装 Hyperresearch

  1. 创建并进入项目目录（每个研究项目建议独立）：

    1
    mkdir my-research-project && cd my-research-project

  2. 安装 Python 包：

    1
    pip install hyperresearch

    • 可选功能安装：如需使用 MCP 服务器、Exa/Tavily 搜索等扩展功能，可安装完整依赖：

      1
      pip install hyperresearch[all]

  3. 在项目中安装 Claude Code 技能：

    1
    hyperresearch install

    • 全局安装（可选）：如果希望在任何目录下都能使用 /hyperresearch，可以执行：

      1
      hyperresearch install --global

      这会将该命令添加到所有 Claude Code 会话中，但可能会增加一些系统提示词的开销 。

⚙️ 第二步：核心配置与模型选择

Hyperresearch 通过配置文件管理模型、运行参数和研究行为。

2.1 配置文件位置

  • 项目级配置：.hyperresearch/config.toml（首次运行后自动生成）。
  • 用户级配置：~/.hyperresearch/config.toml（全局生效）。

2.2 配置模型映射

Hyperresearch 使用多个专门的子代理（Subagent），每个代理默认使用特定模型（如 sonnet 或 opus）。你可以在配置文件中覆盖这些默认值，以平衡性能与成本。

示例配置 (~/.hyperresearch/config.toml)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 为 'full' 运行级别定义模型映射
[profile.full]
# 将资源获取代理改为更经济的模型
models = { fetcher = "haiku", "source-analyst" = "sonnet" }

# 为 'light' 级别设置不同配置
[profile.light]
models = { fetcher = "haiku", "draft-orchestrator" = "sonnet" }

# 学术开放获取恢复配置
[scholar]
contact_email = "你的邮箱@example.com"  # 启用 Unpaywall 所必需
oa_recovery = true
oa_min_full_text_chars = 6000

重要：contact_email 是启用 Unpaywall 服务所必需的，其服务条款要求提供联系邮箱 。

🚀 第三步：启动研究流程

部署完成后，即可在 Claude Code 中启动深度研究任务。

3.1 运行标准研究

在 Claude Code 会话中，使用以下命令触发研究流程：

1
/hyperresearch <你的研究问题或主题>

例如：

1
/hyperresearch 请调研2024-2026年间基于扩散模型的视频生成技术进展，重点关注效率优化方案

3.2 理解运行层级与时间

Hyperresearch 会根据你的提示词自动分类运行层级（Tier），你也可以通过描述来引导 ：

  • light 层级：适用于有明确答案的事实查询、简单对比。耗时约 30-40 分钟。
  • full 层级（默认）：用于深度论证分析，包含完整的 16 步对抗性审查流程。耗时约 1.5 - 2.5 小时。

3.3 控制研究规模（Gear）

你可以通过切换“档位”来控制研究的规模和深度：

1
2
3
hyperresearch profile list          # 查看所有可用档位
hyperresearch profile use premier   # 切换到更大规模（约100-130个来源）
hyperresearch profile use full      # 切换回标准规模（约55-80个来源）

📚 第四步：管理研究知识库（Vault）

Hyperresearch 的核心优势是它会将所有阅读过的资料持久化到知识库中，供后续研究复用。

4.1 知识库位置与结构

  • 所有笔记以 Markdown 格式（包含 YAML 元数据）存储在 research/notes/ 目录下。
  • SQLite 索引（research/vault.db）用于加速搜索，可随时通过 hyperresearch sync 从 Markdown 文件重建。

4.2 搜索与查看笔记

1
2
3
hyperresearch search "扩散模型 效率优化"     # 全文搜索
hyperresearch note show <笔记ID>            # 查看特定笔记
hyperresearch graph hubs                    # 查看最常被引用的核心笔记

4.3 外部访问：MCP 服务器与 Web UI

  • MCP 服务器：允许其他 MCP 客户端（如 Claude Desktop）访问知识库：

    1
    2
    pip install hyperresearch[mcp]
    hyperresearch mcp   # 启动 stdio 服务器

  • 本地 Web UI：启动一个简单的 Web 界面进行浏览：

    1
    hyperresearch serve --open   # 默认在 http://localhost:8080 打开

🩺 第五步：高级特性与运维

5.1 会话管理与恢复

  • 查看运行状态：

    1
    hyperresearch run status -j   # 显示当前运行步骤、花费和队列深度

  • 恢复中断的运行：如果研究过程因故中断，可以无缝恢复：

    1
    hyperresearch run resume -j   # 从中断的精确步骤继续

5.2 通过代理访问受限内容

如果需要抓取 LinkedIn、Twitter 等需要登录的网站，可以使用浏览器认证模式：

1
hyperresearch setup   # 会打开一个浏览器窗口，供你手动登录目标网站

之后，被拦截的抓取任务会自动排队，并通过 Claude-in-Chrome 扩展驱动你的真实浏览器进行处理 。

5.3 健康检查与故障排查

1
2
3
hyperresearch lint -j           # 检查知识库健康状态（如损坏的链接、缺失标签）
hyperresearch sources score -j  # 更新来源的质量评分（基于引用、权威性等）
hyperresearch run verify <运行标签> -j  # 在报告生成前执行最终验证（引用完整性、数据一致性等）

⚠️ 重要声明

  • 模型成本：Hyperresearch 运行时会调用 Anthropic 模型 API，产生相应费用。full 层级或 premier 档位的运行可能消耗大量 token，请留意你的 API 使用量。
  • 内容责任：该工具用于辅助研究，最终报告的内容准确性和使用合规性需由你负责。
  • 开源许可：本项目采用 MIT 许可证 。

至此，你已经完成了 Hyperresearch 的完整部署。通过它将 Claude Code 变成一个拥有持久记忆和严谨流程的深度研究助手。