# 当前知识库自动检索增强设计

> 状态：**已完成** · 实施于 2026-05-28 · 对应 ADR-19 · 阶段 3.5 收尾补强
>
> 本文档是 codex 实施手册。先读 §0 决策摘要，再按 §9 顺序动手。
> 任何与 [PRODUCT.md](../PRODUCT.md) 冲突的描述以 PRODUCT.md 为准；本文档需要破例的地方在 §12 明确写出并对应到 ADR-19。

## 0. 决策摘要（codex 起手必读）

| 决策 | 选择 | 理由速记 |
|---|---|---|
| 架构路线 | **双轨**：新工具 `query_knowledge_base` + `/api/prompt` 预调用同一份代码 | 工具路径符合 ADR-7；预调用兜底弱模型不调工具的情况 |
| 触发策略 | **黑名单**：默认触发，特定场景跳过 | 漏触发的代价是当前 bug；误触发的代价只是浪费 token |
| 多轮检索 | **每轮 user turn 都判断 + 检索** | 用户切话题时能立刻拿到新页面，本地 grep 成本可接受 |
| 失败降级 | **静默降级裸 prompt + SSE error 事件 + 日志** | 用户体验不中断，问题可溯源 |
| 检索 cache | **复用 [pages.ts](../server/src/pages.ts) 的 `getCachedPages`** | 避免两套 cache 失效时机错位 |
| `@` 格式契约 | **解析消息中的 `[[wiki/...]]`**（前端 [ChatPanel.tsx:218-230](../web/src/components/ChatPanel.tsx) 已插入此格式） | 不发明新语法 |
| 上下文上限 | **按 main 模型 contextWindow 的 20% 动态算**；模型未知时 fallback 4000 字符 | 兼顾 glm（4k 级）与 Claude（200k 级） |
| 验收硬标志 | **日志 + 字符串命中**双重客观可查 | 防止"看起来对实际没注入"的 hallucination 蒙混过关 |

## 1. 问题

阶段 3.5 已实现非 wiki 目录初始化 + 批量消化，但用户进入新知识库直接问"这是我自媒体创作的文章，总结一下"，主模型反问用户提供文章内容。

已确认事实：

- 批量消化结果已写入 `wiki/synthesis/sessions/`
- `/api/refs` 能列出这些新页面（[pages.ts](../server/src/pages.ts) PAGE_DIRS 含 `synthesis`）
- 失败对话的会话日志显示模型未调用任何 KB 工具
- `/api/prompt`（[index.ts:745-832](../server/src/index.ts)）当前是裸 `session.prompt(message)`，无任何检索 / 注入
- 现有 Extension 工具 `current_knowledge_base` / `list_knowledge_base_pages`（[extensions/knowledge-base.ts](../server/src/extensions/knowledge-base.ts)）描述写得够强，但 agent 实际不调

**根因**：主对话缺少一层"系统兜底检索"。ADR-7 设计的"靠 Extension 工具让 agent 自觉调用"在弱模型场景下不可靠。

## 2. 设计目标

- 用户在当前库提问，系统默认把当前库作为上下文来源
- `@` 显式引用优先级高于自动检索
- 回答末尾列参考页面；空库 / 无命中时明确说明
- 不把整个库塞进每次对话；不引入新依赖
- 不改变 `@` 引用 / `/` 命令 / 子代理批量消化的现有心智

## 3. 核心思路：双轨

```text
用户提问
  ↓
后端解析消息中的 [[wiki/...]] → 显式引用列表 R_explicit
  ↓
shouldUseKnowledgeBase(message) 判断是否触发自动检索（黑名单）
  ↓
若触发 → 调用同一份 searchKnowledgeBase(kbPath, query, R_explicit)
  ↓
拼成隐藏上下文 + 原始消息 → session.prompt(wrapped)
  ↓
模型输出（包含末尾"参考页面"）
```

同一份 `searchKnowledgeBase` 同时暴露为：

- **新工具** `query_knowledge_base(query)`：让强模型 / 未来强 agent 显式调用，符合 ADR-7
- **后端预调用**：`/api/prompt` 在判断需要时主动调，兜底弱模型不调工具的失败模式

