Markdown 文档全文搜索

基于 SQLite FTS5 实现的快速、已建立索引的 Markdown 文档归档全文搜索，采用 BM25 相关性排序。

适用场景

• 在文档归档中搜索特定功能、能力或信息
• 查找可用于报告引用的官方源 URL
• 查阅技术规格或配置细节
• 跨多个文档源开展研究

预期文档格式

文章以 --- 分隔符分隔，并包含带 *Source: 的 URL：

# 文章标题

*Source: https://docs.example.com/path/to/article.html*

文章内容在此...

---

# 下一篇文章标题

*Source: https://docs.example.com/another/article.html*

更多内容...

快速上手

# 1. 索引文档（一次性操作，或在文档更新后执行）
scripts/docs.py index ./docs

# 2. 搜索
scripts/docs.py search "kubernetes backup" --max 5

# 3. 查看索引状态
scripts/docs.py status

核心工具：docs.py

统一的命令行接口支持全部操作：

索引构建

# 对文档目录建立索引
scripts/docs.py index ./docs

# 强制完全重建索引
scripts/docs.py index ./docs --rebuild

# 自定义数据库路径
scripts/docs.py index ./docs --db /path/to/custom.db

搜索

# 基础搜索
scripts/docs.py search "kubernetes backup"

# 布尔运算符
scripts/docs.py search "AWS AND S3 AND snapshot"

# 短语搜索
scripts/docs.py search '"exact phrase match"'

# 前缀搜索
scripts/docs.py search "kube*"

# 排除关键词
scripts/docs.py search "backup NOT restore"

# 仅在标题中搜索
scripts/docs.py search "kubernetes" --title-only

# 输出格式
scripts/docs.py search "kubernetes" --format json
scripts/docs.py search "kubernetes" --format markdown

# 在匹配结果周围提供更多上下文
scripts/docs.py search "kubernetes" --context 400

# 在 JSON 输出中包含完整正文内容
scripts/docs.py search "kubernetes" --format json --full-content

FTS5 查询语法

获取特定文章

# 根据部分 URL 或标题获取文章
scripts/docs.py get "system_requirements" --full

# 查找所有匹配的文章
scripts/docs.py get "backup" --all

状态查询

# 查看索引统计信息
scripts/docs.py status

研究任务工作流

发现阶段

# 查看当前已索引内容
scripts/docs.py status

# 使用宽泛关键词探索主题
scripts/docs.py search "" --max 20

研究阶段

# 使用布尔运算符缩小范围
scripts/docs.py search " AND "

# 查找具体信息
scripts/docs.py search "limitation OR restriction OR 'not supported'"

引用阶段

每条搜索结果均附带 Source: URL —— 请在报告中直接引用该链接：

根据文档说明，[发现内容]...

Source: https://docs.example.com/path/to/article.html

多源配置

每个 agent 或项目可拥有各自的文档与索引：

~/docs/VendorA/
    ├── docs_part_01.md
    ├── docs.db      # 索引文件与文档共存
    └── ...

~/docs/VendorB/
    ├── docs.md
    ├── docs.db
    └── ...

docs.py 脚本会自动识别数据库位置。

高级脚本

针对特殊需求提供以下脚本：

• scripts/fts_search.py —— 提供更丰富选项的直接 FTS5 搜索
• scripts/index_docs.py —— 独立索引构建脚本
• scripts/list_sources.py —— 列出全部源 URL
• scripts/get_article.py —— 直接获取指定文章
• scripts/search_docs.py —— 基于正则表达式的搜索（无需索引）

研究模式

关于常见搜索模式（如功能调研、架构分析、安全审查等），参见 references/search-patterns.md。

示例会话

# 当前索引情况？
scripts/docs.py status
# 输出：已索引文件数：37，已索引文章数：32065

# 查找相关信息
scripts/docs.py search "kubernetes backup" --max 5

# 进一步限定平台
scripts/docs.py search "kubernetes AND AWS" --max 5

# 查找限制条件
scripts/docs.py search "limitation OR 'not supported'"

# 获取完整文章用于引用
scripts/docs.py get "system_requirements" --full

最佳实践

1. 一次索引，多次搜索 —— FTS5 因已建立索引而具备高速性能
2. 善用布尔运算符 —— 使用 AND、OR、NOT 提升检索精度
3. 短语搜索确保准确性 —— 使用英文双引号包裹 "exact match"
4. 始终注明引用来源 —— 报告中须包含 Source: URL
5. 定期重建索引 —— 文档更新后需重新索引
6. 使用 JSON 格式进行数据分析 —— 可通过管道传给 jq 或其他工具进一步处理