文档修改
This commit is contained in:
1 parent
dffb8a955b
commit
8c55d4b55d
20 files changed
+1315
-5421
No files matched your search
@@ -1,13 +1,52 @@
|
||||
"""Task-intent agent endpoints (Step 1 of the roundtable flow).
|
||||
"""圆桌规划 · 第一步「任务理解」Gateway 路由。
|
||||
|
||||
Lightweight wrapper around the lead-agent runtime that runs a single built-in
|
||||
agent (``roundtable-intent``) on its own thread. The agent's job is to do 2-5
|
||||
clarifying turns with the user and then emit a structured
|
||||
``{objective, constraints, assumptions}`` summary the frontend hands off to
|
||||
the multi-agent roundtable as its initial intent.
|
||||
前端页面:``/page/workspace/roundtable/planning`` Step 1
|
||||
前端模块:``frontend-web/src/roundtable-planning/api/intent.ts``
|
||||
|
||||
Same SSE shape as ``multi_agent.py`` (transparent passthrough + appended
|
||||
status frame), so the frontend can reuse the same reader pattern.
|
||||
职责
|
||||
----
|
||||
在独立 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
|
||||
@@ -40,11 +79,11 @@ 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"
|
||||
|
||||
# Matches the SOUL-mandated handoff signal: a [INTENT_READY] line followed by
|
||||
# a ```json ... ``` block. The model is told to emit this only when it judges
|
||||
# the user's task is fully specified.
|
||||
# SOUL 规定的交接信号:``[INTENT_READY]`` + markdown json 代码块。
|
||||
# group(1) 解析为 IntentSummary;解析失败则继续走澄清/asking 分支。
|
||||
_INTENT_READY_PATTERN = re.compile(
|
||||
r"\[INTENT_READY\]\s*```json\s*(\{.*?\})\s*```",
|
||||
re.DOTALL,
|
||||
@@ -53,12 +92,17 @@ _INTENT_READY_PATTERN = re.compile(
|
||||
|
||||
@router.post("/init")
|
||||
async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str, Any]:
|
||||
"""Create a fresh thread for an intent-clarification session.
|
||||
"""创建任务理解会话用的空 thread。
|
||||
|
||||
Returns the stable built-in ``agent_id`` so the frontend doesn't need to
|
||||
know it. Unlike multi-agent ``/init``, no coordinator is built — the
|
||||
intent agent is long-lived and already registered via the legacy
|
||||
agent-sync path on disk.
|
||||
请求体:``{ "model": "deepseek-chat" }``(可选,当前 init 未把 model 写入 thread,
|
||||
实际模型在 ``/stream`` 的每次 run 里指定)。
|
||||
|
||||
响应::
|
||||
|
||||
{ "status": "success", "agent_id": "roundtable-intent", "thread_id": "<uuid>" }
|
||||
|
||||
与 ``POST /api/multi-agent/init`` 的区别:不创建协调智能体、不建多席位
|
||||
thread 映射;agent 本身已通过磁盘 ``.deer-flow/agents/`` 同步注册。
|
||||
"""
|
||||
base = _loopback_base(request)
|
||||
headers = _auth_headers(request)
|
||||
@@ -119,6 +163,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
# 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",
|
||||
@@ -139,6 +184,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
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:
|
||||
@@ -148,9 +194,10 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
|
||||
messages = _parse_last_messages(captured)
|
||||
|
||||
# [INTENT_READY] wins over ask_clarification: the model may emit
|
||||
# the handoff marker in an earlier AI message while the latest
|
||||
# dispatch still carries a stale clarification tool call.
|
||||
# --- 终态分支 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):
|
||||
@@ -177,9 +224,9 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
return
|
||||
|
||||
# Find the latest AIMessage with tool_calls (typically
|
||||
# ask_clarification) — falls back to the latest plain
|
||||
# AIMessage when the model produced no tool call.
|
||||
# --- 终态分支 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 []
|
||||
@@ -191,6 +238,8 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
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] = {
|
||||
@@ -207,6 +256,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
return
|
||||
|
||||
# --- 终态分支 3:普通 AI 回复,继续多轮对话 ---
|
||||
final_frame: dict[str, Any] = {
|
||||
"status": "asking",
|
||||
"content": content,
|
||||
|
||||
Reference in new issue
Block a user