Skill: hermit-search
Hermit 本地语义搜索服务的使用指南。Hermit 提供基于向量的混合检索（Dense + Sparse）和 Cross-Encoder 精排，支持多知识库管理。
平台支持
- - macOS：已测试通过
- Linux：即将支持（短期内增加测试）
前置条件
安装
CODEBLOCK0
模型下载
首次使用前需下载模型（约 1GB）：
CODEBLOCK1
使用流程
1. 启动服务
CODEBLOCK2
输出示例： INLINECODE0
2. 添加知识库
将一个文件夹注册为知识库 collection：
CODEBLOCK3
- -
name：collection 别名（字母数字 + 下划线/连字符，以字母或数字开头） - INLINECODE2 ：文件夹路径，Hermit 会递归扫描并索引其中的文本文件
- INLINECODE3 ：glob 模式，匹配的相对路径将被忽略（可重复指定多个）
- INLINECODE4 ：文件后缀名，匹配的文件将被忽略（大小写不敏感，可重复指定多个）
示例：
CODEBLOCK4
3. 更新知识库忽略规则
修改已有知识库的忽略配置（替换模式，非追加）：
CODEBLOCK5
- -
--ignore：设置新的路径忽略 glob 模式（替换已有配置） - INLINECODE6 ：设置新的后缀忽略规则（替换已有配置）
- INLINECODE7 ：清除所有路径忽略模式
- INLINECODE8 ：清除所有后缀忽略规则
示例：
CODEBLOCK6
4. 语义搜索
CODEBLOCK7
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|
| INLINECODE9 | str | — | Collection 名称 |
| INLINECODE10 |
str | — | 搜索查询 |
|
--top-k | int | 5 | 返回结果数 |
|
--rerank-candidates | int | 50 | 精排候选池大小 |
示例：
CODEBLOCK8
5. 其他管理命令
CODEBLOCK9
6. 服务生命周期
CODEBLOCK10
输出格式
所有命令输出 JSON。添加 --pretty 获取格式化输出：
CODEBLOCK11
错误输出格式： INLINECODE14
忽略规则说明
- - 路径模式（
--ignore）使用 glob 语法（与 .gitignore 类似），匹配相对于知识库根目录的路径
-
*.log — 忽略根目录下所有
.log 文件
-
build/** — 忽略
build/ 目录下所有文件
-
**/temp/* — 忽略任意层级下的
temp/ 目录内容
- - 后缀模式（
--ignore-ext）大小写不敏感：.PDF 和 .pdf 等价 - 隐藏文件（以
. 开头的目录或文件）始终被忽略，无需额外配置 - INLINECODE27 可查看每个知识库当前的忽略配置
技术细节
- - Embedding 模型：jinaai/jina-embeddings-v2-base-zh（768 维）
- Sparse 模型：Qdrant/bm25
- Reranker：jinaai/jina-reranker-v2-base-multilingual
- 向量数据库：Qdrant（嵌入式模式）
- 推理后端：fastembed（ONNX Runtime，纯 CPU）
- 数据目录：
~/.hermit/（可通过 HERMIT_HOME 环境变量覆盖）
技能：hermit-search
Hermit 本地语义搜索服务的使用指南。Hermit 提供基于向量的混合检索（Dense + Sparse）和 Cross-Encoder 精排，支持多知识库管理。
平台支持
- - macOS：已测试通过
- Linux：即将支持（短期内增加测试）
前置条件
安装
sh
uv tool install git+https://github.com/xxxgqcoder/hermit.git
部署 Skill 到 ~/.agents/skills/hermit-search/（可选，使 Agent 自动发现）
hermit install-skills
模型下载
首次使用前需下载模型（约 1GB）：
sh
hermit download
使用流程
1. 启动服务
sh
hermit start
输出示例：{status: started, pid: 12345, port: 8000}
2. 添加知识库
将一个文件夹注册为知识库 collection：
sh
hermit kb add [--ignore ]... [--ignore-ext ]...
- - name：collection 别名（字母数字 + 下划线/连字符，以字母或数字开头）
- directory：文件夹路径，Hermit 会递归扫描并索引其中的文本文件
- --ignore：glob 模式，匹配的相对路径将被忽略（可重复指定多个）
- --ignore-ext：文件后缀名，匹配的文件将被忽略（大小写不敏感，可重复指定多个）
示例：
sh
基本用法
hermit kb add my-notes ~/Documents/notes
忽略特定路径和后缀
hermit kb add my-project ~/code/project \
--ignore build/
\
--ignore *.tmp \
--ignore node_modules/* \
--ignore-ext .pdf \
--ignore-ext .png
3. 更新知识库忽略规则
修改已有知识库的忽略配置（替换模式，非追加）：
sh
hermit kb update [--ignore ]... [--ignore-ext ]... [--clear-ignore] [--clear-ignore-ext]
- - --ignore：设置新的路径忽略 glob 模式（替换已有配置）
- --ignore-ext：设置新的后缀忽略规则（替换已有配置）
- --clear-ignore：清除所有路径忽略模式
- --clear-ignore-ext：清除所有后缀忽略规则
示例：
sh
更新忽略模式
hermit kb update my-project --ignore dist/
--ignore *.log
清除所有忽略规则
hermit kb update my-project --clear-ignore --clear-ignore-ext
4. 语义搜索
sh
hermit search
参数：
| 参数 | 类型 | 默认值 | 说明 |
|---|
| collection | str | — | Collection 名称 |
| query |
str | — | 搜索查询 |
| --top-k | int | 5 | 返回结果数 |
| --rerank-candidates | int | 50 | 精排候选池大小 |
示例：
sh
hermit search my-notes 如何实现二分查找
5. 其他管理命令
sh
查看所有知识库
hermit kb list
删除知识库
hermit kb remove
触发同步（需要服务运行中）
hermit collection sync
查看索引状态
hermit collection status
查看索引任务队列
hermit collection tasks
6. 服务生命周期
sh
hermit status # 查看服务状态
hermit stop # 停止服务
hermit logs # 查看日志（流式输出）
输出格式
所有命令输出 JSON。添加 --pretty 获取格式化输出：
sh
hermit --pretty search my-notes query
错误输出格式：{error: message}
忽略规则说明
- - 路径模式（--ignore）使用 glob 语法（与 .gitignore 类似），匹配相对于知识库根目录的路径
- *.log — 忽略根目录下所有 .log 文件
- build/ — 忽略 build/ 目录下所有文件
- /temp/* — 忽略任意层级下的 temp/ 目录内容
- - 后缀模式（--ignore-ext）大小写不敏感：.PDF 和 .pdf 等价
- 隐藏文件（以 . 开头的目录或文件）始终被忽略，无需额外配置
- hermit kb list 可查看每个知识库当前的忽略配置
技术细节
- - Embedding 模型：jinaai/jina-embeddings-v2-base-zh（768 维）
- Sparse 模型：Qdrant/bm25
- Reranker：jinaai/jina-reranker-v2-base-multilingual
- 向量数据库：Qdrant（嵌入式模式）
- 推理后端：fastembed（ONNX Runtime，纯 CPU）
- 数据目录：~/.hermit/（可通过 HERMIT_HOME 环境变量覆盖）
