在 Windows 上离线运行 Hermes Agent：从零构建一个 700MB 的便携包
前言
Hermes Agent 是 NousResearch 开源的 AI Agent 框架，支持代码执行、浏览器自动化、定时任务、多平台消息网关等丰富功能。但官方安装流程依赖 curl | bash 和系统级 Python/Node.js，在 Windows 环境下部署一直是个痛点。
本文记录将 Hermes Agent v0.13.0 完整封装为 Windows 离线便携包 的全过程。最终产物是一个 687MB 的自解压 EXE，双击安装即可在任意 Windows 10/11 机器上运行，无需管理员权限，无需预先安装任何运行时。
一、为什么需要便携包
1.1 官方安装的局限性
官方 install.ps1 脚本虽然是用户级安装（无需管理员），但仍存在以下问题：
依赖系统 Python 3.11+ 和 Node.js 22+
需要联网下载大量依赖（pip + npm）
better-sqlite3 等原生模块需要 Visual Studio Build Tools
安装路径散落在 ~/.hermes、~/.local、AppData 等多个目录
换机器需要重新走完整安装流程
1.2 便携包的设计目标
目标
实现方式
零依赖
嵌入式 Python 3.11 + Node.js 22 + PortableGit 全部内置
离线可用
所有 pip/npm 依赖预装，Playwright Chromium 预下载
任意目录
启动时自动修复 pyvenv.cfg 和 launcher shebang 路径
无管理员
纯用户级运行，不写注册表，不碰系统目录
可迁移
整个目录复制到新机器即可使用
二、目录结构
Hermes-Portable/
├── app/hermes-agent/ # 源码 + venv + node_modules (~1GB)
│ ├── venv/ # Python 虚拟环境
│ ├── node_modules/ # npm 依赖
│ ├── ui-tui/ # TUI 组件
│ └── hermes_cli/ # CLI 入口包
├── runtime/ # 运行时环境 (~1.3GB)
│ ├── python/ # Python 3.11.9 嵌入式
│ ├── nodejs/ # Node.js 22.22.2
│ ├── git/ # PortableGit 2.54.0
│ └── playwright-browsers/ # Chromium 引擎 (~670MB)
├── hermes/ # 用户数据（可备份）
│ ├── .env # API 密钥
│ ├── config.yaml # 主配置
│ ├── SOUL.md # 人格设定
│ ├── sessions/ # 聊天记录
│ └── skills/ # 自定义技能
├── scripts/fix-paths.ps1 # 路径自动修复 + 缓存
├── start.bat # 启动 CLI（通用入口）
├── setup.bat # 首次配置向导
├── gateway.bat # 启动消息网关
├── set-model.bat # 设置模型
├── clean.bat # 恢复出厂设置
└── README.md
三、关键技术实现
3.1 嵌入式 Python + virtualenv
Python 官方提供的 python-3.11.9-embed-amd64.zip 是精简版，不包含 venv 模块。需要先用 get-pip.py 安装 pip，再安装 virtualenv：
# 安装 pip
runtime\python\python.exe get-pip.py
# 安装 virtualenv（embedded Python 没有 venv）
runtime\python\python.exe -m pip install virtualenv
# 创建虚拟环境
runtime\python\python.exe -m virtualenv app\hermes-agent\venv
这里有一个坑：清华镜像源的 get-pip.py 404，最终使用官方源才成功：
Invoke-WebRequest -Uri "https://bootstrap.pypa.io/get-pip.py" -OutFile "get-pip.py"
3.2 四级依赖降级策略
Hermes 的 pyproject.toml 定义了大量 extras，[all] 安装可能会失败。实际采用四级降级：
# Tier 1: 全量安装（大概率失败）
venv\Scripts\pip install -e ".[all]"
# Tier 2: 常用 extras（推荐）
venv\Scripts\pip install -e ".[web,mcp,cron,cli,voice,messaging,slack,dev,pty,homeassistant,sms,tts-premium,honcho,google,mistral,bedrock,dingtalk,feishu,modal,daytona,vercel]"
# Tier 3: 核心功能
venv\Scripts\pip install -e ".[web,mcp,cron,cli,messaging,dev]"
# Tier 4: 裸包（保底）
venv\Scripts\pip install -e "."
3.3 npm install 的陷阱
TUI 组件依赖 better-sqlite3，这是一个原生 C++ 模块，需要 VS Build Tools。在便携包环境中没有 Build Tools，初次安装会报错：
npm ERR! gyp ERR! find VS could not find a copy of Visual Studio
解决方案是 --ignore-scripts 跳过 postinstall：
cd app\hermes-agent
npm install --ignore-scripts
cd ui-tui
npm install --ignore-scripts
等安装完 VS Build Tools 后，可以重新跑完整 npm install 让 better-sqlite3 正确编译。
3.4 Launcher Shebang 硬编码问题（Critical）
这是整个项目中最隐蔽的 bug。
setuptools 生成的 hermes.exe launcher 是一个 PE 可执行文件，文件尾部嵌入了 shebang：
#!E:\Hermes-Portable\app\hermes-agent\venv\Scripts\python.exe
当用户把包解压到 D:\ 时，launcher 仍然尝试调用 E:\... 的 Python，报错：
Fatal error in launcher: Unable to create process using '"E:\Hermes-Portable\..."'
修复方案：彻底绕过 launcher
所有 BAT 脚本不再调用 hermes.exe，改用直接调用 Python 模块：
:: 修改前（已废弃）
hermes chat
:: 修改后（推荐）
"%ROOT%\app\hermes-agent\venv\Scripts\python.exe" -m hermes_cli.main chat
同时保留 fix-paths.ps1 对 .exe launcher 的 shebang 修复作为兜底：
# 扫描 .exe 文件尾部 2KB 区域的所有 "#!" 标记
# 匹配后面跟着盘符路径 + python 的 shebang
# 用新路径原地替换（同长度）或填充 null（新路径更短）
3.5 PYTHONPATH 缺失问题
绕过 launcher 后，又遇到新问题：
Error while finding module specification for 'hermes_cli.main'
ModuleNotFoundError: No module named 'hermes_cli'
原因是 hermes_cli 是本地包（位于 app/hermes-agent/hermes_cli），venv 的 Python 默认搜索路径不包含它。需要在 BAT 中显式设置 PYTHONPATH：
set "PYTHONPATH=%ROOT%\app\hermes-agent"
3.6 启动缓存优化
fix-paths.ps1 每次启动都要扫描 50+ 个 .exe launcher 修复 shebang，耗时 2-5 秒。这对用户体验是不可接受的。
优化方案：.pathfix_cache
$cacheFile = Join-Path $PortableRoot "hermes\.pathfix_cache"
if (Test-Path $cacheFile) {
$cachedRoot = Get-Content $cacheFile
if ($cachedRoot -eq $PortableRoot) {
# 路径未变，跳过所有修复
exit 0
}
}
# ... 完整修复逻辑 ...
$PortableRoot | Out-File $cacheFile
效果：首次启动 ~2s（完整修复），后续启动 24ms（直接跳过）。
3.7 便携包自动检测
即使 BAT 脚本设置了 HERMES_HOME，如果用户从 PowerShell 直接运行 python -m hermes_cli.main，HERMES_HOME 未设置，数据会泄露到 C:\Users\<用户名>\.hermes。
修复：修改 hermes_constants.py
def get_hermes_home():
val = os.environ.get("HERMES_HOME", "").strip()
if val:
return Path(val)
# 便携包自动检测
try:
import sys
exe = Path(sys.executable).resolve()
parts = exe.parts
for i, part in enumerate(parts):
if "hermes-portable" in part.lower():
portable_root = Path(*parts[:i + 1])
hermes_home = portable_root / "hermes"
if hermes_home.is_dir():
return hermes_home
except Exception:
pass
# fallback: ~/.hermes
return Path.home() / ".hermes"
四、制作自解压 EXE
使用 7-Zip SFX 模块制作安装包：
# 1. 压缩（-mx=1 最快级别，减少打包时间）
7z.exe a -t7z -mx=1 -mmt=on -y "Hermes-Portable.7z" "Hermes-Portable"
# 2. SFX 配置
$config = @"
;!@Install@!UTF-8!
Title="Hermes Agent Portable v0.13.0"
BeginPrompt="即将安装 Hermes Agent v0.13.0 便携版到 D:\Hermes-Portable"
InstallPath="D:\Hermes-Portable"
OverwriteMode="2"
GUIFlags="8+32"
GUIMode="1"
;!@InstallEnd@!
"@
# 3. 合并
cmd /c "copy /b 7z.sfx + sfx-config.txt + Hermes-Portable.7z Hermes-Agent-Setup.exe"
最终产物：
原始包：2.3GB（解压后）
7z 压缩包：687MB
自解压 EXE：687MB
五、打包前安全检查（Mandatory）
真实踩坑：首次打包时遗漏了 .env 中的 MINIMAX_CN_API_KEY，导致分发包中包含真实 API 密钥。
打包前必须执行的安全清单：
# 1. 终止占用进程（防止 state.db 被锁定）
Get-Process | Where-Object {
$_.Modules | Where-Object { $_.FileName -like "*Hermes-Portable*" }
} | Stop-Process -Force
# 2. 删除敏感文件
$files = @("auth.json", "auth.lock", "state.db", "state.db-shm", "state.db-wal",
".hermes_history", ".skills_prompt_snapshot.json", "models_dev_cache.json",
"memory_store.db", "kanban.db")
foreach ($f in $files) {
Remove-Item "hermes/$f" -Force -ErrorAction SilentlyContinue
}
# 3. 重置配置为模板
copy .env.example her\.env
copy cli-config.yaml.example hermes\config.yaml
# 4. 清空数据目录
Remove-Item hermes\sessions\* -Recurse -Force
Remove-Item hermes\logs\* -Recurse -Force
Remove-Item hermes\memories\* -Recurse -Force
# 5. 删除自定义 skills（保留 .bundled_manifest）
Get-ChildItem hermes\skills -Directory | Remove-Item -Recurse -Force
六、P0 测试验证
打包完成后运行自动化验证脚本，全部通过方可分发：
测试项
验证内容
结果
路径修复
手动破坏 pyvenv.cfg，验证自动修复
✅ PASS
启动
start.bat version 输出版本号
✅ PASS
诊断
start.bat doctor 42+ pass, 0 fail
✅ PASS
可移动性
复制到新目录，验证仍能启动
✅ PASS
编码
所有 .bat 无 UTF-8 BOM
✅ PASS
Launcher 绕过
BAT 脚本使用 python.exe -m，不调用 hermes.exe
✅ PASS
缓存
.pathfix_cache 使二次启动 < 100ms
✅ PASS
敏感数据
hermes/ 目录无 auth.json, state.db 等
✅ PASS
七、快速开始
7.1 安装
下载 Hermes-Agent-v0.13.0-Win-Early-Beta-Setup.exe（687MB）
双击运行，点击 Install
自动解压到 D:\Hermes-Portable
7.2 配置
cd D:\Hermes-Portable
setup.bat
按提示配置 API Key（推荐 OpenRouter）。
7.3 启动
start.bat
或执行子命令：
start.bat doctor # 运行诊断
start.bat skills list # 列出技能
start.bat sessions # 查看会话历史
八、总结
本文完整记录了 Hermes Agent Windows 便携包的构建过程，涵盖：
嵌入式 Python + virtualenv 隔离方案
npm 原生模块编译的绕过策略
setuptools launcher shebang 硬编码问题的根治方案
启动缓存优化（2-5s → 24ms）
便携包自动检测防止数据泄露
7-Zip SFX 自解压安装包制作
打包前敏感数据清理清单
最终产物是一个 687MB 的自解压 EXE，在 Windows 10/11 上双击即用，无需任何预先安装。
参考链接
Hermes Agent 官方仓库：https://github.com/NousResearch/hermes-agent
Python 嵌入式发行版：https://www.python.org/downloads/windows/
7-Zip SFX 文档：https://www.7-zip.org/7z.html
本文涉及的完整构建脚本：https://github.com/your-repo/hermes-portable-tool
下载
夸克网盘：https://pan.quark.cn/s/9973b9c3312a
文件名：Hermes-Agent-v0.13.0-Win-Early-Beta-Setup.exe
SHA256：9AEC77AD1BEC0719630AE3C334688B607F3BFD9F5B2BDE6CFE4A2BC18888C55D