feat: 新增报告协作页,并强化 Deep Research 运行诊断与报告兜底
支持浏览器侧素材快照撰写、拒绝报告读时修复、Mermaid PNG 导出与 Word 导出加固。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
65d6b61d5d
commit
f109a95535
65 files changed
+10342
-245
No files matched your search
@@ -61,6 +61,7 @@ _REPORT_SOURCE_MARKER_RE = re.compile(
|
||||
re.IGNORECASE,
|
||||
)
|
||||
_MAX_HTML_EXPORT_IMAGE_BYTES = 20 * 1024 * 1024
|
||||
_RUNTIME_DIAGNOSTICS_REVISION = "deep-research-observability-20260903-v1"
|
||||
|
||||
|
||||
# ── store getters ───────────────────────────────────────────────────────────
|
||||
@@ -143,6 +144,10 @@ class StartJobRequest(BaseModel):
|
||||
# Optional report-config card overrides (mode/tone/outline/…), merged over
|
||||
# the session's frozen config snapshot before the writing job starts.
|
||||
config: dict[str, Any] | None = None
|
||||
# Browser-side compact evidence snapshot for chat collection. This removes
|
||||
# the assumption that the report worker shares the collector worker's local
|
||||
# checkpointer and remains small enough for ordinary reverse-proxy limits.
|
||||
collector_materials: list[dict[str, Any]] | None = None
|
||||
|
||||
|
||||
class ResumeJobRequest(BaseModel):
|
||||
@@ -217,6 +222,11 @@ class SessionResponse(BaseModel):
|
||||
usage: dict[str, Any] | None = None
|
||||
active_job_id: str | None = None
|
||||
error: str | None = None
|
||||
# Compact, read-only execution trace assembled from the durable job/event/
|
||||
# source rows. This intentionally travels with the session response so a
|
||||
# production incident can be diagnosed from the browser without tailing a
|
||||
# busy server log.
|
||||
runtime_diagnostics: dict[str, Any] | None = None
|
||||
# The real LangGraph thread the collector agent chats on (chat collection).
|
||||
runtime_thread_id: str | None = None
|
||||
created_at: str | None = None
|
||||
@@ -252,7 +262,12 @@ class ResearchMessageResponse(BaseModel):
|
||||
# ── helpers ─────────────────────────────────────────────────────────────────
|
||||
|
||||
|
||||
def _session_to_response(row: dict[str, Any], *, full: bool = False) -> SessionResponse:
|
||||
def _session_to_response(
|
||||
row: dict[str, Any],
|
||||
*,
|
||||
full: bool = False,
|
||||
runtime_diagnostics: dict[str, Any] | None = None,
|
||||
) -> SessionResponse:
|
||||
return SessionResponse(
|
||||
id=row["id"],
|
||||
user_id=row.get("user_id"),
|
||||
@@ -268,12 +283,203 @@ def _session_to_response(row: dict[str, Any], *, full: bool = False) -> SessionR
|
||||
usage=row.get("usage_snapshot") if full else None,
|
||||
active_job_id=row.get("active_job_id"),
|
||||
error=row.get("error"),
|
||||
runtime_diagnostics=runtime_diagnostics if full else None,
|
||||
runtime_thread_id=row.get("runtime_thread_id"),
|
||||
created_at=_iso(row.get("created_at")),
|
||||
updated_at=_iso(row.get("updated_at")),
|
||||
)
|
||||
|
||||
|
||||
async def _build_session_runtime_diagnostics(
|
||||
request: Request,
|
||||
row: dict[str, Any],
|
||||
*,
|
||||
user_id: str,
|
||||
) -> dict[str, Any]:
|
||||
"""Build a failure-safe execution summary for one session."""
|
||||
session_id = str(row["id"])
|
||||
report = str(row.get("report_markdown") or "")
|
||||
diagnostic: dict[str, Any] = {
|
||||
"revision": _RUNTIME_DIAGNOSTICS_REVISION,
|
||||
"userMessage": (
|
||||
"本次报告生成链路出现异常;系统无法据此判断为未收集到素材。"
|
||||
"请复制本诊断信息联系管理员。"
|
||||
),
|
||||
"session": {
|
||||
"status": row.get("status"),
|
||||
"activeJobId": row.get("active_job_id"),
|
||||
"sourceCountProjection": int(row.get("source_count") or 0),
|
||||
"reportChars": len(report),
|
||||
"hasReport": bool(report.strip()),
|
||||
},
|
||||
}
|
||||
|
||||
try:
|
||||
source_store = _get_source_store(request)
|
||||
total_count, selected_count = await asyncio.gather(
|
||||
source_store.count_by_session(session_id, user_id=user_id, selected=None),
|
||||
source_store.count_by_session(session_id, user_id=user_id, selected=True),
|
||||
)
|
||||
diagnostic["sourceRows"] = {"total": total_count, "selected": selected_count}
|
||||
except Exception as exc: # noqa: BLE001 - diagnostics cannot break session GET
|
||||
diagnostic["sourceReadError"] = f"{exc.__class__.__name__}: {exc}"[:1200]
|
||||
|
||||
latest_job: dict[str, Any] | None = None
|
||||
try:
|
||||
jobs = await _get_job_store(request).list_by_session(
|
||||
session_id,
|
||||
user_id=user_id,
|
||||
limit=1,
|
||||
)
|
||||
latest_job = jobs[0] if jobs else None
|
||||
if latest_job is None:
|
||||
diagnostic["latestJob"] = None
|
||||
else:
|
||||
input_snapshot = latest_job.get("input_snapshot") or {}
|
||||
result_snapshot = latest_job.get("result_snapshot") or {}
|
||||
diagnostic["latestJob"] = {
|
||||
"id": latest_job.get("id"),
|
||||
"status": latest_job.get("status"),
|
||||
"phase": latest_job.get("phase"),
|
||||
"progress": latest_job.get("progress"),
|
||||
"entry": input_snapshot.get("entry"),
|
||||
"kind": input_snapshot.get("kind"),
|
||||
"attempt": latest_job.get("attempt"),
|
||||
"errorCode": latest_job.get("error_code"),
|
||||
"errorMessage": str(latest_job.get("error_message") or "")[:1200] or None,
|
||||
"leaseOwner": latest_job.get("lease_owner"),
|
||||
"executorRevision": result_snapshot.get("executorRevision"),
|
||||
"resultDiagnostics": result_snapshot.get("diagnostics") or [],
|
||||
}
|
||||
except Exception as exc: # noqa: BLE001 - diagnostics cannot break session GET
|
||||
diagnostic["jobReadError"] = f"{exc.__class__.__name__}: {exc}"[:1200]
|
||||
|
||||
if latest_job is not None:
|
||||
job_id = str(latest_job.get("id") or "")
|
||||
try:
|
||||
event_store = _get_event_store(request)
|
||||
last_seq = await event_store.last_seq(job_id)
|
||||
# Report lifecycle events are at the tail. A bounded read keeps this
|
||||
# endpoint cheap even when source collection produced many events.
|
||||
events = await event_store.list_after(
|
||||
job_id,
|
||||
after=max(0, last_seq - 300),
|
||||
limit=320,
|
||||
)
|
||||
event_type_counts: dict[str, int] = {}
|
||||
notable_events: list[dict[str, Any]] = []
|
||||
for event in events:
|
||||
event_type = str(event.get("event_type") or "unknown")
|
||||
event_type_counts[event_type] = event_type_counts.get(event_type, 0) + 1
|
||||
if event_type in {"warning", "error", "job_failed"}:
|
||||
notable_events.append(
|
||||
{
|
||||
"seq": event.get("seq"),
|
||||
"type": event_type,
|
||||
"phase": event.get("phase"),
|
||||
"payload": event.get("payload") or {},
|
||||
}
|
||||
)
|
||||
last_event = events[-1] if events else None
|
||||
diagnostic["events"] = {
|
||||
"lastSeq": last_seq,
|
||||
"sampledFromSeq": events[0].get("seq") if events else None,
|
||||
"sampledCount": len(events),
|
||||
"typeCounts": event_type_counts,
|
||||
"hasReportStream": bool(
|
||||
event_type_counts.get("report_delta")
|
||||
or event_type_counts.get("report_chunk")
|
||||
),
|
||||
"hasReportCompleted": bool(event_type_counts.get("report_completed")),
|
||||
"lastEvent": (
|
||||
{
|
||||
"seq": last_event.get("seq"),
|
||||
"type": last_event.get("event_type"),
|
||||
"phase": last_event.get("phase"),
|
||||
}
|
||||
if last_event
|
||||
else None
|
||||
),
|
||||
"notable": notable_events[-12:],
|
||||
}
|
||||
except Exception as exc: # noqa: BLE001 - diagnostics cannot break session GET
|
||||
diagnostic["eventReadError"] = f"{exc.__class__.__name__}: {exc}"[:1200]
|
||||
|
||||
return diagnostic
|
||||
|
||||
|
||||
async def _repair_invalid_persisted_report(
|
||||
request: Request,
|
||||
row: dict[str, Any],
|
||||
*,
|
||||
user_id: str,
|
||||
) -> dict[str, Any]:
|
||||
"""Repair a refusal report that an older/bypassing worker marked complete.
|
||||
|
||||
The executor has the primary terminal gate. This read-boundary gate covers
|
||||
already persisted history and any execution path that incorrectly reaches
|
||||
``completed`` without going through the current executor guard.
|
||||
"""
|
||||
report = str(row.get("report_markdown") or "").strip()
|
||||
if not report:
|
||||
return row
|
||||
|
||||
from app.gateway.deep_research_job_executor import (
|
||||
EXECUTOR_REVISION,
|
||||
_terminal_report_validation_error,
|
||||
)
|
||||
from deerflow.agents.deep_research.runners.basic import _build_report_fallback
|
||||
|
||||
validation_error = _terminal_report_validation_error(report)
|
||||
if validation_error is None:
|
||||
return row
|
||||
|
||||
session_id = str(row["id"])
|
||||
rows: list[dict[str, Any]] = []
|
||||
source_read_error: str | None = None
|
||||
try:
|
||||
rows = await _get_source_store(request).list_by_session(
|
||||
session_id,
|
||||
user_id=user_id,
|
||||
selected=None,
|
||||
limit=500,
|
||||
include_content=True,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - an empty-source fallback is valid
|
||||
source_read_error = f"{exc.__class__.__name__}: {exc}"[:1200]
|
||||
|
||||
fallback_parts: list[str] = []
|
||||
for index, source in enumerate(rows, 1):
|
||||
source_url = str(source.get("url") or "").strip()
|
||||
source_header = f"[{index}] {str(source.get('title') or '研究来源')}"
|
||||
if source_url:
|
||||
source_header += f"({source_url})"
|
||||
source_content = str(source.get("raw_content") or source.get("snippet") or "")
|
||||
fallback_parts.append(f"{source_header}\n{source_content}")
|
||||
|
||||
repair_detail = (
|
||||
f"[session_read_repair revision={EXECUTOR_REVISION}] "
|
||||
f"{validation_error}; original={report[:800]}"
|
||||
)
|
||||
if source_read_error:
|
||||
repair_detail += f"; sourceReadError={source_read_error}"
|
||||
replacement = _build_report_fallback(
|
||||
str(row.get("query") or "研究课题"),
|
||||
"\n\n---\n\n".join(fallback_parts),
|
||||
len(rows),
|
||||
)
|
||||
updated = await _get_session_store(request).update(
|
||||
session_id,
|
||||
status="completed",
|
||||
report_markdown=replacement,
|
||||
report_html=None,
|
||||
source_count=max(int(row.get("source_count") or 0), len(rows)),
|
||||
active_job_id=None,
|
||||
error=repair_detail,
|
||||
)
|
||||
return updated or {**row, "report_markdown": replacement, "error": repair_detail}
|
||||
|
||||
|
||||
def _job_to_response(row: dict[str, Any]) -> JobResponse:
|
||||
return JobResponse(
|
||||
id=row["id"],
|
||||
@@ -609,7 +815,13 @@ async def get_session(session_id: str, request: Request) -> SessionResponse:
|
||||
row = await store.get(session_id, user_id=user_id)
|
||||
if row is None:
|
||||
raise HTTPException(status_code=404, detail="Session not found")
|
||||
return _session_to_response(row, full=True)
|
||||
row = await _repair_invalid_persisted_report(request, row, user_id=user_id)
|
||||
runtime_diagnostics = await _build_session_runtime_diagnostics(
|
||||
request,
|
||||
row,
|
||||
user_id=user_id,
|
||||
)
|
||||
return _session_to_response(row, full=True, runtime_diagnostics=runtime_diagnostics)
|
||||
|
||||
|
||||
@router.get("/sessions/{session_id}/report-variants")
|
||||
@@ -712,19 +924,19 @@ async def start_job(session_id: str, body: StartJobRequest, request: Request) ->
|
||||
config_dict = session_config
|
||||
|
||||
if body.entry == "chat":
|
||||
# Chat entry requires a real collector-agent thread to harvest from.
|
||||
if not session.get("runtime_thread_id"):
|
||||
raise HTTPException(status_code=409, detail="Session has no collection thread to harvest")
|
||||
# A missing collector thread is no longer a hard failure. The
|
||||
# executor creates/repairs the runtime thread when possible and, if no
|
||||
# material can be harvested, continues through the zero-material
|
||||
# report fallback instead of rejecting the user's write request.
|
||||
pass
|
||||
elif body.entry == "regenerate":
|
||||
if not is_report_variant:
|
||||
raise HTTPException(status_code=409, detail="Only an independent report variant can be regenerated")
|
||||
selected_count = await _get_source_store(request).count_by_session(
|
||||
session_id,
|
||||
user_id=user_id,
|
||||
selected=True,
|
||||
)
|
||||
if selected_count < 1:
|
||||
raise HTTPException(status_code=409, detail="No selected source material is available for regeneration")
|
||||
# Both an independent report variant and the first write of a
|
||||
# chat-collected session may use the stable static-material writer.
|
||||
# The latter deliberately bypasses the second conversation-harvest
|
||||
# pass that used to run only when “开始撰写” was clicked. Persisted
|
||||
# sources are used when available; an empty pool is valid and the
|
||||
# report runner completes from its public-knowledge fallback.
|
||||
pass
|
||||
|
||||
if body.entry in ("chat", "regenerate") and body.config:
|
||||
# Both first-write and regenerate use the ordinary report engine. The
|
||||
@@ -766,6 +978,7 @@ async def start_job(session_id: str, body: StartJobRequest, request: Request) ->
|
||||
"title": session.get("title", ""),
|
||||
"runtime_thread_id": session.get("runtime_thread_id"),
|
||||
"entry": body.entry,
|
||||
"collector_materials": body.collector_materials if body.entry == "chat" else None,
|
||||
}
|
||||
|
||||
job, created = await job_store.try_create_or_get_active(
|
||||
@@ -787,6 +1000,10 @@ async def start_job(session_id: str, body: StartJobRequest, request: Request) ->
|
||||
user_id=user_id,
|
||||
status="running",
|
||||
active_job_id=job["id"],
|
||||
# A failed session may be restarted after its code/configuration
|
||||
# has been repaired. Do not keep presenting the previous job's
|
||||
# persisted error as though the newly queued job raised it.
|
||||
error=None,
|
||||
)
|
||||
except Exception: # noqa: BLE001
|
||||
logger.exception(
|
||||
@@ -1082,7 +1299,12 @@ async def stream_job(
|
||||
"type": "job_status",
|
||||
"phase": current.get("phase", "done"),
|
||||
"timestamp": _iso(datetime.now(UTC)),
|
||||
"payload": {"status": current["status"], "progress": current.get("progress", 0)},
|
||||
"payload": {
|
||||
"status": current["status"],
|
||||
"progress": current.get("progress", 0),
|
||||
"errorCode": current.get("error_code"),
|
||||
"errorMessage": current.get("error_message"),
|
||||
},
|
||||
},
|
||||
event_id=str(cursor + 1),
|
||||
)
|
||||
|
||||
@@ -143,6 +143,7 @@ class MarkdownDocxExportRequest(BaseModel):
|
||||
|
||||
title: str | None = Field(default=None, max_length=300)
|
||||
markdown: str = Field(..., min_length=1, max_length=2_000_000)
|
||||
embedded_images: dict[str, str] = Field(default_factory=dict)
|
||||
|
||||
|
||||
class DocumentRewriteRequest(BaseModel):
|
||||
@@ -391,7 +392,12 @@ async def export_markdown_docx(body: MarkdownDocxExportRequest) -> Response:
|
||||
persist the supplied Markdown.
|
||||
"""
|
||||
try:
|
||||
content = await asyncio.to_thread(build_markdown_docx, body.markdown, body.title)
|
||||
content = await asyncio.to_thread(
|
||||
build_markdown_docx,
|
||||
body.markdown,
|
||||
body.title,
|
||||
embedded_images=body.embedded_images or None,
|
||||
)
|
||||
except WordExportFontError as exc:
|
||||
raise HTTPException(status_code=503, detail=str(exc)) from exc
|
||||
except WordExportError as exc:
|
||||
|
||||
Reference in new issue
Block a user