初始化

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

@@ -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} 个章节"},
],
}