# 代码库结构

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