Hermit Search Publish

---

name: hermit-search description: 'Local semantic search over knowledge base collections powered by Hermit. Use when: searching knowledge base, semantic search, querying documents, managing collections, adding knowledge base, indexing files.' version: 1.0.0 metadata: openclaw: requires: bins: - hermit - uv os: - macos homepage: https://github.com/xxxgqcoder/hermit

---

Skill: hermit-search

Hermit 本地语义搜索服务的使用指南。Hermit 提供基于向量的混合检索（Dense + Sparse）和 Cross-Encoder 精排，支持多知识库管理。

平台支持

macOS：已测试通过

Linux：即将支持（短期内增加测试）

前置条件

安装

uv tool install git+https://github.com/xxxgqcoder/hermit.git
部署 Skill 到 ~/.agents/skills/hermit-search/（可选，使 Agent 自动发现）
hermit install-skills

模型下载

首次使用前需下载模型（约 1GB）：

hermit download

使用流程

1. 启动服务

hermit start

输出示例：{"status": "started", "pid": 12345, "port": 8000}

2. 添加知识库

将一个文件夹注册为知识库 collection：

hermit kb add   [--ignore ]... [--ignore-ext ]...

name：collection 别名（字母数字 + 下划线/连字符，以字母或数字开头）

directory：文件夹路径，Hermit 会递归扫描并索引其中的文本文件

--ignore：glob 模式，匹配的相对路径将被忽略（可重复指定多个）

--ignore-ext：文件后缀名，匹配的文件将被忽略（大小写不敏感，可重复指定多个）

示例：

# 基本用法
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. 更新知识库忽略规则

修改已有知识库的忽略配置（替换模式，非追加）：

hermit kb update  [--ignore ]... [--ignore-ext ]... [--clear-ignore] [--clear-ignore-ext]

--ignore：设置新的路径忽略 glob 模式（替换已有配置）

--ignore-ext：设置新的后缀忽略规则（替换已有配置）

--clear-ignore：清除所有路径忽略模式

--clear-ignore-ext：清除所有后缀忽略规则

示例：

# 更新忽略模式
hermit kb update my-project --ignore "dist/**" --ignore "*.log"
清除所有忽略规则
hermit kb update my-project --clear-ignore --clear-ignore-ext

4. 语义搜索

hermit search  ""

参数：

| 参数 | 类型 | 默认值 | 说明 | |---|---|---|---| | collection | str | — | Collection 名称 | | query | str | — | 搜索查询 | | --top-k | int | 5 | 返回结果数 | | --rerank-candidates | int | 50 | 精排候选池大小 |

示例：

hermit search my-notes "如何实现二分查找"

5. 其他管理命令

# 查看所有知识库
hermit kb list
删除知识库
hermit kb remove 
触发同步（需要服务运行中）
hermit collection sync 
查看索引状态
hermit collection status 
查看索引任务队列
hermit collection tasks 

6. 服务生命周期

hermit status    # 查看服务状态
hermit stop      # 停止服务
hermit logs      # 查看日志（流式输出）

输出格式

所有命令输出 JSON。添加 --pretty 获取格式化输出：

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 环境变量覆盖）