feat: refine mcp prompt (#1426)

earayu · web-flow · commit f8aef0e6667a · 2026-01-21T02:32:22.000+08:00
* feat: refine mcp prompt

* feat: refine mcp prompt
diff --git a/aperag/mcp/server.py b/aperag/mcp/server.py
@@ -78,7 +78,12 @@ async def search_collection(
     topk: int = 5,
     query_keywords: list[str] = None,
 ) -> Dict[str, Any]:
-    """Search for knowledge in a specific collection using vector, full-text, graph, and/or summary search.
+    """Search for knowledge in a persistent collection/knowledge base using vector, full-text, graph, and/or summary search.
+
+    PRIMARY USE CASE: This is the main tool for searching permanent knowledge repositories.
+    Use this for general Q&A, knowledge retrieval, and accessing organized knowledge collections.
+
+    For temporary files uploaded in a chat session, use search_chat_files instead.
 
     Args:
         collection_id: The ID of the collection to search in
@@ -215,7 +220,18 @@ async def search_chat_files(
     rerank: bool = True,
     topk: int = 5,
 ) -> Dict[str, Any]:
-    """Search for knowledge in chat files using vector, full-text, graph, and/or summary search.
+    """Search ONLY within files temporarily uploaded by the user in THIS specific chat session.
+
+    IMPORTANT - When to Use This Tool:
+    - ONLY when searching files that the user explicitly uploaded in THIS chat conversation
+    - For temporary, session-specific document analysis (e.g., "analyze this PDF I just uploaded")
+    - When the user references documents they shared in the current chat
+
+    DO NOT Use This Tool For:
+    - Searching general knowledge bases or collections (use search_collection instead)
+    - Accessing persistent/permanent knowledge repositories
+    - General Q&A that doesn't involve chat-uploaded files
+    - When no files have been uploaded in the current chat
 
     Args:
         chat_id: The ID of the chat to search files in
@@ -230,10 +246,9 @@ async def search_chat_files(
 
     Note:
         Uses SearchResult view model for type-safe response parsing and validation.
-        This tool searches within files uploaded to the specified chat.
 
-        The search behavior is similar to search_collection, but limited to documents
-        uploaded in the specified chat context.
+        SCOPE: This tool ONLY searches temporary files uploaded in the current chat.
+        It does NOT search permanent knowledge collections.
 
         Return format follows the same structure as search_collection:
         - rank: Result rank
diff --git a/aperag/service/prompt_template_service.py b/aperag/service/prompt_template_service.py
@@ -50,8 +50,8 @@
 
 ### Knowledge Management
 - `list_collections()`: Discover available knowledge sources
-- `search_collection(collection_id, query, ...)`: Hybrid search within collections
-- `search_chat_files(chat_id, query, ...)`: Search files uploaded in specific chat sessions
+- `search_collection(collection_id, query, ...)`: **[PRIMARY TOOL]** Hybrid search within persistent knowledge collections/repositories
+- `search_chat_files(chat_id, query, ...)`: **[CHAT-ONLY]** Search ONLY temporary files uploaded by user in THIS chat session (NOT for general knowledge bases)
 - `create_diagram(content)`: Create Mermaid diagrams for knowledge graph visualization
 
 ### Web Intelligence
@@ -151,8 +151,8 @@
 
 ### 知识管理
 - `list_collections()`：发现可用知识源
-- `search_collection(collection_id, query, ...)`：知识库内混合搜索
-- `search_chat_files(chat_id, query, ...)`：搜索特定聊天会话中上传的文件
+- `search_collection(collection_id, query, ...)`: **[主要工具]** 在持久化知识库/仓库中进行混合搜索
+- `search_chat_files(chat_id, query, ...)`: **[仅限聊天]** 仅搜索用户在本次聊天会话中临时上传的文件（不用于常规知识库）
 - `create_diagram(content)`：创建Mermaid图表进行知识图谱可视化
 
 ### 网络智能
@@ -235,7 +235,7 @@
 {% set web_status = "enabled" if web_search_enabled else "disabled" %}
 {% set web_instruction = "Use web search strategically for current information, verification, or gap-filling" if web_search_enabled else "Rely entirely on knowledge collections; inform user if web search would be helpful" %}
 {% set chat_context = "Chat ID: " + chat_id if chat_id else "No chat files" %}
-{% set chat_instruction = "Use search_chat_files tool to search files uploaded in this chat" if chat_id else "" %}
+{% set chat_instruction = "ONLY use search_chat_files tool when searching files that user explicitly uploaded in THIS chat. Do NOT use it for general knowledge base queries." if chat_id else "" %}
 
 **User Query**: {{ query }}
 
@@ -272,7 +272,7 @@
 {% set web_status = "已启用" if web_search_enabled else "已禁用" %}
 {% set web_instruction = "战略性地使用网络搜索获取当前信息、验证或填补空白" if web_search_enabled else "完全依赖知识库；如果网络搜索有帮助请告知用户" %}
 {% set chat_context = "聊天ID: " + chat_id if chat_id else "无" %}
-{% set chat_instruction = "可使用 search_chat_files 工具搜索此聊天中上传的文件" if chat_id else "" %}
+{% set chat_instruction = "仅在搜索用户明确在本次聊天中上传的文件时使用 search_chat_files 工具。不要将其用于常规知识库查询。" if chat_id else "" %}
 
 **用户查询**: {{ query }}
 
diff --git a/web/src/lib/prompt-template/query-prompt.en-US.md b/web/src/lib/prompt-template/query-prompt.en-US.md
@@ -1,4 +1,4 @@
-{% set collection_list = [] %} {% if collections %} {% for c in collections %} {% set title = c.title or "Collection " + c.id %} {% set _ = collection_list.append("- " + title + " (ID: " + c.id + ")") %} {% endfor %} {% set collection_context = collection_list | join("\n") %} {% set collection_instruction = "PRIORITY: Search these user-specified collections first" %} {% else %} {% set collection_context = "None specified by user" %} {% set collection_instruction = "discover and select relevant collections automatically" %} {% endif %} {% set web_status = "enabled" if web_search_enabled else "disabled" %} {% set web_instruction = "Use web search strategically for current information, verification, or gap-filling" if web_search_enabled else "Rely entirely on knowledge collections; inform user if web search would be helpful" %} {% set chat_context = "Chat ID: " + chat_id if chat_id else "No chat files" %} {% set chat_instruction = "Use search_chat_files tool to search files uploaded in this chat" if chat_id else "" %}
+{% set collection_list = [] %} {% if collections %} {% for c in collections %} {% set title = c.title or "Collection " + c.id %} {% set _ = collection_list.append("- " + title + " (ID: " + c.id + ")") %} {% endfor %} {% set collection_context = collection_list | join("\n") %} {% set collection_instruction = "PRIORITY: Search these user-specified collections first" %} {% else %} {% set collection_context = "None specified by user" %} {% set collection_instruction = "discover and select relevant collections automatically" %} {% endif %} {% set web_status = "enabled" if web_search_enabled else "disabled" %} {% set web_instruction = "Use web search strategically for current information, verification, or gap-filling" if web_search_enabled else "Rely entirely on knowledge collections; inform user if web search would be helpful" %} {% set chat_context = "Chat ID: " + chat_id if chat_id else "No chat files" %} {% set chat_instruction = "ONLY use search_chat_files tool when searching files that user explicitly uploaded in THIS chat. Do NOT use it for general knowledge base queries." if chat_id else "" %}
 
 **User Query**: {{ query }}
 
@@ -12,7 +12,7 @@
 
 1. LANGUAGE PRIORITY: Respond in the language the user is asking in, not the language of the content
 2. If user specified collections (@mentions), search those first (REQUIRED)
-3. If chat files are available, search files uploaded in this chat when relevant
+3. If chat files are available, ONLY use search_chat_files when the user asks about files they uploaded in THIS chat. Use search_collection for general knowledge queries.
 4. Use appropriate search keywords in multiple languages when beneficial
 5. Assess result quality and decide if additional collections are needed
 6. Use web search strategically if enabled and relevant
diff --git a/web/src/lib/prompt-template/query-prompt.zh-CN.md b/web/src/lib/prompt-template/query-prompt.zh-CN.md
@@ -1,4 +1,4 @@
-{% set collection_list = [] %} {% if collections %} {% for c in collections %} {% set title = c.title or "知识库" + c.id %} {% set _ = collection_list.append("- " + title + " (ID: " + c.id + ")") %} {% endfor %} {% set collection_context = collection_list | join("\n") %} {% set collection_instruction = "优先级：首先搜索这些用户指定的知识库" %} {% else %} {% set collection_context = "用户未指定" %} {% set collection_instruction = "自动发现并选择相关的知识库" %} {% endif %} {% set web_status = "已启用" if web_search_enabled else "已禁用" %} {% set web_instruction = "战略性地使用网络搜索获取当前信息、验证或填补空白" if web_search_enabled else "完全依赖知识库；如果网络搜索有帮助请告知用户" %} {% set chat_context = "聊天ID: " + chat_id if chat_id else "无" %} {% set chat_instruction = "可使用 search_chat_files 工具搜索此聊天中上传的文件" if chat_id else "" %}
+{% set collection_list = [] %} {% if collections %} {% for c in collections %} {% set title = c.title or "知识库" + c.id %} {% set _ = collection_list.append("- " + title + " (ID: " + c.id + ")") %} {% endfor %} {% set collection_context = collection_list | join("\n") %} {% set collection_instruction = "优先级：首先搜索这些用户指定的知识库" %} {% else %} {% set collection_context = "用户未指定" %} {% set collection_instruction = "自动发现并选择相关的知识库" %} {% endif %} {% set web_status = "已启用" if web_search_enabled else "已禁用" %} {% set web_instruction = "战略性地使用网络搜索获取当前信息、验证或填补空白" if web_search_enabled else "完全依赖知识库；如果网络搜索有帮助请告知用户" %} {% set chat_context = "聊天ID: " + chat_id if chat_id else "无" %} {% set chat_instruction = "仅在搜索用户明确在本次聊天中上传的文件时使用 search_chat_files 工具。不要将其用于常规知识库查询。" if chat_id else "" %}
 
 **用户查询**: {{ query }}
 
@@ -12,7 +12,7 @@
 
 1. 语言优先级: 使用用户提问的语言回应，而不是内容的语言
 2. 如果用户指定了知识库（@提及），首先搜索这些（必需）
-3. 如果有聊天文件，可以搜索聊天中上传的文件
+3. 如果有聊天文件，仅在用户询问他们在本次聊天中上传的文件时使用 search_chat_files。对于常规知识查询使用 search_collection。
 4. 在有益时使用多种语言的适当搜索关键词
 5. 评估结果质量并决定是否需要额外的知识库
 6. 如果启用且相关，战略性地使用网络搜索
diff --git a/web/src/lib/prompt-template/system-prompt.en-US.md b/web/src/lib/prompt-template/system-prompt.en-US.md
@@ -31,8 +31,8 @@ You are an advanced AI research assistant powered by ApeRAG's hybrid search capa
 ### Knowledge Management
 
 - `list_collections()`: Discover available knowledge sources
-- `search_collection(collection_id, query, ...)`: Hybrid search within collections
-- `search_chat_files(chat_id, query, ...)`: Search files uploaded in specific chat sessions
+- `search_collection(collection_id, query, ...)`: **[PRIMARY TOOL]** Hybrid search within persistent knowledge collections/repositories
+- `search_chat_files(chat_id, query, ...)`: **[CHAT-ONLY]** Search ONLY temporary files uploaded by user in THIS chat session (NOT for general knowledge bases)
 - `create_diagram(content)`: Create Mermaid diagrams for knowledge graph visualization
 
 ### Web Intelligence
diff --git a/web/src/lib/prompt-template/system-prompt.zh-CN.md b/web/src/lib/prompt-template/system-prompt.zh-CN.md
@@ -31,8 +31,8 @@
 ### 知识管理
 
 - `list_collections()`：发现可用知识源
-- `search_collection(collection_id, query, ...)`：知识库内混合搜索
-- `search_chat_files(chat_id, query, ...)`：搜索特定聊天会话中上传的文件
+- `search_collection(collection_id, query, ...)`: **[主要工具]** 在持久化知识库/仓库中进行混合搜索
+- `search_chat_files(chat_id, query, ...)`: **[仅限聊天]** 仅搜索用户在本次聊天会话中临时上传的文件（不用于常规知识库）
 - `create_diagram(content)`：创建Mermaid图表进行知识图谱可视化
 
 ### 网络智能
