feat: 岗位会商独立意图智能体与四项意图 schema
岗位会商 Step 1 改用 position-roundtable-intent 智能体,输出 coreGoals/riskWarnings/keyPoints/strategicSignificance 四项数组;支持单轮多张协助卡、按轮次计澄清上限,并兼容旧会话 objective/constraints 映射。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
ca32a22c0d
commit
f8757d1a43
24 files changed
+1258
-257
No files matched your search
@@ -34,6 +34,7 @@ SSE 协议(与前端 ``streamIntent`` 对齐)
|
||||
仅 ``status == "done"`` 时带 ``summary``;澄清时还带
|
||||
``question``、``clarification_type``、``clarification_context``、
|
||||
``options``、``allow_custom``、``allow_multiple``(见 ``resolve_allow_multiple``)。
|
||||
多卡回合还带 ``clarifications`` 完整数组;顶层字段始终镜像第一张卡以兼容旧客户端。
|
||||
|
||||
终态判定优先级(实现细节,勿随意调整)
|
||||
------------------------------------
|
||||
@@ -65,7 +66,10 @@ from app.gateway.roundtable_diag import record_foreground_diag
|
||||
|
||||
# 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._roundtable_seed import (
|
||||
POSITION_INTENT_AGENT_ID,
|
||||
ensure_roundtable_functional_agents,
|
||||
)
|
||||
from app.gateway.routers.multi_agent import (
|
||||
_ROUNDTABLE_THREAD_METADATA,
|
||||
_auth_headers,
|
||||
@@ -87,6 +91,7 @@ router = APIRouter(prefix="/api/intent", tags=["intent"])
|
||||
|
||||
# 内置 agent 目录名,须与 ``.deer-flow/agents/roundtable-intent/`` 一致。
|
||||
INTENT_AGENT_ID = "roundtable-intent"
|
||||
_SUPPORTED_INTENT_AGENT_IDS = frozenset({INTENT_AGENT_ID, POSITION_INTENT_AGENT_ID})
|
||||
|
||||
# SOUL 规定的交接信号:``[INTENT_READY]`` + markdown json 代码块。
|
||||
# group(1) 解析为 IntentSummary;解析失败则继续走澄清/asking 分支。
|
||||
@@ -96,7 +101,49 @@ _INTENT_READY_PATTERN = re.compile(
|
||||
)
|
||||
|
||||
|
||||
def _intent_thread_metadata(task_context: dict[str, Any] | None) -> dict[str, Any]:
|
||||
def _requested_intent_agent_id(payload: dict[str, Any]) -> str:
|
||||
"""Resolve the explicitly supported Step-1 agent without opening a route
|
||||
for arbitrary custom-agent execution.
|
||||
|
||||
Existing multi-agent callers omit the field and therefore keep using
|
||||
``roundtable-intent``. Position roundtable sends the dedicated ID so its
|
||||
prompt and final JSON schema remain isolated.
|
||||
"""
|
||||
requested = str(payload.get("intent_agent_id") or "").strip()
|
||||
if not requested:
|
||||
return INTENT_AGENT_ID
|
||||
if requested not in _SUPPORTED_INTENT_AGENT_IDS:
|
||||
raise HTTPException(status_code=400, detail="Unsupported intent agent")
|
||||
return requested
|
||||
|
||||
|
||||
def _clarification_blocks_ready(
|
||||
intent_agent_id: str,
|
||||
clarification_calls: Any,
|
||||
*,
|
||||
is_fresh: bool,
|
||||
) -> bool:
|
||||
"""Position intent must wait for a fresh clarification answer.
|
||||
|
||||
The generic Step-1 route intentionally preserves READY-first behavior for
|
||||
stale tool calls in historical snapshots. Position roundtable instead has
|
||||
a four-part hand-off whose missing context is requested interactively, so
|
||||
a newly dispatched clarification is a strict terminal pause. A historical
|
||||
tool call from the preceding user-assistance turn must not block the next
|
||||
user answer from reaching READY.
|
||||
"""
|
||||
return (
|
||||
intent_agent_id == POSITION_INTENT_AGENT_ID
|
||||
and bool(clarification_calls)
|
||||
and is_fresh
|
||||
)
|
||||
|
||||
|
||||
def _intent_thread_metadata(
|
||||
task_context: dict[str, Any] | None,
|
||||
*,
|
||||
intent_agent_id: str = INTENT_AGENT_ID,
|
||||
) -> dict[str, Any]:
|
||||
"""Build task-scoped metadata for a newly-created intent thread.
|
||||
|
||||
Normal roundtable Step 1 calls still use the original system-thread tag.
|
||||
@@ -122,6 +169,8 @@ def _intent_thread_metadata(task_context: dict[str, Any] | None) -> dict[str, An
|
||||
"position_roundtable_phase": "intent",
|
||||
}
|
||||
)
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID:
|
||||
metadata["position_roundtable_intent_agent_id"] = intent_agent_id
|
||||
return metadata
|
||||
|
||||
|
||||
@@ -190,6 +239,32 @@ def _count_past_clarifications(messages: list[dict[str, Any]]) -> int:
|
||||
return count
|
||||
|
||||
|
||||
def _count_past_clarification_rounds(messages: list[dict[str, Any]]) -> int:
|
||||
"""Count completed assistance *rounds*, rather than question cards.
|
||||
|
||||
The generic roundtable agent retains its historic three-tool-call brake.
|
||||
Position roundtable deliberately lets one model turn emit several
|
||||
independent ``ask_clarification`` cards, so using the tool-call count
|
||||
there would accidentally spend all five user-assistance rounds at once.
|
||||
One AI message containing one or more clarification calls is one round.
|
||||
"""
|
||||
if not isinstance(messages, list):
|
||||
return 0
|
||||
rounds = 0
|
||||
for msg in messages:
|
||||
if not isinstance(msg, dict):
|
||||
continue
|
||||
if (msg.get("type") or "").lower() not in ("ai", "aimessage", "aimessagechunk"):
|
||||
continue
|
||||
if any(
|
||||
(tc.get("name") or "").lower() == "ask_clarification"
|
||||
for tc in msg.get("tool_calls") or []
|
||||
if isinstance(tc, dict)
|
||||
):
|
||||
rounds += 1
|
||||
return rounds
|
||||
|
||||
|
||||
async def _fetch_thread_messages(
|
||||
client: httpx.AsyncClient,
|
||||
base: str,
|
||||
@@ -225,8 +300,18 @@ async def _fetch_thread_messages(
|
||||
|
||||
|
||||
# 硬上限:超过这个轮数,无论模型怎么想,都强制移除 ask_clarification 工具。
|
||||
# 与 SOUL.md §0 「硬规则 2」对齐——"绝不存在第 4 轮"。
|
||||
# 通用会商沿用 3 次工具调用的历史保护;岗位会商按"一轮可多张卡"计数,
|
||||
# 允许最多 5 次用户协助。
|
||||
_MAX_CLARIFICATION_ROUNDS = 3
|
||||
_POSITION_MAX_CLARIFICATION_ROUNDS = 5
|
||||
|
||||
|
||||
def _max_clarification_rounds(intent_agent_id: str) -> int:
|
||||
return (
|
||||
_POSITION_MAX_CLARIFICATION_ROUNDS
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID
|
||||
else _MAX_CLARIFICATION_ROUNDS
|
||||
)
|
||||
|
||||
|
||||
def _is_repeated_clarification(
|
||||
@@ -310,6 +395,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
|
||||
# 调用前自检:内网部署 .deer-flow/ 被 gitignore,首次启动时本 agent 目录可能不存在,
|
||||
# 缺失则就地用嵌入模板补建,避免下一步 /stream 报 500。
|
||||
ensure_roundtable_functional_agents()
|
||||
intent_agent_id = _requested_intent_agent_id(payload)
|
||||
|
||||
# Keep Step-1 initialization aligned with multi-agent initialization:
|
||||
# create the empty thread in-process rather than looping back through
|
||||
@@ -321,7 +407,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
|
||||
try:
|
||||
thread_id = await _create_thread_direct(
|
||||
request,
|
||||
metadata=_intent_thread_metadata(task_context),
|
||||
metadata=_intent_thread_metadata(task_context, intent_agent_id=intent_agent_id),
|
||||
)
|
||||
except HTTPException:
|
||||
# 上游已用结构化方式失败,原样传给前端不需要二次包装。
|
||||
@@ -341,7 +427,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
|
||||
raise HTTPException(status_code=500, detail=diagnostic) from exc
|
||||
return {
|
||||
"status": "success",
|
||||
"agent_id": INTENT_AGENT_ID,
|
||||
"agent_id": intent_agent_id,
|
||||
"thread_id": thread_id,
|
||||
}
|
||||
|
||||
@@ -363,6 +449,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
}
|
||||
"""
|
||||
thread_id = str(payload.get("thread_id") or "").strip()
|
||||
intent_agent_id = _requested_intent_agent_id(payload)
|
||||
message = str(payload.get("message") or "").strip()
|
||||
# 不写死任何默认模型名:空串会让 lead_agent._resolve_model_name() 回退到
|
||||
# config.yaml 的 models[0],与 /api/ai-writing 等其它路由一致,内网部署只配
|
||||
@@ -386,21 +473,30 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
|
||||
base = _loopback_base(request)
|
||||
headers = _auth_headers(request)
|
||||
fallback_instruction = (
|
||||
"四个岗位会商字段都必须保留为字符串数组,依据已获得的用户确认形成明确结论,"
|
||||
"不得写待确认、未明确、需补充、暂无或缺少"
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID
|
||||
else "缺的字段用 assumptions 兜底"
|
||||
)
|
||||
|
||||
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)
|
||||
# —— 澄清轮次硬上限兜底 ——
|
||||
# 通用会商保持原来的 3 次 ask 工具调用上限;岗位会商允许一个
|
||||
# AI turn 同时产生多张独立协助卡,所以必须按 AI 消息(一次
|
||||
# "提问 + 用户回答")计轮,不能按卡片数计轮。
|
||||
past_messages = await _fetch_thread_messages(client, base, headers, thread_id)
|
||||
past_clarifications = _count_past_clarifications(past_messages)
|
||||
past_rounds = (
|
||||
_count_past_clarification_rounds(past_messages)
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID
|
||||
else past_clarifications
|
||||
)
|
||||
max_rounds = _max_clarification_rounds(intent_agent_id)
|
||||
|
||||
# 1. ask_clarification 的工具白名单——超过硬上限就移除。
|
||||
base_excluded_tools = [
|
||||
@@ -420,13 +516,13 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
"task",
|
||||
"write_todos",
|
||||
]
|
||||
if past_clarifications >= _MAX_CLARIFICATION_ROUNDS:
|
||||
if past_rounds >= max_rounds:
|
||||
base_excluded_tools.append("ask_clarification")
|
||||
logger.info(
|
||||
"intent stream: past_clarifications=%d >= %d, force-disabling "
|
||||
"intent stream: past_rounds=%d >= %d, force-disabling "
|
||||
"ask_clarification to break the loop",
|
||||
past_clarifications,
|
||||
_MAX_CLARIFICATION_ROUNDS,
|
||||
past_rounds,
|
||||
max_rounds,
|
||||
)
|
||||
|
||||
# 带了上传文件时,解锁「读」类工具(read_file / ls / grep / view_image),
|
||||
@@ -440,22 +536,42 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
# 2. message 前缀——给模型一个明确的"本轮必须收敛"信号。
|
||||
# 仅文件、无文本时给一句兜底引导,让模型先读文件再澄清意图。
|
||||
effective_message = message or "我上传了文件,请先阅读文件内容,再据此理解并澄清我的任务意图。"
|
||||
if past_clarifications >= _MAX_CLARIFICATION_ROUNDS:
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID and past_rounds < max_rounds:
|
||||
# The position flow needs an actionable four-part hand-off,
|
||||
# not merely a recognizable topic. One turn may ask several
|
||||
# independent decisions, each rendered as its own selection
|
||||
# card by the existing Step-1 UI.
|
||||
effective_message = (
|
||||
f"[系统强制] 已澄清 {past_clarifications} 轮,触发硬上限。"
|
||||
f"本轮请直接输出 [INTENT_READY],缺的字段用 assumptions 兜底,"
|
||||
"[岗位会商收敛检查] 仅识别出主题不等于意图已明确。"
|
||||
"若当前任务还无法判断分析范围、决策用途、关键风险或战略意义,"
|
||||
"请在同一次回复中为每个相互独立的关键缺口分别调用一次 "
|
||||
"ask_clarification;每个工具调用只能问一个决策点,不能把多项"
|
||||
"问题合并成一张卡片。用户会一次性回答这些卡片。"
|
||||
"如果四项意图已经足够明确,则直接输出最终结果。"
|
||||
"不要以风险提示和战略意义为空的 [INTENT_READY] 结束。"
|
||||
"本轮是第 %d/%d 轮用户协助;第 %d 轮若仍有缺口,必须把所有"
|
||||
"剩余关键缺口分别发成卡片,收到回答后立即收敛。\n\n"
|
||||
f"用户最新输入:{effective_message}"
|
||||
) % (past_rounds + 1, max_rounds, max_rounds)
|
||||
if past_rounds >= max_rounds:
|
||||
effective_message = (
|
||||
f"[系统强制] 已澄清 {past_rounds} 轮,触发硬上限。"
|
||||
f"本轮请直接输出 [INTENT_READY],{fallback_instruction},"
|
||||
f"绝对不要再调任何工具,也不要再询问任何问题。\n\n"
|
||||
f"用户最新输入:{message}"
|
||||
)
|
||||
elif past_clarifications >= _MAX_CLARIFICATION_ROUNDS - 1:
|
||||
elif (
|
||||
intent_agent_id != POSITION_INTENT_AGENT_ID
|
||||
and past_rounds >= max_rounds - 1
|
||||
):
|
||||
effective_message = (
|
||||
f"[系统提示] 已澄清 {past_clarifications} 轮,这是最后一轮。"
|
||||
f"本轮请直接输出 [INTENT_READY],未明确的字段用 assumptions 兜底。\n\n"
|
||||
f"[系统提示] 已澄清 {past_rounds} 轮,这是最后一轮。"
|
||||
f"本轮请直接输出 [INTENT_READY],{fallback_instruction}。\n\n"
|
||||
f"用户最新输入:{message}"
|
||||
)
|
||||
|
||||
body = _run_payload(
|
||||
agent_name=INTENT_AGENT_ID,
|
||||
agent_name=intent_agent_id,
|
||||
model_name=model_name,
|
||||
thread_id=thread_id,
|
||||
new_message=effective_message,
|
||||
@@ -479,6 +595,26 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
captured = done
|
||||
|
||||
messages = _parse_last_messages(captured)
|
||||
current_rounds = (
|
||||
_count_past_clarification_rounds(messages)
|
||||
if intent_agent_id == POSITION_INTENT_AGENT_ID
|
||||
else _count_past_clarifications(messages)
|
||||
)
|
||||
clarification_is_fresh = current_rounds > past_rounds
|
||||
|
||||
# A position-roundtable clarification is an explicit pause.
|
||||
# Some models emit a premature [INTENT_READY] text after the
|
||||
# tool call in the same upstream run. For this dedicated flow
|
||||
# the fresh clarification must win so the user can answer it;
|
||||
# generic roundtable keeps its historical READY-first order.
|
||||
dispatch_msg = _find_dispatch_message(messages)
|
||||
tool_calls = dispatch_msg.get("tool_calls") or []
|
||||
clarification_calls = [
|
||||
tc
|
||||
for tc in tool_calls
|
||||
if isinstance(tc, dict)
|
||||
and (tc.get("name") or "").lower() == "ask_clarification"
|
||||
]
|
||||
|
||||
# --- 终态分支 1:结构化意图已就绪(最高优先级)---
|
||||
# 模型可能在较早的 AIMessage 里已输出 [INTENT_READY],而最后一轮
|
||||
@@ -507,7 +643,15 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
# Step1Panel 已经把 `parts.after` 隐藏掉,体验闭环。
|
||||
ready_text = msg_text[: m.end()].rstrip() + "\n"
|
||||
break
|
||||
if summary and ready_text:
|
||||
if (
|
||||
summary
|
||||
and ready_text
|
||||
and not _clarification_blocks_ready(
|
||||
intent_agent_id,
|
||||
clarification_calls,
|
||||
is_fresh=clarification_is_fresh,
|
||||
)
|
||||
):
|
||||
final_frame = {
|
||||
"status": "done",
|
||||
"content": ready_text,
|
||||
@@ -519,42 +663,49 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
# --- 终态分支 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()
|
||||
if clarification_calls:
|
||||
# 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],
|
||||
clarification_payloads: list[dict[str, Any]] = []
|
||||
for clarification_call in clarification_calls:
|
||||
cargs = clarification_call.get("args") or {}
|
||||
question = str(cargs.get("question") or "").strip()
|
||||
# 逐卡过滤已被用户回答过的重复问题,不能因为其中一张
|
||||
# 重复卡而吞掉同轮其它有效的协助卡。
|
||||
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],
|
||||
)
|
||||
continue
|
||||
clarification_payloads.append(
|
||||
{
|
||||
"id": str(clarification_call.get("id") or ""),
|
||||
"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),
|
||||
}
|
||||
)
|
||||
|
||||
if not clarification_payloads:
|
||||
fallback_msg = (
|
||||
display_content
|
||||
follow_up
|
||||
or content
|
||||
or "(系统识别到智能体重复了上一问题,已自动跳过。请补充其他信息继续推进。)"
|
||||
)
|
||||
final_frame: dict[str, Any] = {
|
||||
final_frame = {
|
||||
"status": "asking",
|
||||
"content": fallback_msg,
|
||||
"summary": None,
|
||||
@@ -562,15 +713,15 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
return
|
||||
|
||||
first = clarification_payloads[0]
|
||||
display_content = follow_up or content or str(first["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),
|
||||
# 兼容旧客户端保留首张卡的顶层字段;完整列表使得网络
|
||||
# 重连、缓存重放等没有实时 tool frame 的路径也能还原多卡。
|
||||
**first,
|
||||
"clarifications": clarification_payloads,
|
||||
"summary": None,
|
||||
}
|
||||
yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
|
||||
|
||||
Reference in new issue
Block a user