mirror of
https://gitee.com/wanwujie/deer-flow
synced 2026-04-03 06:12:14 +08:00
feat: fix todos (#9)
This commit is contained in:
DanielWalnut
@@ -1,125 +0,0 @@
|
||||
# DeerFlow Backend TODO List
|
||||
|
||||
## 📋 项目概述
|
||||
|
||||
DeerFlow Backend 是一个基于 LangGraph 的 AI Agent 框架，采用配置驱动架构，支持多种 Sandbox 实现和工具扩展。
|
||||
|
||||
## 🚨 高优先级问题 (P0)
|
||||
|
||||
### 1. LocalSandboxProvider 返回类型不一致
|
||||
**文件**: `src/sandbox/local/local_sandbox_provider.py`
|
||||
**问题**:
|
||||
- `acquire()` 声明返回 `Sandbox` 但实际返回 `str`
|
||||
- `get()` 声明返回 `None` 但实际返回 `LocalSandbox`
|
||||
**影响**: 类型安全破坏，IDE 检查报错
|
||||
**解决方案**: 修正方法签名，确保与抽象基类契约一致
|
||||
|
||||
### 2. Sandbox 资源泄漏风险
|
||||
**文件**: `src/sandbox/middleware.py`
|
||||
**问题**:
|
||||
- 只有 `before_agent` 获取 sandbox
|
||||
- 没有 `after_agent` 释放机制
|
||||
- `LocalSandboxProvider.release()` 是空实现
|
||||
**影响**: 资源泄漏，Docker 容器堆积
|
||||
**解决方案**: 实现完整的生命周期管理
|
||||
|
||||
## 🟡 中优先级问题 (P1)
|
||||
|
||||
### 3. 硬编码路径和个人信息 ✅ 已完成
|
||||
**文件**: `src/agents/lead_agent/prompt.py`
|
||||
**问题**:
|
||||
- `MOUNT_POINT = "/Users/henry/mnt"`
|
||||
- 个人信息出现在系统提示中
|
||||
**影响**: 可移植性差，违反配置分离原则
|
||||
**解决方案**: 移至配置文件中
|
||||
|
||||
### 4. 异常处理过于简单
|
||||
**文件**: `src/sandbox/tools.py`
|
||||
**问题**: 所有异常被吞掉，缺乏结构化错误信息
|
||||
**影响**: 调试困难，用户体验差
|
||||
**解决方案**: 实现分层异常处理机制
|
||||
|
||||
### 5. 全局单例缺乏生命周期管理
|
||||
**文件**: `src/config/app_config.py`, `src/sandbox/sandbox_provider.py`
|
||||
**问题**: 全局变量难以测试，无法重新加载配置
|
||||
**影响**: 可测试性差，多线程风险
|
||||
**解决方案**: 引入依赖注入或 ContextVar
|
||||
|
||||
## 🟢 低优先级问题 (P2)
|
||||
|
||||
### 6. 缺乏异步支持
|
||||
**文件**: `src/community/aio_sandbox/aio_sandbox.py`
|
||||
**问题**: 所有操作都是同步的
|
||||
**影响**: 并发性能受限
|
||||
**解决方案**: 添加 async/await 支持
|
||||
|
||||
### 7. 配置验证不足
|
||||
**文件**: `src/config/model_config.py`
|
||||
**问题**: `extra="allow"` 允许任意字段
|
||||
**影响**: 配置错误难以发现
|
||||
**解决方案**: 使用 `extra="forbid"` 并添加验证器
|
||||
|
||||
### 8. 工具配置重复定义
|
||||
**文件**: `config.yaml` 和 `src/community/tavily/tools.py`
|
||||
**问题**: 同名工具在不同地方定义
|
||||
**影响**: 配置切换混淆
|
||||
**解决方案**: 使用唯一名称或别名机制
|
||||
|
||||
## 🔧 架构优化建议
|
||||
|
||||
### 9. 自动 Thread Title 生成 ✅ 已完成
|
||||
**目的**: 自动为对话线程生成标题
|
||||
**实现**:
|
||||
- 使用 `TitleMiddleware` 在首次对话后自动生成 title
|
||||
- Title 存储在 `ThreadState.title` 中（而非 metadata）
|
||||
- 支持通过 checkpointer 持久化
|
||||
- 详见 [AUTO_TITLE_GENERATION.md](docs/AUTO_TITLE_GENERATION.md)
|
||||
|
||||
### 10. 引入依赖注入容器
|
||||
**目的**: 改善可测试性和模块化
|
||||
**实现**: 创建 `di.py` 提供类型安全的依赖管理
|
||||
|
||||
### 11. 添加健康检查接口
|
||||
**目的**: 监控系统状态
|
||||
**实现**: 创建 `health.py` 提供系统健康状态检查
|
||||
|
||||
### 12. 增加结构化日志
|
||||
**目的**: 改善可观测性
|
||||
**实现**: 集成 `structlog` 提供结构化日志输出
|
||||
|
||||
## 📊 实施计划
|
||||
|
||||
### Phase 1: 安全与稳定性 (Week 1-2)
|
||||
- [ ] 修复 LocalSandboxProvider 类型问题
|
||||
- [ ] 实现 Sandbox 生命周期管理
|
||||
- [ ] 添加异常处理机制
|
||||
|
||||
### Phase 2: 架构优化 (Week 3-4)
|
||||
- [ ] 引入依赖注入
|
||||
- [ ] 添加健康检查
|
||||
- [ ] 实现配置验证
|
||||
- [ ] 移除硬编码路径
|
||||
|
||||
### Phase 3: 性能与扩展性 (Week 5-6)
|
||||
- [ ] 添加异步支持
|
||||
- [ ] 实现结构化日志
|
||||
- [ ] 优化工具配置管理
|
||||
|
||||
## 🎯 成功标准
|
||||
|
||||
- ✅ 所有类型检查通过
|
||||
- ✅ 配置可安全共享
|
||||
- ✅ 资源管理无泄漏
|
||||
- ✅ 异常处理完善
|
||||
- ✅ 测试覆盖率提升
|
||||
- ✅ 部署配置标准化
|
||||
|
||||
## 📝 备注
|
||||
|
||||
- 优先处理高优先级问题，确保系统稳定性和安全性
|
||||
- 中优先级问题影响开发体验和可维护性
|
||||
- 低优先级问题可在系统稳定后逐步优化
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-01-14*
|
||||
76
backend/docs/SETUP.md
Normal file
76
backend/docs/SETUP.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Setup Guide
|
||||
|
||||
Quick setup instructions for DeerFlow.
|
||||
|
||||
## Configuration Setup
|
||||
|
||||
DeerFlow uses a YAML configuration file that should be placed in the **project root directory**.
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Navigate to project root**:
|
||||
```bash
|
||||
cd /path/to/deer-flow
|
||||
```
|
||||
|
||||
2. **Copy example configuration**:
|
||||
```bash
|
||||
cp config.example.yaml config.yaml
|
||||
```
|
||||
|
||||
3. **Edit configuration**:
|
||||
```bash
|
||||
# Option A: Set environment variables (recommended)
|
||||
export OPENAI_API_KEY="your-key-here"
|
||||
|
||||
# Option B: Edit config.yaml directly
|
||||
vim config.yaml # or your preferred editor
|
||||
```
|
||||
|
||||
4. **Verify configuration**:
|
||||
```bash
|
||||
cd backend
|
||||
python -c "from src.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **Location**: `config.yaml` should be in `deer-flow/` (project root), not `deer-flow/backend/`
|
||||
- **Git**: `config.yaml` is automatically ignored by git (contains secrets)
|
||||
- **Priority**: If both `backend/config.yaml` and `../config.yaml` exist, backend version takes precedence
|
||||
|
||||
## Configuration File Locations
|
||||
|
||||
The backend searches for `config.yaml` in this order:
|
||||
|
||||
1. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
|
||||
2. `backend/config.yaml` (current directory when running from backend/)
|
||||
3. `deer-flow/config.yaml` (parent directory - **recommended location**)
|
||||
|
||||
**Recommended**: Place `config.yaml` in project root (`deer-flow/config.yaml`).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Config file not found
|
||||
|
||||
```bash
|
||||
# Check where the backend is looking
|
||||
cd deer-flow/backend
|
||||
python -c "from src.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
|
||||
```
|
||||
|
||||
If it can't find the config:
|
||||
1. Ensure you've copied `config.example.yaml` to `config.yaml`
|
||||
2. Verify you're in the correct directory
|
||||
3. Check the file exists: `ls -la ../config.yaml`
|
||||
|
||||
### Permission denied
|
||||
|
||||
```bash
|
||||
chmod 600 ../config.yaml # Protect sensitive configuration
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configuration Guide](docs/CONFIGURATION.md) - Detailed configuration options
|
||||
- [Architecture Overview](CLAUDE.md) - System architecture
|
||||
11
backend/docs/TODO.md
Normal file
11
backend/docs/TODO.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# TODO List
|
||||
|
||||
## Features
|
||||
|
||||
[ ] Launch the sandbox only after the first file system or bash tool is called
|
||||
[ ] Pooling the sandbox resources to reduce the number of sandbox containers
|
||||
|
||||
## Issues
|
||||
|
||||
[x] Make sure that no duplicated files in `state.artifacts`
|
||||
[ ] Long thinking but with empty content (answer inside thinking process)
|
||||
Reference in New Issue
Block a user