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

6.8 KiB
Raw Blame History

代码库结构

Analysis Date: 2026-04-07

目录布局

deerflow2/
├── backend/                        # Python 后端（Gateway + Harness workspace）
│   ├── app/                        # 应用壳层：HTTP Gateway、IM channels
│   ├── packages/harness/deerflow/  # 运行时内核：agent/runtime/tools/sandbox
│   ├── tests/                      # 后端测试
│   └── pyproject.toml              # 后端 workspace 定义
├── frontend/                       # Next.js 前端（App Router）
│   ├── src/app/                    # 页面与路由入口
│   ├── src/components/             # UI 与业务组件
│   ├── src/core/                   # 领域能力层（API/hooks/types）
│   ├── src/server/                 # 服务端能力（auth）
│   └── tests/                      # 前端 E2E 测试
├── docker/                         # 部署与网关编排
├── docs/                           # 项目文档
├── scripts/                        # 开发与部署脚本
└── skills/                         # 技能资源（public skills）

目录职责

backend/app:

  • Purpose: 面向产品的 API/协议层，不承载核心 agent 组装逻辑
  • Contains: gateway/app.py、gateway/routers/*.py、channels/*.py
  • Key files: backend/app/gateway/app.py, backend/app/gateway/services.py, backend/app/channels/service.py

backend/packages/harness/deerflow:

  • Purpose: 可复用内核层，封装智能体运行时与能力模块
  • Contains: agents/, runtime/, tools/, sandbox/, skills/, models/, config/
  • Key files: backend/packages/harness/deerflow/agents/lead_agent/agent.py, backend/packages/harness/deerflow/runtime/runs/manager.py, backend/packages/harness/deerflow/runtime/stream_bridge/memory.py

frontend/src/app:

  • Purpose: Next.js 路由与页面入口，组合 UI 与 core 能力
  • Contains: 根布局、workspace 页面、docs 页面、API route handlers
  • Key files: frontend/src/app/layout.tsx, frontend/src/app/workspace/layout.tsx, frontend/src/app/workspace/chats/[thread_id]/page.tsx

frontend/src/components:

  • Purpose: 可复用 UI 组件与工作台业务组件
  • Contains: ui/*, workspace/*, landing/*, ai-elements/*
  • Key files: frontend/src/components/workspace/workspace-container.tsx, frontend/src/components/workspace/chats/use-thread-chat.ts

frontend/src/core:

  • Purpose: 前端领域逻辑层，统一管理数据访问、hook 与类型
  • Contains: threads/, api/, memory/, models/, skills/, uploads/, settings/
  • Key files: frontend/src/core/threads/hooks.ts, frontend/src/core/api/api-client.ts, frontend/src/core/config/index.ts

关键文件位置

Entry Points:

  • backend/app/gateway/app.py: FastAPI 入口与路由总装
  • frontend/src/app/layout.tsx: 前端根布局入口
  • frontend/src/app/page.tsx: Landing 页面入口
  • frontend/src/app/workspace/page.tsx: 工作台入口重定向

Configuration:

  • backend/pyproject.toml: Python 依赖与 workspace
  • frontend/package.json: 前端依赖与脚本
  • frontend/tsconfig.json: TS 编译策略与 @/* 别名
  • frontend/next.config.js: Next 构建输出与运行参数
  • config.yaml: 运行配置主文件（存在，勿在规划文档中记录敏感值）

Core Logic:

  • backend/app/gateway/services.py: run 生命周期业务逻辑与 SSE 格式化
  • backend/app/gateway/routers/thread_runs.py: 线程 run 协议接口
  • backend/packages/harness/deerflow/agents/lead_agent/agent.py: 主 Agent 构建逻辑
  • backend/packages/harness/deerflow/runtime/runs/manager.py: run 状态机与并发控制
  • frontend/src/core/threads/hooks.ts: 流式会话、线程列表、突变逻辑
  • frontend/src/core/api/api-client.ts: LangGraph SDK 客户端封装

Testing:

  • backend/tests/*.py: 后端单元/集成测试
  • frontend/tests/e2e/*: 前端端到端测试（Playwright）
  • frontend/src/core/**/*.{test.ts,test.mjs}: 前端核心逻辑单测

命名约定

Files:

  • 前端组件文件：kebab-case.tsx（示例：workspace-container.tsx）
  • 前端 Hook 文件：use-*.ts 或 hooks.ts（示例：use-thread-chat.ts, threads/hooks.ts）
  • 后端 Python 文件：snake_case.py（示例：thread_runs.py, memory_middleware.py）
  • 路由文件：按资源名命名（示例：routers/threads.py, routers/models.py）

Directories:

  • 前端按职责分层：app（路由）/components（视图）/core（领域）
  • 后端按边界分层：app（应用层）/packages/harness/deerflow（内核层）

新增代码放置规则（可执行）

新增后端 API 端点：

  • 路由定义: backend/app/gateway/routers/{resource}.py
  • 复用业务逻辑: 优先放 backend/app/gateway/services.py 或同级 {resource}_service.py
  • 依赖获取: 统一通过 backend/app/gateway/deps.py

新增 Agent/运行时能力：

  • Agent 相关: backend/packages/harness/deerflow/agents/*
  • 运行时状态/流: backend/packages/harness/deerflow/runtime/*
  • 工具能力: backend/packages/harness/deerflow/tools/* 或 community/*
  • 规则: 不在 backend/app/* 写核心算法/agent 编排逻辑

新增前端业务功能：

  • 页面入口: frontend/src/app/{route}/page.tsx
  • 业务组件: frontend/src/components/workspace/*（工作台）或对应域目录
  • 数据访问与副作用: frontend/src/core/{domain}/api.ts|hooks.ts|types.ts
  • 规则: 页面层只做组合，不直接实现复杂 API 调用细节

新增 Next API 代理：

  • 放置于 frontend/src/app/api/{resource}/route.ts 或 [...path]/route.ts
  • 代理逻辑复用现有 proxyRequest 模式（参考 frontend/src/app/api/memory/[...path]/route.ts）

新增测试：

  • 后端: backend/tests/test_{feature}.py
  • 前端 core 单测: 与实现文件同目录 *.test.ts|*.test.mjs
  • 前端 E2E: frontend/tests/e2e/{feature}.spec.ts

特殊目录说明

backend/src:

  • Purpose: 旧路径兼容目录（当前主要为 __pycache__）
  • Generated: Yes（当前内容以缓存文件为主）
  • Committed: Yes（目录存在于仓库）
  • Guidance: 新代码不要放在 backend/src，统一落到 backend/packages/harness/deerflow 或 backend/app

frontend/.next 与 frontend/node_modules:

  • Purpose: 构建产物与依赖缓存
  • Generated: Yes
  • Committed: No（应视为构建输出）

.planning/codebase:

  • Purpose: 供后续规划/执行代理读取的代码库认知文档
  • Generated: Yes（由 map 阶段生成）
  • Committed: Yes（作为流程资产）

结论： 该仓库最重要的结构约束是“后端 Harness 与 App 分层 + 前端 app/components/core 三段分层”。后续新增功能应优先沿既有目录职责扩展，避免把核心逻辑散落到路由层或页面层。

Structure analysis: 2026-04-07