SuperBizAgent-java/mvp/architecture/knowledge-retrieval-usage.md

# 知识库检索使用指南

## 快速开始

### 1. 文档格式要求

所有知识库文档必须包含 YAML frontmatter：

```markdown
---
title: 文档标题（必填）
keywords: [关键词1, 关键词2, 关键词3]（必填）
summary: 文档摘要（必填）
category: api（可选）
version: 1.0（可选）
author: zhangsan（可选）
---

# 正文内容

这里是文档的正文...
```

### 2. 上传文档

**API 端点**：
```
POST /api/documents/upload
Content-Type: multipart/form-data

参数：
- file: Markdown 文件
- category: 分类（如 api, infrastructure, domain, troubleshooting）
```

**示例**：
```bash
curl -X POST http://localhost:9900/api/documents/upload \
  -F "file=@payment-errors.md" \
  -F "category=api"
```

**返回**：
```json
{
  "docId": "abc123-def456-...",
  "status": "success"
}
```

### 3. Agent 调用

在 Agent 对话中，工具会自动可用：

```
用户：ERR_TIMEOUT 是什么错误？

Agent 内部：
1. 调用 lookup_knowledge("ERR_TIMEOUT")
2. L0 精确匹配找到 payment-errors.md
3. 返回完整错误码定义（高置信度）

Agent 回复：
ERR_TIMEOUT 是支付网关超时错误。
原因：...
排查方向：...
```

---

## 编写知识库文档

### Frontmatter 字段说明

#### 必填字段

**title**（标题）
```yaml
title: 支付网关错误码定义
```
- 简洁明了，能准确描述文档内容
- 建议 10-30 字

**keywords**（关键词列表）
```yaml
keywords: [ERR_TIMEOUT, 超时, 支付网关, 错误码]
```
- 用于 L0 精确匹配
- 包含所有可能的查询词
- 建议 3-10 个关键词
- 既要精确（ERR_TIMEOUT），也要通用（超时）

**summary**（摘要）
```yaml
summary: 记录了支付网关所有核心错误码的含义、原因分析及排查方向
```
- 一句话描述文档用途
- 建议 30-100 字

#### 可选字段

**category**（分类）
```yaml
category: api
```
- 推荐值：api, infrastructure, domain, troubleshooting
- 用于目录组织

**version**（版本）
```yaml
version: 1.0
```
- 文档版本号
- 便于追踪更新

**author**（作者）
```yaml
author: zhangsan
```
- 文档维护者

### 关键词设计技巧

#### ✅ 好的关键词设计

```yaml
keywords: [ERR_TIMEOUT, 超时, 支付网关, timeout, 网关超时, 支付超时]
```

**特点**：
- 包含精确术语（ERR_TIMEOUT）
- 包含通用描述（超时）
- 包含组合词（网关超时、支付超时）
- 包含英文（timeout）

#### ❌ 不好的关键词设计

```yaml
keywords: [错误, 问题]
```

**问题**：
- 太宽泛，导致多个文档匹配
- Agent 获得低置信度结果

### 文档内容建议

#### 结构化内容

```markdown
# 支付网关错误码定义

## ERR_TIMEOUT

**错误说明**：支付网关调用超时

**可能原因**：
1. 网络延迟
2. 支付网关响应慢
3. 本地超时配置过短

**排查步骤**：
1. 检查网络连通性
2. 查看支付网关监控
3. 检查超时配置

**解决方案**：
- 增加超时时间
- 优化网络链路
- 联系支付网关排查
```

#### 包含实际示例

```markdown
## 配置示例

```yaml
payment:
  gateway:
    timeout: 5000ms  # 推荐 5 秒
    retry: 3
```

## 日志示例

```
2026-06-24 10:00:00 ERROR PaymentService - ERR_TIMEOUT: 支付请求超时
orderId: 12345, timeout: 3000ms
```
```

---

## 使用场景

### 场景 1: 错误码查询

**用户输入**：
```
ERR_TIMEOUT 是什么意思？
```

**Agent 流程**：
1. 调用 `lookup_knowledge("ERR_TIMEOUT")`
2. L0 精确匹配 → 唯一匹配 → 高置信度
3. 返回完整文档内容（前 2000 字符）
4. Agent 基于文档内容回答

**响应时间**：< 10ms

### 场景 2: 配置项查询

**用户输入**：
```
Redis 连接池怎么配置？
```

**Agent 流程**：
1. 调用 `lookup_knowledge("Redis")`
2. L0 精确匹配 → 可能多个匹配 → 低置信度
3. 同时调用 L1 语义检索补充
4. 返回 primary (L0) + supplement (L1)
5. Agent 综合两份结果回答

**响应时间**：< 500ms

### 场景 3: 流程查询

**用户输入**：
```
如何排查生产故障？
```

**Agent 流程**：
1. 调用 `lookup_knowledge("故障排查")`
2. L0 精确匹配 → 找到故障诊断文档
3. 返回标准诊断流程
4. Agent 按照流程指导用户

### 场景 4: 最佳实践查询

**用户输入**：
```
Spring AI 工具怎么写？
```

