🔬 DeepResearchAgent

一个可运行、可恢复、可审计的深度研究智能体，也是一份面向 AI Agent 爱好者的工程学习参考。

从自然语言问题出发，自动规划研究、搜索并读取网页、整理证据，最终生成带来源的 Markdown 报告。既可以通过 CLI 使用，也可以在 Web 工作台中实时观察研究过程。

快速开始 · 工作流程 · 核心架构 · 学习路线 · 进阶能力 · 示例报告

项目定位

DeepResearchAgent 是一个基于 LangGraph 构建的深度研究 Agent。

它希望同时回答两个问题：

1. 一个深度研究 Agent 怎样可靠地完成长任务？
2. 学习者怎样从最小 Agent 出发，逐步理解并复现一套完整的工程系统？

因此，这个项目既可以作为可运行的研究工具，也可以作为 AI Agent 爱好者的学习参考。你可以直接用它生成研究报告，也可以沿着 CLI、State、Tool、Middleware、Checkpoint、Memory 和 Skill 的顺序阅读代码，理解一次研究任务如何在系统中流动。

[!NOTE] 这是一个面向学习与工程实践的项目。代码和测试覆盖了 README 中描述的主要能力，但“有引用”不等于“事实一定正确”，概率评估也不能代替人工核验。

输入与输出

核心特点

• 研究闭环：计划、搜索、正文读取、证据聚合、缺口检查、引用校验和报告生成。
• 可恢复：使用 SQLite Checkpoint 保存任务，进程中断后可以通过 thread_id 继续执行。
• 可审计：程序记录真实 Tool 调用、来源、证据和模型可见上下文，不依赖模型描述自己做过什么。
• 有边界：通过 Token 治理、搜索与阅读预算、有限 Reflection 和强制收尾避免无限循环。
• 可扩展：模型、Tool、Middleware、Memory、Skill 和评估层相互分离。
• 受控演化：Skill 可以基于跨任务评估生成候选，经规则与概率评审后由人工晋级，并保留旧版本回滚。
• 适合学习：模块职责明确，提供离线 Demo、自动化测试、名词解释和分阶段阅读路线。

快速开始

项目要求 Python 3.12+，推荐使用 uv 管理环境。

git clone https://github.com/1612535983/deepresearchagent.git
cd deepresearchagent
uv sync --extra dev --extra web

先运行完全离线的 Demo，不需要 API Key：

uv run deepresearch demo

预期输出：

最小链路已跑通：命令行输入已经进入 LangChain Agent Graph，模型响应也已被封装为 ResearchResult。

运行测试：

uv run pytest -q

当前项目包含 332 个自动化测试，覆盖 Agent、Tool、Middleware、Checkpoint、上下文治理、Memory、Skill、报告评估、受控 Skill 演化和 Web API。

接入真实模型

复制环境变量模板：

cp .env.example .env

项目通过 ChatOpenAI 接入兼容 OpenAI Chat Completions 协议的模型服务。.env.example 默认以 DeepSeek 为例：

DEEPRESEARCH_API_KEY=sk-your-api-key
DEEPRESEARCH_MODEL=deepseek-chat
DEEPRESEARCH_BASE_URL=https://api.deepseek.com

运行一次真实研究：

uv run deepresearch run "请解释 ReAct Agent 的基本工作方式"

实时查看计划、工具调用、证据和报告进度，并把结果保存为 Markdown：

uv run deepresearch run "研究 LangChain Agent" \
  --stream \
  --show-trace \
  --output reports/langchain-agent.md

可以先查看示例报告：LangGraph Agent 核心工作机制。该报告展示了完整研究正文、参考来源以及 Jev Shadow 模式生成的质量评估附录；真实内容会随研究问题、模型和搜索结果变化。

启动 Web 工作台

先安装并构建前端：

cd web
npm ci
npm run build
cd ..

然后从项目根目录启动本地服务：

uv run deepresearch serve

打开 http://127.0.0.1:8000 即可输入问题。API 文档位于 http://127.0.0.1:8000/docs。服务默认只监听本机；当前版本没有用户登录与权限隔离，不应直接暴露到公网。

前端开发时可以在另一个终端运行 cd web && npm run dev，浏览器访问 http://127.0.0.1:5173；Vite 会把 /api 请求代理到 8000 端口。

Web 工作流的输入与输出：

工作流程

flowchart LR
    A[自然语言问题] --> B[创建研究计划]
    B --> C[网页搜索]
    C --> D[读取关键正文]
    D --> E[沉淀来源与证据]
    E --> F{检查研究缺口}
    F -->|仍需研究| C
    F -->|证据足够| G[生成并校验报告]
    G --> H[ResearchResult / Markdown]

    I[(SQLite Checkpoint)] -.保存与恢复.-> B
    J[(长期记忆)] -.跨任务召回.-> E
    K[Context Governance] -.外化 / 压缩 / 收尾.-> F
    L[(Skill Registry)] -.注入研究方法.-> B
    M[Report Evaluation] -.质量观测 / 有界回跳.-> G
    N[Skill Evolution] -.评估 / 候选 / 人工晋级.-> L

整个流程可以理解为：

