"""圆桌规划 · 第一步「任务理解」Gateway 路由。 前端页面:``/page/workspace/roundtable/planning`` Step 1 前端模块:``frontend-web/src/roundtable-planning/api/intent.ts`` 职责 ---- 在独立 thread 上运行内置智能体 ``roundtable-intent``(SOUL 见 ``.deer-flow/agents/roundtable-intent/SOUL.md``),与用户进行 2–5 轮澄清, 最终输出结构化意图 ``{objective, constraints, assumptions}``,供 Step 2 总控协调智能体作为初始 prompt。 与 ``multi_agent.py`` 的关系 --------------------------- - **复用**同一套 loopback 工具:``_stream_upstream``、``_run_payload``、 ``_parse_last_messages`` 等,保证 SSE 透传 + 末尾状态帧的解析逻辑一致。 - **不复用** ``/init`` 的协调智能体创建逻辑:intent 是长期注册的内置 agent, 只需 ``POST /api/intent/init`` 创建 thread 即可。 SSE 协议(与前端 ``streamIntent`` 对齐) -------------------------------------- 1. 透传 LangGraph ``/api/threads/{id}/runs/stream`` 的全部 ``data:`` 行 (含 ``messages-tuple`` 增量,供 UI 流式打字)。 2. 流结束后追加**一条** JSON 状态帧(``data: {...}\\n\\n``),字段: ``status`` — 终态枚举: - ``asking``:本轮无 ``ask_clarification``,模型仍在追问或闲聊; - ``clarification``:本轮以澄清工具结束,需用户选选项/自定义输入; - ``done``:已解析 ``[INTENT_READY]`` + JSON 块,``summary`` 有值; - ``error``:上游或网关异常。 ``content`` — 展示用 AI 正文(澄清时优先用 tool 后的 follow-up 文本)。 仅 ``status == "done"`` 时带 ``summary``;澄清时还带 ``question``、``clarification_type``、``clarification_context``、 ``options``、``allow_custom``、``allow_multiple``(见 ``resolve_allow_multiple``)。 终态判定优先级(实现细节,勿随意调整) ------------------------------------ 1. **``[INTENT_READY]`` 优先**:从最新消息向前扫描 AIMessage,正则匹配 SOUL 规定的 ``[INTENT_READY]\\n```json {...} `````;即使最后一条消息仍带 过期的 ``ask_clarification`` tool_call,也返回 ``done``(避免前端卡在澄清 UI)。 2. 否则看最后一条带 ``tool_calls`` 的 AIMessage 是否含 ``ask_clarification``。 3. 否则 ``asking``。 工具白名单 ---------- ``excluded_tools`` 屏蔽除 ``ask_clarification`` 外的一切工具,防止模型偏离 澄清任务去写文件、派活等(SOUL 文字约束不可靠,硬排除更稳)。 """ from __future__ import annotations import asyncio import json import logging import re from typing import Any, AsyncIterator import httpx from fastapi import APIRouter, Body, HTTPException, Request from fastapi.responses import StreamingResponse # Reuse the building blocks already in multi_agent.py — keeps both routers # identical in connection handling, payload shape, and error mapping. from app.gateway.routers._roundtable_seed import ensure_roundtable_functional_agents from app.gateway.routers.multi_agent import ( _auth_headers, _create_thread, _diagnose_exception, _find_dispatch_message, _find_trailing_ai_text, _flatten_content, _loopback_base, _make_loopback_client, _parse_last_messages, _run_payload, _stream_upstream, ) from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple logger = logging.getLogger(__name__) router = APIRouter(prefix="/api/intent", tags=["intent"]) # 内置 agent 目录名,须与 ``.deer-flow/agents/roundtable-intent/`` 一致。 INTENT_AGENT_ID = "roundtable-intent" # SOUL 规定的交接信号:``[INTENT_READY]`` + markdown json 代码块。 # group(1) 解析为 IntentSummary;解析失败则继续走澄清/asking 分支。 _INTENT_READY_PATTERN = re.compile( r"\[INTENT_READY\]\s*```json\s*(\{.*?\})\s*```", re.DOTALL, ) @router.post("/init") async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str, Any]: """创建任务理解会话用的空 thread。 请求体:``{ "model": "<可选>" }``(可选,当前 init 未把 model 写入 thread, 实际模型在 ``/stream`` 的每次 run 里指定;缺省由 lead_agent 回退到 ``config.yaml`` 的 ``models[0]``,前端通常传当前下拉框选中的 model 名)。 响应:: { "status": "success", "agent_id": "roundtable-intent", "thread_id": "" } 与 ``POST /api/multi-agent/init`` 的区别:不创建协调智能体、不建多席位 thread 映射;agent 本身已通过磁盘 ``.deer-flow/agents/`` 同步注册。 """ # 调用前自检:内网部署 .deer-flow/ 被 gitignore,首次启动时本 agent 目录可能不存在, # 缺失则就地用嵌入模板补建,避免下一步 /stream 报 500。 ensure_roundtable_functional_agents() base = _loopback_base(request) headers = _auth_headers(request) # TCP loopback 到 127.0.0.1:(详见 multi_agent._make_loopback_client)。 # 不要在这里替换成 httpx.ASGITransport——曾试过,会整段 buffer SSE 流导致前端 # 看不到逐 token 增量。 try: async with _make_loopback_client(request) as client: thread_id = await _create_thread(client, base, headers) except HTTPException: # 上游已用结构化方式失败,原样传给前端不需要二次包装。 raise except Exception as exc: # 把根因暴露给前端而不是吞成裸 500——内网部署常见的「config.yaml 模型外网不通」 # / 「内置 agent 目录缺失」/ 「loopback 走代理」都能在前端面板直接看到。 # FastAPI 把 detail=dict 序列化为 {"detail": {...}};前端 initIntent # 在 !res.ok 分支里读 detail.hint / trace_tail 渲染诊断面板。 diagnostic = _diagnose_exception(exc, context="intent_init") logger.error("intent init failed: %s", diagnostic, exc_info=exc) raise HTTPException(status_code=500, detail=diagnostic) from exc return { "status": "success", "agent_id": INTENT_AGENT_ID, "thread_id": thread_id, } @router.post("/stream") async def stream_intent(request: Request, payload: dict = Body(...)) -> StreamingResponse: """Drive one turn of the intent dialogue via SSE. Body: ``{thread_id, message, model?}``. Streams upstream LangGraph frames through transparently, then appends one status frame: { "status": "asking" | "clarification" | "done" | "error", "content": "", "summary": {...} | null, // only when status == "done" // when status == "clarification": "question", "clarification_type", "clarification_context", "options", "allow_custom", "allow_multiple" } """ thread_id = str(payload.get("thread_id") or "").strip() message = str(payload.get("message") or "").strip() # 不写死任何默认模型名:空串会让 lead_agent._resolve_model_name() 回退到 # config.yaml 的 models[0],与 /api/ai-writing 等其它路由一致,内网部署只配 # 自己的本地模型即可工作。 model_name = str(payload.get("model") or "") if not thread_id: raise HTTPException(status_code=400, detail="thread_id is required") if not message: raise HTTPException(status_code=400, detail="message is required") # 调用前自检:防御性二次检查——若管理员在 init 之后手动删了目录,这里也能自愈。 ensure_roundtable_functional_agents() base = _loopback_base(request) headers = _auth_headers(request) async def stream_generator() -> AsyncIterator[str]: # ASGITransport:进程内直调本机 ASGI app,**不走 TCP / 不经过网络栈**, # 因此既无须 trust_env=False 防代理,也不存在 loopback 40s 超时这种坑。 async with _make_loopback_client(request) as client: try: body = _run_payload( agent_name=INTENT_AGENT_ID, model_name=model_name, thread_id=thread_id, new_message=message, # Intent agent only ever needs ask_clarification. Block # everything else so the model can't drift into solutioning # (e.g. saving a design doc with write_file) — the model # tends to ignore SOUL prose, hard exclusion is reliable. # 仅保留 ask_clarification;其余工具见模块 docstring「工具白名单」。 excluded_tools=[ "web_search", "present_files", "view_image", "agent_orchestration", "bash", "ls", "read_file", "write_file", "str_replace", "memory", "hindsight_recall", "hindsight_reflect", "hindsight_retain", "task", "write_todos", ], skill_stop_names=[], ) # captured:上游 SSE 全部 data 行,用于流结束后从 values 快照取 messages。 captured: list[str] = [] async for line, done in _stream_upstream(client, base, headers, thread_id, body): if line is not None: yield line if line.endswith("\n") else line + "\n" elif done is not None: captured = done messages = _parse_last_messages(captured) # --- 终态分支 1:结构化意图已就绪(最高优先级)--- # 模型可能在较早的 AIMessage 里已输出 [INTENT_READY],而最后一轮 # 仍残留 ask_clarification 的 tool_calls;必须先扫 READY,否则前端 # 会错误展示澄清卡片且 intentReady 无法解锁 Step 2。 summary: dict[str, Any] | None = None ready_text: str = "" for msg in reversed(messages): if not isinstance(msg, dict): continue if (msg.get("type") or "").lower() not in ("ai", "aimessage", "aimessagechunk"): continue msg_text = _flatten_content(msg.get("content", "")) m = _INTENT_READY_PATTERN.search(msg_text) if m: try: summary = json.loads(m.group(1)) except json.JSONDecodeError as exc: logger.warning("intent summary JSON parse failed: %s", exc) summary = None ready_text = msg_text break if summary and ready_text: final_frame = { "status": "done", "content": ready_text, "summary": summary, } yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n" return # --- 终态分支 2:本轮以 ask_clarification 结束 --- # _find_dispatch_message:从后往前找带 tool_calls 的 AIMessage # (SkillStop/澄清 ToolMessage 之后的那条 AI 消息)。 dispatch_msg = _find_dispatch_message(messages) content = _flatten_content(dispatch_msg.get("content", "")) tool_calls = dispatch_msg.get("tool_calls") or [] clarification_call = next( (tc for tc in tool_calls if (tc.get("name") or "").lower() == "ask_clarification"), None, ) if clarification_call is not None: cargs = clarification_call.get("args") or {} question = str(cargs.get("question") or "").strip() # ClarificationMiddleware 常在 tool 之后还有一条纯文本 AIMessage, # 比 tool_call 旁的短 preamble 更适合作为气泡正文。 follow_up = _find_trailing_ai_text(messages, exclude_text=content) display_content = follow_up or content or question final_frame: dict[str, Any] = { "status": "clarification", "content": display_content, "question": question, "clarification_type": str(cargs.get("clarification_type") or ""), "clarification_context": str(cargs.get("context") or ""), "options": cargs.get("options") or [], "allow_custom": bool(cargs.get("allow_custom", True)), "allow_multiple": resolve_allow_multiple(cargs), "summary": None, } yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n" return # --- 终态分支 3:普通 AI 回复,继续多轮对话 --- final_frame: dict[str, Any] = { "status": "asking", "content": content, "summary": None, } yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n" except HTTPException as exc: logger.warning("intent stream HTTPException: %s %s", exc.status_code, exc.detail) # HTTPException 的 detail 可能本身就是 dict(上游已结构化),也可能是 str。 # 统一包装成与 _diagnose_exception 同构的字段,便于前端按一种模型渲染。 detail_payload: Any = exc.detail error_detail: dict[str, Any] if isinstance(detail_payload, dict) and "code" in detail_payload: error_detail = detail_payload else: error_detail = { "code": "http_exception", "message": f"[{exc.status_code}] {detail_payload}", "exception_type": "HTTPException", "exception_repr": repr(exc), "root_type": None, "root_repr": None, "hint": None, "trace_tail": [], "context": "intent_stream", } err = { "status": "error", "content": error_detail["message"], "summary": None, "error_detail": error_detail, } yield f"data: {json.dumps(err, ensure_ascii=False)}\n\n" except Exception as exc: diagnostic = _diagnose_exception(exc, context="intent_stream") logger.error("intent stream failed: %s", diagnostic, exc_info=exc) err = { "status": "error", "content": diagnostic["message"], "summary": None, "error_detail": diagnostic, } yield f"data: {json.dumps(err, ensure_ascii=False)}\n\n" return StreamingResponse( stream_generator(), media_type="text/event-stream", headers={ "Cache-Control": "no-cache", "X-Accel-Buffering": "no", "Connection": "keep-alive", }, )