用 frontmatter 元数据过滤精确查找笔记（状态…

当需要按笔记的自定义 YAML frontmatter 字段（如 status、priority、confidence、tags）而非全文内容来检索笔记时使用。

适用场景

解决思路

1. 使用 `search_notes` 工具进行所有元数据搜索，通过 `metadata_filters` 传入过滤条件，或使用 `tags`、`status` 便捷参数；仅做过滤搜索时省略 `query`（或传 `None`）。
2. 等值匹配：`{"status": "active"}`。
3. 数组包含（列出的所有值都必须存在）：`{"tags": ["security", "oauth"]}`。
4. `$in`（匹配列表中任意一个值）：`{"priority": {"$in": ["high", "critical"]}}`。
5. 比较运算 `$gt`、`$gte`、`$lt`、`$lte`：`{"confidence": {"$gt": 0.7}}`；数值按数值比较，字符串按字典序比较。
6. `$between`（闭区间）：`{"score": {"$between": [0.3, 0.8]}}`。
7. 空值匹配：`{"owner": null}` 匹配没有 `owner` 键或 `owner` 显式为 null 的笔记；null 只能作为普通等值使用，放在 `$in`、`$between`、数组包含列表或比较运算中会被拒绝。
8. 嵌套访问用点号：`{"schema.version": "2"}`。
9. 多个键之间用 AND 逻辑组合，例如 `{"status": "active", "priority": "high"}` 要求两个条件都满足。
10. 键必须匹配 `[A-Za-z0-9_-]+`（点号分隔嵌套层级）；操作符字典必须恰好包含一个操作符；`$in` 和数组包含要求非空列表；`$between` 必须恰好是 `[min, max]`。
11. 比较和 `$between` 的边界必须是有限数值——超出浮点数可表示范围的量级（如 400 位整数）会被拒绝，而不是与无穷边界比较。
12. 操作符必须带 `$` 前缀：写 `$gte` 而不是 `gte`；缺少前缀会被当作精确匹配键并静默返回空结果。
13. 元数据过滤只匹配 Markdown 笔记——索引的 PDF、图片和其他普通文件没有 frontmatter，永远不会命中，即使是 `null` 查询也不会。
14. `tags` 和 `status` 是通过 `setdefault` 合并进 `metadata_filters` 的便捷参数；如果 `metadata_filters` 中已存在同名键，显式过滤条件优先。
15. 查询中的 `tag:` 前缀会自动转换为标签过滤：`search_notes("tag:tier1")` 等价于 `search_notes("", tags=["tier1"])`；多个标签用逗号或空格分隔，必须全部匹配，如 `search_notes("tag:tier1,alpha")`。
16. 可以组合文本搜索与元数据过滤：`search_notes("authentication", metadata_filters={"status": "draft"})`，或混合文本、标签快捷方式和高级过滤：`search_notes("oauth flow", tags=["security"], metadata_filters={"confidence": {"$gt": 0.7}})`。
17. 按已知字段值（status、priority、type）查找时优先用元数据过滤，比文本搜索更精确；查找关于某主题的笔记时用文本搜索，需要精确时两者结合。
18. 任何自定义 YAML 键都会自动可查询，无需 schema 或配置；嵌套 YAML 结构用点号访问。
19. `tags` 和 `status` 只是常见字段的语法糖，其他字段请直接使用 `metadata_filters`。

适用边界 · 注意事项

• 笔记是 PDF、图片或其他非 Markdown 普通文件时——它们没有 frontmatter，元数据过滤永远不会命中。
• 需要按内容主题查找笔记时——应使用文本搜索，元数据过滤只适合按已知字段值精确筛选。
• 在 `$in`、`$between`、数组包含或比较运算中使用 null 时——这些场景会拒绝 null，只能用普通等值形式 `{"field": null}`。