这条路径只覆盖**主对话**。子代理批量消化（[digest/batch.ts](../server/src/digest/)）走的是裸 prompt + only read tool，本设计不涉及它。

## 4. 不采用的方案

### 4.1 纯改 prompt / 加强 system prompt

不稳定。同一模型不同问法、不同 provider 表现差异巨大。

### 4.2 每次塞整库

KB 大了就慢、贵、乱，污染普通聊天。

### 4.3 把批量消化结果写进聊天历史

消化结果属于知识库，不属于某一次对话。塞进历史会让切会话 / 切库 / 长期使用语义错乱。

### 4.4 立即引入向量库

本地文本检索足够覆盖当前阶段。未来 KB 规模 > 100 篇再升级。

### 4.5 纯工具路径（无后端预调用）

ADR-7 的精神路线，但已被你这次"反问要文章"的对话验证为不稳。本设计保留工具（双轨的一条腿），但不依赖它。

## 5. 解法方案

### 5.1 检索函数 `searchKnowledgeBase`

签名（伪代码，仅说明契约）：

```text
searchKnowledgeBase(kbPath, query, options) → SearchResult[]
  options:
    explicitRefs: string[]        // 来自 parseExplicitPageRefs，必含
    maxPages: number              // 默认 6
    snippetMaxChars: number       // 默认 600
    totalBudgetChars: number      // 由 /api/prompt 按模型 contextWindow 算后传入
  SearchResult:
    path: string                  // 相对 KB 根，如 wiki/synthesis/sessions/xxx.md
    title: string
    snippet: string
    mtime: number
    hitReason: 'explicit' | 'title' | 'filename' | 'body' | 'recent_synthesis' | 'kb_meta'
    score: number
```

**实现要点**：

1. **复用 [pages.ts](../server/src/pages.ts)**：调 `getCachedPages(kbPath)` 拿候选，不另建 cache。score 函数在 pages.ts 现有 title 2 / name 1 / path 0.5 基础上扩展（见下）。
2. **检索范围**：
   - `wiki/` 下所有 markdown（已被 pages.ts 覆盖）
   - 额外加 KB 元信息文件：`purpose.md` / `index.md` / `overview.md`（如果存在）—— 这些是"总结这个库"类问题的最强答案源
   - 现阶段**不读** `raw/` 下的原始素材（批量消化后用户应基于消化页问答）
3. **排序规则**（高到低）：
   - hitReason='explicit'（来自 `[[wiki/...]]` 显式引用，固定排首位）
   - hitReason='title'（标题命中）
   - hitReason='kb_meta'（purpose/index/overview 在泛化问题下加权）
   - hitReason='recent_synthesis'（`wiki/synthesis/sessions/` 在"这些文章 / 刚刚消化 / 总结"类问题下加权，按 mtime 降序）
   - hitReason='filename'
   - hitReason='body'
4. **片段提取**：命中 body 时，从命中位置前后各取 ~300 字符；标题/文件名命中时取页面开头 ~600 字符
5. **总预算控制**：累加每个 snippet 字符数，达到 `totalBudgetChars` 立即停止；至少保证 explicitRefs 全部入选（哪怕超 budget 也强保留显式引用的截断版本）
6. **空 KB 返回 `[]`，不抛错**
7. **cache 隔离**：pages.ts 的 cache 按 kbPath 隔离，retrieval 直接复用，无需自己维护

### 5.2 `parseExplicitPageRefs`

签名：

```text
parseExplicitPageRefs(message) → string[]   // 相对路径数组，如 ['wiki/synthesis/sessions/x.md']
```

**实现要点**：

- 正则匹配 `\[\[(wiki\/[^\]\n]+\.md)\]\]`
- 去重，保持出现顺序
- 不验证文件是否存在（验证交给 searchKnowledgeBase）

### 5.3 `shouldUseKnowledgeBase`（黑名单策略）

签名：

```text
shouldUseKnowledgeBase(message, kbSelected) → boolean
```

**实现要点**（按顺序判断，命中即返回）：

