feat(deep-research): 强化任务链路可靠性并接入 agentfx 报告助手种子

功能说明:\n- 重构 Deep Research 调度与执行链,补齐 dispatcher、executor、live hub 与依赖注入入口,提升任务下发、执行、回调的稳定性\n- 增强运行时持久化与恢复能力,接入业务映射、任务来源与任务事件日志模型,覆盖持久化与执行可靠性关键路径测试\n- 新增 agentfx 报告助手 seed 与任务报告导入脚本配置,支持离线环境快速初始化与任务流模板回填\n- 完善 deep-research 与 thread_runs 路由参数编排,兼容不同业务映射与运行入口的前后端联动\n- 补充前端 agentfx deep-link 解析,保证 deep-research 场景下的登录跳转与任务上下文一致
This commit is contained in:
董宏凯 committed 2026-09-04 23:18:52 +08:00
1 parent 438772f0b7
commit 5c75e1af16
36 files changed
+3163 -312

No files matched your search

@@ -16,8 +16,10 @@ from __future__ import annotations
import json
import logging
from collections.abc import Awaitable, Callable
from contextlib import suppress
from datetime import date, datetime
from enum import Enum
from time import monotonic
from typing import TYPE_CHECKING, Any
from deerflow.agents.deep_research.events import (
@@ -42,6 +44,20 @@ def _json_default(value: Any) -> Any:
return str(value)
# Live-only frame types that have no durable counterpart at all. Report and
# summary text are already checkpointed (``report_chunk`` / ``summary_completed``),
# so only the reasoning channel needs a cross-worker mirror.
_MIRRORED_LIVE_TYPES = frozenset({"report_thinking", "plan_reasoning", "summary_thinking"})
# Coalescing bounds for that mirror: one bounded row per ~600 characters or
# ~1.5 seconds, never one row per provider token.
_MIRROR_MIN_CHARS = 600
_MIRROR_MAX_DELAY_S = 1.5
# Floor for the time-based flush: a slowly trickling reasoning stream must not
# degrade into one durable row per token. Anything shorter is carried until the
# next durable milestone flushes it.
_MIRROR_MIN_FLUSH_CHARS = 40
def _json_safe_payload(payload: dict[str, Any]) -> dict[str, Any]:
"""Normalize event payloads before they reach any event repository.
@@ -66,11 +82,18 @@ class PersistingEventSink:
session_id: str,
job_id: str,
on_event: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
live_subscriber_probe: Callable[[str], bool] | None = None,
) -> None:
self._repo = repo
self._session_id = session_id
self._job_id = job_id
self._on_event = on_event
# Reports whether this worker holds an SSE connection for the job.
# Absent probe → assume the live path reaches the viewer (single-worker
# deployments and tests keep today's zero-extra-write behaviour).
self._live_subscriber_probe = live_subscriber_probe
self._mirror_buffers: dict[str, dict[str, Any]] = {}
self._mirroring = False
self.diagnostics: list[dict[str, Any]] = []
# A durable event row normally owns the sequence. When the event
# database is temporarily unavailable, use distinct negative sequence
@@ -87,6 +110,10 @@ class PersistingEventSink:
) -> DeepResearchEvent:
event_payload = _json_safe_payload(payload or {})
persistence_error: Exception | None = None
if not self._mirroring:
# Order any coalesced reasoning tail before the next milestone
# instead of leaving it buffered until the job ends.
await self._flush_live_mirrors()
try:
row = await self._repo.append(
session_id=self._session_id,
@@ -211,6 +238,87 @@ class PersistingEventSink:
type,
exc_info=True,
)
with suppress(Exception):
await self._mirror_live_frame(type, phase=phase, payload=payload or {})
# ── cross-worker mirror for live-only reasoning frames ──────────────────
async def _mirror_live_frame(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase,
payload: dict[str, Any],
) -> None:
"""Buffer a live-only reasoning delta when no local viewer can see it.
The live hub is in-process. A job runs on the worker that won its
durable lease, while the SSE connection is served by whichever worker
accepted it, so on a multi-worker deployment the model's thinking is
usually published into a hub with no subscribers and is then lost —
there is no durable row to replay it from. When that is the case, the
reasoning is coalesced here and persisted as a bounded durable event
so the polling stream on the other worker still renders it.
"""
if type not in _MIRRORED_LIVE_TYPES or self._live_subscriber_probe is None:
return
delta = payload.get("delta")
if not isinstance(delta, str) or not delta:
return
if self._live_subscriber_probe(self._job_id):
# A viewer is attached here and has already received every frame
# live. Drop the buffer rather than flushing it, so that viewer
# does not also receive the same text as a durable replay.
self._mirror_buffers.pop(self._mirror_key(type, payload), None)
return
key = self._mirror_key(type, payload)
buffered = self._mirror_buffers.get(key)
if buffered is None:
buffered = {
"type": type,
"phase": phase,
"target": payload.get("target"),
"reportVersion": payload.get("reportVersion"),
"text": "",
"since": monotonic(),
}
self._mirror_buffers[key] = buffered
buffered["text"] += delta
buffered["phase"] = phase
buffered_chars = len(buffered["text"])
aged_out = (
buffered_chars >= _MIRROR_MIN_FLUSH_CHARS
and monotonic() - float(buffered["since"]) >= _MIRROR_MAX_DELAY_S
)
if buffered_chars >= _MIRROR_MIN_CHARS or aged_out:
await self._emit_mirror(key)
@staticmethod
def _mirror_key(type: str, payload: dict[str, Any]) -> str: # noqa: A002
return f"{type}::{payload.get('target') or 'report'}"
async def _flush_live_mirrors(self) -> None:
for key in tuple(self._mirror_buffers):
with suppress(Exception):
await self._emit_mirror(key)
async def _emit_mirror(self, key: str) -> None:
buffered = self._mirror_buffers.pop(key, None)
if buffered is None or not buffered["text"]:
return
payload: dict[str, Any] = {
"delta": buffered["text"],
"liveMirror": True,
}
if buffered["target"] is not None:
payload["target"] = buffered["target"]
if buffered["reportVersion"] is not None:
payload["reportVersion"] = buffered["reportVersion"]
self._mirroring = True
try:
await self.emit(buffered["type"], phase=buffered["phase"], payload=payload)
finally:
self._mirroring = False
class NullEventSink:
@@ -33,7 +33,7 @@ from deerflow.agents.deep_research.cancellation import CancellationToken
from deerflow.agents.deep_research.config import DeepResearchConfig, ModelRole
from deerflow.agents.deep_research.events import EventSink
from deerflow.agents.deep_research.types import CompletionResult
from deerflow.utils.stream_text import InlineThinkTagFilter
from deerflow.utils.stream_text import InlineThinkTagFilter, strip_inline_think_tags
if TYPE_CHECKING:
from langchain.chat_models import BaseChatModel
@@ -388,31 +388,57 @@ class DeerFlowCompletionBackend:
# Custom ``report_delta`` events remain the only live preview channel.
isolated_config = _parent_isolated_run_config(f"deep_research:{operation}")
reset_parent_config = _clear_inherited_runnable_config(isolated_config)
attempts = 2 if operation.startswith("write_report") else 1
last_error: Exception | None = None
try:
async for chunk in model.astream(
to_langchain_messages(messages),
config=isolated_config,
**kwargs,
):
if self._cancel is not None:
self._cancel.raise_if_cancelled()
reasoning = _reasoning_delta(chunk)
if reasoning and on_reasoning is not None:
await on_reasoning(reasoning)
# A few OpenAI-compatible models put their reasoning in the
# ordinary content channel instead of ``reasoning_content``.
# Split it from Markdown even when tags span tokens: callers may
# display a live thought trace, but it never joins ``text``.
delta, inline_reasoning = inline_think_filter.push_parts(_content_to_text(chunk))
if inline_reasoning and on_reasoning is not None:
await on_reasoning(inline_reasoning)
if delta:
text_parts.append(delta)
if on_delta is not None:
await on_delta(delta)
chunk_usage = _extract_usage(chunk)
if any(chunk_usage.values()):
usage = chunk_usage
for attempt in range(attempts):
text_parts.clear()
inline_think_filter = InlineThinkTagFilter()
try:
async for chunk in model.astream(
to_langchain_messages(messages),
config=isolated_config,
**kwargs,
):
if self._cancel is not None:
self._cancel.raise_if_cancelled()
reasoning = _reasoning_delta(chunk)
if reasoning and on_reasoning is not None:
await on_reasoning(reasoning)
# A few OpenAI-compatible models put their reasoning in the
# ordinary content channel instead of ``reasoning_content``.
# Split it from Markdown even when tags span tokens: callers may
# display a live thought trace, but it never joins ``text``.
delta, inline_reasoning = inline_think_filter.push_parts(_content_to_text(chunk))
if inline_reasoning and on_reasoning is not None:
await on_reasoning(inline_reasoning)
if delta:
text_parts.append(delta)
if on_delta is not None:
await on_delta(delta)
chunk_usage = _extract_usage(chunk)
if any(chunk_usage.values()):
usage = chunk_usage
last_error = None
break
except Exception as exc: # noqa: BLE001 - report writing waits like ordinary chat
from deerflow.agents.deep_research.cancellation import ResearchCancelled
if isinstance(exc, (ResearchCancelled, asyncio.CancelledError)):
raise
last_error = exc
# Only replay a clean connection; a half-written stream is
# reset by the runner, not by appending a second attempt.
if text_parts or attempt + 1 >= attempts:
raise
logger.warning(
"deep_research llm: %s stream interrupted before the first token (%s); retrying once",
operation,
type(exc).__name__,
)
await asyncio.sleep(1.5)
if last_error is not None:
raise last_error
finally:
reset_parent_config()
@@ -470,7 +496,10 @@ class DeerFlowCompletionBackend:
if self._cancel is not None:
self._cancel.raise_if_cancelled()
text = _content_to_text(response)
# ``ainvoke`` returns raw content, including the inline ``<think>``
# block some OpenAI-compatible deployments write there. The streamed
# path filters it out, so this retry path must not reintroduce it.
text = strip_inline_think_tags(_content_to_text(response))
usage = _extract_usage(response)
await self._record_usage(model_name, operation, usage)
return CompletionResult(text=text, model=model_name, usage=usage)
@@ -80,6 +80,13 @@ EventType = Literal[
"deep_branch_completed",
"report_reset",
"report_chunk",
# Model reasoning normally travels as a live-only frame. It becomes a
# durable event when no SSE connection for the job is attached to the
# worker running it, because the in-process live hub cannot reach a
# viewer served by a different worker (see PersistingEventSink).
"report_thinking",
"plan_reasoning",
"summary_thinking",
"report_completed",
"summary_completed",
"collection_completed",
@@ -22,6 +22,7 @@ vendored prompt families in a later commit without changing the runner shape.
from __future__ import annotations
import asyncio
import json
import logging
import re
@@ -46,6 +47,23 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
# Delta size used to replay a non-streamed retry report. Matches the durable
# chunk size so the retry produces the same event volume as a streamed write.
_RETRY_REPLAY_CHUNK = 480
_WRITE_REPORT_TIMEOUT_SECONDS = 180.0
async def _await_writer(coro):
"""Fail a hung production stream before the job lease is reclaimed."""
try:
return await asyncio.wait_for(coro, timeout=_WRITE_REPORT_TIMEOUT_SECONDS)
except TimeoutError as exc:
raise CompletionError(
f"Report writer exceeded {_WRITE_REPORT_TIMEOUT_SECONDS:g} seconds",
code="write_report_timeout",
retryable=True,
) from exc
# ── structured-output schemas ───────────────────────────────────────────────
@@ -508,11 +526,12 @@ class BasicRunner:
*,
collection_outcomes: list[dict[str, Any]] | None = None,
) -> DeepResearchResult:
"""Write a complete fallback report when collection returned no rows.
"""Write a complete report when collection returned no rows.
Research collection is best-effort. A collector timeout must not be
persisted as a "cannot generate" pseudo-report, regardless of which
runner mode is active.
Stream the same model writer as a normal report so the sandbox stays
empty through thinking and fills token-by-token. A refusal or transport
failure still falls through ``_generate_report`` to the deterministic
template; do not dump that template before the model has written.
"""
events = adapters.events
await events.emit(
@@ -520,7 +539,7 @@ class BasicRunner:
phase="curating",
payload={
"code": "no_materials",
"message": "未收集到外部研究材料,已改用领域知识继续撰写完整报告",
"message": "未收集到外部研究材料,将按公开领域知识撰写完整报告",
"recoverable": True,
"diagnostic": {
"stage": "collecting",
@@ -529,30 +548,55 @@ class BasicRunner:
},
},
)
await events.emit(
"report_reset",
phase="writing",
payload={"reportVersion": 1, "reason": "no_materials_write"},
)
await events.emit(
"phase_changed",
phase="writing",
payload={"from": "curating", "to": "writing"},
)
context_text = (
"本次没有可引用的外部研究材料。请只依据公开领域常识,就课题写成一份"
"完整、审慎的分析报告。不要拒绝生成,也不要把「没有资料」写成全文主线;"
"在局限性中说明证据边界即可。"
)
report_md = await self._generate_report(
adapters.llm,
request,
_KNOWLEDGE_FILL_EMPTY_CONTEXT,
context_text,
events,
cancellation,
allow_knowledge_fill=True,
source_count=0,
)
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
await adapters.artifacts.write_text("report.md", report_md)
await adapters.artifacts.write_text("sources.json", "[]")
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
await events.emit("report_completed", phase="writing", payload={"reportVersion": 1, "sourceCount": 0})
await events.emit(
"artifact_created",
phase="exporting",
payload={"format": "markdown", "name": "report.md"},
)
image_paths: dict[str, str] = {}
try:
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
except ResearchCancelled:
raise
except Exception: # noqa: BLE001 - illustrations must not discard the report
logger.warning("no-materials image generation failed; retaining the text report", exc_info=True)
for name, content in (
("report.md", report_md),
("sources.json", "[]"),
("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2)),
):
try:
await adapters.artifacts.write_text(name, content)
except Exception: # noqa: BLE001 - session persistence still receives the report
logger.warning("no-materials artifact write failed for %s", name, exc_info=True)
try:
await events.emit("report_completed", phase="writing", payload={"reportVersion": 1, "sourceCount": 0})
await events.emit(
"artifact_created",
phase="exporting",
payload={"format": "markdown", "name": "report.md"},
)
except Exception: # noqa: BLE001 - completion events must not drop the report
logger.warning("no-materials completion events failed; retaining the report", exc_info=True)
return DeepResearchResult(
report_markdown=report_md,
source_ids=[],
@@ -619,30 +663,110 @@ class BasicRunner:
if request.config.structure_mode == "fixed" and (outline or "").strip():
system += "撰写时必须原样沿用用户大纲中的章节标题与层级,不得改写成通用报告套式。"
completion_messages = [
{"role": "system", "content": system},
{"role": "user", "content": prompt},
]
async def write_once(*, report_version: int) -> str:
emitter = ReportChunkEmitter(events, report_version=report_version)
if filled_preamble:
await emitter.add(filled_preamble + "\n\n")
completion_messages = [
{"role": "system", "content": system},
{"role": "user", "content": prompt},
]
result = await llm.stream_complete(
model_role="smart",
messages=completion_messages,
operation="write_report",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
result = await _await_writer(
llm.stream_complete(
model_role="smart",
messages=completion_messages,
operation="write_report",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
)
await emitter.flush()
return ensure_outline_preamble(result.text, outline, request.query)
async def retry_report(
*,
report_version: int,
reason: str,
code: str,
message: str,
error_type: str,
error_detail: str,
) -> str:
"""Spend one real second model call before any deterministic report.
A broken ``astream`` says nothing about the model's ability to
answer: deployments that stall past the inter-chunk deadline (idle
proxy, long reasoning pause) still return a complete response.
Dropping straight to the template silently downgrades a recoverable
transport failure into a material dump that looks like a success.
"""
await events.emit(
"warning",
phase="writing",
payload={
"code": code,
"message": message,
"recoverable": True,
"errorType": error_type,
"diagnostic": {
"stage": "writing",
"outcome": reason,
"errorType": error_type,
"detail": error_detail[:1200] or error_type,
},
},
)
await events.emit(
"report_reset",
phase="writing",
payload={"reportVersion": report_version, "reason": reason},
)
emitter = ReportChunkEmitter(events, report_version=report_version)
# Prefer the non-streaming transport when the adapter offers it: a
# stream that already died on an inter-chunk deadline usually dies
# the same way again, while ``ainvoke`` waits for the whole answer.
complete_prose = getattr(llm, "complete_prose", None)
if callable(complete_prose):
result = await _await_writer(
complete_prose(
model_role="smart",
messages=completion_messages,
operation="write_report_retry",
)
)
report = ensure_outline_preamble(result.text, outline, request.query)
# Replay as bounded deltas so the live sandbox and the durable
# chunk log see the same shape as a streamed write.
for index in range(0, len(report), _RETRY_REPLAY_CHUNK):
await emitter.add(report[index : index + _RETRY_REPLAY_CHUNK])
else:
result = await _await_writer(
llm.stream_complete(
model_role="smart",
messages=completion_messages,
operation="write_report_retry",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
)
report = ensure_outline_preamble(result.text, outline, request.query)
await emitter.flush()
if not report.strip():
raise CompletionError(
"Report retry returned empty prose",
code="empty_report_retry",
retryable=False,
)
return report
async def complete_with_fallback(
*,
reason: str,
message: str,
error_type: str | None = None,
error_detail: str | None = None,
report_version: int = 2,
) -> str:
"""Replace an invalid streamed draft with a usable deterministic report.
@@ -668,39 +792,81 @@ class BasicRunner:
await events.emit(
"report_reset",
phase="writing",
payload={"reportVersion": 2, "reason": reason},
payload={"reportVersion": report_version, "reason": reason},
)
fallback = ensure_outline_preamble(
_build_report_fallback(request.query, context_text, source_count or 0),
outline,
request.query,
)
emitter = ReportChunkEmitter(events, report_version=2)
emitter = ReportChunkEmitter(events, report_version=report_version)
await emitter.add(fallback)
await emitter.flush()
return fallback
async def refusal_fallback() -> str:
return await complete_with_fallback(
reason="refusal_after_retry",
message="模型两次返回拒绝文本,已根据可用材料生成保底报告",
error_type="InvalidReportOutput",
error_detail=report,
report_version=3,
)
try:
report = await write_once(report_version=1)
except Exception as exc: # noqa: BLE001 - preserve materials without a second model call
if not _is_retryable_report_write_error(exc):
except ResearchCancelled:
raise
except Exception as exc: # noqa: BLE001 - writing must finish even on a transport blip
try:
report = await retry_report(
report_version=2,
reason="transient_write_error",
code="report_stream_retry",
message="报告写入连接中断,正在重试生成(已收集素材保持不变)",
error_type=type(exc).__name__,
error_detail=str(exc),
)
except ResearchCancelled:
raise
return await complete_with_fallback(
reason="report_stream_error",
message="报告写入连接中断,已根据可用材料生成保底报告",
error_type=type(exc).__name__,
error_detail=str(exc),
)
except Exception as retry_exc: # noqa: BLE001 - now use the deterministic report
return await complete_with_fallback(
reason="transient_write_error_after_retry",
message="报告写入连接中断且重试未成功,已根据可用材料生成保底报告",
error_type=type(retry_exc).__name__,
error_detail=(
f"stream={type(exc).__name__}: {str(exc)[:600]}; "
f"retry={type(retry_exc).__name__}: {str(retry_exc)[:600]}"
),
report_version=3,
)
return report if not _is_refusal_report(report) else await refusal_fallback()
if not _is_refusal_report(report):
return report
return await complete_with_fallback(
reason="refusal_output",
message="模型返回了拒绝文本,已根据可用材料生成保底报告",
error_type="InvalidReportOutput",
error_detail=report,
)
# A refusal is a content failure, not a transport failure: one clean
# rewrite recovers it far more often than a material dump does.
try:
report = await retry_report(
report_version=2,
reason="invalid_refusal_output",
code="report_refusal_retry",
message="模型返回了拒绝文本,正在重试生成报告",
error_type="InvalidReportOutput",
error_detail=report,
)
except ResearchCancelled:
raise
except Exception as retry_exc: # noqa: BLE001 - keep the confirmed materials
return await complete_with_fallback(
reason="refusal_output",
message="模型返回了拒绝文本且重试失败,已根据可用材料生成保底报告",
error_type=type(retry_exc).__name__,
error_detail=f"retry={type(retry_exc).__name__}: {str(retry_exc)[:600]}",
report_version=3,
)
return report if not _is_refusal_report(report) else await refusal_fallback()
# ── helpers ─────────────────────────────────────────────────────────────────
@@ -998,7 +1164,29 @@ def _is_retryable_report_write_error(exc: Exception) -> bool:
if isinstance(exc, (TimeoutError, ConnectionError, OSError)):
return True
name = type(exc).__name__.lower()
return any(token in name for token in ("timeout", "connection", "network", "streamchunk"))
text = f"{name} {exc}".lower()
return any(
token in text
for token in (
"timeout",
"connection",
"network",
"streamchunk",
"readtimeout",
"connecterror",
"remoteprotocol",
"chunkedencoding",
"apiconnection",
"apitimeout",
"ratelimit",
"unavailable",
"badgateway",
"gateway",
"502",
"503",
"504",
)
)
def _error_diagnostic(stage: str, exc: Exception, *, query: str | None = None) -> dict[str, str]:
@@ -1039,23 +1227,27 @@ def _build_report_fallback(query: str, context_text: str, source_count: int) ->
## 摘要
本报告围绕“{query}”形成基础研究框架。本次外部检索未返回可引用来源,因此以下内容仅用于明确研究范围、分析维度与后续核验路径。
本报告围绕“{query}”给出可继续推进的研究框架。外部检索通道本次没有返回可引用条目,正文依据公开领域常识整理分析维度,供后续核验使用。
## 研究范围与方法
围绕课题梳理核心对象、时间范围、影响因素和可验证指标;后续应补充权威公开数据、政策文件、原始访谈或业务台账进行交叉验证。
围绕课题梳理核心对象、时间范围、影响因素和可验证指标。后续应补充权威公开数据、政策文件、原始访谈或业务台账,再对关键判断做交叉验证。
## 基础分析框架
可从现状与背景、关键驱动因素、风险与不确定性、利益相关方影响及可执行建议五个方面展开研判。所有具体事实、数值和结论均应在补充来源后确认。
可从现状与背景、关键驱动因素、风险与不确定性、利益相关方影响及可执行建议五个方面展开研判。凡涉及具体事实、数值和因果判断,均应在补充来源后确认。
## 后续核验建议
优先补齐时间线、主体关系、公开统计口径和相互独立的原始记录。每一条新增材料都应对回本框架中的对应问题,避免只堆叠摘要。
## 局限性
本次没有外部来源可供引用,不能将本报告中的研究框架视为已完成的事实核验。
本次成稿未附外部引用条目。文中框架用于界定问题,不等于已经完成事实核验。
## 结论
建议以本框架为基础继续补充可追溯材料,并在材料到位后更新各项实证结论。
建议以本框架为基础继续补充可追溯材料,并在材料到位后更新各项实证结论。即使用户侧素材通道暂时不可用,研究报告也应先完成这一版可阅读成稿。
"""
bounded_context = (context_text or "").strip()