feat(report-collaboration): complete RC-BE-015–018 backend, eval suite, and MySQL sync

Ship report rewrite/version APIs, security budget and audit persistence, AgentScope worker wiring, and the 20-task quality eval harness so the frontend can integrate against a stable contract once enabled in config.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-09-06 17:32:15 +08:00
1 parent 814a44f0b9
commit 5e953c9fcb
123 files changed
+26816 -3505

No files matched your search

@@ -0,0 +1,15 @@
"""Frozen report templates, final publication and replacement candidates."""
from app.report_collaboration.reporting.finalizer import ReportFinalizationError, ReportFinalizer
from app.report_collaboration.reporting.rewrites import ConservativeRewriteGenerator, ModelRewriteGenerator, ReportRewriteService
from app.report_collaboration.reporting.templates import ReportTemplateSnapshot, freeze_report_template
__all__ = [
"ReportFinalizationError",
"ReportFinalizer",
"ConservativeRewriteGenerator",
"ModelRewriteGenerator",
"ReportRewriteService",
"ReportTemplateSnapshot",
"freeze_report_template",
]
@@ -0,0 +1,134 @@
"""Assemble, lint and atomically publish the formal report version."""
from __future__ import annotations
from typing import Any
from app.report_collaboration.reporting.linter import lint_report
from app.report_collaboration.reporting.templates import requirement_snapshot_from_record
from deerflow.persistence.report_collaboration.base import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now
class ReportFinalizationError(RuntimeError):
def __init__(self, code: str, message: str, *, issues: list[dict[str, str]] | None = None) -> None:
super().__init__(message)
self.code = code
self.issues = issues or []
class ReportFinalizer:
"""The only execution-path component allowed to create the initial version."""
def __init__(self, store: ReportCollaborationStore) -> None:
self._store = store
async def finalize_run(self, run_id: str) -> dict[str, Any] | None:
run = await self._store.get_run_record(run_id)
if run is None:
raise ReportFinalizationError("run_missing", f"run not found: {run_id}")
plan = await self._store.get_plan(str(run.get("plan_id") or ""))
nodes = list((plan or {}).get("nodes") or [])
if not any(str(item.get("role_key") or "") in {"writer", "reviser"} for item in nodes):
return None
artifacts = [item for item in await self._store.list_artifacts_full(run_id) if item.get("validation_status") == "validated" and not item.get("superseded_by")]
review_nodes = [item for item in nodes if str(item.get("role_key") or "") == "reviewer"]
reviews = [item for item in artifacts if item.get("artifact_type") == "ReviewDecision"]
reviews.sort(key=lambda item: (int(item.get("attempt") or 0), str(item.get("created_at") or "")))
if review_nodes and (not reviews or (reviews[-1].get("content") or {}).get("verdict") != "pass"):
raise ReportFinalizationError("review_not_passed", "独立审稿尚未通过")
markdown = _assemble_markdown(nodes, artifacts)
if not markdown:
raise ReportFinalizationError("report_draft_missing", "没有可发布的 validated 报告草稿")
source_index = _source_index(artifacts)
session = await self._store.get_session_record(str(run["session_id"]))
requirement = requirement_snapshot_from_record(session)
template = run.get("template_snapshot") if isinstance(run.get("template_snapshot"), dict) else None
lint = lint_report(
markdown,
template_snapshot=template,
source_index=source_index,
required_angles=list(requirement.required_angles if requirement else []),
)
if not lint.ok:
raise ReportFinalizationError("report_quality_gate_failed", "正式报告未通过引用/模板质量门", issues=lint.issues)
versions = await self._store.list_report_versions(str(run["session_id"]))
head = next((item for item in versions if item.get("is_head")), None)
change_type = "initial" if not versions else "revision"
version, created = await self._store.create_report_version(
str(run["session_id"]),
idempotency_key=f"run:{run_id}:formal-report",
markdown=markdown,
source_index=source_index,
change_type=change_type,
change_summary="多智能体协作报告首稿" if change_type == "initial" else "多智能体返工后正式版本",
parent_version_id=(head or {}).get("id"),
template_snapshot=template,
quality_result={
**lint.dump(),
"review": (reviews[-1].get("content") if reviews else None),
"finalized_at": iso_now(),
},
origin_run_id=run_id,
)
if created:
await self._store.append_event(
session_id=str(run["session_id"]),
run_id=run_id,
event_type="report.version.created",
data={"version": version},
)
return version
def _assemble_markdown(nodes: list[dict[str, Any]], artifacts: list[dict[str, Any]]) -> str:
versions = [item for item in artifacts if item.get("artifact_type") == "ReportVersion"]
if versions:
versions.sort(key=lambda item: (int(item.get("attempt") or 0), str(item.get("created_at") or "")))
return str((versions[-1].get("content") or {}).get("markdown") or "").strip()
order = {str(node.get("id")): index for index, node in enumerate(nodes)}
drafts = [item for item in artifacts if item.get("artifact_type") == "ReportSectionDraft"]
drafts.sort(key=lambda item: (order.get(str(item.get("node_id")), 10_000), str(item.get("created_at") or "")))
parts: list[str] = []
for item in drafts:
content = item.get("content") or {}
body = str(content.get("markdown") or "").strip()
title = str(content.get("title") or "").strip()
if body and title and not body.lstrip().startswith("#"):
body = f"## {title}\n\n{body}"
if body:
parts.append(body)
return "\n\n".join(parts).strip()
def _source_index(artifacts: list[dict[str, Any]]) -> list[dict[str, Any]]:
report_versions = [item for item in artifacts if item.get("artifact_type") == "ReportVersion"]
if report_versions:
report_versions.sort(key=lambda item: (int(item.get("attempt") or 0), str(item.get("created_at") or "")))
index = list((report_versions[-1].get("content") or {}).get("source_index") or [])
if index:
return index
now = iso_now()
found: dict[str, dict[str, Any]] = {}
for item in artifacts:
if item.get("artifact_type") != "EvidenceBundle":
continue
content = item.get("content") or {}
sources = {str(source.get("source_id") or ""): source for source in content.get("sources") or []}
for claim in content.get("claims") or []:
claim_id = str(claim.get("claim_id") or "")
if not claim_id:
continue
source = next((sources.get(str(sid)) for sid in claim.get("source_ids") or [] if sources.get(str(sid))), {})
found[claim_id] = {
"id": claim_id,
"url": source.get("url"),
"title": source.get("title") or claim_id,
"published_at": source.get("published_at") or claim.get("published_at"),
"added_at": now,
"agent_run_id": None,
}
return list(found.values())
__all__ = ["ReportFinalizationError", "ReportFinalizer"]
@@ -0,0 +1,75 @@
"""Deterministic citation/template gate used before every formal version."""
from __future__ import annotations
import re
from dataclasses import dataclass, field
from typing import Any
@dataclass(frozen=True)
class ReportLintResult:
ok: bool
issues: list[dict[str, str]] = field(default_factory=list)
covered_sections: list[str] = field(default_factory=list)
cited_ids: list[str] = field(default_factory=list)
def dump(self) -> dict[str, Any]:
return {
"ok": self.ok,
"issues": list(self.issues),
"covered_sections": list(self.covered_sections),
"cited_ids": list(self.cited_ids),
}
def lint_report(
markdown: str,
*,
template_snapshot: dict[str, Any] | None,
source_index: list[dict[str, Any]],
required_angles: list[str] | None = None,
) -> ReportLintResult:
issues: list[dict[str, str]] = []
text = (markdown or "").strip()
if not text:
issues.append({"code": "empty_output", "message": "报告正文为空"})
headings = {match.group(1).strip() for match in re.finditer(r"^#{1,6}\s+(.+?)\s*$", text, re.MULTILINE)}
required_sections = [str(item.get("title") or "").strip() for item in (template_snapshot or {}).get("sections") or [] if str(item.get("title") or "").strip() and str(item.get("title") or "").strip() != "报告标题"]
missing_sections = [title for title in required_sections if title not in headings]
issues.extend({"code": "template_section_missing", "message": f"缺少模板章节:{title}", "target": title} for title in missing_sections)
template_sections = list((template_snapshot or {}).get("sections") or [])
required_questions = [str(question).strip() for section in template_sections for question in section.get("required_questions") or [] if str(question).strip()]
for question in required_questions:
normalized = question.rstrip("??。 ")
if normalized and normalized not in text:
issues.append({"code": "required_question_missing", "message": f"未回答模板必答问题:{question}", "target": question})
required_tables = [str(table).strip() for section in template_sections for table in section.get("required_tables") or [] if str(table).strip()]
if required_tables and not re.search(r"^\s*\|.+\|\s*$", text, re.MULTILINE):
issues.append({"code": "required_table_missing", "message": "模板要求表格,但报告中没有 Markdown 表格"})
dimensions = [str(value).strip() for section in template_sections for value in section.get("comparison_dimensions") or [] if str(value).strip()]
for dimension in dimensions:
if dimension not in text:
issues.append({"code": "comparison_dimension_missing", "message": f"缺少对比维度:{dimension}", "target": dimension})
length_match = re.search(r"(\d{2,6})\s*[–—~-]\s*(\d{2,6})\s*字", str((template_snapshot or {}).get("length_target") or ""))
if length_match:
lower, upper = int(length_match.group(1)), int(length_match.group(2))
body_length = len(re.sub(r"\s+", "", text))
if body_length < lower or body_length > upper:
issues.append({"code": "length_out_of_range", "message": f"报告篇幅 {body_length} 字,不在目标 {lower}–{upper} 字内"})
source_ids = [str(item.get("id") or "") for item in source_index if str(item.get("id") or "")]
cited = [source_id for source_id in source_ids if source_id in text]
if source_ids and not cited:
issues.append({"code": "citation_missing", "message": "正文没有引用来源索引中的 evidence/claim ID"})
for angle in required_angles or []:
if angle and angle not in text:
issues.append({"code": "coverage_gap", "message": f"正文未覆盖必选角度:{angle}", "target": angle})
return ReportLintResult(
ok=not issues,
issues=issues,
covered_sections=[title for title in required_sections if title in headings],
cited_ids=cited,
)
__all__ = ["ReportLintResult", "lint_report"]
@@ -0,0 +1,191 @@
"""Safe replacement-candidate and immutable report-version operations."""
from __future__ import annotations
import re
from typing import Any, Protocol
from app.report_collaboration.reporting.linter import lint_report
from app.report_collaboration.reporting.templates import requirement_snapshot_from_record
from deerflow.persistence.report_collaboration.base import (
ReportCollaborationNotFoundError,
ReportCollaborationStore,
ReportCollaborationValidationError,
)
class RewriteGenerator(Protocol):
async def rewrite(self, markdown: str, *, section: str | None, instruction: str) -> str: ...
class ConservativeRewriteGenerator:
"""Evidence-preserving fallback until the real AgentScope writer is enabled.
It makes the requested change visible without inventing facts. Deployments
may inject a model-backed generator; the same deterministic gate still runs
before the candidate can be persisted or applied.
"""
async def rewrite(self, markdown: str, *, section: str | None, instruction: str) -> str:
note = f"> 本段已按要求调整:{instruction.strip()}。事实与引用范围保持不变。"
if not section:
return f"{markdown.rstrip()}\n\n## 修订说明\n\n{note}\n"
pattern = re.compile(rf"^(#{{1,6}})\s+([^\n]*{re.escape(section)}[^\n]*)$", re.MULTILINE | re.IGNORECASE)
match = pattern.search(markdown)
if match is None:
raise ReportCollaborationValidationError("REPORT_SECTION_NOT_FOUND", f"找不到报告章节:{section}")
next_heading = re.search(rf"^#{{1,{len(match.group(1))}}}\s+", markdown[match.end() :], re.MULTILINE)
end = match.end() + next_heading.start() if next_heading else len(markdown)
return f"{markdown[:end].rstrip()}\n\n{note}\n\n{markdown[end:].lstrip()}".rstrip() + "\n"
class ModelRewriteGenerator:
"""Model-backed writer that cannot use tools or see raw research context."""
def __init__(self, model_name: str, *, fallback: RewriteGenerator | None = None) -> None:
self._model_name = model_name
self._fallback = fallback or ConservativeRewriteGenerator()
async def rewrite(self, markdown: str, *, section: str | None, instruction: str) -> str:
try:
from langchain_core.messages import HumanMessage, SystemMessage
from deerflow.models.factory import create_chat_model
before, target, after = _rewrite_scope(markdown, section)
model = create_chat_model(name=self._model_name, thinking_enabled=False, force_disable_thinking=True)
response = await model.ainvoke(
[
SystemMessage(
content=(
"你是报告定向修订员。只能依据给定正式报告文字进行修改,禁止搜索、调用工具、补造事实或来源。"
"必须保留原有 evidence/claim ID 引用;不确定内容明确标为分析、假设或局限。"
"只输出修改后的 Markdown 目标文本,不解释,不使用代码围栏。"
)
),
HumanMessage(content=f"用户要求:{instruction}\n\n待修改文本:\n{target}"),
]
)
revised = _message_text(getattr(response, "content", response)).strip()
if not revised:
raise ValueError("empty rewrite")
revised = _strip_markdown_fence(revised)
return f"{before}{revised}{after}" if section else revised
except Exception:
return await self._fallback.rewrite(markdown, section=section, instruction=instruction)
class ReportRewriteService:
def __init__(self, store: ReportCollaborationStore, *, generator: RewriteGenerator | None = None) -> None:
self._store = store
self._generator = generator or ConservativeRewriteGenerator()
async def create_candidate(
self,
session_id: str,
*,
idempotency_key: str,
instruction: str,
section: str | None,
) -> dict[str, Any]:
versions = await self._store.list_report_versions(session_id)
head = next((item for item in versions if item.get("is_head")), None)
if head is None:
raise ReportCollaborationValidationError("REPORT_VERSION_REQUIRED", "尚无正式报告,不能创建改写候选")
candidate = await self._generator.rewrite(str(head.get("markdown") or ""), section=section, instruction=instruction)
head_record = await self._store.get_report_version_record(session_id, str(head["id"]))
template = (head_record or {}).get("template_snapshot") or await self._template_snapshot(session_id)
requirement = requirement_snapshot_from_record(await self._store.get_session_record(session_id))
lint = lint_report(
candidate,
template_snapshot=template,
source_index=list(head.get("source_index") or []),
required_angles=list(requirement.required_angles if requirement else []),
)
if not lint.ok:
raise ReportCollaborationValidationError(
"REPORT_REWRITE_QUALITY_FAILED",
"改写候选未通过引用/模板质量门:" + ";".join(item["message"] for item in lint.issues[:3]),
)
return await self._store.create_rewrite_proposal(
session_id,
idempotency_key=idempotency_key,
parent_version_id=str(head["id"]),
section=section,
instruction=instruction.strip(),
markdown=candidate,
source_index=list(head.get("source_index") or []),
quality_result=lint.dump(),
)
async def apply_candidate(self, session_id: str, proposal_id: str, *, idempotency_key: str) -> tuple[dict[str, Any], bool]:
proposal = await self._store.get_rewrite_proposal(session_id, proposal_id)
if proposal is None:
raise ReportCollaborationNotFoundError("report rewrite", proposal_id)
return await self._store.apply_rewrite_proposal(session_id, proposal_id, idempotency_key=idempotency_key)
async def restore(self, session_id: str, version_id: str, *, idempotency_key: str) -> tuple[dict[str, Any], bool]:
source = await self._store.get_report_version_record(session_id, version_id)
if source is None:
raise ReportCollaborationNotFoundError("report version", version_id)
versions = await self._store.list_report_versions(session_id)
head = next((item for item in versions if item.get("is_head")), None)
template = source.get("template_snapshot") or await self._template_snapshot(session_id)
requirement = requirement_snapshot_from_record(await self._store.get_session_record(session_id))
lint = lint_report(
str(source.get("markdown") or ""),
template_snapshot=template,
source_index=list(source.get("source_index") or []),
required_angles=list(requirement.required_angles if requirement else []),
)
if not lint.ok:
raise ReportCollaborationValidationError("REPORT_RESTORE_QUALITY_FAILED", "目标版本不满足当前模板/引用质量门")
return await self._store.create_report_version(
session_id,
idempotency_key=idempotency_key,
markdown=str(source.get("markdown") or ""),
source_index=list(source.get("source_index") or []),
change_type="restore",
change_summary=f"恢复自 v{source['version']}",
parent_version_id=(head or {}).get("id"),
template_snapshot=template,
quality_result=lint.dump(),
)
async def _template_snapshot(self, session_id: str) -> dict[str, Any] | None:
session = await self._store.get_session_record(session_id)
run_id = str((session or {}).get("active_run_id") or "")
run = await self._store.get_run_record(run_id) if run_id else None
value = (run or {}).get("template_snapshot")
return value if isinstance(value, dict) else None
__all__ = ["ConservativeRewriteGenerator", "ReportRewriteService", "RewriteGenerator"]
def _rewrite_scope(markdown: str, section: str | None) -> tuple[str, str, str]:
if not section:
return "", markdown, ""
pattern = re.compile(rf"^(#{{1,6}})\s+([^\n]*{re.escape(section)}[^\n]*)$", re.MULTILINE | re.IGNORECASE)
match = pattern.search(markdown)
if match is None:
raise ReportCollaborationValidationError("REPORT_SECTION_NOT_FOUND", f"找不到报告章节:{section}")
next_heading = re.search(rf"^#{{1,{len(match.group(1))}}}\s+", markdown[match.end() :], re.MULTILINE)
end = match.end() + next_heading.start() if next_heading else len(markdown)
return markdown[: match.start()], markdown[match.start() : end].rstrip(), markdown[end:]
def _message_text(content: Any) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
return "".join(str(item.get("text") or "") if isinstance(item, dict) else str(getattr(item, "text", "")) for item in content)
return str(content or "")
def _strip_markdown_fence(text: str) -> str:
match = re.fullmatch(r"```(?:markdown|md)?\s*\n([\s\S]*?)\n```", text.strip(), re.IGNORECASE)
return match.group(1).strip() if match else text.strip()
__all__.append("ModelRewriteGenerator")
@@ -0,0 +1,136 @@
"""Immutable run-time snapshots of the shared report-structure library."""
from __future__ import annotations
import hashlib
import re
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
from deerflow.persistence.report_collaboration.codec import iso_now
_HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*$", re.MULTILINE)
_LENGTH = re.compile(r"(\d{2,6})\s*[–—~-]\s*(\d{2,6})\s*字")
class TemplateSection(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
level: int = Field(ge=1, le=6)
title: str
goal: str | None = None
required_questions: list[str] = Field(default_factory=list)
required_tables: list[str] = Field(default_factory=list)
comparison_dimensions: list[str] = Field(default_factory=list)
class ReportTemplateSnapshot(BaseModel):
model_config = ConfigDict(extra="forbid")
structure_id: str | None = None
title: str
content: str
content_sha256: str
sections: list[TemplateSection] = Field(default_factory=list)
language: str = "中文"
tone: str = "专业、审慎"
length_target: str | None = None
retrieval_directions: list[str] = Field(default_factory=list)
allowed_retrieval_skills: list[str] = Field(default_factory=list)
citation_format: str = "正文使用 evidence/claim ID,文末列出实际使用来源"
frozen_at: str
def freeze_report_template(
structure: dict[str, Any] | None,
*,
requirement: ReportRequirementSnapshot | None,
) -> ReportTemplateSnapshot:
"""Normalize a mutable shared structure into an immutable run snapshot.
A run without an explicitly selected structure intentionally uses a small
contract. This preserves user choice: the large shared default outline is
not silently imposed on every report.
"""
if structure:
content = str(structure.get("content") or "").strip()
title = str(structure.get("title") or structure.get("name") or "报告结构")
structure_id = str(structure.get("id") or "") or None
directions = [str(item) for item in structure.get("retrieval_directions") or [] if str(item).strip()]
skills = [str(item) for item in structure.get("retrieval_skills") or [] if str(item).strip()]
else:
topic = (requirement.topic if requirement else None) or "研究报告"
content = "# 报告标题\n\n# 核心分析\n\n# 结论与局限\n\n# 参考资料"
title = f"{topic}·运行默认结构"
structure_id = None
directions = []
skills = []
sections = _parse_sections(content)
match = _LENGTH.search(content)
inferred_length = f"{match.group(1)}–{match.group(2)}字" if match else None
return ReportTemplateSnapshot(
structure_id=structure_id,
title=title,
content=content,
content_sha256=hashlib.sha256(content.encode("utf-8")).hexdigest(),
sections=sections,
language=(requirement.language if requirement and requirement.language else "中文"),
tone=(requirement.tone if requirement and requirement.tone else "专业、审慎"),
length_target=(requirement.length_target if requirement and requirement.length_target else inferred_length),
retrieval_directions=directions,
allowed_retrieval_skills=skills,
frozen_at=iso_now(),
)
def _parse_sections(content: str) -> list[TemplateSection]:
matches = list(_HEADING.finditer(content))
sections: list[TemplateSection] = []
for index, match in enumerate(matches):
title = match.group(2).strip()
end = matches[index + 1].start() if index + 1 < len(matches) else len(content)
body = content[match.end() : end].strip()
questions = [part.strip() for part in re.split(r"[\n。]", body) if part.strip().endswith(("?", "?"))]
tables = [line.strip(" -*") for line in body.splitlines() if "表格" in line or "表:" in line]
dimensions = []
for line in body.splitlines():
if "对比维度" in line or "比较维度" in line:
dimensions.extend(part.strip() for part in re.split(r"[::,,、]", line)[1:] if part.strip())
sections.append(
TemplateSection(
id=f"section-{index + 1}",
level=len(match.group(1)),
title=title,
goal=(body.splitlines()[0].strip()[:500] if body else None),
required_questions=questions,
required_tables=tables,
comparison_dimensions=dimensions,
)
)
return sections
__all__ = ["ReportTemplateSnapshot", "TemplateSection", "freeze_report_template"]
def requirement_snapshot_from_record(record: dict[str, Any] | None) -> ReportRequirementSnapshot | None:
if not record:
return None
raw = record.get("requirement_json")
snapshot = dict(raw.get("snapshot") or {}) if isinstance(raw, dict) else {}
if not snapshot.get("topic"):
return None
snapshot.setdefault("required_angles", [])
snapshot.setdefault("excluded_angles", [])
snapshot["revision"] = max(1, int(snapshot.get("revision") or record.get("requirement_revision") or 1))
try:
return ReportRequirementSnapshot.model_validate(snapshot)
except Exception:
return None
__all__.append("requirement_snapshot_from_record")