feat(workflow): 增加会话级多智能体任务规划运行能力

提交范围聚焦于工作流编排新增:新增 workflow_planning 路由与前后端运行入口(workflow_planning.py、workflow_proposal_planner.py、workflow_deep_research_adapter.py),支持基于会话的提案-规划-执行流程,满足任务驱动式多智能体协作。

完成网关层运行时适配:扩展 workflow_resource_checks、workflow_executor、workflow_runs、workflow_agent_runner 与依赖注入,新增/更新配置(config.yaml、workflow_config),并补充 lead_agent 路径与节点实现,确保 Planner 与普通工作流运行态衔接一致。

补齐持久化与建模:新增 workflow_planning 持久化模块与 MySQL migration(20260831_01_workflow_planning_sessions),注册 SQL 与模型、内存 store,并扩展错误/表达式/validator/节点语义以承载新会话态输入输出。

增强文档与测试:新增会话式多智能体编排中文说明、更新开发文档与 AGENTS 指南、补充 workflow_engine/workflow_runs 回归测试,提高新路径的行为可验证性;同时留存 seed 资产(workflow-planner)便于一体化部署。
This commit is contained in:
董宏凯 committed 2026-09-01 11:47:30 +08:00
1 parent ac92f29db1
commit 1706a24182
39 files changed
+4896 -81

No files matched your search

