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):

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 两个不同概念

修复方案:

# 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 - 获取待审批列表

批量审批示例:

# 批量批准
await approve_tool_calls(
    BatchApprovalRequest(
        approval_ids=["approval_001", "approval_002", "approval_003"],
        one_time=True,
    )
)

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

4. Smoke Test 依赖修复

需要的依赖:

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 驱动配置
• 长期记忆支持

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:

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

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

修改 backend/main.py:

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. 快速修复清单

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

# 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