第2章 源码安装
墨鱼说：🦑 "想体验最新功能？想在代码里自由潜水？跟我来，从源码构建属于你自己的 Hermes Agent！"
为什么要从源码安装？
第 1 章介绍的一键安装方式简单快捷，适合大多数用户。但在以下场景中，源码安装会是更好的选择：
- 获取最新功能 — 源码仓库包含尚未发布到 PyPI 的最新功能和修复，让你始终走在前沿。
- 参与贡献 — 如果你希望向 Hermes Agent 提交 Bug 报告、功能建议或代码贡献，源码安装是第一步。
- 自定义修改 — 你可以自由修改源代码，定制适合自己工作流的 Agent 行为。
- 学习与探索 — 阅读和调试源码是深入理解项目架构的最佳途径。
TIP
如果你只是想快速上手使用 Hermes Agent，第 1 章的一键安装方式完全够用。源码安装主要面向开发者和高级用户。
前置条件
在开始之前，请确保你的系统已具备以下工具：
| 工具 | 最低版本 | 检查命令 | 说明 |
|---|---|---|---|
| Git | 2.0+ | git --version | 用于克隆和更新仓库 |
| Python | 3.10+ | python3 --version | Hermes Agent 运行环境 |
| pip | 最新版 | pip --version | Python 包管理器 |
| venv | 内置 | python3 -m venv --help | 虚拟环境管理（Python 自带） |
快速检查脚本：
# 一键检查所有前置条件
echo "Git: $(git --version)"
echo "Python: $(python3 --version)"
echo "pip: $(pip --version)"
echo "venv: $(python3 -m venv --help >/dev/null 2>&1 && 'OK' || 'MISSING')"如果缺少 Git，请访问 git-scm.com 下载安装。如果 Python 版本低于 3.10，请前往 python.org 升级。
克隆仓库
首先，将 Hermes Agent 的源码仓库克隆到本地：
# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
# 进入项目目录
cd hermes-agent克隆完成后，你的目录结构大致如下：
hermes-agent/
├── README.md
├── requirements.txt
├── setup.py
├── pyproject.toml
├── src/
│ └── hermes/
├── tests/
└── docs/创建虚拟环境并安装依赖
为了不污染系统 Python 环境，强烈建议使用虚拟环境。
创建并激活虚拟环境
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
# Linux / macOS:
source venv/bin/activate
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# Windows (CMD):
.\venv\Scripts\activate.bat激活成功后，你的终端提示符前面会出现 (venv) 标识。
安装依赖
有两种方式安装依赖，按需选择：
方式一：可编辑模式安装（推荐）
pip install -e .-e 参数表示以"可编辑"模式安装。这样你对源码的任何修改都会立即生效，无需重新安装。适合需要修改代码的开发者。
方式二：安装 requirements
pip install -r requirements.txt这种方式只安装运行依赖，不会将包注册到 pip 中。适合只运行不修改代码的用户。
WARNING
每次打开新的终端窗口后，都需要重新激活虚拟环境（source venv/bin/activate）。如果觉得麻烦，可以将其加入 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）。
验证安装
安装完成后，运行以下命令验证一切正常：
# 检查版本
hermes --version
# 查看帮助信息
hermes --help如果能看到版本号和帮助信息，恭喜你——安装成功！🎉
你也可以快速确认可编辑模式是否生效：
# 在 Python 中验证
python -c "import hermes; print(hermes.__file__)"输出的路径应该指向你克隆的 hermes-agent/ 目录下的源码文件，说明可编辑模式正常工作。
安装完成后，配置文件仍然存放在 ~/.hermes/.env，与一键安装的方式一致。具体配置步骤将在第 3 章详细介绍。
保持更新
源码安装的一个特点是：你需要手动同步上游仓库来获取更新。
日常更新流程
# 进入项目目录
cd hermes-agent
# 激活虚拟环境
source venv/bin/activate
# 拉取最新代码
git pull origin main
# 更新依赖（如有变化）
pip install -e .查看更新内容
# 查看最近的提交记录
git log --oneline -10
# 查看当前版本与上次拉取的差异
git log HEAD@{1}..HEAD --oneline墨鱼小贴士 🦑
建议定期（比如每周）执行一次 git pull，保持与上游同步。如果长时间不更新，可能会遇到依赖冲突或功能不兼容的问题。
一键安装 vs 源码安装 对比
| 特性 | 一键安装 (pip) | 源码安装 (git) |
|---|---|---|
| 安装难度 | ⭐ 简单 | ⭐⭐⭐ 中等 |
| 安装步骤 | 1 步 | 4-5 步 |
| 最新功能 | 需等待版本发布 | ✅ 实时获取 |
| 自定义修改 | ❌ 不支持 | ✅ 完全自由 |
| 参与贡献 | ❌ 不方便 | ✅ 开箱即用 |
| 更新方式 | pip install --upgrade | git pull |
| 依赖管理 | pip 自动处理 | 需手动同步 |
| 磁盘占用 | 较小 | 较大（含 .git） |
| 适合人群 | 普通用户 | 开发者 / 高级用户 |
| 配置文件位置 | ~/.hermes/.env | ~/.hermes/.env |
| hermes 命令 | ✅ 可用 | ✅ 可用 |
INFO
两种安装方式最终都会提供相同的 hermes 命令，配置文件位置也完全一致。你可以随时从一种方式切换到另一种。
国内用户加速指南
由于网络原因，国内用户在访问 GitHub 和 PyPI 时可能会遇到速度慢或连接失败的问题。以下是一些实用的加速方案。
GitHub 克隆加速
方案一：使用镜像站
# 使用 GitHub 镜像站加速克隆（以 ghfast.top 为例）
git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git常见的 GitHub 镜像站（请选择当前可用的）：
| 镜像站 | 用法 |
|---|---|
| ghfast.top | https://ghfast.top/https://github.com/... |
| ghproxy.cn | https://ghproxy.cn/https://github.com/... |
| hub.gitmirror.com | https://hub.gitmirror.com/https://github.com/... |
WARNING
镜像站可能不稳定，如果某个不可用，请尝试其他的。正式环境中建议使用官方地址 + 代理。
方案二：配置 Git 代理
如果你有 HTTP 代理（如 Clash、V2Ray 等），可以直接配置 Git：
# 设置 HTTP 代理（请替换为你的代理地址和端口）
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
# 仅对 GitHub 使用代理
git config --global http.https://github.com.proxy http://127.0.0.1:7890
# 取消代理设置
git config --global --unset http.proxy
git config --global --unset https.proxy方案三：使用 SSH + 代理
# 克隆 SSH 版本
git clone git@github.com:NousResearch/hermes-agent.git
# 在 ~/.ssh/config 中配置代理
Host github.com
ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %ppip 安装加速
使用国内 PyPI 镜像源加速依赖安装：
# 临时使用清华镜像源
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple
# 永久配置镜像源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple常用的国内 PyPI 镜像源：
| 镜像源 | 地址 |
|---|---|
| 清华大学 | https://pypi.tuna.tsinghua.edu.cn/simple |
| 阿里云 | https://mirrors.aliyun.com/pypi/simple |
| 中国科技大学 | https://pypi.mirrors.ustc.edu.cn/simple |
| 豆瓣 | https://pypi.douban.com/simple |
小结
本章我们学习了如何从源码安装 Hermes Agent。让我们回顾一下关键步骤：
- 确认前置条件 — Git、Python 3.10+、venv 缺一不可
- 克隆仓库 —
git clone获取源码 - 创建虚拟环境 —
python3 -m venv venv隔离依赖 - 安装依赖 —
pip install -e .或pip install -r requirements.txt - 验证安装 —
hermes --version确认一切正常 - 保持更新 — 定期
git pull同步上游代码
下一章，我们将进入 第 3 章 初始配置向导，配置你的第一个 AI 模型 API，让墨鱼真正"活"起来！🦑