"""圆桌规划 · 第一步「任务理解」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 ( _ROUNDTABLE_THREAD_METADATA, _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, ) def _normalize_question(text: str) -> str: """归一化澄清问题文本,用于"和过往是否重复"的判断。 LLM 复述时常见模式: - 完全一样的字符串 - 仅前后空白、标点、emoji 不同(如多/少一个问号) - 仅大小写差异(中文场景几乎不见,但兼容英文/拼音) 所以归一化时统一:小写 + 去除非字母/数字/中文字符 + 折叠空白。 Levenshtein/语义相似度等模糊匹配先不做,等观察到误判再迭代。 """ if not isinstance(text, str): return "" lowered = text.strip().lower() # 只保留中英文字符与数字,去掉 ?。!?,。"":/、() 等标点 + emoji + 空白。 return re.sub(r"[^0-9a-z一-鿿]+", "", lowered) def _normalize_options(raw: object) -> tuple[str, ...]: """把 options 拍平成可比较的归一化元组,用于"选项是否和上一轮一致"的判断。""" if raw is None: return () if isinstance(raw, str): # 偶有模型把 list 序列化成 JSON 字符串发回来。 try: raw = json.loads(raw) except (json.JSONDecodeError, TypeError): return (_normalize_question(raw),) if not isinstance(raw, list): return (_normalize_question(str(raw)),) out: list[str] = [] for item in raw: if isinstance(item, dict): label = item.get("label") or item.get("title") or item.get("name") or item.get("value") or item.get("id") or "" out.append(_normalize_question(str(label))) else: out.append(_normalize_question(str(item))) # 顺序无关:LLM 偶尔会调换选项顺序,但语义上还是同一组。 return tuple(sorted(o for o in out if o)) def _count_past_clarifications(messages: list[dict[str, Any]]) -> int: """统计当前 thread 内已经发出过的 ``ask_clarification`` 次数。 用来给 ``stream_intent`` 做"3 轮硬上限"兜底: - 0-1 次:正常流程,模型自行决定继续问还是收敛 - 2 次(即将进入第 3 轮):prompt 追加系统提示,要求本轮必须 INTENT_READY - ≥3 次:工具白名单移除 ``ask_clarification``,模型物理上无法再问 只数"已经成型"的 tool_call,不区分用户是否回答过——LangGraph 把 ask 工具的调用永久记录在 AIMessage.tool_calls 里,数它即可。 """ if not isinstance(messages, list): return 0 count = 0 for msg in messages: if not isinstance(msg, dict): continue if (msg.get("type") or "").lower() not in ("ai", "aimessage", "aimessagechunk"): continue for tc in msg.get("tool_calls") or []: if (tc.get("name") or "").lower() == "ask_clarification": count += 1 return count async def _fetch_thread_messages( client: httpx.AsyncClient, base: str, headers: dict[str, str], thread_id: str, ) -> list[dict[str, Any]]: """读取当前 thread checkpoint 的 messages 列表(best-effort)。 用 ASGITransport loopback 调 ``GET /api/threads/{tid}/state``,失败时返回 空列表——计数兜底是个"刹车",失败时退化成原有的纯 SOUL 自律行为,不阻断主流程。 """ try: resp = await client.get(f"{base}/api/threads/{thread_id}/state", headers=headers) except Exception as exc: logger.warning("intent: get thread state failed (%s) — falling back to soul-only flow", exc) return [] if resp.status_code != 200: logger.warning( "intent: get thread state %s returned %s — falling back to soul-only flow", thread_id, resp.status_code, ) return [] try: payload = resp.json() except Exception: return [] values = payload.get("values") if isinstance(payload, dict) else None if not isinstance(values, dict): return [] messages = values.get("messages") return messages if isinstance(messages, list) else [] # 硬上限:超过这个轮数,无论模型怎么想,都强制移除 ask_clarification 工具。 # 与 SOUL.md §0 「硬规则 2」对齐——"绝不存在第 4 轮"。 _MAX_CLARIFICATION_ROUNDS = 3 def _is_repeated_clarification( messages: list[dict[str, Any]], *, new_question: str, new_options: object, new_tool_call_id: str | None = None, ) -> bool: """检测本轮的 ask_clarification 是否在过往轮次问过。 判定为重复必须同时满足: 1. 历史里至少有一次 ``ask_clarification`` 的问题文本 / 选项 与本次归一化相同; 2. 用户在那次之后**已经发过消息**(即"已回答过")。 没有这条限制会把"模型在同一 run 内多次输出同一 tool_call_chunks" 误判成重复,导致首次澄清都吞掉。 3. 不是同一个 tool_call(LangGraph 偶有把同一 call 拆成多块返回的情况)。 传回 True → 上层应把 status 从 ``clarification`` 降级为 ``asking``, 避免前端弹同一张卡片(配合 SOUL §2.5 prompt 双层防御)。 """ norm_new_q = _normalize_question(new_question) norm_new_opts = _normalize_options(new_options) if not norm_new_q and not norm_new_opts: return False seen_match_index: int | None = None for idx, msg in enumerate(messages): if not isinstance(msg, dict): continue if (msg.get("type") or "").lower() not in ("ai", "aimessage", "aimessagechunk"): continue for tc in msg.get("tool_calls") or []: if (tc.get("name") or "").lower() != "ask_clarification": continue if new_tool_call_id and tc.get("id") == new_tool_call_id: # 同一个 tool_call 的不同 chunk,不算重复。 continue args = tc.get("args") or {} past_q = _normalize_question(str(args.get("question") or "")) past_opts = _normalize_options(args.get("options")) # 问题文本和选项任一明确重叠就视为重复: # - question 相同(options 可能空) # - options 相同且非空(question 可能被改写) q_match = bool(past_q) and past_q == norm_new_q opt_match = bool(past_opts) and past_opts == norm_new_opts if q_match or opt_match: seen_match_index = idx break if seen_match_index is not None: break if seen_match_index is None: return False # 校验用户在该次澄清之后是否已经发过 human 消息(= 回答过)。 for msg in messages[seen_match_index + 1:]: if not isinstance(msg, dict): continue msg_type = (msg.get("type") or "").lower() if msg_type in ("human", "humanmessage", "user"): return True return False @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, metadata=_ROUNDTABLE_THREAD_METADATA) 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 "") # 用户在 Step 1 上传的参考文件(已经过 /api/threads/{thread_id}/uploads)。 # 前端传 [{filename, size, path, status}, ...],这里原样透传给 _run_payload → # additional_kwargs.files → UploadsMiddleware 自动注入清单 + 解锁 read_file 等工具。 raw_files = payload.get("files") files = raw_files if isinstance(raw_files, list) else [] if not thread_id: raise HTTPException(status_code=400, detail="thread_id is required") # 允许「仅文件、无文本」的回合:带了文件就不强制要求 message。 if not message and not files: 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: # —— 3 轮硬上限兜底 —— # 在发起 run 之前先读一次 thread state,数当前 ask_clarification 已发出次数: # past=0/1 → 正常,不动 message,不动工具白名单 # past=2(本轮即将变成第 3 轮)→ 给消息加前缀,强提示"必须 INTENT_READY" # past≥3 → 直接把 ask_clarification 也加进 excluded_tools,工具物理消失 # 这一步是个"刹车":SOUL 让模型自律,这里让系统兜底。 past_clarifications = _count_past_clarifications( await _fetch_thread_messages(client, base, headers, thread_id) ) # 1. ask_clarification 的工具白名单——超过硬上限就移除。 base_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", ] if past_clarifications >= _MAX_CLARIFICATION_ROUNDS: base_excluded_tools.append("ask_clarification") logger.info( "intent stream: past_clarifications=%d >= %d, force-disabling " "ask_clarification to break the loop", past_clarifications, _MAX_CLARIFICATION_ROUNDS, ) # 带了上传文件时,解锁「读」类工具(read_file / ls / grep / view_image), # 否则 UploadsMiddleware 注入了文件清单、模型却没工具读取。仍保留对 # write_file / str_replace / present_files / bash / agent_orchestration 的封锁, # 防止意图阶段越界做方案/派活。 if files: read_tools = {"read_file", "ls", "grep", "view_image"} base_excluded_tools = [t for t in base_excluded_tools if t not in read_tools] # 2. message 前缀——给模型一个明确的"本轮必须收敛"信号。 # 仅文件、无文本时给一句兜底引导,让模型先读文件再澄清意图。 effective_message = message or "我上传了文件,请先阅读文件内容,再据此理解并澄清我的任务意图。" if past_clarifications >= _MAX_CLARIFICATION_ROUNDS: effective_message = ( f"[系统强制] 已澄清 {past_clarifications} 轮,触发硬上限。" f"本轮请直接输出 [INTENT_READY],缺的字段用 assumptions 兜底," f"绝对不要再调任何工具,也不要再询问任何问题。\n\n" f"用户最新输入:{message}" ) elif past_clarifications >= _MAX_CLARIFICATION_ROUNDS - 1: effective_message = ( f"[系统提示] 已澄清 {past_clarifications} 轮,这是最后一轮。" f"本轮请直接输出 [INTENT_READY],未明确的字段用 assumptions 兜底。\n\n" f"用户最新输入:{message}" ) body = _run_payload( agent_name=INTENT_AGENT_ID, model_name=model_name, thread_id=thread_id, new_message=effective_message, # Intent agent only ever needs ask_clarification (and even that # is yanked once past_clarifications hits the cap above). Block # everything else so the model can't drift into solutioning # (e.g. saving a design doc with write_file) — SOUL prose is # not reliable on its own, hard exclusion is. excluded_tools=base_excluded_tools, skill_stop_names=[], files=files, ) # 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 # SOUL §0 硬规则 3 要求 ```json``` 反引号闭合后不得再输出任何字符, # 但模型仍偶尔会在后面接 "那么我帮你列一下大纲……" 之类的尾巴。 # 终态帧只回到 marker 块结尾 + 一个换行,把废话从 content 里裁掉—— # 草稿持久化 / 跨设备重放 / 前端 splitIntentReadyBlock 的 after # 段都因此干净。流式期间用户仍会逐 token 看到那段废话,前端 # Step1Panel 已经把 `parts.after` 隐藏掉,体验闭环。 ready_text = msg_text[: m.end()].rstrip() + "\n" 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 # 兜底:模型偶尔会复述上一轮的同一澄清问题(SOUL §2.5 prompt # 已经强约束,但小模型 / 长上下文仍可能漏跟随)。检测到完全 # 重复时,把 status 从 clarification 降级为 asking,前端只渲染 # 文本气泡不弹卡片,避免用户看到"同样选项又出现一次"。 if _is_repeated_clarification( messages, new_question=question, new_options=cargs.get("options"), new_tool_call_id=clarification_call.get("id"), ): logger.warning( "intent stream: dropping duplicate ask_clarification " "(question=%r) — already asked & answered earlier in thread", question[:80], ) fallback_msg = ( display_content or "(系统识别到智能体重复了上一问题,已自动跳过。请补充其他信息继续推进。)" ) final_frame: dict[str, Any] = { "status": "asking", "content": fallback_msg, "summary": None, } yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n" return 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", }, )