1. 没选中 KB → `false`
2. 消息 trim 后以 `/` 开头（命令）→ `false`
3. 消息已含 `[[wiki/...]]`（显式引用）→ `true`（短路，必须检索）
4. 消息 trim 后字符数 < 3 → `false`
5. 命中**寒暄白名单**（精确匹配，忽略标点）→ `false`
   - 集合：`你好` / `hi` / `hello` / `在吗` / `谢谢` / `thanks` / `thx` / `ok` / `好的`
6. 命中**元问询白名单**（含其一即跳过）→ `false`
   - 关键词：`当前模型` / `模型是什么` / `怎么设置` / `怎么用` / `界面` / `快捷键` / `登录` / `API key`
7. 其余 → `true`（默认触发）

**关键**：本策略激进地默认触发。误触发的代价只是 token，漏触发的代价是当前观察到的 bug。

### 5.4 `buildKnowledgeContextPrompt`

签名：

```text
buildKnowledgeContextPrompt(originalMessage, kb, results) → wrappedMessage
```

**输出格式**（results 非空时）：

```text
{用户原始消息原样保留在最前}

---
[系统检索上下文 / 用户不可见]

当前知识库：
- 名称: {kb.name}
- 路径: {kb.path}

系统已从当前知识库检索到以下页面（按相关度排序）：

[1] {results[0].title}
    路径: {results[0].path}
    {results[0].snippet}

[2] ...

回答约束：
- 必须基于以上页面内容回答；不得编造未在页面中出现的事实
- 如果以上页面不足以回答，明确说明"当前知识库未找到相关内容"，禁止反问用户提供文章
- 回答末尾必须列出"参考页面"，格式为 `- 《标题》：路径`
- 参考页面只能从上述检索结果中选取，禁止编造路径
```

**results 为空时**：仍包装一段简短上下文：

```text
{用户原始消息}

---
[系统检索上下文]

当前知识库：{kb.name}
系统已尝试检索，但未在当前知识库找到与该问题相关的页面。
请明确告诉用户"当前知识库未找到相关内容"，禁止反问用户提供文章，也禁止编造来源。
```

**关键**：空结果也包装，因为弱模型一旦完全没拿到上下文就会回到"反问要文章"的失败模式。强制告诉它"找过了，没有"。

### 5.5 主对话 `/api/prompt` 改造

[index.ts:745-832](../server/src/index.ts) 当前逻辑：

```text
session.prompt(message)
```

改造后：

```text
1. 解析: explicitRefs = parseExplicitPageRefs(message)
2. 判断: shouldUse = shouldUseKnowledgeBase(message, kbSelected)
3. 若 !shouldUse → 直接 session.prompt(message)（与今日行为一致）
4. 若 shouldUse:
   a. 算 totalBudgetChars = floor(activeModel.contextWindow * 0.2) || 4000
   b. SSE 推送 knowledge_search_start
   c. try {
        results = searchKnowledgeBase(kbPath, message, { explicitRefs, totalBudgetChars })
        wrapped = buildKnowledgeContextPrompt(message, kb, results)
        SSE 推送 knowledge_search_done { count: results.length, paths: results.map(r => r.path) }
        写日志（见 §5.7）
        session.prompt(wrapped)
      } catch (err) {
        SSE 推送 knowledge_search_error { message: err.message }
        写日志
        session.prompt(message)   // 静默降级
      }
```

**每轮 user turn 独立判断 + 检索**。不缓存判断结果。

### 5.6 失败降级

任何一环抛异常（IO 失败、parseExplicitPageRefs throw、buildKnowledgeContextPrompt 字符数爆掉）：

- 不中断 prompt
- 降级为裸 `session.prompt(message)`
- SSE 推 `knowledge_search_error` 事件，前端在状态栏轻量显示"知识库检索失败，已按普通对话处理"
- 日志（见 §5.7）写完整 error stack

### 5.7 检索日志

写入 `~/.llm-wiki-agent/logs/retrieval/<YYYY-MM-DD>.jsonl`，每行：

