HermesAgent脚本更新失败？手动拉取代码与重新编译完整指南
Hermes Agent自动更新失败需手动拉取代码并重装：一、确认Git部署形态并进入根目录；二、git fetch+submodule update同步主干与子模块；三、删除旧venv，用Python 3.11/3.12重建并重装依赖；四、校验hermes-cli命令与配置路径；五、执行setup.py构建并启动服务。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当Hermes Agent的自动更新脚本失效时，无论是无响应、报错退出，还是提示命令或文件不存在，都意味着自动更新链路已中断。这通常源于脚本路径失效、Git仓库结构变更、权限丢失或Python环境异常。遵循以下手动拉取代码与重新编译的流程，可以系统性地恢复其更新与运行能力。
一、验证当前部署形态并进入项目根目录
操作前，必须明确你的Hermes Agent部署方式：是源码编译安装，还是容器化部署？这决定了后续所有操作的基准路径。如果原始的Git工作区已丢失，你需要首先重建完整的源码树，确保后续操作基于一个真实且可编译的代码基线。
1. 首先，检查是否存在`.git`目录，这是判断是否为Git克隆部署的关键：ls -la ~/.hermes/hermes-agent/.git
2. 如果这个目录存在，并且输出显示它是一个目录结构，那么恭喜，直接进入它：cd ~/.hermes/hermes-agent
3. 如果不存在，那就需要先重建源码目录：mkdir -p ~/.hermes/hermes-agent && cd ~/.hermes/hermes-agent
4. 最后，别忘了确认当前用户对这个目录拥有读写权限：ls -ld ~/.hermes/hermes-agent
二、手动拉取最新主干代码并同步子模块
自动更新失败常因子模块同步问题导致，例如核心的`tinker-atropos`模块缺失会中断整个依赖链。手动执行`git fetch`与`submodule update`可以绕过脚本逻辑缺陷，强制同步所有嵌套组件，确保代码库完整性。
1. 执行远程分支同步：git fetch origin main
2. 检出最新的稳定提交（注意，这里通常用主干`main`，而不是开发`dev`分支）：git checkout `git rev-list -n 1 --first-parent origin/main`
3. 初始化并更新全部子模块：git submodule update --init --recursive
4. 如果上一步提示`tinker-atropos`子模块克隆失败，可以尝试手动指定一个镜像地址：git config --file .gitmodules submodule.tinker-atropos.url https://ghfast.top/https://github.com/nousresearch/tinker-atropos.git
5. 再次执行子模块更新，确保万无一失：git submodule sync && git submodule update --init --recursive
三、重建 Python 环境并强制重装依赖
旧的虚拟环境可能残留过时的包缓存或冲突的wheel文件，导致`hermes-cli`命令不可用。最彻底的解决方案是删除旧环境，并基于当前的`requirements.txt`文件，使用指定版本的Python（3.11或3.12）从头完整重装所有依赖，以清除潜在的包冲突与ABI不兼容问题。
1. 找到并移除现有的虚拟环境：rm -rf ~/.hermes/hermes-agent/.venv
2. 创建一个新的虚拟环境（注意，限定使用Python 3.11或3.12版本）：python3.12 -m venv ~/.hermes/hermes-agent/.venv
3. 激活这个新环境：source ~/.hermes/hermes-agent/.venv/bin/activate
4. 将pip升级到一个已知兼容的最新版本：pip install --upgrade pip==23.3.1
5. 安装核心依赖项，这里建议跳过预编译的轮子文件，以规避manylinux环境可能带来的冲突：pip install -r requirements.txt --no-binary :all:
6. 最后，以开发模式重新安装Hermes Agent主体：pip install -e . --force-reinstall
四、校验 CLI 可用性与配置路径映射
依赖重装后，必须验证`hermes-cli`命令是否已正确注册到系统PATH，并确保其内部解析的配置路径指向实际的数据目录。否则，即使编译成功，运行时也可能因加载空配置或找不到配置文件而失败。
1. 验证命令能否正常调用：hermes-cli --version
2. 检查CLI实际解析的配置根路径是什么：hermes-cli info | grep "config_root"
3. 如果输出的路径不是`~/.hermes`，就需要手动设置一下环境变量：export HERMES_CONFIG_ROOT=~/.hermes
4. 确认配置文件（`config.py`或`config.yaml`）确实存在于上一步的路径下：ls -l ~/.hermes/config.{py,yaml}
5. 如果两个文件都找不到，那就从项目模板里复制一个基础配置过来：cp ~/.hermes/hermes-agent/hermes_cli/config_template.py ~/.hermes/config.py
五、执行本地编译构建并启动服务
最后一步是执行本地构建。Hermes Agent的部分高级功能（如MCP网关、技能编译器）依赖于`setup.py`构建阶段生成的C扩展或字节码缓存。跳过此步骤可能导致Web UI加载失败或工具调用无响应。
1. 运行构建脚本：python setup.py build_ext --inplace
2. 生成wheel包，方便以后快速复用：python setup.py bdist_wheel
3. 启动后台服务，并抓取开头的日志以便观察：hermes-cli serve --log-level debug 2>&1 | head -n 50
4. 检查关键组件的加载状态：hermes-cli health-check | grep -E "(memory|skills|models)"
5. 如果`health-check`结果显示`models`为0，说明模型没有注册，需要手动触发一下：hermes-cli model register --all