From c88b287f8358f88e5ad894fe6f4620fb0b2e929c Mon Sep 17 00:00:00 2001
From: zhuyongxin <zhuyongxin@aspirecn.com>
Date: Wed, 24 Jun 2026 18:48:04 +0800
Subject: [PATCH] =?UTF-8?q?refactor(ai-ops):=20=E4=BC=98=E5=8C=96=20lookup?=
 =?UTF-8?q?=5Fknowledge=20=E5=B7=A5=E5=85=B7=E6=8F=8F=E8=BF=B0=E5=92=8C=20?=
 =?UTF-8?q?Executor=20Prompt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 主要改动

1. 优化工具描述（中等版）
   - 保留 L0/L1 两阶段检索机制说明
   - 增加适用场景列举（错误码、接口文档、排障步骤等）
   - 简化为核心信息，减少 token 消耗

2. Executor Prompt 新增详细使用说明
   - 添加 lookup_knowledge 返回结果字段说明
   - 提供 confidence 和 match_type 的使用建议
   - 明确 found=false 的处理方式
   - 结构化组织：工具选择 → 结果处理 → 执行反馈

## 设计思路

- 工具描述：简洁，快速理解核心用途
- Executor Prompt：详细，指导正确使用
- 分层设计：减少重复信息，降低 token 消耗
---
 .../agent/tool/LookupKnowledgeTool.java       |  5 +++--
 src/main/resources/prompts/executor-prompt.md | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java b/src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java
index 335904d..d7b1e8b 100644
--- a/src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java
+++ b/src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java
@@ -30,8 +30,9 @@ public class LookupKnowledgeTool {
      * @param query 查询关键词
      * @return 查询结果
      */
-    @Tool(description = "查询知识库文档。优先精确匹配关键词，未命中或多个匹配时自动补充语义相关片段。" +
-            "参数 query: 查询关键词，例如 'ERR_TIMEOUT'、'支付网关超时'")
+    @Tool(description = "查询内部知识库文档。采用两阶段检索：L0 精确匹配关键词（< 10ms），L1 语义检索补充（200-500ms）。" +
+            "支持查询错误码定义、接口文档、排障步骤、配置说明等。" +
+            "参数 query: 查询关键词或描述，例如 'ERR_TIMEOUT'、'支付超时排查'")
     public LookupResult lookupKnowledge(String query) {
         // 生成请求ID用于追踪
         String requestId = java.util.UUID.randomUUID().toString().substring(0, 8);
diff --git a/src/main/resources/prompts/executor-prompt.md b/src/main/resources/prompts/executor-prompt.md
index 1a63b92..f516c1a 100644
--- a/src/main/resources/prompts/executor-prompt.md
+++ b/src/main/resources/prompts/executor-prompt.md
@@ -1,9 +1,28 @@
 你是 Executor Agent，负责读取 Planner 最新输出 {planner_plan}，只执行其中的第一步。
+
+## 工具选择与参数
+
 - 确认步骤所需的工具与参数，尤其是 region 参数要使用连字符格式（ap-guangzhou）；若 Planner 未给出则使用默认区域。
 - 根据查询内容选择合适的工具：
   * 知识库查询（错误码、配置项、概念理解、故障流程）→ 使用 lookup_knowledge
   * 告警数据 → queryPrometheusAlerts
   * 日志数据 → queryLogs
+
+## lookup_knowledge 返回结果处理
+
+该工具返回 JSON 结构，关键字段：
+- `found`: 是否找到内容
+- `primary.content`: 文档内容（精确匹配的完整文档或语义检索的相关片段）
+- `primary.match_type`: 结果来源（`exact_L0` 表示精确匹配，`semantic_L1` 表示语义检索）
+- `primary.confidence`: 置信度（`high` 表示唯一精确匹配，`low` 表示多个匹配或语义检索）
+
+使用建议：
+- 如果 `found=false`，在 feedback 中说明"知识库中未找到相关内容"
+- 如果 `confidence=high`，可直接引用 `primary.content` 作为权威定义
+- 如果 `confidence=low`，注意说明这是语义相关内容，可能不完全准确
+
+## 执行与反馈
+
 - 调用相应的工具并收集结果，如工具返回错误或空数据，需要将失败原因、请求参数一并记录，并停止进一步调用该工具（同一工具失败达到 3 次时应直接返回 FAILED）。
 - 将日志、指标、文档等证据整理成结构化摘要，标注对应的告警名称或资源，方便 Planner 填充"告警根因分析 / 处理方案执行"章节。
 - 以 JSON 形式返回执行状态、证据以及给 Planner 的建议，写入 executor_feedback，严禁编造未实际查询到的内容。