# 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`
```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`

**注入新组件**：
```java
@Autowired
private LookupKnowledgeTool lookupKnowledgeTool;

@Autowired
private AiOpsPromptProperties promptProperties;
```

**使用配置化 Prompt**：
```java
// 原来
.systemPrompt(buildPlannerPrompt())

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

**添加工具到工具数组**：
```java
return new Object[]{
    dateTimeTools, 
    internalDocsTools, 
    queryMetricsTools, 
    lookupKnowledgeTool  // 新增
};
```

**删除方法**：
- `buildPlannerPrompt()`
- `buildExecutorPrompt()`
- `buildSupervisorSystemPrompt()`

---

## 四、Executor Prompt 变更详情

### 4.1 新增工具选择指南

```yaml
- 根据查询内容选择合适的工具：
  * 精确关键词（错误码、配置项名称）→ 优先使用 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 编译验证

```bash
mvn clean compile -DskipTests
```

✅ **结果**: BUILD SUCCESS

### 6.2 运行时验证（待完成）

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

---

## 七、后续工作

### 7.1 知识库内容准备

当前 `knowledge_base/` 目录需要补充文档：
- 错误码定义（支付网关、订单系统等）
- 配置最佳实践（Redis、HikariCP、Flyway 等）
- 故障排查流程

**文档格式示例**：
```markdown
---
title: 支付网关错误码定义
keywords: [ERR_TIMEOUT, 超时, 支付网关]
summary: 记录了支付网关所有核心错误码的含义及排查方向
category: api
---

# 支付网关错误码定义

## ERR_TIMEOUT
...
```

### 7.2 Prompt 优化

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

### 7.3 可观测性增强

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

---

## 八、参考文档

- [知识库检索架构说明](./mvp/architecture/knowledge-retrieval-architecture.md)
- [AI Ops 核心设计 Essence 报告](../docs/learning/01-AI-Ops-核心设计-Essence报告.md)