agentic-research

agentic-research-engine-oss

在笔记本电脑上运行的最佳 $0 研究 Agent。 全流程开源， 可复现，并保护隐私。默认不依赖云服务；不收集遥测数据； 每次大模型调用、每个来源和每项验证决策都清晰可见。

---

目录

• 概览
• 为什么选择它，而不是……
• 快速开始 — Mac 本地运行
• 快速开始 — 无需安装（Google Colab）
• 三种使用方式
• 包含内容
• 领域预设
• 使用你自己的文档
• MCP + Claude 插件
• 插件 / 技能加载器
• 架构概览
• 仓库结构
• 配置（环境变量）
• 测试
• 故障排除
• 如实说明局限
• 状态 + 路线图
• 贡献
• 许可证

---

概览

本地优先的研究 Agent，可验证自己的答案。 使用 Gemma 3 4B + Ollama 运行（磁盘占用 3.3 GB），每次查询费用为 $0； 只需设置一个环境变量，即可切换到任何兼容 OpenAI 的端点。

pip install agentic-research-engine
agentic-research ask "what is Anthropic's contextual retrieval?" --domain papers

接口	CLI · Textual TUI · FastAPI Web GUI · MCP 服务（Claude Desktop / Cursor / Continue）
流水线	8 节点 LangGraph（classify → plan → search → retrieve → fetch → compress → synthesize → verify）；每个节点都可通过环境变量开关进行消融
检索	SearXNG 元搜索 + trafilatura 抓取 + 混合 BM25 / dense / RRF；可选择启用 bge-reranker-v2-m3 交叉编码器
推理	HyDE 查询扩展 · FLARE 主动检索 · Chain-of-Verification（Dhuliawala 等人，2023）· ThinkPRM 步骤评判器
领域	6 个预设（general · medical · papers · financial · stock_trading · personal_docs）——只需 10 行 YAML 即可编写自己的预设
插件	从 GitHub 或本地路径加载 Claude 插件或 agentskills.io 技能
记忆	可选的本地 SQLite 轨迹日志，支持语义检索；可随时清除；不收集遥测数据
提供方	OpenAI · Groq · vLLM · SGLang · Together · Ollama——通过 OPENAI_BASE_URL 使用任何兼容 OpenAI 的端点
质量	137 项模拟测试，不访问网络 · 真实基准测试结果见 RESULTS.md · 全流程采用 MIT 许可证

---

为什么选择它，而不是……

你目前使用的工具	我们提供的功能
Perplexity / ChatGPT Deep Research / Kagi Assistant	同样的推理加引用流程，本地运行且免费，数据绝不会离开你的设备
Perplexica self-hosted	Perplexica 的用户体验，加上 CoVe 验证器、FLARE 主动检索、自适应计算路由器，以及 Claude 插件打包方案
Khoj	更强的研究专用推理能力（我们并不专注于个人知识），六种领域预设，以及供其他 Agent 调用的 MCP 服务
gpt-researcher	更新的流水线架构、更好的小模型处理能力、可观察的执行轨迹和插件生态
MiroThinker-H1 / OpenResearcher-30B	它们在 BrowseComp 上更强；我们能在没有 GPU 的笔记本电脑上运行，成本为 $0
自己编写 LangGraph 研究 Agent	节省 2-3 个月；复用我们的 8 节点流水线 + 30 多个经过测试的环境门控 + 137 项测试

坦诚地说： 在复杂的多跳推理基准测试中，Gemma 3 4B 的表现比 30 B+ 开源模型低 15–25%。我们不声称能胜过 GPT-5.4 Pro。我们声称自己是 2026 年 4 月最出色的**$0、可在笔记本电脑上运行、完全开源**的研究 Agent。

---

快速开始 — Mac 本地运行

选项 A — PyPI（最快）

# 1) Local inference (Ollama + Gemma 3 4B + embedding model — 3.6 GB combined)
brew install ollama
ollama pull gemma3:4b nomic-embed-text

# 2) Self-hosted meta-search (Docker; optional but recommended)
docker run -d --name searxng -p 8888:8080 searxng/searxng

