deerflow2/.planning/codebase/ARCHITECTURE.md

# 架构分析

**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*