**Agent 流程**：
1. 调用 `lookup_knowledge("Spring AI")`
2. L0 + L1 混合检索
3. 返回最佳实践文档
4. Agent 提供具体建议和代码示例

---

## 维护知识库

### 文档更新流程

1. **修改本地文件**
   ```bash
   vim knowledge_base/api/payment-errors.md
   ```

2. **重新上传**
   ```bash
   curl -X POST http://localhost:9900/api/documents/upload \
     -F "file=@payment-errors.md" \
     -F "category=api"
   ```

3. **验证更新**
   - 重启应用（L0 索引重建）
   - 或等待下次部署

### 文档删除

```bash
DELETE /api/documents/{docId}
```

**注意**：
- 同时删除 MySQL 记录
- 删除 Milvus 向量索引
- 删除本地文件
- 从 L0 索引移除

### 查看已索引文档

启动日志中查看：
```
[INFO] 开始扫描知识库目录: knowledge_base/
[DEBUG] 文档已加入索引: title=支付网关错误码定义
[DEBUG] 文档已加入索引: title=Redis 缓存配置指南
[INFO] 知识库索引加载完成，共 6 个文档
```

---

## 故障排查

### 问题 1: 文档未被索引

**症状**：
- 上传成功，但 Agent 查询不到

**排查**：
1. 检查 frontmatter 格式是否正确
2. 查看启动日志是否有 WARN
3. 确认文件保存位置

**解决**：
```bash
# 检查文件是否存在
ls knowledge_base/api/payment-errors.md

# 检查 frontmatter 格式
head -20 knowledge_base/api/payment-errors.md

# 重启应用重建索引
```

### 问题 2: 总是调用 L1（低置信度）

**症状**：
- 查询耗时 > 200ms
- 日志显示调用 L1

**原因**：
- L0 未匹配（关键词不在 keywords 中）
- L0 多个匹配（关键词重复）

**解决**：
```yaml
# 检查关键词是否覆盖查询词
keywords: [ERR_TIMEOUT, 超时, timeout]

# 避免关键词过于宽泛
❌ keywords: [错误, 问题]  # 太宽泛
✅ keywords: [ERR_TIMEOUT, 超时]  # 精准
```

### 问题 3: 查询返回不完整

**症状**：
- 文档内容被截断

**原因**：
- 文档过长，L0 只返回前 2000 字符

**解决**：
1. 将长文档拆分成多个短文档
2. 每个文档聚焦一个主题
3. 或等待 Phase 2 章节锚点功能

### 问题 4: 启动扫描很慢

**症状**：
- 应用启动时间过长

**原因**：
- knowledge_base/ 文件过多

**解决**：
```bash
# 检查文档数量
find knowledge_base -name "*.md" | wc -l

# 清理无用文档
rm knowledge_base/.backup/*.md
```

**参考指标**：
- 500 个文档：< 1s
- 1000 个文档：可能需要优化

---

## 性能优化

### 优化关键词匹配率

**目标**：提高高置信度命中率（减少 L1 调用）

**方法**：
1. 分析查询日志，找到常见查询词
2. 将常见查询词加入 keywords
3. 定期审查和优化 keywords

**示例**：
```bash
# 查看低置信度查询
grep "confidence=low" logs/application.log | \
  awk -F'query=' '{print $2}' | \
  awk -F',' '{print $1}' | \
  sort | uniq -c | sort -rn
```

### 减少文档数量

**策略**：
- 删除过时文档
- 合并相似文档
- 归档不常用文档

### 监控关键指标

**配置监控**：
- L0 查询耗时（目标 < 10ms）
- L1 调用频率（目标 < 30%）
- 高置信度命中率（目标 > 70%）

---

## 最佳实践总结

### ✅ 推荐做法

1. **关键词全面**
   - 包含精确术语和通用描述
   - 包含英文和中文
   - 包含常见拼写变体

2. **文档聚焦**
   - 一个文档一个主题
   - 避免大而全的文档

3. **结构化内容**
   - 使用清晰的标题层次
   - 包含实际示例
   - 提供具体步骤

4. **定期维护**
   - 定期审查和更新
   - 删除过时内容
   - 优化关键词

### ❌ 避免做法

1. **关键词模糊**
   ```yaml
   ❌ keywords: [错误, 问题]
   ✅ keywords: [ERR_TIMEOUT, 超时]
   ```

2. **文档过长**
   ```markdown
   ❌ 一个文档包含 50 个错误码定义（会被截断）
   ✅ 每个错误码一个文档，或按类型分组
   ```

3. **缺少实际示例**
   ```markdown
   ❌ Redis 配置很重要，需要优化
   ✅ 
   ```yaml
   spring:
     redis:
       lettuce:
         pool:
           max-active: 8
   ```
   ```

4. **长期不更新**
   - 定期审查（建议每季度）
   - 删除过时内容
   - 添加新的常见问题

---

## 参考资料

- **架构文档**：`mvp/architecture/knowledge-retrieval-architecture.md`
- **可观测性**：`.docs/knowledge-observability.md`
- **Handoff 文档**：`handoff/2026-06-24-lookup-knowledge-integration.md`
- **OpenSpec**：`openspec/changes/lookup-knowledge-integration/`