skills
/
deerflow2
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
deerflow2/.planning/codebase/ARCHITECTURE.md

7.7 KiB
Raw Blame History

架构分析

Analysis Date: 2026-04-07

模式概览

Overall: 分层单体 + 前后端分离 + 运行时内核（Harness）与应用壳层（App）拆分

Key Characteristics:

  • 后端采用 Harness(Core) 与 Gateway/Channels(App) 分层，依赖方向固定为 app.* -> deerflow.*，反向依赖禁止（见 backend/docs/HARNESS_APP_SPLIT.md）
  • 前端采用 Next.js App Router，页面层(src/app)与领域能力层(src/core)分离，UI 组件集中在 src/components
  • 运行时通过单例对象管理（RunManager、StreamBridge、checkpointer、store），由网关生命周期统一初始化（backend/app/gateway/deps.py）

结论： 当前架构边界清晰，后续规划应优先沿“Gateway 负责协议与路由、Harness 负责运行时与智能体能力、Frontend core 负责数据访问”的既有分层扩展，避免跨层直接调用。

分层设计

前端展示与路由层（Next App Router）:

  • Purpose: 负责页面路由、布局装配、页面级 Provider 注入
  • Location: frontend/src/app
  • Contains: layout.tsx、page.tsx、workspace/*、api/* Route Handler
  • Depends on: frontend/src/components、frontend/src/core、frontend/src/server
  • Used by: 浏览器请求与 Next.js 运行时

前端领域能力层（Core）:

  • Purpose: 负责 API 客户端、流式会话、线程管理、上传、设置与 i18n 逻辑
  • Location: frontend/src/core
  • Contains: core/threads/hooks.ts、core/api/api-client.ts、core/*/api.ts|hooks.ts
  • Depends on: @langchain/langgraph-sdk、@tanstack/react-query、后端 API
  • Used by: frontend/src/components/workspace/* 与页面组件

后端 API 网关层（App Gateway）:

  • Purpose: 负责 HTTP 协议适配、路由聚合、SSE 输出、线程与运行生命周期接口
  • Location: backend/app/gateway
  • Contains: app.py、deps.py、services.py、routers/*.py
  • Depends on: deerflow.runtime、deerflow.config、deerflow.agents
  • Used by: 前端、第三方客户端、IM 渠道服务

后端 IM 渠道层（App Channels）:

  • Purpose: 负责飞书/Slack/Telegram 等外部消息通道接入与消息转发
  • Location: backend/app/channels
  • Contains: service.py、manager.py、feishu.py、slack.py、telegram.py
  • Depends on: deerflow 核心能力与 Gateway 配置
  • Used by: 网关生命周期在启动阶段触发（backend/app/gateway/app.py）

后端运行时内核层（Harness）:

  • Purpose: 负责 Agent 构建、Middleware 编排、工具系统、运行时状态与流桥接
  • Location: backend/packages/harness/deerflow
  • Contains: agents/、runtime/、tools/、sandbox/、skills/、models/、config/
  • Depends on: LangChain/LangGraph 与基础设施依赖
  • Used by: backend/app/gateway/* 与潜在 SDK/CLI 调用

关键数据/控制流

Flow 1: Web 会话流式对话（主链路）

  1. 前端聊天页通过 useThreadStream 发起 runs.stream（frontend/src/core/threads/hooks.ts）
  2. LangGraph SDK 客户端调用网关流式接口（frontend/src/core/api/api-client.ts -> /api/langgraph）
  3. Gateway 路由进入 thread_runs.py 或 runs.py，委派 start_run（backend/app/gateway/routers/thread_runs.py, backend/app/gateway/services.py）
  4. start_run 创建 RunRecord 并启动后台任务，运行 make_lead_agent 构建的 Agent 图（backend/packages/harness/deerflow/agents/lead_agent/agent.py）
  5. 运行时事件通过 MemoryStreamBridge 发布，sse_consumer 序列化为 SSE 推送到前端（backend/packages/harness/deerflow/runtime/stream_bridge/memory.py）
  6. 前端 useStream 消费增量状态，刷新消息、标题、子任务与线程列表缓存（frontend/src/core/threads/hooks.ts）

Flow 2: 线程生命周期与状态持久化

  1. 前端线程列表调用 threads.search，线程详情页读取/更新状态（frontend/src/core/threads/hooks.ts）
  2. Gateway threads.py 通过 store + checkpointer 读写线程元数据与 checkpoint
  3. run 完成后，服务层将 checkpoint 中的标题回写线程 store（_sync_thread_title_after_run，backend/app/gateway/services.py）

Flow 3: 前端 API 代理转发（非 LangGraph SDK 路径）

  1. 前端 Route Handler 接收 /api/memory/* 请求（frontend/src/app/api/memory/[...path]/route.ts）
  2. 直接代理至 NEXT_PUBLIC_BACKEND_BASE_URL 对应网关地址
  3. Gateway 处理并返回，前端透明透传响应头与响应体

State Management:

  • 前端 UI 状态：React State + Context（例如 ArtifactsProvider、SubtasksProvider）
  • 前端服务端状态：React Query（线程列表、突变后失效重取）
  • 后端运行状态：RunManager 内存注册表（运行中任务）
  • 后端持久状态：LangGraph checkpointer + store（线程状态、checkpoint、元数据）

关键抽象

Run 生命周期抽象（RunManager + RunRecord）:

  • Purpose: 统一 run 的创建、冲突策略、取消、状态迁移
  • Examples: backend/packages/harness/deerflow/runtime/runs/manager.py
  • Pattern: 内存注册表 + asyncio 锁保护并发一致性

流桥接抽象（StreamBridge）:

  • Purpose: 将后台执行事件转换为可订阅的事件流
  • Examples: backend/packages/harness/deerflow/runtime/stream_bridge/base.py, backend/packages/harness/deerflow/runtime/stream_bridge/memory.py
  • Pattern: 每 run 一条队列 + END/HEARTBEAT 哨兵事件

Agent 组装抽象（make_lead_agent / create_deerflow_agent）:

  • Purpose: 基于配置与上下文动态装配模型、工具与 middleware 链
  • Examples: backend/packages/harness/deerflow/agents/lead_agent/agent.py, backend/packages/harness/deerflow/agents/factory.py
  • Pattern: “配置驱动 + 有序中间件管线 + 条件启用能力”

前端会话编排抽象（useThreadStream）:

  • Purpose: 屏蔽流式协议细节，提供统一发送消息/停止运行/状态更新能力
  • Examples: frontend/src/core/threads/hooks.ts
  • Pattern: Hook 封装 SDK + optimistic UI + query cache 同步

关键入口

Gateway 入口:

  • Location: backend/app/gateway/app.py
  • Triggers: uvicorn app.gateway.app:app（见 backend/Makefile）
  • Responsibilities: 应用启动、router 装配、生命周期内 runtime 单例初始化

Gateway 运行时依赖入口:

  • Location: backend/app/gateway/deps.py
  • Triggers: FastAPI lifespan 调用 langgraph_runtime
  • Responsibilities: 创建/销毁 stream_bridge、checkpointer、store、run_manager

前端根入口:

  • Location: frontend/src/app/layout.tsx
  • Triggers: Next.js App Router 根布局渲染
  • Responsibilities: 注入主题与 i18n Provider

前端工作台入口:

  • Location: frontend/src/app/workspace/layout.tsx, frontend/src/app/workspace/chats/[thread_id]/page.tsx
  • Triggers: 访问 /workspace/*
  • Responsibilities: QueryClient 注入、侧边栏控制、聊天线程交互

错误处理策略

Strategy: 分层兜底 + 协议一致化

Patterns:

  • 路由层用 HTTP 状态码表达失败，依赖层缺失返回 503（backend/app/gateway/deps.py）
  • 流式执行失败统一在服务层记录并通过 SSE/最终状态输出（backend/app/gateway/services.py）
  • 前端流式错误统一 toast 呈现并清理 optimistic 状态（frontend/src/core/threads/hooks.ts）

跨切面关注点

Logging: 后端在网关入口统一配置 logging，模块内按 logger 输出（backend/app/gateway/app.py） Validation: 请求模型使用 Pydantic；运行配置做字段规整（如 normalize_stream_modes、build_run_config） Authentication: 前端通过 better-auth 路由处理认证（frontend/src/app/api/auth/[...all]/route.ts, frontend/src/server/better-auth/*）；网关核心 API 当前以部署侧网关/Nginx 控制为主

Architecture analysis: 2026-04-07