Skip to main content

贡献

Welcome! We're excited to have you contribute to Hermes Agent, an open-source AI agent framework designed for building intelligent, autonomous agents. This guide walks you through setting up your development environment, following our code style conventions, and submitting high-quality pull requests (PRs).

🛠️ Development Setup​

1. Prerequisites​

Make sure you have the following installed:

  • Python 3.10+
  • Poetry (for dependency management)
  • Git
  • Node.js (if working on frontend components or integrations)

💡 Tip: Use pyenv or conda to manage Python versions if needed.

2. Fork & Clone the Repository​

git clone https://github.com/your-username/hermes-agent.git
cd hermes-agent

Replace your-username with your GitHub username.

3. Set Up Poetry Environment​

poetry env use python3.10
poetry install

This installs all dependencies and sets up a virtual environment.

4. Install Pre-commit Hooks​

We use pre-commit to enforce code quality:

poetry run pre-commit install

Now, every time you commit, linting and formatting checks will run automatically.

5. Configure Environment Variables​

Create a .env file in the root directory:

cp .env.example .env

Edit .env to include your API keys (e.g., OpenAI, OpenRouter, etc.) if testing integrations.

🔐 Never commit secrets. Use .env for local dev only.

📝 Code Style & Best Practices​

We follow strict standards to ensure consistency and readability.

✅ Python Code Style​

  • Use Black for formatting (poetry run black .)
  • Follow PEP 8 guidelines
  • Use type hints everywhere (e.g., def func(x: int) -> str:)
  • Write clear, descriptive docstrings using Google-style format:
def calculate_total(items: list[float]) -> float:
    """Calculate the total sum of item prices.

    Args:
        items: List of item prices as floats.

    Returns:
        Total price as a float.
    """
    return sum(items)

✅ JavaScript/TypeScript (if applicable)​

  • Use ESLint + Prettier
  • Enforced via pre-commit hooks
  • Follow camelCase naming, avoid global variables

✅ Commit Messages​

Use clear, concise messages in imperative mood:

  • ✅ Good: Add support for OpenRouter API
  • ❌ Bad: Added OpenRouter support or Fixes issue #123

Use conventional commit prefixes:

  • feat: – New feature
  • fix: – Bug fix
  • docs: – Documentation changes
  • style: – Code style changes (no logic impact)
  • refactor: – Code refactoring
  • test: – Test-related changes
  • chore: – Maintenance tasks

Example:

git commit -m "feat: add Telegram integration via webhook"

🔄 Pull Request (PR) Process​

1. Branch Naming​

Always create a feature branch from main:

git checkout main
git pull origin main
git checkout -b feat/telegram-integration

Use this pattern: feat/<feature-name>, fix/<bug-description>, docs/<topic>.

2. Push Your Changes​

git push origin feat/telegram-integration

3. Open a Pull Request​

Go to GitHub → "Pull Requests" → "New Pull Request"

  • Base: main
  • Compare: your branch
  • Title: Use the same convention as commit messages (e.g., feat: Add Telegram integration)
  • Description:
    • Explain what the PR does
    • Reference any related issues (#123)
    • Include screenshots or logs if relevant
    • Mention any breaking changes

4. CI Checks​

Your PR will trigger automated checks:

  • Linting (flake8, black, eslint)
  • Unit tests (pytest)
  • Type checking (mypy)
  • Security scanning (if applicable)

✅ Wait for all checks to pass before merging.

5. Review & Feedback​

A maintainer will review your PR. Be responsive to feedback and ready to make adjustments.

⏳ Typically within 2–3 business days.

6. Merge​

Once approved and all checks pass:

  • The PR will be merged into main
  • A new release may be triggered automatically

🤝 Additional Tips​

  • Test First: Write unit and integration tests for new features.
  • Keep PRs Small: Smaller PRs are faster to review and less error-prone.
  • Document Everything: Update README.md, SOUL.md, or internal docs when adding features.
  • Join Our Community:

🎯 Want to Go Further?​

Check out our Contribution Guide for advanced topics like:

  • Adding new agent tools
  • Building custom agents with MCP (Multi-Agent Collaboration Protocol)
  • Contributing to Honcho (our agent orchestration layer)
  • Publishing to PyPI or npm

🙌 Thank You!​

Your contributions help shape the future of autonomous AI agents. Whether it’s fixing a bug, improving documentation, or building a new feature — every contribution matters.

Let’s build smarter agents, together.
👉 Start contributing now

📌 Note: This guide is based on the current state of main. Always check the latest CONTRIBUTING.md in the repo for updates.

Hermes Agent is developed by Nous Research and the open-source community.
Powered by OpenAI, OpenRouter, Modal, and more."​

贡献指南

感谢您对 Hermes Agent 的贡献！本指南将帮助您设置开发环境、理解代码库，并顺利合并您的 PR。

贡献优先级​

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

  1. 缺陷修复 —— 程序崩溃、行为错误、数据丢失
  2. 跨平台兼容性 —— macOS、不同 Linux 发行版、WSL2
  3. 安全加固 —— Shell 注入、提示注入、路径遍历
  4. 性能与健壮性 —— 重试逻辑、错误处理、优雅降级
  5. 新技能 —— 广泛适用的技能（参见 创建技能）
  6. 新工具 —— 较少需要；大多数功能应通过技能实现
  7. 文档 —— 修正、澄清、新增示例

常见贡献路径​

开发环境搭建​

前置条件​

要求说明
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

提交前准备​

  1. 运行测试：pytest tests/ -v
  2. 手动测试：运行 hermes，并验证你修改的代码路径
  3. 评估跨平台影响：考虑 macOS 和不同 Linux 发行版
  4. 保持 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 许可证。