hermes doctor 是系统性诊断工具，用于检测模型连接、技能加载和安全策略；出现 FAIL 时功能不可信，需结合 --deep、--target memory、--no-cache 等参数定位具体故障。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在终端输入 hermes 却收到 command not found，或运行 hermes chat 后卡住无响应、报错信息里反复出现 Failed to load model 或 Connection refused，说明底层环境或配置已出现断裂，必须用 hermes doctor 系统性扫描真实状态，而非凭猜测修改配置文件。
快速验证命令是否真正就位
打开终端，直接执行：
hermes --version
若输出类似 hermes 0.8.0，说明二进制已安装且 PATH 正确；
若提示 command not found，请立即执行 source ~/.bashrc（zsh 用户用 source ~/.zshrc），【这是最常被跳过的一步，90% 的“命令不存在”问题在此解决】；
仍失败则检查 ~/.local/bin 是否在 PATH 中：echo $PATH | grep local。
执行基础健康检查
运行：
hermes doctor
该命令会自动检测模型连接性、技能加载状态、安全策略初始化三项核心能力。
输出中每行以 [PASS] 或 [FAIL] 开头，【只要出现一个 [FAIL]，后续所有功能都不可信】；
常见 [FAIL] 条目如 Model provider unreachable，意味着 API Key 无效或 base_url 格式错误；
若全部显示 [PASS] 但实际仍无法聊天，请进入下一步深度诊断。
启用深度诊断模式定位隐性故障
方法一：全量依赖与技能扫描
hermes doctor --deep
此模式会递归检查 ~/.hermes/skills/ 下每个技能的 manifest.yaml 是否语法合法、依赖声明是否完整、Python 模块能否成功 import。若某技能缺失 __init__.py 或引用了未安装的包，此处会明确标出路径和错误类型。
方法二：聚焦记忆模块校验
hermes doctor --target memory
专用于排查会话历史丢失、上下文截断异常等问题。它会读取 ~/.hermes/state.db，输出最近 5 条会话摘要及时间戳哈希值。若返回 No records found，说明持久化存储未启用或数据库损坏，需重置：rm ~/.hermes/state.db。
方法三：强制跳过缓存验证原始配置
hermes doctor --no-cache
当修改了 config.yaml 却始终不生效，极可能是旧缓存干扰。此参数让诊断完全绕过内存缓存，直读磁盘文件。若 --no-cache 下显示 [FAIL] 而默认模式下是 [PASS]，说明你正在编辑的配置文件根本不是 Hermes 实际加载的那个路径。
生成离线诊断快照供协作分析
第一步：生成结构化诊断包
hermes dump --show-keys
第二步：将输出保存为文件
hermes dump --show-keys > ~/hermes-diag-$(date +%Y%m%d).txt
第三步：检查文件内容
cat ~/hermes-diag-*.txt | head -n 20
该命令输出不含任何 API Key 明文（仅显示 api_key: [REDACTED]），但包含完整的环境变量快照、模型配置摘要、技能列表及 gateway 绑定地址。把此文件发给同事或社区时，对方能立刻判断是 Python 版本冲突、端口被占，还是模型 provider 配置错写成 openai 却填了 Anthropic 的 key。
