minion: Instructions file for Claude Code

🧠 记忆存储

系统架构记忆

• never put test in the top level folder

• agent.run_async() 返回的是一个async函数，需要先await才能获得async generator

  • 正确用法: async for event in (await agent.run_async(input_obj, **kwargs)):
  • 错误用法: async for event in agent.run_async(input_obj, **kwargs):
  • 这是因为run_async是async函数，它delegate到其他函数，本身需要await才能返回真正的async generator

• Agent构造函数设计模式

  • 所有Agent应继承BaseAgent并使用@dataclass装饰器
  • 构造函数参数应与BaseAgent对齐，使用dataclass字段而非__init__方法
  • stream相关参数不应在构造函数中，而是通过run_async(stream=True/False)动态控制

• LLM构造和获取最佳实践

  • MinionToolCallingAgent构造时会自动从model配置创建LLM
  • 标准LLM获取模式（参考brain.py）：

    # 方式1：直接指定model名称，从config.models获取配置
    model = "gpt-4o"  # 或其他模型: "gemini-2.0-flash-exp", "deepseek-r1", "phi-4", "llama3.2"
    llm_config = config.models.get(model)
    llm = create_llm_provider(llm_config)
    
    # 方式2：使用默认模型
    llm = create_llm_provider(config.models.get("default"))
    
    # 方式3：在Agent构造时传入model名称，让Agent自动创建
    agent = MinionToolCallingAgent(model="gpt-4o")  # 会自动创建LLM
    
    # 使用dataclass风格构造
    agent = MinionToolCallingAgent(
        name="my_agent",
        tools=[tool1, tool2],
        model="gpt-4o",
        max_tool_threads=4
    )
    

  • Brain类LLM处理逻辑：支持字符串model名称或直接传入LLM实例
    • 如果llm参数是字符串，会调用create_llm_provider(config.models.get(llm))
    • 如果llm参数是LLM实例，直接使用
    • 支持llms字典批量处理多个模型配置

• functions.final_answer调用修复

  • 修复了functions.final_answer()调用不抛异常的问题
  • 问题原因：functions命名空间中的final_answer是原始版本，不会抛出FinalAnswerException
  • 解决方案：在evaluate_async_python_code中创建异常包装器后，同时更新functions命名空间
  • 现在functions.final_answer()和直接调用final_answer()都会正确抛出异常并设置is_final_answer=True

• worker.py终止逻辑修复

  • 修复了Python executor返回is_final_answer=True但任务不终止的问题
  • 问题原因：worker.py获取了is_final_answer值但没有使用，硬编码terminated=False
  • 解决方案：当is_final_answer=True时立即返回terminated=True的AgentResponse
  • 现在final_answer工具调用会正确终止任务执行

• Minion流式处理重构

  • 在基类Minion中添加了stream_node_execution通用方法
  • 所有子类现在使用统一的流式处理逻辑，直接yield StreamChunk对象
  • 移除了错误的final_answer检测逻辑，final_answer处理由LmpActionNode负责
  • 保持StreamChunk对象的原始结构，便于上层UI正确处理不同类型的chunk