"""AI 写作 LangGraph Graph,含 4 个用户干预点。""" from __future__ import annotations import logging from langgraph.graph import END, StateGraph from langgraph.types import interrupt from .state import AIWritingState from .nodes.intent_parser import intent_parser_node from .nodes.researcher import researcher_node from .nodes.writer_outline import writer_outline_node from .nodes.writer_draft import writer_draft_node from .nodes.editor import editor_node logger = logging.getLogger(__name__) # ── 干预节点 ────────────────────────────────────────────────────────────────── 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") 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} return { "material_package": updated_pkg, "last_user_intervention": user_input, "status": "writing_outline", "progress_events": [{"type": "resumed", "agent_name": "系统", "message": "用户已确认素材,开始规划大纲"}], } # re_search:重新搜索 extra_kws = user_input.get("extraKeywords") or [] return { "last_user_intervention": {**user_input, "_extra_keywords": extra_kws}, "status": "researching", "progress_events": [{"type": "resumed", "agent_name": "系统", "message": "重新搜索中..."}], } 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) -> dict: """PAUSE-3:草稿确认""" draft = state["current_draft"] 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": 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 return { "last_user_intervention": user_input, "status": "reviewing", "progress_events": [{"type": "resumed", "agent_name": "系统", "message": "提交编辑审核"}], } 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) -> 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": 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: return "researcher" if state["status"] == "researching" else "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: """写作完成后:素材不足则去求助暂停点,否则去草稿确认。""" 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" # ── 组装 Graph ──────────────────────────────────────────────────────────────── def build_ai_writing_graph(checkpointer=None): """构建并 compile AI 写作 graph。 Args: checkpointer: 可选的 LangGraph checkpointer。 - ``None`` → 退回 ``MemorySaver`` —— 仅供测试 / 开发使用。 进程或容器重启后会话状态全部丢失,前端拿着旧 session_id 调 ``/resume`` 会得到 404。 - 其他 → 传入的 (Async)BaseCheckpointSaver 实例,用于持久化。 """ g = StateGraph(AIWritingState) 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("intent_parser") g.add_edge("intent_parser", "researcher") g.add_conditional_edges("researcher", after_researcher, {"pause_material": "pause_material", "writer_draft": "writer_draft"}) g.add_conditional_edges("pause_material", after_material_pause, {"researcher": "researcher", "writer_outline": "writer_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"}) 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"}) if checkpointer is None: # MemorySaver 仅作为 fallback —— 提示一下,正式部署应通过 # get_ai_writing_graph() 拿到带持久化 checkpointer 的 graph。 from langgraph.checkpoint.memory import MemorySaver checkpointer = MemorySaver() return g.compile(checkpointer=checkpointer) # ── 持久化 checkpointer 单例(懒加载)───────────────────────────────────────── # 模块级 graph 槽位。import 时为 None;首次 ``get_ai_writing_graph()`` 调用时 # 按 config.yaml 的 checkpointer 段懒构建出真正的 graph。 # 测试可通过 ``monkeypatch.setattr(graph_mod, "AI_WRITING_GRAPH", stub)`` # 直接注入桩;本模块所有访问点都走 ``get_ai_writing_graph()`` 这一入口,会优先 # 返回 module attribute 的值,保留测试桩注入路径。 AI_WRITING_GRAPH = None # 持有 async checkpointer(底层 aiosqlite Connection 或 psycopg pool 的所有者)。 # 进程生命周期内常驻;shutdown 时由 ``shutdown_ai_writing_graph`` 显式关闭。 _async_checkpointer_singleton = None def _fallback_to_memory_saver(reason: str): """退回 InMemorySaver 的统一兜底入口。 把 reason 打到 warning 日志里方便运维定位。InMemorySaver 进程重启会丢 状态,但**当次写作能跑完** —— 我们的首要目标是「写作流程能继续」, 持久化是锦上添花。 """ from langgraph.checkpoint.memory import InMemorySaver logger.warning( "ai_writing: 持久化 checkpointer 不可用,退回 InMemorySaver。原因: %s", reason, ) return InMemorySaver() async def _get_async_checkpointer(): """按 config.yaml 的 checkpointer 段返回一个 async checkpointer 实例。 **绝不抛异常** —— 任何失败一律退回 InMemorySaver。这是为了保证「写作 流程能继续」这个首要目标:持久化坏了用户至少还能写完当次稿,重启会丢 会话但不影响当下创作。 优先级: 1. ``checkpointer:`` 段(``type=sqlite|postgres|memory``) 2. fallback 到 ``InMemorySaver`` 并打 warning 返回的 saver 与主 agent 公用同一 sqlite 文件 —— LangGraph 的 schema 用 ``(thread_id, checkpoint_ns)`` 做主键,AI 写作的 thread_id 是 会话 uuid,跟主 agent 的 LangGraph thread_id 不会撞。 """ global _async_checkpointer_singleton if _async_checkpointer_singleton is not None: return _async_checkpointer_singleton try: from deerflow.config.checkpointer_config import get_checkpointer_config cp_cfg = get_checkpointer_config() except Exception: logger.exception("ai_writing: 加载 checkpointer 配置失败") _async_checkpointer_singleton = _fallback_to_memory_saver("加载 config 抛异常") return _async_checkpointer_singleton if cp_cfg is None: _async_checkpointer_singleton = _fallback_to_memory_saver( "config.yaml 未配置 checkpointer 段" ) return _async_checkpointer_singleton if cp_cfg.type == "memory": from langgraph.checkpoint.memory import InMemorySaver _async_checkpointer_singleton = InMemorySaver() logger.info("ai_writing: 配置 type=memory,使用 InMemorySaver") return _async_checkpointer_singleton if cp_cfg.type == "sqlite": try: import aiosqlite from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver from deerflow.runtime.store._sqlite_utils import ( ensure_sqlite_parent_dir, resolve_sqlite_conn_str, ) conn_str = resolve_sqlite_conn_str( cp_cfg.connection_string or "ai_writing_checkpoints.db" ) ensure_sqlite_parent_dir(conn_str) # 直接持有 aiosqlite.Connection —— 进程生命周期,shutdown 时显式关。 conn = await aiosqlite.connect(conn_str) saver = AsyncSqliteSaver(conn) await saver.setup() _async_checkpointer_singleton = saver logger.info("ai_writing: 使用 AsyncSqliteSaver (%s)", conn_str) return saver except Exception as exc: # sqlite 失败原因可能是:依赖未装 / 磁盘满 / 文件权限 / 路径不存在 / # 文件被外部进程独占锁。任何一个都不能让 AI 写作整个不可用。 logger.exception( "ai_writing: AsyncSqliteSaver 初始化失败,conn_str=%r", getattr(cp_cfg, "connection_string", None), ) _async_checkpointer_singleton = _fallback_to_memory_saver( f"sqlite 初始化失败: {type(exc).__name__}: {exc}" ) return _async_checkpointer_singleton if cp_cfg.type == "postgres": try: from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver from psycopg_pool import AsyncConnectionPool if not cp_cfg.connection_string: raise ValueError("checkpointer.connection_string 是 postgres 必填项") pool = AsyncConnectionPool(cp_cfg.connection_string, open=False) await pool.open() saver = AsyncPostgresSaver(pool) await saver.setup() _async_checkpointer_singleton = saver logger.info("ai_writing: 使用 AsyncPostgresSaver") return saver except Exception as exc: logger.exception("ai_writing: AsyncPostgresSaver 初始化失败") _async_checkpointer_singleton = _fallback_to_memory_saver( f"postgres 初始化失败: {type(exc).__name__}: {exc}" ) return _async_checkpointer_singleton # 未知 type —— config 配错也不能让服务挂 _async_checkpointer_singleton = _fallback_to_memory_saver( f"未知 checkpointer.type={cp_cfg.type!r}" ) return _async_checkpointer_singleton async def get_ai_writing_graph(): """懒加载并返回 AI 写作 graph 单例。 第一次调用按 config 选定的 checkpointer 构建 graph 并缓存;后续调用直接 返回缓存。测试可在调用前通过 ``monkeypatch.setattr`` 直接替换模块级 ``AI_WRITING_GRAPH`` —— 本函数会优先返回已设的值。 """ global AI_WRITING_GRAPH if AI_WRITING_GRAPH is not None: return AI_WRITING_GRAPH checkpointer = await _get_async_checkpointer() AI_WRITING_GRAPH = build_ai_writing_graph(checkpointer=checkpointer) return AI_WRITING_GRAPH def get_ai_writing_checkpointer(): """返回当前已实例化的 checkpointer(清理任务用它来删 thread)。 若尚未懒构建过则返回 None。 """ return _async_checkpointer_singleton async def shutdown_ai_writing_graph() -> None: """关闭 saver 持有的底层连接,并清空 graph 单例。Lifespan shutdown 调用。""" global AI_WRITING_GRAPH, _async_checkpointer_singleton saver = _async_checkpointer_singleton _async_checkpointer_singleton = None AI_WRITING_GRAPH = None if saver is None: return # aiosqlite saver: saver.conn 是 aiosqlite.Connection conn = getattr(saver, "conn", None) if conn is not None and hasattr(conn, "close"): try: await conn.close() except Exception: logger.warning("ai_writing: 关闭 checkpointer connection 失败", exc_info=True) # postgres saver: saver.pool 是 AsyncConnectionPool pool = getattr(saver, "pool", None) if pool is not None and hasattr(pool, "close"): try: await pool.close() except Exception: logger.warning("ai_writing: 关闭 checkpointer pool 失败", exc_info=True)