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,6 @@
"""Pre-plan requirement resolution package."""
from app.report_collaboration.requirement.intent_router import PrePlanDecision, route_pre_plan_turn
from app.report_collaboration.requirement.resolver import RequirementResolver
__all__ = ["PrePlanDecision", "RequirementResolver", "route_pre_plan_turn"]
@@ -0,0 +1,25 @@
"""Default assumptions applied when the user skips clarification or hits the round cap."""
from __future__ import annotations
DEFAULT_AUDIENCE = "企业战略决策人员"
DEFAULT_LANGUAGE = "中文"
DEFAULT_TONE = "面向企业战略决策,结论可执行"
DEFAULT_SOURCE_CONSTRAINTS = "所有关键数字必须给出可核对来源"
DEFAULT_ANGLES = (
"市场份额",
"价格策略",
"技术路线",
"海外进展",
"政策环境",
"风险与机会",
)
DEFAULT_TITLE = "未命名报告"
COORDINATOR_NAME = "协调者"
# Gaps that actually change plan strategy (audience / parallel angles). Time range is optional.
PLAN_AFFECTING_GAPS: tuple[tuple[str, str, str], ...] = (
("audience", "这份报告的主要读者是谁?(例如企业战略决策层 / 投资机构 / 业务部门)", "影响语气、深度和结论呈现方式"),
("required_angles", "是否有必须覆盖的分析角度或资料范围限制?", "影响团队编制、并行策略和检索范围"),
)
@@ -0,0 +1,121 @@
"""Deterministic extraction of report requirements from a user turn.
The pre-plan IntentRouterAgent uses this first. A later model adapter may
fill remaining gaps; it must not build graphs or start runs.
"""
from __future__ import annotations
import re
from typing import Any
_DIRECT_START_RE = re.compile(
r"(直接开始|按默认|默认假设|不用问了|不用问|不用澄清|跳过澄清|直接规划|开始规划|按默认假设)"
)
_AUDIENCE_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
(re.compile(r"投资(机构|人|者)?|基金|卖方"), "投资机构"),
(re.compile(r"业务(部门|团队|一线)|运营|产品经理"), "业务部门"),
(re.compile(r"公众|媒体|传播|对外口径"), "公众沟通"),
(re.compile(r"战略|决策层|高管|董事会|管理层|企划"), "企业战略决策人员"),
)
_ANGLE_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
(re.compile(r"市场份额|市场规模|市场格局|占有率|(?:覆盖|包括|含)[^。]{0,16}市场"), "市场份额"),
(re.compile(r"价格|定价|促销"), "价格策略"),
(re.compile(r"技术(路线)?|电池|智驾|平台"), "技术路线"),
(re.compile(r"海外|出口|出海|国际化"), "海外进展"),
(re.compile(r"政策|监管|补贴"), "政策环境"),
(re.compile(r"风险|机会|展望"), "风险与机会"),
(re.compile(r"竞争|对手"), "竞争格局"),
(re.compile(r"供应链|原材料"), "供应链与原材料"),
)
_TIME_RE = re.compile(r"((?:19|20)\d{2}\s*(?:年)?\s*(?:至|-|—|至今)?\s*(?:(?:19|20)\d{2}|今)?|(?:近|过去)\s*\d+\s*(?:年|个月)|至今)")
_LANGUAGE_RE = re.compile(r"(英文|英语|English|中文|汉语)")
_TOPIC_NOISE_RE = re.compile(r"^(请|帮我|麻烦|我想|我要|帮忙)")
_TOPIC_PREFIX_RE = re.compile(r"^(撰写|写|生成|做|出)\s*(一份|一篇|一个|张)?")
def wants_direct_start(text: str) -> bool:
return bool(_DIRECT_START_RE.search(text or ""))
def extract_audience(text: str) -> str | None:
for pattern, label in _AUDIENCE_PATTERNS:
if pattern.search(text or ""):
return label
return None
def extract_angles(text: str) -> list[str]:
found: list[str] = []
for pattern, label in _ANGLE_PATTERNS:
if pattern.search(text or "") and label not in found:
found.append(label)
return found
def extract_time_range(text: str) -> str | None:
match = _TIME_RE.search(text or "")
if not match:
return None
return re.sub(r"\s+", "", match.group(1))
def extract_language(text: str) -> str | None:
match = _LANGUAGE_RE.search(text or "")
if not match:
return None
token = match.group(1)
if token.lower() in {"英文", "英语", "english"}:
return "English"
return "中文"
def extract_source_constraints(text: str) -> str | None:
if re.search(r"来源|引用|出处|cite|source", text or "", re.I):
if re.search(r"必须|一定|需要|要求", text or ""):
return "所有关键数字必须给出可核对来源"
return None
def extract_topic(text: str, *, previous_topic: str | None = None) -> str:
raw = (text or "").strip()
if not raw:
return (previous_topic or "").strip()
cleaned = _DIRECT_START_RE.sub(" ", raw)
cleaned = re.sub(r"\s+", " ", cleaned).strip(" ::,,。")
cleaned = _TOPIC_NOISE_RE.sub("", cleaned).strip()
cleaned = _TOPIC_PREFIX_RE.sub("", cleaned).strip(" ::,,。")
if len(cleaned) < 4:
return (previous_topic or "").strip()
return cleaned[:200]
def extract_requirement_patch(text: str, *, previous: dict[str, Any] | None = None) -> dict[str, Any]:
"""Return only fields discovered in this turn (plus topic when present)."""
prev = previous or {}
topic = extract_topic(text, previous_topic=str(prev.get("topic") or "") or None)
patch: dict[str, Any] = {}
if topic:
patch["topic"] = topic
audience = extract_audience(text)
if audience:
patch["audience"] = audience
angles = extract_angles(text)
if angles:
existing = [str(item) for item in (prev.get("required_angles") or [])]
merged = list(existing)
for angle in angles:
if angle not in merged:
merged.append(angle)
patch["required_angles"] = merged
time_range = extract_time_range(text)
if time_range:
patch["time_range"] = time_range
language = extract_language(text)
if language:
patch["language"] = language
sources = extract_source_constraints(text)
if sources:
patch["source_constraints"] = sources
return patch
@@ -0,0 +1,143 @@
"""Pre-plan IntentRouterAgent: understand the user turn, never dispatch work."""
from __future__ import annotations
from typing import Any, Literal
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
from app.report_collaboration.requirement.defaults import DEFAULT_ANGLES, DEFAULT_AUDIENCE, DEFAULT_LANGUAGE, DEFAULT_SOURCE_CONSTRAINTS, DEFAULT_TONE, PLAN_AFFECTING_GAPS
from app.report_collaboration.requirement.extractor import extract_requirement_patch, wants_direct_start
class PrePlanDecision(BaseModel):
"""Structured output of the pre-plan router. It never builds a graph or starts a run."""
model_config = ConfigDict(extra="forbid")
action: Literal["clarify", "ready"]
requirement: ReportRequirementSnapshot
questions: list[str] = Field(default_factory=list)
impact: list[str] = Field(default_factory=list)
assumptions: list[str] = Field(default_factory=list)
used_defaults: bool = False
reason: str
confidence: float = Field(ge=0, le=1)
def _merge_snapshot(previous: dict[str, Any] | None, patch: dict[str, Any], *, revision: int) -> ReportRequirementSnapshot:
base = dict(previous or {})
base.update(patch)
topic = str(base.get("topic") or "").strip()
return ReportRequirementSnapshot(
topic=topic or "未指定主题",
objective=base.get("objective"),
audience=base.get("audience"),
language=base.get("language"),
time_range=base.get("time_range"),
geography=base.get("geography"),
required_angles=list(base.get("required_angles") or []),
excluded_angles=list(base.get("excluded_angles") or []),
source_constraints=base.get("source_constraints"),
report_structure_id=base.get("report_structure_id"),
length_target=base.get("length_target"),
tone=base.get("tone"),
deadline_hint=base.get("deadline_hint"),
quality_priority=base.get("quality_priority"),
revision=max(1, int(revision)),
)
def _gaps(requirement: ReportRequirementSnapshot) -> list[tuple[str, str, str]]:
missing: list[tuple[str, str, str]] = []
if not requirement.topic or requirement.topic == "未指定主题":
missing.append(("topic", "这份报告要写什么主题?请用一两句话说明对象、时间和目的。", "没有主题无法选择方案"))
for field, question, impact in PLAN_AFFECTING_GAPS:
value = getattr(requirement, field, None)
if field == "required_angles":
empty = not value
else:
empty = not (value or "").strip()
if empty:
missing.append((field, question, impact))
return missing
def apply_default_assumptions(requirement: ReportRequirementSnapshot) -> tuple[ReportRequirementSnapshot, list[str]]:
assumptions: list[str] = []
data = requirement.model_dump()
if not data.get("audience"):
data["audience"] = DEFAULT_AUDIENCE
assumptions.append(f"读者默认为{DEFAULT_AUDIENCE}")
if not data.get("required_angles"):
data["required_angles"] = list(DEFAULT_ANGLES)
assumptions.append("覆盖角度默认为" + "、".join(DEFAULT_ANGLES))
if not data.get("source_constraints"):
data["source_constraints"] = DEFAULT_SOURCE_CONSTRAINTS
assumptions.append(DEFAULT_SOURCE_CONSTRAINTS)
if not data.get("language"):
data["language"] = DEFAULT_LANGUAGE
if not data.get("tone"):
data["tone"] = DEFAULT_TONE
assumptions.append(DEFAULT_TONE)
return ReportRequirementSnapshot.model_validate(data), assumptions
def route_pre_plan_turn(
text: str,
*,
previous_snapshot: dict[str, Any] | None,
previous_revision: int,
clarification_round: int,
max_clarification_rounds: int,
) -> PrePlanDecision:
"""Rule-based pre-plan routing. Does not call tools or create plans."""
patch = extract_requirement_patch(text, previous=previous_snapshot)
revision = max(1, int(previous_revision) + 1) if previous_snapshot or patch else max(1, int(previous_revision) or 1)
if not previous_snapshot:
revision = 1
requirement = _merge_snapshot(previous_snapshot, patch, revision=revision)
skip = wants_direct_start(text)
hit_cap = clarification_round >= max_clarification_rounds
gaps = _gaps(requirement)
if requirement.topic == "未指定主题" and skip:
return PrePlanDecision(
action="clarify",
requirement=requirement,
questions=["这份报告要写什么主题?请用一两句话说明对象、时间和目的。"],
impact=["没有主题无法选择方案"],
reason="用户要求直接开始,但还没有主题",
confidence=0.9,
)
if skip or (hit_cap and gaps):
filled, assumptions = apply_default_assumptions(requirement)
return PrePlanDecision(
action="ready",
requirement=filled,
assumptions=assumptions,
used_defaults=True,
reason="用户要求按默认假设继续" if skip else "已达澄清上限,使用明确假设继续",
confidence=0.86 if skip else 0.7,
)
if gaps:
return PrePlanDecision(
action="clarify",
requirement=requirement,
questions=[item[1] for item in gaps],
impact=[item[2] for item in gaps],
reason="缺少真正影响方案选择的信息",
confidence=0.8,
)
return PrePlanDecision(
action="ready",
requirement=requirement,
reason="必要信息已齐,可以进入规划",
confidence=0.84,
used_defaults=False,
)
@@ -0,0 +1,184 @@
"""Validate and persist requirement revisions. Never starts planning or a run."""
from __future__ import annotations
from typing import Any
from uuid import uuid4
from app.report_collaboration.contracts.clarifications import ClarificationRecord
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
from app.report_collaboration.requirement.defaults import COORDINATOR_NAME, DEFAULT_TITLE
from app.report_collaboration.requirement.intent_router import PrePlanDecision, route_pre_plan_turn
from deerflow.config.app_config import get_app_config
from deerflow.persistence.report_collaboration import ReportCollaborationStore
from deerflow.persistence.report_collaboration.codec import iso_now
def _state_from_session(record: dict[str, Any]) -> dict[str, Any]:
raw = record.get("requirement_json")
if isinstance(raw, dict) and ("snapshot" in raw or "clarifications" in raw):
return {
"snapshot": raw.get("snapshot"),
"clarifications": list(raw.get("clarifications") or []),
"assumptions": list(raw.get("assumptions") or []),
"clarification_round": int(raw.get("clarification_round") or 0),
"ready_to_plan": bool(raw.get("ready_to_plan")),
}
if isinstance(raw, dict) and raw.get("topic"):
return {
"snapshot": raw,
"clarifications": [],
"assumptions": [],
"clarification_round": 0,
"ready_to_plan": False,
}
return {"snapshot": None, "clarifications": [], "assumptions": [], "clarification_round": 0, "ready_to_plan": False}
def _dump_state(
*,
snapshot: ReportRequirementSnapshot,
clarifications: list[dict[str, Any]],
assumptions: list[str],
clarification_round: int,
ready_to_plan: bool,
) -> dict[str, Any]:
return {
"snapshot": snapshot.model_dump(),
"clarifications": clarifications,
"assumptions": assumptions,
"clarification_round": clarification_round,
"ready_to_plan": ready_to_plan,
}
def format_clarification_message(questions: list[str], *, allow_skip: bool = True) -> str:
numbered = "\n".join(f"{index}. {question}" for index, question in enumerate(questions, start=1))
suffix = "\n\n也可以直接回复「直接开始」,我会按默认假设记录需求。澄清完成不会自动生成方案。" if allow_skip else ""
return f"收到您的报告需求。为了给出最合适的协作方案,请先确认:\n\n{numbered}{suffix}"
def format_ready_message(decision: PrePlanDecision) -> str:
req = decision.requirement
angles = "、".join(req.required_angles) if req.required_angles else "(未指定)"
lines = [
f"已写入需求版本 v{req.revision}。",
f"主题:{req.topic}",
f"读者:{req.audience or '未指定'}",
f"角度:{angles}",
]
if decision.assumptions:
lines.append("默认假设:" + ";".join(decision.assumptions) + "。")
lines.append("澄清完成不等于已经生成候选方案,需要显式发起规划后才会出现方案卡。")
return "\n".join(lines)
def _title_from_topic(topic: str, current: str | None) -> str | None:
if current and current != DEFAULT_TITLE:
return None
cleaned = (topic or "").strip()
if not cleaned or cleaned == "未指定主题":
return None
return cleaned[:40]
class RequirementResolver:
"""Writes requirement revisions and clarification records. Does not enqueue plans."""
def __init__(self, store: ReportCollaborationStore) -> None:
self._store = store
async def handle_user_message(
self,
session_id: str,
*,
user_message: dict[str, Any],
idempotency_key: str,
max_clarification_rounds: int | None = None,
) -> PrePlanDecision | None:
record = await self._store.get_session_record(session_id)
if record is None:
return None
status = str(record.get("status") or "empty")
if status not in {"empty", "clarifying"}:
return None
messages = await self._store.list_messages(session_id)
if any((item.get("metadata") or {}).get("preplan_for") == user_message["message_id"] for item in messages):
return None
state = _state_from_session(record)
cfg_rounds = max_clarification_rounds
if cfg_rounds is None:
cfg_rounds = int(get_app_config().report_collaboration.max_clarification_rounds)
decision = route_pre_plan_turn(
str(user_message.get("content") or ""),
previous_snapshot=state["snapshot"],
previous_revision=int(record.get("requirement_revision") or 0),
clarification_round=int(state["clarification_round"] or 0),
max_clarification_rounds=cfg_rounds,
)
await self._apply(session_id, record, state, decision, user_message=user_message, idempotency_key=idempotency_key)
return decision
async def _apply(
self,
session_id: str,
record: dict[str, Any],
state: dict[str, Any],
decision: PrePlanDecision,
*,
user_message: dict[str, Any],
idempotency_key: str,
) -> None:
clarifications = [dict(item) for item in state["clarifications"]]
round_count = int(state["clarification_round"] or 0)
if decision.action == "clarify":
round_count += 1
for item in clarifications:
if not item.get("resolved"):
item["resolved"] = True
clarification = ClarificationRecord(
id=f"clr_{uuid4().hex[:12]}",
questions=list(decision.questions),
impact=list(decision.impact),
resolved=False,
created_at=iso_now(),
)
clarifications.append(clarification.model_dump())
content = format_clarification_message(decision.questions)
metadata = {
"preplan_for": user_message["message_id"],
"clarification": clarification.model_dump(),
}
ready = False
else:
for item in clarifications:
item["resolved"] = True
content = format_ready_message(decision)
metadata = {"preplan_for": user_message["message_id"], "ready_to_plan": True}
ready = True
payload = _dump_state(
snapshot=decision.requirement,
clarifications=clarifications,
assumptions=list(decision.assumptions),
clarification_round=round_count,
ready_to_plan=ready,
)
await self._store.save_requirement_state(
session_id,
requirement_json=payload,
requirement_revision=decision.requirement.revision,
status="clarifying",
title=_title_from_topic(decision.requirement.topic, record.get("title")),
)
await self._store.create_message(
session_id,
role="ai",
content=content,
idempotency_key=f"{idempotency_key}:preplan",
name=COORDINATOR_NAME,
metadata=metadata,
completed=True,
)