From 363767d3e7b22b3a345215d87bd62a5429244003 Mon Sep 17 00:00:00 2001
From: zhuyongxin <zhuyongxin@aspirecn.com>
Date: Wed, 24 Jun 2026 18:38:39 +0800
Subject: [PATCH] =?UTF-8?q?refactor(ai-ops):=20=E6=A0=87=E8=AE=B0=20queryI?=
 =?UTF-8?q?nternalDocs=20=E4=B8=BA=E5=BC=83=E7=94=A8=EF=BC=8C=E7=BB=9F?=
 =?UTF-8?q?=E4=B8=80=E4=BD=BF=E7=94=A8=20lookup=5Fknowledge?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 改动说明

1. 标记 InternalDocsTools 为 @Deprecated
   - 添加弃用注解和说明文档
   - 工具描述中明确提示使用 lookup_knowledge 替代

2. 简化 Executor Prompt
   - 移除 queryInternalDocs 相关的工具选择逻辑
   - 统一使用 lookup_knowledge 处理所有知识库查询
   - 精确关键词、模糊概念、故障流程都使用同一个工具

## 理由

lookup_knowledge 已经支持：
- L0 精确匹配（< 10ms，高置信度）
- L1 语义检索（自动兜底）

功能完全覆盖 queryInternalDocs（纯 L1 检索），且性能更优。
保留 queryInternalDocs 会导致：
- 工具功能重叠，Agent 决策困难
- 维护两套相似的代码逻辑

## 迁移路径

- 当前：标记为弃用，但保持可用
- 验证：观察 lookup_knowledge 是否能完全替代
- 未来：确认无问题后，在下个版本中移除
---
 .../agent/agent/tool/InternalDocsTools.java        | 14 ++++++++++----
 src/main/resources/prompts/executor-prompt.md      |  3 +--
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/src/main/java/com/superbiz/agent/agent/tool/InternalDocsTools.java b/src/main/java/com/superbiz/agent/agent/tool/InternalDocsTools.java
index db82685..8212c31 100644
--- a/src/main/java/com/superbiz/agent/agent/tool/InternalDocsTools.java
+++ b/src/main/java/com/superbiz/agent/agent/tool/InternalDocsTools.java
@@ -15,7 +15,12 @@ import java.util.List;
 /**
  * 内部文档查询工具
  * 使用 RAG (Retrieval-Augmented Generation) 从内部知识库检索相关文档
+ *
+ * @deprecated 请使用 {@link com.superbiz.agent.tool.LookupKnowledgeTool} 替代。
+ *             lookup_knowledge 支持 L0 精确匹配 + L1 语义检索，性能更优且功能更全面。
+ *             计划在下一个版本中移除此工具。
  */
+@Deprecated
 @Component
 public class InternalDocsTools {
     
@@ -45,11 +50,12 @@ public class InternalDocsTools {
      *
      * @param query 搜索查询，描述您要查找的信息
      * @return JSON 格式的搜索结果，包含相关文档内容、相似度分数和元数据
+     * @deprecated 请使用 {@link com.superbiz.agent.tool.LookupKnowledgeTool#lookupKnowledge(String)} 替代
      */
-    @Tool(description = "Use this tool to search internal documentation and knowledge base for relevant information. " +
-            "It performs RAG (Retrieval-Augmented Generation) to find similar documents and extract processing steps. " +
-            "This is useful when you need to understand internal procedures, best practices, or step-by-step guides " +
-            "stored in the company's documentation.")
+    @Deprecated
+    @Tool(description = "[DEPRECATED] Use lookup_knowledge instead. " +
+            "This tool performs semantic search only. " +
+            "lookup_knowledge provides L0 exact match + L1 semantic search with better performance.")
     public String queryInternalDocs(
             @ToolParam(description = "Search query describing what information you are looking for") 
             String query) {
diff --git a/src/main/resources/prompts/executor-prompt.md b/src/main/resources/prompts/executor-prompt.md
index 991d10f..1a63b92 100644
--- a/src/main/resources/prompts/executor-prompt.md
+++ b/src/main/resources/prompts/executor-prompt.md
@@ -1,8 +1,7 @@
 你是 Executor Agent，负责读取 Planner 最新输出 {planner_plan}，只执行其中的第一步。
 - 确认步骤所需的工具与参数，尤其是 region 参数要使用连字符格式（ap-guangzhou）；若 Planner 未给出则使用默认区域。
 - 根据查询内容选择合适的工具：
-  * 精确关键词（错误码、配置项名称）→ 优先使用 lookup_knowledge，未找到时降级到 queryInternalDocs
-  * 模糊概念、故障流程 → 直接使用 queryInternalDocs
+  * 知识库查询（错误码、配置项、概念理解、故障流程）→ 使用 lookup_knowledge
   * 告警数据 → queryPrometheusAlerts
   * 日志数据 → queryLogs
 - 调用相应的工具并收集结果，如工具返回错误或空数据，需要将失败原因、请求参数一并记录，并停止进一步调用该工具（同一工具失败达到 3 次时应直接返回 FAILED）。