from __future__ import annotations import re from datetime import date from typing import Any, TypedDict from langgraph.graph import END, START, StateGraph from sqlalchemy.orm import Session from app.schemas.steward import StewardPlanRequest, StewardPlanResponse from app.services import steward_intent_bootstrap # noqa: F401 导入即注册全部业务意图 from app.services.agent_conversations import AgentConversationService from app.services.scenes import REGISTRY as SCENE_REGISTRY from app.services.scenes.gate_rules import GateRule, SceneRoute from app.services.steward_action_contracts import StewardActionPlanBuilder from app.services.steward_constants import BUSINESS_CANONICAL_FIELD_ORDER from app.services.steward_context_resume import attach_resumed_task, should_resume_recent_task from app.services.steward_intent_agent import StewardIntentAgent, StewardIntentAgentResult from app.services.steward_model_plan_builder import StewardModelPlanBuilder from app.services.steward_off_topic_agent import StewardOffTopicAgent from app.services.steward_planner_extraction import StewardPlannerExtractionMixin from app.services.steward_planner_fallback import StewardPlannerFallbackMixin # ---- 模块级辅助函数:gate_classify 的判断逻辑 ---- def _compact_text(text: str) -> str: return re.sub(r"\s+", "", str(text or "")) def _scene_route_to_gate_decision(route: SceneRoute) -> str: """SceneRoute 映射到 gate_decision 字符串。""" if route == SceneRoute.HANDLER_ONLY: return "handler_only" if route == SceneRoute.OFF_TOPIC: return "off_topic" if route == SceneRoute.RESUME: return "resume" if route == SceneRoute.AMBIGUOUS: return "ambiguous" return "model_intent" class StewardGraphState(TypedDict, total=False): request: StewardPlanRequest db: Session message: str base_date: date scenario: str | None should_use_model: bool intent_result: StewardIntentAgentResult | None plan: StewardPlanResponse model_call_traces: list[dict[str, Any]] fallback_reason: str # 新增:上下文状态 recent_history: list[dict[str, Any]] steward_state: dict[str, Any] # 新增:门控裁决 gate_decision: str # "off_topic" | "handler_only" | "resume" | "ambiguous" | "model_intent" | "fallback" gate_scene_id: str | None # 新增:回填的 conversation_id conversation_id: str | None class StewardGraphPlannerService(StewardPlannerFallbackMixin, StewardPlannerExtractionMixin): """用 LangGraph 编排小财管家的意图识别、流程判断和兜底路径。 Phase 1 P1.3-P1.7:LangGraph 是唯一编排者,endpoint 退化为 3 行。 图拓扑: load_context → gate_classify → {off_topic/handler_only/resume/ambiguous/model_intent} → {build_off_topic_plan / execute_scene_handler / resume_recent_task / detect_model_intent} → attach_action_steps → persist_state """ def __init__( self, intent_agent: StewardIntentAgent | None = None, off_topic_agent: StewardOffTopicAgent | None = None, ) -> None: self.intent_agent = intent_agent self.off_topic_agent = off_topic_agent self._graph = self._build_graph() # ---- 上下文加载 + 门控裁决(P1.3-P1.4 新增) ---- def _load_context(self, state: StewardGraphState) -> dict[str, Any]: """读最近 10 条对话历史 + steward_state,注入 state。 替代 endpoint 的 _hydrate_required_application_gate + _inject_recent_conversation_history。 """ request = state.get("request") if request is None: return {} db = state.get("db") # 1. 读对话历史(只给模型用,不返回前端) recent_history: list[dict[str, Any]] = [] context_json = dict(request.context_json or {}) conversation_id = self._extract_conversation_id(context_json) if db is not None and conversation_id: try: recent_history = AgentConversationService(db).list_message_history( conversation_id, limit=10 ) except Exception: recent_history = [] # 2. 读 steward_state(DB 优先,前端传次之) steward_state: dict[str, Any] = {} if db is not None and conversation_id: try: conversation = AgentConversationService(db).get_conversation(conversation_id) if conversation is not None and isinstance(conversation.state_json, dict): stored = conversation.state_json.get("steward_state") if isinstance(stored, dict): steward_state = stored except Exception: steward_state = {} if not steward_state: incoming = context_json.get("steward_state") or context_json.get("stewardState") if isinstance(incoming, dict): steward_state = incoming # 3. 注入 recent_history 到 context_json(供 LLM 使用) if recent_history: request = request.model_copy( update={ "context_json": { **context_json, "recent_history": recent_history, } } ) return { "request": request, "recent_history": recent_history, "steward_state": steward_state, "message": str(request.message or "").strip(), "base_date": self._resolve_base_date_from_request(request), } def _gate_classify(self, state: StewardGraphState) -> dict[str, Any]: """统一门控裁决:单一决策点,按固定顺序决定场景和路由。 顺序: ① resume 门(用户说"再提交"+ state 有可恢复 flow → 上下文恢复) ② off_topic 门(复用 _classify_irrelevant_input:legacy 94 词 + registry 信号词 + greeting/meaningless 细分) ③ 规则匹配门(按 priority 遍历 scene_registry,命中 CHOICE 规则的) ④ LLM 门(规则未命中,走 model function call) """ from app.services.scenes import REGISTRY from app.services.scenes.gate_rules import GateRule request = state.get("request") if request is None: return {"gate_decision": "off_topic", "gate_scene_id": None} message = str(state.get("message") or "").strip() steward_state = state.get("steward_state") or {} # ① 闲聊拦截(极轻量:greeting + meaningless,省 LLM 成本,不依赖业务关键词) # 不用 _classify_irrelevant_input(那套带 94 词判断,会误杀"下周去上海"等正常业务输入) if self._is_lightweight_off_topic(message, request): return {"gate_decision": "off_topic", "gate_scene_id": None} # ② resume 门(用户说"再提交" + state 有可恢复 flow → 确定性恢复) resume_scene = should_resume_recent_task(message, steward_state) if resume_scene: return {"gate_decision": "resume", "gate_scene_id": resume_scene} # ③ 其他全部走 LLM(不再有规则匹配门;LLM function call 是唯一的意图识别者) return {"gate_decision": "model_intent", "gate_scene_id": None} def _is_lightweight_off_topic(self, message: str, request: StewardPlanRequest) -> bool: """极轻量闲聊拦截:只拦 greeting 和 meaningless,不做业务相关性判断。 有附件时一定不是闲聊(附件意味着用户有业务诉求)。 业务相关性交给 LLM 判断,规则只挡掉绝对无关的输入省 LLM 成本。 """ if request.attachments: return False compact = _compact_text(message) if not compact: return True if self._looks_like_greeting(compact): return True if self._looks_like_meaningless(compact): return True return False def _execute_scene_handler(self, state: StewardGraphState) -> dict[str, Any]: """HANDLER_ONLY 路由:不调 LLM,直接执行 scene 的 handler。 当前只有 query_travel_standard 走这条路径。handler 签名约定: handler(executor_self, request, current_user, trace) -> StewardActionExecuteResponse """ from app.services.scenes import REGISTRY from app.schemas.steward import ( StewardActionExecuteRequest, StewardActionExecuteResponse, StewardActionStep, StewardPlanResponse, StewardTask, StewardThinkingEvent, ) import time # scene_id 优先从 gate_scene_id 取(兼容旧行为),否则从 plan.tasks[0].task_type 取(LLM 驱动) scene_id = state.get("gate_scene_id") if not scene_id: plan = state.get("plan") if isinstance(plan, StewardPlanResponse) and plan.tasks: scene_id = str(plan.tasks[0].task_type or "").strip() scene = REGISTRY.get(scene_id or "") if scene_id else None if scene is None or scene.handler is None: plan = self._build_rule_fallback_graph_plan(state) return {"plan": plan} request = state.get("request") if request is None: plan = self._build_rule_fallback_graph_plan(state) return {"plan": plan} # 构造 handler 期望的 StewardActionExecuteRequest # 优先使用 LLM 已生成的 task(含 ontology_fields),否则构造最小 task existing_plan = state.get("plan") llm_task = None if isinstance(existing_plan, StewardPlanResponse) and existing_plan.tasks: llm_task = existing_plan.tasks[0] if llm_task is not None: task = llm_task elif scene.action_steps_builder is not None: task = StewardTask( task_id=f"task_handler_{int(time.time() * 1000)}", task_type=scene.scene_id, assigned_agent=scene.assigned_agent or "policy_query_assistant", title=scene.label, summary=str(request.message or "").strip(), status="delegated", requested_action="preview", ontology_fields={}, missing_fields=[], confirmation_required=False, ) else: task = StewardTask( task_id=f"task_handler_{int(time.time() * 1000)}", task_type=scene.scene_id, assigned_agent=scene.assigned_agent or "policy_query_assistant", title=scene.label, summary=str(request.message or "").strip(), status="delegated", requested_action="preview", ontology_fields={}, missing_fields=[], confirmation_required=False, ) # 构造 action steps(优先用 scene 的 builder,否则最小 step) action_steps: list[StewardActionStep] = [] if scene.action_steps_builder is not None: try: action_steps = list(scene.action_steps_builder(task) or []) except Exception: action_steps = [] if not action_steps: action_steps = [StewardActionStep( step_id=f"handler_{int(time.time() * 1000)}", action_type=scene.side_effect_actions[0] if scene.side_effect_actions else scene.scene_id, label=scene.label, target_task_id=task.task_id, status="planned", requires_confirmation=False, payload={"task_id": task.task_id, "ontology_fields": task.ontology_fields}, )] step = action_steps[0] action_request = StewardActionExecuteRequest( action_type=step.action_type, message=str(request.message or "").strip(), task=task, ) try: response = scene.handler(self, action_request, current_user=None, trace=[]) except Exception as exc: plan = self._build_rule_fallback_graph_plan(state) plan.thinking_events = list(plan.thinking_events) + [ StewardThinkingEvent( event_id=f"handler_error_{scene.scene_id}", stage="llm_function_call", title=f"{scene.label}执行失败", content=f"handler 抛错: {type(exc).__name__}: {str(exc)[:80]}", status="completed", ), ] return {"plan": plan} # handler 返回 StewardActionExecuteResponse,转换为 StewardPlanResponse answer = "" result_payload: dict[str, Any] = {} if isinstance(response, StewardActionExecuteResponse): answer = response.message or response.result_payload.get("answer_markdown", "") result_payload = dict(response.result_payload or {}) # 把查询结果放进 summary(给前端展示)和 thinking_event(过程摘要) plan = StewardPlanResponse( plan_id=f"steward_handler_{int(time.time() * 1000)}", planning_source=f"scene_handler:{scene.scene_id}", summary=answer or scene.label, next_action="answer_only", tasks=[task] if scene.action_steps_builder else [], thinking_events=[ StewardThinkingEvent( event_id=f"handler_{scene.scene_id}_done", stage="llm_function_call", title=f"已执行{scene.label}", content=answer or f"场景 {scene.scene_id} 已执行", status="completed", ) ], pending_flow_confirmation={"status": "none"}, conversation_id=state.get("conversation_id") or "", steward_state=state.get("steward_state") or {}, action_steps=[], ) return {"plan": plan} def _resume_recent_task(self, state: StewardGraphState) -> dict[str, Any]: """RESUME 路由:从 steward_state 恢复之前被拦/中断的 task。 保险①:100% 可靠,覆盖"再提交""继续提交"等确认类话术。 """ steward_state = state.get("steward_state") or {} scene_id = state.get("gate_scene_id") # 先建一个空 plan(无 task),让 attach_resumed_task 把恢复的 task 挂上 from app.schemas.steward import StewardPlanResponse empty_plan = StewardPlanResponse( plan_id="steward_resume_pending", planning_source="rule_fallback", summary="恢复上下文中的待办任务。", next_action="confirm_task", tasks=[], thinking_events=[], pending_flow_confirmation={"status": "none"}, ) if not scene_id: return {"plan": empty_plan} resumed = attach_resumed_task(empty_plan, steward_state, scene_id) return {"plan": resumed} def _persist_state( self, db: Session, request: StewardPlanRequest, plan: StewardPlanResponse, final_state: StewardGraphState, ) -> StewardPlanResponse: """图执行后的副作用:写 message + steward_state 到 DB。 替代 endpoint 的 _attach_conversation_state。 """ if db is None: return plan try: context_json = dict(request.context_json or {}) context_json["session_type"] = str(context_json.get("session_type") or "steward").strip() or "steward" conversation_id = self._extract_conversation_id(context_json) conversation_service = AgentConversationService(db) conversation = conversation_service.get_or_create_conversation( conversation_id=conversation_id, user_id=request.user_id, source="user_message", context_json=context_json, ) current_state = self._resolve_steward_state_for_persist(conversation.state_json, final_state) from app.services.steward_flow_state import StewardFlowStateService steward_state = StewardFlowStateService().merge_plan(current_state, plan) conversation = conversation_service.update_state( conversation_id=conversation.conversation_id, run_id=None, scenario="steward", intent="plan", context_json={**context_json, "steward_state": steward_state}, ) or conversation conversation_service.append_message( conversation_id=conversation.conversation_id, role="user", content=request.message, message_json={"source": "steward_plan_request"}, ) conversation_service.append_message( conversation_id=conversation.conversation_id, role="assistant", content=plan.summary, message_json={ "source": "steward_plan_response", "plan_id": plan.plan_id, "steward_state": steward_state, }, ) return plan.model_copy( update={ "conversation_id": conversation.conversation_id, "steward_state": steward_state, } ) except Exception: return plan # ---- 路由函数 ---- def _route_after_gate_classify(self, state: StewardGraphState) -> str: """gate_classify 后的路由:把 gate_decision 映射到下一个节点。""" decision = str(state.get("gate_decision") or "model_intent") return decision @staticmethod def _extract_conversation_id(context_json: dict[str, Any]) -> str | None: return str( context_json.get("conversation_id") or context_json.get("conversationId") or "" ).strip() or None @staticmethod def _resolve_base_date_from_request(request: StewardPlanRequest | None) -> date: if request is None: return date.today() from app.services.steward_planner_extraction import StewardPlannerExtractionMixin return StewardPlannerExtractionMixin._resolve_base_date( request.client_now_iso, dict(request.context_json or {}), ) @staticmethod def _resolve_steward_state_for_persist( conversation_state: Any, final_state: StewardGraphState, ) -> dict[str, Any]: state_json = conversation_state if isinstance(conversation_state, dict) else {} stored = state_json.get("steward_state") if isinstance(stored, dict) and stored: return stored graph_state = final_state.get("steward_state") if isinstance(graph_state, dict) and graph_state: return graph_state return {} def build_plan( self, request: StewardPlanRequest, db: Session | None = None, ) -> StewardPlanResponse: """编排一次 steward 计划请求,内部执行:load → classify → plan。 P1 中间状态:签名保持 build_plan(request) 不变以兼容现有测试/消费者。 显式传 db 时,load_context 节点会读历史/state;不传时图内 IO 静默跳过。 持久化由 endpoint 显式调用 _attach_conversation_state 完成(P3 收敛到图内)。 """ final_state = self._graph.invoke( { "request": request, "db": db, "model_call_traces": [], "fallback_reason": "", } ) plan = final_state.get("plan") if not isinstance(plan, StewardPlanResponse): raise RuntimeError("LangGraph 小财管家规划未生成有效计划。") return plan def _build_graph(self): graph = StateGraph(StewardGraphState) # 节点 graph.add_node("load_context", self._load_context) graph.add_node("gate_classify", self._gate_classify) graph.add_node("execute_scene_handler", self._execute_scene_handler) graph.add_node("resume_recent_task", self._resume_recent_task) graph.add_node("prepare_context", self._prepare_context) graph.add_node("detect_model_intent", self._detect_model_intent) graph.add_node("build_off_topic_plan", self._build_off_topic_graph_plan) graph.add_node("build_rule_fallback_plan", self._build_rule_fallback_graph_plan) graph.add_node("build_pending_flow_plan", self._build_pending_flow_fallback_graph_plan) graph.add_node("attach_action_steps", self._attach_action_steps) # 拓扑(P2:LLM 驱动,gate_classify 只输出 off_topic|resume|model_intent) graph.add_edge(START, "load_context") graph.add_edge("load_context", "gate_classify") graph.add_conditional_edges( "gate_classify", self._route_after_gate_classify, { "off_topic": "build_off_topic_plan", "resume": "resume_recent_task", "model_intent": "prepare_context", }, ) graph.add_edge("resume_recent_task", "attach_action_steps") graph.add_conditional_edges( "prepare_context", self._route_after_prepare_context, { "model": "detect_model_intent", "off_topic": "build_off_topic_plan", "fallback": "build_rule_fallback_plan", }, ) # detect_model_intent 成功后:HANDLER_ONLY 类(task_type 对应 scene.route=HANDLER_ONLY) # 转 execute_scene_handler;其他转 attach_action_steps graph.add_conditional_edges( "detect_model_intent", self._route_after_model_intent, { "done": "attach_action_steps", "handler_only": "execute_scene_handler", "off_topic": "build_off_topic_plan", "fallback": "build_rule_fallback_plan", }, ) graph.add_edge("execute_scene_handler", "attach_action_steps") graph.add_edge("build_off_topic_plan", "attach_action_steps") graph.add_edge("build_rule_fallback_plan", "attach_action_steps") graph.add_edge("attach_action_steps", END) return graph.compile() def _prepare_context(self, state: StewardGraphState) -> dict[str, Any]: request = state["request"] message = self._clean_text(request.message) if not message: raise ValueError("小财管家需要一段任务描述。") base_date = self._resolve_base_date(request.client_now_iso, request.context_json) return { "message": message, "base_date": base_date, "scenario": self._classify_irrelevant_input(message, request), "should_use_model": bool( self.intent_agent is not None and self._should_use_model_intent_recognition(message, base_date, request) ), } @staticmethod def _route_after_prepare_context(state: StewardGraphState) -> str: if state.get("should_use_model"): return "model" if state.get("scenario") is not None: return "off_topic" return "fallback" def _detect_model_intent(self, state: StewardGraphState) -> dict[str, Any]: request = state["request"] message = state["message"] base_date = state["base_date"] model_call_traces: list[dict[str, Any]] = [] if self.intent_agent is None: return {} try: intent_result = self.intent_agent.detect( request, base_date=base_date, canonical_fields=list(BUSINESS_CANONICAL_FIELD_ORDER), ) if intent_result is None: return { "model_call_traces": self._last_intent_call_traces(model_call_traces), "fallback_reason": ( "主模型未返回可用的 function calling 计划，已切换到规则兜底。" ), } model_call_traces = intent_result.model_call_traces llm_plan = StewardModelPlanBuilder(self).build( intent_result, request=request, base_date=base_date, ) if llm_plan is None: return { "model_call_traces": self._last_intent_call_traces(model_call_traces), "fallback_reason": ( "主模型未返回可用的 function calling 计划，已切换到规则兜底。" ), } if self._looks_like_ambiguous_travel_flow(message, base_date, request): return { "plan": self._build_pending_flow_fallback_plan( request, base_date=base_date, model_call_traces=model_call_traces, fallback_reason=( "主模型返回了直接任务，但当前话术没有明确申请或报销动作；" "服务端已改为候选流程确认，避免误入申请流程。" ), planning_source="llm_function_call", ), "model_call_traces": model_call_traces, } return { "intent_result": intent_result, "plan": llm_plan, "model_call_traces": model_call_traces, } except Exception as exc: return { "model_call_traces": self._last_intent_call_traces(model_call_traces), "fallback_reason": f"主模型 function calling 调用失败，已切换到规则兜底：{exc}", } @staticmethod def _route_after_model_intent(state: StewardGraphState) -> str: plan = state.get("plan") if isinstance(plan, StewardPlanResponse): # LLM 成功:检查第一个 task 是否对应 HANDLER_ONLY 场景(查询类,直接执行 handler) if plan.tasks: from app.services.scenes import REGISTRY from app.services.scenes.gate_rules import SceneRoute first_task_type = str(plan.tasks[0].task_type or "").strip() scene = REGISTRY.get(first_task_type) if scene is not None and scene.route == SceneRoute.HANDLER_ONLY: return "handler_only" return "done" if state.get("scenario") is not None: return "off_topic" return "fallback" def _build_off_topic_graph_plan( self, state: StewardGraphState, ) -> dict[str, StewardPlanResponse]: return { "plan": self._build_off_topic_plan( state["request"], scenario=str(state.get("scenario") or ""), model_call_traces=state.get("model_call_traces") or [], fallback_reason=str(state.get("fallback_reason") or ""), ) } def _build_pending_flow_fallback_graph_plan( self, state: StewardGraphState, ) -> dict[str, StewardPlanResponse]: request = state["request"] return { "plan": self._build_pending_flow_fallback_plan( request, base_date=state["base_date"], model_call_traces=state.get("model_call_traces") or [], fallback_reason=str(state.get("fallback_reason") or ""), ) } def _build_rule_fallback_graph_plan( self, state: StewardGraphState, ) -> dict[str, StewardPlanResponse]: return { "plan": self._build_rule_fallback_plan( state["request"], base_date=state["base_date"], model_call_traces=state.get("model_call_traces"), fallback_reason=str(state.get("fallback_reason") or ""), ) } @staticmethod def _attach_action_steps(state: StewardGraphState) -> dict[str, StewardPlanResponse]: plan = state.get("plan") if not isinstance(plan, StewardPlanResponse): raise RuntimeError("LangGraph 小财管家动作规划缺少有效计划。") return {"plan": StewardActionPlanBuilder().attach_action_steps(plan)} def _last_intent_call_traces( self, fallback_traces: list[dict[str, Any]], ) -> list[dict[str, Any]]: return getattr(self.intent_agent, "last_call_traces", []) or fallback_traces