145 lines
6.8 KiB
Markdown
145 lines
6.8 KiB
Markdown
# 代码库结构
|
||
|
||
**Analysis Date:** 2026-04-07
|
||
|
||
## 目录布局
|
||
|
||
```text
|
||
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*
|