Merge branch 'dhk-1' of http://192.168.0.200/knowledge-base-bj/deerflow-server into dhk-1

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py

@@ -305,8 +305,10 @@ RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
 - `reason` 必须**具体**,不要"很合适"、"很强"这类空话
 
 ## 输出风格
-- 思路部分简短:用一句话概括你为什么挑这些(例如"按情报→设计→风险→执行的研讨节奏挑选了 4 位")
-- 推荐理由要**具体到任务**,例如"负责检索同类合规改造案例,直接对应本次等保 2.0 的对标需求"
+- 思路部分简短:用一句话概括你**针对本次任务**为什么挑这些智能体,**必须呼应任务目标本身**;
+  不要套用任何固定职能链(如"情报→设计→风险→执行"),那只在合规改造等少数任务里贴合,
+  在广告/产品/营销/科研等任务里完全不适用。
+- 推荐理由要**具体到本次任务**,例如"负责设计落地页文案,直接对应本次品牌曝光目标"
 - 适度用 emoji:📋 表示开始汇总
 
 ## 边界
@@ -317,7 +319,11 @@ RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
 
 ## 示例
 
-**用户输入**(由后端拼装):
+> 以下两个示例覆盖**不同任务类型**,目的是教你「思路要呼应任务本身」,**不要**把任何一个示例的具体职能链当模板。
+
+### 示例 A:合规改造任务(职能型候选池)
+
+**用户输入**:
 ```
 任务目标:对生产系统进行安全改造,满足等保 2.0 合规要求
 约束:预算 ≤ 500 万元;工期 ≤ 6 个月;必须满足等保 2.0
@@ -334,7 +340,7 @@ RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
 ```
 
 **你的输出**:
-按"情报→设计→风险→执行"的研讨节奏,挑选 5 位最贴合本次等保 2.0 改造任务的智能体,并加入成本测算覆盖预算硬约束。📋
+本次任务核心是等保 2.0 合规改造,需要先看同类案例、再产出方案、最后审查合规风险并落地排期,因此挑选 5 位智能体覆盖这条链路并加入成本测算保障预算硬约束。📋
 
 [RECOMMEND_READY]
 ```json
@@ -348,6 +354,40 @@ RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
   ]
 }
 ```
+
+### 示例 B:广告/营销任务(用户自建领域候选池)
+
+**用户输入**:
+```
+任务目标:为某新能源汽车品牌设计一套季度品牌曝光广告投放方案
+约束:预算 ≤ 200 万元;周期 1 个月内上线
+关键假设:目标人群覆盖一二线城市;以社媒为主、信息流为辅
+
+候选智能体池:
+- ad-design (广告设计智能体):产出广告创意脚本、海报设计稿、文案 hook
+- channel-planner (渠道规划师):按预算和受众设计跨平台投放组合
+- audience-insight (受众洞察):画像、关键词、情绪点研究
+- creative-copy (创意文案):产出落地页与社媒文案变体
+- roundtable-risk-review (风险审查):合规红线检查与收敛建议
+```
+
+**你的输出**:
+本次是品牌曝光广告投放,核心要先做受众洞察、再产出创意与文案、最后规划渠道投放组合,因此挑选 4 位直接相关的智能体;合规审查在广告场景里也保留一个位置避免文案踩雷。📋
+
+[RECOMMEND_READY]
+```json
+{
+  "picks": [
+    {"agent_id": "audience-insight", "reason": "新能源汽车一二线人群画像与情绪点研究,决定后续创意切入角度"},
+    {"agent_id": "ad-design", "reason": "产出社媒主推海报与脚本,直接对应品牌曝光交付物"},
+    {"agent_id": "creative-copy", "reason": "为社媒/信息流产出多版本文案 hook,配合 A/B 测试"},
+    {"agent_id": "channel-planner", "reason": "200 万预算内规划社媒+信息流的组合与节奏"}
+  ]
+}
+```
+
+> **关键观察**:示例 A 选了 `roundtable-intelligence / solution-design / execution-plan` 等"职能型"智能体,示例 B **完全没用任何 `roundtable-*` 内置**,而是从用户自建的领域智能体里挑。
+> 这是因为:**候选池里的智能体能不能匹配任务,只看 description 和任务的实际语义,不看 id 是不是 `roundtable-` 开头**。如果候选池里有"广告设计智能体"且任务是广告设计,**你必须挑它**,而不是套用示例 A 的职能链。
 """
 
 

offline-backend-20260512/backend/app/gateway/routers/multi_agent.py

@@ -590,8 +590,18 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
                     "当你觉得已有信息支持回答用户问题时候,停止调度,并输出最后的结果\n"
                     "#调度方法：\n"
                     "通过使用agent_orchestration技能调用其他智能体干活,使用技能时传入agent_name和需要做的活。"
-                    "注意：agent_name 必须严格使用下方列出的英文 id（例如 roundtable-intelligence），"
+                    "注意：agent_name 必须严格使用下方列出的英文 id（例如 roundtable-intelligence,"
+                    "或形如 02714cbe6e64406a8a4659f0e3d9c0b8 这样的 UUID）,"
                     "不要把括号里的中文显示名拼进 agent_name 里。\n"
+                    "#关键约束(必读)：\n"
+                    "1. **不要对同一子智能体重复派同样的活**：每次派活前回顾对话历史,"
+                    "如果某个子智能体已经针对你正要派的任务完成过交付("
+                    "看到形如\"子智能体[名称]完成XX工作,交付内容为:...\"的 human 消息),"
+                    "就直接基于已有交付推进,**不要重复派活**,除非你确实有**具体的、不一样的**补充问题。\n"
+                    "2. **看到交付要会用**：子智能体的交付内容会作为 human 消息追加到你的对话历史里,"
+                    "你能完整看见。当各方信息已足够形成结论时,**直接综合输出最终方案**(此时不再调用任何工具),"
+                    "让讨论收敛。\n"
+                    "3. **避免无意义循环**：如果连续两轮都没有新信息流入,立刻停止派活并基于现有素材给出最终结论。\n"
                     "#可调度智能体：\n"
                     + "\n".join(descriptions)
                 )
@@ -940,6 +950,8 @@ async def _special_run(
     new_message: str,
     skill_stop_names: list[str],
     model_name: str,
+    *,
+    display_name: str = "",
 ) -> AsyncIterator[str | dict[str, Any]]:
     """子智能体（special）单轮：执行总控下发的 task 文本，交付 content。
 
