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

## 当前状态评估

### 已完成的工作
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 长期记忆支持

**问题描述**:
```python
# 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 修复

**当前测试**:
```bash
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 基础设施

**当前状态**:
```python
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 沙盒执行

**当前状态**:
```python
SKILL_SANDBOX_MODE=none  # 开发模式，直接执行
```

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

**实施步骤**:
1. 完成 `DockerSandboxBackend`
2. 添加资源限制（CPU、内存、网络）
3. 添加执行超时控制

---

### Phase 3: P2 代码质量

#### P2-1: 统一 Agent 工厂

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

**设计**:
```python
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*