beaver_project/docs/superpowers/specs/2026-06-26-local-mcp-team-workflows-design.md

Local MCP Team Workflow Tools Clean Architecture

0. 结论

Agent Team 重新收口成一个干净模型：

用户任务
→ Root AgentLoop
→ 选择一个本地常驻 Workflow MCP Tool
→ Workflow Tool 接收 agents / instructions / 必要结构参数
→ Workflow Tool 内部生成 ExecutionGraph
→ Scheduler 启动多个平级 AgentLoop
→ 汇总 Team 结果

不再让 Planner 或 Agent 自由生成复杂 DAG。

不再把 run_agent_team 作为主入口。

不再把 Skill 里的 beaver-team-template 当成执行图模板。

最终目标是：

Workflow 是工具
Agent 只填槽
结构由代码生成
ExecutionGraph 是内部 IR
所有 agent 都是平级 AgentLoop

---

1. 架构原则

1.1 没有特殊 Main Agent

系统里只有 AgentLoop。

产品文案上可以说“当前会话 agent”或“root agent”，但代码和架构里不再把它设计成特殊 Main Agent。

Root AgentLoop
Worker AgentLoop
Aggregator AgentLoop
Validator AgentLoop

这些都是同一种执行单元。

区别只来自：

输入任务不同
上下文不同
可见 Skill 不同
可见工具不同
dependency_outputs 不同

1.2 Planner 不再负责 Team DAG

TaskExecutionPlanner 不再是 Agent Team 的入口。

它不再负责输出：

mode = team
strategy
nodes
depends_on
ExecutionGraph

如果还保留 Planner，它只能做非 Team 核心逻辑，例如：

创建 Task 前的轻量判断
任务标题 / 摘要
上下文提示
legacy 迁移期兼容

但它不能再是“Team 是否启动”和“Team 图怎么连”的权威来源。

1.3 run_agent_team 不再是主入口

旧路径：

AgentLoop
→ run_agent_team({strategy, nodes, depends_on})
→ Planner.from_json()
→ ExecutionGraph

新路径：

AgentLoop
→ SequentialWorkflow(...)
→ workflow code builds ExecutionGraph

或：

AgentLoop
→ GraphWorkflow(...)
→ graph.py validates edges
→ workflow code builds ExecutionGraph

run_agent_team 可以在迁移期保留为隐藏兼容工具，但不进入新设计目标，不应该继续作为 root AgentLoop 的推荐工具。

1.4 Skill 不再携带可执行 DAG

旧设计：

SKILL.md
→ beaver-team-template
→ Planner adapts template
→ ExecutionGraph

新设计：

SKILL.md
→ workflow guidance
→ Root AgentLoop reads guidance
→ Root AgentLoop calls Workflow Tool

Skill 的职责是指导 Agent：

应该选哪个 workflow tool
应该创建哪些 agents
每个 agent 应该做什么
哪些 agent 需要 use_skill / skill_query
输出边界是什么

Skill 不再直接定义 runtime DAG。

1.5 ExecutionGraph 是内部 IR

ExecutionGraph / ExecutionNode 继续保留。

但它们的定位变成：

runtime intermediate representation

也就是：

LLM 不直接写 ExecutionGraph
Skill 不直接写 ExecutionGraph
前端不直接编辑 ExecutionGraph
Workflow tool 内部生成 ExecutionGraph
Scheduler 执行 ExecutionGraph

这样可以保留已有调度器和 evidence gate，同时把“图的正确性”从 LLM 输出转移到代码。

---

2. 新执行链路

2.1 单 Agent 任务

用户输入
→ 创建 Task
→ Root AgentLoop
→ Skill / ToolAssembler 装载普通工具
→ Agent 直接调用普通工具或直接回答
→ Task 完成

这种场景不进入 Team。

2.2 Team 任务

