SuperBizAgent-java/mvp/architecture/knowledge-base-authoring.md

知识库文档编写与维护

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

1. 定位

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

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

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

2. 文档进入系统的链路

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

推荐模板：

---
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. 关键词写法

好的关键词应该覆盖：

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

示例：

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

避免：

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

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

6. Markdown 结构

推荐结构：

# 文档总标题

## 场景或错误码

### 含义

### 常见原因

### 排查步骤

### 处理方案

### 日志示例

为什么这样写：

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

7. 内容建议

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

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

示例：

## ERR_TIMEOUT

### 含义

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

### 常见原因

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

### 排查步骤

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

### 处理建议

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

8. 上传与索引

上传接口：

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。

特别注意：

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

可用 live 验收：

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。