feat(auth): 添加异步密码哈希和验证函数
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled

refactor(relay): 复用HTTP客户端和请求体序列化结果

feat(kernel): 添加获取单个审批记录的方法

fix(store): 改进SaaS连接错误分类和降级处理

docs: 更新审计文档和系统架构文档

refactor(prompt): 优化SQL查询参数化绑定

refactor(migration): 使用静态SQL和COALESCE更新配置项

feat(commands): 添加审批执行状态追踪和事件通知

chore: 更新启动脚本以支持Admin后台

fix(auth-guard): 优化授权状态管理和错误处理

refactor(db): 使用异步密码哈希函数

refactor(totp): 使用异步密码验证函数

style: 清理无用文件和注释

docs: 更新功能全景和审计文档

refactor(service): 优化HTTP客户端重用和请求处理

fix(connection): 改进SaaS不可用时的降级处理

refactor(handlers): 使用异步密码验证函数

chore: 更新依赖和工具链配置
This commit is contained in:
iven
2026-03-29 21:45:29 +08:00
parent b7ec317d2c
commit 7de294375b
34 changed files with 2041 additions and 894 deletions

View File

@@ -0,0 +1,504 @@
# DeerFlow 2.0 深度分析报告
> **项目**: [bytedance/deer-flow](https://github.com/bytedance/deer-flow)
> **版本**: 2.0 (完全重写,与 1.x 无代码共享)
> **分析日期**: 2026-03-29
> **定位**: 开源 Super Agent Harness超级智能体运行时
---
## 1. 项目概览
DeerFlow**D**eep **E**xploration and **E**fficient **R**esearch **Flow**)是字节跳动开源的 AI Agent 基础设施能编排子智能体、记忆、沙箱来执行分钟到小时级别的长周期任务。2026 年 2 月 28 日发布 2.0 后登上 GitHub Trending #1
**核心主张**: 一个可扩展的 Agent 运行时,通过 SKILL.md 技能定义 + LangGraph 编排 + 沙箱隔离,实现接近自主的复杂任务执行。
---
## 2. 系统架构
### 2.1 三层分离 + 统一反向代理
```
┌──────────────────────────────────┐
│ Nginx (Port 2026) │
│ 统一反向代理入口 │
└─────┬──────────────┬─────────────┘
│ │
/api/langgraph/* │ │ /api/*
▼ ▼
┌──────────────────────┐ ┌────────────────────────┐
│ LangGraph Server │ │ Gateway API (8001) │
│ (Port 2024) │ │ FastAPI REST │
│ │ │ │
│ Agent Runtime │ │ Models / MCP / Skills │
│ Thread Management │ │ Memory / Uploads │
│ SSE Streaming │ │ Artifacts / Threads │
│ Checkpointing │ │ │
└──────────────────────┘ └────────────────────────┘
┌──────────────────────────────────────────────┐
│ Frontend (Next.js, Port 3000) │
└──────────────────────────────────────────────┘
```
**路由规则**:
- `/api/langgraph/*` → LangGraph ServerAgent 交互、线程、流式响应)
- `/api/*` → Gateway API配置管理、文件上传、制品服务
- 其余 → Next.js 前端
### 2.2 代码规模
| 模块 | 文件数 | 技术栈 |
|------|--------|--------|
| 后端核心 (harness) | 124 .py | Python 3.12+, LangGraph, LangChain |
| 后端测试 | 69 .py | pytest |
| 前端 | 225 .ts/.tsx | Next.js 16, React 19, Tailwind v4 |
| 内置技能 | 17 个 | SKILL.md + 脚本/模板 |
---
## 3. 核心功能模块
### 3.1 Agent 编排 — Lead Agent + 中间件链
入口: `packages/harness/deerflow/agents/lead_agent/agent.py:make_lead_agent`
Lead Agent 通过工厂函数动态组装,包含 **9 层有序中间件**:
| # | 中间件 | 职责 |
|---|--------|------|
| 1 | ThreadDataMiddleware | 为线程创建隔离目录 (workspace/uploads/outputs) |
| 2 | UploadsMiddleware | 将上传文件注入对话上下文 |
| 3 | SandboxMiddleware | 获取沙箱执行环境 |
| 4 | SummarizationMiddleware | Token 接近上限时压缩上下文(可选) |
| 5 | TodoListMiddleware | Plan 模式下跟踪多步骤任务 |
| 6 | TitleMiddleware | 自动生成对话标题 |
| 7 | MemoryMiddleware | 异步排队记忆提取 |
| 8 | ViewImageMiddleware | 视觉模型图像注入 |
| 9 | ClarificationMiddleware | 拦截澄清请求(必须最后) |
额外运行时中间件:
- `LoopDetectionMiddleware` — 检测重复工具调用循环
- `SubagentLimitMiddleware` — 限制子 Agent 并发数
- `TokenUsageMiddleware` — Token 用量追踪
- `ToolErrorHandlingMiddleware` — 工具调用错误处理
- `GuardrailMiddleware` — 安全护栏(工具调用前评估)
**设计模式**: 洋葱模型Onion Model每层中间件可拦截、修改或转发请求。这与传统 Web 中间件概念一致,但应用在了 Agent 执行层面。
### 3.2 子 Agent 系统
**内置 Agent**:
- `general-purpose` — 拥有完整工具集的通用 Agent
- `bash` — 命令执行专家
**执行机制**:
- 最大 3 个子 Agent 并发(双线程池: scheduler + execution
- 15 分钟默认超时(按 Agent 可单独配置)
- 后台异步执行 + SSE 事件推送状态
- 流程: Lead Agent 调用 `task()` → 后台线程池运行子 Agent → 轮询完成 → 返回结果
### 3.3 ThreadState — 扩展的状态 Schema
```python
class ThreadState(AgentState):
messages: list[BaseMessage] # LangGraph 原生消息
sandbox: dict # 沙箱环境信息
artifacts: list[str] # 生成的文件路径
thread_data: dict # {workspace, uploads, outputs} 路径
title: str | None # 自动生成的标题
todos: list[dict] # 任务追踪 (plan mode)
viewed_images: dict # 视觉模型图像数据
```
### 3.4 技能系统
**SKILL.md 格式**:
```markdown
---
name: skill-name
description: 触发条件和工作描述
---
# 技能标题
## 工作流步骤 / 最佳实践 / 参考资源
```
**加载机制**:
- 递归扫描 `skills/{public,custom}/` 下所有 SKILL.md
- **渐进式加载** — 只有任务需要时才注入上下文,不一次性全加载
- 沙箱内通过 `/mnt/skills/` 虚拟路径访问
**17 个内置技能**:
| 技能 | 功能 | 附加资源 |
|------|------|----------|
| deep-research | 系统性深度研究方法论 | — |
| data-analysis | 数据分析 | analyze.py |
| chart-visualization | 图表可视化 | generate.js + 22 种图表参考 |
| ppt-generation | PPT 生成 | generate.py |
| image-generation | 图片生成 | generate.py + 模板 |
| video-generation | 视频生成 | generate.py |
| podcast-generation | 播客生成 | generate.py + 模板 |
| frontend-design | 前端设计 | — |
| consulting-analysis | 咨询分析 | — |
| github-deep-research | GitHub 深度研究 | github_api.py |
| skill-creator | 技能创建器 | 评估脚本 + 查看器 |
| web-design-guidelines | Web 设计指南 | — |
| surprise-me | 惊喜生成 | — |
| vercel-deploy-claimable | Vercel 部署 | deploy.sh |
| find-skills | 技能发现安装 | install-skill.sh |
| claude-to-deerflow | Claude Code 集成 | chat.sh / status.sh |
| bootstrap | 引导技能 | 模板 + 对话指南 |
### 3.5 沙箱隔离系统
**三种执行模式**:
| 模式 | Provider | 隔离级别 | 场景 |
|------|----------|----------|------|
| Local | `LocalSandboxProvider` | 无隔离 | 开发 |
| Docker | `AioSandboxProvider` | 容器级 | 生产 |
| Kubernetes | `AioSandboxProvider` + Provisioner | Pod 级 | 高安全要求 |
**虚拟路径映射**:
| 虚拟路径 | 物理映射 |
|----------|----------|
| `/mnt/user-data/workspace/` | `.deer-flow/threads/{id}/user-data/workspace` |
| `/mnt/user-data/uploads/` | `.deer-flow/threads/{id}/user-data/uploads` |
| `/mnt/user-data/outputs/` | `.deer-flow/threads/{id}/user-data/outputs` |
| `/mnt/skills/` | `deer-flow/skills/` |
**沙箱工具集**: `bash`, `ls`, `read_file`, `write_file`, `str_replace`
### 3.6 记忆系统
```
对话流 → MemoryMiddleware → Queue (防抖 30s) → Updater (LLM 提取) → memory.json
System Prompt ← 注入 Top Facts + Context ← format_memory_for_injection()
```
**记忆结构**:
- **用户上下文** — 工作背景、个人信息、当前关注点
- **对话历史** — 近期/早期/长期背景
- **事实列表** — 带置信度评分(阈值 0.7),最大 100 条,按置信度排序,受 max_injection_tokens 约束
**关键配置**:
| 参数 | 默认值 | 说明 |
|------|--------|------|
| debounce_seconds | 30 | 防抖间隔 |
| max_facts | 100 | 最大事实条数 |
| fact_confidence_threshold | 0.7 | 存储置信度阈值 |
| max_injection_tokens | 2000 | 注入上限 |
**待实现**: TF-IDF 上下文感知检索(文档已规划,尚未合并)
### 3.7 消息网关 — IM 通道集成
| 通道 | 传输方式 | 流式支持 |
|------|----------|----------|
| Telegram | Bot API (长轮询) | 等待完整响应 |
| Slack | Socket Mode | 等待完整响应 |
| 飞书/Lark | WebSocket | 流式更新消息卡片 |
所有通道使用**出站连接**,无需公网 IP。支持 `/new`, `/status`, `/models`, `/memory`, `/help` 命令。
### 3.8 模型抽象层
通过 `config.yaml``use` 字段动态加载 LangChain 类:
```yaml
models:
- name: gpt-4
use: langchain_openai:ChatOpenAI
- name: claude-sonnet-4.6
use: deerflow.models.claude_provider:ClaudeChatModel # CLI 后端
```
**支持类型**: OpenAI 兼容、Anthropic、DeepSeek、Google Gemini、OpenRouter、Codex CLI、Claude Code OAuth以及自定义 Provider通过 Python 反射机制)。
### 3.9 MCP 协议集成
支持 stdio / SSE / HTTP 三种传输方式的 MCP Server通过 `extensions_config.json` 配置,使用 `langchain-mcp-adapters` 连接。支持 OAuth 认证和工具缓存。
### 3.10 安全护栏 (Guardrails)
`GuardrailMiddleware` 在工具调用执行前评估:
- 每次工具调用通过 `GuardrailProvider` 评估
- 拒绝的调用返回错误 ToolMessageAgent 可自适应调整
- 支持 fail-closed默认阻止和 fail-open允许通过模式
---
## 4. 前端架构
### 4.1 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Next.js | 16.1.7 | App Router + SSR |
| React | 19.0.0 | UI 框架 |
| Tailwind CSS | 4.0.15 | 样式方案 |
| Radix UI | 多组件 | 无障碍 UI 基础 |
| @xyflow/react | 12.10.0 | 流程图可视化 |
| @tanstack/react-query | 5.x | 服务端状态 |
| better-auth | 1.3+ | 认证 |
| shiki | 3.15.0 | 代码高亮 |
| streamdown | 1.4.0 | 流式 Markdown 渲染 |
| Codemirror | 6.x | 代码编辑器 |
### 4.2 前端目录结构
```
frontend/src/
├── app/ # Next.js App Router
│ ├── api/auth/ # better-auth 认证路由
│ ├── workspace/ # 主工作区
│ │ ├── chats/ # 聊天页面
│ │ └── agents/ # 自定义 Agent 管理
│ └── mock/api/ # Mock API (开发用)
├── components/
│ ├── ai-elements/ # AI 交互组件 (25+)
│ ├── workspace/ # 工作区组件
│ ├── landing/ # 着陆页
│ └── ui/ # 基础 UI 组件
├── core/ # 核心业务逻辑
│ ├── agents/ # Agent 管理
│ ├── api/ # API 客户端
│ ├── i18n/ # 国际化
│ ├── memory/ # 记忆管理
│ ├── mcp/ # MCP 集成
│ ├── skills/ # 技能管理
│ ├── streamdown/ # 流式渲染
│ ├── threads/ # 线程管理
│ └── tools/ # 工具管理
└── hooks/ # React Hooks
```
### 4.3 前端通信
- **Agent 交互**: 通过 `@langchain/langgraph-sdk` 连接 LangGraph Server
- **配置管理**: 通过 Gateway REST API
- **流式响应**: SSE (Server-Sent Events)
- **文件上传**: multipart/form-data → Gateway → 自动转 Markdown
---
## 5. 关键实现原理
### 5.1 上下文工程 (Context Engineering)
DeerFlow 的核心设计哲学是**上下文工程** — 精心控制每次 LLM 调用的输入:
1. **渐进式技能加载** — 技能不全部注入,只在相关时加载
2. **Token 预算管理** — SummarizationMiddleware 在接近上限时压缩
3. **记忆选择性注入** — 按置信度排序,受 token 预算约束
4. **工具按需暴露** — 通过 `tool_search` 按需发现工具,不全部列出
### 5.2 线程隔离
每个对话线程拥有独立的:
- workspace 目录 — Agent 工作空间
- uploads 目录 — 用户上传文件
- outputs 目录 — 生成的制品
- 沙箱实例 — 代码执行环境
- checkpointer — 状态持久化
### 5.3 配置热重载
`AppConfig` 支持运行时重新加载Agent 配置、模型列表、工具集等可在不重启的情况下更新。
### 5.4 Agent 工厂模式
`make_lead_agent()` 是工厂函数,根据运行时配置动态组装:
- 选择模型(支持 thinking/vision 标记)
- 组装中间件链
- 加载工具集(内置 + MCP + 配置)
- 注入系统提示词(含技能上下文)
---
## 6. 技术栈全景
| 层级 | 技术 | 说明 |
|------|------|------|
| **Agent 框架** | LangGraph 1.0.x | 状态图驱动的 Agent 编排 |
| **LLM 抽象** | LangChain 1.2+ | 多模型统一接口 |
| **后端 API** | FastAPI | REST + SSE |
| **前端框架** | Next.js 16 + React 19 | App Router |
| **样式** | Tailwind CSS v4 | 原子化 CSS |
| **沙箱** | Docker / Kubernetes | 容器级隔离 |
| **MCP** | langchain-mcp-adapters | 工具协议集成 |
| **IM 集成** | lark-oapi / slack-sdk / python-telegram-bot | 消息通道 |
| **搜索** | Tavily / Firecrawl / DuckDuckGo / InfoQuest | 信息获取 |
| **认证** | better-auth | Web 端用户认证 |
| **可观测** | LangSmith | 链路追踪 |
| **包管理** | uv (Python) + pnpm (JS) | monorepo workspace |
| **反向代理** | Nginx | 统一入口 |
| **语言要求** | Python 3.12+, Node.js 22+ | — |
| **License** | MIT | 开源 |
---
## 7. 优势分析
### 7.1 架构优势
1. **中间件链模式** — 9 层有序中间件,横切关注点高度模块化,新增功能只需添加中间件
2. **渐进式上下文工程** — 不是一股脑注入所有信息,而是按需、按预算精确控制 LLM 输入
3. **技能热插拔** — SKILL.md 格式简单直观,用户可自行创建和安装技能
4. **模型无关** — 通过 LangChain 类路径动态加载,支持任意 OpenAI 兼容 API
5. **三层分离** — LangGraph Server / Gateway API / Frontend 各司其职,独立扩展
### 7.2 生态优势
1. **LangGraph 生态** — 直接受益于 LangChain/LangGraph 社区的持续迭代
2. **MCP 协议** — 无缝接入 MCP 工具生态
3. **多 IM 通道** — Telegram/Slack/飞书开箱即用
4. **字节跳动背书** — 企业级投入InfoQuest 等增值服务集成
5. **社区活跃** — GitHub Trending #1,多语言 README活跃的 Issue/PR
### 7.3 工程优势
1. **完整的测试覆盖** — 69 个测试文件,覆盖核心路径
2. **多沙箱模式** — 从开发到生产无缝切换
3. **配置版本管理** — config_version + `make config-upgrade` 平滑升级
4. **嵌入式 Python 客户端**`deerflow-harness` 可作为独立包使用
---
## 8. 局限性分析
### 8.1 架构局限
1. **Python 性能瓶颈** — Python 3.12 + asyncio 在高并发场景下受限GIL 限制了真正的并行
2. **LangGraph 耦合** — 核心编排绑定 LangGraph迁移成本高
3. **单 Lead Agent 模型** — 不支持多 Agent 协作(仅 Lead → Sub 单向委托),缺少 Agent 间协商
4. **文件系统状态** — Checkpointer 默认用 SQLite 本地文件,生产需外部化
### 8.2 功能局限
1. **记忆系统不成熟** — TF-IDF 上下文感知检索尚未实现,当前仅按置信度排序
2. **无实时协作** — 不支持多用户同时操作同一线程
3. **沙箱冷启动** — Docker 容器启动有延迟,影响首次响应时间
4. **技能质量参差** — 17 个内置技能,深度和完成度不一
5. **无内置 RAG** — 知识检索依赖外部搜索 API无本地知识库
### 8.3 运维局限
1. **依赖链复杂** — LangGraph + LangChain + FastAPI + Docker + Nginx + MCP 等,部署门槛高
2. **无内置用户管理** — Web 端认证由 better-auth 提供,但无企业级 RBAC
3. **成本控制有限** — Token 用量追踪有,但无细粒度的配额/限流机制
4. **可观测性依赖外部** — 需要 LangSmith 才能获得完整链路追踪
---
## 9. 适用场景
### 9.1 最佳场景
| 场景 | 适配度 | 原因 |
|------|--------|------|
| 深度研究任务 | ⭐⭐⭐⭐⭐ | 原生设计目标deep-research 技能成熟 |
| 内容生成PPT/视频/播客) | ⭐⭐⭐⭐⭐ | 丰富的多媒体生成技能 |
| 数据分析与可视化 | ⭐⭐⭐⭐ | chart-visualization + data-analysis 组合 |
| IM Bot 开发 | ⭐⭐⭐⭐ | 三大 IM 通道开箱即用 |
| 编程辅助(代码生成/调试) | ⭐⭐⭐⭐ | 沙箱 + 工具链完善 |
### 9.2 勉强场景
| 场景 | 适配度 | 原因 |
|------|--------|------|
| 企业级 SaaS 平台 | ⭐⭐ | 缺少 RBAC、审计、多租户 |
| 实时协作应用 | ⭐⭐ | 无多用户并发支持 |
| 边缘/离线部署 | ⭐⭐ | 依赖云 API 和 Docker |
### 9.3 不适用场景
| 场景 | 原因 |
|------|------|
| 低延迟实时系统 | Python + LLM API 调用固有延迟 |
| 高并发生产服务 | 单进程 + GIL 限制 |
| 安全合规要求高的环境 | 沙箱隔离非零信任 |
---
## 10. 与同类项目对比
| 维度 | DeerFlow 2.0 | OpenHands | CrewAI | AutoGen | Devin |
|------|-------------|-----------|--------|---------|-------|
| **定位** | Super Agent Harness | 软件开发 Agent | 多 Agent 框架 | 多 Agent 对话 | 自主编程 Agent |
| **编排模型** | Lead + Sub (LangGraph) | 单 Agent + Action | Crew + Task | GroupChat | 单 Agent |
| **沙箱隔离** | Docker/K8s | Docker | 无内置 | 无内置 | 自研 |
| **技能扩展** | SKILL.md 热插拔 | 无 | 工具定义 | 函数注册 | 无 |
| **IM 集成** | 3 通道 | 无 | 无 | 无 | 无 |
| **记忆系统** | LLM 提取 + JSON | 无 | 无 | 无 | 有 |
| **开源** | MIT | MIT | MIT | MIT | 不开源 |
| **语言** | Python | Python | Python | Python | 未知 |
| **背书** | 字节跳动 | All Hands AI | CrewAI Inc | Microsoft | Cognition |
---
## 11. 未来发展方向(推断)
### 11.1 短期 (3-6 个月)
1. **记忆系统增强** — TF-IDF 上下文感知检索合并,记忆质量提升
2. **更多 IM 通道** — 微信、钉钉等国内平台集成
3. **技能市场** — 社区技能共享与评分系统
4. **多 Agent 协作** — 从单向委托升级为多 Agent 协商
### 11.2 中期 (6-12 个月)
1. **企业级功能** — RBAC、审计日志、多租户、配额管理
2. **RAG 集成** — 本地知识库支持,减少对外部搜索的依赖
3. **模型微调** — 针对 Agent 任务的专项微调指南
4. **多模态增强** — 更强的图像/视频理解与生成
### 11.3 长期 (12+ 个月)
1. **Agent 操作系统** — 从工具到真正的自主 Agent 平台
2. **去中心化** — 支持 Agent-to-Agent 通信协议
3. **端侧部署** — 支持模型本地化运行,降低 API 依赖
---
## 12. 对 ZCLAW 的借鉴价值
| DeerFlow 设计 | 借鉴价值 | 实施难度 |
|---------------|----------|----------|
| **中间件链模式** | Agent 执行前的横切关注点模块化ZCLAW Kernel 可引入类似模式 | 中 |
| **渐进式技能加载** | SKILL.md 按需注入而非全量,减少 Token 浪费 | 低 |
| **LLM 驱动记忆提取** | 用 LLM 从对话中提取结构化记忆,比规则提取更鲁棒 | 中 |
| **沙箱虚拟路径** | 统一的路径抽象,代码与平台无关 | 高 |
| **IM 通道架构** | Channel 抽象 + MessageBus 模式,易于扩展新通道 | 低 |
| **模型动态加载** | `use` 字段 + 反射机制,无需硬编码 Provider | 中 |
| **Guardrail 安全护栏** | 工具调用前评估,可配置的拦截策略 | 中 |
**核心差异**: DeerFlow 是 Python 服务端架构ZCLAW 是 Rust + TS 桌面架构。技术栈不同,但在 **Agent 编排模式、技能系统设计、记忆系统架构** 等领域无关的设计层面DeerFlow 提供了成熟的参考。
---
## 13. 项目关键数据
| 指标 | 值 |
|------|-----|
| GitHub Stars | 20k+ (2026-03 Trending #1) |
| License | MIT |
| 主要语言 | Python (后端), TypeScript (前端) |
| Python 版本 | 3.12+ |
| Node.js 版本 | 22+ |
| 后端源文件 | 124 .py (harness) |
| 前端源文件 | 225 .ts/.tsx |
| 测试文件 | 69 .py |
| 内置技能 | 17 个 |
| 支持的 IM | Telegram, Slack, 飞书 |
| 沙箱模式 | Local / Docker / Kubernetes |
| 端口 | 2026 (Nginx), 2024 (LangGraph), 8001 (Gateway), 3000 (Frontend) |
---
*本分析基于 DeerFlow 2.0 main 分支 (截至 2026-03-29) 的源代码和文档。*