# RAG L0 关键词匹配质量不足

**状态**：待规划  
**严重程度**：中  
**发现时间**：2026-07-04  
**范围**：L0 索引、frontmatter、精确召回

---

## 现象

L0 当前依赖文档 frontmatter 中的关键词，并使用较粗的字符串包含逻辑做匹配。关键词质量越依赖人工维护，召回稳定性越容易波动。

如果 frontmatter 填写不完整、同义词缺失、关键词过短或过泛，L0 就可能误召回或漏召回。

---

## 当前实现

- `KnowledgeIndexService` 从 `ApiDocument` metadata/frontmatter 加载关键词。
- exact match 的判断类似：

```java
query.contains(keywordLower) || keywordLower.contains(query)
```

- 没有分词、同义词归一、字段权重、关键词质量校验。

---

## 影响

- 短关键词容易误命中。
- 用户换一种说法时，L0 无法命中。
- 文档 frontmatter 质量变成检索质量的隐性前提。

---

## 建议修复

1. 为关键词增加最小长度、停用词、领域前缀等基础规则。
2. 区分 `exactKeywords`、`aliases`、`domainTags`，避免所有词混在一个匹配池。
3. 引入轻量中文分词或归一化策略，先不必上复杂搜索引擎。
4. 上传文档时校验 frontmatter 质量，缺失关键词时给出警告。
5. 在 issue 修复前，至少补一份知识库文档 frontmatter 编写规范。

---

## 相关文件

- `src/main/java/com/superbiz/agent/service/KnowledgeIndexService.java`
- `src/main/java/com/superbiz/agent/service/DocumentManagementService.java`
- `src/main/java/com/superbiz/agent/controller/DocumentController.java`