贡献指南
感谢你为 Hermes Agent 做出贡献！本指南涵盖如何设置开发环境、理解代码库以及让 Pull Request 成功合并。
贡献优先级
我们按以下顺序评估贡献：
- Bug 修复 — 崩溃、错误行为、数据丢失
- 跨平台兼容性 — macOS、不同 Linux 发行版、WSL2
- 安全加固 — Shell 注入、提示注入、路径遍历
- 性能和健壮性 — 重试逻辑、错误处理、优雅降级
- 新技能 — 具有广泛实用性的技能（参见创建技能）
- 新工具 — 很少需要；大多数功能应通过技能实现
- 文档 — 修正、澄清说明、新增示例
常见贡献路径
- 想要构建自定义/本地工具而不修改 Hermes 核心？请从构建 Hermes 插件开始
- 想要为 Hermes 自身构建新的内置核心工具？请从添加工具开始
- 想要构建新技能？请从创建技能开始
- 想要构建新的推理提供者？请从添加提供者开始
开发环境设置
前置条件
| 要求 | 说明 |
|---|---|
| Git | 需支持 --recurse-submodules，并安装 git-lfs 扩展 |
| Python 3.11+ | 如果缺失，uv 会自动安装 |
| uv | 快速 Python 包管理器（安装指南） |
| Node.js 20+ | 可选——浏览器工具和 WhatsApp 桥接需要（与根目录 package.json engines 字段匹配） |
克隆与安装
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
# 使用 Python 3.11 创建虚拟环境
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
# 安装所有扩展（消息通信、定时任务、CLI 菜单、开发工具）
uv pip install -e ".[all,dev]"
# 可选：浏览器工具
npm install配置开发环境
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
# 至少添加一个 LLM 提供者的 API 密钥：
echo 'OPENROUTER_API_KEY=***' >> ~/.hermes/.env运行
# 创建全局符号链接
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
# 验证安装
hermes doctor
hermes chat -q "Hello"运行测试
pytest tests/ -v代码风格
- PEP 8 标准，允许实际例外（不强制严格的行长度限制）
- 注释：仅在解释非显而易见的意图、权衡或 API 特殊行为时添加
- 错误处理：捕获特定异常。对意外错误使用
logger.warning()/logger.error()并带上exc_info=True - 跨平台：切勿假定 Unix（详见下文）
- 配置文件安全路径：切勿硬编码
~/.hermes——代码路径使用get_hermes_home()（来自hermes_constants），面向用户的消息使用display_hermes_home()。完整规则请参见 AGENTS.md。
跨平台兼容性
Hermes 正式支持 Linux、macOS、WSL2 和原生 Windows（早期测试版——通过 PowerShell 安装）。原生 Windows 使用 Git Bash（来自 Git for Windows）执行 Shell 命令。部分功能需要 POSIX 内核原语并设有防护：仪表盘中嵌入的 PTY 终端面板（/chat 标签页）仅限 WSL2。原生 Windows 路径较新且迭代较快——如果你主要从事 Windows 开发，预计会遇到并修复一些粗糙边缘。
贡献代码时，请牢记以下规则：
- 不要添加无防护的
signal.SIGKILL引用。 该常量在 Windows 上未定义。要么通过gateway.status.terminate_pid(pid, force=True)（该集中式原语在 Windows 上执行taskkill /T /F，在 POSIX 上执行 SIGKILL），要么使用getattr(signal, "SIGKILL", signal.SIGTERM)作为回退。 - 在
os.kill(pid, 0)探测时，同时捕获OSError和ProcessLookupError。 Windows 对已不存在的 PID 会抛出OSError（WinError 87，“parameter is incorrect”）而不是ProcessLookupError。 - 不要强制终端使用 POSIX 语义。
os.setsid、os.killpg、os.getpgid、os.fork在 Windows 上都会抛出异常——请使用if sys.platform != "win32":或if os.name != "nt":进行防护。 - 打开文件时显式指定
encoding="utf-8"。 Windows 上 Python 的默认编码是系统区域设置（通常是 cp1252），这会导致非拉丁文字出现乱码或崩溃。 - 使用
pathlib.Path/os.path.join——切勿手动拼接/。 对于操作系统返回的字符串影响不大，但对于我们构造后传递给子进程的字符串则至关重要。
关键模式：
1. termios 和 fcntl 仅适用于 Unix
始终同时捕获 ImportError 和 NotImplementedError：
try:
from simple_term_menu import TerminalMenu
menu = TerminalMenu(options)
idx = menu.show()
except (ImportError, NotImplementedError):
# 回退：编号菜单
for i, opt in enumerate(options):
print(f" {i+1}. {opt}")
idx = int(input("请选择: ")) - 12. 文件编码
某些环境可能使用非 UTF-8 编码保存 .env 文件：
try:
load_dotenv(env_path)
except UnicodeDecodeError:
load_dotenv(env_path, encoding="latin-1")3. 进程管理
os.setsid()、os.killpg() 和信号处理因平台而异：
import platform
if platform.system() != "Windows":
kwargs["preexec_fn"] = os.setsid4. 路径分隔符
使用 pathlib.Path 替代字符串拼接 /。
安全考量
Hermes 具有终端访问权限。安全至关重要。
现有防护
| 层 | 实现 |
|---|---|
| Sudo 密码管道 | 使用 shlex.quote() 防止 Shell 注入 |
| 危险命令检测 | tools/approval.py 中的正则表达式模式，附带用户审批流程 |
| Cron 提示注入 | 扫描器阻止指令覆盖模式 |
| 写入黑名单 | 受保护路径通过 os.path.realpath() 解析，防止符号链接绕过 |
| 技能防护 | 对 Hub 安装的技能进行安全扫描 |
| 代码执行沙箱 | 子进程运行时剥离 API 密钥 |
| 容器加固 | Docker：删除所有能力，无特权提升，PID 限制 |
贡献安全相关代码
- 将用户输入插入 Shell 命令时，始终使用
shlex.quote() - 在访问控制检查前，使用
os.path.realpath()解析符号链接 - 不要记录日志中的密钥信息
- 在工具执行周围捕获宽泛异常
- 如果你的修改涉及文件路径或进程，在所有平台上进行测试
Pull Request 流程
分支命名
fix/description # Bug 修复
feat/description # 新功能
docs/description # 文档
test/description # 测试
refactor/description # 代码重构
提交前
- 运行测试：
pytest tests/ -v - 手动测试：运行
hermes并执行你修改的代码路径 - 检查跨平台影响：考虑 macOS 和不同的 Linux 发行版
- 保持 PR 聚焦：每个 PR 只做一个逻辑改动
PR 描述
需包含：
- 什么发生了变化以及为什么
- 如何测试
- 在哪些平台上测试过
- 引用相关 Issue
提交信息
我们使用约定式提交：
<类型>(<作用域>): <描述>
| 类型 | 用途 |
|---|---|
fix | Bug 修复 |
feat | 新功能 |
docs | 文档 |
test | 测试 |
refactor | 代码重构 |
chore | 构建、CI、依赖更新 |
作用域：cli、gateway、tools、skills、agent、install、whatsapp、security
示例：
fix(cli): prevent crash in save_config_value when model is a string
feat(gateway): add WhatsApp multi-user session isolation
fix(security): prevent shell injection in sudo password piping
报告问题
- 使用 GitHub Issues
- 包含：操作系统、Python 版本、Hermes 版本（
hermes version）、完整错误堆栈追踪 - 包含复现步骤
- 在创建重复 Issue 前先检查已有 Issue
- 对于安全漏洞，请私下报告
社区
- Discord：discord.gg/NousResearch
- GitHub Discussions：用于设计方案和架构讨论
- Skills Hub：上传专业技能并与社区分享
许可证
通过贡献，你同意你的贡献将按照 MIT 许可证 进行许可。