evotraders/docs/CRITICAL_FIXES.md

# 关键代码修复方案

## 1. EvoAgent 长期记忆支持 ✅

**状态**: EvoAgent 已支持 `long_term_memory` 参数，但需要移除 Legacy 回退逻辑

**需要修改的文件**:
- `backend/main.py` 第 158-176 行 - 移除记忆启用时的 Legacy 回退
- `backend/core/pipeline.py` - 同样更新
- `backend/core/pipeline_runner.py` - 同样更新

**修复代码** (main.py):
```python
def _create_analyst_agent(...):
    # ... 工具包创建代码 ...
    
    use_evo_agent = analyst_type in _resolve_evo_agent_ids()
    
    if use_evo_agent:
        workspace_dir = skills_manager.get_agent_asset_dir(config_name, analyst_type)
        agent_config = load_agent_workspace_config(workspace_dir / "agent.yaml")
        agent = EvoAgent(
            agent_id=analyst_type,
            config_name=config_name,
            workspace_dir=workspace_dir,
            model=model,
            formatter=formatter,
            skills_manager=skills_manager,
            prompt_files=agent_config.prompt_files,
            long_term_memory=long_term_memory,  # 已支持
            long_term_memory_mode="static_control",
        )
        agent.toolkit = toolkit
        setattr(agent, "workspace_id", config_name)
        return agent
    
    # Legacy fallback (deprecated)
    return AnalystAgent(...)
```

## 2. Workspace ID 语义清理

**问题**: `workspace_id` 同时用于 design-time 和 runtime 两个不同概念

**修复方案**:

```python
# backend/api/workspaces.py
# 明确区分两种资源

# Design-time workspaces (CRUD)
@router.get("/design-workspaces/{workspace_id}/...")
async def get_design_workspace(workspace_id: str): ...

# Runtime runs (只读)
@router.get("/runs/{run_id}/agents/{agent_id}/...")
async def get_runtime_agent(run_id: str, agent_id: str): ...
```

## 3. ToolGuard 与 Gateway 审批同步 ✅ 已完成

**状态**: 审批同步已完善，添加了批量审批支持

**API 端点**:
- `POST /api/guard/check` - 检查工具调用是否需要审批
- `POST /api/guard/approve` - 批准单个工具调用
- `POST /api/guard/approve/batch` - ✅ 批量批准多个工具调用（新增）
- `POST /api/guard/deny` - 拒绝工具调用
- `GET /api/guard/pending` - 获取待审批列表

**批量审批示例**:
```python
# 批量批准
await approve_tool_calls(
    BatchApprovalRequest(
        approval_ids=["approval_001", "approval_002", "approval_003"],
        one_time=True,
    )
)
```

**超时处理**: 默认 300 秒超时，可在 `ToolGuardMixin._init_tool_guard()` 中配置

## 4. Smoke Test 依赖修复

**需要的依赖**:
```bash
pip install pandas numpy matplotlib seaborn
pip install finnhub-python yfinance
pip install loguru rich
pip install websockets
pip install httpx requests
pip install PyYAML
pip install pandas-market-calendars exchange-calendars
```

## 5. 统一 Agent 工厂 ✅ 已完成

**文件** `backend/agents/unified_factory.py`:

统一工厂已创建，支持：
- 所有 6 种 Agent 角色的创建
- 自动 EvoAgent vs Legacy Agent 选择
- Workspace 驱动配置
- 长期记忆支持

```python
from backend.agents.unified_factory import UnifiedAgentFactory, get_agent_factory

# 使用示例
factory = UnifiedAgentFactory(
    config_name="smoke_fullstack",
    skills_manager=skills_manager,
)

# 创建分析师
analyst = factory.create_analyst(
    analyst_type="fundamentals_analyst",
    model=model,
    formatter=formatter,
    long_term_memory=memory,
)
```

## 6. EvoAgent 默认启用

**修改** `backend/config/constants.py`:

```python
# 默认所有角色使用 EvoAgent
DEFAULT_EVO_AGENT_ROLES = {
    "fundamentals_analyst",
    "technical_analyst", 
    "sentiment_analyst",
    "valuation_analyst",
    "risk_manager",
    "portfolio_manager",
}

# EVO_AGENT_IDS 现在用于选择性地禁用 EvoAgent
# 如果设置，只启用指定的角色
# 如果未设置，启用所有角色
```

