Files

T

zhuyongxin 9b52afce07 docs: 合并 .docs/mvp 到根 mvp 目录并更新文档

- 删除 .docs/mvp 目录，内容合并到根目录 mvp/
- 更新 session-storage-design.md 实现变更记录
- 修复引用路径

2026-06-26 17:29:27 +08:00

5.8 KiB

Raw Blame History

AI Ops Prompt 配置化 & LookupKnowledgeTool 集成

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

一、变更背景

1.1 问题

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

1.2 解决方案

Prompt 配置化：将所有 Agent 的 Prompt 抽取到 prompts/ai-ops-prompts.yml 配置文件
集成 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 补充）

5.8 KiB Raw Blame History Unescape Escape