貢獻指南

感謝您為 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

# 使用 Python 3.11 創建虛擬環境
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# 安裝所有附加功能（消息、cron、CLI 菜單、開發 tools）
uv pip install -e ".[all,dev]"
uv pip install -e "./tinker-atropos"

# 可選：瀏覽器tools
npm install

開發配置

mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# 至少添加一個 LLM provider 密鑰：
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 特性時使用
錯誤處理：捕獲具體異常。對於意外錯誤，使用 logger.warning() / logger.error() 並傳入 exc_info=True
跨平臺：永遠不要假設為 Unix 系統（見下文）
安全路徑：永遠不要硬編碼 ~/.hermes —— 代碼路徑請使用 hermes_constants 中的 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):
    # 後備：編號菜單
    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() 解析符號鏈接
不要記錄密鑰
在工具執行周圍捕獲寬泛異常
若您的更改涉及文件路徑或進程，請在所有平臺上進行測試

拉取請求流程

分支命名

fix/description        # 錯誤修復
feat/description       # 新功能
docs/description       # 文檔
test/description       # 測試
refactor/description   # 代碼重構

提交前檢查

運行測試：pytest tests/ -v
手動測試：運行 hermes 並測試您修改的代碼路徑
檢查跨平臺影響：考慮 macOS 和不同 Linux 發行版
保持 PR 聚焦：每個 PR 僅包含一個邏輯變更

PR 描述

請包含：

變更內容 及原因
如何測試 該變更
測試過的平臺
引用任何相關問題

提交信息

我們使用 Conventional Commits：

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

類型	用途
`fix`	修復缺陷
`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：用於設計提案和架構討論
Skills Hub：上傳專業技能並與其他社區成員共享

許可證

通過貢獻，您同意您的貢獻將遵循 MIT 許可證。

貢獻優先級​

常見貢獻路徑​

開發環境設置​

前提條件​

克隆與安裝​

開發配置​

運行​

運行測試​

代碼風格​

跨平臺兼容性​

1. termios 和 fcntl 僅限 Unix​

2. 文件編碼​

3. 進程管理​

4. 路徑分隔符​

安全注意事項​

現有防護措施​

貢獻安全敏感代碼​

拉取請求流程​

分支命名​

提交前檢查​

PR 描述​

提交信息​

報告問題​

社區​

許可證​