用户输入
→ 创建 Task
→ Root AgentLoop
→ Skill guidance 告诉它适合哪个 workflow
→ Root AgentLoop 调用本地 Workflow MCP Tool
→ Workflow Tool 解析 agents / instructions
→ Workflow Tool 生成 ExecutionGraph
→ TeamService / Scheduler 执行 graph
→ 每个 node 启动一个 Worker AgentLoop
→ Worker AgentLoop 选择或绑定 Skill
→ Worker AgentLoop 调用工具并产出 evidence
→ Scheduler 根据 graph / evidence 决定继续或阻断
→ Aggregator / final synthesis 汇总
→ Task 完成或 incomplete

2.3 多 Agent 不是多角色

不要把 workflow agents 理解成固定角色 Agent。

它们不是：

researcher
writer
reviewer
analyst

它们只是当前 workflow 的工作节点：

source_collector
metric_extractor
validator
reporter

每个节点仍然是：

AgentDescriptor(role="")
metadata["sub_agent_kind"] = "generic_skill_worker"

role="" 只是为了兼容现有 dataclass 字段，不代表固定角色。

---

3. Root AgentLoop 能看到什么

Root AgentLoop 看到的是：

用户任务
会话上下文
已激活 Skill guidance
普通工具
本地常驻 Team Workflow MCP tools

示例工具：

web_search
web_fetch
skill_view
...
SequentialWorkflow
ConcurrentWorkflow
MixtureOfAgents
AgentRearrange
GraphWorkflow

如果当前 MCP wrapper 仍带 server 前缀，实际名字可能是：

mcp_local_team_workflow_mcp_SequentialWorkflow
mcp_local_team_workflow_mcp_GraphWorkflow

但产品目标应该是让 Agent 看到短名字：

SequentialWorkflow
GraphWorkflow

Root AgentLoop 不应该看到或输出：

TaskExecutionPlanner JSON
ExecutionGraph JSON
free-form depends_on DAG
researcher / writer / reviewer role agents

---

4. Worker AgentLoop 能看到什么

Workflow Tool 生成 ExecutionGraph 后，Scheduler 会按 node 启动 Worker AgentLoop。

每个 Worker AgentLoop 看到：

当前 node instruction
上游 dependency outputs
当前 node 的 pinned SkillContext
当前 node 的 skill_query fallback
Skill / ToolAssembler 装载出的工具
allowed_tool_names safety scope
required_evidence / validation_rules / evidence_contract

Worker AgentLoop 默认不应该看到 Team Workflow tools。

原因：

避免 nested Team
避免一个 worker 再启动另一个 workflow
避免 timeline / evidence ownership 混乱

如果未来要支持 nested workflow，需要独立设计，不进入 v1。

---

5. allowed_tool_names 的准确语义

allowed_tool_names 不是工具来源。

工具来源仍然是：

Skill
ToolAssembler
AgentLoop 的正常工具装载机制

allowed_tool_names 只是安全上限：

effective_tools = assembled_tools ∩ allowed_tool_names

三态：

None
→ 不启用 node-level scope
→ 保留原工具装载行为

[]
→ 显式禁止该 node 使用任何工具

["web_search", "web_fetch"]
→ 只允许已装载工具里的 web_search / web_fetch 通过

Workflow Tool 可以把这个字段写进 ExecutionNode，但不能用它凭空暴露工具。

---

6. Workflow Tools

6.1 设计原则

每种 workflow 是一个工具。

不是：

run_swarm_workflow({architecture: "sequential"})

而是：

SequentialWorkflow(...)
ConcurrentWorkflow(...)
MixtureOfAgents(...)
GraphWorkflow(...)

这样 LLM 的选择难度更低：

先选工具
再填工具 schema

而不是：

先选 architecture 字符串
再猜不同 architecture 需要哪些字段

6.2 v1 实现范围

v1 实现：

SequentialWorkflow
ConcurrentWorkflow
MixtureOfAgents
AgentRearrange
GraphWorkflow

v1 不实现或只占位：

GroupChat
HierarchicalSwarm
ForestSwarm
dynamic team expansion

原因：

GroupChat 需要多轮 conversation state
HierarchicalSwarm 需要 manager 动态拆分任务
ForestSwarm 接近动态多图执行

这些不适合和第一版稳定 workflow tool 混在一起。

