SuperBizAgent-java/.docs/2026-06-24-ai-ops-prompt-config-and-lookup-tool.md

AI Ops Prompt 配置化 & LookupKnowledgeTool 集成

日期: 2026-06-24
类型: 功能增强 + 架构优化
影响范围: AI Ops 服务

---

一、变更背景

1.1 问题

• 硬编码 Prompt：Planner、Executor、Supervisor 的系统提示词硬编码在 AiOpsService.java 中，难以维护和版本控制
• 缺少知识库精确检索：现有 InternalDocsTools 只支持 L1 语义检索（200-500ms），对于错误码、配置项等精确关键词查询效率较低

1.2 解决方案

1. Prompt 配置化：将所有 Agent 的 Prompt 抽取到 prompts/ai-ops-prompts.yml 配置文件
2. 集成 L0+L1 混合检索：引入 LookupKnowledgeTool，支持精确关键词匹配（< 10ms）+ 语义检索补充

---

二、架构变更

2.1 Prompt 配置化架构

AiOpsService
    ↓ 注入
AiOpsPromptProperties (配置类)
    ↓ @PostConstruct 加载
ClassPathResource 读取 Markdown 文件
    ↓ 读取
prompts/
├── planner-prompt.md
├── executor-prompt.md
└── supervisor-prompt.md

优点：

• 易于维护：Prompt 修改不需要重新编译
• 格式友好：Markdown 格式支持代码块、表格，无 YAML 转义问题
• 版本控制：配置文件独立管理
• 易于扩展：后续可按环境区分（dev/prod）

2.2 工具层增强

原有工具：
- queryInternalDocs (纯 L1 语义检索，200-500ms)

新增工具：
- lookup_knowledge (L0 精确匹配 + L1 补充，< 10ms 高置信度)

使用策略：

• 精确关键词（错误码、配置项）→ lookup_knowledge，未找到时降级到 queryInternalDocs
• 模糊概念、故障流程 → 直接使用 queryInternalDocs

---

三、核心改动

3.1 新增文件

AiOpsPromptProperties.java

@Configuration
public class AiOpsPromptProperties {
    private String planner;
    private String executor;
    private String supervisor;

    @PostConstruct
    public void loadPrompts() {
        planner = loadPromptFromFile("prompts/planner-prompt.md");
        executor = loadPromptFromFile("prompts/executor-prompt.md");
        supervisor = loadPromptFromFile("prompts/supervisor-prompt.md");
    }
    
    private String loadPromptFromFile(String path) throws IOException {
        ClassPathResource resource = new ClassPathResource(path);
        return new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
    }
}

prompts/*.md

三个独立的 Markdown 文件，包含 Agent 的完整系统提示词：

• planner-prompt.md - Planner Agent 系统提示词
• executor-prompt.md - Executor Agent 系统提示词（含工具选择指南）
• supervisor-prompt.md - Supervisor Agent 系统提示词

3.2 修改文件

AiOpsService.java

注入新组件：

@Autowired
private LookupKnowledgeTool lookupKnowledgeTool;

@Autowired
private AiOpsPromptProperties promptProperties;

使用配置化 Prompt：

// 原来
.systemPrompt(buildPlannerPrompt())

// 改为
.systemPrompt(promptProperties.getPlanner())

添加工具到工具数组：

return new Object[]{
    dateTimeTools, 
    internalDocsTools, 
    queryMetricsTools, 
    lookupKnowledgeTool  // 新增
};

删除方法：

• buildPlannerPrompt()
• buildExecutorPrompt()
• buildSupervisorSystemPrompt()

---

四、Executor Prompt 变更详情

4.1 新增工具选择指南

- 根据查询内容选择合适的工具：
  * 精确关键词（错误码、配置项名称）→ 优先使用 lookup_knowledge，未找到时降级到 queryInternalDocs
  * 模糊概念、故障流程 → 直接使用 queryInternalDocs
  * 告警数据 → queryPrometheusAlerts
  * 日志数据 → queryLogs

4.2 降级策略

关键改进：明确了 lookup_knowledge 未找到时的降级策略。

流程：

1. Planner: "查询 ERR_TIMEOUT 定义"
2. Executor: 调用 lookup_knowledge("ERR_TIMEOUT")
3a. 如果 found=true, confidence=high → 使用 primary.content
3b. 如果 found=false → 自动降级到 queryInternalDocs("ERR_TIMEOUT 超时错误")
4. 返回 feedback 给 Planner

---

五、兼容性说明

5.1 向后兼容

✅ 完全兼容：

• 现有工具调用逻辑不变
• 3-Agent 协同模式不变
• Planner/Executor/Supervisor 的职责边界不变

5.2 新增依赖

• LookupKnowledgeTool 依赖 KnowledgeIndexService 和 VectorSearchService
• 需要 knowledge_base/ 目录存在（已在 application.yml 中配置）

---

六、验证清单

6.1 编译验证

mvn clean compile -DskipTests

✅ 结果: BUILD SUCCESS

6.2 运行时验证（待完成）

• 启动应用，验证 Prompt 配置加载成功
• 触发 AI Ops 流程，验证 lookup_knowledge 工具可调用
• 测试精确关键词查询（如 "ERR_TIMEOUT"）
• 测试降级策略（查询不存在的关键词）

---

七、后续工作

7.1 知识库内容准备

当前 knowledge_base/ 目录需要补充文档：

• 错误码定义（支付网关、订单系统等）
• 配置最佳实践（Redis、HikariCP、Flyway 等）
• 故障排查流程

文档格式示例：

---
title: 支付网关错误码定义
keywords: [ERR_TIMEOUT, 超时, 支付网关]
summary: 记录了支付网关所有核心错误码的含义及排查方向
category: api
---

# 支付网关错误码定义

## ERR_TIMEOUT
...

7.2 Prompt 优化

基于实际运行反馈，持续优化 prompts/ai-ops-prompts.yml 中的提示词。

7.3 可观测性增强

• 监控 lookup_knowledge 的调用频率和命中率
• 记录降级场景（L0 未找到 → L1 补充）

---

八、参考文档

• 知识库检索架构说明
• AI Ops 核心设计 Essence 报告