# 3) The engine itself
pip install agentic-research-engine

# 4) Go
export OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_API_KEY=ollama
export MODEL_SYNTHESIZER=gemma3:4b EMBED_MODEL=nomic-embed-text
export SEARXNG_URL=http://localhost:8888
agentic-research ask "what is Anthropic's contextual retrieval?" --domain papers

选项 B — 从源代码安装

# 1) Same local-inference prereqs as Option A (ollama pull + docker run)

# 2) Clone + install (gives you the CLI, TUI, Web GUI, MCP server, benchmarks, tutorials)
git clone https://github.com/TheAiSingularity/agentic-research-engine-oss
cd agentic-research-engine-oss
(cd scripts/searxng && docker compose up -d)
cd engine && make install
make smoke    # end-to-end run on the canonical "what is contextual retrieval" question

在 M 系列 Mac 上的预计实际耗时：事实型问题约 45 秒，多跳综合约 90 秒。每次查询成本为零。

更诚实的高准确性 — 云模型模式

Gemma 3 4B 在结构方面（规划、路由、验证、压缩）表现出人意料地好，但当 SearXNG 没有找到包含正确词元的来源时，它会编造具体事实型信息。2026-04-21 的 SimpleQA-mini 实时运行（参见 engine/benchmarks/RESULTS.md）显示，gemma3:4b 对 “Anthropic 发布 Contextual Retrieval 的年份” 给出了“2023”（标准答案：2024），对 “用于重排的交叉编码器” 给出了“LayoutLMv3”（标准答案：bge-reranker-v2-m3）。

你可能需要的解决方案不是更聪明的综合器，而是一个更诚实的综合器。针对相同检索结果进行的 5 道题正面对比显示，当缺少证据时，gpt-5-nano + gpt-5-mini 会拒绝编造（“提供的证据无法回答这个问题”），而 gemma3:4b 会自信地猜测。单项主张的忠实度从 82.9 % → 100 %。通过率几乎没有变化（1/5 对 0/5），因为真正的瓶颈在检索——如果 SearXNG 没有返回包含标准答案词元的来源，任何模型都无法给出答案。

将整个技术栈切换到云端接口：

# drop the Ollama base URL (fall back to OpenAI cloud)
unset OPENAI_BASE_URL
export OPENAI_API_KEY=sk-...
# defaults are already cloud-sized: gpt-5-nano for plan/verify, gpt-5-mini for synth.
# Explicit override if you want to pin them:
export MODEL_PLANNER=gpt-5-nano
export MODEL_SYNTHESIZER=gpt-5-mini        # or gpt-5, claude-sonnet-4-5, etc.
agentic-research ask "…" --domain papers

成本主要来自综合器词元（每次查询约 5–15 k）。完整云端模式使用 gpt-5-nano + gpt-5-mini 时，每次研究查询的费用约为 $0.02–0.05，速度比 Gemma 本地运行慢约 2-3 倍（实测：5 道题子集的平均实际耗时为 127 秒，而非 52 秒）。它兼容任何 OpenAI 兼容接口——Groq、Together、Mistral、DeepSeek、本地 vLLM——因此你可以选择快速廉价的模型（Groq 上的 llama-3.3-70b 约为 $0.003/次查询），也可以选择前沿模型。按节点配置基础 URL 路由（在同一次查询中，本地运行 gemma3:4b 来规划/验证，并在云端运行 gpt-5-mini 来综合）已列入 0.2 版本计划；目前流水线使用一个全局 OPENAI_BASE_URL。

更能显著提升准确性的因素是检索。 将 LOCAL_CORPUS_PATH 指向包含答案的已索引语料库，任何一个模型都能答对。

---

快速入门 — 无需安装（Google Colab）

tutorials/ 中有五个可运行的 Notebook：

1. 01 — Engine API 快速入门（模拟运行，无需密钥） — 了解管线的工作方式，无需运行推理。
2. 02 — Groq 云端推理（免费套餐） — 使用真实的大模型，无需本地 GPU。
3. 03 — 构建自己的语料库 — 上传 PDF、为其编制索引并进行查询。
4. 04 — 使用 Python 构建 MCP 服务 — 从另一个 Agent 调用引擎，将其用作工具。
5. 05 — 领域预设展示 — 比较不同预设对同一问题的处理效果。

