# MNote local index

使用场景：需要检索本地工作区资料、引用可回跳证据，或让 agent 帮忙查看、新增、刷新、删除本地索引范围。

证据检索：

- 先用 `mnote.evidence.search` 搜索资料证据，回答时保留返回的 `quote`、`source` 和 `openAction`。
- `mnote.evidence.search` / `mnote.evidence.read` 会返回 `citationUrl`、`citationLabel`、`citationMarkdown`。最终回答引用时优先直接使用 `citationMarkdown`，格式如 `[文件名 · p.3](citationUrl)`；该链接在 MNote Page AI 中点击会在当前页面的资源新 tab 打开，并按 `page` / `bbox` / `blockId` / `sourceMapPath` 跳转或高亮到证据位置。
- 如果用户查询语言与资料语言可能不一致，不要假定目标资料语言，也不要只把整句原文直接丢给 FTS。先保留用户意图，再根据文件名、题名、领域术语和已知上下文生成 2-6 个轻量多语关键词候选；不确定时优先同时尝试原语言关键词和常见英文术语。中文问法查生命科学文献时，例如“分子对接软件”可扩展为 `分子对接`, `molecular docking`, `docking software`, `AutoDock`, `Vina`。
- 关键词扩展只是检索策略，不是结论。回答仍按用户语言组织，且只根据 evidence 结果确认事实。
- 需要更多上下文时，用 `mnote.evidence.read` 按 locator 读回周边证据。
- 需要让 UI 打开定位时，用 `mnote.evidence.open`，不要自行拼接 URL。

索引管理：

- 用 `mnote.index.status` 查看当前 root 的 `settings`、`effectiveSettings`、索引文件是否存在、文档数和证据块数。
- 用 `mnote.index.update_settings` 新增或删除索引范围。`includePaths` 是 root 内相对路径；已保存范围视为固化记录，不直接改目录。要改目录时，删除旧范围并新增新范围。
- `includePaths: []` 表示删除当前用户的索引范围；当没有任何有效范围时，会清空 `.mnote/index/search-index.json` 和 `.mnote/index/evidence.sqlite`。
- 用 `mnote.index.refresh` 重建当前有效范围的索引缓存。刷新只重建索引，不修改 Markdown 正文。

写入约束：

- 调用 `mnote.index.update_settings` 必须显式携带 `dryRun` 和 `idempotencyKey`。
- 在只读或共享只读 AI scope 下，不要调用 `mnote.index.update_settings`。
- `dryRun: true` 只返回计划，不写设置、不重建索引。

回答要求：

- 关键事实必须带可回跳来源，至少包含文档名、资源名或页码、quote 摘要。
- 关键事实后必须给可点击引用链接；如果 `citationMarkdown` 缺失，先调用 `mnote.evidence.open` 取得 `citationUrl`，不要自己拼 `file://`、`.mnote/index` 或 OCR sidecar 路径。
- 不要直接读取 `.mnote/index`、OCR sidecar 或 provider 原始响应来替代 evidence tool。
- 不要把 OCR 文本当成 owner Markdown 正文真相。
- 如果 evidence 结果没有 page、bbox 或 section，只说明定位能力降级，不伪造页码。