```json
{
  "ts": 1735000000000,
  "sessionId": "abc12345",
  "kbPath": "~/my-kb",
  "messagePreview": "这是我自媒体创作的文章...",
  "triggered": true,
  "explicitRefs": [],
  "results": [{"path": "wiki/synthesis/sessions/x.md", "hitReason": "recent_synthesis", "score": 3.2}],
  "wrappedCharCount": 4823,
  "error": null
}
```

**作用**：验收脚本、用户反馈复现、长期效果分析都依赖这份日志。

### 5.8 新工具 `query_knowledge_base`

在 [extensions/knowledge-base.ts](../server/src/extensions/knowledge-base.ts) 注册第三个工具：

```text
pi.registerTool({
  name: 'query_knowledge_base',
  parameters: { query: string },
  execute: ({ query }) => {
    results = searchKnowledgeBase(currentKbPath, query, { explicitRefs: [], totalBudgetChars: 4000 })
    return formatted text for agent
  }
})
```

**作用**：让强模型在主对话流中也能继续追问 KB；未来若改为"工具优先 + 注入降级"也只是改 `/api/prompt` 的判断条件，retrieval 函数不动。

工具描述要点："Search the user's current knowledge base for pages relevant to a query. Use this when the user asks a follow-up question that may require pulling additional context from the knowledge base beyond what's already in the conversation."

### 5.9 前端反馈

复用现有 tool 状态显示样式。新增三个 SSE 事件渲染：

- `knowledge_search_start` → 显示"正在检索当前知识库…"
- `knowledge_search_done { count, paths }` → 显示"已检索到 N 个相关页面"
- `knowledge_search_empty`（count=0 时）→ 显示"当前知识库未找到相关内容"
- `knowledge_search_error` → 显示"知识库检索失败，已按普通对话处理"

不新增大面板。

## 6. API 与模块边界

### 6.1 新增文件

- `server/src/retrieval.ts`：导出 `searchKnowledgeBase` / `parseExplicitPageRefs` / `shouldUseKnowledgeBase` / `buildKnowledgeContextPrompt`
- 单测 `server/src/retrieval.test.ts`：触发策略、`[[...]]` 解析、空 KB、cache 隔离、budget 控制

### 6.2 复用与改动

- **复用** [pages.ts](../server/src/pages.ts) 的 `getCachedPages` —— retrieval 在其上加片段提取与扩展 score
- **改动** [index.ts](../server/src/index.ts) 的 `/api/prompt`：按 §5.5 改造，新增 SSE 事件类型
- **改动** [extensions/knowledge-base.ts](../server/src/extensions/knowledge-base.ts)：新增 `query_knowledge_base` 工具
- **不动**：digest/ 目录全部（子代理批量消化不受影响）

### 6.3 不新增对外 HTTP API

第一版只在 `/api/prompt` 内部使用。

## 7. 验收标准

### 7.1 客观可查标志（**所有验收的硬底线**）

每条主对话验收必须同时满足：

1. **日志可查**：`~/.llm-wiki-agent/logs/retrieval/*.jsonl` 中存在对应记录，`triggered` / `results` / `wrappedCharCount` 字段符合预期
2. **字符串命中**：模型回答中至少出现一次检索结果的页面标题或独特短语（grep 可验）

无法同时通过这两条的验收一律不算过。

### 7.2 检索函数 `searchKnowledgeBase`

1. 对"总结这些文章"类问题，能命中 `wiki/synthesis/sessions/` 下最新页面
2. 对具体关键词（如 `OpenClaw`），能命中标题或正文相关页面
3. 返回结果含 path / title / snippet / mtime / hitReason / score
4. 默认 maxPages=6，可配置
5. 单页 snippet 不超过 snippetMaxChars
6. 总字符数不超过 totalBudgetChars
7. explicitRefs 即使超 budget 也强保留（可截断片段）
8. 空 KB 返回 `[]`，不抛错
9. 同一 query 在 cache 未失效时多次调用，结果一致
10. 批量消化新文件后，调用 pages.ts cache 失效路径，下一次检索能拿到新页

### 7.3 `parseExplicitPageRefs`

