feat: 新增报告协作页,并强化 Deep Research 运行诊断与报告兜底

支持浏览器侧素材快照撰写、拒绝报告读时修复、Mermaid PNG 导出与 Word 导出加固。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-09-03 11:16:50 +08:00
1 parent 65d6b61d5d
commit f109a95535
65 files changed
+10342 -245

No files matched your search

@@ -22,8 +22,10 @@ full result without extra joins.
from __future__ import annotations
import asyncio
import hashlib
import logging
import os
import re
import time
import uuid as _uuid
from collections.abc import Awaitable, Callable
@@ -59,6 +61,7 @@ logger = logging.getLogger(__name__)
# ── constants ───────────────────────────────────────────────────────────────
WORKER_ID = f"w-{os.getpid()}-{_uuid.uuid4().hex[:8]}"
EXECUTOR_REVISION = "deep-research-browser-db-checkpoint-20260903-v6"
_LEASE_TTL_SECONDS = 60
_HEARTBEAT_INTERVAL = 20.0
@@ -66,6 +69,86 @@ _CANCEL_POLL_INTERVAL = 5.0
_REPORT_PROJECTION_RETRY_ATTEMPTS = 3
_REPORT_PROJECTION_RETRY_DELAY_SECONDS = 0.5
# This validation deliberately lives in the executor, not in an individual
# runner. Every mode and every entry must pass this gate immediately before a
# session can be marked completed. Keep the semantic spans generous: the
# production refusal often contains a long assessment between “资料不足” and
# “无法生成报告”, so a short literal-marker check is not sufficient.
_TERMINAL_REPORT_REFUSAL_PATTERNS = (
re.compile(
r"(?:无法|不能|未能|不可以|不宜|难以|不具备条件|不足以)"
r".{0,120}?(?:生成|撰写|产出|输出|完成|提供).{0,40}?(?:研究)?报告",
re.S,
),
re.compile(
r"(?:未收集到|未找到|没有|缺少|缺乏|不足).{0,120}?(?:资料|材料|信息|来源|证据)"
r".{0,180}?(?:无法|不能|未能|不可以|不宜|难以).{0,80}?(?:生成|撰写|产出|输出|完成|提供).{0,40}?(?:研究)?报告",
re.S,
),
)
def _terminal_report_validation_error(report: str | None) -> str | None:
"""Return why a model response cannot be persisted as a completed report."""
text = (report or "").strip()
compact = re.sub(r"\s+", "", text)
if not compact:
return "empty_report"
headings = re.findall(r"(?m)^#{1,6}\s+\S+", text)
# A real report may quote or discuss a refusal/material-gap sentence in a
# limitations section. Only replace short or unstructured refusal output;
# a substantive multi-section report is accepted unchanged.
if (
(len(compact) < 800 or len(headings) < 2)
and any(pattern.search(compact) for pattern in _TERMINAL_REPORT_REFUSAL_PATTERNS)
):
return "refusal_semantics"
return None
def _materials_from_browser_snapshot(
values: list[dict[str, Any]] | None,
*,
query: str,
) -> list[ResearchMaterial]:
"""Validate and bound the evidence frozen by the browser."""
allowed_types = {"web", "knowledge", "skill", "mcp", "file", "other"}
materials: list[ResearchMaterial] = []
seen: set[str] = set()
for value in values or []:
if not isinstance(value, dict):
continue
title = str(value.get("title") or "").strip()[:500]
url = str(value.get("url") or "").strip()[:2000] or None
content = str(value.get("raw_content") or value.get("snippet") or "").strip()[:6000]
if not title and not url and not content:
continue
raw_key = str(value.get("id") or value.get("rec_uuid") or url or f"{title}\n{content[:240]}")
digest = hashlib.sha256(raw_key.encode("utf-8", errors="ignore")).hexdigest()
material_id = str(value.get("id") or f"src_{digest[:16]}")[:128]
if material_id in seen:
continue
seen.add(material_id)
source_type = str(value.get("source_type") or "other")
materials.append(
ResearchMaterial(
id=material_id,
query=query,
title=title or "研究来源",
url=url,
raw_content=content,
snippet=str(value.get("snippet") or content[:500]).strip()[:500] or None,
source=str(value.get("source") or "browser_collector").strip()[:200],
source_type=source_type if source_type in allowed_types else "other",
rec_uuid=str(value.get("rec_uuid") or "").strip()[:128] or None,
content_hash=digest[:32],
metadata={"retrieval_channel": "browser_material_snapshot"},
)
)
if len(materials) >= 80:
break
return materials
# Phase → progress% mapping for the job timeline.
_PHASE_PROGRESS: dict[str, int] = {
"initializing": 0,
@@ -83,6 +166,21 @@ _PHASE_PROGRESS: dict[str, int] = {
}
def _session_diagnostic_error(diagnostics: list[dict[str, Any]]) -> str | None:
"""Render real degraded-run causes into the session API's error field."""
lines: list[str] = []
for item in diagnostics[-20:]:
code = str(item.get("code") or "deep_research_degraded")
stage = str(item.get("stage") or "unknown")
error_type = str(item.get("errorType") or item.get("outcome") or "Warning")
detail = str(item.get("detail") or "").strip()
line = f"[{code}] stage={stage} type={error_type}"
if detail:
line += f": {detail}"
lines.append(line[:1200])
return "\n".join(lines)[:8000] or None
class _JobUser:
"""Minimal CurrentUser: satisfies user_context's ``.id`` protocol."""
@@ -124,10 +222,19 @@ class RecordingEventSink:
self._session_id = session_id
self._user_id = user_id
self._lease_owner = lease_owner
self.diagnostics: list[dict[str, Any]] = []
async def emit(self, type, *, phase="initializing", payload=None): # noqa: A002
# Delegate first (persist-then-stream ordering).
ev = await self._delegate.emit(type, phase=phase, payload=payload or {})
diagnostic = (payload or {}).get("diagnostic")
if isinstance(diagnostic, dict):
self.diagnostics.append(
{
"code": str((payload or {}).get("code") or type),
**diagnostic,
}
)
# Side-effects.
if type == "source_added" and self._source_store is not None:
@@ -140,8 +247,17 @@ class RecordingEventSink:
user_id=self._user_id,
**src,
)
except Exception: # noqa: BLE001
logger.debug("source upsert failed for %s", src.get("id"), exc_info=True)
except Exception as exc: # noqa: BLE001
self.diagnostics.append(
{
"code": "source_projection_failed",
"stage": "collecting",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
"sourceId": str(src.get("id") or ""),
}
)
logger.warning("source upsert failed for %s", src.get("id"), exc_info=True)
elif type == "phase_changed":
new_phase = (payload or {}).get("to", phase)
@@ -303,18 +419,140 @@ class DeepResearchJobExecutor:
lease_owner=lease_owner,
)
return
result = await self._execute(
job_id=job_id,
session_id=session_id,
from deerflow.agents.deep_research.runners.basic import _build_report_fallback
entry = str(snapshot.get("entry") or "legacy")
snapshot_projection_diagnostics: list[dict[str, Any]] = []
# A structural regeneration has its own cloned durable source pool.
# The browser snapshot is intentionally kept frozen in the job
# input until the final fallback step. Persisting it here would
# contaminate the database channel and make it impossible to tell
# whether the runtime/checkpoint or durable-source path worked.
try:
result = await self._execute(
job_id=job_id,
session_id=session_id,
user_id=user_id,
query=query,
title=title,
config=config,
lease_owner=lease_owner,
cancel_token=cancel_token,
entry=entry,
collector_materials=(snapshot.get("collector_materials") or []) if entry == "chat" else None,
)
except (ResearchAwaitingInput, ResearchCancelled):
raise
except Exception as exc: # noqa: BLE001 - complete without a second model call
# Do not repeat a full model generation. Preserve any durable
# sources and complete with a deterministic report so one
# failed model/checkpointer/event path cannot stop the job.
logger.exception(
"deep-research job %s execution failed; completing from durable materials",
job_id,
)
rows: list[dict[str, Any]] = []
source_read_error: Exception | None = None
snapshot_materials: list[ResearchMaterial] = []
snapshot_read_error: Exception | None = None
if entry == "chat":
try:
snapshot_materials = _materials_from_browser_snapshot(
snapshot.get("collector_materials") or [],
query=query,
)
except Exception as snapshot_exc: # noqa: BLE001
snapshot_read_error = snapshot_exc
if not snapshot_materials and self._source_store is not None:
try:
rows = await self._source_store.list_by_session(
session_id,
user_id=user_id,
selected=None,
limit=500,
include_content=True,
)
except Exception as read_exc: # noqa: BLE001
source_read_error = read_exc
fallback_parts: list[str] = []
source_ids: list[str] = []
seen_source_ids: set[str] = set()
for index, row in enumerate(rows, 1):
source_id = str(row.get("id") or "")
if source_id and source_id in seen_source_ids:
continue
if source_id:
seen_source_ids.add(source_id)
source_ids.append(source_id)
source_url = str(row.get("url") or "").strip()
source_header = f"[{len(source_ids) or index}] {str(row.get('title') or '研究来源')}"
if source_url:
source_header += f"({source_url})"
source_content = str(row.get("raw_content") or row.get("snippet") or "")
fallback_parts.append(f"{source_header}\n{source_content}")
for material in snapshot_materials:
if material.id in seen_source_ids:
continue
seen_source_ids.add(material.id)
source_ids.append(material.id)
source_header = f"[{len(source_ids)}] {material.title or '研究来源'}"
if material.url:
source_header += f"({material.url})"
fallback_parts.append(f"{source_header}\n{material.raw_content or material.snippet or ''}")
diagnostics = [
{
"code": "execution_failed_report_fallback",
"stage": "execution",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
}
]
if source_read_error is not None:
diagnostics.append(
{
"code": "fallback_source_read_failed",
"stage": "collecting",
"errorType": source_read_error.__class__.__name__,
"detail": str(source_read_error)[:1200]
or source_read_error.__class__.__name__,
}
)
if snapshot_read_error is not None:
diagnostics.append(
{
"code": "fallback_browser_snapshot_read_failed",
"stage": "collecting",
"errorType": snapshot_read_error.__class__.__name__,
"detail": str(snapshot_read_error)[:1200]
or snapshot_read_error.__class__.__name__,
}
)
result = DeepResearchResult(
report_markdown=_build_report_fallback(
query,
"\n\n---\n\n".join(fallback_parts),
len(source_ids),
),
source_ids=source_ids,
diagnostics=diagnostics,
)
if snapshot_projection_diagnostics:
result = result.model_copy(
update={
"diagnostics": [
*result.diagnostics,
*snapshot_projection_diagnostics,
]
}
)
await self._mark_completed(
job_id,
session_id,
lease_owner,
result,
user_id=user_id,
query=query,
title=title,
config=config,
lease_owner=lease_owner,
cancel_token=cancel_token,
entry=str(snapshot.get("entry") or "legacy"),
)
await self._mark_completed(job_id, session_id, lease_owner, result)
except ResearchAwaitingInput as pause:
logger.info("deep-research job %s awaiting human plan review", job_id)
@@ -1324,6 +1562,7 @@ class DeepResearchJobExecutor:
lease_owner: str | None,
cancel_token: CancellationToken,
entry: str = "legacy",
collector_materials: list[dict[str, Any]] | None = None,
) -> DeepResearchResult:
from deerflow.agents.deep_research.adapters.artifacts import ThreadOutputsArtifactWriter
from deerflow.agents.deep_research.adapters.context import DeerFlowContextCompressor
@@ -1359,10 +1598,14 @@ class DeepResearchJobExecutor:
# from the collector-agent conversation; legacy keeps the search tiers.
if entry == "chat":
material_provider = await self._build_chat_materials(
job_id=job_id,
session_id=session_id,
user_id=user_id,
runtime_thread_id=runtime_thread_id,
query=query,
events=recording_sink,
cancellation=cancel_token,
collector_materials=collector_materials,
)
elif entry == "regenerate":
material_provider = await self._build_selected_materials(
@@ -1419,6 +1662,12 @@ class DeepResearchJobExecutor:
)
# Fold the summary call's tokens into the billed totals.
result = result.model_copy(update={"usage": llm_backend.usage_totals})
diagnostics = [
*getattr(base_sink, "diagnostics", []),
*recording_sink.diagnostics,
]
if diagnostics:
result = result.model_copy(update={"diagnostics": diagnostics})
return result
async def _build_selected_materials(
@@ -1444,6 +1693,19 @@ class DeepResearchJobExecutor:
limit=500,
include_content=True,
)
if not rows:
# Before a first report is written, collector material may already
# be durable but not yet carry the runner's later curation flag.
# Treat every source in this session as the static input pool. A
# genuinely empty session remains valid and is handled by the
# runner's zero-material report path.
rows = await self._source_store.list_by_session(
session_id,
user_id=user_id,
selected=None,
limit=500,
include_content=True,
)
allowed_types = {"web", "knowledge", "skill", "mcp", "file", "other"}
materials = [
ResearchMaterial(
@@ -1468,16 +1730,24 @@ class DeepResearchJobExecutor:
if row.get("id")
]
if not materials:
raise RuntimeError("No selected source material is available for regeneration")
logger.warning(
"deep-research static report writer has no persisted sources; continuing with no-material fallback "
"(session_id=%s)",
session_id,
)
return StaticHarvestMaterialProvider(materials)
async def _build_chat_materials(
self,
*,
job_id: str,
session_id: str,
user_id: str,
runtime_thread_id: str,
query: str,
events,
cancellation: CancellationToken,
collector_materials: list[dict[str, Any]] | None = None,
):
"""Harvest the collector thread into a static material pool.
@@ -1485,22 +1755,207 @@ class DeepResearchJobExecutor:
the sources panel fills exactly like the legacy channel (the recording
sink persists them to the source store).
"""
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.collection.thread_harvester import (
MAX_HARVESTED_MATERIALS,
StaticHarvestMaterialProvider,
harvest_thread_materials,
)
cancellation.raise_if_cancelled()
if self._checkpointer is None:
raise RuntimeError("Chat-entry deep-research jobs require a checkpointer")
if not runtime_thread_id:
raise RuntimeError("Chat-entry deep-research job has no runtime thread")
harvested: list[ResearchMaterial] = []
agent_summary = ""
browser_material_count = 0
checkpoint_material_count = 0
durable_material_count = 0
material_channel = "none"
browser_snapshot_persisted = False
channel_failures: list[dict[str, str]] = []
def persisted_rows_to_materials(rows: list[dict[str, Any]]) -> list[ResearchMaterial]:
allowed_types = {"web", "knowledge", "skill", "mcp", "file", "other"}
return [
ResearchMaterial(
id=str(row.get("id") or ""),
query=str(row.get("first_seen_query") or query),
title=str(row.get("title") or ""),
url=row.get("url"),
raw_content=str(row.get("raw_content") or row.get("snippet") or ""),
snippet=row.get("snippet"),
source=str(row.get("source") or ""),
source_type=(
str(row.get("source_type"))
if str(row.get("source_type")) in allowed_types
else "other"
),
published_at=row.get("published_at"),
relevance_score=row.get("relevance_score"),
rec_uuid=row.get("rec_uuid"),
content_hash=str(row.get("content_hash") or ""),
)
for row in rows
if row.get("id")
]
async def try_browser_snapshot() -> None:
nonlocal browser_material_count, browser_snapshot_persisted, harvested, material_channel
if not collector_materials:
channel_failures.append(
{
"channel": "browser_snapshot",
"outcome": "absent",
"detail": "浏览器未传入素材快照",
}
)
return
try:
browser_materials = _materials_from_browser_snapshot(
collector_materials,
query=query,
)
browser_material_count = len(browser_materials)
harvested = dedupe_materials(browser_materials)[:MAX_HARVESTED_MATERIALS]
if not harvested:
channel_failures.append(
{
"channel": "browser_snapshot",
"outcome": "empty",
"detail": "浏览器快照中没有可用素材",
}
)
return
material_channel = "browser_snapshot"
if self._source_store is None:
return
browser_snapshot_persisted = True
for material in harvested:
try:
await self._source_store.upsert(
session_id=session_id,
job_id=job_id,
user_id=user_id or None,
**material.to_persistence_dict(material.query),
)
except Exception as exc: # noqa: BLE001 - report can still use the snapshot
browser_snapshot_persisted = False
channel_failures.append(
{
"channel": "browser_snapshot_projection",
"outcome": "error",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
}
)
logger.warning(
"browser snapshot source projection failed for %s",
material.id,
exc_info=True,
)
except Exception as exc: # noqa: BLE001 - later material channels remain valid
channel_failures.append(
{
"channel": "browser_snapshot",
"outcome": "error",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
}
)
logger.warning(
"deep-research browser material snapshot could not be normalized",
exc_info=True,
)
# First-report recovery is deliberately sequential, not additive:
# browser snapshot → durable source rows → runtime checkpoint. Once a
# channel provides material, later channels are not opened.
await try_browser_snapshot()
if not harvested:
try:
if self._checkpointer is None:
raise RuntimeError("Deep Research checkpointer is unavailable")
if not runtime_thread_id:
raise RuntimeError("Deep Research collector thread is unavailable")
checkpoint_materials, checkpoint_summary = await harvest_thread_materials(
checkpointer=self._checkpointer,
runtime_thread_id=runtime_thread_id,
query=query,
)
checkpoint_material_count = len(checkpoint_materials)
agent_summary = checkpoint_summary or ""
harvested = dedupe_materials(checkpoint_materials)[:MAX_HARVESTED_MATERIALS]
if harvested:
material_channel = "runtime_checkpoint"
else:
channel_failures.append(
{
"channel": "runtime_checkpoint",
"outcome": "empty",
"detail": "运行时会话未返回可用素材",
}
)
except ResearchCancelled:
raise
except Exception as exc: # noqa: BLE001 - all earlier channels remain available
channel_failures.append(
{
"channel": "runtime_checkpoint",
"outcome": "error",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
}
)
logger.warning(
"deep-research collector checkpoint harvest failed; no earlier material channel was usable "
"(thread=%s, error=%s)",
runtime_thread_id,
exc.__class__.__name__,
)
if not harvested:
if self._source_store is None:
channel_failures.append(
{
"channel": "durable_sources",
"outcome": "unavailable",
"detail": "素材存储库不可用",
}
)
else:
try:
rows = await self._source_store.list_by_session(
session_id,
user_id=user_id,
selected=None,
limit=500,
include_content=True,
)
persisted_materials = persisted_rows_to_materials(rows)
durable_material_count = len(persisted_materials)
harvested = dedupe_materials(persisted_materials)[:MAX_HARVESTED_MATERIALS]
if harvested:
material_channel = "durable_sources"
else:
channel_failures.append(
{
"channel": "durable_sources",
"outcome": "empty",
"detail": "数据库中没有可用素材",
}
)
except Exception as exc: # noqa: BLE001 - no-material report remains valid
channel_failures.append(
{
"channel": "durable_sources",
"outcome": "error",
"errorType": exc.__class__.__name__,
"detail": str(exc)[:1200] or exc.__class__.__name__,
}
)
logger.warning(
"chat deep-research durable material read failed; entering no-material route if needed",
exc_info=True,
)
harvested, agent_summary = await harvest_thread_materials(
checkpointer=self._checkpointer,
runtime_thread_id=runtime_thread_id,
query=query,
)
# Freeze the harvested list before publishing any progress. Source
# event persistence is intentionally best-effort: a bad payload or a
# temporarily unavailable event table must never prevent the writer
@@ -1511,42 +1966,80 @@ class DeepResearchJobExecutor:
"collection_completed",
phase="collecting",
payload={
"source": "chat_thread",
"source": material_channel,
"materialCount": material_provider.material_count,
"browserMaterialCount": browser_material_count,
"checkpointMaterialCount": checkpoint_material_count,
"durableMaterialCount": durable_material_count,
"agentSummaryChars": len(agent_summary),
},
)
except Exception: # noqa: BLE001 - progress telemetry must not lose evidence
logger.warning("chat deep-research collection event failed; retaining harvested materials", exc_info=True)
for material in harvested:
# A last-resort browser snapshot is written directly above. Avoid a
# second source-added projection only when every direct write succeeded.
if material_channel != "browser_snapshot" or not browser_snapshot_persisted:
for material in harvested:
try:
await events.emit(
"source_added",
phase="collecting",
payload={
"sourceId": material.id,
"title": material.title,
"url": material.url,
"sourceType": material.source_type,
"source": material.to_persistence_dict(material.query),
},
)
except Exception: # noqa: BLE001 - source rows are a projection, not the input
logger.warning(
"chat deep-research source event failed for %s; retaining harvested materials",
material.id,
exc_info=True,
)
if material_provider.material_count and material_channel != "browser_snapshot":
try:
await events.emit(
"source_added",
"warning",
phase="collecting",
payload={
"sourceId": material.id,
"title": material.title,
"url": material.url,
"sourceType": material.source_type,
"source": material.to_persistence_dict(material.query),
"code": "material_channel_fallback_used",
"message": f"前序素材通道不可用,已使用{material_channel}继续撰写报告",
"recoverable": True,
"diagnostic": {
"stage": "collecting",
"outcome": "sequential_material_fallback",
"selectedChannel": material_channel,
"browserMaterialCount": browser_material_count,
"checkpointMaterialCount": checkpoint_material_count,
"durableMaterialCount": durable_material_count,
"runtimeThreadId": runtime_thread_id,
"failures": channel_failures,
},
},
)
except Exception: # noqa: BLE001 - source rows are a projection, not the input
logger.warning(
"chat deep-research source event failed for %s; retaining harvested materials",
material.id,
exc_info=True,
except Exception: # noqa: BLE001 - diagnostics never block writing
logger.warning("failed to publish material fallback diagnostic", exc_info=True)
if not material_provider.material_count:
try:
await events.emit(
"warning",
phase="collecting",
payload={
"code": "chat_harvest_empty",
"message": "所有素材通道均为空,已继续进入无素材报告流程",
"recoverable": True,
"diagnostic": {
"stage": "collecting",
"outcome": "all_material_channels_empty",
"runtimeThreadId": runtime_thread_id,
"failures": channel_failures,
},
},
)
if not harvested:
await events.emit(
"warning",
phase="collecting",
payload={
"code": "chat_harvest_empty",
"message": "收集对话中没有可用的检索材料,报告将仅基于收集员小结生成。",
"recoverable": True,
},
)
except Exception: # noqa: BLE001 - diagnostics never block writing
logger.warning("failed to publish empty-material diagnostic", exc_info=True)
return material_provider
async def _generate_report_summary(
@@ -1617,7 +2110,78 @@ class DeepResearchJobExecutor:
# ── terminal-state writers ──────────────────────────────────────────────
async def _mark_completed(self, job_id: str, session_id: str, lease_owner: str | None, result: DeepResearchResult) -> None:
async def _mark_completed(
self,
job_id: str,
session_id: str,
lease_owner: str | None,
result: DeepResearchResult,
*,
user_id: str,
query: str,
) -> None:
# Final persistence gate. Even if a runner/provider takes an
# unexpected path, refusal prose must never become the durable report.
# Keep the original model output as a visible diagnostic and replace
# it with a conservative report assembled from every persisted source.
from deerflow.agents.deep_research.runners.basic import _build_report_fallback
validation_error = _terminal_report_validation_error(result.report_markdown)
if validation_error is not None:
invalid_output = result.report_markdown
rows: list[dict[str, Any]] = []
source_load_error: Exception | None = None
if self._source_store is not None:
try:
rows = await self._source_store.list_by_session(
session_id,
user_id=user_id,
selected=None,
limit=500,
include_content=True,
)
except Exception as exc: # noqa: BLE001 - fallback must still complete
source_load_error = exc
fallback_parts: list[str] = []
for index, row in enumerate(rows, 1):
source_url = str(row.get("url") or "").strip()
source_header = f"[{index}] {str(row.get('title') or '研究来源')}"
if source_url:
source_header += f"({source_url})"
source_content = str(row.get("raw_content") or row.get("snippet") or "")
fallback_parts.append(f"{source_header}\n{source_content}")
diagnostics = [
*result.diagnostics,
{
"code": "terminal_invalid_report_replaced",
"stage": "persisting",
"errorType": "InvalidReportOutput",
"detail": f"{validation_error}: {invalid_output[:1200]}",
},
]
if source_load_error is not None:
diagnostics.append(
{
"code": "terminal_fallback_source_load_failed",
"stage": "persisting",
"errorType": source_load_error.__class__.__name__,
"detail": str(source_load_error)[:1200],
}
)
result = result.model_copy(
update={
"report_markdown": _build_report_fallback(
query or "研究课题",
"\n\n---\n\n".join(fallback_parts),
len(rows) or len(result.source_ids),
),
"report_html": None,
"diagnostics": diagnostics,
}
)
# Persist the report projection before exposing a terminal completed
# job. The session row is the durable report itself; marking the job
# complete first and suppressing a session-write failure can otherwise
@@ -1639,6 +2203,8 @@ class DeepResearchJobExecutor:
"report_markdown": result.report_markdown[:200] if result.report_markdown else "",
"source_ids": result.source_ids,
"plan": result.plan,
"diagnostics": result.diagnostics,
"executorRevision": EXECUTOR_REVISION,
},
)
# Emit a terminal event for SSE consumers.
@@ -1674,6 +2240,7 @@ class DeepResearchJobExecutor:
usage_snapshot={**(result.usage or {}), "lastJobId": job_id},
source_count=len(result.source_ids),
active_job_id=None,
error=_session_diagnostic_error(result.diagnostics),
)
if updated is not None:
return
@@ -1717,7 +2284,14 @@ class DeepResearchJobExecutor:
await self._session_store.update(
session_id,
status="failed",
error=f"{code}: {message}",
# Correlate the user-visible session error with the exact
# durable job and gateway worker that produced it. This
# distinguishes a newly raised failure from stale session
# state and exposes mixed-version workers immediately.
error=(
f"[job={job_id} worker={WORKER_ID} revision={EXECUTOR_REVISION}] "
f"{code}: {message}"
),
active_job_id=None,
)
with suppress(Exception): # noqa: BLE001
@@ -1805,4 +2379,10 @@ class DeepResearchJobExecutor:
return thread_id
__all__ = ["DeepResearchJobExecutor", "WORKER_ID", "_LEASE_TTL_SECONDS"]
__all__ = [
"DeepResearchJobExecutor",
"EXECUTOR_REVISION",
"WORKER_ID",
"_LEASE_TTL_SECONDS",
"_terminal_report_validation_error",
]
@@ -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:
@@ -9,6 +9,8 @@ recipient's computer does not need the font installed.
from __future__ import annotations
import base64
import binascii
import hashlib
import io
import os
@@ -82,7 +84,23 @@ class TableBlock:
rows: list[list[str]]
Block = ParagraphBlock | TableBlock
@dataclass(slots=True)
class ImageBlock:
alt: str
data: bytes
media_name: str
width_px: int
height_px: int
Block = ParagraphBlock | TableBlock | ImageBlock
_EMU_PER_TWIP = 635
_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
_MAX_EMBEDDED_IMAGES = 40
_MAX_EMBEDDED_IMAGE_BYTES = 8 * 1024 * 1024
_EMBEDDED_IMAGE_ID = re.compile(r"^embedded:([A-Za-z0-9_-]{1,80})$")
_DATA_PNG_URI = re.compile(r"^data:image/png;base64,([A-Za-z0-9+/=\s]+)$", re.IGNORECASE)
def _safe_xml_text(value: str) -> str:
@@ -260,11 +278,67 @@ def _extract_title(markdown: str, explicit_title: str | None) -> tuple[str | Non
return (explicit_title or "").strip() or None, lines
def _parse_markdown(markdown: str, explicit_title: str | None) -> tuple[str | None, list[Block]]:
def _png_size(data: bytes) -> tuple[int, int]:
if len(data) < 24 or data[:8] != _PNG_SIGNATURE:
raise WordExportError("嵌入的流程图不是有效的 PNG 图片。")
width, height = struct.unpack(">II", data[16:24])
if width < 1 or height < 1 or width > 20_000 or height > 20_000:
raise WordExportError("嵌入图片尺寸无效。")
return width, height
def _decode_png_base64(payload: str) -> bytes:
try:
data = base64.b64decode(re.sub(r"\s+", "", payload), validate=False)
except (ValueError, binascii.Error) as exc:
raise WordExportError("嵌入图片编码无效。") from exc
if not data or len(data) > _MAX_EMBEDDED_IMAGE_BYTES:
raise WordExportError("嵌入图片为空或超过 8 MB 限制。")
_png_size(data)
return data
def _resolve_markdown_image(
alt: str,
target: str,
embedded_images: dict[str, str],
image_index: int,
) -> Block:
payload: str | None = None
embedded = _EMBEDDED_IMAGE_ID.match(target.strip())
if embedded:
payload = embedded_images.get(embedded.group(1))
else:
data_uri = _DATA_PNG_URI.match(target.strip())
if data_uri:
payload = data_uri.group(1)
if not payload:
return ParagraphBlock("image", f"图片:{alt}|{target}")
try:
data = _decode_png_base64(payload)
width, height = _png_size(data)
except WordExportError:
return ParagraphBlock("image", f"图片:{alt}|{target}")
return ImageBlock(
alt=alt,
data=data,
media_name=f"image{image_index}.png",
width_px=width,
height_px=height,
)
def _parse_markdown(
markdown: str,
explicit_title: str | None,
embedded_images: dict[str, str] | None = None,
) -> tuple[str | None, list[Block]]:
title, lines = _extract_title(markdown, explicit_title)
blocks: list[Block] = []
paragraph_buffer: list[str] = []
in_fence = False
images = embedded_images or {}
image_count = 0
def flush_paragraph() -> None:
if paragraph_buffer:
@@ -313,11 +387,20 @@ def _parse_markdown(markdown: str, explicit_title: str | None) -> tuple[str | No
blocks.append(TableBlock(header, rows))
continue
image = re.match(r'^\s*!\[([^\]]*)\]\(([^)\s]+)(?:\s+["\'][^"\']*["\'])?\)\s*$', raw)
image = re.match(r'^\s*!\[([^\]]*)\]\(([^)]+)(?:\s+["\'][^"\']*["\'])?\)\s*$', raw)
if image:
flush_paragraph()
alt = image.group(1).strip() or "未命名图片"
blocks.append(ParagraphBlock("image", f"图片:{alt}|{image.group(2)}"))
target = image.group(2).strip()
if image_count >= _MAX_EMBEDDED_IMAGES and (
_EMBEDDED_IMAGE_ID.match(target) or _DATA_PNG_URI.match(target)
):
blocks.append(ParagraphBlock("image", f"图片:{alt}|{target}"))
else:
resolved = _resolve_markdown_image(alt, target, images, image_count + 1)
if isinstance(resolved, ImageBlock):
image_count += 1
blocks.append(resolved)
index += 1
continue
@@ -357,12 +440,20 @@ def _parse_markdown(markdown: str, explicit_title: str | None) -> tuple[str | No
class _DocumentRelationships:
def __init__(self) -> None:
self._hyperlinks: list[tuple[str, str]] = []
self._images: list[tuple[str, str]] = []
self._drawing_id = 0
def add_hyperlink(self, target: str) -> str:
relation_id = f"rId{100 + len(self._hyperlinks)}"
self._hyperlinks.append((relation_id, target))
return relation_id
def add_image(self, target: str) -> tuple[str, int]:
self._drawing_id += 1
relation_id = f"rId{200 + len(self._images)}"
self._images.append((relation_id, target))
return relation_id, self._drawing_id
def xml(self) -> str:
fixed = [
("rId1", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles", "styles.xml"),
@@ -380,6 +471,10 @@ class _DocumentRelationships:
f'<Relationship Id="{relation_id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" Target="{_xml_attr(target)}" TargetMode="External"/>'
for relation_id, target in self._hyperlinks
)
relationships += "".join(
f'<Relationship Id="{relation_id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="{_xml_attr(target)}"/>'
for relation_id, target in self._images
)
return f'{_XML_DECL}<Relationships xmlns="{_PACKAGE_REL_NS}">{relationships}</Relationships>'
@@ -471,6 +566,45 @@ def _paragraph_xml(
return f"<w:p><w:pPr>{properties}</w:pPr>{children}</w:p>"
def _image_extent_emu(width_px: int, height_px: int) -> tuple[int, int]:
max_width_emu = CONTENT_WIDTH_TWIPS * _EMU_PER_TWIP
width_emu = max(1, int(width_px * 9525))
height_emu = max(1, int(height_px * 9525))
if width_emu > max_width_emu:
scale = max_width_emu / width_emu
width_emu = max_width_emu
height_emu = max(1, int(height_emu * scale))
return width_emu, height_emu
def _embedded_image_xml(block: ImageBlock, relationships: _DocumentRelationships) -> str:
relation_id, drawing_id = relationships.add_image(f"media/{block.media_name}")
cx, cy = _image_extent_emu(block.width_px, block.height_px)
name = _xml_attr(block.alt or block.media_name)
drawing = (
'<w:r><w:drawing><wp:inline distT="0" distB="0" distL="0" distR="0">'
f'<wp:extent cx="{cx}" cy="{cy}"/>'
f'<wp:docPr id="{drawing_id}" name="{name}"/>'
'<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">'
'<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">'
'<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">'
f'<pic:nvPicPr><pic:cNvPr id="0" name="{name}"/><pic:cNvPicPr/></pic:nvPicPr>'
f'<pic:blipFill><a:blip r:embed="{relation_id}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill>'
"<pic:spPr>"
f'<a:xfrm><a:off x="0" y="0"/><a:ext cx="{cx}" cy="{cy}"/></a:xfrm>'
'<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>'
"</pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>"
)
return (
"<w:p><w:pPr>"
'<w:pStyle w:val="ImageCaption"/>'
'<w:jc w:val="center"/>'
'<w:spacing w:before="160" w:after="160" w:line="240" w:lineRule="auto"/>'
'<w:ind w:left="0" w:hanging="0" w:firstLineChars="0"/>'
f"</w:pPr>{drawing}</w:p>"
)
def _image_paragraph_xml(text: str, relationships: _DocumentRelationships) -> str:
label, _, target = text.partition("|")
children = _run_xml(label)
@@ -536,6 +670,9 @@ def _table_xml(block: TableBlock, relationships: _DocumentRelationships) -> str:
def _blocks_xml(blocks: list[Block], relationships: _DocumentRelationships) -> str:
output: list[str] = []
for block in blocks:
if isinstance(block, ImageBlock):
output.append(_embedded_image_xml(block, relationships))
continue
if isinstance(block, TableBlock):
output.append(_table_xml(block, relationships))
continue
@@ -897,7 +1034,8 @@ def _document_xml(title: str | None, blocks: list[Block], relationships: _Docume
'<w:pgNumType w:start="1" w:fmt="decimal"/><w:cols w:space="720"/></w:sectPr>'
)
return (
f'{_XML_DECL}<w:document xmlns:w="{_W_NS}" xmlns:r="{_R_NS}">'
f'{_XML_DECL}<w:document xmlns:w="{_W_NS}" xmlns:r="{_R_NS}" '
'xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing">'
f"<w:body>{''.join(body)}{section}</w:body></w:document>"
)
@@ -908,6 +1046,7 @@ def _content_types_xml() -> str:
'<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
'<Default Extension="xml" ContentType="application/xml"/>'
'<Default Extension="odttf" ContentType="application/vnd.openxmlformats-officedocument.obfuscatedFont"/>'
'<Default Extension="png" ContentType="image/png"/>'
'<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
'<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>'
'<Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>'
@@ -952,18 +1091,29 @@ def _app_properties_xml() -> str:
)
def build_markdown_docx(markdown: str, title: str | None = None, *, font_path: Path | None = None) -> bytes:
def build_markdown_docx(
markdown: str,
title: str | None = None,
*,
font_path: Path | None = None,
embedded_images: dict[str, str] | None = None,
) -> bytes:
"""Build a formal DOCX and embed the validated server-side title font."""
if not markdown or not markdown.strip():
raise WordExportError("文档内容为空。")
if len(markdown) > 2_000_000:
raise WordExportError("文档内容超过 200 万字符,无法导出。")
if embedded_images and len(embedded_images) > _MAX_EMBEDDED_IMAGES:
raise WordExportError("嵌入图片数量超过限制。")
font = load_title_font(font_path)
resolved_title, blocks = _parse_markdown(markdown, title)
resolved_title, blocks = _parse_markdown(markdown, title, embedded_images)
relationships = _DocumentRelationships()
document_xml = _document_xml(resolved_title, blocks, relationships)
font_key = str(uuid.uuid4()).upper()
media_files = {
f"word/media/{block.media_name}": block.data for block in blocks if isinstance(block, ImageBlock)
}
output = io.BytesIO()
with zipfile.ZipFile(output, mode="w", compression=zipfile.ZIP_DEFLATED, compresslevel=6) as archive:
@@ -984,6 +1134,7 @@ def build_markdown_docx(markdown: str, title: str | None = None, *, font_path: P
"word/footer1.xml": _footer_xml("left"),
"word/footer2.xml": _footer_xml("right"),
"word/fonts/font1.odttf": _obfuscate_font(font.data, font_key),
**media_files,
}
for name, value in parts.items():
archive.writestr(name, value.encode("utf-8") if isinstance(value, str) else value)