一键搞定 Hermes Agent：跨平台自动化安装脚本的深度技术拆解
图片来源：https://unsplash.com/photos/man-standing-in-front-of-server-racks-with-tablet-73766IW_fQY
核心问题：为什么我们需要两套截然不同的安装脚本？
本段欲回答的核心问题：Hermes Agent 的安装脚本是如何实现跨平台兼容的？
我研究过很多自动化安装脚本，Hermes Agent 的这套逻辑是我认为非常老练的。它没有尝试用一套代码包打天下，而是针对 Windows 和类 Unix 系统（Linux、macOS、Android/Termux）分别编写了 install.ps1 和 install.sh。这种设计虽然增加了维护成本，但在实际部署场景中非常稳健。Windows 环境依赖 PowerShell 的对象化处理能力，而 Linux 环境则依赖 Bash 的流式处理。
我发现很多开发者在 Windows 上强行使用 WSL 运行 Linux 脚本，其实这会破坏宿主机的环境隔离。Hermes Agent 的做法是：如果你在 PowerShell 里输入命令，它就调用 irm | iex；如果你在 Linux 终端里，它就用 curl | bash。这种“原生对原生”的处理方式，直接避开了路径斜杠方向、权限管理机制以及包管理器之间的天然鸿沟。
核心问题：uv 在安装过程中扮演什么角色？
本段欲回答的核心问题：为什么脚本执着于先安装 uv 而不是直接用 pip？
在详细拆解代码后，我看到这两个脚本的第一步几乎都是在安装 uv。对于不熟悉它的朋友，你可以把它看作是 Python 界的“火箭推进器”。
在 install.ps1 中，脚本通过 irm https://astral.sh/uv/install.ps1 | iex 来抓取 uv。而在 install.sh 中，则是通过 curl -LsSf https://astral.sh/uv/install.sh | sh。为什么要这么做？因为 uv 解决了 Python 环境版本管理最头疼的问题。它不依赖系统预装的 Python，而是能够自己下载并管理特定版本的 Python 二进制文件。
我特别欣赏脚本里的一个细节：它指定了 PythonVersion = "3.11"。这意味着无论你的系统里装的是 Python 3.8 还是 3.12，uv 都会精准地为你拉取一个隔离的 3.11 环境。这种设计保证了后续安装 hermes-agent 的所有依赖库时，不会因为版本冲突导致整个安装进程崩溃。
核心问题：Windows 环境下的 PowerShell 脚本是如何运作的？
本段欲回答的核心问题：install.ps1 是如何处理 Windows 复杂的依赖项和环境变量的？
Windows 的安装逻辑非常琐碎。我把 install.ps1 拆开来看，它主要执行了以下几个关键动作。
1. 参数与权限初始化
脚本开头定义了 param 块，支持 -NoVenv、-SkipSetup 等开关。如果你想自定义安装目录，可以通过修改 $HermesHome 来实现。默认情况下，它会躲在你的 %LOCALAPPDATA%\hermes 文件夹里。我发现它设置了 $ErrorActionPreference = "Stop"，这太重要了。如果不设这个，PowerShell 可能会在某个命令报错后继续往下跑，最后给你一个半吊子的安装结果。
2. 疯狂的包管理器适配
我看到 Install-SystemPackages 函数里有一段很有趣的代码。它在尝试安装 ripgrep 和 ffmpeg 时，会依次检查 winget、choco（Chocolatey）和 scoop。
-
首先尝试 winget install ... -
如果没有 winget，改用choco install ... -
再不行，就用 scoop install ...
这种“三重保底”机制最大程度地利用了 Windows 现有的生态。如果这三者都没有，脚本甚至会输出提示，告诉你手动去哪下载。
3. Node.js 的特殊对待
对于 Node.js，脚本的逻辑更进一步。如果检测到系统中没有 Node，它甚至会下载一个独立的 .zip 包，解压到 $HermesHome\node，然后直接把这个路径塞进 Path。这种“不给用户添麻烦”的自动下载逻辑，是专业级脚本的标志。
4. Git 的“补丁”操作
在克隆仓库时，脚本执行了 git config --global windows.appendAtomically false。这其实是针对 Windows 文件系统的一个深坑：在某些杀毒软件或 OneDrive 同步环境下，Git 写入文件可能会报错。这行代码虽然不起眼，但能解决 90% 的克隆失败问题。
核心问题：Linux 和 macOS 上的 Bash 脚本有何不同？
本段欲回答的核心问题：install.sh 如何适配从 Ubuntu 到 Android Termux 的所有环境？
比起 Windows，类 Unix 系统的环境更加碎片化。install.sh 展现出了极强的适应性。
1. 系统检测与架构识别
脚本使用 detect_os 函数来识别你的身份。它通过 uname -s 区分 Linux 和 Darwin（macOS），再通过 uname -m 识别你是 x86_64 还是 arm64。这意味着它能自动适配你的 M1/M2 Mac 或是传统的 Intel 服务器。
2. Termux 的“特权”通道
我发现脚本里有大量的 if [ "$DISTRO" = "termux" ]; then 判断。这是一个很贴心的设计。在 Android 的 Termux 环境下，很多标准工具是不通用的。例如，Termux 不支持 uv 的自动安装方式，脚本就果断切换到 pkg install python 和 python -m venv 这种原生路径。
3. 环境变量的持久化
与 Windows 修改注册表不同，Linux 下需要修改 shell 的配置文件。脚本会自动检测你用的是 bash、zsh 还是 fish。
-
如果是 bash，它往~/.bashrc里写。 -
如果是 zsh，它往~/.zshrc里写。 -
它还会写入 ~/.profile作为保底。
这种全方位的配置文件覆盖，保证了你下次打开终端时，hermes 命令一定是可用的。
图片来源：https://pexels.com/photo/person-using-silver-laptop-1181244/
核心问题：安装过程中最容易忽略的系统依赖有哪些？
本段欲回答的核心问题：除了 Python，Hermes Agent 运行还需要哪些底层支持？
很多人以为装完 Python 环境就万事大吉了，但从代码来看，Hermes Agent 的野心很大，它需要以下三个核心组件的支持：
| 依赖组件 | 作用 | 安装方式 (Windows) | 安装方式 (Linux) |
|---|---|---|---|
| 「Node.js」 | 处理前端与浏览器工具 | 自动下载 Zip 或 Winget | 系统包管理器 (apt/brew/pkg) |
| 「ripgrep (rg)」 | 高性能文件内容搜索 | Winget/Choco/Scoop | 系统包管理器 |
| 「ffmpeg」 | 处理音视频数据 | Winget/Choco/Scoop | 系统包管理器 |
我注意到脚本在安装这些工具时非常谨慎。例如在 Linux 上，它会先运行 sudo apt update（如果是 Debian 系）。在安装 Node.js 依赖时，它会进入 client 目录执行 npm install。这意味着 Hermes Agent 不仅仅是一个 Python 后端，它还包含一个完整的 Node.js 前端或中间件。
核心问题：仓库克隆与虚拟环境的构建细节
本段欲回答的核心问题：脚本是如何确保代码成功下载并隔离运行的？
克隆仓库是安装的关键环节。我发现脚本采用了一种“先礼后兵”的策略。
SSH 与 HTTPS 的自动切换
无论是 .ps1 还是 .sh，都会先定义两个 URL：一个 SSH 格式（git@github.com...），一个 HTTPS 格式。
脚本会先尝试 git clone $RepoUrlSsh。我推测这是为了方便开发者，因为 SSH 密钥通常更稳定。如果 SSH 连接失败（比如你没配置密钥），它会立刻静默切换到 HTTPS。这种逻辑非常人性化，避免了用户卡在权限报错上。
虚拟环境的“冷启动”
在依赖安装阶段，脚本体现了极高的效率：
-
「创建环境」： uv venv。 -
「安装 Python 依赖」：通过 uv pip install -r requirements.txt。 -
「安装 Node 依赖」：进入特定目录执行 npm install。
如果你在安装时使用了 --no-venv 参数，脚本会跳过创建步骤。但我强烈建议不要这么做，除非你非常清楚自己在干什么。
核心问题：安装完成后，脚本是如何配置自动启动的？
本段欲回答的核心问题：如何确保 Hermes Agent 安装完就能直接运行？
脚本在最后一步会尝试启动“网关（Gateway）”。
Windows 上的后台运行
在 install.ps1 的末尾，它调用了 Start-GatewayIfConfigured。它使用了一个很取巧的办法：Start-Process -WindowStyle Hidden。这会让 Gateway 程序在后台悄悄运行，不会弹出一个黑乎乎的窗口打扰你工作。
Linux 上的系统集成
在 Linux 上，它更倾向于使用正规军。如果系统支持 systemd，它会尝试生成一个服务文件。这样当你重启电脑时，Hermes Agent 会自动拉起。如果不支持 systemd（比如在 macOS 或轻量级容器里），它会退而求其次，使用 nohup 配合 & 符号，让进程在后台挂载。
实用摘要 / 操作清单
如果你正准备开始安装，请务必核对以下清单：
-
「权限检查」：Windows 用户建议在管理员模式下打开 PowerShell；Linux 用户确保有 sudo权限。 -
「网络环境」：脚本需要访问 GitHub 和 Astral（uv 官网），建议配置好全局代理。 -
「Git 准备」：确保你的系统已经安装了 Git，否则脚本会在第一步就报错。 -
「路径确认」：默认安装在 ~/.hermes(Linux) 或AppData\Local\hermes(Windows)。 -
「手动步骤」：安装完成后，记得根据提示运行 source ~/.bashrc(Linux) 或重启 PowerShell，否则hermes命令可能不生效。
一页速览（One-page Summary）
-
「脚本定位」：两套脚本分别针对 Windows (PS1) 和 Unix (SH) 环境，通过原生工具链实现自动化。 -
「核心工具」：深度依赖 uv进行 Python 版本管理和依赖提速。 -
「依赖矩阵」：除了 Python 3.11，还需要 Node.js、ripgrep 和 ffmpeg。 -
「安装逻辑」：采用“环境检查 -> 包管理器安装依赖 -> 克隆仓库 -> 构建虚拟环境 -> 配置环境变量 -> 启动服务”的线性流程。 -
「容错机制」：支持 SSH/HTTPS 自动切换、多重包管理器尝试（Winget/Choco/Scoop）、以及特定环境（Termux）的降级处理。 -
「部署结果」：安装后，Agent Gateway 会以隐藏窗口或后台服务形式运行，且 hermes命令被添加到系统路径。
常见问答（FAQ）
「Q1：安装脚本报错提示“Git not found”怎么办？」
答：脚本不负责安装 Git 客户端。你需要先去 git-scm.com 下载安装，或者在终端运行 winget install git.git (Windows) 或 apt install git (Linux)。
「Q2：为什么我的 Windows 终端运行脚本显示“在此系统上禁止运行脚本”？」
答：这是 PowerShell 的执行策略保护。你需要先执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，然后再运行安装命令。
「Q3：我可以使用现有的 Python 环境而不让脚本下载新的吗？」
答：可以。在运行脚本时添加 --no-venv (Linux) 或 -NoVenv (Windows) 开关。但这样容易导致依赖冲突，我不推荐。
「Q4：如果我的网络无法访问 GitHub，脚本能离线安装吗？」
答：目前这两个脚本都是基于在线资源的。它们会尝试从 GitHub 克隆仓库和下载 Node.js、uv 等工具。离线环境下无法直接运行此脚本。
「Q5：安装后的 hermes-agent 文件夹可以移动到其他硬盘吗？」
答：不建议手动移动。因为脚本已经把当前的安装路径写死在了环境变量和配置文件里。如果必须移动，你需要手动更新 Path 变量和相关配置文件中的 HERMES_HOME 指向。
「Q6：Termux 用户安装有什么特别需要注意的？」
答：脚本在 Termux 下会自动跳过 uv 和 systemd 的安装。你会发现它直接使用 pkg install python。请确保你的 Termux 存储空间充足，因为编译 Python 包可能比较占空间。
