切换到源码安装

源码检出和打包应用是两份独立的安装。随包附带的应用继续使用自己的载荷；它不会采用旁边的检出。当你想让 GUI 跑修改过的代码时，再使用源码构建的桌面端。

用户数据通常位于应用之外：

宿主默认数据位置
Linux、macOS、WSL、Termux~/.hermes/
原生 Windows%LOCALAPPDATA%\hermes\
官方 Docker 容器/opt/data/，映射到宿主机存储

HERMES_HOME 和所选 profile 可覆盖这些默认值。在更换安装之前，记录下实际的源 home 和目标 home。

1. 备份并停止旧运行时

从现有安装运行：

hermes backup
hermes gateway status

把备份放在你计划删除的任何目录之外。备份可能包含凭据，因此相应保护它。

交接前退出桌面端，并停掉你自己的网关/服务。退出桌面和 hermes gateway stop 是两回事：退出应用不一定会停掉一个独立托管的消息网关。

按 profile 的网关锁防止重复网关。会话锁和 SQLite 并发是两回事；启动第二个进程本身并不会切换 SQLite 日志模式。交接时，避免在任一版本执行迁移期间，让混合代码版本写入同一个 home。

2. 克隆一份独立检出

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

开发时改为克隆你的 fork，并把 canonical 仓库加为 upstream。在准备依赖之前选定分支或 commit。不要克隆进已签名的应用包，也不要覆盖打包运行时。

3. 准备源码运行时

阅读开发者工作流，了解原生构建前置条件和当前的引导限制。准备之前先选定你要用的 HERMES_HOME，然后激活。激活会自己运行引导：

source ./activate
hermes --version

在原生 Windows 上，用 PowerShell：

. .\activate.ps1
hermes --version

引导从 pm/lock.json 读取工具锁定值，并把安装交给 PM。当前的一方代码跑在 Python 3.14 上。更宽的 >=3.11,<3.15 包元数据只是让旧安装在 PM 把它们切到 3.14 之前能跑更新器；它不是运行时支持范围。源码默认是 all extra，而不是桌面包的 --all-extras。

激活会组合已安装的工具环境，并把 hermes 定义为这个工作树的 CLI。该函数会隐藏旧的 hermes 命令或 MSIX 别名，且在工作树之外拒绝生效。完成后 deactivate 会恢复 shell 环境并移除该函数。

测试依赖和手动环境请使用开发环境搭建。所选 Python 代际和可写工具存储见包管理。

4. 有意识地选择数据

在同一台机器上日常使用时，选择与上次安装相同的 HERMES_HOME 和 profile。开发时，单独的 home 更安全，因为新代码可能迁移已存储的数据。

POSIX 示例：

export HERMES_HOME="$HOME/hermes-source-data"
hermes setup
hermes

PowerShell 示例：

$env:HERMES_HOME = Join-Path $HOME 'hermes-source-data'
hermes setup
hermes

如果你在准备好 PM 状态之后改了 home，在依赖其选定的依赖之前，先为那个 home 运行引导。不要以为改环境变量就会搬数据或复制运行时状态。

要构建源码桌面端，从准备好的检出运行 hermes desktop。打开旧的打包应用仍会启动它自己的打包后端。

Docker 用户

/opt/data 是容器路径，不一定是可用的宿主机路径。对于绑定挂载，把宿主机侧目录作为源进程的 HERMES_HOME。对于命名卷或 Docker Desktop VM 存储，先停掉旧网关。然后导出/导入备份，或通过受控挂载复制数据。检查目标位置的属主和权限。

本地 docker build -t hermes-agent . 产出的是另一份镜像托管的安装。它不会把正在运行的容器变成一个自更新的源码检出。重新创建容器以使用该镜像。参见 Docker。

Nix 和 Termux 用户

本地 nix run . 仍运行一个 Nix 拥有的 derivation。它的包文件保持不可变，更新仍由 Nix 管。开发 shell 用 nix develop，或在宿主支持的地方按上面的源码流程操作。

Termux 发行版是一个 bionic APT 包。桌面/服务器源码引导不是它支持的开发或修复路径。其包与构建边界见 Termux 指南。

切回时不要想当然地认为降级安全

停掉源码运行时，退出其激活，然后打开打包应用。再次使用 hermes 之前，先确认解析到的是哪个 CLI 命令：

command -v hermes

在 Windows 上用 Get-Command hermes -All。不要在没查清属主的情况下替换一个无关命令或执行别名。

较新的源码修订可能改变数据格式。回到旧包并不是 schema 迁移的逆过程。保留当前数据；如果旧包需要，恢复一份兼容的、切换前的备份。

删除源码检出不会移除打包应用。它也不会自动回收每一条 PM 工具项或 Python 代际。用 PM 的诊断和垃圾回收，而不是删除共享数据根。

故障排查

  • 版本不对： 检查命令解析，然后在已激活的检出中用 hermes --version。
  • 缺依赖： 在目标源码环境中运行 python -m pm.cli install，然后重启受影响的 Hermes 进程。
  • 网关已在运行： 用 hermes gateway status 检查所选 profile。停掉已识别的属主；不要杀无关进程。
  • 首次运行后 skill 不同： 较新的代码可能把内置 skill 同步进数据 home。源码检出不是那个 home 的只读视图。