mini-deerflow

A minimal deep-research agent harness built on LangGraph 1.x + LangChain 1.x — search, browse, execute, plan, delegate.

一个深度研究智能体 Harness：研读字节 DeerFlow 的核心架构后，做的教学级精简复刻——保留 agent harness 最核心、最能体现设计功力的机制（工具沙箱、代理浏览器、子智能体编排、记忆与技能、MCP 扩展），压缩到可通读、可面试讲解的体量。

它能做什么

给它一个研究问题，它会：规划（todo 计划）→ 并行委派（派生子智能体分头调查）→ 搜索/抓取/操作浏览器（三层 web 能力）→ 在沙箱里执行代码与读写文件 → 综合成带引用的研究报告。

核心特性

能力	说明
核心工具集	web_search / web_fetch / web_capture（渲染后捕获）/ 文件五件套 / bash
代理浏览器工具组（可选）	常驻 per-conversation 浏览器会话：navigate → observe → act 循环。每个动作返回以固定 [ref] 编号寻址的页面快照，模型按刚观察到的元素行动而非猜 CSS selector；出站 URL 默认 SSRF 双重过滤。Playwright 驱动，作为可选附加组件保持核心安装精简
沙箱感知执行	Sandbox 抽象：本地 subprocess 沙箱 与 E2B 云沙箱（真实隔离 microVM）可互换，切换只改配置一行；虚拟路径契约 /mnt/user-data/* + 懒初始化 + sandbox_id 入 LangGraph state 可随 checkpoint 恢复
规划系统	write_todos 计划 + 上下文丢失恢复 + 未完成计划的提前退出拦截（jump_to 强制续跑）
子智能体	task 工具派生独立 agent graph 并行执行；并发/总量限额由 middleware 硬执行而非 prompt 约束
Memory 记忆	跨会话长期记忆：memory_search/add/update/delete 四工具，JSON 落盘
Skills 技能	SKILL.md（YAML frontmatter）渐进加载：索引进系统提示，正文按需 read_file
自定义工具	MCP 服务器（langchain-mcp-adapters）+ Python 函数（use: "module:var" 反射注册）
上下文压缩	token 超阈值自动把旧消息压成摘要，todo 计划在压缩后自动恢复
追踪评估	LangSmith / Langfuse 一键接入（callbacks 只挂 graph 根，防双 span）
前端	TypeScript + React + Vite：SSE 流式输出、计划面板、工具调用卡片、子智能体时间线

快速开始

依赖用 uv 管理（没装：curl -LsSf https://astral.sh/uv/install.sh | sh）。

# 1. 后端
cd backend && uv sync                        # 建 .venv 并按 uv.lock 精确安装（含 dev）
cp ../config.example.yaml ../config.yaml     # 填 base_url（DeepSeek/Qwen/GLM 任意 OpenAI 兼容端点）
cp ../.env.example ../.env                   # 填 OPENAI_COMPAT_API_KEY 与 TAVILY_API_KEY
uv run python -m harness.server.app          # 或 uv run python -m harness.cli 直接在终端对话

# 2. 前端（另开终端）
cd frontend && npm install && npm run dev    # http://localhost:5173

# 可选特性（按需叠加）
uv sync --extra e2b                          # E2B 云沙箱
uv sync --extra browser && uv run playwright install chromium   # 浏览器工具组

详见 docs/01-quickstart.md。

架构总览

┌─────────────────────────  FastAPI Gateway (SSE)  ─────────────────────────┐
│  POST /api/chat → agent.astream(stream_mode=[messages, updates, custom])  │
└────────────────────────────────────┬──────────────────────────────────────┘
                                     │
      ┌──────────────────  create_agent(...)  收敛点 agent.py ─────────────┐
      │  静态系统提示 prompts.py     ThreadState state.py    checkpointer  │
      │                                                                    │
      │  Middleware 栈（wrap_* 首个最外层 / after_model 逆序）：           │
      │  Sandbox → ToolError → DynamicContext → Compaction → Planning →    │
      │  SubagentLimit                                                     │
      └──────┬──────────────┬───────────────┬────────────────┬─────────────┘
             │              │               │                │
        sandbox/        web/ + browser/   subagents.py     mcp.py + config
        Sandbox ABC     search/fetch/     task 工具 →      MCP 工具 +
        LocalSandbox    capture +         独立 agent       Python 反射工具
        7 个工具        [ref] 快照会话    graph 并行

每个模块头部的 docstring 都注明了它对应 DeerFlow 的哪个源文件、保留了什么、砍掉了什么。

文档

文档	内容
01-quickstart	环境配置、启动命令、常见问题
02-architecture	架构总览：数据流、状态、生命周期
03-code-walkthrough	代码拆解：逐模块精读，对照 DeerFlow 原始设计
04-tutorial-from-zero	新手课程：从零一步步搭出这个系统（10 课）
05-resume	把这个项目写进简历的方法与模板
06-interview-qa	面试拷问应对：30+ 深挖问题与答法

测试

cd backend && uv run pytest ../tests -v   # 33 项：SSRF / 沙箱逃逸与掩码 / E2B 适配 / skills 解析与转义 / agent 端到端冒烟

技术栈

LangGraph 1.0.6+ · LangChain 1.2.3+ · FastAPI 0.115+ · langchain-mcp-adapters · E2B（可选云沙箱）· Playwright（可选）· Tavily / Firecrawl · Markitdown · LangSmith / Langfuse · React + TypeScript + Vite · uv（依赖管理）

License

MIT