modbender Doc Search 文档检索
轻量级本地文档检索，无需向量数据库。
核心能力
- 多策略搜索 - 文件名 > 标题/frontmatter > 正文内容，按相关性排序
- 增量索引 - 基于文件修改时间，只更新变化的文件
- 上下文返回 - 返回匹配行及前后 N 行
- TF-IDF 排序 - 可选的轻量相关性排序
快速使用
直接搜索（无需索引）
# 简单关键词搜索
python scripts/search.py "关键词" /path/to/docs
# 带上下文
python scripts/search.py "关键词" /path/to/docs --context 3
# 限制文件类型
python scripts/search.py "关键词" /path/to/docs --types md,txt
使用索引（大型项目推荐）
# 构建索引
python scripts/indexer.py /path/to/docs --output index.json
# 基于索引搜索（更快）
python scripts/search.py "关键词" --index index.json
搜索策略
搜索按以下优先级返回结果：
| 优先级 | 匹配类型 | 权重 |
|---|---|---|
| 1 | 文件名完全匹配 | 100 |
| 2 | 文件名包含 | 80 |
| 3 | 标题/H1 匹配 | 70 |
| 4 | Frontmatter 匹配 | 60 |
| 5 | 正文内容匹配 | 40 |
多次匹配会累加权重。
输出格式
{
"query": "搜索词",
"total": 5,
"results": [
{
"file": "docs/guide.md",
"score": 150,
"matches": [
{
"type": "title",
"line": 1,
"content": "# 用户指南",
"context": ["---", "title: 用户指南", "---"]
},
{
"type": "content",
"line": 42,
"content": "这是关于搜索词的说明",
"context": ["上一行", "这是关于搜索词的说明", "下一行"]
}
]
}
]
}
配置文件（可选）
在项目根目录创建 .docsearch.yaml：
# 要索引的目录
include:
- docs/
- README.md
- src/**/*.md
# 排除的模式
exclude:
- node_modules/
- "*.min.js"
- .git/
# 文件类型
types:
- md
- txt
- py
- js
# 索引选项
index:
max_file_size: 1mb
extract_frontmatter: true
extract_headings: true
高级用法
组合 Bash 工具
当不需要索引时，直接用 ripgrep：
# 快速搜索
rg "关键词" --type md -C 2 --json
# 搜索标题
rg "^#.*关键词" --type md
# 搜索 frontmatter
rg -U "^---[\s\S]*?关键词[\s\S]*?^---" --type md
Python API
from scripts.search import DocSearch
searcher = DocSearch("/path/to/docs")
results = searcher.search("关键词", context_lines=2)
for r in results:
print(f"{r['file']} (score: {r['score']})")
for m in r['matches']:
print(f" L{m['line']}: {m['content']}")
适用场景
- 项目文档快速定位
- 代码库中查找注释/文档
- 笔记系统内容检索
- 配置文件搜索
限制
- 不支持语义搜索（需要向量数据库）
- 中文分词依赖简单切分
- 大文件（>1MB）建议跳过