文件搜索功能异常时，需依次检查ripgrep是否安装、搜索根目录是否配置、索引是否预热、.gitignore排除机制是否启用，以及权限、编码、别名等常见问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用 Hermes Agent 时发现文件搜索功能无法响应或返回空结果，则可能是由于 ripgrep 工具未正确安装，或本地索引目录未初始化。以下是配置 ripgrep 并构建可搜索索引的具体步骤：
一、验证并安装 ripgrep 工具
ripgrep（rg）是 Hermes Agent 执行快速全文搜索的核心依赖，它比传统 grep 更快且默认支持递归、忽略 .gitignore 规则。Hermes 的一键安装脚本通常已自动部署 ripgrep，但部分系统（如某些 Windows PowerShell 环境或自定义 Shell）可能未成功写入 PATH。
1、打开终端（macOS/Linux/WSL2）或 PowerShell（Windows），执行以下命令检测是否可用：
rg --version
2、若提示 command not found 或 未识别的命令，需手动安装：
3、macOS 用户执行：
brew install ripgrep
4、Ubuntu/Debian 系统执行：
sudo apt update && sudo apt install ripgrep
5、Windows 用户（PowerShell）执行：
choco install ripgrep
6、安装完成后，再次运行 rg --version，确认输出版本号（如 14.1.0）且无报错。
二、配置 Hermes Agent 的搜索根目录
Hermes Agent 默认仅对项目工作区（~/.hermes/workspace）及用户主目录下的特定子目录进行索引。您需显式声明希望被纳入搜索范围的路径，否则 rg 将无法定位目标文件。
1、运行配置命令启动搜索路径管理：
hermes tools
2、在交互菜单中选择 File Search 选项
3、按提示输入要添加的根路径，例如：
/Users/yourname/Documents
4、确认后，Hermes 将把该路径写入 ~/.hermes/config.yaml 中的 search.roots 字段
5、如需批量添加，可直接编辑 config.yaml 文件，在 search.roots 下以 YAML 列表格式追加路径条目。
三、手动触发索引预热与缓存构建
ripgrep 本身不维护持久化索引，但 Hermes Agent 通过 fzf + rg 组合实现类“索引”体验——首次搜索会触发全量扫描并缓存结果结构。为避免每次搜索都重复遍历，建议主动执行一次预热扫描。
1、执行以下命令启动一次全路径扫描：
hermes search --all
2、等待终端输出完成提示（如 Indexed 12,487 files）
3、此时 ~/.hermes/cache/search/ 目录下将生成 timestamped 缓存文件
4、后续调用 hermes search keyword 时，Hermes 会优先读取缓存元数据，再对变更文件增量扫描
5、如需强制刷新全部缓存，删除 ~/.hermes/cache/search/ 下所有文件后重跑 hermes search --all
四、启用 .gitignore 自动排除机制
为避免搜索结果混杂构建产物、日志或临时文件，Hermes Agent 默认启用 ripgrep 的 --no-ignore-vcs 行为。但若您的项目使用标准 .gitignore，应显式开启 VCS 排除以提升结果精准度。
1、编辑 ~/.hermes/config.yaml 文件
2、在 search 节点下添加或修改字段：
ignore_vcs: true
3、保存后重启 Hermes Agent 进程（Ctrl+C 停止当前会话，再执行 hermes）
4、验证是否生效：在含 .gitignore 的代码目录中执行 hermes search __pycache__，应无任何结果返回
5、若仍出现匹配，请检查 .gitignore 是否包含通配符语法错误，或是否存在父级目录的 .gitignore 覆盖了当前设置
五、排查常见搜索失败场景
即使 ripgrep 已安装且路径已配置，仍可能出现“无结果”现象。以下为高频原因及对应操作：
1、当前用户对目标目录无读取权限：
执行 ls -l /path/to/search，确认输出中包含 r 权限；若缺失，运行 chmod +r /path/to/search 或改用 sudo hermes search（不推荐长期使用）
2、目标路径含中文或特殊字符导致 rg 解码异常：
在终端中先切换至该路径，执行 rg -i "test" .，观察是否报错；若提示 invalid utf-8 sequence，需在 config.yaml 中添加 search.encoding: utf-8
3、Hermes 搜索命令被别名覆盖：
运行 type hermes，确认指向 ~/.hermes/bin/hermes；若指向 shell 别名或旧版本脚本，执行 unalias hermes 后重试
4、rg 版本过低（升级 rg 至最新稳定版，macOS 执行 brew upgrade ripgrep，Linux 执行 curl -LO https://github.com/BurntSushi/ripgrep/releases/download/14.1.0/ripgrep_14.1.0_amd64.deb && sudo dpkg -i rippgrep_14.1.0_amd64.deb