6.3 SequentialWorkflow

输入：

{
  "task": "比较 MGM China 和 Galaxy Entertainment，输出中文财务报告",
  "agents": [
    {"name": "source_collector", "instruction": "收集官方财务披露来源"},
    {"name": "metric_extractor", "instruction": "提取可比财务指标"},
    {"name": "validator", "instruction": "校验周期、币种、单位、来源一致性"},
    {"name": "reporter", "instruction": "生成中文报告、对比表和 chart-ready data"}
  ]
}

内部生成：

source_collector
→ metric_extractor
→ validator
→ reporter

6.4 ConcurrentWorkflow

输入：

{
  "task": "从多个独立角度调研同一主题",
  "agents": [
    {"name": "official_sources", "instruction": "查官方资料"},
    {"name": "media_sources", "instruction": "查媒体报道"},
    {"name": "data_sources", "instruction": "查数据来源"}
  ]
}

内部生成：

official_sources ∥ media_sources ∥ data_sources

只能用于真正互不依赖的工作。

不能用于：

先搜索事实，再基于事实做多个分析

这种要用 GraphWorkflow 或 MixtureOfAgents。

6.5 MixtureOfAgents

输入：

{
  "task": "对一个问题做多角度分析并汇总",
  "agents": [
    {"name": "tactics", "instruction": "分析战术"},
    {"name": "players", "instruction": "分析球员表现"},
    {"name": "media", "instruction": "分析媒体舆论"}
  ],
  "aggregator": {
    "name": "synthesizer",
    "instruction": "合并所有分析，输出中文结构化报告"
  }
}

内部生成：

tactics ┐
players ├→ synthesizer
media   ┘

6.6 AgentRearrange

输入：

{
  "task": "先收集，再多角度分析，再汇总",
  "agents": [
    {"name": "collector", "instruction": "收集事实"},
    {"name": "tactics", "instruction": "分析战术"},
    {"name": "players", "instruction": "分析球员"},
    {"name": "media", "instruction": "分析舆论"},
    {"name": "synthesizer", "instruction": "汇总报告"}
  ],
  "flow": "collector -> tactics, players, media -> synthesizer"
}

flow 是结构参数，不是自然语言说明。

必须严格解析：

节点必须存在
不允许未知节点
不允许环
不允许无法到达输出节点

6.7 GraphWorkflow

输入：

{
  "task": "分析韩国队今早世界杯比赛表现",
  "agents": [
    {"name": "collector", "instruction": "收集比赛事实、比分、关键事件和来源"},
    {"name": "tactics", "instruction": "基于 collector 结果分析战术"},
    {"name": "players", "instruction": "基于 collector 结果分析球员表现"},
    {"name": "media", "instruction": "基于 collector 结果分析媒体舆论"},
    {"name": "synthesizer", "instruction": "合并所有分析，输出中文报告"}
  ],
  "edges": [
    ["collector", "tactics"],
    ["collector", "players"],
    ["collector", "media"],
    ["tactics", "synthesizer"],
    ["players", "synthesizer"],
    ["media", "synthesizer"]
  ],
  "output_agent": "synthesizer"
}

这是唯一 v1 允许直接暴露 edges 的工具。

必须校验：

edges 必填
edge 两端 agent 必须存在
不允许 cycle
output_agent 必须存在
output_agent 必须可达
不能有无意义孤岛，除非显式 allow_disconnected=true

---

7. Skill 里的 Team 指导怎么写

7.1 Skill 的新职责

Skill 不再写执行 DAG。

Skill 写的是：

什么时候使用 Team
推荐哪个 Workflow Tool
每个 agent slot 怎么填
每个 agent 需要什么 Skill
每个 agent 的工具安全上限
输出边界

7.2 示例：MGM / Galaxy finance skill

# MGM / Galaxy Financial Comparison Report

Use this skill when the user asks for a financial comparison report comparing
MGM China and Galaxy Entertainment.

Recommended workflow:

- Use `SequentialWorkflow` for ordinary finance comparison reports.
- Use `GraphWorkflow` only if the user asks for multiple independent analysis branches.

