refactor(ai-ops): 标记 queryInternalDocs 为弃用,统一使用 lookup_knowledge

## 改动说明

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

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

## 理由

lookup_knowledge 已经支持:
- L0 精确匹配(< 10ms,高置信度)
- L1 语义检索(自动兜底)

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

## 迁移路径

- 当前:标记为弃用,但保持可用
- 验证:观察 lookup_knowledge 是否能完全替代
- 未来:确认无问题后,在下个版本中移除
This commit is contained in:
zhuyongxin
2026-06-24 18:38:39 +08:00
parent c4d23c3bd8
commit 363767d3e7
2 changed files with 11 additions and 6 deletions
@@ -15,7 +15,12 @@ import java.util.List;
/** /**
* 内部文档查询工具 * 内部文档查询工具
* 使用 RAG (Retrieval-Augmented Generation) 从内部知识库检索相关文档 * 使用 RAG (Retrieval-Augmented Generation) 从内部知识库检索相关文档
*
* @deprecated 请使用 {@link com.superbiz.agent.tool.LookupKnowledgeTool} 替代。
* lookup_knowledge 支持 L0 精确匹配 + L1 语义检索,性能更优且功能更全面。
* 计划在下一个版本中移除此工具。
*/ */
@Deprecated
@Component @Component
public class InternalDocsTools { public class InternalDocsTools {
@@ -45,11 +50,12 @@ public class InternalDocsTools {
* *
* @param query 搜索查询,描述您要查找的信息 * @param query 搜索查询,描述您要查找的信息
* @return JSON 格式的搜索结果,包含相关文档内容、相似度分数和元数据 * @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. " + @Deprecated
"It performs RAG (Retrieval-Augmented Generation) to find similar documents and extract processing steps. " + @Tool(description = "[DEPRECATED] Use lookup_knowledge instead. " +
"This is useful when you need to understand internal procedures, best practices, or step-by-step guides " + "This tool performs semantic search only. " +
"stored in the company's documentation.") "lookup_knowledge provides L0 exact match + L1 semantic search with better performance.")
public String queryInternalDocs( public String queryInternalDocs(
@ToolParam(description = "Search query describing what information you are looking for") @ToolParam(description = "Search query describing what information you are looking for")
String query) { String query) {
@@ -1,8 +1,7 @@
你是 Executor Agent,负责读取 Planner 最新输出 {planner_plan},只执行其中的第一步。 你是 Executor Agent,负责读取 Planner 最新输出 {planner_plan},只执行其中的第一步。
- 确认步骤所需的工具与参数,尤其是 region 参数要使用连字符格式(ap-guangzhou);若 Planner 未给出则使用默认区域。 - 确认步骤所需的工具与参数,尤其是 region 参数要使用连字符格式(ap-guangzhou);若 Planner 未给出则使用默认区域。
- 根据查询内容选择合适的工具: - 根据查询内容选择合适的工具:
* 精确关键词(错误码、配置项名称)→ 优先使用 lookup_knowledge,未找到时降级到 queryInternalDocs * 知识库查询(错误码、配置项、概念理解、故障流程)→ 使用 lookup_knowledge
* 模糊概念、故障流程 → 直接使用 queryInternalDocs
* 告警数据 → queryPrometheusAlerts * 告警数据 → queryPrometheusAlerts
* 日志数据 → queryLogs * 日志数据 → queryLogs
- 调用相应的工具并收集结果,如工具返回错误或空数据,需要将失败原因、请求参数一并记录,并停止进一步调用该工具(同一工具失败达到 3 次时应直接返回 FAILED)。 - 调用相应的工具并收集结果,如工具返回错误或空数据,需要将失败原因、请求参数一并记录,并停止进一步调用该工具(同一工具失败达到 3 次时应直接返回 FAILED)。