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

@@ -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()