When using `SequentialWorkflow`, create agents in this order:

1. `source_collector`
   - instruction: Collect official MGM China and Galaxy Entertainment disclosures.
   - skill_query: official web search and web fetch.
   - allowed_tool_names: web_search, web_fetch.

2. `metric_extractor`
   - instruction: Extract comparable financial metrics from collected sources.

3. `validator`
   - instruction: Validate period, currency, unit, source, and metric definitions.

4. `reporter`
   - instruction: Generate Chinese Markdown report, comparison table, and chart-ready data.

Output boundary:

- Allowed: Markdown table, chart-ready data, Mermaid, text bar chart fallback.
- Not allowed: generated chart image, generated chart file, saved chart artifact.

7.3 可选结构化 guidance block

建议新 block：

```beaver-team-workflow
{
  "version": 1,
  "preferred_tool": "SequentialWorkflow",
  "agents": [
    {
      "name": "source_collector",
      "instruction": "Collect official MGM China and Galaxy Entertainment disclosures.",
      "skill_query": "official web search financial filings",
      "allowed_tool_names": ["web_search", "web_fetch"]
    },
    {
      "name": "metric_extractor",
      "instruction": "Extract comparable financial metrics from collected sources."
    },
    {
      "name": "validator",
      "instruction": "Validate period, currency, unit, source, and metric definitions."
    },
    {
      "name": "reporter",
      "instruction": "Generate Chinese Markdown report, comparison table, and chart-ready data."
    }
  ],
  "output_boundary": {
    "allow": ["markdown_table", "chart_ready_data", "mermaid", "text_bar_chart"],
    "deny": ["generated_chart_image", "generated_chart_file", "saved_chart_artifact"]
  }
}
```

这个 block 不是执行图。

它只是 root AgentLoop 的 workflow tool-call guidance。

---

8. 代码存放位置

8.1 新增目录

app-instance/backend/beaver/team_workflows/
  __init__.py
  base.py
  mcp_tools.py
  sequential.py
  concurrent.py
  mixture_of_agents.py
  agent_rearrange.py
  graph.py

v2 再考虑：

  group_chat.py
  hierarchical.py
  forest.py

8.2 base.py

负责公共结构：

WorkflowAgentSpec
WorkflowGraphBuilder
WorkflowExecutionRequest
WorkflowExecutionResult
agent name validation
common schema fragments
ExecutionNode construction helper
ExecutionGraph validation helper

base.py 生成 node 时统一：

AgentDescriptor(
    name=agent.name,
    role="",
    system_prompt="",
    metadata={
        "sub_agent_kind": "generic_skill_worker",
        "workflow_tool": workflow_name,
        "workflow_agent_name": agent.name,
    },
)

8.3 sequential.py

负责：

SequentialWorkflow schema
SequentialWorkflow args validation
agents order → chain dependencies

8.4 concurrent.py

负责：

ConcurrentWorkflow schema
ConcurrentWorkflow args validation
all agents → no dependencies

8.5 mixture_of_agents.py

负责：

MixtureOfAgents schema
expert agents validation
aggregator validation
experts → aggregator dependencies

8.6 agent_rearrange.py

负责：

AgentRearrange schema
flow parser
flow → edges
edges validation

8.7 graph.py

负责：

GraphWorkflow schema
required edges
required output_agent
cycle detection
unknown node detection
reachability validation
edges → depends_on

8.8 mcp_tools.py

负责把 workflow 实现暴露成 MCP tools：

create_team_workflow_tools()
→ SequentialWorkflowTool
→ ConcurrentWorkflowTool
→ MixtureOfAgentsTool
→ AgentRearrangeTool
→ GraphWorkflowTool

---

9. 本地 MCP 常加载

9.1 修改 config loader

文件：

app-instance/backend/beaver/foundation/config/loader.py

在 LOCAL_MCP_CATEGORIES 加：

"local_team_workflow_mcp": {
    "category": "team_workflow",
    "display_name": "本地 Agent Team Workflow 工具",
}

这样 Beaver 默认启动时就会加载：

