fix: writing mode uses chat search then pipeline write only

Keep deep_research_report as a write-only deliverable from conversation materials, block post-success rewrite loops with a summary nudge, fill thin/empty pools from model knowledge, and open the sandbox only on real report.md content.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-30 12:41:04 +08:00
1 parent 9afb9750e5
commit 49c01cb72b
20 files changed
+1449 -381

No files matched your search

@@ -43,6 +43,41 @@ if TYPE_CHECKING:
logger = logging.getLogger(__name__)
def _parent_isolated_run_config(run_name: str) -> dict[str, Any]:
"""Keep LangGraph runtime, drop only inherited LLM streaming callbacks.
``StreamWriter`` reads ``get_config()[configurable]`` at emit time. Replacing
the child config with a blank dict makes ``report_delta`` / ``report_thinking``
raise and get swallowed, so the sandbox only appears after the file lands.
"""
parent: dict[str, Any] = {}
try:
from langchain_core.runnables.config import var_child_runnable_config
current = var_child_runnable_config.get()
if isinstance(current, dict):
parent = dict(current)
except Exception: # noqa: BLE001 — isolation must never fail the completion
parent = {}
tags = [tag for tag in (parent.get("tags") or []) if tag != "nostream"]
tags.append("nostream")
parent["callbacks"] = []
parent["tags"] = tags
parent["run_name"] = run_name
return parent
def _clear_inherited_runnable_config(isolated: dict[str, Any]) -> Callable[[], None]:
"""Install the isolated config for the duration of ``astream``."""
try:
from langchain_core.runnables.config import var_child_runnable_config
except ImportError:
return lambda: None
token = var_child_runnable_config.set(isolated)
return lambda: var_child_runnable_config.reset(token)
# ── message conversion ──────────────────────────────────────────────────────
@@ -347,26 +382,39 @@ class DeerFlowCompletionBackend:
text_parts: list[str] = []
usage: dict[str, Any] = {}
inline_think_filter = InlineThinkTagFilter()
async for chunk in model.astream(to_langchain_messages(messages), **kwargs):
if self._cancel is not None:
self._cancel.raise_if_cancelled()
reasoning = _reasoning_delta(chunk)
if reasoning and on_reasoning is not None:
await on_reasoning(reasoning)
# A few OpenAI-compatible models put their reasoning in the
# ordinary content channel instead of ``reasoning_content``.
# Split it from Markdown even when tags span tokens: callers may
# display a live thought trace, but it never joins ``text``.
delta, inline_reasoning = inline_think_filter.push_parts(_content_to_text(chunk))
if inline_reasoning and on_reasoning is not None:
await on_reasoning(inline_reasoning)
if delta:
text_parts.append(delta)
if on_delta is not None:
await on_delta(delta)
chunk_usage = _extract_usage(chunk)
if any(chunk_usage.values()):
usage = chunk_usage
# Isolate from the parent LangGraph run: inherited callbacks would
# replay every report token into the chat ``messages`` stream, so the
# left-hand bubble and the sandbox would write the same prose at once.
# Custom ``report_delta`` events remain the only live preview channel.
isolated_config = _parent_isolated_run_config(f"deep_research:{operation}")
reset_parent_config = _clear_inherited_runnable_config(isolated_config)
try:
async for chunk in model.astream(
to_langchain_messages(messages),
config=isolated_config,
**kwargs,
):
if self._cancel is not None:
self._cancel.raise_if_cancelled()
reasoning = _reasoning_delta(chunk)
if reasoning and on_reasoning is not None:
await on_reasoning(reasoning)
# A few OpenAI-compatible models put their reasoning in the
# ordinary content channel instead of ``reasoning_content``.
# Split it from Markdown even when tags span tokens: callers may
# display a live thought trace, but it never joins ``text``.
delta, inline_reasoning = inline_think_filter.push_parts(_content_to_text(chunk))
if inline_reasoning and on_reasoning is not None:
await on_reasoning(inline_reasoning)
if delta:
text_parts.append(delta)
if on_delta is not None:
await on_delta(delta)
chunk_usage = _extract_usage(chunk)
if any(chunk_usage.values()):
usage = chunk_usage
finally:
reset_parent_config()
tail, inline_reasoning_tail = inline_think_filter.finish_parts()
if inline_reasoning_tail and on_reasoning is not None:
@@ -198,35 +198,63 @@ class BasicRunner:
cancellation.raise_if_cancelled()
if not all_materials:
knowledge_fill = _allows_knowledge_fill(request.config.report_instruction)
await events.emit(
"warning",
phase="curating",
payload={"code": "no_materials", "message": "未收集到任何研究材料", "recoverable": False},
payload={
"code": "no_materials",
"message": (
"未收集到外部研究材料,改用领域知识撰写"
if knowledge_fill
else "未收集到任何研究材料"
),
"recoverable": knowledge_fill,
},
)
report_md = f"# {request.query}\n\n未能收集到与研究课题「{request.query}」相关的材料,无法生成报告。"
await adapters.artifacts.write_text("report.md", report_md)
await events.emit("report_completed", phase="writing", payload={"reportVersion": 1, "sourceCount": 0})
return DeepResearchResult(report_markdown=report_md, source_ids=[], plan=plan)
if not knowledge_fill:
report_md = (
f"# {request.query}\n\n"
f"未能收集到与研究课题「{request.query}」相关的材料,无法生成报告。"
)
await adapters.artifacts.write_text("report.md", report_md)
await events.emit(
"report_completed",
phase="writing",
payload={"reportVersion": 1, "sourceCount": 0},
)
return DeepResearchResult(report_markdown=report_md, source_ids=[], plan=plan)
deduped: list[ResearchMaterial] = []
selected_ids: list[str] = []
context_list: list[dict[str, Any]] = []
context_text = _KNOWLEDGE_FILL_EMPTY_CONTEXT
else:
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.adapters.material import dedupe_materials
deduped = dedupe_materials(all_materials)
context_comp.set_materials(deduped)
deduped = dedupe_materials(all_materials)
context_comp.set_materials(deduped)
selected_ids = [m.id for m in deduped]
await events.emit(
"sources_curated",
phase="curating",
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped"},
)
selected_ids = [m.id for m in deduped]
await events.emit(
"sources_curated",
phase="curating",
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped"},
)
# ── 4. compress context ────────────────────────────────────────
await events.emit(
"phase_changed",
phase="compressing",
payload={"from": "curating", "to": "compressing"},
)
if cancellation:
cancellation.raise_if_cancelled()
# ── 4. compress context ────────────────────────────────────────
await events.emit("phase_changed", phase="compressing", payload={"from": "curating", "to": "compressing"})
if cancellation:
cancellation.raise_if_cancelled()
context_list = await context_comp.async_get_context(request.query, max_results=min(len(deduped), config.max_search_results_per_query * 2))
context_text = _format_context(context_list, deduped)
context_list = await context_comp.async_get_context(
request.query,
max_results=min(len(deduped), config.max_search_results_per_query * 2),
)
context_text = _format_context(context_list, deduped)
# ── 5. writing: generate report ────────────────────────────────
await events.emit("phase_changed", phase="writing", payload={"from": "compressing", "to": "writing"})
@@ -403,6 +431,13 @@ class BasicRunner:
)
outline_block = _report_outline_instruction(outline)
requirements_block = _report_requirements_instruction(request.config.report_instruction)
if _allows_knowledge_fill(request.config.report_instruction):
system_extra = (
"用户已要求在材料不足时用模型自身的公开领域知识写成完整报告。"
"禁止把「材料不足/未提供文献」写成章节主线;参考文献可标注为基于公开领域知识。"
)
else:
system_extra = ""
if request.config.structure_mode == "fixed":
# Recency bias: keep the skeleton immediately before "请撰写报告".
context_block = (
@@ -427,6 +462,8 @@ class BasicRunner:
if filled_preamble:
await emitter.add(filled_preamble + "\n\n")
system = _SYSTEM
if system_extra:
system += system_extra
if request.config.structure_mode == "fixed" and (outline or "").strip():
system += "撰写时必须原样沿用用户大纲中的章节标题与层级,不得改写成通用报告套式。"
result = await llm.stream_complete(
@@ -624,12 +661,31 @@ def ensure_markdown_standalone_lines(text: str) -> str:
return "\n".join(output)
_KNOWLEDGE_FILL_EMPTY_CONTEXT = (
"(本次未收集到外部研究材料。请基于模型自身的公开领域知识撰写完整、有实质内容的研究报告,"
"含架构说明;用户要求流程图时输出 Mermaid。"
"禁止只写「无法生成报告」或把「材料不足」写成全文。)"
)
_KNOWLEDGE_FILL_MARKERS = ("必须基于模型自身的领域知识", "基于模型自身的领域知识")
def _allows_knowledge_fill(report_instruction: str | None) -> bool:
text = report_instruction or ""
return any(marker in text for marker in _KNOWLEDGE_FILL_MARKERS)
def _report_requirements_instruction(report_instruction: str | None) -> str:
"""Render confirmed generation requirements as bounded, untrusted content."""
if not report_instruction:
return "User generation requirements: none provided."
evidence_note = (
"these requirements override the default 'do not go beyond materials' rule "
"when they ask to write from model knowledge"
if _allows_knowledge_fill(report_instruction)
else "content only; system and evidence rules still win"
)
return (
"User generation requirements (content only; system and evidence rules still win):\n"
f"User generation requirements ({evidence_note}):\n"
f"<user-report-requirements>\n{report_instruction}\n</user-report-requirements>"
)
@@ -1,5 +1,5 @@
import hashlib
import logging
import hashlib
import logging
from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware
@@ -38,45 +38,45 @@ logger = logging.getLogger(__name__)
# 写作配置 Q&A 现在「先生成大纲并与用户多轮确认 → 再提交配置」,需要更多来回,故上限放宽。
# 仍是兜底安全阀:到顶才用 tool_choice 强制提交,正常流程由用户确认大纲后自然提交。
WRITING_SETUP_MAX_ROUNDS = 8
REPORT_STRUCTURE_SETUP_MAX_ROUNDS = 8
_ES_QUERY_ROUTING_OPEN_TAG = '<skill_routing skill="es_query">'
def _log_es_query_routing_registration(
*,
system_prompt: str,
app_config: AppConfig,
agent_id: str | None,
available_skills: set[str] | None,
) -> None:
"""Log whether the exact configured ES routing block reached this Q&A prompt."""
routing = app_config.skills.es_query_routing
configured_prompt = (routing.prompt or "").strip()
expected_block = (
f"{_ES_QUERY_ROUTING_OPEN_TAG}\n{configured_prompt}\n</skill_routing>"
if configured_prompt
else ""
)
eligible = available_skills is None or "es_query" in available_skills
registered = bool(expected_block) and expected_block in system_prompt
fingerprint = (
hashlib.sha256(configured_prompt.encode("utf-8")).hexdigest()[:12]
if configured_prompt
else "-"
)
log = logger.info if registered or not routing.enabled or not eligible else logger.warning
log(
"ES query routing prompt registration: agent_id=%s enabled=%s eligible=%s "
"registered=%s prompt_chars=%d prompt_sha256=%s",
agent_id or "default",
routing.enabled,
eligible,
registered,
len(configured_prompt),
fingerprint,
)
REPORT_STRUCTURE_SETUP_MAX_ROUNDS = 8
_ES_QUERY_ROUTING_OPEN_TAG = '<skill_routing skill="es_query">'
def _log_es_query_routing_registration(
*,
system_prompt: str,
app_config: AppConfig,
agent_id: str | None,
available_skills: set[str] | None,
) -> None:
"""Log whether the exact configured ES routing block reached this Q&A prompt."""
routing = app_config.skills.es_query_routing
configured_prompt = (routing.prompt or "").strip()
expected_block = (
f"{_ES_QUERY_ROUTING_OPEN_TAG}\n{configured_prompt}\n</skill_routing>"
if configured_prompt
else ""
)
eligible = available_skills is None or "es_query" in available_skills
registered = bool(expected_block) and expected_block in system_prompt
fingerprint = (
hashlib.sha256(configured_prompt.encode("utf-8")).hexdigest()[:12]
if configured_prompt
else "-"
)
log = logger.info if registered or not routing.enabled or not eligible else logger.warning
log(
"ES query routing prompt registration: agent_id=%s enabled=%s eligible=%s "
"registered=%s prompt_chars=%d prompt_sha256=%s",
agent_id or "default",
routing.enabled,
eligible,
registered,
len(configured_prompt),
fingerprint,
)
def _get_runtime_config(config: RunnableConfig) -> dict:
@@ -426,6 +426,18 @@ def _build_middlewares(
if agent_name == FORCED_RESEARCH_AGENT_ID:
middlewares.append(ForcedResearchMiddleware())
# 写作模式首轮:允许先聊/检索;只有模型开始写 md 时才改走 deep_research_report。
# 不设 tool_choice——thinking 模式的兼容接口会 400。
writing_mode = bool(cfg.get("writing_mode", False))
writing_artifact_path = cfg.get("writing_artifact_path") if writing_mode else None
if writing_mode:
from deerflow.tools.builtins.deep_research_report_tool import is_writing_mode_report_path
if not is_writing_mode_report_path(writing_artifact_path if isinstance(writing_artifact_path, str) else None):
from deerflow.agents.middlewares.writing_mode_report_middleware import WritingModeReportMiddleware
middlewares.append(WritingModeReportMiddleware())
# LoopDetectionMiddleware — detect and break repetitive tool call loops
middlewares.append(LoopDetectionMiddleware())
@@ -517,6 +529,12 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
writing_artifact_path = cfg.get("writing_artifact_path") if writing_mode else None
if not isinstance(writing_artifact_path, str) or not writing_artifact_path.strip():
writing_artifact_path = None
# 只有写作模式产物 report.md 才走续写;其它 leftover .md 不得跳过管线。
if writing_artifact_path is not None:
from deerflow.tools.builtins.deep_research_report_tool import is_writing_mode_report_path
if not is_writing_mode_report_path(writing_artifact_path):
writing_artifact_path = None
agent_id = validate_agent_id(cfg.get("agent_id") or cfg.get("agent_name"))
requested_excluded_tools = cfg.get("excluded_tools") or None
@@ -691,10 +709,10 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
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 过滤——
# 它是写作模式合约的核心交付手段。
# 写作模式首轮(尚无 report.md):挂深度研究报告工具,报告由管线生成而非
# 模型手工 write_file。续写轮(已有 report.md)不挂,保持原有「直接编辑
# 该文件」行为。不受 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
@@ -726,8 +744,8 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
writing_mode=writing_mode,
writing_artifact_path=writing_artifact_path,
)
else:
system_prompt = apply_prompt_template(
else:
system_prompt = apply_prompt_template(
subagent_enabled=subagent_enabled,
max_concurrent_subagents=max_concurrent_subagents,
agent_id=agent_id,
@@ -737,20 +755,20 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
available_skills=prompt_available_skills,
app_config=resolved_app_config,
memory_injection_enabled=memory_injection_enabled,
rag_mode_enabled=rag_mode_enabled,
is_notebook_mode=is_notebook_mode,
notebook_source_ids=notebook_source_ids,
is_scheduled_run=bool(cfg.get("is_scheduled_run", False)),
)
_log_es_query_routing_registration(
system_prompt=system_prompt,
app_config=resolved_app_config,
agent_id=agent_id,
available_skills=prompt_available_skills,
)
return create_agent(
rag_mode_enabled=rag_mode_enabled,
is_notebook_mode=is_notebook_mode,
notebook_source_ids=notebook_source_ids,
is_scheduled_run=bool(cfg.get("is_scheduled_run", False)),
)
_log_es_query_routing_registration(
system_prompt=system_prompt,
app_config=resolved_app_config,
agent_id=agent_id,
available_skills=prompt_available_skills,
)
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, reasoning_effort=reasoning_effort, force_disable_thinking=thinking_force_disabled, app_config=resolved_app_config),
tools=default_tools,
middleware=_build_middlewares(config, model_name=model_name, agent_name=agent_id, app_config=resolved_app_config),
@@ -486,19 +486,19 @@ task(description="Oracle Cloud analysis", prompt="...", subagent_type="general-p
</subagent_system>"""
_ORDINARY_QA_MARKDOWN_FORMAT_SECTION = """
<ordinary_qa_markdown_format>
当普通问答需要输出带章节结构的较长内容时,必须采用以下 Markdown 规范,以便下载为 Word 后得到正确的自动编号和公文标题格式:
- 文档主标题使用 `# 主标题`;主标题只写标题文字,不添加章节编号。
- 一级章节使用 `## 一、标题`,二级章节使用 `### (一) 标题`,三级章节使用 `#### 1. 标题`。二级编号必须使用半角括号 `(一)`。
- 不要在标题中使用 `2.1`、`2.1.1` 等多级阿拉伯数字编号;章节编号直接按上述三种形式书写。
- 默认禁止使用以 `-`、`*`、`+` 或 `•` 开头的无序圆点列表;并列内容优先改写为完整自然段,确需逐项表达时使用有序列表。只有用户明确要求无序列表时才使用。
- 简短问答不必为了套用格式而强行添加标题;本规范只约束实际使用的标题和列表。
</ordinary_qa_markdown_format>
"""
SYSTEM_PROMPT_TEMPLATE = """
_ORDINARY_QA_MARKDOWN_FORMAT_SECTION = """
<ordinary_qa_markdown_format>
当普通问答需要输出带章节结构的较长内容时,必须采用以下 Markdown 规范,以便下载为 Word 后得到正确的自动编号和公文标题格式:
- 文档主标题使用 `# 主标题`;主标题只写标题文字,不添加章节编号。
- 一级章节使用 `## 一、标题`,二级章节使用 `### (一) 标题`,三级章节使用 `#### 1. 标题`。二级编号必须使用半角括号 `(一)`。
- 不要在标题中使用 `2.1`、`2.1.1` 等多级阿拉伯数字编号;章节编号直接按上述三种形式书写。
- 默认禁止使用以 `-`、`*`、`+` 或 `•` 开头的无序圆点列表;并列内容优先改写为完整自然段,确需逐项表达时使用有序列表。只有用户明确要求无序列表时才使用。
- 简短问答不必为了套用格式而强行添加标题;本规范只约束实际使用的标题和列表。
</ordinary_qa_markdown_format>
"""
SYSTEM_PROMPT_TEMPLATE = """
<role>
You are {agent_name}, an internal super agent.
</role>
@@ -624,15 +624,15 @@ You: "Deploying to staging..." [proceed]
{acp_section}
</working_directory>
<response_style>
- Clear and Concise: Avoid over-formatting unless requested
- Natural Tone: Use paragraphs and prose, not bullet points by default
- Action-Oriented: Focus on delivering results, not explaining processes
</response_style>
{ordinary_qa_format_section}
<citations>
<response_style>
- Clear and Concise: Avoid over-formatting unless requested
- Natural Tone: Use paragraphs and prose, not bullet points by default
- Action-Oriented: Focus on delivering results, not explaining processes
</response_style>
{ordinary_qa_format_section}
<citations>
**CRITICAL: Always include citations when using web search results**
- **When to Use**: MANDATORY after web_search, web_fetch, or any external information source
@@ -792,8 +792,7 @@ def apply_agent_only_prompt_template(
else ""
)
if writing_mode and not writing_artifact_path:
# 与通用模板一致:对话行为照旧,交付时刻的「写 md」动作交给
# deep_research_report 管线;资料不足时先经 ask_clarification 问用户。
# 对话行为照旧;只有开始写 md 时才走 deep_research_report。资料不足也直接开写。
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.
@@ -801,11 +800,11 @@ Writing mode is enabled for this run (first report turn — no existing artifact
`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.
- If harvested materials are thin, still call `deep_research_report` once and let it write immediately.
Do NOT ask the user whether to search for more, and do NOT call `ask_clarification` for insufficient materials.
- Search with your normal conversation tools. `deep_research_report` only writes the report file from materials already in this conversation; it does not search.
- 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.
- After the tool returns successfully: do NOT call `read_file`, `write_file`, `str_replace`, or `present_files` on the report. Reply briefly (2-3 sentences) summarizing the core conclusions. Do not rewrite even if you think materials were thin.
- Only if the tool fails, tell the user and offer to retry.
</writing_mode>
"""
@@ -1407,7 +1406,7 @@ def build_report_structure_setup_prompt(
"""
def apply_prompt_template(
def apply_prompt_template(
subagent_enabled: bool = False,
max_concurrent_subagents: int = 3,
*,
@@ -1419,11 +1418,11 @@ def apply_prompt_template(
is_bootstrap: bool = False,
app_config: AppConfig | None = None,
memory_injection_enabled: bool = True,
rag_mode_enabled: bool = False,
is_notebook_mode: bool = False,
notebook_source_ids: list[int] | None = None,
is_scheduled_run: bool = False,
) -> str:
rag_mode_enabled: bool = False,
is_notebook_mode: bool = False,
notebook_source_ids: list[int] | None = None,
is_scheduled_run: bool = False,
) -> str:
storage_agent_id = agent_id if agent_id is not None else agent_name
# Get memory context
@@ -1473,9 +1472,8 @@ def apply_prompt_template(
else ""
)
if writing_mode and not writing_artifact_path:
# 首轮:对话行为一切照旧,仅在交付时刻把「写 md」动作交给
# deep_research_report 管线(收割对话资料 + 通用分析结构)。资料不足时
# 工具会返回指令,让模型经 ask_clarification 征询用户是否补充检索。
# 对话行为一切照旧;只有开始写 md 时才把交付交给 deep_research_report。
# 资料不足也直接开写,不再经 ask_clarification 征询用户是否补充检索。
writing_mode_section = """
<writing_mode>
Writing mode is enabled for this run (first report turn — no existing artifact).
@@ -1487,14 +1485,13 @@ Writing mode is enabled for this run (first report turn — no existing artifact
- 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
- The tool reuses the materials already collected in this conversation, 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.
- If harvested materials are thin, still call `deep_research_report` once and let it start the writing pipeline immediately.
Do NOT ask the user whether to search for more materials, and do NOT call `ask_clarification` for that reason.
- Search with your normal conversation tools. `deep_research_report` only writes the report file from materials already in this conversation; it does not search.
- 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.
- While the tool runs, stay silent. After it returns successfully: do NOT call `read_file`, `write_file`, `str_replace`, or `present_files` on the report. 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, and do not rewrite even if you think materials were thin.
- 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>
"""
@@ -1528,7 +1525,7 @@ Writing mode is enabled for this run.
# Build the offline-network policy block (empty unless DEER_FLOW_OFFLINE_MODE is set).
network_policy_section = _build_network_policy_section()
rag_mode_section = (
rag_mode_section = (
"""
<rag_citation_mode>
RAG/reference display mode is enabled.
@@ -1541,15 +1538,15 @@ When a search, knowledge, skill, or MCP tool returns a result list:
</rag_citation_mode>
"""
if rag_mode_enabled
else ""
)
ordinary_qa_format_section = (
_ORDINARY_QA_MARKDOWN_FORMAT_SECTION
if not is_bootstrap and not writing_mode and not is_notebook_mode and not is_scheduled_run
else ""
)
# Format the prompt with dynamic skills and memory
else ""
)
ordinary_qa_format_section = (
_ORDINARY_QA_MARKDOWN_FORMAT_SECTION
if not is_bootstrap and not writing_mode and not is_notebook_mode and not is_scheduled_run
else ""
)
# 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),
@@ -1562,10 +1559,10 @@ When a search, knowledge, skill, or MCP tool returns a result list:
network_policy_section=network_policy_section,
subagent_section=subagent_section,
subagent_reminder=subagent_reminder,
subagent_thinking=subagent_thinking,
acp_section=acp_and_mounts_section,
ordinary_qa_format_section=ordinary_qa_format_section,
)
subagent_thinking=subagent_thinking,
acp_section=acp_and_mounts_section,
ordinary_qa_format_section=ordinary_qa_format_section,
)
prompt = prompt + rag_mode_section + _current_time_context()
@@ -0,0 +1,468 @@
"""Redirect writing-mode Markdown deliverables onto ``deep_research_report``.
Writing mode still allows normal chat, search, and clarification. The pipeline
starts only when the model begins writing the report file (``write_file`` /
``str_replace`` of ``report.md`` or any Markdown under
``/mnt/user-data/outputs/``): those calls are rewritten to
``deep_research_report``. Sibling ``present_files`` of the same report are
dropped because the pipeline presents the file itself.
After the pipeline has succeeded once in this thread, further
``deep_research_report`` / hand-written report writes / ``read_file`` of the
report are dropped. The first time that happens, a hidden summary nudge is
injected and the graph jumps back to the model so it can write the 2–3
sentence wrap-up. If it still tries to loop after that nudge, the turn ends.
Ending immediately on the first rewrite attempt left the model's
"I will rewrite this" text as the visible summary.
This middleware never sets ``tool_choice``. Thinking-mode providers (Aliyun
compatible-mode) reject ``required`` / object ``tool_choice`` with HTTP 400.
"""
from __future__ import annotations
import json
import logging
from collections.abc import Awaitable, Callable
from copy import deepcopy
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
from deerflow.tools.builtins.deep_research_report_tool import is_writing_mode_report_path
logger = logging.getLogger(__name__)
TOOL_NAME = "deep_research_report"
_WRITE_TOOLS = frozenset({"write_file", "str_replace"})
_READ_TOOLS = frozenset({"read_file", "read_multiple_files"})
_PRESENT_TOOL = "present_files"
_OUTPUTS_PREFIX = "/mnt/user-data/outputs"
_MAX_TOPIC_CHARS = 500
_NUDGE_KWARG = "writing_mode_summary_nudge"
_REJECT_HANDWRITTEN = (
"写作模式的报告文件必须由 `deep_research_report` 生成,禁止用 write_file / "
"str_replace 手写报告。请立即调用 `deep_research_report`(topic=用户课题原文)。"
)
_REJECT_AFTER_SUCCESS = (
"写作管线已经完成,报告已写入 /mnt/user-data/outputs/report.md 并展示给用户。"
"禁止再次调用 deep_research_report,也禁止用 write_file / str_replace / "
"read_file 读写该报告。请只用 2-3 句话总结核心结论后结束本轮,不要再调用任何文件或写作工具。"
)
_SUMMARY_NUDGE = (
"<system_reminder>\n"
"写作管线已经完成,报告已写入 /mnt/user-data/outputs/report.md 并展示给用户。\n"
"请只用 2-3 句话总结核心结论,不要再调用任何工具,不要阅读或重写该文件。\n"
"不要评价材料是否不足,不要计划重写。\n"
"</system_reminder>"
)
def _is_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
return not kwargs.get("hide_from_ui")
def _normalize_args(raw: object) -> dict[str, Any]:
if isinstance(raw, dict):
return raw
if isinstance(raw, str):
try:
parsed = json.loads(raw)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: object, key: str, default: Any = None) -> Any:
if isinstance(tool_call, dict):
return tool_call.get(key, default)
getter = getattr(tool_call, "get", None)
if callable(getter):
return getter(key, default)
return getattr(tool_call, key, default)
def _tool_name(tool_call: object) -> str:
return str(_tool_field(tool_call, "name", "") or "")
def _tool_path(tool_call: object) -> str:
args = _normalize_args(_tool_field(tool_call, "args", {}))
path = args.get("path")
if path is None:
files = args.get("files") or args.get("filepaths") or args.get("paths")
if isinstance(files, list) and files:
path = files[0]
return str(path or "").strip().replace("\\", "/")
def _is_outputs_markdown_path(path: str) -> bool:
if is_writing_mode_report_path(path):
return True
if not path:
return False
lowered = path.lower()
if not (lowered.endswith(".md") or lowered.endswith(".markdown")):
return False
if path == _OUTPUTS_PREFIX or path.startswith(f"{_OUTPUTS_PREFIX}/"):
return True
relative = path.lstrip("./")
return relative == "outputs" or relative.startswith("outputs/")
def is_handwritten_report_call(tool_call: object) -> bool:
"""True when the model is about to hand-write the writing-mode Markdown file."""
if _tool_name(tool_call) not in _WRITE_TOOLS:
return False
return _is_outputs_markdown_path(_tool_path(tool_call))
def is_report_present_call(tool_call: object) -> bool:
if _tool_name(tool_call) != _PRESENT_TOOL:
return False
path = _tool_path(tool_call)
if path:
return _is_outputs_markdown_path(path)
args = _normalize_args(_tool_field(tool_call, "args", {}))
files = args.get("files") or args.get("filepaths") or args.get("paths") or []
if isinstance(files, list):
return any(_is_outputs_markdown_path(str(item or "").strip().replace("\\", "/")) for item in files)
return False
def is_pipeline_call(tool_call: object) -> bool:
return _tool_name(tool_call) == TOOL_NAME
def is_report_reread_call(tool_call: object) -> bool:
"""True when the model is about to re-read the writing-mode Markdown file."""
if _tool_name(tool_call) not in _READ_TOOLS:
return False
path = _tool_path(tool_call)
if path:
return _is_outputs_markdown_path(path)
args = _normalize_args(_tool_field(tool_call, "args", {}))
files = args.get("files") or args.get("filepaths") or args.get("paths") or []
if isinstance(files, list):
return any(_is_outputs_markdown_path(str(item or "").strip().replace("\\", "/")) for item in files)
return False
def is_deliverable_loop_call(tool_call: object) -> bool:
"""Pipeline, hand-written report, or presenting the report — all loop fuel."""
return is_pipeline_call(tool_call) or is_handwritten_report_call(tool_call) or is_report_present_call(tool_call)
def is_post_success_loop_call(tool_call: object) -> bool:
"""After a successful pipeline, re-reading the report is also a loop."""
return is_deliverable_loop_call(tool_call) or is_report_reread_call(tool_call)
def _already_nudged_summary(messages: list[Any]) -> bool:
for message in messages:
if not isinstance(message, HumanMessage):
continue
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get(_NUDGE_KWARG):
return True
return False
def _summary_nudge_message() -> HumanMessage:
return HumanMessage(
content=_SUMMARY_NUDGE,
additional_kwargs={"hide_from_ui": True, _NUDGE_KWARG: True},
)
def is_post_success_loop_call(tool_call: object) -> bool:
"""After a successful pipeline, re-reading the report is also a loop."""
return is_deliverable_loop_call(tool_call) or is_report_reread_call(tool_call)
def _already_nudged_summary(messages: list[Any]) -> bool:
for message in messages:
if not isinstance(message, HumanMessage):
continue
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get(_NUDGE_KWARG):
return True
return False
def _summary_nudge_message() -> HumanMessage:
return HumanMessage(
content=_SUMMARY_NUDGE,
additional_kwargs={"hide_from_ui": True, _NUDGE_KWARG: True},
)
def _report_tool_succeeded(message: ToolMessage) -> bool:
if str(getattr(message, "name", "") or "") != TOOL_NAME:
return False
status = str(getattr(message, "status", "") or "").lower()
if status == "error":
return False
content = str(getattr(message, "content", "") or "").strip()
if not content:
return False
return not content.lower().startswith("error")
def pipeline_already_succeeded(messages: list[Any]) -> bool:
"""True after any successful ``deep_research_report`` in this thread."""
return any(isinstance(message, ToolMessage) and _report_tool_succeeded(message) for message in messages)
def _message_text(message: Any) -> str:
content = getattr(message, "content", "")
if isinstance(content, list):
parts: list[str] = []
for part in content:
if isinstance(part, str):
parts.append(part)
elif isinstance(part, dict):
text = part.get("text")
if isinstance(text, str):
parts.append(text)
return " ".join(parts).strip()
return str(content or "").strip()
def extract_report_topic(messages: list[Any]) -> str:
"""Use the latest visible user text as ``deep_research_report.topic``."""
for message in reversed(messages):
if _is_visible_human(message):
text = " ".join(_message_text(message).split())
if text:
return text[:_MAX_TOPIC_CHARS]
return "当前课题"
def _as_report_call(tool_call: object, topic: str) -> dict[str, Any]:
call_id = str(_tool_field(tool_call, "id") or "")
return {
"name": TOOL_NAME,
"args": {"topic": topic},
"id": call_id,
"type": "tool_call",
}
def _kept_call_ids(calls: list[Any]) -> set[str]:
return {str(_tool_field(call, "id") or "") for call in calls if _tool_field(call, "id")}
def _sync_raw_tool_calls(last: AIMessage, kept: list[Any]) -> dict[str, Any]:
update: dict[str, Any] = {"tool_calls": kept}
additional_kwargs = dict(getattr(last, "additional_kwargs", {}) or {})
raw_calls = additional_kwargs.get("tool_calls")
kept_ids = _kept_call_ids(kept)
rewritten_by_id = {
str(_tool_field(call, "id") or ""): call
for call in kept
if _tool_field(call, "id")
}
if isinstance(raw_calls, list) and raw_calls:
synced: list[Any] = []
for item in raw_calls:
if not isinstance(item, dict):
continue
item_id = str(item.get("id") or "")
if item_id not in kept_ids:
continue
replacement = rewritten_by_id.get(item_id)
if replacement is not None and _tool_name(replacement) == TOOL_NAME:
function = dict(item.get("function") or {})
function["name"] = TOOL_NAME
function["arguments"] = json.dumps(
_normalize_args(_tool_field(replacement, "args", {})),
ensure_ascii=False,
)
synced.append({**item, "function": function})
else:
synced.append(item)
if synced:
additional_kwargs["tool_calls"] = synced
else:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
elif not kept:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
update["additional_kwargs"] = additional_kwargs
if not kept:
response_metadata = deepcopy(getattr(last, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def rewrite_handwritten_report_calls(
last: AIMessage,
*,
topic: str,
pipeline_already_done: bool = False,
) -> AIMessage | None:
"""Rewrite or drop report deliverable tool calls.
Before the pipeline has succeeded: rewrite the first hand-written report
write to ``deep_research_report`` and drop sibling presents.
After it has succeeded: drop every pipeline / hand-written / present /
report-reread call so the model cannot start another writing loop.
"""
tool_calls = list(getattr(last, "tool_calls", None) or [])
if not tool_calls:
return None
if pipeline_already_done:
kept = [call for call in tool_calls if not is_post_success_loop_call(call)]
if len(kept) == len(tool_calls):
return None
update = _sync_raw_tool_calls(last, kept)
if not kept:
update["content"] = ""
return last.model_copy(update=update)
has_pipeline = any(is_pipeline_call(call) for call in tool_calls)
rewritten: list[Any] = []
changed = False
redirected = has_pipeline
for call in tool_calls:
if is_pipeline_call(call):
rewritten.append(call)
continue
if is_handwritten_report_call(call):
changed = True
if redirected:
continue
rewritten.append(_as_report_call(call, topic))
redirected = True
continue
if is_report_present_call(call) and (
has_pipeline or redirected or any(is_handwritten_report_call(item) for item in tool_calls)
):
changed = True
continue
rewritten.append(call)
if not changed:
return None
return last.model_copy(update=_sync_raw_tool_calls(last, rewritten))
def _messages_from_tool_request(request: ToolCallRequest) -> list[Any]:
state = getattr(request, "state", None) or {}
if isinstance(state, dict):
return list(state.get("messages") or [])
messages = getattr(state, "messages", None)
return list(messages or [])
class WritingModeReportMiddleware(AgentMiddleware[AgentState]):
"""Start the writing pipeline only when the model begins writing the Markdown file."""
state_schema = AgentState
def _redirect_or_stop(self, state: AgentState) -> dict[str, Any] | None:
messages = list(state.get("messages") or [])
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
already_done = pipeline_already_succeeded(messages)
patched = rewrite_handwritten_report_calls(
last,
topic=extract_report_topic(messages),
pipeline_already_done=already_done,
)
if patched is None:
return None
result: dict[str, Any] = {"messages": [patched]}
if already_done and not (patched.tool_calls or []):
if _already_nudged_summary(messages):
logger.info(
"Writing-mode pipeline already succeeded; summary nudge ignored, ending turn"
)
result["jump_to"] = "end"
return result
logger.info(
"Writing-mode pipeline already succeeded; dropping deliverable tools and nudging summary"
)
result["messages"] = [patched, _summary_nudge_message()]
result["jump_to"] = "model"
return result
def _reject_loop_tool(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
already_done = pipeline_already_succeeded(_messages_from_tool_request(request))
if already_done and is_post_success_loop_call(tool_call):
return ToolMessage(
content=f"Error: {_REJECT_AFTER_SUCCESS}",
tool_call_id=str(_tool_field(tool_call, "id") or ""),
name=str(_tool_name(tool_call) or TOOL_NAME),
)
if not already_done and is_handwritten_report_call(tool_call):
return ToolMessage(
content=f"Error: {_REJECT_HANDWRITTEN}",
tool_call_id=str(_tool_field(tool_call, "id") or ""),
name=str(_tool_name(tool_call) or "write_file"),
)
return None
@hook_config(can_jump_to=["end", "model"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._redirect_or_stop(state)
@hook_config(can_jump_to=["end", "model"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._redirect_or_stop(state)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_loop_tool(request)
if rejected is not None:
return rejected
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
rejected = self._reject_loop_tool(request)
if rejected is not None:
return rejected
return await handler(request)
__all__ = [
"TOOL_NAME",
"WritingModeReportMiddleware",
"extract_report_topic",
"is_handwritten_report_call",
"is_post_success_loop_call",
"is_report_present_call",
"is_report_reread_call",
"pipeline_already_succeeded",
"rewrite_handwritten_report_calls",
]