PDF文档智能解析：HermesAgent高效读取与知识库构建指南

PDF文档存入本地知识库后，若Hermes Agent无法识别或检索内容，通常指向文档解析失败或索引未生效。此问题有明确的排查路径，按以下步骤操作即可解决。

一、启用并配置ocr-and-documents技能

读取本地PDF文档的核心，在于启用ocr-and-documents技能。该技能专门解析PDF等非纯文本格式，提取其中的结构化文本以供检索。此技能默认未激活，需手动启用。

首先，执行命令 hermes skills list，检查当前已加载的技能列表。若未发现该技能，则运行 hermes skills install ocr-and-documents 进行安装。安装后，务必执行 hermes skills load ocr-and-documents 将其加载至当前会话环境。完成这三步，文档解析的基础能力方准备就绪。

二、检查PDF文件存放路径与命名规范

技能就位后，需确保文件存储位置符合规范。Hermes Agent的检索层仅扫描预设知识库目录下的文件，并对路径与命名有严格要求。

请确认PDF文件已置于 knowledge-base/ 目录或其子目录下（例如 knowledge-base/02_技术/）。存放于其他位置的文件将无法被索引。

文件名应遵循规范，避免使用中文标点、空格或点号开头。建议采用英文与下划线命名，如 api_security_guide_v2.pdf，以最大限度保证兼容性。在Linux或WSL2环境下，可使用命令 ls -l knowledge-base/**/*.pdf 检查文件读取权限是否正常。

三、触发手动索引重建

即使文件与技能均已正确配置，Hermes Agent也不会自动监控文件系统的变更。新存入或更新的PDF文件，必须通过手动命令触发索引重建，才能启动OCR与文本提取流程。

操作流程：进入知识库根目录 cd ~/knowledge-base，随后运行 hermes index --force。--force参数将强制系统重新遍历并处理所有PDF文件。

执行时，请密切关注终端输出日志。若出现类似 [INFO] Extracted 1248 tokens from /02_技术/nginx_tuning.pdf 的信息，则表明文件内容已被成功提取。

四、验证MEMORY.md中是否注入PDF元信息

索引成功不代表流程结束。Hermes Agent会将提取的PDF文档标题、关键摘要及文件路径，写入 MEMORY.md 文件。后续的自然语言检索依赖此文件中的上下文信息建立关联。若此处未更新，检索层依然无法定位你的PDF。

打开 ~/knowledge-base/MEMORY.md 文件，搜索你的PDF文件名或文档内关键词。若未找到对应条目，请检查配置文件 ~/.hermes/skills/ocr-and-documents/config.yaml，确认其中的 inject_to_memory 选项已设置为 true。

若配置正确但信息仍未注入，可临时手动在MEMORY.md中添加记录，格式参考：- 文件: nginx_tuning.pdf | 摘要: Nginx性能调优参数详解，含worker_connections与keepalive_timeout配置说明。此举可辅助检索层快速建立关联。

五、使用自然语言发起检索测试

全部配置完成后，需通过自然语言查询进行最终验证。此步骤应完全脱离对文件路径的依赖，纯粹测试系统的语义理解与检索能力。

首先启动交互会话：hermes chat。随后，输入一个基于文档内容的自然语言问题，例如：“nginx keepalive_timeout 参数的作用是什么？在哪份文档里提到过？”

理想的响应应包含从 nginx_tuning.pdf 中提取的相关原文片段，并明确提示文档的存放路径。若得到此结果，则表明从本地PDF文档到智能检索的通道已完全打通。