python -m beaver.interfaces.mcp.tools_server --category team_workflow

9.2 修改 MCP tools server

文件：

app-instance/backend/beaver/interfaces/mcp/tools_server.py

加 category：

LOCAL_TOOL_CATEGORIES = {
    ...
    "team_workflow": "Beaver Local Team Workflow Tools",
}

加工具分发：

elif category == "team_workflow":
    from beaver.team_workflows.mcp_tools import create_team_workflow_tools
    tools = create_team_workflow_tools()

---

10. Runtime bridge 必须干净处理

这里是实现关键点。

当前普通 MCP wrapper 的问题：

MCPToolWrapper.invoke(arguments, context)
→ 只把 arguments 发给 MCP server
→ MCP server 不知道当前 task_id / session_id / loaded runtime

但 Workflow Tool 要启动 Team，必须知道：

task_id
session_id
loaded runtime
TeamService
workspace
provider context

所以设计上要明确：

Team Workflow MCP tools 是本地托管工具，不是普通远端 MCP 工具。

推荐实现：

MCP server 负责暴露 schema
AgentLoop 通过 tool schema 让模型选择工具
执行时 Beaver 识别 category=team_workflow
在当前进程内调用 TeamWorkflowExecutor
TeamWorkflowExecutor 使用当前 ToolContext 调 TeamService.run_team()

也就是：

MCP as schema surface
current process as execution owner

不要让 MCP 子进程自己 boot 一套 Beaver runtime。

否则会带来：

session 写入归属不清
task run 绑定不稳
provider config 重复初始化
日志难追踪
并发锁更复杂

---

11. 要修改的代码

11.1 新增

app-instance/backend/beaver/team_workflows/__init__.py
app-instance/backend/beaver/team_workflows/base.py
app-instance/backend/beaver/team_workflows/mcp_tools.py
app-instance/backend/beaver/team_workflows/sequential.py
app-instance/backend/beaver/team_workflows/concurrent.py
app-instance/backend/beaver/team_workflows/mixture_of_agents.py
app-instance/backend/beaver/team_workflows/agent_rearrange.py
app-instance/backend/beaver/team_workflows/graph.py
app-instance/backend/beaver/team_workflows/executor.py

11.2 修改

app-instance/backend/beaver/foundation/config/loader.py

新增 local_team_workflow_mcp。

app-instance/backend/beaver/interfaces/mcp/tools_server.py

新增 team_workflow category。

app-instance/backend/beaver/tools/mcp/wrapper.py

增加本地 team workflow bridge，避免普通 MCP 子进程执行 Team runtime。

app-instance/backend/beaver/engine/loop.py

调整：

• root task AgentLoop 可以看到 Workflow tools；
• worker AgentLoop 默认看不到 Workflow tools；
• 去掉 “Main Agent” 概念文案；
• 不再鼓励 run_agent_team。

app-instance/backend/beaver/tasks/attempt_orchestrator.py

调整：

• Task 执行主路径进入 Root AgentLoop；
• 不再要求 Planner 先判断 team；
• Planner 生成 team DAG 的路径降级或删除。

app-instance/backend/beaver/skills/catalog/utils.py
app-instance/backend/beaver/skills/catalog/loader.py
app-instance/backend/beaver/engine/context/builder.py
app-instance/backend/beaver/skills/assembler/task_assembler.py

调整：

• 解析 beaver-team-workflow guidance；
• 不再把 beaver-team-template 作为新执行图入口；
• 旧字段如保留，仅作为 migration metadata，不进入新主路径。

11.3 废弃或删除

app-instance/backend/beaver/tools/builtins/agent_team.py

废弃为主入口。

迁移期可隐藏保留，但不再暴露给 root AgentLoop。

app-instance/backend/beaver/tasks/planner.py

删除或废弃 Team DAG generation 责任。

不再让它输出 ExecutionGraph。

---

12. 测试计划

12.1 Workflow graph builder

新增：

app-instance/backend/tests/unit/test_team_workflow_graph.py

覆盖：

