# 知识查询最佳实践

> **版本**: v1.0  
> **任务**: BIZ-19 (BIZ-14-4)  
> **日期**: 2026-06-22

---

## 一、查询策略

### 1.1 渐进式检索原则

```
先宽后窄 → 先模糊后精确 → 先搜索后读取
```

**标准流程**：
1. `wiki_search(query="关键词")` — 发现有哪些相关内容
2. `wiki_get(lookup="匹配页面")` — 精确读取具体内容
3. 如搜索结果过多（>10） → 收窄关键词重新搜索
4. 如搜索结果与需求不相关 → 调整表述方式重新搜索

### 1.2 查询词构造技巧

#### DO ✅

| 技巧 | 示例 | 说明 |
|------|------|------|
| 用领域特定术语 | `wiki_search(query="nginx 反向代理")` | 专业词汇提升精确度 |
| 用动词+对象 | `wiki_search(query="部署 Node.js")` | 明确查询意图 |
| 用自然语言问题 | `wiki_search(query="如何配置 nginx logrotate")` | 适合语义检索 |
| 用缩写和全称组合 | `wiki_search(query="CI/CD 持续集成")` | 覆盖不同表述 |
| 分步搜索 | 先搜 "nginx"，再搜 "nginx 日志" | 逐步收窄范围 |

#### DON'T ❌

| 反模式 | 错误示例 | 问题 |
|--------|----------|------|
| 过于泛化的词 | `wiki_search(query="配置")` | 结果太多太杂 |
| 过于具体的短语 | `wiki_search(query="192.168.1.99 端口 22 上的 nginx")` | 命中率低 |
| 跳过搜索直接 guess 路径 | `wiki_get(lookup="随便猜的页面名")` | 大概率找不到 |
| 一次加载超大页面 | `wiki_get(lookup="巨型文档")` | 超出上下文容量 |
| 无结果后直接放弃 | 只搜一次就说"知识库没内容" | 可能是查询词不准确 |

---

## 二、结果处理

### 2.1 匹配结果数量处理

| 结果数 | 处理方式 |
|--------|----------|
| 0 | 尝试同义词/相关词 → qmd 搜索 → 上报知识缺口 |
| 1-3 | 逐个 `wiki_get` 读取完整内容 |
| 4-10 | 按评分排序，取前 3 个读取 |
| 10+ | 收窄搜索词重新搜索 |

### 2.2 大页面分页读取

```bash
# 超过 100 行的页面，分页读取
wiki_get(lookup="长文档标题", fromLine=1, lineCount=50)   # 第一部分
wiki_get(lookup="长文档标题", fromLine=51, lineCount=50)  # 第二部分
```

### 2.3 信息来源交叉验证

当多个查询返回不同信息时：
1. 检查页面更新时间（优先信任较新的）
2. 交叉对比多个来源
3. 如信息冲突 → 标记为"需确认"，汇报给 architect

---

## 三、知识缺口处理

### 3.1 判定标准

满足以下任一条件即报告知识缺口：
- `wiki_search` 和 `qmd` 均无匹配
- 搜索结果与需求明显不相关
- 找到的文档内容已过时或不完整

### 3.2 上报模板

```
【知识缺口 - YYYY-MM-DD】

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

### 3.3 上报路径

| 缺口类型 | 上报目标 |
|----------|----------|
| 架构/技术 | architect (梁思筑) |
| 业务/流程 | projectmanager (胡蓉) |
| 法务/合规 | lawyer (苏慎) |
| 市场/分析 | marketanalysis (顾析策) |
| 通用/不确定 | COO (陆怀瑾) — 由 COO 分配 |

---

## 四、知识库写入准则

### 4.1 何时写入

- 完成重要决策后（如架构选型、策略调整）
- 发现可复用的模板/清单
- 完成深度分析后（市场报告、竞品分析）
- 知识缺口被填补后

### 4.2 写入工具选择

| 场景 | 工具 |
|------|------|
| 创建新知识页面 | `wiki_apply(op="create_synthesis", ...)` |
| 更新已有页面元数据 | `wiki_apply(op="update_metadata", ...)` |

### 4.3 不写入的内容

- 机密信息（密码、密钥、token）
- 临时信息（当天的具体任务进度）
- 已过时会被频繁更新的数据
- 纯个人笔记（放 `memory/` 下）

---

## 五、定期维护

### 5.1 COO 每周检查清单

- [ ] 运行 `wiki_lint()` 检查质量
- [ ] 统计各 Agent 知识库查询频率
- [ ] 清理过时页面
- [ ] 评估知识缺口数量和解决率
- [ ] 输出知识库运营周报

### 5.2 Agent 自检清单

每次心跳时：
- [ ] 上次查询的知识缺口是否已上报
- [ ] 本轮工作中是否有应写入知识库的发现

---

## 附录

- `docs/agent-kb-retrieval-guide.md` — 工具使用完整指南
- `docs/Agent 知识库集成指南.md` — 集成方案总览