# 知识库文档编写与维护

**更新日期**：2026-07-05  
**状态**：当前建议规范  
**参考历史文档**：`archive/2026-07-05-legacy/knowledge-retrieval-usage.md`

## 1. 定位

知识库文档不是普通 Markdown 资料堆叠，而是 RAG 检索的输入资产。写得好的文档会提升：

- L0 hint 的关键词和领域识别。
- L1 向量召回质量。
- `breadcrumb` 上下文恢复能力。
- Verifier 可引用的证据质量。

当前推荐写法：结构化 Markdown + frontmatter + 明确分类 + 可检索关键词。

## 2. 文档进入系统的链路

```mermaid
flowchart TD
    Markdown["Markdown file"] --> Upload["POST /api/documents/upload"]
    Upload --> Parse["FrontmatterParser"]
    Parse --> Enrich["DocumentFieldEnricher"]
    Enrich --> Metadata["api_document.metadata"]
    Upload --> Chunk["DocumentChunkService"]
    Chunk --> Breadcrumb["title / breadcrumb / chunkIndex"]
    Breadcrumb --> Embedding["VectorIndexService embedding text"]
    Embedding --> Milvus["Milvus/Zilliz"]
    Metadata --> L0["KnowledgeIndexService L0 index"]
    Milvus --> L1["VectorSearchService L1 retrieval"]
```

## 3. Frontmatter

推荐模板：

```markdown
---
title: 支付网关错误码定义
keywords: [ERR_TIMEOUT, 支付超时, payment timeout, 支付网关]
summary: 记录支付网关核心错误码的含义、常见原因和排查步骤
category: api
version: 1.0
author: sre-team
---

# 支付网关错误码定义

...
```

字段说明：

| 字段 | 必填 | 用途 |
|---|---:|---|
| `title` | 是 | 文档标题，进入 L0 索引和 embedding 上下文 |
| `keywords` | 是 | L0 hint 的主要来源 |
| `summary` | 是 | 文档摘要，进入知识域描述和 Agent 上下文 |
| `category` | 建议 | 知识域、metadata filter、上传目录 |
| `version` | 可选 | 文档版本 |
| `author` | 可选 | 维护人 |

当前解析器会提示缺少 `title`、`keywords`、`summary` 的情况；缺失不一定阻断上传，但会降低检索质量。

## 4. category 建议

`category` 会影响：

- 上传文件本地目录。
- Milvus metadata。
- L0 domain hint。
- `knowledge_domain` 聚合。
- VectorStore / SDK category filter。

推荐保持稳定，不要频繁换名。

| category | 用途 |
|---|---|
| `api` | 接口、错误码、请求/响应协议 |
| `infrastructure` | MySQL、Redis、JVM、网络、中间件 |
| `troubleshooting` | 通用排障流程、Runbook |
| `domain` | 业务领域规则 |
| `spring-ai` | Spring AI / Agent / 工具最佳实践 |

注意：分类过细会导致 filter 召回不足；分类过粗会降低 L0 hint 解释力。

## 5. 关键词写法

好的关键词应该覆盖：

- 精确实体：错误码、服务名、指标名。
- 常用中文说法。
- 英文别名。
- 组合词。

示例：

```yaml
keywords: [ERR_TIMEOUT, timeout, 支付超时, 支付网关超时, payment-service, gateway timeout]
```

避免：

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

原因：过宽关键词会让 L0 hint 变脏，多个文档同时命中，影响解释性和 category filter。

## 6. Markdown 结构

推荐结构：

```markdown
# 文档总标题

## 场景或错误码

### 含义

### 常见原因

### 排查步骤

### 处理方案

### 日志示例
```

为什么这样写：

- `DocumentChunkService` 会按 Markdown 标题切分。
- 标题层级会生成 `breadcrumb`。
- `title + breadcrumb + content` 会一起进入 embedding 文本。
- 命中 chunk 时，Agent 更容易知道证据属于哪个章节。

## 7. 内容建议

每个可诊断条目尽量包含：

- 现象。
- 判断条件。
- 可能原因。
- 证据来源。
- 排查步骤。
- 处理建议。
- 日志或配置示例。

示例：

```markdown
## ERR_TIMEOUT

### 含义

支付网关请求超过本地或上游超时时间。

### 常见原因

1. 第三方支付服务响应慢。
2. 本地 timeout 配置过短。
3. 网络链路抖动。

### 排查步骤

1. 查询 payment-service 日志中的请求耗时。
2. 查看网关 5xx 和 timeout 指标。
3. 对比当前 timeout 配置。

### 处理建议

- 短期：重试受影响订单。
- 长期：调整 timeout 和重试策略，并监控上游延迟。
```

## 8. 上传与索引

上传接口：

```text
POST /api/documents/upload
Content-Type: multipart/form-data

file=<markdown file>
category=<category>
```

系统处理：

1. 计算文件 hash，避免重复上传。
2. 保存原始文件。
3. 解析 frontmatter。
4. 补全文档字段。
5. 写入 `api_document`。
6. Markdown-aware chunking。
7. 写入 Milvus/Zilliz。
8. 更新 L0 索引和 `knowledge_domain`。

## 9. 重建索引注意事项

当以下内容变化时，需要重新索引：

- 正文内容。
- 标题层级。
- `category`。
- `title`、`summary`、`keywords`。
- embedding 输入策略，例如加入 `breadcrumb`。

特别注意：

```text
修改 Markdown 或 embedding 输入策略，不会自动改变已有向量。
必须重新上传或重建索引后，live retrieval 才能体现变化。
```

可用 live 验收：

```bash
python scripts/eval_rag_live_acceptance.py
```

## 10. 维护 checklist

新增文档前检查：

- frontmatter 是否包含 `title`、`keywords`、`summary`。
- `category` 是否属于现有稳定分类。
- 关键词是否既有精确词也有常用表达。
- Markdown 标题层级是否清晰。
- 每个故障条目是否包含可执行排查步骤。
- 日志/配置示例是否脱敏。

更新文档后检查：

- `api_document.status` 是否为 `INDEXED`。
- `/api/search/similar` 是否能搜到目标文档。
- `eval/rag-retrieval` 是否需要新增 golden case。
- Trace 中 `tool_invocation` 是否记录到正确 source 和 breadcrumb。