SequentialWorkflow builds A → B → C
ConcurrentWorkflow builds independent nodes
MixtureOfAgents builds experts → aggregator
AgentRearrange parses flow
GraphWorkflow requires edges
GraphWorkflow rejects unknown nodes
GraphWorkflow rejects cycles
GraphWorkflow requires reachable output_agent

12.2 MCP loading

修改：

app-instance/backend/tests/unit/test_config_loader.py

覆盖：

load_config injects local_team_workflow_mcp
category = team_workflow
managed = true

新增：

app-instance/backend/tests/unit/test_team_workflow_mcp.py

覆盖：

tools_server category team_workflow lists workflow tools
SequentialWorkflow schema has task + agents
GraphWorkflow schema has task + agents + edges + output_agent

12.3 Runtime bridge

新增：

app-instance/backend/tests/unit/test_team_workflow_runtime_bridge.py

覆盖：

workflow tool call keeps current task_id/session_id
workflow tool calls TeamService.run_team()
workflow result is attached to parent task
ordinary MCP tools still use normal MCP execution

12.4 AgentLoop visibility

修改：

app-instance/backend/tests/unit/test_agent_loop.py

覆盖：

root task AgentLoop sees workflow tools
worker AgentLoop does not see workflow tools
run_agent_team is not exposed as preferred root tool
allowed_tool_names remains safety filter only

12.5 Skill guidance

新增或修改：

app-instance/backend/tests/unit/test_skill_team_workflow_guidance.py

覆盖：

beaver-team-workflow block parses
preferred_tool preserved
agents guidance preserved
output_boundary preserved
guidance reaches SkillContext

---

13. 迁移计划

Phase 1：建立 workflow builders

只做：

beaver/team_workflows/base.py
sequential.py
concurrent.py
mixture_of_agents.py
agent_rearrange.py
graph.py

不接 AgentLoop。

验收：

workflow args 能稳定生成 ExecutionGraph

Phase 2：接本地 MCP schema

做：

local_team_workflow_mcp
team_workflow category
mcp_tools.py

验收：

AgentLoop tool registry 能看到 Workflow tools

Phase 3：接 runtime bridge

做：

team_workflows/executor.py
MCP wrapper category bridge
TeamService.run_team integration

验收：

调用 SequentialWorkflow 真的启动 Team

Phase 4：移除旧主入口

做：

Root AgentLoop 不再暴露 run_agent_team
TaskExecutionPlanner 不再生成 team graph
beaver-team-template 不再进入新主路径

验收：

Team 只能通过 Workflow tools 启动

Phase 5：Skill guidance 升级

做：

支持 beaver-team-workflow
更新 MGM/Galaxy Skill
更新其他 Team Skill 示例

验收：

Skill 指导 Agent 调 SequentialWorkflow / GraphWorkflow
而不是写 DAG

---

14. 明确不做

v1 不做：

固定角色 Agent registry
Planner-generated Team DAG
Main Agent 特殊类
nested Team
运行中动态新增节点
GroupChat 真多轮状态机
HierarchicalSwarm manager 动态派工
ForestSwarm
chart renderer
高风险审批 UI
前端大改
Skill learning / eval / publish / rollback 改造

---

15. 最终目标图

User Task
  ↓
Root AgentLoop
  ↓ sees
Skill workflow guidance
ordinary tools
Workflow MCP tools
  ↓ calls
SequentialWorkflow / ConcurrentWorkflow / MixtureOfAgents / AgentRearrange / GraphWorkflow
  ↓
workflow Python implementation
  ↓ builds
ExecutionGraph / ExecutionNode
  ↓
TeamService
  ↓
Scheduler
  ↓
Worker AgentLoops
  ↓ each sees
node instruction
dependency outputs
pinned/dynamic Skill
assembled tools
allowed_tool_names safety scope
  ↓
NodeRunResult + evidence
  ↓
TeamRunResult complete / incomplete
  ↓
Task final result

这是干净版本的架构边界：

Workflow Tool 是 Team 的唯一新入口。
ExecutionGraph 是内部 IR。
AgentLoop 是唯一 agent 执行单元。
Skill 只提供 workflow guidance。