evotraders/docs/OPTIMIZATION_PLAN.md

大时代项目优化和功能补齐计划

当前状态评估

已完成的工作

1. ✅ EvoAgent 核心实现 (backend/agents/base/evo_agent.py)
2. ✅ ToolGuardMixin 工具守卫 (backend/agents/base/tool_guard.py)
3. ✅ Hooks 系统 (backend/agents/base/hooks.py)
4. ✅ Smoke test 脚本 (scripts/smoke_evo_runtime.py)
5. ✅ 选择性 EvoAgent 测试 (backend/tests/test_evo_agent_selection.py)
6. ✅ 删除 backend/agents/compat.py 兼容性层
7. ✅ 删除 useWebsocketSessionSync.js 旧钩子

遗留问题清单

🔴 P0: 阻塞 EvoAgent 全面推出

#	问题	位置	影响	解决方案
P0-1	EvoAgent 不支持长期记忆	evo_agent.py:165-166	启用 memory 时回退到 Legacy Agent	集成 ReMe 记忆系统
P0-2	Pipeline 运行时分析师创建路径不一致	pipeline.py	运行时动态创建可能跳过 EvoAgent 路径	统一 _create_runtime_analyst 逻辑
P0-3	Workspace 加载路径混乱	workspace.py, workspace_manager.py	workspace_id vs run_id 语义混合	明确区分 design-time 和 runtime 路径
P0-4	Smoke test 失败排查	scripts/smoke_evo_runtime.py	无法验证 EvoAgent 是否正确启动	修复测试并确保通过

🟡 P1: 功能完善

#	问题	位置	影响	解决方案
P1-1	Team 基础设施未完成	evo_agent.py:41-48	Agent 间通信和任务委托不可用	完成 messenger 和 task_delegator
P1-2	ToolGuard 与 Gateway 审批流程集成	tool_guard.py, api/guard.py	审批状态同步可能不一致	统一审批存储和事件通知
P1-3	Skills 沙盒执行	tools/sandboxed_executor.py	生产环境需要 Docker 隔离	完善沙盒执行器
P1-4	错误处理和重试机制	多处	部分错误未正确处理	添加统一的错误处理

🟢 P2: 代码质量和可维护性

#	问题	位置	影响	解决方案
P2-1	重复的 Agent 创建逻辑	main.py, pipeline.py, pipeline_runner.py	维护困难，容易遗漏	提取统一的 Agent 工厂
P2-2	类型注解不完整	多处	IDE 提示不足	完善类型注解
P2-3	缺少 EvoAgent 集成测试	backend/tests/	无法确保功能完整	添加集成测试
P2-4	文档和注释	多处	新贡献者理解困难	完善文档

---

详细实施方案

Phase 1: P0 阻塞问题修复

P0-1: EvoAgent 长期记忆支持

问题描述:

# main.py 中当前逻辑
if long_term_memory and agent_id not in EVO_AGENT_IDS:
    # 使用 Legacy Agent
else:
    # 使用 EvoAgent

目标: EvoAgent 支持 ReMe 长期记忆系统

实施步骤:

1. 在 EvoAgent.__init__ 中正确接收 long_term_memory 参数
2. 集成 ReMe 记忆系统的读写
3. 在 Hooks 中添加记忆相关的生命周期管理
4. 修改 main.py, pipeline.py 中移除 EvoAgent 的记忆回退逻辑

文件修改:

• backend/agents/base/evo_agent.py
• backend/main.py
• backend/core/pipeline.py

P0-2: Pipeline 运行时分析师创建统一

问题描述: TradingPipeline._create_runtime_analyst 方法需要确保:

1. 检查 EVO_AGENT_IDS 环境变量
2. 正确传递所有必要参数给 EvoAgent
3. 处理 workspace 资产准备

实施步骤:

1. 统一 pipeline.py 和 main.py 中的 Agent 创建逻辑
2. 确保 EvoAgent 路径和 Legacy 路径参数一致
3. 添加运行时动态 Agent 创建的测试

文件修改:

• backend/core/pipeline.py
• backend/main.py

P0-3: Workspace 路径清理

问题描述:

