参考文献模式合并为单一 referenceBatch 并统一连续编号

将同一轮检索结果合并为一个 referenceBatch，由系统统一从 [1] 连续编号，避免每个检索词各自重新编号；提示词引导优先并行检索后再作答。智能体列表接口并发加载技能等轻量信息以渲染卡片徽章，并新增参考文献相关测试。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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

@@ -435,14 +435,19 @@ async def list_agents(
             agents = await store.list_all()
         else:
             agents = await store.list_visible(user_id)
-        # List endpoint stays lean: skip per-agent SOUL.md read, config.yaml
-        # parse, and dir self-heal — none of those feed UI fields the gallery /
-        # recommend dialog / selector actually render. Detail endpoints (single
-        # agent + create/update responses) still load them.
-        responses = [
-            _record_to_response(a, include_soul=False, include_extras=False)
-            for a in agents
-        ]
+        # Load lightweight extras (skills / model / tool_groups from config.yaml)
+        # so the gallery cards can render skill badges. SOUL.md is still skipped
+        # (only the edit dialog reads it). The per-agent config.yaml reads run in
+        # worker threads concurrently, so the event loop stays responsive even
+        # with many agents.
+        responses = list(
+            await asyncio.gather(
+                *(
+                    _record_to_response_async(a, include_soul=False, include_extras=True)
+                    for a in agents
+                )
+            )
+        )
 
         assignments = await tag_store.list_assignments("agent", [r.id for r in responses])
         favorite_ids = await store.list_favorite_ids(user_id)

offline-backend-20260512/backend/app/gateway/services.py

@@ -104,7 +104,8 @@ _BUILTIN_GRAPH_IDS: frozenset[str] = frozenset({"lead_agent", "canvas_agent", "a
 
 _RAG_CITATION_PROMPT = """当前对话已开启参考文献模式。
 如果本轮调用了搜索、知识库、检索类技能或工具，请基于本轮所有检索结果整体回答。
-你必须把同一轮内多次检索得到的资料视为同一批参考文献，按出现顺序从 [1] 开始连续编号，不要让每个检索词各自从 [1] 重新编号。
+如果你已经知道需要多个检索词，请优先在同一步里并行调用检索工具，等这些检索都返回后再回答，不要查一个检索词就先写一版答案。
+你必须把同一轮内多次检索得到的资料视为同一个 referenceBatch，按系统稍后提供的合并批次从 [1] 开始连续编号，不要让每个检索词各自从 [1] 重新编号。
 回答正文中的关键结论必须标注对应编号，例如 [1]、[2]，多个来源可写为 [1][3][5]。
 不要引用不存在的编号，不要使用技能内部自带的编号，不要把参考文献完整列表堆在正文末尾。
 如果没有任何可用检索结果，请直接说明未检索到可靠参考资料。"""

offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py

@@ -703,12 +703,14 @@ def _get_cached_skills_prompt_section(
 
     display_pattern = (
         """
-**Skill Result Display Pattern:**
-- If a skill has `<display mode="citation">`, use the skill's returned result order as reference numbers. Cite facts from the first result as `[[1]]`, the second as `[[2]]`, and so on. Use only numbers that correspond to returned results.
-- If a skill has `<display mode="list">`, summarize the returned items as a concise list and keep item order stable.
-- If a skill has `<display mode="table">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="table" />` where the frontend should render the real table. Do not hand-write the table rows yourself.
-- If a skill has `<display mode="card">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="card" />` where the frontend should render the cards.
-- If a skill has `<display mode="custom">`, follow the custom display instruction in the `<display>` tag when presenting the skill result.
+**Skill Result Display Pattern:**
+- If RAG/reference display mode is enabled, do not number each skill result independently. Treat all retrieval results from the same user turn as one combined `referenceBatch` and cite with `[1]`, `[2]`, etc. from the system-provided reference prompt.
+- In RAG/reference display mode, do not output `<skill-display .../>`; the frontend renders cards, tables, lists, and citation details in the right reference panel.
+- If RAG/reference display mode is not enabled and a skill has `<display mode="citation">`, use the skill's returned result order as reference numbers. Cite facts from the first result as `[1]`, the second as `[2]`, and so on. Use only numbers that correspond to returned results.
+- If a skill has `<display mode="list">`, summarize the returned items as a concise list and keep item order stable.
+- If a skill has `<display mode="table">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="table" />` where the frontend should render the real table. Do not hand-write the table rows yourself.
+- If a skill has `<display mode="card">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="card" />` where the frontend should render the cards.
+- If a skill has `<display mode="custom">`, follow the custom display instruction in the `<display>` tag when presenting the skill result.
 """
         if display_signature
         else ""
@@ -993,16 +995,16 @@ Writing mode is enabled for this run.
     network_policy_section = _build_network_policy_section()
     rag_mode_section = (
         """
-<rag_citation_mode>
-RAG/reference display mode is enabled.
-When a search, knowledge, skill, or MCP tool returns a result list:
-- If the skill has a display adapter, follow that adapter first.
-- For `citation`, cite returned items with `[[1]]`, `[[2]]`, etc. Only cite real returned items.
-- For `table`, do not hand-write the table. Summarize and place `<skill-display tool="SKILL_OR_TOOL_NAME" mode="table" />` where the table should appear. The frontend will render the real tool result as a stable table.
-- For `list` or `card`, summarize and place `<skill-display tool="SKILL_OR_TOOL_NAME" mode="list" />` or `<skill-display tool="SKILL_OR_TOOL_NAME" mode="card" />` where the structured result should appear.
-- If no display adapter exists, default to citation mode with numbered citations.
-</rag_citation_mode>
-"""
+<rag_citation_mode>
+RAG/reference display mode is enabled.
+When a search, knowledge, skill, or MCP tool returns a result list:
+- If multiple search terms are needed, prefer calling the retrieval tools for all known terms in the same step, then answer after the tool results are returned.
+- Treat every retrieval result from the same user turn as one combined `referenceBatch`; do not restart numbering for each search term, tool call, skill, or display adapter.
+- Use only the system-provided merged reference numbers in the final answer, formatted as `[1]`, `[2]`, `[1][3][5]`.
+- Do not output `<skill-display .../>` in RAG/reference mode. The frontend renders configured cards, tables, lists, and citation details in the right reference panel.
+- If no display adapter exists, the frontend defaults the right reference panel to numbered citations.
+</rag_citation_mode>
+"""
         if rag_mode_enabled
         else ""
     )

offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/rag_citation_middleware.py

@@ -80,13 +80,15 @@ class RagCitationMiddleware(AgentMiddleware[AgentState]):
             return None
         summary = build_reference_debug_summary(messages, [batch] if batch else None)
         _log_rag_debug(
-            "middleware reference-prompt enabled=true prompt=true messages=%s tool_messages=%s "
-            "raw_items=%s normalized_items=%s kept_items=%s latest_batch_sources=%s",
+            "middleware reference-prompt enabled=true prompt=true single_batch=true messages=%s "
+            "tool_messages=%s raw_items=%s normalized_items=%s kept_items=%s latest_batch_id=%s "
+            "latest_batch_sources=%s",
             summary["messages"],
             summary["tool_messages"],
             summary["raw_items"],
             summary["normalized_items"],
             summary["kept_items"],
+            (batch or {}).get("id"),
             len((batch or {}).get("sources") or []),
         )
         _log_rag_debug(

offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py

@@ -37,24 +37,45 @@ def build_reference_batches(messages: list[Any]) -> list[dict[str, Any]]:
     return batches
 
 
-def build_latest_reference_prompt(messages: list[Any]) -> tuple[str, dict[str, Any] | None]:
+def build_latest_reference_batch(messages: list[Any]) -> dict[str, Any] | None:
+    """Return the single combined citation batch for the latest human turn."""
     human_index = _find_latest_human_index(messages)
     if human_index is None:
-        return "", None
+        return None
     sources = _collect_sources(messages[human_index + 1 :])
     if not sources:
-        return "", None
+        return None
     assistant = _find_reference_batch_anchor(messages, human_index + 1, len(messages))
     message_id = _message_id(assistant) or _message_id(messages[human_index]) or str(human_index)
-    batch = {
+    return {
         "id": message_id,
         "assistant_message_id": message_id,
+        "source_count": len(sources),
         "sources": sources,
     }
+
+
+def build_latest_reference_prompt(messages: list[Any]) -> tuple[str, dict[str, Any] | None]:
+    batch = build_latest_reference_batch(messages)
+    if batch is None:
+        return "", None
+    return build_reference_prompt_for_batch(batch), batch
+
+
+def build_reference_prompt_for_batch(batch: dict[str, Any]) -> str:
+    """Build the authoritative model prompt from one already-combined batch."""
+    sources = [
+        source
+        for source in batch.get("sources", [])
+        if isinstance(source, dict)
+    ]
+    source_count = len(sources)
     lines = [
-        "本轮检索结果已由系统统一合并并重新编号。最终回答必须使用下面这套编号。",
-        "如果你仍需要补充检索，请先继续调用工具；最终回答只能引用最新合并后的编号。",
+        f"本轮所有检索结果已合并为同一个 referenceBatch，共 {source_count} 条，编号从 [1] 到 [{source_count}] 唯一连续。",
+        "下面这一批就是当前回答唯一可用的参考文献批次；不要按检索词、工具调用次数或工具原始编号重新分批编号。",
+        "如果你仍需要补充检索，请只继续调用工具，不要输出正文；最终回答只能引用补充检索后系统重新合并出的最新 referenceBatch。",
         "",
+        f"<reference_batch source_count=\"{source_count}\">",
     ]
     for source in sources:
         title = source.get("title") or f"参考文献 {source.get('index')}"
@@ -73,18 +94,20 @@ def build_latest_reference_prompt(messages: list[Any]) -> tuple[str, dict[str, A
         if content:
             lines.append(content)
         lines.append("")
+    lines.append("</reference_batch>")
+    lines.append("")
     lines.extend(
         [
             "引用规则：",
             "1. 回答正文中的关键结论必须标注对应编号，例如 [1]、[2]。",
             "2. 多个来源可写为 [1][3][5]。",
             "3. 只能引用上方存在的编号，不要编造编号。",
-            "4. 不要使用工具原始编号，也不要重新排序编号。",
+            "4. 不要使用工具原始编号，也不要重新排序、重新分批或重新从 [1] 开始编号。",
             "5. 不要在正文末尾堆完整参考文献列表，前端会展示右侧参考文献。",
             "6. 参考文献模式下不要输出 <skill-display .../> 占位符，也不要在正文里额外渲染卡片、表格或列表；前端会在右侧参考文献区域展示。",
         ]
     )
-    return "\n".join(lines).strip(), batch
+    return "\n".join(lines).strip()
 
 
 def _find_latest_human_index(messages: list[Any]) -> int | None:

offline-backend-20260512/backend/packages/harness/tests/test_rag_references.py

@@ -0,0 +1,96 @@
+"""Tests for RAG citation batch construction."""
+
+from __future__ import annotations
+
+import json
+
+from deerflow.runtime.references import (
+    build_latest_reference_batch,
+    build_latest_reference_prompt,
+    build_reference_batches,
+)
+
+
+def _tool_message(call_id: str, query: str, start: int) -> dict:
+    return {
+        "type": "tool",
+        "name": "web_search",
+        "tool_call_id": call_id,
+        "content": json.dumps(
+            {
+                "query": query,
+                "results": [
+                    {
+                        "title": f"{query} result {start}",
+                        "content": f"{query} content {start}",
+                        "url": f"https://example.test/{start}",
+                    },
+                    {
+                        "title": f"{query} result {start + 1}",
+                        "content": f"{query} content {start + 1}",
+                        "url": f"https://example.test/{start + 1}",
+                    },
+                ],
+            },
+            ensure_ascii=False,
+        ),
+    }
+
+
+def test_latest_reference_prompt_uses_one_combined_batch_for_multi_search_turn() -> None:
+    messages = [
+        {"type": "human", "id": "human-1", "content": "search two terms"},
+        {
+            "type": "ai",
+            "id": "ai-search-1",
+            "content": "",
+            "tool_calls": [{"id": "call-1", "name": "web_search", "args": {"query": "Trump"}}],
+        },
+        _tool_message("call-1", "Trump", 1),
+        {
+            "type": "ai",
+            "id": "ai-search-2",
+            "content": "",
+            "tool_calls": [{"id": "call-2", "name": "web_search", "args": {"query": "White House"}}],
+        },
+        _tool_message("call-2", "White House", 3),
+    ]
+
+    batch = build_latest_reference_batch(messages)
+    assert batch is not None
+    assert batch["source_count"] == 4
+    assert [source["index"] for source in batch["sources"]] == [1, 2, 3, 4]
+    assert [source["title"] for source in batch["sources"]] == [
+        "Trump result 1",
+        "Trump result 2",
+        "White House result 3",
+        "White House result 4",
+    ]
+
+    prompt, prompt_batch = build_latest_reference_prompt(messages)
+    assert prompt_batch == batch
+    assert '<reference_batch source_count="4">' in prompt
+    assert "[1] Trump result 1" in prompt
+    assert "[4] White House result 4" in prompt
+    assert "重新分批" in prompt
+
+
+def test_reference_batches_keep_separate_user_turns_but_merge_searches_inside_turn() -> None:
+    messages = [
+        {"type": "human", "id": "human-1", "content": "first"},
+        {"type": "ai", "id": "ai-1", "content": "", "tool_calls": [{"id": "c1", "name": "web_search"}]},
+        _tool_message("c1", "first", 1),
+        {"type": "ai", "id": "answer-1", "content": "answer [1]"},
+        {"type": "human", "id": "human-2", "content": "second"},
+        {"type": "ai", "id": "ai-2", "content": "", "tool_calls": [{"id": "c2", "name": "web_search"}]},
+        _tool_message("c2", "second-a", 3),
+        {"type": "ai", "id": "ai-3", "content": "", "tool_calls": [{"id": "c3", "name": "web_search"}]},
+        _tool_message("c3", "second-b", 5),
+        {"type": "ai", "id": "answer-2", "content": "answer [1][4]"},
+    ]
+
+    batches = build_reference_batches(messages)
+    assert [len(batch["sources"]) for batch in batches] == [2, 4]
+    assert [source["index"] for source in batches[1]["sources"]] == [1, 2, 3, 4]
+    assert batches[0]["assistant_message_id"] == "answer-1"
+    assert batches[1]["assistant_message_id"] == "answer-2"