每个 Notebook 都独立完整，可在 Colab 免费套餐上端到端运行， 无需信用卡。

---

三种调用方式

CLI

engine ask "what is hybrid retrieval?" --domain papers --memory session
engine reset-memory
engine domains list
engine version

TUI（Textual — 键盘操作，适用于 SSH）

make tui

三个窗格：来源 · 答案 + 幻觉标记 · 轨迹 + 记忆命中。 按 Enter 提问，按 Ctrl-M 切换记忆模式， 按 Ctrl-L 清除，按 Ctrl-Q 退出。

Web GUI（FastAPI + HTMX，位于 localhost:8080）

make gui
# open http://127.0.0.1:8080 in your browser

无需身份验证。无需云服务。无分析功能。深色主题。令牌会就地流式输出。

---

包含内容

engine/ — 核心引擎

采用 2026 年 SOTA 组合的 8 节点 LangGraph 管线： classify → plan → search → retrieve → fetch_url → compress → synthesize → verify

每个阶段都可通过环境变量开关进行留一法消融。集成的技术包括： HyDE、CoVe 验证、迭代检索、FLARE 主动检索、问题分类器路由器、 步骤评判器（ThinkPRM 模式）、LongLLMLingua-lite 压缩、交叉编码器重排 （BAAI/bge-reranker-v2-m3）、Anthropic 上下文分块，以及 W6 小模型强化 （三种情况的 synthesize 提示词 + 每个分块的字符数上限）。

core/rag/ — 可复用的检索基础组件（v1 稳定版）

HybridRetriever（BM25 + 稠密检索 + RRF）· CrossEncoderReranker · contextualize_chunks（Anthropic 模式）· CorpusIndex（接入自己的 PDF）。 共 5 个导出项，供引擎和归档的示例配方使用。

archive/recipes/ — 引擎推出前的参考配方

research-assistant、trading-copilot、document-qa、 rust-mcp-search-tool。这些配方仍可正常使用，所有测试仍能通过。research-assistant/production/main.py 是对 engine.core.pipeline 的轻量封装，以保留教程式的呈现方式。

---

领域预设

engine/domains/ 中有六个 YAML 文件：

预设	适用场景
general	默认；适用于任何场景
medical	疾病 / 治疗 / 药物 / 临床试验（偏向 PubMed / Cochrane / NEJM；不提供处方性建议）
papers	学术领域的 CS / ML / 物理 / 生物学（arXiv + Semantic Scholar + OpenReview）
financial	SEC 文件、收益、公司基本面（每个数字都标注日期）
stock_trading	每个股票代码的技术分析 + 新闻 — 硬性规则：绝不推荐买入 / 卖出 / 持有
personal_docs	基于个人语料库的问答，采用物理隔离网络（仅允许 corpus:// URL）

你可以用约 10 行 YAML 编写自己的预设 — 参见 docs/domains.md。

---

接入自己的文档

python scripts/index_corpus.py build ~/papers --out ~/papers.idx
export LOCAL_CORPUS_PATH=~/papers.idx
engine ask "what do my papers say about contextual retrieval?" --domain personal_docs

支持的格式：PDF（通过 pypdf）、Markdown、纯文本、HTML（通过 trafilatura）。索引会作为目录持久化，其中包含人类可读的 manifest.json 和经过 pickle 序列化的 index.pkl。文档更改后可随时重建索引。

详情请参阅 docs/self-learning.md，了解轨迹 + 记忆模型； docs/plugins-skills.md 介绍外部插件。

---

MCP + Claude 插件

engine/mcp/server.py 是一个 Python MCP 服务，提供：

• research(question, domain?, memory?) → 结构化 {answer, verified_claims, unverified_claims, sources, trace, totals, memory_hits}
• reset_memory()
• memory_count()

打包的 Claude 插件位于 engine/mcp/claude_plugin/，包含四个技能 （/research、/cite-sources、/verify-claim、/set-domain），可随时 提交至 Anthropic marketplace。

