贡献指南

感谢您为 Hermes Agent 做出贡献！本指南涵盖开发环境搭建、代码库理解以及 PR 合并流程。

贡献优先级

我们按以下顺序重视贡献：

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` 引擎版本）

克隆与安装

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 提供商密钥：
echo 'OPENROUTER_API_KEY=sk-or-v1-your-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 特殊之处时添加
错误处理：捕获特定异常。对意外错误使用带 exc_info=True 的 logger.warning()/logger.error()
跨平台：不要假定 Unix 环境（见下文）
配置文件安全路径：永远不要硬编码 ~/.hermes——代码路径使用 hermes_constants 中的 get_hermes_home()，用户界面消息使用 display_hermes_home()。完整规则参见 AGENTS.md

跨平台兼容性

Hermes 官方支持 Linux、macOS、WSL2 和原生 Windows（早期 beta 版 —— 通过 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) 探测时，除了 ProcessLookupError 还要捕获 OSError。 Windows 对已消失的 PID 引发 OSError（WinError 87，"参数不正确"），而不是 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("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` 中的正则模式，带用户审批流程
定时任务提示词注入	扫描器阻止指令覆盖模式
写入拒绝列表	通过 `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

提交信息

我们使用 Conventional Commits：

<type>(<scope>): <description>

类型	用途
`fix`	Bug 修复
`feat`	新功能
`docs`	文档
`test`	测试
`refactor`	代码重构
`chore`	构建、CI、依赖更新

Scope 范围：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：用于设计提案和架构讨论
技能 Hub：上传专业技能并与社区分享

许可证

通过贡献，您同意您的贡献将在 MIT 许可证下授权。

贡献优先级​

常见贡献路径​

开发环境搭建​

前置要求​

克隆与安装​

配置开发环境​

运行​

运行测试​

代码风格​

跨平台兼容性​

1. termios 和 fcntl 仅限 Unix​

2. 文件编码​

3. 进程管理​

4. 路径分隔符​

安全考虑​

现有保护措施​

贡献安全敏感代码​

Pull Request 流程​

分支命名​

提交前​

PR 描述​

提交信息​

报告问题​

社区​

许可证​