1. CLI 接收问题和运行参数。
2. Agent 创建结构化研究计划。
3. 模型选择搜索、正文读取、计划更新或报告工具。
4. Middleware 把真实工具结果整理为来源和证据，并同步到 State。
5. 程序检查计划、证据、上下文和工具预算，决定继续研究还是开始收尾。
6. 报告工具校验引用，把 Markdown 写入 State.final_report。
7. Runner 返回 ResearchResult，也可以把报告保存到本地文件。

核心架构

本项目刻意把模型能力与确定性程序逻辑分开：

• 模型负责：理解问题、制定计划、选择工具、判断下一步和撰写报告。
• 程序负责：记录真实执行结果、更新状态、校验引用、保存 Checkpoint、控制预算和处理失败。

这样既保留了 Agent 的灵活性，也让关键行为可以测试、恢复和审计。

flowchart TB
    ENTRY[CLI / Web / Python API] --> RUNNER[Runner / Stream]
    RUNNER --> GRAPH[LangGraph Agent]
    GRAPH <--> MODEL[Chat Model]
    GRAPH <--> TOOLS[Research Tools]
    GRAPH <--> MW[Middleware Chain]

    MW <--> STATE[ResearchState]
    STATE <--> CHECKPOINT[(SQLite Checkpoint)]
    MW <--> MEMORY[(Long-term Memory)]
    MW <--> SKILL[(Versioned Skills)]
    MW --> CONTEXT[Context Governance]
    MW --> EVAL[Report Evaluation]

组件的输入、输出与职责

项目结构

.
├── src/deepresearch/
│   ├── cli.py               # 命令行入口
│   ├── agent.py             # 组装并运行 Agent Graph
│   ├── state.py             # 研究状态与 reducer
│   ├── checkpointing.py     # SQLite Checkpoint 与任务恢复
│   ├── events.py            # 流式事件
│   ├── api/                 # FastAPI、公开 DTO、异步任务与 SSE
│   ├── tools/               # 搜索、正文读取、计划和报告工具
│   ├── middlewares/         # 证据、反思、治理、记忆等横切逻辑
│   ├── context/             # Token、外化、快照、摘要和收尾策略
│   ├── memory/              # 长期记忆存储、检索与 Worker
│   ├── skill/               # Skill 解析、版本、选择、注入、指标和受控演化
│   └── evaluation/          # 报告/Skill 概率评估与 Provider 适配
├── web/                     # React + TypeScript 研究工作台
├── tests/                   # 自动化测试
├── examples/                # 输出样例
├── reports/                 # 运行报告与 Jev Shadow 示例
├── docs/assets/             # README 素材
├── .github/workflows/       # GitHub Actions
└── pyproject.toml           # 依赖、脚本入口与打包配置

面向爱好者的学习路线

如果你刚开始学习 Agent，不建议直接从最复杂的 Middleware 入手。可以按照下面的顺序阅读和动手：

推荐的完整代码阅读顺序：

cli.py
  ↓
agent.py
  ↓
state.py
  ↓
tools/
  ↓
middlewares/
  ↓
context/
  ↓
memory/ → skill/ → evaluation/

这个顺序先回答“输入如何变成输出”，再逐步展开状态、工具、可靠性和高级能力，适合边运行、边阅读、边修改。

值得关注的工程问题

这些问题也是阅读项目时最值得追问的部分：不仅要知道“使用了什么技术”，还要理解它解决了什么问题，以及付出了什么代价。

常用命令

流式运行与执行记录

uv run deepresearch run "研究 LangChain Agent" --stream --show-trace

--stream 展示由真实 Graph 更新转换出的 ResearchEvent；--show-trace 读取 State 中的搜索、正文、来源、证据、上下文和评估统计，不会额外调用模型。

保存 Markdown 报告

uv run deepresearch run "研究 LangChain Agent" \
  --output reports/langchain-agent.md

程序不会覆盖已经存在的文件。报告正文来自 State.final_report；如果已完成质量评估，还会追加程序确定性渲染的评估附录。

中断恢复与状态查看

uv run deepresearch run "研究 LangGraph" \
  --thread-id research-001 \
  --stream

uv run deepresearch resume research-001 --stream
uv run deepresearch inspect research-001

• 新任务应该使用新的 thread_id。
• resume 从最近的 Graph 快照继续，不会重新创建初始 State。
• inspect 只读取最新持久化摘要，不会调用模型。
• 不要让两个进程同时执行同一个 thread_id。

进阶能力

以下能力默认关闭，便于学习者先理解最小研究链路，再按需启用。

Checkpoint 保存“同一个任务怎样继续”，Memory 保存“后续任务可能再次用到什么”。两者不是同一个概念。

DEEPRESEARCH_MEMORY_USE=default
DEEPRESEARCH_MEMORY_NAMESPACE=default
DEEPRESEARCH_MEMORY_ENABLE_RECALL=true
DEEPRESEARCH_MEMORY_ENABLE_EXTRACT=false

Retriever 使用基础中英文分词、BM25 和记忆强度排序。召回内容只进入当前模型请求的 <memory_context>，不会写入正式对话历史。

Tool 解决“Agent 能执行什么动作”，Skill 解决“Agent 应该怎样完成某类任务”。

DEEPRESEARCH_SKILL_USE=default
DEEPRESEARCH_SKILL_DIRS=skills
DEEPRESEARCH_SKILL_INCLUDE_BUILTIN=true

uv run deepresearch skills validate
uv run de