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

@@ -175,10 +175,14 @@ class DeerFlowCompletionBackend:
config: DeepResearchConfig,
event_sink: EventSink | None = None,
cancellation: CancellationToken | None = None,
force_disable_thinking: bool = False,
) -> None:
self._config = config
self._events = event_sink
self._cancel = cancellation
# 与 lead agent 同语义的「思考硬关」开关(内网 vLLM/Qwen 只声明
# supports_thinking 时,thinking_enabled=False 不会注入 enable_thinking=false)。
self._force_disable_thinking = force_disable_thinking
self._models: dict[str, BaseChatModel] = {}
# Running token totals (keyed by model name) for the final usage report.
self._usage_totals: dict[str, dict[str, int]] = {}
@@ -196,7 +200,11 @@ class DeerFlowCompletionBackend:
return cached
from deerflow.models import create_chat_model
model = create_chat_model(name=name, thinking_enabled=self._config.thinking_enabled)
model = create_chat_model(
name=name,
thinking_enabled=self._config.thinking_enabled,
force_disable_thinking=self._force_disable_thinking,
)
self._models[cache_key] = model
return model
@@ -57,7 +57,7 @@ _TOOL_SOURCE_TYPES: dict[str, str] = {
}
# Tool results that never carry report materials.
_IGNORED_TOOLS = {"ask_clarification", "write_todos"}
_IGNORED_TOOLS = {"ask_clarification", "write_todos", "deep_research_report"}
async def harvest_thread_materials(
@@ -80,7 +80,24 @@ async def harvest_thread_materials(
return [], ""
values = checkpoint_tuple.checkpoint.get("channel_values", {}) or {}
messages = values.get("messages") or []
return harvest_messages_materials(messages, query=query)
def harvest_messages_materials(
messages: list[Any],
*,
query: str,
) -> tuple[list[ResearchMaterial], str]:
"""Convert an in-memory message list into research materials.
Same conversion as :func:`harvest_thread_materials` minus the checkpoint
read — for callers that already hold the messages (e.g. a tool reading
``runtime.state`` inside the same run).
Returns ``(materials, agent_summary)`` — the summary is the agent's last
visible text (its collection小结) and doubles as a fallback material when
the thread produced no harvestable tool results.
"""
materials = _harvest_tool_messages(messages, query=query)
agent_summary = _last_assistant_text(messages)
if not materials and agent_summary.strip():
@@ -235,5 +252,6 @@ class StaticHarvestMaterialProvider:
__all__ = [
"MAX_HARVESTED_MATERIALS",
"StaticHarvestMaterialProvider",
"harvest_messages_materials",
"harvest_thread_materials",
]
@@ -5,12 +5,12 @@ from langchain.agents.middleware import AgentMiddleware
from langchain_core.runnables import RunnableConfig
from deerflow.agents.lead_agent.prompt import apply_prompt_template
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
from deerflow.agents.middlewares.forced_research_middleware import (
FORCED_RESEARCH_AGENT_ID,
ForcedResearchMiddleware,
filter_forced_research_tools,
)
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
from deerflow.agents.middlewares.forced_research_middleware import (
FORCED_RESEARCH_AGENT_ID,
ForcedResearchMiddleware,
filter_forced_research_tools,
)
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
from deerflow.agents.middlewares.prompt_prefix_middleware import PromptPrefixMiddleware
@@ -373,21 +373,21 @@ def _build_middlewares(
middlewares.append(SkillReviewMiddleware())
# PositionArtifactCapMiddleware — position-roundtable seats (and summary)
# PositionArtifactCapMiddleware — position-roundtable seats (and summary)
# may only emit N outputs write_file calls per user turn. Action-plan skips
# the context flag so it can still write report + JSON.
from deerflow.agents.middlewares.position_artifact_cap_middleware import PositionArtifactCapMiddleware
middlewares.append(PositionArtifactCapMiddleware())
# The built-in forced-research responder has a hard per-turn collection
# gate plus temporary-Python-only sandbox IO. This is runtime enforcement,
# not merely SOUL prompt steering, so weak models cannot answer before a
# successful retrieval/skill-script result exists.
if agent_name == FORCED_RESEARCH_AGENT_ID:
middlewares.append(ForcedResearchMiddleware())
# LoopDetectionMiddleware — detect and break repetitive tool call loops
middlewares.append(PositionArtifactCapMiddleware())
# The built-in forced-research responder has a hard per-turn collection
# gate plus temporary-Python-only sandbox IO. This is runtime enforcement,
# not merely SOUL prompt steering, so weak models cannot answer before a
# successful retrieval/skill-script result exists.
if agent_name == FORCED_RESEARCH_AGENT_ID:
middlewares.append(ForcedResearchMiddleware())
# LoopDetectionMiddleware — detect and break repetitive tool call loops
middlewares.append(LoopDetectionMiddleware())
# Inject custom middlewares before ClarificationMiddleware
@@ -638,20 +638,32 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
# Default lead agent (unchanged behavior)
is_notebook_mode = bool(cfg.get("notebook_search_space_id"))
notebook_source_ids: list[int] = cfg.get("notebook_source_ids") or []
default_tools = get_available_tools(
default_tools = get_available_tools(
model_name=model_name,
groups=agent_config.tool_groups if agent_config else None,
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
app_config=resolved_app_config,
)
if agent_id == FORCED_RESEARCH_AGENT_ID:
default_tools = filter_forced_research_tools(default_tools)
app_config=resolved_app_config,
)
if agent_id == FORCED_RESEARCH_AGENT_ID:
default_tools = filter_forced_research_tools(default_tools)
if is_notebook_mode:
from deerflow.tools.builtins.notebook_search_tool import notebook_search_tool
default_tools = [notebook_search_tool] + default_tools
# 写作模式首轮(尚无 md 产物):挂深度研究报告工具,报告由管线生成而非
# 模型手工 write_file。续写轮(已有 writing_artifact_path)不挂,保持
# 原有「直接编辑该文件」行为。不受 tool_groups/excluded_tools 过滤——
# 它是写作模式合约的核心交付手段。
if writing_mode and not writing_artifact_path:
from deerflow.tools.builtins.deep_research_report_tool import deep_research_report_tool
default_tools = [*default_tools, deep_research_report_tool]
logger.info(
"Writing mode first report turn: deep_research_report tool mounted for agent=%s",
agent_id,
)
# Custom agents are steered ONLY by their own SOUL.md — no generic
# super-agent system template and no personal memory injection. We branch to
@@ -271,42 +271,42 @@ answers — and never create a skill silently without user confirmation.
"""
def _build_es_query_routing_section(
*,
app_config: AppConfig | None = None,
available_skills: set[str] | None = None,
) -> str:
"""Return the configurable ``es_query`` routing rule for the system prompt.
A custom agent with an explicit skill allowlist only receives the rule when
``es_query`` is in that allowlist. The default lead agent has no allowlist,
so the operator-controlled config switch is authoritative there.
"""
if available_skills is not None and "es_query" not in available_skills:
return ""
config = app_config
if config is None:
try:
from deerflow.config import get_app_config
config = get_app_config()
except Exception:
logger.debug("Failed to load es_query routing config", exc_info=True)
return ""
routing = getattr(getattr(config, "skills", None), "es_query_routing", None)
if routing is None or not routing.enabled:
return ""
prompt = (routing.prompt or "").strip()
if not prompt:
return ""
return f'<skill_routing skill="es_query">\n{prompt}\n</skill_routing>'
def _build_available_subagents_description(available_names: list[str], bash_available: bool, *, app_config: AppConfig | None = None) -> str:
def _build_es_query_routing_section(
*,
app_config: AppConfig | None = None,
available_skills: set[str] | None = None,
) -> str:
"""Return the configurable ``es_query`` routing rule for the system prompt.
A custom agent with an explicit skill allowlist only receives the rule when
``es_query`` is in that allowlist. The default lead agent has no allowlist,
so the operator-controlled config switch is authoritative there.
"""
if available_skills is not None and "es_query" not in available_skills:
return ""
config = app_config
if config is None:
try:
from deerflow.config import get_app_config
config = get_app_config()
except Exception:
logger.debug("Failed to load es_query routing config", exc_info=True)
return ""
routing = getattr(getattr(config, "skills", None), "es_query_routing", None)
if routing is None or not routing.enabled:
return ""
prompt = (routing.prompt or "").strip()
if not prompt:
return ""
return f'<skill_routing skill="es_query">\n{prompt}\n</skill_routing>'
def _build_available_subagents_description(available_names: list[str], bash_available: bool, *, app_config: AppConfig | None = None) -> str:
"""Dynamically build subagent type descriptions from registry.
Mirrors Codex's pattern where agent_type_description is dynamically generated
@@ -583,11 +583,11 @@ User: "staging"
You: "Deploying to staging..." [proceed]
</clarification_system>
{skills_section}
{es_query_routing_section}
{bootstrap_section}
{skills_section}
{es_query_routing_section}
{bootstrap_section}
{deferred_tools_section}
@@ -700,12 +700,12 @@ combined with a FastAPI gateway for REST API access [citation:FastAPI](https://f
# style, clarification system, citation rules, response-style / critical-reminder
# defaults) and no personal memory injection. Only the mechanical sections an
# agent still needs to actually use its configured skills/tools are kept.
AGENT_ONLY_PROMPT_TEMPLATE = """{soul}
{network_policy_section}{skills_section}
{es_query_routing_section}
{deferred_tools_section}
AGENT_ONLY_PROMPT_TEMPLATE = """{soul}
{network_policy_section}{skills_section}
{es_query_routing_section}
{deferred_tools_section}
{writing_mode_section}
@@ -758,16 +758,16 @@ def apply_agent_only_prompt_template(
soul = get_agent_soul(storage_agent_id)
skills_section = get_skills_prompt_section(
available_skills,
app_config=app_config,
display_enabled=rag_mode_enabled,
)
es_query_routing_section = _build_es_query_routing_section(
app_config=app_config,
available_skills=available_skills,
)
deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
skills_section = get_skills_prompt_section(
available_skills,
app_config=app_config,
display_enabled=rag_mode_enabled,
)
es_query_routing_section = _build_es_query_routing_section(
app_config=app_config,
available_skills=available_skills,
)
deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
n = max_concurrent_subagents
subagent_section = _build_subagent_section(n, app_config=app_config) if subagent_enabled else ""
@@ -777,17 +777,36 @@ def apply_agent_only_prompt_template(
if writing_artifact_path
else ""
)
writing_mode_section = (
f"""<writing_mode>
if writing_mode and not writing_artifact_path:
# 与通用模板一致:对话行为照旧,交付时刻的「写 md」动作交给
# deep_research_report 管线;资料不足时先经 ask_clarification 问用户。
writing_mode_section = """<writing_mode>
Writing mode is enabled for this run (first report turn — no existing artifact).
- HARD RULE: the report file is produced ONLY by the `deep_research_report` tool — never write it yourself with `write_file`, never `present_files` it.
- Work normally (chat, search, clarify) until the report is due; then produce it by calling the `deep_research_report` tool:
`topic` = the user's subject copied faithfully, `focus` = the user's extra requirements (if any).
The tool reuses the conversation's collected materials and writes the full report (general-analysis structure with references)
to `/mnt/user-data/outputs/report.md`, presented automatically.
- If the tool reports insufficient materials, call `ask_clarification` to ask whether to search for more; after the user answers,
re-call the tool with the same `topic`/`focus` plus `retrieve=true` (search more) or `retrieve=false` (existing materials only).
NEVER pass `retrieve=true` before the user has answered — the tool rejects it and bounces you back to the question.
- Do NOT write the report body yourself with `write_file`, and do NOT call `present_files` for it.
- After the tool returns, reply briefly (2-3 sentences) summarizing the core conclusions; do not duplicate the report inline.
- Only if the tool fails, tell the user and offer to retry.
</writing_mode>
"""
else:
writing_mode_section = (
f"""<writing_mode>
Writing mode is enabled for this run.
- Your final deliverable MUST be a Markdown file saved under `/mnt/user-data/outputs/` (e.g. `/mnt/user-data/outputs/report.md`).
- If a current Markdown artifact is provided below, revise that file rather than creating a new one unless the user explicitly asks for a separate document.
- After writing the file, call `present_files` with the Markdown file path.
{current_writing_artifact}</writing_mode>
"""
if writing_mode
else ""
)
if writing_mode
else ""
)
acp_section = _build_acp_section(app_config=app_config)
custom_mounts_section = _build_custom_mounts_section(app_config=app_config)
@@ -809,10 +828,10 @@ RAG/reference display mode is enabled.
)
prompt = AGENT_ONLY_PROMPT_TEMPLATE.format(
soul=soul,
skills_section=skills_section,
es_query_routing_section=es_query_routing_section,
deferred_tools_section=deferred_tools_section,
soul=soul,
skills_section=skills_section,
es_query_routing_section=es_query_routing_section,
deferred_tools_section=deferred_tools_section,
writing_mode_section=writing_mode_section,
subagent_section=subagent_section,
network_policy_section=network_policy_section,
@@ -1421,15 +1440,15 @@ def apply_prompt_template(
bootstrap_section = _build_bootstrap_section() if is_bootstrap else ""
# Get skills section
skills_section = get_skills_prompt_section(
available_skills,
app_config=app_config,
display_enabled=rag_mode_enabled,
)
es_query_routing_section = _build_es_query_routing_section(
app_config=app_config,
available_skills=available_skills,
)
skills_section = get_skills_prompt_section(
available_skills,
app_config=app_config,
display_enabled=rag_mode_enabled,
)
es_query_routing_section = _build_es_query_routing_section(
app_config=app_config,
available_skills=available_skills,
)
# Get deferred tools section (tool_search)
deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
@@ -1438,8 +1457,35 @@ def apply_prompt_template(
if writing_artifact_path
else ""
)
writing_mode_section = (
f"""
if writing_mode and not writing_artifact_path:
# 首轮:对话行为一切照旧,仅在交付时刻把「写 md」动作交给
# deep_research_report 管线(收割对话资料 + 通用分析结构)。资料不足时
# 工具会返回指令,让模型经 ask_clarification 征询用户是否补充检索。
writing_mode_section = """
<writing_mode>
Writing mode is enabled for this run (first report turn — no existing artifact).
**Mandatory Output Contract**
- HARD RULE: the report file is produced ONLY by the `deep_research_report` tool. You are FORBIDDEN from writing the report yourself — do not call `write_file`
(or any file-writing tool) to create the report, and do not call `present_files` for it.
- Treat the user's request as a research-report writing task. Work normally until delivery time: discuss, search, and clarify exactly as you always would.
- When the report file is due — the user asks to start writing, or you have finished gathering what the conversation needs — call the `deep_research_report` tool:
- `topic`: the user's subject/thesis, copied faithfully.
- `focus`: the user's extra requirements (length, tone, must-cover points), if any.
- The tool reuses the materials already collected in this conversation (and searches more only if the user agrees), then writes the full
report (general-analysis structure with a numbered reference section) to `/mnt/user-data/outputs/report.md`, presented automatically.
- If the tool replies that the harvested materials are insufficient, it returns instructions: immediately call `ask_clarification` asking
whether to search for more materials, and after the user answers, re-call `deep_research_report` with the same `topic`/`focus` plus
`retrieve=true` (user agreed) or `retrieve=false` (user declined — write with what exists).
NEVER pass `retrieve=true` before the user has answered — the tool rejects it and bounces you back to the question.
- Do NOT write the report body yourself with `write_file`, and do NOT call `present_files` for the report — the tool already handles both.
- While the tool runs, stay silent; after it returns, reply briefly (2-3 sentences) summarizing the report's core conclusions and point the user to the Markdown artifact. Do not duplicate the report inline.
- Only if the tool fails, tell the user what went wrong and offer to retry; do not silently fall back to writing the report by hand unless the user explicitly asks.
</writing_mode>
"""
else:
writing_mode_section = (
f"""
<writing_mode>
Writing mode is enabled for this run.
@@ -1456,9 +1502,9 @@ Writing mode is enabled for this run.
{current_writing_artifact}
</writing_mode>
"""
if writing_mode
else ""
)
if writing_mode
else ""
)
# Build ACP agent section only if ACP agents are configured
acp_section = _build_acp_section(app_config=app_config)
@@ -1486,10 +1532,10 @@ When a search, knowledge, skill, or MCP tool returns a result list:
# Format the prompt with dynamic skills and memory
prompt = SYSTEM_PROMPT_TEMPLATE.format(
agent_name=agent_name or storage_agent_id or "CM 助手",
soul=get_agent_soul(storage_agent_id),
skills_section=skills_section,
es_query_routing_section=es_query_routing_section,
bootstrap_section=bootstrap_section,
soul=get_agent_soul(storage_agent_id),
skills_section=skills_section,
es_query_routing_section=es_query_routing_section,
bootstrap_section=bootstrap_section,
deferred_tools_section=deferred_tools_section,
writing_mode_section=writing_mode_section,
memory_context=memory_context,
@@ -20,11 +20,13 @@ _UNSET = object()
# Fixed business rows (业务码 → 展示名). Seeded on first boot; agent/chain left empty.
# 8BF 页面尚未建好,先占位保留行。顺序即管理表的展示顺序。
# AFX = goPath=agentfx 深链(新系统 iframe 嵌入的智能体问答,任务详情取本系统 cop-task-detail)。
DEFAULT_BUSINESS_ROWS: list[dict[str, Any]] = [
{"business_code": "3Q", "label": "3QFX"},
{"business_code": "6BF", "label": "任务FX"},
{"business_code": "7BF", "label": "XDFX"},
{"business_code": "8BF", "label": "8BF"},
{"business_code": "AFX", "label": "AGENTFX"},
]
@@ -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",
]