文档修改

This commit is contained in:
董宏凯 committed 2026-05-25 18:19:16 +08:00
1 parent dffb8a955b
commit 8c55d4b55d
20 files changed
+1315 -5421

No files matched your search

@@ -1,20 +1,39 @@
"""Agent recommendation endpoint (between Step 1 and Step 2 of the roundtable flow).
"""圆桌规划 · Step 1→2 之间「智能体推荐」Gateway 路由。
Given the Step-1 intent summary (``objective`` + ``constraints`` + ``assumptions``)
and a frontend-filtered candidate agent pool, drives the built-in
``roundtable-recommender`` agent to pick 2-6 agents most relevant to the task
and explain why.
前端页面:推荐弹窗 ``RecommendAgentsDialog``
前端模块:``frontend-web/src/roundtable-planning/api/recommend.ts``
Single one-shot endpoint — no ``/init`` is exposed because the recommendation
is stateless: the agent never needs the prior turn's history. We create a
fresh thread internally per request and let the LangGraph runtime clean it up
in the background. The frontend handles filtering ``roundtable-intent`` /
``roundtable-recommender`` / ``roundtable-coordinator-*`` out of the candidate
pool before calling here.
职责
----
根据 Step 1 的 ``IntentSummary`` 与前端过滤后的候选池,驱动内置
``roundtable-recommender``(SOUL 见 ``.deer-flow/agents/roundtable-recommender/``),
输出 2–6 个 ``{agent_id, reason}`` 推荐席位。
SSE shape is the same family as ``intent.py`` / ``multi_agent.py``:
transparent passthrough of the upstream LangGraph stream, then a single
status frame appended at the end so the frontend can finalize.
设计为**无状态单次调用**:
- **不暴露** ``/init``:每次请求内部 ``_create_thread``,推荐 agent 不需要历史轮次。
- 候选池过滤由前端完成(剔除 ``roundtable-intent``、``roundtable-recommender``、
``roundtable-coordinator-*``),本路由只做校验与 clamp。
SSE 协议
--------
1. 透传上游 LangGraph 流(前端用 ``parseRecommendStreamContent`` 把正文拆成
``[RECOMMEND_READY]`` 前的 ``rationale`` 与 JSON 里的 ``picks``,实现卡片增量渲染)。
2. 末尾状态帧::
{ "status": "done"|"asking"|"error", "content": "<全文>", "picks": [...]|null }
- ``done``:``picks`` 经 ``_validate_picks`` 后 ≥2 条且 id 均在候选池内;
- ``asking``:未匹配 ``[RECOMMEND_READY]`` 或校验后不足 2 条(前端走 FALLBACK 默认 6 席);
- ``error``:HTTP/未捕获异常。
与 SOUL 的契约
--------------
模型须在自然语言思路后输出::
[RECOMMEND_READY]
```json
{"picks": [{"agent_id": "...", "reason": "..."}, ...]}
```
"""
from __future__ import annotations
@@ -43,15 +62,14 @@ router = APIRouter(prefix="/api/recommend", tags=["recommend"])
RECOMMENDER_AGENT_ID = "roundtable-recommender"
# Matches the SOUL-mandated handoff signal: a [RECOMMEND_READY] line followed
# by a ```json ... ``` block carrying {"picks": [{agent_id, reason}, ...]}.
# 从模型最终 AIMessage 全文提取 picks;非贪婪 ``.*?`` 只匹配第一个 json 块。
_RECOMMEND_READY_PATTERN = re.compile(
r"\[RECOMMEND_READY\]\s*```json\s*(\{.*?\})\s*```",
re.DOTALL,
)
# Mirrors the SOUL constraint so a misbehaving model can't push >6 picks to
# the frontend or fall below the "this isn't a roundtable" floor.
# 与 SOUL / 前端 ``RecommendAgentsDialog`` 一致:少于 2 无法成桌,多于 6 由网关截断。
# 前端确认按钮另限制 2≤N≤8(用户可手动多选),后端此处只负责模型输出校验。
_MIN_PICKS = 2
_MAX_PICKS = 6
@@ -178,8 +196,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
# proxy and wait ~40 seconds for timeout before falling back.
async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
try:
# One-shot recommendation: spin up a fresh thread per request.
# The recommender never needs to see prior turns.
# 每次推荐独立 thread;prompt 已包含完整 intent + 候选列表,无需多轮。
thread_id = await _create_thread(client, base, headers)
body = _run_payload(
@@ -187,7 +204,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
model_name=model_name,
thread_id=thread_id,
new_message=prompt,
# Recommender is pure judgment: no tools, no dispatching.
# 推荐只做判断:禁止澄清、派活、文件等,避免跑题或二次追问。
excluded_tools=[
"web_search",
"present_files",
@@ -217,6 +234,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
last_ai_content = text
break
# 只扫描「最后一条非空 AIMessage」:推荐 agent 单轮输出,无多轮 READY 问题。
picks: list[dict[str, str]] = []
match = _RECOMMEND_READY_PATTERN.search(last_ai_content)
if match:
@@ -228,6 +246,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
if isinstance(parsed, dict):
picks = _validate_picks(parsed.get("picks"), candidate_ids)
# asking ≠ 模型在追问用户,而是「网关未能产出合法 picks」,由前端 fallback。
status_value = "done" if picks else "asking"
final_frame: dict[str, Any] = {
"status": status_value,