| 依赖与代理 |
go.mod 直接依赖 github.com/cloudwego/eino、eino-ext/.../openai；go.mod 注释与 scripts/bootstrap-go.sh 指导 GOPROXY（如 https://goproxy.cn,direct）。 |
| 配置 |
config.yaml → agent.max_iterations 为全局 ReAct 上限（主/子代理统一）；multi_agent：enabled、robot_use_multi_agent、sub_agents（含可选 bind_role）、eino_skills、eino_middleware 等；结构体见 internal/config/config.go。 |
| Markdown 子代理 / 主代理 |
在 agents_dir 下放 *.md。子代理：供 Deep task 与 supervisor transfer。主代理（按模式分离）：orchestrator.md（或 kind: orchestrator 的单个其他 .md）→ Deep；固定名 orchestrator-plan-execute.md → plan_execute；固定名 orchestrator-supervisor.md → supervisor。正文优先于 YAML：multi_agent.orchestrator_instruction、orchestrator_instruction_plan_execute、orchestrator_instruction_supervisor；plan_execute / supervisor 不会回退到 Deep 的 orchestrator_instruction。皆空时 plan_execute / supervisor 使用代码内置默认提示。管理：Agents → Agent管理；API：/api/multi-agent/markdown-agents*。 |
| MCP 桥 |
internal/einomcp：ToolsFromDefinitions + 会话 ID 持有者，执行走 Agent.ExecuteMCPToolForConversation。 |
| 编排 |
internal/multiagent/runner.go：单代理、Deep 主代理与子代理、Supervisor 主代理与子代理均使用 TypedChatModelAgent[*schema.AgenticMessage] / deep.NewTyped[*schema.AgenticMessage]，再经 adapter 接回现有 adk.Runner / TurnLoop / SSE 边界；plan_execute 的 Executor 也使用 Agentic typed agent，经 adapter 挂入 Eino 官方 planexecute.Config 的经典外层契约。 |
| HTTP |
POST /api/multi-agent（非流式）、POST /api/multi-agent/stream（SSE）；路由常注册，是否可用由运行时 multi_agent.enabled 决定（流式未启用时 SSE 内 error + done）。 |
| 会话准备 |
internal/handler/multi_agent_prepare.go：prepareMultiAgentSession（含 WebShell CreateConversationWithWebshell、工具白名单与单代理一致）。 |
| 单 Agent |
internal/agent 为 MCP/工具层（ToolsForRole、ExecuteMCPToolForConversation）；单代理编排走 RunEinoSingleChatModelAgent（/api/eino-agent*）。 |
| 前端 |
主聊天 / WebShell：Eino 单代理（/api/eino-agent/stream）与 Deep / Plan-Execute / Supervisor（/api/multi-agent/stream + orchestration）；multi_agent.enabled 控制多代理选项是否展示；设置页已暴露 Eino 原生模型 retry/failover 参数，运行态时间线展示 eino_model_retry / eino_model_failover / eino_usage_summary。 |
| 流式兼容 |
Eino 单/多代理与 Web UI 共用 handleStreamEvent：conversation、progress、response_start / response_delta、thinking / thinking_stream_*、tool_*、response、done 等。 |
| 批量任务 |
队列 agentMode 为 deep / plan_execute / supervisor 时子任务带对应 orchestration 调用 RunDeepAgent；旧值 multi 与「agentMode 为空且 batch_use_multi_agent: true」均按 deep。 |
| 配置 API |
GET /api/config 返回 multi_agent 标量与 Eino middleware 可运营字段（含用户输入预算、model_retry_*、model_failover_*、常驻工具白名单）；PUT /api/config 可更新这些字段且不覆盖 sub_agents。 |
| OpenAPI |
多代理路径说明已更新（流式未启用为 SSE 错误事件）。 |
| 机器人 |
ProcessMessageForRobot 按 robot_default_agent_mode（默认 eino_single）调用 RunEinoSingleChatModelAgent 或 RunDeepAgent。 |
| 预置编排 |
聊天 / WebShell：POST /api/multi-agent* 请求体 orchestration：deep | plan_execute | supervisor（缺省 deep）。deep 使用 task 子代理协作；plan_execute 不构建 YAML/Markdown 子代理；plan_execute_loop_max_iterations 仍来自配置；supervisor 至少需一个子代理，只有一个子代理时会提示其专家路由空间有限。 |
| Eino 中间件 |
multi_agent.eino_middleware（可选）：patchtoolcalls（默认开）、toolsearch（按阈值拆分 MCP 工具列表）、plantask（需 eino_skills）、reduction（大工具输出截断/落盘）、checkpoint_dir（Runner 断点）、model_retry_* / model_failover_channels（单代理、Deep、Supervisor 与 plan_execute Executor 均走 Eino 原生 AgenticModel retry/failover）、deep_output_key / task_tool_description_prefix（Deep 与 supervisor 主代理共享其中模型容错与 OutputKey）。Agentic 路径的 patchtoolcalls / toolsearch / plantask / reduction / filesystem / skill / summarization tail 均使用 Eino v0.9.14 官方 typed middleware。plan_execute：Executor 使用 Agentic typed agent，经 adapter 保持官方 Plan/UserInput/ExecutedSteps session contract；Planner/Replanner 仅 summarization tail + prompt 预算截断，不跑 MCP 工具链，因当前 Eino 官方 Planner/Replanner 构造仍是经典 ChatModel 接口。 |
| AgenticMessage 边界 |
internal/multiagent/eino_agentic_message.go 提供 schema.Message ↔ schema.AgenticMessage 的文本、reasoning、函数工具调用、函数工具结果映射；internal/multiagent/eino_agentic_event_adapter.go 将 TypedAgentEvent[*schema.AgenticMessage] 转成现有 SSE/MCP drain 消费的 AgentEvent[*schema.Message]，覆盖 assistant/tool result/stream/error，并保证 Agentic 流式 FunctionToolResult 的 tool name / call id 可被现有 einoToolResultEventHandler 回放、持久化与展示；internal/multiagent/eino_agentic_agent_adapter.go 将 TypedAgent[*schema.AgenticMessage] 包装成现有 adk.Agent / adk.ResumableAgent，使 checkpoint resume、Runner、TurnLoop 与 SSE 边界无需重写；internal/multiagent/eino_agentic_chat_model_agent.go 组装 TypedChatModelAgent[*schema.AgenticMessage]；internal/multiagent/eino_single_runner.go、Deep、Supervisor 生产路径已切到 AgenticModel；internal/multiagent/eino_model_resilience.go 已接入 agenticopenai.ChatModel 工厂、Agentic 原生 ModelRetry 与 ModelFailover 配置，OpenAI/OpenAI-compatible 配置可实际构建 model.AgenticModel；internal/multiagent/eino_middleware.go 已提供 Agentic 官方泛型 patchtoolcalls / toolsearch / plantask / reduction prepender；internal/multiagent/eino_agentic_summarize.go 已把项目领域化摘要策略接入 Eino 原生 summarization.NewTyped[*schema.AgenticMessage]；internal/multiagent/eino_agentic_chat_model_tail_middleware.go 提供 protocol-neutral 的 Agentic typed tail（system 合并、continuation 去重、typed summarization、model-facing trace、model-output guard）。 |
| TurnLoop 接入桥 |
主聊天 Eino 单代理 / 多代理流式路径已通过 WithAgentTurnLoopInterruptRegistrar 启用 Eino 原生 adk.TurnLoop bridge：internal/multiagent/eino_run_trace.go 为每次 Eino run 生成统一 runId，自动注入所有 Eino progress data，并让 einoobserve callbacks 复用同一 id；internal/multiagent/eino_turn_loop_runtime.go 封装会话 item、PushInterruptContinue（WithPreemptTimeout(AnySafePoint, ...)）、idle stop 与 checkpoint 参数；internal/multiagent/eino_turn_loop_iterator_starter.go 统一 runtime 创建、旧 registrar 清理、interrupt/cancel registrar 绑定、idle stop 与 TurnLoop exit 转发；internal/multiagent/eino_runner_iterator_starter.go 统一 Runner fallback 的原生 cancel option、runtime cancel registrar、fresh run checkpoint id 与 resume cancel option；internal/multiagent/eino_checkpoint_runtime.go 统一 checkpoint_dir 规整、store 创建、checkpoint id 与启停日志；internal/multiagent/eino_checkpoint_resume_handler.go 统一 Runner checkpoint preflight、resume 进度事件、resume 调用与失败回退；internal/multiagent/eino_initial_iterator_start_handler.go 统一 checkpoint resume 后的 Runner / TurnLoop fresh start 选择与 TurnLoop takeover 进度事件；internal/multiagent/eino_turn_loop_event_bridge.go 将 TurnLoop OnAgentEvents 显式转发给现有 SSE/MCP drain，并吞掉 preempt 产生的框架级 cancel；internal/multiagent/eino_run_runtime_session.go 统一 Runner/TurnLoop 启动、checkpoint resume、fresh restart、native cancel registrar、run recovery、stream error、completion/cancellation cleanup 与 final result builder；internal/multiagent/eino_run_error_handler.go 统一不可重试 run error 的 pending flush、cancel fallback、timeout、iteration limit 与 error progress；internal/multiagent/eino_run_recovery_handler.go 统一 Eino 原生 retry、context overflow、run-level transient retry 与 fatal fallback 的恢复策略分派；internal/multiagent/eino_stream_error_handler.go 统一 assistant stream recv error 的 interrupt-continue、eino_stream_error、retry 与 partial result 分派；internal/multiagent/eino_run_cancellation_handler.go 统一 iter ctx cancel / interrupt-continue 时的 pending flush、进度事件与 partial result；internal/multiagent/eino_run_completion_handler.go 统一正常完成时 orphan pending flush 与 checkpoint cleanup；internal/multiagent/eino_run_event_drain.go 统一 Runner/TurnLoop 共享的 runMessages、assistantOutput、pending tool calls、stream id、tool-result / assistant-stream / materialized-message handlers 装配；internal/multiagent/eino_run_result_builder.go 统一 partial/final RunResult 构建、model-facing trace 持久化、plan_execute executor 输出优先级与 exit fallback；internal/multiagent/eino_pending_tool_calls.go 抽出 pending tool-call drain state；internal/multiagent/eino_tool_result_progress_emitter.go 统一 tool_result 的 pending 关联、去重、background wait 展示、execute stdout 抑制与 filesystem monitor 更新；internal/multiagent/eino_tool_result_event_handler.go 统一 ADK 流式/非流式 tool result 到 runMessages 与 tool_result 事件的适配；internal/multiagent/eino_assistant_stream_event_handler.go 统一 ADK 流式 assistant 输出到主助手、子代理回复、reasoning 与 tool-call fragments 的 drain；internal/multiagent/eino_materialized_message_event_handler.go 统一 ADK 非流式 message 到 runMessages、reasoning、主/子回复、tool-call 与 tool-result drain；internal/multiagent/eino_stream_tool_call_completion_handler.go 统一流式 assistant tool-call fragments 的合并、pending 标记与 runMessages 持久化；internal/multiagent/eino_execute_stdout_suppressor.go 抽出 execute 输出重复抑制状态；internal/multiagent/eino_message_stream_receiver.go 统一 schema.Message stream 的 ctx cancel / EOF / nil chunk / recv error 处理；internal/multiagent/eino_main_response_stream_emitter.go 统一主助手 response_start/response_delta 与 SSE accumulated 字段；internal/multiagent/eino_main_assistant_stream_handler.go 统一主助手流式正文缓冲、execute 复述去重、最终输出记录与 runMessages 追加；internal/multiagent/eino_main_assistant_complete_handler.go 统一主助手非流式正文的 execute 复述去重、UI 发射与最终输出记录；internal/multiagent/eino_sub_agent_reply_emitter.go 统一子代理 eino_agent_reply(_stream_*) 事件；internal/multiagent/eino_reasoning_stream_emitter.go 统一 reasoning chain 流式/非流式事件与 Claude signature 展示过滤；internal/multiagent/eino_assistant_output_accumulator.go 统一最后助手输出与 plan_execute executor 展示文本记录；internal/multiagent/eino_run_message_accumulator.go 统一事件流累积消息，作为异常重试/partial result 的 Runner/TurnLoop 共享上下文来源；internal/multiagent/eino_run_progress_tracker.go 收敛主/子代理轮次、工具调用去重与 pending 标记状态；internal/multiagent/model_output_recovery_compat.go 仅保留旧 recovery marker 的历史兼容拦截，默认链路不再预改写模型工具调用；internal/multiagent/eino_context_overflow_retry.go 统一上下文超限后的单次激进压缩、restart 上下文选择、SSE 事件与结构化日志；internal/multiagent/eino_transient_run_retry_handler.go 统一 run-level 临时错误退避、pending flush、eino_run_retry 事件与重试耗尽日志；internal/multiagent/eino_native_model_retry_progress.go 统一 Eino 原生 WillRetryError 的 eino_model_retry 事件与结构化日志。“中断并继续”会优先 push 用户补充进 TurnLoop，未注册或 push 失败时回退到 Eino 原生 cancel + trace 续跑链路。context overflow 压缩、run-level transient retry 的 fresh restart 入口已统一为 TurnLoop-aware，避免异常续跑退回普通 Runner。 |