1. `这是什么 [[wiki/synthesis/sessions/x.md]]` → `['wiki/synthesis/sessions/x.md']`
2. `[[wiki/a.md]] 和 [[wiki/b.md]]` → `['wiki/a.md', 'wiki/b.md']`
3. `[[wiki/a.md]] [[wiki/a.md]]` → `['wiki/a.md']`（去重）
4. `普通文本无引用` → `[]`
5. `[[notwiki.md]]` → `[]`（必须以 wiki/ 开头）

### 7.4 `shouldUseKnowledgeBase`（黑名单）

1. 未选 KB → false
2. `/sediment` / `/pdf` → false
3. `你好` / `谢谢` / `ok` → false
4. `当前模型是什么` → false
5. `[[wiki/x.md]] 说了啥` → true（含显式引用，短路）
6. `总结一下` → true
7. `这是我自媒体创作的文章，总结一下` → true（本 bug 的原始 case）
8. `OpenClaw 相关页面讲了什么` → true
9. 长度 < 3 → false（如 `嗯`）

### 7.5 `/api/prompt` 端到端

1. 触发路径：SSE 顺序为 `knowledge_search_start → knowledge_search_done → text_delta* → done`
2. 不触发路径：SSE 不出现任何 knowledge_search_* 事件
3. 触发但检索抛错：SSE 出现 `knowledge_search_error`，但 `text_delta` 仍正常流出（裸 prompt 降级）
4. 注入字符数符合模型 contextWindow * 20% 上限
5. 模型回答末尾出现"参考页面"列表，所有路径都在 `results.paths` 中（禁止幻觉路径）
6. 多轮：第 1 轮触发后第 2 轮再问新话题，第 2 轮独立判断 + 独立检索

### 7.6 `@` 显式引用

1. `@A` 选中后输入框变成 `[[wiki/.../A.md]]`，发送后 A 在 results 首位（hitReason='explicit'）
2. `[[wiki/.../A.md]] [[wiki/.../B.md]] 对比` → results 前两个是 A 和 B
3. `[[wiki/.../A.md]] 再结合全库看看` → results[0]=A，后续是自动检索补充
4. `[[wiki/不存在.md]] 说了啥` → results 中无该路径，buildKnowledgeContextPrompt 在末尾加一行"用户引用了 wiki/不存在.md，但该页面不存在"

### 7.7 切库隔离

1. A 库批量消化后，问"总结" → results 全部属于 A 库
2. 切到 B 库（B 库为空）→ 问"总结" → results 为空 / 模型说"未找到"
3. 切回 A 库 → 问"总结" → 仍能命中 A 库的页面

### 7.8 失败降级

1. mock fs read 失败 → SSE 推 error 事件、回答仍能流式输出、日志写 error stack
2. 注入字符数超 contextWindow → 自动截断到 budget 内，不抛错
3. shouldUseKnowledgeBase 抛错（不应发生，但兜底）→ 走裸 prompt

## 8. 端到端验收剧本

### 场景 1：批量消化后总结（本 bug 原始 case）

1. 选择普通目录 → 初始化为 KB → 批量消化 7 篇文章
2. 进入该 KB
3. 问："这是我自媒体创作的文章，总结一下。"

**必须结果**：
- 不反问用户要文章
- 回答覆盖多篇文章主题
- 末尾"参考页面"列出 ≥ 3 篇 sessions/ 下的页面
- 日志 jsonl 中 `triggered=true`、`results.length ≥ 3`
- 模型回答中 grep 到至少 1 个 results.paths 中页面的标题

### 场景 2：具体主题检索

1. 同一库问："OpenClaw 相关的文章讲了什么？"

**必须结果**：
- results 中至少 1 篇含 `OpenClaw`
- 回答基于这些页面，无幻觉

### 场景 3：切库隔离

1. 切到另一个 KB（已知不含相关内容）
2. 问："这些文章总结一下。"

**必须结果**：
- results 为空 or 全部属于新 KB
- 模型明确说"当前知识库未找到相关内容"
- 不出现上一 KB 的页面路径

### 场景 4：`@` 显式引用

1. 输入 `@某篇文章 总结它的传播亮点`（前端会替换为 `[[wiki/.../某篇.md]] 总结它的传播亮点`）

