feat(backend): 完善 Workflow 与 DeepResearch 的运行链路与持久化能力

功能说明:\n- 重构并增强工作流网关执行链路,支持更完整的 proposal 与 run 调度参数透传\n- 增加 DeepResearch/workflow 运行事件持久化能力并补齐建表 SQL 与查询/保存接口适配\n- 优化 lead agent 与 deep research runner 的中间态处理,增强线程收集与执行链并发控制\n- 调整工作流执行器与任务路由,提升兼容性并完善错误与回放行为\n- 补充回归测试:deep_research 持久化、workflow 并发、定义加载、引擎执行、run 流程等覆盖
This commit is contained in:
董宏凯 committed 2026-09-02 12:52:37 +08:00
1 parent f5bf7897b9
commit 6d326a21cd
28 files changed
+836 -135

No files matched your search

@@ -23,6 +23,8 @@ from deerflow.workflows.schemas import WorkflowGraph
_JSON_BLOCK = re.compile(r"```(?:json)?\s*(.+?)\s*```", re.DOTALL | re.IGNORECASE)
_QUERY_PREVIEW = 64
_STRATEGIES = ("collaborative", "parallel_research", "quick_answer")
_TASK_CONTRACT_FIELDS = ("mission", "deliverable", "scope", "handoff")
_TASK_CONTRACT_FIELD_LIMIT = 600
PlanningProgressEmitter = Callable[[dict[str, Any]], Awaitable[None]]
@@ -106,6 +108,103 @@ def _agent_skills(node: Any) -> list[str]:
return [str(item) for item in raw] if isinstance(raw, list) else []
def _default_task_contract(
node: Any,
*,
strategy: str,
index: int,
total: int,
) -> dict[str, str]:
"""Describe one worker's bounded responsibility when the controller omits it.
The controller may specialize these fields, but an omitted model field must
never send a worker back to a vague "help with the task" instruction.
"""
role = _agent_name(node)
capability = _agent_description(node) or "其已配置的专业能力"
if strategy == "parallel_research" and index == total - 1:
return {
"mission": f"作为{role}整合各并行调研分支,不重新发起无关调研。",
"deliverable": "输出证据对照、冲突与不确定性、结论和可执行的下一步建议。",
"scope": "只使用 workflowInput 和 evidencePack;将来源事实、推断和待验证假设明确区分。",
"handoff": "交给深度研究报告写作节点;用清晰的结论结构和证据缺口帮助其成文。",
}
if strategy == "parallel_research":
return {
"mission": f"作为{role}从一个独立视角调查用户问题,发挥:{capability}。",
"deliverable": "交付结构化证据笔记:关键事实、来源或验证方法、判断、置信度与信息缺口。",
"scope": "只完成本调研分支;不替代综合角色写最终报告,不把未验证内容表述为事实。",
"handoff": "结果会进入 Evidence Pack,供综合角色比对并交给报告写作节点。",
}
if strategy == "collaborative" and index == 0:
return {
"mission": f"作为{role}完成第一阶段任务拆解和基础分析,发挥:{capability}。",
"deliverable": "交付问题分解、关键判断、证据或验证路径、明确的假设与待补信息。",
"scope": "只建立可靠的上游材料,不假装已经完成后续角色的审阅或最终交付。",
"handoff": "将可复核的结构化结果交给下游角色继续审阅和补强。",
}
if strategy == "collaborative":
return {
"mission": f"作为{role}审阅并补强上游成果,发挥:{capability}。",
"deliverable": "交付经过校正的结论、补充证据、冲突说明、剩余风险与下一步建议。",
"scope": "围绕 workflowInput 和 upstreamResult 工作;保留有效材料,明确标注不能确认的部分。",
"handoff": "将可直接被下一阶段使用的完整结果交接给下游角色。",
}
return {
"mission": f"作为{role}快速分析用户问题,发挥:{capability}。",
"deliverable": "交付直接结论、可验证依据、关键假设和仍需用户补充的信息。",
"scope": "只处理当前用户问题;信息不足时先说明限制,不能臆造事实或虚构执行结果。",
"handoff": "这是该策略的最终用户可读输出,无需自行编排其他智能体。",
}
def _contract_text(value: Any, fallback: str) -> str:
"""Accept short controller-owned text while keeping prompt assembly bounded."""
text = _text(value).replace("\x00", " ")
return (text or fallback)[:_TASK_CONTRACT_FIELD_LIMIT]
def _task_contracts(
model_result: dict[str, Any],
agents: list[Any],
*,
strategy: str,
) -> dict[str, dict[str, str]]:
"""Map controller task contracts to selected, visible worker ids only."""
raw_contracts = model_result.get("taskContracts") or model_result.get("task_contracts")
strategy_contracts = raw_contracts.get(strategy) if isinstance(raw_contracts, dict) else {}
contracts: dict[str, dict[str, str]] = {}
for index, agent in enumerate(agents):
agent_id = _agent_id(agent)
fallback = _default_task_contract(
agent,
strategy=strategy,
index=index,
total=len(agents),
)
raw = strategy_contracts.get(agent_id) if isinstance(strategy_contracts, dict) else None
contracts[agent_id] = {
field: _contract_text(raw.get(field) if isinstance(raw, dict) else None, fallback[field])
for field in _TASK_CONTRACT_FIELDS
}
return contracts
def _task_contract_suffix(contract: dict[str, str] | None) -> str:
if not contract:
return ""
return (
"<workflow-task-contract>\n"
"这是工作流总控为你分配的固定岗位。只完成这个岗位,不自行改派角色或重复总控职责。\n"
f"专属任务:{contract['mission']}\n"
f"交付产物:{contract['deliverable']}\n"
f"工作范围与质量要求:{contract['scope']}\n"
f"交接方式:{contract['handoff']}\n"
"如果缺少完成本岗位必需的信息,说明缺口并通过用户协助工具提问;不要用虚构内容填补。\n"
"</workflow-task-contract>"
)
def _catalog_payload(agents: list[Any]) -> list[dict[str, Any]]:
"""Return metadata only; agent SOUL/configuration must never enter a prompt."""
unique: dict[str, dict[str, Any]] = {}
@@ -219,16 +318,26 @@ def _chat_input_schema(graph: WorkflowGraph) -> dict[str, Any]:
return schema
def _agent_config(node: Any, *, prompt_suffix: str = "", bindings: dict[str, str] | None = None) -> dict[str, Any]:
def _agent_config(
node: Any,
*,
prompt_suffix: str = "",
task_contract: dict[str, str] | None = None,
bindings: dict[str, str] | None = None,
model_name: str | None = None,
) -> dict[str, Any]:
config = copy.deepcopy(node.config)
template = _text(config.get("promptTemplate") or config.get("prompt_template"), "请完成用户的请求。")
config["promptTemplate"] = f"{template}\n\n{prompt_suffix}".strip()
prompt_parts = [template, prompt_suffix, _task_contract_suffix(task_contract)]
config["promptTemplate"] = "\n\n".join(part for part in prompt_parts if part).strip()
original = config.get("inputBindings") or config.get("input_bindings")
resolved = dict(original) if isinstance(original, dict) else {}
resolved["workflowInput"] = "{{ inputs }}"
if bindings:
resolved.update(bindings)
config["inputBindings"] = resolved
if model_name:
config["modelName"] = model_name
return config
@@ -241,7 +350,15 @@ def _output_node(node_id: str, source_id: str) -> dict[str, Any]:
}
def _single_agent_graph(source: WorkflowGraph, node: Any, *, name: str, strategy: str) -> dict[str, Any]:
def _single_agent_graph(
source: WorkflowGraph,
node: Any,
*,
name: str,
strategy: str,
task_contract: dict[str, str] | None = None,
model_name: str | None = None,
) -> dict[str, Any]:
source_id = str(node.id)
start_id = f"__{strategy}_start__"
output_id = f"__{strategy}_output__"
@@ -260,6 +377,8 @@ def _single_agent_graph(source: WorkflowGraph, node: Any, *, name: str, strategy
"config": _agent_config(
node,
prompt_suffix="你负责快速澄清用户问题、给出可验证的结论;信息不足时明确列出缺口。",
task_contract=task_contract,
model_name=model_name,
),
},
_output_node(output_id, source_id),
@@ -271,10 +390,23 @@ def _single_agent_graph(source: WorkflowGraph, node: Any, *, name: str, strategy
}
def _parallel_research_graph(source: WorkflowGraph, agents: list[Any]) -> dict[str, Any]:
def _parallel_research_graph(
source: WorkflowGraph,
agents: list[Any],
*,
task_contracts: dict[str, dict[str, str]] | None = None,
model_name: str | None = None,
) -> dict[str, Any]:
"""Fan out collection roles and use the last configured agent as synthesizer."""
if len(agents) < 2:
return _single_agent_graph(source, agents[0], name="快速验证方案", strategy="quick_answer")
return _single_agent_graph(
source,
agents[0],
name="快速验证方案",
strategy="quick_answer",
task_contract=(task_contracts or {}).get(_agent_id(agents[0])),
model_name=model_name,
)
start_id = "__parallel_start__"
evidence_id = "__parallel_evidence__"
report_id = "__parallel_report__"
@@ -294,6 +426,8 @@ def _parallel_research_graph(source: WorkflowGraph, agents: list[Any]) -> dict[s
"config": _agent_config(
researcher,
prompt_suffix="你是并行调研角色。围绕用户任务收集事实、假设和可引用依据,输出结构化要点给汇总角色。",
task_contract=(task_contracts or {}).get(_agent_id(researcher)),
model_name=model_name,
),
}
)
@@ -319,7 +453,9 @@ def _parallel_research_graph(source: WorkflowGraph, agents: list[Any]) -> dict[s
"config": _agent_config(
synthesis,
prompt_suffix="你是综合分析角色。基于 Evidence Pack 比较各调研结果,标注冲突、假设和证据不足,形成面向用户的结论与下一步建议。",
task_contract=(task_contracts or {}).get(_agent_id(synthesis)),
bindings=synthesis_bindings,
model_name=model_name,
),
}
)
@@ -375,7 +511,13 @@ def _parallel_research_graph(source: WorkflowGraph, agents: list[Any]) -> dict[s
}
def _collaborative_graph(source: WorkflowGraph, agents: list[Any]) -> dict[str, Any]:
def _collaborative_graph(
source: WorkflowGraph,
agents: list[Any],
*,
task_contracts: dict[str, dict[str, str]] | None = None,
model_name: str | None = None,
) -> dict[str, Any]:
"""Build a sequential expert hand-off from the controller's selection."""
if not agents:
raise WorkflowPlannerUnavailableError("总控没有选出可执行的协作智能体")
@@ -399,7 +541,13 @@ def _collaborative_graph(source: WorkflowGraph, agents: list[Any]) -> dict[str,
"id": node_id,
"type": agent.type,
"name": _agent_name(agent),
"config": _agent_config(agent, prompt_suffix=role_hint, bindings=bindings),
"config": _agent_config(
agent,
prompt_suffix=role_hint,
task_contract=(task_contracts or {}).get(_agent_id(agent)),
bindings=bindings,
model_name=model_name,
),
}
)
edges.append({"id": f"{previous_id}_to_{node_id}", "source": previous_id, "target": node_id})
@@ -435,6 +583,7 @@ async def _ask_workflow_controller(
query: str,
owner_id: str,
agents: list[Any],
model_name: str | None = None,
on_progress: PlanningProgressEmitter | None = None,
) -> dict[str, Any]:
"""Ask the dedicated controller to understand intent and select agents.
@@ -479,9 +628,16 @@ async def _ask_workflow_controller(
'"recommendedStrategy":"collaborative|parallel_research|quick_answer",'
'"strategyOrder":["..."],'
'"agentSelections":{"collaborative":["agentId"],"parallel_research":["agentId"],"quick_answer":["agentId"]},'
'"taskContracts":{"策略":{"agentId":{"mission":"不超过180字的专属任务",'
'"deliverable":"不超过180字的交付物",'
'"scope":"不超过180字的边界和证据要求",'
'"handoff":"不超过180字的交接说明"}}},'
'"titles":{"策略":"不超过20字标题"},'
'"summaries":{"策略":"不超过120字方案说明"},'
'"rationales":{"策略":"不超过120字选择理由"}}。\n\n'
'"rationales":{"策略":"不超过120字选择理由"}}。'
"taskContracts 只能为已选中的逐字匹配 agentId 提供岗位说明;"
"并行策略中每个调研角色必须分配互补视角,最后的综合角色必须明确 Evidence Pack 的使用方式;"
"顺序协作策略必须明确上一角色交接给下一角色的内容。\n\n"
f"用户需求:{query}\n可用业务智能体目录:{json.dumps(catalog, ensure_ascii=False)}"
)
received_first_delta = False
@@ -506,6 +662,7 @@ async def _ask_workflow_controller(
disable_tools=True,
thinking_enabled=False,
force_disable_thinking=True,
model_name=model_name,
on_delta=on_delta,
)
parsed = _decode_planner_json(_text(result.get("text")))
@@ -564,6 +721,7 @@ async def build_workflow_proposals(
source_graph: WorkflowGraph,
query: str,
owner_id: str,
model_name: str | None = None,
source_canvas_schema: str = "{}",
on_progress: PlanningProgressEmitter | None = None,
) -> list[dict[str, Any]]:
@@ -589,6 +747,7 @@ async def build_workflow_proposals(
query=query,
owner_id=owner_id,
agents=agents,
model_name=model_name,
on_progress=on_progress,
)
await _emit_progress(
@@ -604,6 +763,21 @@ async def build_workflow_proposals(
parallel_agents = _strategy_selection(
model_result, agents, "parallel_research", fallback_count=min(4, len(agents))
)
collaborative_contracts = _task_contracts(
model_result,
collaborative_agents,
strategy="collaborative",
)
quick_contracts = _task_contracts(
model_result,
quick_agents,
strategy="quick_answer",
)
parallel_contracts = _task_contracts(
model_result,
parallel_agents,
strategy="parallel_research",
)
await _emit_progress(
on_progress,
phase="selection",
@@ -625,7 +799,12 @@ async def build_workflow_proposals(
"summary": f"由选定角色依次复核“{preview}”,逐步补足证据与结论。",
"rationale": "适合需要角色接力、审阅和逐步收敛的复杂任务。",
"estimated_duration_seconds": 180,
"graph": _collaborative_graph(source_graph, collaborative_agents),
"graph": _collaborative_graph(
source_graph,
collaborative_agents,
task_contracts=collaborative_contracts,
model_name=model_name,
),
"canvas_schema": "{}",
},
}
@@ -635,7 +814,14 @@ async def build_workflow_proposals(
"summary": f"由 {_agent_name(quick_agents[0])} 先处理“{preview}”,快速给出结论与信息缺口。",
"rationale": "适合先校验方向、范围明确或需要控制成本的任务。",
"estimated_duration_seconds": 45,
"graph": _single_agent_graph(source_graph, quick_agents[0], name="快速验证方案", strategy="quick_answer"),
"graph": _single_agent_graph(
source_graph,
quick_agents[0],
name="快速验证方案",
strategy="quick_answer",
task_contract=quick_contracts.get(_agent_id(quick_agents[0])),
model_name=model_name,
),
"canvas_schema": "{}",
}
if len(parallel_agents) >= 2:
@@ -645,7 +831,12 @@ async def build_workflow_proposals(
"summary": f"多个角色并行收集“{preview}”相关依据,再由综合角色输出统一结论和报告。",
"rationale": "适合研究、诊断、方案和报告类任务,可减少单一视角遗漏。",
"estimated_duration_seconds": 600,
"graph": _parallel_research_graph(source_graph, parallel_agents),
"graph": _parallel_research_graph(
source_graph,
parallel_agents,
task_contracts=parallel_contracts,
model_name=model_name,
),
"canvas_schema": "{}",
}