贡献指南
感谢您对 Hermes Agent 的贡献！本指南将帮助您设置开发环境、理解代码库，并顺利合并您的 PR。
贡献优先级
我们按以下顺序重视各类贡献：
- 缺陷修复 —— 程序崩溃、行为错误、数据丢失
- 跨平台兼容性 —— macOS、不同 Linux 发行版、WSL2
- 安全加固 —— Shell 注入、提示注入、路径遍历
- 性能与健壮性 —— 重试逻辑、错误处理、优雅降级
- 新技能 —— 广泛适用的技能（参见 创建技能）
- 新工具 —— 较少需要；大多数功能应通过技能实现
- 文档 —— 修正、澄清、新增示例
常见贡献路径
开发环境搭建
前置条件
| 要求 | 说明 |
|---|---|
| Git | 需支持 --recurse-submodules |
| Python 3.11+ | 若缺失，uv 会自动安装 |
| uv | 快速的 Python 包管理器 (安装指南) |
| Node.js 18+ | 可选 —— 用于浏览器工具和 WhatsApp 桥接 |
克隆并安装
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
# Create venv with Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"
# Install with all extras (messaging, cron, CLI menus, dev tools)
uv pip install -e ".[all,dev]"
uv pip install -e "./tinker-atropos"
# Optional: browser tools
npm install
开发配置
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
# Add at minimum an LLM provider key:
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env
运行
# Symlink for global access
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
# Verify
hermes doctor
hermes chat -q "Hello"
运行测试
pytest tests/ -v
代码风格规范
- PEP 8，允许实际应用中的例外（不强制限制行长度）
- 注释：仅在解释非显而易见的意图、权衡或 API 特性时使用
- 错误处理：捕获具体异常。对意外错误使用
logger.warning()/logger.error()并配合exc_info=True - 跨平台兼容：永远不要假设为 Unix 系统（详见下文）
- 安全路径处理：绝不硬编码
~/.hermes—— 使用get_hermes_home()来获取代码路径，display_hermes_home()用于用户界面消息。完整规则请参考 AGENTS.md
跨平台兼容性
Hermes 官方支持 Linux、macOS 和 WSL2。原生 Windows 不被支持，但代码库中已包含一些防御性编程模式，以避免极端情况下的崩溃。关键规则如下：
1. termios 和 fcntl 仅限 Unix 系统
始终同时捕获 ImportError 和 NotImplementedError：
try:
from simple_term_menu import TerminalMenu
menu = TerminalMenu(options)
idx = menu.show()
except (ImportError, NotImplementedError):
# Fallback: numbered menu
for i, opt in enumerate(options):
print(f" {i+1}. {opt}")
idx = int(input("Choice: ")) - 1
2. 文件编码
某些环境可能以非 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.setsid
4. 路径分隔符
请使用 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 fixes
feat/description # New features
docs/description # Documentation
test/description # Tests
refactor/description # Code restructuring
提交前准备
- 运行测试：
pytest tests/ -v - 手动测试：运行
hermes，并验证你修改的代码路径 - 评估跨平台影响：考虑 macOS 和不同 Linux 发行版
- 保持 PR 聚焦：每个 PR 仅包含一个逻辑变更
PR 描述要求
请包含：
- 更改内容及原因
- 如何测试该变更
- 测试过的平台
- 引用相关问题（如有）
提交信息格式
我们采用 Conventional Commits 规范：
<type>(<scope>): <description>
| 类型 | 用途 |
|---|---|
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）、完整的错误堆栈跟踪 - 提供复现步骤
- 创建前请先搜索已有问题，避免重复提交
- 如发现安全漏洞，请私密报告
社区交流
- Discord：discord.gg/NousResearch
- GitHub Discussions：用于设计提案与架构讨论
- 技能中心：上传专业技能并与社区共享
许可协议
通过贡献，您同意您的贡献将遵循 MIT 许可证。