@@ -17,14 +17,16 @@ import pytest
import pytest_asyncio
from fastapi import FastAPI
from app.gateway.routers import workflow_data_sources, workflow_embed, workflow_resources
from app.gateway.routers import workflow_data_sources, workflow_embed, workflow_planning, workflow_resources
from app.gateway.routers import workflow_runs as runs_router
from app.gateway.workflow_agent_runner import WorkflowAgentRunner
from app.gateway.workflow_dispatcher import WorkflowRunDispatcher
from app.gateway.workflow_executor import WorkflowRunExecutor
from app.gateway.workflow_live_hub import WorkflowLiveHub
from deerflow.config.workflow_config import WorkflowConfig
from deerflow.persistence.workflow_data_sources import MemoryWorkflowDataSourceStore
from deerflow.persistence.workflow_events import MemoryWorkflowEventStore
from deerflow.persistence.workflow_planning import MemoryWorkflowPlanningStore
from deerflow.persistence.workflow_runs import MemoryWorkflowRunStore
from deerflow.persistence.workflows import MemoryWorkflowStore
@@ -60,11 +62,13 @@ FAIL_GRAPH: dict[str, Any] = {
"type": "transform",
"config": {"operations": [{"op": "set", "target": "title", "value": "{{ inputs.topic }}"}]},
},
{"id": "boom", "type": "code", "config": {"source": "output['x'] = 1"}},
{"id": "boom", "type": "transform", "config": {"operations": [{"op": "not_a_real_op"}]}},
{"id": "end", "type": "output", "config": {"mapping": {"title": "{{ nodes.boom.data.title }}"}}},
],
"edges": [
{"id": "e1", "source": "start", "target": "shape"},
{"id": "e2", "source": "shape", "target": "boom"},
{"id": "e3", "source": "boom", "target": "end"},
],
}
@@ -87,6 +91,62 @@ PAUSE_GRAPH: dict[str, Any] = {
],
}
PLANNING_GRAPH: dict[str, Any] = {
"schemaVersion": "1.0",
"id": "wf-planning",
"name": "planning",
"nodes": [
{"id": "start", "type": "start"},
{
"id": "research",
"type": "agent",
"name": "研究员",
"config": {"agentId": "default", "promptTemplate": "收集事实"},
},
{
"id": "writer",
"type": "agent",
"name": "分析师",
"config": {"agentId": "default", "promptTemplate": "综合结论"},
},
{"id": "end", "type": "output", "config": {"mapping": {"text": "{{ nodes.writer.data.text }}"}}},
],
"edges": [
{"id": "p1", "source": "start", "target": "research"},
{"id": "p2", "source": "research", "target": "writer"},
{"id": "p3", "source": "writer", "target": "end"},
],
}
FEEDBACK_GRAPH: dict[str, Any] = {
"schemaVersion": "1.0",
"id": "wf-feedback",
"name": "feedback",
"inputSchema": {"type": "object", "required": ["topic"], "properties": {"topic": {"type": "string"}}},
"nodes": [
{"id": "start", "type": "start"},
{
"id": "shape",
"type": "transform",
"config": {"operations": [{"op": "set", "target": "brief", "value": "{{ inputs.topic }} 的基础材料"}]},
},
{
"id": "writer",
"type": "agent",
"config": {
"agentId": "default",
"promptTemplate": "请基于 {{ nodes.shape.data.brief }} 写出分析。",
},
},
{"id": "end", "type": "output", "config": {"mapping": {"text": "{{ nodes.writer.data.text }}"}}},
],
"edges": [
{"id": "feedback-1", "source": "start", "target": "shape"},
{"id": "feedback-2", "source": "shape", "target": "writer"},
{"id": "feedback-3", "source": "writer", "target": "end"},
],
}
TYPED_INPUT_GRAPH: dict[str, Any] = {
"schemaVersion": "1.0",
"id": "wf-typed",
@@ -165,7 +225,7 @@ async def harness(monkeypatch: pytest.MonkeyPatch):
async def _optional(_request=None):
return None
for module in (runs_router, workflow_data_sources, workflow_embed, workflow_resources):
for module in (runs_router, workflow_data_sources, workflow_embed, workflow_planning, workflow_resources):
monkeypatch.setattr(module, "get_app_config", lambda: _Cfg())
monkeypatch.setattr(module, "get_current_user", _user)
if hasattr(module, "get_optional_user_from_request"):
@@ -174,6 +234,7 @@ async def harness(monkeypatch: pytest.MonkeyPatch):
app = FastAPI()
app.state.workflow_store = MemoryWorkflowStore()
app.state.workflow_run_store = MemoryWorkflowRunStore()
app.state.workflow_planning_store = MemoryWorkflowPlanningStore()
app.state.workflow_event_store = MemoryWorkflowEventStore()
app.state.workflow_data_source_store = MemoryWorkflowDataSourceStore()
app.state.workflow_live_hub = WorkflowLiveHub()
@@ -197,6 +258,7 @@ async def harness(monkeypatch: pytest.MonkeyPatch):
)
app.include_router(workflow_data_sources.router)
app.include_router(workflow_embed.router)
app.include_router(workflow_planning.router)
app.include_router(workflow_resources.router)
app.include_router(runs_router.router)
@@ -246,6 +308,445 @@ async def test_missing_required_input_is_rejected_before_queueing(harness: Harne
assert await harness.runs.list_runs(limit=10) == []
@pytest.mark.asyncio
async def test_planning_session_selects_an_editable_candidate_then_confirms_one_durable_run(
harness: Harness,
) -> None:
async def planner(**_kwargs: Any) -> dict[str, Any]:
return {
"recommendedStrategy": "parallel_research",
"titles": {"parallel_research": "多角度调研方案"},
}
harness.app.state.workflow_proposal_planner = planner
definition = await harness.app.state.workflow_store.create_definition(
{"name": "planner", "owner_id": "user-a", "draft_graph": PLANNING_GRAPH},
)
created = await harness.client.post(
f"/api/workflows/{definition['id']}/planning-sessions",
json={"query": "分析本周销售下滑并给出改进方案"},
)
assert created.status_code == 200, created.text
session = created.json()
assert session["status"] == "proposed"
assert [proposal["strategy"] for proposal in session["proposals"]] == [
"parallel_research",
"collaborative",
"quick_answer",
]
assert session["proposals"][0]["title"] == "多角度调研方案"
assert all(proposal["validation"]["valid"] for proposal in session["proposals"])
parallel_graph = session["proposals"][0]["graph"]
evidence = next(node for node in parallel_graph["nodes"] if node["type"] == "evidence_normalizer")
synthesis = next(node for node in parallel_graph["nodes"] if node["id"] == "writer")
report = next(node for node in parallel_graph["nodes"] if node["type"] == "deep_research_write")
assert evidence["config"]["sources"] == [{"nodeId": "research", "label": "研究员"}]
assert synthesis["config"]["inputBindings"]["evidencePack"] == "{{ nodes.__parallel_evidence__.data.evidencePack }}"
assert report["config"]["evidenceBinding"] == "{{ nodes.__parallel_evidence__.data.evidencePack }}"
assert report["config"]["researchConfig"]["mode"] == "detailed"
assert [role["name"] for role in session["proposals"][0]["roles"]] == ["研究员", "分析师"]
assert session["proposals"][0]["steps"] == ["研究员", "证据归一化", "分析师", "深度研究报告写作"]
selected = session["proposals"][0]
selected_response = await harness.client.post(
f"/api/workflows/planning-sessions/{session['planningSessionId']}/proposals/{selected['proposalId']}/select",
)
assert selected_response.status_code == 200, selected_response.text
selected_session = selected_response.json()
assert selected_session["status"] == "selected"
assert selected_session["selectedProposalId"] == selected["proposalId"]
started = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={
"planningSessionId": session["planningSessionId"],
"proposalId": selected["proposalId"],
"idempotencyKey": "confirm-proposal-1",
},
)
assert started.status_code == 200, started.text
run = started.json()
assert run["created"] is True
assert run["executionMode"] == "planned_workflow"
assert run["planningSessionId"] == session["planningSessionId"]
# A duplicate confirmation never creates a second execution. The planning
# session is the durable source of truth, not a front-end disabled button.
duplicate = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={
"planningSessionId": session["planningSessionId"],
"proposalId": selected["proposalId"],
"idempotencyKey": "confirm-proposal-1",
},
)
assert duplicate.status_code == 200, duplicate.text
assert duplicate.json()["runId"] == run["runId"]
assert duplicate.json()["created"] is False
persisted = await harness.client.get(
f"/api/workflows/planning-sessions/{session['planningSessionId']}",
)
assert persisted.status_code == 200
assert persisted.json()["status"] == "confirmed"
assert persisted.json()["confirmedRunId"] == run["runId"]
@pytest.mark.asyncio
async def test_planning_session_streams_real_controller_milestones_before_result(
harness: Harness,
) -> None:
async def planner(**_kwargs: Any) -> dict[str, Any]:
return {
"recommendedStrategy": "quick_answer",
"strategyOrder": ["quick_answer", "collaborative"],
"agentSelections": {"quick_answer": ["default"], "collaborative": ["default"]},
}
harness.app.state.workflow_proposal_planner = planner
definition = await harness.app.state.workflow_store.create_definition(
{"name": "stream-planner", "owner_id": "user-a", "draft_graph": PLANNING_GRAPH},
)
async with harness.client.stream(
"POST",
f"/api/workflows/{definition['id']}/planning-sessions/stream",
json={"query": "请评估本周销售下滑原因"},
) as response:
assert response.status_code == 200
payload = "".join([chunk async for chunk in response.aiter_text()])
assert "event: progress" in payload
assert '"phase": "connection"' in payload
assert '"phase": "catalog"' in payload
assert '"phase": "controller"' in payload
assert '"phase": "selection"' in payload
assert '"phase": "assembly"' in payload
assert '"phase": "validation"' in payload
assert '"phase": "complete"' in payload
assert "event: result" in payload
assert ": stream-flush" in payload
@pytest.mark.asyncio
async def test_dedicated_workflow_controller_has_no_tools_or_thinking(
harness: Harness,
monkeypatch: pytest.MonkeyPatch,
) -> None:
captured: dict[str, Any] = {}
async def fake_run_agent(_self: Any, **kwargs: Any) -> dict[str, Any]:
captured.update(kwargs)
return {
"text": (
'{"recommendedStrategy":"quick_answer",'
'"agentSelections":{"collaborative":["default"],'
'"quick_answer":["default"]}}'
)
}
monkeypatch.setattr(WorkflowAgentRunner, "run_agent", fake_run_agent)
definition = await harness.app.state.workflow_store.create_definition(
{"name": "controller-boundary", "owner_id": "user-a", "draft_graph": PLANNING_GRAPH},
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/planning-sessions",
json={"query": "快速确认这份材料是否有缺口"},
)
assert response.status_code == 200, response.text
assert captured["agent_id"] == "workflow-planner"
assert captured["disable_tools"] is True
assert captured["thinking_enabled"] is False
assert captured["force_disable_thinking"] is True
@pytest.mark.asyncio
async def test_planner_uses_visible_agent_catalog_when_canvas_is_only_start_and_end(
harness: Harness,
) -> None:
class VisibleAgentStore:
async def list_visible(self, _user_id: str) -> list[dict[str, str]]:
return [
{
"id": "agent-research",
"name": "行业研究员",
"description": "收集行业数据、案例和不确定性。",
},
{
"id": "agent-writer",
"name": "策略分析师",
"description": "比较证据并形成策略建议。",
},
{
"id": "workflow-planner",
"name": "工作流总控",
"description": "不应被选作正式工作流执行角色。",
},
]
async def get_extras_for(self, _agent_ids: list[str]) -> dict[str, dict[str, list[str]]]:
return {
"agent-research": {"skills": ["web-search"]},
"agent-writer": {"skills": []},
}
captured: dict[str, Any] = {}
async def planner(**kwargs: Any) -> dict[str, Any]:
captured.update(kwargs)
return {
"recommendedStrategy": "parallel_research",
"strategyOrder": ["parallel_research", "collaborative", "quick_answer"],
"agentSelections": {
"parallel_research": ["agent-research", "agent-writer"],
"collaborative": ["agent-research", "agent-writer"],
"quick_answer": ["agent-research"],
},
"titles": {"parallel_research": "双角色调研报告"},
}
harness.app.state.agent_store = VisibleAgentStore()
harness.app.state.workflow_proposal_planner = planner
resource_response = await harness.client.get("/api/workflows/resources/agents?keyword=总控")
assert resource_response.status_code == 200
assert resource_response.json() == {"agents": []}
definition = await harness.app.state.workflow_store.create_definition(
{
"name": "empty-canvas-planner",
"owner_id": "user-a",
"draft_graph": {
"schemaVersion": "1.0",
"id": "wf-empty-planning",
"nodes": [
{"id": "start", "type": "start"},
{"id": "end", "type": "output", "config": {"mapping": {}}},
],
"edges": [{"id": "start-to-end", "source": "start", "target": "end"}],
},
}
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/planning-sessions",
json={"query": "研究新能源乘用车市场,并给出落地建议"},
)
assert response.status_code == 200, response.text
assert [item["agentId"] for item in captured["agents"]] == [
"agent-research",
"agent-writer",
]
session = response.json()
assert [proposal["strategy"] for proposal in session["proposals"]] == [
"parallel_research",
"collaborative",
"quick_answer",
]
parallel = session["proposals"][0]
assert parallel["title"] == "双角色调研报告"
assert [role["agentId"] for role in parallel["roles"]] == [
"agent-research",
"agent-writer",
]
assert all(proposal["validation"]["valid"] for proposal in session["proposals"])
@pytest.mark.asyncio
async def test_sql_planning_store_flushes_the_session_before_its_candidates() -> None:
"""A durable planning session can insert its child proposals with FK checks on."""
from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
from deerflow.persistence.base import Base
from deerflow.persistence.workflow_planning import SqlWorkflowPlanningStore
engine = create_async_engine("sqlite+aiosqlite:///:memory:")
try:
async with engine.begin() as connection:
await connection.run_sync(Base.metadata.create_all)
store = SqlWorkflowPlanningStore(async_sessionmaker(engine, expire_on_commit=False))
created = await store.create_session(
{
"id": "wps-parent",
"workflow_id": "wf-parent",
"owner_id": "user-a",
"query": "生成一份市场分析",
"proposals": [
{
"id": "wpp-child",
"strategy": "collaborative",
"title": "协同分析",
"graph": {"nodes": [], "edges": []},
}
],
}
)
assert created["id"] == "wps-parent"
assert [proposal["id"] for proposal in created["proposals"]] == ["wpp-child"]
persisted = await store.get_session("wps-parent")
assert persisted is not None
assert persisted["proposals"][0]["session_id"] == "wps-parent"
finally:
await engine.dispose()
@pytest.mark.asyncio
async def test_run_start_rejects_unbound_nodes_before_queueing(harness: Harness) -> None:
graph = {
"schemaVersion": "1.0",
"id": "wf-unbound",
"nodes": [
{"id": "start", "type": "start"},
{"id": "agent", "type": "agent", "config": {"agentId": "default", "promptTemplate": ""}},
{"id": "end", "type": "output", "config": {"mapping": {"text": "{{ nodes.agent.data.text }}"}}},
],
"edges": [
{"id": "e1", "source": "start", "target": "agent"},
{"id": "e2", "source": "agent", "target": "end"},
],
}
definition = await harness.app.state.workflow_store.create_definition(
{"name": "unbound", "owner_id": "user-a", "draft_graph": graph},
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={"target": "draft", "inputs": {}},
)
assert response.status_code == 400
detail = response.json()["detail"]
assert detail["code"] == "WORKFLOW_RESOURCE_MISSING"
assert detail["nodeId"] == "agent"
assert await harness.runs.list_runs(limit=10) == []
@pytest.mark.asyncio
async def test_directed_agent_task_projects_one_bound_agent_into_a_durable_run(harness: Harness) -> None:
class VisibleAgentStore:
async def list_visible(self, _user_id: str) -> list[dict[str, str]]:
return [{"id": "agent-research"}]
async def get_extras_for(self, _agent_ids: list[str]) -> dict[str, dict[str, list[str]]]:
return {}
harness.app.state.agent_store = VisibleAgentStore()
graph = {
"schemaVersion": "1.0",
"id": "wf-directed",
"nodes": [
{"id": "start", "type": "start"},
{
"id": "100002",
"type": "agent",
"name": "市场研究员",
"config": {
"agentId": "agent-research",
"promptTemplate": "分析用户的市场研究任务",
},
},
{"id": "end", "type": "output", "config": {"mapping": {"text": "{{ nodes.100002.data.text }}"}}},
],
"edges": [
{"id": "e1", "source": "start", "target": "100002"},
{"id": "e2", "source": "100002", "target": "end"},
],
}
definition = await harness.app.state.workflow_store.create_definition(
{"name": "directed", "owner_id": "user-a", "draft_graph": graph},
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={
"target": "draft",
"input": {"query": "分析新能源行业趋势"},
"targetAgentId": "agent-research",
},
)
assert response.status_code == 200, response.text
run = response.json()
assert run["executionMode"] == "agent_task"
assert run["targetAgentId"] == "agent-research"
assert run["targetAgentName"] == "市场研究员"
stored = await harness.runs.get_run(run["runId"])
assert stored is not None
projected = stored["context"]["draftGraph"]
assert [node["id"] for node in projected["nodes"]] == [
"__agent_task_start__",
"100002",
"__agent_task_output__",
]
agent = projected["nodes"][1]
assert agent["config"]["inputBindings"] == {"workflowInput": "{{ inputs }}"}
assert projected["nodes"][2]["config"]["mapping"] == {
"text": "{{ nodes.100002.data.text }}"
}
@pytest.mark.asyncio
async def test_directed_agent_task_rejects_agents_not_bound_on_the_canvas(harness: Harness) -> None:
definition = await harness.app.state.workflow_store.create_definition(
{"name": "not-bound", "owner_id": "user-a", "draft_graph": REPORT_GRAPH},
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={"target": "draft", "input": {"query": "你好"}, "targetAgentId": "agent-missing"},
)
assert response.status_code == 400
assert response.json()["detail"]["code"] == "WORKFLOW_AGENT_TARGET_NOT_BOUND"
assert await harness.runs.list_runs(limit=10) == []
@pytest.mark.asyncio
async def test_draft_human_resume_preserves_the_execution_graph_snapshot(harness: Harness) -> None:
definition = await harness.app.state.workflow_store.create_definition(
{"name": "draft-pause", "owner_id": "user-a", "draft_graph": PAUSE_GRAPH},
)
response = await harness.client.post(
f"/api/workflows/{definition['id']}/runs",
json={"target": "draft", "inputs": {}},
)
assert response.status_code == 200, response.text
run_id = response.json()["runId"]
await harness.drive()
paused = await harness.runs.get_run(run_id)
assert paused is not None and paused["status"] == "awaiting_input"
assert [node["id"] for node in paused["context"]["draftGraph"]["nodes"]] == [
"start",
"ask",
"end",
]
resumed = await harness.client.post(
f"/api/workflows/runs/{run_id}/resume",
json={
"resumeToken": paused["resume_token"],
"action": "submit",
"payload": {"comment": "继续执行"},
},
)
assert resumed.status_code == 200, resumed.text
await harness.drive()
finished = await harness.runs.get_run(run_id)
assert finished is not None
assert finished["status"] == "completed"
assert finished["output"] == {"comment": "继续执行"}
assert [node["id"] for node in finished["context"]["draftGraph"]["nodes"]] == [
"start",
"ask",
"end",
]
@pytest.mark.asyncio
async def test_typed_input_schema_violations_return_structured_400(harness: Harness) -> None:
"""Wrong types (not just missing keys) fail at start with field paths."""
@@ -465,6 +966,74 @@ async def test_retry_rejected_unless_failed(harness: Harness) -> None:
assert completed.json()["detail"]["code"] == "WORKFLOW_RUN_NOT_RETRYABLE"
@pytest.mark.asyncio
async def test_completed_agent_feedback_creates_revision_and_reuses_unaffected_nodes(
harness: Harness,
monkeypatch: pytest.MonkeyPatch,
) -> None:
prompts: list[str] = []
async def fake_run_agent(_self: Any, **kwargs: Any) -> dict[str, Any]:
prompt = str(kwargs["prompt"])
prompts.append(prompt)
text = "已根据反馈重写" if "<workflow-user-feedback>" in prompt else "初版分析"
on_delta = kwargs.get("on_delta")
if on_delta is not None:
await on_delta(text)
return {"text": text, "thread_id": "fake-workflow-agent"}
monkeypatch.setattr(WorkflowAgentRunner, "run_agent", fake_run_agent)
workflow_id, version_id = await harness.publish(FEEDBACK_GRAPH, name="feedback")
original = await harness.start(workflow_id, version_id)
await harness.drive()
original_detail = (await harness.client.get(f"/api/workflows/runs/{original['id']}")).json()
assert original_detail["status"] == "completed"
assert original_detail["output"] == {"text": "初版分析"}
response = await harness.client.post(
f"/api/workflows/runs/{original['id']}/feedback",
json={
"nodeId": "writer",
"message": "请从成本、风险和可执行性三个维度重新分析。",
"idempotencyKey": "writer-revision-1",
},
)
assert response.status_code == 201, response.text
revision = response.json()
assert revision["created"] is True
assert revision["revisionOfRunId"] == original["id"]
assert revision["retryOfRunId"] == original["id"]
assert revision["affectedNodeIds"] == ["end", "writer"]
assert revision["reusedNodeIds"] == ["shape", "start"]
assert revision["feedback"]["targetNodeId"] == "writer"
assert revision["feedback"]["reusedNodeIds"] == ["shape", "start"]
before_drive = (await harness.client.get(f"/api/workflows/runs/{revision['id']}")).json()
assert {row["nodeId"] for row in before_drive["nodeRuns"]} == {"start", "shape"}
await harness.drive()
completed = (await harness.client.get(f"/api/workflows/runs/{revision['id']}")).json()
assert completed["status"] == "completed"
assert completed["output"] == {"text": "已根据反馈重写"}
assert {row["nodeId"] for row in completed["nodeRuns"]} == {"start", "shape", "writer", "end"}
assert "<workflow-user-feedback>" in prompts[-1]
assert "成本、风险和可执行性" in prompts[-1]
duplicate = await harness.client.post(
f"/api/workflows/runs/{original['id']}/feedback",
json={
"nodeId": "writer",
"message": "请从成本、风险和可执行性三个维度重新分析。",
"idempotencyKey": "writer-revision-1",
},
)
assert duplicate.status_code == 201
assert duplicate.json()["id"] == revision["id"]
assert duplicate.json()["created"] is False
assert duplicate.json()["reused"] is True
assert (await harness.client.get(f"/api/workflows/runs/{original['id']}")).json()["output"] == {"text": "初版分析"}
@pytest.mark.asyncio
async def test_stream_last_event_id_beats_after_query(harness: Harness) -> None:
workflow_id, version_id = await harness.publish(REPORT_GRAPH)