**必须结果**：
- results[0] 是该指定页面
- 自动检索补充 ≤ 3 篇
- 回答主要基于指定页面

### 场景 5：普通聊天不检索

1. 问："你好。"
2. 问："当前模型是什么？"
3. 输入 `/sediment`

**必须结果**：
- 三次都不触发 knowledge_search_* 事件
- 日志 jsonl 中 `triggered=false`

### 场景 6：多轮切话题

1. 第 1 轮："总结一下这批文章"
2. 第 2 轮（在同一对话）："其中讲 AI 的那篇具体说了什么？"

**必须结果**：
- 两轮独立检索，各自有日志记录
- 第 2 轮 results 与第 1 轮不必相同（query 变了）

### 场景 7：失败降级

1. 用 `chmod 000` 临时让 KB 某文件不可读
2. 问："总结一下"

**必须结果**：
- SSE 出现 `knowledge_search_error`
- 但 `text_delta` 仍正常输出
- 日志 jsonl 中 `error` 字段非空
- 前端状态栏短暂显示"知识库检索失败，已按普通对话处理"

## 9. 实施顺序（codex 起手必读）

| 步骤 | 任务 | 验收 |
|---|---|---|
| 1 | 新建 `server/src/retrieval.ts` + 单测；实现 `parseExplicitPageRefs` / `shouldUseKnowledgeBase` | §7.3 §7.4 全过 |
| 2 | 在 retrieval.ts 实现 `searchKnowledgeBase`（复用 pages.ts `getCachedPages`） | §7.2 全过 |
| 3 | 实现 `buildKnowledgeContextPrompt` + 日志写入 | 单测覆盖空 results / 含 explicit / 含 error 三种形态 |
| 4 | 改造 [index.ts](../server/src/index.ts) `/api/prompt`：增加判断 + 调用 + SSE 新事件 + 失败降级 | §7.5 §7.8 全过 |
| 5 | 在 [extensions/knowledge-base.ts](../server/src/extensions/knowledge-base.ts) 注册 `query_knowledge_base` 工具 | 单测：工具签名正确、execute 返回格式符合 §5.8 |
| 6 | 前端新增 3 个 SSE 事件渲染（knowledge_search_start/done/error） | 手动验：剧本 1 能看到检索状态 |
| 7 | 跑完 §8 全部 7 个端到端剧本 | 所有剧本通过 §7.1 双重客观标志 |

每步动手前先在对话里说"准备改 X，影响 Y"，作者确认后再动。

## 10. 风险与边界

### 10.1 模型不读注入内容

弱模型（glm 等）可能拿到注入仍反问。
- 缓解：§5.4 wrappedMessage 末尾加强约束句（"如未基于以下页面回答而再次反问用户提供文章，视为错误"）
- 监控：日志可统计"注入了但模型反问"的发生率

### 10.2 cache 失效窗口

批量消化刚跑完、pages.ts cache 还指向旧 fingerprint。
- 缓解：pages.ts 已用 mtime+size fingerprint，每次 retrieval 都会触发重新扫描
- 验收：场景 1 必须在批量消化结束后立即问（不等手动刷新）

### 10.3 切库 cache 串库

pages.ts cache 按 kbPath 隔离，retrieval 复用，不会串库。
- 验收：场景 3 必须通过

### 10.4 检索误触发

黑名单策略激进。
- 缓解：寒暄白名单 + 元问询白名单 + `/` 命令短路 + 长度 < 3 短路
- 监控：日志可统计触发率，过高时回头收紧

### 10.5 来源不真实

模型可能编造路径作为来源。
- 缓解：§5.4 prompt 中强约束"参考页面只能从上述检索结果中选取"
- 验收：§7.5.5 grep 检验回答中所有路径都在 results.paths 中

### 10.6 与 `@` 心智冲突

用户老心智："想引用必须 @"。新行为："不 @ 系统也可能引用"。
- 缓解：§5.9 前端轻量状态显示让用户知道何时检索了
- 长期：如果用户反馈混乱，提供"关闭自动检索"开关（本轮不做）