在 Claude Desktop 中注册：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "engine": {
      "command": "python",
      "args": ["-m", "engine.mcp.server"],
      "env": {
        "OPENAI_BASE_URL": "http://localhost:11434/v1",
        "OPENAI_API_KEY":  "ollama",
        "MODEL_SYNTHESIZER": "gemma3:4b",
        "SEARXNG_URL":    "http://localhost:8888"
      }
    }
  }
}

---

插件 / 技能加载器

安装第三方 Claude 插件或 Hermes（agentskills.io）技能：

engine plugins install gh:owner/some-research-plugin@v1
engine plugins install file:./my-local-plugin
engine plugins install https://example.com/marketplace.json
engine plugins list
engine plugins uninstall some-plugin

安全性：每次安装都会运行禁用符号扫描 （eval(、exec(、os.system(，……），拒绝会 执行任意代码的插件。注册表位于 ~/.agentic-research/plugins/，可完整检查，也可清空。

完整文档：docs/plugins-skills.md。

---

架构一览

                ┌─────────────┐
                │   question  │
                └──────┬──────┘
                       ▼
           ┌─────────────────────────┐   T4.3 router  — route by question type
           │  classify               │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T1 decompose · T2 HyDE · T4.1 critic
           │  plan                   │   T4.5 refine-on-reject
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   SearXNG parallel × N
           │  search                 │   + W5 local corpus (optional)
           │  (+ T4.1 critic)        │   + T4.1 coverage critic
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T1 hybrid BM25 + dense + RRF
           │  retrieve               │   W4.1 cross-encoder rerank (opt-in)
           │  (+ W4.1 rerank)        │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   W4.2 trafilatura clean-text
           │  fetch_url              │   skips corpus:// URLs
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T4.4 LLM distillation
           │  compress               │   + W6.2 per-chunk char cap
           │  (+ W6.2 cap)           │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T2 synth · T4.2 FLARE on hedges
           │  synthesize             │   W6.1 three-case anti-hallucinate
           │  (+ FLARE + stream)     │   W7 streaming
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T2 CoVe — decompose + verify
           │  verify                 │
           └────────┬────────────────┘
                    │
              verified? ── yes ──▶ END
                    │
                    no
                    │
           ◀────── re-search unverified claims ──── loop (bounded by MAX_ITERATIONS)

每个阶段都有一个 ENABLE_* 标志，方便进行留一消融。 详细规范：docs/architecture.md。

---

仓库布局

agentic-research-engine-oss/
├── engine/                        the flagship research engine
│   ├── core/                      pipeline · models · trace · memory
│   │   ├── pipeline.py              · compaction · domains · plugins
│   │   ├── models.py
│   │   ├── trace.py
│   │   ├── memory.py
│   │   ├── compaction.py
│   │   ├── domains.py
│   │   └── plugins.py
│   ├── interfaces/
│   │   ├── cli.py                 rich stdout CLI with subcommands
│   │   ├── tui.py                 Textual TUI
│   │   └── web/                   FastAPI + HTMX localhost GUI
│   ├── mcp/
│   │   ├── server.py              Python FastMCP server
│   │   └── claude_plugin/         submittable Claude plugin bundle
│   ├── domains/                   6 YAML presets
│   ├── examples/                  5 worked research examples
│   ├── benchmarks/                mini SimpleQA + BrowseComp fixtures + runner
│   └── tests/                     pytest suite (all mocked, zero-network)
├── core/rag/                      shared retrieval primitives (stable v1)
├── archive/                       pre-engine recipes (kept for reference)
├── tutorials/                     5 Google Colab notebooks
│   ├── 01_engine_api_quickstart.ipynb
│   ├── 02_groq_cloud_inference.ipynb
│   ├── 03_build_your_own_corpus.ipynb
│   ├── 04_mcp_server_from_python.ipynb
│   └── 05_domain_presets_showcase.ipynb
├── scripts/
│   ├── searxng/                   self-hosted meta-search (docker-compose)
│   ├── setup-local-mac.sh         Ollama + Docker + SearXNG one-liner
│   ├── setup-vm-gpu.sh            Linux + vLLM/SGLang setup
│   └── index_corpus.py            build a CorpusIndex from PDFs/md/txt
├── docs/
│   ├── architecture.md            deep technical spec
│   ├── plugins-skills.md          write + install plugins
│   ├── domains.md                 write a new preset
│   ├── self-learning.md           trajectory logging + memory
│   ├── progress.md                wave-by-wave build log
│   ├── how-it-works.md            elevator pitches + SOTA comparison
│   ├── launch-checklist.md        go-live sequence
│   └── launch-copy.md             drafted HN / Reddit / Twitter copy
├── .github/
│   ├── workflows/
│   │   └── engine-tests.yml       CI: mocked suite on every PR
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE                        MIT
└── README.md                      you're reading it

---

配置（环境变量）

完整列表见 engine/core/pipeline.py 文件头。最常用的配置项：

变量	默认值	用途
OPENAI_BASE_URL	未设置（云端 OpenAI）	路由至 Ollama / vLLM / Groq 等
OPENAI_API_KEY	ollama	本地环境使用占位值；云端使用真实密钥
MODEL_SYNTHESIZER	gpt-5-mini（云端）或 gemma3:4b（Mac 本地路径）	最终答案模型。可替换为 gpt-5、claude-sonnet-4-5、Groq 上的 llama-3.3-70b 等，以提高事实类问题的准确性，同时让流水线其余部分保持在本地运行。
TOP_K_EVIDENCE	自动（小型模型为 5，大型模型为 8）	检索预算
ENABLE_RERANK	0	选择启用；首次运行会下载 bge-reranker-v2-m3（约 560 MB）
ENABLE_FETCH	1	使用 trafilatura 获取完整网页
ENABLE_STREAM	1	将合成令牌流式输出到 stdout
ENABLE_TRACE	1	提供每次调用的可观测性，并在 CLI 结束时显示摘要
LOCAL_CORPUS_PATH	未设置	设置为索引目录，以使用你的文档扩展搜索
MEMORY_DB_PATH	~/.agentic-research/memory.db	SQLite 轨迹存储

完整列表：docs/architecture.md 的环境变量部分。

---

测试

cd engine && make test     # 120+ mocked tests in engine/tests/
# or repo-wide:
PYTHONPATH=$(pwd) .venv/bin/python -m pytest core/rag recipes engine/tests -q

所有测试均使用模拟，不需要网络、API 密钥或模型下载。实时 集成冒烟测试单独运行（make smoke）。

CI 会在每次推送或 PR 修改 engine / core / recipes 时运行，详见 .github/workflows/engine-tests.yml。

---

故障排查

症状	可能原因	修复方法
ModuleNotFoundError: No module named 'engine'	PYTHONPATH 缺少仓库根目录	在仓库根目录运行 export PYTHONPATH=$(pwd)
CLI 回答为空且速度很快	Ollama 未运行	在另一个终端运行 ollama serve，或运行 ollama list 检查
Connection refused on :8888	SearXNG 未启动	运行 cd scripts/searxng && docker compose up -d
Connection refused on :11434	Ollama 未运行	运行 ollama serve，或让系统服务启动它
首次运行 make smoke 时，在输出前卡住约 20 秒	模型正在预热，处理首次请求	正常；后续查询会更快
首次运行时 ENABLE_RERANK=1 卡住	正在下载 560 MB 的 bge-reranker	等待这一次；之后会使用缓存
[corpus] LOAD BROKEN	索引损坏或版本不正确	删除索引，并通过 scripts/index_corpus.py 重建
通过 SSH 使用 TUI 时显示乱码	终端太窄	调整大小至 ≥ 100 列；Textual 需要足够空间显示三栏布局
Web GUI 显示 Invalid memory mode	POST 格式错误	使用表单界面；输入值会根据 off/session/persistent 进行验证
流式输出在回答中途截断	后端不稳定	重新运行；下次尝试时会启用批处理回退。如果问题持续，请设置 ENABLE_STREAM=0
运行 uv pip install <pkg> 后出现 zsh: command not found: twine（或类似错误）	shell 未自动激活 uv 的虚拟环境	使用 .venv/bin/<cmd> …、uv run <cmd> …，或在运行前执行 source .venv/bin/activate
移动或重命名仓库目录后出现 bad interpreter: .../python3: no such file or directory	venv 的 shebang 使用绝对路径，指向创建 venv 时所在的目录	重新创建：rm -rf .venv && uv venv && uv pip install -e .（或重新安装你之前安装的内容）
make test 显示收集到 0 个测试	当前工作目录不正确	在 engine/ 目录中运行，或设置 PYTHONPATH
Claude Desktop 看不到插件	plugin.json 路径错误	/plugin marketplace add <absolute-path-to>/engine/mcp/claude_plugin

还是无法解决？请使用 bug_report 模板提交 issue，并附上 ollama list、engine version 和错误信息。

---

客观局限

• Gemma 4B ≠ GPT-5.4 Pro。 在难度较高的多跳问题上，比 30 B 以上的开源模型低 15–25 %。我们的定位是“最佳 $0 本地方案”，而非“最先进水平”。
• 当 SearXNG 返回的来源中不包含正确 token 时，Gemma 3 4B 会臆造具体事实。 在 SimpleQA-mini 上测得的结果：严格通过率为 0/20（参见 engine/benchmarks/RESULTS.md — verified_ratio 为 85.5 %，must_not_contain 命中数为零；模型没有输出禁止的字符串，而是选错了字符串）。缓解方法：(a) 将整个技术栈切换到云端端点（见上文“更高的事实准确度” — 使用 gpt-5-nano + gpt-5-mini 时，每次查询 $0.02–0.05），(b) 为引擎设置 LOCAL_CORPUS_PATH，将你自己的文档作为检索目标，(c) 设置 ENABLE_RERANK=1，让检索结果更偏向正确来源。
• CoVe 能确认内部一致性，但无法确认事实真相。 系统会对照检索到的证据检查每项综合结论；结论不会由现实世界来验证。如果检索遗漏了相关信息，CoVe 仍会轻松地验证一个自信却错误的回答。引擎绝不会编造引用，但可能会自信地重复证据池中的错误信息。
• v1 不支持 LoRA 微调。 系统会收集轨迹数据；实际模型训练将推迟到可使用 GPU 且数据量充足时进行。
• 不提供托管 SaaS。 v1 的整体定位就是本地优先。
• 团队／多用户功能。 不在 v1 范围内。
• 通用网络爬虫／自有搜索索引。 不会提供。继续使用 SearXNG。面向研究的精选索引可能会在 v2 推出。
• 移动端。 不在范围内。

---

状态 + 路线图

• 0.1.3 — 公开 Alpha 版（当前版本）。包含上述功能；已发布到 PyPI、 官方 MCP 注册表和 Anthropic 插件市场。请参阅 CHANGELOG.md。
• 0.2 — 专业工具接入（预设中的 tools_enabled 字段终于启用）、若 GPU 到位则进行首次 LoRA 运行、在 docs/ 中提供插件目录。
• 0.3 — 团队协作功能（共享记忆、由 PR 驱动的领域预设）、通过 Tauri 打包桌面应用。
• 0.4+ — 开放工作项请参阅 GitHub Issues。

---

贡献

适合新手的议题：CONTRIBUTING.md。涉及流水线范围的事项请提交 RFC。欢迎提交插件和领域预设。

不要添加 Co-Authored-By 尾注；作者信息按原样保留。

---

许可证

MIT。请参阅 LICENSE。

相关项目（姊妹项目）

• HermesClaw — 可在其中运行这些方案的安全运行时
• NVIDIA/OpenShell — 内核级 Agent 沙箱
• NousResearch/hermes-agent — 可自我改进的 Agent（我们与其 agentskills.io 技能格式互通）

---

MCP 注册表所有权

此 PyPI 包是注册在 https://registry.modelcontextprotocol.io 上的 MCP 服务的官方来源。下面这行是注册表验证的 所有权标记——编辑此 README 时不要删除。

mcp-name: io.github.TheAiSingularity/agentic-research