• workspace_id 有时指 workspaces/ 目录下的设计时 workspace
• 有时指 runs/<run_id>/ 下的运行时 workspace

解决方案:

1. 明确命名：design_workspace_id vs run_id
2. 在 API 路由中区分两种资源
3. 内部统一使用 run_id 作为运行时标识

文件修改:

• backend/api/workspaces.py
• backend/api/agents.py
• backend/agents/workspace_manager.py

P0-4: Smoke Test 修复

当前测试:

python3 scripts/smoke_evo_runtime.py --agent-id fundamentals_analyst

验证点:

1. Gateway 正常启动
2. EvoAgent 日志出现
3. runtime_state.json 正确写入
4. 审批流程正常工作

实施步骤:

1. 运行测试并识别失败点
2. 修复 EvoAgent 初始化问题
3. 确保所有 6 个角色都能通过测试

---

Phase 2: P1 功能完善

P1-1: Team 基础设施

当前状态:

try:
    from backend.agents.team.messenger import AgentMessenger
    from backend.agents.team.task_delegator import TaskDelegator
    TEAM_INFRA_AVAILABLE = True
except ImportError:
    TEAM_INFRA_AVAILABLE = False

目标: 完成 Agent 间通信和任务委托

实施步骤:

1. 完成 AgentMessenger 实现
2. 完成 TaskDelegator 实现
3. 添加 Agent 团队协调的测试

P1-2: ToolGuard 与 Gateway 集成

当前状态:

• ToolGuardStore 是内存存储
• Gateway 通过 get_global_runtime_manager() 访问

改进:

1. 确保审批状态在 Gateway 和 Agent 间同步
2. 添加审批超时处理
3. 支持批量审批

P1-3: Skills 沙盒执行

当前状态:

SKILL_SANDBOX_MODE=none  # 开发模式，直接执行

目标: 生产环境使用 Docker 隔离

实施步骤:

1. 完成 DockerSandboxBackend
2. 添加资源限制（CPU、内存、网络）
3. 添加执行超时控制

---

Phase 3: P2 代码质量

P2-1: 统一 Agent 工厂

目标: 提取 AgentFactory 统一处理所有 Agent 创建

设计:

class AgentFactory:
    def create_analyst(self, analyst_type: str, **kwargs) -> BaseAgent
    def create_risk_manager(self, **kwargs) -> BaseAgent
    def create_portfolio_manager(self, **kwargs) -> BaseAgent

P2-2: 类型注解

目标: 所有公共 API 完整的类型注解

P2-3: 集成测试

目标: EvoAgent 完整的端到端测试

---

实施顺序

Week 1: P0 阻塞问题

1. P0-4: 运行 Smoke Test，识别失败点
2. P0-1: EvoAgent 长期记忆支持
3. P0-2: Pipeline 运行时统一
4. P0-3: Workspace 路径清理
5. 验证所有 Smoke Test 通过

Week 2: P1 功能完善

1. P1-1: Team 基础设施
2. P1-2: ToolGuard 集成优化
3. P1-3: Skills 沙盒执行

Week 3: P2 代码质量

1. P2-1: 统一 Agent 工厂
2. P2-2: 类型注解
3. P2-3: 集成测试
4. P2-4: 文档完善

---

成功标准

EvoAgent 全面推出标准

1. ✅ 所有 6 个角色通过 smoke test
2. ✅ 长期记忆功能正常工作
3. ✅ 无需 EVO_AGENT_IDS 环境变量即可使用 EvoAgent
4. ✅ Legacy Agent 代码标记为 deprecated
5. ✅ 集成测试覆盖主要使用场景

架构清理标准

1. ✅ runs/<run_id>/ 是唯一的运行时数据来源
2. ✅ workspaces/ 仅用于设计时注册表
3. ✅ 所有服务边界清晰，无循环依赖
4. ✅ 文档和代码一致

---

风险和对策

风险	可能性	影响	对策
EvoAgent 与 Legacy 行为不一致	中	高	并行运行对比测试
长期记忆集成复杂	中	中	分阶段实现，先支持基础功能
性能下降	低	高	基准测试，性能剖析
迁移期间系统不稳定	中	高	保持 Legacy 作为回退

---

计划创建日期: 2026-04-01 负责: Claude Code