@@ -1007,18 +1019,21 @@ async def _special_run(
     # closes; the SSE connection stays open a bit longer but the frontend has
     # already consumed the result.
     t_before_post = time.perf_counter()
+    # 优先用 display_name(中文友好,例如"情报收集")提示 leader,id 放括号备查;
+    # display_name 缺失时退化为仅 agent_name —— 与旧行为一致。
+    speaker_label = f"{display_name}({agent_name})" if display_name else agent_name
     post_broadcast_task = asyncio.create_task(
         _broadcast(
             client,
             base,
             headers,
-            f"子智能体{agent_name}完成{new_message}工作,交付内容为:" + content,
+            f"子智能体{speaker_label}完成{new_message}工作,交付内容为:" + content,
             agent_threads,
             [agent_name],
         )
     )
     yield {
-        "status": f"子智能体{agent_name}完成{new_message}工作",
+        "status": f"子智能体{speaker_label}完成{new_message}工作",
         "content": content,
         "agent_name": agent_name,
     }
@@ -1059,6 +1074,11 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
     agent_type: str = str(payload.get("agent_type") or "leader").lower()
     agent_threads: dict[str, str] = payload.get("d_agent_thread_id") or {}
     agent_name: str = str(payload.get("agent_name") or "").lower()
+    # 人类可读名,仅 special 用 —— 后端把它拼进 post-broadcast 文本,这样 leader
+    # 下一轮看到的是"子智能体[中文名](id)完成..."而非"子智能体[UUID]完成...";
+    # LLM 对 UUID 不友好,只用 id 会导致总控认不出已完成的子智能体,无限循环派活。
+    # 缺失时 fallback 到 agent_name,旧前端不传也不破坏。
+    display_name: str = str(payload.get("display_name") or "").strip()
     new_message: str = str(payload.get("new_message") or "")
     skill_stop_names: list[str] = payload.get("skill_stop_names") or []
     # 不写死任何默认模型;空串会让 lead_agent._resolve_model_name() 回退到
@@ -1089,6 +1109,7 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
                 else:
                     gen = _special_run(
                         client, base, headers, agent_threads, agent_name, new_message, skill_stop_names, model_name,
+                        display_name=display_name,
                     )
                 async for chunk in gen:
                     if isinstance(chunk, dict):

offline-backend-20260512/backend/app/gateway/routers/recommend.py

@@ -112,7 +112,7 @@ def _build_prompt(intent: dict[str, Any], candidates: list[dict[str, Any]]) -> s
 
 def _validate_picks(
     raw_picks: Any,
-    candidate_ids: set[str],
+    candidates: list[dict[str, Any]],
 ) -> list[dict[str, str]]:
     """Filter the model's picks against the candidate pool and clamp to 2-6.
 
@@ -121,18 +121,50 @@ def _validate_picks(
     model over-picked. Returns ``[]`` if validation leaves us with fewer than
     ``_MIN_PICKS`` valid picks — the caller treats that as "fall back to
     defaults".
+
+    容错策略(2026-XX 修复 "用户自建 agent 被推荐丢失" 的问题):
+      模型有时把候选池里的 ``name`` 当成 ``agent_id`` 回填(尤其当 id 是 UUID
+      形式时, LLM 倾向用人类可读名),或者顺便也回了 ``name`` 字段。本函数:
+        1. 先按 agent_id 命中候选池(严格匹配,原行为);
+        2. 否则按 ``agent_id`` 的字面值反查 name → 找回真实 id;
+        3. 否则按 ``name`` 字段反查 name → 找回真实 id。
+      只要能定位到候选池里**唯一**一个 agent,就算 pick 成功。
     """
     if not isinstance(raw_picks, list):
         return []
 
+    id_set: set[str] = set()
+    name_to_id: dict[str, str] = {}
+    for c in candidates:
+        aid = str(c.get("agent_id") or "").strip()
+        if not aid:
+            continue
+        id_set.add(aid)
+        nm = str(c.get("name") or "").strip()
+        if nm:
+            # 大小写不敏感反查 —— 模型可能用空格 / 不同大小写 echo 中文名。
+            name_to_id.setdefault(nm.lower(), aid)
+
     picked: list[dict[str, str]] = []
     seen: set[str] = set()
     for item in raw_picks:
         if not isinstance(item, dict):
             continue
-        aid = str(item.get("agent_id") or "").strip()
+        raw_id = str(item.get("agent_id") or "").strip()
+        raw_name = str(item.get("name") or "").strip()
         reason = str(item.get("reason") or "").strip()
-        if not aid or aid not in candidate_ids or aid in seen:
+
+        aid = ""
+        if raw_id and raw_id in id_set:
+            aid = raw_id
+        elif raw_id and raw_id.lower() in name_to_id:
+            # 模型把"广告设计智能体"这种 name 当成 agent_id 回填了
+            aid = name_to_id[raw_id.lower()]
+        elif raw_name and raw_name.lower() in name_to_id:
+            # 模型 agent_id 字段乱了,但 name 字段对得上
+            aid = name_to_id[raw_name.lower()]
+
+        if not aid or aid in seen:
             continue
         picked.append({"agent_id": aid, "reason": reason})
         seen.add(aid)
@@ -245,14 +277,30 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
                 # 只扫描「最后一条非空 AIMessage」：推荐 agent 单轮输出，无多轮 READY 问题。
                 picks: list[dict[str, str]] = []
                 match = _RECOMMEND_READY_PATTERN.search(last_ai_content)
+                # 诊断:打印模型输出末尾(含 RECOMMEND_READY 块)。grep "recommend stream debug"
+                # 即可看到 LLM 实际推荐了什么、_validate_picks 解析前/后的差异。
+                logger.info(
+                    "recommend stream debug | last_ai_tail=%r | match=%s | candidate_count=%d",
+                    last_ai_content[-600:] if last_ai_content else "",
+                    bool(match),
+                    len(candidates),
+                )
                 if match:
                     try:
                         parsed = json.loads(match.group(1))
                     except json.JSONDecodeError as exc:
-                        logger.warning("recommend picks JSON parse failed: %s", exc)
+                        logger.warning("recommend picks JSON parse failed: %s | raw=%r", exc, match.group(1)[:300])
                         parsed = {}
                     if isinstance(parsed, dict):
-                        picks = _validate_picks(parsed.get("picks"), candidate_ids)
+                        raw_picks = parsed.get("picks")
+                        # 传完整 candidates 列表(含 name) —— _validate_picks 容错按 name 反查 id,
+                        # 修复 LLM 把"广告设计智能体"这种 name 当 agent_id 回填导致全丢的问题。
+                        picks = _validate_picks(raw_picks, candidates)
+                        logger.info(
+                            "recommend stream debug | raw_picks=%r | validated_picks=%r",
+                            raw_picks,
+                            picks,
+                        )
 
                 # asking ≠ 模型在追问用户，而是「网关未能产出合法 picks」，由前端 fallback。
                 status_value = "done" if picks else "asking"