Classic IR

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install classic-ir
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 classic-ir。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Classic IR 是一款轻量级本地信息检索引擎，可在无需网络访问、外部服务或机密凭据的情况下，为 Markdown 和文本文件建立索引并进行搜索。它使用 SQLite FTS5，为代码、笔记和文档语料库中的精确匹配与词法搜索提供可靠的 BM25 排名。
作为 Openclaw Skills 的一部分，它可以在成本高昂的密集嵌入或 LLM 重排之前，充当可靠的检索基础。可选的 RM3 风格伪相关性扩展会从顶部结果中生成候选词，而倒数排名融合则通过简单的 JSON 工作流合并多个已排名的结果集。

应用场景

以低延迟搜索本地代码库、Markdown 笔记、文档和文本语料库。
在密集搜索或 LLM 重排之前，运行经济高效的初步检索阶段。
查找语义搜索可能遗漏的精确标识符、术语、文件名和技术短语。
使用排名最高结果中的 RM3 候选词扩展简短或描述不充分的查询。
使用倒数排名融合 (RRF) 合并两个检索系统的排名。
在 breakthrough-finder 或其他多阶段研究工作流中衡量并提升检索召回率。
通过仅使用标准库的离线搜索流程，保护敏感语料库的隐私。

工作原理

对目录运行 index，以发现 .md 和 .txt 文件，并将其编入本地 SQLite FTS5 数据库。
使用 search 提交查询，以 JSON 格式检索按 BM25 排名的结果，并可选设置 top-k 限制。
将 BM25 用作必需的初步检索方法，因为它成本低廉、无需训练数据也很可靠，并且擅长精确词法匹配。
可选运行 expand，从 top-k 文档中提取 RM3 风格的候选词；由于可能发生查询漂移，应将扩展作为可选功能使用。
记录扩展词及其在 top-k 文档中的出现频率，以便检查和衡量检索行为。
如果有第二组排名结果，运行 fuse，使用倒数排名融合合并两个 JSON 排名结果。
仅将排名最高的结果（通常为前 100 条）传递给密集检索或 LLM 重排；切勿对整个语料库重新排名。

配置指南

确保可使用 Python 3.8 或更高版本，并支持 SQLite FTS5。此技能需要 python3 可执行文件，且仅使用 Python 标准库。
将 ir.py 放在工作目录中，或从安装此技能的位置调用它。
为包含 Markdown 或文本文件的目录建立索引：
python ir.py index ./notes --db notes.db
运行 BM25 搜索，并可选控制返回结果数量：
python ir.py search notes.db "BM25 saturation" --k 100
从排名最高的文档中生成可选的 RM3 扩展候选词：
python ir.py expand notes.db "BM25" --k 5
使用 RRF 融合两个排名 JSON 文件：
python ir.py fuse A.json B.json --k 60
无需安装软件包、连接网络、API 密钥或机密配置。该引擎仅进行词法检索，因此需要语义相似度时，请使用下游密集检索或基于 LLM 的处理阶段。

数据架构

已索引语料库
源文件： 在传递给 index 的目录下发现的 .md 和 .txt 文件。
存储： 本地 SQLite 数据库，例如 corpus.db 或 notes.db。
搜索索引： SQLite FTS5，通过 BM25 排名进行查询。
隐私模型： 数据保留在本地；此技能不需要网络访问。
输出记录
操作 输出字段 用途
search path, rank 标识匹配的源文件及其 BM25 结果位置。
expand term, df_topk 报告候选 RM3 词及其在 top-k 结果中的出现频率。
fuse 合并后的排名 JSON 结果 根据两个输入结果列表生成 RRF 排名。
此工作流将文件路径视为源元数据，将排名视为检索顺序元数据，并将扩展词视为查询改写元数据。密集检索或重排结果可通过此技能兼容 dense-slot 的检索工作流进行处理，但文档中介绍的命令仍是本地 BM25 搜索、RM3 扩展和 JSON 排名融合。

高级特性

由 SQLite FTS5 提供支持的 BM25 检索，无外部依赖。
使用倒数排名融合合并独立的排名输出。
提供可选查询扩展的 RM3 风格伪相关性反馈。
可配置搜索、扩展和融合操作的 top-k 限制。
兼容 dense-slot 的架构，可将词法检索连接到后续语义或 LLM 重排阶段。
通过将成本高昂的重排限制在前 100 条结果内来控制检索成本。
面向召回率的工作流，适用于多阶段研究和 breakthrough-finder 流程。
使用 Python 3.8+ 和标准库完全在本地运行，无需网络或机密信息。

name: classic-ir description: Local BM25 code and text search + hybrid retrieval engine (SQLite FTS5 + RRF fusion). Use when finding code, searching notes/corpora, or first-pass retrieval before dense/rerank spend. Covers recall measurement and RM3-style expansion. Feeds breakthrough-finder stages retrieve/expand. version: 1.0.0