336 lines
16 KiB
Python
336 lines
16 KiB
Python
"""圆桌规划 · 第一步「任务理解」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": "<uuid>" }
|
||
|
||
与 ``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:<gateway port>(详见 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": "<final AI text>",
|
||
"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",
|
||
},
|
||
)
|