初始化

This commit is contained in:
gozeros committed 2026-09-07 18:24:55 +08:00
1 parent 34474bd5fc
commit b638b541d0
3008 files changed
+837699

No files matched your search

Whitespace-only changes.
@@ -0,0 +1,20 @@
from .factory import create_deerflow_agent
from .features import Next, Prev, RuntimeFeatures
from .lead_agent import make_lead_agent
from .lead_agent.prompt import prime_enabled_skills_cache
from .thread_state import SandboxState, ThreadState
# LangGraph imports deerflow.agents when registering the graph. Prime the
# enabled-skills cache here so the request path can usually read a warm cache
# without forcing synchronous filesystem work during prompt module import.
prime_enabled_skills_cache()
__all__ = [
"create_deerflow_agent",
"RuntimeFeatures",
"Next",
"Prev",
"make_lead_agent",
"SandboxState",
"ThreadState",
]
@@ -0,0 +1,3 @@
from .graph import make_ai_writing_graph
__all__ = ["make_ai_writing_graph"]
@@ -0,0 +1,463 @@
"""AI 写作 LangGraph Graph,含 4 个用户干预点。"""
from __future__ import annotations
import logging
from langchain_core.runnables import RunnableConfig
from langgraph.graph import END, StateGraph
from langgraph.types import interrupt
from .nodes.editor import editor_node
from .nodes.intent_parser import intent_parser_node
from .nodes.researcher import researcher_node
from .nodes.sample_analyzer import sample_analyzer_node
from .nodes.writer_draft import writer_draft_node
from .nodes.writer_outline import writer_outline_node
from .state import AIWritingState
logger = logging.getLogger(__name__)
async def _mark_session_done(config: RunnableConfig | None) -> None:
"""把业务表行 status 写成 ``done``。
pause_draft_confirm action=finalize / pause_review_confirm force_finalize 时调,
让 LangGraph Server 路径下新会话有正确终态(老路径靠 ``_stream_graph_segment``
finally 块写终态,新路径完全不走它)。失败不影响 graph 流程。
"""
if not config:
return
thread_id = (config.get("configurable") or {}).get("thread_id")
if not thread_id:
return
from deerflow.persistence.ai_writing_sessions import get_default_store
from deerflow.runtime.user_context import AUTO
repo = get_default_store()
if repo is None:
return
try:
await repo.update(thread_id, user_id=AUTO, status="done")
except Exception:
logger.exception("ai_writing: mark_session_done failed (non-fatal) thread_id=%s", thread_id)
# ── 干预节点 ──────────────────────────────────────────────────────────────────
async def pause_material_confirm(state: AIWritingState) -> dict:
"""PAUSE-1:素材确认"""
pkg = state["material_package"]
user_input: dict = interrupt({
"pause_point": "material_confirm",
"message": "素材收集专家已完成素材搜集,请确认素材后继续。",
"materials": pkg["materials"],
"keywords": pkg["keywords"],
"summary": pkg["summary"],
})
action = user_input.get("action", "confirm")
# 单输入框文本:可能是技能名 / 来源 / 检索意图,re_search 和 enable_skill_search 都用得到
user_query = (user_input.get("userQuery") or user_input.get("user_query") or "").strip()
requested_source = user_input.get("materialSource") or user_input.get("material_source")
fallback_source = state.get("material_source") or "general"
material_source = requested_source if requested_source in ("general", "knowledge_base", "notebook") else fallback_source
if material_source not in ("general", "knowledge_base", "notebook"):
material_source = "general"
source_label = {
"general": "通用检索",
"knowledge_base": "知识库检索",
"notebook": "我的空间",
}.get(material_source, "通用检索")
if action == "confirm":
approved_ids = set(user_input.get("approvedMaterialIds") or [m["id"] for m in pkg["materials"]])
filtered = [m for m in pkg["materials"] if m["id"] in approved_ids]
updated_pkg = {**pkg, "materials": filtered}
# 用户自带大纲:researcher 已在「搜集素材」阶段解析大纲并归类素材 → 跳过大纲生成步,
# 仅把被用户取消勾选的素材从各章节 material_ids 里剔除,直接进入大纲确认。
prebuilt = state.get("current_outline")
if prebuilt and (state.get("user_outline_raw") or "").strip():
return {
"material_package": updated_pkg,
"current_outline": _prune_outline_material_ids(prebuilt, approved_ids),
"last_user_intervention": user_input,
"status": "awaiting_outline_confirm",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "已采用你提供的大纲并归类素材,请确认大纲"}],
}
return {
"material_package": updated_pkg,
"last_user_intervention": user_input,
"status": "writing_outline",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "用户已确认素材,开始规划大纲"}],
}
# enable_skill_search:旧版「启用技能检索」按钮的兼容入口——通用检索现在
# 本来就按 agent 配置技能编排,researcher 把它按 user_query 追加检索处理
if action == "enable_skill_search":
msg = f"按输入「{user_query[:30]}」使用{source_label}追加素材…" if user_query else f"使用{source_label}重新检索中…"
return {
"last_user_intervention": {**user_input, "action": "enable_skill_search", "user_query": user_query, "material_source": material_source},
"material_source": material_source,
"status": "researching",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": msg}],
}
# re_search:带 user_query = 在配置技能中匹配检索并**追加**素材;
# 不带输入 = 重新生成检索词、覆盖式重检(兼容旧版 extraKeywords 数组追加)
extra_kws = user_input.get("extraKeywords") or []
msg = f"按输入「{user_query[:30]}」使用{source_label}追加素材…" if user_query else f"使用{source_label}重新搜索中..."
return {
"last_user_intervention": {**user_input, "_extra_keywords": extra_kws, "user_query": user_query, "material_source": material_source},
"material_source": material_source,
"status": "researching",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": msg}],
}
def _prune_outline_material_ids(outline: dict, approved_ids: set) -> dict:
"""把大纲各章节 material_ids 里、用户在素材确认卡取消勾选的素材编号剔除掉。
用户自带大纲时素材归类发生在「搜集素材」阶段(researcher),早于素材确认;
用户在确认卡里去掉某些素材后,用这个函数把对应编号从大纲剔除,保持一致。
"""
if not outline:
return outline
sections = []
for s in outline.get("sections", []):
kept = [mid for mid in (s.get("material_ids") or []) if mid in approved_ids]
sections.append({**s, "material_ids": kept})
return {**outline, "sections": sections}
def _normalize_outline(outline: dict) -> dict:
"""将前端回传的 camelCase 大纲统一为后端 snake_case 格式。"""
if not outline:
return outline
sections = []
for s in outline.get("sections", []):
sections.append({
"section_title": s.get("section_title") or s.get("sectionTitle", ""),
"key_points": s.get("key_points") or s.get("keyPoints", []),
"material_ids": s.get("material_ids") or s.get("materialIds", []),
})
return {"title": outline.get("title", ""), "sections": sections}
def _check_outline_material_support(outline: dict) -> str:
"""轻量启发式:统计未关联任何素材的章节,返回预警文案(空串=无需预警)。
仅做提示、不拦截流程;真正的素材不足会在写作节点被检出并触发求助暂停。
"""
sections = (outline or {}).get("sections", [])
weak = [
(s.get("section_title") or s.get("sectionTitle") or "")
for s in sections
if not (s.get("material_ids") or s.get("materialIds"))
]
weak = [t for t in weak if t]
if not weak:
return ""
return (
f"有 {len(weak)} 个章节未关联检索素材({('、'.join(weak))})。"
"严格依据素材模式下,这些章节在写作时可能因素材不足而暂停向你求助。"
)
async def pause_outline_confirm(state: AIWritingState) -> dict:
"""PAUSE-2:大纲确认"""
user_input: dict = interrupt({
"pause_point": "outline_confirm",
"message": "作家已完成大纲规划,请确认或编辑大纲后继续。",
"outline": state["current_outline"],
})
action = user_input.get("action", "confirm")
if action == "confirm":
raw_outline = user_input.get("editedOutline") or state["current_outline"]
edited = _normalize_outline(raw_outline) if raw_outline else state["current_outline"]
events: list[dict] = [{"type": "resumed", "agent_name": "系统", "message": "用户已确认大纲,开始写作"}]
# 阶段四:严格模式下对大纲做轻量素材充分性预警(仅提示,不拦截流程)
if state.get("writing_mode") == "strict":
warning = _check_outline_material_support(edited)
if warning:
events.append({
"type": "notice", "agent_name": "系统",
"title": "素材充分性提示", "detail": warning,
})
return {
"current_outline": edited,
"last_user_intervention": user_input,
"status": "writing_draft",
"progress_events": events,
}
# re_outline
feedback = user_input.get("outlineFeedback", "")
updates: dict = {
"last_user_intervention": {**user_input, "_feedback": feedback},
"status": "writing_outline",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": f"重新规划大纲({feedback[:30]})"}],
}
# 用户在卡片里手动改过大纲 → 以手动版作为本次重规划的编辑基准
raw_edited = user_input.get("editedOutline")
if raw_edited:
updates["current_outline"] = _normalize_outline(raw_edited)
return updates
async def pause_draft_confirm(state: AIWritingState, config: RunnableConfig) -> dict:
"""PAUSE-3:草稿确认"""
draft = state.get("current_draft")
# 防御:草稿缺失(写作节点异常未产出)时不进入确认暂停,转 error 优雅结束,
# 避免 draft["title"] 在 None 上崩溃。正常路径下 after_writer_draft 已拦截
# status:error,这里是兜底第二道防线(如 editor 异常等边角情形)。
if not draft:
return {
"status": "error",
"progress_events": [{
"type": "error", "agent_name": "作家",
"title": "草稿缺失", "detail": "草稿尚未生成,无法进入确认环节,请重试。",
"message": "草稿生成失败",
}],
}
user_input: dict = interrupt({
"pause_point": "draft_confirm",
"message": "草稿已完成,请确认或给出修改意见。",
"draft_title": draft["title"],
"revision_count": draft["revision_count"],
"review_result": state.get("review_result"),
})
action = user_input.get("action", "to_editor")
if action == "finalize":
await _mark_session_done(config)
return {
"last_user_intervention": user_input,
"status": "done",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "用户确认定稿"}],
}
if action == "user_revise":
notes = user_input.get("userRevisionNotes", "")
return {
"last_user_intervention": {**user_input, "_user_notes": notes},
"revision_count": state.get("revision_count", 0) + 1,
"status": "revising",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": f"按用户意见重写({notes[:30]})"}],
}
# to_editor:用户可能在「您的修改意见」里填了关注点再点「让编辑继续审核」,
# 把它带给编辑节点,让三维度审查重点核查用户在意的方面(不再被丢弃)。
editor_notes = (user_input.get("userRevisionNotes") or "").strip()
msg = (
f"提交编辑审核(已附带你的修改意见:{editor_notes[:30]})"
if editor_notes else "提交编辑审核"
)
return {
"last_user_intervention": {**user_input, "_editor_notes": editor_notes},
"status": "reviewing",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": msg}],
}
async def pause_section_help(state: AIWritingState) -> dict:
"""素材不足求助点:严格模式下作家发现章节缺素材,让用户逐章决定如何处理。
用户对每个被阻塞章节选择:
- supplement:补充检索素材(整体回到检索流程重走)
- delete:删除该章节
- loose:按通用知识续写该章节
"""
blocked = state.get("blocked_sections") or []
user_input: dict = interrupt({
"pause_point": "section_help",
"message": "部分章节缺少足够素材支撑写作,请决定如何处理。",
"blocked_sections": blocked,
})
# sectionDecisions: [{"sectionTitle": "...", "decision": "supplement|delete|loose"}]
by_title: dict = {}
for d in user_input.get("sectionDecisions") or []:
title = d.get("sectionTitle") or d.get("section_title")
if title:
by_title[title] = d.get("decision", "loose")
# 任一章节选「补充检索」→ 整体回到检索,重走「检索 → 素材确认 → 大纲 → 写作」
supplement_reasons = [
b["reason"] for b in blocked if by_title.get(b["section_title"]) == "supplement"
]
if supplement_reasons:
return {
# supplement_search:补充检索(保留已有素材、追加新素材),完成后直接回写作、不重排大纲
"last_user_intervention": {**user_input, "action": "supplement_search", "_extra_keywords": supplement_reasons},
"status": "researching",
"blocked_sections": None,
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "补充检索素材中…"}],
}
# 否则:删除标记章节、记录「通用知识续写」章节,直接回写作
outline = state.get("current_outline") or {"title": "", "sections": []}
kept, loose_titles = [], []
for s in outline.get("sections", []):
title = s.get("section_title") or s.get("sectionTitle", "")
decision = by_title.get(title)
if decision == "delete":
continue
if decision == "loose":
loose_titles.append(title)
kept.append(s)
# 防御:用户把所有章节都删了 → 保留原大纲并全部按通用知识写,避免空文章
if not kept:
kept = outline.get("sections", [])
loose_titles = [s.get("section_title") or s.get("sectionTitle", "") for s in kept]
return {
"current_outline": {**outline, "sections": kept},
"last_user_intervention": {**user_input, "_loose_sections": loose_titles},
"status": "writing_draft",
"blocked_sections": None,
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "已按你的选择继续写作…"}],
}
async def pause_review_confirm(state: AIWritingState, config: RunnableConfig) -> dict:
"""PAUSE-4:编辑打回确认"""
user_input: dict = interrupt({
"pause_point": "review_confirm",
"message": "编辑认为文章需要修改,请决定下一步操作。",
"review_result": state["review_result"],
"revision_count": state.get("revision_count", 0),
"max_revisions": state.get("max_revisions", 3),
})
if user_input.get("overrideVerdict") or user_input.get("action") == "force_finalize":
await _mark_session_done(config)
return {
"last_user_intervention": user_input,
"status": "done",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "用户强制定稿"}],
}
action = user_input.get("action", "accept_review")
extra_notes = user_input.get("userRevisionNotes", "")
return {
"last_user_intervention": {**user_input, "_extra_notes": extra_notes, "action": action},
"revision_count": state.get("revision_count", 0) + 1,
"status": "revising",
"progress_events": [{"type": "resumed", "agent_name": "系统", "message": "按编辑意见重写"}],
}
# ── 条件路由 ──────────────────────────────────────────────────────────────────
def after_researcher(state: AIWritingState) -> str:
"""检索完成后:补充检索(素材不足求助)直接回写作,否则去素材确认。"""
return "writer_draft" if state.get("status") == "writing_draft" else "pause_material"
def after_material_pause(state: AIWritingState) -> str:
status = state["status"]
if status == "researching":
return "researcher"
# 用户自带大纲:researcher 已在搜集阶段整理好大纲 → 跳过 writer_outline 生成步,直接确认大纲。
if status == "awaiting_outline_confirm":
return "pause_outline"
return "writer_outline"
def after_outline_pause(state: AIWritingState) -> str:
return "writer_outline" if state["status"] == "writing_outline" else "writer_draft"
def after_writer_draft(state: AIWritingState) -> str:
"""写作完成后:素材不足则去求助暂停点,否则去草稿确认。
写作节点兜底成 ``status:error``(如模型创建失败)时直接结束本次 run —— 否则会
流到 pause_draft,而此时 ``current_draft`` 为 None,``pause_draft_confirm`` 取
``draft["title"]`` 会二次崩溃('NoneType' object is not subscriptable)。错误事件
已由写作节点 emit,run 优雅结束即可,用户重试不受影响。
"""
if state["status"] == "error":
return "end"
return "pause_section_help" if state["status"] == "awaiting_section_help" else "pause_draft"
def after_section_help_pause(state: AIWritingState) -> str:
"""求助暂停点之后:补充检索回 researcher,否则回写作。"""
return "researcher" if state["status"] == "researching" else "writer_draft"
def after_draft_pause(state: AIWritingState) -> str:
status = state["status"]
if status == "done":
return "end"
if status == "revising":
return "writer_draft"
return "editor"
def after_review(state: AIWritingState) -> str:
review = state.get("review_result") or {}
if review.get("verdict") == "pass":
return "pause_draft"
rev_count = state.get("revision_count", 0)
max_rev = state.get("max_revisions", 3)
if rev_count >= max_rev:
return "pause_draft" # 超出上限,强制到草稿确认
return "pause_review"
def after_review_pause(state: AIWritingState) -> str:
return "end" if state["status"] == "done" else "writer_draft"
# ── LangGraph Server 入口 ────────────────────────────────────────────────────
#
# compile 出裸 graph(不带 checkpointer),由 LangGraph Server 注入主 checkpointer
# (langgraph.json 里 ``make_checkpointer`` 配的那个)。AI 写作的 thread 状态与
# 主聊天共享同一份 saver —— LangGraph schema 用 ``(thread_id, checkpoint_ns)`` 做
# 主键,UUID 不会撞。
def make_ai_writing_graph(config=None):
"""LangGraph Server graph factory:不接收 checkpointer,由 Server 注入。
Args:
config: LangGraph Server 调用工厂时注入的 RunnableConfig(暂未消费)。
"""
g = StateGraph(AIWritingState)
g.add_node("sample_analyzer", sample_analyzer_node)
g.add_node("intent_parser", intent_parser_node)
g.add_node("researcher", researcher_node)
g.add_node("pause_material", pause_material_confirm)
g.add_node("writer_outline", writer_outline_node)
g.add_node("pause_outline", pause_outline_confirm)
g.add_node("writer_draft", writer_draft_node)
g.add_node("pause_section_help", pause_section_help)
g.add_node("pause_draft", pause_draft_confirm)
g.add_node("editor", editor_node)
g.add_node("pause_review", pause_review_confirm)
g.set_entry_point("sample_analyzer")
g.add_edge("sample_analyzer", "intent_parser")
g.add_edge("intent_parser", "researcher")
g.add_conditional_edges("researcher", after_researcher,
{"pause_material": "pause_material", "writer_draft": "writer_draft", "writer_outline": "writer_outline"})
g.add_conditional_edges("pause_material", after_material_pause,
{"researcher": "researcher", "writer_outline": "writer_outline", "pause_outline": "pause_outline"})
g.add_edge("writer_outline", "pause_outline")
g.add_conditional_edges("pause_outline", after_outline_pause,
{"writer_outline": "writer_outline", "writer_draft": "writer_draft"})
g.add_conditional_edges("writer_draft", after_writer_draft,
{"pause_section_help": "pause_section_help", "pause_draft": "pause_draft", "end": END})
g.add_conditional_edges("pause_section_help", after_section_help_pause,
{"researcher": "researcher", "writer_draft": "writer_draft"})
g.add_conditional_edges("pause_draft", after_draft_pause,
{"end": END, "writer_draft": "writer_draft", "editor": "editor"})
g.add_conditional_edges("editor", after_review,
{"pause_draft": "pause_draft", "pause_review": "pause_review"})
g.add_conditional_edges("pause_review", after_review_pause,
{"end": END, "writer_draft": "writer_draft"})
return g.compile()
@@ -0,0 +1,573 @@
"""对话驱动写作台的意图路由:用户自由文本 → 结构化 action/payload。
供 Gateway 的 ``POST /api/ai-writing/sessions/{id}/intent`` 调用:读该会话的
graph checkpoint state(素材/大纲/草稿/审核摘要)+ 当前暂停点,用 LLM 把用户的
一句话翻译成 ``UserInterventionPayload`` 可直接消费的指令;或识别为提问(直接
带回 answer)、控制指令、需澄清。
核心安全边界(避免"原逻辑不支持硬套用"):
- action 白名单严格对齐 graph.py 各 pause 节点真实接受的动作(见
``ALLOWED_ACTIONS``),LLM 输出不在白名单内 → 一律降级为 clarify;
- 高代价动作(finalize / force_finalize / 无查询词的覆盖式 re_search)要求
confidence ≥ 0.85,不够 → 降级 clarify;
- 无暂停点(运行中/已结束)时不允许输出任何 action;
- payload 逐 key 白名单清洗,杜绝 LLM 编造字段污染 resume 载荷。
"""
from __future__ import annotations
import logging
import re
from typing import Any, AsyncIterator
from .prompts.intent_router_prompts import (
INTENT_ROUTER_SYSTEM,
INTENT_ROUTER_USER_TEMPLATE,
NO_PAUSE_GUIDE,
STAGE_ACTION_GUIDES,
)
logger = logging.getLogger(__name__)
# 各暂停点合法动作 —— 与 graph.py 的 pause_material_confirm / pause_outline_confirm /
# pause_draft_confirm / pause_review_confirm / pause_section_help 严格对齐。
# 注意 material_confirm 的 enable_skill_search 是旧按钮兼容入口,语义 = 带
# userQuery 的 re_search,意图层统一输出 re_search,不再暴露旧动作。
ALLOWED_ACTIONS: dict[str, set[str]] = {
"material_confirm": {"confirm", "re_search"},
"outline_confirm": {"confirm", "re_outline"},
"draft_confirm": {"to_editor", "finalize", "user_revise"},
"review_confirm": {"accept_review", "force_finalize"},
"section_help": {"section_help"},
}
# 高代价动作的置信度下限(misfire 代价大:结束流程 / 丢弃现有素材)。
HIGH_COST_CONFIDENCE = 0.85
# 普通动作的置信度下限。
ACTION_CONFIDENCE = 0.5
_SECTION_DECISIONS = {"supplement", "loose", "delete"}
_THINK_RE = re.compile(r"<think>.*?</think>", re.S)
_WRITING_ACTION_VERB_RE = re.compile(
r"(新增|增加|添加|加入|加上|补充|补上|补个|补一个|生成|撰写|写一|写个|写成|扩写|缩写|精简|改写|润色|调整|修改|重写|删除|删掉|拆成|合并|挪到|移动|规划|重新规划|设计|安排)"
)
_WRITING_ACTION_TARGET_RE = re.compile(
r"(第[一二三四五六七八九十\d]+[章节段]|章节|章|小节|段落|段|结尾|开头|标题|大纲|内容|案例|表格|总结章|总结章节|结论|摘要|观点|部分)"
)
_INFO_QUESTION_RE = re.compile(r"(哪些|什么|为什么|是什么|有哪些|多少|是否)")
def _fallback_intent() -> dict:
return {
"intent": "clarify",
"action": None,
"payload": {},
"need_research": False,
"research_query": "",
"answer": "",
"confidence": 0.0,
"clarify": "我没有理解你的意思,能换个说法再试一次吗?也可以直接点击上方卡片里的按钮操作。",
}
def _looks_like_writing_change_request(text: str) -> bool:
text = (text or "").strip()
if _INFO_QUESTION_RE.search(text):
return False
return bool(_WRITING_ACTION_VERB_RE.search(text) and _WRITING_ACTION_TARGET_RE.search(text))
def _rule_based_intent(text: str, pause_point: str | None) -> dict | None:
"""Deterministic guard for writing-operation requests that look like Q&A."""
if not _looks_like_writing_change_request(text):
return None
if pause_point == "outline_confirm":
return {
"intent": "revise_outline",
"action": "re_outline",
"payload": {"outlineFeedback": text.strip()},
"need_research": False,
"research_query": "",
"answer": "",
"confidence": 1.0,
"clarify": "",
}
if pause_point == "draft_confirm":
return {
"intent": "revise_draft",
"action": "user_revise",
"payload": {"userRevisionNotes": text.strip()},
"need_research": False,
"research_query": "",
"answer": "",
"confidence": 1.0,
"clarify": "",
}
if pause_point == "review_confirm":
return {
"intent": "accept_review_with_user_notes",
"action": "accept_review",
"payload": {"userRevisionNotes": text.strip()},
"need_research": False,
"research_query": "",
"answer": "",
"confidence": 1.0,
"clarify": "",
}
return None
# ── 上下文快照 ────────────────────────────────────────────────────────────────
def _shorten(text: str, limit: int) -> str:
text = (text or "").strip().replace("\n", " ")
return text if len(text) <= limit else text[: limit - 1] + "…"
def _materials_block(values: dict, limit: int = 30) -> str:
pkg = values.get("material_package") or {}
materials = pkg.get("materials") or []
if not materials:
return "(当前没有素材)"
lines = []
for i, m in enumerate(materials[:limit]):
mid = m.get("id", "")
title = _shorten(str(m.get("title") or ""), 60)
source = _shorten(str(m.get("source") or ""), 20)
excerpt = _shorten(str(m.get("content") or ""), 80)
lines.append(f"{i + 1}. [id={mid}] {title}(来源:{source}){excerpt}")
if len(materials) > limit:
lines.append(f"…共 {len(materials)} 条,仅列出前 {limit} 条")
keywords = pkg.get("keywords") or []
head = f"检索关键词:{'、'.join(str(k) for k in keywords[:10])}\n" if keywords else ""
return head + "\n".join(lines)
def _outline_block(values: dict) -> str:
outline = values.get("current_outline") or {}
sections = outline.get("sections") or []
if not sections:
return "(尚无大纲)"
lines = [f"文章标题:{outline.get('title') or ''}"]
for i, s in enumerate(sections):
title = s.get("section_title") or s.get("sectionTitle") or ""
points = s.get("key_points") or s.get("keyPoints") or []
point_titles = []
for p in points[:6]:
if isinstance(p, dict):
point_titles.append(str(p.get("point_title") or p.get("pointTitle") or ""))
else:
point_titles.append(str(p))
suffix = f"(要点:{_shorten(';'.join(t for t in point_titles if t), 120)})" if point_titles else ""
lines.append(f"第{i + 1}章 {title}{suffix}")
return "\n".join(lines)
def _draft_block(values: dict, body_limit: int = 4000) -> str:
draft = values.get("current_draft") or {}
markdown = str(draft.get("full_markdown") or draft.get("fullMarkdown") or "")
if not markdown:
return "(尚无草稿)"
title = draft.get("title") or ""
word_count = draft.get("word_count") or draft.get("wordCount") or ""
revision = draft.get("revision_count") or draft.get("revisionCount") or 0
body = markdown if len(markdown) <= body_limit else markdown[:body_limit] + "\n…(正文过长已截断)"
return f"草稿标题:《{title}》 修改次数:{revision} 字数:{word_count}\n--- 草稿正文 ---\n{body}"
def _review_block(values: dict) -> str:
review = values.get("review_result") or {}
if not review:
return "(尚无编辑审核结果)"
notes = review.get("revision_notes") or review.get("revisionNotes") or []
lines = [
f"编辑结论:{review.get('verdict', '')}(总分 {review.get('overall_score', review.get('overallScore', ''))},"
f"事实 {review.get('fact_score', review.get('factScore', ''))} / 逻辑 {review.get('logic_score', review.get('logicScore', ''))} / "
f"语言 {review.get('language_score', review.get('languageScore', ''))})",
]
for i, n in enumerate(notes):
issue = _shorten(str(n.get("issue") or ""), 80)
suggestion = _shorten(str(n.get("suggestion") or ""), 80)
lines.append(f"意见[index={i}] [{n.get('category', '')}/{n.get('severity', '')}] {issue} → {suggestion}")
return "\n".join(lines)
def _blocked_block(values: dict, interrupt_value: dict | None) -> str:
blocked = (interrupt_value or {}).get("blocked_sections") or values.get("blocked_sections") or []
if not blocked:
return ""
lines = ["受阻章节(素材不足):"]
for b in blocked:
title = b.get("section_title") or b.get("sectionTitle") or ""
reason = _shorten(str(b.get("reason") or ""), 80)
lines.append(f"- {title}:{reason}")
return "\n".join(lines)
def build_context_snapshot(values: dict, pause_point: str | None, interrupt_value: dict | None = None) -> str:
"""把 checkpoint state 压成 LLM 可读的中文上下文快照。
按当前阶段裁剪重点:素材阶段给全量素材清单;大纲阶段给大纲;草稿/审核阶段给
草稿正文(截断)+ 审核意见(带 index,供 selectedIssueIndices 映射)。
"""
status = str(values.get("status") or "")
intent = _shorten(str(values.get("user_intent") or ""), 200)
parts = [f"写作主题:{intent}", f"流程状态:{status or '未知'}"]
if pause_point == "material_confirm":
parts.append("素材清单:\n" + _materials_block(values))
outline = _outline_block(values)
if outline != "(尚无大纲)":
parts.append("已有大纲:\n" + outline)
elif pause_point == "outline_confirm":
parts.append("当前大纲:\n" + _outline_block(values))
parts.append("素材清单(供判断 need_research):\n" + _materials_block(values, limit=20))
elif pause_point in ("draft_confirm", "review_confirm"):
parts.append(_draft_block(values))
parts.append("编辑审核:\n" + _review_block(values))
parts.append("素材清单(供判断 need_research):\n" + _materials_block(values, limit=15))
elif pause_point == "section_help":
blocked = _blocked_block(values, interrupt_value)
if blocked:
parts.append(blocked)
parts.append("当前大纲:\n" + _outline_block(values))
else:
# 运行中 / 已结束:给全景概要,支撑 ask_meta / ask_content
parts.append("素材清单:\n" + _materials_block(values, limit=15))
outline = _outline_block(values)
if outline != "(尚无大纲)":
parts.append("大纲:\n" + outline)
draft = _draft_block(values, body_limit=2500)
if draft != "(尚无草稿)":
parts.append(draft)
review = _review_block(values)
if review != "(尚无编辑审核结果)":
parts.append("编辑审核:\n" + review)
return "\n\n".join(p for p in parts if p)
# ── 结果清洗 ──────────────────────────────────────────────────────────────────
def _clean_payload(raw: Any, action: str, values: dict, interrupt_value: dict | None) -> dict:
"""按动作白名单清洗 payload(键名统一驼峰,供前端直接喂 submitIntervention)。"""
p = raw if isinstance(raw, dict) else {}
out: dict[str, Any] = {}
def _str(key: str) -> str:
v = p.get(key)
return v.strip() if isinstance(v, str) else ""
if action == "confirm":
ids = p.get("approvedMaterialIds") or p.get("approved_material_ids")
if isinstance(ids, list) and ids:
known = {str(m.get("id")) for m in ((values.get("material_package") or {}).get("materials") or [])}
kept = [str(i) for i in ids if not known or str(i) in known]
if kept:
out["approvedMaterialIds"] = kept
elif action == "re_search":
query = _str("userQuery") or _str("user_query")
if query:
out["userQuery"] = query
out["approvedMaterialIds"] = []
elif action == "re_outline":
feedback = _str("outlineFeedback") or _str("outline_feedback")
if feedback:
out["outlineFeedback"] = feedback
elif action in ("user_revise", "to_editor", "accept_review"):
notes = _str("userRevisionNotes") or _str("user_revision_notes")
if notes:
out["userRevisionNotes"] = notes
indices = p.get("selectedIssueIndices") or p.get("selected_issue_indices")
if isinstance(indices, list):
review = values.get("review_result") or {}
total = len(review.get("revision_notes") or review.get("revisionNotes") or [])
cleaned = sorted({int(i) for i in indices if isinstance(i, (int, float)) and 0 <= int(i) < max(total, 0)})
if cleaned:
out["selectedIssueIndices"] = cleaned
# user_revise 必须有意见原文,没有就说明 LLM 输出不完整 → 由上层降级 clarify
elif action == "force_finalize":
out["overrideVerdict"] = True
elif action == "section_help":
blocked = (interrupt_value or {}).get("blocked_sections") or values.get("blocked_sections") or []
blocked_titles = [
str(b.get("section_title") or b.get("sectionTitle") or "") for b in blocked
]
raw_decisions = p.get("sectionDecisions") or p.get("section_decisions") or []
by_title: dict[str, str] = {}
for d in raw_decisions if isinstance(raw_decisions, list) else []:
if not isinstance(d, dict):
continue
title = str(d.get("sectionTitle") or d.get("section_title") or "")
decision = str(d.get("decision") or "")
if title and decision in _SECTION_DECISIONS:
by_title[title] = decision
# 覆盖全部受阻章节;LLM 漏掉的按多数倾向补齐,无倾向用 loose(与后台挂起默认一致)
majority = "loose"
if by_title:
counts: dict[str, int] = {}
for v in by_title.values():
counts[v] = counts.get(v, 0) + 1
majority = max(counts, key=lambda k: counts[k])
out["sectionDecisions"] = [
{"sectionTitle": t, "decision": by_title.get(t, majority)} for t in blocked_titles if t
]
return out
def normalize_intent_result(raw: dict, pause_point: str | None, values: dict, interrupt_value: dict | None = None) -> dict:
"""LLM 原始输出 → 安全的意图契约(动作白名单 / 置信度门槛 / payload 清洗)。"""
intent = str(raw.get("intent") or "unknown").strip() or "unknown"
action = raw.get("action")
action = action.strip() if isinstance(action, str) and action.strip() else None
answer = str(raw.get("answer") or "").strip()
clarify = str(raw.get("clarify") or "").strip()
need_research = bool(raw.get("need_research"))
research_query = str(raw.get("research_query") or "").strip()
try:
confidence = max(0.0, min(1.0, float(raw.get("confidence") or 0.0)))
except (TypeError, ValueError):
confidence = 0.0
def _clarified(message: str) -> dict:
return {
"intent": intent if intent != "unknown" else "clarify",
"pause_point": pause_point,
"action": None,
"payload": {},
"need_research": need_research,
"research_query": research_query,
"answer": answer,
"confidence": confidence,
"clarify": clarify or message,
}
# clarify 非空 / 问答类 → 不执行动作
if clarify:
return _clarified(clarify)
if action is None:
return {
"intent": intent,
"pause_point": pause_point,
"action": None,
"payload": {},
"need_research": need_research,
"research_query": research_query,
"answer": answer,
"confidence": confidence,
"clarify": "",
}
# 无暂停点:图没有可 resume 的 interrupt,任何动作都执行不了
allowed = ALLOWED_ACTIONS.get(pause_point or "")
if not allowed:
return _clarified("当前流程正在自动执行或已结束,没有等待确认的步骤,暂时不能执行该操作。")
if action not in allowed:
return _clarified(
f"这个操作在当前阶段做不了(可用:{'、'.join(sorted(allowed))})。请换一种说法,或等流程走到对应阶段再提。"
)
payload = _clean_payload(raw.get("payload"), action, values, interrupt_value)
# user_revise 没带意见原文 = 输出不完整,宁可反问
if action == "user_revise" and not payload.get("userRevisionNotes"):
return _clarified("你希望怎么修改草稿?请具体说明(例如:第三段太啰嗦,精简一下)。")
# 高代价动作置信度门槛
is_high_cost = action in ("finalize", "force_finalize") or (
action == "re_search" and not payload.get("userQuery")
)
threshold = HIGH_COST_CONFIDENCE if is_high_cost else ACTION_CONFIDENCE
if confidence < threshold:
hint = {
"finalize": "确认要定稿并结束本次写作吗?",
"force_finalize": "确认忽略编辑意见、强制定稿吗?",
"re_search": "重新搜索会重新生成检索词并覆盖现有素材,确认吗?(若只想补充素材,请描述想补充的内容)",
}.get(action, "我理解得不够确定,能再说得具体一点吗?")
return _clarified(hint)
return {
"intent": intent,
"pause_point": pause_point,
"action": action,
"payload": payload,
"need_research": need_research,
"research_query": research_query,
"answer": answer,
"confidence": confidence,
"clarify": "",
}
# ── LLM 调用 ──────────────────────────────────────────────────────────────────
def _build_messages(text: str, pause_point: str | None, values: dict, interrupt_value: dict | None):
from langchain_core.messages import HumanMessage, SystemMessage
stage_guide = STAGE_ACTION_GUIDES.get(pause_point or "", NO_PAUSE_GUIDE)
context = build_context_snapshot(values, pause_point, interrupt_value)
user = INTENT_ROUTER_USER_TEMPLATE.format(stage_guide=stage_guide, context=context, text=text.strip())
return [SystemMessage(content=INTENT_ROUTER_SYSTEM), HumanMessage(content=user)]
async def parse_user_intent(
*,
text: str,
pause_point: str | None,
values: dict,
interrupt_value: dict | None = None,
model_name: str | None = None,
model: Any | None = None,
) -> dict:
"""用户自由文本 → 意图契约 dict(snake_case 顶层字段 + 驼峰 payload)。
``model`` 参数仅供测试注入 fake;生产走 ``create_chat_model`` + 配置模型
容错链(与 intent_parser 同套 fallback_chain)。任何模型层失败都不抛给调用方,
降级为 clarify(意图解析是辅助能力,绝不能把写作页面搞挂)。
"""
from .nodes._utils import _content_to_text, parse_json
fallback = _fallback_intent()
rule = _rule_based_intent(text, pause_point)
if rule is not None:
return normalize_intent_result(rule, pause_point, values, interrupt_value)
messages = _build_messages(text, pause_point, values, interrupt_value)
raw_text = ""
if model is not None:
try:
resp = await model.ainvoke(messages)
raw_text = _content_to_text(getattr(resp, "content", "") or "")
except Exception:
logger.exception("intent_router: injected model failed")
else:
from deerflow.models import create_chat_model
from .nodes._model_fallback import classify_exception, fallback_chain
chain = fallback_chain((model_name or "").strip() or None) or [None]
for candidate in chain:
try:
m = create_chat_model(name=candidate) if candidate else create_chat_model()
resp = await m.ainvoke(messages)
raw_text = _content_to_text(getattr(resp, "content", "") or "")
break
except Exception as exc: # noqa: BLE001 — 换下一个模型继续
logger.warning(
"intent_router: model=%s failed (reason=%s): %s",
candidate, classify_exception(exc), exc,
)
continue
raw_text = _THINK_RE.sub("", raw_text or "").strip()
if not raw_text:
return normalize_intent_result(fallback, pause_point, values, interrupt_value)
parsed = parse_json(raw_text, fallback)
return normalize_intent_result(parsed, pause_point, values, interrupt_value)
async def stream_user_intent(
*,
text: str,
pause_point: str | None,
values: dict,
interrupt_value: dict | None = None,
model_name: str | None = None,
model: Any | None = None,
) -> AsyncIterator[dict]:
"""流式解析用户自由文本。
事件契约:
- ``{"type": "chunk", "chunk": "...", "is_thinking": bool}``
- ``{"type": "result", "result": normalized_intent}``
解析阶段仍以结构化 JSON 为最终产物;流式输出用于前端实时展示模型的
思考/解析过程。``<think>...</think>`` 内容和 provider reasoning 字段都会作为
``is_thinking=True`` 分流,正文 JSON 只参与最终解析。
"""
from .nodes._utils import ThinkTagParser, _content_to_text, parse_json, reasoning_delta
fallback = _fallback_intent()
rule = _rule_based_intent(text, pause_point)
if rule is not None:
yield {
"type": "result",
"result": normalize_intent_result(rule, pause_point, values, interrupt_value),
}
return
messages = _build_messages(text, pause_point, values, interrupt_value)
def content_events(parser: ThinkTagParser, raw_parts: list[str], delta: str) -> list[dict]:
events = []
for is_thinking, part in parser.feed(delta):
if not is_thinking:
raw_parts.append(part)
events.append({"type": "chunk", "chunk": part, "is_thinking": is_thinking})
return events
async def run_model(m: Any) -> AsyncIterator[dict]:
parser = ThinkTagParser()
raw_parts: list[str] = []
if hasattr(m, "astream"):
async for chunk in m.astream(messages):
reasoning = reasoning_delta(chunk)
if reasoning:
yield {"type": "chunk", "chunk": reasoning, "is_thinking": True}
content = _content_to_text(getattr(chunk, "content", "") or "")
if content:
for event in content_events(parser, raw_parts, content):
yield event
else:
resp = await m.ainvoke(messages)
content = _content_to_text(getattr(resp, "content", "") or "")
if content:
for event in content_events(parser, raw_parts, content):
yield event
yield {"type": "_raw_text", "raw_text": "".join(raw_parts)}
raw_text = ""
if model is not None:
try:
async for event in run_model(model):
if event["type"] == "_raw_text":
raw_text = str(event.get("raw_text") or "")
else:
yield event
except Exception:
raw_text = ""
logger.exception("intent_router: injected stream model failed")
else:
from deerflow.models import create_chat_model
from .nodes._model_fallback import classify_exception, fallback_chain
chain = fallback_chain((model_name or "").strip() or None) or [None]
for candidate in chain:
try:
m = create_chat_model(name=candidate) if candidate else create_chat_model()
async for event in run_model(m):
if event["type"] == "_raw_text":
raw_text = str(event.get("raw_text") or "")
else:
yield event
break
except Exception as exc: # noqa: BLE001 — 换下一个模型继续
raw_text = ""
logger.warning(
"intent_router: stream model=%s failed (reason=%s): %s",
candidate, classify_exception(exc), exc,
)
continue
raw_text = _THINK_RE.sub("", raw_text or "").strip()
if not raw_text:
result = normalize_intent_result(fallback, pause_point, values, interrupt_value)
else:
parsed = parse_json(raw_text, fallback)
result = normalize_intent_result(parsed, pause_point, values, interrupt_value)
yield {"type": "result", "result": result}
@@ -0,0 +1,279 @@
"""AI 写作「内置功能型智能体」运行助手。
四个写作阶段(素材收集/大纲/写作/审核)的图节点在 ``config.yaml →
ai_writing.use_builtin_agents.<stage>`` 打开时,不再使用 ``prompts/*.py`` 的
硬编码提示词直调 LLM,而是改为:
1. 从 ``.deer-flow/agents/<agent-id>/`` 加载该内置 agent 的 **SOUL.md**
(人设 + 工作流 + 结构化输出契约)作为 system prompt;
2. 模型按 ``agent config.yaml 的 model > 节点显式回退模型 > state.model_name``
的优先级解析(admin 可在智能体管理页给某阶段单独配模型);
3. 流式调用该模型,chunk 通过调用方传入的回调透传到 LangGraph ``custom``
通道(前端时间线打字机不回归);
4. 按 SOUL 规定的 marker(如 ``[OUTLINE_READY]``)+ ```json``` 块解析结构化
输出,解析复用 ``_utils.parse_json`` 多级容错。
设计取舍(对应 ai-writing-内置智能体改造.md §3.2 / §7):
- **编排控制权留在节点**:writer 的逐章循环、researcher 的检索编排、editor 的
三维度循环都不交给 agent——agent 只承担「单次结构化产出」,这样干预点/逐章
流式/严格模式求助逻辑全部原样保留。
- **不经过 lead agent 运行时**:本模块位于 harness 层,不能 import ``app.*``
(intent.py 的 loopback 机制在 app 层),也无需为单轮结构化调用付出
thread/checkpointer/中间件链的成本。SOUL + per-agent 模型已覆盖本场景的
可配置性诉求;researcher 的「挂载技能」(Phase 3)再考虑接入完整运行时。
- **agent 目录缺失时抛 ``WritingAgentUnavailable``**:由节点捕获后回退旧的
硬编码 prompt 路径,种子器(app 层 ``_ai_writing_seed.py``)失败不阻断写作。
"""
from __future__ import annotations
import logging
import re
from collections.abc import Callable
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from ._utils import ThinkTagParser, _content_to_text, parse_json, reasoning_delta
logger = logging.getLogger(__name__)
# ── 内置写作 agent 的稳定 id(与 app 层种子器 _ai_writing_seed.py 对齐)──────────
RESEARCHER_AGENT_ID = "ai-writing-researcher"
OUTLINER_AGENT_ID = "ai-writing-outliner"
WRITER_AGENT_ID = "ai-writing-writer"
EDITOR_AGENT_ID = "ai-writing-editor"
# ── SOUL 规定的结构化输出 marker(契约见各 agent 的 SOUL.md)─────────────────────
KEYWORDS_READY_MARKER = "[KEYWORDS_READY]"
MATERIALS_RANKED_MARKER = "[MATERIALS_RANKED]"
OUTLINE_READY_MARKER = "[OUTLINE_READY]"
REVIEW_READY_MARKER = "[REVIEW_READY]"
# flag 名(config.yaml ai_writing.use_builtin_agents.<stage>)→ agent id
STAGE_AGENT_IDS = {
"researcher": RESEARCHER_AGENT_ID,
"outliner": OUTLINER_AGENT_ID,
"writer": WRITER_AGENT_ID,
"editor": EDITOR_AGENT_ID,
}
class WritingAgentUnavailable(RuntimeError):
"""内置写作 agent 的 SOUL.md 缺失/为空,无法按 agent 模式运行。
节点捕获后应回退到旧的硬编码 prompt 路径(等价于 flag 关闭),不让写作
流程因 agent 目录被删而中断。
"""
def use_builtin_agent(stage: str) -> bool:
"""读 ``config.yaml → ai_writing.use_builtin_agents.<stage>`` 开关。
缺失/非法一律视为 False(默认走旧节点逻辑)。config 带 mtime 热加载,
改完 config.yaml 新会话即生效。
"""
from ._utils import get_ai_writing_config
flags = get_ai_writing_config().get("use_builtin_agents")
if not isinstance(flags, dict):
return False
return bool(flags.get(stage, False))
def load_writing_agent(agent_id: str):
"""加载内置写作 agent 的 (config, soul);SOUL 缺失抛 WritingAgentUnavailable。"""
from deerflow.config.agents_config import load_agent_config, load_agent_soul
soul = load_agent_soul(agent_id)
if not soul:
raise WritingAgentUnavailable(
f"内置写作智能体 '{agent_id}' 的 SOUL.md 缺失或为空"
"(目录可能被删除,重启 Gateway 或重新打开写作页可自动补建)"
)
try:
agent_cfg = load_agent_config(agent_id)
except ValueError:
# config.yaml 解析失败不致命:SOUL 仍可用,模型回退节点/表单选择。
logger.warning("load_writing_agent: config.yaml of '%s' is invalid, ignoring", agent_id)
agent_cfg = None
return agent_cfg, soul
def agent_display_name(agent_id: str, default: str) -> str:
"""取 agent 的展示名(progress_events.agent_name 用),加载失败回退默认值。"""
try:
from deerflow.config.agents_config import load_agent_config
cfg = load_agent_config(agent_id)
name = (cfg.name or "").strip() if cfg else ""
return name or default
except Exception:
return default
def resolve_agent_model_name(
agent_cfg,
state: dict,
config: RunnableConfig,
*,
explicit_fallback: str | None = None,
strict: bool = True,
) -> str | None:
"""解析本次 agent 调用使用的模型名。
优先级:agent config.yaml 的 ``model`` > ``explicit_fallback``(节点显式
传入,如 researcher 的 keyword_model/rank_model)> ``state.model_name``
(用户写作表单选的主模型)> configurable.model_name。
全部为空时**不再抛错**(旧实现 strict=True 抛 ValueError 会把「未选模型」直接打成
草稿失败,且后续 pause_draft 还会因 current_draft 为空二次崩溃):统一返回 None,
由 create_chat_model 回退 config.yaml 的 ``models[0]``。``strict`` 仅用于区分日志
级别——大纲/写作/审核阶段缺模型属异常配置,记 warning,调用方据 None 向用户提示
「已用默认模型」。
"""
candidates = (
(getattr(agent_cfg, "model", None) or "") if agent_cfg else "",
explicit_fallback or "",
(state or {}).get("model_name") or "",
(config.get("configurable", {}) or {}).get("model_name") or "",
)
for name in candidates:
if isinstance(name, str) and name.strip():
return name.strip()
if strict:
logger.warning("写作模型未指定(state/configurable/agent.model 均为空),回退默认模型")
return None
def parse_marker_json(text: str, marker: str, fallback: dict) -> dict:
"""从 agent 输出中按「marker + ```json``` 块」契约解析 JSON,多级降级。
1. ``marker\\n```json {...} ``` ``(SOUL 规定的标准形态,正则仿
intent.py::_INTENT_READY_PATTERN);
2. marker 存在但没包代码块 → 取 marker 之后的全部文本交给 parse_json;
3. marker 缺失(弱模型漏输出)→ 整段文本交给 parse_json;
4. 全部失败 → fallback。
"""
if not text or not text.strip():
return fallback
pattern = re.compile(re.escape(marker) + r"\s*```(?:json)?\s*(\{.*?\})\s*```", re.DOTALL)
m = pattern.search(text)
if m:
result = parse_json(m.group(1), fallback)
if result is not fallback:
return result
idx = text.find(marker)
if idx != -1:
tail = text[idx + len(marker):]
result = parse_json(tail, fallback)
if result is not fallback:
return result
return parse_json(text, fallback)
async def stream_writing_agent(
*,
agent_id: str,
user_payload: str,
state: dict,
config: RunnableConfig,
on_text: Callable[[str, bool], None] | None = None,
explicit_model_fallback: str | None = None,
strict_model: bool = True,
disable_thinking: bool = False,
) -> str:
"""在「SOUL 作 system prompt + 单条 Human 输入」契约下流式运行一个写作 agent。
Args:
agent_id: 内置写作 agent id(STAGE_AGENT_IDS 的值之一)。
user_payload: 本阶段输入(意图/素材/大纲/草稿等拼成的一段文本)。
on_text: 每个流式片段回调 ``(text, is_thinking)``,调用方在回调里把
chunk 包装成本阶段的 custom 事件(outline_chunk / draft_chunk /
review_chunk ...)推给前端;None = 不透传(如 researcher 的辅助任务)。
explicit_model_fallback / strict_model: 见 resolve_agent_model_name。
disable_thinking: True 时强制关闭模型思考(force_disable_thinking),用于
素材收集/大纲整理这类不需要思考的阶段(GLM5 等爱出 <think>)。关不掉的
模型仍由下方 ThinkTagParser 把思考分流到思考框,不会泄进正文。
Returns:
累积的**正文**文本(<think> 思考与 reasoning_content 已剥离),供
parse_marker_json / 章节拼装使用。
Raises:
WritingAgentUnavailable: SOUL 缺失(调用方回退旧 prompt 路径)。
其余模型异常原样上抛,由调用方按既有 try/except 兜底成 status:error。
"""
agent_cfg, soul = load_writing_agent(agent_id)
model_name = resolve_agent_model_name(
agent_cfg, state, config,
explicit_fallback=explicit_model_fallback,
strict=strict_model,
)
from deerflow.models import create_chat_model
model = create_chat_model(name=model_name, force_disable_thinking=disable_thinking)
full_text = ""
parser = ThinkTagParser()
async for chunk in model.astream([
SystemMessage(content=soul),
HumanMessage(content=user_payload),
]):
# 推理模型的思考走 reasoning_content(content 为空):作为思考实时推送
reasoning = reasoning_delta(chunk)
if reasoning and on_text is not None:
on_text(reasoning, True)
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
if on_text is not None:
on_text(text, is_thinking)
return full_text
async def run_writing_agent(
*,
agent_id: str,
user_payload: str,
marker: str,
fallback: dict,
state: dict,
config: RunnableConfig,
on_text: Callable[[str, bool], None] | None = None,
explicit_model_fallback: str | None = None,
strict_model: bool = True,
disable_thinking: bool = False,
) -> dict:
"""跑一个写作 agent 并按 marker 契约解析其结构化输出(失败回 fallback)。
模型调用异常时与 ``_utils.llm_json`` 同口径:返回
``{**fallback, "_llm_error": str(e)}``,不上抛(SOUL 缺失除外——
WritingAgentUnavailable 原样上抛,由节点切回旧 prompt 路径)。
disable_thinking: 透传给 stream_writing_agent,强制关闭思考(见其文档)。
"""
try:
full_text = await stream_writing_agent(
agent_id=agent_id,
user_payload=user_payload,
state=state,
config=config,
on_text=on_text,
explicit_model_fallback=explicit_model_fallback,
strict_model=strict_model,
disable_thinking=disable_thinking,
)
except WritingAgentUnavailable:
raise
except Exception as e:
logger.error("run_writing_agent(%s) failed: %s", agent_id, e, exc_info=True)
return {**fallback, "_llm_error": str(e)}
return parse_marker_json(full_text, marker, fallback)
@@ -0,0 +1,197 @@
"""AI 写作模型自动容错(按 ``config.yaml models[]`` 顺序换下一个模型继续)。
与多智能体会商 ``app/gateway/roundtable_model_fallback.py`` 同思路,但**只放在 harness 层**
避免 ``app→harness`` 单向依赖被反向打破:
- ``fallback_chain(current)``:候选模型链 ``[当前, …其余]``(按 config.yaml 顺序,去重保序);
- ``classify_exception(exc)``:把异常归到一个用户可读的失败原因码;
- ``reason_text(reason)``:原因码 → 简短中文(用于「『X』模型 <原因>,已切换『Y』继续」);
- ``emit_model_switch_event(writer, ...)``:把 ``model_switch`` 推到 LangGraph custom 通道
供前端时间线展示;
- ``build_switch_progress_event(...)``:节点 return 的 ``progress_events`` 里同样塞一份
(走 updates 通道,前端 reducer 据此刷新缓冲并落到时间线)。
总开关 / 上限沿用会商的 env:
- ``ROUNDTABLE_MODEL_FALLBACK``:默认开;``0/false/off/no`` 关闭(链只含当前模型);
- ``ROUNDTABLE_MODEL_FALLBACK_MAX``:候选数上限(含当前),0/未设 = 不限。
放在 ai_writing 节点目录下而非 harness/agents/middlewares:本模块不是中间件,
且仅服务 ai_writing 的几个流式节点;如果未来圆桌也想下沉合并,再统一拎出去。
"""
from __future__ import annotations
import logging
import os
from typing import Any, Callable
logger = logging.getLogger(__name__)
_REASON_TEXT: dict[str, str] = {
"quota": "额度不足/账单异常",
"auth": "鉴权失败/无访问权限",
"busy": "服务繁忙",
"transient": "网络/连接异常",
"upstream": "上游响应异常",
"config": "模型未配置或配置异常",
"exception": "调用异常",
"generic": "调用失败",
}
def reason_text(reason: str | None) -> str:
"""原因码 → 简短中文(未知码 → 「调用失败」)。"""
if not reason:
return "调用失败"
return _REASON_TEXT.get(reason, "调用失败")
_QUOTA_PATTERNS = ("insufficient_quota", "quota", "billing", "credit", "payment",
"余额不足", "超出限额", "额度不足", "欠费")
_AUTH_PATTERNS = ("authentication", "unauthorized", "invalid api key", "invalid_api_key",
"permission", "forbidden", "access denied", "无权", "未授权")
_BUSY_PATTERNS = ("server busy", "temporarily unavailable", "try again later", "please retry",
"please try again", "overloaded", "high demand", "rate limit",
"负载较高", "服务繁忙", "稍后重试", "请稍后重试")
_UPSTREAM_PATTERNS = ("bad_response_status_code", "bad response status",
"expecting ',' delimiter", "expecting value", "expecting property name",
"unexpected character", "unterminated string", "jsondecodeerror")
_TRANSIENT_EXC_NAMES = {"APITimeoutError", "APIConnectionError", "InternalServerError",
"ReadError", "RemoteProtocolError", "ReadTimeout", "ConnectTimeout", "TimeoutError"}
def classify_exception(exc: BaseException) -> str:
"""异常 → 失败原因码(quota/auth/busy/transient/upstream/config/generic/exception)。
与 ``LLMErrorHandlingMiddleware._classify_error`` 同口径,简化版:不区分是否可重试
(ai_writing 的容错只换模型,不在同模型上重试)。``create_chat_model`` 抛
``ValueError("Model X not found in config")`` 这类配置缺失另归 ``config``。
"""
name = exc.__class__.__name__
detail = str(exc).lower()
if isinstance(exc, ValueError) and "not found in config" in detail:
return "config"
if any(p in detail for p in _QUOTA_PATTERNS):
return "quota"
if any(p in detail for p in _AUTH_PATTERNS):
return "auth"
if name in _TRANSIENT_EXC_NAMES:
return "transient"
if any(p in detail for p in _BUSY_PATTERNS):
return "busy"
if any(p in detail for p in _UPSTREAM_PATTERNS):
return "upstream"
return "exception"
def _fallback_enabled() -> bool:
raw = (os.getenv("ROUNDTABLE_MODEL_FALLBACK", "1") or "1").strip().lower()
return raw not in {"0", "false", "no", "off"}
def _max_attempts() -> int:
try:
return max(0, int(os.getenv("ROUNDTABLE_MODEL_FALLBACK_MAX", "0") or "0"))
except (TypeError, ValueError):
return 0
def _config_model_names() -> list[str]:
try:
from deerflow.config import get_app_config
cfg = get_app_config()
return [m.name for m in (cfg.models or []) if getattr(m, "name", None)]
except Exception: # noqa: BLE001 — 拿不到配置(测试桩)时退化为空
logger.debug("ai_writing fallback_chain: get_app_config().models unavailable", exc_info=True)
return []
def fallback_chain(current: str | None) -> list[str]:
"""``[当前模型, …config.yaml 其余模型]``(去重保序)。
- ``current`` 为空 → 链头落到 ``models[0]``;
- ``current`` 在配置内 → 排第一,余者按配置顺序补齐;
- ``current`` 不在配置内 → 仍排第一(让 ``create_chat_model`` 在第一轮按原行为抛,
之后再换模型),再补齐全部配置模型;
- 总开关关闭 → 只返回头一个;
- 拿不到配置 → ``[current]``(current 为空则空列表)。
"""
all_names = _config_model_names()
cur = (current or "").strip()
ordered: list[str] = []
if cur:
ordered.append(cur)
for n in all_names:
if n and n not in ordered:
ordered.append(n)
if not ordered:
return [cur] if cur else []
if not _fallback_enabled():
return ordered[:1]
cap = _max_attempts()
if cap > 0:
ordered = ordered[:cap]
return ordered
def build_switch_progress_event(
*,
agent_name: str,
stage: str,
failed_model: str,
next_model: str,
reason: str,
section_index: int | None = None,
section_title: str | None = None,
) -> dict:
"""构造一条 ``model_switch`` ``progress_event`` 字典(供节点 return 时塞进 ``progress_events`` 数组)。
``stage`` ∈ {intent, outline, draft, review}:前端 reducer 据此清掉对应阶段的流式缓冲,
避免半段输出被下一个模型的输出粘在一起。
"""
fm = (failed_model or "").strip() or "当前模型"
nm = (next_model or "").strip() or "下一个模型"
rt = reason_text(reason)
detail = f"「{agent_name}」所用模型「{fm}」{rt},已自动切换到「{nm}」继续。"
payload: dict[str, Any] = {
"type": "model_switch",
"agent_name": agent_name,
"title": "模型容错",
"detail": detail,
"message": detail,
"stage": stage,
"failed_model": fm,
"next_model": nm,
"reason": reason,
}
if section_index is not None:
payload["section_index"] = section_index
if section_title:
payload["section_title"] = section_title
return payload
def emit_model_switch_event(
writer: Callable[[dict], None] | None,
*,
agent_name: str,
stage: str,
failed_model: str,
next_model: str,
reason: str,
section_index: int | None = None,
section_title: str | None = None,
) -> None:
"""把 ``model_switch`` 事件推到 LangGraph custom 通道(前端 useStream onCustomEvent 收)。"""
if writer is None:
return
payload = build_switch_progress_event(
agent_name=agent_name, stage=stage,
failed_model=failed_model, next_model=next_model, reason=reason,
section_index=section_index, section_title=section_title,
)
try:
writer(payload)
except Exception: # noqa: BLE001 — writer 在无 runtime 时是 no-op,理论不抛
logger.debug("emit_model_switch_event: writer raised", exc_info=True)
@@ -0,0 +1,671 @@
"""像「智能体调用技能」那样用一个技能检索素材。
背景:素材收集专家(ai-writing-researcher)是内置智能体,但此前它「用技能检索」只是
拿技能的 ``description`` 拼一个 query 丢给通用 web/intranet 检索 provider——技能自己
SKILL.md 里写的检索说明 / 策略并没有真正跑起来,和真实智能体「读 SKILL.md → 按说明
调工具检索」的逻辑不一致。
本模块把两者对齐:把技能 **SKILL.md 全文**连同素材收集专家 SOUL 注入 system prompt,
给模型绑定一个 ``search`` 工具,跑一个**有界的工具调用循环**——模型按技能说明自行决定
检索词与轮次(就像智能体读了技能后驱动检索),我们直接**收割工具返回的 SearchResult**
作为素材(无需再从自由文本里抽取,检索 provider 的结果本就是结构化素材)。
仅在 ``config.yaml → ai_writing.researcher_skill_agent`` 打开时启用(默认 false,走旧的
description→检索 直连路径)。弱模型不会工具调用 / 检索失败时,调用方回退旧路径,保证
素材不为空。
"""
from __future__ import annotations
import asyncio
import logging
from langchain_core.runnables import RunnableConfig
from ._agent_runner import (
RESEARCHER_AGENT_ID,
WritingAgentUnavailable,
load_writing_agent,
resolve_agent_model_name,
)
from ._utils import get_ai_writing_config
logger = logging.getLogger(__name__)
# 工具调用循环上限(每轮 = 一次模型调用,可含多个 search 调用)。
_MAX_TURNS = 4
def use_skill_search_agent() -> bool:
"""读 ``config.yaml → ai_writing.researcher_skill_agent`` 开关(默认 false,mtime 热加载)。"""
cfg = get_ai_writing_config()
return bool(cfg.get("researcher_skill_agent", False)) if isinstance(cfg, dict) else False
# ── 用真实智能体运行时跑技能(和「别的智能体调用技能」完全一致)────────────────────
#
# 旧的 run_skill_search_agent 只给模型绑了一个写死路由到 DDG 的通用 search 工具,技能
# SKILL.md 里要用的真实工具(read_file / bash / 内网检索工具 / MCP)根本不存在,所以
# 内网技能跑不出东西。本函数改为复用 **SubagentExecutor**(与 lead agent / 子智能体同一套
# 运行时):加载技能 SKILL.md(skills 白名单)+ 全套工具 + 懒加载沙箱,让技能按其说明真正
# 检索,再让模型把检索到的真实素材按 JSON 契约输出,我们解析成结构化素材。
#
# 单次工具调用循环上限(防跑飞)。
_REAL_AGENT_MAX_TURNS = 16
# 真实智能体跑技能:整段运行(读 SKILL.md + 多轮工具调用)的超时上限,**硬编码 5 分钟**。
# 内网检索很慢、技能常做多次检索,单次直连检索的 120s 不够整段用;5 分钟足够整段跑完
# (含模型对超时检索词自行换简单词重试),不依赖 env(部署方不一定会配环境变量)。
_REAL_AGENT_TIMEOUT_SECONDS = 300
_MATERIAL_OUTPUT_CONTRACT = (
"你的任务:用上面挂载的检索技能(<skill> 里的 SKILL.md)按它的说明**实际执行检索**,"
"收集与「写作意图」相关的真实素材。\n"
"\n"
"【第一步 · 必须真正执行技能,绝不能跳过】\n"
"- 你**必须先实际调用工具去检索**,再谈输出。技能通常自带脚本——按 SKILL.md 的说明用 **bash** 运行它,"
"例如:`cd <技能目录> && python3 scripts/xxx.py \"检索词\"`(具体脚本名/参数以 SKILL.md 为准),"
"或调用它说明里的内网接口 / MCP 工具。\n"
"- **严禁不调用任何工具就直接输出 JSON**,更不许凭记忆编造素材。哪怕你“觉得”知道答案,也必须真的去检索。\n"
"- 对每个检索方向各执行一次;可多次调用工具覆盖不同角度。\n"
"- 某个检索词返回 0 条或报「请求超时」时**不要放弃**:换成更核心、更短的检索词再试一次"
"(去掉「竞选/诉讼/政策/动向」等后缀,只留核心实体,如「特朗普竞选」→「特朗普」)。\n"
"\n"
"【第二步 · 检索完成后再整理输出】\n"
"- 把工具**实际返回**的真实素材整理成一个 JSON 对象(不要解释、不要 markdown 代码块、用英文双引号):\n"
'{"materials": [{"title": "标题", "content": "素材正文摘录(尽量保留原文, <=500字)", "source": "来源", "url": "原文链接(可空)", "published_at": "日期(可空)"}]}\n'
"- content 必须来自工具实际返回的内容;只要有任何检索词拿到数据就**全部收下**,不要因别的检索词没结果而丢弃。\n"
"- 只有当你**确实执行了检索、且所有检索词(含简化重试)都没有结果**时,才输出 {\"materials\": []}。"
)
def _scan_balanced_json_objects(text: str) -> list:
"""从可能被**中间截断**的文本里扫出所有「括号平衡且完整」的 ``{...}`` 子串(含各嵌套层级)。
根因:bash 工具对超过 ~20000 字的输出做**中间截断**(插入「... [middle truncated …] ...」),
使整段大 JSON(如 count=30 的技能返回)无法解析;但被截断点**两侧的单条结果对象**通常仍是
完整合法的 JSON,可逐个抢救出来。带字符串状态机(正确处理引号内的 {}/转义),逐个返回闭合的
对象子串,调用方再逐个 json.loads + 字段识别。
"""
import json as _json
out: list = []
stack: list[int] = []
in_str = False
esc = False
for i, ch in enumerate(text):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
continue
if ch == '"':
in_str = True
elif ch == "{":
stack.append(i)
elif ch == "}":
if stack:
s = stack.pop()
frag = text[s : i + 1]
try:
parsed = _json.loads(frag)
except Exception: # noqa: BLE001
continue
if isinstance(parsed, dict):
out.append(parsed)
return out
def _describe_tool_output(raw: str, skill_name: str) -> str:
"""从单次技能输出里提炼一句步骤条文案:**检索词 + 本次命中条数**(用户要求实时显示每次拿到多少条)。
返回空串 = 这次工具输出不是可识别的检索结果(如 read_file 读 SKILL.md),不发步骤。
"""
import re as _re
from deerflow.runtime import references as _ref
if not isinstance(raw, str) or not raw.strip():
return ""
payload = _ref._parse_json_like(raw)
query = ""
if isinstance(payload, dict):
query = str(payload.get("query") or "").strip()
# 明确失败(超时/报错):也给一条「0 条 + 原因」,让用户看到这次没出数据
if payload.get("success") is False:
err = str(payload.get("error") or "").strip()
q = f"「{query}」" if query else ""
return f"技能「{skill_name}」检索{q}未获得数据(0 条){(':' + err) if err else ''}"
count: int | None = None
if isinstance(payload, dict) and isinstance(payload.get("count"), int):
count = payload["count"]
items = _ref._first_list(payload) if payload is not None else []
if count is None and items:
count = len(items)
if count is None:
# 整段没解析出来(最常见:bash 输出被中间截断)→ 从头部正则抢救 query/count,
# 再退化为「抢救出的完整记录对象」计数。
if not query:
m = _re.search(r'"query"\s*:\s*"([^"]{1,80})"', raw)
query = m.group(1).strip() if m else ""
m2 = _re.search(r'"count"\s*:\s*(\d+)', raw)
if m2:
count = int(m2.group(1))
else:
salvaged = _scan_balanced_json_objects(raw)
n = sum(1 for o in salvaged if o.get("content") or o.get("content_preview") or o.get("title") or o.get("m_title"))
count = n if n > 0 else None
if count is None:
return "" # 非检索类输出,不发步骤
q = f"「{query}」" if query else ""
return f"技能「{skill_name}」检索{q}获得 {count} 条数据"
def _harvest_tool_results(tool_outputs: list, skill_name: str, limit: int) -> list:
"""**直接从技能 stdout 收割真实检索结果**(不依赖模型最后的 JSON 汇总)。
**复用主智能体「参考文献」模式同一套久经考验的提取逻辑**(`deerflow.runtime.references`):
那套逻辑在 ChatPage/AgentChatPage 已 100% 稳定地把技能 JSON 解析成参考文献——它对结果列表
字段(results/data/items/documents/...)、单条字段(title/m_title、content/page_content/
content_preview/snippet/...、recUuid/uuid/docId/...)都做了超大并集兼容,并尊重每个技能的
展示配置。ai 写作直接复用它,确保和参考文献模式「解析能力完全一致」。
在此基础上再叠加两层本地容错:
- 跳过 ``success:false`` 的输出(某检索词超时不影响其它成功的);
- 整段 JSON 解析不出结果时(最常见:bash 输出被**中间截断**),退化为「逐个抢救完整的
记录对象」(`_scan_balanced_json_objects`),截断点两侧的单条记录仍能救回。
"""
from ..search.base import SearchResult
from deerflow.runtime import references as _ref
tool_context = {"skill_name": skill_name, "tool_name": skill_name}
harvested: list = []
seen: set[str] = set()
for raw in tool_outputs:
if not isinstance(raw, str):
continue
payload = _ref._parse_json_like(raw)
# 明确标记失败的(超时 / 报错)跳过,但不影响其它成功的输出
if isinstance(payload, dict) and payload.get("success") is False:
continue
items = _ref._first_list(payload) if payload is not None else []
if not items:
# 整段解析不出结果(bash 中间截断把大 JSON 剪断)→ 逐个抢救完整的记录对象
items = _scan_balanced_json_objects(raw)
for idx, it in enumerate(items):
if not isinstance(it, dict):
continue
# 用参考文献模式的归一化(含字段并集 + 每技能展示配置),与右侧参考文献完全一致
norm = _ref._normalize_reference_item(
it, len(harvested) + 1, payload=payload, tool_context=tool_context
)
if not norm:
continue
content = str(norm.get("content") or norm.get("snippet") or "").strip()
title = str(norm.get("title") or "").strip()
if not content and not title:
continue
raw_rec = norm.get("raw") if isinstance(norm.get("raw"), dict) else {}
rec = str(raw_rec.get("recUuid") or raw_rec.get("uuid") or raw_rec.get("docId") or "").strip()
url = str(norm.get("url") or "").strip()
key = url or rec or title
if key in seen:
continue
seen.add(key)
try:
score = float(norm.get("score"))
except (TypeError, ValueError):
score = 0.75
harvested.append(SearchResult(
title=title or "(无标题)",
content=content[:500],
source=str(norm.get("source") or skill_name).strip() or skill_name,
published_at=str(norm.get("time") or "").strip(),
url=url,
relevance_score=score or 0.75,
source_type="skill",
recUuid=rec,
))
if len(harvested) >= limit:
return harvested
return harvested
def _summarize_tool_args(args: dict) -> str:
"""把工具调用参数压成一句简短摘要,放进步骤条文案(取最能代表本次调用的字段)。"""
if isinstance(args, dict):
for key in ("command", "query", "path", "file_path", "pattern", "name", "input", "url"):
v = args.get(key)
if isinstance(v, str) and v.strip():
return v.strip()[:80]
try:
import json as _json
return _json.dumps(args, ensure_ascii=False)[:80]
except Exception: # noqa: BLE001
return str(args)[:80]
return str(args)[:80]
async def run_skill_via_real_agent(
*,
skill,
intent: str,
keywords: list[str],
user_query: str,
config: RunnableConfig,
state: dict,
model_name_fallback: str | None,
max_results: int,
timeout_s: int,
emit_query=None,
) -> tuple[list, str]:
"""用真实智能体运行时(SubagentExecutor)跑一个检索技能,收割结构化素材。
与「别的智能体调用技能」一致:技能 SKILL.md + 全套工具 + 沙箱都齐全,技能的真实检索
逻辑(读文件 / 调内网接口 / MCP)能真正执行。模型最终按 JSON 契约吐出素材,解析成
SearchResult。返回 ``(results, error_detail)``:results 为空且 error 非空 = 该技能失败
(researcher 据此回退直连检索)。
"""
from langchain_core.messages import AIMessage, ToolMessage
from deerflow.config import get_app_config
from deerflow.subagents.config import SubagentConfig
from deerflow.subagents.executor import SubagentExecutor
from deerflow.tools import get_available_tools
from ..search.base import SearchResult
from ._agent_runner import RESEARCHER_AGENT_ID, WritingAgentUnavailable, load_writing_agent
from ._utils import _content_to_text, parse_json
skill_name = getattr(skill, "name", "") or "技能"
try:
agent_cfg, soul = load_writing_agent(RESEARCHER_AGENT_ID)
except WritingAgentUnavailable:
agent_cfg, soul = None, ""
model_name = resolve_agent_model_name(
agent_cfg, state, config, explicit_fallback=model_name_fallback, strict=False
)
try:
app_config = get_app_config()
tools = get_available_tools(
model_name=model_name, subagent_enabled=False, include_mcp=True, app_config=app_config
)
except Exception as e: # noqa: BLE001
logger.warning("skill real-agent[%s]: build tools failed: %s", skill_name, e)
return [], f"工具初始化失败: {e}"
# 技能在容器内的目录:注入 SKILL.md 时模型只有内容、不知道脚本在哪,会用相对路径
# (python3 scripts/xxx.py)在错误的 CWD 下跑 → No such file。把绝对目录告诉它,让它
# 先 cd 进去再执行(与「别的智能体」里 skill_view/read_file 拿到 location 后的行为一致)。
try:
base_path = getattr(getattr(app_config, "skills", None), "container_path", None) or "/mnt/skills"
except Exception: # noqa: BLE001
base_path = "/mnt/skills"
try:
skill_dir = skill.get_container_path(base_path)
except Exception: # noqa: BLE001
skill_dir = ""
try:
skill_file_path = skill.get_container_file_path(base_path)
except Exception: # noqa: BLE001
skill_file_path = f"{skill_dir}/SKILL.md" if skill_dir else ""
skill_loc_hint = (
f"\n\n【技能目录(重要)】技能「{skill_name}」在容器内的目录是:{skill_dir}\n"
f"- 技能说明文件是:{skill_file_path}\n"
f"- 运行该技能自带的脚本时,**务必先 `cd {skill_dir}` 再执行**"
f"(例如 `cd {skill_dir} && python3 scripts/xxx.py ...`),或对脚本用绝对路径;\n"
"- **不要用相对路径**(如 `python3 scripts/xxx.py`),否则当前目录不对会报 No such file。"
) if skill_dir else ""
system_prompt = (soul + "\n\n" if soul else "") + _MATERIAL_OUTPUT_CONTRACT + skill_loc_hint
task_lines = [f"写作意图:{intent or '(无)'}"]
if user_query:
task_lines.append(f"用户补充检索意图:{user_query}")
if keywords:
task_lines.append(f"可参考的检索方向:{', '.join(keywords[:8])}")
task_lines.append(f"目标素材数量约 {max_results} 条。")
if skill_file_path or skill_dir:
task_lines.extend([
"",
"【必须使用技能(弱模型也必须遵守)】",
f"- 当前指定技能:{skill_name}",
f"- SKILL.md 路径:{skill_file_path or '(见上方 <skill> 内容)'}",
f"- 技能目录:{skill_dir or '(未知)'}",
"- 你的下一步必须先调用 `read_file` 读取这个 SKILL.md(即使上方已有技能摘要,也要读取完整说明),"
"再按 SKILL.md 的脚本/接口流程获取真实数据。",
"- 如果 SKILL.md 提到 `scripts/*.py`,必须调用 `bash` 实际运行脚本;优先使用 "
f"`cd {skill_dir or '<技能目录>'} && python scripts/xxx.py ...` 或 "
f"`cd {skill_dir or '<技能目录>'} && python3 scripts/xxx.py ...`。",
"- 禁止第一轮就直接输出 JSON;没有执行过 read_file 和技能要求的脚本/工具前,不能输出 `materials`。",
])
# 弱模型强提示:明确要求「先动手执行技能脚本」,避免它直接吐空 JSON 不检索。
task_lines.append(
f"现在请**立刻开始执行检索**:按上面挂载技能的 SKILL.md,用 bash 运行它的脚本"
f"(如 `cd {skill_dir or '<技能目录>'} && python3 scripts/...py \"检索词\"`)实际检索,"
"先执行工具拿到真实数据,再整理输出 JSON;不要不检索就直接输出。"
)
task = "\n".join(task_lines)
sub_cfg = SubagentConfig(
name=f"ai-writing-skill-{skill_name}",
description="AI 写作素材检索",
system_prompt=system_prompt,
tools=None, # 继承全套工具,技能按 SKILL.md 自行取用
disallowed_tools=["task"], # 素材检索不需要再派生子任务
skills=[skill_name], # 仅加载这个技能的 SKILL.md
model=model_name or "inherit",
max_turns=_REAL_AGENT_MAX_TURNS,
# 整段运行硬编码至少 5 分钟(_REAL_AGENT_TIMEOUT_SECONDS),内网慢检索不被过早切断;
# 调用方传入更大的 timeout_s 时以更大者为准。
timeout_seconds=max(timeout_s, _REAL_AGENT_TIMEOUT_SECONDS),
)
# 复用 SubagentExecutor 的 agent/state 构建(模型 + 中间件 + 沙箱 + 技能注入),但**不**走
# 它阻塞式的 execute()。
thread_id = (config.get("configurable") or {}).get("thread_id")
try:
executor = SubagentExecutor(
config=sub_cfg, tools=tools, app_config=app_config,
parent_model=model_name, thread_id=thread_id,
)
agent = executor._create_agent()
init_state = await executor._build_initial_state(task)
except Exception as e: # noqa: BLE001
logger.warning("skill real-agent[%s]: init failed: %s", skill_name, e)
return [], f"运行时初始化失败: {e}"
# recursion_limit 计的是 graph 超级步(每个「模型→工具」回合≈2 步),不能直接等于 max_turns,
# 否则模型做了 N 个检索词后还没来得及写最终汇总就被 GraphRecursionError 截断(实测 10 个
# 检索词≈20 步 > 16,结果汇总丢失)。给到 ~2×turns + 余量,让模型正常情况下能写完汇总。
run_config: dict = {
"recursion_limit": _REAL_AGENT_MAX_TURNS * 2 + 4,
"configurable": {"agent_id": RESEARCHER_AGENT_ID},
}
run_context: dict = {"agent_id": RESEARCHER_AGENT_ID, "agent_name": RESEARCHER_AGENT_ID}
if thread_id:
run_config["configurable"]["thread_id"] = thread_id
run_context["thread_id"] = thread_id
if app_config is not None:
run_context["app_config"] = app_config
# 首步:技能开始(SKILL.md 已注入,给一条起始进度)
if emit_query:
emit_query(f"读取技能「{skill_name}」的 SKILL.md,开始执行检索…")
# ── 实时步骤的关键 ──
# 嵌套 agent.astream 跑在**后台任务**里,只把工具调用塞进队列;真正的 emit_query(writer)
# 由本协程(researcher 节点自身的协程)从队列里取出来调——和 draft_chunk 同一上下文。
# 这样 custom 事件能被 LangGraph **实时**刷给前端 SSE;若在嵌套 astream 里直接 emit,
# 事件会被攒到整段跑完才一次性吐出(后端在跑、前端却一直 loading)。
final_text = ""
# 技能每次工具调用的 stdout(如 search.py 打印的 {success,results} JSON),用于**直接收割**
# 真实检索结果,不依赖模型最后是否把它们汇总进 {materials}。
tool_outputs: list[str] = []
seen_msg_ids: set[str] = set()
step_queue: asyncio.Queue = asyncio.Queue()
async def _drive() -> None:
nonlocal final_text
reached_limit = False
try:
async for chunk in agent.astream(
init_state, config=run_config, context=run_context, stream_mode="values"
):
for m in chunk.get("messages") or []:
mid = getattr(m, "id", None)
if not mid or mid in seen_msg_ids:
continue
seen_msg_ids.add(mid)
for tc in (getattr(m, "tool_calls", None) or []):
tname = (tc.get("name") or "").strip() or "工具"
step_queue.put_nowait(
f"技能「{skill_name}」调用 {tname}:{_summarize_tool_args(tc.get('args') or {})}"
)
if isinstance(m, AIMessage):
text = _content_to_text(m.content)
if text.strip():
final_text = text
elif isinstance(m, ToolMessage):
out = _content_to_text(m.content)
if out.strip():
tool_outputs.append(out)
# 实时步骤条:这次检索拿到多少条数据(含失败/截断的诚实计数)
desc = _describe_tool_output(out, skill_name)
if desc:
step_queue.put_nowait(desc)
# **早停**:已收割素材达上限就停止驱动模型——否则弱模型会无限换检索词
# (步骤条爆 100+ 条、素材远超上限)。停掉嵌套 astream 即不再检索。
if max_results and len(_harvest_tool_results(tool_outputs, skill_name, max_results)) >= max_results:
step_queue.put_nowait(f"已获取 {max_results} 条素材,达到上限,停止本技能检索")
reached_limit = True
break
if reached_limit:
break
finally:
step_queue.put_nowait(None) # sentinel:跑完/出错都让 pump 收尾
task = asyncio.create_task(_drive())
async def _pump() -> None:
while True:
item = await step_queue.get()
if item is None:
break
if emit_query:
emit_query(item) # 本协程上下文调用 writer → custom 事件实时刷给前端
def _finalize() -> list:
"""把「模型最终汇总的 materials」与「技能 stdout 直接收割的结果」合并去重。
**关键**:无论本次运行是正常结束、超时、还是抛异常,只要已经收到过技能的工具输出,
就必须把这些真实结果收割下来——绝不能因为模型还没来得及汇总、或整段被切断,就把已经
拿到的数据整段丢掉(用户实测:技能明明检到了 30+ 条,却因没汇总而全丢)。
"""
# 1) 模型最终汇总的 materials(它可能已按相关度筛选/去重)
model_results: list = []
parsed = parse_json(final_text or "", {"materials": []})
raw_materials = parsed.get("materials")
if isinstance(raw_materials, list):
for m in raw_materials:
if not isinstance(m, dict):
continue
content = str(m.get("content") or "").strip()
title = str(m.get("title") or "").strip()
if not content and not title:
continue
model_results.append(SearchResult(
title=title or "(无标题)",
content=content[:500],
source=str(m.get("source") or skill_name).strip() or skill_name,
published_at=str(m.get("published_at") or "").strip(),
url=str(m.get("url") or "").strip(),
relevance_score=0.8,
source_type="skill",
))
# 2) **直接从技能 stdout 收割真实检索结果**——哪怕模型最后没汇总、或别的检索词超时,
# 成功检索词拿回的数据也照单全收。
harvested = _harvest_tool_results(tool_outputs, skill_name, max_results)
# 3) 合并去重(模型汇总优先、技能原始结果补齐),按 url/recUuid/title 去重,截断到上限。
merged: list = []
seen_keys: set[str] = set()
for r in model_results + harvested:
key = (r.url or "").strip() or (r.recUuid or "").strip() or (r.title or "").strip()
if key and key in seen_keys:
continue
if key:
seen_keys.add(key)
merged.append(r)
if len(merged) >= max_results:
break
return merged
try:
await asyncio.wait_for(_pump(), timeout=max(timeout_s, _REAL_AGENT_TIMEOUT_SECONDS))
except asyncio.TimeoutError:
task.cancel()
# 超时也要收割已拿到的技能数据:有就返回(无错误),实在没有才报超时。
salvaged = _finalize()
if salvaged:
logger.info("skill real-agent[%s]: timed out but salvaged %d results", skill_name, len(salvaged))
return salvaged, ""
return [], f"技能检索超时(>{max(timeout_s, _REAL_AGENT_TIMEOUT_SECONDS)}s)"
# pump 正常结束(收到 sentinel)后等后台任务收尾,拿 final_text / 抛出的异常
try:
await task
except Exception as e: # noqa: BLE001
logger.warning("skill real-agent[%s]: astream failed: %s", skill_name, e, exc_info=True)
# 递归上限 / 中途异常同样要收割已拿到的技能数据,不整段丢。
salvaged = _finalize()
if salvaged:
logger.info("skill real-agent[%s]: errored but salvaged %d results", skill_name, len(salvaged))
return salvaged, ""
return [], f"技能检索失败: {e}"
return _finalize(), ""
def _read_skill_body(skill) -> str:
"""读技能 SKILL.md 全文;失败回退 name+description。"""
try:
return skill.skill_file.read_text(encoding="utf-8")
except Exception: # noqa: BLE001
return f"# 技能:{getattr(skill, 'name', '')}\n{getattr(skill, 'description', '') or ''}"
async def run_skill_search_agent(
*,
skill,
intent: str,
keywords: list[str],
user_query: str,
config: RunnableConfig,
state: dict,
model_name_fallback: str | None,
max_results: int,
timeout_s: int,
emit_query=None,
) -> tuple[list, str]:
"""像智能体一样按技能 SKILL.md 检索素材。
Returns ``(results, error_detail)``:results 为收割到的 SearchResult 列表(调用方再
去全局去重/合并);error_detail 非空且 results 为空 = 该技能整体失败(触发兜底)。
模型不支持工具调用 / 始终不发起检索时返回 ``([], "")``,调用方据此回退旧检索路径。
"""
from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage
from langchain_core.tools import tool
from ..search import get_search_provider
skill_name = getattr(skill, "name", "") or "技能"
skill_body = _read_skill_body(skill)
try:
agent_cfg, soul = load_writing_agent(RESEARCHER_AGENT_ID)
except WritingAgentUnavailable:
agent_cfg, soul = None, ""
model_name = resolve_agent_model_name(
agent_cfg, state, config, explicit_fallback=model_name_fallback, strict=False
)
from deerflow.models import create_chat_model
try:
model = create_chat_model(name=model_name)
except Exception as e: # noqa: BLE001
return [], f"模型创建失败: {e}"
@tool
def search(query: str) -> str: # noqa: ARG001 — 仅用于给模型生成 schema,真正检索在循环里执行
"""根据 query 检索素材。一次只传一个检索词;可多次调用以覆盖不同角度。"""
return ""
try:
model_tools = model.bind_tools([search])
except Exception as e: # noqa: BLE001 — 模型不支持工具调用
logger.info("skill agent: model lacks tool-calling, fallback. err=%s", e)
return [], ""
provider = get_search_provider(get_ai_writing_config())
system = (
(soul + "\n\n" if soul else "")
+ "你现在挂载了下面这个检索技能,请**严格按它的说明**来检索素材。\n"
"通过调用 search 工具执行检索(一次一个检索词,可多次调用覆盖不同角度/来源);\n"
"收集到足够素材后直接回复「检索完成」即可,不要编造任何内容。\n\n"
f"=== 技能:{skill_name} ===\n{skill_body}"
)
task_lines = [f"写作意图:{intent or '(无)'}"]
if user_query:
task_lines.append(f"用户补充:{user_query}")
if keywords:
task_lines.append(f"可参考的检索方向:{', '.join(keywords[:8])}")
task_lines.append(f"请按上面技能的说明检索相关素材(目标约 {max_results} 条)。")
messages: list = [SystemMessage(content=system), HumanMessage(content="\n".join(task_lines))]
results: list = []
seen_urls: set[str] = set()
last_error = ""
search_timeout = max(timeout_s, _REAL_AGENT_TIMEOUT_SECONDS)
for _turn in range(_MAX_TURNS):
try:
ai = await model_tools.ainvoke(messages)
except Exception as e: # noqa: BLE001
last_error = f"模型调用失败: {e}"
logger.warning("skill agent[%s] model invoke failed: %s", skill_name, e)
break
messages.append(ai)
tool_calls = getattr(ai, "tool_calls", None) or []
if not tool_calls:
break # 模型不再检索(回复「检索完成」或纯文本)
for tc in tool_calls:
tc_id = tc.get("id") or ""
query = ((tc.get("args") or {}).get("query") or "").strip()
if not query:
messages.append(ToolMessage(content="query 为空,已跳过", tool_call_id=tc_id))
continue
if emit_query:
emit_query(query)
try:
found = await asyncio.wait_for(
provider.search(query, max_results=max_results), timeout=search_timeout
)
except asyncio.TimeoutError:
last_error = f"检索超时(>{search_timeout}s)"
messages.append(ToolMessage(content=last_error, tool_call_id=tc_id))
continue
except Exception as e: # noqa: BLE001
last_error = str(e)
messages.append(ToolMessage(content=f"检索失败: {e}", tool_call_id=tc_id))
continue
added = 0
for r in found or []:
url = getattr(r, "url", None)
if url and url in seen_urls:
continue
if url:
seen_urls.add(url)
results.append(r)
added += 1
# 给模型一个简短回执,让它据此决定是否继续换角度检索。
sample = ";".join((getattr(r, "title", "") or "")[:40] for r in (found or [])[:5]) or "无结果"
messages.append(
ToolMessage(content=f"检索到 {added} 条新素材。标题样例:{sample}", tool_call_id=tc_id)
)
if len(results) >= max_results:
break
if not results and last_error:
return [], last_error
return results, ""
@@ -0,0 +1,341 @@
"""节点共用工具:JSON 解析容错、LLM 创建。
弱模型经常输出不规范 JSON(中文标点、结尾多余逗号、被 markdown 包裹、
夹带解释文字、嵌套对象)。parse_json 用多级降级策略尽量抢救出结构化结果。
"""
from __future__ import annotations
import json
import logging
import re
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
logger = logging.getLogger(__name__)
def get_ai_writing_config() -> dict:
"""读 ``config.yaml`` 的 ``ai_writing`` 段。
阶段 7 之前由路由层 ``_make_config`` 把这份 dict 注入到 ``configurable.ai_writing_config``
给节点使用。阶段 7 删冗余后 ``_make_config`` 和注入路径全部消失(前端 ``stream.submit``
的 config 只传 ``model_name``)—— 节点改成自己直接从 ``get_app_config()`` 读,跨边界
更干净,``config.yaml`` 改完也不用重启前端 / 重发起会话。
返回字段(按使用方):
- researcher:``keyword_model`` / ``rank_model`` / ``max_materials`` /
``search_provider`` 等
- editor:``pass_threshold``
"""
try:
from deerflow.config import get_app_config
aw = getattr(get_app_config(), "ai_writing", None)
if isinstance(aw, dict):
return aw
return dict(aw) if aw else {}
except Exception:
logger.exception("ai_writing: 读取 app config 失败,使用空配置")
return {}
def safe_get_stream_writer():
"""返回一个 stream writer callable;在没有 LangGraph runtime 上下文时退化成 no-op。
AI 写作节点用它把流式 chunk 推到 LangGraph 原生 ``custom`` 通道。
场景:
- LangGraph Server 路径(``client.runs.stream`` 订阅了 ``stream_mode=["custom", ...]``)
→ 真实 writer,事件透传给 SDK 消费方。
- 老 ``/start /stream /resume`` 路径(``graph.astream(stream_mode="updates")``)
→ 真实 writer 仍可调用,只是没人订阅 custom 通道,事件被静默丢弃。
这是阶段 2「硬切到 get_stream_writer」的预期行为:老前端 EventSource 不再收到
token-level chunk,但整体进度卡(draft_ready / review_ready 这些 state 级事件)
仍正常 —— 阶段 3 前端切到 useStream 后立刻补齐。
- 单测里直接调节点函数(无 LangGraph runtime) → 返回 no-op,调用方零分支。
"""
try:
from langgraph.config import get_stream_writer # 延迟 import,便于单测打补丁
return get_stream_writer()
except Exception:
return lambda _payload: None
def get_model(config: RunnableConfig, model_name: str | None = None, *, disable_thinking: bool = False):
"""创建对话模型。
model_name 显式传入时优先使用(如素材收集专家的检索词/排序专用快模型),
否则回退到 configurable.model_name(用户在写作表单里选的主模型)。
disable_thinking=True 时强制关闭模型的思考/推理(force_disable_thinking):
对 OpenAI 兼容网关注入 GLM ``thinking.type=disabled`` / Qwen·vLLM
``enable_thinking=False`` 三种禁用形态,用于素材收集、大纲整理这类不需要思考的
结构化任务(GLM5 等内网模型尤其爱出 <think>)。关不掉的模型由各调用方的
ThinkTagParser 兜底,照常把思考分流到思考框。
"""
from deerflow.models import create_chat_model
name = model_name or config.get("configurable", {}).get("model_name", "") or None
return create_chat_model(name=name, force_disable_thinking=disable_thinking)
def resolve_writing_model_name(config: RunnableConfig, state: dict) -> tuple[str | None, bool]:
"""解析大纲 / 写作 / 审核阶段使用的模型名,返回 ``(name, used_default)``。
优先级:``state['model_name']``(用户在表单选定,由 intent_parser 在首次
invocation 捕获并经 checkpoint 持久化)> ``configurable.model_name``(同一
invocation 内直跑、或前端在 resume 时一并回传的兜底)。
interrupt/resume 是新 invocation,其 config 默认不带原 model_name,所以正常情况
要从 state 读。两者皆空(历史会话 / 首轮捕获就为空 / 前端没传)时不再视为致命
错误,而是返回 ``(None, True)``:调用方据此回退 config.yaml 的 ``models[0]`` 并向
用户提示「未选模型,已用默认模型」,保证写作流程不被一个空模型名硬卡住。
"""
name = ((state or {}).get("model_name") or "").strip()
if not name:
name = (config.get("configurable", {}).get("model_name", "") or "").strip()
if name:
return name, False
logger.warning("写作模型未指定(state/configurable 均为空),回退默认模型")
return None, True
def get_writing_model(config: RunnableConfig, state: dict):
"""大纲 / 写作 / 审核:解析用户选定模型,缺失时回退默认模型(见 resolve_writing_model_name)。"""
name, _ = resolve_writing_model_name(config, state)
from deerflow.models import create_chat_model
return create_chat_model(name=name)
# 弱模型常把结构性标点写成中文全角符号,仅在常规解析失败后作为修复手段
_FULLWIDTH_FIX = {
"“": '"', # 左双引号 “
"”": '"', # 右双引号 ”
"‘": "'", # 左单引号 ‘
"’": "'", # 右单引号 ’
":": ":", # 全角冒号 :
",": ",", # 全角逗号 ,
"(": "(", # 全角左括号 (
")": ")", # 全角右括号 )
"{": "{", # 全角左花括号 {
"}": "}", # 全角右花括号 }
"[": "[", # 全角左方括号 [
"]": "]", # 全角右方括号 ]
"【": "[", # 黑方括号 【
"】": "]", # 黑方括号 】
}
def _extract_balanced(text: str) -> str | None:
"""从文本中提取第一个括号平衡的 {...} 块(支持嵌套,忽略字符串内的括号)。"""
start = text.find("{")
if start == -1:
return None
depth = 0
in_str = False
escape = False
for i in range(start, len(text)):
ch = text[i]
if escape:
escape = False
continue
if ch == "\\":
escape = True
continue
if ch == '"':
in_str = not in_str
continue
if in_str:
continue
if ch == "{":
depth += 1
elif ch == "}":
depth -= 1
if depth == 0:
return text[start:i + 1]
return None
def _repair_json(text: str) -> str:
"""尽力修复弱模型常见的 JSON 错误:全角标点、结尾多余逗号。"""
for bad, good in _FULLWIDTH_FIX.items():
text = text.replace(bad, good)
# 去掉对象/数组结尾多余的逗号: ,} 或 ,]
text = re.sub(r",(\s*[}\]])", r"\1", text)
return text
def _try_load(text: str) -> dict | None:
try:
result = json.loads(text)
except Exception:
return None
return result if isinstance(result, dict) else None
def parse_json(text: str, fallback: dict) -> dict:
"""从 LLM 响应中提取 JSON 对象,多级降级,失败时返回 fallback。"""
if not text or not text.strip():
return fallback
text = text.strip()
# 1. 直接解析
if (r := _try_load(text)) is not None:
return r
# 2. markdown 代码块内容
m = re.search(r"```(?:json)?\s*(.+?)\s*```", text, re.DOTALL)
if m:
fenced = m.group(1).strip()
if (r := _try_load(fenced)) is not None:
return r
text = fenced # 用代码块内容继续后续步骤
# 3. 平衡括号提取(处理夹带解释文字、嵌套对象的情况)
candidate = _extract_balanced(text)
if candidate:
if (r := _try_load(candidate)) is not None:
return r
# 4. 修复后再试
if (r := _try_load(_repair_json(candidate))) is not None:
return r
# 5. 整体修复后兜底
if (r := _try_load(_repair_json(text))) is not None:
return r
logger.warning("JSON parse failed, using fallback. raw=%r", text[:200])
return fallback
def reasoning_delta(chunk) -> str:
"""提取流式 chunk 的增量「推理内容」。
推理模型(deepseek-reasoner / GLM 等)会把思考过程放在
``additional_kwargs.reasoning_content`` 增量字段里,而 ``content`` 为空 ——
只读 content 的流式循环会把这些 chunk 全部跳过,前端就看不到任何实时输出。
各写作节点用本函数把推理增量当作 ``is_thinking=True`` 推给前端的思考框。
兼容不同 provider 的字段名:``reasoning_content``(主流)/ ``reasoning``。
"""
ak = getattr(chunk, "additional_kwargs", None) or {}
val = ak.get("reasoning_content") or ak.get("reasoning") or ""
return val if isinstance(val, str) else ""
def _content_to_text(content) -> str:
"""将 LLM 响应内容统一为字符串(部分模型返回结构化 content 块列表)。"""
if isinstance(content, str):
return content
if isinstance(content, list):
return "".join(
part.get("text", "") if isinstance(part, dict) else str(part)
for part in content
)
return str(content)
# 中文常见标点:参与「字数」统计,与 Word 字数统计 / 用户直觉口径对齐
_CJK_PUNCTUATION = ",。、;:?!“”‘’()《》【】「」『』〈〉—…·~"
def count_words(text: str) -> int:
"""统计中文语境下的「字数」。
口径:汉字逐字计 + 中文标点逐个计 + 连续数字/英文各算 1 字。
不计入空白、markdown 语法符号(# * - 等)与 ASCII 标点。
前后端共用同一口径(前端 utils/wordCount.ts 实现一致)。
"""
if not text:
return 0
cjk = len(re.findall(r"[一-鿿]", text))
cjk_punct = sum(1 for c in text if c in _CJK_PUNCTUATION)
alnum_runs = len(re.findall(r"[A-Za-z0-9]+", text))
return cjk + cjk_punct + alnum_runs
class ThinkTagParser:
"""流式 <think>...</think> 标签解析器。
模型可能在任意 chunk 边界截断标签,通过尾部缓冲处理跨 chunk 边界情况。
调用 feed(chunk) 返回 list[tuple[bool, str]],每项为 (is_thinking, text)。
"""
_OPEN_TAG = "<think>"
_CLOSE_TAG = "</think>"
def __init__(self) -> None:
self._in_think = False
self._buf = "" # 潜在标签的部分匹配缓冲
def feed(self, chunk: str) -> list[tuple[bool, str]]:
"""处理一个流式 chunk,返回 (is_thinking, text) 片段列表。"""
self._buf += chunk
result: list[tuple[bool, str]] = []
while self._buf:
if self._in_think:
tag = self._CLOSE_TAG
idx = self._buf.find(tag)
if idx != -1:
if idx > 0:
result.append((True, self._buf[:idx]))
self._buf = self._buf[idx + len(tag):]
self._in_think = False
else:
partial = self._partial_suffix(self._buf, tag)
if partial:
result.append((True, self._buf[:-partial]))
self._buf = self._buf[-partial:]
else:
result.append((True, self._buf))
self._buf = ""
break
else:
tag = self._OPEN_TAG
idx = self._buf.find(tag)
if idx != -1:
if idx > 0:
result.append((False, self._buf[:idx]))
self._buf = self._buf[idx + len(tag):]
self._in_think = True
else:
partial = self._partial_suffix(self._buf, tag)
if partial:
result.append((False, self._buf[:-partial]))
self._buf = self._buf[-partial:]
else:
result.append((False, self._buf))
self._buf = ""
break
return [(is_t, t) for (is_t, t) in result if t]
@staticmethod
def _partial_suffix(text: str, tag: str) -> int:
"""返回 text 尾部与 tag 前缀匹配的最长长度(>0 说明可能是部分标签)。"""
max_check = min(len(tag) - 1, len(text))
for length in range(max_check, 0, -1):
if tag.startswith(text[-length:]):
return length
return 0
async def llm_json(system: str, user: str, fallback: dict, config: RunnableConfig, model_name: str | None = None, *, disable_thinking: bool = False) -> dict:
"""调用 LLM,解析 JSON 输出,失败用 fallback。
model_name 可覆盖默认模型(如检索词/排序使用配置的专用快模型)。
disable_thinking=True 时强制关闭思考(见 get_model),用于检索词/素材排序这类
结构化抽取任务,省掉 GLM5 等模型的 <think> 思考开销。
"""
messages = [SystemMessage(content=system), HumanMessage(content=user)]
try:
# get_model 放进 try:模型名在 config.yaml 找不到时 create_chat_model 会抛
# ValueError,若留在 try 外会逐层上抛使整个图硬崩溃。
model = get_model(config, model_name=model_name, disable_thinking=disable_thinking)
resp = await model.ainvoke(messages)
return parse_json(_content_to_text(resp.content), fallback)
except Exception as e:
logger.error("llm_json failed: %s", e, exc_info=True)
return {**fallback, "_llm_error": str(e)}
@@ -0,0 +1,321 @@
"""编辑节点:三项独立 LLM 审查(事实/逻辑/语言),逐 token 流式推送以支持打字机效果。"""
from __future__ import annotations
import logging
from typing import Callable
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from ..state import AIWritingState, ReviewResult, ReviewIssue
from ..prompts.editor_prompts import (
EDITOR_SYSTEM, FACT_REVIEW_USER, LOGIC_REVIEW_USER, LANGUAGE_REVIEW_USER,
USER_FOCUS_BLOCK,
)
from ._agent_runner import (
EDITOR_AGENT_ID,
REVIEW_READY_MARKER,
WritingAgentUnavailable,
agent_display_name,
load_writing_agent,
resolve_agent_model_name,
run_writing_agent,
use_builtin_agent,
)
from ._model_fallback import (
build_switch_progress_event,
classify_exception,
emit_model_switch_event,
fallback_chain,
)
from ._utils import get_ai_writing_config, parse_json, resolve_writing_model_name, _content_to_text, reasoning_delta, ThinkTagParser, safe_get_stream_writer
logger = logging.getLogger(__name__)
_DEFAULT_PASS_THRESHOLD = 75
def _build_user_focus(state: AIWritingState) -> str:
"""从干预数据取用户在「编辑审核」时附带的修改意见,拼成注入审查提示词的关注块。
仅当用户点「让编辑继续审核」且填了意见(graph.py `to_editor` 分支 stash 的
``_editor_notes``)时返回非空块;否则返回空串,三维度审查保持原样。
"""
intervention = state.get("last_user_intervention") or {}
notes = (intervention.get("_editor_notes") or "").strip()
if not notes:
return ""
return USER_FOCUS_BLOCK.format(notes=notes)
def _materials_summary(pkg: dict) -> str:
lines = []
for m in (pkg.get("materials") or [])[:6]:
lines.append(f"[{m['id']}] {m['title']}: {m['content'][:200]}")
return "\n".join(lines) or "(无素材)"
def _parse_issues(raw_issues: list, category: str) -> list[ReviewIssue]:
issues = []
for item in (raw_issues or []):
issues.append(ReviewIssue(
category=category,
severity=item.get("severity", "minor"),
location=item.get("location", ""),
issue=item.get("issue", ""),
suggestion=item.get("suggestion", ""),
))
return issues
async def _stream_one_review(
model, user_prompt: str, category: str,
writer: Callable[[dict], None],
) -> str:
"""流式执行单项审查,逐 chunk 经 LangGraph custom 通道推送 review_chunk 事件,返回累积的正文文本(用于 JSON 解析)。"""
full_text = "" # 仅累积正文(非思考),供后续 JSON 解析
parser = ThinkTagParser()
async for chunk in model.astream([
SystemMessage(content=EDITOR_SYSTEM),
HumanMessage(content=user_prompt),
]):
# 推理模型的思考走 reasoning_content(content 为空):作为思考实时推送
reasoning = reasoning_delta(chunk)
if reasoning:
writer({"type": "review_chunk", "category": category, "text": reasoning, "is_thinking": True})
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
writer({
"type": "review_chunk",
"category": category,
"text": text,
"is_thinking": is_thinking,
})
return full_text
async def _save_review_to_repo(config: RunnableConfig, review: ReviewResult) -> None:
"""把 review_result 异步落到业务表(best-effort,写失败不影响流程)。
``user_id`` 走 ``resolve_user_id(AUTO)`` 读 contextvar(与 intent_parser 建行、
writer_draft 写草稿同套规则)。
"""
cfg = config.get("configurable", {}) or {}
thread_id = cfg.get("thread_id")
if not thread_id:
return
from deerflow.persistence.ai_writing_sessions import get_default_store
from deerflow.runtime.user_context import AUTO
repo = get_default_store()
if repo is None:
return
try:
await repo.update(
thread_id,
user_id=AUTO,
status="review_ready",
review_result=dict(review),
)
except Exception:
logger.exception("editor: save_review failed (non-fatal) thread_id=%s", thread_id)
async def editor_node(state: AIWritingState, config: RunnableConfig) -> dict:
draft = state.get("current_draft")
if not draft:
return {
"status": "error",
"progress_events": [{"type": "error", "agent_name": "编辑", "message": "草稿为空,无法审核"}],
}
article = draft["full_markdown"]
pkg = state.get("material_package") or {}
mats = _materials_summary(pkg)
cfg = config.get("configurable", {})
writer = safe_get_stream_writer()
# 阶段 7 后从 app config 直接读,不走 configurable 注入
ai_writing_config = get_ai_writing_config()
pass_threshold = int(ai_writing_config.get("pass_threshold", _DEFAULT_PASS_THRESHOLD))
# 用户在草稿确认时附带的修改意见 → 注入三维度审查,让编辑重点核查(空则不影响原审查)
user_focus = _build_user_focus(state)
REVIEW_TASKS = [
("fact", FACT_REVIEW_USER.format(materials_summary=mats, article=article, user_focus=user_focus)),
("logic", LOGIC_REVIEW_USER.format(article=article, user_focus=user_focus)),
("language", LANGUAGE_REVIEW_USER.format(article=article, user_focus=user_focus)),
]
# 内置 agent 模式(config.yaml ai_writing.use_builtin_agents.editor):
# 三维度循环仍由节点编排(review_chunk / review_item_done 流式形态不变),
# 每个维度跑一次 ai-writing-editor agent(SOUL 作 system prompt,输出
# [REVIEW_READY] + {"score","issues"})。agent 目录缺失则静默回退旧路径。
use_agent = use_builtin_agent("editor")
agent_label = "编辑"
model = None
if use_agent:
try:
agent_cfg, _soul = load_writing_agent(EDITOR_AGENT_ID)
# 模型守卫提前到循环外:模型名缺失/配错时与旧路径同样转成 status:error
resolve_agent_model_name(agent_cfg, state, config)
agent_label = agent_display_name(EDITOR_AGENT_ID, "编辑")
except WritingAgentUnavailable as e:
logger.warning("editor builtin agent unavailable, falling back to legacy prompts: %s", e)
use_agent = False
except Exception as e:
logger.error("editor agent model resolution failed: %s", e, exc_info=True)
return {
"status": "error",
"progress_events": [{
"type": "error", "agent_name": agent_label,
"title": "模型错误", "detail": str(e), "message": "审核失败",
}],
}
# 旧路径下模型由 fallback_chain 在每维度审查前按候选顺序解析;模型挂掉自动换下一个继续。
editor_chain: list[str] = []
current_model_name: str | None = None
if not use_agent:
initial_name, _ud = resolve_writing_model_name(config, state)
editor_chain = fallback_chain(initial_name)
current_model_name = editor_chain[0] if editor_chain else None
from deerflow.models import create_chat_model
results: dict[str, dict] = {}
review_errors: list[str] = [] # 分项审查的模型异常,供完成后非致命提示
switch_notices: list[dict] = [] # 模型容错切换记录,最终塞进 progress_events 走时间线
_CATEGORY_LABEL = {"fact": "事实性", "logic": "逻辑性", "language": "语言文字"}
for category, user_prompt in REVIEW_TASKS:
fallback = {"score": 80, "issues": []}
try:
if use_agent:
def _on_text(text: str, is_thinking: bool, _cat: str = category) -> None:
writer({"type": "review_chunk", "category": _cat, "text": text, "is_thinking": is_thinking})
res = await run_writing_agent(
agent_id=EDITOR_AGENT_ID,
user_payload=user_prompt,
marker=REVIEW_READY_MARKER,
fallback=fallback,
state=state,
config=config,
on_text=_on_text,
)
if res.get("_llm_error"):
review_errors.append(f"「{_CATEGORY_LABEL.get(category, category)}审查」{res['_llm_error']}")
else:
# 旧路径:按 fallback_chain 试候选模型,失败就换下一个继续本维度。
# 与 writer_draft 同思路:以「上一维度成功使用的模型」为头部。
dim_chain: list[str] = []
if current_model_name:
dim_chain.append(current_model_name)
for n in editor_chain:
if n and n not in dim_chain:
dim_chain.append(n)
if not dim_chain:
dim_chain = [None] # type: ignore[list-item]
full_text = ""
dim_succeeded = False
last_dim_exc: BaseException | None = None
for d_idx, candidate in enumerate(dim_chain):
try:
m = create_chat_model(name=candidate) if candidate else create_chat_model()
full_text = await _stream_one_review(m, user_prompt, category, writer)
dim_succeeded = True
current_model_name = candidate or current_model_name
break
except Exception as e:
last_dim_exc = e
reason = classify_exception(e)
logger.error(
"editor review [%s] failed on model=%s (reason=%s): %s",
category, candidate, reason, e, exc_info=True,
)
next_candidate = dim_chain[d_idx + 1] if d_idx + 1 < len(dim_chain) else None
if next_candidate:
emit_model_switch_event(
writer, agent_name=agent_label, stage="review",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
)
switch_notices.append(build_switch_progress_event(
agent_name=agent_label, stage="review",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
))
continue
if not dim_succeeded:
assert last_dim_exc is not None
raise last_dim_exc
res = parse_json(full_text, fallback)
except Exception as e:
logger.warning("editor review [%s] failed: %s", category, e)
res = fallback
review_errors.append(f"「{_CATEGORY_LABEL.get(category, category)}审查」{type(e).__name__}: {e}")
results[category] = res
# 这一项审查完成 —— 推送结构化结果(前端据此把流式文本替换为评分/意见)
issues = _parse_issues(res.get("issues", []), category)
writer({
"type": "review_item_done",
"category": category,
"score": int(res.get("score", 80)),
"issues": [dict(iss) for iss in issues],
})
# 汇总
fact_score = int(results["fact"].get("score", 80))
logic_score = int(results["logic"].get("score", 80))
lang_score = int(results["language"].get("score", 80))
overall_score = (fact_score + logic_score + lang_score) // 3
all_issues: list[ReviewIssue] = (
_parse_issues(results["fact"].get("issues", []), "fact") +
_parse_issues(results["logic"].get("issues", []), "logic") +
_parse_issues(results["language"].get("issues", []), "language")
)
all_issues.sort(key=lambda x: (0 if x["severity"] == "major" else 1))
verdict = "pass" if overall_score >= pass_threshold else "reject"
review = ReviewResult(
verdict=verdict,
fact_score=fact_score,
logic_score=logic_score,
language_score=lang_score,
overall_score=overall_score,
pass_threshold=pass_threshold,
revision_notes=all_issues,
)
# 阶段 2:节点内并存 DB 写入(路由层同样也写一遍,阶段 7 删冗余时移除路由那份)
await _save_review_to_repo(config, review)
# 分项审查出现模型异常时,以非致命 notice 提示用户,审核结论仍照常产出
notices: list[dict] = []
if review_errors:
notices.append({
"type": "notice",
"agent_name": agent_label,
"title": "模型错误",
"detail": "部分审查项调用失败,已按默认分兜底。原因:" + ";".join(review_errors[:3]),
})
return {
"review_result": review,
"progress_events": [
{"type": "step_start", "agent_name": agent_label, "message": "开始审核"},
*switch_notices,
*notices,
{
"type": "review_ready",
"agent_name": agent_label,
"message": f"审核完成,综合得分 {overall_score},结论:{'通过' if verdict == 'pass' else '打回修改'}",
},
],
}
@@ -0,0 +1,346 @@
"""意图解析节点:将用户自然语言意图结构化为写作配置。"""
from __future__ import annotations
import logging
import re
from langchain_core.runnables import RunnableConfig
from langchain_core.messages import HumanMessage, SystemMessage
from ..state import AIWritingState
from ._model_fallback import (
build_switch_progress_event,
classify_exception,
emit_model_switch_event,
fallback_chain,
)
from ._utils import (
ThinkTagParser,
_content_to_text,
parse_json,
reasoning_delta,
safe_get_stream_writer,
)
logger = logging.getLogger(__name__)
def _truncate_title(text: str, max_len: int = 50) -> str:
"""与老 /start 路由里 _truncate_title 行为一致:UTF 字符截断 + 省略号。"""
text = (text or "").strip()
if len(text) <= max_len:
return text
return text[:max_len].rstrip() + "…"
async def _upsert_business_row(configurable: dict, state: AIWritingState) -> None:
"""在 intent_parser 入口幂等创建 ai_writing_sessions 业务表行。
LangGraph Server 路径下没有 /start 路由建行,必须节点自建,否则列表页查不到、
transcript / draft / review 后续写入都会因 update 找不到行而静默丢数据。
resume 路径下 thread_id 已经有行,upsert_session 只刷新 updated_at。
user_id 走 ``resolve_user_id(AUTO)``:FastAPI 请求线程把它写到 contextvar,
asyncio.create_task 继承父任务的 context,所以这里能拿到当前用户;
contextvar 没设时(测试 / 离线场景)抛 RuntimeError,try/except 兜底跳过。
"""
from deerflow.persistence.ai_writing_sessions import get_default_store
from deerflow.runtime.user_context import AUTO
thread_id = configurable.get("thread_id")
if not thread_id:
return
repo = get_default_store()
if repo is None:
return
user_intent = (state.get("user_intent") or "").strip()
try:
await repo.upsert_session(
id=thread_id,
title=_truncate_title(user_intent) or "AI 写作",
user_intent=user_intent,
user_id=AUTO,
status="in_progress",
)
except Exception:
logger.exception("intent_parser: upsert_session failed (non-fatal) thread_id=%s", thread_id)
# 兜底类型列表,当 config 中未注入 valid_article_types 时使用
_DEFAULT_ARTICLE_TYPES: list[dict] = [
{"key": "news", "label": "新闻资讯"},
{"key": "analysis", "label": "分析报道"},
{"key": "feature", "label": "深度特稿"},
{"key": "report", "label": "调研报告"},
]
_SYSTEM_TEMPLATE = """你是一名写作助手。
你的任务:分析用户的写作意图,提取结构化的写作配置。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块。
- 必须使用英文双引号 "。
- article_type 只能是以下之一:{type_options}。
【完整示例】
输入意图:帮我写一篇面向行业专家的深度文章,分析今年新能源汽车出口为什么大涨,大概两千字
正确输出:
{{"article_type": "feature", "target_audience": "行业专家", "word_count_target": 2000, "refined_intent": "分析今年新能源汽车出口高速增长的原因"}}"""
_USER_TEMPLATE = """用户写作意图:{user_intent}
用户在表单中已指定写作配置(以下三项必须原样输出,不要自行修改):
- 文章类型(article_type):{preconfigured_article_type}
- 目标读者(target_audience):{preconfigured_audience}
- 目标字数(word_count_target):{preconfigured_word_count}
请输出以下 JSON,article_type / target_audience / word_count_target 必须与上述一致,只需根据用户意图精炼 refined_intent:
{{{{
"article_type": "{preconfigured_article_type}",
"target_audience": "{preconfigured_audience}",
"word_count_target": {preconfigured_word_count},
"refined_intent": "精炼后的写作意图(一句话)"
}}}}"""
def _build_type_options(types: list[dict]) -> str:
"""将类型列表格式化为提示词中的枚举说明,如 news(新闻资讯)/ analysis(分析报道)。"""
return " / ".join(f'{t["key"]}({t["label"]})' for t in types)
def _coerce_word_count(raw) -> int | None:
"""稳健地把模型返回的字数字段转成正整数;无法解析时返回 None。
弱模型(尤其老模型被陌生词带偏时)常返回「约800字」「两千」「800.0」
这类非纯数字形式,直接 int() 会抛 ValueError/TypeError 使整个图崩溃。
此处用「提取首个数字串」策略容错,解析不出就返回 None 让调用方保留默认值。
"""
if raw is None:
return None
if isinstance(raw, bool): # bool 是 int 子类,需先排除
return None
if isinstance(raw, (int, float)):
value = int(raw)
return value if value > 0 else None
if not isinstance(raw, str):
# dict / list 等结构化类型:str() 化后可能误含数字,直接判为无法解析
return None
m = re.search(r"\d[\d,]*", raw)
if not m:
return None
try:
value = int(m.group().replace(",", ""))
except ValueError:
return None
return value if value > 0 else None
def _resolve_intent_fields(
state: AIWritingState,
result: dict,
fallback_result: dict,
valid_keys: list[str],
default_key: str,
) -> tuple[str, str, int, str]:
"""合并 LLM 解析结果与用户表单预填字段;预填字段优先(见 AI_WRITING_BACKEND_DEV_ZH §intent_parser)。"""
fallback_type = fallback_result["article_type"]
if fallback_type not in valid_keys:
fallback_type = default_key
raw_type = result.get("article_type", "")
llm_type = raw_type if raw_type in valid_keys else fallback_type
preconfigured_type = (state.get("article_type") or "").strip()
if preconfigured_type:
# 用户/配置助手已明确指定文章类型(含**列表外的自定义/新类型**)→ 原样尊重,
# 不再因不在默认表里被丢弃回退成默认(否则自定义/新类型在写作时会被还原成默认)。
final_article_type = preconfigured_type
else:
final_article_type = llm_type
preconfigured_audience = (state.get("target_audience") or "").strip()
if preconfigured_audience:
final_target_audience = preconfigured_audience
else:
final_target_audience = result.get("target_audience") or fallback_result["target_audience"]
preconfigured_wc = state.get("word_count_target")
if isinstance(preconfigured_wc, int) and preconfigured_wc > 0:
final_word_count = preconfigured_wc
else:
word_count = _coerce_word_count(result.get("word_count_target"))
final_word_count = word_count if word_count is not None else fallback_result["word_count_target"]
final_refined_intent = result.get("refined_intent") or state["user_intent"]
return final_article_type, final_target_audience, final_word_count, final_refined_intent
async def intent_parser_node(state: AIWritingState, config: RunnableConfig) -> dict:
# 从 configurable 读取动态类型列表,未配置时退回默认值
configurable = (config or {}).get("configurable", {})
valid_article_types: list[dict] = configurable.get("valid_article_types") or _DEFAULT_ARTICLE_TYPES
valid_keys: list[str] = [t["key"] for t in valid_article_types]
default_key: str = valid_keys[0] if valid_keys else "analysis"
# 业务表 upsert(LangGraph Server 路径下没有 /start 路由建行,节点入口自建;
# resume 时幂等不重复建。失败不阻断写作流程)。
await _upsert_business_row(configurable, state)
type_options = _build_type_options(valid_article_types)
system = _SYSTEM_TEMPLATE.format(type_options=type_options)
fallback_type = state.get("article_type", default_key)
if fallback_type not in valid_keys:
fallback_type = default_key
fallback_result = {
"article_type": fallback_type,
"target_audience": state.get("target_audience", "普通读者"),
"word_count_target": state.get("word_count_target", 800),
"refined_intent": state["user_intent"],
}
preconfigured_wc = fallback_result["word_count_target"]
if not isinstance(preconfigured_wc, int) or preconfigured_wc <= 0:
preconfigured_wc = 800
if state.get("skip_intent_parser"):
writer = safe_get_stream_writer()
final_article_type, final_target_audience, final_word_count, final_refined_intent = _resolve_intent_fields(
state, fallback_result, fallback_result, valid_keys, default_key
)
writer({
"type": "intent_ready",
"article_type": final_article_type,
"target_audience": final_target_audience,
"word_count_target": final_word_count,
"refined_intent": final_refined_intent,
})
progress_events = [{
"type": "step_done",
"agent_name": "系统",
"message": "意图解析完成(已使用已确认配置)",
}]
updates: dict = {
"status": "researching",
"progress_events": progress_events,
"article_type": final_article_type,
"target_audience": final_target_audience,
"word_count_target": final_word_count,
}
persisted_model = (configurable.get("model_name") or "").strip()
if persisted_model:
updates["model_name"] = persisted_model
if final_refined_intent != state["user_intent"]:
updates["user_intent"] = final_refined_intent
return updates
user = _USER_TEMPLATE.format(
user_intent=state["user_intent"],
preconfigured_article_type=fallback_type,
preconfigured_audience=fallback_result["target_audience"],
preconfigured_word_count=preconfigured_wc,
)
# 流式调用:与 writer_outline / writer_draft 同套机制 —— LLM 逐字吐出 JSON,
# 通过 ``intent_chunk`` 推给前端打字机;完成后 ``parse_json`` 解析结构化结果,
# 再通过 ``intent_ready`` 推一份结构化字段给前端结果卡片。
#
# 模型自动容错:失败时按 fallback_chain 顺序换下一个模型重试本环节。每次切换
# 都通过 ``model_switch`` custom 事件 + ``progress_events`` 同步告诉前端,前端
# 清掉本环节已累积的 intent_chunk 缓冲,避免半段输出和下个模型的输出拼接错乱。
writer = safe_get_stream_writer()
initial_model = (configurable.get("model_name") or "").strip() or None
chain = fallback_chain(initial_model)
progress_events: list[dict] = []
from deerflow.models import create_chat_model
full_text = ""
success_model: str | None = None
last_error: BaseException | None = None
for idx, candidate in enumerate(chain or [None]):
full_text = "" # 每次重试都从头累积,避免不同模型的输出粘在一起
parser = ThinkTagParser()
try:
model = create_chat_model(name=candidate) if candidate else create_chat_model()
async for chunk in model.astream(
[SystemMessage(content=system), HumanMessage(content=user)]
):
# 推理模型的思考走 reasoning_content(content 为空):作为思考实时推送
reasoning = reasoning_delta(chunk)
if reasoning:
writer({"type": "intent_chunk", "text": reasoning, "is_thinking": True})
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
writer({
"type": "intent_chunk",
"text": text,
"is_thinking": is_thinking,
})
success_model = candidate or ""
break
except Exception as exc:
last_error = exc
reason = classify_exception(exc)
logger.error(
"intent_parser streaming failed on model=%s (reason=%s): %s",
candidate, reason, exc, exc_info=True,
)
next_candidate = chain[idx + 1] if idx + 1 < len(chain) else None
if next_candidate:
emit_model_switch_event(
writer, agent_name="系统", stage="intent",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
)
progress_events.append(build_switch_progress_event(
agent_name="系统", stage="intent",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
))
continue
# 链尾仍失败:保留 fallback 默认值,向用户报一条非致命 notice,流程继续。
progress_events.append({
"type": "notice",
"agent_name": "系统",
"title": "模型错误",
"detail": (
f"意图解析失败,已按默认配置兜底。原因:{type(exc).__name__}: {exc}"
),
})
result = parse_json(full_text, fallback_result) if full_text else fallback_result
final_article_type, final_target_audience, final_word_count, final_refined_intent = _resolve_intent_fields(
state, result, fallback_result, valid_keys, default_key
)
# 推送结构化结果给前端 —— 结果卡片显示文章类型 / 目标读者 / 字数 / 精炼意图
writer({
"type": "intent_ready",
"article_type": final_article_type,
"target_audience": final_target_audience,
"word_count_target": final_word_count,
"refined_intent": final_refined_intent,
})
progress_events.append({"type": "step_done", "agent_name": "系统", "message": "意图解析完成"})
updates: dict = {"status": "researching", "progress_events": progress_events}
# 捕获用户表单选定的主模型进 state(仅本节点能可靠拿到 configurable.model_name —
# 它运行在首次 invocation;后续大纲/写作/审核在 resume 后跑,config 已不带它)。
# 大纲/写作/审核经 get_writing_model 严格读 state['model_name'],不回退默认。
# 容错切换后用实际成功的模型作为后续阶段起点,避免每个阶段都重复经历同一次失败。
persisted_model = (success_model or initial_model or "").strip()
if persisted_model:
updates["model_name"] = persisted_model
_ = last_error # 链尾失败已生成 notice,这里保留变量供调试时断点查看
updates["article_type"] = final_article_type
updates["target_audience"] = final_target_audience
updates["word_count_target"] = final_word_count
if final_refined_intent != state["user_intent"]:
updates["user_intent"] = final_refined_intent
return updates
@@ -0,0 +1,279 @@
"""样文仿写:分析用户上传/粘贴的样文,提取可复用的文风画像。"""
from __future__ import annotations
import json
import logging
import re
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from ..state import AIWritingState, SampleStyleProfile
from ._utils import (
ThinkTagParser,
_content_to_text,
count_words,
get_model,
parse_json,
reasoning_delta,
safe_get_stream_writer,
)
logger = logging.getLogger(__name__)
_MAX_SAMPLE_ANALYSIS_CHARS = 12000
SAMPLE_ANALYZE_SYSTEM = """你是一名资深中文编辑和文风分析师。
你的任务:阅读用户提供的样文,提取「可用于仿写的文风画像」,供后续写作模型模仿其结构、语气和表达节奏。
【重要边界】
- 你不是改写样文本身,而是分析它的写作风格。
- 不要复述样文的具体事实、数字、人名、机构名,除非用于概括文章结构。
- 后续写作必须避免直接照抄样文,因此你要明确指出哪些表达方式可以学、哪些原文内容不能复制。
【输出要求】
- 只输出一个 JSON 对象,不要解释文字,不要 markdown 代码块。
- 必须使用英文双引号。
- 字段结构:
{
"summary": "一句话概括样文风格",
"article_type_guess": "推测文章类型",
"tone": "语气/立场/情绪特征",
"structure": ["篇章结构特征1", "篇章结构特征2"],
"language_features": ["遣词造句特征1", "修辞/表达特征2"],
"sentence_style": "句式、长短句、节奏特征",
"opening_style": "开头方式",
"ending_style": "结尾方式",
"imitation_guidance": ["后续仿写应遵守的建议1", "建议2"],
"avoid_copying": ["不得复制的内容/风险1", "风险2"],
"sample_outline": ["样文结构骨架1", "样文结构骨架2"]
}"""
SAMPLE_ANALYZE_USER = """样文文件名:{filename}
样文字数:约 {word_count} 字
样文内容(可能已截断):
{sample_text}
请提取可用于后续仿写的文风画像,只输出 JSON。"""
def _is_imitate_mode(state: AIWritingState) -> bool:
mode = (state.get("writing_mode_type") or "").strip().lower()
return mode == "imitate"
def _compact_list(values: object, limit: int = 6) -> list[str]:
if not isinstance(values, list):
return []
out: list[str] = []
for item in values:
text = str(item or "").strip()
if text:
out.append(text[:120])
if len(out) >= limit:
break
return out
def _normalize_profile(raw: dict, sample_text: str) -> SampleStyleProfile:
"""规整 LLM 输出,避免缺字段影响后续提示词。"""
first_lines = [ln.strip() for ln in sample_text.splitlines() if ln.strip()][:5]
fallback_outline = first_lines or ["起承转合清晰", "围绕主题分段展开"]
profile: SampleStyleProfile = {
"summary": str(raw.get("summary") or "样文表达较为完整,结构清晰,适合提取篇章节奏与措辞习惯。")[:200],
"article_type_guess": str(raw.get("article_type_guess") or raw.get("articleTypeGuess") or "")[:80],
"tone": str(raw.get("tone") or "稳健、清晰")[:120],
"structure": _compact_list(raw.get("structure"), 8) or ["先交代背景或问题,再分层展开,最后收束观点。"],
"language_features": _compact_list(raw.get("language_features") or raw.get("languageFeatures"), 8) or ["表达相对凝练,注重段落之间的衔接。"],
"sentence_style": str(raw.get("sentence_style") or raw.get("sentenceStyle") or "长短句结合,段落节奏平稳。")[:160],
"opening_style": str(raw.get("opening_style") or raw.get("openingStyle") or "开头直接引入主题。")[:160],
"ending_style": str(raw.get("ending_style") or raw.get("endingStyle") or "结尾总结全文并给出判断或展望。")[:160],
"imitation_guidance": _compact_list(raw.get("imitation_guidance") or raw.get("imitationGuidance"), 8) or ["模仿篇章结构、语气和句式节奏,不搬运样文事实。"],
"avoid_copying": _compact_list(raw.get("avoid_copying") or raw.get("avoidCopying"), 8) or ["不得连续照抄样文原句或复用样文中的专有事实。"],
"sample_outline": _compact_list(raw.get("sample_outline") or raw.get("sampleOutline"), 10) or fallback_outline,
}
return profile
def _fallback_profile(sample_text: str) -> SampleStyleProfile:
"""模型失败时的确定性兜底画像。"""
paragraphs = [p.strip() for p in re.split(r"\n\s*\n+", sample_text) if p.strip()]
avg_len = round(sum(len(p) for p in paragraphs) / max(len(paragraphs), 1))
return {
"summary": "已根据样文段落和篇幅提取基础仿写约束。",
"article_type_guess": "",
"tone": "保持样文的正式程度和表达密度。",
"structure": [
f"样文约 {len(paragraphs)} 个自然段,平均每段约 {avg_len} 字。",
"仿写时保留相近的段落推进节奏。",
],
"language_features": ["保留样文的用词正式程度、连接方式和论述密度。"],
"sentence_style": "参照样文长短句比例,避免明显口语化或突兀转换。",
"opening_style": "参照样文开头的切入方式,但改写为新主题。",
"ending_style": "参照样文结尾的收束方式,形成新主题下的总结。",
"imitation_guidance": ["学习样文结构和语气,所有事实内容以用户新要求为准。"],
"avoid_copying": ["不要连续复用样文原句,不要照搬样文专有事实、案例和数据。"],
"sample_outline": [p[:80] for p in paragraphs[:8]] or ["围绕主题分层展开"],
}
def render_sample_style_section(state: AIWritingState) -> str:
"""把文风画像渲染成可注入大纲/写作提示词的约束片段。"""
if not _is_imitate_mode(state):
return ""
profile = state.get("sample_style_profile") or {}
if not profile:
return ""
strength = (state.get("imitate_strength") or "medium").strip().lower()
strength_label = {
"light": "轻度:只参考语气和部分表达节奏,结构可按新主题调整。",
"medium": "中度:同时参考语气、段落节奏和篇章推进方式。",
"strong": "高度:尽量贴近样文结构骨架、标题组织和表达密度,但仍不得照抄原文。",
}.get(strength, "中度:同时参考语气、段落节奏和篇章推进方式。")
preserve = "是" if state.get("preserve_sample_structure") else "否"
compact = {
"summary": profile.get("summary", ""),
"tone": profile.get("tone", ""),
"structure": profile.get("structure", []),
"language_features": profile.get("language_features", []),
"sentence_style": profile.get("sentence_style", ""),
"opening_style": profile.get("opening_style", ""),
"ending_style": profile.get("ending_style", ""),
"imitation_guidance": profile.get("imitation_guidance", []),
"avoid_copying": profile.get("avoid_copying", []),
"sample_outline": profile.get("sample_outline", []),
}
return (
"\n\n【样文仿写要求】\n"
f"- 仿写强度:{strength_label}\n"
f"- 是否尽量沿用样文结构:{preserve}\n"
"- 仿写目标:学习样文的篇章结构、语气、段落节奏、句式和表达密度;新文章主题、事实与论点必须服务用户的新要求。\n"
"- 严禁:不得连续照抄样文原句,不得搬运样文中的专有事实、数据、人物、机构或案例。\n"
"文风画像 JSON:\n"
f"{json.dumps(compact, ensure_ascii=False)}"
)
async def _stream_sample_analysis(
*,
filename: str,
sample_text: str,
clipped: str,
fallback: dict,
config: RunnableConfig,
model_name: str | None,
) -> dict:
writer = safe_get_stream_writer()
writer({
"type": "sample_chunk",
"agent_name": "样文分析师",
"text": (
f"读取样文《{filename}》,约 {count_words(sample_text)} 字;"
f"本轮提取前 {len(clipped)} 字用于文风画像。\n"
"正在识别文章类型、结构骨架、语气、句式节奏、仿写建议和避抄边界...\n\n"
),
"is_thinking": False,
})
messages = [
SystemMessage(content=SAMPLE_ANALYZE_SYSTEM),
HumanMessage(content=SAMPLE_ANALYZE_USER.format(
filename=filename,
word_count=count_words(sample_text),
sample_text=clipped,
)),
]
full_text = ""
try:
# Keep thinking enabled for the sample analyst. Reasoning models may
# stream it through additional_kwargs.reasoning_content, while some
# local models emit literal <think>...</think> in content; both paths
# are split below just like intent/outline/draft streaming.
model = get_model(config, model_name=model_name, disable_thinking=False)
parser = ThinkTagParser()
async for chunk in model.astream(messages):
reasoning = reasoning_delta(chunk)
if reasoning:
writer({
"type": "sample_chunk",
"agent_name": "样文分析师",
"text": reasoning,
"is_thinking": True,
})
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
writer({
"type": "sample_chunk",
"agent_name": "样文分析师",
"text": text,
"is_thinking": is_thinking,
})
return parse_json(full_text, fallback) if full_text.strip() else fallback
except Exception as exc:
logger.error("sample_analyzer streaming failed: %s", exc, exc_info=True)
writer({
"type": "sample_chunk",
"agent_name": "样文分析师",
"text": "\n样文分析模型异常,已改用基础画像兜底。\n",
"is_thinking": False,
})
return {**fallback, "_llm_error": str(exc)}
async def sample_analyzer_node(state: AIWritingState, config: RunnableConfig) -> dict:
if not _is_imitate_mode(state):
return {}
sample_text = (state.get("sample_text") or "").strip()
filename = (state.get("sample_filename") or "粘贴文本").strip()
if not sample_text:
return {
"writing_mode_type": "normal",
"status": "researching",
"progress_events": [{
"type": "notice",
"agent_name": "系统",
"title": "样文为空",
"detail": "未收到可分析的样文内容,已按普通写作继续。",
}],
}
clipped = sample_text[:_MAX_SAMPLE_ANALYSIS_CHARS]
fallback = _fallback_profile(clipped)
configurable = (config or {}).get("configurable", {}) or {}
model_name = (state.get("model_name") or configurable.get("model_name") or "").strip() or None
raw = await _stream_sample_analysis(
filename=filename,
sample_text=sample_text,
clipped=clipped,
fallback=fallback,
config=config,
model_name=model_name,
)
profile = _normalize_profile(raw, clipped)
events = [
{"type": "step_start", "agent_name": "样文分析师", "message": "正在分析样文风格"},
{
"type": "sample_profile_ready",
"agent_name": "样文分析师",
"message": profile.get("summary") or "样文风格分析完成",
"sample_style_profile": profile,
},
]
if raw.get("_llm_error"):
events.append({
"type": "notice",
"agent_name": "样文分析师",
"title": "样文分析模型异常",
"detail": f"已使用基础画像兜底。原因:{raw['_llm_error']}",
})
return {
"sample_style_profile": profile,
"status": "researching",
"progress_events": events,
}
@@ -0,0 +1,530 @@
"""作家节点 Phase 1:生成文章大纲,支持流式 chunk 输出。"""
from __future__ import annotations
import json
import logging
import re
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from ..outline_parser import parse_user_outline
from ..prompts.writer_prompts import (
OUTLINE_NORMALIZE_SYSTEM,
OUTLINE_NORMALIZE_USER,
OUTLINE_REVISE_SYSTEM,
OUTLINE_REVISE_USER,
OUTLINE_SYSTEM,
OUTLINE_USER,
)
from ..state import AIWritingState, KeyPoint, Outline, OutlineSection
from ._agent_runner import (
OUTLINE_READY_MARKER,
OUTLINER_AGENT_ID,
WritingAgentUnavailable,
agent_display_name,
load_writing_agent,
parse_marker_json,
stream_writing_agent,
use_builtin_agent,
)
from ._model_fallback import (
build_switch_progress_event,
classify_exception,
emit_model_switch_event,
fallback_chain,
)
from ._utils import ThinkTagParser, _content_to_text, parse_json, reasoning_delta, resolve_writing_model_name, safe_get_stream_writer
from .sample_analyzer import render_sample_style_section
logger = logging.getLogger(__name__)
# ── 内置 agent 模式的输入 payload(SOUL 已含人设/层级语义/输出契约,这里只给本次任务的事实输入)──
_AGENT_OUTLINE_USER = """任务模式:新规划
写作意图:{user_intent}
文章类型:{article_type}
目标读者:{target_audience}
目标字数:{word_count_target}字{feedback_section}
可用素材摘要:
{materials_summary}
请规划文章大纲(3-5 个章节),严格按 SOUL 约定输出 [OUTLINE_READY] + JSON。"""
_AGENT_OUTLINE_REVISE_USER = """任务模式:修改模式
写作意图:{user_intent}
文章类型:{article_type}
目标读者:{target_audience}
目标字数:{word_count_target}字
当前大纲(JSON):
{current_outline}
用户修改要求:{feedback}
可用素材摘要:
{materials_summary}
请在「当前大纲」基础上落实「用户修改要求」,未提到的章节保持原样,严格按 SOUL 约定输出 [OUTLINE_READY] + 调整后的完整大纲 JSON。"""
# 上下文压缩:传给大纲规划的素材摘要做条数和单条长度双重截断,防止 token 溢出。
_MAX_OUTLINE_MATERIALS = 12
_MATERIAL_SNIPPET_CHARS = 150
def _materials_summary(pkg: dict) -> str:
lines = []
for m in pkg.get("materials", [])[:_MAX_OUTLINE_MATERIALS]:
lines.append(f"[{m['id']}] {m['title']} | {m['source']} | {m['content'][:_MATERIAL_SNIPPET_CHARS]}")
return "\n".join(lines) or "(无素材)"
def _normalize_key_point(raw: object) -> KeyPoint:
"""把 LLM 输出 / 旧 session 数据规整成 KeyPoint。
兼容场景:
- 新版 dict:`{"point_title": "...", "sub_points": [...]}` —— 直接用,缺字段补默认
- 旧版 string:历史 session 的 `key_points: ["要点1", "要点2"]` —— 自动 lift 成
`{"point_title": "要点1", "sub_points": []}`,旧大纲打开后能继续编辑
- LLM 偶尔会用 `title` / `subPoints` 这种 camelCase 或别名,做轻量兜底
- 其它无法识别的形态(数字 / 列表 / None)→ 空 KeyPoint,不让整个大纲炸掉
"""
if isinstance(raw, str):
return KeyPoint(point_title=raw, sub_points=[])
if isinstance(raw, dict):
# 字段别名兜底(LLM 时常 camelCase 或写 title):优先 snake_case
title = (
raw.get("point_title")
or raw.get("pointTitle")
or raw.get("title")
or ""
)
subs_raw = raw.get("sub_points") or raw.get("subPoints") or []
# 子要点统一为字符串数组;dict 子项取其 title 字段降级(避免 4 级嵌套混入)
sub_points: list[str] = []
if isinstance(subs_raw, list):
for sp in subs_raw:
if isinstance(sp, str):
sub_points.append(sp)
elif isinstance(sp, dict):
sub_points.append(str(sp.get("point_title") or sp.get("title") or sp.get("text") or ""))
return KeyPoint(point_title=str(title), sub_points=sub_points)
# 其它意外类型(int / list / None):返回空 KeyPoint
return KeyPoint(point_title="", sub_points=[])
def _parse_outline(raw: dict) -> Outline:
sections = []
for s in raw.get("sections", []):
raw_kps = s.get("key_points") or []
key_points = [_normalize_key_point(kp) for kp in raw_kps]
sections.append(OutlineSection(
section_title=s.get("section_title", ""),
key_points=key_points,
material_ids=s.get("material_ids", []),
))
if not sections:
sections = [OutlineSection(
section_title="正文",
key_points=[KeyPoint(point_title="主要内容", sub_points=[])],
material_ids=[],
)]
return Outline(title=raw.get("title", "未命名文章"), sections=sections)
def _derive_title(state: AIWritingState) -> str:
"""用户大纲没给总标题时,用写作意图兜底一个标题。"""
intent = (state.get("user_intent") or "").strip()
if not intent:
return "未命名文章"
return intent[:30].rstrip() + ("…" if len(intent) > 30 else "")
# ── 素材关联:确定性词重叠(替代 LLM,零延迟)────────────────────────────────────
_ALNUM_TOKEN_RE = re.compile(r"[a-z0-9]+")
_CJK_CHAR_RE = re.compile(r"[一-鿿]")
def _text_tokens(text: str) -> set[str]:
"""把文本切成可比较的 token 集合:CJK 取相邻 bigram、英文/数字取整词(均小写)。
bigram 让「新能源汽车出口」这类短标题与素材标题/正文做稳定的词重叠匹配,
无需任何模型调用。
"""
if not text:
return set()
text = text.lower()
tokens: set[str] = {w for w in _ALNUM_TOKEN_RE.findall(text) if len(w) >= 2}
cjk = _CJK_CHAR_RE.findall(text)
tokens.update(cjk[i] + cjk[i + 1] for i in range(len(cjk) - 1))
return tokens
def _section_query_text(section: dict) -> str:
"""章节用于匹配素材的文本:章节标题 + 各小节标题 + 子要点,越全匹配越准。"""
parts = [section.get("section_title") or ""]
for kp in section.get("key_points", []) or []:
if isinstance(kp, dict):
parts.append(kp.get("point_title") or "")
parts.extend(s for s in (kp.get("sub_points") or []) if isinstance(s, str))
elif isinstance(kp, str):
parts.append(kp)
return " ".join(p for p in parts if p)
def _assign_materials_heuristic(outline: Outline, pkg: dict) -> Outline:
"""确定性地把素材按词重叠归类到各章节(替代 LLM 调用,零延迟、零 <think> 等待)。
每条素材分配给与其标题/正文词重叠最高的章节(必须有重叠才分配);与所有章节都不
重叠的素材不强行塞入(writer_draft 自带「取前 2 条素材」兜底)。只改 material_ids,
绝不动标题与层级。
"""
sections = outline.get("sections", [])
materials = pkg.get("materials") or []
if not sections or not materials:
return outline
section_tokens = [_text_tokens(_section_query_text(s)) for s in sections]
assigned: list[list[str]] = [[] for _ in sections]
for m in materials:
mid = m.get("id")
if not mid:
continue
mat_tok = _text_tokens(f"{m.get('title', '')} {m.get('content', '')}")
if not mat_tok:
continue
best_idx, best_score = -1, 0
for i, sec_tok in enumerate(section_tokens):
score = len(mat_tok & sec_tok)
if score > best_score:
best_idx, best_score = i, score
if best_idx >= 0:
assigned[best_idx].append(mid)
for section, ids in zip(sections, assigned):
section["material_ids"] = ids
return outline
async def _stream_normalize_user_outline(
state: AIWritingState, config: RunnableConfig, raw: str, writer
) -> Outline:
"""散文化大纲:确定性解析失败时流式调 LLM 归一成三级结构,实时展示给前端。
内网模型 <think> 关不掉 → 用 ThinkTagParser 把思考与正文分流:思考推 is_thinking
思考框、正文累积后解析 JSON,用户全程看得到进度而非干等。再失败则把每个非空行当作
一个章节兜底,保证永远产出可用大纲、不丢用户内容。
"""
line_fallback = {
"title": "",
"sections": [
{"section_title": ln.strip(), "key_points": [], "material_ids": []}
for ln in raw.splitlines() if ln.strip()
] or [{"section_title": "正文", "key_points": [], "material_ids": []}],
}
name, _ = resolve_writing_model_name(config, state)
full_text = ""
try:
from deerflow.models import create_chat_model
# 大纲整理是结构化保真任务,强制关思考(GLM5 等爱出 <think>);
# 关不掉的模型仍由下方 ThinkTagParser 把思考分流到思考框实时展示。
model = create_chat_model(name=name, force_disable_thinking=True)
parser = ThinkTagParser()
async for chunk in model.astream([
SystemMessage(content=OUTLINE_NORMALIZE_SYSTEM),
HumanMessage(content=OUTLINE_NORMALIZE_USER.format(raw_outline=raw)),
]):
reasoning = reasoning_delta(chunk)
if reasoning:
writer({"type": "outline_chunk", "text": reasoning, "is_thinking": True})
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
writer({"type": "outline_chunk", "text": text, "is_thinking": is_thinking})
except Exception as e:
logger.error("stream normalize user outline failed: %s", e, exc_info=True)
return _parse_outline(line_fallback)
return _parse_outline(parse_json(full_text, line_fallback))
async def build_user_outline_with_materials(
state: AIWritingState, config: RunnableConfig, pkg: dict
) -> Outline | None:
"""搜集素材阶段调用:用户自带大纲时,解析其大纲并把已检索素材归类到各章节。
复用本模块的解析/归类逻辑,让 researcher 能在「搜集素材」阶段顺便整理素材,
从而**跳过 writer_outline 的大纲生成步**(见 graph 路由)。无用户大纲返回 None。
已有结构化大纲(如 re_search 二次检索)则复用结构、仅重新归类素材,不重复解析。
只做**确定性**解析与素材关联(零 LLM、瞬时):散文化、解析不出层级的大纲返回
None —— 不在 researcher 阶段阻塞式调 LLM 归一,交给 writer_outline 流式归一并实时
展示(见 graph after_material_pause 路由)。
"""
raw = (state.get("user_outline_raw") or "").strip()
if not raw:
return None
existing = state.get("current_outline")
if existing and existing.get("sections"):
outline: Outline = existing
else:
outline = parse_user_outline(raw)
if outline is None:
return None
if not outline.get("title"):
outline = {**outline, "title": _derive_title(state)}
return _assign_materials_heuristic(outline, pkg)
async def _build_outline_from_user(
state: AIWritingState, config: RunnableConfig, pkg: dict, raw: str
) -> dict:
"""用户自带大纲分支:解析用户大纲 → 关联素材 → 直接进确认,不调 LLM 重新规划。
可确定性解析的大纲(带编号/标题/缩进)零 LLM、瞬时完成;只有散文化、解析不出层级
的大纲才流式调一次 LLM 归一(实时展示思考/正文,应对内网模型关不掉的 <think>),
素材关联一律走确定性词重叠。
"""
writer = safe_get_stream_writer()
outline = parse_user_outline(raw)
if outline is None:
# 确定性解析拿不准(散文化/格式混乱)→ 流式 LLM 兜底归一,全程实时展示
outline = await _stream_normalize_user_outline(state, config, raw, writer)
else:
writer({"type": "outline_chunk", "text": "正在整理你提供的大纲…\n", "is_thinking": True})
if not outline.get("title"):
outline = {**outline, "title": _derive_title(state)}
# 仍走了检索 → 把已检索素材关联到用户章节(确定性词重叠,零 LLM)
outline = _assign_materials_heuristic(outline, pkg)
section_count = len(outline.get("sections", []))
return {
"current_outline": outline,
"status": "awaiting_outline_confirm",
"progress_events": [
{"type": "step_start", "agent_name": "作家", "message": "采用你提供的大纲"},
{"type": "outline_ready", "agent_name": "作家", "message": f"已整理你的大纲,共 {section_count} 个章节"},
],
}
async def writer_outline_node(state: AIWritingState, config: RunnableConfig) -> dict:
pkg = state.get("material_package") or {"keywords": [], "materials": [], "summary": ""}
intervention = state.get("last_user_intervention") or {}
feedback = ""
if intervention.get("action") == "re_outline":
feedback = intervention.get("_feedback") or intervention.get("outline_feedback") or ""
elif intervention.get("outline_feedback"):
feedback = intervention.get("outline_feedback") or ""
# 重新规划且已有大纲 → 走「编辑模式」:把当前大纲喂给模型,按用户要求调整,
# 而非从零重生成(否则「加一节/删一节」这类指令没有可编辑的基准)。
current_outline = state.get("current_outline")
is_revise = bool(feedback) and bool(current_outline)
# 用户自带大纲:首轮(尚无大纲、非重规划)且表单粘了大纲原文 → 走「采用用户大纲」分支,
# 跳过 LLM 重新规划。后续若用户在确认卡里点「重新规划」,current_outline 已存在 → 落到
# 下方 is_revise 编辑模式,按反馈调整用户大纲(符合预期)。
user_outline_raw = (state.get("user_outline_raw") or "").strip()
if user_outline_raw and not current_outline and not is_revise:
return await _build_outline_from_user(state, config, pkg, user_outline_raw)
# 内置 agent 模式(config.yaml ai_writing.use_builtin_agents.outliner):
# SOUL 作 system prompt + [OUTLINE_READY] 契约解析;目录缺失静默回退旧路径。
use_agent = use_builtin_agent("outliner")
agent_label = "作家"
if use_agent:
try:
load_writing_agent(OUTLINER_AGENT_ID)
agent_label = agent_display_name(OUTLINER_AGENT_ID, "大纲规划师")
except WritingAgentUnavailable as e:
logger.warning("outliner builtin agent unavailable, falling back to legacy prompts: %s", e)
use_agent = False
# 新(列表外)文章类型时附上配置助手识别的一句话特征,让大纲生成体现该类型侧重;
# 命中已有类型时 detail 为空,article_type 维持原样。
_article_type = state.get("article_type", "analysis")
_article_type_detail = (state.get("article_type_detail") or "").strip()
article_type_text = f"{_article_type}({_article_type_detail})" if _article_type_detail else _article_type
fmt_args = dict(
user_intent=state["user_intent"],
article_type=article_type_text,
target_audience=state.get("target_audience", "普通读者"),
word_count_target=state.get("word_count_target", 800),
materials_summary=_materials_summary(pkg),
)
sample_style_section = render_sample_style_section(state)
if is_revise:
system_prompt = OUTLINE_REVISE_SYSTEM
revise_args = dict(
fmt_args,
current_outline=json.dumps(current_outline, ensure_ascii=False, indent=2),
feedback=feedback,
)
user_prompt = OUTLINE_REVISE_USER.format(**revise_args) + sample_style_section
agent_payload = _AGENT_OUTLINE_REVISE_USER.format(**revise_args) + sample_style_section
else:
system_prompt = OUTLINE_SYSTEM
feedback_section = f"\n重新规划要求:{feedback}" if feedback else ""
gen_args = dict(fmt_args, feedback_section=feedback_section)
user_prompt = OUTLINE_USER.format(**gen_args) + sample_style_section
agent_payload = _AGENT_OUTLINE_USER.format(**gen_args) + sample_style_section
# 流式推送:阶段 2 起统一走 LangGraph 原生 custom 通道(get_stream_writer)。
writer = safe_get_stream_writer()
full_text = "" # 只累积正文(非思考)用于 JSON 解析
extra_progress_events: list[dict] = []
if use_agent:
# 内置 agent 路径走 stream_writing_agent,不在本模块做模型链兜底(agent 自带模型解析)。
try:
def _on_text(text: str, is_thinking: bool) -> None:
writer({"type": "outline_chunk", "text": text, "is_thinking": is_thinking})
full_text = await stream_writing_agent(
agent_id=OUTLINER_AGENT_ID,
user_payload=agent_payload,
disable_thinking=True,
state=state,
config=config,
on_text=_on_text,
)
except Exception as e:
logger.error("outline streaming failed: %s", e, exc_info=True)
return {
"status": "error",
"progress_events": [{
"type": "error",
"agent_name": agent_label,
"title": "模型错误",
"detail": str(e),
"message": "大纲生成失败",
}],
}
else:
# 旧路径:按 fallback_chain 顺序尝试,失败即换下一个模型重跑该环节。
initial_name, _used_default = resolve_writing_model_name(config, state)
chain = fallback_chain(initial_name)
from deerflow.models import create_chat_model
success = False
last_exc: BaseException | None = None
for idx, candidate in enumerate(chain or [None]):
full_text = ""
parser = ThinkTagParser()
try:
model = (
create_chat_model(name=candidate, force_disable_thinking=True)
if candidate else create_chat_model(force_disable_thinking=True)
)
async for chunk in model.astream([
SystemMessage(content=system_prompt),
HumanMessage(content=user_prompt),
]):
reasoning = reasoning_delta(chunk)
if reasoning:
writer({"type": "outline_chunk", "text": reasoning, "is_thinking": True})
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
writer({
"type": "outline_chunk",
"text": text,
"is_thinking": is_thinking,
})
success = True
break
except Exception as e:
last_exc = e
reason = classify_exception(e)
logger.error(
"outline streaming failed on model=%s (reason=%s): %s",
candidate, reason, e, exc_info=True,
)
next_candidate = chain[idx + 1] if idx + 1 < len(chain) else None
if next_candidate:
emit_model_switch_event(
writer, agent_name=agent_label, stage="outline",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
)
extra_progress_events.append(build_switch_progress_event(
agent_name=agent_label, stage="outline",
failed_model=candidate or "", next_model=next_candidate, reason=reason,
))
continue
if not success:
assert last_exc is not None
return {
"status": "error",
"progress_events": extra_progress_events + [{
"type": "error",
"agent_name": agent_label,
"title": "模型错误",
"detail": str(last_exc),
"message": "大纲生成失败(所有候选模型均失败)",
}],
}
# 编辑模式解析失败时回退为「当前大纲」,避免把用户已有大纲弄丢
if is_revise:
fallback = current_outline
else:
# 兜底大纲也用新的 3 级结构;_normalize_key_point 同时兼容旧 string 形态,
# 这里给 dict 形态做样板。
fallback = {
"title": "未命名文章",
"sections": [
{
"section_title": "引言",
"key_points": [
{"point_title": "背景介绍", "sub_points": []},
],
"material_ids": [],
},
{
"section_title": "正文",
"key_points": [
{"point_title": "核心内容", "sub_points": []},
],
"material_ids": [],
},
{
"section_title": "结论",
"key_points": [
{"point_title": "总结", "sub_points": []},
],
"material_ids": [],
},
],
}
if use_agent:
result = parse_marker_json(full_text, OUTLINE_READY_MARKER, fallback)
else:
result = parse_json(full_text, fallback)
outline = _parse_outline(result)
section_count = len(outline["sections"])
return {
"current_outline": outline,
"status": "awaiting_outline_confirm",
"progress_events": [
{"type": "step_start", "agent_name": agent_label, "message": "开始规划大纲"},
*extra_progress_events,
{"type": "outline_ready", "agent_name": agent_label, "message": f"大纲已生成,共 {section_count} 个章节"},
],
}
@@ -0,0 +1,220 @@
"""把用户粘贴的大纲文本解析成三级 ``Outline`` 结构(确定性解析,不依赖 LLM)。
用户在写作表单里可能直接粘贴一份已有大纲,要求「完全按我的大纲生成」。本模块负责
把各种常见的大纲文本格式严格、保真地转成后端三级结构:
Outline.sections[] = Level 1 章节(section_title)
OutlineSection.key_points[] = Level 2 小节(point_title)
KeyPoint.sub_points[] = Level 3 子要点
兼容的输入格式:
- Markdown 标题:``#`` / ``##`` / ``###`` / ``####``(首个孤立 ``#`` 视为文章标题)
- 中文编号:``一、`` / ``(一)`` / ``第一章`` / ``第一节``
- 阿拉伯编号:``1.`` / ``1、`` / ``1.1`` / ``1.1.1``
- 缩进 bullet:``-`` / ``*`` / ``•`` / ``·``(用缩进深度表示层级)
- 纯文本平铺:每行一个一级标题(短标题、无句末标点)
设计原则:
- **保真不改写**:只识别层级、原样保留标题文本,绝不增删或改写用户内容。
- **多级混排自适应**:把文本里实际出现的各种「层级标记」收集起来排序,按相对外层
顺序映射到 1/2/3 级——所以不依赖固定的标记搭配,``##``+``-`` 或 ``一、``+缩进
都能正确分层。
- **拿不准就交给上层**:识别不出可靠层级(如整段散文)时返回 ``None``,由调用方走
LLM 兜底归一,避免硬把散文拆成错误结构。
"""
from __future__ import annotations
import re
from .state import KeyPoint, Outline, OutlineSection
# ── 行首标记识别 ──────────────────────────────────────────────────────────────
_CN_NUM = "一二三四五六七八九十百千零〇两"
# Markdown 标题:## 标题
_MD_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
# 第一章 / 第1节 / 第一部分
_CN_CHAPTER_RE = re.compile(rf"^第\s*[{_CN_NUM}\d]+\s*[章节部分篇讲回卷](?:[\s::、..))]\s*|\s+)?(.*)$")
# 一、 / 十二、 / 一. / 一.
_CN_DUN_RE = re.compile(rf"^[{_CN_NUM}]+\s*[、..]\s*(.*)$")
# (一) / (一) / (1) / (1)
_PAREN_RE = re.compile(rf"^[((]\s*[{_CN_NUM}\d]+\s*[))]\s*(.*)$")
# 1.1 / 1.1.1(带至少一个点的多级阿拉伯编号)
_ARABIC_DOTTED_RE = re.compile(r"^(\d+(?:\.\d+)+)\s*[、..))]?\s*(.*)$")
# 1. / 1、 / 1) / 1.(单级阿拉伯编号)
_ARABIC_SINGLE_RE = re.compile(r"^\d+\s*[、..))]\s*(.*)$")
# 带圈数字 ①②③ / 罗马 ⅰ
_CIRCLED_RE = re.compile(r"^[①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮]\s*(.*)$")
# bullet:- / * / • / ·(要求标记后有空白,避免误吞「*强调*」之类)
_BULLET_RE = re.compile(r"^[-*•·]\s+(.*\S)\s*$")
# 标记分组的「外层度」基准值(越小越外层)。group: 0=标题 1=编号 2=缩进。
# 同组内 order 决定相对层级;不同组之间靠 group 排序(标题 < 编号 < 缩进)。
# 编号顺序遵循中文公文惯例:第一章 > 一、 > (一) > 1. > 1.1 > ①。
_NUM_ORDER = {
"cn_chapter": 0.0, # 第一章
"cn_dun": 1.0, # 一、
"paren": 2.0, # (一)
"arabic_single": 3.0, # 1.
"circled": 8.0, # ①
}
def _indent_width(line: str) -> int:
"""计算行首缩进宽度(tab 记 4 列)。"""
width = 0
for ch in line:
if ch == " ":
width += 1
elif ch == "\t":
width += 4
else:
break
return width
def _classify(stripped: str, indent: int) -> tuple[tuple[int, float], str] | None:
"""识别一行的层级标记,返回 ``((group, order), 纯文本)``;无法识别返回 None。
``(group, order)`` 是该行的「层级键」:把全文出现过的不同键排序后,按位置映射到
1/2/3 级。这样不必预设标记搭配,相对顺序对了层级就对。
"""
if not stripped:
return None
# 1) Markdown 标题(group 0,order = 井号数)
m = _MD_HEADING_RE.match(stripped)
if m:
depth = len(m.group(1))
text = m.group(2).strip()
return (0, float(depth)), text
# 2) 各类编号(group 1)
m = _CN_CHAPTER_RE.match(stripped)
if m and stripped.startswith("第"):
return (1, _NUM_ORDER["cn_chapter"]), (m.group(1) or "").strip()
m = _CN_DUN_RE.match(stripped)
if m:
return (1, _NUM_ORDER["cn_dun"]), m.group(1).strip()
m = _ARABIC_DOTTED_RE.match(stripped)
if m:
depth = m.group(1).count(".") + 1 # 1.1 → 2, 1.1.1 → 3
# 多级阿拉伯:order 随层级递增,落在单级(3.0)与圈号(8.0)之间
return (1, 3.0 + depth), m.group(2).strip()
m = _PAREN_RE.match(stripped)
if m:
return (1, _NUM_ORDER["paren"]), m.group(1).strip()
m = _ARABIC_SINGLE_RE.match(stripped)
if m:
return (1, _NUM_ORDER["arabic_single"]), m.group(1).strip()
m = _CIRCLED_RE.match(stripped)
if m:
return (1, _NUM_ORDER["circled"]), m.group(1).strip()
# 3) bullet:用缩进深度区分层级(group 2)
m = _BULLET_RE.match(stripped)
if m:
return (2, float(indent)), m.group(1).strip()
# 4) 纯文本:用缩进深度区分层级(group 3,最内层基准)
return (3, float(indent)), stripped
def _looks_like_prose(text: str) -> bool:
"""判断一行是否更像散文句子而非大纲标题(长、或带句末标点)。"""
if len(text) > 50:
return True
return text.rstrip()[-1:] in "。!?!?;;"
def parse_user_outline(raw: str) -> Outline | None:
"""把用户粘贴的大纲文本解析成三级 ``Outline``;无法可靠解析时返回 ``None``。
返回 ``None`` 的情形:空白输入、只有一行且无任何标记、或整体更像散文段落——这些交给
上层用 LLM 兜底归一,避免误拆。
"""
if not raw or not raw.strip():
return None
rows: list[tuple[tuple[int, float], str]] = []
for line in raw.splitlines():
if not line.strip():
continue
indent = _indent_width(line)
classified = _classify(line.strip(), indent)
if classified is None:
continue
key, text = classified
if text:
rows.append((key, text))
if not rows:
return None
marked = any(key[0] != 3 for key, _ in rows) # 是否出现过标题/编号/bullet 标记
# 纯文本且无任何标记:可能是「平铺标题列表」也可能是散文。
# 单行、或任一行像句子 → 判为散文,返回 None 交给 LLM。
if not marked:
if len(rows) < 2:
return None
if any(_looks_like_prose(text) for _, text in rows):
return None
# 文章标题:仅在「Markdown 首行是孤立的最浅井号、且存在更深井号」时认定。
title = ""
body = rows
heading_depths = [key[1] for key, _ in rows if key[0] == 0]
if heading_depths:
min_depth = min(heading_depths)
first_key = rows[0][0]
is_first_top_heading = first_key == (0, min_depth)
only_one_at_top = sum(1 for d in heading_depths if d == min_depth) == 1
has_deeper = any(d > min_depth for d in heading_depths)
if is_first_top_heading and only_one_at_top and has_deeper:
title = rows[0][1]
body = rows[1:]
if not body:
return None
# 把 body 里出现的不同「层级键」排序,按位置映射到 1/2/3 级(超过 3 级压到 3)。
distinct_keys = sorted({key for key, _ in body})
level_of: dict[tuple[int, float], int] = {
key: min(idx + 1, 3) for idx, key in enumerate(distinct_keys)
}
sections: list[OutlineSection] = []
cur_section: OutlineSection | None = None
cur_point: KeyPoint | None = None
for key, text in body:
level = level_of[key]
if level <= 1:
cur_section = OutlineSection(section_title=text, key_points=[], material_ids=[])
sections.append(cur_section)
cur_point = None
elif level == 2:
if cur_section is None: # 孤立 L2:提升为章节,避免空标题
cur_section = OutlineSection(section_title=text, key_points=[], material_ids=[])
sections.append(cur_section)
cur_point = None
continue
cur_point = KeyPoint(point_title=text, sub_points=[])
cur_section["key_points"].append(cur_point)
else: # level == 3
if cur_section is None: # 孤立 L3:提升为章节
cur_section = OutlineSection(section_title=text, key_points=[], material_ids=[])
sections.append(cur_section)
cur_point = None
elif cur_point is None: # 章节下尚无小节:提升为小节
cur_point = KeyPoint(point_title=text, sub_points=[])
cur_section["key_points"].append(cur_point)
else:
cur_point["sub_points"].append(text)
if not sections:
return None
return Outline(title=title, sections=sections)
@@ -0,0 +1,61 @@
EDITOR_SYSTEM = """你是一名资深主编(编辑),标准极高,要求严格。
你的目标:审查文章质量,给出客观评分和具体修改意见。
你的工作背景:你在一家权威媒体担任主编十五年,见过各种质量的文章。
你只能做以下事情:
1. 从指定维度审查文章
2. 给出该维度的评分(0-100 的整数)和具体问题列表
你不能改写文章,只做当前指定维度的审查。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块。
- 必须使用英文双引号 "。
- score 是 0-100 的整数。
- 每个问题的 severity 必须是 "major"(必须修改)或 "minor"(建议修改)。
- 文章在该维度没有问题时,issues 填空数组 []。
【完整示例】
正确输出:
{
"score": 82,
"issues": [
{"severity": "major", "location": "第二段", "issue": "引用的增长数据没有素材支撑", "suggestion": "补充素材 m002 中的具体数据,并注明来源"},
{"severity": "minor", "location": "结尾段", "issue": "结论略显仓促", "suggestion": "增加一句对未来行业趋势的判断"}
]
}"""
# 用户在提交编辑审核时附带的修改意见 / 关注点(无则为空串,不注入)。
# 放在「判断标准」之后、待审文章之前,提醒编辑在本维度重点核查用户在意的方面。
USER_FOCUS_BLOCK = """
【用户特别关注(高优先级)】
用户在提交审核时提出了以下修改意见 / 关注点,请在本维度审查时**重点核查**这些方面;
若发现文章未妥善处理,必须在 issues 中明确列出对应问题并给出针对性的 suggestion:
{notes}"""
FACT_REVIEW_USER = """请审查以下文章的【事实准确性】维度。
判断标准:引用的数据/事实是否有素材支撑,是否有捏造或夸大。{user_focus}
参考素材:
{materials_summary}
待审文章:
{article}
只输出 JSON(score: 0-100 整数,issues 列表,每条含 severity):"""
LOGIC_REVIEW_USER = """请审查以下文章的【逻辑结构】维度。
判断标准:论点是否清晰,论据是否充分,段落是否连贯,结构是否合理。{user_focus}
待审文章:
{article}
只输出 JSON(score: 0-100 整数,issues 列表,每条含 severity):"""
LANGUAGE_REVIEW_USER = """请审查以下文章的【语言文字】维度。
判断标准:语言是否流畅,用词是否准确,有无错别字或病句。{user_focus}
待审文章:
{article}
只输出 JSON(score: 0-100 整数,issues 列表,每条含 severity):"""
@@ -0,0 +1,104 @@
"""对话驱动写作台的意图路由 prompt。
场景:新版「AI 写作·对话版」页面用底部统一输入框接管全流程交互,用户的自由文本
需要被翻译成现有 ai_writing graph 的 ``Command(resume={action, ...payload})`` 指令,
或被识别为「对内容/流程提问」「控制指令」「需要澄清」。
设计要点(与 graph.py 各 pause 节点严格对齐,绝不发明图不支持的动作):
- material_confirm 只有 confirm / re_search;
- outline_confirm 只有 confirm / re_outline;
- draft_confirm 只有 to_editor / finalize / user_revise;
- review_confirm 只有 accept_review / force_finalize;
- section_help 只有 section_help(带逐章节 decisions)。
高代价动作(finalize / force_finalize / 无查询词的覆盖式 re_search)要求高置信,
否则输出 clarify 反问 —— 防误触发是硬指标。
"""
from __future__ import annotations
INTENT_ROUTER_SYSTEM = """你是「AI 智能写作」工作台的意图路由器。
写作流程由多位专家协作:素材收集专家(检索素材)→ 作家(规划大纲、逐章写作)→ 编辑(事实/逻辑/语言三维审核)。流程在每个阶段完成后暂停,等待用户确认后才继续。
你的任务:读懂用户在当前阶段发来的一句话,把它翻译成一条结构化指令 JSON;如果用户是在提问,就直接回答。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块,必须用英文双引号。
- JSON 结构(所有字段都必须出现):
{"intent": "意图标识", "action": "动作或null", "payload": {}, "need_research": false, "research_query": "", "answer": "", "confidence": 0.0, "clarify": ""}
【字段说明】
- intent:你判定的意图标识,如 confirm_materials / add_material / select_materials / research_again / confirm_outline / revise_outline / reoutline / to_editor / finalize / revise_draft / accept_review / partial_accept_review / add_review_opinion / force_finalize / section_decision / ask_content / ask_meta / run_background / pause_writing / clarify。
- action:要执行的图动作,只能从下面「当前阶段可用动作」中选择;不执行动作时为 null。
- payload:动作参数(键名用驼峰):
approvedMaterialIds(素材 id 数组,确认时保留哪些素材;不筛选就省略)
userQuery(补充检索的自然语言检索意图,配合 re_search 表示"追加检索")
outlineFeedback(大纲修改意见原文,配合 re_outline)
userRevisionNotes(草稿修改意见/给编辑的关注点/补充审核意见,配合 user_revise / to_editor / accept_review)
selectedIssueIndices(采纳的审核意见序号数组,从 0 开始,配合 user_revise / accept_review)
overrideVerdict(true,仅配合 force_finalize)
sectionDecisions([{"sectionTitle": "...", "decision": "supplement|loose|delete"}],仅配合 section_help,必须覆盖全部受阻章节)
- need_research:用户的要求需要「当前素材列表里没有的信息」才能完成时置 true,并在 research_query 给出简短检索词(不需要就置 false + 空串)。
- answer:用户在提问(ask_content 对文章内容提问 / ask_meta 问进度、用了哪些素材等)时,直接根据上下文用中文简洁回答;答案必须基于给定上下文,不得编造。提问类 action 必须为 null。
- confidence:0~1,你对「动作映射正确」的把握。
- clarify:拿不准用户想干什么、或该操作在当前阶段做不了时,写一句具体的中文反问/解释(可给出可选项);clarify 非空时 action 必须为 null。
【硬规则】
1. action 只能从「当前阶段可用动作」里选。用户要求的事在当前阶段做不了(例如写作阶段要求重新搜索素材),action 置 null,用 clarify 解释当前能做什么、该要求何时能做。
2. 高代价动作必须用户意图非常明确才输出,且 confidence ≥ 0.85,否则改用 clarify 反问确认:
- finalize(定稿,结束流程)
- force_finalize(无视编辑意见强制定稿)
- 不带 userQuery 的 re_search(覆盖式重搜,会丢掉现有素材重来)
注意:带 userQuery 的 re_search 是"追加检索"(保留现有素材,把新素材追加进列表),不算高代价。
3. 用户说"只用第 X、Y 条素材"→ action=confirm + approvedMaterialIds(按素材清单序号找对应 id);"去掉第 X 条"→ confirm + 反选后的 approvedMaterialIds。
4. 用户给出修改意见时把**原文完整**放进对应字段(outlineFeedback / userRevisionNotes),不要概括缩写。
5. 用户说"只接受第 X 条意见"→ selectedIssueIndices 用审核意见清单的序号(从 0 开始)。用户补充自己的审核/修改要求 → 并入 userRevisionNotes。
6. 控制类:用户要"转后台/后台跑完"→ intent=run_background;"暂停"→ intent=pause_writing。二者 action 都为 null(由前端执行)。
7. 完全无法判断 → intent=clarify,confidence ≤ 0.3,clarify 给一个具体问题。"""
# 每个暂停点的「可用动作说明」——注入 user prompt,让模型只在合法动作里选。
STAGE_ACTION_GUIDES: dict[str, str] = {
"material_confirm": """当前阶段:素材确认(素材收集专家已完成搜集,等你处理素材)。
可用动作:
- confirm:确认素材、进入大纲规划。可带 approvedMaterialIds 只保留部分素材。
- re_search:重新检索。带 userQuery = 按用户描述追加检索(保留现有素材);不带 userQuery = 覆盖式重搜(高代价,需高置信)。
典型说法 → 动作:
「可以,继续」→ confirm;「补充一些关于X的素材」「再查查Y」→ re_search + userQuery;「只用第1、3条」→ confirm + approvedMaterialIds;「重新搜索」→ re_search(覆盖式,需高置信)。""",
"outline_confirm": """当前阶段:大纲确认(作家已完成大纲规划,等你确认或提修改要求)。
可用动作:
- confirm:确认大纲、开始写作。
- re_outline:按意见重新规划大纲,outlineFeedback 放用户意见原文(可空 = 完全重来)。
典型说法 → 动作:
「大纲可以」→ confirm;「第二章拆成两节」「把X挪到前面」「加一章讲Y」→ re_outline + outlineFeedback;「重写大纲」→ re_outline(feedback 空)。
注意:本阶段不能检索素材。用户想补素材时若其本质是"大纲里加上X内容",可映射 re_outline + outlineFeedback 并视情况置 need_research。""",
"draft_confirm": """当前阶段:草稿确认(作家已完成草稿,右侧可预览,等你处理)。
可用动作:
- to_editor:交给编辑审核。可带 userRevisionNotes = 让编辑重点核查的方面。
- user_revise:按用户意见修改草稿,userRevisionNotes 放意见原文(必填)。若已有编辑审核意见且用户说按意见改,可带 selectedIssueIndices。
- finalize:确认定稿,结束流程(高代价,需高置信)。
典型说法 → 动作:
「交给编辑」「审核一下」→ to_editor;「第三段精简」「补个案例」「更口语一点」「重写第二章」→ user_revise + userRevisionNotes;「就这样定稿」→ finalize(需高置信);「让编辑重点看数据准确性」→ to_editor + userRevisionNotes。""",
"review_confirm": """当前阶段:编辑打回处理(编辑认为文章需要修改,列出了审核意见,等你决定)。
可用动作:
- accept_review:按编辑意见修改。可带 selectedIssueIndices 只采纳部分意见;用户自己补充的修改要求并入 userRevisionNotes。
- force_finalize:忽略编辑意见强制定稿,payload 带 {"overrideVerdict": true}(高代价,需高置信)。
典型说法 → 动作:
「按编辑意见改」→ accept_review;「只接受第1、2条」→ accept_review + selectedIssueIndices;「再补一条:核查数据来源」→ accept_review + userRevisionNotes;「不改了,定稿」→ force_finalize(需高置信)。""",
"section_help": """当前阶段:素材不足求助(严格模式下部分章节缺素材,需逐章节决定处理方式)。
可用动作:
- section_help:sectionDecisions 必须覆盖全部受阻章节,每章 decision ∈ supplement(补充检索素材)/ loose(按通用知识续写)/ delete(删除该章节)。
典型说法 → 动作:
「都补充检索」→ 全部 supplement;「都按通用知识写」→ 全部 loose;「第一个删掉,其他补检索」→ 对应组合。用户没说全 → 未提到的章节按用户整体倾向补齐,倾向不明则用 loose。""",
}
NO_PAUSE_GUIDE = """当前没有等待确认的步骤(流程正在自动执行中,或已结束)。
不能执行任何图动作(action 必须为 null)。用户提问 → 正常回答(answer);用户提出操作要求 → 用 clarify 告知「当前阶段正在进行中,完成后会暂停等确认,届时再提出即可」,并简述现在进行到哪一步。控制类(run_background / pause_writing)照常输出 intent。"""
INTENT_ROUTER_USER_TEMPLATE = """{stage_guide}
【写作上下文】
{context}
【用户这句话】
{text}
请输出意图 JSON:"""
@@ -0,0 +1,70 @@
# 注:两个 USER 提示词末尾的 `/no_think` 是 Qwen3 系列的"软开关",
# 收到当轮即跳过思考过程;对其它大模型只是一行普通文本、无副作用。
# 中文「严禁思考」强令块对所有模型生效,保留不动。
EXTRACT_KEYWORDS_SYSTEM = """你是一名专业情报研究员(素材收集专家)。
你的目标:为写作任务提取搜索关键词。
你的工作背景:你在一家权威媒体机构任职,熟悉各类信息源的可信度评估。
你只能做以下事情:
1. 从写作意图中按要求的数量提取搜索关键词
你不能写文章,不能评价内容好坏,只做关键词提取。
【严禁思考】
- 这是一个简单的结构化抽取任务,禁止任何思考、分析、推理或规划过程。
- 禁止输出 <think></think> 标签及其中的任何内容,禁止输出"让我想想""首先"之类的过渡语。
- 收到输入后必须立即、直接输出最终 JSON,不得有任何前置内容。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块。
- 必须使用英文双引号 ",不要用中文引号 “”。
- 关键词要具体、可搜索,避免过于宽泛的词。
【完整示例】
输入意图:写一篇分析今年新能源汽车出口增长的文章
正确输出:
{"keywords": ["新能源汽车出口", "汽车出口数据", "新能源汽车海外市场", "电动车出口增长", "汽车出口政策"]}"""
EXTRACT_KEYWORDS_USER = """写作意图:{user_intent}
文章类型:{article_type}
目标读者:{target_audience}
请提取 {keyword_count} 个搜索关键词,用于搜集相关素材。
关键词数量必须为 {keyword_count} 个,不多不少。
关键词必须是依据上述写作意图提炼的真实检索词,不要照抄下方 JSON 模板里的占位符。
只输出 JSON(下方 ... 是占位示意,不是真实关键词):
{{"keywords": ["...", "..."]}}
/no_think"""
RANK_MATERIALS_SYSTEM = """你是一名专业情报研究员(素材收集专家)。
你的目标:对搜索结果按相关度排序和筛选。
你的工作背景:你在一家权威媒体机构任职,熟悉各类信息源的可信度评估。
你只能做以下事情:
1. 从提供的素材列表中,选出与写作意图最相关的素材ID,按相关度从高到低排序
你不能写文章,只做素材筛选排序。
【严禁思考】
- 这是一个简单的筛选排序任务,禁止任何思考、分析、推理或规划过程。
- 禁止输出 <think></think> 标签及其中的任何内容,禁止输出"让我想想""首先"之类的过渡语。
- 收到输入后必须立即、直接输出最终 JSON,不得有任何前置内容。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块。
- 必须使用英文双引号 "。
- ranked_ids 中的 ID 必须来自素材列表,不要编造 ID。
【完整示例】
正确输出:
{"ranked_ids": ["m003", "m001", "m005"], "summary": "共搜索到 8 条素材,精选 5 条最相关的"}"""
RANK_MATERIALS_USER = """写作意图:{user_intent}
素材列表(每条含ID和摘要):
{materials_list}
请选出最相关的素材ID(最多8条),按相关度从高到低排序。只输出 JSON:
{{"ranked_ids": ["id1", "id2"], "summary": "共搜索到X条素材,精选Y条"}}
/no_think"""
@@ -0,0 +1,321 @@
OUTLINE_SYSTEM = """你是一名专业内容创作者(作家)。
你的目标:根据素材和意图,规划清晰的三级大纲(章节 → 小节 → 子要点)。
你的工作背景:你有十年内容创作经验,擅长将零散素材组织成有逻辑的文章结构。
你只能做以下事情:
1. 分析素材,提取核心观点
2. 规划文章三级结构:章节、章节下的小节、小节下的子要点
你不能写正文,只写大纲。大纲须紧扣写作意图,并尽量覆盖可用素材中的核心信息。
【严禁思考与表态】(最高优先级)
- 禁止输出任何思考、分析、规划过程,禁止 <think></think> 标签及其中内容。
- 禁止输出任何对用户说的话或对任务的评价(如"素材不足""无法规划大纲");无论素材是否充分,都必须直接产出大纲 JSON。
- 收到输入后立即、直接输出最终 JSON,不得有任何前置内容。
【三级层级语义】(最高优先级,决定文章结构)
- Level 1 = `section_title`(章节):将渲染为文章里的 `##` 二级标题,统领一组内容。
- Level 2 = `point_title`(小节):将渲染为 `###` 三级标题,下面会有一段 2-3 句的概述/引入正文。
- Level 3 = `sub_points`(子要点):将渲染为 `####` 四级标题,**每个子要点都是一个有自己 3-5 句独立正文段的小标题**——不是 bullet 列表。
→ 因此子要点要规划成「能独立成段展开」的小主题,而不是一句话能讲完的零散点。
【三级字段的具体要求】
- `section_title`(章节标题):高度概括的短语,6-15 字。每篇文章规划 3-5 个章节。
- `point_title`(小节标题):名词性短语,控制在 15 字以内,不要写成完整句子,不要带句末标点。每个章节规划 2-4 个小节。
- `sub_points`(子要点标题):名词性短语,<= 15 字,**不带句末标点**。每个小节规划 2-4 条子要点;如果该小节信息确实少到无法拆分子主题,可留 `[]`(此时只写小节级正文)。
【输出要求】
- 只输出一个 JSON 对象,不要任何解释文字,不要 markdown 代码块。
- 必须使用英文双引号 ",不要用中文引号 “”。
- 规划 3-5 个章节;material_ids 中的 ID 必须来自给定素材,没有合适素材时填 []。
【完整示例】
正确输出:
{
"title": "新能源汽车出口为何高速增长",
"sections": [
{
"section_title": "引言:出口数据创新高",
"key_points": [
{"point_title": "出口量同比增幅", "sub_points": ["2024 年累计出口规模", "同比增速对比 2023"]},
{"point_title": "全球市场排名变化", "sub_points": ["对欧出口跃升", "对东盟首次反超日韩"]}
],
"material_ids": ["m001"]
},
{
"section_title": "增长背后的三大动因",
"key_points": [
{"point_title": "产业链成本优势", "sub_points": ["电池原料端议价能力", "整车规模效应"]},
{"point_title": "海外政策利好", "sub_points": ["欧盟碳关税倒逼", "中东购车补贴"]},
{"point_title": "产品竞争力提升", "sub_points": ["智能化配置溢价", "出海车型迭代速度"]}
],
"material_ids": ["m002", "m003"]
},
{
"section_title": "结论与展望",
"key_points": [
{"point_title": "未来增长挑战", "sub_points": ["欧盟反补贴调查", "海外渠道建设成本"]},
{"point_title": "行业趋势判断", "sub_points": []}
],
"material_ids": ["m004"]
}
]
}"""
OUTLINE_USER = """写作意图:{user_intent}
文章类型:{article_type}
目标读者:{target_audience}
目标字数:{word_count_target}字{feedback_section}
可用素材摘要:
{materials_summary}
请规划文章大纲(3-5个章节),只输出 JSON 格式。"""
# ── 重新规划(基于现有大纲的编辑)─────────────────────────────────────────────
OUTLINE_REVISE_SYSTEM = """你是一名专业内容创作者(作家)。
你的目标:根据用户的修改要求,调整一份【已有的三级文章大纲】。
你的工作背景:你有十年内容创作经验,擅长精准理解修改意图并落实到大纲结构上。
你只能做以下事情:
1. 在「当前大纲」基础上,按「用户修改要求」做调整
你不能写正文,只输出调整后的大纲。
【修改原则】(最高优先级)
- 准确识别并落实用户意图,常见操作:新增/删除/合并/拆分章节或小节、调整顺序、修改标题、调整子要点。
- 只改用户明确提到的部分:用户没要求改动的章节、小节、子要点必须原样保留(标题、内容、material_ids 全部不变)。
- 新增内容时:紧扣写作意图,并尽量关联可用素材的 material_ids。
- 章节/小节/子要点数量完全由用户要求决定,没有上下限——用户要加就加、要减就减。
【严禁思考与表态】(最高优先级)
- 禁止输出任何思考、分析、规划过程,禁止 <think></think> 标签及其中内容。
- 禁止输出任何对用户说的话;收到输入后立即、直接输出最终 JSON。
【三级层级语义】(最高优先级)
- `section_title`(章节,`##` 二级标题):高度概括的短语,6-15 字。
- `point_title`(小节,`###` 三级标题):名词性短语,15 字以内,无句末标点;小节下会有一段概述正文。每章节 2-4 个小节。
- `sub_points`(子要点,`####` 四级标题):名词性短语,<= 15 字,无句末标点;**每条子要点会展开成一段独立正文**,所以要写成能成段的主题。每小节 2-4 条,信息少到无法拆时可留 `[]`。
【兼容历史大纲】
- 若「当前大纲」里的 `key_points` 是字符串数组(旧版 2 级结构),保留原值视为小节标题,
在补充 `sub_points: []` 后输出新格式:`{"point_title": "<原 string>", "sub_points": []}`。
- 用户修改时如要求"为某要点补充更详细的子项",就把对应小节的 sub_points 填上。
【输出要求】
- 只输出一个调整后的【完整】大纲 JSON 对象,不要解释文字,不要 markdown 代码块。
- 必须使用英文双引号 "。
- material_ids 中的 ID 必须来自给定素材,没有合适素材时填 []。
- 结构(嵌套三级):
{"title": "...", "sections": [{"section_title": "...", "key_points": [{"point_title": "...", "sub_points": ["..."]}], "material_ids": ["..."]}]}"""
OUTLINE_REVISE_USER = """写作意图:{user_intent}
文章类型:{article_type}
目标读者:{target_audience}
目标字数:{word_count_target}字
当前大纲(JSON):
{current_outline}
用户修改要求:{feedback}
可用素材摘要:
{materials_summary}
请在「当前大纲」基础上落实上述「用户修改要求」,未提到的章节保持原样,输出调整后的完整大纲 JSON。"""
# ── 用户自带大纲:LLM 兜底归一(确定性解析失败时才用)──────────────────────────
OUTLINE_NORMALIZE_SYSTEM = """你是一名大纲格式整理助手。
用户粘贴了一份已有的文章大纲(格式可能不规范),你的任务是把它原样转成结构化 JSON。
【最高原则:保真,绝不改写】
- 严格保留用户写的每一条标题文字,逐字照搬,不要润色、改写、翻译、增加或删除任何条目。
- 你只判断层级(哪条是章节、哪条是小节、哪条是子要点),不创作内容。
- 层级判断依据用户原文里的编号(一、/(一)/1./1.1)、Markdown 井号数、或缩进深度。
【三级结构】
- Level 1 章节 → section_title
- Level 2 小节 → key_points[].point_title
- Level 3 子要点 → key_points[].sub_points[](字符串数组)
- 用户大纲只有一级时,每条都是章节,key_points 留空 []。
- 用户大纲只有两级时,sub_points 留空 []。
【输出要求】
- 只输出一个 JSON 对象,不要解释文字,不要 markdown 代码块,必须用英文双引号。
- material_ids 一律输出 [](此步不关联素材)。
- 结构:{"title": "...", "sections": [{"section_title": "...", "key_points": [{"point_title": "...", "sub_points": ["..."]}], "material_ids": []}]}
- 用户大纲若包含一个总标题,放进 title;没有就留空字符串。"""
OUTLINE_NORMALIZE_USER = """用户粘贴的大纲原文:
{raw_outline}
请逐条保留原文,仅判断层级,输出结构化大纲 JSON。
/no_think"""
# 注:用户自带大纲的「素材关联」已改为确定性词重叠(writer_outline._assign_materials_heuristic),
# 零 LLM、零 <think> 等待,原 OUTLINE_MATERIAL_ASSIGN_* 提示词已废弃移除。
DRAFT_SECTION_SYSTEM = """你是一名专业内容创作者(作家)。
你的目标:根据大纲和素材,写出一段结构清晰、高质量的文章内容。
你的工作背景:你有十年内容创作经验,文字流畅,善于用事实说话。
你只能做以下事情:
1. 根据给定的章节要点和素材写这一段内容
2. 优先采用素材中的事实与数据;素材不足时可结合你的通用知识与常识补充论述,但须紧扣写作意图与章节主题,不要脱离主题杜撰具体的数字、人名、机构名与日期
你不能修改大纲,不能写其他章节,只写当前这一段。
【严禁思考与表态】(最高优先级)
- 禁止输出任何思考、分析、规划过程,禁止"让我想想""首先""我需要""根据写作要求"之类的过渡语。
- 禁止输出 <think></think> 标签及其中的任何内容。
- 禁止输出任何对用户说的话或对任务本身的评价,例如"我无法完成此任务""您提供的素材无法支撑写作""建议您提供……素材""素材与意图不匹配"等——这类话绝不允许出现在文章里。
- 无论素材是否充分,你都必须直接产出文章正文本身;收到输入后立即开始写正文(含 ### 小标题),不要有任何前置说明。
【结构要求】(三级结构,必须严格遵守)
- 「章节要点」用层级 bullet 列表给出:
- 主要 bullet(顶格)= 小节标题,对应 Markdown `###` 三级标题
- 缩进 bullet(带前导空格)= 该小节下的子要点,对应 Markdown `####` 四级标题
- **每个小节、每个子要点都要有自己的正文段,分两层展开**:
1. `### 小节标题` 下先写一段「概述/引入正文」(2-3 句),说明本小节要讨论什么、几个子要点之间的关系。
2. 然后对每个子要点:`#### 子要点标题` 单起一行,再展开 3-5 句具体论述(结合素材中的事实/数据)。
- 若小节**没有子要点**(缩进 bullet 为空):在 `### 小节标题` 下直接连贯成段论述,**不出现 ####**。
- 即使章节只有一个小节,也要为它写出对应的 `###` 标题。
- 标题层级严格对应:文章 `#` / 章节 `##`(系统注入,作家**不要输出**)/ 小节 `###` / 子要点 `####`。
- 不要输出 `#####` 或更深;这种深度不在结构里。
【输出要求】
- 直接返回这一段的内容(含 `### 小节标题` + 概述段 + `#### 子要点标题` + 各自正文),不要 JSON,不要解释。
- 不要写"以下是正文""本段内容如下"之类的开场白。
- 紧扣本章节主题,不要写「文章整体结构」中其他章节负责的内容,避免重复。
- 充分展开每一层:小节级 2-3 句概述,子要点级 3-5 句具体论述,尽量结合素材中的事实与数据说理。
- 【字数纪律,硬性要求】严格遵守用户给定的字数区间:既不要明显写不够,更不要超出上限。靠控制论述详略来卡字数,不要为凑字数注水,也不要为收尾而草草带过。"""
# ── 写作模式说明:注入 DRAFT_SECTION_USER 的 {mode_section} ───────────────────
# 章节无法基于素材写作时,作家在严格模式下输出的哨兵标记
SECTION_BLOCKED_MARKER = "[[SECTION_BLOCKED]]"
WRITER_MODE_LOOSE = """
【写作模式:宽松】
素材充分时优先采用素材;素材不足时可结合你的通用知识与常识补充论述,
但必须紧扣写作意图与本章节主题,不要脱离主题杜撰具体数字、人名、机构名。"""
WRITER_MODE_STRICT = """
【写作模式:严格依据素材】
本章节论述必须严格基于上方「相关素材」,不得使用素材之外的知识,不得杜撰任何事实与数据。
如果上方素材确实不足以支撑本章节的写作,不要勉强拼凑、不要写无关内容,
此时只输出一行:{marker} 一句话说明缺什么素材(例:{marker} 缺少关于XX的具体数据与案例),
此外不要输出任何内容。只要素材能支撑哪怕部分要点,就正常写作,不要输出该标记。""".format(
marker=SECTION_BLOCKED_MARKER
)
DRAFT_SECTION_USER = """文章标题:{article_title}
文章整体结构:
{outline_context}
当前章节:{section_title}
章节内的小节与子要点(层级 bullet 列表):
{key_points}
相关素材:
{section_materials}
{revision_section}{mode_section}
请写出「{section_title}」这一章节的内容,目标约 {target_words} 字,并**严格控制在 {min_words}~{max_words} 字之间**——不要明显少于下限,更绝不要超过上限。
按下面的结构两层展开写:
- 每个主要 bullet(顶格)→ `### 小节标题`,标题下先写 2-3 句概述/引入正文。
- 该小节的每个缩进 bullet(子要点)→ `#### 子要点标题`,标题下展开 3-5 句具体论述。
- 没有缩进 bullet 的小节,直接在 ### 标题下连贯成段论述,不出现 ####。
论述层次清晰、内容充实,但务必在上述字数上限内完成:宁可精炼也不要为凑字数注水。"""
# ── 用户局部修改:识别意见指向的章节范围 ───────────────────────────────────────
DRAFT_REVISE_SCOPE_SYSTEM = """你是一名编辑助理。用户对一篇已成稿的文章提出了一句修改意见,你要判断这条意见要改文章里的哪些「章节」,以及每个章节具体改什么。
文章由若干带编号的章节组成(编号从 0 开始)。
【判断规则】(最高优先级)
1. 定位意见指向的章节:
- 序号:「第一段 / 第一部分 / 第1章」→ 编号 0,「第二段」→ 编号 1,依此类推;
- 位置:「开头 / 引言 / 导语」→ 第一个章节,「结尾 / 结论 / 最后一段」→ 最后一个章节;
- 直接点名某个章节的标题或主题。
2. 对每个命中的章节,判断用户要改什么:
- 若要改这一章节的**标题**(如「把第一章的标题改为简介」「第二部分改名叫…」),把新标题文字放进 new_title;否则 new_title 写 null。
- 若要改这一章节的**正文内容**(润色 / 补充 / 精简 / 重写等),rewrite_body 写 true;若只改标题、不动正文,rewrite_body 写 false。
3. 下列情况属于整体性、或会改变文章结构,一律令 whole_article=true、targets 留空:
- 整体性:「全文都改」「通篇润色」「整体语气更正式」「每一部分都精简」;
- 结构性:新增章节、删除章节、调整章节顺序、合并 / 拆分章节;
- 改**文章总标题**(注意:是整篇文章的标题,不是某个章节的标题)。
4. 拿不准、无法明确定位到具体章节时,一律 whole_article=true(交给整篇重写更安全)。
【严禁思考与表态】
- 不要输出任何思考、解释或对用户说的话;收到输入后立即直接输出最终 JSON。
【输出要求】
- 只输出一个 JSON 对象,不要解释文字,不要 markdown 代码块,必须用英文双引号。
- new_title 没有就写 null;targets 为空数组表示走整篇重写。
- 结构:{"whole_article": false, "targets": [{"index": 0, "new_title": "简介", "rewrite_body": false}]}"""
DRAFT_REVISE_SCOPE_USER = """文章共有 {n} 个章节,编号与标题如下:
{sections}
用户的修改意见:{note}
请判断这条意见要改哪些章节、各自怎么改(标题 / 正文),按要求只输出 JSON。"""
# ── 用户局部修改:只重写命中的单个章节(保留其余内容)─────────────────────────
DRAFT_REVISE_SECTION_USER = """文章标题:{article_title}
当前章节:{section_title}
章节内的小节与子要点(层级 bullet 列表):
{key_points}
相关素材:
{section_materials}
这一章节的现有内容如下:
{existing_text}
用户对本章节的修改意见:{note}
请**只针对用户意见**修改这一章节:
- 落实用户意见的同时,未被要求改动的内容、事实与措辞尽量保留原样,不要借机重写整段。
- 保留原有的「### 小节标题 / #### 子要点标题」两级结构,不要新增或删除小节/子要点,也不要把 #### 改成 bullet。
- 不要输出 # 或 ##(文章标题、章节标题由系统添加)。
- 直接返回修改后的完整章节内容(含 ### 与 #### 两级标题及各自正文段),不要解释、不要前置说明。"""
DRAFT_EXPAND_USER = """文章标题:{article_title}
当前章节:{section_title}
章节内的小节与子要点(层级 bullet 列表):
{key_points}
相关素材:
{section_materials}
这一章节已有内容如下:
{existing_text}
以上内容篇幅不足。请在保留原意、事实和「### 小节 / #### 子要点」两级标题结构的基础上重写并扩充这一章节,使内容不少于 {target_words} 字。
要求:
- 补充更多来自素材的事实、数据与分析,让每一层都论述更充分、更具体。
- 保留原有的 ### 小节标题与 #### 子要点标题;不要新增或删除小节/子要点,也不要把 #### 改成 bullet。
- 不要输出 # 或 ##(文章标题、章节标题由系统添加)。
- 直接返回扩充后的完整章节内容(含 ### 与 #### 两层标题及各自正文段),不要解释。"""
DRAFT_COMPRESS_USER = """文章标题:{article_title}
当前章节:{section_title}
章节内的小节与子要点(层级 bullet 列表):
{key_points}
相关素材:
{section_materials}
这一章节已有内容如下:
{existing_text}
以上内容篇幅明显偏长。请在保留原意、关键事实和「### 小节 / #### 子要点」两级标题结构的基础上**大幅精简**改写这一章节,使内容**压到 {target_words} 字以内**——这是硬性上限,宁可删减细节也绝不能超过。
要求:
- 这是「压缩」任务,不是「重写扩充」:必须比原文明显更短。大胆删减冗余表述、合并重复论点、砍掉次要细节与铺陈,只保留关键事实、数据与核心结论。
- 保留原有的 ### 小节标题与 #### 子要点标题;不要新增或删除小节/子要点,也不要把 #### 改成 bullet。
- 不要输出 # 或 ##(文章标题、章节标题由系统添加)。
- 直接返回精简后的完整章节内容(含 ### 与 #### 两层标题及各自正文段),不要解释。"""
@@ -0,0 +1,70 @@
from .base import BaseSearchProvider, SearchResult
from .demo_search import DemoSearchProvider
from .duckduckgo_search import DuckDuckGoSearchProvider
from .internet_search import InternetSearchProvider
from .intranet_stub import IntranetSearchProvider, normalize_intranet_timeout, normalize_intranet_verify_ssl
from .skill_search import SkillSearchProvider
def get_search_provider(ai_writing_config: dict) -> BaseSearchProvider:
"""
config.yaml 中配置:
ai_writing:
search_provider: internet # internet(默认,DDG) / intranet / tavily / demo
intranet_search_url: http://10.106.57.180:7863/knowledge_base/search_docs_es
intranet_knowledge_base: samples
intranet_search_timeout: 300 # 内网检索超时秒数,最少 300 秒
intranet_verify_ssl: false # 内网 HTTPS 自签名证书场景默认关闭证书校验
ddg_region: "cn-zh" # DuckDuckGo 区域,默认 cn-zh
internet 模式:DuckDuckGo 为主搜索(免 API Key),失败时 fallback 到 demo 演示素材。
"""
cfg = ai_writing_config or {}
provider = cfg.get("search_provider", "internet")
if provider == "intranet":
return IntranetSearchProvider(
base_url=cfg.get("intranet_search_url", ""),
knowledge_base_name=cfg.get("intranet_knowledge_base", "samples"),
timeout=normalize_intranet_timeout(cfg.get("intranet_search_timeout")),
verify_ssl=normalize_intranet_verify_ssl(cfg.get("intranet_verify_ssl")),
)
if provider == "tavily":
return _FallbackSearchProvider(InternetSearchProvider(), DemoSearchProvider())
if provider == "demo":
return DemoSearchProvider()
# 默认 internet 模式:DuckDuckGo + demo fallback
region = cfg.get("ddg_region", "cn-zh")
return _FallbackSearchProvider(DuckDuckGoSearchProvider(region=region), DemoSearchProvider())
class _FallbackSearchProvider(BaseSearchProvider):
"""当主 provider 返回空结果时自动切换到 fallback provider。"""
def __init__(self, primary: BaseSearchProvider, fallback: BaseSearchProvider):
self._primary = primary
self._fallback = fallback
@property
def errors(self) -> list[str]:
"""聚合主/兜底 provider 的检索异常,供 researcher 节点取用。"""
return list(getattr(self._primary, "errors", [])) + list(getattr(self._fallback, "errors", []))
async def search(self, query: str, max_results: int = 5, **kwargs):
results = await self._primary.search(query, max_results=max_results, **kwargs)
if not results:
results = await self._fallback.search(query, max_results=max_results, **kwargs)
return results
async def health_check(self) -> bool:
return await self._primary.health_check() or await self._fallback.health_check()
__all__ = [
"BaseSearchProvider", "SearchResult",
"InternetSearchProvider", "IntranetSearchProvider",
"DemoSearchProvider", "DuckDuckGoSearchProvider",
"SkillSearchProvider",
"get_search_provider",
]
@@ -0,0 +1,84 @@
import re
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import List
# 复合检索词里常见的「话题/类别后缀」——核心实体后面跟的修饰词。内网 ES 对
# 「实体+话题」这类长词常检不出(如「特朗普竞选」0 条),但「实体」本身能检出
# (「特朗普」30 条)。剥掉这些后缀回退到核心实体重试,能救回大量检索词。
_TOPIC_SUFFIXES = (
"竞选", "诉讼", "法律", "政策", "主张", "纲领", "动向", "动态", "影响", "分析",
"进展", "现状", "情况", "问题", "事件", "活动", "关系", "布局", "态势", "格局",
"趋势", "背景", "历史", "观点", "评价", "报道", "新闻", "研究", "报告", "概况",
"走势", "前景", "措施", "方案", "计划", "战略", "改革", "发展",
)
def simplify_query(query: str) -> str:
"""把一个「检不出」的复合检索词简化成更核心、更短的检索词,供 0 结果时重试。
规则(无需大模型,纯启发式):
1. 多词(含空格)→ 取第一个词(通常是核心实体),如「美国政局 特朗普」→「美国政局」;
2. 单词复合 → 反复剥掉结尾的话题后缀,保留核心实体,如「特朗普法律诉讼」→「特朗普」、
「特朗普竞选」→「特朗普」。
返回空串 = 无法进一步简化(调用方据此不再重试,避免空转)。
"""
s = (query or "").strip()
if not s:
return ""
# 1) 多词:取第一个词
if re.search(r"\s", s):
first = re.split(r"\s+", s)[0].strip()
if first and first != s and len(first) >= 2:
return first
# 2) 单词复合:循环剥离结尾话题后缀
changed = s
while True:
stripped = changed
for suf in sorted(_TOPIC_SUFFIXES, key=len, reverse=True):
if stripped.endswith(suf) and len(stripped) - len(suf) >= 2:
stripped = stripped[: -len(suf)]
break
if stripped == changed:
break
changed = stripped
if changed != s and len(changed) >= 2:
return changed
return ""
@dataclass
class SearchResult:
"""统一搜索结果格式 —— 内外网共用"""
title: str
content: str
source: str
published_at: str
url: str = ""
relevance_score: float = 0.0
source_type: str = "internet"
recUuid: str = ""
extra_metadata: dict = field(default_factory=dict)
class BaseSearchProvider(ABC):
"""搜索提供者抽象基类。
对接内网步骤:
1. 继承此类,创建 IntranetSearchProvider
2. 实现 search() —— 调用内网 API,将响应映射到 SearchResult
3. 在 config.yaml 中设置 ai_writing.search_provider: intranet
4. 无需修改任何 Agent 代码
"""
@abstractmethod
async def search(
self,
query: str,
max_results: int = 5,
date_from: str = "",
date_to: str = "",
) -> List[SearchResult]: ...
@abstractmethod
async def health_check(self) -> bool: ...
@@ -0,0 +1,183 @@
"""离线演示搜索提供者 —— 当无法访问互联网/内网时返回模拟素材,供测试完整写作流程。"""
from __future__ import annotations
import hashlib
from typing import List
from .base import BaseSearchProvider, SearchResult
# 演示素材库:按话题分类,用于关键词模糊匹配
_DEMO_CORPUS = [
{
"keywords": ["新能源", "电动车", "汽车", "ev", "electric"],
"items": [
{
"title": "2025年新能源汽车市场规模突破万亿,渗透率达45%",
"content": "据中国汽车工业协会数据,2025年前三季度新能源汽车累计销量超过850万辆,同比增长32%,市场渗透率达到45.3%。比亚迪、吉利、长城等头部企业份额持续集中,纯电与插混比例趋近5:5。",
"source": "中国汽车工业协会",
"published_at": "2025-10-15",
"relevance_score": 0.95,
},
{
"title": "固态电池量产进入倒计时:多家车企宣布2026年装车计划",
"content": "宁德时代、比亚迪、丰田同步推进固态电池量产。固态电池能量密度可达400Wh/kg,较现有液态锂电池提升60%,续航里程有望突破1000公里。成本仍是主要瓶颈,预计量产初期每度电成本高出30%。",
"source": "电池中国网",
"published_at": "2025-09-20",
"relevance_score": 0.88,
},
{
"title": "充电基础设施缺口分析:农村地区桩车比仅1:12",
"content": "截至2025年8月,全国充电桩保有量达1120万根,城市地区桩车比约1:2.8,但农村及县域地区桩车比仅1:12,制约新能源汽车下沉市场。国家电网计划2026年前新增农村快充站3万座。",
"source": "中国充电联盟",
"published_at": "2025-08-30",
"relevance_score": 0.82,
},
],
},
{
"keywords": ["人工智能", "ai", "大模型", "llm", "机器学习", "深度学习"],
"items": [
{
"title": "国内大模型进入「百亿参数普惠化」阶段,推理成本下降90%",
"content": "2025年第三季度,国内主要大模型服务商将百亿参数模型推理价格降至每百万token不足1元,较2024年同期下降90%。开源生态加速,Qwen3、DeepSeek-V3等模型在多项基准测试中超越GPT-4o。",
"source": "中国信通院",
"published_at": "2025-10-08",
"relevance_score": 0.93,
},
{
"title": "企业AI应用落地白皮书:制造业ROI最高达300%",
"content": "调研覆盖500家企业的白皮书显示,AI在质检、排产、预测性维护三个场景ROI最高,部分制造企业ROI超300%。阻碍因素:数据孤岛(67%)、人才不足(54%)、安全合规(48%)。",
"source": "麦肯锡中国",
"published_at": "2025-09-12",
"relevance_score": 0.87,
},
{
"title": "AI写作助手用户规模达2.3亿,内容质量争议持续",
"content": "国内AI写作工具月活用户突破2.3亿,覆盖学术论文、营销文案、新闻报道等场景。争议焦点:AI生成内容的版权归属、事实准确性(幻觉率约15%)、对写作从业者就业影响。",
"source": "艾瑞咨询",
"published_at": "2025-10-01",
"relevance_score": 0.79,
},
],
},
{
"keywords": ["碳中和", "双碳", "绿色", "低碳", "碳排放", "可再生能源", "光伏", "风电"],
"items": [
{
"title": "光伏装机量突破900GW,度电成本降至0.18元",
"content": "国家能源局数据显示,截至2025年9月,全国光伏累计装机量达912GW,占总装机的28%。光伏度电成本已降至0.18元,首次低于煤电基准价,推动更多省份出现「光伏平价」区域。",
"source": "国家能源局",
"published_at": "2025-10-12",
"relevance_score": 0.92,
},
{
"title": "碳市场价格突破200元/吨,倒逼高耗能行业转型",
"content": "全国碳排放权交易市场碳价已突破200元/吨,较2024年底上涨65%。水泥、电解铝、造纸等高耗能行业面临显著成本压力,碳减排投入年均增速达40%。",
"source": "上海环境能源交易所",
"published_at": "2025-09-28",
"relevance_score": 0.85,
},
],
},
{
"keywords": ["医疗", "健康", "药物", "生物", "医药", "病"],
"items": [
{
"title": "AI辅助诊断落地三甲医院,影像科漏诊率降低23%",
"content": "北京协和、上海瑞金等20家三甲医院数据显示,引入AI辅助诊断系统后,肺结节、眼底病变早期漏诊率降低23%,放射科医生平均阅片时间减少40%。监管层面,NMPA已批准38款AI医疗器械。",
"source": "医学界",
"published_at": "2025-09-18",
"relevance_score": 0.91,
},
],
},
{
"keywords": ["经济", "GDP", "贸易", "出口", "产业", "制造"],
"items": [
{
"title": "2025年前三季度GDP同比增长5.1%,消费贡献率提升至58%",
"content": "国家统计局公布,2025年前三季度GDP同比增长5.1%,最终消费对经济增长贡献率达58%,较去年同期提升8个百分点。工业增加值增长5.8%,其中装备制造业增长9.2%,成重要支撑。",
"source": "国家统计局",
"published_at": "2025-10-18",
"relevance_score": 0.90,
},
{
"title": "跨境电商出口额突破2.4万亿元,东南亚成最大增量市场",
"content": "商务部数据显示,2025年前三季度跨境电商出口额达2.4万亿元,同比增长28%。东南亚市场增速最快(+45%),中东、南美紧随其后。Temu、速卖通、Shopee三平台合计占出口份额约62%。",
"source": "商务部",
"published_at": "2025-10-05",
"relevance_score": 0.84,
},
],
},
]
# 通用兜底素材(与任意查询都能凑合搭配)
_FALLBACK_ITEMS = [
{
"title": "行业研究方法论:如何构建有效的一手与二手数据体系",
"content": "高质量行业报告需整合政府统计、上市公司财报、行业协会数据与专家访谈。一手调研样本量建议≥200份,二手数据优先选用权威机构发布的年度报告与季度白皮书,并注明数据时效性与口径差异。",
"source": "产业研究院",
"published_at": "2025-08-15",
"relevance_score": 0.55,
},
{
"title": "政策解读:2025年产业发展专项支持资金管理办法",
"content": "工信部发布2025年产业发展专项资金管理办法,重点支持「专精特新」企业数字化改造、绿色制造和关键技术攻关。单项目最高补贴1000万元,要求申报企业研发投入不低于营收3%。",
"source": "工信部",
"published_at": "2025-07-20",
"relevance_score": 0.50,
},
{
"title": "市场竞争格局分析:头部集中与长尾分散并存",
"content": "多个新兴行业呈现「哑铃型」竞争格局:头部3-5家企业合计市占率超60%,长尾中小企业依靠细分场景差异化生存,中间层企业面临最大竞争压力。并购整合预期升温,2025年战略性并购交易同比增长35%。",
"source": "普华永道",
"published_at": "2025-09-01",
"relevance_score": 0.48,
},
]
def _score_topic(query: str, keywords: list[str]) -> int:
"""简单关键词匹配打分"""
q = query.lower()
return sum(1 for kw in keywords if kw in q)
class DemoSearchProvider(BaseSearchProvider):
"""离线演示搜索提供者:根据查询关键词从内置语料库返回模拟素材。
仅用于开发测试;生产环境应配置 intranet 提供者。
"""
async def search(self, query: str, max_results: int = 5, **kwargs) -> List[SearchResult]:
best_topic = max(_DEMO_CORPUS, key=lambda t: _score_topic(query, t["keywords"]), default=None)
best_score = _score_topic(query, best_topic["keywords"]) if best_topic else 0
items = []
if best_score > 0 and best_topic:
items.extend(best_topic["items"])
# 用通用素材补齐
for fb in _FALLBACK_ITEMS:
if len(items) >= max_results:
break
items.append(fb)
results = []
for i, it in enumerate(items[:max_results]):
url_hash = hashlib.md5(it["title"].encode()).hexdigest()[:8]
results.append(SearchResult(
title=it["title"],
content=it["content"],
source=it["source"],
published_at=it["published_at"],
url=f"https://demo.internal/{url_hash}",
relevance_score=it["relevance_score"],
source_type="demo",
recUuid=f"demo-{i:03d}",
))
return results
async def health_check(self) -> bool:
return True
@@ -0,0 +1,81 @@
"""DuckDuckGo 搜索提供者 —— 免 API Key 互联网搜索。"""
from __future__ import annotations
import asyncio
import logging
from typing import List
from .base import BaseSearchProvider, SearchResult
logger = logging.getLogger(__name__)
class DuckDuckGoSearchProvider(BaseSearchProvider):
"""使用 DuckDuckGo 进行互联网搜索,无需 API Key。"""
def __init__(self, region: str = "cn-zh", max_timeout: int = 120):
self.region = region
self.max_timeout = max_timeout
# 收集本次运行的检索异常,供 researcher 节点取出并提示用户
self.errors: list[str] = []
async def search(
self,
query: str,
max_results: int = 5,
date_from: str = "",
date_to: str = "",
) -> List[SearchResult]:
try:
results = await asyncio.to_thread(
self._sync_search, query, max_results
)
return results
except Exception as e:
logger.warning("DuckDuckGo search failed for query=%r: %s", query, e)
self.errors.append(f"{type(e).__name__}: {e}")
return []
def _sync_search(self, query: str, max_results: int) -> List[SearchResult]:
try:
from ddgs import DDGS
except ImportError:
logger.error("ddgs not installed. Run: uv add ddgs")
self.errors.append("ImportError: ddgs 未安装")
return []
ddgs = DDGS(timeout=self.max_timeout)
try:
raw = ddgs.text(
query,
region=self.region,
safesearch="moderate",
max_results=max_results,
)
items = list(raw) if raw else []
except Exception as e:
logger.warning("DDGS.text failed: %s", e)
self.errors.append(f"{type(e).__name__}: {e}")
return []
results = []
for item in items:
url = item.get("href", item.get("link", ""))
source = url.split("/")[2] if url and "/" in url else "web"
results.append(SearchResult(
title=item.get("title", ""),
content=item.get("body", item.get("snippet", ""))[:500],
source=source,
published_at=item.get("published", ""),
url=url,
relevance_score=0.75,
source_type="internet",
))
return results
async def health_check(self) -> bool:
try:
results = await self.search("test", max_results=1)
return len(results) > 0
except Exception:
return False
@@ -0,0 +1,66 @@
import asyncio
import logging
from typing import List
from .base import BaseSearchProvider, SearchResult
logger = logging.getLogger(__name__)
class InternetSearchProvider(BaseSearchProvider):
"""互联网搜索,使用项目已有的 Tavily 搜索工具。"""
async def search(
self,
query: str,
max_results: int = 5,
date_from: str = "",
date_to: str = "",
) -> List[SearchResult]:
try:
results = await asyncio.to_thread(self._sync_search, query, max_results)
return results
except Exception as e:
logger.warning("internet search failed for query=%r: %s", query, e)
return []
def _sync_search(self, query: str, max_results: int) -> List[SearchResult]:
from deerflow.config import get_app_config
try:
from tavily import TavilyClient
except ImportError:
logger.warning("tavily not installed, falling back to demo search")
return []
config = get_app_config().get_tool_config("web_search")
api_key = None
if config is not None and "api_key" in config.model_extra:
api_key = config.model_extra.get("api_key")
if not api_key:
logger.warning("Tavily API key not configured, falling back to demo search")
return []
client = TavilyClient(api_key=api_key)
res = client.search(query, max_results=max_results)
results = []
for item in res.get("results", []):
content = item.get("content", "")
results.append(SearchResult(
title=item.get("title", ""),
content=content[:500],
source=item.get("url", "").split("/")[2] if "/" in item.get("url", "") else "web",
published_at=item.get("published_date", ""),
url=item.get("url", ""),
relevance_score=item.get("score", 0.0),
source_type="internet",
))
return results
async def health_check(self) -> bool:
try:
results = await self.search("test", max_results=1)
return True
except Exception:
return False
@@ -0,0 +1,282 @@
"""内网知识库搜索适配器 —— 对接 ES 检索接口 search_docs_es。"""
from __future__ import annotations
import logging
import time
from .base import BaseSearchProvider, SearchResult, simplify_query
logger = logging.getLogger(__name__)
# 内网知识库默认检索接口与知识库名(可经 config.yaml 的 ai_writing 段覆盖)
_DEFAULT_ENDPOINT = "http://10.106.57.180:7863/knowledge_base/search_docs_es"
_DEFAULT_KB = "samples"
# 内网检索最少等待 5 分钟;该接口经常慢返回,低于这个值会造成素材收集误判为空。
_MIN_TIMEOUT_SECONDS = 300
_DEFAULT_TIMEOUT_SECONDS = 600
# 内网 HTTPS 检索服务常使用自签名/内部 CA 证书,默认跳过证书校验避免 SSL 证书链错误。
_DEFAULT_VERIFY_SSL = False
# 单条原始响应体最大保留长度,避免把超大响应整段灌进前端时间线
_RAW_SNIPPET_LIMIT = 2000
def normalize_intranet_timeout(timeout: object, default: int = _DEFAULT_TIMEOUT_SECONDS) -> int:
"""返回内网检索超时秒数,并强制不低于 5 分钟。"""
try:
value = int(timeout)
except (TypeError, ValueError):
value = default
return max(value, _MIN_TIMEOUT_SECONDS)
def normalize_intranet_verify_ssl(value: object, default: bool = _DEFAULT_VERIFY_SSL) -> bool:
"""返回内网检索是否校验 SSL 证书,兼容 config.yaml 里的 bool / 字符串写法。"""
if isinstance(value, bool):
return value
if value is None:
return default
if isinstance(value, (int, float)):
return bool(value)
if isinstance(value, str):
normalized = value.strip().lower()
if normalized in {"1", "true", "yes", "on"}:
return True
if normalized in {"0", "false", "no", "off"}:
return False
return default
def _pick(d: dict, keys: tuple) -> str:
"""从结果项里按候选字段名取第一个非空值(两套接口字段名不同,做并集兼容)。"""
for k in keys:
v = d.get(k)
if isinstance(v, str) and v.strip():
return v.strip()
if v not in (None, "") and not isinstance(v, (dict, list)):
return str(v).strip()
return ""
def _raw_snippet(body: str) -> str:
"""Return a bounded raw response snippet for diagnostics."""
body = (body or "").strip()
if not body:
return ""
if len(body) > _RAW_SNIPPET_LIMIT:
return body[:_RAW_SNIPPET_LIMIT] + "…(响应体过长,已截断)"
return body
class IntranetSearchProvider(BaseSearchProvider):
"""内网知识库搜索接口适配器。
接口:POST {endpoint}
请求体:{"query": "...", "knowledge_base_name": "samples", "ts": "yes"}
响应体:[{"page_content": "...", "metadata": {m_title, content, recUuid, m_publish, source1}}]
"""
def __init__(
self,
base_url: str = "",
knowledge_base_name: str = _DEFAULT_KB,
timeout: int = _DEFAULT_TIMEOUT_SECONDS,
verify_ssl: bool = _DEFAULT_VERIFY_SSL,
**_ignored,
):
self.endpoint = base_url or _DEFAULT_ENDPOINT
self.knowledge_base_name = knowledge_base_name or _DEFAULT_KB
# 内网 ES 接口很慢,兜底检索超时默认 10 分钟,且无论配置如何至少 5 分钟。
self.timeout = normalize_intranet_timeout(timeout)
self.verify_ssl = normalize_intranet_verify_ssl(verify_ssl)
# 收集本次运行的检索异常,供 researcher 节点取出并提示用户(ES 波动等)
self.errors: list[str] = []
# 解析失败时收集的原始响应体,供前端「错误返回结果」折叠展示
self.raw_responses: list[str] = []
# 每一次真实 HTTP 调用的诊断明细。search() 可能会因 0 结果触发简化词重试,
# 因此一个业务关键词可能对应多条 calls。
self.calls: list[dict] = []
def _record_raw(self, body: str) -> None:
"""收集解析失败 / 结构异常时的原始响应体,供前端折叠查看。"""
snippet = _raw_snippet(body)
if snippet:
self.raw_responses.append(snippet)
async def search(self, query: str, max_results: int = 5, **kwargs) -> list[SearchResult]:
results = await self._search_once(query, max_results)
# 0 结果兜底:复合检索词常检不出(如「特朗普竞选」),换成更核心的检索词重试一次
# (「特朗普竞选」→「特朗普」)。仅在首检为空、且能简化出不同的词时才重试。
if not results:
simpler = simplify_query(query)
if simpler and simpler != query:
logger.info("intranet search empty for %r, retry with simplified %r", query, simpler)
results = await self._search_once(simpler, max_results)
return results
async def _search_once(self, query: str, max_results: int = 5) -> list[SearchResult]:
import httpx
payload = {
"query": query,
"knowledge_base_name": self.knowledge_base_name,
"ts": "yes",
}
# 先拿到原始响应文本,JSON 解析失败时把它原样回传前端便于定位接口返回了什么
raw_text = ""
started = time.monotonic()
call: dict = {
"query": query,
"endpoint": self.endpoint,
"knowledge_base_name": self.knowledge_base_name,
"max_results": max_results,
"status": "pending",
"ok": False,
"count": 0,
"verify_ssl": self.verify_ssl,
}
# 排查用:每次真实调用都打一行请求明细(端点 / 知识库 / 检索词 / 超时),
# 内网复现时直接看后端日志即可知道"到底请求了哪个地址、用什么参数"。
logger.info(
"[intranet-search] POST endpoint=%s kb=%s timeout=%ss verify_ssl=%s query=%r",
self.endpoint, self.knowledge_base_name, self.timeout, self.verify_ssl, query,
)
try:
# trust_env=False:**关键**。内网 ES 是内网地址,但本部署的模型走公网,
# 服务器通常设了 HTTP_PROXY/HTTPS_PROXY 出公网;httpx 默认 trust_env=True
# 会把这个内网请求也套用公网代理 → 代理到不了内网 IP → 连接被重置/空回复,
# 表现为「接口异常」。强制忽略代理 env、直连内网(与 multi_agent.py 的回环
# 调用同款修法)。
# verify=False:内网 HTTPS 常见自签名/内部 CA 证书;这里仅跳过本内网检索端点的证书校验。
async with httpx.AsyncClient(timeout=self.timeout, trust_env=False, verify=self.verify_ssl) as client:
resp = await client.post(self.endpoint, json=payload)
call["http_status"] = getattr(resp, "status_code", None)
resp.raise_for_status()
raw_text = resp.text
data = resp.json()
except httpx.HTTPStatusError as e:
# 非 2xx:接口有响应但状态码异常,把响应体一并暴露给前端
body_for_log = e.response.text if e.response is not None else ""
logger.warning(
"[intranet-search] HTTP error endpoint=%s query=%r status=%s body=%s",
self.endpoint, query, getattr(e.response, "status_code", None), _raw_snippet(body_for_log),
)
message = f"{type(e).__name__}: {e}"
self.errors.append(message)
call.update({
"status": "http_error",
"error": message,
"http_status": getattr(e.response, "status_code", None),
})
snippet = _raw_snippet(body_for_log)
if snippet:
call["raw_response"] = snippet
self._record_raw(body_for_log)
return []
except Exception as e:
# 连接失败 / 超时 / JSON 解析失败等;JSON 解析失败时 raw_text 已是接口响应体。
# 打出异常类型,便于区分 ConnectError / ConnectTimeout / ReadTimeout /
# RemoteProtocolError(空回复) / JSONDecodeError(返回非 JSON) 等具体根因。
logger.warning(
"[intranet-search] request failed endpoint=%s query=%r error=%s: %s",
self.endpoint, query, type(e).__name__, e,
)
message = f"{type(e).__name__}: {e}"
self.errors.append(message)
call.update({"status": "error", "error": message})
snippet = _raw_snippet(raw_text)
if snippet:
call["raw_response"] = snippet
self._record_raw(raw_text)
return []
finally:
call["elapsed_ms"] = int((time.monotonic() - started) * 1000)
# 非 pending 表示已经在异常分支写好;成功分支会在 return 前覆盖并追加。
if call.get("status") != "pending":
self.calls.append(call)
# 正常情况下接口直接返回数组;兼容包了一层 data/results 的结构(含工作正常的
# knowledge-search-v2:{"success":true,"results":[...]})。
if isinstance(data, list):
items = data
elif isinstance(data, dict):
if "success" in data:
call["response_success"] = bool(data.get("success"))
if "count" in data:
call["response_count"] = data.get("count")
# 接口显式标失败时把整体回传前端便于定位
if data.get("success") is False:
message = f"接口返回 success=false:{str(data.get('error') or '')[:200]}"
self.errors.append(message)
call.update({"status": "success_false", "error": message})
snippet = _raw_snippet(raw_text)
if snippet:
call["raw_response"] = snippet
self.calls.append(call)
self._record_raw(raw_text)
return []
items = data.get("data") or data.get("results") or data.get("documents") or []
else:
# 返回结构既不是数组也不是已知 dict 包装:视为异常,把原始响应回传前端
logger.warning("intranet search unexpected response type for query=%r: %s", query, type(data).__name__)
message = f"返回结构异常:期望数组,实际为 {type(data).__name__}"
self.errors.append(message)
call.update({"status": "bad_shape", "error": message})
snippet = _raw_snippet(raw_text)
if snippet:
call["raw_response"] = snippet
self.calls.append(call)
self._record_raw(raw_text)
return []
logger.info(
"[intranet-search] OK endpoint=%s query=%r http_status=%s raw_items=%s",
self.endpoint, query, call.get("http_status"), len(items) if isinstance(items, list) else 0,
)
results: list[SearchResult] = []
for i, item in enumerate(items[:max_results]):
if not isinstance(item, dict):
continue
# 字段名做并集兼容两套接口:
# 老 ES: {page_content, metadata:{m_title, content, recUuid, m_publish, source1}}
# knowledge-search-v2:{title, content_preview, url, recUuid, source_category, publish_time, relevance_score}
md = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
merged = {**md, **item} if md else item
content = _pick(merged, ("content", "content_preview", "page_content", "text", "summary"))
title = _pick(merged, ("title", "m_title", "name", "doc_title"))
if not content and not title:
continue
try:
score = float(merged.get("relevance_score"))
except (TypeError, ValueError):
# 接口未返回相关度分值:按返回顺序赋递减分以保留排序
score = max(0.5, 0.95 - i * 0.03)
results.append(SearchResult(
title=title or "(无标题)",
content=str(content)[:500],
source=_pick(merged, ("source_category", "source1", "source", "source_name", "kb_name")) or "内网知识库",
published_at=_pick(merged, ("publish_time", "m_publish", "published_at", "date")),
# 工作接口直接给了 url;老 ES 没有 url(由前端依据 recUuid 拼接),保持空串
url=_pick(merged, ("url",)),
relevance_score=score,
source_type="intranet",
recUuid=_pick(merged, ("recUuid", "rec_uuid", "id")),
))
call.update({
"status": "ok" if results else "empty",
"ok": True,
"count": len(results),
"item_count": len(items) if isinstance(items, list) else 0,
})
if not results:
snippet = _raw_snippet(raw_text)
if snippet:
call["raw_response"] = snippet
self.calls.append(call)
return results
async def health_check(self) -> bool:
try:
await self.search("测试", max_results=1)
return True
except Exception:
return False
@@ -0,0 +1,229 @@
"""技能选择器:根据用户意图 + 输入,从启用的 Skills 里挑出按相关度排序的若干个。
注意:这个模块**只负责选择技能,不直接产出素材**。
真正的素材产出由 researcher 节点用每个 skill 的描述去编排真实 web/intranet 检索。
流程(对应素材确认卡上的"技能检索"按钮):
1) list_skills 事件 —— 列出当前启用的全部 skill
2) skill_select_chunk 事件 —— LLM 流式打字 + <think></think> 分离(前端打字机展示)
3) select_skills 事件 —— LLM 给出的排序结果(结构化字段,写到 SkillStepsCard 里)
下游 researcher 节点拿到 selected_skills 后,**按顺序**:
- 用 skill.description + user_query 生成针对性 query
- 调真实 web search provider 执行
- 累积素材达到阈值就停(推 stop_early)
"""
from __future__ import annotations
import logging
import time
from typing import Callable, List, Optional
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.runnables import RunnableConfig
from ..nodes._utils import (
ThinkTagParser,
_content_to_text,
get_model,
parse_json,
reasoning_delta,
safe_get_stream_writer,
)
logger = logging.getLogger(__name__)
_SELECT_SKILLS_SYSTEM = """你是一名情报研究员,需要从可用「技能」中挑出对当前检索任务最有帮助的若干个,并按相关度从高到低排序。
技能是一段封装好的指令 / 知识 / 检索策略,每个技能有 name 和 description。
【输出要求】
- 只输出一个 JSON 对象,不要 markdown 代码块。
- 必须使用英文双引号。
- selected_skills 中的 name 必须严格来自下方"可用技能"列表,不要编造,按相关度从高到低排序。
- 如果用户输入里明确点名了某个技能(按 name 完全匹配),把它排在第一位。
- 至少选 1 个,最多选 {max_select} 个。
【完整示例】
{{"selected_skills": ["platform-sales-data", "industry-report"], "reason": "用户想查各平台销量,平台销量技能最相关"}}"""
_SELECT_SKILLS_USER = """写作意图:{user_intent}
用户补充输入:{user_query}
可用技能(共 {skill_count} 个):
{skill_list}
请从中按相关度从高到低选出最多 {max_select} 个技能。
只输出 JSON:
{{"selected_skills": ["name1", "name2"], "reason": "为什么选这些 + 排序依据"}}"""
EmitStepFn = Callable[[dict], None]
class SkillPicker:
"""从启用的 Skills 中流式选择按相关度排序的若干个供下游编排使用。
构造参数:
config: LangGraph runnable config(用于创建 model)
model_name: 指定使用的模型,None 则用 configurable.model_name
emit_step: 推送时间线步骤事件(list_skills / select_skills)
max_select: LLM 单次最多挑几个技能
user_query: 用户在素材确认卡输入框写的自然语言
candidates: 候选技能池。None = 全部启用的技能(旧行为);
传入列表(如素材收集专家 agent 配置的技能)则只在其中匹配排序
"""
def __init__(
self,
config: RunnableConfig,
*,
model_name: Optional[str] = None,
emit_step: Optional[EmitStepFn] = None,
max_select: int = 5,
user_query: str = "",
candidates: Optional[list] = None,
) -> None:
self._config = config
self._model_name = model_name
self._emit_step = emit_step or (lambda _step: None)
self._max_select = max_select
self._user_query = (user_query or "").strip()
self._candidates = candidates
self._errors: list[str] = []
@property
def errors(self) -> list[str]:
return list(self._errors)
def _load_enabled_skills(self) -> list:
if self._candidates is not None:
skills = list(self._candidates)
self._emit_step({
"type": "list_skills",
"message": f"素材收集专家已配置 {len(skills)} 个检索技能",
"skill_names": [s.name for s in skills],
})
return skills
try:
from deerflow.skills import get_or_new_skill_storage
storage = get_or_new_skill_storage()
skills = storage.load_skills(enabled_only=True)
except Exception as e:
logger.exception("ai_writing.skill_search: 加载启用技能失败")
self._errors.append(f"skill list error: {e}")
skills = []
self._emit_step({
"type": "list_skills",
"message": f"发现 {len(skills)} 个可用技能",
"skill_names": [s.name for s in skills],
})
return skills
async def pick(self, user_intent: str) -> List[dict]:
"""流式选择并排序候选技能,返回 [{skill, reason}, ...],按相关度降序。
过程中通过 custom 通道推送 ``skill_select_chunk`` 事件给前端打字机;
结束后再推一条 ``select_skills`` 结构化事件。
"""
skills = self._load_enabled_skills()
if not skills:
self._emit_step({
"type": "select_skills",
"message": "当前没有启用的技能可用",
"skill_names": [],
})
return []
skill_list_text = "\n".join(
f"- {s.name}: {s.description or '(无描述)'}" for s in skills
)
fallback = {"selected_skills": [s.name for s in skills[: self._max_select]], "reason": ""}
# list_skills 之后立刻发一个"分析中"提示步骤,避免 LLM 第一个 chunk 到来前
# 用户看到空窗期(某些模型 astream 在头部 buffer 时间较长)
self._emit_step({
"type": "match_skills",
"message": "正在让模型从候选技能中筛选最合适的…",
})
# 流式 LLM 调用:与 intent_parser / writer_outline 同套机制
writer = safe_get_stream_writer()
parser = ThinkTagParser()
full_text = ""
_chunk_count = {"n": 0}
def _emit_chunk(text: str, is_thinking: bool) -> None:
# 只在首个 chunk 打一条 timing,避免逐 token 刷屏;用来和 skill_search_step
# 的 [skill-timing] 对比"选择打字"与"步骤事件"谁先到。
if _chunk_count["n"] == 0:
logger.info("[skill-timing] t=%.3f first skill_select_chunk", time.monotonic())
_chunk_count["n"] += 1
writer({
"type": "skill_select_chunk",
"text": text,
"is_thinking": is_thinking,
"agent_name": "素材收集专家",
})
# 立刻推一个空 chunk,让前端 streaming view 立即挂载(占位 + 闪烁光标),
# 即使后续 LLM 首个 chunk 到达较慢,UI 也不再静默
_emit_chunk("", False)
try:
model = get_model(self._config, model_name=self._model_name)
async for chunk in model.astream([
SystemMessage(content=_SELECT_SKILLS_SYSTEM.format(max_select=self._max_select)),
HumanMessage(content=_SELECT_SKILLS_USER.format(
user_intent=user_intent or "(无明确写作意图)",
user_query=self._user_query or "(无)",
skill_count=len(skills),
skill_list=skill_list_text,
max_select=self._max_select,
)),
]):
# 推理模型的思考走 reasoning_content(content 为空):作为思考实时推送
reasoning = reasoning_delta(chunk)
if reasoning:
_emit_chunk(reasoning, True)
delta = _content_to_text(chunk.content)
if not delta:
continue
for is_thinking, text in parser.feed(delta):
if not is_thinking:
full_text += text
_emit_chunk(text, is_thinking)
except Exception as e:
logger.exception("ai_writing.skill_search: 流式选择技能失败")
self._errors.append(f"skill select error: {e}")
result = parse_json(full_text, fallback) if full_text else fallback
wanted_names = result.get("selected_skills") or []
if not isinstance(wanted_names, list):
wanted_names = []
by_name = {s.name: s for s in skills}
reason = result.get("reason", "") or ""
chosen: list[dict] = []
for name in wanted_names:
if not isinstance(name, str):
continue
sk = by_name.get(name.strip())
if sk and sk.name not in {c["skill"].name for c in chosen}:
chosen.append({"skill": sk, "reason": reason})
if len(chosen) >= self._max_select:
break
self._emit_step({
"type": "select_skills",
"message": f"按相关度排序,候选 {len(chosen)} 个技能(将按顺序使用)",
"skill_names": [c["skill"].name for c in chosen],
"reason": reason,
})
return chosen
# 保留旧名字让 search/__init__.py 的导出不报错;研究节点不再用它
SkillSearchProvider = SkillPicker
@@ -0,0 +1,217 @@
import operator
from typing import Annotated, List, Literal, Optional, TypedDict
# ── 素材 ──────────────────────────────────────────────────────────────────────
class Material(TypedDict, total=False):
id: str
title: str
content: str # 截断到 500 字
source: str
published_at: str
relevance_score: float
source_type: str # "internet" | "intranet" | "skill"
url: str
recUuid: str
# skill 类素材附带的元信息(skill_name / container_path / category),其他类型为空
extra_metadata: dict
class SkillStep(TypedDict, total=False):
"""技能检索过程的单步记录,用于前端时间线展示。
type=match_skills:根据用户输入流式分析有没有匹配技能(无 skill_names)
type=list_skills:列出可用技能
type=select_skills:LLM 从中选出的相关技能
type=invoke_skill:实际调用某一个技能检索
type=stop_early:达到素材阈值,提前停止后续技能调用
"""
type: str
message: str
skill_names: List[str]
skill_name: str
matched_count: int
reason: str
class MaterialPackage(TypedDict, total=False):
keywords: List[str]
materials: List[Material]
summary: str
# 是否本次素材来自技能检索(覆盖式替换 web 检索)
skill_search_used: bool
# 技能检索的步骤记录(前端展示"使用了 X 技能"卡片)
skill_search_steps: List[SkillStep]
# 内网知识库接口诊断:端点、每个检索词的命中数/耗时/错误、原始响应片段等。
# 用于排查 "检索很快返回 0 条" 时到底是否真正调用了内网接口。
intranet_debug: dict
# ── 大纲 ──────────────────────────────────────────────────────────────────────
# 三级结构:章节(##) → 小节(###) → 子要点(bullet -)。
# Outline.sections[] = Level 1 章节(渲染为 ## 由系统注入)
# OutlineSection.key_points[] = Level 2 小节(渲染为 ### 标题)
# KeyPoint.sub_points[] = Level 3 子要点(bullet "- ...",非标题)
#
# 历史上 key_points 曾是 List[str](2 级):每个 str 既是小节标题又是渲染单位。
# 升级到 3 级后,key_points 变成 List[KeyPoint],每个 KeyPoint 自带 sub_points
# 列表;旧 session 里的 string 项由 writer_outline._parse_outline 自动 lift 成
# {point_title: <原 string>, sub_points: []},无需迁移数据。
class KeyPoint(TypedDict):
point_title: str # 小节标题(渲染为 ### 二级小标题)
sub_points: List[str] # 子要点(可为空;非空时在小节正文里以 bullet 列表呈现)
class OutlineSection(TypedDict):
section_title: str
key_points: List[KeyPoint] # 注意:旧版是 List[str],解析层做了兼容
material_ids: List[str]
class Outline(TypedDict):
title: str
sections: List[OutlineSection]
# ── 草稿 ──────────────────────────────────────────────────────────────────────
class DraftArticle(TypedDict):
title: str
outline: Outline
full_markdown: str
word_count: int
revision_count: int
# ── 样文仿写 ──────────────────────────────────────────────────────────────────
class SampleStyleProfile(TypedDict, total=False):
summary: str
article_type_guess: str
tone: str
structure: List[str]
language_features: List[str]
sentence_style: str
opening_style: str
ending_style: str
imitation_guidance: List[str]
avoid_copying: List[str]
sample_outline: List[str]
# ── 编辑审核 ──────────────────────────────────────────────────────────────────
class ReviewIssue(TypedDict):
category: str # "fact" | "logic" | "language"
severity: str # "major" | "minor"
location: str
issue: str
suggestion: str
class ReviewResult(TypedDict):
verdict: str # "pass" | "reject"
fact_score: int
logic_score: int
language_score: int
overall_score: int
pass_threshold: int
revision_notes: List[ReviewIssue]
# ── 用户干预 ──────────────────────────────────────────────────────────────────
class UserInterventionPayload(TypedDict, total=False):
action: str
approved_material_ids: List[str]
extra_keywords: List[str]
# PAUSE-1 素材确认 / enable_skill_search 共用:用户在单输入框里填的自然语言
# (可能是要使用的技能名、想检索的来源、或者一段补充检索意图)。
user_query: str
# PAUSE-1 素材确认卡切换的检索方式:general / knowledge_base / notebook。
material_source: str
edited_outline: Optional[Outline]
outline_feedback: str
user_revision_notes: str
override_verdict: bool
# ── 主状态 ────────────────────────────────────────────────────────────────────
WritingStatus = Literal[
"analyzing_sample",
"researching", "awaiting_material_confirm",
"writing_outline", "awaiting_outline_confirm",
"writing_draft", "awaiting_section_help", "awaiting_draft_confirm",
"reviewing", "awaiting_review_confirm",
"revising", "done", "error",
]
class BlockedSection(TypedDict):
"""严格模式下素材不足、无法写作的章节。"""
section_title: str
reason: str
class AIWritingState(TypedDict):
# 写作配置
user_intent: str
# 用户在写作表单粘贴的「已有大纲」原文(可选)。非空时 writer_outline 跳过 LLM 规划,
# 直接解析这份大纲并按用户结构生成,做到「完全按我的大纲写」。留空走正常自动规划。
user_outline_raw: str
# True when setup chat has already produced structured intent fields.
skip_intent_parser: bool
# 写作入口模式:normal=普通写作 / imitate=样文仿写。仿写模式下先分析 sample_text,
# 得到 sample_style_profile,再将其注入大纲与草稿提示词。
writing_mode_type: str
sample_text: str
sample_filename: str
sample_style_profile: Optional[SampleStyleProfile]
imitate_strength: str
preserve_sample_structure: bool
article_type: str
# 当 article_type 是「已有类型库里没有」的新类型时,配置助手识别出的一句话特征说明。
# 仅本次写作临时使用(不入库):在大纲生成时作为 hint 附在类型后,影响全文结构与侧重。
article_type_detail: str
target_audience: str
word_count_target: int
# 素材检索关键词数量(用户指定,1~10,默认 6)
keyword_count: int
# 写作模式:strict=严格依据素材 / loose=可结合通用知识(默认 loose)
writing_mode: str
# 是否在成稿里加参考文献:正文引用素材处加角标 [n],文末按出现顺序生成「参考文献」列表(像论文)。
add_references: bool
# 检索类型:general=通用检索(按素材收集专家 agent 配置的技能编排,默认)/
# knowledge_base=知识库检索(直连 ai_writing.intranet_search_url 内网 ES 接口,
# 不走技能编排——弱模型识别不了技能时用这条)/ notebook=我的空间(仅笔记检索)。
# 旧值 skill 由 researcher 节点按 general 兼容处理。
material_source: str
# 跳过素材收集:用户在初始表单勾选「不收集素材,直接用通用知识写作」时为 True。
# researcher 节点在**首次**进入(无任何 pause 干预)时短路,跳过整个检索流程直接
# 去大纲规划;强制 loose 写作模式(没有素材可严格依据)。
skip_research: bool
# 用户在写作表单选定的主模型。大纲/写作/审核严格使用它(不回退默认)。
# 由 intent_parser 在首次 invocation 从 configurable.model_name 捕获进 state,
# 经 checkpoint 持久化 —— interrupt/resume 是新 invocation、其 config 不带原
# model_name,存进 state 才能让 resume 后才运行的节点拿到用户模型。
model_name: str
# 笔记来源(可选):传入后 researcher 阶段会额外从笔记检索素材
notebook_search_space_id: Optional[int]
notebook_source_ids: Optional[List[int]]
# Agent A 输出
material_package: Optional[MaterialPackage]
# Agent B 输出
current_outline: Optional[Outline]
drafts: Annotated[List[DraftArticle], operator.add]
current_draft: Optional[DraftArticle]
# Agent C 输出
review_result: Optional[ReviewResult]
# 用户干预数据(每个干预点会覆盖)
last_user_intervention: Optional[UserInterventionPayload]
# 严格模式下素材不足、待用户决策的章节(写作节点产出,求助暂停点消费)
blocked_sections: Optional[List[BlockedSection]]
# 流程控制
revision_count: int
max_revisions: int
status: WritingStatus
# SSE 进度推送队列(每个节点追加)
progress_events: Annotated[List[dict], operator.add]
@@ -0,0 +1,3 @@
from deerflow.agents.canvas_agent.agent import make_canvas_agent
__all__ = ["make_canvas_agent"]
@@ -0,0 +1,80 @@
from __future__ import annotations
import logging
from langchain.agents import create_agent
from langchain_core.runnables import RunnableConfig
from deerflow.agents.canvas_agent.prompt import build_canvas_system_prompt
from deerflow.agents.canvas_agent.tools import update_artifact_tool
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
from deerflow.agents.middlewares.title_middleware import TitleMiddleware
from deerflow.agents.middlewares.tool_error_handling_middleware import ToolErrorHandlingMiddleware
from deerflow.agents.thread_state import ThreadState
from deerflow.config.app_config import get_app_config
from deerflow.models import create_chat_model
from deerflow.tools.builtins import ask_clarification_tool
logger = logging.getLogger(__name__)
def _get_runtime_config(config: RunnableConfig) -> dict:
cfg = dict(config.get("configurable", {}) or {})
context = config.get("context", {}) or {}
if isinstance(context, dict):
cfg.update(context)
return cfg
def make_canvas_agent(config: RunnableConfig):
"""LangGraph graph factory for canvas mode; signature compatible with LangGraph Server."""
app_config = get_app_config()
cfg = _get_runtime_config(config)
requested_model = cfg.get("model_name") or cfg.get("model")
if requested_model and app_config.get_model_config(requested_model):
model_name = requested_model
else:
if requested_model:
logger.warning("Canvas agent: model '%s' not found; falling back to default.", requested_model)
model_name = app_config.models[0].name if app_config.models else None
if model_name is None:
raise ValueError("No chat models configured. Please add at least one model in config.yaml.")
thinking_enabled = cfg.get("thinking_enabled", False)
model_config = app_config.get_model_config(model_name)
if thinking_enabled and model_config and not model_config.supports_thinking:
thinking_enabled = False
canvas_artifact_title = cfg.get("canvas_artifact_title") or None
canvas_artifact_type = cfg.get("canvas_artifact_type") or None
system_prompt = build_canvas_system_prompt(
artifact_title=canvas_artifact_title,
artifact_type=canvas_artifact_type,
)
logger.info(
"Create CanvasAgent -> model_name: %s, thinking_enabled: %s, artifact_title: %s",
model_name,
thinking_enabled,
canvas_artifact_title,
)
middlewares = [
DanglingToolCallMiddleware(),
ToolErrorHandlingMiddleware(),
TitleMiddleware(app_config=app_config),
LoopDetectionMiddleware(),
ClarificationMiddleware(),
]
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, app_config=app_config),
tools=[update_artifact_tool, ask_clarification_tool],
middleware=middlewares,
system_prompt=system_prompt,
state_schema=ThreadState,
)
@@ -0,0 +1,100 @@
def build_canvas_system_prompt(
artifact_title: str | None = None,
artifact_type: str | None = None,
) -> str:
existing_artifact_block = ""
if artifact_title:
type_label = "代码" if artifact_type == "code" else "文档"
existing_artifact_block = f"""
<existing_artifact>
用户当前有一个{type_label}制品,标题为 "{artifact_title}"。
请继续编辑该制品——除非用户明确要求新建,否则不要创建新制品。
</existing_artifact>
"""
return f"""You are a Canvas AI assistant that helps users create and edit documents and code.
<canvas_behavior>
You work with an **artifact** — a document or code file shown in the canvas panel on the right.
ALWAYS call `update_artifact` to save your work. Never embed the artifact content in your chat response.
Rules:
- On every request that creates or changes the artifact, call `update_artifact` ONCE with the COMPLETE updated content.
- In your text reply, describe what you did in 1–2 sentences.
- If the user is only asking a question (no edit needed), answer in text — skip the tool call.
</canvas_behavior>
<clarification_system>
Before creating a brand-new artifact or performing a major rewrite, verify you have enough
information to do the job well. When key details are missing, call `ask_clarification` FIRST
— do NOT start generating the artifact and ask questions mid-way.
**MUST clarify when (no existing artifact or major rewrite requested):**
1. OUTPUT TYPE IS VAGUE
- "帮我做个主页" / "make a homepage" → ask: tech stack (plain HTML / React / Vue?),
design style, which sections to include
- "写个报告" / "write a report" → ask: topic, target audience, expected length,
required sections
- "写个脚本" / "write a script" → ask: programming language, what it should do
2. REQUIRED CONTENT IS MISSING
- User wants a personal profile page but hasn't provided their name / bio / links
- User wants a data table but hasn't provided the data or schema
3. AMBIGUOUS APPROACH WITH SIGNIFICANTLY DIFFERENT OUTCOMES
- "Design a chat system" → ask: client–server or peer-to-peer, persistence needed?
- "Write an intro" → ask: formal essay or casual blog post?
**DO NOT clarify for:**
- Simple edits to an existing artifact: "make it bold", "fix the typo", "shorten paragraph 2"
- Formatting / style tweaks: "add comments", "use camelCase", "format the code"
- Quick actions: expand / shorten / formalize / casualize / add_comments / fix_bugs / optimize_code
- Requests where intent is clear from context (e.g., user pastes content and says "translate this")
- Follow-up turns where enough context already exists in the conversation
**Format for clarification (use options when practical):**
ask_clarification(
question="你希望这个主页使用什么技术栈?",
clarification_type="missing_info",
options=[
{{"id": "html", "label": "纯 HTML / CSS / JS", "description": "无框架,最简单"}},
{{"id": "react", "label": "React", "description": "组件化,适合复杂交互"}},
{{"id": "vue", "label": "Vue", "description": "渐进式框架,上手容易"}},
],
allow_custom=True,
)
CRITICAL: clarification ALWAYS comes before generating the artifact. Never produce a partial
artifact and then ask for clarification in the same response.
</clarification_system>
<artifact_context>
The current artifact state is injected into your context. When editing, build on the existing content exactly.
When creating from scratch, produce a complete, high-quality artifact in one shot.
</artifact_context>
{existing_artifact_block}
<selection_rewrite>
When the user's message contains a <selection> block, you MUST:
1. Identify the exact selection in the current artifact content.
2. Rewrite ONLY that selection according to the user's instruction.
3. Keep the rest of the artifact exactly unchanged.
4. Call update_artifact with the complete artifact where the selection has been replaced.
Example: if the artifact is "A B C" and the selection is "B" with instruction "make it bold",
produce "A **B** C" — not a new document.
</selection_rewrite>
<quick_actions>
When the user triggers a quick action, apply it to the full artifact unless specific highlighted text is provided:
- expand: Add depth and detail while preserving structure
- shorten: Condense to the essential points
- formalize: Rewrite in professional, formal language
- casualize: Rewrite in friendly, conversational language
- add_comments: Add clear, helpful code comments
- add_logs: Add appropriate logging statements
- fix_bugs: Identify and fix all bugs in the code
- optimize_code: Improve performance and readability
</quick_actions>
"""
# Backward-compatible constant for callers that don't pass artifact context.
CANVAS_SYSTEM_PROMPT = build_canvas_system_prompt()
@@ -0,0 +1,65 @@
from __future__ import annotations
from typing import Annotated, Literal
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.thread_state import CanvasArtifact, CanvasArtifactCode, CanvasArtifactText, ThreadState
@tool("update_artifact", parse_docstring=True)
def update_artifact_tool(
runtime: ToolRuntime[ContextT, ThreadState],
tool_call_id: Annotated[str, InjectedToolCallId],
type: Literal["text", "code"],
title: str,
content: str,
language: str = "other",
) -> Command:
"""Create or update the canvas artifact. Always call this to persist your work.
Args:
type: Artifact type — "text" for markdown documents, "code" for source code.
title: Human-readable title of the artifact.
content: Full artifact content: markdown text or complete source code.
language: Programming language (for code type only, e.g. "python", "typescript"). Ignored for text.
"""
current: CanvasArtifact | None = (runtime.state or {}).get("artifact") if runtime.state else None
if current is not None:
existing_contents = list(current.get("contents", []))
new_index = current.get("currentIndex", len(existing_contents)) + 1
else:
existing_contents = []
new_index = 1
if type == "text":
new_entry: CanvasArtifactText | CanvasArtifactCode = CanvasArtifactText(
index=new_index,
type="text",
title=title,
fullMarkdown=content,
)
else:
new_entry = CanvasArtifactCode(
index=new_index,
type="code",
title=title,
language=language,
code=content,
)
updated: CanvasArtifact = {
"currentIndex": new_index,
"contents": existing_contents + [new_entry],
}
return Command(
update={
"artifact": updated,
"messages": [ToolMessage("Artifact updated.", tool_call_id=tool_call_id)],
}
)
@@ -0,0 +1,56 @@
# GPT Researcher adaptation manifest
This directory implements Deep Research for DeerFlow. It is an **algorithmic
adaptation** of selected GPT Researcher control flows, not an import of the
upstream package at runtime. This boundary is intentional: GPT Researcher's
LLM providers, search/scrape stack, MCP setup, global configuration and
dependency graph must not bypass DeerFlow's model factory, material-security
policy, user context or durable-job lifecycle.
## Fixed upstream baseline
| Field | Value |
| --- | --- |
| Project | `assafelovic/gpt-researcher` |
| Local review checkout | `F:\react01\deeflow-code\gpt-researcher` |
| Commit | `5d84d2f5553e70a2765a8ff3a0d2672d60437ce8` |
| License | Apache License 2.0 (`F:\react01\deeflow-code\gpt-researcher\LICENSE`) |
| Upstream repository | <https://github.com/assafelovic/gpt-researcher> |
No upstream executable source file is copied into this directory at present.
If a future change copies an upstream file or a non-trivial portion of one,
add its copyright/license notice next to that file, record the exact source
path and commit below, and keep the Apache-2.0 notice in the distribution.
## Adapted control-flow mapping
| DeerFlow code | Upstream reference | Adaptation made |
| --- | --- | --- |
| `runners/basic.py` | `gpt_researcher/agent.py`, `backend/report_type/basic_report/basic_report.py` | Planning → bounded material collection → de-duplication/context compression → cited report is expressed through `AdapterBundle`. |
| `runners/detailed.py` | `backend/report_type/detailed_report/detailed_report.py` | Subtopic planning, concurrent sub-research and section assembly are retained; all upstream `GPTResearcher` instances become bounded DeerFlow adapters. |
| `runners/deep.py` | `gpt_researcher/skills/deep_research.py` | Breadth/depth branching, learnings and follow-up questions are preserved with an explicit global budget, semaphores and cooperative cancellation. |
| `runners/multi_agent.py` | `multi_agents/agents/{orchestrator,editor,writer,fact_checker}.py` | Editor/researcher/writer/reviewer roles become a LangGraph 1.x `StateGraph`, with the review pause persisted as a durable job state. |
| `adapters/context.py`, `adapters/material.py` | `gpt_researcher/context/compression.py`, `gpt_researcher/skills/researcher.py` | Retains context/de-duplication intent while preserving DeerFlow provenance (`rec_uuid`, source id, source type) and enforcing the existing material-provider boundary. |
| `runners/images.py`, `adapters/image.py` | `gpt_researcher/skills/image_generator.py` | Retains report-image placement intent, while configured OpenAI-compatible and DashScope-native adapters both persist protected hidden-thread artifacts. |
## Required adaptation invariants
1. Harness code may not import `app.*`; this is covered by
`tests/test_deep_research_harness_boundary.py`.
2. Research collection may only use `MaterialProvider`; upstream retrievers,
scrapers and MCP clients are not imported.
3. Model calls may only use `DeerFlowCompletionBackend` and
`create_chat_model()`; no upstream provider configuration is accepted.
4. Every job uses a frozen `DeepResearchConfig` snapshot, a user-scoped
session and a durable event log.
5. Upstream examples that run network calls, write unrestricted paths, or
block for terminal input must be redesigned rather than copied.
## Upgrade procedure
1. Review the candidate upstream commit in the local checkout.
2. Update the commit and mapping table in this manifest and in
`docs/gpt-researcher-deerflow-集成开发方案.md`.
3. Re-evaluate dependency, license and security implications before copying
any source.
4. Run the complete deep-research suite and the harness-boundary test.
@@ -0,0 +1,26 @@
"""Deep Research agent package — vendored GPT Researcher algorithms adapted to DeerFlow.
This package integrates selected GPT Researcher research-planning, recursive
exploration, report-generation, and multi-agent editorial algorithms into the
DeerFlow runtime. The *algorithms* are vendored (``vendor/``); all infrastructure
(model, search, events, artifacts) is injected through a small set of adapters
defined in ``adapters/`` so the vendored code never touches the network, the
filesystem, or ``app.*``.
Architecture (see ``docs/gpt-researcher-deerflow-集成开发方案.md``):
DeepResearchEngine ──► runners/{basic,detailed,deep,multi_agent}
│
▼
AdapterBundle ──► adapters/{llm,material,context,artifacts,event_sink}
│
▼
vendor/gpt_researcher/* (algorithms only)
Harness-layer constraint: **no imports from ``app.*``** (enforced by
``tests/test_deep_research_harness_boundary.py``).
"""
from __future__ import annotations
__all__: list[str] = []
@@ -0,0 +1,19 @@
"""Deep Research adapters — the four-boundary isolation layer.
Adapters are the *only* place the vendored GPT Researcher algorithms touch
DeerFlow infrastructure. Each adapter wraps one concern:
================ ===========================================================
``llm`` model calls → ``create_chat_model()`` (no upstream Provider)
``material`` search/fetch → DeerFlow ``web_search`` + knowledge + MCP
``context`` context compression (no legacy text-splitter deps)
``event_sink`` progress events → ``deep_research_events`` + SSE
``artifacts`` report/export writes → hidden runtime-thread outputs
``image`` image generation (optional, Phase 5)
================ ===========================================================
Protocols live in each module alongside (or ahead of) their concrete impl, so
tests can inject fakes that satisfy the protocol without importing infra.
"""
from __future__ import annotations
@@ -0,0 +1,159 @@
"""Artifact writer — writes report/export files into the session's hidden thread.
Each deep-research session owns a *hidden* DeerFlow runtime thread
(``metadata.thread_type=deep_research``, ``hidden=true``). Report artifacts
(``report.md``, ``report.html``, ``sources.json``, …) are written into that
thread's sandbox ``outputs/`` directory and downloaded through the existing
``/api/threads/{thread_id}/artifacts`` endpoint (which already has path-safety
guards + owner checks — §13.6, §18.3).
The writer is a thin protocol so the engine/runner never touches the filesystem
layout directly.
"""
from __future__ import annotations
import re
from pathlib import Path
from typing import Protocol, runtime_checkable
@runtime_checkable
class ArtifactWriter(Protocol):
"""Protocol for writing research artifacts (§13.6 §18)."""
@property
def thread_id(self) -> str:
"""The hidden runtime thread that owns these artifacts."""
...
async def write_text(self, name: str, content: str) -> str:
"""Write a text artifact (e.g. ``report.md``) and return its virtual path."""
...
async def write_bytes(self, name: str, content: bytes) -> str:
"""Write a binary artifact (e.g. ``report.pdf``). Optional capability."""
...
def allowed_names(self) -> tuple[str, ...]:
"""The server-enumerated filename whitelist (§18.3 — no arbitrary paths)."""
...
# Server-enumerated artifact filename whitelist (§18.3, §13.6).
# The writer rejects any name not in this set to prevent path traversal.
ARTIFACT_NAMES: tuple[str, ...] = (
"report.md",
"report.html",
"sources.json",
"research-plan.json",
"report.pdf", # optional capability
"report.docx", # optional capability
)
# Image artifact names are server-generated only. Keeping the numerical range
# small makes the whitelist finite in practice while still letting the report
# writer select the matching format returned by the configured provider.
_RESEARCH_IMAGE_NAME_RE = re.compile(r"research-image-0[1-4]\.(?:png|jpe?g|webp)$")
def is_allowed_artifact_name(name: str) -> bool:
"""Return whether *name* is one of the server-controlled research outputs."""
return name in ARTIFACT_NAMES or bool(_RESEARCH_IMAGE_NAME_RE.fullmatch(name))
def resolve_research_artifact_path(
thread_id: str,
name: str,
*,
user_id: str | None = None,
) -> Path:
"""Resolve a whitelisted research artifact into its thread outputs dir.
``Paths.resolve_virtual_path`` intentionally accepts only paths that an
in-sandbox agent could see. Research code deals in server-generated file
names, so passing a bare name (for example ``report.md``) would fail that
guard on every host, including native Windows deployments. Keep the name
allowlist and construct the canonical sandbox path here, at the boundary.
"""
if not is_allowed_artifact_name(name):
raise ValueError(f"Artifact name {name!r} is not in the allowed research-artifact whitelist")
from deerflow.config.paths import VIRTUAL_PATH_PREFIX, get_paths
return get_paths().resolve_virtual_path(
thread_id,
f"{VIRTUAL_PATH_PREFIX}/outputs/{name}",
user_id=user_id,
)
class ThreadOutputsArtifactWriter:
"""Concrete writer backed by a DeerFlow thread's sandbox ``outputs/`` dir.
The actual path resolution reuses
:func:`deerflow.config.paths.get_paths().sandbox_outputs_dir` (the same
guard ``app/gateway/routers/artifacts.py`` uses), so traversal/symlink
protection is inherited. File IO is offloaded to a thread so the event
loop is never blocked (§25.6).
"""
def __init__(self, thread_id: str, *, user_id: str | None = None) -> None:
self._thread_id = thread_id
self._user_id = user_id
@property
def thread_id(self) -> str:
return self._thread_id
def allowed_names(self) -> tuple[str, ...]:
return ARTIFACT_NAMES
async def write_text(self, name: str, content: str) -> str:
self._validate_name(name)
import asyncio
path = await asyncio.to_thread(self._resolve_path, name)
await asyncio.to_thread(self._write_file, path, content.encode("utf-8"))
return name
async def write_bytes(self, name: str, content: bytes) -> str:
self._validate_name(name)
import asyncio
path = await asyncio.to_thread(self._resolve_path, name)
await asyncio.to_thread(self._write_file, path, content)
return name
# ── internals ───────────────────────────────────────────────────────────
def _validate_name(self, name: str) -> None:
if not is_allowed_artifact_name(name):
raise ValueError(
f"Artifact name {name!r} is not in the allowed research-artifact whitelist"
)
def _resolve_path(self, name: str):
# Ensure the outputs dir exists; the paths module rejects traversal and
# the name is whitelisted above, so the canonical virtual path is safe.
from deerflow.config.paths import get_paths
get_paths().sandbox_outputs_dir(self._thread_id, user_id=self._user_id)
return resolve_research_artifact_path(
self._thread_id,
name,
user_id=self._user_id,
)
def _write_file(self, path, data: bytes) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(data)
__all__ = [
"ARTIFACT_NAMES",
"ArtifactWriter",
"ThreadOutputsArtifactWriter",
"is_allowed_artifact_name",
"resolve_research_artifact_path",
]
@@ -0,0 +1,130 @@
"""Context compressor — DeerFlow replacement for upstream's legacy compressor.
Upstream's ``ContextManager`` / ``compression`` module depends on
``langchain_classic`` and ``langchain_text_splitters``, which DeerFlow does not
declare. Rather than pull in those legacy packages, we keep the *calling
interface* (§10) and provide :class:`DeerFlowContextCompressor` with a
self-contained algorithm:
1. Chunk by title/paragraph/char-limit without breaking Markdown code blocks.
2. Each chunk retains its source id (no cross-source amalgamation).
3. If embeddings are configured → similarity pre-filter; else keyword/BM25-style.
4. Over budget → per-source summary via ``fast_model`` (Phase 2).
5. Final ranking balances source diversity, recency, relevance.
Phase 1 ships the chunking + keyword pre-filter (no embedding dependency);
the ``fast_model`` summarisation path is wired but only triggers when the
context genuinely exceeds ``max_context_words``.
"""
from __future__ import annotations
from collections.abc import Callable
from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
if TYPE_CHECKING:
from deerflow.agents.deep_research.adapters.llm import DeerFlowCompletionBackend
from deerflow.agents.deep_research.types import ResearchMaterial
@runtime_checkable
class ContextCompressor(Protocol):
"""The interface vendored ``ContextManager`` is rewired to call (§10)."""
async def async_get_context(
self,
query: str,
max_results: int = 10,
cost_callback: Callable[..., Any] | None = None,
) -> list[dict[str, Any]]:
"""Return the compressed context list (each item = one material's context dict).
Output shape matches :meth:`ResearchMaterial.to_context_dict` so the
vendored writer sees what it expects.
"""
...
class DeerFlowContextCompressor:
"""Concrete compressor: chunk → keyword-filter → optional summary.
Holds a reference to the current material set (set by the runner before
the vendored research loop calls ``async_get_context``) and the LLM backend
(for the summary path).
"""
def __init__(
self,
*,
llm: DeerFlowCompletionBackend | None = None,
max_context_words: int = 24_000,
) -> None:
self._llm = llm
self._max_words = max_context_words
self._materials: list[ResearchMaterial] = []
def set_materials(self, materials: list[ResearchMaterial]) -> None:
"""Prime the compressor with the current source pool (called per research phase)."""
self._materials = list(materials)
async def async_get_context(
self,
query: str,
max_results: int = 10,
cost_callback: Callable[..., Any] | None = None,
) -> list[dict[str, Any]]:
"""Select + compress the best ``max_results`` materials for ``query``."""
from deerflow.agents.deep_research.adapters.material import dedupe_materials
deduped = dedupe_materials(self._materials)
# Keyword pre-filter (no embedding dep in Phase 1).
scored = [(_keyword_score(query, m), m) for m in deduped]
scored.sort(key=lambda pair: pair[0], reverse=True)
selected = [m for _, m in scored[:max_results]]
# Budget guard: if total words exceed limit, summarise the tail.
total_words = sum(len((m.raw_content or "").split()) for m in selected)
if total_words > self._max_words and self._llm is not None:
selected = await self._summarise_tail(selected, query)
if cost_callback is not None:
try:
cost_callback(1, 0) # upstream signature: (total, done)
except Exception: # noqa: BLE001
pass
return [m.to_context_dict() for m in selected]
async def _summarise_tail(
self, materials: list[ResearchMaterial], query: str
) -> list[ResearchMaterial]:
"""Summarise lower-ranked materials to fit the word budget (Phase 2)."""
# Phase 1: simply truncate the list rather than calling the model,
# so a fresh deploy without model tuning still produces a report.
# (The full summarisation path is enabled once the basic runner is green.)
words = 0
kept: list[ResearchMaterial] = []
for m in materials:
w = len((m.raw_content or "").split())
if words + w > self._max_words:
break
words += w
kept.append(m)
return kept or materials[:1]
def _keyword_score(query: str, material: ResearchMaterial) -> float:
"""Cheap relevance heuristic: fraction of query terms present in the material."""
q_terms = {t.lower() for t in query.split() if len(t) > 1}
if not q_terms:
return 0.0
haystack = f"{material.title}\n{material.raw_content}".lower()
hits = sum(1 for t in q_terms if t in haystack)
base = hits / len(q_terms)
# Tiny recency/relevance nudges when metadata is present.
if material.relevance_score:
base += 0.01 * float(material.relevance_score)
return base
__all__ = ["ContextCompressor", "DeerFlowContextCompressor"]
@@ -0,0 +1,376 @@
"""Persisting event sink — bridges runners to the event-store repository.
Runners call :meth:`PersistingEventSink.emit` (which satisfies the
:class:`~deerflow.agents.deep_research.events.EventSink` protocol); the sink
delegates to :class:`~deerflow.persistence.deep_research_events.DeepResearchEventRepository`,
which assigns the monotonic ``seq`` and persists the row **before** returning.
This "persist-then-stream" ordering (§15.3) is what makes ``?after=<seq>``
reconnect-replay correct.
The sink is bound to one ``(session_id, job_id)`` pair at construction; runners
don't carry those ids around.
"""
from __future__ import annotations
import json
import logging
from collections.abc import Awaitable, Callable
from contextlib import suppress
from datetime import date, datetime
from enum import Enum
from time import monotonic
from typing import TYPE_CHECKING, Any
from deerflow.agents.deep_research.events import (
DeepResearchEvent,
EventType,
ResearchPhase,
)
if TYPE_CHECKING:
from deerflow.persistence.deep_research_events import DeepResearchEventRepository
logger = logging.getLogger(__name__)
def _json_default(value: Any) -> Any:
if isinstance(value, (datetime, date)):
return value.isoformat()
if isinstance(value, Enum):
return value.value
if hasattr(value, "model_dump"):
return value.model_dump(mode="json")
return str(value)
# Live-only frame types that have no durable counterpart at all. Report and
# summary text are already checkpointed (``report_chunk`` / ``summary_completed``),
# so only the reasoning channel needs a cross-worker mirror.
_MIRRORED_LIVE_TYPES = frozenset({"report_thinking", "plan_reasoning", "summary_thinking"})
# Coalescing bounds for that mirror: one bounded row per ~600 characters or
# ~1.5 seconds, never one row per provider token.
_MIRROR_MIN_CHARS = 600
_MIRROR_MAX_DELAY_S = 1.5
# Floor for the time-based flush: a slowly trickling reasoning stream must not
# degrade into one durable row per token. Anything shorter is carried until the
# next durable milestone flushes it.
_MIRROR_MIN_FLUSH_CHARS = 40
def _json_safe_payload(payload: dict[str, Any]) -> dict[str, Any]:
"""Normalize event payloads before they reach any event repository.
This protects deployments that still use a strict ``json.dumps`` inside
the SQL repository and keeps native datetime values in source metadata
from degrading every ``source_added`` event.
"""
return json.loads(json.dumps(payload, ensure_ascii=False, default=_json_default))
class PersistingEventSink:
"""EventSink implementation backed by the deep-research event repository.
Satisfies :class:`~deerflow.agents.deep_research.events.EventSink` (the
runtime-checkable protocol) via structural typing.
"""
def __init__(
self,
repo: DeepResearchEventRepository,
*,
session_id: str,
job_id: str,
on_event: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
live_subscriber_probe: Callable[[str], bool] | None = None,
) -> None:
self._repo = repo
self._session_id = session_id
self._job_id = job_id
self._on_event = on_event
# Reports whether this worker holds an SSE connection for the job.
# Absent probe → assume the live path reaches the viewer (single-worker
# deployments and tests keep today's zero-extra-write behaviour).
self._live_subscriber_probe = live_subscriber_probe
self._mirror_buffers: dict[str, dict[str, Any]] = {}
self._mirroring = False
self.diagnostics: list[dict[str, Any]] = []
# A durable event row normally owns the sequence. When the event
# database is temporarily unavailable, use distinct negative sequence
# numbers for the live-only path so clients can render every milestone
# without advancing their durable ``after`` cursor.
self._fallback_seq = 0
async def emit(
self,
type: EventType, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict | None = None,
) -> DeepResearchEvent:
event_payload = _json_safe_payload(payload or {})
persistence_error: Exception | None = None
if not self._mirroring:
# Order any coalesced reasoning tail before the next milestone
# instead of leaving it buffered until the job ends.
await self._flush_live_mirrors()
try:
row = await self._repo.append(
session_id=self._session_id,
job_id=self._job_id,
event_type=type,
phase=phase,
payload=event_payload,
)
# Reconstruct the envelope from the persisted row (seq is now assigned).
event = DeepResearchEvent(
seq=int(row.get("seq", 0)),
session_id=self._session_id,
job_id=self._job_id,
type=row.get("event_type", type),
phase=row.get("phase", phase),
payload=row.get("payload") or event_payload,
)
except Exception as exc: # noqa: BLE001
# Progress persistence must not turn a recoverable database blip
# into a failed report. The job/status stores still record terminal
# state; this live-only frame lets an attached UI stay responsive
# until durable replay becomes available again after reconnect.
self._fallback_seq -= 1
persistence_error = exc
self.diagnostics.append(
{
"code": "event_persistence_degraded",
"stage": phase,
"eventType": type,
"errorType": exc.__class__.__name__,
"detail": str(exc).split("[SQL:", 1)[0].strip()[:600] or exc.__class__.__name__,
}
)
logger.warning(
"deep-research event persistence degraded; continuing job with a live-only event "
"(job=%s, type=%s, phase=%s, error=%s)",
self._job_id,
type,
phase,
persistence_error.__class__.__name__,
)
event = DeepResearchEvent(
seq=self._fallback_seq,
session_id=self._session_id,
job_id=self._job_id,
type=type,
phase=phase,
payload={**event_payload, "eventPersistenceDegraded": True},
)
await self._publish_event(event)
if persistence_error is not None:
# Keep the original source/progress event live, and additionally
# expose one copyable diagnostic frame. This never re-enters the
# failing repository and therefore cannot interrupt the job.
self._fallback_seq -= 1
detail = str(persistence_error).split("[SQL:", 1)[0].strip()[:600]
await self._publish_event(
DeepResearchEvent(
seq=self._fallback_seq,
session_id=self._session_id,
job_id=self._job_id,
type="warning",
phase=phase,
payload={
"code": "event_persistence_degraded",
"message": "研究过程事件暂未写入数据库,报告任务已继续运行",
"recoverable": True,
"diagnostic": {
"stage": phase,
"eventType": type,
"errorType": persistence_error.__class__.__name__,
"detail": detail or persistence_error.__class__.__name__,
},
},
)
)
return event
async def _publish_event(self, event: DeepResearchEvent) -> None:
"""Push a persisted or live-only event without risking the worker."""
if self._on_event is None:
return
wire = event.to_sse_dict()
if event.seq < 0:
wire["liveId"] = f"event-persistence-fallback:{self._job_id}:{abs(event.seq)}"
try:
await self._on_event(wire)
except Exception: # noqa: BLE001
# A browser disconnect or a live-hub issue must not abort report
# generation; persisted rows will still be replayable on reconnect.
logger.warning(
"deep-research live event publish failed; job continues (job=%s, seq=%s)",
self._job_id,
event.seq,
exc_info=True,
)
async def publish_live(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict | None = None,
) -> None:
if self._on_event is None:
return
try:
await self._on_event(
{
"seq": 0,
"sessionId": self._session_id,
"jobId": self._job_id,
"type": type,
"phase": phase,
"payload": payload or {},
}
)
except Exception: # noqa: BLE001
logger.warning(
"deep-research live frame publish failed; job continues (job=%s, type=%s)",
self._job_id,
type,
exc_info=True,
)
with suppress(Exception):
await self._mirror_live_frame(type, phase=phase, payload=payload or {})
# ── cross-worker mirror for live-only reasoning frames ──────────────────
async def _mirror_live_frame(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase,
payload: dict[str, Any],
) -> None:
"""Buffer a live-only reasoning delta when no local viewer can see it.
The live hub is in-process. A job runs on the worker that won its
durable lease, while the SSE connection is served by whichever worker
accepted it, so on a multi-worker deployment the model's thinking is
usually published into a hub with no subscribers and is then lost —
there is no durable row to replay it from. When that is the case, the
reasoning is coalesced here and persisted as a bounded durable event
so the polling stream on the other worker still renders it.
"""
if type not in _MIRRORED_LIVE_TYPES or self._live_subscriber_probe is None:
return
delta = payload.get("delta")
if not isinstance(delta, str) or not delta:
return
if self._live_subscriber_probe(self._job_id):
# A viewer is attached here and has already received every frame
# live. Drop the buffer rather than flushing it, so that viewer
# does not also receive the same text as a durable replay.
self._mirror_buffers.pop(self._mirror_key(type, payload), None)
return
key = self._mirror_key(type, payload)
buffered = self._mirror_buffers.get(key)
if buffered is None:
buffered = {
"type": type,
"phase": phase,
"target": payload.get("target"),
"reportVersion": payload.get("reportVersion"),
"text": "",
"since": monotonic(),
}
self._mirror_buffers[key] = buffered
buffered["text"] += delta
buffered["phase"] = phase
buffered_chars = len(buffered["text"])
aged_out = (
buffered_chars >= _MIRROR_MIN_FLUSH_CHARS
and monotonic() - float(buffered["since"]) >= _MIRROR_MAX_DELAY_S
)
if buffered_chars >= _MIRROR_MIN_CHARS or aged_out:
await self._emit_mirror(key)
@staticmethod
def _mirror_key(type: str, payload: dict[str, Any]) -> str: # noqa: A002
return f"{type}::{payload.get('target') or 'report'}"
async def _flush_live_mirrors(self) -> None:
for key in tuple(self._mirror_buffers):
with suppress(Exception):
await self._emit_mirror(key)
async def _emit_mirror(self, key: str) -> None:
buffered = self._mirror_buffers.pop(key, None)
if buffered is None or not buffered["text"]:
return
payload: dict[str, Any] = {
"delta": buffered["text"],
"liveMirror": True,
}
if buffered["target"] is not None:
payload["target"] = buffered["target"]
if buffered["reportVersion"] is not None:
payload["reportVersion"] = buffered["reportVersion"]
self._mirroring = True
try:
await self.emit(buffered["type"], phase=buffered["phase"], payload=payload)
finally:
self._mirroring = False
class NullEventSink:
"""No-op sink for unit tests / dry runs that don't have a database.
Satisfies :class:`EventSink` structurally; assigns a monotonic in-memory seq
so fake tests can still assert event ordering.
"""
def __init__(self, *, session_id: str = "test", job_id: str = "test") -> None:
self._session_id = session_id
self._job_id = job_id
self._seq = 0
self.events: list[DeepResearchEvent] = []
self.live_events: list[dict[str, Any]] = []
async def emit(
self,
type: EventType, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict | None = None,
) -> DeepResearchEvent:
self._seq += 1
ev = DeepResearchEvent(
seq=self._seq,
session_id=self._session_id,
job_id=self._job_id,
type=type,
phase=phase,
payload=payload or {},
)
self.events.append(ev)
return ev
async def publish_live(
self,
type: str, # noqa: A002
*,
phase: ResearchPhase = "initializing",
payload: dict | None = None,
) -> None:
self.live_events.append(
{
"seq": 0,
"sessionId": self._session_id,
"jobId": self._job_id,
"type": type,
"phase": phase,
"payload": payload or {},
}
)
__all__ = ["NullEventSink", "PersistingEventSink"]
@@ -0,0 +1,432 @@
"""Optional, DeerFlow-configured report image generation.
The upstream GPT Researcher image skill owns its provider configuration, so it
cannot be safely reused in DeerFlow. This adapter supports both a deployment
configured OpenAI-compatible ``/images/generations`` endpoint and the native
DashScope multimodal-generation endpoint used by Qwen Image 3.0 and Wan 2.7.
It is never configured from a browser request: model credentials stay in
``config.yaml`` and the per-session snapshot contains only the boolean
``generate_images``.
OpenAI-compatible images are requested as base64; DashScope image URLs are
downloaded immediately. The runner therefore always puts exact bytes into the
session's protected artifact directory, and reports never depend on an expiring
public image URL.
"""
from __future__ import annotations
import base64
import binascii
from typing import Any, Literal, Protocol, runtime_checkable
from urllib.parse import urlparse
import httpx
from pydantic import BaseModel, Field, field_validator
_MAX_IMAGE_BYTES = 20 * 1024 * 1024
_DASHSCOPE_GENERATION_PATH = "/api/v1/services/aigc/multimodal-generation/generation"
class ImageGenerationError(RuntimeError):
"""A recoverable image-provider failure (the report still completes)."""
class ImageGenerationSettings(BaseModel):
"""Server-only configuration for a report image endpoint.
Example ``config.yaml`` section::
deep_research:
image_generation:
enabled: true
provider: dashscope_native
base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
api_key: $DEEP_RESEARCH_IMAGE_API_KEY
model: qwen-image-3.0-pro
``api_key`` is resolved by :class:`AppConfig` while loading YAML, but this
object is deliberately not placed in ``DeepResearchConfig`` and is never
persisted to a session/job row.
"""
enabled: bool = False
provider: Literal["openai_compatible", "dashscope_native"] = "openai_compatible"
base_url: str = ""
api_key: str = ""
model: str = ""
size: str = "1024x1024"
quality: str | None = None
watermark: bool = False
timeout_seconds: float = Field(default=120, ge=1, le=300)
model_config = {"extra": "ignore"}
@field_validator("base_url")
@classmethod
def _normalise_base_url(cls, value: str) -> str:
return value.strip().rstrip("/")
@field_validator("size")
@classmethod
def _validate_size(cls, value: str) -> str:
text = value.strip()
if not text or len(text) > 32:
raise ValueError("image_generation.size must be a short non-empty value")
return text
@property
def is_configured(self) -> bool:
return (
self.enabled
and self.base_url.startswith(("https://", "http://"))
and bool(self.api_key.strip())
and bool(self.model.strip())
)
@classmethod
def from_app_config(cls) -> ImageGenerationSettings:
"""Read the optional ``deep_research.image_generation`` section.
The core ``AppConfig`` allows product-specific extra sections, which
keeps this optional capability backward-compatible with old installs.
Any malformed optional configuration disables image generation rather
than preventing the gateway from serving normal research requests.
"""
try:
from deerflow.config import get_app_config
root = (get_app_config().model_extra or {}).get("deep_research")
raw = root.get("image_generation") if isinstance(root, dict) else None
return cls.model_validate(raw if isinstance(raw, dict) else {})
except Exception: # noqa: BLE001
return cls()
@runtime_checkable
class ImageProvider(Protocol):
"""Generate an image for a research section.
Successful providers return a mapping with binary ``data``, ``mime_type``,
``alt`` and ``prompt`` fields. The runner, not the provider, writes the
result into a protected research artifact.
"""
async def generate(
self,
prompt: str,
*,
section_id: str = "",
user_id: str = "",
) -> dict[str, Any] | None:
"""Return image bytes metadata, or ``None`` when generation is disabled."""
...
class NullImageProvider:
"""No-op image provider — ``generate_images=false`` default."""
async def generate(
self,
prompt: str,
*,
section_id: str = "",
user_id: str = "",
) -> None:
return None
class OpenAICompatibleImageProvider:
"""Generate one image through a configured OpenAI-compatible endpoint.
``transport`` is injection-only for adapter tests. Production instances
use a normal ``httpx.AsyncClient`` and make no assumptions about a specific
vendor beyond the standard ``/images/generations`` response shape.
"""
def __init__(
self,
settings: ImageGenerationSettings,
*,
transport: httpx.AsyncBaseTransport | None = None,
) -> None:
if not settings.is_configured:
raise ValueError("Image generation provider is not configured")
self._settings = settings
self._transport = transport
async def generate(
self,
prompt: str,
*,
section_id: str = "",
user_id: str = "",
) -> dict[str, Any]:
del user_id # Credentials are deployment-scoped; users never supply them.
body: dict[str, Any] = {
"model": self._settings.model,
"prompt": prompt,
"n": 1,
"size": self._settings.size,
# Base64 is mandatory: it yields a stable, protected local artifact.
"response_format": "b64_json",
}
if self._settings.quality:
body["quality"] = self._settings.quality
headers = {
"Authorization": f"Bearer {self._settings.api_key}",
"Content-Type": "application/json",
}
endpoint = f"{self._settings.base_url}/images/generations"
try:
async with httpx.AsyncClient(
timeout=self._settings.timeout_seconds,
transport=self._transport,
) as client:
response = await client.post(endpoint, json=body, headers=headers)
response.raise_for_status()
except httpx.TimeoutException as exc:
raise ImageGenerationError("图片生成服务响应超时") from exc
except httpx.HTTPStatusError as exc:
raise ImageGenerationError(f"图片生成服务返回 HTTP {exc.response.status_code}") from exc
except httpx.HTTPError as exc:
raise ImageGenerationError("图片生成服务暂时不可用") from exc
try:
payload = response.json()
except ValueError as exc:
raise ImageGenerationError("图片生成服务返回了无效响应") from exc
items = payload.get("data") if isinstance(payload, dict) else None
item = items[0] if isinstance(items, list) and items and isinstance(items[0], dict) else None
encoded = str((item or {}).get("b64_json") or "")
if not encoded:
raise ImageGenerationError("图片生成服务未返回可保存的图片数据")
# A few compatible endpoints prepend a data-URL header. Strip it
# without accepting arbitrary content as a URL or another fetch target.
if encoded.startswith("data:") and "," in encoded:
encoded = encoded.split(",", 1)[1]
try:
data = base64.b64decode(encoded, validate=True)
except (ValueError, binascii.Error) as exc:
raise ImageGenerationError("图片生成服务返回的图片编码无效") from exc
if not data or len(data) > _MAX_IMAGE_BYTES:
raise ImageGenerationError("生成图片为空或超过大小限制")
mime_type = str((item or {}).get("mime_type") or "image/png").lower()
if mime_type not in {"image/png", "image/jpeg", "image/webp"}:
mime_type = "image/png"
alt = f"{section_id or '研究报告'}配图"
return {"data": data, "mime_type": mime_type, "alt": alt, "prompt": prompt}
class DashScopeNativeImageProvider:
"""Generate report illustrations through DashScope's native image API.
Qwen Image 3.0 and Wan 2.7 do not implement the OpenAI
``/images/generations`` request/response contract. They receive a
multimodal ``input.messages`` payload and normally return a short-lived
image URL. The URL is downloaded immediately so the research report keeps
a protected local artifact, just like the OpenAI-compatible provider.
"""
def __init__(
self,
settings: ImageGenerationSettings,
*,
transport: httpx.AsyncBaseTransport | None = None,
) -> None:
if not settings.is_configured:
raise ValueError("Image generation provider is not configured")
self._settings = settings
self._transport = transport
async def generate(
self,
prompt: str,
*,
section_id: str = "",
user_id: str = "",
) -> dict[str, Any]:
del user_id # Credentials are deployment-scoped; users never supply them.
body = _dashscope_request_body(self._settings, prompt)
headers = {
"Authorization": f"Bearer {self._settings.api_key}",
"Content-Type": "application/json",
}
try:
async with httpx.AsyncClient(
timeout=self._settings.timeout_seconds,
transport=self._transport,
follow_redirects=True,
) as client:
response = await client.post(
_dashscope_generation_endpoint(self._settings.base_url),
json=body,
headers=headers,
)
response.raise_for_status()
payload = response.json()
encoded, image_url, mime_type = _dashscope_image_result(payload)
if encoded:
data = _decode_image_base64(encoded)
elif image_url:
data, mime_type = await _download_dashscope_image(client, image_url, mime_type)
else:
raise ImageGenerationError("千问图片生成服务未返回图片地址或图片数据")
except ImageGenerationError:
raise
except httpx.TimeoutException as exc:
raise ImageGenerationError("图片生成服务响应超时") from exc
except httpx.HTTPStatusError as exc:
raise ImageGenerationError(_http_error_message(exc.response)) from exc
except httpx.HTTPError as exc:
raise ImageGenerationError("图片生成服务暂时不可用") from exc
except ValueError as exc:
raise ImageGenerationError("图片生成服务返回了无效响应") from exc
if not data or len(data) > _MAX_IMAGE_BYTES:
raise ImageGenerationError("生成图片为空或超过大小限制")
alt = f"{section_id or '研究报告'}配图"
return {"data": data, "mime_type": _normalise_mime_type(mime_type), "alt": alt, "prompt": prompt}
def _dashscope_generation_endpoint(base_url: str) -> str:
"""Resolve a native DashScope endpoint without relying on a workspace id.
Token Plan deployments commonly expose the full native endpoint, while
regular DashScope configuration often uses just an API origin. Supporting
both avoids an accidental ``.../generation/images/generations`` path.
"""
base = base_url.rstrip("/")
if base.endswith(_DASHSCOPE_GENERATION_PATH):
return base
parsed = urlparse(base)
if not parsed.scheme or not parsed.netloc:
return base
return f"{parsed.scheme}://{parsed.netloc}{_DASHSCOPE_GENERATION_PATH}"
def _dashscope_request_body(settings: ImageGenerationSettings, prompt: str) -> dict[str, Any]:
parameters: dict[str, Any] = {
"n": 1,
"size": settings.size.replace("x", "*").replace("X", "*"),
"watermark": settings.watermark,
}
# ``prompt_extend`` is a Qwen Image-only parameter. Wan 2.7 rejects
# unrelated generation options, so do not send it there.
if settings.model.strip().lower().startswith("qwen-image-"):
parameters["prompt_extend"] = True
return {
"model": settings.model,
"input": {
"messages": [
{
"role": "user",
"content": [{"text": prompt}],
}
]
},
"parameters": parameters,
}
def _dashscope_image_result(payload: object) -> tuple[str, str, str]:
"""Return optional base64, image URL and MIME type from native output."""
if not isinstance(payload, dict):
return "", "", ""
output = payload.get("output")
choices = output.get("choices") if isinstance(output, dict) else None
if not isinstance(choices, list):
return "", "", ""
for choice in choices:
message = choice.get("message") if isinstance(choice, dict) else None
content = message.get("content") if isinstance(message, dict) else None
if not isinstance(content, list):
continue
for part in content:
if not isinstance(part, dict):
continue
encoded = str(part.get("b64_json") or "")
raw_image_url = part.get("image") or part.get("image_url")
if isinstance(raw_image_url, dict):
raw_image_url = raw_image_url.get("url")
image_url = str(raw_image_url or "")
if encoded or image_url:
return encoded, image_url, str(part.get("mime_type") or "")
return "", "", ""
async def _download_dashscope_image(
client: httpx.AsyncClient,
image_url: str,
mime_type: str,
) -> tuple[bytes, str]:
"""Download only an HTTPS model result, never forwarding the API key."""
parsed = urlparse(image_url)
if parsed.scheme != "https" or not parsed.netloc:
raise ImageGenerationError("千问图片生成服务返回了不安全的图片地址")
response = await client.get(image_url, headers={"Accept": "image/png,image/jpeg,image/webp"})
response.raise_for_status()
final_url = urlparse(str(response.url))
if final_url.scheme != "https" or not final_url.netloc:
raise ImageGenerationError("千问图片下载地址不安全")
response_mime_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
return response.content, response_mime_type or mime_type
def _decode_image_base64(encoded: str) -> bytes:
if encoded.startswith("data:") and "," in encoded:
encoded = encoded.split(",", 1)[1]
try:
return base64.b64decode(encoded, validate=True)
except (ValueError, binascii.Error) as exc:
raise ImageGenerationError("图片生成服务返回的图片编码无效") from exc
def _normalise_mime_type(value: str) -> str:
mime_type = value.lower()
return mime_type if mime_type in {"image/png", "image/jpeg", "image/webp"} else "image/png"
def _http_error_message(response: httpx.Response) -> str:
"""Expose a short provider message without leaking credentials or payloads."""
detail = ""
try:
payload = response.json()
if isinstance(payload, dict):
error = payload.get("error")
source = error if isinstance(error, dict) else payload
message = source.get("message") if isinstance(source, dict) else None
if isinstance(message, str) and message.strip():
detail = f":{message.strip()[:300]}"
except ValueError:
pass
return f"图片生成服务返回 HTTP {response.status_code}{detail}"
def build_image_provider() -> ImageProvider:
"""Build the optional provider from server config, or a safe no-op."""
settings = ImageGenerationSettings.from_app_config()
if not settings.is_configured:
return NullImageProvider()
if settings.provider == "dashscope_native":
return DashScopeNativeImageProvider(settings)
return OpenAICompatibleImageProvider(settings)
__all__ = [
"ImageGenerationError",
"ImageGenerationSettings",
"ImageProvider",
"NullImageProvider",
"OpenAICompatibleImageProvider",
"DashScopeNativeImageProvider",
"build_image_provider",
]
@@ -0,0 +1,639 @@
"""LLM adapter — the single chokepoint between vendored code and DeerFlow models.
The vendored GPT Researcher code expects ``create_chat_completion()`` /
``get_llm()`` style helpers (``gpt_researcher/utils/llm.py``). Rather than
letting it dynamically import providers, we keep those function *signatures* in
the vendored copy but route them through :class:`DeerFlowCompletionBackend`,
which delegates to DeerFlow's :func:`create_chat_model`.
Responsibilities (§9):
- Resolve the model name from the per-task ``DeepResearchConfig`` by role
(``fast`` / ``smart`` / ``strategic``); ``None`` → system default.
- Convert ``[{role, content}, ...]`` dicts to LangChain messages.
- Call ``model.ainvoke()`` and normalise text + ``usage_metadata``.
- Support structured output via a Pydantic ``response_schema`` (one JSON-repair
retry, no ``json-repair`` hard dep — §9.5).
- Emit a ``model_usage`` event per call.
- Honour the :class:`CancellationToken`.
Retry policy (§9.5): exactly **one** retry layer here — a structured-output
parse failure triggers one "fix the JSON" re-prompt. Cancel / permission /
config errors are never retried.
"""
from __future__ import annotations
import asyncio
import logging
from collections.abc import Awaitable, Callable
from typing import TYPE_CHECKING, Any
from deerflow.agents.deep_research.cancellation import CancellationToken
from deerflow.agents.deep_research.config import DeepResearchConfig, ModelRole
from deerflow.agents.deep_research.events import EventSink
from deerflow.agents.deep_research.types import CompletionResult
from deerflow.utils.stream_text import InlineThinkTagFilter, strip_inline_think_tags
if TYPE_CHECKING:
from langchain.chat_models import BaseChatModel
from langchain_core.messages import BaseMessage
from pydantic import BaseModel
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 ──────────────────────────────────────────────────────
def to_langchain_messages(messages: list[dict[str, str]]) -> list[BaseMessage]:
"""Convert ``[{role, content}, ...]`` dicts to LangChain message objects.
``role`` accepts the usual OpenAI-ish names: ``system`` / ``user`` /
``assistant`` / ``human`` / ``ai``. Unknown roles fall back to ``HumanMessage``
so a bad prompt never crashes the whole research run.
"""
from langchain_core.messages import (
AIMessage,
HumanMessage,
SystemMessage,
)
out: list[BaseMessage] = []
for m in messages:
role = (m.get("role") or "user").lower()
content = m.get("content") or ""
if role in ("system", "developer"):
out.append(SystemMessage(content=content))
elif role in ("assistant", "ai"):
out.append(AIMessage(content=content))
else: # user / human / unknown → human (safe default)
out.append(HumanMessage(content=content))
return out
def _content_to_text(resp: Any) -> str:
"""Best-effort extraction of text from a LangChain AIMessage-like response."""
content = getattr(resp, "content", None)
if isinstance(content, str):
return content
if isinstance(content, list):
# Some providers return content blocks; concatenate text parts.
parts: list[str] = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict):
# Never fall through to ``content`` for structured reasoning
# blocks. Providers differ here, but those blocks are not
# report prose and must not reach ReportChunkEmitter.
if block.get("type") in {
"thinking",
"thinking_delta",
"reasoning",
"reasoning_delta",
}:
continue
parts.append(str(block.get("text") or block.get("content") or ""))
return "".join(parts)
return str(content or "")
def _reasoning_delta(chunk: Any) -> str:
"""Extract the incremental reasoning/thinking text from a streamed chunk.
Reasoning models (deepseek-reasoner, GLM thinking, QwQ, ...) stream their
thinking in ``additional_kwargs.reasoning_content`` while ``content`` stays
empty until the final answer starts. A stream loop that only reads
``content`` skips these chunks entirely, so callers get a dedicated
callback for them.
"""
ak = getattr(chunk, "additional_kwargs", None) or {}
val = ak.get("reasoning_content") or ak.get("reasoning") or ""
if isinstance(val, str) and val:
return val
# Anthropic/OpenAI-compatible adapters may put the same increment in an
# explicitly typed content block instead of ``additional_kwargs``.
content = getattr(chunk, "content", None)
if isinstance(content, list):
parts = [
str(block.get("text") or block.get("content") or "")
for block in content
if isinstance(block, dict)
and block.get("type") in {"thinking", "thinking_delta", "reasoning", "reasoning_delta"}
]
return "".join(parts)
return ""
def _extract_usage(resp: Any) -> dict[str, Any]:
"""Read ``AIMessage.usage_metadata`` (§9.4) — model-agnostic token accounting."""
um = getattr(resp, "usage_metadata", None)
if isinstance(um, dict):
return {
"prompt_tokens": um.get("input_tokens", 0),
"completion_tokens": um.get("output_tokens", 0),
"total_tokens": um.get("total_tokens", 0),
}
# Fallback: some providers populate response_metadata.
rm = getattr(resp, "response_metadata", None) or {}
token_usage = rm.get("token_usage") or rm.get("usage") or {}
if isinstance(token_usage, dict) and token_usage:
return {
"prompt_tokens": token_usage.get("prompt_tokens", 0),
"completion_tokens": token_usage.get("completion_tokens", 0),
"total_tokens": token_usage.get("total_tokens", 0),
}
return {}
# ── errors ──────────────────────────────────────────────────────────────────
class CompletionError(Exception):
"""Non-retryable completion failure (config / permission / budget)."""
def __init__(self, message: str, *, code: str = "completion_error", retryable: bool = False) -> None:
super().__init__(message)
self.code = code
self.retryable = retryable
# ── the backend ─────────────────────────────────────────────────────────────
class DeerFlowCompletionBackend:
"""The LLM adapter every vendored call funnels through.
Constructed once per job (with the frozen config) and handed to runners via
:class:`AdapterBundle`. Model instances are cached by role so repeated
calls don't rebuild the provider.
"""
def __init__(
self,
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]] = {}
# ── model resolution ────────────────────────────────────────────────────
def _resolve_model_name(self, role: ModelRole) -> str | None:
return self._config.resolve_model_name(role)
def _get_model(self, role: ModelRole) -> BaseChatModel:
name = self._resolve_model_name(role)
cache_key = name or "__default__"
cached = self._models.get(cache_key)
if cached is not None:
return cached
from deerflow.models import create_chat_model
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
# ── the main entry point ────────────────────────────────────────────────
async def complete(
self,
*,
model_role: ModelRole = "smart",
messages: list[dict[str, str]],
temperature: float | None = None,
response_schema: type[BaseModel] | None = None,
operation: str = "unknown",
) -> CompletionResult:
"""Run one completion, normalise output, bill usage.
Args:
model_role: which config role to use (fast/cheap research queries →
``fast``; report writing → ``smart``; strategic planning → ``strategic``).
messages: OpenAI-style ``[{role, content}]`` dicts.
temperature: optional override (most vendored calls don't set one).
response_schema: if given, parse + validate the output against this
Pydantic model (structured output). One JSON-repair retry on
parse failure (§9.5).
operation: a short label for the ``model_usage`` event
(e.g. ``"generate_queries"``, ``"write_report"``).
"""
if self._cancel is not None:
self._cancel.raise_if_cancelled()
model = self._get_model(model_role)
model_name = self._resolve_model_name(model_role) or "default"
lc_messages = to_langchain_messages(messages)
kwargs: dict[str, Any] = {}
if temperature is not None:
kwargs["temperature"] = temperature
# ── plain completion ──
if response_schema is None:
resp = await self._invoke_with_timeout(model, lc_messages, kwargs, operation)
text = _content_to_text(resp)
usage = _extract_usage(resp)
await self._record_usage(model_name, operation, usage)
return CompletionResult(text=text, model=model_name, usage=usage)
# ── structured completion (with one repair retry) ──
schema_instructions = _schema_instructions(response_schema)
structured_messages = list(lc_messages)
# Append the schema instruction to the last system/user message block.
structured_messages = _inject_schema_hint(structured_messages, schema_instructions)
for attempt in range(2):
if self._cancel is not None:
self._cancel.raise_if_cancelled()
resp = await self._invoke_with_timeout(model, structured_messages, kwargs, operation)
text = _content_to_text(resp)
usage = _extract_usage(resp)
parsed = _try_parse_structured(text, response_schema)
if parsed is not None:
await self._record_usage(model_name, operation, usage)
return CompletionResult(text=text, model=model_name, usage=usage, structured=parsed)
if attempt == 0:
# One repair re-prompt (§9.5).
logger.warning("deep_research llm: JSON parse failed for %s, retrying", operation)
structured_messages = _inject_repair_hint(structured_messages, text, response_schema)
await self._record_usage(model_name, operation, usage)
raise CompletionError(
f"Structured output for '{operation}' could not be parsed after retry",
code="structured_parse_failed",
retryable=True,
)
async def _invoke_with_timeout(
self,
model: BaseChatModel,
messages: list[BaseMessage],
kwargs: dict[str, Any],
operation: str,
) -> Any:
"""Bound a non-streaming control-plane call without capping report prose.
Model configurations may have a much longer HTTP ``request_timeout``.
A research job cannot leave its visible planning/review stage frozen for
that whole interval, so these short structured calls get their own
deadline. ``wait_for`` cancels the pending provider coroutine before a
durable runner either uses its safe fallback or records a terminal error.
"""
timeout = self._config.control_plane_timeout_seconds
try:
return await asyncio.wait_for(model.ainvoke(messages, **kwargs), timeout=timeout)
except TimeoutError as exc:
if self._cancel is not None:
self._cancel.raise_if_cancelled()
raise CompletionError(
f"Model did not complete '{operation}' within {timeout:g} seconds",
code="completion_timeout",
retryable=True,
) from exc
async def stream_complete(
self,
*,
model_role: ModelRole = "smart",
messages: list[dict[str, str]],
temperature: float | None = None,
max_tokens: int | None = None,
operation: str = "unknown",
on_delta: Callable[[str], Awaitable[None]] | None = None,
on_reasoning: Callable[[str], Awaitable[None]] | None = None,
) -> CompletionResult:
"""Run a prose completion through LangChain's incremental stream API.
Structured planning/review calls intentionally stay on :meth:`complete`.
This method is reserved for report prose so the final returned text is
exactly the concatenation of the deltas the user has already seen.
``on_reasoning`` receives the thinking/reasoning increments reasoning
models emit before the answer; they are not part of the returned text.
"""
if self._cancel is not None:
self._cancel.raise_if_cancelled()
model = self._get_model(model_role)
model_name = self._resolve_model_name(model_role) or "default"
kwargs: dict[str, Any] = {}
if temperature is not None:
kwargs["temperature"] = temperature
if max_tokens is not None:
# Report-only callers may need a larger completion than a model's
# conservative deployment default. Codex Responses endpoints
# reject both token-limit parameters, so preserve the factory's
# provider-specific exclusion for that adapter.
from deerflow.models.openai_codex_provider import CodexChatModel
if not isinstance(model, CodexChatModel):
kwargs["max_tokens"] = max_tokens
text_parts: list[str] = []
usage: dict[str, Any] = {}
inline_think_filter = InlineThinkTagFilter()
# 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)
attempts = 2 if operation.startswith("write_report") else 1
last_error: Exception | None = None
try:
for attempt in range(attempts):
text_parts.clear()
inline_think_filter = InlineThinkTagFilter()
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
last_error = None
break
except Exception as exc: # noqa: BLE001 - report writing waits like ordinary chat
from deerflow.agents.deep_research.cancellation import ResearchCancelled
if isinstance(exc, (ResearchCancelled, asyncio.CancelledError)):
raise
last_error = exc
# Only replay a clean connection; a half-written stream is
# reset by the runner, not by appending a second attempt.
if text_parts or attempt + 1 >= attempts:
raise
logger.warning(
"deep_research llm: %s stream interrupted before the first token (%s); retrying once",
operation,
type(exc).__name__,
)
await asyncio.sleep(1.5)
if last_error is not None:
raise last_error
finally:
reset_parent_config()
tail, inline_reasoning_tail = inline_think_filter.finish_parts()
if inline_reasoning_tail and on_reasoning is not None:
await on_reasoning(inline_reasoning_tail)
if tail:
text_parts.append(tail)
if on_delta is not None:
await on_delta(tail)
await self._record_usage(model_name, operation, usage)
return CompletionResult(text="".join(text_parts), model=model_name, usage=usage)
async def complete_prose(
self,
*,
model_role: ModelRole = "smart",
messages: list[dict[str, str]],
temperature: float | None = None,
max_tokens: int | None = None,
operation: str = "unknown",
) -> CompletionResult:
"""Generate long prose without the provider's inter-chunk timeout.
This is the report retry path. Some reasoning models pause for longer
than the streaming client's 120-second chunk deadline after already
producing several chunks. A normal complete response can still finish
successfully, so the retry deliberately waits for that full response.
"""
if self._cancel is not None:
self._cancel.raise_if_cancelled()
model = self._get_model(model_role)
model_name = self._resolve_model_name(model_role) or "default"
kwargs: dict[str, Any] = {}
if temperature is not None:
kwargs["temperature"] = temperature
if max_tokens is not None:
from deerflow.models.openai_codex_provider import CodexChatModel
if not isinstance(model, CodexChatModel):
kwargs["max_tokens"] = max_tokens
isolated_config = _parent_isolated_run_config(f"deep_research:{operation}")
reset_parent_config = _clear_inherited_runnable_config(isolated_config)
try:
response = await model.ainvoke(
to_langchain_messages(messages),
config=isolated_config,
**kwargs,
)
finally:
reset_parent_config()
if self._cancel is not None:
self._cancel.raise_if_cancelled()
# ``ainvoke`` returns raw content, including the inline ``<think>``
# block some OpenAI-compatible deployments write there. The streamed
# path filters it out, so this retry path must not reintroduce it.
text = strip_inline_think_tags(_content_to_text(response))
usage = _extract_usage(response)
await self._record_usage(model_name, operation, usage)
return CompletionResult(text=text, model=model_name, usage=usage)
# ── usage accounting ────────────────────────────────────────────────────
async def _record_usage(self, model_name: str, operation: str, usage: dict[str, Any]) -> None:
"""Accumulate per-model totals + emit a ``model_usage`` event."""
bucket = self._usage_totals.setdefault(model_name, {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0})
for k in bucket:
bucket[k] += int(usage.get(k, 0) or 0)
if self._events is not None:
await self._events.emit(
"model_usage",
payload={
"model": model_name,
"operation": operation,
"usage": usage,
},
)
@property
def usage_totals(self) -> dict[str, dict[str, int]]:
"""Snapshot of cumulative token usage by model (for the final result)."""
return {k: dict(v) for k, v in self._usage_totals.items()}
# ── convenience: the upstream-compatible function family ────────────────
#
# These mirror ``gpt_researcher/utils/llm.py`` signatures so the vendored
# action/skill code needs minimal changes — it calls a context-local bound
# method instead of a module global.
async def create_chat_completion(
self,
messages: list[dict[str, str]],
*,
model_role: ModelRole = "smart",
temperature: float | None = None,
response_format: type[BaseModel] | None = None,
stream: bool = False,
) -> str:
"""Upstream-compatible ``create_chat_completion`` → returns raw text."""
if stream and response_format is None:
result = await self.stream_complete(
model_role=model_role,
messages=messages,
temperature=temperature,
operation="chat_completion",
)
else:
result = await self.complete(
model_role=model_role,
messages=messages,
temperature=temperature,
response_schema=response_format,
operation="chat_completion",
)
return result.text
# ── structured-output helpers (no json-repair dependency) ───────────────────
def _schema_instructions(schema: type[BaseModel]) -> str:
"""Build a compact "respond as JSON matching this schema" instruction."""
props = schema.model_json_schema().get("properties", {})
fields = ", ".join(f'"{k}"' for k in props)
return f"Respond with ONLY a valid JSON object (no markdown, no prose) containing these keys: {fields}."
def _inject_schema_hint(messages: list[BaseMessage], hint: str) -> list[BaseMessage]:
"""Append the schema instruction as a final system message."""
from langchain_core.messages import SystemMessage
return [*messages, SystemMessage(content=hint)]
def _inject_repair_hint(messages: list[BaseMessage], bad_text: str, schema: type[BaseModel]) -> list[BaseMessage]:
"""Re-prompt: 'your last reply was invalid JSON, fix it'."""
from langchain_core.messages import HumanMessage
return [
*messages,
HumanMessage(content=(f"Your previous reply was not valid JSON and could not be parsed:\n{bad_text[:500]}\n\nPlease respond again with ONLY a valid JSON object.")),
]
def parse_structured_text(text: str, schema: type[BaseModel]) -> BaseModel | None:
"""Parse a completed (possibly streamed) model output against a schema.
Public wrapper over the same fence-stripping, blob-extracting parse used
by :meth:`DeerFlowCompletionBackend.complete`, so runners that collect the
text through :meth:`stream_complete` can validate it afterwards.
"""
return _try_parse_structured(text, schema)
def _try_parse_structured(text: str, schema: type[BaseModel]) -> BaseModel | None:
"""Strip markdown fences + attempt ``schema.model_validate_json``."""
cleaned = _strip_code_fences(text).strip()
if not cleaned:
return None
try:
return schema.model_validate_json(cleaned)
except Exception:
# Try to locate the first {...} blob as a last resort.
start = cleaned.find("{")
end = cleaned.rfind("}")
if start != -1 and end > start:
try:
return schema.model_validate_json(cleaned[start : end + 1])
except Exception:
return None
return None
def _strip_code_fences(text: str) -> str:
"""Remove ```json ... ``` / ``` ... ``` wrapping if present."""
stripped = text.strip()
if stripped.startswith("```"):
# Drop first line (the fence + optional language tag).
lines = stripped.splitlines()
if len(lines) >= 2:
lines = lines[1:]
if lines and lines[-1].strip().startswith("```"):
lines = lines[:-1]
return "\n".join(lines)
return stripped
__all__ = [
"CompletionError",
"DeerFlowCompletionBackend",
"parse_structured_text",
"to_langchain_messages",
]
@@ -0,0 +1,75 @@
"""Material provider — DeerFlow's unified information-collection boundary.
The vendored GPT Researcher code normally fires off its own retrievers + scrapers
per source URL. We replace that entirely: the :class:`MaterialProvider` returns
**fully-fetched** :class:`ResearchMaterial` objects (``raw_content`` already
populated), so the vendored scraper/BrowserManager is never invoked (§6.4).
First version (Phase 1) wraps :func:`deerflow.community.configurable_search.execute_search`:
1. Run the configured ``web_search`` tool for the query.
2. Map normalised results (``recUuid / content / title / url / source / time``)
→ :class:`ResearchMaterial`.
3. If ``content`` is already full text → use as ``raw_content`` (no fetch needed).
4. If only a snippet → a DeerFlow fetch tool backfills (Phase 2).
5. Dedupe by ``rec_uuid`` → canonical URL → ``content_hash``.
The provider never imports ``app.*`` and never does raw ``requests.get``.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Protocol, runtime_checkable
from deerflow.agents.deep_research.types import ResearchMaterial
if TYPE_CHECKING:
from deerflow.agents.deep_research.cancellation import CancellationToken
@runtime_checkable
class MaterialProvider(Protocol):
"""Protocol every material channel implements (§8.3)."""
async def search(
self,
query: str,
*,
domains: list[str] | None = None,
limit: int = 8,
user_id: str = "",
session_id: str = "",
cancellation: CancellationToken | None = None,
) -> list[ResearchMaterial]:
"""Return fully-fetched materials for ``query``.
Implementations guarantee ``raw_content`` is non-empty for every item
that has fetchable text (the vendored writer relies on this).
"""
...
def dedupe_materials(materials: list[ResearchMaterial]) -> list[ResearchMaterial]:
"""Stable dedup by rec_uuid → canonical url → content_hash (§8.3 §6).
Keeps the first occurrence; later duplicates are dropped (but their queries
are noted on the survivor's metadata so multi-query hits aren't lost).
"""
seen: dict[str, int] = {} # key → index in result
out: list[ResearchMaterial] = []
for m in materials:
key = (m.rec_uuid and f"rec:{m.rec_uuid}") or (m.url and f"url:{m.url}") or m.compute_hash()
if key in seen:
idx = seen[key]
# Record that another query also surfaced this material.
surviving = out[idx]
extra_queries = surviving.metadata.setdefault("_also_matched_queries", [])
if m.query and m.query not in extra_queries:
extra_queries.append(m.query)
continue
seen[key] = len(out)
out.append(m)
return out
__all__ = ["MaterialProvider", "dedupe_materials"]
@@ -0,0 +1,601 @@
"""Deep Research material provider backed by DeerFlow's Q&A retrieval stack.
This is the only place adapted GPT Researcher runners retrieve materials. It
uses the same hierarchy as DeerFlow Q&A instead of treating the legacy
configurable ``web_search`` endpoint as the only possible source:
1. Run enabled Q&A research skills through the existing ``SubagentExecutor``
runtime when their required search tool is registered.
2. Use a configured ``web_search`` provider when the deployment has one.
3. Fall back to DeerFlow's existing keyless DuckDuckGo search provider.
The fallback is important for this offline deployment: its configurable search
entry is deliberately disabled while it still contains a placeholder intranet
endpoint. A missing endpoint must never turn every Deep Research report into
"no materials collected".
"""
from __future__ import annotations
import asyncio
import hashlib
import importlib.util
import json
import logging
import re
from datetime import datetime
from typing import Any
from urllib.parse import urlparse
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.types import ResearchMaterial
logger = logging.getLogger(__name__)
# Treat shorter content as a snippet and try a full-text fetch when available.
SNIPPET_THRESHOLD = 300
ONLINE_SEARCH_TIMEOUT_SECONDS = 45
SECONDARY_ONLINE_SEARCH_TIMEOUT_SECONDS = 20
# Same skills that guide the Q&A assistant's public-web / knowledge retrieval.
# The order deliberately prefers the multi-round skill for a Deep Research job.
QUESTION_ANSWER_RESEARCH_SKILLS: tuple[str, ...] = (
"deep-search",
"web-research",
"weknora-knowledge-search",
)
# A skill is run only when the Q&A runtime exposes the search tool it needs.
# This prevents a disabled placeholder web_search config from launching an
# agent which is incapable of searching and can only wait for its timeout.
_SKILL_REQUIRED_TOOLS: dict[str, set[str]] = {
"deep-search": {"web_search"},
"web-research": {"web_search"},
"weknora-knowledge-search": {"weknora_search"},
}
class DeerFlowMaterialProvider:
"""MaterialProvider backed by the Q&A skills and online retrieval stack.
A configurable ``web_search`` endpoint remains supported, but it is no
longer a single point of failure. All returned materials preserve the
original source, URL and retrieval channel for citations and auditing.
"""
def __init__(
self,
*,
user_id: str = "",
session_id: str = "",
runtime_thread_id: str = "",
model_name: str | None = None,
fetch_enabled: bool = True,
retrieval_skills: list[str] | None = None,
) -> None:
self._user_id = user_id
self._session_id = session_id
self._runtime_thread_id = runtime_thread_id
self._model_name = model_name
self._fetch_enabled = fetch_enabled
self._retrieval_skills = _normalize_named_skills(retrieval_skills)
self._settings = None
self._settings_error: str | None = None
self._question_answer_tool_names = _load_question_answer_tool_names(model_name)
self._research_skills = _load_question_answer_research_skills()
self._online_search_available = importlib.util.find_spec("ddgs") is not None
self._online_search_semaphore: asyncio.Semaphore | None = None
try:
from deerflow.community.configurable_search.tools import ConfigurableSearchSettings
from deerflow.config import get_app_config
cfg = get_app_config().get_tool_config("web_search")
self._settings = ConfigurableSearchSettings.from_tool_config(cfg)
if not self._settings.enabled:
self._settings_error = "web_search tool is disabled in config"
self._settings = None
except Exception as exc: # noqa: BLE001
self._settings_error = f"web_search not configured: {exc}"
logger.warning("Deep Research configurable web_search unavailable: %s", self._settings_error)
async def search(
self,
query: str,
*,
domains: list[str] | None = None,
limit: int = 8,
user_id: str = "",
session_id: str = "",
cancellation=None,
) -> list[ResearchMaterial]:
"""Collect actual Q&A-compatible materials for one research query."""
if cancellation is not None:
cancellation.raise_if_cancelled()
materials: list[ResearchMaterial] = []
seen_keys: set[str] = set()
directed_skills = bool(self._retrieval_skills)
# 1. The genuine Q&A skill runtime. Skills may call web, MCP or another
# deployment-specific source according to their SKILL.md instructions.
# A non-empty 检索来源 list replaces the default research-skill trio.
skill_results = await self._search_via_question_answer_skills(query, limit=limit)
materials.extend(
self._normalise_search_results(
skill_results,
query=query,
channel="skill",
domains=domains,
seen_keys=seen_keys,
)
)
if cancellation is not None:
cancellation.raise_if_cancelled()
# Specified skills are the retrieval source: do not also dump generic
# web_search / DDG on top. Empty 检索来源 keeps the original fallbacks.
if directed_skills:
hydrated: list[ResearchMaterial] = []
for material in materials[:limit]:
if cancellation is not None:
cancellation.raise_if_cancelled()
if material.url and len(material.raw_content) < SNIPPET_THRESHOLD and self._fetch_enabled:
fetched = await asyncio.to_thread(_safe_fetch, material.url)
if fetched:
material.raw_content = fetched
if material.raw_content:
hydrated.append(material)
return dedupe_materials(hydrated)[:limit]
# 2. Retain compatibility with deployed configurable search providers.
if len(materials) < limit:
configured_results = await self._search_configured_web(query)
materials.extend(
self._normalise_configured_results(
configured_results,
query=query,
domains=domains,
seen_keys=seen_keys,
)
)
if cancellation is not None:
cancellation.raise_if_cancelled()
# 3. Reuse DeerFlow's maintained online provider if the Q&A search tool
# is absent or the configured provider returned too few materials.
if len(materials) < limit:
online_results = await self._search_via_online_fallback(query, limit=limit - len(materials))
materials.extend(
self._normalise_search_results(
online_results,
query=query,
channel="web_search",
domains=domains,
seen_keys=seen_keys,
)
)
hydrated: list[ResearchMaterial] = []
for material in materials[:limit]:
if cancellation is not None:
cancellation.raise_if_cancelled()
if material.url and len(material.raw_content) < SNIPPET_THRESHOLD and self._fetch_enabled:
fetched = await asyncio.to_thread(_safe_fetch, material.url)
if fetched:
material.raw_content = fetched
if material.raw_content:
hydrated.append(material)
return dedupe_materials(hydrated)[:limit]
async def _search_via_question_answer_skills(self, query: str, *, limit: int) -> list[Any]:
"""Run eligible research skills through the same runtime as Q&A."""
runnable = self._runnable_research_skills()
if not runnable:
logger.info(
"Deep Research Q&A skills are enabled but their required search tools are unavailable; "
"using the online fallback"
)
return []
try:
from deerflow.agents.ai_writing.nodes._skill_agent import run_skill_via_real_agent
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research could not load the Q&A skill runtime: %s", exc)
return []
run_config = {
"configurable": {
"thread_id": self._runtime_thread_id,
"model_name": self._model_name or "",
}
}
state = {"model_name": self._model_name or ""}
collected: list[Any] = []
directed = bool(self._retrieval_skills)
for skill in runnable:
try:
results, error = await run_skill_via_real_agent(
skill=skill,
intent=f"Collect verifiable research materials for: {query}",
keywords=[query],
user_query=query,
config=run_config,
state=state,
model_name_fallback=self._model_name,
max_results=limit,
timeout_s=ONLINE_SEARCH_TIMEOUT_SECONDS,
)
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research Q&A skill %s failed: %s", skill.name, exc)
continue
if results:
collected.extend(list(results)[:limit])
if not directed or len(collected) >= limit:
return collected[:limit]
if error:
logger.info("Deep Research Q&A skill %s returned no materials: %s", skill.name, error)
return collected[:limit]
def _runnable_research_skills(self) -> list[Any]:
"""Default Q&A trio, or the report-structure 检索来源 when named."""
skills = (
_load_named_research_skills(self._retrieval_skills)
if self._retrieval_skills
else self._research_skills
)
if self._retrieval_skills:
# User-named skills may use any tool; skip the trio's required-tool gate.
return list(skills)
return [
skill
for skill in skills
if _SKILL_REQUIRED_TOOLS.get(skill.name, set()) <= self._question_answer_tool_names
]
async def _search_configured_web(self, query: str) -> list[dict[str, Any]]:
"""Run the existing configurable ``web_search`` adapter when enabled."""
if self._settings is None:
return []
try:
from deerflow.community.configurable_search.tools import execute_search
raw = await execute_search(query, self._settings)
envelope = json.loads(raw)
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research configured web_search failed: %s", exc)
return []
if not isinstance(envelope, dict) or envelope.get("error"):
logger.info("Deep Research configured web_search returned no materials: %s", envelope)
return []
return [item for item in envelope.get("results") or [] if isinstance(item, dict)]
async def _search_via_online_fallback(self, query: str, *, limit: int) -> list[Any]:
"""Use maintained DDG retrieval, then a relevant-result web fallback."""
if not self._online_search_available or limit < 1:
return []
if self._online_search_semaphore is None:
self._online_search_semaphore = asyncio.Semaphore(2)
try:
from deerflow.agents.ai_writing.search.duckduckgo_search import DuckDuckGoSearchProvider
async with self._online_search_semaphore:
provider = DuckDuckGoSearchProvider(max_timeout=ONLINE_SEARCH_TIMEOUT_SECONDS)
ddg_results = await asyncio.wait_for(
provider.search(query, max_results=limit),
timeout=ONLINE_SEARCH_TIMEOUT_SECONDS + 5,
)
relevant_results = _filter_relevant_search_results(ddg_results, query)
if relevant_results:
return relevant_results[:limit]
# DDGS can occasionally return generic login/tracking pages for
# Chinese queries. Do not turn those into report citations;
# collect a second set from the search HTML instead.
return await asyncio.to_thread(_search_360_web, query, limit)
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research online fallback search failed for %r: %s", query, exc)
return []
def _normalise_configured_results(
self,
results: list[dict[str, Any]],
*,
query: str,
domains: list[str] | None,
seen_keys: set[str],
) -> list[ResearchMaterial]:
materials: list[ResearchMaterial] = []
for item in results:
material = result_to_material(item, query=query)
if not _material_matches_domains(material, domains) or not _accept_material(material, seen_keys):
continue
material.metadata["retrieval_channel"] = "configured_web_search"
materials.append(material)
return materials
def _normalise_search_results(
self,
results: list[Any],
*,
query: str,
channel: str,
domains: list[str] | None,
seen_keys: set[str],
) -> list[ResearchMaterial]:
materials: list[ResearchMaterial] = []
for result in results:
material = _search_result_to_material(result, query=query, channel=channel)
if material is None or not _material_matches_domains(material, domains) or not _accept_material(material, seen_keys):
continue
materials.append(material)
return materials
@property
def is_configured(self) -> bool:
"""Whether at least one material channel can run."""
return bool(self.material_channels)
@property
def material_channels(self) -> list[str]:
"""Advertise active Q&A-compatible retrieval channels to the frontend."""
channels: list[str] = []
if any(
_SKILL_REQUIRED_TOOLS.get(skill.name, set()) <= self._question_answer_tool_names
for skill in self._research_skills
):
channels.append("skill")
if self._settings is not None or self._online_search_available:
channels.append("web_search")
return channels
@property
def settings_error(self) -> str | None:
return self._settings_error
def result_to_material(item: dict[str, Any], *, query: str) -> ResearchMaterial:
"""Map a configurable-search result item into a research material.
Public so the chat-collection thread harvester can reuse the exact same
field mapping for ``web_search`` tool envelopes harvested off a thread.
"""
rec_uuid = str(item.get("recUuid") or "").strip() or None
url = str(item.get("url") or "").strip() or None
title = str(item.get("title") or "").strip()
content = str(item.get("content") or "").strip()
source = str(item.get("source") or "").strip() or "web"
raw_hash = hashlib.sha256((url or rec_uuid or content).encode("utf-8")).hexdigest()[:32]
published_at = _try_parse_datetime(str(item.get("publish_time") or item.get("time") or "").strip())
return ResearchMaterial(
id=f"src_{raw_hash[:16]}",
query=query,
title=title,
url=url,
raw_content=content,
snippet=content[:200] if content else None,
source=source,
source_type="web",
published_at=published_at,
rec_uuid=rec_uuid,
content_hash=raw_hash,
)
def _search_result_to_material(result: Any, *, query: str, channel: str) -> ResearchMaterial | None:
"""Map a Q&A/AI-writing SearchResult-like object into ResearchMaterial."""
title = str(getattr(result, "title", "") or "").strip()
content = str(getattr(result, "content", "") or "").strip()
if not title and not content:
return None
url = str(getattr(result, "url", "") or "").strip() or None
rec_uuid = str(getattr(result, "recUuid", "") or "").strip() or None
source = str(getattr(result, "source", "") or "").strip() or channel
source_type = str(getattr(result, "source_type", "") or "").strip()
if source_type not in {"web", "knowledge", "skill", "mcp", "file", "other"}:
source_type = "skill" if channel == "skill" else "web"
raw_hash = hashlib.sha256((url or rec_uuid or title or content).encode("utf-8")).hexdigest()[:32]
return ResearchMaterial(
id=f"src_{raw_hash[:16]}",
query=query,
title=title,
url=url,
raw_content=content,
snippet=content[:200] if content else None,
source=source,
source_type=source_type,
published_at=_try_parse_datetime(str(getattr(result, "published_at", "") or "").strip()),
relevance_score=_safe_float(getattr(result, "relevance_score", None)),
rec_uuid=rec_uuid,
content_hash=raw_hash,
metadata={"retrieval_channel": channel},
)
def _load_question_answer_tool_names(model_name: str | None) -> set[str]:
"""Return exactly the tool names the Q&A agent can currently call."""
try:
from deerflow.tools import get_available_tools
return {str(tool.name) for tool in get_available_tools(model_name=model_name, include_mcp=True)}
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research failed to inspect Q&A tools: %s", exc)
return set()
def _load_question_answer_research_skills() -> list[Any]:
"""Load only enabled Q&A research skills, preserving normal skill state."""
try:
from deerflow.skills import get_or_new_skill_storage
by_name = {skill.name: skill for skill in get_or_new_skill_storage().load_skills(enabled_only=True)}
return [by_name[name] for name in QUESTION_ANSWER_RESEARCH_SKILLS if name in by_name]
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research failed to load Q&A research skills: %s", exc)
return []
def _load_named_research_skills(names: list[str]) -> list[Any]:
"""Load enabled skills by name, preserving the requested order."""
if not names:
return []
try:
from deerflow.skills import get_or_new_skill_storage
by_name = {skill.name: skill for skill in get_or_new_skill_storage().load_skills(enabled_only=True)}
return [by_name[name] for name in names if name in by_name]
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research failed to load named retrieval skills: %s", exc)
return []
def _normalize_named_skills(value: list[str] | None) -> list[str]:
from deerflow.persistence.report_structures.skills import normalize_retrieval_skills
return normalize_retrieval_skills(value)
def _material_matches_domains(material: ResearchMaterial, domains: list[str] | None) -> bool:
"""Apply the requested domain allow-list without dropping URL-less KB hits."""
if not domains or not material.url:
return True
host = (urlparse(material.url).hostname or "").lower()
allowed = {str(domain).lower().strip().lstrip(".") for domain in domains if str(domain).strip()}
return not allowed or any(host == domain or host.endswith(f".{domain}") for domain in allowed)
def _accept_material(material: ResearchMaterial, seen_keys: set[str]) -> bool:
"""Deduplicate cross-channel hits before optional fetch backfill."""
key = material.url or material.rec_uuid or material.content_hash
if not key or key in seen_keys:
return False
seen_keys.add(key)
return True
def _safe_float(value: Any) -> float | None:
try:
return float(value) if value is not None else None
except (TypeError, ValueError):
return None
def _filter_relevant_search_results(results: list[Any], query: str) -> list[Any]:
"""Discard obvious search-engine noise before it reaches report citations."""
tokens = _query_relevance_tokens(query)
if not tokens:
return list(results)
kept: list[Any] = []
for result in results:
haystack = " ".join(
[
str(getattr(result, "title", "") or ""),
str(getattr(result, "content", "") or ""),
str(getattr(result, "url", "") or ""),
]
).lower()
if any(token in haystack for token in tokens):
kept.append(result)
return kept
def _query_relevance_tokens(query: str) -> set[str]:
"""Build compact English/CJK tokens suitable for rejecting blank noise."""
tokens = {token.lower() for token in re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", query)}
for chunk in re.findall(r"[\u4e00-\u9fff]+", query):
for width in (4, 3, 2):
tokens.update(chunk[index : index + width] for index in range(max(0, len(chunk) - width + 1)))
return tokens
def _search_360_web(query: str, limit: int) -> list[Any]:
"""Return parsed, real 360 Search snippets when DDG returns no relevant hit."""
try:
import httpx
from bs4 import BeautifulSoup
from deerflow.agents.ai_writing.search.base import SearchResult
response = httpx.get(
"https://www.so.com/s",
params={"q": query},
headers={"User-Agent": "Mozilla/5.0 (compatible; DeerFlow/1.0)"},
timeout=SECONDARY_ONLINE_SEARCH_TIMEOUT_SECONDS,
follow_redirects=True,
)
response.raise_for_status()
soup = BeautifulSoup(response.text, "html.parser")
rows: list[Any] = []
seen_urls: set[str] = set()
for card in soup.select("li.res-list"):
anchor = card.select_one("h3 a") or card.select_one("a.res-link")
if anchor is None:
continue
title = anchor.get_text(" ", strip=True)
url = str(anchor.get("href") or "").strip()
content_node = card.select_one(".res-desc") or card.select_one(".res-rich") or card
content = content_node.get_text(" ", strip=True)
if not title or not content or not url or url in seen_urls:
continue
seen_urls.add(url)
rows.append(
SearchResult(
title=title,
content=content[:500],
source=urlparse(url).hostname or "360 Search",
published_at="",
url=url,
relevance_score=0.7,
source_type="internet",
)
)
if len(rows) >= limit:
break
return _filter_relevant_search_results(rows, query)[:limit]
except Exception as exc: # noqa: BLE001
logger.warning("Deep Research 360 fallback search failed for %r: %s", query, exc)
return []
def _try_parse_datetime(value: str) -> datetime | None:
for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d", "%Y/%m/%d", "%Y-%m-%dT%H:%M:%S"):
try:
return datetime.strptime(value[:19], fmt)
except ValueError:
continue
return None
def _safe_fetch(url: str) -> str:
"""Best-effort full-text fetch via the configured DeerFlow web_fetch tool."""
try:
from deerflow.config import get_app_config
fetch_cfg = get_app_config().get_tool_config("web_fetch")
if fetch_cfg is None or not fetch_cfg.enabled:
return ""
use = fetch_cfg.use or ""
html = ""
if "jina_ai" in use:
from deerflow.community.jina_ai.jina_client import JinaClient
html = JinaClient().crawl(url, return_format="html", timeout=10) or ""
elif "infoquest" in use:
from deerflow.community.infoquest.infoquest_client import InfoQuestClient
html = InfoQuestClient().fetch(url, return_format="html") or ""
if not html or html.startswith("Error"):
return ""
from deerflow.utils.readability import ReadabilityExtractor
return ReadabilityExtractor().extract_article(html).to_markdown(including_title=True) or ""
except Exception as exc: # noqa: BLE001
logger.debug("Deep Research material fetch failed for %s: %s", url, exc)
return ""
__all__ = [
"DeerFlowMaterialProvider",
"ONLINE_SEARCH_TIMEOUT_SECONDS",
"QUESTION_ANSWER_RESEARCH_SKILLS",
"SNIPPET_THRESHOLD",
"result_to_material",
]
@@ -0,0 +1,135 @@
"""Cooperative cancellation token for deep-research jobs.
The vendored GPT Researcher loops (recursive deep research, sub-topic fan-out,
multi-agent review cycles) can run for minutes. Every adapter and runner polls
a single :class:`CancellationToken` so a user cancel (or a lease takeover)
promptly unwinds the whole tree instead of burning model budget to completion.
Design:
- ``CancellationToken`` is an asyncio-friendly flag — ``cancel()`` flips it,
``raise_if_cancelled()`` is the checked-call sites sprinkle at loop boundaries.
- A token is created **per job execution** by the executor and threaded into the
``AdapterBundle``; it is never a process global.
- The executor's cancellation watcher calls ``cancel()`` when it observes
``cancel_requested`` in the DB; the running ``asyncio.Task`` sees
``CancelledError`` propagate up.
"""
from __future__ import annotations
import asyncio
class CancellationToken:
"""A lightweight cooperative cancel flag.
Thread-safe in the asyncio sense (single event loop): ``cancel()`` and
``is_cancelled`` only touch the flag / an asyncio event.
"""
__slots__ = ("_cancelled", "_event", "_reason")
def __init__(self) -> None:
self._cancelled: bool = False
self._reason: str = ""
# Used by ``wait()``; lazily created on first await so we don't need a
# running loop at construction time (tokens are often built in sync code).
self._event: asyncio.Event | None = None
# ── state queries ───────────────────────────────────────────────────────
@property
def is_cancelled(self) -> bool:
return self._cancelled
@property
def reason(self) -> str:
return self._reason
# ── transitions ─────────────────────────────────────────────────────────
def cancel(self, reason: str = "cancelled") -> None:
"""Flip the flag and wake any coroutine blocked on ``wait()``."""
self._cancelled = True
self._reason = reason
if self._event is not None:
self._event.set()
# ── checked-call helpers ────────────────────────────────────────────────
def raise_if_cancelled(self) -> None:
"""Raise :class:`ResearchCancelled` if the token has been cancelled.
Sprinkle at the top of every loop iteration in vendored / runner code:
search fan-out, context compression, report chunking, graph nodes.
"""
if self._cancelled:
raise ResearchCancelled(self._reason)
async def wait(self, timeout: float | None = None) -> None:
"""Block until cancelled (or ``timeout`` elapses).
Useful when a node needs to *park* until either cancellation or an
external resume signal — though for human-review interrupts the
LangGraph ``interrupt()`` mechanism is preferred.
"""
if self._cancelled:
return
if self._event is None:
self._event = asyncio.Event()
try:
await asyncio.wait_for(self._event.wait(), timeout=timeout)
except TimeoutError:
pass
# ── context-manager sugar (check on enter/exit of a scoped unit) ────────
def __enter__(self) -> CancellationToken:
self.raise_if_cancelled()
return self
def __exit__(self, *exc: object) -> None:
self.raise_if_cancelled()
class ResearchCancelled(Exception):
"""Raised when a :class:`CancellationToken` is flipped mid-run.
Deliberately **not** a subclass of ``asyncio.CancelledError``: the latter is
used by the executor to kill the task object; ``ResearchCancelled`` is the
*checked* variant that lets adapters/runners unwind cleanly and record a
``cancelled`` terminal state rather than an error.
"""
def __init__(self, reason: str = "cancelled") -> None:
super().__init__(reason)
self.reason = reason
class ResearchAwaitingInput(Exception):
"""Signal a durable human-review pause to the job executor.
This is intentionally separate from cancellation: the runner has completed
a safe checkpoint and the executor must preserve its plan, release the
worker lease, and let a later ``resume`` job continue from that checkpoint.
"""
def __init__(self, interrupt_id: str, plan: dict) -> None:
super().__init__(f"Research is awaiting input at {interrupt_id}")
self.interrupt_id = interrupt_id
self.plan = plan
def raise_if_cancelled_or_return(value: CancellationToken | None) -> None:
"""Convenience for adapters that receive an optional token."""
if value is not None:
value.raise_if_cancelled()
__all__ = [
"CancellationToken",
"ResearchAwaitingInput",
"ResearchCancelled",
"raise_if_cancelled_or_return",
]
@@ -0,0 +1 @@
"""Chat collection package — harvest materials from a collector-agent thread."""
@@ -0,0 +1,311 @@
"""Harvest research materials from a collector-agent chat thread.
The chat collection flow replaces the runner-driven search tiers with a real
collector-agent conversation on the session's runtime LangGraph thread (same
pipeline as normal chat — skills, sandbox tools, repair middlewares all work
with weak models). When the user confirms report writing, the writing job
reads that thread's checkpoint and converts the tool results the agent already
produced into :class:`ResearchMaterial` objects:
- ``web_search`` tool envelopes reuse the exact configured-search field
mapping (``result_to_material``) so citations stay identical to the legacy
channel.
- other tool outputs (knowledge/skill/MCP/bash stdout, including
middle-truncated JSON) are normalized through ``deerflow.runtime.references``
— the same robust harvester the chat reference batches use.
- the agent's final collection summary becomes a fallback material so a weak
model that finished without usable tool output still yields a report.
The harvested pool is served to the runners through
:class:`StaticHarvestMaterialProvider` — runners and their dedupe/compress/
write stages stay untouched.
"""
from __future__ import annotations
import hashlib
import logging
from datetime import datetime
from typing import Any
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.adapters.material_provider import result_to_material
from deerflow.agents.deep_research.types import ResearchMaterial
from deerflow.runtime.references import (
_extract_tool_payload,
_first_list,
_message_content,
_message_name,
_message_type,
_normalize_reference_item,
)
logger = logging.getLogger(__name__)
# Upper bound on harvested materials so a chatty collector thread cannot blow
# up the report context; the curating/compressing stages trim further anyway.
MAX_HARVESTED_MATERIALS = 80
# A collector model may time out after tool calls were checkpointed but before
# its final assistant response advanced the thread head. Keep the scan bounded
# while retaining the richest checkpoint from that short history.
MAX_CHECKPOINT_HISTORY = 32
# Tool-name → ResearchMaterial.source_type. Everything unknown maps to
# ``other``; ``bash`` is treated as ``skill`` because skill scripts emit there.
_TOOL_SOURCE_TYPES: dict[str, str] = {
"web_search": "web",
"weknora_search": "knowledge",
"bash": "skill",
"read_file": "file",
"write_file": "file",
}
# Tool results that never carry report materials.
_IGNORED_TOOLS = {"ask_clarification", "write_todos", "deep_research_report"}
async def harvest_thread_materials(
*,
checkpointer: Any,
runtime_thread_id: str,
query: str,
) -> tuple[list[ResearchMaterial], str]:
"""Read the collector thread's checkpointed messages into materials.
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.
"""
config = {"configurable": {"thread_id": runtime_thread_id, "checkpoint_ns": ""}}
checkpoint_tuple = await checkpointer.aget_tuple(config)
if checkpoint_tuple is None:
logger.warning("deep-research harvest: no checkpoint for thread %s", runtime_thread_id)
return [], ""
best_materials, best_summary = _harvest_checkpoint_tuple(checkpoint_tuple, query=query)
# The latest checkpoint is the normal, fast path. Historical traversal is
# only a recovery for a stale/empty head after an interrupted collector
# stream. Scanning it after usable material was already found adds dozens
# of checkpoint reads and can make report writing appear to stop halfway
# on deployments whose checkpoint store is slow or isolated per worker.
if best_materials:
return best_materials, best_summary
# ``aget_tuple`` normally returns the latest state. When a streamed lead
# agent call fails, however, some checkpointers leave that head at the
# final input checkpoint even though an earlier checkpoint already holds
# the successful web-search tool results. With an empty head, prefer the
# richest available material pool rather than treating it as an empty run.
checkpoint_history = getattr(checkpointer, "alist", None)
if callable(checkpoint_history):
try:
history = checkpoint_history(config, limit=MAX_CHECKPOINT_HISTORY)
if hasattr(history, "__aiter__"):
async for candidate in history:
materials, summary = _harvest_checkpoint_tuple(candidate, query=query)
if len(materials) > len(best_materials):
best_materials, best_summary = materials, summary
else:
for candidate in history:
materials, summary = _harvest_checkpoint_tuple(candidate, query=query)
if len(materials) > len(best_materials):
best_materials, best_summary = materials, summary
except Exception: # noqa: BLE001 - newest checkpoint remains a safe fallback
logger.debug("deep-research harvest: checkpoint history unavailable for %s", runtime_thread_id, exc_info=True)
return best_materials, best_summary
def _harvest_checkpoint_tuple(checkpoint_tuple: Any, *, query: str) -> tuple[list[ResearchMaterial], str]:
checkpoint = getattr(checkpoint_tuple, "checkpoint", None)
if not isinstance(checkpoint, dict):
return [], ""
values = 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():
# Weak-model fallback: the agent narrated its findings but never called
# a harvestable tool — its summary is still real collected knowledge.
materials.append(
ResearchMaterial(
id=f"src_{hashlib.sha256(agent_summary.encode('utf-8')).hexdigest()[:16]}",
query=query,
title="收集员小结",
url=None,
raw_content=agent_summary,
snippet=agent_summary[:200],
source="collector",
source_type="other",
content_hash=hashlib.sha256(agent_summary.encode("utf-8")).hexdigest()[:32],
metadata={"retrieval_channel": "chat_collector_summary"},
)
)
return dedupe_materials(materials)[:MAX_HARVESTED_MATERIALS], agent_summary
def _harvest_tool_messages(messages: list[Any], *, query: str) -> list[ResearchMaterial]:
"""Convert every harvestable tool result in the thread into materials.
每条材料在 ``metadata["message_index"]`` 记录其来源工具消息在对话中的
位置——写作管线据此区分「课题请求之后检索的(属于当前课题)」与
「课题切换前的旧检索」(后者才做词面相关度过滤)。
"""
materials: list[ResearchMaterial] = []
for message_index, message in enumerate(messages):
if _message_type(message) != "tool":
continue
tool_name = str(_message_name(message) or "")
if tool_name in _IGNORED_TOOLS:
continue
payload = _extract_tool_payload(message)
if payload is None:
continue
if tool_name == "web_search" and isinstance(payload, dict):
# Highest-fidelity path: identical field mapping to the legacy
# configured-search channel (recUuid/url/content/publish_time).
envelope_query = str(payload.get("query") or "").strip() or query
for item in payload.get("results") or []:
if isinstance(item, dict):
material = result_to_material(item, query=envelope_query)
material.metadata["retrieval_channel"] = "chat_web_search"
material.metadata["message_index"] = message_index
materials.append(material)
continue
materials.extend(_harvest_generic_payload(payload, tool_name=tool_name, query=query, message_index=message_index))
return materials
def _harvest_generic_payload(
payload: Any,
*,
tool_name: str,
query: str,
message_index: int | None = None,
) -> list[ResearchMaterial]:
"""Normalize a non-web_search tool payload (skill/knowledge/bash/MCP)."""
source_type = _TOOL_SOURCE_TYPES.get(tool_name, "other")
materials: list[ResearchMaterial] = []
for index, raw_item in enumerate(_first_list(payload), 1):
normalized = _normalize_reference_item(raw_item, index, payload=payload, tool_context=None)
if not normalized:
continue
title = str(normalized.get("title") or "").strip()
content = str(normalized.get("content") or normalized.get("snippet") or "").strip()
url = str(normalized.get("url") or "").strip() or None
if not title and not content:
continue
raw_hash = hashlib.sha256((url or title or content).encode("utf-8")).hexdigest()[:32]
materials.append(
ResearchMaterial(
id=f"src_{raw_hash[:16]}",
query=query,
title=title or f"结果 {index}",
url=url,
raw_content=content,
snippet=content[:200] or None,
source=str(normalized.get("source") or tool_name).strip() or tool_name,
source_type=source_type, # type: ignore[arg-type]
published_at=_try_parse_datetime(str(normalized.get("time") or "")),
content_hash=raw_hash,
metadata={
"retrieval_channel": "chat_tool",
"tool_name": tool_name,
**({"message_index": message_index} if message_index is not None else {}),
},
)
)
return materials
def _last_assistant_text(messages: list[Any]) -> str:
"""The collector's last visible answer (its collection summary)."""
for message in reversed(messages):
if _message_type(message) != "ai":
continue
content = _message_content(message)
text = _content_to_text(content)
if text.strip():
return text.strip()
return ""
def _content_to_text(content: Any) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for part in content:
if isinstance(part, str):
parts.append(part)
elif isinstance(part, dict) and isinstance(part.get("text"), str):
parts.append(part["text"])
return "".join(parts)
return ""
def _try_parse_datetime(value: str) -> datetime | None:
for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%d", "%Y/%m/%d", "%Y-%m-%dT%H:%M:%S"):
try:
return datetime.strptime(value[:19], fmt)
except ValueError:
continue
return None
class StaticHarvestMaterialProvider:
"""MaterialProvider serving the pre-harvested collector-thread pool.
Runners call ``search`` per planned sub-query; for a chat-collected pool
every call returns the whole harvest (the runners' dedupe + compress
stages trim it). ``limit`` therefore does not truncate — it bounds
network fan-out, which this provider never performs.
"""
def __init__(self, materials: list[ResearchMaterial]) -> None:
self._materials = list(materials)
@property
def material_count(self) -> int:
return len(self._materials)
async def search(
self,
query: str,
*,
domains: list[str] | None = None,
limit: int = 8,
user_id: str = "",
session_id: str = "",
cancellation=None,
) -> list[ResearchMaterial]:
if cancellation is not None:
cancellation.raise_if_cancelled()
return list(self._materials)
__all__ = [
"MAX_CHECKPOINT_HISTORY",
"MAX_HARVESTED_MATERIALS",
"StaticHarvestMaterialProvider",
"harvest_messages_materials",
"harvest_thread_materials",
]
@@ -0,0 +1,230 @@
"""Deep Research configuration — frozen per-task snapshot.
Every deep-research job captures the *full* ``DeepResearchConfig`` as an immutable
``config_snapshot`` at creation time; the running job reads **only** that snapshot
and never consults mutable global config mid-run (prevents mid-flight setting
changes from corrupting a long research session).
Server-side clamps (``clamp()``) bound every numeric field regardless of what the
client sent — client-side limits are convenience only.
"""
from __future__ import annotations
from typing import Any, Literal
from pydantic import BaseModel, Field, field_validator
# ── enums (kept as plain Literal unions so the model is JSON-serialisable) ──
ResearchMode = Literal["quick", "basic", "detailed", "deep", "multi_agent"]
ResearchTone = Literal["objective", "formal", "analytical", "persuasive"]
ReportFormat = Literal["markdown", "apa", "mla", "chicago"]
ModelRole = Literal["fast", "smart", "strategic"]
MaterialChannel = Literal["web_search", "knowledge", "skill", "mcp", "file", "other"]
SourceType = Literal["web", "knowledge", "skill", "mcp", "file", "other"]
# How the collecting stage runs. ``chat`` (the default) means the frontend
# drives a real collector-agent conversation on the session's runtime thread
# and the writing job harvests materials from that thread; ``legacy`` keeps the
# runner-driven skill/web tiers searching on their own.
CollectionMode = Literal["chat", "legacy"]
# How the writer treats ``custom_outline``.
# ``fixed`` (固定大纲) reproduces the stored headings and hierarchy.
# ``adaptive`` (弹性大纲) keeps the current material-driven layout.
StructureMode = Literal["fixed", "adaptive"]
# ── server-side bounds (§4.3 / §19.4) ────────────────────────────────────────
# Centralised so the router, the executor, and tests all share one truth source.
_MAX_SEARCH_RESULTS_PER_QUERY = 20
_MAX_ITERATIONS = 10
_MAX_SUBTOPICS = 20
_MAX_DEEP_BREADTH = 8
_MAX_DEEP_DEPTH = 4
_MAX_CONCURRENCY = 8
_MAX_CONTEXT_WORDS = 120_000
_MAX_REVISION_LOOPS = 5
MAX_GENERATED_IMAGES = 4
_MAX_CUSTOM_OUTLINE_CHARS = 4_000
_MAX_REPORT_INSTRUCTION_CHARS = 4_000
_MAX_CONTROL_PLANE_TIMEOUT_SECONDS = 120.0
# Per-user active job ceiling (§19.4 / §26).
DEFAULT_MAX_ACTIVE_JOBS_PER_USER = 3
class DeepResearchConfig(BaseModel):
"""Per-task research configuration.
Field names mirror the upstream GPT Researcher knobs but use DeerFlow
conventions (``snake_case``, explicit clamps, no ``os.environ`` reads).
"""
mode: ResearchMode = "basic"
collection_mode: CollectionMode = "chat"
language: str = "zh-CN"
tone: ResearchTone = "objective"
report_format: ReportFormat = "markdown"
# Model role overrides; ``None`` → fall back to the system default model.
fast_model: str | None = None
smart_model: str | None = None
strategic_model: str | None = None
thinking_enabled: bool = False
# Research budget knobs (client may request, server clamps).
max_search_results_per_query: int = Field(default=8, ge=1)
max_iterations: int = Field(default=3, ge=1)
max_subtopics: int = Field(default=8, ge=1)
deep_breadth: int = Field(default=4, ge=1)
deep_depth: int = Field(default=2, ge=1)
max_concurrency: int = Field(default=3, ge=1)
max_context_words: int = Field(default=24_000, ge=500)
# A provider may retain a hung HTTP request for several minutes. Planning,
# query generation, and review calls must fail in a bounded time so the
# durable job can either fall back to the topic or finish with a real error.
# Report prose deliberately uses ``stream_complete`` and is not subject to
# this total-duration cap.
control_plane_timeout_seconds: float = Field(default=45.0, ge=0.1)
# Editorial / quality knobs.
curate_sources: bool = True
generate_images: bool = False
max_generated_images: int = Field(default=2, ge=1)
include_human_feedback: bool = False
max_revision_loops: int = Field(default=2, ge=0)
# Material channels — only admin-configured tool groups are accepted
# (router validates against capabilities; ``other`` reserved for future).
allowed_material_channels: list[MaterialChannel] = Field(default_factory=lambda: ["web_search"])
allowed_domains: list[str] = Field(default_factory=list)
# Optional user-supplied outline (sanitised; never overrides system safety
# prompts in the vendored writer).
custom_outline: str | None = Field(default=None, max_length=_MAX_CUSTOM_OUTLINE_CHARS)
# Optional write-time requirements confirmed by the user. This is kept
# separate from ``custom_outline`` so prose/style requirements can never be
# misread as extra chapter headings by detailed runners.
report_instruction: str | None = Field(default=None, max_length=_MAX_REPORT_INSTRUCTION_CHARS)
# Writing constraint copied from the selected report structure (结构约束).
# Default ``adaptive`` preserves today's material-driven layout.
structure_mode: StructureMode = "adaptive"
# Optional search facets copied from the selected report structure (检索方向).
# Empty → unconstrained query-planning. Non-empty → split retrievable terms
# along those facets; never treat the labels themselves as search queries.
retrieval_directions: list[str] = Field(default_factory=list)
# Optional skill names copied from the selected report structure (检索来源).
# Empty → collector / material provider keep today's default sources.
retrieval_skills: list[str] = Field(default_factory=list)
model_config = {"extra": "forbid"}
# ── server-side clamping ────────────────────────────────────────────────
def clamp(self) -> DeepResearchConfig:
"""Return a copy with every numeric field bounded to its server ceiling.
Call this at job-creation time so the persisted snapshot is already safe;
the executor can then trust ``config_snapshot`` unconditionally.
"""
return self.model_copy(
update={
"max_search_results_per_query": min(
self.max_search_results_per_query, _MAX_SEARCH_RESULTS_PER_QUERY
),
"max_iterations": min(self.max_iterations, _MAX_ITERATIONS),
"max_subtopics": min(self.max_subtopics, _MAX_SUBTOPICS),
"deep_breadth": min(self.deep_breadth, _MAX_DEEP_BREADTH),
"deep_depth": min(self.deep_depth, _MAX_DEEP_DEPTH),
"max_concurrency": min(self.max_concurrency, _MAX_CONCURRENCY),
"max_context_words": min(self.max_context_words, _MAX_CONTEXT_WORDS),
"control_plane_timeout_seconds": min(
self.control_plane_timeout_seconds, _MAX_CONTROL_PLANE_TIMEOUT_SECONDS
),
"max_revision_loops": min(self.max_revision_loops, _MAX_REVISION_LOOPS),
"max_generated_images": min(self.max_generated_images, MAX_GENERATED_IMAGES),
}
)
@field_validator("allowed_material_channels")
@classmethod
def _dedupe_channels(cls, v: list[MaterialChannel]) -> list[MaterialChannel]:
# Preserve order, drop duplicates.
seen: set[str] = set()
out: list[MaterialChannel] = []
for ch in v:
if ch not in seen:
seen.add(ch)
out.append(ch)
return out
@field_validator("custom_outline", mode="before")
@classmethod
def _sanitize_custom_outline(cls, value: Any) -> str | None:
"""Keep a bounded user outline as content, never as a system prompt.
Newlines are retained because Markdown/numbered headings are useful to
report planning; NUL/control separators are removed so the snapshot is
portable across the database, events and artifact JSON.
"""
if value is None:
return None
cleaned = str(value).replace("\x00", "").replace("\r", "").strip()
return cleaned or None
@field_validator("report_instruction", mode="before")
@classmethod
def _sanitize_report_instruction(cls, value: Any) -> str | None:
if value is None:
return None
cleaned = str(value).replace("\x00", "").replace("\r", "").strip()
return cleaned or None
@field_validator("structure_mode", mode="before")
@classmethod
def _normalize_structure_mode(cls, value: Any) -> StructureMode:
raw = str(value or "").strip().lower()
if raw in {"fixed", "canonical", "prescriptive", "rigid"}:
return "fixed"
return "adaptive"
@field_validator("retrieval_directions", mode="before")
@classmethod
def _normalize_retrieval_directions(cls, value: Any) -> list[str]:
from deerflow.persistence.report_structures.directions import normalize_retrieval_directions
return normalize_retrieval_directions(value)
@field_validator("retrieval_skills", mode="before")
@classmethod
def _normalize_retrieval_skills(cls, value: Any) -> list[str]:
from deerflow.persistence.report_structures.skills import normalize_retrieval_skills
return normalize_retrieval_skills(value)
def resolve_model_name(self, role: ModelRole) -> str | None:
"""Return the configured model name for a role, or ``None`` for system default."""
return {
"fast": self.fast_model,
"smart": self.smart_model,
"strategic": self.strategic_model,
}[role]
# Convenience: the full set of supported modes, for capability discovery.
ALL_MODES: tuple[ResearchMode, ...] = (
"quick",
"basic",
"detailed",
"deep",
"multi_agent",
)
def config_from_dict(data: dict[str, Any]) -> DeepResearchConfig:
"""Build + clamp a config from a raw dict (e.g. JSON column / request body)."""
return DeepResearchConfig.model_validate(data).clamp()
@@ -0,0 +1,90 @@
"""DeepResearchEngine — mode-dispatching entry point (§12.1).
The engine selects the appropriate runner for the request's ``mode`` and hands
it the assembled :class:`AdapterBundle`. It is a thin dispatcher: all research
logic lives in the runners; all infrastructure wiring lives in the adapter
construction (done by the executor before calling ``run``).
``basic``/``quick`` use the compact path. ``detailed`` and ``deep`` use their
dedicated runners; ``multi_agent`` runs the LangGraph editor/researcher/writer/
reviewer workflow with durable plan-review pause and resume.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
from deerflow.agents.deep_research.runners.basic import BasicRunner
from deerflow.agents.deep_research.runners.deep import DeepRunner
from deerflow.agents.deep_research.runners.detailed import DetailedRunner
from deerflow.agents.deep_research.runners.multi_agent import MultiAgentRunner
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult
if TYPE_CHECKING:
from deerflow.agents.deep_research.cancellation import CancellationToken
from deerflow.agents.deep_research.types import AdapterBundle
logger = logging.getLogger(__name__)
class DeepResearchEngine:
"""Dispatches a research request to the mode-appropriate runner."""
def __init__(self) -> None:
self._basic = BasicRunner()
self._detailed = DetailedRunner()
self._deep = DeepRunner()
self._multi_agent = MultiAgentRunner()
async def run(
self,
request: DeepResearchRequest,
*,
adapters: AdapterBundle,
cancellation: CancellationToken | None = None,
) -> DeepResearchResult:
mode = request.config.mode
# Chat/regeneration entries use a static material provider. First chat
# writes select exactly one channel in order (browser snapshot,
# durable rows, checkpoint); regeneration reads its cloned durable
# source pool directly. Once the selected path is empty, that is
# authoritative:
# bypass every planning/search/curation branch and enter the supported
# no-material report path immediately, regardless of requested mode.
material_count = getattr(adapters.materials, "material_count", None)
if material_count == 0:
return await self._basic._no_materials_result(
request,
adapters,
{
"queries": [request.query],
"collection": "no_material_fallback",
"requestedMode": mode,
},
cancellation,
collection_outcomes=[
{
"query": request.query,
"status": "completed",
"resultCount": 0,
"route": "no_material_fallback",
}
],
)
if mode in ("basic", "quick"):
return await self._basic.run(request, adapters, cancellation)
if mode == "detailed":
return await self._detailed.run(request, adapters, cancellation)
if mode == "deep":
return await self._deep.run(request, adapters, cancellation)
if mode == "multi_agent":
return await self._multi_agent.run(request, adapters, cancellation)
# Phase 1 scope guard — these modes are planned for later phases.
raise NotImplementedError(
f"Research mode '{mode}' is not implemented. "
"Available modes: quick, basic, detailed, deep, multi_agent."
)
__all__ = ["DeepResearchEngine"]
@@ -0,0 +1,176 @@
"""Deep Research event protocol.
Every observable thing that happens during a research job — a search query fired,
a source added, a report chunk written, a model invocation billed — becomes an
event. Events are **persisted first** (to ``deep_research_events``) then pushed
to the SSE stream; this ordering lets a client reconnect with ``?after=<seq>``
and replay anything missed (§15.3).
This module defines:
- :data:`EventType` — the closed set of event ``type`` strings (§15.2).
- :data:`ResearchPhase` — the phase enum (§14.3).
- :class:`DeepResearchEvent` — the envelope persisted + serialised over SSE.
- :class:`EventSink` — the adapter protocol runners call.
The concrete :class:`PersistingEventSink` (adapter) lives in
``adapters/event_sink.py`` and bridges to the event-store repository.
"""
from __future__ import annotations
from datetime import UTC, datetime
from typing import Any, Literal, Protocol, runtime_checkable
from pydantic import BaseModel, Field
# ── phase enum (§14.3) ───────────────────────────────────────────────────────
ResearchPhase = Literal[
"initializing",
"planning",
"collecting",
"curating",
"compressing",
"deepening",
"writing",
"summarizing",
"reviewing",
"illustrating",
"exporting",
"done",
]
ALL_PHASES: tuple[ResearchPhase, ...] = (
"initializing",
"planning",
"collecting",
"curating",
"compressing",
"deepening",
"writing",
"summarizing",
"reviewing",
"illustrating",
"exporting",
"done",
)
# ── event type enum (§15.2) ──────────────────────────────────────────────────
#
# Kept as a Literal union (not an enum.IntEnum) so the persisted string and the
# SSE JSON ``type`` field are identical and stable across versions.
EventType = Literal[
"job_status",
# Terminal events are kept separate from job_status for the historical
# event timeline. The executor persists these after the DB state has
# been committed, so a reconnecting browser receives an explicit end.
"job_completed",
"job_failed",
"phase_changed",
"plan_created",
"queries_planned",
"query_started",
"query_completed",
"source_added",
"sources_curated",
"context_compressed",
"deep_branch_started",
"deep_branch_completed",
"report_reset",
"report_chunk",
# Model reasoning normally travels as a live-only frame. It becomes a
# durable event when no SSE connection for the job is attached to the
# worker running it, because the in-process live hub cannot reach a
# viewer served by a different worker (see PersistingEventSink).
"report_thinking",
"plan_reasoning",
"summary_thinking",
"report_completed",
"summary_completed",
"collection_completed",
"artifact_created",
"image_generation_started",
"image_generated",
"awaiting_input",
"model_usage",
# Durable whole-document rewrite milestones reuse the deep-research job
# event log, but have their own frontend SSE payload contract.
"document_rewrite",
"warning",
"error",
"heartbeat",
]
class DeepResearchEvent(BaseModel):
"""A single observable event in a research job.
``seq`` is assigned by the event store (monotonic per job); callers leave it
``0`` when emitting and read it back from the persisted row.
"""
seq: int = 0
session_id: str = ""
job_id: str = ""
type: EventType
phase: ResearchPhase = "initializing"
timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
payload: dict[str, Any] = Field(default_factory=dict)
model_config = {"extra": "allow"}
def to_sse_dict(self) -> dict[str, Any]:
"""Serialise for the ``data:`` line of the SSE stream (§15.1)."""
return {
"seq": self.seq,
"sessionId": self.session_id,
"jobId": self.job_id,
"type": self.type,
"phase": self.phase,
"timestamp": self.timestamp.isoformat() if self.timestamp else None,
"payload": self.payload,
}
@runtime_checkable
class EventSink(Protocol):
"""Adapter protocol for emitting research events.
Implementations persist the event (assigning ``seq``) before returning, so a
crash after ``emit()`` never loses an already-observed event.
"""
async def emit(
self,
type: EventType, # noqa: A002 — intentional arg name for readability
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> DeepResearchEvent:
"""Persist + return an event. ``session_id``/``job_id`` are bound by the sink."""
...
async def publish_live(
self,
type: str, # noqa: A002 - intentionally outside the durable EventType union
*,
phase: ResearchPhase = "initializing",
payload: dict[str, Any] | None = None,
) -> None:
"""Publish a best-effort, non-persisted frame.
Provider text deltas use this path. Bounded ``report_chunk`` events
remain the durable recovery checkpoints.
"""
...
__all__ = [
"ALL_PHASES",
"DeepResearchEvent",
"EventSink",
"EventType",
"ResearchPhase",
]
@@ -0,0 +1,138 @@
"""Optional retrieval directions and skills attached to a report structure.
检索方向 (``retrieval_directions``): when listed, material collection **splits
search terms along those facets** instead of treating the labels as queries.
检索来源 (``retrieval_skills``): when listed, collection calls those skills
instead of the collector's default web_search / Q&A research-skill stack.
Empty lists are no-ops: runners and the chat collector keep today's behaviour.
"""
from __future__ import annotations
from typing import Any
from deerflow.persistence.report_structures.directions import (
MAX_DIRECTION_CHARS,
MAX_RETRIEVAL_DIRECTIONS,
normalize_retrieval_directions,
)
from deerflow.persistence.report_structures.skills import (
MAX_RETRIEVAL_SKILLS,
MAX_SKILL_NAME_CHARS,
normalize_retrieval_skills,
)
# Must match the built-in collector agent id (seed + frontend). Extra skills
# from a report structure are only merged onto this agent so other custom
# agents cannot widen their whitelist via run context.
COLLECTOR_AGENT_ID = "deep-research-collector"
# Keep in sync with frontend ``COLLECTOR_DIRECTION_INTRO``.
_COLLECTOR_DIRECTION_INTRO = (
"请按以下检索方向拆分检索词(这是拆词约束,不是检索词本身):"
"每个方向拆成若干具体、可检索的检索词(含课题中的专名、时间、地点、同义/中英对照等),"
"不要直接把方向名称拿去搜索——方向标签往往搜不到结果。"
"覆盖列出的每一个方向;未列出的方面不必主动扩展。"
"某个检索词没有结果时,换更具体或更短的词再试,仍不要改用未列出的方向。"
)
_COLLECTOR_SKILL_INTRO = (
"请严格按照以下技能收集素材:先用 read_file 读取每个技能的 SKILL.md,"
"再按其说明调用工具检索。不要改用未列出的技能,也不要自行改成纯 web_search"
"(除非技能说明要求联网)。每个技能至少使用一轮。"
)
__all__ = [
"COLLECTOR_AGENT_ID",
"MAX_DIRECTION_CHARS",
"MAX_RETRIEVAL_DIRECTIONS",
"MAX_RETRIEVAL_SKILLS",
"MAX_SKILL_NAME_CHARS",
"format_collector_direction_block",
"format_collector_skill_block",
"format_direction_lines",
"merge_collector_skill_allowlist",
"normalize_retrieval_directions",
"normalize_retrieval_skills",
"queries_from_retrieval_directions",
"runtime_extra_skills",
]
def format_direction_lines(directions: Any) -> str:
"""Numbered direction list, or ``""`` when empty."""
dirs = normalize_retrieval_directions(directions)
return "\n".join(f"{i}. {item}" for i, item in enumerate(dirs, 1))
def queries_from_retrieval_directions(topic: str, directions: Any) -> list[str]:
"""Last-resort search strings when directed query-planning fails.
Prefer LLM/collector splitting: direction labels concatenated with the
topic are often not retrievable. Empty directions → ``[]``.
"""
topic_text = " ".join((topic or "").split()).strip()
dirs = normalize_retrieval_directions(directions)
if not dirs:
return []
seen: set[str] = set()
queries: list[str] = []
for direction in dirs:
if topic_text and topic_text not in direction:
query = f"{topic_text} {direction}".strip()
else:
query = direction
key = query.casefold()
if not query or key in seen:
continue
seen.add(key)
queries.append(query)
return queries
def format_collector_direction_block(directions: Any) -> str:
"""XML block appended to the collector's first user message, or ``""``."""
lines = format_direction_lines(directions)
if not lines:
return ""
return f"<retrieval-directions>\n{_COLLECTOR_DIRECTION_INTRO}\n{lines}\n</retrieval-directions>"
def format_collector_skill_block(skills: Any) -> str:
"""XML block appended to the collector's first user message, or ``""``."""
names = normalize_retrieval_skills(skills)
if not names:
return ""
lines = "\n".join(f"{i}. {item}" for i, item in enumerate(names, 1))
return f"<retrieval-skills>\n{_COLLECTOR_SKILL_INTRO}\n{lines}\n</retrieval-skills>"
def runtime_extra_skills(cfg: Any) -> list[str]:
"""Read extra skill names from a LangGraph run config / context dict."""
if not isinstance(cfg, dict):
return []
return normalize_retrieval_skills(cfg.get("extra_skills") or cfg.get("retrieval_skills"))
def merge_collector_skill_allowlist(
agent_id: str | None,
base: list[str] | None,
extra: Any,
) -> list[str] | None:
"""Widen the collector agent's skill allowlist for one run.
Other agents are unchanged. Empty extras are a no-op. ``None`` base means
"all skills" (default lead agent) and is left alone.
"""
extras = normalize_retrieval_skills(extra)
if not extras or agent_id != COLLECTOR_AGENT_ID:
return list(base) if base is not None else None
seen: set[str] = set()
out: list[str] = []
for name in [*(base or []), *extras]:
if not name or name in seen:
continue
seen.add(name)
out.append(name)
return out
@@ -0,0 +1,19 @@
"""Deep Research runners — one per research mode.
Each runner maps a :class:`~deerflow.agents.deep_research.types.DeepResearchRequest`
to a concrete research pipeline using the injected :class:`AdapterBundle`.
Runners never touch the network, filesystem, or ``app.*`` directly — they call
only the adapters.
The detailed and deep runners use the same adapter boundary as the basic
runner, so they do not add a model/search runtime dependency.
"""
from __future__ import annotations
from deerflow.agents.deep_research.runners.basic import BasicRunner
from deerflow.agents.deep_research.runners.deep import DeepRunner
from deerflow.agents.deep_research.runners.detailed import DetailedRunner
from deerflow.agents.deep_research.runners.multi_agent import MultiAgentRunner
__all__ = ["BasicRunner", "DeepRunner", "DetailedRunner", "MultiAgentRunner"]
@@ -0,0 +1,462 @@
"""Recursive deep-research runner adapted from GPT Researcher's DeepResearchSkill.
The original skill expands search goals by breadth, extracts learnings from each
branch, and recursively investigates follow-up questions with a smaller width.
This module keeps those mechanics but routes all search/model work through the
DeerFlow adapter bundle. A deterministic query budget is reserved before any
branch runs, so recursive fan-out cannot exceed the persisted job configuration.
"""
from __future__ import annotations
import asyncio
import json
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any
from pydantic import BaseModel, Field
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.cancellation import ResearchCancelled
from deerflow.agents.deep_research.retrieval import (
format_direction_lines,
normalize_retrieval_directions,
queries_from_retrieval_directions,
)
from deerflow.agents.deep_research.runners.basic import (
_SYSTEM,
BasicRunner,
_format_context,
ensure_reference_section,
)
from deerflow.agents.deep_research.runners.images import generate_report_images
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
if TYPE_CHECKING:
from deerflow.agents.deep_research.types import AdapterBundle
class ResearchBranch(BaseModel):
query: str
research_goal: str = ""
class ResearchBranches(BaseModel):
branches: list[ResearchBranch] = Field(default_factory=list)
class ResearchLearnings(BaseModel):
learnings: list[str] = Field(default_factory=list)
follow_up_questions: list[str] = Field(default_factory=list)
_BRANCH_PROMPT = """Research topic: {query}
Generate at most {breadth} independent search branches. Each branch must include
a concrete search query and a one-sentence research goal. Return JSON only:
{{"branches": [{{"query": "...", "research_goal": "..."}}]}}.
"""
_DIRECTED_BRANCH_PROMPT = """Research topic: {query}
The user named these retrieval directions. Use them only as facets for splitting
search terms — do not use the direction labels themselves as queries (they often
return no results):
{directions}
Generate at most {breadth} independent search branches covering those directions.
Each branch must include a concrete, retrievable search query (entities, dates,
places, synonyms) and a one-sentence research goal. Do not invent branches
outside the listed directions. Return JSON only:
{{"branches": [{{"query": "...", "research_goal": "..."}}]}}.
"""
_LEARNING_PROMPT = """Research objective: {goal}
Extract concise, evidence-grounded learnings from the materials. Then propose
follow-up questions that would reduce the most important uncertainty. Return
JSON only: {{"learnings": ["..."], "follow_up_questions": ["..."]}}.
Materials:
{context}
"""
def calculate_query_budget(breadth: int, depth: int) -> int:
"""Return the maximum number of searches reachable by recursive expansion.
A depth level creates ``width`` branches per existing branch. Each next
level halves the width (with a floor of one), mirroring GPT Researcher's
``new_breadth=breadth // 2`` expansion while remaining bounded for
DeerFlow's small default budgets.
"""
width = max(1, breadth)
nodes = 1
total = 0
for _ in range(max(1, depth)):
total += nodes * width
nodes *= width
width = max(1, width // 2)
return total
@dataclass
class _Budget:
remaining: int
lock: asyncio.Lock
async def take(self) -> bool:
async with self.lock:
if self.remaining <= 0:
return False
self.remaining -= 1
return True
class DeepRunner(BasicRunner):
"""Run bounded recursive research and synthesize a final cited report."""
async def run(
self,
request: DeepResearchRequest,
adapters: AdapterBundle,
cancellation=None,
) -> DeepResearchResult:
config = request.config
events = adapters.events
all_materials: list[ResearchMaterial] = []
learnings: list[str] = []
materials_lock = asyncio.Lock()
learnings_lock = asyncio.Lock()
budget = _Budget(calculate_query_budget(config.deep_breadth, config.deep_depth), asyncio.Lock())
model_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
try:
await events.emit(
"phase_changed",
phase="planning",
payload={"from": "initializing", "to": "planning"},
)
self._raise_if_cancelled(cancellation)
roots = await self._generate_branches(
adapters.llm,
request.query,
config.deep_breadth,
retrieval_directions=config.retrieval_directions,
)
if not roots:
roots = [ResearchBranch(query=request.query, research_goal=request.query)]
plan = {
"branches": [branch.model_dump() for branch in roots],
"deepBreadth": config.deep_breadth,
"deepDepth": config.deep_depth,
"queryBudget": budget.remaining,
}
await events.emit("plan_created", phase="planning", payload={"plan": plan, "subtopics": []})
await events.emit(
"phase_changed",
phase="deepening",
payload={"from": "planning", "to": "deepening"},
)
await asyncio.gather(
*[
self._research_branch(
branch=branch,
depth_remaining=config.deep_depth,
branch_width=config.deep_breadth,
path=str(index + 1),
request=request,
adapters=adapters,
cancellation=cancellation,
model_semaphore=model_semaphore,
budget=budget,
all_materials=all_materials,
materials_lock=materials_lock,
learnings=learnings,
learnings_lock=learnings_lock,
)
for index, branch in enumerate(roots)
]
)
self._raise_if_cancelled(cancellation)
await events.emit(
"phase_changed",
phase="curating",
payload={"from": "deepening", "to": "curating"},
)
deduped = dedupe_materials(all_materials)
if not deduped:
return await self._no_materials_result(request, adapters, plan)
selected_ids = [material.id for material in deduped]
await events.emit(
"sources_curated",
phase="curating",
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped_recursive"},
)
await events.emit(
"phase_changed",
phase="compressing",
payload={"from": "curating", "to": "compressing"},
)
adapters.context.set_materials(deduped)
context_list = await adapters.context.async_get_context(
request.query,
max_results=min(len(deduped), config.max_search_results_per_query * 2),
)
if not context_list:
context_list = [
material.to_context_dict()
for material in deduped[: min(len(deduped), config.max_search_results_per_query * 2)]
]
await events.emit(
"warning",
phase="compressing",
payload={
"code": "context_fallback",
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
"recoverable": True,
"sourceCount": len(deduped),
"diagnostic": {
"stage": "compressing",
"outcome": "empty_context",
"sourceCount": len(deduped),
},
},
)
material_context = _format_context(context_list, deduped)
learning_context = "\n".join(f"- {learning}" for learning in dict.fromkeys(learnings))
context_text = f"## Recursive research learnings\n{learning_context}\n\n## Source materials\n{material_context}" if learning_context else material_context
await events.emit(
"context_compressed",
phase="compressing",
payload={"sourceCount": len(context_list), "learningCount": len(learnings)},
)
await events.emit(
"phase_changed",
phase="writing",
payload={"from": "compressing", "to": "writing"},
)
self._raise_if_cancelled(cancellation)
report_md = await self._generate_report(
adapters.llm,
request,
context_text,
events,
cancellation,
source_count=len(deduped),
)
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
# Ensure before _write_artifacts so the artifact AND the returned
# report_markdown (persisted by the executor) both carry it.
report_md = ensure_reference_section(report_md, context_list, deduped)
await self._write_artifacts(adapters, report_md, deduped, plan)
await events.emit(
"report_completed",
phase="writing",
payload={"reportVersion": 1, "sourceCount": len(deduped)},
)
await events.emit(
"artifact_created",
phase="exporting",
payload={"format": "markdown", "name": "report.md"},
)
return DeepResearchResult(
report_markdown=report_md,
source_ids=selected_ids,
artifact_paths={
"report.md": "report.md",
"sources.json": "sources.json",
**image_paths,
},
usage=adapters.llm.usage_totals,
plan=plan,
)
except ResearchCancelled:
await events.emit(
"warning",
phase="deepening",
payload={"code": "cancelled", "message": "Research job cancelled", "recoverable": False},
)
raise
async def _research_branch(
self,
*,
branch: ResearchBranch,
depth_remaining: int,
branch_width: int,
path: str,
request: DeepResearchRequest,
adapters: AdapterBundle,
cancellation,
model_semaphore: asyncio.Semaphore,
budget: _Budget,
all_materials: list[ResearchMaterial],
materials_lock: asyncio.Lock,
learnings: list[str],
learnings_lock: asyncio.Lock,
) -> None:
self._raise_if_cancelled(cancellation)
if not await budget.take():
await adapters.events.emit(
"warning",
phase="deepening",
payload={"code": "deep_budget_exhausted", "message": "Recursive query budget exhausted", "recoverable": True},
)
return
await adapters.events.emit(
"deep_branch_started",
phase="deepening",
payload={"path": path, "query": branch.query, "goal": branch.research_goal, "depthRemaining": depth_remaining},
)
try:
materials = await self._search_one(
adapters.materials,
branch.query,
request.config,
request,
cancellation,
adapters.events,
)
except ResearchCancelled:
raise
except Exception as exc: # noqa: BLE001 - one branch must not abort all research
await adapters.events.emit(
"warning",
phase="deepening",
payload={"code": "deep_branch_search_failed", "message": str(exc), "recoverable": True},
)
materials = []
async with materials_lock:
all_materials.extend(materials)
branch_learnings: list[str] = []
follow_ups: list[str] = []
if materials:
deduped_materials = dedupe_materials(materials)
context = _format_context(
[material.to_context_dict() for material in deduped_materials],
deduped_materials,
)
async with model_semaphore:
extraction = await self._extract_learnings(adapters.llm, branch.research_goal or branch.query, context)
branch_learnings = extraction.learnings
follow_ups = extraction.follow_up_questions
async with learnings_lock:
learnings.extend(branch_learnings)
await adapters.events.emit(
"deep_branch_completed",
phase="deepening",
payload={
"path": path,
"query": branch.query,
"resultCount": len(materials),
"learningCount": len(branch_learnings),
"nextQuestionCount": len(follow_ups),
},
)
self._raise_if_cancelled(cancellation)
if depth_remaining <= 1 or not follow_ups:
return
next_width = max(1, branch_width // 2)
await asyncio.gather(
*[
self._research_branch(
branch=ResearchBranch(query=question, research_goal=question),
depth_remaining=depth_remaining - 1,
branch_width=next_width,
path=f"{path}.{index + 1}",
request=request,
adapters=adapters,
cancellation=cancellation,
model_semaphore=model_semaphore,
budget=budget,
all_materials=all_materials,
materials_lock=materials_lock,
learnings=learnings,
learnings_lock=learnings_lock,
)
for index, question in enumerate(follow_ups[:next_width])
if question.strip()
]
)
async def _generate_branches(
self,
llm,
query: str,
breadth: int,
retrieval_directions: list[str] | None = None,
) -> list[ResearchBranch]:
dirs = normalize_retrieval_directions(retrieval_directions)
prompt = (
_DIRECTED_BRANCH_PROMPT.format(
query=query, breadth=breadth, directions=format_direction_lines(dirs)
)
if dirs
else _BRANCH_PROMPT.format(query=query, breadth=breadth)
)
result = await llm.complete(
model_role="strategic",
messages=[
{"role": "system", "content": _SYSTEM},
{"role": "user", "content": prompt},
],
response_schema=ResearchBranches,
operation="generate_deep_queries",
)
branches = result.structured.branches if result.structured else []
seen: set[str] = set()
output: list[ResearchBranch] = []
for branch in branches:
query_text = branch.query.strip()
if not query_text or query_text in seen:
continue
seen.add(query_text)
output.append(ResearchBranch(query=query_text, research_goal=branch.research_goal.strip()))
if len(output) >= breadth:
break
if output:
return output
fallback = queries_from_retrieval_directions(query, dirs)
return [ResearchBranch(query=item, research_goal=item) for item in fallback[:breadth]]
async def _extract_learnings(self, llm, goal: str, context: str) -> ResearchLearnings:
result = await llm.complete(
model_role="fast",
messages=[
{"role": "system", "content": _SYSTEM},
{"role": "user", "content": _LEARNING_PROMPT.format(goal=goal, context=context)},
],
response_schema=ResearchLearnings,
operation="extract_research_learnings",
)
return result.structured if result.structured else ResearchLearnings()
async def _write_artifacts(
self,
adapters: AdapterBundle,
report_md: str,
materials: list[ResearchMaterial],
plan: dict[str, Any],
) -> None:
await adapters.artifacts.write_text("report.md", report_md)
await adapters.artifacts.write_text("sources.json", json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2))
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
return await super()._no_materials_result(request, adapters, plan)
@staticmethod
def _raise_if_cancelled(cancellation) -> None:
if cancellation:
cancellation.raise_if_cancelled()
__all__ = ["DeepRunner", "ResearchBranch", "ResearchBranches", "ResearchLearnings", "calculate_query_budget"]
@@ -0,0 +1,502 @@
"""Detailed-report runner adapted from GPT Researcher's subtopic workflow.
The upstream ``DetailedReport`` flow plans a set of subtopics, researches each
one, writes independently usable sections, then assembles an introduction and
conclusion. This adaptation deliberately retains that control flow while using
only DeerFlow's injected adapters for models, materials, events, and artifacts.
"""
from __future__ import annotations
import asyncio
import json
import logging
from typing import TYPE_CHECKING, Any
from pydantic import BaseModel, Field
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.cancellation import ResearchCancelled
from deerflow.agents.deep_research.runners.basic import (
_SYSTEM,
BasicRunner,
_format_context,
ensure_outline_preamble,
ensure_reference_section,
extract_outline_sections,
)
from deerflow.agents.deep_research.runners.images import generate_report_images
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
if TYPE_CHECKING:
from deerflow.agents.deep_research.types import AdapterBundle
logger = logging.getLogger(__name__)
class DetailedSubtopics(BaseModel):
"""The bounded section plan for a detailed report."""
subtopics: list[str] = Field(default_factory=list)
_SUBTOPIC_PROMPT = """Research topic: {query}
Create at most {count} mutually exclusive report sections. Cover the most
decision-useful dimensions of the topic and make each section title concise.
Return JSON only: {{"subtopics": ["section one", "section two"]}}.
"""
_SECTION_PROMPT = """Write the Markdown section titled "{topic}" for a report on
"{query}". Use only the supplied evidence, distinguish facts from inference,
and cite evidence with [N]. Output the section body only; do not repeat a #
title.
Evidence:
{context}
"""
_INTRODUCTION_PROMPT = """Write a concise Markdown introduction for a detailed
research report about "{query}". State scope and method without inventing facts.
The report sections are: {sections}. Output prose only.
"""
_CONCLUSION_PROMPT = """Write a concise Markdown conclusion for a detailed
research report about "{query}". Synthesize only the supplied section findings;
note important uncertainty where appropriate. Output prose only.
Section findings:
{sections}
"""
def _confirmed_requirements(value: str | None) -> str:
if not value:
return ""
return f"\n\nConfirmed user generation requirements:\n<user-report-requirements>\n{value}\n</user-report-requirements>"
class DetailedRunner(BasicRunner):
"""Plan, research, and write bounded subtopic sections in parallel."""
async def run(
self,
request: DeepResearchRequest,
adapters: AdapterBundle,
cancellation=None,
) -> DeepResearchResult:
config = request.config
events = adapters.events
try:
await events.emit(
"phase_changed",
phase="planning",
payload={"from": "initializing", "to": "planning"},
)
self._raise_if_cancelled(cancellation)
subtopics = extract_outline_sections(
config.custom_outline,
config.max_subtopics,
structure_mode=config.structure_mode,
)
if not subtopics:
subtopics = await self._generate_subtopics(adapters.llm, request.query, config.max_subtopics, events)
if not subtopics:
subtopics = [request.query]
plan = {"subtopics": subtopics, "queries": []}
await events.emit(
"plan_created",
phase="planning",
payload={"plan": plan, "subtopics": subtopics},
)
await events.emit(
"phase_changed",
phase="collecting",
payload={"from": "planning", "to": "collecting"},
)
semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
topic_results = await asyncio.gather(
*[
self._research_subtopic(
topic,
request,
adapters,
semaphore,
cancellation,
)
for topic in subtopics
],
return_exceptions=True,
)
self._raise_if_cancelled(cancellation)
materials_by_topic: dict[str, list[ResearchMaterial]] = {topic: [] for topic in subtopics}
all_materials: list[ResearchMaterial] = []
for result in topic_results:
if isinstance(result, ResearchCancelled):
raise result
if isinstance(result, Exception):
await events.emit(
"warning",
phase="collecting",
payload={"code": "subtopic_failed", "message": str(result), "recoverable": True},
)
continue
topic, materials = result
materials_by_topic[topic] = materials
all_materials.extend(materials)
await events.emit(
"phase_changed",
phase="curating",
payload={"from": "collecting", "to": "curating"},
)
self._raise_if_cancelled(cancellation)
deduped = dedupe_materials(all_materials)
if not deduped:
return await self._no_materials_result(request, adapters, plan)
selected_ids = [material.id for material in deduped]
await events.emit(
"sources_curated",
phase="curating",
payload={"selectedIds": selected_ids, "removedIds": [], "reason": "deduped"},
)
await events.emit(
"phase_changed",
phase="compressing",
payload={"from": "curating", "to": "compressing"},
)
adapters.context.set_materials(deduped)
global_context = await adapters.context.async_get_context(
request.query,
max_results=min(len(deduped), config.max_search_results_per_query * 2),
)
if not global_context:
global_context = [
material.to_context_dict()
for material in deduped[: min(len(deduped), config.max_search_results_per_query * 2)]
]
await events.emit(
"warning",
phase="compressing",
payload={
"code": "context_fallback",
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
"recoverable": True,
"sourceCount": len(deduped),
"diagnostic": {
"stage": "compressing",
"outcome": "empty_context",
"sourceCount": len(deduped),
},
},
)
await events.emit(
"context_compressed",
phase="compressing",
payload={"sourceCount": len(global_context)},
)
await events.emit(
"phase_changed",
phase="writing",
payload={"from": "compressing", "to": "writing"},
)
self._raise_if_cancelled(cancellation)
if config.structure_mode == "fixed":
introduction = ""
writing_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
section_results = await asyncio.gather(
*[
self._write_section(
topic,
materials_by_topic.get(topic) or deduped,
request,
adapters,
writing_semaphore,
cancellation,
index,
)
for index, topic in enumerate(subtopics)
]
)
self._raise_if_cancelled(cancellation)
conclusion = ""
else:
introduction = await self._write_introduction(adapters.llm, request, adapters.events, subtopics)
writing_semaphore = asyncio.Semaphore(max(1, config.max_concurrency))
section_results = await asyncio.gather(
*[
self._write_section(
topic,
materials_by_topic.get(topic) or deduped,
request,
adapters,
writing_semaphore,
cancellation,
index,
)
for index, topic in enumerate(subtopics)
]
)
self._raise_if_cancelled(cancellation)
conclusion = await self._write_conclusion(adapters.llm, request, adapters.events, section_results)
report_md = self._assemble_report(
request.query,
introduction,
subtopics,
section_results,
conclusion,
outline=request.config.custom_outline,
structure_mode=request.config.structure_mode,
)
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
# Sections cite with per-topic local numbering that cannot be
# mapped to the global list, so list every source instead of
# filtering by [N]. Ensured here so the artifact AND the returned
# report_markdown (persisted by the executor) both carry it.
report_md = ensure_reference_section(report_md, global_context, deduped, filter_by_citations=False)
await self._write_artifacts(adapters, report_md, deduped, plan)
await events.emit(
"report_completed",
phase="writing",
payload={"reportVersion": 1, "sourceCount": len(deduped)},
)
await events.emit(
"artifact_created",
phase="exporting",
payload={"format": "markdown", "name": "report.md"},
)
return DeepResearchResult(
report_markdown=report_md,
source_ids=selected_ids,
artifact_paths={
"report.md": "report.md",
"sources.json": "sources.json",
**image_paths,
},
usage=adapters.llm.usage_totals,
plan=plan,
)
except ResearchCancelled:
await events.emit(
"warning",
phase="writing",
payload={"code": "cancelled", "message": "Research job cancelled", "recoverable": False},
)
raise
async def _generate_subtopics(self, llm, query: str, max_subtopics: int, events) -> list[str]:
try:
result = await llm.complete(
model_role="strategic",
messages=[
{"role": "system", "content": _SYSTEM},
{"role": "user", "content": _SUBTOPIC_PROMPT.format(query=query, count=max_subtopics)},
],
response_schema=DetailedSubtopics,
operation="generate_detailed_subtopics",
)
except ResearchCancelled:
raise
except Exception:
logger.warning("detailed runner: subtopic planning failed; using original topic", exc_info=True)
await events.emit(
"warning",
phase="planning",
payload={
"code": "subtopic_planning_fallback",
"message": "研究范围规划超时或失败,已直接使用研究课题继续检索。",
"recoverable": True,
},
)
return []
raw = result.structured.subtopics if result.structured else []
seen: set[str] = set()
subtopics: list[str] = []
for item in raw:
title = item.strip()
if not title or title in seen:
continue
seen.add(title)
subtopics.append(title)
if len(subtopics) >= max_subtopics:
break
return subtopics
async def _research_subtopic(
self,
topic: str,
request: DeepResearchRequest,
adapters: AdapterBundle,
semaphore: asyncio.Semaphore,
cancellation,
) -> tuple[str, list[ResearchMaterial]]:
self._raise_if_cancelled(cancellation)
async with semaphore:
queries = await self._generate_queries(
adapters.llm,
topic,
request.config.max_iterations,
cancellation,
events=adapters.events,
phase="collecting",
retrieval_directions=request.config.retrieval_directions,
)
ordered_queries = list(dict.fromkeys([*queries, topic]))[: request.config.max_iterations + 1]
# The generated terms are useful user-facing progress, not internal
# reasoning. Persist them before dispatching the parallel searches so
# an SSE reconnect can faithfully replay the fan-out.
await adapters.events.emit(
"queries_planned",
phase="collecting",
payload={"parentTopic": topic, "queries": ordered_queries},
)
materials: list[ResearchMaterial] = []
for query in ordered_queries:
try:
materials.extend(
await self._search_one(
adapters.materials,
query,
request.config,
request,
cancellation,
adapters.events,
)
)
except ResearchCancelled:
raise
except Exception as exc: # noqa: BLE001 - one failed term must not abort the topic
logger.warning("detailed runner: subtopic search failed: %s", exc)
await adapters.events.emit(
"warning",
phase="collecting",
payload={"code": "search_failed", "message": str(exc), "recoverable": True},
)
return topic, materials
async def _write_introduction(self, llm, request: DeepResearchRequest, events, subtopics: list[str]) -> str:
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
emitter = ReportChunkEmitter(events, target="introduction")
result = await llm.stream_complete(
model_role="smart",
messages=[
{"role": "system", "content": _SYSTEM},
{
"role": "user",
"content": _INTRODUCTION_PROMPT.format(query=request.query, sections=", ".join(subtopics))
+ _confirmed_requirements(request.config.report_instruction),
},
],
operation="write_detailed_introduction",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
await emitter.flush()
return result.text
async def _write_section(
self,
topic: str,
materials: list[ResearchMaterial],
request: DeepResearchRequest,
adapters: AdapterBundle,
semaphore: asyncio.Semaphore,
cancellation,
index: int,
) -> str:
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
async with semaphore:
self._raise_if_cancelled(cancellation)
deduped_materials = dedupe_materials(materials)
context = _format_context(
[material.to_context_dict() for material in deduped_materials],
deduped_materials,
)
emitter = ReportChunkEmitter(adapters.events, target=f"section:{index}")
result = await adapters.llm.stream_complete(
model_role="smart",
messages=[
{"role": "system", "content": _SYSTEM},
{
"role": "user",
"content": _SECTION_PROMPT.format(query=request.query, topic=topic, context=context)
+ _confirmed_requirements(request.config.report_instruction),
},
],
operation="write_detailed_section",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
await emitter.flush()
return result.text
async def _write_conclusion(self, llm, request: DeepResearchRequest, events, sections: list[str]) -> str:
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
emitter = ReportChunkEmitter(events, target="conclusion")
result = await llm.stream_complete(
model_role="smart",
messages=[
{"role": "system", "content": _SYSTEM},
{
"role": "user",
"content": _CONCLUSION_PROMPT.format(query=request.query, sections="\n\n".join(sections))
+ _confirmed_requirements(request.config.report_instruction),
},
],
operation="write_detailed_conclusion",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
await emitter.flush()
return result.text
async def _write_artifacts(
self,
adapters: AdapterBundle,
report_md: str,
materials: list[ResearchMaterial],
plan: dict[str, Any],
) -> None:
await adapters.artifacts.write_text("report.md", report_md)
await adapters.artifacts.write_text("sources.json", json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2))
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
return await super()._no_materials_result(request, adapters, plan)
@staticmethod
def _assemble_report(
query: str,
introduction: str,
subtopics: list[str],
sections: list[str],
conclusion: str,
outline: str | None = None,
structure_mode: str = "adaptive",
) -> str:
section_md = "\n\n".join(f"## {topic}\n\n{body}" for topic, body in zip(subtopics, sections, strict=True))
if structure_mode == "fixed":
report = section_md + "\n"
else:
toc = "\n".join(f"- {topic}" for topic in subtopics)
report = f"# {query}\n\n## 摘要\n\n{introduction}\n\n## 目录\n\n{toc}\n\n{section_md}\n\n## 结论\n\n{conclusion}\n"
return ensure_outline_preamble(report, outline, query)
@staticmethod
def _raise_if_cancelled(cancellation) -> None:
if cancellation:
cancellation.raise_if_cancelled()
__all__ = ["DetailedRunner", "DetailedSubtopics"]
@@ -0,0 +1,180 @@
"""Shared optional report-illustration step for every research runner.
This module is intentionally independent of any particular runner. A basic,
detailed, recursive or multi-agent report receives the same bounded, best-effort
image behavior after its Markdown draft is complete and before ``report.md`` is
written. Image failures emit warnings and never discard an otherwise valid
research report.
"""
from __future__ import annotations
import re
from typing import TYPE_CHECKING
from deerflow.agents.deep_research.adapters.image import ImageGenerationError
if TYPE_CHECKING:
from deerflow.agents.deep_research.types import AdapterBundle, DeepResearchRequest
_HEADING_RE = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
_EXTENSIONS = {
"image/png": "png",
"image/jpeg": "jpg",
"image/webp": "webp",
}
async def generate_report_images(
request: DeepResearchRequest,
adapters: AdapterBundle,
report_markdown: str,
cancellation=None,
) -> tuple[str, dict[str, str]]:
"""Generate bounded section illustrations and inject protected references.
The generated Markdown uses a private ``deep-research://`` URI. The React
report renderer maps it to an authenticated session-artifact endpoint, so
image paths never expose the hidden runtime-thread id or an external model
provider URL.
"""
if not request.config.generate_images:
return report_markdown, {}
if adapters.images is None:
await adapters.events.emit(
"warning",
phase="illustrating",
payload={
"code": "image_provider_unavailable",
"message": "当前部署未配置图片生成服务,已跳过报告配图",
"recoverable": True,
},
)
return report_markdown, {}
sections = _report_sections(report_markdown, request.query, request.config.max_generated_images)
if not sections:
return report_markdown, {}
await adapters.events.emit(
"phase_changed",
phase="illustrating",
payload={"from": "writing", "to": "illustrating"},
)
image_paths: dict[str, str] = {}
amended_report = report_markdown
total = len(sections)
for position, section in enumerate(sections, 1):
if cancellation is not None:
cancellation.raise_if_cancelled()
prompt = _image_prompt(request.query, section)
await adapters.events.emit(
"image_generation_started",
phase="illustrating",
payload={"section": section, "position": position, "total": total},
)
try:
generated = await adapters.images.generate(
prompt,
section_id=section,
user_id=request.user_id,
)
if not generated:
raise ImageGenerationError("图片生成服务未返回图片")
data = generated.get("data")
if not isinstance(data, bytes) or not data:
raise ImageGenerationError("图片生成服务未返回可保存的图片数据")
mime_type = str(generated.get("mime_type") or "image/png").lower()
extension = _EXTENSIONS.get(mime_type, "png")
name = f"research-image-{position:02d}.{extension}"
await adapters.artifacts.write_bytes(name, data)
alt = _clean_alt(str(generated.get("alt") or f"{section}配图"))
amended_report = _insert_image(amended_report, section, alt, name)
image_paths[name] = name
await adapters.events.emit(
"image_generated",
phase="illustrating",
payload={
"section": section,
"position": position,
"total": total,
"name": name,
"alt": alt,
},
)
except ImageGenerationError as exc:
await adapters.events.emit(
"warning",
phase="illustrating",
payload={
"code": "image_generation_failed",
"message": str(exc),
"recoverable": True,
"section": section,
"position": position,
"total": total,
},
)
except Exception: # noqa: BLE001
# Third-party image APIs and artifact storage must never turn a
# completed text report into a failed job. Keep internal details
# out of the browser event stream.
await adapters.events.emit(
"warning",
phase="illustrating",
payload={
"code": "image_generation_failed",
"message": "报告配图生成失败,已继续保留文字报告",
"recoverable": True,
"section": section,
"position": position,
"total": total,
},
)
await adapters.events.emit(
"phase_changed",
phase="exporting",
payload={"from": "illustrating", "to": "exporting"},
)
return amended_report, image_paths
def _report_sections(report_markdown: str, query: str, maximum: int) -> list[str]:
seen: set[str] = set()
sections: list[str] = []
for match in _HEADING_RE.finditer(report_markdown):
section = _clean_heading(match.group(1))
if section and section not in seen:
seen.add(section)
sections.append(section)
if len(sections) >= maximum:
return sections
return sections or [_clean_heading(query) or "研究主题"]
def _image_prompt(query: str, section: str) -> str:
return (
f"为一份中文专业研究报告生成一张信息性配图。研究主题:{_clean_heading(query)}。对应章节:{section}。画面应当客观、简洁、适合商务报告;使用抽象示意、数据视觉化或场景插画表达主题。不要在图片中放置可读文字、品牌标志、水印或人物肖像。"
)
def _insert_image(report: str, section: str, alt: str, name: str) -> str:
marker = f"## {section}"
image = f"\n\n![{alt}](deep-research://{name})\n"
if marker in report:
return report.replace(marker, f"{marker}{image}", 1)
return f"{report.rstrip()}{image}"
def _clean_heading(value: str) -> str:
return " ".join(value.replace("\r", " ").replace("\n", " ").split())[:160]
def _clean_alt(value: str) -> str:
return _clean_heading(value).replace("[", "").replace("]", "") or "研究报告配图"
__all__ = ["generate_report_images"]
@@ -0,0 +1,449 @@
"""LangGraph 1.x multi-agent research runner with durable plan review.
The workflow adapts GPT Researcher's editor/researcher/writer/reviewer shape:
an editor plans sections, researchers collect evidence, a writer drafts the
report, and a reviewer can request a bounded revision loop. Human plan review
is durable at the runner/executor boundary: a first execution raises
``ResearchAwaitingInput`` after persisting its plan; a resumed job rebuilds the
same graph from the persisted plan and action payload.
"""
from __future__ import annotations
import asyncio
import json
import uuid
from typing import TYPE_CHECKING, Any, TypedDict
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel, Field
from deerflow.agents.deep_research.adapters.material import dedupe_materials
from deerflow.agents.deep_research.cancellation import ResearchAwaitingInput, ResearchCancelled
from deerflow.agents.deep_research.runners.basic import (
_SYSTEM,
BasicRunner,
_format_context,
ensure_reference_section,
extract_outline_sections,
)
from deerflow.agents.deep_research.runners.images import generate_report_images
from deerflow.agents.deep_research.types import DeepResearchRequest, DeepResearchResult, ResearchMaterial
if TYPE_CHECKING:
from deerflow.agents.deep_research.types import AdapterBundle
class MultiAgentPlan(BaseModel):
sections: list[str] = Field(default_factory=list)
class ReviewVerdict(BaseModel):
approved: bool = True
revision_notes: str = ""
class _MultiAgentState(TypedDict, total=False):
plan: dict[str, Any]
materials: list[ResearchMaterial]
report: str
review: dict[str, Any]
revision_count: int
context_list: list[dict[str, Any]]
_PLAN_PROMPT = """Research topic: {query}
Act as the research editor. Produce at most {count} focused sections for a
multi-agent report. Each section must describe a different decision-relevant
dimension. Return JSON only: {{"sections": ["...", "..."]}}.
"""
_REVIEW_PROMPT = """Review this research report for unsupported claims, missing
citations, and material contradictions. Approve it when it is publishable;
otherwise provide concise revision notes. Return JSON only:
{{"approved": true, "revision_notes": ""}}.
Report:
{report}
"""
_REVISE_PROMPT = """Revise the research report using the reviewer notes. Retain
valid citations, do not invent facts or sources, and return the full Markdown
report only.
Reviewer notes:
{notes}
Report:
{report}
"""
class MultiAgentRunner(BasicRunner):
"""Run a LangGraph editor/researcher/writer/reviewer workflow."""
async def run(
self,
request: DeepResearchRequest,
adapters: AdapterBundle,
cancellation=None,
) -> DeepResearchResult:
await adapters.events.emit(
"phase_changed",
phase="planning",
payload={"from": "initializing", "to": "planning"},
)
self._raise_if_cancelled(cancellation)
plan = await self._resolve_plan(request, adapters, cancellation)
if not request.interrupted_plan:
interrupt_id = f"plan-review-{uuid.uuid4().hex[:12]}"
await adapters.events.emit(
"plan_created",
phase="planning",
payload={"plan": plan, "subtopics": plan["sections"]},
)
await adapters.events.emit(
"awaiting_input",
phase="planning",
payload={
"interruptId": interrupt_id,
"kind": "plan_review",
"plan": plan,
"allowedActions": ["approve", "revise", "cancel"],
},
)
raise ResearchAwaitingInput(interrupt_id, plan)
graph = self._build_graph(request, adapters, cancellation)
initial_state: _MultiAgentState = {"plan": plan, "revision_count": 0}
state = await graph.ainvoke(initial_state)
materials = dedupe_materials(state.get("materials") or [])
report_md = str(state.get("report") or "")
if not materials or not report_md:
return await self._no_materials_result(request, adapters, plan)
report_md, image_paths = await generate_report_images(request, adapters, report_md, cancellation)
report_md = ensure_reference_section(report_md, state.get("context_list") or [], materials)
await adapters.artifacts.write_text("report.md", report_md)
await adapters.artifacts.write_text(
"sources.json",
json.dumps([material.to_context_dict() for material in materials], ensure_ascii=False, indent=2),
)
await adapters.artifacts.write_text("research-plan.json", json.dumps(plan, ensure_ascii=False, indent=2))
await adapters.events.emit(
"report_completed",
phase="writing",
payload={"reportVersion": 1, "sourceCount": len(materials)},
)
await adapters.events.emit(
"artifact_created",
phase="exporting",
payload={"format": "markdown", "name": "report.md"},
)
return DeepResearchResult(
report_markdown=report_md,
source_ids=[material.id for material in materials],
artifact_paths={
"report.md": "report.md",
"sources.json": "sources.json",
**image_paths,
},
usage=adapters.llm.usage_totals,
plan=plan,
)
async def _resolve_plan(self, request: DeepResearchRequest, adapters: AdapterBundle, cancellation) -> dict[str, Any]:
if request.interrupted_plan:
plan = dict(request.interrupted_plan)
action = str(request.resume_payload.get("action") or "approve")
if action == "cancel":
raise ResearchCancelled("plan review cancelled")
if action == "revise":
feedback = str((request.resume_payload.get("payload") or {}).get("feedback") or "")
plan = await self._revise_plan(adapters.llm, request.query, plan, feedback)
await adapters.events.emit(
"plan_created",
phase="planning",
payload={"plan": plan, "subtopics": plan.get("sections", []), "resumed": True},
)
return plan
outline_sections = extract_outline_sections(
request.config.custom_outline,
request.config.max_subtopics,
structure_mode=request.config.structure_mode,
)
if outline_sections:
return {"sections": outline_sections}
try:
result = await adapters.llm.complete(
model_role="strategic",
messages=[
{"role": "system", "content": _SYSTEM},
{
"role": "user",
"content": _PLAN_PROMPT.format(query=request.query, count=request.config.max_subtopics),
},
],
response_schema=MultiAgentPlan,
operation="generate_multi_agent_plan",
)
except ResearchCancelled:
raise
except Exception:
await adapters.events.emit(
"warning",
phase="planning",
payload={
"code": "multi_agent_plan_fallback",
"message": "研究计划生成超时或失败,已使用原始课题作为研究范围。",
"recoverable": True,
},
)
return {"sections": [request.query]}
sections = result.structured.sections if result.structured else []
normalised = self._normalise_sections(sections, request.config.max_subtopics)
return {"sections": normalised or [request.query]}
async def _revise_plan(self, llm, query: str, plan: dict[str, Any], feedback: str) -> dict[str, Any]:
prompt = f'Research topic: {query}\nExisting plan: {json.dumps(plan, ensure_ascii=False)}\nHuman feedback: {feedback}\nReturn JSON only: {{"sections": ["..."]}}.'
result = await llm.complete(
model_role="strategic",
messages=[{"role": "system", "content": _SYSTEM}, {"role": "user", "content": prompt}],
response_schema=MultiAgentPlan,
operation="revise_multi_agent_plan",
)
sections = result.structured.sections if result.structured else []
normalised = self._normalise_sections(sections, len(plan.get("sections") or []) or 1)
return {"sections": normalised or list(plan.get("sections") or [query])}
def _build_graph(self, request: DeepResearchRequest, adapters: AdapterBundle, cancellation):
model_semaphore = asyncio.Semaphore(max(1, request.config.max_concurrency))
async def research_node(state: _MultiAgentState) -> dict[str, Any]:
await adapters.events.emit(
"phase_changed",
phase="collecting",
payload={"from": "planning", "to": "collecting"},
)
sections = list(state["plan"].get("sections") or [])
results = await asyncio.gather(
*[self._research_section(section, request, adapters, cancellation, model_semaphore) for section in sections],
return_exceptions=True,
)
materials: list[ResearchMaterial] = []
for result in results:
if isinstance(result, ResearchCancelled):
raise result
if isinstance(result, Exception):
await adapters.events.emit(
"warning",
phase="collecting",
payload={"code": "multi_agent_researcher_failed", "message": str(result), "recoverable": True},
)
else:
materials.extend(result)
return {"materials": materials}
async def writer_node(state: _MultiAgentState) -> dict[str, Any]:
materials = dedupe_materials(state.get("materials") or [])
if not materials:
return {"report": ""}
await adapters.events.emit(
"phase_changed",
phase="curating",
payload={"from": "collecting", "to": "curating"},
)
await adapters.events.emit(
"sources_curated",
phase="curating",
payload={"selectedIds": [material.id for material in materials], "removedIds": [], "reason": "multi_agent_deduped"},
)
await adapters.events.emit(
"phase_changed",
phase="compressing",
payload={"from": "curating", "to": "compressing"},
)
adapters.context.set_materials(materials)
context_list = await adapters.context.async_get_context(
request.query,
max_results=min(len(materials), request.config.max_search_results_per_query * 2),
)
if not context_list:
context_list = [
material.to_context_dict()
for material in materials[: min(len(materials), request.config.max_search_results_per_query * 2)]
]
await adapters.events.emit(
"warning",
phase="compressing",
payload={
"code": "context_fallback",
"message": "材料压缩未返回上下文,已直接使用已收集素材撰写报告",
"recoverable": True,
"sourceCount": len(materials),
"diagnostic": {
"stage": "compressing",
"outcome": "empty_context",
"sourceCount": len(materials),
},
},
)
await adapters.events.emit(
"phase_changed",
phase="writing",
payload={"from": "compressing", "to": "writing"},
)
report = await self._generate_report(
adapters.llm,
request,
_format_context(context_list, materials),
adapters.events,
cancellation,
source_count=len(materials),
)
# Keep the numbered context around so the runner can append the
# deterministic reference section with the same [N] numbers the
# writer saw (revise_node rewrites the report but keeps citations).
return {"report": report, "context_list": context_list}
async def reviewer_node(state: _MultiAgentState) -> dict[str, Any]:
await adapters.events.emit(
"phase_changed",
phase="reviewing",
payload={"from": "writing", "to": "reviewing"},
)
async with model_semaphore:
result = await adapters.llm.complete(
model_role="smart",
messages=[
{"role": "system", "content": _SYSTEM},
{"role": "user", "content": _REVIEW_PROMPT.format(report=state.get("report") or "")},
],
response_schema=ReviewVerdict,
operation="review_multi_agent_report",
)
verdict = result.structured if result.structured else ReviewVerdict()
return {"review": verdict.model_dump()}
async def revise_node(state: _MultiAgentState) -> dict[str, Any]:
review = state.get("review") or {}
report_version = int(state.get("revision_count") or 0) + 2
await adapters.events.emit(
"report_reset",
phase="writing",
payload={"reportVersion": report_version, "reason": "review_revision"},
)
from deerflow.agents.deep_research.runners.report_stream import ReportChunkEmitter
emitter = ReportChunkEmitter(adapters.events, report_version=report_version)
async with model_semaphore:
result = await adapters.llm.stream_complete(
model_role="smart",
messages=[
{"role": "system", "content": _SYSTEM},
{
"role": "user",
"content": _REVISE_PROMPT.format(notes=review.get("revision_notes") or "", report=state.get("report") or ""),
},
],
operation="revise_multi_agent_report",
on_delta=emitter.add,
on_reasoning=emitter.add_thinking,
)
await emitter.flush()
return {"report": result.text, "revision_count": int(state.get("revision_count") or 0) + 1}
def route_review(state: _MultiAgentState) -> str:
review = state.get("review") or {}
if review.get("approved") or int(state.get("revision_count") or 0) >= request.config.max_revision_loops:
return "done"
return "revise"
workflow = StateGraph(_MultiAgentState)
workflow.add_node("researcher", research_node)
workflow.add_node("writer", writer_node)
workflow.add_node("reviewer", reviewer_node)
workflow.add_node("reviser", revise_node)
workflow.add_edge(START, "researcher")
workflow.add_edge("researcher", "writer")
workflow.add_edge("writer", "reviewer")
workflow.add_conditional_edges("reviewer", route_review, {"done": END, "revise": "reviser"})
workflow.add_edge("reviser", "reviewer")
return workflow.compile()
async def _research_section(
self,
section: str,
request: DeepResearchRequest,
adapters: AdapterBundle,
cancellation,
model_semaphore: asyncio.Semaphore,
) -> list[ResearchMaterial]:
self._raise_if_cancelled(cancellation)
async with model_semaphore:
queries = await self._generate_queries(
adapters.llm,
section,
request.config.max_iterations,
cancellation,
events=adapters.events,
phase="collecting",
retrieval_directions=request.config.retrieval_directions,
)
ordered_queries = list(dict.fromkeys([*queries, section]))[: request.config.max_iterations + 1]
await adapters.events.emit(
"queries_planned",
phase="collecting",
payload={"parentTopic": section, "queries": ordered_queries},
)
materials: list[ResearchMaterial] = []
for query in ordered_queries:
try:
materials.extend(
await self._search_one(
adapters.materials,
query,
request.config,
request,
cancellation,
adapters.events,
)
)
except ResearchCancelled:
raise
except Exception as exc: # noqa: BLE001 - one failed term must not abort the section
await adapters.events.emit(
"warning",
phase="collecting",
payload={"code": "search_failed", "message": str(exc), "recoverable": True},
)
return materials
async def _no_materials_result(self, request: DeepResearchRequest, adapters: AdapterBundle, plan: dict[str, Any]) -> DeepResearchResult:
return await super()._no_materials_result(request, adapters, plan)
@staticmethod
def _normalise_sections(sections: list[str], max_sections: int) -> list[str]:
seen: set[str] = set()
result: list[str] = []
for section in sections:
title = section.strip()
if not title or title in seen:
continue
seen.add(title)
result.append(title)
if len(result) >= max_sections:
break
return result
@staticmethod
def _raise_if_cancelled(cancellation) -> None:
if cancellation:
cancellation.raise_if_cancelled()
__all__ = ["MultiAgentPlan", "MultiAgentRunner", "ReviewVerdict"]
@@ -0,0 +1,101 @@
"""Small, durable report-delta emitter shared by research runners.
The event store intentionally persists every emitted event. Sending one event
for each provider token would therefore create excessive database writes and
make reconnect replay expensive. This helper keeps the first visible delta
immediate, then coalesces later deltas into bounded chunks.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from deerflow.agents.deep_research.events import EventSink, ResearchPhase
class ReportChunkEmitter:
"""Coalesce model deltas into replayable ``report_chunk`` events."""
def __init__(
self,
events: EventSink,
*,
target: str = "report",
report_version: int = 1,
phase: ResearchPhase = "writing",
chunk_size: int = 480,
) -> None:
self._events = events
self._target = target
self._report_version = report_version
self._phase = phase
self._chunk_size = chunk_size
self._buffer = ""
self._sent_first = False
self._next_offset = 0
self._persisted_offset = 0
async def add(self, delta: str) -> None:
"""Add a provider delta, making the first one visible immediately."""
if not delta:
return
# The sandbox UI receives the native model delta immediately. This is
# intentionally non-durable; ``report_chunk`` below remains the
# bounded checkpoint used for reconnect replay.
await self._events.publish_live(
"report_delta",
phase=self._phase,
payload={
"delta": delta,
"target": self._target,
"reportVersion": self._report_version,
"offset": self._next_offset,
},
)
self._next_offset += len(delta)
self._buffer += delta
if not self._sent_first:
first = self._buffer[: self._chunk_size]
await self._emit(first)
self._buffer = self._buffer[self._chunk_size :]
self._sent_first = True
while len(self._buffer) >= self._chunk_size:
await self._emit(self._buffer[: self._chunk_size])
self._buffer = self._buffer[self._chunk_size :]
async def add_thinking(self, delta: str) -> None:
"""Forward reasoning to the live UI without persisting it as report text."""
if not delta:
return
await self._events.publish_live(
"report_thinking",
phase=self._phase,
payload={
"delta": delta,
"target": self._target,
"reportVersion": self._report_version,
},
)
async def flush(self) -> None:
"""Persist the final tail once the model stream has finished."""
if self._buffer:
await self._emit(self._buffer)
self._buffer = ""
async def _emit(self, delta: str) -> None:
await self._events.emit(
"report_chunk",
phase=self._phase,
payload={
"delta": delta,
"target": self._target,
"reportVersion": self._report_version,
"offset": self._persisted_offset,
},
)
self._persisted_offset += len(delta)
__all__ = ["ReportChunkEmitter"]
@@ -0,0 +1,181 @@
"""Deep Research domain types.
These types are the **contract** between the DeerFlow adapters and the vendored
GPT Researcher algorithms:
- ``ResearchMaterial`` — the richer replacement for upstream's ``{url, raw_content}``
dict. Carries full DeerFlow provenance (title, source, ``rec_uuid``, publish time,
relevance) so report citations can always trace back to the originating record.
- ``DeepResearchRequest`` / ``DeepResearchResult`` — engine I/O.
- ``AdapterBundle`` — the named tuple of adapters handed to every runner.
"""
from __future__ import annotations
import hashlib
from datetime import datetime
from typing import TYPE_CHECKING, Any, NamedTuple
from pydantic import BaseModel, Field
from deerflow.agents.deep_research.config import DeepResearchConfig, ModelRole, SourceType
if TYPE_CHECKING:
from deerflow.agents.deep_research.adapters.artifacts import ArtifactWriter
from deerflow.agents.deep_research.adapters.context import DeerFlowContextCompressor
from deerflow.agents.deep_research.adapters.event_sink import EventSink
from deerflow.agents.deep_research.adapters.image import ImageProvider
from deerflow.agents.deep_research.adapters.llm import DeerFlowCompletionBackend
from deerflow.agents.deep_research.adapters.material import MaterialProvider
# ── Research material ────────────────────────────────────────────────────────
class ResearchMaterial(BaseModel):
"""A single piece of research material, fully provenance-tagged.
Supersedes upstream's bare ``{url, raw_content}``: the vendored code receives
``raw_content`` already fetched by the DeerFlow material provider, so it
**never** calls a scraper. Every field here survives into the source store
and into report citations.
"""
id: str
query: str = ""
title: str = ""
url: str | None = None
raw_content: str = ""
snippet: str | None = None
source: str = ""
source_type: SourceType = "web"
published_at: datetime | None = None
relevance_score: float | None = None
rec_uuid: str | None = None
content_hash: str = ""
metadata: dict[str, Any] = Field(default_factory=dict)
model_config = {"extra": "allow"}
def to_context_dict(self) -> dict[str, Any]:
"""The dict shape written into the vendored context list.
Mirrors upstream ``{url, raw_content}`` but preserves *all* DeerFlow
fields so downstream citation binding can recover the source id.
"""
return {
"id": self.id,
"query": self.query,
"title": self.title,
"url": self.url,
"raw_content": self.raw_content,
"snippet": self.snippet,
"source": self.source,
"source_type": self.source_type,
"published_at": self.published_at.isoformat() if self.published_at else None,
"relevance_score": self.relevance_score,
"recUuid": self.rec_uuid,
"metadata": self.metadata,
}
def compute_hash(self) -> str:
"""Stable content fingerprint for dedup (canonical URL preferred)."""
basis = self.url or self.rec_uuid or self.content_hash or self.raw_content
return hashlib.sha256(basis.encode("utf-8")).hexdigest()[:32]
def to_persistence_dict(self, query: str = "") -> dict[str, Any]:
"""Fields for ``DeepResearchSourceRepository.upsert()``.
Excludes ``session_id`` / ``job_id`` (the executor supplies those).
Backfills ``content_hash`` from :meth:`compute_hash` if empty so the
dedup-by-hash fallback works out of the box.
"""
return {
"id": self.id,
"first_seen_query": query or self.query,
"title": self.title,
"url": self.url,
"raw_content": self.raw_content,
"snippet": self.snippet,
"source": self.source,
"source_type": self.source_type,
"published_at": self.published_at,
"relevance_score": self.relevance_score,
"rec_uuid": self.rec_uuid,
"content_hash": self.content_hash or self.compute_hash(),
}
# ── Engine I/O ───────────────────────────────────────────────────────────────
class DeepResearchRequest(BaseModel):
"""Input to ``DeepResearchEngine.run()``."""
session_id: str
user_id: str
query: str
config: DeepResearchConfig
request_id: str = ""
# Filled only when a durable multi-agent plan-review job is resumed.
resume_payload: dict[str, Any] = Field(default_factory=dict)
interrupted_plan: dict[str, Any] | None = None
model_config = {"extra": "forbid"}
class DeepResearchResult(BaseModel):
"""Output of ``DeepResearchEngine.run()``."""
report_markdown: str = ""
report_html: str | None = None
source_ids: list[str] = Field(default_factory=list)
artifact_paths: dict[str, str] = Field(default_factory=dict)
usage: dict[str, Any] = Field(default_factory=dict)
plan: dict[str, Any] | None = None
diagnostics: list[dict[str, Any]] = Field(default_factory=list)
# ── Adapter bundle ───────────────────────────────────────────────────────────
class AdapterBundle(NamedTuple):
"""The five adapters every runner needs, bundled for clean passing.
The vendored GPT Researcher code is adapted to call *only* these (or objects
they produce) — never ``requests``, never ``create_chat_model`` directly,
never the filesystem outside ``ArtifactWriter``.
"""
llm: DeerFlowCompletionBackend
materials: MaterialProvider
context: DeerFlowContextCompressor
artifacts: ArtifactWriter
events: EventSink
images: ImageProvider | None
# ── Completion result (returned by the LLM adapter) ─────────────────────────
class CompletionResult(BaseModel):
"""Normalised LLM completion — text + usage, model-agnostic."""
text: str
model: str = ""
usage: dict[str, Any] = Field(default_factory=dict)
# When ``response_schema`` was requested, the parsed object (already validated).
structured: Any | None = None
model_config = {"extra": "allow"}
__all__ = [
"AdapterBundle",
"CompletionResult",
"DeepResearchRequest",
"DeepResearchResult",
"ModelRole",
"ResearchMaterial",
"SourceType",
]
@@ -0,0 +1,374 @@
"""Pure-argument factory for DeerFlow agents.
``create_deerflow_agent`` accepts plain Python arguments — no YAML files, no
global singletons. It is the SDK-level entry point sitting between the raw
``langchain.agents.create_agent`` primitive and the config-driven
``make_lead_agent`` application factory.
Note: the factory assembly itself is config-free, but some injected runtime
components (e.g. ``task_tool`` for subagent) may still read global config at
invocation time. Full config-free runtime is a Phase 2 goal.
"""
from __future__ import annotations
import logging
from typing import TYPE_CHECKING
from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware
from deerflow.agents.features import RuntimeFeatures
from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
from deerflow.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
from deerflow.agents.middlewares.tool_error_handling_middleware import ToolErrorHandlingMiddleware
from deerflow.agents.thread_state import ThreadState
from deerflow.tools.builtins import ask_clarification_tool
if TYPE_CHECKING:
from langchain_core.language_models import BaseChatModel
from langchain_core.tools import BaseTool
from langgraph.checkpoint.base import BaseCheckpointSaver
from langgraph.graph.state import CompiledStateGraph
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# TodoMiddleware prompts (minimal SDK version)
# ---------------------------------------------------------------------------
_TODO_SYSTEM_PROMPT = """
<todo_list_system>
You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
**CRITICAL RULES:**
- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
</todo_list_system>
"""
_TODO_TOOL_DESCRIPTION = "Use this tool to create and manage a structured task list for complex work sessions. Only use for complex tasks (3+ steps)."
# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------
def create_deerflow_agent(
model: BaseChatModel,
tools: list[BaseTool] | None = None,
*,
system_prompt: str | None = None,
middleware: list[AgentMiddleware] | None = None,
features: RuntimeFeatures | None = None,
extra_middleware: list[AgentMiddleware] | None = None,
plan_mode: bool = False,
state_schema: type | None = None,
checkpointer: BaseCheckpointSaver | None = None,
name: str = "default",
) -> CompiledStateGraph:
"""Create a DeerFlow agent from plain Python arguments.
The factory assembly itself reads no config files. Some injected runtime
components (e.g. ``task_tool``) may still depend on global config at
invocation time — see Phase 2 roadmap for full config-free runtime.
Parameters
----------
model:
Chat model instance.
tools:
User-provided tools. Feature-injected tools are appended automatically.
system_prompt:
System message. ``None`` uses a minimal default.
middleware:
**Full takeover** — if provided, this exact list is used.
Cannot be combined with *features* or *extra_middleware*.
features:
Declarative feature flags. Cannot be combined with *middleware*.
extra_middleware:
Additional middlewares inserted into the auto-assembled chain via
``@Next``/``@Prev`` positioning. Cannot be used with *middleware*.
plan_mode:
Enable TodoMiddleware for task tracking.
state_schema:
LangGraph state type. Defaults to ``ThreadState``.
checkpointer:
Optional persistence backend.
name:
Agent name (passed to middleware that cares, e.g. ``MemoryMiddleware``).
Raises
------
ValueError
If both *middleware* and *features*/*extra_middleware* are provided.
"""
if middleware is not None and features is not None:
raise ValueError("Cannot specify both 'middleware' and 'features'. Use one or the other.")
if middleware is not None and extra_middleware:
raise ValueError("Cannot use 'extra_middleware' with 'middleware' (full takeover).")
if extra_middleware:
for mw in extra_middleware:
if not isinstance(mw, AgentMiddleware):
raise TypeError(f"extra_middleware items must be AgentMiddleware instances, got {type(mw).__name__}")
effective_tools: list[BaseTool] = list(tools or [])
effective_state = state_schema or ThreadState
if middleware is not None:
effective_middleware = list(middleware)
else:
feat = features or RuntimeFeatures()
effective_middleware, extra_tools = _assemble_from_features(
feat,
name=name,
plan_mode=plan_mode,
extra_middleware=extra_middleware or [],
)
# Deduplicate by tool name — user-provided tools take priority.
existing_names = {t.name for t in effective_tools}
for t in extra_tools:
if t.name not in existing_names:
effective_tools.append(t)
existing_names.add(t.name)
return create_agent(
model=model,
tools=effective_tools or None,
middleware=effective_middleware,
system_prompt=system_prompt,
state_schema=effective_state,
checkpointer=checkpointer,
name=name,
)
# ---------------------------------------------------------------------------
# Internal: feature-driven middleware assembly
# ---------------------------------------------------------------------------
def _assemble_from_features(
feat: RuntimeFeatures,
*,
name: str = "default",
plan_mode: bool = False,
extra_middleware: list[AgentMiddleware] | None = None,
) -> tuple[list[AgentMiddleware], list[BaseTool]]:
"""Build an ordered middleware chain + extra tools from *feat*.
Middleware order matches ``make_lead_agent`` (14 middlewares):
0-2. Sandbox infrastructure (ThreadData → Uploads → Sandbox)
3. DanglingToolCallMiddleware (always)
4. GuardrailMiddleware (guardrail feature)
5. ToolErrorHandlingMiddleware (always)
6. SummarizationMiddleware (summarization feature)
7. TodoMiddleware (plan_mode parameter)
8. TitleMiddleware (auto_title feature)
9. MemoryMiddleware (memory feature)
10. ViewImageMiddleware (vision feature)
11. SubagentLimitMiddleware (subagent feature)
12. LoopDetectionMiddleware (always)
13. ClarificationMiddleware (always last)
Two-phase ordering:
1. Built-in chain — fixed sequential append.
2. Extra middleware — inserted via @Next/@Prev.
Each feature value is handled as:
- ``False``: skip
- ``True``: create the built-in default middleware (not available for
``summarization`` and ``guardrail`` — these require a custom instance)
- ``AgentMiddleware`` instance: use directly (custom replacement)
"""
chain: list[AgentMiddleware] = []
extra_tools: list[BaseTool] = []
# --- [0-2] Sandbox infrastructure ---
if feat.sandbox is not False:
if isinstance(feat.sandbox, AgentMiddleware):
chain.append(feat.sandbox)
else:
from deerflow.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
from deerflow.agents.middlewares.uploads_middleware import UploadsMiddleware
from deerflow.sandbox.middleware import SandboxMiddleware
chain.append(ThreadDataMiddleware(lazy_init=True))
chain.append(UploadsMiddleware())
chain.append(SandboxMiddleware(lazy_init=True))
# --- [3] DanglingToolCall (always) ---
chain.append(DanglingToolCallMiddleware())
# --- [4] Guardrail ---
if feat.guardrail is not False:
if isinstance(feat.guardrail, AgentMiddleware):
chain.append(feat.guardrail)
else:
raise ValueError("guardrail=True requires a custom AgentMiddleware instance (no built-in GuardrailMiddleware yet)")
# --- [5] ToolErrorHandling (always) ---
chain.append(ToolErrorHandlingMiddleware())
# --- [6] Summarization ---
if feat.summarization is not False:
if isinstance(feat.summarization, AgentMiddleware):
chain.append(feat.summarization)
else:
raise ValueError("summarization=True requires a custom AgentMiddleware instance (SummarizationMiddleware needs a model argument)")
# --- [7] TodoMiddleware (plan_mode) ---
if plan_mode:
from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
chain.append(TodoMiddleware(system_prompt=_TODO_SYSTEM_PROMPT, tool_description=_TODO_TOOL_DESCRIPTION))
# --- [8] Auto Title ---
if feat.auto_title is not False:
if isinstance(feat.auto_title, AgentMiddleware):
chain.append(feat.auto_title)
else:
from deerflow.agents.middlewares.title_middleware import TitleMiddleware
chain.append(TitleMiddleware())
# --- [9] Memory ---
if feat.memory is not False:
if isinstance(feat.memory, AgentMiddleware):
chain.append(feat.memory)
else:
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
chain.append(MemoryMiddleware(agent_name=name))
# --- [10] Vision ---
if feat.vision is not False:
if isinstance(feat.vision, AgentMiddleware):
chain.append(feat.vision)
else:
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
chain.append(ViewImageMiddleware())
if feat.sandbox is not False:
from deerflow.tools.builtins import view_image_tool
extra_tools.append(view_image_tool)
# --- [11] Subagent ---
if feat.subagent is not False:
if isinstance(feat.subagent, AgentMiddleware):
chain.append(feat.subagent)
else:
from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
chain.append(SubagentLimitMiddleware())
from deerflow.tools.builtins import task_tool
extra_tools.append(task_tool)
# --- [12] LoopDetection (always) ---
from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
chain.append(LoopDetectionMiddleware())
# --- [13] Clarification (always last among built-ins) ---
chain.append(ClarificationMiddleware())
extra_tools.append(ask_clarification_tool)
# --- Insert extra_middleware via @Next/@Prev ---
if extra_middleware:
_insert_extra(chain, extra_middleware)
# Invariant: ClarificationMiddleware must always be last.
# @Next(ClarificationMiddleware) could push it off the tail.
clar_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
if clar_idx != len(chain) - 1:
chain.append(chain.pop(clar_idx))
return chain, extra_tools
# ---------------------------------------------------------------------------
# Internal: extra middleware insertion with @Next/@Prev
# ---------------------------------------------------------------------------
def _insert_extra(chain: list[AgentMiddleware], extras: list[AgentMiddleware]) -> None:
"""Insert extra middlewares into *chain* using ``@Next``/``@Prev`` anchors.
Algorithm:
1. Validate: no middleware has both @Next and @Prev.
2. Conflict detection: two extras targeting same anchor (same or opposite direction) → error.
3. Insert unanchored extras before ClarificationMiddleware.
4. Insert anchored extras iteratively (supports cross-external anchoring).
5. If an anchor cannot be resolved after all rounds → error.
"""
next_targets: dict[type, type] = {}
prev_targets: dict[type, type] = {}
anchored: list[tuple[AgentMiddleware, str, type]] = []
unanchored: list[AgentMiddleware] = []
for mw in extras:
next_anchor = getattr(type(mw), "_next_anchor", None)
prev_anchor = getattr(type(mw), "_prev_anchor", None)
if next_anchor and prev_anchor:
raise ValueError(f"{type(mw).__name__} cannot have both @Next and @Prev")
if next_anchor:
if next_anchor in next_targets:
raise ValueError(f"Conflict: {type(mw).__name__} and {next_targets[next_anchor].__name__} both @Next({next_anchor.__name__})")
if next_anchor in prev_targets:
raise ValueError(f"Conflict: {type(mw).__name__} @Next({next_anchor.__name__}) and {prev_targets[next_anchor].__name__} @Prev({next_anchor.__name__}) — use cross-anchoring between extras instead")
next_targets[next_anchor] = type(mw)
anchored.append((mw, "next", next_anchor))
elif prev_anchor:
if prev_anchor in prev_targets:
raise ValueError(f"Conflict: {type(mw).__name__} and {prev_targets[prev_anchor].__name__} both @Prev({prev_anchor.__name__})")
if prev_anchor in next_targets:
raise ValueError(f"Conflict: {type(mw).__name__} @Prev({prev_anchor.__name__}) and {next_targets[prev_anchor].__name__} @Next({prev_anchor.__name__}) — use cross-anchoring between extras instead")
prev_targets[prev_anchor] = type(mw)
anchored.append((mw, "prev", prev_anchor))
else:
unanchored.append(mw)
# Unanchored → before ClarificationMiddleware
clarification_idx = next(i for i, m in enumerate(chain) if isinstance(m, ClarificationMiddleware))
for mw in unanchored:
chain.insert(clarification_idx, mw)
clarification_idx += 1
# Anchored → iterative insertion (supports external-to-external anchoring)
pending = list(anchored)
max_rounds = len(pending) + 1
for _ in range(max_rounds):
if not pending:
break
remaining = []
for mw, direction, anchor in pending:
idx = next(
(i for i, m in enumerate(chain) if isinstance(m, anchor)),
None,
)
if idx is None:
remaining.append((mw, direction, anchor))
continue
if direction == "next":
chain.insert(idx + 1, mw)
else:
chain.insert(idx, mw)
if len(remaining) == len(pending):
names = [type(m).__name__ for m, _, _ in remaining]
anchor_types = {a for _, _, a in remaining}
remaining_types = {type(m) for m, _, _ in remaining}
circular = anchor_types & remaining_types
if circular:
raise ValueError(f"Circular dependency among extra middlewares: {', '.join(t.__name__ for t in circular)}")
raise ValueError(f"Cannot resolve positions for {', '.join(names)} — anchors {', '.join(a.__name__ for _, _, a in remaining)} not found in chain")
pending = remaining
@@ -0,0 +1,62 @@
"""Declarative feature flags and middleware positioning for create_deerflow_agent.
Pure data classes and decorators — no I/O, no side effects.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Literal
from langchain.agents.middleware import AgentMiddleware
@dataclass
class RuntimeFeatures:
"""Declarative feature flags for ``create_deerflow_agent``.
Most features accept:
- ``True``: use the built-in default middleware
- ``False``: disable
- An ``AgentMiddleware`` instance: use this custom implementation instead
``summarization`` and ``guardrail`` have no built-in default — they only
accept ``False`` (disable) or an ``AgentMiddleware`` instance (custom).
"""
sandbox: bool | AgentMiddleware = True
memory: bool | AgentMiddleware = False
summarization: Literal[False] | AgentMiddleware = False
subagent: bool | AgentMiddleware = False
vision: bool | AgentMiddleware = False
auto_title: bool | AgentMiddleware = False
guardrail: Literal[False] | AgentMiddleware = False
# ---------------------------------------------------------------------------
# Middleware positioning decorators
# ---------------------------------------------------------------------------
def Next(anchor: type[AgentMiddleware]):
"""Declare this middleware should be placed after *anchor* in the chain."""
if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
raise TypeError(f"@Next expects an AgentMiddleware subclass, got {anchor!r}")
def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
cls._next_anchor = anchor # type: ignore[attr-defined]
return cls
return decorator
def Prev(anchor: type[AgentMiddleware]):
"""Declare this middleware should be placed before *anchor* in the chain."""
if not (isinstance(anchor, type) and issubclass(anchor, AgentMiddleware)):
raise TypeError(f"@Prev expects an AgentMiddleware subclass, got {anchor!r}")
def decorator(cls: type[AgentMiddleware]) -> type[AgentMiddleware]:
cls._prev_anchor = anchor # type: ignore[attr-defined]
return cls
return decorator
@@ -0,0 +1,186 @@
"""Small local streaming graph used for exact-match fixed answers.
The graph deliberately uses a local ``BaseChatModel`` implementation so
LangGraph emits the same token/message stream events as a normal model-backed
answer, while making no network or model-provider request.
"""
from __future__ import annotations
import asyncio
import codecs
import math
import uuid
from collections.abc import AsyncIterator, Sequence
from typing import Any
import tiktoken
from langchain_core.callbacks import AsyncCallbackManagerForLLMRun, CallbackManagerForLLMRun
from langchain_core.language_models.chat_models import BaseChatModel
from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage
from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
from langchain_core.runnables import RunnableConfig
from langgraph.graph import END, START, StateGraph
from deerflow.agents.thread_state import ThreadState
_TOKEN_ENCODING = tiktoken.get_encoding("cl100k_base")
_TARGET_CHUNKS_PER_SECOND = 10
_MAX_TOKENS_PER_CHUNK = 20
_MAX_TOKENS_PER_SECOND = 1_000
class FixedAnswerChatModel(BaseChatModel):
"""A local streaming model that only replays an administrator answer."""
answer: str
message_id: str
fixed_question_id: str
tokens_per_second: int = 100
@property
def _llm_type(self) -> str:
return "fixed-answer"
@property
def _identifying_params(self) -> dict[str, Any]:
return {
"fixed_question_id": self.fixed_question_id,
"tokens_per_second": self.tokens_per_second,
}
def _message(self) -> AIMessage:
return AIMessage(
content=self.answer,
id=self.message_id,
additional_kwargs={
"fixed_answer": True,
"fixed_question_id": self.fixed_question_id,
"tokens_per_second": self.tokens_per_second,
},
)
def _generate(
self,
messages: list[BaseMessage],
stop: list[str] | None = None,
run_manager: CallbackManagerForLLMRun | None = None,
**kwargs: Any,
) -> ChatResult:
del messages, stop, run_manager, kwargs
return ChatResult(generations=[ChatGeneration(message=self._message())])
async def _astream(
self,
messages: list[BaseMessage],
stop: list[str] | None = None,
run_manager: AsyncCallbackManagerForLLMRun | None = None,
**kwargs: Any,
) -> AsyncIterator[ChatGenerationChunk]:
del messages, stop, run_manager, kwargs
answer = self.answer
if not answer:
yield ChatGenerationChunk(message=AIMessageChunk(content="", id=self.message_id))
return
token_ids = _TOKEN_ENCODING.encode(answer, disallowed_special=())
tokens_per_second = max(
1,
min(_MAX_TOKENS_PER_SECOND, self.tokens_per_second),
)
chunk_size = max(
1,
min(
_MAX_TOKENS_PER_CHUNK,
math.ceil(tokens_per_second / _TARGET_CHUNKS_PER_SECOND),
),
)
decoder = codecs.getincrementaldecoder("utf-8")()
token_groups = [token_ids[:1], *(token_ids[offset : offset + chunk_size] for offset in range(1, len(token_ids), chunk_size))]
for index, chunk_token_ids in enumerate(token_groups):
if index > 0:
await asyncio.sleep(len(chunk_token_ids) / tokens_per_second)
chunk_bytes = b"".join(_TOKEN_ENCODING.decode_single_token_bytes(token_id) for token_id in chunk_token_ids)
is_last = index == len(token_groups) - 1
content = decoder.decode(chunk_bytes, final=is_last)
chunk_kwargs = (
{
"fixed_answer": True,
"fixed_question_id": self.fixed_question_id,
"tokens_per_second": tokens_per_second,
}
if index == 0
else {}
)
yield ChatGenerationChunk(
message=AIMessageChunk(
content=content,
id=self.message_id,
additional_kwargs=chunk_kwargs,
)
)
def _fallback_title(question: str) -> str:
if len(question) > 50:
return question[:50].rstrip() + "..."
return question or "New Conversation"
def make_fixed_answer_agent(
*,
question: str,
answer: str,
fixed_question_id: str,
tokens_per_second: int = 100,
):
"""Build a one-node graph that streams and persists a fixed answer."""
tokens_per_second = max(
1,
min(_MAX_TOKENS_PER_SECOND, int(tokens_per_second)),
)
message_id = f"fixed-answer-{uuid.uuid4()}"
model = FixedAnswerChatModel(
answer=answer,
message_id=message_id,
fixed_question_id=fixed_question_id,
tokens_per_second=tokens_per_second,
).with_config(tags=["fixed-answer"])
async def respond(
state: ThreadState,
config: RunnableConfig,
) -> dict[str, Any]:
messages: Sequence[BaseMessage] = state.get("messages", [])
# Calling the local model through ``astream`` makes the runtime publish
# normal messages-mode chunks. The full AIMessage returned below is the
# durable checkpoint value used on refresh/history reads.
async for _chunk in model.astream(list(messages), config=config):
pass
update: dict[str, Any] = {
"messages": [
AIMessage(
content=answer,
id=message_id,
additional_kwargs={
"fixed_answer": True,
"fixed_question_id": fixed_question_id,
"tokens_per_second": tokens_per_second,
},
)
]
}
if not state.get("title"):
update["title"] = _fallback_title(question)
update["title_provisional"] = False
elif state.get("title_provisional") is True:
# A fixed-answer run must not trigger the worker's background LLM
# title finalizer either; keep the already-visible local title.
update["title_provisional"] = False
return update
graph = StateGraph(ThreadState)
graph.add_node("fixed_answer", respond)
graph.add_edge(START, "fixed_answer")
graph.add_edge("fixed_answer", END)
return graph.compile()
@@ -0,0 +1,3 @@
from .agent import make_lead_agent
__all__ = ["make_lead_agent"]
@@ -0,0 +1,870 @@
import hashlib
import logging
from langchain.agents import create_agent
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.loop_detection_middleware import LoopDetectionMiddleware
from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
from deerflow.agents.middlewares.prompt_prefix_middleware import PromptPrefixMiddleware
from deerflow.agents.middlewares.rag_citation_middleware import RagCitationMiddleware
from deerflow.agents.middlewares.setup_agent_approval_middleware import SetupAgentApprovalMiddleware
from deerflow.agents.middlewares.setup_report_structure_approval_middleware import SetupReportStructureApprovalMiddleware
from deerflow.agents.middlewares.setup_writing_approval_middleware import SetupWritingApprovalMiddleware
from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
from deerflow.agents.middlewares.summarization_middleware import BeforeSummarizationHook, DeerFlowSummarizationMiddleware
from deerflow.agents.middlewares.task_external_context_middleware import TaskExternalContextMiddleware
from deerflow.agents.middlewares.title_middleware import TitleMiddleware
from deerflow.agents.middlewares.todo_middleware import TodoMiddleware
from deerflow.agents.middlewares.token_usage_middleware import TokenUsageMiddleware
from deerflow.agents.middlewares.tool_error_handling_middleware import build_lead_runtime_middlewares
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
from deerflow.agents.thread_state import ThreadState
from deerflow.config.agents_config import load_agent_config, load_agent_soul, validate_agent_id
from deerflow.config.app_config import AppConfig, get_app_config
from deerflow.models import create_chat_model
logger = logging.getLogger(__name__)
# 写作配置 Q&A:意图澄清最多几轮(一条用户消息 = 一轮),到顶强制提交配置卡。
# 写作配置 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">'
_SKILLS_BLOCKED_BY_EXCLUDED_TOOL: dict[str, frozenset[str]] = {
# 内置 tool 与历史 custom skill 目录存在两种拼写;禁用编排工具时两者都必须从系统提示和
# runtime skill allowlist 中消失,防止误配的席位仍看到「加载编排技能」。
"agent_orchestration": frozenset({"agent_orchestration", "agent-orchestration"}),
}
_ROUNDTABLE_COORDINATOR_AGENT_ID = "roundtable-coordinator"
_NON_COORDINATOR_ORCHESTRATION_BOUNDARY = """
<orchestration_capability_boundary>
你不是多智能体圆桌总控,因此没有编排、派活或调度其它智能体的权限。
不得加载、读取、检索或调用 agent_orchestration / agent-orchestration,
不得声称准备使用编排技能;请直接完成当前问答或你的本职任务。
</orchestration_capability_boundary>
""".strip()
def _enforce_coordinator_only_tool_exclusions(
agent_id: str | None,
excluded_tools: list[str] | None,
) -> list[str] | None:
"""Make orchestration unavailable to every agent except the fixed roundtable coordinator."""
if agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID:
return excluded_tools
effective = list(excluded_tools or [])
if "agent_orchestration" not in effective:
effective.append("agent_orchestration")
return effective
def _append_orchestration_capability_boundary(system_prompt: str, agent_id: str | None) -> str:
"""Reinforce the physical tool/skill gate in every non-coordinator system prompt."""
if agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID:
return system_prompt
return f"{system_prompt}\n\n{_NON_COORDINATOR_ORCHESTRATION_BOUNDARY}"
def _filter_available_skills_for_excluded_tools(
available_skills: list[str] | None,
excluded_tools: list[str] | None,
) -> list[str] | None:
"""让工具级禁用同步收紧 skill allowlist,必要时把「全部」展开为安全列表。"""
if not excluded_tools:
return available_skills
excluded = {name.strip().lower() for name in excluded_tools if name}
blocked = {
skill_name
for tool_name, skill_names in _SKILLS_BLOCKED_BY_EXCLUDED_TOOL.items()
if tool_name in excluded
for skill_name in skill_names
}
if not blocked:
return available_skills
if available_skills is None:
# ``None`` 原本表示「全部启用技能可见」,无法表达「除了总控专属技能之外的全部」。
# 此时显式展开存储中的启用技能;扫描失败则 fail closed,避免角色隔离失效。
try:
from deerflow.skills.storage import get_or_new_skill_storage
available_skills = [
skill.name for skill in get_or_new_skill_storage().load_skills(enabled_only=True)
]
except Exception: # noqa: BLE001
logger.warning("Failed to expand skills while applying excluded-tool boundary", exc_info=True)
available_skills = []
return [name for name in available_skills if name.strip().lower() not in blocked]
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:
"""Merge legacy configurable options with LangGraph runtime context."""
cfg = dict(config.get("configurable", {}) or {})
context = config.get("context", {}) or {}
if isinstance(context, dict):
cfg.update(context)
return cfg
def _resolve_model_name(requested_model_name: str | None = None, *, app_config: AppConfig | None = None) -> str:
"""Resolve a runtime model name safely, falling back to default if invalid. Returns None if no models are configured."""
app_config = app_config or get_app_config()
default_model_name = app_config.models[0].name if app_config.models else None
if default_model_name is None:
raise ValueError("No chat models are configured. Please configure at least one model in config.yaml.")
if requested_model_name and app_config.get_model_config(requested_model_name):
return requested_model_name
if requested_model_name and requested_model_name != default_model_name:
logger.warning(f"Model '{requested_model_name}' not found in config; fallback to default model '{default_model_name}'.")
return default_model_name
def _create_summarization_middleware(*, app_config: AppConfig | None = None, force_enabled: bool = False) -> DeerFlowSummarizationMiddleware | None:
"""Create and configure the summarization middleware from config.
Args:
force_enabled: When True, build the middleware regardless of the config
``summarization.enabled`` flag. The per-request 上下文压缩 toggle
(chat input box, default off) drives this — the config file no longer
owns the on/off switch, only the tuning (trigger/keep/...).
"""
resolved_app_config = app_config or get_app_config()
config = resolved_app_config.summarization
if not (config.enabled or force_enabled):
return None
# Prepare trigger parameter
trigger = None
if config.trigger is not None:
if isinstance(config.trigger, list):
trigger = [t.to_tuple() for t in config.trigger]
else:
trigger = config.trigger.to_tuple()
# Prepare keep parameter
keep = config.keep.to_tuple()
# Prepare model parameter.
# Bind "middleware:summarize" tag so RunJournal identifies these LLM calls
# as middleware rather than lead_agent (SummarizationMiddleware is a
# LangChain built-in, so we tag the model at creation time).
if config.model_name:
model = create_chat_model(name=config.model_name, thinking_enabled=False, app_config=resolved_app_config)
else:
model = create_chat_model(thinking_enabled=False, app_config=resolved_app_config)
model = model.with_config(tags=["middleware:summarize"])
# Prepare kwargs
kwargs = {
"model": model,
"trigger": trigger,
"keep": keep,
}
if config.trim_tokens_to_summarize is not None:
kwargs["trim_tokens_to_summarize"] = config.trim_tokens_to_summarize
if config.summary_prompt is not None:
kwargs["summary_prompt"] = config.summary_prompt
# Memory V2:不再有后台抽取队列,无需 summarization 前的 flush hook。
hooks: list[BeforeSummarizationHook] = []
# The logic below relies on two assumptions holding true: this factory is
# the sole entry point for DeerFlowSummarizationMiddleware, and the runtime
# config is not expected to change after startup.
skills_container_path = resolved_app_config.skills.container_path or "/mnt/skills"
return DeerFlowSummarizationMiddleware(
**kwargs,
skills_container_path=skills_container_path,
skill_file_read_tool_names=config.skill_file_read_tool_names,
before_summarization=hooks,
preserve_recent_skill_count=config.preserve_recent_skill_count,
preserve_recent_skill_tokens=config.preserve_recent_skill_tokens,
preserve_recent_skill_tokens_per_skill=config.preserve_recent_skill_tokens_per_skill,
)
def _create_todo_list_middleware(is_plan_mode: bool) -> TodoMiddleware | None:
"""Create and configure the TodoList middleware.
Args:
is_plan_mode: Whether to enable plan mode with TodoList middleware.
Returns:
TodoMiddleware instance if plan mode is enabled, None otherwise.
"""
if not is_plan_mode:
return None
# Custom prompts matching DeerFlow's style
system_prompt = """
<todo_list_system>
You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
**CRITICAL RULES:**
- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
**When to Use:**
This tool is designed for complex objectives that require systematic tracking:
- Complex multi-step tasks requiring 3+ distinct steps
- Non-trivial tasks needing careful planning and execution
- User explicitly requests a todo list
- User provides multiple tasks (numbered or comma-separated list)
- The plan may need revisions based on intermediate results
**When NOT to Use:**
- Single, straightforward tasks
- Trivial tasks (< 3 steps)
- Purely conversational or informational requests
- Simple tool calls where the approach is obvious
**Best Practices:**
- Break down complex tasks into smaller, actionable steps
- Use clear, descriptive task names
- Remove tasks that become irrelevant
- Add new tasks discovered during implementation
- Don't be afraid to revise the todo list as you learn more
**Task Management:**
Writing todos takes time and tokens - use it when helpful for managing complex problems, not for simple requests.
</todo_list_system>
"""
tool_description = """Use this tool to create and manage a structured task list for complex work sessions.
**IMPORTANT: Only use this tool for complex tasks (3+ steps). For simple requests, just do the work directly.**
## When to Use
Use this tool in these scenarios:
1. **Complex multi-step tasks**: When a task requires 3 or more distinct steps or actions
2. **Non-trivial tasks**: Tasks requiring careful planning or multiple operations
3. **User explicitly requests todo list**: When the user directly asks you to track tasks
4. **Multiple tasks**: When users provide a list of things to be done
5. **Dynamic planning**: When the plan may need updates based on intermediate results
## When NOT to Use
Skip this tool when:
1. The task is straightforward and takes less than 3 steps
2. The task is trivial and tracking provides no benefit
3. The task is purely conversational or informational
4. It's clear what needs to be done and you can just do it
## How to Use
1. **Starting a task**: Mark it as `in_progress` BEFORE beginning work
2. **Completing a task**: Mark it as `completed` IMMEDIATELY after finishing
3. **Updating the list**: Add new tasks, remove irrelevant ones, or update descriptions as needed
4. **Multiple updates**: You can make several updates at once (e.g., complete one task and start the next)
## Task States
- `pending`: Task not yet started
- `in_progress`: Currently working on (can have multiple if tasks run in parallel)
- `completed`: Task finished successfully
## Task Completion Requirements
**CRITICAL: Only mark a task as completed when you have FULLY accomplished it.**
Never mark a task as completed if:
- There are unresolved issues or errors
- Work is partial or incomplete
- You encountered blockers preventing completion
- You couldn't find necessary resources or dependencies
- Quality standards haven't been met
If blocked, keep the task as `in_progress` and create a new task describing what needs to be resolved.
## Best Practices
- Create specific, actionable items
- Break complex tasks into smaller, manageable steps
- Use clear, descriptive task names
- Update task status in real-time as you work
- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
- Remove tasks that are no longer relevant
- **IMPORTANT**: When you write the todo list, mark your first task(s) as `in_progress` immediately
- **IMPORTANT**: Unless all tasks are completed, always have at least one task `in_progress` to show progress
Being proactive with task management demonstrates thoroughness and ensures all requirements are completed successfully.
**Remember**: If you only need a few tool calls to complete a task and it's clear what to do, it's better to just do the task directly and NOT use this tool at all.
"""
return TodoMiddleware(system_prompt=system_prompt, tool_description=tool_description)
# ThreadDataMiddleware must be before SandboxMiddleware to ensure thread_id is available
# UploadsMiddleware should be after ThreadDataMiddleware to access thread_id
# DanglingToolCallMiddleware patches missing ToolMessages before model sees the history
# SummarizationMiddleware should be early to reduce context before other processing
# TodoListMiddleware should be before ClarificationMiddleware to allow todo management
# TitleMiddleware generates title after first exchange
# MemoryMiddleware queues conversation for memory update (after TitleMiddleware)
# ViewImageMiddleware should be before ClarificationMiddleware to inject image details before LLM
# ToolErrorHandlingMiddleware should be before ClarificationMiddleware to convert tool exceptions to ToolMessages
# ClarificationMiddleware should be last to intercept clarification requests after model calls
def _build_middlewares(
config: RunnableConfig,
model_name: str | None,
agent_name: str | None = None,
custom_middlewares: list[AgentMiddleware] | None = None,
*,
app_config: AppConfig | None = None,
):
"""Build middleware chain based on runtime configuration.
Args:
config: Runtime configuration containing configurable options like is_plan_mode.
agent_name: If provided, MemoryMiddleware will use per-agent memory storage.
custom_middlewares: Optional list of custom middlewares to inject into the chain.
Returns:
List of middleware instances.
"""
resolved_app_config = app_config or get_app_config()
cfg = _get_runtime_config(config)
middlewares = build_lead_runtime_middlewares(app_config=resolved_app_config, lazy_init=True)
# Inject the admin prompt prefix into the model request (kept out of the
# persisted/displayed message so the user never sees it).
middlewares.append(PromptPrefixMiddleware())
if cfg.get("rag_mode_enabled", False):
middlewares.append(RagCitationMiddleware())
# Add summarization middleware. The on/off switch now lives in the chat UI
# (上下文压缩 toggle, default off) and arrives as ``summarization_enabled`` in
# the runtime config; the config file only supplies tuning. force_enabled
# lets the per-request toggle turn it on even when config.enabled is false,
# while non-UI paths (channels/scheduled) still fall back to config.enabled.
summarization_requested = cfg.get("summarization_enabled", False)
summarization_middleware = _create_summarization_middleware(app_config=resolved_app_config, force_enabled=summarization_requested)
if summarization_middleware is not None:
middlewares.append(summarization_middleware)
# Add TodoList middleware if plan mode is enabled
is_plan_mode = cfg.get("is_plan_mode", False)
is_bootstrap = cfg.get("is_bootstrap", False)
is_writing_setup = cfg.get("is_writing_setup", False)
is_report_structure_setup = cfg.get("is_report_structure_setup", False)
todo_list_middleware = _create_todo_list_middleware(is_plan_mode)
if todo_list_middleware is not None:
middlewares.append(todo_list_middleware)
# Add TokenUsageMiddleware when token_usage tracking is enabled
if resolved_app_config.token_usage.enabled:
middlewares.append(TokenUsageMiddleware())
# Add TitleMiddleware — but skip it for scheduled runs. Each scheduled run
# executes on a throwaway thread whose title is never shown to a user, and
# generating one would fire an extra LLM call on the *default* model
# (config.title.model_name is usually unset → models[0]), which is not the
# model the task selected. Skipping it keeps scheduled/HTML runs on exactly
# the chosen model.
if not cfg.get("is_scheduled_run", False):
middlewares.append(TitleMiddleware(app_config=resolved_app_config))
# Ephemeral runs (e.g. the open Q&A API /api/open/chat) must NOT touch any
# server-side per-user state: no memory recall/retain, no knowledge-base
# recall/auto-ingest. Those runs use the shared "default" user bucket, so
# persisting their conversations there would both store records the caller
# explicitly asked NOT to keep and leak content across unrelated callers.
# Skip both write-capable middlewares entirely.
is_ephemeral = cfg.get("ephemeral", False)
# Add MemoryMiddleware (after TitleMiddleware) — skip in bootstrap mode (agent creation flow) and ephemeral runs
memory_injection_enabled = cfg.get("memory_injection_enabled", True)
if not is_bootstrap and not is_writing_setup and not is_report_structure_setup and not is_ephemeral:
middlewares.append(MemoryMiddleware(agent_name=agent_name, memory_config=resolved_app_config.memory, injection_enabled=memory_injection_enabled))
# KnowledgeRagMiddleware — inject knowledge-base recall (phase 2). Gated
# per-conversation by the ``knowledge_rag_enabled`` runtime flag, defaulting
# to the global ``knowledge.rag_enabled`` config. No-op when knowledge is
# disabled. Skipped in bootstrap/writing-setup/ephemeral like MemoryMiddleware.
knowledge_cfg = getattr(resolved_app_config, "knowledge", None)
if not is_bootstrap and not is_writing_setup and not is_report_structure_setup and not is_ephemeral and knowledge_cfg is not None and knowledge_cfg.enabled:
from deerflow.agents.middlewares.knowledge_rag_middleware import KnowledgeRagMiddleware
middlewares.append(KnowledgeRagMiddleware(limit=knowledge_cfg.rag_limit, default_enabled=knowledge_cfg.rag_enabled))
# TaskExternalContextMiddleware — inject hidden per-run business context
# (for example rwfx's completed 3q report) into the model request only.
middlewares.append(TaskExternalContextMiddleware())
# Add ViewImageMiddleware only for the NATIVE-vision path (main model
# ingests raw image data). In delegated mode the view_image tool already
# returns a text description and stores nothing in `viewed_images`, so the
# middleware would otherwise inject a spurious "No images have been viewed."
# message. Use the resolved runtime model_name to avoid stale config values.
from deerflow.models.vision import is_delegated_vision, vision_enabled
if vision_enabled(model_name, app_config=resolved_app_config) and not is_delegated_vision(app_config=resolved_app_config):
middlewares.append(ViewImageMiddleware())
# Add DeferredToolFilterMiddleware to hide deferred tool schemas from model binding
if resolved_app_config.tool_search.enabled:
from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
middlewares.append(DeferredToolFilterMiddleware())
# Add SubagentLimitMiddleware to truncate excess parallel task calls
subagent_enabled = cfg.get("subagent_enabled", False)
if subagent_enabled:
max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))
# SkillReviewMiddleware — trigger background skill review after each turn.
# Gated by skill_evolution.enabled + skill_evolution.review_worker.enabled.
if resolved_app_config.skill_evolution.enabled and resolved_app_config.skill_evolution.review_worker.enabled:
from deerflow.agents.middlewares.skill_review_middleware import SkillReviewMiddleware
middlewares.append(SkillReviewMiddleware())
# 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())
# 写作模式首轮:允许先聊/检索;只有模型开始写 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())
# Inject custom middlewares before ClarificationMiddleware
if custom_middlewares:
middlewares.extend(custom_middlewares)
middlewares.append(SetupAgentApprovalMiddleware())
middlewares.append(SetupWritingApprovalMiddleware())
middlewares.append(SetupReportStructureApprovalMiddleware())
# SkillStopMiddleware — intercepts skill invocations and halts execution
# when a configured skill is about to run. Request-level options
# (skill_stop_names / skill_stop_message) take precedence; static
# config in ``app_config.skill_stop`` is the fallback.
skill_stop_names = cfg.get("skill_stop_names")
skill_stop_message = cfg.get("skill_stop_message")
if skill_stop_names:
from deerflow.agents.middlewares.skill_stop_middleware import SkillStopMiddleware
middlewares.append(
SkillStopMiddleware(
skill_names=skill_stop_names,
skills_root=resolved_app_config.skills.container_path or "/mnt/skills",
stop_message=skill_stop_message,
stop_on_match=True,
)
)
logger.info("SkillStopMiddleware enabled (from request): %s", skill_stop_names)
elif resolved_app_config.skill_stop.enabled and resolved_app_config.skill_stop.skill_names:
from deerflow.agents.middlewares.skill_stop_middleware import SkillStopMiddleware
middlewares.append(
SkillStopMiddleware(
skill_names=resolved_app_config.skill_stop.skill_names,
skills_root=resolved_app_config.skills.container_path or "/mnt/skills",
stop_message=resolved_app_config.skill_stop.stop_message,
stop_on_match=resolved_app_config.skill_stop.stop_on_match,
)
)
logger.info("SkillStopMiddleware enabled (from config): %s", resolved_app_config.skill_stop.skill_names)
# ClarificationMiddleware should always be last
middlewares.append(ClarificationMiddleware())
return middlewares
def make_lead_agent(config: RunnableConfig):
"""LangGraph graph factory; keep the signature compatible with LangGraph Server."""
runtime_config = _get_runtime_config(config)
runtime_app_config = runtime_config.get("app_config")
return _make_lead_agent(config, app_config=runtime_app_config or get_app_config())
def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
# Lazy import to avoid circular dependency
from deerflow.tools import get_available_tools
from deerflow.tools.builtins import ask_clarification_tool, setup_agent, setup_report_structure, setup_writing
cfg = _get_runtime_config(config)
resolved_app_config = app_config
thinking_enabled = cfg.get("thinking_enabled", True)
# Hard "thinking off" switch for internal vLLM/Qwen models whose config only
# declares `supports_thinking: true` (no disable shape) — passes through to
# create_chat_model(force_disable_thinking=...) so enable_thinking=false is
# actually injected. Default off → no behavior change for normal chats.
thinking_force_disabled = bool(cfg.get("thinking_force_disabled", False))
reasoning_effort = cfg.get("reasoning_effort", None)
requested_model_name: str | None = cfg.get("model_name") or cfg.get("model")
is_plan_mode = cfg.get("is_plan_mode", False)
disable_tools = bool(cfg.get("disable_tools", False))
subagent_enabled = cfg.get("subagent_enabled", False)
max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
is_bootstrap = cfg.get("is_bootstrap", False)
# 写作配置 Q&A:与 is_bootstrap 同构的另一种「最小化 bootstrap」——挂 setup_writing 工具、
# 走写作配置专用 prompt,只负责帮用户把写作表单聊清并提交,不真正开始写作。
is_writing_setup = cfg.get("is_writing_setup", False)
writing_setup_article_types = cfg.get("valid_article_types") if is_writing_setup else None
# 快捷模式:跳过逐项选项澄清,给标题直接出大纲(见 build_writing_setup_prompt)。
writing_setup_quick = bool(cfg.get("writing_setup_quick", False)) if is_writing_setup else False
writing_sample_context = cfg.get("writing_sample_context") if is_writing_setup else None
# 报告结构智能新增:与 is_writing_setup 同构的最小化 bootstrap。
is_report_structure_setup = cfg.get("is_report_structure_setup", False)
report_structure_setup_skills = cfg.get("valid_retrieval_skills") if is_report_structure_setup else None
report_structure_setup_quick = bool(cfg.get("writing_setup_quick", False)) if is_report_structure_setup else False
memory_injection_enabled = bool(cfg.get("memory_injection_enabled", True))
rag_mode_enabled = bool(cfg.get("rag_mode_enabled", False))
writing_mode = bool(cfg.get("writing_mode", False))
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 = _enforce_coordinator_only_tool_exclusions(
agent_id,
cfg.get("excluded_tools") or None,
)
try:
agent_config = load_agent_config(agent_id) if not is_bootstrap and not is_writing_setup and not is_report_structure_setup else None
except FileNotFoundError:
logger.warning("Agent directory not found for '%s'; running with default config", agent_id)
agent_config = None
agent_display_name = agent_config.name if agent_config else agent_id
# Custom agent model from agent config (if any), or None to let _resolve_model_name pick the default
agent_model_name = agent_config.model if agent_config and agent_config.model else None
# Final model name resolution: request → agent config → global default, with fallback for unknown names
model_name = _resolve_model_name(requested_model_name or agent_model_name, app_config=resolved_app_config)
model_config = resolved_app_config.get_model_config(model_name)
if model_config is None:
raise ValueError("No chat model could be resolved. Please configure at least one model in config.yaml or provide a valid 'model_name'/'model' in the request.")
if thinking_enabled and not model_config.supports_thinking:
logger.warning(f"Thinking mode is enabled but model '{model_name}' does not support it; fallback to non-thinking mode.")
thinking_enabled = False
logger.info(
"Create Agent(%s) -> thinking_enabled: %s, reasoning_effort: %s, model_name: %s, is_plan_mode: %s, subagent_enabled: %s, max_concurrent_subagents: %s, writing_mode: %s",
agent_id or "default",
thinking_enabled,
reasoning_effort,
model_name,
is_plan_mode,
subagent_enabled,
max_concurrent_subagents,
writing_mode,
)
# Inject run metadata for LangSmith trace tagging
if "metadata" not in config:
config["metadata"] = {}
if is_bootstrap:
runtime_available_skills: list[str] | None = None # all enabled skills visible in bootstrap
elif agent_config:
# Custom agents must use an explicit allowlist. If omitted, default to none.
runtime_available_skills = list(agent_config.skills or [])
else:
# Default lead agent keeps existing behavior (all enabled skills).
runtime_available_skills = None
from deerflow.agents.deep_research.retrieval import merge_collector_skill_allowlist, runtime_extra_skills
runtime_available_skills = merge_collector_skill_allowlist(
agent_id, runtime_available_skills, runtime_extra_skills(cfg)
)
runtime_available_skills = _filter_available_skills_for_excluded_tools(
runtime_available_skills,
requested_excluded_tools,
)
prompt_available_skills = set(runtime_available_skills) if runtime_available_skills is not None else None
config["metadata"].update(
{
"agent_id": agent_id,
"agent_name": agent_display_name or "default",
"model_name": model_name or "default",
"thinking_enabled": thinking_enabled,
"reasoning_effort": reasoning_effort,
"is_plan_mode": is_plan_mode,
"subagent_enabled": subagent_enabled,
"writing_mode": writing_mode,
"writing_artifact_path": writing_artifact_path,
"tool_groups": agent_config.tool_groups if agent_config else None,
"available_skills": runtime_available_skills,
}
)
if is_writing_setup:
# 写作配置 Q&A:最小化 agent —— 只挂 setup_writing(提交配置)+ ask_clarification(弹澄清卡)。
# 关键:绝不给全套工具、绝不复用 lead 超级体提示,否则模型会把「新能源汽车市场分析」之类
# 长得像任务的输入直接做掉,而不是转成写作配置提交。
# 末尾追加 WritingSetupRoundCapMiddleware:澄清最多 3 轮,到顶用 tool_choice 强制提交配置卡。
# 快捷模式:用默认选项、不逐项澄清提问(但仍生成并确认大纲)——直接**不挂** ask_clarification,
# 让模型物理上问不了澄清问题,比只靠提示词约束更可靠。
from deerflow.agents.lead_agent.prompt import build_writing_setup_prompt
from deerflow.agents.middlewares.writing_setup_round_cap_middleware import WritingSetupRoundCapMiddleware
setup_tools = [setup_writing] if writing_setup_quick else [setup_writing, ask_clarification_tool]
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, force_disable_thinking=thinking_force_disabled, app_config=resolved_app_config),
tools=setup_tools,
middleware=[
*_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
WritingSetupRoundCapMiddleware(max_rounds=WRITING_SETUP_MAX_ROUNDS),
],
system_prompt=build_writing_setup_prompt(
writing_setup_article_types,
quick_mode=writing_setup_quick,
sample_context=writing_sample_context,
),
state_schema=ThreadState,
)
if is_report_structure_setup:
from deerflow.agents.lead_agent.prompt import build_report_structure_setup_prompt
from deerflow.agents.middlewares.writing_setup_round_cap_middleware import WritingSetupRoundCapMiddleware
setup_tools = (
[setup_report_structure]
if report_structure_setup_quick
else [setup_report_structure, ask_clarification_tool]
)
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, force_disable_thinking=thinking_force_disabled, app_config=resolved_app_config),
tools=setup_tools,
middleware=[
*_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
WritingSetupRoundCapMiddleware(
max_rounds=REPORT_STRUCTURE_SETUP_MAX_ROUNDS,
tool_name="setup_report_structure",
force_instruction=(
f"【系统强制】意图澄清已达 {REPORT_STRUCTURE_SETUP_MAX_ROUNDS} 轮上限。"
"现在必须立即调用 setup_report_structure 提交报告结构配置,禁止再向用户提任何问题。"
"缺失或不确定的字段一律用合理默认值:"
"title 根据对话主题拟一个短标题、name 用一句话描述、structure_mode 默认 adaptive、"
"retrieval_directions / retrieval_skills 不确定就留空、content 必须给出一份 Markdown 大纲。"
),
),
],
system_prompt=build_report_structure_setup_prompt(
report_structure_setup_skills,
quick_mode=report_structure_setup_quick,
),
state_schema=ThreadState,
)
if is_bootstrap:
# Special bootstrap agent with minimal prompt for initial custom agent creation flow
return create_agent(
model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled, force_disable_thinking=thinking_force_disabled, app_config=resolved_app_config),
tools=get_available_tools(
model_name=model_name,
subagent_enabled=subagent_enabled,
is_scheduled_run=cfg.get("is_scheduled_run", False),
excluded_tools=requested_excluded_tools,
allow_agent_orchestration=agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID,
app_config=resolved_app_config,
)
+ [setup_agent],
middleware=_build_middlewares(config, model_name=model_name, app_config=resolved_app_config),
system_prompt=apply_prompt_template(
subagent_enabled=subagent_enabled,
max_concurrent_subagents=max_concurrent_subagents,
writing_mode=writing_mode,
writing_artifact_path=writing_artifact_path,
available_skills=None,
is_bootstrap=True,
app_config=resolved_app_config,
memory_injection_enabled=memory_injection_enabled,
rag_mode_enabled=rag_mode_enabled,
),
state_schema=ThreadState,
)
# 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 = (
[]
if disable_tools
else 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,
allow_agent_orchestration=agent_id == _ROUNDTABLE_COORDINATOR_AGENT_ID,
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
# 写作模式首轮(尚无 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
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
# the agent-only prompt builder whenever a custom agent config carries a
# non-empty SOUL.md. The plain default lead agent (no agent_config) and
# notebook mode keep the full template. See apply_agent_only_prompt_template.
has_agent_soul = bool(agent_config) and bool(load_agent_soul(agent_id))
use_agent_only_prompt = has_agent_soul and not is_notebook_mode
if use_agent_only_prompt:
from deerflow.agents.lead_agent.prompt import apply_agent_only_prompt_template
system_prompt = apply_agent_only_prompt_template(
agent_id=agent_id,
agent_name=agent_display_name,
subagent_enabled=subagent_enabled,
max_concurrent_subagents=max_concurrent_subagents,
available_skills=prompt_available_skills,
app_config=resolved_app_config,
rag_mode_enabled=rag_mode_enabled,
writing_mode=writing_mode,
writing_artifact_path=writing_artifact_path,
)
else:
system_prompt = apply_prompt_template(
subagent_enabled=subagent_enabled,
max_concurrent_subagents=max_concurrent_subagents,
agent_id=agent_id,
agent_name=agent_display_name,
writing_mode=writing_mode,
writing_artifact_path=writing_artifact_path,
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)),
)
# 前端可提供当前视觉明暗模式给页面生成类任务。把值放入系统提示而不是
# 指望模型从 ToolRuntime.context 猜测,确保自定义 SOUL 也能稳定使用。
presentation_theme = str(cfg.get("presentation_theme") or "").strip().lower()
if presentation_theme in {"dark", "light"}:
system_prompt += (
"\n\n【当前界面主题】\n"
f"当前页面呈现主题为 `{presentation_theme}`。若本轮生成汇报页面,请优先选择同色系 HTML 模板;"
"除非用户明确要求覆盖该主题。"
)
system_prompt = _append_orchestration_capability_boundary(system_prompt, agent_id)
_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),
system_prompt=system_prompt,
state_schema=ThreadState,
)
@@ -0,0 +1,37 @@
"""DeerFlow 记忆模块 (Memory V2)。
架构 (详见 docs/MEMORY_V2_DESIGN_ZH.md):
- :class:`MemoryProvider` 可插拔记忆 provider 抽象基类
- :class:`MemoryManager` 编排内建 + 至多 1 个外部 provider
- :func:`build_memory_manager` 按生效配置组装 manager 的统一入口
- :class:`BuiltinFileProvider` 本地 USER.md / MEMORY.md provider
- :class:`HindsightProvider` Hindsight HTTP 外部 provider
- :mod:`deerflow.agents.memory.security` 记忆内容安全扫描
记忆有两条自动写入路径:LLM 主动调 ``memory`` / ``hindsight_*`` 工具,
以及 Hindsight 的 auto-retain。注入走系统提示词 (builtin frozen snapshot)
与 ``MemoryMiddleware.wrap_model_call`` (Hindsight 动态召回)。
"""
from deerflow.agents.memory.manager import MemoryManager, build_memory_manager
from deerflow.agents.memory.message_processing import filter_messages_for_memory
from deerflow.agents.memory.provider import MemoryProvider
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
from deerflow.agents.memory.providers.hindsight import HindsightProvider
from deerflow.agents.memory.security import (
MemoryContentBlocked,
assert_memory_content_safe,
scan_memory_content,
)
__all__ = [
"MemoryProvider",
"MemoryManager",
"build_memory_manager",
"BuiltinFileProvider",
"HindsightProvider",
"MemoryContentBlocked",
"scan_memory_content",
"assert_memory_content_safe",
"filter_messages_for_memory",
]
@@ -0,0 +1,313 @@
"""Memory V2 - MemoryManager 编排层。
职责
====
编排 1 个内建 provider (``builtin``,始终存在) + 至多 1 个外部 provider
(P2 期的 ``hindsight``)。把系统提示词组装、召回、生命周期 hook 分发到各 provider。
任一 provider 出错都不会阻断其他 provider,也不会阻断对话。
典型用法 (由 MemoryMiddleware 每轮构建)
=======================================
::
manager = MemoryManager()
manager.add_provider(BuiltinFileProvider(...))
manager.add_provider(hindsight_provider) # 可选,至多 1 个
manager.initialize_all(user_id=..., agent_id=..., thread_id=..., base_dir=...)
block = manager.build_injection_block(query=user_msg, thread_id=tid)
# ... 把 block 注入系统提示词 ...
manager.sync_all(user_msg, assistant_msg, thread_id=tid)
"""
from __future__ import annotations
import logging
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
logger = logging.getLogger(__name__)
#: 内建 provider 的固定名字。
BUILTIN_PROVIDER_NAME = "builtin"
KNOWLEDGE_PROVIDER_NAME = "knowledge"
_INTERNAL_PROVIDER_NAMES = {BUILTIN_PROVIDER_NAME, KNOWLEDGE_PROVIDER_NAME}
class MemoryManager:
"""编排内建 provider + 至多 1 个外部 provider。"""
def __init__(self) -> None:
self._providers: list[MemoryProvider] = []
self._has_external: bool = False
# ---- 注册 ------------------------------------------------------------
def add_provider(self, provider: MemoryProvider) -> bool:
"""注册一个 provider。
内建 provider (``name == "builtin"``) 始终接受。外部 provider 至多 1 个,
第二个会被拒绝并 log 警告。返回是否注册成功。
"""
is_internal = provider.name in _INTERNAL_PROVIDER_NAMES
if not is_internal:
if self._has_external:
existing = next(
(p.name for p in self._providers if p.name not in _INTERNAL_PROVIDER_NAMES),
"unknown",
)
logger.warning(
"拒绝注册记忆 provider '%s' —— 已存在外部 provider '%s'。"
"同一时间只允许 1 个外部 provider,请用 config.memory.provider 选择。",
provider.name,
existing,
)
return False
self._has_external = True
self._providers.append(provider)
logger.info("记忆 provider '%s' 已注册", provider.name)
return True
@property
def providers(self) -> list[MemoryProvider]:
"""按注册顺序返回所有 provider。"""
return list(self._providers)
def get_provider(self, name: str) -> MemoryProvider | None:
"""按名字取 provider,不存在返回 ``None``。"""
for p in self._providers:
if p.name == name:
return p
return None
# ---- 生命周期 ---------------------------------------------------------
def initialize_all(self, **kwargs: Any) -> None:
"""初始化所有 provider。单个 provider 失败不影响其他。"""
for provider in self._providers:
try:
provider.initialize(**kwargs)
except Exception as exc: # noqa: BLE001 - provider 失败必须隔离
logger.warning("记忆 provider '%s' initialize 失败:%s", provider.name, exc)
def shutdown_all(self) -> None:
"""关闭所有 provider (逆序,保证干净拆除)。"""
for provider in reversed(self._providers):
try:
provider.shutdown()
except Exception as exc: # noqa: BLE001
logger.warning("记忆 provider '%s' shutdown 失败:%s", provider.name, exc)
# ---- 系统提示词组装 / 召回 -------------------------------------------
def build_system_prompt(self) -> str:
"""收集所有 provider 的静态系统提示词块。"""
blocks: list[str] = []
for provider in self._providers:
try:
block = provider.system_prompt_block()
except Exception as exc: # noqa: BLE001
logger.warning("记忆 provider '%s' system_prompt_block 失败:%s", provider.name, exc)
continue
if block and block.strip():
blocks.append(block)
return "\n\n".join(blocks)
def prefetch_all(self, query: str, *, thread_id: str = "") -> str:
"""收集所有 provider 的召回上下文。单个失败不阻断其他。"""
parts: list[str] = []
for provider in self._providers:
try:
result = provider.prefetch(query, thread_id=thread_id)
except Exception as exc: # noqa: BLE001
logger.debug("记忆 provider '%s' prefetch 失败 (非致命):%s", provider.name, exc)
continue
if result and result.strip():
parts.append(result)
return "\n\n".join(parts)
def build_injection_block(self, query: str, *, thread_id: str = "") -> str:
"""组装注入系统提示词的完整记忆块。
= 所有 provider 的静态块 (frozen snapshot 等) + 动态召回块。
返回空串表示无内容可注入。
"""
static_part = self.build_system_prompt()
dynamic_part = self.prefetch_all(query, thread_id=thread_id)
parts = [p for p in (static_part, dynamic_part) if p and p.strip()]
return "\n\n".join(parts)
def queue_prefetch_all(self, query: str, *, thread_id: str = "") -> None:
"""通知所有 provider 后台预热下一轮召回。"""
for provider in self._providers:
try:
provider.queue_prefetch(query, thread_id=thread_id)
except Exception as exc: # noqa: BLE001
logger.debug("记忆 provider '%s' queue_prefetch 失败:%s", provider.name, exc)
# ---- 写入 ------------------------------------------------------------
def sync_all(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""把一轮完成的对话同步到所有 provider。
``turn_index`` 是当前对话的轮次序号,透传给各 provider 用于轮次节流。
"""
for provider in self._providers:
try:
provider.sync_turn(
user_content,
assistant_content,
thread_id=thread_id,
turn_index=turn_index,
)
except Exception as exc: # noqa: BLE001
logger.warning("记忆 provider '%s' sync_turn 失败:%s", provider.name, exc)
def on_memory_write(
self,
action: str,
target: str,
content: str,
metadata: dict[str, Any] | None = None,
) -> None:
"""builtin 写入后,通知外部 provider 镜像。
跳过 builtin 自身 (它就是写入源,镜像回去没有意义)。
"""
for provider in self._providers:
if provider.name == BUILTIN_PROVIDER_NAME:
continue
try:
provider.on_memory_write(action, target, content, metadata)
except Exception as exc: # noqa: BLE001
logger.debug("记忆 provider '%s' on_memory_write 失败:%s", provider.name, exc)
# ---- 可选 hooks ------------------------------------------------------
def on_session_switch_all(
self,
new_thread_id: str,
*,
parent_thread_id: str = "",
reset: bool = False,
**kwargs: Any,
) -> None:
"""通知所有 provider thread_id 已切换。"""
if not new_thread_id:
return
for provider in self._providers:
try:
provider.on_session_switch(
new_thread_id,
parent_thread_id=parent_thread_id,
reset=reset,
**kwargs,
)
except Exception as exc: # noqa: BLE001
logger.debug("记忆 provider '%s' on_session_switch 失败:%s", provider.name, exc)
def build_memory_manager(
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
config: Any = None,
app_config: Any = None,
) -> MemoryManager:
"""按生效配置组装并初始化一个 MemoryManager。
这是构建 manager 的统一入口 —— 根据 ``config.version`` 选择 V1 或 V2 provider:
- ``version="v1"``: 仅注册 V1BuiltinProvider (memory.json + LLM 自动提取)
- ``version="v2"``: 注册 BuiltinFileProvider + 可选 HindsightProvider (USER.md/MEMORY.md)
所有 provider 已 ``initialize`` 完毕,可直接使用。
Parameters
----------
user_id / agent_id / thread_id:
请求上下文标识。
config:
生效的 :class:`MemoryConfig`;为 ``None`` 时按 ``user_id`` 解析 per-user 配置。
"""
from deerflow.config.memory_config import get_effective_memory_config
from deerflow.config.paths import get_paths
if config is None:
config = get_effective_memory_config(user_id)
manager = MemoryManager()
base_dir = str(get_paths().base_dir)
memory_enabled = bool(getattr(config, "enabled", True) and getattr(config.injection, "enabled", True))
if memory_enabled and getattr(config, "version", "v2") == "v1":
# V1 模式:原版 DeerFlow memory.json + LLM 自动提取
from deerflow.agents.memory.providers.v1_builtin import V1BuiltinProvider
v1_cfg = config.v1
manager.add_provider(
V1BuiltinProvider(
max_facts=v1_cfg.max_facts,
fact_confidence_threshold=v1_cfg.fact_confidence_threshold,
debounce_seconds=v1_cfg.debounce_seconds,
model_name=v1_cfg.model_name,
token_budget=v1_cfg.token_budget,
)
)
elif memory_enabled:
# V2 模式:USER.md / MEMORY.md + 可选 Hindsight
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
if config.builtin.enabled:
manager.add_provider(
BuiltinFileProvider(
memory_char_limit=config.builtin.memory_char_limit,
user_char_limit=config.builtin.user_char_limit,
deduplicate_on_load=config.builtin.deduplicate_on_load,
security=config.security,
)
)
if config.provider == "hindsight":
try:
from deerflow.agents.memory.providers.hindsight import HindsightProvider
hindsight = HindsightProvider(config.hindsight)
if hindsight.is_available():
manager.add_provider(hindsight)
else:
logger.info("Hindsight provider 已配置但不可用 (包未装或缺 api_url),退回纯 builtin")
except Exception as exc: # noqa: BLE001 - Hindsight 接入失败不能阻断记忆系统
logger.warning("加载 Hindsight provider 失败,退回纯 builtin:%s", exc)
try:
from deerflow.agents.memory.providers.knowledge import KnowledgeProvider
knowledge = KnowledgeProvider(app_config=app_config)
if knowledge.is_available():
manager.add_provider(knowledge)
except Exception as exc: # noqa: BLE001 - 知识库路由失败不能阻断对话
logger.warning("加载 Knowledge provider 失败:%s", exc)
manager.initialize_all(
user_id=user_id,
agent_id=agent_id,
thread_id=thread_id,
base_dir=base_dir,
app_config=app_config,
)
return manager
__all__ = ["MemoryManager", "BUILTIN_PROVIDER_NAME", "build_memory_manager"]
@@ -0,0 +1,110 @@
"""把对话整理成记忆写入所需输入的共享辅助函数。
Memory V2 说明:后台抽取已舍弃,这里只保留 ``filter_messages_for_memory``
(供 MemoryMiddleware 取出最后一轮对话用于 Hindsight retain)。
"""
from __future__ import annotations
import re
from copy import copy
from typing import Any
_UPLOAD_BLOCK_RE = re.compile(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", re.IGNORECASE)
def extract_message_text(message: Any) -> str:
"""Extract plain text from message content for filtering and signal detection."""
content = getattr(message, "content", "")
if isinstance(content, list):
text_parts: list[str] = []
for part in content:
if isinstance(part, str):
text_parts.append(part)
elif isinstance(part, dict):
text_val = part.get("text")
if isinstance(text_val, str):
text_parts.append(text_val)
return " ".join(text_parts)
return str(content)
def count_user_turns(filtered_messages: list[Any]) -> int:
"""统计已过滤消息里的用户轮次数 (= human 消息条数)。
供 MemoryMiddleware 算出当前轮次序号传给 provider 做轮次节流 ——
provider 每轮被重建、无法靠自身计数,必须由这里按对话历史推算。
入参应是 :func:`filter_messages_for_memory` 的输出。
"""
return sum(1 for msg in filtered_messages if getattr(msg, "type", None) == "human")
def filter_messages_for_memory(messages: list[Any]) -> list[Any]:
"""Keep only user inputs and final assistant responses for memory updates."""
filtered = []
skip_next_ai = False
for msg in messages:
msg_type = getattr(msg, "type", None)
if msg_type == "human":
content_str = extract_message_text(msg)
if "<uploaded_files>" in content_str:
stripped = _UPLOAD_BLOCK_RE.sub("", content_str).strip()
if not stripped:
skip_next_ai = True
continue
clean_msg = copy(msg)
clean_msg.content = stripped
filtered.append(clean_msg)
skip_next_ai = False
else:
filtered.append(msg)
skip_next_ai = False
elif msg_type == "ai":
tool_calls = getattr(msg, "tool_calls", None)
if not tool_calls:
if skip_next_ai:
skip_next_ai = False
continue
filtered.append(msg)
return filtered
_CORRECTION_PATTERNS = re.compile(
r"\b(?:no[,.]?\s+(?:that'?s?\s+)?(?:wrong|incorrect|not\s+right|not\s+what)|"
r"actually[,.]?\s+(?:it\s+(?:is|should)|you\s+(?:should|need|must)|the\s+correct)|"
r"that'?s?\s+(?:wrong|incorrect|not\s+right|not\s+what\s+i)|"
r"you\s+(?:got\s+it\s+wrong|misunderstood|made\s+an?\s+error|made\s+a\s+mistake)|"
r"incorrect[,.]|wrong[,.]|mistake[,.]|correction:|that\s+is\s+not\s+right)\b",
re.IGNORECASE,
)
_REINFORCEMENT_PATTERNS = re.compile(
r"\b(?:perfect[,.]?|exactly[,.]?|correct[,.]?|that'?s?\s+(?:right|correct|perfect|exactly\s+right)|"
r"you\s+(?:got\s+it|nailed\s+it)|great\s+(?:job|work)|well\s+done|"
r"yes[,.]?\s+(?:that'?s?\s+(?:right|correct|exactly)|exactly)|"
r"keep\s+(?:it\s+up|doing\s+that|going)|"
r"(?:that'?s?\s+|this\s+is\s+)?(?:exactly|precisely)\s+(?:what\s+i|right))\b",
re.IGNORECASE,
)
def detect_correction(messages: list[Any]) -> bool:
"""Detect if the conversation contains explicit user correction signals."""
for msg in messages:
if getattr(msg, "type", None) == "human":
text = extract_message_text(msg)
if _CORRECTION_PATTERNS.search(text):
return True
return False
def detect_reinforcement(messages: list[Any]) -> bool:
"""Detect if the conversation contains positive reinforcement signals."""
for msg in messages:
if getattr(msg, "type", None) == "human":
text = extract_message_text(msg)
if _REINFORCEMENT_PATTERNS.search(text):
return True
return False
@@ -0,0 +1,205 @@
"""Memory V2 - 记忆 Provider 抽象基类。
设计动机
========
Hermes Agent 的可插拔记忆系统的 deerflow 版本。所有具体的记忆后端
(builtin 本地文件、Hindsight HTTP 等)都实现这个接口,由 ``MemoryManager``
统一编排。Provider 之间互不感知,可自由组合 (内建 + 至多 1 个外部 plugin)。
生命周期
========
:func:`MemoryProvider.initialize` 初始化 (创建 bank、加载本地文件、建立连接)
:func:`MemoryProvider.system_prompt_block` 注入系统提示词的静态说明文本
:func:`MemoryProvider.prefetch` 每轮对话前召回上下文
:func:`MemoryProvider.queue_prefetch` 下一轮的后台预热
:func:`MemoryProvider.sync_turn` 每轮对话后异步写入后端
:func:`MemoryProvider.get_tool_schemas` 暴露给 LLM 的工具 schema
:func:`MemoryProvider.handle_tool_call` 路由工具调用
:func:`MemoryProvider.shutdown` 清理 (flush 队列、关连接)
可选 hooks
==========
仅按 ``生产推荐档`` 移植两个 ——
- :func:`MemoryProvider.on_session_switch` thread_id 切换时 (branch/resume/reset/压缩后)
- :func:`MemoryProvider.on_memory_write` builtin 写入时,通知外部 provider 镜像
参见 ``docs/MEMORY_V2_DESIGN_ZH.md`` §4 的完整接口定义和 §16 的实施分期。
"""
from __future__ import annotations
import logging
from abc import ABC, abstractmethod
from typing import Any
logger = logging.getLogger(__name__)
class MemoryProvider(ABC):
"""所有记忆 provider 必须实现的接口。"""
# ---- 身份 ------------------------------------------------------------
@property
@abstractmethod
def name(self) -> str:
"""短标识,如 ``'builtin'`` / ``'hindsight'``。"""
# ---- 生命周期 ---------------------------------------------------------
@abstractmethod
def is_available(self) -> bool:
"""是否已配置并可用。
在 agent 启动时被调用,用于判断要不要激活该 provider。
实现里只检查配置和依赖,不发网络请求。
"""
@abstractmethod
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str,
**kwargs: Any,
) -> None:
"""初始化:打开连接、创建 bank、加载本地文件等。
kwargs 至少包含 ``user_id`` / ``base_dir``,其余字段视 provider 而定。
Provider 可以根据 ``agent_id is None`` 决定走全局还是 per-agent 路径。
Parameters
----------
user_id:
当前用户的隔离标识(无认证场景下为 ``"default"``)。
agent_id:
当前 agent 的稳定标识;``None`` 表示走全局/默认 agent。
thread_id:
当前对话的 thread id;某些 provider 用它做并发隔离或 bank 后缀。
base_dir:
``Paths.base_dir`` 字符串形式,避免每个 provider 重复解析路径。
"""
def shutdown(self) -> None:
"""清理:刷队列、关连接。默认 no-op。"""
# ---- 系统提示词块 -----------------------------------------------------
def system_prompt_block(self) -> str:
"""注入系统提示词的静态文本。
典型用途:USER.md / MEMORY.md 的 frozen snapshot,provider 状态说明等。
返回空串表示不贡献内容。
"""
return ""
# ---- 召回 / 写入 -----------------------------------------------------
def prefetch(self, query: str, *, thread_id: str = "") -> str:
"""对话前召回上下文。
在每次 LLM 调用前由 :class:`MemoryMiddleware` 触发。``query`` 通常
是用户最近一条消息。实现要快;真正的网络召回应该走后台线程,
这里直接返回缓存结果。
返回值:带格式的文本块,会被拼接到系统提示词末尾。空串表示无内容。
"""
return ""
def queue_prefetch(self, query: str, *, thread_id: str = "") -> None:
"""后台预热下一轮的召回。默认 no-op。"""
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""每轮对话结束后把对话持久化到后端。
实现应当非阻塞 —— 如果后端有延迟,排队到后台处理而不是直接调用。
默认 no-op。
``turn_index`` 是当前对话的轮次序号 (从 1 开始,由编排层按对话历史算出)。
provider 通常被每轮重新构造、无法靠自身计数,需要按轮次节流写入
(例如 "每 N 轮 retain 一次") 的实现应当用它而非进程内计数器。
缺省 ``None`` 表示调用方未提供。
"""
# ---- LLM 工具 --------------------------------------------------------
@abstractmethod
def get_tool_schemas(self) -> list[dict[str, Any]]:
"""暴露给 LLM 的工具 schema 列表。
每个 schema 遵循 OpenAI function calling 格式::
{"name": "...", "description": "...", "parameters": {...}}
空数组表示 context-only(只做自动 recall/retain,不让 LLM 看见工具)。
"""
def handle_tool_call(
self, tool_name: str, args: dict[str, Any], **kwargs: Any
) -> str:
"""处理一个工具调用,必须返回 JSON 字符串。
``MemoryManager`` 会确保只把本 provider ``get_tool_schemas`` 里
声明的工具名路由到这里。
"""
raise NotImplementedError(
f"Provider {self.name} does not handle tool {tool_name}"
)
# ---- 可选 hooks (生产推荐档移植) -------------------------------------
def on_session_switch(
self,
new_thread_id: str,
*,
parent_thread_id: str = "",
reset: bool = False,
**kwargs: Any,
) -> None:
"""thread_id 切换时触发。
deerflow 的 thread_id 在以下场景会变化:
- 用户新建/切换 thread (``reset=True``)
- LangGraph thread branch (``reset=False``,``parent_thread_id`` 为原 thread)
- SummarizationMiddleware 压缩后继续 (``reset=False``)
Provider 在 ``initialize`` 时如果缓存了 per-session 的状态
(``_session_turns`` 累积缓冲、bank 关联、查询缓存等),应当在
这里刷新。默认 no-op。
"""
def on_memory_write(
self,
action: str,
target: str,
content: str,
metadata: dict[str, Any] | None = None,
) -> None:
"""builtin 写入时触发,通知外部 provider 镜像同一条记忆。
Parameters
----------
action:
``'add'`` / ``'replace'`` / ``'remove'``。
target:
``'user'`` / ``'memory'``,决定走全局 user bank 还是 agent 工作 bank。
content:
条目内容。``remove`` 时为待删除条目的内容(供 external 做幂等)。
metadata:
写入来源元数据 (``user_id`` / ``agent_id`` / ``thread_id`` / ``tool_name``)。
默认 no-op —— 只有需要镜像 builtin 写入的外部 provider (例如 Hindsight)
才需要重写。``MemoryManager`` 调度时会跳过 builtin 自身,避免无意义的回环。
"""
__all__ = ["MemoryProvider"]
@@ -0,0 +1,10 @@
"""Memory V2 - 具体 provider 实现。
- :class:`~deerflow.agents.memory.providers.builtin.BuiltinFileProvider`
本地文件 provider (USER.md / MEMORY.md),始终启用。
- ``HindsightProvider`` — Hindsight HTTP 客户端,P2 期接入。
"""
from deerflow.agents.memory.providers.builtin import BuiltinFileProvider
__all__ = ["BuiltinFileProvider"]
@@ -0,0 +1,420 @@
"""Memory V2 - 本地文件 provider (USER.md / MEMORY.md)。
从 Hermes ``tools/memory_tool.py`` 的 ``MemoryStore`` 移植,适配 deerflow 的
per-user / per-agent 目录结构与 :class:`MemoryProvider` 接口。
两类存储
========
- ``USER.md`` 用户画像 —— LLM 主动写入的 ``target="user"`` 记忆,跨 agent 共享。
路径:``{base_dir}/users/{user_id}/USER.md``
- ``MEMORY.md`` agent 工作笔记 —— LLM 主动写入的 ``target="memory"`` 记忆,agent 隔离。
路径:``{base_dir}/users/{user_id}/agents/{agent_id}/MEMORY.md``
设计要点
========
- 条目以 ``\\n§\\n`` 分隔,支持多行;采用字符级配额 (与模型无关)。
- frozen snapshot:``initialize`` 时读盘一次并冻结为系统提示词块,会话内写入
直接落盘 (durable) 但不刷新快照 —— 保持系统提示词稳定,利于 prefix cache。
- 读-改-写经文件锁串行化;写入用临时文件 + 原子 rename,避免并发读到半截文件。
- 写入前经 :mod:`deerflow.agents.memory.security` 扫描注入/外渗。
"""
from __future__ import annotations
import logging
import os
import tempfile
import threading
from contextlib import contextmanager
from pathlib import Path
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
from deerflow.agents.memory.security import scan_memory_content
from deerflow.config.memory_config import SecurityConfig
from deerflow.config.paths import get_paths
from deerflow.runtime.user_context import DEFAULT_USER_ID
logger = logging.getLogger(__name__)
# 跨平台文件锁:Unix 用 fcntl,Windows 用 msvcrt。
_fcntl: Any = None
_msvcrt: Any = None
try: # pragma: no cover - 平台相关
import fcntl as _fcntl_mod
_fcntl = _fcntl_mod
except ImportError: # pragma: no cover - Windows
try:
import msvcrt as _msvcrt_mod
_msvcrt = _msvcrt_mod
except ImportError:
pass
#: 条目分隔符。``§`` = section sign (U+00A7)。
ENTRY_DELIMITER = "\n§\n"
#: target 取值。
_VALID_TARGETS = ("memory", "user")
# 同一进程内对同一文件路径的写入串行化锁 (文件锁之上再加一层,降低自争用)。
_PATH_LOCKS: dict[str, threading.Lock] = {}
_PATH_LOCKS_GUARD = threading.Lock()
def _get_path_lock(path: Path) -> threading.Lock:
"""返回某文件路径对应的进程内锁 (按路径字符串缓存)。"""
key = str(path)
with _PATH_LOCKS_GUARD:
lock = _PATH_LOCKS.get(key)
if lock is None:
lock = threading.Lock()
_PATH_LOCKS[key] = lock
return lock
@contextmanager
def _file_lock(path: Path):
"""获取某文件的排他锁,保证读-改-写安全。
用单独的 ``.lock`` 文件加锁,这样记忆文件本身仍可被 ``os.replace`` 原子替换。
进程内先抢 :func:`_get_path_lock`,再抢跨进程文件锁。
"""
process_lock = _get_path_lock(path)
process_lock.acquire()
lock_path = path.with_suffix(path.suffix + ".lock")
try:
lock_path.parent.mkdir(parents=True, exist_ok=True)
if _fcntl is None and _msvcrt is None: # pragma: no cover - 无锁平台
yield
return
if _msvcrt is not None and (not lock_path.exists() or lock_path.stat().st_size == 0):
lock_path.write_text(" ", encoding="utf-8")
fd = open(lock_path, "r+" if _msvcrt is not None else "a+")
try:
if _fcntl is not None:
_fcntl.flock(fd, _fcntl.LOCK_EX)
else: # pragma: no cover - Windows
fd.seek(0)
_msvcrt.locking(fd.fileno(), _msvcrt.LK_LOCK, 1)
yield
finally:
try:
if _fcntl is not None:
_fcntl.flock(fd, _fcntl.LOCK_UN)
elif _msvcrt is not None: # pragma: no cover - Windows
fd.seek(0)
_msvcrt.locking(fd.fileno(), _msvcrt.LK_UNLCK, 1)
except OSError:
pass
fd.close()
finally:
process_lock.release()
def _read_entries(path: Path) -> list[str]:
"""读取一个记忆文件并按分隔符切成条目列表。
无需加锁:写入用原子 rename,读者总能看到旧文件或新文件的完整内容。
"""
if not path.exists():
return []
try:
raw = path.read_text(encoding="utf-8")
except OSError:
return []
if not raw.strip():
return []
entries = [e.strip() for e in raw.split(ENTRY_DELIMITER)]
return [e for e in entries if e]
def _write_entries(path: Path, entries: list[str]) -> None:
"""用临时文件 + 原子 rename 写入记忆文件。"""
content = ENTRY_DELIMITER.join(entries) if entries else ""
path.parent.mkdir(parents=True, exist_ok=True)
fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp", prefix=".mem_")
try:
with os.fdopen(fd, "w", encoding="utf-8") as f:
f.write(content)
f.flush()
os.fsync(f.fileno())
os.replace(tmp_path, path)
except BaseException:
try:
os.unlink(tmp_path)
except OSError:
pass
raise
class BuiltinFileProvider(MemoryProvider):
"""本地文件记忆 provider,始终可用,不可移除。"""
def __init__(
self,
*,
memory_char_limit: int = 2200,
user_char_limit: int = 1375,
deduplicate_on_load: bool = True,
security: SecurityConfig | None = None,
) -> None:
self._memory_char_limit = memory_char_limit
self._user_char_limit = user_char_limit
self._deduplicate_on_load = deduplicate_on_load
self._security = security or SecurityConfig()
self._user_id: str = DEFAULT_USER_ID
self._agent_id: str = "default"
self._user_path: Path | None = None
self._memory_path: Path | None = None
# 实时状态 (工具写入后立即更新并落盘)
self._user_entries: list[str] = []
self._memory_entries: list[str] = []
# frozen snapshot (initialize 时冻结,系统提示词注入用)
self._snapshot: dict[str, str] = {"user": "", "memory": ""}
# ---- 身份 ------------------------------------------------------------
@property
def name(self) -> str:
return "builtin"
def is_available(self) -> bool:
"""本地文件 provider 无外部依赖,始终可用。"""
return True
# ---- 生命周期 ---------------------------------------------------------
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str = "",
**kwargs: Any,
) -> None:
"""解析 per-user / per-agent 路径,加载文件并冻结系统提示词快照。"""
self._user_id = user_id or DEFAULT_USER_ID
self._agent_id = (agent_id or "default").lower()
paths = get_paths()
self._user_path = paths.user_profile_md_file(self._user_id)
self._memory_path = paths.user_agent_memory_md_file(self._user_id, self._agent_id)
self._load_from_disk()
def _load_from_disk(self) -> None:
"""从磁盘加载两个文件,去重,并冻结系统提示词快照。"""
assert self._user_path is not None and self._memory_path is not None
self._user_entries = _read_entries(self._user_path)
self._memory_entries = _read_entries(self._memory_path)
if self._deduplicate_on_load:
self._user_entries = list(dict.fromkeys(self._user_entries))
self._memory_entries = list(dict.fromkeys(self._memory_entries))
self._snapshot = {
"user": self._render_block("user", self._user_entries),
"memory": self._render_block("memory", self._memory_entries),
}
# ---- 系统提示词块 -----------------------------------------------------
def system_prompt_block(self) -> str:
"""返回 frozen snapshot:USER PROFILE 块 + MEMORY 块。
返回 ``initialize`` 时冻结的内容,会话内的工具写入不影响它 ——
保持系统提示词稳定,利于 prefix cache。
"""
blocks = [b for b in (self._snapshot.get("user"), self._snapshot.get("memory")) if b]
content = "\n\n".join(blocks)
if not content:
return ""
return f"<memory>\n{content}\n</memory>"
def get_tool_schemas(self) -> list[dict[str, Any]]:
"""builtin 的 ``memory`` 工具以 LangChain BaseTool 形式独立注册,
不经 MemoryManager 路由,因此这里返回空列表。
"""
return []
# ---- 工具写入操作 (供 memory 工具直接调用) ---------------------------
def add(self, target: str, content: str) -> dict[str, Any]:
"""追加一条记忆条目。超出字符配额时返回错误。"""
content = (content or "").strip()
if not content:
return {"success": False, "error": "条目内容不能为空。"}
if (err := self._scan(content)) is not None:
return {"success": False, "error": err}
path = self._path_for(target)
with _file_lock(path):
entries = self._reload_target(target)
if content in entries:
return self._success(target, "条目已存在,未重复添加。")
limit = self._char_limit(target)
new_total = len(ENTRY_DELIMITER.join([*entries, content]))
if new_total > limit:
current = self._char_count(entries)
return {
"success": False,
"error": (
f"记忆已用 {current:,}/{limit:,} 字符,"
f"再加这条 ({len(content)} 字符) 会超出配额。"
"请先 replace 或 remove 现有条目。"
),
"entries": entries,
}
entries.append(content)
_write_entries(path, entries)
self._set_entries(target, entries)
return self._success(target, "条目已添加。")
def replace(self, target: str, old_text: str, new_content: str) -> dict[str, Any]:
"""用 ``old_text`` 短串定位条目,替换为 ``new_content``。"""
old_text = (old_text or "").strip()
new_content = (new_content or "").strip()
if not old_text:
return {"success": False, "error": "old_text 不能为空。"}
if not new_content:
return {"success": False, "error": "new_content 不能为空;删除条目请用 remove。"}
if (err := self._scan(new_content)) is not None:
return {"success": False, "error": err}
path = self._path_for(target)
with _file_lock(path):
entries = self._reload_target(target)
matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
if not matches:
return {"success": False, "error": f"没有条目匹配 '{old_text}'。"}
if len({e for _, e in matches}) > 1:
previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
return {
"success": False,
"error": f"多个条目匹配 '{old_text}',请用更精确的 old_text。",
"matches": previews,
}
idx = matches[0][0]
limit = self._char_limit(target)
test_entries = list(entries)
test_entries[idx] = new_content
new_total = len(ENTRY_DELIMITER.join(test_entries))
if new_total > limit:
return {
"success": False,
"error": (
f"替换后会达到 {new_total:,}/{limit:,} 字符,超出配额。"
"请缩短新内容或先删除其他条目。"
),
}
entries[idx] = new_content
_write_entries(path, entries)
self._set_entries(target, entries)
return self._success(target, "条目已替换。")
def remove(self, target: str, old_text: str) -> dict[str, Any]:
"""用 ``old_text`` 短串定位并删除条目。"""
old_text = (old_text or "").strip()
if not old_text:
return {"success": False, "error": "old_text 不能为空。"}
path = self._path_for(target)
with _file_lock(path):
entries = self._reload_target(target)
matches = [(i, e) for i, e in enumerate(entries) if old_text in e]
if not matches:
return {"success": False, "error": f"没有条目匹配 '{old_text}'。"}
if len({e for _, e in matches}) > 1:
previews = [e[:80] + ("..." if len(e) > 80 else "") for _, e in matches]
return {
"success": False,
"error": f"多个条目匹配 '{old_text}',请用更精确的 old_text。",
"matches": previews,
}
entries.pop(matches[0][0])
_write_entries(path, entries)
self._set_entries(target, entries)
return self._success(target, "条目已删除。")
def read(self, target: str) -> list[str]:
"""返回某 target 的实时条目列表 (从磁盘重读)。"""
return self._reload_target(target)
def usage(self, target: str) -> str:
"""返回某 target 的字符用量描述,如 ``'12% — 165/1375 字符'``。"""
entries = self._reload_target(target)
current = self._char_count(entries)
limit = self._char_limit(target)
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
return f"{pct}% — {current:,}/{limit:,} 字符"
# ---- 内部辅助 --------------------------------------------------------
def _scan(self, content: str) -> str | None:
return scan_memory_content(
content,
scan_threats=self._security.scan_content,
block_invisible_unicode=self._security.block_invisible_unicode,
)
def _path_for(self, target: str) -> Path:
if target not in _VALID_TARGETS:
raise ValueError(f"非法 target '{target}',只能是 'memory' 或 'user'。")
if self._user_path is None or self._memory_path is None:
raise RuntimeError("BuiltinFileProvider 未初始化,请先调用 initialize()。")
return self._user_path if target == "user" else self._memory_path
def _char_limit(self, target: str) -> int:
return self._user_char_limit if target == "user" else self._memory_char_limit
@staticmethod
def _char_count(entries: list[str]) -> int:
return len(ENTRY_DELIMITER.join(entries)) if entries else 0
def _reload_target(self, target: str) -> list[str]:
"""加锁状态下从磁盘重读条目 (拿到其他会话写入的最新状态)。"""
entries = _read_entries(self._path_for(target))
if self._deduplicate_on_load:
entries = list(dict.fromkeys(entries))
self._set_entries(target, entries)
return entries
def _set_entries(self, target: str, entries: list[str]) -> None:
if target == "user":
self._user_entries = entries
else:
self._memory_entries = entries
def _success(self, target: str, message: str) -> dict[str, Any]:
entries = self._user_entries if target == "user" else self._memory_entries
current = self._char_count(entries)
limit = self._char_limit(target)
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
return {
"success": True,
"target": target,
"entries": entries,
"entry_count": len(entries),
"usage": f"{pct}% — {current:,}/{limit:,} 字符",
"message": message,
}
def _render_block(self, target: str, entries: list[str]) -> str:
"""渲染一个系统提示词块 (带表头和用量指示)。"""
if not entries:
return ""
limit = self._char_limit(target)
content = ENTRY_DELIMITER.join(entries)
current = len(content)
pct = min(100, int(current / limit * 100)) if limit > 0 else 0
if target == "user":
header = f"用户画像 USER PROFILE [{pct}% — {current:,}/{limit:,} 字符]"
else:
header = f"记忆笔记 MEMORY [{pct}% — {current:,}/{limit:,} 字符]"
separator = "═" * 46
return f"{separator}\n{header}\n{separator}\n{content}"
__all__ = ["BuiltinFileProvider", "ENTRY_DELIMITER"]
@@ -0,0 +1,462 @@
"""Memory V2 - Hindsight 外部 provider。
Hindsight 是带知识图谱、实体消解、多策略检索的长期记忆服务。本 provider 以
HTTP 客户端方式接入一个用户自起的 Hindsight Docker 实例 (``local_external`` 模式)。
双 bank 隔离 (B 方案,详见 docs/MEMORY_V2_DESIGN_ZH.md §3)
==========================================================
- 全局 user bank ``bank_id_template`` 例:``deerflow-user-{user_id}``
存用户身份、偏好,跨 agent 共享。
- agent 工作 bank ``work_bank_id_template`` 例:``deerflow-work-{user_id}-{agent_id}``
存 agent 私有工作笔记。
写入路由:
- LLM 主动 ``memory(target="user")`` -> 镜像到 user bank
- LLM 主动 ``memory(target="memory")`` -> 镜像到 work bank
- 自动 retain 的对话 (``sync_turn``) -> work bank
召回:``prefetch`` 并发查两个 bank,合并结果。
document_id 与轮次计数
======================
本 provider 被 ``build_memory_manager`` 每轮重新构造 —— 是无状态的。因此:
- ``document_id`` 每次 ``initialize`` 用带时间戳的新值,每轮对话的 retain 落到
各自独立的 Hindsight 文档。
- ``retain_every_n_turns`` 的轮次判定依赖外部传入的 ``turn_index``
(由 ``MemoryMiddleware`` 按对话历史算出);未传时退回进程内 ``_turn_counter``。
客户端生命周期
==============
``_run_coro`` 每次操作新建一个事件循环。aiohttp ``ClientSession`` 是
loop-bound 的,跨 loop 复用会泄漏并失效。因此本 provider **不缓存客户端** ——
每次记忆操作在 :meth:`_run_with_client` 里即开即关,保证 session 在其所属的
loop 内被正常关闭。
降级
====
``hindsight-client`` 是可选依赖。未安装或未配置 ``api_url`` 时 :meth:`is_available`
返回 ``False``,provider 不会被注册,记忆系统退回纯 builtin —— 不影响任何功能。
"""
from __future__ import annotations
import asyncio
import logging
import threading
from datetime import UTC, datetime
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
from deerflow.config.memory_config import HindsightMemoryConfig
logger = logging.getLogger(__name__)
#: hindsight-client 最低版本。
MIN_CLIENT_VERSION = "0.4.22"
def hindsight_client_available() -> bool:
"""返回 ``hindsight-client`` 包是否已安装 (不导入实际客户端)。"""
import importlib.util
return importlib.util.find_spec("hindsight_client") is not None
def _run_coro(coro: Any, timeout: float) -> Any:
"""把一个 async coro 跑到完成并返回结果 (带超时)。
deerflow 的中间件钩子有同步也有异步路径;本 helper 两种场景都能用:
- 当前线程没有运行中的事件循环 -> 直接 ``asyncio.run``
- 当前线程已在事件循环里 -> 另起线程跑,避免嵌套循环报错
"""
try:
asyncio.get_running_loop()
in_loop = True
except RuntimeError:
in_loop = False
if not in_loop:
return asyncio.run(asyncio.wait_for(coro, timeout))
box: dict[str, Any] = {}
def _runner() -> None:
try:
box["value"] = asyncio.run(asyncio.wait_for(coro, timeout))
except BaseException as exc: # noqa: BLE001 - 跨线程传递异常
box["error"] = exc
thread = threading.Thread(target=_runner, name="hindsight-coro", daemon=True)
thread.start()
thread.join(timeout + 5)
if "error" in box:
raise box["error"]
if "value" not in box:
raise TimeoutError("Hindsight 操作超时")
return box["value"]
def _utc_now_iso() -> str:
return datetime.now(UTC).isoformat()
class HindsightProvider(MemoryProvider):
"""Hindsight 外部记忆 provider。"""
def __init__(self, config: HindsightMemoryConfig | None = None) -> None:
self._config = config or HindsightMemoryConfig()
self._user_id: str = ""
self._agent_id: str = "default"
self._thread_id: str = ""
self._user_bank: str = ""
self._work_bank: str = ""
# retain 批次的 document id 与轮次计数 (on_session_switch 会重置)
self._document_id: str = ""
self._turn_counter: int = 0
# ---- 身份 ------------------------------------------------------------
@property
def name(self) -> str:
return "hindsight"
def is_available(self) -> bool:
"""配置完整且 hindsight-client 已安装时才可用。"""
if not hindsight_client_available():
logger.debug("Hindsight 不可用:hindsight-client 未安装")
return False
if not self._config.api_url:
logger.debug("Hindsight 不可用:未配置 api_url")
return False
return True
# ---- 生命周期 ---------------------------------------------------------
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str = "",
**kwargs: Any,
) -> None:
"""解析双 bank 名称,准备 retain 批次状态。客户端每次操作即开即关。"""
self._user_id = user_id or "default"
self._agent_id = (agent_id or "default").lower()
self._thread_id = thread_id or ""
self._user_bank = self._resolve_bank(self._config.bank_id_template)
self._work_bank = self._resolve_bank(self._config.work_bank_id_template)
self._reset_retain_batch()
def _resolve_bank(self, template: str) -> str:
"""用 user_id / agent_id / thread_id 填充 bank 名称模板。
空占位符会塌缩 (例如 ``deerflow-{thread_id}`` 在无 thread 时变成 ``deerflow-``,
再清理多余连字符)。
"""
name = template.format(
user_id=self._user_id,
agent_id=self._agent_id,
thread_id=self._thread_id,
)
# 清理空占位符塌缩留下的多余连字符
while "--" in name:
name = name.replace("--", "-")
return name.strip("-") or "deerflow"
def _reset_retain_batch(self) -> None:
"""重置 retain 批次状态 (新的 document_id + 轮次清零)。
每次 ``initialize`` 用带时间戳的新 ``document_id`` —— 每轮对话的 retain
落到各自独立的 Hindsight 文档。轮次计数清零,仅作为 ``turn_index`` 缺失
时的退路。
"""
ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
self._document_id = f"{self._thread_id or 'thread'}-{ts}"
self._turn_counter = 0
def shutdown(self) -> None:
"""无需清理 —— 客户端在每次操作内即开即关,不缓存。"""
# ---- 客户端生命周期 --------------------------------------------------
def _client_factory(self) -> Any:
"""创建一个新的 Hindsight HTTP 客户端。
每次记忆操作都新建一个、用完即关,**不缓存** —— aiohttp ClientSession
是 loop-bound 的,而 ``_run_coro`` 每次新建事件循环。测试可覆盖本方法
注入 fake 客户端。
"""
from hindsight_client import Hindsight
kwargs: dict[str, Any] = {
"base_url": self._config.api_url,
"timeout": 30.0,
}
if self._config.api_key:
kwargs["api_key"] = self._config.api_key
return Hindsight(**kwargs)
@staticmethod
async def _aclose_client(client: Any) -> None:
"""关闭客户端 (兼容暴露 ``aclose`` 或 ``close`` 的实现)。"""
close = getattr(client, "aclose", None) or getattr(client, "close", None)
if close is None:
return
try:
result = close()
if asyncio.iscoroutine(result):
await result
except Exception as exc: # noqa: BLE001 - 关闭失败不影响结果
logger.debug("Hindsight 客户端关闭失败:%s", exc)
async def _run_with_client(self, op: Any) -> Any:
"""在当前事件循环内创建客户端、执行 ``op(client)``、保证关闭客户端。
``op`` 是一个接收 client、返回 awaitable 的协程函数。无论成功、异常还是
被取消 (超时),``finally`` 都会关闭客户端 —— 杜绝 ``Unclosed client session``。
"""
client = self._client_factory()
try:
return await op(client)
finally:
await self._aclose_client(client)
# ---- 系统提示词块 -----------------------------------------------------
def system_prompt_block(self) -> str:
"""返回一小段静态说明 (告诉 LLM Hindsight 处于哪种模式)。"""
mode = self._config.memory_mode
if mode == "context":
return "" # context 模式纯后台,无需告知 LLM
if mode == "tools":
return (
"# Hindsight 长期记忆\n"
"可用 hindsight_recall 检索、hindsight_reflect 综合、hindsight_retain 存储。"
)
return (
"# Hindsight 长期记忆\n"
"相关记忆会自动注入上下文;也可用 hindsight_recall / hindsight_reflect / "
"hindsight_retain 主动检索与存储。"
)
# ---- 召回 ------------------------------------------------------------
def prefetch(self, query: str, *, thread_id: str = "") -> str:
"""并发召回两个 bank 并合并结果。
``memory_mode='tools'`` 或 ``auto_recall=False`` 时不做自动召回。
召回失败 (Hindsight 不可达等) 返回空串,不抛异常。
"""
if self._config.memory_mode == "tools":
return ""
if not self._config.auto_recall:
return ""
query = (query or "").strip()
if not query:
return ""
if self._config.recall_max_input_chars and len(query) > self._config.recall_max_input_chars:
query = query[: self._config.recall_max_input_chars]
try:
merged = self._recall_both(query)
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
logger.debug("Hindsight 召回失败 (非致命):%s", exc)
return ""
if not merged:
return ""
lines = "\n".join(f"- {text}" for text in merged)
return (
"# Hindsight 记忆召回 (跨会话持久上下文)\n"
"下面是与当前对话相关的历史记忆,可据此回答关于用户和过往会话的问题。\n\n"
f"{lines}"
)
def _recall_both(self, query: str) -> list[str]:
"""并发召回 user + work 两个 bank,合并去重。一次操作共用一个客户端。"""
async def _op(client: Any) -> tuple[Any, Any]:
return await asyncio.gather(
client.arecall(
bank_id=self._user_bank,
query=query,
budget=self._config.recall_budget,
max_tokens=self._config.recall_max_tokens,
),
client.arecall(
bank_id=self._work_bank,
query=query,
budget=self._config.recall_budget,
max_tokens=self._config.recall_max_tokens,
),
)
user_resp, work_resp = _run_coro(self._run_with_client(_op), timeout=15)
return self._merge_results(
self._extract_results(user_resp),
self._extract_results(work_resp),
)
@staticmethod
def _extract_results(resp: Any) -> list[tuple[float, str]]:
"""从一个 recall 响应里抽出 ``[(score, text), ...]``。"""
results = getattr(resp, "results", None) or []
out: list[tuple[float, str]] = []
for r in results:
text = (getattr(r, "text", "") or "").strip()
if text:
out.append((float(getattr(r, "score", 0.0) or 0.0), text))
return out
@staticmethod
def _merge_results(
user_results: list[tuple[float, str]],
work_results: list[tuple[float, str]],
) -> list[str]:
"""合并双 bank 召回结果:按 score 倒序,去重保序。"""
combined = sorted(user_results + work_results, key=lambda x: -x[0])
seen: set[str] = set()
merged: list[str] = []
for _, text in combined:
if text not in seen:
seen.add(text)
merged.append(text)
return merged
# ---- 写入 ------------------------------------------------------------
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""自动 retain 一轮对话到 work bank。
``auto_retain=False`` 时不写。按 ``retain_every_n_turns`` 控制频率。
轮次判定优先用调用方传入的 ``turn_index`` (由 MemoryMiddleware 按对话历史
算出) —— 因为本 provider 每轮被重建、进程内 ``_turn_counter`` 会被重置,
单靠它在 ``retain_every_n_turns > 1`` 时会永远不触发。``turn_index`` 缺失
时才退回 ``_turn_counter``。
"""
if not self._config.auto_retain:
return
if turn_index is not None:
counter = turn_index
else:
self._turn_counter += 1
counter = self._turn_counter
every = max(1, self._config.retain_every_n_turns)
if counter % every != 0:
return
turn_text = (
f"{self._config.retain_user_prefix}: {user_content}\n"
f"{self._config.retain_assistant_prefix}: {assistant_content}"
)
try:
self._retain(self._work_bank, turn_text, kind="conversation")
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
logger.warning("Hindsight sync_turn 写入失败:%s", exc)
def on_memory_write(
self,
action: str,
target: str,
content: str,
metadata: dict[str, Any] | None = None,
) -> None:
"""builtin 写入时镜像到 Hindsight。
``target="user"`` -> user bank;``target="memory"`` -> work bank。
目前只镜像 ``add`` / ``replace`` 的新内容 (Hindsight 是 append-only 语义,
``remove`` 不反向删除)。
"""
if action not in ("add", "replace"):
return
content = (content or "").strip()
if not content:
return
bank = self._user_bank if target == "user" else self._work_bank
try:
self._retain(bank, content, kind=f"builtin_{target}")
except Exception as exc: # noqa: BLE001
logger.debug("Hindsight on_memory_write 镜像失败:%s", exc)
def _retain(self, bank_id: str, content: str, *, kind: str) -> None:
"""向某 bank 写入一条记忆。客户端即开即关。"""
metadata = {
"retained_at": _utc_now_iso(),
"kind": kind,
"user_id": self._user_id,
"agent_id": self._agent_id,
}
if self._thread_id:
metadata["thread_id"] = self._thread_id
async def _op(client: Any) -> Any:
return await client.aretain(
bank_id=bank_id,
content=content,
context=self._config.bank_retain_mission or None,
metadata=metadata,
document_id=self._document_id,
retain_async=self._config.retain_async,
)
_run_coro(self._run_with_client(_op), timeout=15)
def reflect(self, query: str, *, use_user_bank: bool = True) -> str:
"""对某 bank 做跨记忆综合 (LLM 推理)。供 hindsight_reflect 工具调用。"""
bank = self._user_bank if use_user_bank else self._work_bank
async def _op(client: Any) -> Any:
return await client.areflect(
bank_id=bank,
query=query,
budget=self._config.recall_budget,
)
resp = _run_coro(self._run_with_client(_op), timeout=30)
return getattr(resp, "text", "") or ""
def recall(self, query: str) -> list[str]:
"""召回双 bank 并返回文本列表。供 hindsight_recall 工具调用。"""
return self._recall_both(query)
def retain_to_user_bank(self, content: str) -> None:
"""主动写入 user bank。供 hindsight_retain 工具调用。"""
self._retain(self._user_bank, content, kind="tool_retain")
# ---- LLM 工具 --------------------------------------------------------
def get_tool_schemas(self) -> list[dict[str, Any]]:
"""Hindsight 的 3 个工具以 LangChain BaseTool 独立注册,不经 manager 路由。"""
return []
# ---- 可选 hooks ------------------------------------------------------
def on_session_switch(
self,
new_thread_id: str,
*,
parent_thread_id: str = "",
reset: bool = False,
**kwargs: Any,
) -> None:
"""thread 切换:重新解析 work bank,重置 retain 批次。"""
self._thread_id = new_thread_id
self._work_bank = self._resolve_bank(self._config.work_bank_id_template)
self._reset_retain_batch()
__all__ = ["HindsightProvider", "hindsight_client_available", "MIN_CLIENT_VERSION"]
@@ -0,0 +1,93 @@
"""Read-only provider for the mounted policy knowledge base.
This provider keeps the current knowledge-base behaviour: inject the lightweight
``routing.md`` guide and let the model decide when to read concrete files. It
does not automatically retrieve snippets and never writes to the knowledge base.
"""
from __future__ import annotations
import logging
from functools import lru_cache
from pathlib import Path
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
logger = logging.getLogger(__name__)
@lru_cache(maxsize=16)
def _read_routing_file(host_path: str) -> str:
path = Path(host_path)
if not path.is_file():
return ""
return path.read_text(encoding="utf-8").strip()
class KnowledgeProvider(MemoryProvider):
"""Injects the knowledge routing guide as a read-only context provider."""
def __init__(self, *, app_config: Any | None = None) -> None:
self._app_config = app_config
self._routing_host_path: Path | None = None
@property
def name(self) -> str:
return "knowledge"
def is_available(self) -> bool:
return True
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str,
**kwargs: Any,
) -> None:
app_config = self._app_config or kwargs.get("app_config")
if app_config is None:
from deerflow.config import get_app_config
app_config = get_app_config()
self._routing_host_path = None
for mount in app_config.sandbox.mounts or []:
if mount.container_path.rstrip("/") == "/mnt/knowledge":
self._routing_host_path = Path(mount.host_path) / "routing.md"
break
def system_prompt_block(self) -> str:
if self._routing_host_path is None:
return ""
content = _read_routing_file(str(self._routing_host_path.resolve()))
if not content:
return ""
logger.debug("Injected knowledge routing memory from %s", self._routing_host_path)
return f"""<knowledge_routing_memory source="/mnt/knowledge/routing.md">
{content}
</knowledge_routing_memory>"""
def prefetch(self, query: str, *, thread_id: str = "") -> str:
return ""
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
return None
def get_tool_schemas(self) -> list[dict[str, Any]]:
return []
__all__ = ["KnowledgeProvider"]
@@ -0,0 +1,161 @@
"""Memory V1 — 原版 DeerFlow JSON-based MemoryProvider 实现。
存储格式:``{base_dir}/users/{user_id}/memory.json``(经 FileMemoryStorage 管理)
JSON 结构使用嵌套 ``{summary, updatedAt}`` 对象,与原版 DeerFlow 完全一致。
LLM 在 V1 模式下不调用 memory 工具 —— 事实完全由异步 LLM 提取。
"""
from __future__ import annotations
import logging
from typing import Any
from deerflow.agents.memory.provider import MemoryProvider
logger = logging.getLogger(__name__)
class _FakeMsg:
"""轻量 message 对象,用于将文本传给原版 format_conversation_for_update。"""
__slots__ = ("type", "content")
def __init__(self, type_: str, content: str) -> None:
self.type = type_
self.content = content
class V1BuiltinProvider(MemoryProvider):
"""原版 DeerFlow V1 记忆 provider。"""
def __init__(
self,
*,
max_facts: int = 100,
fact_confidence_threshold: float = 0.7,
debounce_seconds: int = 30,
model_name: str = "",
token_budget: int = 2000,
) -> None:
self._max_facts = max_facts
self._confidence_threshold = fact_confidence_threshold
self._debounce_seconds = debounce_seconds
self._model_name = model_name
self._token_budget = token_budget
self._user_id: str = ""
self._thread_id: str = ""
self._agent_id: str | None = None
self._frozen_block: str = ""
@property
def name(self) -> str:
return "v1_builtin"
def is_available(self) -> bool:
return True
def initialize(
self,
*,
user_id: str,
agent_id: str | None = None,
thread_id: str | None = None,
base_dir: str,
**kwargs: Any,
) -> None:
_ = base_dir # FileMemoryStorage uses get_paths() internally
self._user_id = user_id
self._thread_id = thread_id or ""
self._agent_id = agent_id
self._frozen_block = self._build_frozen_block()
# ---- 系统提示词 -------------------------------------------------------
def _build_frozen_block(self) -> str:
"""从 memory.json 读取数据,用 format_memory_for_injection 渲染注入块。
当 agent_id 已知时加载 per-agent 记忆;否则加载用户级记忆。
"""
try:
from deerflow.agents.memory.v1.prompt import format_memory_for_injection
from deerflow.agents.memory.v1.storage import get_memory_storage
data = get_memory_storage().load(
agent_name=self._agent_id or None,
user_id=self._user_id,
)
text = format_memory_for_injection(data, max_tokens=self._token_budget)
if not text:
return ""
return f"<memory>\n{text}\n</memory>"
except Exception as exc: # noqa: BLE001
logger.warning("V1 provider 加载 memory.json 失败: %s", exc)
return ""
def system_prompt_block(self) -> str:
return self._frozen_block
# ---- 召回 / 写入 ------------------------------------------------------
def prefetch(self, query: str, *, thread_id: str = "") -> str:
# V1 无动态召回,静态 snapshot 已在 system_prompt_block 里
return ""
def sync_turn(
self,
user_content: str,
assistant_content: str,
*,
thread_id: str = "",
turn_index: int | None = None,
) -> None:
"""把本轮对话加入防抖队列,等待 LLM 异步提取事实。"""
if not user_content.strip() and not assistant_content.strip():
return
try:
from deerflow.agents.memory.v1.queue import get_memory_queue
msgs = [
_FakeMsg("human", user_content),
_FakeMsg("ai", assistant_content),
]
queue = get_memory_queue()
queue.add(
thread_id=thread_id or self._thread_id,
messages=msgs,
user_id=self._user_id,
agent_name=self._agent_id or None,
)
except Exception as exc: # noqa: BLE001
logger.warning("V1 provider sync_turn 入队失败: %s", exc)
# ---- 工具 (V1 不暴露工具给 LLM) -------------------------------------
def get_tool_schemas(self) -> list[dict[str, Any]]:
return []
# ---- API 读取接口 (供 Gateway router 用) -----------------------------
def read_v1_data(self) -> dict[str, Any]:
"""读取 memory.json 的当前内容(实时读磁盘,非 frozen snapshot)。
当 agent_id 已知时读取 per-agent 记忆;否则读用户级记忆。
"""
from deerflow.agents.memory.v1.storage import get_memory_storage
return get_memory_storage().load(
agent_name=self._agent_id or None,
user_id=self._user_id,
)
def fact_count(self) -> int:
try:
return len(self.read_v1_data().get("facts", []))
except Exception: # noqa: BLE001
return 0
def usage_text(self) -> str:
return f"{self.fact_count()}/{self._max_facts} 个事实"
__all__ = ["V1BuiltinProvider"]
@@ -0,0 +1,141 @@
"""Memory V2 - 记忆内容安全扫描。
记忆条目会被注入到系统提示词里,因此写入前必须扫描,阻断:
- Prompt 注入 / 角色劫持 / 隐藏指令
- 凭证外渗 (curl/wget 带密钥、读 .env 等敏感文件)
- 持久化后门 (写 authorized_keys 等)
- 不可见 unicode (零宽字符、双向控制符)
这是从 Hermes ``tools/memory_tool.py`` 的 ``_scan_memory_content`` 移植而来,
并针对 deerflow 的目录结构调整了敏感路径模式。
扫描默认开启,可由 ``config.memory.security.scan_content`` /
``block_invisible_unicode`` 关闭(不建议)。
"""
from __future__ import annotations
import re
# ---------------------------------------------------------------------------
# 威胁正则模式表:(正则, 模式 id)
# ---------------------------------------------------------------------------
_THREAT_PATTERNS: list[tuple[re.Pattern[str], str]] = [
# --- Prompt 注入 / 角色劫持 ---
# 允许多个限定词,如 "ignore ALL above instructions"
(re.compile(r"ignore\s+(?:(?:previous|all|above|prior|any)\s+)+instructions", re.IGNORECASE), "prompt_injection"),
(re.compile(r"忽略(?:以上|之前|上述|所有|全部|一切)+(?:的)?(?:指令|指示|要求|提示词)"), "prompt_injection_zh"),
(re.compile(r"you\s+are\s+now\s+", re.IGNORECASE), "role_hijack"),
(re.compile(r"do\s+not\s+tell\s+the\s+user", re.IGNORECASE), "deception_hide"),
(re.compile(r"不要(告诉|让)用户(知道)?"), "deception_hide_zh"),
(re.compile(r"system\s+prompt\s+override", re.IGNORECASE), "sys_prompt_override"),
(re.compile(r"disregard\s+(your|all|any)\s+(instructions|rules|guidelines)", re.IGNORECASE), "disregard_rules"),
(re.compile(r"act\s+as\s+(if|though)\s+you\s+(have\s+no|don'?t\s+have)\s+(restrictions|limits|rules)", re.IGNORECASE), "bypass_restrictions"),
# --- 凭证外渗 ---
(re.compile(r"curl\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)", re.IGNORECASE), "exfil_curl"),
(re.compile(r"wget\s+[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|API)", re.IGNORECASE), "exfil_wget"),
(re.compile(r"cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass|\.npmrc|\.pypirc)", re.IGNORECASE), "read_secrets"),
# --- 持久化后门 ---
(re.compile(r"authorized_keys", re.IGNORECASE), "ssh_backdoor"),
(re.compile(r"(\$HOME|~)/\.ssh", re.IGNORECASE), "ssh_access"),
]
# 不可见 unicode 字符:零宽字符 + 双向控制符。
# 它们肉眼不可见,常被用来在记忆里藏注入 payload。
_INVISIBLE_CHARS: frozenset[str] = frozenset(
{
"​", # ZERO WIDTH SPACE
"‌", # ZERO WIDTH NON-JOINER
"‍", # ZERO WIDTH JOINER
"⁠", # WORD JOINER
"", # ZERO WIDTH NO-BREAK SPACE / BOM
"‪", # LEFT-TO-RIGHT EMBEDDING
"‫", # RIGHT-TO-LEFT EMBEDDING
"‬", # POP DIRECTIONAL FORMATTING
"‭", # LEFT-TO-RIGHT OVERRIDE
"‮", # RIGHT-TO-LEFT OVERRIDE
}
)
class MemoryContentBlocked(ValueError):
"""记忆内容被安全扫描阻断时抛出。
``pattern_id`` 标明命中的威胁模式,便于上层返回结构化错误。
"""
def __init__(self, pattern_id: str, message: str) -> None:
self.pattern_id = pattern_id
super().__init__(message)
def scan_memory_content(
content: str,
*,
scan_threats: bool = True,
block_invisible_unicode: bool = True,
) -> str | None:
"""扫描记忆内容,命中威胁时返回错误描述,干净则返回 ``None``。
不抛异常 —— 返回字符串方便工具层直接塞进 ``{"success": False, "error": ...}``。
需要异常语义时用 :func:`assert_memory_content_safe`。
Parameters
----------
content:
待写入的记忆条目内容。
scan_threats:
是否扫描注入/外渗模式。对应 ``config.memory.security.scan_content``。
block_invisible_unicode:
是否阻断不可见 unicode。对应 ``config.memory.security.block_invisible_unicode``。
"""
if block_invisible_unicode:
for char in _INVISIBLE_CHARS:
if char in content:
return (
f"已阻断:内容包含不可见 unicode 字符 U+{ord(char):04X},"
"可能是注入 payload。"
)
if scan_threats:
for pattern, pattern_id in _THREAT_PATTERNS:
if pattern.search(content):
return (
f"已阻断:内容命中威胁模式 '{pattern_id}'。"
"记忆条目会被注入系统提示词,不允许包含注入或外渗内容。"
)
return None
def assert_memory_content_safe(
content: str,
*,
scan_threats: bool = True,
block_invisible_unicode: bool = True,
) -> None:
"""扫描记忆内容,命中威胁时抛出 :class:`MemoryContentBlocked`。
:func:`scan_memory_content` 的异常版本,供需要异常语义的调用方使用。
"""
error = scan_memory_content(
content,
scan_threats=scan_threats,
block_invisible_unicode=block_invisible_unicode,
)
if error is not None:
# 从错误描述里反推 pattern_id 不可靠,这里重新扫一遍拿确切 id。
pattern_id = "invisible_unicode"
for pattern, pid in _THREAT_PATTERNS:
if pattern.search(content):
pattern_id = pid
break
raise MemoryContentBlocked(pattern_id, error)
__all__ = [
"MemoryContentBlocked",
"scan_memory_content",
"assert_memory_content_safe",
]
@@ -0,0 +1 @@
"""Memory V1 — 原版 DeerFlow JSON-based 记忆子模块。"""
@@ -0,0 +1,371 @@
"""Prompt templates for memory update and injection."""
import math
import re
from typing import Any
try:
import tiktoken
TIKTOKEN_AVAILABLE = True
except ImportError:
TIKTOKEN_AVAILABLE = False
# Prompt template for updating memory based on conversation
MEMORY_UPDATE_PROMPT = """You are a memory management system. Your task is to analyze a conversation and update the user's memory profile.
Current Memory State:
<current_memory>
{current_memory}
</current_memory>
New Conversation to Process:
<conversation>
{conversation}
</conversation>
Instructions:
1. Analyze the conversation for important information about the user
2. Extract relevant facts, preferences, and context with specific details (numbers, names, technologies)
3. Update the memory sections as needed following the detailed length guidelines below
Before extracting facts, perform a structured reflection on the conversation:
1. Error/Retry Detection: Did the agent encounter errors, require retries, or produce incorrect results?
If yes, record the root cause and correct approach as a high-confidence fact with category "correction".
2. User Correction Detection: Did the user correct the agent's direction, understanding, or output?
If yes, record the correct interpretation or approach as a high-confidence fact with category "correction".
Include what went wrong in "sourceError" only when category is "correction" and the mistake is explicit in the conversation.
3. Project Constraint Discovery: Were any project-specific constraints discovered during the conversation?
If yes, record them as facts with the most appropriate category and confidence.
{correction_hint}
Memory Section Guidelines:
**User Context** (Current state - concise summaries):
- workContext: Professional role, company, key projects, main technologies (2-3 sentences)
Example: Core contributor, project names with metrics (16k+ stars), technical stack
- personalContext: Languages, communication preferences, key interests (1-2 sentences)
Example: Bilingual capabilities, specific interest areas, expertise domains
- topOfMind: Multiple ongoing focus areas and priorities (3-5 sentences, detailed paragraph)
Example: Primary project work, parallel technical investigations, ongoing learning/tracking
Include: Active implementation work, troubleshooting issues, market/research interests
Note: This captures SEVERAL concurrent focus areas, not just one task
**History** (Temporal context - rich paragraphs; updated incrementally each conversation):
- recentMonths: Running log of recent work and activities (4-6 sentences or 1-2 paragraphs)
Scope: Accumulate from each conversation — any task the user worked on, problems solved, technologies touched
Update policy: Set shouldUpdate=true whenever the conversation contains any task, discussion, or work activity; integrate new content into existing text rather than overwriting
Include: Technologies explored, projects worked on, problems solved, interests demonstrated
- earlierContext: Important patterns promoted from recentMonths over time (3-5 sentences or 1 paragraph)
Scope: Recurring themes and established patterns across multiple conversations
Update policy: Set shouldUpdate=true when a pattern repeats or an older item in recentMonths should be archived here
Include: Past projects, learning journeys, established patterns
- longTermBackground: Persistent foundational context that rarely changes (2-4 sentences)
Scope: Core expertise, fundamental working style, long-standing interests
Update policy: Set shouldUpdate=true only when a genuinely new foundational fact emerges
Include: Core expertise, longstanding interests, fundamental working style
**Facts Extraction**:
- Extract specific, quantifiable details (e.g., "16k+ GitHub stars", "200+ datasets")
- Include proper nouns (company names, project names, technology names)
- Preserve technical terminology and version numbers
- Categories:
* preference: Tools, styles, approaches user prefers/dislikes
* knowledge: Specific expertise, technologies mastered, domain knowledge
* context: Background facts (job title, projects, locations, languages)
* behavior: Working patterns, communication habits, problem-solving approaches
* goal: Stated objectives, learning targets, project ambitions
* correction: Explicit agent mistakes or user corrections, including the correct approach
- Confidence levels:
* 0.9-1.0: Explicitly stated facts ("I work on X", "My role is Y")
* 0.7-0.8: Strongly implied from actions/discussions
* 0.5-0.6: Inferred patterns (use sparingly, only for clear patterns)
**What Goes Where**:
- workContext: Current job, active projects, primary tech stack
- personalContext: Languages, personality, interests outside direct work tasks
- topOfMind: Multiple ongoing priorities and focus areas user cares about recently (gets updated most frequently)
Should capture 3-5 concurrent themes: main work, side explorations, learning/tracking interests
- recentMonths: Cumulative log of recent work — update from EVERY conversation with meaningful content
- earlierContext: Recurring patterns promoted from recentMonths; update when patterns solidify
- longTermBackground: Unchanging foundational facts about the user; update only for new foundational info
**Language Requirement**:
- ALL summaries and fact content MUST be written in Chinese (Simplified)
- Keep technical terms, proper nouns, product names, and company names in their original form (e.g., DeepSeek, LangGraph, GitHub)
- Surrounding descriptive text must be in Chinese regardless of the conversation language
Output Format (JSON):
{{
"user": {{
"workContext": {{ "summary": "...", "shouldUpdate": true/false }},
"personalContext": {{ "summary": "...", "shouldUpdate": true/false }},
"topOfMind": {{ "summary": "...", "shouldUpdate": true/false }}
}},
"history": {{
"recentMonths": {{ "summary": "...", "shouldUpdate": true/false }},
"earlierContext": {{ "summary": "...", "shouldUpdate": true/false }},
"longTermBackground": {{ "summary": "...", "shouldUpdate": true/false }}
}},
"newFacts": [
{{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
],
"factsToRemove": ["fact_id_1", "fact_id_2"]
}}
Important Rules:
- For recentMonths: set shouldUpdate=true whenever the conversation contains any task, work, or substantive discussion — this field accumulates like a log
- For earlierContext / longTermBackground: set shouldUpdate=true only when a new pattern solidifies or a foundational fact changes
- For user context fields: set shouldUpdate=true if there's meaningful new information
- Follow length guidelines: workContext/personalContext are concise (1-3 sentences), topOfMind and history sections are detailed (paragraphs)
- Include specific metrics, version numbers, and proper nouns in facts
- Only add facts that are clearly stated (0.9+) or strongly implied (0.7+)
- Use category "correction" for explicit agent mistakes or user corrections; assign confidence >= 0.95 when the correction is explicit
- Include "sourceError" only for explicit correction facts when the prior mistake or wrong approach is clearly stated; omit it otherwise
- Remove facts that are contradicted by new information
- When updating topOfMind, integrate new focus areas while removing completed/abandoned ones
Keep 3-5 concurrent focus themes that are still active and relevant
- For history sections, integrate new information chronologically into appropriate time period
- Preserve technical accuracy - keep exact names of technologies, companies, projects
- Focus on information useful for future interactions and personalization
- IMPORTANT: Do NOT record file upload events in memory. Uploaded files are
session-specific and ephemeral — they will not be accessible in future sessions.
Recording upload events causes confusion in subsequent conversations.
- CRITICAL: Write ALL summary text and fact content in Chinese (Simplified). Technical terms and proper nouns (product names, company names, technology names) may remain in their original language, but all other text must be in Chinese.
Return ONLY valid JSON, no explanation or markdown."""
# Prompt template for extracting facts from a single message
FACT_EXTRACTION_PROMPT = """Extract factual information about the user from this message.
Message:
{message}
Extract facts in this JSON format:
{{
"facts": [
{{ "content": "...", "category": "preference|knowledge|context|behavior|goal|correction", "confidence": 0.0-1.0 }}
]
}}
Categories:
- preference: User preferences (likes/dislikes, styles, tools)
- knowledge: User's expertise or knowledge areas
- context: Background context (location, job, projects)
- behavior: Behavioral patterns
- goal: User's goals or objectives
- correction: Explicit corrections or mistakes to avoid repeating
Rules:
- Only extract clear, specific facts
- Confidence should reflect certainty (explicit statement = 0.9+, implied = 0.6-0.8)
- Skip vague or temporary information
- Write all fact content in Chinese (Simplified); technical terms and proper nouns may remain in their original language
Return ONLY valid JSON."""
def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
"""Count tokens in text using tiktoken.
Args:
text: The text to count tokens for.
encoding_name: The encoding to use (default: cl100k_base for GPT-4/3.5).
Returns:
The number of tokens in the text.
"""
if not TIKTOKEN_AVAILABLE:
return len(text) // 4
try:
encoding = tiktoken.get_encoding(encoding_name)
return len(encoding.encode(text))
except Exception:
return len(text) // 4
def _coerce_confidence(value: Any, default: float = 0.0) -> float:
"""Coerce a confidence-like value to a bounded float in [0, 1].
Non-finite values (NaN, inf, -inf) are treated as invalid and fall back
to the default before clamping, preventing them from dominating ranking.
The ``default`` parameter is assumed to be a finite value.
"""
try:
confidence = float(value)
except (TypeError, ValueError):
return max(0.0, min(1.0, default))
if not math.isfinite(confidence):
return max(0.0, min(1.0, default))
return max(0.0, min(1.0, confidence))
def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
"""Format memory data for injection into system prompt.
Args:
memory_data: The memory data dictionary.
max_tokens: Maximum tokens to use (counted via tiktoken for accuracy).
Returns:
Formatted memory string for system prompt injection.
"""
if not memory_data:
return ""
sections = []
# Format user context
user_data = memory_data.get("user", {})
if user_data:
user_sections = []
work_ctx = user_data.get("workContext", {})
if work_ctx.get("summary"):
user_sections.append(f"Work: {work_ctx['summary']}")
personal_ctx = user_data.get("personalContext", {})
if personal_ctx.get("summary"):
user_sections.append(f"Personal: {personal_ctx['summary']}")
top_of_mind = user_data.get("topOfMind", {})
if top_of_mind.get("summary"):
user_sections.append(f"Current Focus: {top_of_mind['summary']}")
if user_sections:
sections.append("User Context:\n" + "\n".join(f"- {s}" for s in user_sections))
# Format history
history_data = memory_data.get("history", {})
if history_data:
history_sections = []
recent = history_data.get("recentMonths", {})
if recent.get("summary"):
history_sections.append(f"Recent: {recent['summary']}")
earlier = history_data.get("earlierContext", {})
if earlier.get("summary"):
history_sections.append(f"Earlier: {earlier['summary']}")
background = history_data.get("longTermBackground", {})
if background.get("summary"):
history_sections.append(f"Background: {background['summary']}")
if history_sections:
sections.append("History:\n" + "\n".join(f"- {s}" for s in history_sections))
# Format facts (sorted by confidence; include as many as token budget allows)
facts_data = memory_data.get("facts", [])
if isinstance(facts_data, list) and facts_data:
ranked_facts = sorted(
(f for f in facts_data if isinstance(f, dict) and isinstance(f.get("content"), str) and f.get("content").strip()),
key=lambda fact: _coerce_confidence(fact.get("confidence"), default=0.0),
reverse=True,
)
base_text = "\n\n".join(sections)
base_tokens = _count_tokens(base_text) if base_text else 0
facts_header = "Facts:\n"
separator_tokens = _count_tokens("\n\n" + facts_header) if base_text else _count_tokens(facts_header)
running_tokens = base_tokens + separator_tokens
fact_lines: list[str] = []
for fact in ranked_facts:
content_value = fact.get("content")
if not isinstance(content_value, str):
continue
content = content_value.strip()
if not content:
continue
category = str(fact.get("category", "context")).strip() or "context"
confidence = _coerce_confidence(fact.get("confidence"), default=0.0)
source_error = fact.get("sourceError")
if category == "correction" and isinstance(source_error, str) and source_error.strip():
line = f"- [{category} | {confidence:.2f}] {content} (avoid: {source_error.strip()})"
else:
line = f"- [{category} | {confidence:.2f}] {content}"
line_text = ("\n" + line) if fact_lines else line
line_tokens = _count_tokens(line_text)
if running_tokens + line_tokens <= max_tokens:
fact_lines.append(line)
running_tokens += line_tokens
else:
break
if fact_lines:
sections.append("Facts:\n" + "\n".join(fact_lines))
if not sections:
return ""
result = "\n\n".join(sections)
token_count = _count_tokens(result)
if token_count > max_tokens:
char_per_token = len(result) / token_count
target_chars = int(max_tokens * char_per_token * 0.95)
result = result[:target_chars] + "\n..."
return result
def format_conversation_for_update(messages: list[Any]) -> str:
"""Format conversation messages for memory update prompt.
Args:
messages: List of conversation messages.
Returns:
Formatted conversation string.
"""
lines = []
for msg in messages:
role = getattr(msg, "type", "unknown")
content = getattr(msg, "content", str(msg))
# Handle content that might be a list (multimodal)
if isinstance(content, list):
text_parts = []
for p in content:
if isinstance(p, str):
text_parts.append(p)
elif isinstance(p, dict):
text_val = p.get("text")
if isinstance(text_val, str):
text_parts.append(text_val)
content = " ".join(text_parts) if text_parts else str(content)
# Strip uploaded_files tags from human messages to avoid persisting
# ephemeral file path info into long-term memory. Skip the turn entirely
# when nothing remains after stripping (upload-only message).
if role == "human":
content = re.sub(r"<uploaded_files>[\s\S]*?</uploaded_files>\n*", "", str(content)).strip()
if not content:
continue
# Truncate very long messages
if len(str(content)) > 1000:
content = str(content)[:1000] + "..."
if role == "human":
lines.append(f"User: {content}")
elif role == "ai":
lines.append(f"Assistant: {content}")
return "\n\n".join(lines)
__all__ = [
"MEMORY_UPDATE_PROMPT",
"FACT_EXTRACTION_PROMPT",
"format_memory_for_injection",
"format_conversation_for_update",
"_count_tokens",
"_coerce_confidence",
]
@@ -0,0 +1,253 @@
"""Memory V1 — 防抖异步更新队列(原版 DeerFlow MemoryUpdateQueue)。"""
from __future__ import annotations
import logging
import threading
import time
from dataclasses import dataclass, field
from datetime import UTC, datetime
from typing import Any
logger = logging.getLogger(__name__)
def _get_v1_cfg():
from deerflow.config.memory_config import get_memory_config
return get_memory_config().v1
def _memory_enabled() -> bool:
from deerflow.config.memory_config import get_memory_config
return get_memory_config().enabled
@dataclass
class ConversationContext:
"""Context for a conversation to be processed for memory update."""
thread_id: str
messages: list[Any]
timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
agent_name: str | None = None
user_id: str | None = None
correction_detected: bool = False
reinforcement_detected: bool = False
class MemoryUpdateQueue:
"""Queue for memory updates with debounce mechanism.
Collects conversation contexts and processes them after a configurable
debounce period. Multiple conversations received within the debounce
window are deduplicated by (thread_id, user_id, agent_name).
"""
def __init__(self) -> None:
self._queue: list[ConversationContext] = []
self._lock = threading.Lock()
self._timer: threading.Timer | None = None
self._processing = False
@staticmethod
def _queue_key(thread_id: str, user_id: str | None, agent_name: str | None) -> tuple[str, str | None, str | None]:
return (thread_id, user_id, agent_name)
def add(
self,
thread_id: str,
messages: list[Any],
agent_name: str | None = None,
user_id: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
) -> None:
"""Add a conversation to the update queue (with debounce)."""
if not _memory_enabled():
return
with self._lock:
self._enqueue_locked(
thread_id=thread_id,
messages=messages,
agent_name=agent_name,
user_id=user_id,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
)
self._reset_timer()
logger.info("V1 memory update queued for thread %s, queue size: %d", thread_id, len(self._queue))
def add_nowait(
self,
thread_id: str,
messages: list[Any],
agent_name: str | None = None,
user_id: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
) -> None:
"""Add a conversation and start processing immediately in the background."""
if not _memory_enabled():
return
with self._lock:
self._enqueue_locked(
thread_id=thread_id,
messages=messages,
agent_name=agent_name,
user_id=user_id,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
)
self._schedule_timer(0)
logger.info("V1 memory update queued for immediate processing on thread %s, queue size: %d", thread_id, len(self._queue))
def _enqueue_locked(
self,
*,
thread_id: str,
messages: list[Any],
agent_name: str | None,
user_id: str | None,
correction_detected: bool,
reinforcement_detected: bool,
) -> None:
queue_key = self._queue_key(thread_id, user_id, agent_name)
existing = next(
(ctx for ctx in self._queue if self._queue_key(ctx.thread_id, ctx.user_id, ctx.agent_name) == queue_key),
None,
)
merged_correction = correction_detected or (existing.correction_detected if existing is not None else False)
merged_reinforcement = reinforcement_detected or (existing.reinforcement_detected if existing is not None else False)
context = ConversationContext(
thread_id=thread_id,
messages=messages,
agent_name=agent_name,
user_id=user_id,
correction_detected=merged_correction,
reinforcement_detected=merged_reinforcement,
)
self._queue = [ctx for ctx in self._queue if self._queue_key(ctx.thread_id, ctx.user_id, ctx.agent_name) != queue_key]
self._queue.append(context)
def _reset_timer(self) -> None:
cfg = _get_v1_cfg()
self._schedule_timer(cfg.debounce_seconds)
logger.debug("V1 memory update timer set for %ss", cfg.debounce_seconds)
def _schedule_timer(self, delay_seconds: float) -> None:
if self._timer is not None:
self._timer.cancel()
self._timer = threading.Timer(delay_seconds, self._process_queue)
self._timer.daemon = True
self._timer.start()
def _process_queue(self) -> None:
from deerflow.agents.memory.v1.updater import MemoryUpdater
with self._lock:
if self._processing:
self._schedule_timer(0)
return
if not self._queue:
return
self._processing = True
contexts_to_process = self._queue.copy()
self._queue.clear()
self._timer = None
logger.info("V1 memory: processing %d queued updates", len(contexts_to_process))
try:
updater = MemoryUpdater()
for context in contexts_to_process:
try:
logger.info("V1 memory: updating for thread %s", context.thread_id)
success = updater.update_memory(
messages=context.messages,
thread_id=context.thread_id,
agent_name=context.agent_name,
correction_detected=context.correction_detected,
reinforcement_detected=context.reinforcement_detected,
user_id=context.user_id,
)
if success:
logger.info("V1 memory: updated successfully for thread %s", context.thread_id)
else:
logger.warning("V1 memory: update skipped/failed for thread %s", context.thread_id)
except Exception as e: # noqa: BLE001
logger.error("V1 memory: error updating for thread %s: %s", context.thread_id, e)
if len(contexts_to_process) > 1:
time.sleep(0.5)
finally:
with self._lock:
self._processing = False
def flush(self) -> None:
"""Force immediate processing of the queue."""
with self._lock:
if self._timer is not None:
self._timer.cancel()
self._timer = None
self._process_queue()
def flush_nowait(self) -> None:
"""Start queue processing immediately in a background thread."""
with self._lock:
self._schedule_timer(0)
def clear(self) -> None:
"""Clear the queue without processing (for testing)."""
with self._lock:
if self._timer is not None:
self._timer.cancel()
self._timer = None
self._queue.clear()
self._processing = False
@property
def pending_count(self) -> int:
with self._lock:
return len(self._queue)
@property
def is_processing(self) -> bool:
with self._lock:
return self._processing
_memory_queue: MemoryUpdateQueue | None = None
_queue_lock = threading.Lock()
def get_memory_queue() -> MemoryUpdateQueue:
"""Get the global memory update queue singleton."""
global _memory_queue
with _queue_lock:
if _memory_queue is None:
_memory_queue = MemoryUpdateQueue()
return _memory_queue
def reset_memory_queue() -> None:
"""Reset the global memory queue (for testing)."""
global _memory_queue
with _queue_lock:
if _memory_queue is not None:
_memory_queue.clear()
_memory_queue = None
__all__ = [
"ConversationContext",
"MemoryUpdateQueue",
"get_memory_queue",
"reset_memory_queue",
]
@@ -0,0 +1,226 @@
"""Memory V1 — 存储层(原版 DeerFlow 格式)。
JSON 结构:
{
"version": "1.0",
"lastUpdated": "...",
"user": {
"workContext": {"summary": "", "updatedAt": ""},
"personalContext": {"summary": "", "updatedAt": ""},
"topOfMind": {"summary": "", "updatedAt": ""}
},
"history": {
"recentMonths": {"summary": "", "updatedAt": ""},
"earlierContext": {"summary": "", "updatedAt": ""},
"longTermBackground":{"summary": "", "updatedAt": ""}
},
"facts": []
}
"""
from __future__ import annotations
import json
import logging
import threading
import uuid
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from deerflow.config.agents_config import AGENT_NAME_PATTERN
from deerflow.config.paths import get_paths
logger = logging.getLogger(__name__)
def utc_now_iso_z() -> str:
"""Current UTC time as ISO-8601 with ``Z`` suffix."""
return datetime.now(UTC).isoformat().removesuffix("+00:00") + "Z"
def create_empty_memory() -> dict[str, Any]:
"""Create an empty memory structure (new format)."""
return {
"version": "1.0",
"lastUpdated": utc_now_iso_z(),
"user": {
"workContext": {"summary": "", "updatedAt": ""},
"personalContext": {"summary": "", "updatedAt": ""},
"topOfMind": {"summary": "", "updatedAt": ""},
},
"history": {
"recentMonths": {"summary": "", "updatedAt": ""},
"earlierContext": {"summary": "", "updatedAt": ""},
"longTermBackground": {"summary": "", "updatedAt": ""},
},
"facts": [],
}
def _migrate_legacy(data: dict[str, Any]) -> dict[str, Any]:
"""把老格式 {userContext: {workContext: str}} 迁移到新格式 {user: {workContext: {summary, updatedAt}}}。"""
if "userContext" not in data:
return data
now = utc_now_iso_z()
old_ctx = data.pop("userContext", {})
data["user"] = {
k: {"summary": v or "", "updatedAt": now} if isinstance(v, str) else v
for k, v in old_ctx.items()
}
# history 字段可能是纯字符串,需要包裹
if "history" in data:
hist = data["history"]
data["history"] = {
k: {"summary": v or "", "updatedAt": now} if isinstance(v, str) else v
for k, v in hist.items()
}
# 确保 user 包含所有必要字段
base = create_empty_memory()
for key in ("user", "history"):
section = base[key]
for field in section:
if field not in data.get(key, {}):
data.setdefault(key, {})[field] = section[field]
data["version"] = "1.0"
data.pop("updatedAt", None)
return data
class FileMemoryStorage:
"""File-based memory storage provider (原版 DeerFlow 实现)。"""
def __init__(self) -> None:
# Per-(user_id, agent_name) cache: value = (memory_data, file_mtime)
self._memory_cache: dict[tuple[str | None, str | None], tuple[dict[str, Any], float | None]] = {}
self._cache_lock = threading.Lock()
def _validate_agent_name(self, agent_name: str) -> None:
if not agent_name:
raise ValueError("Agent name must be a non-empty string.")
if not AGENT_NAME_PATTERN.match(agent_name):
raise ValueError(f"Invalid agent name {agent_name!r}: names must match {AGENT_NAME_PATTERN.pattern}")
def _get_memory_file_path(self, agent_name: str | None = None, *, user_id: str | None = None) -> Path:
paths = get_paths()
if user_id is not None:
if agent_name is not None:
self._validate_agent_name(agent_name)
return paths.user_agent_memory_file(user_id, agent_name)
return paths.user_memory_file(user_id)
# Legacy: no user_id
if agent_name is not None:
self._validate_agent_name(agent_name)
return paths.agent_memory_file(agent_name)
return paths.memory_file
def _load_from_file(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
if not file_path.exists():
return create_empty_memory()
try:
with open(file_path, encoding="utf-8") as f:
data = json.load(f)
if not isinstance(data, dict):
return create_empty_memory()
data = _migrate_legacy(data)
return data
except (json.JSONDecodeError, OSError) as e:
logger.warning("Failed to load memory file %s: %s", file_path, e)
return create_empty_memory()
@staticmethod
def _cache_key(agent_name: str | None = None, *, user_id: str | None = None) -> tuple[str | None, str | None]:
return (user_id, agent_name)
def load(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
"""Load memory data (cached with file modification time check)."""
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
cache_key = self._cache_key(agent_name, user_id=user_id)
try:
current_mtime = file_path.stat().st_mtime if file_path.exists() else None
except OSError:
current_mtime = None
with self._cache_lock:
cached = self._memory_cache.get(cache_key)
if cached is not None and cached[1] == current_mtime:
return cached[0]
memory_data = self._load_from_file(agent_name, user_id=user_id)
with self._cache_lock:
self._memory_cache[cache_key] = (memory_data, current_mtime)
return memory_data
def reload(self, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
"""Reload memory data from file, forcing cache invalidation."""
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
memory_data = self._load_from_file(agent_name, user_id=user_id)
cache_key = self._cache_key(agent_name, user_id=user_id)
try:
mtime = file_path.stat().st_mtime if file_path.exists() else None
except OSError:
mtime = None
with self._cache_lock:
self._memory_cache[cache_key] = (memory_data, mtime)
return memory_data
def save(self, memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> bool:
"""Save memory data to file and update cache (atomic write)."""
file_path = self._get_memory_file_path(agent_name, user_id=user_id)
cache_key = self._cache_key(agent_name, user_id=user_id)
try:
file_path.parent.mkdir(parents=True, exist_ok=True)
memory_data = {**memory_data, "lastUpdated": utc_now_iso_z()}
temp_path = file_path.with_suffix(f".{uuid.uuid4().hex}.tmp")
with open(temp_path, "w", encoding="utf-8") as f:
json.dump(memory_data, f, indent=2, ensure_ascii=False)
temp_path.replace(file_path)
try:
mtime = file_path.stat().st_mtime
except OSError:
mtime = None
with self._cache_lock:
self._memory_cache[cache_key] = (memory_data, mtime)
logger.info("Memory saved to %s", file_path)
return True
except OSError as e:
logger.error("Failed to save memory file: %s", e)
return False
_storage_instance: FileMemoryStorage | None = None
_storage_lock = threading.Lock()
def get_memory_storage() -> FileMemoryStorage:
"""Get the global FileMemoryStorage singleton."""
global _storage_instance
if _storage_instance is not None:
return _storage_instance
with _storage_lock:
if _storage_instance is None:
_storage_instance = FileMemoryStorage()
return _storage_instance
__all__ = [
"create_empty_memory",
"utc_now_iso_z",
"FileMemoryStorage",
"get_memory_storage",
]
@@ -0,0 +1,55 @@
"""Hooks fired before summarization removes messages from state(原版 DeerFlow)。"""
from __future__ import annotations
from deerflow.agents.memory.message_processing import detect_correction, detect_reinforcement, filter_messages_for_memory
from deerflow.agents.memory.v1.queue import get_memory_queue
from deerflow.config.memory_config import get_memory_config
def memory_flush_hook(event: object) -> None:
"""Flush messages about to be summarized into the V1 memory queue.
``event`` is expected to be a ``SummarizationEvent``-like object with:
- ``thread_id: str``
- ``messages_to_summarize: list``
- ``agent_name: str | None``
- ``runtime: RunnableConfig``
"""
if not get_memory_config().enabled:
return
thread_id = getattr(event, "thread_id", None)
if not thread_id:
return
messages_to_summarize = getattr(event, "messages_to_summarize", [])
filtered_messages = filter_messages_for_memory(list(messages_to_summarize))
user_messages = [m for m in filtered_messages if getattr(m, "type", None) == "human"]
assistant_messages = [m for m in filtered_messages if getattr(m, "type", None) == "ai"]
if not user_messages or not assistant_messages:
return
correction_detected = detect_correction(filtered_messages)
reinforcement_detected = not correction_detected and detect_reinforcement(filtered_messages)
try:
from deerflow.runtime.user_context import resolve_runtime_user_id
runtime = getattr(event, "runtime", None)
user_id = resolve_runtime_user_id(runtime) if runtime is not None else None
except Exception: # noqa: BLE001
user_id = None
agent_name = getattr(event, "agent_name", None)
queue = get_memory_queue()
queue.add_nowait(
thread_id=thread_id,
messages=filtered_messages,
agent_name=agent_name,
user_id=user_id,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
)
__all__ = ["memory_flush_hook"]
@@ -0,0 +1,495 @@
"""Memory V1 — updater(原版 DeerFlow MemoryUpdater)。"""
from __future__ import annotations
import asyncio
import atexit
import concurrent.futures
import copy
import json
import logging
import math
import re
import uuid
from typing import Any
from deerflow.agents.memory.v1.prompt import (
MEMORY_UPDATE_PROMPT,
format_conversation_for_update,
)
from deerflow.agents.memory.v1.storage import (
create_empty_memory,
get_memory_storage,
utc_now_iso_z,
)
logger = logging.getLogger(__name__)
_SYNC_MEMORY_UPDATER_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
max_workers=4,
thread_name_prefix="v1-memory-updater-sync",
)
atexit.register(lambda: _SYNC_MEMORY_UPDATER_EXECUTOR.shutdown(wait=False))
def _get_v1_cfg():
"""返回 V1MemoryConfig(含 max_facts, fact_confidence_threshold, model_name)。"""
from deerflow.config.memory_config import get_memory_config
return get_memory_config().v1
# ---------------------------------------------------------------------------
# 向后兼容的便捷函数(供 gateway router 等调用)
# ---------------------------------------------------------------------------
def get_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
return get_memory_storage().load(agent_name, user_id=user_id)
def reload_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
return get_memory_storage().reload(agent_name, user_id=user_id)
def import_memory_data(memory_data: dict[str, Any], agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
storage = get_memory_storage()
if not storage.save(memory_data, agent_name, user_id=user_id):
raise OSError("Failed to save imported memory data")
return storage.load(agent_name, user_id=user_id)
def clear_memory_data(agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
cleared = create_empty_memory()
if not get_memory_storage().save(cleared, agent_name, user_id=user_id):
raise OSError("Failed to save cleared memory data")
return cleared
def _validate_confidence(confidence: float) -> float:
if not math.isfinite(confidence) or confidence < 0 or confidence > 1:
raise ValueError("confidence")
return confidence
def create_memory_fact(
content: str,
category: str = "context",
confidence: float = 0.5,
agent_name: str | None = None,
*,
user_id: str | None = None,
) -> dict[str, Any]:
normalized_content = content.strip()
if not normalized_content:
raise ValueError("content")
normalized_category = category.strip() or "context"
validated_confidence = _validate_confidence(confidence)
now = utc_now_iso_z()
memory_data = get_memory_data(agent_name, user_id=user_id)
updated_memory = dict(memory_data)
facts = list(memory_data.get("facts", []))
facts.append({
"id": f"fact_{uuid.uuid4().hex[:8]}",
"content": normalized_content,
"category": normalized_category,
"confidence": validated_confidence,
"createdAt": now,
"source": "manual",
})
updated_memory["facts"] = facts
if not get_memory_storage().save(updated_memory, agent_name, user_id=user_id):
raise OSError("Failed to save memory data after creating fact")
return updated_memory
def delete_memory_fact(fact_id: str, agent_name: str | None = None, *, user_id: str | None = None) -> dict[str, Any]:
memory_data = get_memory_data(agent_name, user_id=user_id)
facts = memory_data.get("facts", [])
updated_facts = [f for f in facts if f.get("id") != fact_id]
if len(updated_facts) == len(facts):
raise KeyError(fact_id)
updated_memory = dict(memory_data)
updated_memory["facts"] = updated_facts
if not get_memory_storage().save(updated_memory, agent_name, user_id=user_id):
raise OSError(f"Failed to save memory data after deleting fact '{fact_id}'")
return updated_memory
def update_memory_fact(
fact_id: str,
content: str | None = None,
category: str | None = None,
confidence: float | None = None,
agent_name: str | None = None,
*,
user_id: str | None = None,
) -> dict[str, Any]:
memory_data = get_memory_data(agent_name, user_id=user_id)
updated_memory = dict(memory_data)
updated_facts: list[dict[str, Any]] = []
found = False
for fact in memory_data.get("facts", []):
if fact.get("id") == fact_id:
found = True
updated_fact = dict(fact)
if content is not None:
normalized = content.strip()
if not normalized:
raise ValueError("content")
updated_fact["content"] = normalized
if category is not None:
updated_fact["category"] = category.strip() or "context"
if confidence is not None:
updated_fact["confidence"] = _validate_confidence(confidence)
updated_facts.append(updated_fact)
else:
updated_facts.append(fact)
if not found:
raise KeyError(fact_id)
updated_memory["facts"] = updated_facts
if not get_memory_storage().save(updated_memory, agent_name, user_id=user_id):
raise OSError(f"Failed to save memory data after updating fact '{fact_id}'")
return updated_memory
# ---------------------------------------------------------------------------
# 内容提取辅助
# ---------------------------------------------------------------------------
def _extract_text(content: Any) -> str:
"""从 LLM response content(str 或 list of blocks)提取纯文本。"""
if isinstance(content, str):
return content
if isinstance(content, list):
pieces: list[str] = []
pending: list[str] = []
def flush():
if pending:
pieces.append("".join(pending))
pending.clear()
for block in content:
if isinstance(block, str):
pending.append(block)
elif isinstance(block, dict):
flush()
text_val = block.get("text")
if isinstance(text_val, str):
pieces.append(text_val)
flush()
return "\n".join(pieces)
return str(content)
_UPLOAD_SENTENCE_RE = re.compile(
r"[^.!?]*\b(?:"
r"upload(?:ed|ing)?(?:\s+\w+){0,3}\s+(?:file|files?|document|documents?|attachment|attachments?)"
r"|file\s+upload"
r"|/mnt/user-data/uploads/"
r"|<uploaded_files>"
r")[^.!?]*[.!?]?\s*",
re.IGNORECASE,
)
def _strip_upload_mentions_from_memory(memory_data: dict[str, Any]) -> dict[str, Any]:
"""移除记忆中关于文件上传事件的句子(上传文件是会话级临时的)。"""
for section in ("user", "history"):
section_data = memory_data.get(section, {})
for _key, val in section_data.items():
if isinstance(val, dict) and "summary" in val:
cleaned = _UPLOAD_SENTENCE_RE.sub("", val["summary"]).strip()
cleaned = re.sub(r" +", " ", cleaned)
val["summary"] = cleaned
facts = memory_data.get("facts", [])
if facts:
memory_data["facts"] = [f for f in facts if not _UPLOAD_SENTENCE_RE.search(f.get("content", ""))]
return memory_data
def _fact_content_key(content: Any) -> str | None:
if not isinstance(content, str):
return None
stripped = content.strip()
if not stripped:
return None
return stripped.casefold()
# ---------------------------------------------------------------------------
# MemoryUpdater(原版核心类)
# ---------------------------------------------------------------------------
class MemoryUpdater:
"""Updates memory using LLM based on conversation context."""
def __init__(self, model_name: str | None = None) -> None:
self._model_name = model_name
def _get_model(self):
from deerflow.models import create_chat_model
cfg = _get_v1_cfg()
model_name = self._model_name or cfg.model_name
return create_chat_model(name=model_name or None, thinking_enabled=False)
def _build_correction_hint(self, correction_detected: bool, reinforcement_detected: bool) -> str:
correction_hint = ""
if correction_detected:
correction_hint = (
"IMPORTANT: Explicit correction signals were detected in this conversation. "
"Pay special attention to what the agent got wrong, what the user corrected, "
"and record the correct approach as a fact with category "
'"correction" and confidence >= 0.95 when appropriate.'
)
if reinforcement_detected:
reinforcement_hint = (
"IMPORTANT: Positive reinforcement signals were detected in this conversation. "
"The user explicitly confirmed the agent's approach was correct or helpful. "
"Record the confirmed approach, style, or preference as a fact with category "
'"preference" or "behavior" and confidence >= 0.9 when appropriate.'
)
correction_hint = (correction_hint + "\n" + reinforcement_hint).strip() if correction_hint else reinforcement_hint
return correction_hint
def _prepare_update_prompt(
self,
messages: list[Any],
agent_name: str | None,
correction_detected: bool,
reinforcement_detected: bool,
user_id: str | None = None,
) -> tuple[dict[str, Any], str] | None:
from deerflow.config.memory_config import get_memory_config
config = get_memory_config()
if not config.enabled or not messages:
return None
current_memory = get_memory_data(agent_name, user_id=user_id)
conversation_text = format_conversation_for_update(messages)
if not conversation_text.strip():
return None
correction_hint = self._build_correction_hint(correction_detected, reinforcement_detected)
prompt = MEMORY_UPDATE_PROMPT.format(
current_memory=json.dumps(current_memory, indent=2, ensure_ascii=False),
conversation=conversation_text,
correction_hint=correction_hint,
)
return current_memory, prompt
def _finalize_update(
self,
current_memory: dict[str, Any],
response_content: Any,
thread_id: str | None,
agent_name: str | None,
user_id: str | None = None,
) -> bool:
response_text = _extract_text(response_content).strip()
if response_text.startswith("```"):
lines = response_text.split("\n")
response_text = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
update_data = json.loads(response_text)
updated_memory = self._apply_updates(copy.deepcopy(current_memory), update_data, thread_id)
updated_memory = _strip_upload_mentions_from_memory(updated_memory)
return get_memory_storage().save(updated_memory, agent_name, user_id=user_id)
async def aupdate_memory(
self,
messages: list[Any],
thread_id: str | None = None,
agent_name: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
user_id: str | None = None,
) -> bool:
return await asyncio.to_thread(
self._do_update_memory_sync,
messages=messages,
thread_id=thread_id,
agent_name=agent_name,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
user_id=user_id,
)
def _do_update_memory_sync(
self,
messages: list[Any],
thread_id: str | None = None,
agent_name: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
user_id: str | None = None,
) -> bool:
try:
prepared = self._prepare_update_prompt(
messages=messages,
agent_name=agent_name,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
user_id=user_id,
)
if prepared is None:
return False
current_memory, prompt = prepared
model = self._get_model()
response = model.invoke(prompt, config={"run_name": "v1_memory_agent"})
return self._finalize_update(
current_memory=current_memory,
response_content=response.content,
thread_id=thread_id,
agent_name=agent_name,
user_id=user_id,
)
except json.JSONDecodeError as e:
logger.warning("V1 memory: failed to parse LLM response: %s", e)
return False
except Exception as e: # noqa: BLE001
logger.exception("V1 memory update failed: %s", e)
return False
def update_memory(
self,
messages: list[Any],
thread_id: str | None = None,
agent_name: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
user_id: str | None = None,
) -> bool:
try:
loop = asyncio.get_running_loop()
except RuntimeError:
loop = None
if loop is not None and loop.is_running():
try:
future = _SYNC_MEMORY_UPDATER_EXECUTOR.submit(
self._do_update_memory_sync,
messages=messages,
thread_id=thread_id,
agent_name=agent_name,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
user_id=user_id,
)
return future.result()
except Exception: # noqa: BLE001
logger.exception("V1 memory: failed to offload update to executor")
return False
return self._do_update_memory_sync(
messages=messages,
thread_id=thread_id,
agent_name=agent_name,
correction_detected=correction_detected,
reinforcement_detected=reinforcement_detected,
user_id=user_id,
)
def _apply_updates(
self,
current_memory: dict[str, Any],
update_data: dict[str, Any],
thread_id: str | None = None,
) -> dict[str, Any]:
cfg = _get_v1_cfg()
now = utc_now_iso_z()
# 更新 user context 段
user_updates = update_data.get("user", {})
for section in ("workContext", "personalContext", "topOfMind"):
section_data = user_updates.get(section, {})
if section_data.get("shouldUpdate") and section_data.get("summary"):
current_memory.setdefault("user", {})[section] = {
"summary": section_data["summary"],
"updatedAt": now,
}
# 更新 history 段
history_updates = update_data.get("history", {})
for section in ("recentMonths", "earlierContext", "longTermBackground"):
section_data = history_updates.get(section, {})
if section_data.get("shouldUpdate") and section_data.get("summary"):
current_memory.setdefault("history", {})[section] = {
"summary": section_data["summary"],
"updatedAt": now,
}
# 删除事实
facts_to_remove = set(update_data.get("factsToRemove", []))
if facts_to_remove:
current_memory["facts"] = [f for f in current_memory.get("facts", []) if f.get("id") not in facts_to_remove]
# 新增事实(去重 + 置信度过滤)
existing_keys = {
key for key in (_fact_content_key(f.get("content")) for f in current_memory.get("facts", []))
if key is not None
}
for fact in update_data.get("newFacts", []):
confidence = fact.get("confidence", 0.5)
if confidence < cfg.fact_confidence_threshold:
continue
raw_content = fact.get("content", "")
if not isinstance(raw_content, str):
continue
normalized_content = raw_content.strip()
fact_key = _fact_content_key(normalized_content)
if fact_key is not None and fact_key in existing_keys:
continue
fact_entry: dict[str, Any] = {
"id": f"fact_{uuid.uuid4().hex[:8]}",
"content": normalized_content,
"category": fact.get("category", "context"),
"confidence": confidence,
"createdAt": now,
"source": thread_id or "unknown",
}
source_error = fact.get("sourceError")
if isinstance(source_error, str) and source_error.strip():
fact_entry["sourceError"] = source_error.strip()
current_memory["facts"].append(fact_entry)
if fact_key is not None:
existing_keys.add(fact_key)
# 超出上限时驱逐置信度最低的事实
if len(current_memory["facts"]) > cfg.max_facts:
current_memory["facts"] = sorted(
current_memory["facts"],
key=lambda f: f.get("confidence", 0),
reverse=True,
)[:cfg.max_facts]
return current_memory
def update_memory_from_conversation(
messages: list[Any],
thread_id: str | None = None,
agent_name: str | None = None,
correction_detected: bool = False,
reinforcement_detected: bool = False,
user_id: str | None = None,
) -> bool:
updater = MemoryUpdater()
return updater.update_memory(messages, thread_id, agent_name, correction_detected, reinforcement_detected, user_id=user_id)
__all__ = [
"MemoryUpdater",
"update_memory_from_conversation",
"get_memory_data",
"reload_memory_data",
"import_memory_data",
"clear_memory_data",
"create_memory_fact",
"delete_memory_fact",
"update_memory_fact",
]
@@ -0,0 +1,333 @@
"""Middleware for intercepting clarification requests and presenting them to the user."""
import json
import logging
from collections.abc import Callable
from hashlib import sha256
from typing import Any, override
from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
logger = logging.getLogger(__name__)
class ClarificationMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class ClarificationMiddleware(AgentMiddleware[ClarificationMiddlewareState]):
"""Intercepts clarification tool calls and interrupts execution to present questions to the user.
When the model calls the `ask_clarification` tool, this middleware:
1. Intercepts the tool call before execution
2. Extracts the clarification question and metadata
3. Formats a user-friendly message
4. Returns a Command that interrupts execution and presents the question
5. Waits for user response before continuing
This replaces the tool-based approach where clarification continued the conversation flow.
"""
state_schema = ClarificationMiddlewareState
def _stable_message_id(self, tool_call_id: str, formatted_message: str) -> str:
"""Build a deterministic message ID so retried clarification calls replace, not append."""
if tool_call_id:
return f"clarification:{tool_call_id}"
digest = sha256(formatted_message.encode("utf-8")).hexdigest()[:16]
return f"clarification:{digest}"
def _is_chinese(self, text: str) -> bool:
"""Check if text contains Chinese characters.
Args:
text: Text to check
Returns:
True if text contains Chinese characters
"""
return any("\u4e00" <= char <= "\u9fff" for char in text)
def _format_clarification_message(self, args: dict) -> str:
"""Format the clarification arguments into a user-friendly message.
Args:
args: The tool call arguments containing clarification details
Returns:
Formatted message string
"""
question = args.get("question", "")
clarification_type = args.get("clarification_type", "missing_info")
context = args.get("context")
options = self._normalize_options(args.get("options", []))
# Type-specific icons
type_icons = {
"missing_info": "❓",
"ambiguous_requirement": "🤔",
"approach_choice": "🔀",
"risk_confirmation": "⚠️",
"suggestion": "💡",
}
icon = type_icons.get(clarification_type, "❓")
# Build the message naturally
message_parts = []
# Add icon and question together for a more natural flow
if context:
# If there's context, present it first as background
message_parts.append(f"{icon} {context}")
message_parts.append(f"\n{question}")
else:
# Just the question with icon
message_parts.append(f"{icon} {question}")
# Add options in a cleaner format
if options and len(options) > 0:
message_parts.append("") # blank line for spacing
for i, option in enumerate(options, 1):
label = option.get("label") or option.get("id") or ""
message_parts.append(f" {i}. {label}")
return "\n".join(message_parts)
def _normalize_options(self, raw_options: object) -> list[dict[str, str]]:
"""Normalize model-produced options into a stable UI-friendly shape."""
options = raw_options
# Some models serialize array parameters as JSON strings instead of native arrays.
if isinstance(options, str):
try:
options = json.loads(options)
except (json.JSONDecodeError, TypeError):
options = [options]
if options is None:
values: list[object] = []
elif isinstance(options, list):
values = options
else:
values = [options]
normalized: list[dict[str, str]] = []
for index, value in enumerate(values, 1):
if isinstance(value, dict):
raw_label = value.get("label") or value.get("title") or value.get("name") or value.get("value") or value.get("id")
label = str(raw_label).strip() if raw_label is not None else ""
if not label:
continue
raw_id = value.get("id") or value.get("value") or f"option-{index}"
option = {
"id": str(raw_id).strip() or f"option-{index}",
"label": label,
}
description = value.get("description")
if description is not None and str(description).strip():
option["description"] = str(description).strip()
normalized.append(option)
else:
label = str(value).strip()
if label:
normalized.append({"id": f"option-{index}", "label": label})
return normalized
def _build_payload(self, args: dict) -> dict:
"""Build structured clarification data for rich clients."""
return {
"question": str(args.get("question", "")).strip(),
"clarification_type": args.get("clarification_type", "missing_info"),
"context": args.get("context"),
"options": self._normalize_options(args.get("options", [])),
"allow_custom": True,
"allow_multiple": resolve_allow_multiple(args),
}
def _parse_tool_args(self, tool_call: Any) -> dict[str, Any]:
args = self._tool_field(tool_call, "args") or {}
if isinstance(args, dict):
return args
if isinstance(args, str):
try:
parsed = json.loads(args)
return parsed if isinstance(parsed, dict) else {}
except (json.JSONDecodeError, TypeError):
return {}
return {}
def _handle_clarification(self, request: ToolCallRequest) -> ToolMessage:
"""Return the clarification ToolMessage without Command(goto=END).
Stopping the turn is ``after_model`` + ``jump_to=end``. Returning a
Command here used to mix with parallel tool results and loop the graph.
If the tools node still runs (jump_to not honored), a ToolMessage with
the same stable id replaces rather than appends.
"""
args = self._parse_tool_args(request.tool_call)
tool_call_id = str(self._tool_field(request.tool_call, "id") or "")
logger.info("Intercepted clarification request in wrap_tool_call")
return self._clarification_tool_message(tool_call_id, args)
def _tool_field(self, tool_call: Any, 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(self, tool_call: Any) -> str:
"""Normalize tool names from dict / object / OpenAI-style nested function."""
raw = self._tool_field(tool_call, "name")
if raw is None and isinstance(tool_call, dict):
fn = tool_call.get("function")
if isinstance(fn, dict):
raw = fn.get("name")
name = str(raw or "").strip()
if "." in name:
name = name.rsplit(".", 1)[-1]
return name
def _is_clarification_call(self, tool_call: Any) -> bool:
return self._tool_name(tool_call).casefold() == "ask_clarification"
def _clarification_tool_message(self, tool_call_id: str, args: dict[str, Any]) -> ToolMessage:
formatted_message = self._format_clarification_message(args)
return ToolMessage(
id=self._stable_message_id(tool_call_id, formatted_message),
content=formatted_message,
tool_call_id=tool_call_id,
name="ask_clarification",
additional_kwargs={"clarification": self._build_payload(args)},
)
def _after_model_intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Stop the run as soon as the model emits ask_clarification.
Applies to **all** lead-agent chats (通用问答 / 智能体 / 写作配置 / 报告结构…)。
``wrap_tool_call`` + ``Command(goto=END)`` is unreliable with parallel
tool calls (weak models often emit two clarifications, or clarification
plus another tool): the Command mixes with other tool results and the
graph loops back to the model, which then treats the question ToolMessage
as "the user still hasn't answered" and keeps generating.
"""
tool_calls = list(last.tool_calls or [])
clarification_calls = [tc for tc in tool_calls if self._is_clarification_call(tc)]
if not clarification_calls:
return None
messages: list[ToolMessage] = []
for tc in tool_calls:
name = self._tool_name(tc) or "unknown"
tool_call_id = str(self._tool_field(tc, "id") or "")
args = self._parse_tool_args(tc)
if self._is_clarification_call(tc):
messages.append(self._clarification_tool_message(tool_call_id, args))
else:
messages.append(
ToolMessage(
id=f"clarification-skip:{tool_call_id or name}",
content="已暂停:需要先等待用户回答澄清问题,本工具未执行。",
tool_call_id=tool_call_id,
name=name,
)
)
logger.info(
"Intercepted %s clarification tool call(s) in after_model; ending turn",
len(clarification_calls),
)
return {"messages": messages, "jump_to": "end"}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: ClarificationMiddlewareState,
runtime: object,
) -> dict[str, Any] | None:
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._after_model_intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: ClarificationMiddlewareState,
runtime: object,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@override
def _stub_sibling_tool(self, request: ToolCallRequest) -> ToolMessage:
name = self._tool_name(request.tool_call) or "unknown"
tool_call_id = str(self._tool_field(request.tool_call, "id") or "")
return ToolMessage(
id=f"clarification-skip:{tool_call_id or name}",
content="已暂停:需要先等待用户回答澄清问题,本工具未执行。",
tool_call_id=tool_call_id,
name=name,
)
def _request_has_sibling_clarification(self, request: ToolCallRequest) -> bool:
state = getattr(request, "state", None)
messages: Any = None
if isinstance(state, dict):
messages = state.get("messages")
elif state is not None:
getter = getattr(state, "get", None)
if callable(getter):
messages = getter("messages")
else:
messages = getattr(state, "messages", None)
if not messages:
return False
last = messages[-1]
tool_calls = getattr(last, "tool_calls", None) or []
return any(self._is_clarification_call(tc) for tc in tool_calls)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
"""Complete clarification tool calls; do not Command(goto=END).
Turn-stop is ``after_model`` + ``jump_to=end``. If the tools node still
runs, return a ToolMessage so parallel tools do not mix Commands.
"""
if self._is_clarification_call(request.tool_call):
return self._handle_clarification(request)
if self._request_has_sibling_clarification(request):
return self._stub_sibling_tool(request)
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
if self._is_clarification_call(request.tool_call):
return self._handle_clarification(request)
if self._request_has_sibling_clarification(request):
return self._stub_sibling_tool(request)
return await handler(request)
@@ -0,0 +1,149 @@
"""Middleware to fix dangling tool calls in message history.
A dangling tool call occurs when an AIMessage contains tool_calls but there are
no corresponding ToolMessages in the history (e.g., due to user interruption or
request cancellation). This causes LLM errors due to incomplete message format.
This middleware intercepts the model call to detect and patch such gaps by
inserting synthetic ToolMessages with an error indicator immediately after the
AIMessage that made the tool calls, ensuring correct message ordering.
Note: Uses wrap_model_call instead of before_model to ensure patches are inserted
at the correct positions (immediately after each dangling AIMessage), not appended
to the end of the message list as before_model + add_messages reducer would do.
"""
import json
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import ToolMessage
logger = logging.getLogger(__name__)
class DanglingToolCallMiddleware(AgentMiddleware[AgentState]):
"""Inserts placeholder ToolMessages for dangling tool calls before model invocation.
Scans the message history for AIMessages whose tool_calls lack corresponding
ToolMessages, and injects synthetic error responses immediately after the
offending AIMessage so the LLM receives a well-formed conversation.
"""
@staticmethod
def _message_tool_calls(msg) -> list[dict]:
"""Return normalized tool calls from structured fields or raw provider payloads."""
tool_calls = getattr(msg, "tool_calls", None) or []
if tool_calls:
return list(tool_calls)
raw_tool_calls = (getattr(msg, "additional_kwargs", None) or {}).get("tool_calls") or []
normalized: list[dict] = []
for raw_tc in raw_tool_calls:
if not isinstance(raw_tc, dict):
continue
function = raw_tc.get("function")
name = raw_tc.get("name")
if not name and isinstance(function, dict):
name = function.get("name")
args = raw_tc.get("args", {})
if not args and isinstance(function, dict):
raw_args = function.get("arguments")
if isinstance(raw_args, str):
try:
parsed_args = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
parsed_args = {}
args = parsed_args if isinstance(parsed_args, dict) else {}
normalized.append(
{
"id": raw_tc.get("id"),
"name": name or "unknown",
"args": args if isinstance(args, dict) else {},
}
)
return normalized
def _build_patched_messages(self, messages: list) -> list | None:
"""Return a new message list with patches inserted at the correct positions.
For each AIMessage with dangling tool_calls (no corresponding ToolMessage),
a synthetic ToolMessage is inserted immediately after that AIMessage.
Returns None if no patches are needed.
"""
# Collect IDs of all existing ToolMessages
existing_tool_msg_ids: set[str] = set()
for msg in messages:
if isinstance(msg, ToolMessage):
existing_tool_msg_ids.add(msg.tool_call_id)
# Check if any patching is needed
needs_patch = False
for msg in messages:
if getattr(msg, "type", None) != "ai":
continue
for tc in self._message_tool_calls(msg):
tc_id = tc.get("id")
if tc_id and tc_id not in existing_tool_msg_ids:
needs_patch = True
break
if needs_patch:
break
if not needs_patch:
return None
# Build new list with patches inserted right after each dangling AIMessage
patched: list = []
patched_ids: set[str] = set()
patch_count = 0
for msg in messages:
patched.append(msg)
if getattr(msg, "type", None) != "ai":
continue
for tc in self._message_tool_calls(msg):
tc_id = tc.get("id")
if tc_id and tc_id not in existing_tool_msg_ids and tc_id not in patched_ids:
patched.append(
ToolMessage(
content="[Tool call was interrupted and did not return a result.]",
tool_call_id=tc_id,
name=tc.get("name", "unknown"),
status="error",
)
)
patched_ids.add(tc_id)
patch_count += 1
logger.warning(f"Injecting {patch_count} placeholder ToolMessage(s) for dangling tool calls")
return patched
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._build_patched_messages(request.messages)
if patched is not None:
request = request.override(messages=patched)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._build_patched_messages(request.messages)
if patched is not None:
request = request.override(messages=patched)
return await handler(request)
@@ -0,0 +1,107 @@
"""Middleware to filter deferred tool schemas from model binding.
When tool_search is enabled, MCP tools are registered in the DeferredToolRegistry
and passed to ToolNode for execution, but their schemas should NOT be sent to the
LLM via bind_tools (that's the whole point of deferral — saving context tokens).
This middleware intercepts wrap_model_call and removes deferred tools from
request.tools so that model.bind_tools only receives active tool schemas.
The agent discovers deferred tools at runtime via the tool_search tool.
"""
import logging
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
logger = logging.getLogger(__name__)
class DeferredToolFilterMiddleware(AgentMiddleware[AgentState]):
"""Remove deferred tools from request.tools before model binding.
ToolNode still holds all tools (including deferred) for execution routing,
but the LLM only sees active tool schemas — deferred tools are discoverable
via tool_search at runtime.
"""
def _filter_tools(self, request: ModelRequest) -> ModelRequest:
from deerflow.tools.builtins.tool_search import get_deferred_registry
registry = get_deferred_registry()
if not registry:
return request
deferred_names = registry.deferred_names
active_tools = [t for t in request.tools if getattr(t, "name", None) not in deferred_names]
if len(active_tools) < len(request.tools):
logger.debug(f"Filtered {len(request.tools) - len(active_tools)} deferred tool schema(s) from model binding")
return request.override(tools=active_tools)
def _blocked_tool_message(self, request: ToolCallRequest) -> ToolMessage | None:
from deerflow.tools.builtins.tool_search import get_deferred_registry
registry = get_deferred_registry()
if not registry:
return None
tool_name = str(request.tool_call.get("name") or "")
if not tool_name:
return None
if not registry.contains(tool_name):
return None
tool_call_id = str(request.tool_call.get("id") or "missing_tool_call_id")
return ToolMessage(
content=(f"Error: Tool '{tool_name}' is deferred and has not been promoted yet. Call tool_search first to expose and promote this tool's schema, then retry."),
tool_call_id=tool_call_id,
name=tool_name,
status="error",
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._filter_tools(request))
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
blocked = self._blocked_tool_message(request)
if blocked is not None:
return blocked
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._filter_tools(request))
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
blocked = self._blocked_tool_message(request)
if blocked is not None:
return blocked
return await handler(request)
@@ -0,0 +1,382 @@
"""Hard runtime policy for the built-in forced-research responder.
The ordinary custom-agent skill allowlist only makes skills visible to the
model; it does not guarantee that a model will use one before answering. This
middleware turns that behavioural preference into a per-user-turn runtime
contract:
* before a successful information-gathering tool result exists, every model
call is made with ``tool_choice=required``;
* a provider that ignores ``tool_choice`` and emits text is sent back to the
model node (with the premature text hidden);
* after a bounded number of failed attempts the model may only report the
collection failure instead of looping forever;
* ``write_file`` / ``str_replace`` are restricted to temporary ``.py`` files
under ``/mnt/user-data/workspace`` and ``bash`` may only execute Python
scripts. Markdown/document deliverables and ``present_files`` are denied.
The policy is mounted only for :data:`FORCED_RESEARCH_AGENT_ID`.
"""
from __future__ import annotations
import json
import re
from collections.abc import Awaitable, Callable
from copy import deepcopy
from pathlib import PurePosixPath
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
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
FORCED_RESEARCH_AGENT_ID = "forced-research-responder"
_WORKSPACE_PREFIX = "/mnt/user-data/workspace"
_MAX_COLLECTION_ATTEMPTS = 8
# These tools prepare/discover capabilities but do not themselves return the
# information requested by the user. Unknown tools (not in this set) are
# intentionally accepted so configured MCP/skill-specific retrieval tools work.
_NON_EVIDENCE_TOOLS = {
"agent_orchestration",
"ask_clarification",
"bash",
"glob",
"grep",
"ls",
"memory",
"present_files",
"read_file",
"scheduled_task",
"search_skills",
"skill_list",
"skill_manage",
"skill_view",
"str_replace",
"task",
"tool_search",
"write_file",
"write_todos",
}
_TOOLS_REMOVED_FROM_FORCED_RESEARCH = {
"agent_orchestration",
"ask_clarification",
"memory",
"present_files",
"scheduled_task",
"skill_manage",
"task",
}
_FAILED_RESULT_MARKERS = (
"error:",
"no results found",
"no result found",
"success\": false",
"success': false",
"未找到",
"没有找到",
"检索失败",
"查询失败",
)
_FORCE_COLLECTION_TEXT = """<forced_research_gate>
【运行时强制】本轮尚未取得任何有效的信息采集结果,禁止直接回答用户。
请先分析用户意图,拆分检索方向和具体检索词,然后立即调用已配置技能所需的工具、检索工具、知识库工具或技能 Python 脚本。
读取 SKILL.md、搜索技能、编写临时 Python 脚本都只是准备步骤,不能替代实际信息采集。
至少取得一次有效工具结果后,才能按照用户指定的格式直接在聊天中回答。
</forced_research_gate>"""
_COLLECTION_FAILED_TEXT = """<forced_research_gate>
【运行时强制】本轮已经多次尝试调用工具,但仍未取得有效的信息采集结果。
现在不要继续循环,也不得凭模型记忆补写事实。请直接用用户要求的格式如实说明本轮检索失败、已经尝试的方向以及仍缺少的信息。
禁止生成或呈现任何文件。
</forced_research_gate>"""
def filter_forced_research_tools(tools: list[Any]) -> list[Any]:
"""Remove unrelated/write-capable built-ins while retaining skill tools.
``write_file`` and ``str_replace`` stay available because the policy below
narrows them to temporary Python source files. ``bash`` stays available so
script-backed skills can execute their own or those temporary scripts.
"""
return [tool for tool in tools if getattr(tool, "name", "") not in _TOOLS_REMOVED_FROM_FORCED_RESEARCH]
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 _normalized_container_path(value: object) -> str:
text = str(value or "").strip().replace("\\", "/")
if not text:
return ""
try:
return str(PurePosixPath(text))
except Exception: # noqa: BLE001 - invalid model-provided path is denied
return ""
def _is_workspace_python_path(value: object) -> bool:
path = _normalized_container_path(value)
return path.startswith(f"{_WORKSPACE_PREFIX}/") and path.lower().endswith(".py")
_PYTHON_EXECUTABLE_RE = re.compile(r"(?:^|[\s;&|])(?:python(?:3(?:\.\d+)?)?|py)(?:\.exe)?(?:\s|$)", re.IGNORECASE)
_PYTHON_FILE_RE = re.compile(r"(?:^|[\s\"'])([^\s\"']+\.py)(?=$|[\s\"'])", re.IGNORECASE)
_SHELL_WRITE_RE = re.compile(r"(?:>|\b(?:tee|touch|cp|mv|rm|del|erase|out-file|set-content|add-content)\b)", re.IGNORECASE)
_FORBIDDEN_DELIVERABLE_RE = re.compile(r"(?:/mnt/user-data/outputs|\.(?:md|markdown|docx?|pdf|xlsx?|pptx?|html?)(?:\s|$|[\"']))", re.IGNORECASE)
def _validate_python_command(command: object) -> str | None:
text = str(command or "").strip()
if not text:
return "bash 仅允许执行技能所需的 Python 脚本,command 不能为空。"
if _FORBIDDEN_DELIVERABLE_RE.search(text):
return "禁止通过 bash 创建、修改或处理 Markdown/文档交付物及 outputs 目录。"
if _SHELL_WRITE_RE.search(text):
return "bash 仅允许执行 Python 脚本,禁止使用 shell 重定向或文件管理命令。"
if not _PYTHON_EXECUTABLE_RE.search(text) or not _PYTHON_FILE_RE.search(text):
return "bash 仅允许执行 .py 脚本(例如 cd <技能目录> && python scripts/search.py ...)。"
return None
def validate_forced_research_tool_call(tool_call: object) -> str | None:
"""Return a rejection reason, or ``None`` when the call is permitted."""
name = str(_tool_field(tool_call, "name", "") or "")
args = _normalize_args(_tool_field(tool_call, "args", {}))
if name == "present_files":
return "本智能体只在聊天中输出,禁止呈现沙箱文件。"
if name in {"write_file", "str_replace"}:
if not _is_workspace_python_path(args.get("path")):
return "只允许在 /mnt/user-data/workspace/ 下创建或修改临时 .py 文件。"
if name == "bash":
return _validate_python_command(args.get("command"))
return None
def _is_visible_human(message: Any) -> bool:
if not isinstance(message, HumanMessage):
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get("hide_from_ui"):
return False
return getattr(message, "name", None) != "forced_research_gate"
def _turn_start(messages: list[Any]) -> int:
for index in range(len(messages) - 1, -1, -1):
if _is_visible_human(messages[index]):
return index
return 0
def _call_map(messages: list[Any], start: int) -> dict[str, tuple[str, dict[str, Any]]]:
calls: dict[str, tuple[str, dict[str, Any]]] = {}
for message in messages[start:]:
if not isinstance(message, AIMessage):
continue
for call in message.tool_calls or []:
call_id = str(_tool_field(call, "id", "") or "")
if call_id:
calls[call_id] = (
str(_tool_field(call, "name", "") or ""),
_normalize_args(_tool_field(call, "args", {})),
)
return calls
def _tool_result_succeeded(message: ToolMessage) -> bool:
status = str(getattr(message, "status", "") or "").lower()
if status == "error":
return False
content = str(getattr(message, "content", "") or "").strip()
if not content:
return False
lowered = content.lower()
return not any(marker in lowered for marker in _FAILED_RESULT_MARKERS)
def _is_information_result(name: str, args: dict[str, Any], message: ToolMessage) -> bool:
if name in _NON_EVIDENCE_TOOLS:
if name == "read_file":
path = str(args.get("path") or "").replace("\\", "/").lower()
if path.endswith("/skill.md") or path.endswith(".py"):
return False
elif name == "bash":
# bash is evidence only when it actually executed a Python skill
# script; policy validation has already rejected other commands.
if _validate_python_command(args.get("command")) is not None:
return False
else:
return False
return _tool_result_succeeded(message)
def _turn_collection_state(messages: list[Any]) -> tuple[bool, int]:
start = _turn_start(messages)
calls = _call_map(messages, start)
attempts = 0
for message in messages[start:]:
if not isinstance(message, ToolMessage):
continue
call_id = str(getattr(message, "tool_call_id", "") or "")
call = calls.get(call_id)
if call is None:
continue
attempts += 1
if _is_information_result(call[0], call[1], message):
return True, attempts
return False, attempts
def _hidden_reminder(text: str) -> HumanMessage:
return HumanMessage(
name="forced_research_gate",
content=text,
additional_kwargs={"hide_from_ui": True, "lc_source": "forced_research_gate"},
)
class ForcedResearchMiddleware(AgentMiddleware[AgentState]):
"""Require information collection and enforce temporary-Python-only IO."""
state_schema = AgentState
def _patch_model_request(self, request: ModelRequest) -> ModelRequest:
messages = list(request.messages or [])
collected, attempts = _turn_collection_state(messages)
if collected:
return request
if attempts >= _MAX_COLLECTION_ATTEMPTS:
return request.override(messages=[*messages, _hidden_reminder(_COLLECTION_FAILED_TEXT)])
return request.override(
messages=[*messages, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
tool_choice="required",
)
def _prevent_premature_exit(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) or last.tool_calls:
return None
collected, attempts = _turn_collection_state(messages)
if collected or attempts >= _MAX_COLLECTION_ATTEMPTS:
return None
# Some OpenAI-compatible gateways ignore ``tool_choice=required``.
# Hide/blank that premature answer and explicitly jump back to model.
additional_kwargs = dict(last.additional_kwargs or {})
additional_kwargs["hide_from_ui"] = True
additional_kwargs["lc_source"] = "forced_research_suppressed_answer"
response_metadata = deepcopy(last.response_metadata or {})
if response_metadata.get("finish_reason") == "stop":
response_metadata["finish_reason"] = "tool_calls"
suppressed = last.model_copy(
update={
"content": "",
"additional_kwargs": additional_kwargs,
"response_metadata": response_metadata,
}
)
return {
"jump_to": "model",
"messages": [suppressed, _hidden_reminder(_FORCE_COLLECTION_TEXT)],
}
def _reject_tool_call(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
reason = validate_forced_research_tool_call(tool_call)
if reason is None:
return None
return ToolMessage(
content=f"Error: {reason}",
tool_call_id=str(_tool_field(tool_call, "id", "") or ""),
name=str(_tool_field(tool_call, "name", "") or ""),
status="error",
)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._patch_model_request(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._patch_model_request(request))
@hook_config(can_jump_to=["model"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@hook_config(can_jump_to=["model"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
return self._prevent_premature_exit(state)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_tool_call(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_tool_call(request)
if rejected is not None:
return rejected
return await handler(request)
__all__ = [
"FORCED_RESEARCH_AGENT_ID",
"ForcedResearchMiddleware",
"filter_forced_research_tools",
"validate_forced_research_tool_call",
]
@@ -0,0 +1,190 @@
"""KnowledgeRagMiddleware — inject knowledge-base recall before the model call.
Phase 2 of the product knowledge base. When enabled (per-conversation runtime
flag ``knowledge_rag_enabled``, falling back to the global
``knowledge.rag_enabled`` config), the latest user question is used to retrieve
the most relevant knowledge notes, which are injected as a transient
``<knowledge-context>`` system message — not persisted to state, so it never
leaks to the frontend transcript.
Retrieval is hybrid (vector + keyword) when an embedding endpoint is
configured, else keyword/wiki-query layered search. Failures are swallowed: RAG
must never break a conversation.
"""
from __future__ import annotations
import asyncio
import logging
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
_TAG = "knowledge-context"
def _coerce_text(content: Any) -> str:
if isinstance(content, str):
return content
if isinstance(content, list):
parts = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text", "")))
return " ".join(parts)
return str(content or "")
def _latest_human_text(messages: list) -> str:
for msg in reversed(messages or []):
if isinstance(msg, HumanMessage):
return _coerce_text(msg.content).strip()
return ""
class KnowledgeRagMiddleware(AgentMiddleware[AgentState]):
"""Inject knowledge-base recall as transient system context."""
state_schema = AgentState
def __init__(self, *, limit: int = 5, default_enabled: bool = False) -> None:
super().__init__()
self._limit = limit
self._default_enabled = default_enabled
self._service = None # lazy
def _get_service(self):
if self._service is not None:
return self._service
try:
from deerflow.config import get_app_config
from deerflow.knowledge import make_knowledge_service
from deerflow.persistence.engine import get_session_factory
config = get_app_config()
self._service = make_knowledge_service(get_session_factory(), config.knowledge)
except Exception:
logger.exception("KnowledgeRagMiddleware: failed to build knowledge service")
self._service = None
return self._service
def _enabled_for(self, request: Any) -> bool:
runtime = getattr(request, "runtime", None)
if runtime is not None and getattr(runtime, "context", None):
flag = runtime.context.get("knowledge_rag_enabled")
if flag is not None:
return bool(flag)
return self._default_enabled
async def _build_context_message(self, request: Any) -> HumanMessage | None:
if not self._enabled_for(request):
return None
service = self._get_service()
if service is None:
return None
query = _latest_human_text(getattr(request, "messages", None) or [])
if not query:
return None
try:
result = await service.build_rag_context(query, limit=self._limit)
except Exception:
logger.exception("KnowledgeRagMiddleware: recall failed (non-fatal)")
return None
text = result.get("text") if isinstance(result, dict) else ""
if not text:
return None
fenced = (
f"<{_TAG}>\n"
"[系统提示:以下是知识库召回的背景资料,不是用户的新输入。回答时优先参考,"
"并在使用到时标注来源 note_id。]\n\n"
f"{text}\n"
f"</{_TAG}>"
)
return HumanMessage(content=fenced)
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
msg = await self._build_context_message(request)
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return await handler(request)
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
# Sync path: best-effort. The gateway runtime is async, so this is rarely
# hit; run the async recall in a private loop when there is none.
if not self._enabled_for(request):
return handler(request)
try:
loop = asyncio.get_event_loop()
if loop.is_running():
# Cannot block a running loop from sync code; skip injection.
return handler(request)
msg = loop.run_until_complete(self._build_context_message(request))
except Exception:
msg = None
if msg is not None:
request = request.override(messages=[*request.messages, msg])
return handler(request)
# ---- after_agent: enqueue background auto-sedimentation -------------
def _resolve_thread_id(self, runtime: Runtime | None) -> str | None:
if runtime is not None and getattr(runtime, "context", None):
tid = runtime.context.get("thread_id")
if tid:
return str(tid)
try:
from langgraph.config import get_config
return get_config().get("configurable", {}).get("thread_id")
except Exception:
return None
@override
def after_agent(self, state: AgentState, runtime: Runtime) -> dict | None:
"""When auto-ingest is on, hand the finished turn to the background queue."""
try:
from deerflow.config import get_app_config
knowledge_cfg = getattr(get_app_config(), "knowledge", None)
if knowledge_cfg is None or not knowledge_cfg.enabled or not knowledge_cfg.auto_ingest_enabled:
return None
from deerflow.knowledge.auto_ingest import AutoIngestItem, get_auto_ingest_queue
queue = get_auto_ingest_queue()
if queue is None:
return None
messages = state.get("messages") if isinstance(state, dict) else getattr(state, "messages", None)
if not messages:
return None
from deerflow.runtime.references import build_reference_batches
from deerflow.runtime.serialization import serialize_lc_object
from deerflow.runtime.user_context import get_effective_user_id
serialized = [serialize_lc_object(m) for m in messages]
thread_id = self._resolve_thread_id(runtime)
if not thread_id:
return None
title = state.get("title") if isinstance(state, dict) else getattr(state, "title", None)
queue.enqueue(
AutoIngestItem(
thread_id=thread_id,
user_id=get_effective_user_id(),
messages=serialized,
thread_title=title if isinstance(title, str) else None,
reference_batches=build_reference_batches(serialized),
)
)
except Exception:
logger.exception("KnowledgeRagMiddleware.after_agent enqueue failed (non-fatal)")
return None
@@ -0,0 +1,464 @@
"""LLM error handling middleware with retry/backoff and user-facing fallbacks."""
from __future__ import annotations
import asyncio
import logging
import threading
import time
from collections.abc import Awaitable, Callable
from email.utils import parsedate_to_datetime
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import (
ModelCallResult,
ModelRequest,
ModelResponse,
)
from langchain_core.messages import AIMessage
from langgraph.errors import GraphBubbleUp
from deerflow.config.app_config import AppConfig
logger = logging.getLogger(__name__)
# 兜底/熔断的 AIMessage 会带上 ``additional_kwargs[LLM_ERROR_MARKER] = reason``,
# 让下游(圆桌会商的单轮执行器等)能**可靠识别**「这条 AI 回复其实是模型调用失败的
# 兜底文案」而不是真实交付——据此触发自动换模型。``reason`` ∈ {quota, auth, busy,
# transient, upstream, generic, circuit}。注意:model_dump() 会保留 additional_kwargs,
# 故经 checkpointer 序列化后仍在;万一被剥离,``is_llm_error_message`` 还会回退按已知
# 兜底文案精确匹配。
LLM_ERROR_MARKER = "deerflow_llm_error"
# 各 reason 对应的用户可见兜底文案(单一数据源:构造与识别都用它)。
_USER_MESSAGES: dict[str, str] = {
"quota": "大模型因账户额度不足、账单异常或使用受限而拒绝请求,请检查模型账户后再试。",
"auth": "大模型因鉴权失败或无访问权限而拒绝请求,请检查模型的 API Key 与权限配置后再试。",
"busy": "大模型服务暂时繁忙,多次自动重试后仍未恢复,请稍候再继续。",
"transient": "大模型响应暂时中断或超时,多次自动重试后仍未恢复,请稍候再继续。",
"upstream": "大模型当前响应异常(上游模型或网关临时故障),多次重试后仍未恢复,请稍后再试或更换模型。",
"generic": "大模型本次调用未能成功完成,请稍后再试或更换模型。",
}
_CIRCUIT_MESSAGE = "大模型因连续多次调用失败已被熔断保护,请稍候再试。"
# 全部兜底文案集合,供 ``is_llm_error_message`` 在 additional_kwargs 被剥离时按正文回退识别。
_ALL_ERROR_MESSAGES: frozenset[str] = frozenset({*_USER_MESSAGES.values(), _CIRCUIT_MESSAGE})
def is_llm_error_message(message: Any) -> str | None:
"""判断一条 AI 消息是否为「模型调用失败的兜底文案」,是则返回 reason,否则 None。
入参可为 LangChain ``BaseMessage``,或 checkpointer 序列化后的 dict(两种都支持)。
优先看 ``additional_kwargs[LLM_ERROR_MARKER]``(最可靠);万一被序列化剥离,再回退
按正文是否精确等于已知兜底文案识别(容忍前后空白)。
"""
if message is None:
return None
# additional_kwargs(dict 或对象属性两种形态)。
extra: Any = None
if isinstance(message, dict):
extra = message.get("additional_kwargs")
else:
extra = getattr(message, "additional_kwargs", None)
if isinstance(extra, dict):
reason = extra.get(LLM_ERROR_MARKER)
if reason:
return str(reason)
# 正文回退匹配。
if isinstance(message, dict):
content = message.get("content")
else:
content = getattr(message, "content", None)
text = ""
if isinstance(content, str):
text = content
elif isinstance(content, list):
text = "\n".join(p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text")
text = text.strip()
if text and text in _ALL_ERROR_MESSAGES:
return "generic"
return None
_RETRIABLE_STATUS_CODES = {408, 409, 425, 429, 500, 502, 503, 504}
_BUSY_PATTERNS = (
"server busy",
"temporarily unavailable",
"try again later",
"please retry",
"please try again",
"overloaded",
"high demand",
"rate limit",
"负载较高",
"服务繁忙",
"稍后重试",
"请稍后重试",
)
_QUOTA_PATTERNS = (
"insufficient_quota",
"quota",
"billing",
"credit",
"payment",
"余额不足",
"超出限额",
"额度不足",
"欠费",
)
_AUTH_PATTERNS = (
"authentication",
"unauthorized",
"invalid api key",
"invalid_api_key",
"permission",
"forbidden",
"access denied",
"无权",
"未授权",
)
# Upstream model gateway returned a malformed payload (typically a JSON decode
# error wrapped as `bad_response_status_code`, or a truncated/garbled inference
# response). These are almost always transient inference-side issues and safe
# to retry.
_UPSTREAM_GARBAGE_PATTERNS = (
"bad_response_status_code",
"bad response status",
"expecting ',' delimiter",
"expecting value",
"expecting property name",
"unexpected character",
"unterminated string",
"extra data",
"jsondecodeerror",
)
class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
"""Retry transient LLM errors and surface graceful assistant messages."""
retry_max_attempts: int = 3
retry_base_delay_ms: int = 1000
retry_cap_delay_ms: int = 8000
def __init__(self, *, app_config: AppConfig, **kwargs: Any) -> None:
super().__init__(**kwargs)
self.circuit_failure_threshold = app_config.circuit_breaker.failure_threshold
self.circuit_recovery_timeout_sec = app_config.circuit_breaker.recovery_timeout_sec
# Circuit Breaker state
self._circuit_lock = threading.Lock()
self._circuit_failure_count = 0
self._circuit_open_until = 0.0
self._circuit_state = "closed"
self._circuit_probe_in_flight = False
def _check_circuit(self) -> bool:
"""Returns True if circuit is OPEN (fast fail), False otherwise."""
with self._circuit_lock:
now = time.time()
if self._circuit_state == "open":
if now < self._circuit_open_until:
return True
self._circuit_state = "half_open"
self._circuit_probe_in_flight = False
if self._circuit_state == "half_open":
if self._circuit_probe_in_flight:
return True
self._circuit_probe_in_flight = True
return False
return False
def _record_success(self) -> None:
with self._circuit_lock:
if self._circuit_state != "closed" or self._circuit_failure_count > 0:
logger.info("Circuit breaker reset (Closed). LLM service recovered.")
self._circuit_failure_count = 0
self._circuit_open_until = 0.0
self._circuit_state = "closed"
self._circuit_probe_in_flight = False
def _record_failure(self) -> None:
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
self._circuit_state = "open"
self._circuit_probe_in_flight = False
logger.error(
"Circuit breaker probe failed (Open). Will probe again after %ds.",
self.circuit_recovery_timeout_sec,
)
return
self._circuit_failure_count += 1
if self._circuit_failure_count >= self.circuit_failure_threshold:
self._circuit_open_until = time.time() + self.circuit_recovery_timeout_sec
if self._circuit_state != "open":
self._circuit_state = "open"
self._circuit_probe_in_flight = False
logger.error(
"Circuit breaker tripped (Open). Threshold reached (%d). Will probe after %ds.",
self.circuit_failure_threshold,
self.circuit_recovery_timeout_sec,
)
def _classify_error(self, exc: BaseException) -> tuple[bool, str]:
detail = _extract_error_detail(exc)
lowered = detail.lower()
error_code = _extract_error_code(exc)
error_code_lower = str(error_code).lower() if error_code is not None else ""
status_code = _extract_status_code(exc)
if _matches_any(lowered, _QUOTA_PATTERNS) or _matches_any(error_code_lower, _QUOTA_PATTERNS):
return False, "quota"
if _matches_any(lowered, _AUTH_PATTERNS):
return False, "auth"
exc_name = exc.__class__.__name__
if exc_name in {
"APITimeoutError",
"APIConnectionError",
"InternalServerError",
"ReadError", # httpx.ReadError: connection dropped mid-stream
"RemoteProtocolError", # httpx: server closed connection unexpectedly
# httpx.TimeoutException family escapes the streaming path unwrapped
# (seen live: httpx.ReadTimeout mid-generation after 200 OK — the
# provider stalled ~17s; that must retry, not fail the whole run).
"ReadTimeout",
"ConnectTimeout",
"WriteTimeout",
"PoolTimeout",
"TimeoutError", # asyncio chunk timeout / builtin timeout
"ConnectError", # httpx: connection refused / DNS blip
}:
return True, "transient"
if status_code in _RETRIABLE_STATUS_CODES:
return True, "transient"
if _matches_any(lowered, _BUSY_PATTERNS):
return True, "busy"
# Treat upstream gateway garbage (malformed JSON, truncated responses)
# as a retriable transient — the deterministic char-position errors we
# see from vLLM/proxy layers usually clear on a re-roll.
if _matches_any(lowered, _UPSTREAM_GARBAGE_PATTERNS) or _matches_any(error_code_lower, _UPSTREAM_GARBAGE_PATTERNS):
return True, "upstream"
return False, "generic"
def _build_retry_delay_ms(self, attempt: int, exc: BaseException) -> int:
retry_after = _extract_retry_after_ms(exc)
if retry_after is not None:
return retry_after
backoff = self.retry_base_delay_ms * (2 ** max(0, attempt - 1))
return min(backoff, self.retry_cap_delay_ms)
def _build_retry_message(self, attempt: int, wait_ms: int, reason: str) -> str:
seconds = max(1, round(wait_ms / 1000))
if reason == "busy":
reason_text = "服务繁忙"
elif reason == "upstream":
reason_text = "上游响应异常"
else:
reason_text = "响应中断或超时"
return f"大模型因{reason_text}暂未返回,正在第 {attempt}/{self.retry_max_attempts} 次自动重试,{seconds} 秒后继续…"
def _build_circuit_breaker_message(self) -> str:
return _CIRCUIT_MESSAGE
def _build_user_message(self, reason: str) -> str:
# NOTE: We intentionally do NOT embed the raw exception detail into the
# user-facing message. Raw `Error code: 400 - {...}` strings — especially
# Python repr-style dict literals — get persisted as AI messages and then
# re-fed to the model on the next turn, where their unescaped quotes /
# braces can corrupt the upstream JSON payload and cause deterministic
# JSONDecodeError loops. Keep the user message clean; full detail is
# already in the backend log via `logger.warning(..., exc_info=exc)`.
return _USER_MESSAGES.get(reason, _USER_MESSAGES["generic"])
def _error_message(self, content: str, reason: str) -> AIMessage:
"""构造带 ``LLM_ERROR_MARKER`` 标记的兜底 AIMessage(供下游识别+换模型)。"""
return AIMessage(content=content, additional_kwargs={LLM_ERROR_MARKER: reason})
def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
try:
from langgraph.config import get_stream_writer
writer = get_stream_writer()
writer(
{
"type": "llm_retry",
"attempt": attempt,
"max_attempts": self.retry_max_attempts,
"wait_ms": wait_ms,
"reason": reason,
"message": self._build_retry_message(attempt, wait_ms, reason),
}
)
except Exception:
logger.debug("Failed to emit llm_retry event", exc_info=True)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
if self._check_circuit():
return self._error_message(self._build_circuit_breaker_message(), "circuit")
attempt = 1
while True:
try:
response = handler(request)
self._record_success()
return response
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_probe_in_flight = False
raise
except Exception as exc:
retriable, reason = self._classify_error(exc)
if retriable and attempt < self.retry_max_attempts:
wait_ms = self._build_retry_delay_ms(attempt, exc)
logger.warning(
"Transient LLM error on attempt %d/%d; retrying in %dms: %s",
attempt,
self.retry_max_attempts,
wait_ms,
_extract_error_detail(exc),
)
self._emit_retry_event(attempt, wait_ms, reason)
time.sleep(wait_ms / 1000)
attempt += 1
continue
logger.warning(
"LLM call failed after %d attempt(s): %s",
attempt,
_extract_error_detail(exc),
exc_info=exc,
)
if retriable:
self._record_failure()
return self._error_message(self._build_user_message(reason), reason)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
if self._check_circuit():
return self._error_message(self._build_circuit_breaker_message(), "circuit")
attempt = 1
while True:
try:
response = await handler(request)
self._record_success()
return response
except GraphBubbleUp:
# Preserve LangGraph control-flow signals (interrupt/pause/resume).
with self._circuit_lock:
if self._circuit_state == "half_open":
self._circuit_probe_in_flight = False
raise
except Exception as exc:
retriable, reason = self._classify_error(exc)
if retriable and attempt < self.retry_max_attempts:
wait_ms = self._build_retry_delay_ms(attempt, exc)
logger.warning(
"Transient LLM error on attempt %d/%d; retrying in %dms: %s",
attempt,
self.retry_max_attempts,
wait_ms,
_extract_error_detail(exc),
)
self._emit_retry_event(attempt, wait_ms, reason)
await asyncio.sleep(wait_ms / 1000)
attempt += 1
continue
logger.warning(
"LLM call failed after %d attempt(s): %s",
attempt,
_extract_error_detail(exc),
exc_info=exc,
)
if retriable:
self._record_failure()
return self._error_message(self._build_user_message(reason), reason)
def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
return any(pattern in detail for pattern in patterns)
def _extract_error_code(exc: BaseException) -> Any:
for attr in ("code", "error_code"):
value = getattr(exc, attr, None)
if value not in (None, ""):
return value
body = getattr(exc, "body", None)
if isinstance(body, dict):
error = body.get("error")
if isinstance(error, dict):
for key in ("code", "type"):
value = error.get(key)
if value not in (None, ""):
return value
return None
def _extract_status_code(exc: BaseException) -> int | None:
for attr in ("status_code", "status"):
value = getattr(exc, attr, None)
if isinstance(value, int):
return value
response = getattr(exc, "response", None)
status = getattr(response, "status_code", None)
return status if isinstance(status, int) else None
def _extract_retry_after_ms(exc: BaseException) -> int | None:
response = getattr(exc, "response", None)
headers = getattr(response, "headers", None)
if headers is None:
return None
raw = None
header_name = ""
for key in ("retry-after-ms", "Retry-After-Ms", "retry-after", "Retry-After"):
header_name = key
if hasattr(headers, "get"):
raw = headers.get(key)
if raw:
break
if not raw:
return None
try:
multiplier = 1 if "ms" in header_name.lower() else 1000
return max(0, int(float(raw) * multiplier))
except (TypeError, ValueError):
try:
target = parsedate_to_datetime(str(raw))
delta = target.timestamp() - time.time()
return max(0, int(delta * 1000))
except (TypeError, ValueError, OverflowError):
return None
def _extract_error_detail(exc: BaseException) -> str:
detail = str(exc).strip()
if detail:
return detail
message = getattr(exc, "message", None)
if isinstance(message, str) and message.strip():
return message.strip()
return exc.__class__.__name__
@@ -0,0 +1,331 @@
"""Middleware that records per-LLM-call metrics for the admin audit page.
Captures **every** provider invocation regardless of the frontend speed-meter
toggle: the goal is a complete admin-side audit log of LLM usage, including
failures. The user-facing speed indicator (controlled by
``LocalSettings.display.streamSpeedMeterEnabled``) is a separate, purely
cosmetic feature — turning it off does not stop this recording.
Each call ends with one row in ``llm_call_metrics``:
- Successes record duration, token counts, and ``tokens_per_sec``.
- Errors record the duration spent before the failure, the exception class as
``error_type`` and a one-line ``error_message``.
Writes go through a best-effort store: a DB outage logs a warning and the
agent runtime keeps streaming. We intentionally place this middleware
*inside* :class:`LLMErrorHandlingMiddleware` (i.e. nested deeper in the
``wrap_model_call`` chain) so we observe the **real** provider call timings —
not the retry-wrapped successful response.
"""
from __future__ import annotations
import logging
import time
import uuid
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import (
ModelCallResult,
ModelRequest,
ModelResponse,
)
from langchain_core.messages import AIMessage
from langgraph.errors import GraphBubbleUp
from deerflow.persistence.engine import fire_and_forget_db_write, get_session_factory
from deerflow.persistence.llm_metrics import LlmMetricRecord, make_llm_metrics_store
from deerflow.persistence.llm_metrics.base import LlmMetricsStore
from deerflow.runtime.user_context import get_effective_user_id
logger = logging.getLogger(__name__)
def _now() -> datetime:
return datetime.now(UTC)
def _safe_get_thread_id(request: ModelRequest) -> str | None:
state = getattr(request, "state", None)
if isinstance(state, dict):
thread_id = state.get("thread_id")
if isinstance(thread_id, str) and thread_id:
return thread_id
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
config = getattr(runtime, "config", None)
configurable = (config or {}).get("configurable", {}) if isinstance(config, dict) else {}
thread_id = configurable.get("thread_id") if isinstance(configurable, dict) else None
if isinstance(thread_id, str) and thread_id:
return thread_id
return None
def _safe_get_run_id(request: ModelRequest) -> str | None:
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in ("run_id", "langgraph_run_id"):
value = context.get(key)
if isinstance(value, str) and value:
return value
config = getattr(runtime, "config", None)
if isinstance(config, dict):
metadata = config.get("metadata") if isinstance(config.get("metadata"), dict) else {}
if isinstance(metadata, dict):
for key in ("run_id", "langgraph_run_id"):
value = metadata.get(key)
if isinstance(value, str) and value:
return value
return None
def _safe_get_model_name(request: ModelRequest) -> str | None:
model = getattr(request, "model", None)
for attr in ("model_name", "model", "name"):
value = getattr(model, attr, None)
if isinstance(value, str) and value:
return value
return None
def _safe_get_agent_name(request: ModelRequest) -> str | None:
runtime = getattr(request, "runtime", None)
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in ("agent_name", "agent_id"):
value = context.get(key)
if isinstance(value, str) and value:
return value
return None
def _coerce_int(value: Any) -> int | None:
if isinstance(value, bool):
return None
if isinstance(value, int):
return value
if isinstance(value, float):
return int(value)
if isinstance(value, str):
try:
return int(value)
except (TypeError, ValueError):
return None
return None
def _extract_usage(response: Any) -> dict[str, int]:
"""Pull token counts out of an AIMessage, falling back to provider-native shapes.
The handler in ``wrap_model_call`` actually hands us a
:class:`langchain.agents.middleware.types.ModelResponse` dataclass whose
``.result`` is a ``list[BaseMessage]``. Earlier versions of this helper
only matched ``AIMessage`` and ``list``, which meant we silently dropped
every successful call and stored None for input/output/total. To stay
robust we now also handle ``ModelResponse`` (and ``ExtendedModelResponse``,
which wraps a ModelResponse), and we walk the messages list for the first
``AIMessage``.
LangChain normalises usage into ``message.usage_metadata`` with the keys
``input_tokens`` / ``output_tokens`` / ``total_tokens``. Several
OpenAI-compatible providers (DeepSeek, vLLM, some Azure deployments) leave
that dict partial — typically only ``total_tokens`` is populated — and the
real breakdown sits under ``response_metadata.token_usage`` with the
provider-native key names ``prompt_tokens`` / ``completion_tokens``. We
merge both so the admin audit view always has the most complete numbers
available.
"""
message: AIMessage | None = None
def _find_ai(candidate: Any) -> AIMessage | None:
if isinstance(candidate, AIMessage):
return candidate
if isinstance(candidate, list):
for item in candidate:
found = _find_ai(item)
if found is not None:
return found
return None
message = _find_ai(response)
if message is None:
# ModelResponse / ExtendedModelResponse — defined as dataclasses with a
# ``result`` field holding ``list[BaseMessage]``. Recurse via attribute
# access so we don't tightly couple to the dataclass class itself.
for attr in ("result", "model_response"):
inner = getattr(response, attr, None)
if inner is None:
continue
message = _find_ai(inner)
if message is None and attr == "model_response":
inner_result = getattr(inner, "result", None)
message = _find_ai(inner_result)
if message is not None:
break
if message is None:
return {}
out: dict[str, int] = {}
usage = getattr(message, "usage_metadata", None) or {}
if isinstance(usage, dict):
for key in ("input_tokens", "output_tokens", "total_tokens"):
coerced = _coerce_int(usage.get(key))
if coerced is not None:
out[key] = coerced
response_metadata = getattr(message, "response_metadata", None) or {}
token_usage = response_metadata.get("token_usage") if isinstance(response_metadata, dict) else None
if isinstance(token_usage, dict):
# Map both the LangChain-canonical names and OpenAI-native names; later
# writes win so a more-precise provider-native value can override a
# zero placeholder from usage_metadata.
candidates = {
"input_tokens": ("input_tokens", "prompt_tokens"),
"output_tokens": ("output_tokens", "completion_tokens"),
"total_tokens": ("total_tokens",),
}
for canonical, keys in candidates.items():
for key in keys:
coerced = _coerce_int(token_usage.get(key))
if coerced is not None and coerced > 0:
out[canonical] = coerced
break
# Derive a missing or implausibly-zero field if the other two are present.
# Some providers report ``input_tokens=0`` / ``output_tokens=0`` next to a
# real ``total_tokens`` — treat those zeros as missing so we don't silently
# store nonsense breakdowns.
def _missing_or_zero(key: str) -> bool:
return out.get(key) in (None, 0)
if "total_tokens" not in out and out.get("input_tokens") and out.get("output_tokens"):
out["total_tokens"] = out["input_tokens"] + out["output_tokens"]
if _missing_or_zero("output_tokens") and out.get("total_tokens") and out.get("input_tokens"):
derived = out["total_tokens"] - out["input_tokens"]
if derived > 0:
out["output_tokens"] = derived
if _missing_or_zero("input_tokens") and out.get("total_tokens") and out.get("output_tokens"):
derived = out["total_tokens"] - out["output_tokens"]
if derived > 0:
out["input_tokens"] = derived
return out
def _classify_exception(exc: BaseException) -> tuple[str, str]:
"""Return (error_type, error_message). Message is trimmed to 500 chars."""
name = exc.__class__.__name__
raw = (str(exc) or name).strip()
return name, (raw[:500] if len(raw) > 500 else raw)
class LlmMetricsMiddleware(AgentMiddleware[AgentState]):
"""Wrap each model call to time it and persist a metric row."""
def __init__(self, *, store: LlmMetricsStore | None = None, **kwargs: Any) -> None:
super().__init__(**kwargs)
self._store_override = store
def _store(self) -> LlmMetricsStore | None:
if self._store_override is not None:
return self._store_override
try:
sf = get_session_factory()
except Exception:
return None
return make_llm_metrics_store(sf)
def _build_base_record(self, request: ModelRequest) -> LlmMetricRecord:
return LlmMetricRecord(
id=uuid.uuid4().hex,
created_at=_now(),
user_id=get_effective_user_id(),
thread_id=_safe_get_thread_id(request),
run_id=_safe_get_run_id(request),
agent_name=_safe_get_agent_name(request),
model_name=_safe_get_model_name(request),
)
def _finalize_success(self, record: LlmMetricRecord, response: ModelResponse, started: float) -> None:
elapsed = max(0.0, time.monotonic() - started)
record.duration_ms = int(elapsed * 1000)
usage = _extract_usage(response)
record.input_tokens = usage.get("input_tokens")
record.output_tokens = usage.get("output_tokens")
record.total_tokens = usage.get("total_tokens") or (
(record.input_tokens or 0) + (record.output_tokens or 0) or None
)
if record.output_tokens is not None and elapsed > 0:
record.tokens_per_sec = round(record.output_tokens / elapsed, 3)
record.status = "success"
def _finalize_error(self, record: LlmMetricRecord, exc: BaseException, started: float) -> None:
record.duration_ms = int(max(0.0, time.monotonic() - started) * 1000)
record.status = "error"
record.error_type, record.error_message = _classify_exception(exc)
def _flush(self, record: LlmMetricRecord) -> None:
store = self._store()
if store is None:
return
# Route the best-effort write onto the engine's home loop. Doing
# ``asyncio.run(store.record(...))`` here (when the model call ran in a worker
# thread) would reuse the global engine's pooled connections on a fresh loop and
# raise "got Future attached to a different loop" — harmless (caught below) but
# log-spammy and pool-churning under concurrency. See ``fire_and_forget_db_write``.
try:
fire_and_forget_db_write(store.record(record))
except Exception:
logger.warning("LlmMetricsMiddleware: failed to flush metric %s", record.id, exc_info=True)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
record = self._build_base_record(request)
started = time.monotonic()
try:
response = handler(request)
except GraphBubbleUp:
# LangGraph control flow — not a real LLM failure.
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_success(record, response, started)
self._flush(record)
return response
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
record = self._build_base_record(request)
started = time.monotonic()
try:
response = await handler(request)
except GraphBubbleUp:
raise
except Exception as exc:
self._finalize_error(record, exc, started)
self._flush(record)
raise
self._finalize_success(record, response, started)
self._flush(record)
return response
@@ -0,0 +1,389 @@
"""Middleware to detect and break repetitive tool call loops.
P0 safety: prevents the agent from calling the same tool with the same
arguments indefinitely until the recursion limit kills the run.
Detection strategy:
1. After each model response, hash the tool calls (name + args).
2. Track recent hashes in a sliding window.
3. If the same hash appears >= warn_threshold times, inject a
"you are repeating yourself — wrap up" system message (once per hash).
4. If it appears >= hard_limit times, strip all tool_calls from the
response so the agent is forced to produce a final text answer.
"""
import hashlib
import json
import logging
import threading
from collections import OrderedDict, defaultdict
from copy import deepcopy
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import HumanMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
# Defaults — can be overridden via constructor
_DEFAULT_WARN_THRESHOLD = 8 # inject warning after 8 identical calls
_DEFAULT_HARD_LIMIT = 20 # force-stop after 20 identical calls
_DEFAULT_WINDOW_SIZE = 60 # track last N tool calls (must be >= hard_limit)
_DEFAULT_MAX_TRACKED_THREADS = 100 # LRU eviction limit
_DEFAULT_TOOL_FREQ_WARN = 80 # warn after 80 calls to the same tool type
_DEFAULT_TOOL_FREQ_HARD_LIMIT = 120 # force-stop after 120 calls to the same tool type
def _normalize_tool_call_args(raw_args: object) -> tuple[dict, str | None]:
"""Normalize tool call args to a dict plus an optional fallback key.
Some providers serialize ``args`` as a JSON string instead of a dict.
We defensively parse those cases so loop detection does not crash while
still preserving a stable fallback key for non-dict payloads.
"""
if isinstance(raw_args, dict):
return raw_args, None
if isinstance(raw_args, str):
try:
parsed = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
return {}, raw_args
if isinstance(parsed, dict):
return parsed, None
return {}, json.dumps(parsed, sort_keys=True, default=str)
if raw_args is None:
return {}, None
return {}, json.dumps(raw_args, sort_keys=True, default=str)
def _stable_tool_key(name: str, args: dict, fallback_key: str | None) -> str:
"""Derive a stable key from salient args without overfitting to noise."""
if name == "read_file" and fallback_key is None:
path = args.get("path") or ""
start_line = args.get("start_line")
end_line = args.get("end_line")
bucket_size = 200
try:
start_line = int(start_line) if start_line is not None else 1
except (TypeError, ValueError):
start_line = 1
try:
end_line = int(end_line) if end_line is not None else start_line
except (TypeError, ValueError):
end_line = start_line
start_line, end_line = sorted((start_line, end_line))
bucket_start = max(start_line, 1)
bucket_end = max(end_line, 1)
bucket_start = (bucket_start - 1) // bucket_size
bucket_end = (bucket_end - 1) // bucket_size
return f"{path}:{bucket_start}-{bucket_end}"
# write_file / str_replace are content-sensitive: same path may be updated
# with different payloads during iteration. Using only salient fields (path)
# can collapse distinct calls, so we hash full args to reduce false positives.
if name in {"write_file", "str_replace"}:
if fallback_key is not None:
return fallback_key
return json.dumps(args, sort_keys=True, default=str)
salient_fields = ("path", "url", "query", "command", "pattern", "glob", "cmd")
stable_args = {field: args[field] for field in salient_fields if args.get(field) is not None}
if stable_args:
return json.dumps(stable_args, sort_keys=True, default=str)
if fallback_key is not None:
return fallback_key
return json.dumps(args, sort_keys=True, default=str)
def _hash_tool_calls(tool_calls: list[dict]) -> str:
"""Deterministic hash of a set of tool calls (name + stable key).
This is intended to be order-independent: the same multiset of tool calls
should always produce the same hash, regardless of their input order.
"""
# Normalize each tool call to a stable (name, key) structure.
normalized: list[str] = []
for tc in tool_calls:
name = tc.get("name", "")
args, fallback_key = _normalize_tool_call_args(tc.get("args", {}))
key = _stable_tool_key(name, args, fallback_key)
normalized.append(f"{name}:{key}")
# Sort so permutations of the same multiset of calls yield the same ordering.
normalized.sort()
blob = json.dumps(normalized, sort_keys=True, default=str)
return hashlib.md5(blob.encode()).hexdigest()[:12]
_WARNING_MSG = "[LOOP DETECTED] You are repeating the same tool calls. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
_TOOL_FREQ_WARNING_MSG = (
"[LOOP DETECTED] You have called {tool_name} {count} times without producing a final answer. Stop calling tools and produce your final answer now. If you cannot complete the task, summarize what you accomplished so far."
)
_HARD_STOP_MSG = "[FORCED STOP] Repeated tool calls exceeded the safety limit. Producing final answer with results collected so far."
_TOOL_FREQ_HARD_STOP_MSG = "[FORCED STOP] Tool {tool_name} called {count} times — exceeded the per-tool safety limit. Producing final answer with results collected so far."
class LoopDetectionMiddleware(AgentMiddleware[AgentState]):
"""Detects and breaks repetitive tool call loops.
Args:
warn_threshold: Number of identical tool call sets before injecting
a warning message. Default: 8.
hard_limit: Number of identical tool call sets before stripping
tool_calls entirely. Default: 20.
window_size: Size of the sliding window for tracking calls.
Default: 60.
max_tracked_threads: Maximum number of threads to track before
evicting the least recently used. Default: 100.
tool_freq_warn: Number of calls to the same tool *type* (regardless
of arguments) before injecting a frequency warning. Catches
cross-file read loops that hash-based detection misses.
Default: 80.
tool_freq_hard_limit: Number of calls to the same tool type before
forcing a stop. Default: 120.
"""
def __init__(
self,
warn_threshold: int = _DEFAULT_WARN_THRESHOLD,
hard_limit: int = _DEFAULT_HARD_LIMIT,
window_size: int = _DEFAULT_WINDOW_SIZE,
max_tracked_threads: int = _DEFAULT_MAX_TRACKED_THREADS,
tool_freq_warn: int = _DEFAULT_TOOL_FREQ_WARN,
tool_freq_hard_limit: int = _DEFAULT_TOOL_FREQ_HARD_LIMIT,
):
super().__init__()
self.warn_threshold = warn_threshold
self.hard_limit = hard_limit
self.window_size = window_size
self.max_tracked_threads = max_tracked_threads
self.tool_freq_warn = tool_freq_warn
self.tool_freq_hard_limit = tool_freq_hard_limit
self._lock = threading.Lock()
# Per-thread tracking using OrderedDict for LRU eviction
self._history: OrderedDict[str, list[str]] = OrderedDict()
self._warned: dict[str, set[str]] = defaultdict(set)
# Per-thread, per-tool-type cumulative call counts
self._tool_freq: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
self._tool_freq_warned: dict[str, set[str]] = defaultdict(set)
def _get_thread_id(self, runtime: Runtime) -> str:
"""Extract thread_id from runtime context for per-thread tracking."""
thread_id = runtime.context.get("thread_id") if runtime.context else None
if thread_id:
return thread_id
return "default"
def _evict_if_needed(self) -> None:
"""Evict least recently used threads if over the limit.
Must be called while holding self._lock.
"""
while len(self._history) > self.max_tracked_threads:
evicted_id, _ = self._history.popitem(last=False)
self._warned.pop(evicted_id, None)
self._tool_freq.pop(evicted_id, None)
self._tool_freq_warned.pop(evicted_id, None)
logger.debug("Evicted loop tracking for thread %s (LRU)", evicted_id)
def _track_and_check(self, state: AgentState, runtime: Runtime) -> tuple[str | None, bool]:
"""Track tool calls and check for loops.
Two detection layers:
1. **Hash-based** (existing): catches identical tool call sets.
2. **Frequency-based** (new): catches the same *tool type* being
called many times with varying arguments (e.g. ``read_file``
on 40 different files).
Returns:
(warning_message_or_none, should_hard_stop)
"""
messages = state.get("messages", [])
if not messages:
return None, False
last_msg = messages[-1]
if getattr(last_msg, "type", None) != "ai":
return None, False
tool_calls = getattr(last_msg, "tool_calls", None)
if not tool_calls:
return None, False
thread_id = self._get_thread_id(runtime)
call_hash = _hash_tool_calls(tool_calls)
with self._lock:
# Touch / create entry (move to end for LRU)
if thread_id in self._history:
self._history.move_to_end(thread_id)
else:
self._history[thread_id] = []
self._evict_if_needed()
history = self._history[thread_id]
history.append(call_hash)
if len(history) > self.window_size:
history[:] = history[-self.window_size :]
count = history.count(call_hash)
tool_names = [tc.get("name", "?") for tc in tool_calls]
# --- Layer 1: hash-based (identical call sets) ---
if count >= self.hard_limit:
logger.error(
"Loop hard limit reached — forcing stop",
extra={
"thread_id": thread_id,
"call_hash": call_hash,
"count": count,
"tools": tool_names,
},
)
return _HARD_STOP_MSG, True
if count >= self.warn_threshold:
warned = self._warned[thread_id]
if call_hash not in warned:
warned.add(call_hash)
logger.warning(
"Repetitive tool calls detected — injecting warning",
extra={
"thread_id": thread_id,
"call_hash": call_hash,
"count": count,
"tools": tool_names,
},
)
return _WARNING_MSG, False
# --- Layer 2: per-tool-type frequency ---
freq = self._tool_freq[thread_id]
for tc in tool_calls:
name = tc.get("name", "")
if not name:
continue
freq[name] += 1
tc_count = freq[name]
if tc_count >= self.tool_freq_hard_limit:
logger.error(
"Tool frequency hard limit reached — forcing stop",
extra={
"thread_id": thread_id,
"tool_name": name,
"count": tc_count,
},
)
return _TOOL_FREQ_HARD_STOP_MSG.format(tool_name=name, count=tc_count), True
if tc_count >= self.tool_freq_warn:
warned = self._tool_freq_warned[thread_id]
if name not in warned:
warned.add(name)
logger.warning(
"Tool frequency warning — too many calls to same tool type",
extra={
"thread_id": thread_id,
"tool_name": name,
"count": tc_count,
},
)
return _TOOL_FREQ_WARNING_MSG.format(tool_name=name, count=tc_count), False
return None, False
@staticmethod
def _append_text(content: str | list | None, text: str) -> str | list:
"""Append *text* to AIMessage content, handling str, list, and None.
When content is a list of content blocks (e.g. Anthropic thinking mode),
we append a new ``{"type": "text", ...}`` block instead of concatenating
a string to a list, which would raise ``TypeError``.
"""
if content is None:
return text
if isinstance(content, list):
return [*content, {"type": "text", "text": f"\n\n{text}"}]
if isinstance(content, str):
return content + f"\n\n{text}"
# Fallback: coerce unexpected types to str to avoid TypeError
return str(content) + f"\n\n{text}"
@staticmethod
def _build_hard_stop_update(last_msg, content: str | list) -> dict:
"""Clear tool-call metadata so forced-stop messages serialize as plain assistant text."""
update = {
"tool_calls": [],
"content": content,
}
additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
for key in ("tool_calls", "function_call"):
additional_kwargs.pop(key, None)
update["additional_kwargs"] = additional_kwargs
response_metadata = deepcopy(getattr(last_msg, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def _apply(self, state: AgentState, runtime: Runtime) -> dict | None:
warning, hard_stop = self._track_and_check(state, runtime)
if hard_stop:
# Strip tool_calls from the last AIMessage to force text output
messages = state.get("messages", [])
last_msg = messages[-1]
content = self._append_text(last_msg.content, warning or _HARD_STOP_MSG)
stripped_msg = last_msg.model_copy(update=self._build_hard_stop_update(last_msg, content))
return {"messages": [stripped_msg]}
if warning:
# Inject as HumanMessage instead of SystemMessage to avoid
# Anthropic's "multiple non-consecutive system messages" error.
# Anthropic models require system messages only at the start of
# the conversation; injecting one mid-conversation crashes
# langchain_anthropic's _format_messages(). HumanMessage works
# with all providers. See #1299.
return {"messages": [HumanMessage(content=warning, name="loop_warning")]}
return None
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._apply(state, runtime)
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._apply(state, runtime)
def reset(self, thread_id: str | None = None) -> None:
"""Clear tracking state. If thread_id given, clear only that thread."""
with self._lock:
if thread_id:
self._history.pop(thread_id, None)
self._warned.pop(thread_id, None)
self._tool_freq.pop(thread_id, None)
self._tool_freq_warned.pop(thread_id, None)
else:
self._history.clear()
self._warned.clear()
self._tool_freq.clear()
self._tool_freq_warned.clear()
@@ -0,0 +1,262 @@
"""记忆机制中间件 (Memory V2)。
本中间件负责两件事:
1. **wrap_model_call** —— Hindsight 动态召回注入。
每次 LLM 调用前,用最近一条用户消息作为 query 召回 Hindsight 记忆,
作为一条带 ``<memory-context>`` 标签的消息**临时**追加到本次模型请求里。
关键:用 ``wrap_model_call`` 而非 ``before_model`` —— 注入只作用于这一次
模型调用,不写入持久 state,因此不会泄漏给前端、也不会在历史里堆积。
仅在 ``provider="hindsight"`` 且配置允许时生效;builtin 的 frozen
snapshot 走系统提示词,不在这里。
2. **after_agent** —— Hindsight 自动 retain。
Hindsight ``auto_retain`` 开启时,把本轮对话写入工作 bank。
LLM 主动写入走 ``memory`` / ``hindsight_*`` 工具,不经过本中间件。
"""
import asyncio
import logging
from typing import TYPE_CHECKING, Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import AIMessage, HumanMessage
from langgraph.config import get_config
from langgraph.runtime import Runtime
from deerflow.agents.memory.manager import build_memory_manager
from deerflow.agents.memory.message_processing import count_user_turns, filter_messages_for_memory
from deerflow.config.memory_config import get_effective_memory_config, get_memory_config
from deerflow.runtime.user_context import get_effective_user_id
if TYPE_CHECKING:
from deerflow.config.memory_config import MemoryConfig
logger = logging.getLogger(__name__)
def _coerce_text(content: Any) -> str:
"""把消息 content (可能是 str 或多模态 block 列表) 压成纯文本。"""
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for block in content:
if isinstance(block, str):
parts.append(block)
elif isinstance(block, dict) and block.get("type") == "text":
parts.append(str(block.get("text", "")))
return " ".join(parts)
return str(content or "")
def _latest_human_text(messages: list) -> str:
"""返回最近一条用户消息的纯文本。"""
for msg in reversed(messages):
if isinstance(msg, HumanMessage):
return _coerce_text(msg.content).strip()
return ""
def _last_exchange(filtered_messages: list) -> tuple[str, str]:
"""从过滤后的消息里取最后一轮 (用户输入, 助手回复) 的纯文本。"""
user_text = ""
assistant_text = ""
for msg in reversed(filtered_messages):
if not assistant_text and isinstance(msg, AIMessage):
assistant_text = _coerce_text(msg.content).strip()
elif not user_text and isinstance(msg, HumanMessage):
user_text = _coerce_text(msg.content).strip()
if user_text and assistant_text:
break
return user_text, assistant_text
class MemoryMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class MemoryMiddleware(AgentMiddleware[MemoryMiddlewareState]):
"""记忆中间件:wrap_model_call 注入 Hindsight 召回,after_agent 自动 retain。
Memory V2 说明:
- builtin 本地记忆的 frozen snapshot 走系统提示词 (``_get_memory_context``)。
- Hindsight 动态召回走本中间件 ``wrap_model_call`` —— 临时注入,不落 state。
"""
state_schema = MemoryMiddlewareState
def __init__(self, agent_name: str | None = None, *, memory_config: "MemoryConfig | None" = None, injection_enabled: bool = True):
"""初始化 MemoryMiddleware。
Args:
agent_name: 提供时记忆按 agent 隔离;None 用默认 agent。
memory_config: 显式记忆配置;省略时用全局配置。
injection_enabled: 运行时开关;``False`` 时跳过 Hindsight 动态召回注入。
"""
super().__init__()
self._agent_name = agent_name
self._memory_config = memory_config
self._injection_enabled = injection_enabled
# ---- 运行时上下文解析 -------------------------------------------------
def _resolve_thread_id(self, runtime: Runtime | None) -> str | None:
"""从 runtime context 取 thread_id,回退到 LangGraph configurable。"""
thread_id = None
if runtime is not None and getattr(runtime, "context", None):
thread_id = runtime.context.get("thread_id")
if thread_id:
return thread_id
try:
return get_config().get("configurable", {}).get("thread_id")
except RuntimeError:
return None
def _resolve_agent_id(self, runtime: Runtime | None) -> str | None:
"""解析 agent_id;优先 middleware 构造时的 agent_name,再 runtime context。
无 agent 上下文时返回 None,使 V1 记忆存入全局文件(users/{id}/memory.json)。
"""
if self._agent_name:
return self._agent_name
if runtime is not None and getattr(runtime, "context", None):
agent_id = runtime.context.get("agent_id")
if agent_id:
return str(agent_id)
return None
# ---- wrap_model_call:Hindsight 动态召回注入 -------------------------
def _build_recall_message(self, request: Any) -> HumanMessage | None:
"""按本次模型请求构建一条 Hindsight 召回消息;无召回内容时返回 None。
召回结果包在 ``<memory-context>`` 标签里并带系统提示,告诉模型这是
背景信息而非用户的新输入。
**跳过开关**:若 ``runtime.context.memory_recall_disabled`` 为真,直接
返回 None。圆桌规划等临时性任务(intent / recommend / leader / special)
不需要从用户个人记忆里召回,Hindsight HTTP 同步阻塞会显著增加 LLM 首
字节延迟(前端"调度中"卡顿);由路由层通过 ``_run_payload`` 的 context
字段统一关闭。
"""
runtime = getattr(request, "runtime", None)
if runtime is not None and getattr(runtime, "context", None):
if runtime.context.get("memory_recall_disabled"):
return None
if not self._injection_enabled:
return None
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if not effective_config.enabled or not effective_config.injection.enabled:
return None
# 只有 Hindsight 提供动态召回;builtin 走系统提示词。
if effective_config.provider != "hindsight" or not effective_config.injection.include_hindsight:
return None
messages = getattr(request, "messages", None) or []
query = _latest_human_text(messages)
if not query:
return None
runtime = getattr(request, "runtime", None)
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
user_id=user_id,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
recall = manager.prefetch_all(query, thread_id=thread_id or "")
except Exception as exc: # noqa: BLE001 - 召回失败不能阻断对话
logger.debug("Hindsight 召回注入失败 (非致命):%s", exc)
return None
if not recall or not recall.strip():
return None
tag = effective_config.injection.context_tag
fenced = (
f"<{tag}>\n"
"[系统提示:以下是召回的记忆上下文,不是用户的新输入,作为背景信息参考。]\n\n"
f"{recall}\n"
f"</{tag}>"
)
return HumanMessage(content=fenced)
@override
def wrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (同步路径)。"""
recall_msg = self._build_recall_message(request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return handler(request)
@override
async def awrap_model_call(self, request: Any, handler: Any) -> Any:
"""模型调用前临时注入 Hindsight 召回 (异步路径)。
召回过程是同步阻塞 (含 Hindsight HTTP),放到线程池里跑以免阻塞事件循环。
"""
recall_msg = await asyncio.to_thread(self._build_recall_message, request)
if recall_msg is not None:
request = request.override(messages=[*request.messages, recall_msg])
return await handler(request)
# ---- after_agent:Hindsight 自动 retain -------------------------------
@override
def after_agent(self, state: MemoryMiddlewareState, runtime: Runtime) -> dict | None:
"""agent 完成后把本轮对话写入 Hindsight 工作 bank。
Returns:
None (本中间件不改状态)。
"""
config = self._memory_config or get_memory_config()
if not config.enabled:
return None
user_id = get_effective_user_id()
effective_config = get_effective_memory_config(user_id)
if effective_config.provider != "hindsight" or not effective_config.hindsight.auto_retain:
return None
messages = state.get("messages", [])
if not messages:
return None
filtered_messages = filter_messages_for_memory(messages)
user_text, assistant_text = _last_exchange(filtered_messages)
if not user_text or not assistant_text:
return None
# 轮次序号按对话历史算出 —— provider 每轮被重建、无法自行计数,
# retain_every_n_turns 的节流必须靠这个外部传入的值。
turn_index = count_user_turns(filtered_messages)
thread_id = self._resolve_thread_id(runtime)
try:
manager = build_memory_manager(
user_id=user_id,
agent_id=self._resolve_agent_id(runtime),
thread_id=thread_id,
config=effective_config,
)
manager.sync_all(
user_text,
assistant_text,
thread_id=thread_id or "",
turn_index=turn_index,
)
except Exception as exc: # noqa: BLE001 - 写入失败不能阻断对话
logger.warning("Hindsight retain 失败:%s", exc)
return None
@@ -0,0 +1,468 @@
"""Cap deliverable tools for position-roundtable seats.
Weak models (especially after a first successful Markdown write) often call
``write_file`` again with another copy of the same report, or call
``present_files`` twice for the same path, and loop until the recursion
limit kills the run. The UI then shows two identical "Successfully
presented files" cards even though only one file exists on disk.
When the run context carries ``position_artifact_cap`` (set by the position-
roundtable UI for ordinary seats and the summary agent — **not** for
action-plan, which must emit report + JSON), this middleware:
1. Truncates excess outputs ``write_file`` **and** ``present_files`` calls in
a single model response (keeps only the first *N* of each), including
raw provider metadata.
2. Rejects further such calls once *N* successful *or* earlier in-batch
calls already exist in the current user turn (so parallel tool calls
cannot race past the cap).
3. Ends the turn when the only remaining calls were excess writes/presents.
4. Injects a brief hidden reminder before the next model call:
- write done, not yet presented → present once, then wrap up;
- write **and** present already done → wrap up, do **not** present again.
"""
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.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage, ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.runtime import Runtime
from langgraph.types import Command
logger = logging.getLogger(__name__)
_CONTEXT_KEY = "position_artifact_cap"
_OUTPUTS_PREFIX = "/mnt/user-data/outputs"
_WRITE_TOOL = "write_file"
_PRESENT_TOOL = "present_files"
_REJECT_WRITE = (
"本席位本轮产物上限已达:outputs 下只允许写入一份交付文件。"
"请勿再次调用 write_file;若尚未呈现文件请调用 present_files,"
"然后用简短文字说明交付已完成。"
)
_REJECT_PRESENT = (
"本席位本轮产物已经呈现过一次,请勿再次调用 present_files。"
"用一两句话说明交付已完成即可,不要再调用任何文件工具。"
)
_REMINDER_NEED_PRESENT = (
"【系统提示】本席位本轮产物文件已成功写入 outputs。"
"禁止再次调用 write_file 生成第二份(或相同)产物。"
"请立即 present_files(仅此一次,如尚未呈现),并给出简短收尾回复后结束本轮。"
)
_REMINDER_DONE = (
"【系统提示】本席位本轮产物已写入 outputs 并且已经 present_files 呈现过。"
"禁止再次调用 write_file 或 present_files。"
"请只用一两句话收尾说明交付已完成,不要再调用任何工具。"
)
def _normalize_args(raw_args: object) -> dict[str, Any]:
if isinstance(raw_args, dict):
return raw_args
if isinstance(raw_args, str):
try:
parsed = json.loads(raw_args)
except (TypeError, ValueError, json.JSONDecodeError):
return {}
return parsed if isinstance(parsed, dict) else {}
return {}
def _tool_field(tool_call: Any, 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 _is_outputs_path(path: object) -> bool:
text = str(path or "").strip().replace("\\", "/")
if not text:
return False
if text == _OUTPUTS_PREFIX or text.startswith(f"{_OUTPUTS_PREFIX}/"):
return True
lowered = text.lstrip("./")
return lowered == "outputs" or lowered.startswith("outputs/")
def _tool_call_writes_outputs(tool_call: Any) -> bool:
if _tool_field(tool_call, "name") != _WRITE_TOOL:
return False
args = _normalize_args(_tool_field(tool_call, "args"))
return _is_outputs_path(args.get("path"))
def _tool_call_is_present(tool_call: Any) -> bool:
return _tool_field(tool_call, "name") == _PRESENT_TOOL
def _is_successful_tool_result(content: str) -> bool:
text = content.strip()
if not text or text.startswith("Error"):
return False
return True
def _cap_from_mapping(mapping: object) -> int | None:
if not isinstance(mapping, dict):
return None
raw = mapping.get(_CONTEXT_KEY)
if raw is None or raw is False:
return None
try:
value = int(raw)
except (TypeError, ValueError):
return None
return value if value > 0 else None
def _cap_from_runtime(runtime: object | None) -> int | None:
if runtime is None:
return None
context = getattr(runtime, "context", None)
cap = _cap_from_mapping(context)
if cap is not None:
return cap
config = getattr(runtime, "config", None)
if not isinstance(config, dict):
return None
for bucket_key in ("configurable", "metadata", "context"):
cap = _cap_from_mapping(config.get(bucket_key))
if cap is not None:
return cap
return None
def _is_visible_human(message: Any) -> bool:
if getattr(message, "type", None) != "human":
return False
kwargs = getattr(message, "additional_kwargs", None) or {}
if kwargs.get("hide_from_ui"):
return False
name = getattr(message, "name", None)
if name in {"loop_warning", "position_artifact_cap"}:
return False
return True
def _current_turn_start(messages: list[Any]) -> int:
for index in range(len(messages) - 1, -1, -1):
if _is_visible_human(messages[index]):
return index
return 0
def _collect_call_ids(messages: list[Any], *, turn_start: int, match: Callable[[Any], bool]) -> set[str]:
ids: set[str] = set()
for message in messages[turn_start:]:
if getattr(message, "type", None) != "ai":
continue
for tool_call in getattr(message, "tool_calls", None) or []:
if not match(tool_call):
continue
call_id = _tool_field(tool_call, "id")
if isinstance(call_id, str) and call_id:
ids.add(call_id)
return ids
def _count_successful_tools(
messages: list[Any],
*,
turn_start: int,
match: Callable[[Any], bool],
) -> int:
matching_ids = _collect_call_ids(messages, turn_start=turn_start, match=match)
success = 0
for message in messages[turn_start:]:
if getattr(message, "type", None) != "tool":
continue
call_id = getattr(message, "tool_call_id", None)
if not isinstance(call_id, str) or call_id not in matching_ids:
continue
content = str(getattr(message, "content", "") or "")
if _is_successful_tool_result(content):
success += 1
return success
def _successful_outputs_writes(messages: list[Any], *, turn_start: int) -> int:
"""Count successful outputs ``write_file`` calls in the current user turn."""
return _count_successful_tools(messages, turn_start=turn_start, match=_tool_call_writes_outputs)
def _successful_presents(messages: list[Any], *, turn_start: int) -> int:
"""Count successful ``present_files`` calls in the current user turn."""
return _count_successful_tools(messages, turn_start=turn_start, match=_tool_call_is_present)
def _kept_call_ids(tool_calls: list[Any]) -> set[str]:
ids: set[str] = set()
for tool_call in tool_calls:
call_id = _tool_field(tool_call, "id")
if isinstance(call_id, str) and call_id:
ids.add(call_id)
return ids
def _build_truncated_update(last_msg: Any, kept: list[Any]) -> dict[str, Any]:
"""Replace structured tool_calls and keep raw provider metadata in sync."""
update: dict[str, Any] = {"tool_calls": kept}
additional_kwargs = dict(getattr(last_msg, "additional_kwargs", {}) or {})
raw_calls = additional_kwargs.get("tool_calls")
kept_ids = _kept_call_ids(kept)
if isinstance(raw_calls, list) and raw_calls:
if not kept:
additional_kwargs.pop("tool_calls", None)
additional_kwargs.pop("function_call", None)
else:
filtered = [item for item in raw_calls if isinstance(item, dict) and item.get("id") in kept_ids]
if filtered:
additional_kwargs["tool_calls"] = filtered
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_msg, "response_metadata", {}) or {})
if response_metadata.get("finish_reason") == "tool_calls":
response_metadata["finish_reason"] = "stop"
update["response_metadata"] = response_metadata
return update
def _in_flight_siblings(
messages: list[Any],
*,
current_id: str | None,
match: Callable[[Any], bool],
) -> int:
"""Earlier same-batch tool calls that would consume the same budget."""
if not current_id:
return 0
last_ai = None
for message in reversed(messages):
if getattr(message, "type", None) == "ai":
last_ai = message
break
if last_ai is None:
return 0
batch = list(getattr(last_ai, "tool_calls", None) or [])
if current_id not in {str(_tool_field(tool_call, "id") or "") for tool_call in batch}:
return 0
used = 0
for tool_call in batch:
call_id = str(_tool_field(tool_call, "id") or "")
if call_id == current_id:
break
if match(tool_call):
used += 1
return used
def _outputs_budget_used(messages: list[Any], *, turn_start: int, current_id: str | None) -> int:
return _successful_outputs_writes(messages, turn_start=turn_start) + _in_flight_siblings(
messages, current_id=current_id, match=_tool_call_writes_outputs
)
def _present_budget_used(messages: list[Any], *, turn_start: int, current_id: str | None) -> int:
return _successful_presents(messages, turn_start=turn_start) + _in_flight_siblings(
messages, current_id=current_id, match=_tool_call_is_present
)
def _reminder_for(*, writes_done: bool, presents_done: bool) -> str | None:
if not writes_done:
return None
if presents_done:
return _REMINDER_DONE
return _REMINDER_NEED_PRESENT
class PositionArtifactCapMiddleware(AgentMiddleware[AgentState]):
"""Enforce a per-turn outputs write/present budget for position roundtable."""
state_schema = AgentState
def _truncate_excess(self, state: AgentState, runtime: Runtime) -> dict | None:
cap = _cap_from_runtime(runtime)
if cap is None:
return None
messages = list(state.get("messages") or [])
if not messages:
return None
last_msg = messages[-1]
if getattr(last_msg, "type", None) != "ai":
return None
tool_calls = list(getattr(last_msg, "tool_calls", None) or [])
if not tool_calls:
return None
turn_start = _current_turn_start(messages)
prior = messages[:-1]
remaining_writes = max(0, cap - _successful_outputs_writes(prior, turn_start=turn_start))
remaining_presents = max(0, cap - _successful_presents(prior, turn_start=turn_start))
kept: list[Any] = []
dropped = 0
kept_writes = 0
kept_presents = 0
for tool_call in tool_calls:
if _tool_call_writes_outputs(tool_call):
if kept_writes >= remaining_writes:
dropped += 1
continue
kept_writes += 1
elif _tool_call_is_present(tool_call):
if kept_presents >= remaining_presents:
dropped += 1
continue
kept_presents += 1
kept.append(tool_call)
if dropped == 0:
return None
logger.warning(
"Position artifact cap truncated %s excess write_file/present_files call(s) "
"(cap=%s, remaining_writes=%s, remaining_presents=%s)",
dropped,
cap,
remaining_writes,
remaining_presents,
)
updated = last_msg.model_copy(update=_build_truncated_update(last_msg, kept))
result: dict[str, Any] = {"messages": [updated]}
if not kept:
# No remaining tools — stop instead of looping back to the model
# which would just emit another copy of write_file / present_files.
result["jump_to"] = "end"
return result
def _reject_over_cap(self, request: ToolCallRequest) -> ToolMessage | None:
tool_call = getattr(request, "tool_call", None) or {}
is_write = _tool_call_writes_outputs(tool_call)
is_present = _tool_call_is_present(tool_call)
if not is_write and not is_present:
return None
runtime = getattr(request, "runtime", None)
cap = _cap_from_runtime(runtime)
if cap is None:
return None
state = getattr(request, "state", None) or {}
messages = list(state.get("messages") or []) if isinstance(state, dict) else []
current_id = str(_tool_field(tool_call, "id") or "")
turn_start = _current_turn_start(messages)
if is_write:
used = _outputs_budget_used(messages, turn_start=turn_start, current_id=current_id or None)
reject_text = _REJECT_WRITE
tool_name = _WRITE_TOOL
else:
used = _present_budget_used(messages, turn_start=turn_start, current_id=current_id or None)
reject_text = _REJECT_PRESENT
tool_name = _PRESENT_TOOL
if used < cap:
return None
logger.warning(
"Position artifact cap rejected %s (cap=%s, used=%s, id=%s)",
tool_name,
cap,
used,
current_id,
)
return ToolMessage(
content=f"Error: {reject_text}",
tool_call_id=current_id,
name=tool_name,
)
def _maybe_remind(self, request: ModelRequest) -> ModelRequest:
cap = _cap_from_runtime(getattr(request, "runtime", None))
if cap is None:
return request
messages = list(getattr(request, "messages", None) or [])
turn_start = _current_turn_start(messages)
writes_done = _successful_outputs_writes(messages, turn_start=turn_start) >= cap
presents_done = _successful_presents(messages, turn_start=turn_start) >= cap
text = _reminder_for(writes_done=writes_done, presents_done=presents_done)
if text is None:
return request
reminder = HumanMessage(
content=text,
name="position_artifact_cap",
additional_kwargs={"hide_from_ui": True, "lc_source": "position_artifact_cap"},
)
return request.override(messages=[*messages, reminder])
@hook_config(can_jump_to=["end"])
@override
def after_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_excess(state, runtime)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(self, state: AgentState, runtime: Runtime) -> dict | None:
return self._truncate_excess(state, runtime)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
rejected = self._reject_over_cap(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_over_cap(request)
if rejected is not None:
return rejected
return await handler(request)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
return handler(self._maybe_remind(request))
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
return await handler(self._maybe_remind(request))
@@ -0,0 +1,78 @@
"""Middleware that injects the admin-configured prompt prefix at model-call time.
The prompt-prefix feature lets an admin prepend a fixed instruction to the
user's question before it reaches the LLM. To keep the prefix invisible in the
chat UI, the Gateway does **not** concatenate it into the persisted
``HumanMessage.content``; instead it tags the first human message with
``additional_kwargs["prompt_prefix"]`` (see ``app.gateway.services``).
This middleware reads that tag and prepends the prefix to the message content
*only in the request handed to the model*. The persisted state — and therefore
what the frontend renders — keeps the clean, prefix-free content.
"""
from collections.abc import Awaitable, Callable
from typing import override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage
PROMPT_PREFIX_KEY = "prompt_prefix"
class PromptPrefixMiddleware(AgentMiddleware[AgentState]):
"""Prepends ``additional_kwargs['prompt_prefix']`` to human messages for the LLM only.
The transformation is applied to the model request copy, never written back
to state, so it is naturally idempotent across the multiple model calls of a
single turn.
"""
@staticmethod
def _apply(messages: list) -> list | None:
"""Return a patched copy with prefixes prepended, or None if nothing to do."""
patched: list | None = None
for idx, msg in enumerate(messages):
if not isinstance(msg, HumanMessage):
continue
raw_prefix = (getattr(msg, "additional_kwargs", None) or {}).get(PROMPT_PREFIX_KEY)
prefix = str(raw_prefix).strip() if raw_prefix else ""
if not prefix:
continue
content = msg.content
if isinstance(content, str):
new_content: object = f"{prefix}\n\n{content}".strip("\n")
elif isinstance(content, list):
# Structured content (text blocks + media): prepend a text block.
new_content = [{"type": "text", "text": prefix}, *content]
else:
new_content = f"{prefix}\n\n{content!s}"
if patched is None:
patched = list(messages)
# model_copy preserves the message id so streaming dedup is unaffected.
patched[idx] = msg.model_copy(update={"content": new_content})
return patched
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._apply(request.messages)
if patched is not None:
request = request.override(messages=patched)
return handler(request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._apply(request.messages)
if patched is not None:
request = request.override(messages=patched)
return await handler(request)
@@ -0,0 +1,131 @@
"""Inject stable citation numbering before RAG final answers."""
from __future__ import annotations
import json
import logging
import os
from pathlib import Path
from collections.abc import Awaitable, Callable
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
from langchain_core.messages import HumanMessage
from deerflow.runtime.references import (
build_latest_reference_prompt,
build_reference_debug_payload,
build_reference_debug_summary,
)
logger = logging.getLogger(__name__)
_RAG_DEBUG_LOGGER_NAME = "rag_citation_debug"
def _get_rag_debug_logger() -> logging.Logger:
debug_logger = logging.getLogger(_RAG_DEBUG_LOGGER_NAME)
if getattr(debug_logger, "_rag_file_configured", False):
return debug_logger
log_path = Path(os.environ.get("RAG_CITATION_DEBUG_LOG", "logs/rag_citation_debug.log"))
if not log_path.is_absolute():
log_path = Path.cwd() / log_path
log_path.parent.mkdir(parents=True, exist_ok=True)
handler = logging.FileHandler(log_path, encoding="utf-8")
handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
debug_logger.addHandler(handler)
debug_logger.setLevel(logging.INFO)
debug_logger.propagate = False
setattr(debug_logger, "_rag_file_configured", True)
setattr(debug_logger, "_rag_file_path", str(log_path))
return debug_logger
def _log_rag_debug(message: str, *args: Any) -> None:
logger.info(message, *args)
_get_rag_debug_logger().info(message, *args)
class RagCitationMiddleware(AgentMiddleware[AgentState]):
"""Give the model the same numbered references the frontend will render."""
@staticmethod
def _enabled(request: ModelRequest) -> bool:
runtime = getattr(request, "runtime", None)
context = getattr(runtime, "context", None) if runtime is not None else None
if isinstance(context, dict) and context.get("rag_mode_enabled"):
return True
config = getattr(runtime, "config", None) if runtime is not None else None
if isinstance(config, dict):
configurable = config.get("configurable")
if isinstance(configurable, dict) and configurable.get("rag_mode_enabled"):
return True
runtime_context = config.get("context")
if isinstance(runtime_context, dict) and runtime_context.get("rag_mode_enabled"):
return True
return False
@staticmethod
def _patch(request: ModelRequest) -> ModelRequest | None:
if not RagCitationMiddleware._enabled(request):
return None
messages = list(request.messages)
prompt, batch = build_latest_reference_prompt(messages)
if not prompt:
_log_rag_debug(
"middleware reference-prompt enabled=true prompt=false messages=%s",
len(messages),
)
return None
summary = build_reference_debug_summary(messages, [batch] if batch else None)
_log_rag_debug(
"middleware reference-prompt enabled=true prompt=true single_batch=true messages=%s "
"tool_messages=%s raw_items=%s normalized_items=%s kept_items=%s latest_batch_id=%s "
"latest_batch_sources=%s",
summary["messages"],
summary["tool_messages"],
summary["raw_items"],
summary["normalized_items"],
summary["kept_items"],
(batch or {}).get("id"),
len((batch or {}).get("sources") or []),
)
_log_rag_debug(
"middleware reference-prompt-payload %s",
json.dumps(
build_reference_debug_payload(
messages=messages,
batch=batch,
prompt=prompt,
),
ensure_ascii=False,
default=str,
),
)
patched_messages = [
*messages,
HumanMessage(
content=prompt,
additional_kwargs={"hide_from_ui": True, "lc_source": "rag_citation"},
),
]
return request.override(messages=patched_messages)
@override
def wrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelCallResult:
patched = self._patch(request)
return handler(patched or request)
@override
async def awrap_model_call(
self,
request: ModelRequest,
handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
) -> ModelCallResult:
patched = self._patch(request)
return await handler(patched or request)
@@ -0,0 +1,363 @@
"""SandboxAuditMiddleware - bash command security auditing."""
import json
import logging
import re
import shlex
from collections.abc import Awaitable, Callable
from datetime import UTC, datetime
from typing import override
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.agents.thread_state import ThreadState
logger = logging.getLogger(__name__)
# ---------------------------------------------------------------------------
# Command classification rules
# ---------------------------------------------------------------------------
# Each pattern is compiled once at import time.
_HIGH_RISK_PATTERNS: list[re.Pattern[str]] = [
# --- original rules (retained) ---
re.compile(r"rm\s+-[^\s]*r[^\s]*\s+(/\*?|~/?\*?|/home\b|/root\b)\s*$"),
re.compile(r"dd\s+if="),
re.compile(r"mkfs"),
re.compile(r"cat\s+/etc/shadow"),
re.compile(r">+\s*/etc/"),
# --- pipe to sh/bash (generalised, replaces old curl|sh rule) ---
re.compile(r"\|\s*(ba)?sh\b"),
# --- command substitution (targeted – only dangerous executables) ---
re.compile(r"[`$]\(?\s*(curl|wget|bash|sh|python|ruby|perl|base64)"),
# --- base64 decode piped to execution ---
re.compile(r"base64\s+.*-d.*\|"),
# --- overwrite system binaries ---
re.compile(r">+\s*(/usr/bin/|/bin/|/sbin/)"),
# --- overwrite shell startup files ---
re.compile(r">+\s*~/?\.(bashrc|profile|zshrc|bash_profile)"),
# --- process environment leakage ---
re.compile(r"/proc/[^/]+/environ"),
# --- dynamic linker hijack (one-step escalation) ---
re.compile(r"\b(LD_PRELOAD|LD_LIBRARY_PATH)\s*="),
# --- bash built-in networking (bypasses tool allowlists) ---
re.compile(r"/dev/tcp/"),
# --- fork bomb ---
re.compile(r"\S+\(\)\s*\{[^}]*\|\s*\S+\s*&"), # :(){ :|:& };:
re.compile(r"while\s+true.*&\s*done"), # while true; do bash & done
]
_MEDIUM_RISK_PATTERNS: list[re.Pattern[str]] = [
re.compile(r"chmod\s+777"),
re.compile(r"pip3?\s+install"),
re.compile(r"apt(-get)?\s+install"),
# sudo/su: no-op under Docker root; warn so LLM is aware
re.compile(r"\b(sudo|su)\b"),
# PATH modification: long attack chain, warn rather than block
re.compile(r"\bPATH\s*="),
]
def _split_compound_command(command: str) -> list[str]:
"""Split a compound command into sub-commands (quote-aware).
Scans the raw command string so unquoted shell control operators are
recognised even when they are not surrounded by whitespace
(e.g. ``safe;rm -rf /`` or ``rm -rf /&&echo ok``). Operators inside
quotes are ignored. If the command ends with an unclosed quote or a
dangling escape, return the whole command unchanged (fail-closed —
safer to classify the unsplit string than silently drop parts).
"""
parts: list[str] = []
current: list[str] = []
in_single_quote = False
in_double_quote = False
escaping = False
index = 0
while index < len(command):
char = command[index]
if escaping:
current.append(char)
escaping = False
index += 1
continue
if char == "\\" and not in_single_quote:
current.append(char)
escaping = True
index += 1
continue
if char == "'" and not in_double_quote:
in_single_quote = not in_single_quote
current.append(char)
index += 1
continue
if char == '"' and not in_single_quote:
in_double_quote = not in_double_quote
current.append(char)
index += 1
continue
if not in_single_quote and not in_double_quote:
if command.startswith("&&", index) or command.startswith("||", index):
part = "".join(current).strip()
if part:
parts.append(part)
current = []
index += 2
continue
if char == ";":
part = "".join(current).strip()
if part:
parts.append(part)
current = []
index += 1
continue
current.append(char)
index += 1
# Unclosed quote or dangling escape → fail-closed, return whole command
if in_single_quote or in_double_quote or escaping:
return [command]
part = "".join(current).strip()
if part:
parts.append(part)
return parts if parts else [command]
def _classify_single_command(command: str) -> str:
"""Classify a single (non-compound) command. Return 'block', 'warn', or 'pass'."""
normalized = " ".join(command.split())
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(normalized):
return "block"
# Also try shlex-parsed tokens for high-risk detection
try:
tokens = shlex.split(command)
joined = " ".join(tokens)
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(joined):
return "block"
except ValueError:
# shlex.split fails on unclosed quotes — treat as suspicious
return "block"
for pattern in _MEDIUM_RISK_PATTERNS:
if pattern.search(normalized):
return "warn"
return "pass"
def _classify_command(command: str) -> str:
"""Return 'block', 'warn', or 'pass'.
Strategy:
1. First scan the *whole* raw command against high-risk patterns. This
catches structural attacks like ``while true; do bash & done`` or
``:(){ :|:& };:`` that span multiple shell statements — splitting them
on ``;`` would destroy the pattern context.
2. Then split compound commands (e.g. ``cmd1 && cmd2 ; cmd3``) and
classify each sub-command independently. The most severe verdict wins.
"""
# Pass 1: whole-command high-risk scan (catches multi-statement patterns)
normalized = " ".join(command.split())
for pattern in _HIGH_RISK_PATTERNS:
if pattern.search(normalized):
return "block"
# Pass 2: per-sub-command classification
sub_commands = _split_compound_command(command)
worst = "pass"
for sub in sub_commands:
verdict = _classify_single_command(sub)
if verdict == "block":
return "block" # short-circuit: can't get worse
if verdict == "warn":
worst = "warn"
return worst
# ---------------------------------------------------------------------------
# Middleware
# ---------------------------------------------------------------------------
class SandboxAuditMiddleware(AgentMiddleware[ThreadState]):
"""Bash command security auditing middleware.
For every ``bash`` tool call:
1. **Command classification**: regex + shlex analysis grades commands as
high-risk (block), medium-risk (warn), or safe (pass).
2. **Audit log**: every bash call is recorded as a structured JSON entry
via the standard logger (visible in langgraph.log).
High-risk commands (e.g. ``rm -rf /``, ``curl url | bash``) are blocked:
the handler is not called and an error ``ToolMessage`` is returned so the
agent loop can continue gracefully.
Medium-risk commands (e.g. ``pip install``, ``chmod 777``) are executed
normally; a warning is appended to the tool result so the LLM is aware.
"""
state_schema = ThreadState
# ------------------------------------------------------------------
# Helpers
# ------------------------------------------------------------------
def _get_thread_id(self, request: ToolCallRequest) -> str | None:
runtime = request.runtime # ToolRuntime; may be None-like in tests
if runtime is None:
return None
ctx = getattr(runtime, "context", None) or {}
thread_id = ctx.get("thread_id") if isinstance(ctx, dict) else None
if thread_id is None:
cfg = getattr(runtime, "config", None) or {}
thread_id = cfg.get("configurable", {}).get("thread_id")
return thread_id
_AUDIT_COMMAND_LIMIT = 200
def _write_audit(self, thread_id: str | None, command: str, verdict: str, *, truncate: bool = False) -> None:
audited_command = command
if truncate and len(command) > self._AUDIT_COMMAND_LIMIT:
audited_command = f"{command[: self._AUDIT_COMMAND_LIMIT]}... ({len(command)} chars)"
record = {
"timestamp": datetime.now(UTC).isoformat(),
"thread_id": thread_id or "unknown",
"command": audited_command,
"verdict": verdict,
}
logger.info("[SandboxAudit] %s", json.dumps(record, ensure_ascii=False))
def _build_block_message(self, request: ToolCallRequest, reason: str) -> ToolMessage:
tool_call_id = str(request.tool_call.get("id") or "missing_id")
return ToolMessage(
content=f"Command blocked: {reason}. Please use a safer alternative approach.",
tool_call_id=tool_call_id,
name="bash",
status="error",
)
def _append_warn_to_result(self, result: ToolMessage | Command, command: str) -> ToolMessage | Command:
"""Append a warning note to the tool result for medium-risk commands."""
if not isinstance(result, ToolMessage):
return result
warning = f"\n\n⚠️ Warning: `{command}` is a medium-risk command that may modify the runtime environment."
if isinstance(result.content, list):
new_content = list(result.content) + [{"type": "text", "text": warning}]
else:
new_content = str(result.content) + warning
return ToolMessage(
content=new_content,
tool_call_id=result.tool_call_id,
name=result.name,
status=result.status,
)
# ------------------------------------------------------------------
# Input sanitisation
# ------------------------------------------------------------------
# Normal bash commands rarely exceed a few hundred characters. 10 000 is
# well above any legitimate use case yet a tiny fraction of Linux ARG_MAX.
# Anything longer is almost certainly a payload injection or base64-encoded
# attack string.
_MAX_COMMAND_LENGTH = 10_000
def _validate_input(self, command: str) -> str | None:
"""Return ``None`` if *command* is acceptable, else a rejection reason."""
if not command.strip():
return "empty command"
if len(command) > self._MAX_COMMAND_LENGTH:
return "command too long"
if "\x00" in command:
return "null byte detected"
return None
# ------------------------------------------------------------------
# Core logic (shared between sync and async paths)
# ------------------------------------------------------------------
def _pre_process(self, request: ToolCallRequest) -> tuple[str, str | None, str, str | None]:
"""
Returns (command, thread_id, verdict, reject_reason).
verdict is 'block', 'warn', or 'pass'.
reject_reason is non-None only for input sanitisation rejections.
"""
args = request.tool_call.get("args", {})
raw_command = args.get("command")
command = raw_command if isinstance(raw_command, str) else ""
thread_id = self._get_thread_id(request)
# ① input sanitisation — reject malformed input before regex analysis
reject_reason = self._validate_input(command)
if reject_reason:
self._write_audit(thread_id, command, "block", truncate=True)
logger.warning("[SandboxAudit] INVALID INPUT thread=%s reason=%s", thread_id, reject_reason)
return command, thread_id, "block", reject_reason
# ② classify command
verdict = _classify_command(command)
# ③ audit log
self._write_audit(thread_id, command, verdict)
if verdict == "block":
logger.warning("[SandboxAudit] BLOCKED thread=%s cmd=%r", thread_id, command)
elif verdict == "warn":
logger.warning("[SandboxAudit] WARN (medium-risk) thread=%s cmd=%r", thread_id, command)
return command, thread_id, verdict, None
# ------------------------------------------------------------------
# wrap_tool_call hooks
# ------------------------------------------------------------------
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
if request.tool_call.get("name") != "bash":
return handler(request)
command, _, verdict, reject_reason = self._pre_process(request)
if verdict == "block":
reason = reject_reason or "security violation detected"
return self._build_block_message(request, reason)
result = handler(request)
if verdict == "warn":
result = self._append_warn_to_result(result, command)
return result
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
if request.tool_call.get("name") != "bash":
return await handler(request)
command, _, verdict, reject_reason = self._pre_process(request)
if verdict == "block":
reason = reject_reason or "security violation detected"
return self._build_block_message(request, reason)
result = await handler(request)
if verdict == "warn":
result = self._append_warn_to_result(result, command)
return result
@@ -0,0 +1,118 @@
"""Approval middleware for the custom-agent setup tool."""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
class SetupAgentApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupAgentApprovalMiddleware(AgentMiddleware[SetupAgentApprovalMiddlewareState]):
"""Stop before ``setup_agent`` writes files and ask the user to approve.
The interception runs in ``after_model``: as soon as the model emits an
AIMessage that contains a ``setup_agent`` tool call (and the run has not
been pre-approved via ``setup_agent_approved=True`` in runtime context),
we append a structured approval ``ToolMessage`` and return
``jump_to="end"`` to terminate the LangGraph run *before* the tool node
executes. This is the LangChain-recommended way to short-circuit after
the model; using ``wrap_tool_call`` + ``Command(goto=END)`` proved
unreliable when the AIMessage contained multiple parallel tool calls
(the ``Command`` got mixed with normal tool outputs and the graph
looped back to the model instead of terminating).
"""
state_schema = SetupAgentApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_agent_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-agent-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-agent-approval:{digest}"
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
skills = args.get("skills")
return {
"name": str(args.get("name") or "").strip(),
"description": str(args.get("description") or "").strip(),
"soul": str(args.get("soul") or "").strip(),
"skills": skills if isinstance(skills, list) else [],
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Return a state update if setup_agent must be gated; None to passthrough."""
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_agent"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
if isinstance(args.get("skills"), list) and len(args["skills"]) > 5:
args = {**args, "skills": args["skills"][:5]}
payload = self._build_payload(args)
logger.info("Setup agent approval requested before writing agent files")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否创建/更新这个智能体配置。",
tool_call_id=tool_call_id,
name="setup_agent",
additional_kwargs={"setup_agent_approval": payload},
)
# Any other tool_calls on the same AIMessage are left dangling; the
# existing DanglingToolCallMiddleware will inject placeholder
# ToolMessages on the next model invocation, which matches the
# desired semantics: every action pauses until the user approves.
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupAgentApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupAgentApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,113 @@
"""Approval middleware for the report-structure setup tool.
与 ``SetupWritingApprovalMiddleware`` 同构:模型在「智能新增报告结构」里调用
``setup_report_structure`` 时,于 ``after_model`` 拦截,附上一条结构化审批 ToolMessage
(建议字段打包在 ``additional_kwargs["setup_report_structure_approval"]``)并
``jump_to="end"`` 立即结束本轮——前端据此渲染确认卡,用户点「应用到表单」后回填右侧表单。
"""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
from deerflow.persistence.report_structures.directions import normalize_retrieval_directions
from deerflow.persistence.report_structures.skills import normalize_retrieval_skills
logger = logging.getLogger(__name__)
class SetupReportStructureApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupReportStructureApprovalMiddleware(AgentMiddleware[SetupReportStructureApprovalMiddlewareState]):
"""Stop before ``setup_report_structure`` and ask the user to apply the proposed config."""
state_schema = SetupReportStructureApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_report_structure_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-report-structure-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-report-structure-approval:{digest}"
def _normalize_mode(self, raw: Any) -> str:
text = str(raw or "").strip().lower()
if text in {"fixed", "固定", "固定大纲"}:
return "fixed"
return "adaptive"
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
return {
"title": str(args.get("title") or "").strip()[:256],
"name": str(args.get("name") or "").strip()[:256],
"content": str(args.get("content") or "").strip(),
"structure_mode": self._normalize_mode(args.get("structure_mode")),
"retrieval_directions": normalize_retrieval_directions(args.get("retrieval_directions")),
"retrieval_skills": normalize_retrieval_skills(args.get("retrieval_skills")),
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_report_structure"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
payload = self._build_payload(args)
logger.info("Setup report-structure approval requested before applying config")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否把这份报告结构应用到表单。",
tool_call_id=tool_call_id,
name="setup_report_structure",
additional_kwargs={"setup_report_structure_approval": payload},
)
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupReportStructureApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupReportStructureApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,135 @@
"""Approval middleware for the AI-writing config setup tool.
与 ``SetupAgentApprovalMiddleware`` 同构:模型在「写作配置 Q&A」里调用 ``setup_writing``
时,于 ``after_model`` 拦截,附上一条结构化审批 ToolMessage(建议的写作配置打包在
``additional_kwargs["setup_writing_approval"]``)并 ``jump_to="end"`` 立即结束本轮运行——
前端据此渲染审批卡,用户点「应用到表单」后把这些字段回填到左侧写作表单。
"""
from __future__ import annotations
import logging
from hashlib import sha256
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware, hook_config
from langchain_core.messages import AIMessage, ToolMessage
from langgraph.runtime import Runtime
logger = logging.getLogger(__name__)
class SetupWritingApprovalMiddlewareState(AgentState):
"""Compatible with the DeerFlow thread state schema."""
pass
class SetupWritingApprovalMiddleware(AgentMiddleware[SetupWritingApprovalMiddlewareState]):
"""Stop before ``setup_writing`` and ask the user to apply the proposed config.
See ``SetupAgentApprovalMiddleware`` for the rationale behind intercepting in
``after_model`` + ``jump_to="end"`` (robust against parallel tool calls).
"""
state_schema = SetupWritingApprovalMiddlewareState
def _is_approved(self, runtime: Runtime) -> bool:
context = getattr(runtime, "context", None) or {}
if not isinstance(context, dict):
return False
return context.get("setup_writing_approved") is True
def _stable_message_id(self, tool_call_id: str, args: dict[str, Any]) -> str:
if tool_call_id:
return f"setup-writing-approval:{tool_call_id}"
digest = sha256(repr(sorted(args.items())).encode("utf-8")).hexdigest()[:16]
return f"setup-writing-approval:{digest}"
def _coerce_word_count(self, raw: Any) -> int | None:
if isinstance(raw, bool): # bool 是 int 子类,先排除
return None
if isinstance(raw, int):
return raw if raw > 0 else None
if isinstance(raw, float):
return int(raw) if raw > 0 else None
if isinstance(raw, str):
import re
m = re.search(r"\d[\d,]*", raw)
if m:
try:
value = int(m.group().replace(",", ""))
return value if value > 0 else None
except ValueError:
return None
return None
def _build_payload(self, args: dict[str, Any]) -> dict[str, Any]:
# 素材来源:仅当模型明确给出 "skill" 时才用技能检索;用户没明确要求就一律默认知识库。
material_source = (
"skill" if str(args.get("material_source") or "").strip() == "skill" else "knowledge_base"
)
return {
"user_intent": str(args.get("user_intent") or "").strip(),
"article_type": str(args.get("article_type") or "").strip(),
# 新(列表外)文章类型的一句话特征说明;命中已有类型时为空。
"article_type_detail": str(args.get("article_type_detail") or "").strip(),
"word_count_target": self._coerce_word_count(args.get("word_count_target")),
"target_audience": str(args.get("target_audience") or "").strip(),
"writing_mode": str(args.get("writing_mode") or "").strip(),
"material_source": material_source,
"outline": str(args.get("outline") or "").strip(),
}
def _intercept(self, last: AIMessage) -> dict[str, Any] | None:
"""Return a state update if setup_writing must be gated; None to passthrough."""
tool_calls = list(last.tool_calls or [])
setup_call = next((tc for tc in tool_calls if tc.get("name") == "setup_writing"), None)
if setup_call is None:
return None
args = setup_call.get("args") or {}
tool_call_id = setup_call.get("id") or ""
payload = self._build_payload(args)
logger.info("Setup writing approval requested before applying writing config")
approval_msg = ToolMessage(
id=self._stable_message_id(tool_call_id, args),
content="请确认是否把这份写作配置应用到表单。",
tool_call_id=tool_call_id,
name="setup_writing",
additional_kwargs={"setup_writing_approval": payload},
)
return {
"messages": [approval_msg],
"jump_to": "end",
}
@hook_config(can_jump_to=["end"])
@override
def after_model(
self,
state: SetupWritingApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
if self._is_approved(runtime):
return None
messages = state.get("messages") or []
if not messages:
return None
last = messages[-1]
if not isinstance(last, AIMessage):
return None
return self._intercept(last)
@hook_config(can_jump_to=["end"])
@override
async def aafter_model(
self,
state: SetupWritingApprovalMiddlewareState,
runtime: Runtime,
) -> dict[str, Any] | None:
return self.after_model(state, runtime)
@@ -0,0 +1,54 @@
"""SkillReviewMiddleware — triggers background skill review after each agent turn.
Hooks into ``after_agent``: once the lead agent graph has finished a full turn,
this middleware counts the tool calls made and, if the threshold is met, hands
the conversation messages to the SkillReviewWorker as a background asyncio task.
No blocking I/O or LLM calls happen in-band — the review runs fully in the
background and never delays the HTTP response.
"""
from __future__ import annotations
import logging
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langgraph.runtime import Runtime
from deerflow.config.app_config import get_app_config
from deerflow.runtime.user_context import get_effective_user_id
from deerflow.skills.review_worker import maybe_start_review
logger = logging.getLogger(__name__)
class SkillReviewMiddlewareState(AgentState):
"""Minimal state schema — only needs ``messages``."""
pass
class SkillReviewMiddleware(AgentMiddleware[SkillReviewMiddlewareState]):
"""Dispatch a background skill review after every substantial agent turn.
'Substantial' is defined by ``skill_evolution.review_worker.min_tool_calls``
(default 5). Turns below the threshold are silently skipped to avoid
wasting LLM tokens on trivial exchanges.
"""
state_schema = SkillReviewMiddlewareState
@override
def after_agent(self, state: Any, runtime: Runtime) -> None:
"""Fire background review; never raises — failures are logged only."""
try:
app_config = get_app_config()
messages = state.get("messages", []) if hasattr(state, "get") else []
thread_id: str = runtime.context.get("thread_id", "") if runtime.context else ""
if not thread_id:
return
user_id = get_effective_user_id()
maybe_start_review(thread_id, messages, app_config, user_id)
except Exception:
logger.exception("SkillReviewMiddleware.after_agent: unexpected error (ignored)")
@@ -0,0 +1,158 @@
"""Middleware for intercepting skill calls and stopping execution when specific skills are invoked."""
import logging
import re
from collections.abc import Callable
from typing import Any, override
from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command, interrupt
logger = logging.getLogger(__name__)
def extract_name_task(text: str) -> tuple[str, str]:
"""Extract `agent_name` and `task_content` from a bash invocation that triggers
a sub-agent via ``python3 scripts/agent_orchestration.py "<agent>" "<task>"``.
Returns empty strings when no match is found so the caller can treat the
absence of a match as "not a target skill call".
"""
try:
pattern = r'\.py\s+"([^"]*)"\s+"([^"]*)"'
match = re.search(pattern, text)
if match:
return match.group(1), match.group(2)
return "", ""
except Exception:
return "", ""
class SkillStopMiddlewareState(AgentState):
"""Compatible with the `ThreadState` schema."""
pass
class SkillStopMiddleware(AgentMiddleware[SkillStopMiddlewareState]):
"""Intercepts skill file reads and stops execution when specific skills are invoked.
When the model reads a file from a skill directory that matches one of the
configured skill names, this middleware:
1. Intercepts the tool call before execution
2. Returns a Command that stops execution (goes to END)
3. Optionally returns a message indicating which skill was triggered
This is useful for implementing "skill triggers" that pause the agent
when certain skills are about to be used.
"""
state_schema = SkillStopMiddlewareState
def __init__(
self,
*,
skill_names: list[str],
skills_root: str = "/mnt/skills",
stop_message: str | None = None,
stop_on_match: bool = True,
):
"""Initialize the skill stop middleware.
Args:
skill_names: List of skill names to intercept (e.g., ["newsletter-generation", "podcast-generation"]).
skills_root: Root directory where skills are located (default: "/mnt/skills").
stop_message: Optional message to return when stopping. If None, a default message is used.
stop_on_match: If True, stop when skill matches. If False, continue execution (for logging only).
"""
super().__init__()
self._skill_names = set(skill_names)
self._skills_root = skills_root.rstrip("/")
self._stop_message = stop_message
self._stop_on_match = stop_on_match
def _is_target_skill_call(self, tool_call: dict[str, Any]) -> str | None:
"""Return the matched skill name if this tool call invokes one of the
configured target skills, otherwise ``None``.
Two invocation patterns are recognized:
1. **Structured tool call** — the model emits a tool call whose ``name``
literally matches one of the configured skill names (e.g. the
multi-agent leader calling
``agent_orchestration({"agent_name": "...", "task": "..."})``).
This is the natural form most LLMs produce when told to "use a
skill", and it's the form that drives the roundtable dispatch.
2. **Bash + argv** — the legacy form where the lead agent reaches into
a skill by running ``python3 scripts/<skill-name>.py "<arg1>" "<arg2>"``.
Kept for backward compatibility with skills that use bash for
dispatch.
"""
name = tool_call.get("name") or ""
lowered_targets = {s.lower() for s in self._skill_names}
# Pattern 1: structured tool call whose tool name IS the skill name.
if name and (name in self._skill_names or name.lower() in lowered_targets):
logger.info("SkillStopMiddleware: matched structured skill call name=%s", name)
return name
# Pattern 2: bash invocation with argv-style skill name.
if name == "bash" and "args" in tool_call:
skill_name, _ = extract_name_task(str(tool_call["args"]))
if skill_name and (skill_name in self._skill_names or skill_name.lower() in lowered_targets):
logger.info("SkillStopMiddleware: matched bash skill call name=%s", skill_name)
return skill_name
return None
def _handle_skill_stop(self, request: ToolCallRequest, skill_name: str) -> Command:
"""Build the stop response — an interrupt that includes a ToolMessage
describing which skill was triggered."""
logger.info("Skill stop triggered: skill_name=%s", skill_name)
tool_call_id = request.tool_call.get("id", "")
message_content = self._stop_message or f"⏹️ Skill '{skill_name}' triggered. Execution stopped."
tool_message = ToolMessage(
id=f"skill_stop:{tool_call_id}",
content=message_content,
tool_call_id=tool_call_id,
name="skill_stop",
)
return interrupt(
{
"messages": [tool_message],
"skill_name": skill_name,
}
)
@override
def wrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
matched_skill = self._is_target_skill_call(request.tool_call)
if matched_skill:
if self._stop_on_match:
return self._handle_skill_stop(request, matched_skill)
logger.info("Skill detected (not stopping): skill_name=%s", matched_skill)
return handler(request)
@override
async def awrap_tool_call(
self,
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
matched_skill = self._is_target_skill_call(request.tool_call)
if matched_skill:
if self._stop_on_match:
return self._handle_skill_stop(request, matched_skill)
logger.info("Skill detected (not stopping): skill_name=%s", matched_skill)
return await handler(request)
Loaded 100 of 3008 files, more files were not shown because too many files have changed in this diff. Show more