feat: 新增 agentfx 任务深链与研判报告入库流程

支持 goPath=agentfx 的 iframe 嵌入问答、内置研判助手种子与报告导入协助卡,并完善深度研究流式报告能力。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-27 16:32:22 +08:00
1 parent 6e9e89a6cb
commit 52b9cbf707
34 files changed
+4488 -392

No files matched your search

@@ -0,0 +1,641 @@
"""写作模式的内联深度研究报告工具。
聊天输入框「写作模式」首轮(尚无 report.md 产物)在**交付时刻**(模型认为
对话已经聊得差不多、该出报告了)调用本工具:优先把**对话中已经产生的**
工具结果收割成研究资料池,内联运行 DeepResearchEngine(basic runner),按
「通用分析结构」大纲撰写 ``report.md``,直接写进**当前聊天线程**的沙箱
``outputs/`` 目录——前端画布 / 编辑 / 下载 / 续写全部沿用既有 artifacts 通道。
除「写 md」这一动作换成管线外,agent 的对话 / 检索 / 澄清行为一切照旧。
资料来源三分支(收割池先按**当前主题**做词面相关度强过滤——旧课题的检索
结果既不计入门槛,也不进报告):
- 主题相关池足够(≥ :data:`_MIN_HARVESTED_MATERIALS`)→ 直接用对话资料写;
- 不足且用户已答复 → ``retrieve=True`` 自检索(对话资料合并去重)、
``retrieve=False`` 只用现有资料(哪怕为空——basic runner 有优雅兜底);
- 不足且未询问 → 返回指令 ToolMessage,让模型用 ``ask_clarification``
询问用户是否补充检索,用户答复后带 ``retrieve`` 重调本工具。
``retrieve=True`` 不只是提示词约束:工具会核验消息史里存在
「本工具的资料不足答复 → ask_clarification → 用户回复」完整链
(:func:`_retrieval_confirmed_by_user`),模型擅自传 ``retrieve=True``
会被拒绝并打回询问流程。
报告管线继承聊天里选择的模型与思考开关(``context.model_name`` /
``thinking_enabled`` / ``thinking_force_disabled``,经 run config 白名单透
传),与「除写 md 外其他行为保持原样」一致;缺省回落系统默认模型。
与 job 执行器(``app/gateway/deep_research_job_executor.py``)的差异:
- 不建会话 / 任务 / 事件库行——生命周期就是本次聊天 run;
- 产物写入器定向到聊天线程(执行器定向到会话的隐藏 ``dr_`` 线程);
- 事件不落库,经 LangGraph 的 ``get_stream_writer()`` custom 通道直达前端
``onCustomEvent``(与子智能体 ``task_running`` 事件同一通道),帧统一带
``{"type": "deep_research_report", ...}`` 前缀。
"""
from __future__ import annotations
import logging
import re
from typing import Annotated, Any
from langchain.tools import InjectedToolCallId, ToolRuntime, tool
from langchain_core.messages import ToolMessage
from langgraph.types import Command
from langgraph.typing import ContextT
from deerflow.agents.deep_research.adapters.artifacts import ThreadOutputsArtifactWriter
from deerflow.agents.deep_research.adapters.context import DeerFlowContextCompressor
from deerflow.agents.deep_research.adapters.image import build_image_provider
from deerflow.agents.deep_research.adapters.llm import DeerFlowCompletionBackend
from deerflow.agents.deep_research.adapters.material_provider import DeerFlowMaterialProvider
from deerflow.agents.deep_research.collection.thread_harvester import (
StaticHarvestMaterialProvider,
harvest_messages_materials,
)
from deerflow.agents.deep_research.config import DeepResearchConfig
from deerflow.agents.deep_research.engine import DeepResearchEngine
from deerflow.agents.deep_research.events import DeepResearchEvent, EventType, ResearchPhase
from deerflow.agents.deep_research.types import AdapterBundle, DeepResearchRequest, ResearchMaterial
from deerflow.agents.thread_state import ThreadState
from deerflow.persistence.report_structures.defaults import GENERAL_OUTLINE
from deerflow.runtime.references import _message_name, _message_type
from deerflow.runtime.thread_paths import resolve_path_user_id
logger = logging.getLogger(__name__)
# 收割池低于该条数视为「资料不足」,需要先征询用户是否补充检索。
_MIN_HARVESTED_MATERIALS = 3
# 引擎事件中值得转发到聊天的子集(model_usage / heartbeat / job_* 只对持久
# 任务管道有意义,聊天内是噪音)。
_FORWARDABLE_EVENTS: frozenset[str] = frozenset(
{
"phase_changed",
"plan_created",
"queries_planned",
"query_started",
"query_completed",
"source_added",
"sources_curated",
"context_compressed",
"report_reset",
"report_chunk",
"report_completed",
"summary_completed",
"artifact_created",
"warning",
"error",
}
)
# live-only 帧类型(不落库的 token 级增量,ReportChunkEmitter.publish_live)。
_FORWARDABLE_LIVE_EVENTS: frozenset[str] = frozenset({"report_delta", "report_thinking"})
REPORT_VIRTUAL_PATH = "/mnt/user-data/outputs/report.md"
class StreamWriterEventSink:
"""把引擎事件经 LangGraph custom 通道转发到聊天前端。
满足 :class:`~deerflow.agents.deep_research.events.EventSink` 协议(结构
类型)。不持久化——``seq`` 恒为 0,聊天内没有 ``?after`` 重放需求;转发
失败只记日志,绝不影响研究执行。
"""
def __init__(
self,
writer: Any,
*,
session_id: str,
job_id: str,
) -> None:
self._writer = writer
self._session_id = session_id
self._job_id = job_id
async def emit(
self,
type: EventType, # noqa: A002 — 与协议参数名保持一致
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> DeepResearchEvent:
event = DeepResearchEvent(
seq=0,
session_id=self._session_id,
job_id=self._job_id,
type=type,
phase=phase,
payload=payload or {},
)
if type in _FORWARDABLE_EVENTS:
self._forward(event.to_sse_dict())
return event
async def publish_live(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> None:
if type not in _FORWARDABLE_LIVE_EVENTS:
return
self._forward(
{
"seq": 0,
"sessionId": self._session_id,
"jobId": self._job_id,
"type": type,
"phase": phase,
"payload": payload or {},
"live": True,
}
)
def _forward(self, frame: dict[str, Any]) -> None:
if self._writer is None:
return
try:
self._writer({"type": "deep_research_report", "event": frame})
except Exception: # noqa: BLE001 - 进度转发绝不影响研究本体
logger.debug("deep_research_report: custom stream frame dropped", exc_info=True)
class HarvestPlusSearchMaterialProvider:
"""对话收割池优先 + 自检索补充的合并资料源(``retrieve=True`` 分支)。
与 :class:`StaticHarvestMaterialProvider` 同协议:每个子查询返回合并池,
交由 runner 的 dedupe / compress 阶段裁剪。自检索单项失败不致命——
退化为只用对话资料。
"""
def __init__(self, harvested: list[ResearchMaterial], search_provider: DeerFlowMaterialProvider) -> None:
self._harvested = list(harvested)
self._search = search_provider
@property
def material_count(self) -> int:
return len(self._harvested)
async def search(
self,
query: str,
*,
domains: list[str] | None = None,
limit: int = 8,
user_id: str = "",
session_id: str = "",
cancellation=None,
) -> list[ResearchMaterial]:
from deerflow.agents.deep_research.adapters.material import dedupe_materials
if cancellation is not None:
cancellation.raise_if_cancelled()
combined = list(self._harvested)
try:
combined.extend(
await self._search.search(
query,
domains=domains,
limit=limit,
user_id=user_id,
session_id=session_id,
cancellation=cancellation,
)
)
except Exception: # noqa: BLE001 - 自检索失败退化为对话资料
logger.warning("deep_research_report: supplementary search failed", exc_info=True)
return dedupe_materials(combined)
def build_writing_research_config(
*,
focus: str | None = None,
thinking_enabled: bool = False,
model_name: str | None = None,
) -> DeepResearchConfig:
"""组装聊天写作模式的研究配置:basic + 通用分析结构 + adaptive。
与深度研究工作台确认卡的默认值一致(``ReportConfigCard.DEFAULT_ADVANCED_OPTIONS``)。
``model_name`` / ``thinking_enabled`` 继承自聊天 run 的模型选择——同一模型
覆盖 fast/smart/strategic 三个角色,使报告管线与对话用同一个模型和思考
开关(缺省回落系统默认模型)。
"""
instruction = focus.strip() if focus and focus.strip() else None
return DeepResearchConfig(
mode="basic",
collection_mode="legacy",
custom_outline=GENERAL_OUTLINE,
structure_mode="adaptive",
generate_images=False,
thinking_enabled=thinking_enabled,
fast_model=model_name,
smart_model=model_name,
strategic_model=model_name,
**({"report_instruction": instruction} if instruction else {}),
).clamp()
def _resolve_chat_model(context: dict[str, Any] | None) -> tuple[str | None, bool, bool]:
"""从 run 上下文解析聊天选择的模型与思考开关(P2:管线继承聊天模型)。
Returns ``(model_name, thinking_enabled, force_disable_thinking)``。模型名
对不上 config.yaml 时回落 ``None``(系统默认);模型不支持思考时关思考,
语义与 lead agent 的解析一致(``_make_lead_agent``)。
"""
cfg = context or {}
name = cfg.get("model_name") or cfg.get("model") or None
thinking = bool(cfg.get("thinking_enabled", True))
force_disable = bool(cfg.get("thinking_force_disabled", False))
name = str(name).strip() if isinstance(name, str) else None
if not name:
return None, thinking, force_disable
try:
from deerflow.config.app_config import get_app_config
model_config = get_app_config().get_model_config(name)
except Exception: # noqa: BLE001 - 配置不可用时交由 create_chat_model 自行兜底
logger.warning("[deep_research_report] app config unavailable; passing model through: %s", name)
return name, thinking, force_disable
if model_config is None:
logger.warning("[deep_research_report] chat model '%s' not in app config; using system default", name)
return None, thinking, force_disable
if thinking and not model_config.supports_thinking:
thinking = False
return name, thinking, force_disable
# ── 当前主题相关度强过滤(P1:旧课题资料不得凑门槛、不得入报告) ────────────
# 主题切词:ASCII 词(≥2 字符)+ CJK 连续段的全部 bigram;≥4 字的整段额外
# 作为强词(命中标题即认定相关)。
_ASCII_WORD_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]+")
_CJK_RUN_RE = re.compile(r"[\u4e00-\u9fff]+")
_STRONG_TERM_MIN_CHARS = 4
# 词面命中判定:标题 ≥2 个不同词,或正文 ≥4 个不同词,或 标题≥1 且正文≥2,
# 或强词(整段主题短语)出现在标题。
_TITLE_MIN_HITS = 2
_CONTENT_MIN_HITS = 4
# 正文只扫前若干字符——相关度信号在开头最密,长文省 CPU。
_CONTENT_SCAN_CHARS = 4000
def _topic_terms(topic: str) -> tuple[frozenset[str], frozenset[str]]:
"""切出 ``(强词, 弱词)``:强词=主题整段短语,弱词=bigram + ASCII 词。"""
weak: set[str] = set()
strong: set[str] = set()
for word in _ASCII_WORD_RE.findall(topic):
weak.add(word.lower())
for run in _CJK_RUN_RE.findall(topic):
if len(run) >= _STRONG_TERM_MIN_CHARS:
strong.add(run)
for i in range(len(run) - 1):
weak.add(run[i : i + 2])
return frozenset(strong), frozenset(weak)
def _is_topic_relevant(material: ResearchMaterial, strong: frozenset[str], weak: frozenset[str]) -> bool:
title = (material.title or "").lower()
content = (material.raw_content or "")[:_CONTENT_SCAN_CHARS].lower()
title_hits = sum(1 for term in weak if term in title)
content_hits = sum(1 for term in weak if term in content)
if any(term in title for term in strong):
return True
if title_hits >= _TITLE_MIN_HITS:
return True
if content_hits >= _CONTENT_MIN_HITS:
return True
if title_hits >= 1 and content_hits >= 2:
return True
# 短主题兜底:切出的词 ≤2 个时(如「课题」「AI」),命中任意一词即相关。
return len(weak) <= 2 and (title_hits + content_hits) >= 1
def _filter_relevant_materials(
materials: list[ResearchMaterial], *, topic: str
) -> tuple[list[ResearchMaterial], int]:
"""按当前主题过滤收割池;返回 ``(相关池, 被剔除条数)``。"""
strong, weak = _topic_terms(topic)
if not strong and not weak:
return list(materials), 0
relevant = [m for m in materials if _is_topic_relevant(m, strong, weak)]
return relevant, len(materials) - len(relevant)
# ── retrieve=True 的用户确认核验(P1:不靠提示词,消息史里找证据链) ──────────
def _retrieval_confirmed_by_user(messages: list[Any]) -> bool:
"""核验消息史存在「本工具资料不足答复 → ask_clarification → 用户回复」。
模型无法伪造 ToolMessage / HumanMessage(分别由工具执行与真实用户输入
产生),因此该链成立 ⇔ 用户确实被问过并答过。跨 run 依然有效——消息
历史就是 LangGraph 的持久状态。
"""
last_report_reply = -1
for index, message in enumerate(messages):
if _message_type(message) == "tool" and str(_message_name(message) or "") == "deep_research_report":
last_report_reply = index
if last_report_reply < 0:
return False
asked = False
for message in messages[last_report_reply + 1 :]:
if _message_type(message) != "tool":
if asked and _message_type(message) == "human":
return True
continue
if str(_message_name(message) or "") == "ask_clarification":
asked = True
return False
def _safe_stream_writer() -> Any:
"""获取当前 run 的 custom 事件写入器;非流式上下文返回 None。"""
try:
from langgraph.config import get_stream_writer
return get_stream_writer()
except Exception: # noqa: BLE001 - 非流式运行(测试/后台)没有 writer
return None
def _insufficient_materials_message(
relevant_count: int,
minimum: int,
*,
topic: str,
total_count: int,
dropped_count: int,
) -> str:
detail = (
f"对话中共整理出 {total_count} 条资料,其中与当前主题「{topic}」相关的仅 {relevant_count} 条"
if dropped_count > 0
else f"对话中仅整理出 {relevant_count} 条与主题「{topic}」相关的资料"
)
return (
f"[需要用户确认] {detail}(低于 {minimum} 条的最低参考线)。"
"在生成报告前,请立即调用 `ask_clarification` 询问用户:\n"
'question: "对话中已有的资料较少,是否自动检索更多资料来写报告?"\n'
'clarification_type: "missing_info"\n'
f'context: "当前对话仅整理出 {relevant_count} 条与主题相关的资料;补充检索可让报告更充实,但会多花一些时间。"\n'
'options: ["检索更多资料,再写报告", "不用检索,直接用现有资料写"]\n'
"用户选择检索 → 携带 retrieve=true 重新调用本工具(参数 topic/focus 保持不变);"
"用户选择不检索 → 携带 retrieve=false 重新调用本工具。"
"在得到用户答复前,不要自行检索,也不要用 write_file 手工撰写报告。"
"注意:未经上述询问并获得用户答复,本工具会拒绝 retrieve=true。"
)
def _retrieve_without_confirmation_message() -> str:
return (
"[参数被拒绝] retrieve=true 只允许在用户通过 ask_clarification 明确同意补充检索之后使用;"
"本次调用未检测到「询问用户 → 用户答复」的记录,已按资料不足处理。"
"请立即调用 `ask_clarification` 询问用户是否检索更多资料"
'(question: "对话中已有的资料较少,是否自动检索更多资料来写报告?",'
'clarification_type: "missing_info",options: ["检索更多资料,再写报告", "不用检索,直接用现有资料写"]),'
"用户答复后再按其选择重新调用本工具(retrieve=true / false)。"
"不要不经询问直接传 retrieve=true,也不要用 write_file 手工撰写报告。"
)
@tool("deep_research_report", parse_docstring=True)
async def deep_research_report_tool(
runtime: ToolRuntime[ContextT, ThreadState],
tool_call_id: Annotated[str, InjectedToolCallId],
topic: str,
focus: str | None = None,
retrieve: bool | None = None,
) -> Command:
"""Run the deep-research report pipeline on the conversation's materials and produce report.md as the writing-mode deliverable.
Call this AT DELIVERY TIME — when the conversation has gathered enough substance
and the user expects the report file now (they asked to start writing, or you have
finished discussing and the report is the natural next step). Before that, work
exactly as usual (chat, search, clarify); do NOT call this tool early.
The tool harvests the materials already produced in this conversation (search /
knowledge / skill / file tool results) and writes a full research report
(general-analysis structure, numbered reference section) to
/mnt/user-data/outputs/report.md in this thread. The file is presented
automatically; do NOT write the report body yourself with write_file.
If the harvested pool is thin (or little of it matches the current topic), the
tool returns instructions to ask the user whether to search for more materials
(via ask_clarification); after the user answers, re-call this tool with
`retrieve` set accordingly (same topic/focus). `retrieve=true` is REJECTED
unless the conversation shows that ask_clarification exchange — never pass it
speculatively.
Args:
topic: The research topic / thesis to investigate. Copy the user's subject faithfully;
do not paraphrase it into something narrower unless the user asked for that scope.
focus: Optional extra write-time requirements from the user (length, tone, must-cover
points, language preferences). Omit when the user gave none.
retrieve: Only set on a re-call after the user answered the insufficient-materials
question. True = search more materials (combined with the conversation pool);
False = write directly with existing materials only. Omit on the first call.
tool_call_id: Injected tool call id.
"""
# 与 present_file_tool 相同的解析顺序:runtime.context → runtime.config。
thread_id = runtime.context.get("thread_id") if runtime.context else None
if not thread_id:
thread_id = ((getattr(runtime, "config", None) or {}).get("configurable") or {}).get("thread_id")
thread_id = str(thread_id) if thread_id else ""
if not thread_id:
return Command(
update={
"messages": [
ToolMessage(
content="Error: deep_research_report could not resolve the current thread id.",
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
query = topic.strip()
state = getattr(runtime, "state", None) or {}
conversation_messages = state.get("messages") or []
harvested, _agent_summary = harvest_messages_materials(conversation_messages, query=query)
# 按当前主题强过滤:旧课题的检索结果不计门槛、不入报告(课题切换场景)。
materials, dropped_count = _filter_relevant_materials(harvested, topic=query)
harvested_count = len(materials)
logger.info(
"[deep_research_report] thread=%s harvested %d materials from conversation "
"(topic-relevant %d, off-topic dropped %d)",
thread_id,
len(harvested),
harvested_count,
dropped_count,
)
if retrieve is True and not _retrieval_confirmed_by_user(conversation_messages):
# P1:retrieve=true 只认「已询问且用户已答复」,提示词约束之外在工具层强制。
logger.warning(
"[deep_research_report] thread=%s rejected retrieve=true without user confirmation",
thread_id,
)
return Command(
update={
"messages": [
ToolMessage(
content=_retrieve_without_confirmation_message(),
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
if harvested_count < _MIN_HARVESTED_MATERIALS and retrieve is None:
# 资料不足且未征询过用户:不静默自检索,交给模型发起用户协助。
logger.info(
"[deep_research_report] thread=%s insufficient materials (%d < %d); asking user",
thread_id,
harvested_count,
_MIN_HARVESTED_MATERIALS,
)
return Command(
update={
"messages": [
ToolMessage(
content=_insufficient_materials_message(
harvested_count,
_MIN_HARVESTED_MATERIALS,
topic=query,
total_count=len(harvested),
dropped_count=dropped_count,
),
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
if harvested_count >= _MIN_HARVESTED_MATERIALS or retrieve is False:
materials_provider: Any = StaticHarvestMaterialProvider(materials)
material_source = "对话资料"
else: # retrieve is True 且已核验用户同意补充检索
materials_provider = HarvestPlusSearchMaterialProvider(
materials,
DeerFlowMaterialProvider(
user_id=resolve_path_user_id(str(thread_id)),
session_id=f"chat-{thread_id}",
runtime_thread_id=str(thread_id),
),
)
material_source = "对话资料+补充检索"
user_id = resolve_path_user_id(str(thread_id))
session_id = f"chat-{thread_id}"
writer = _safe_stream_writer()
events = StreamWriterEventSink(writer, session_id=session_id, job_id=tool_call_id)
# P2:报告管线继承聊天选择的模型与思考开关,缺省回落系统默认模型。
model_name, thinking_enabled, force_disable_thinking = _resolve_chat_model(runtime.context)
research_config = build_writing_research_config(
focus=focus,
thinking_enabled=thinking_enabled,
model_name=model_name,
)
llm_backend = DeerFlowCompletionBackend(
research_config,
event_sink=events,
force_disable_thinking=force_disable_thinking,
)
bundle = AdapterBundle(
llm=llm_backend,
materials=materials_provider,
context=DeerFlowContextCompressor(llm=llm_backend),
artifacts=ThreadOutputsArtifactWriter(str(thread_id), user_id=user_id or None),
events=events,
images=build_image_provider(),
)
request = DeepResearchRequest(
session_id=session_id,
user_id=user_id,
query=query,
config=research_config,
request_id=tool_call_id,
)
logger.info(
"[deep_research_report] thread=%s starting inline research (topic=%.80r, source=%s, harvested=%d)",
thread_id,
topic,
material_source,
harvested_count,
)
result = None
error_message: str | None = None
try:
result = await DeepResearchEngine().run(request, adapters=bundle)
except Exception as exc: # noqa: BLE001 - 工具错误以 ToolMessage 回给模型自纠
logger.exception("[deep_research_report] thread=%s research failed", thread_id)
error_message = f"深度研究报告生成失败:{exc}"
# 终态帧:无论成败都发,前端据此收尾进度条 / 停止流式预览。
if writer is not None:
try:
writer(
{
"type": "deep_research_report",
"event": {
"type": "tool_finished",
"sessionId": session_id,
"jobId": tool_call_id,
"phase": "done" if result is not None else "error",
"payload": {
"status": "success" if result is not None else "error",
**({"error": error_message} if error_message else {}),
},
},
}
)
except Exception: # noqa: BLE001
logger.debug("[deep_research_report] tool_finished frame dropped", exc_info=True)
if result is None:
return Command(
update={
"messages": [
ToolMessage(
content=f"Error: {error_message}. 收集资料或模型调用可能暂时不可用,可建议用户稍后重试。",
tool_call_id=tool_call_id,
name="deep_research_report",
)
]
}
)
source_count = len(result.source_ids or [])
summary = (
f"研究报告已完成:基于 {source_count} 条资料({material_source})按「通用分析结构」撰写,"
f"已写入 {REPORT_VIRTUAL_PATH} 并展示给用户。"
"请用 2-3 句话向用户简要总结报告的核心结论,不要复述全文。"
)
logger.info(
"[deep_research_report] thread=%s completed (sources=%d, report_chars=%d)",
thread_id,
source_count,
len(result.report_markdown or ""),
)
return Command(
update={
"artifacts": [REPORT_VIRTUAL_PATH],
"messages": [ToolMessage(content=summary, tool_call_id=tool_call_id, name="deep_research_report")],
},
)
__all__ = [
"HarvestPlusSearchMaterialProvider",
"StreamWriterEventSink",
"build_writing_research_config",
"deep_research_report_tool",
]