### 10.7 中文路径 / emoji

PRODUCT.md §6.6 UTF-8 铁律。
- retrieval 所有字符串处理用 raw UTF-8，不 normalize
- cache key 用原始 absolute path

### 10.8 多轮成本

每轮都检索 = 每轮多 100-300ms IO。
- 本地 grep + cache 命中下可接受
- 监控：日志记 retrieval 耗时，> 1s 时考虑优化

## 11. 本轮不做

- 不引入向量数据库
- 不引入新 npm 包
- 不做复杂搜索 UI
- 不把整个知识库塞进每次 prompt
- 不把批量消化结果写进聊天历史
- 不改变 `@` / `/` / 子代理批量消化的现有心智
- 不动 digest/ 目录任何代码
- 不做"关闭自动检索"开关（等用户反馈再说）

## 12. ADR 影响

本设计**正面破例** [PRODUCT.md ADR-7](../PRODUCT.md)（"知识库上下文用 Extension 注入，不拼 prompt"）。需要在 PRODUCT.md 第 7 节追加：

### ADR-19：主对话引入"系统检索 + 上下文注入"

**背景**：ADR-7 设计的"靠 Extension 工具让 agent 自觉调用"在阶段 3.5 批量消化后的真实场景下不稳——弱模型不调 `list_knowledge_base_pages` / `read`，直接反问用户提供文章。

**决策**：

1. 主对话 `/api/prompt` 路径破例采用"后端检索 + 拼隐藏上下文"模式
2. ADR-7 的"应用状态用 Extension 注入"原则在 `currentKnowledgeBase` 等状态查询上仍然成立，本破例只针对"问答类知识库检索"
3. 同一份 `searchKnowledgeBase` 同时暴露为新工具 `query_knowledge_base`，保留 ADR-7 路径供未来强模型使用
4. 子代理批量消化（digest/ 目录）不受影响，继续走裸 prompt + only read tool
5. 主对话流式输出过程中，每个 user turn 独立判断 + 独立检索，不跨轮缓存
6. 失败降级为裸 prompt，SSE 推 error 事件 + 写日志，绝不中断对话

**与既有 ADR 的关系**：

- 破例 **ADR-7**：仅限主对话问答检索，状态查询工具保留
- 兼容 **ADR-3**（SSE）：新增 3 个轻量事件类型
- 兼容 **ADR-16**（Skill 优先 / agent 元能力用 Extension）：检索是 agent 工作台元能力，落 server/ 端合理
- 兼容 **ADR-18**（子代理路径）：不影响 digest/ 目录

**何时重新评估**：

- 主流模型工具调用稳定性显著提升 → 考虑改回纯工具路径
- 用户大量反馈"参考页面被编造" → 强化 prompt 约束 + 引入后置校验
- KB 规模 > 100 篇时检索耗时不可接受 → 引入向量检索

## 13. 完成情况

本设计已在阶段 3.5 收尾中落地。

- `/api/prompt` 已接入当前知识库自动检索；每轮用户消息独立判断，触发时推送 `knowledge_search_start` / `knowledge_search_done` / `knowledge_search_empty` / `knowledge_search_error`
- `query_knowledge_base` 工具已注册，和主对话预检索共用同一套检索函数
- 检索结果复用 `pages.ts` 的缓存与扫描路径，覆盖 `wiki/synthesis/sessions/`、`purpose.md`、`index.md`、`wiki/overview.md`
- `[[wiki/...]]` 显式引用会优先进入结果；缺失页面会进入包装提示，不静默吞掉
- 检索日志写入 `~/.llm-wiki-agent/logs/retrieval/<YYYY-MM-DD>.jsonl`
- 普通寒暄、`/` 命令、模型/设置类问题、导出产物指令不会触发知识库检索

**验收实况**：

- `node --import tsx --test server/src/retrieval.test.ts server/src/digest/concurrency.test.ts` 通过
- `npm run --silent typecheck` 通过
- 真实接口验证通过：`这是我自媒体创作的文章，总结一下` 触发检索并返回参考页面；`你好` 不触发检索；导出 PDF 指令不触发检索