EnterpriseArchitect/docs/agent-kb-retrieval-guide.md

# Agent 知识库检索指南

> **版本**: v1.0  
> **维护**: 严维序 (opengineer)  
> **日期**: 2026-06-22

---

## 一、检索工具选择决策树

```
需要检索知识库？
├── 精确查找已知页面 → wiki_get(lookup="页面路径")
├── 搜索未知内容
│   ├── 关键词明确 → wiki_search(query="关键词")
│   ├── 语义模糊 → wiki_search(query="自然语言问题")
│   └── 需要文档全文 → qmd query / qmd search
├── 需要深度分析（跨文档） → wiki_search + wiki_get 组合
├── 质量检查 → wiki_lint()
└── 系统状态确认 → wiki_status()
```

---

## 二、工具对比速查表

| 维度 | wiki_search | wiki_get | qmd (CLI) |
|------|-------------|----------|-----------|
| **用途** | 模糊搜索/发现 | 精确读取 | 全文/语义搜索 |
| **查询类型** | 标题+路径+正文 | 精确路径或 ID | lex/vec/hyde 多类型 |
| **返回内容** | 匹配片段+元数据 | 完整页面内容 | 排序结果+评分 |
| **速度** | 快 | 最快 | 依赖索引（首次慢） |
| **适用场景** | "有没有关于 X 的文档" | "打开 X 页面" | "找所有涉及 Y 的内容" |
| **依赖** | 无（OpenClaw 内置） | 无（OpenClaw 内置） | QMD 服务（需运行） |
| **搜索范围** | Wiki vault | Wiki vault | 注册的 markdown 目录 |

---

## 三、查询语句构造示例

### wiki_search

**简单关键词搜索**:
```
wiki_search(query="nginx 配置")
```

**多词精确搜索**:
```
wiki_search(query="deployment pipeline CI/CD")
```

**语义问题搜索**:
```
wiki_search(query="如何配置 nginx 反向代理")
```

**限制结果数量**:
```
wiki_search(query="监控告警", maxResults=5)
```

### wiki_get

**按页面标题查找**:
```
wiki_get(lookup="服务器清单")
```

**按文件路径查找**:
```
wiki_get(lookup="docs/deployment-guide")
```

**分页读取大文件**:
```
wiki_get(lookup="长文档", fromLine=1, lineCount=50)
```

### qmd (CLI)

**关键词搜索**:
```bash
qmd search "nginx logrotate configuration"
```

**语义搜索**:
```bash
qmd query "如何解决 nginx 日志轮转失败的问题"
```

**结构化搜索 (JSON)**:
```bash
qmd query --json --explain "nginx logrotate error"
```

**多类型组合**:
```bash
qmd query $'lex: nginx logrotate\nvec: how to fix log rotation failure'
```

---

## 四、结果处理流程

```
搜索结果
├── 有匹配结果
│   ├── 1-3 个结果 → wiki_get 逐个读取完整内容
│   ├── 4-10 个结果 → 按评分排序，取前 3 个读取
│   └── 10+ 个结果 → 收窄搜索词重新搜索
├── 无结果
│   ├── 尝试同义词/相关词重新搜索
│   ├── 尝试 qmd 搜索（如果 wiki_search 无结果）
│   └── 仍无结果 → 触发知识缺口上报
└── 结果不相关
    └── 调整查询词 → 重新搜索 → 仍不相关 → 上报缺口
```

---

## 五、知识缺口上报机制

### 触发条件

1. `wiki_search` 和 `qmd` 均无匹配结果
2. 搜索结果与需求明显不相关
3. 找到的文档内容已过时或不完整

### 上报格式

缺口上报应包含以下信息：

```
【知识缺口】

- 查询意图: [用户/Agent 想了解什么]
- 已尝试检索词: [用过的搜索词列表]
- 已搜索工具: [wiki_search / qmd]
- 期望内容: [期望知识库中应有什么内容]
- 紧急程度: [high / normal / low]
- 建议: [建议谁负责补充、建议写入什么内容]
```

### 上报目标

- 紧急缺口 → architect（梁思筑）
- 文档更新缺口 → 对应领域 Agent
- 通用知识缺口 → projectmanager（胡蓉）

---

## 六、最佳实践

### DO ✅

- 先用 `wiki_search` 发现，再用 `wiki_get` 精读
- 搜索无结果时尝试多种表述方式
- `wiki_search` 结果多时限制 `maxResults`
- 大文档用 `fromLine`/`lineCount` 分页读取
- 定期运行 `wiki_lint` 检查知识库质量
- 每次重要发现后考虑是否需写入知识库

### DON'T ❌

- 不要跳过 `wiki_search` 直接用 `wiki_get` 猜测路径
- 不要单次读取超大页面全部内容（影响上下文）
- 不要忽略 `wiki_lint` 的报告建议
- 不要在 `wiki_search` 无结果后直接放弃（尝试 qmd）
- 不要将敏感信息（密钥/密码）写入 Wiki

---

## 七、示例工作流

### 场景: 查找"如何部署 Node.js 服务"

```
1. wiki_search(query="Node.js 部署")
   → 返回 2 个匹配: "服务部署规范", "Node.js 开发指南"

2. wiki_get(lookup="服务部署规范")
   → 读取完整内容，找到 systemd 配置部分

3. wiki_get(lookup="Node.js 开发指南", fromLine=30, lineCount=20)
   → 补充读取环境变量和启动参数配置

4. 整合信息 → 回答 Agent 问题
```

### 场景: 知识库中无结果

```
1. wiki_search(query="淘宝 API 对接")
   → No results

2. qmd query "淘宝 API"
   → No results

3. 上报知识缺口:
   【知识缺口】
   - 查询意图: 淘宝电商 API 对接文档
   - 已尝试: wiki_search("淘宝 API 对接"), qmd query "淘宝 API"
   - 期望内容: 淘宝开放平台 API 对接指南
   - 紧急程度: normal
   - 建议: 联系 taobaospecialist (陆云帆) 补充
```