**修改** `backend/main.py`:
```python
def _resolve_evo_agent_ids() -> set[str]:
    """Return agent ids selected to use EvoAgent.
    
    By default, all supported roles use EvoAgent.
    EVO_AGENT_IDS can be used to limit to specific roles.
    """
    from backend.config.constants import DEFAULT_EVO_AGENT_ROLES
    
    raw = os.getenv("EVO_AGENT_IDS", "")
    if raw.strip():
        # Filter to only valid roles
        requested = {x.strip() for x in raw.split(",") if x.strip()}
        return requested & DEFAULT_EVO_AGENT_ROLES
    
    # Default: all roles use EvoAgent
    return DEFAULT_EVO_AGENT_ROLES
```

## 7. 遗留代码清理

**可以删除的文件**:
- `backend/agents/compat.py` ✅ 已删除
- `frontend/src/hooks/useWebsocketSessionSync.js` ✅ 已删除

**标记为废弃的文件** ✅ 已完成:
- `backend/agents/analyst.py` - 已添加 DeprecationWarning
- `backend/agents/risk_manager.py` - 已添加 DeprecationWarning
- `backend/agents/portfolio_manager.py` - 已添加 DeprecationWarning

## 8. 测试修复

**更新** `backend/tests/test_evo_agent_selection.py`:

移除这些测试 ✅ 已完成:
- `test_main_create_analyst_agent_falls_back_to_legacy_when_memory_enabled`
- `test_main_create_risk_manager_falls_back_to_legacy_when_memory_enabled`
- `test_main_create_portfolio_manager_falls_back_to_legacy_when_memory_enabled`

添加新测试 ✅ 已完成:
- `test_evo_agent_supports_long_term_memory`
- `test_all_roles_use_evo_agent_by_default`

新增集成测试文件 ✅ 已完成:
- `backend/tests/test_evo_agent_integration.py` - 13 个集成测试覆盖 Factory、ToolGuard、Workspace 集成

## 9. 快速修复清单

运行以下命令应用关键修复:

```bash
# 1. 修复 EvoAgent 记忆支持 (修改 main.py, pipeline.py, pipeline_runner.py)
# 移除 long_term_memory 检查导致的 Legacy 回退

# 2. 修复默认 EvoAgent 启用
sed -i 's/def _resolve_evo_agent_ids():/def _resolve_evo_agent_ids() -> set[str]:/' backend/main.py

# 3. 确保所有测试通过
pytest backend/tests/test_evo_agent_selection.py -v

# 4. 运行 smoke test
python3 scripts/smoke_evo_runtime.py --test-all-roles
```

## 10. 实施进度

### ✅ 已完成

| 任务 | 状态 | 文件 |
|------|------|------|
| EvoAgent 长期记忆支持 | ✅ 已完成 | `evo_agent.py`, `main.py` |
| 默认启用所有角色 EvoAgent | ✅ 已完成 | `main.py`, `pipeline.py` |
| 统一 Agent 工厂 | ✅ 已完成 | `unified_factory.py` |
| ToolGuard Gateway 同步 | ✅ 已完成 | `tool_guard.py`, `guard.py` |
| ToolGuard 批量审批 | ✅ 已完成 | `guard.py` |
| 废弃标记 Legacy Agent | ✅ 已完成 | `analyst.py`, `risk_manager.py`, `portfolio_manager.py` |
| 集成测试 | ✅ 已完成 | `test_evo_agent_integration.py` |
| 类型注解 | ✅ 已完成 | `unified_factory.py` |
| Team 基础设施 | ✅ 已完成 | `messenger.py`, `task_delegator.py` |
| Skills 沙盒执行 | ✅ 已完成 | `sandboxed_executor.py` |

### 🚧 待完成

| 优先级 | 任务 | 说明 |
|--------|------|------|
| P0 | Smoke Test 依赖修复 | 需要安装 pandas, finnhub, pandas-market-calendars 等 |
| P1 | Workspace ID 语义清理 | ✅ 已添加 `run_id`，保留 `workspace_id` 用于向后兼容 |
| P2 | 文档完善 | ✅ 已完成 |

*最后更新: 2026-04-02*

---

*文档生成时间: 2026-04-01*