社区贡献与开源生态参与指南

你把 /memory export 输完最后一行参数，看着屏幕上整齐的 JSON 块，突然意识到：Hermes 里有个 Skill 的触发条件写得太僵硬了，明明三行代码就能修掉。另一个念头紧随其后——修完之后怎么办？怎么把它塞回那个正在高速迭代的仓库里，而不是烂在自己的本地分支上？

截至 2026 年中，Hermes Agent 在 GitHub 上已获得超过 160k 星标，骨干维护者与社区贡献者之间形成了一套相当清晰的“接收->审查->合入”流水线。这一章的任务就是带你从头跑通这条流水线：从签署 CLA、搭建可运行全套测试的开发环境，到按规范提交 Issue 或 Feature Request，再到最终发出一个符合 PR 模板的修改。读完这一章，你就可以把自己的技能和补丁变成 Hermes 生态里真正运转的部件。

你需要什么

最终成果

完成下列三项中的至少一项：

1. 一个被维护者认可的 Issue 或 Feature Request，含最小可复现示例
2. 一个通过 CI 检查并被 review 的 Pull Request
3. （可选）一个通过 Skill 校验的 SKILL.md，提交到社区 Skill 仓库

整个过程不只是“交代码”，更是理解 Hermes 项目如何通过 CLA、代码风格检查与 PR 模板来维持 160k+ 星标项目的工程质量。

步骤一：阅读并签署贡献者协议（CLA）

大多数高星标开源项目都会要求贡献者签署 CLA（Contributor License Agreement），Hermes 也不例外。

动作
进入仓库根目录，打开 CONTRIBUTING.md，查找 “Contributor License Agreement” 章节。若仓库启用了 CLA 机器人，当你第一次提交 PR 时，机器人会自动在 PR 下评论，要求你回复 /cla sign 或在指定网页完成电子签署。

预期结果
在发起正式 PR 前，你的 GitHub 账号已与 CLA 数据库关联。如果因为未签署 CLA 导致 PR 被自动关闭，只需补签后重新开启即可，不会丢失代码。

踩坑经验
公司企业邮箱与个人 GitHub 账号绑定时，部分 CLA 系统会要求二次验证。建议使用个人邮箱注册 GitHub 并完成签署，避免公司邮件网关拦截验证链接。

步骤二：搭建开发环境并跑通测试套件

2.1 获取源码

# 克隆主仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

2.2 一键安装依赖（推荐）

项目提供了 setup-hermes.sh 脚本，用于创建虚拟环境并安装所有依赖。

# 执行安装脚本，该脚本会检测 Python 版本并安装开发依赖
bash setup-hermes.sh
# 激活虚拟环境
source .venv/bin/activate

若脚本执行失败，可手动安装：

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

开发依赖通常包含 pytest、pre-commit、black、flake8 等。

2.3 运行测试套件

# 运行全部单元测试
pytest tests/ -v

# （可选）只运行与记忆模块相关的测试，便于聚焦
pytest tests/test_memory.py -v

预期结果
终端最后一行为 == X passed in Ys ==，无失败用例。如果有跳过项（如缺外部 API Key），属于正常，只要失败数为 0 即可。

2.4 配置 pre-commit 钩子

# 安装 Git 提交前自动检查钩子
pre-commit install

此后每次 git commit 都会自动运行代码格式化与安全检查，避免推送后 CI 直接变红。

踩坑经验
macOS 上 setup-hermes.sh 可能因缺少 wget 或 coreutils 而中断，执行 brew install wget coreutils 即可解决。Windows/WSL 用户如遇到权限问题，请确认代码放在 WSL 的文件系统下（如 /home/user/），而非挂载的 /mnt/c/，否则文件监控与虚拟环境性能会严重下降。

关键依赖速查

步骤三：理解代码风格与 PR 模板

Hermes 项目使用 PEP 8 作为 Python 代码风格基准，并在此基础上通过 black 自动格式化，最大行宽 100 字符。所有函数、类与模块均需包含 Google 风格的 docstring。

3.1 代码风格示例

def normalize_context(messages: list[dict]) -> list[dict]:
    """Remove consecutive duplicate messages from the context window.

    Args:
        messages: A list of message dicts with 'role' and 'content'.

    Returns:
        A new list with duplicates collapsed.
    """
    cleaned = []
    for msg in messages:
        if not cleaned or msg != cleaned[-1]:
            cleaned.append(msg)
    return cleaned

3.2 PR 模板的填写要点

当你创建 Pull Request 时，GitHub 会自动预填一个模板，核心字段包括：

• Describe your changes：说明改了什么，解决什么问题，动机是什么
• Testing performed：列出你跑了哪些测试，并附上关键结果截图或日志
• Related issue：关联的 Issue 编号（如 Fixes #342）
• Checklist：勾选代码已格式化、测试已通过、文档已更新等条目

预期结果
维护者在点开你的 PR 后，能够在 10 秒内理解你的意图、复现你的测试、并信任这次的改动不会引入回归。

步骤四：提交一个高效的 Issue 或 Feature Request

在动手改代码之前，最好先通过 Issue 对齐预期。一个有效的 Issue 必须包含三个要素：触发条件、实际行为、预期行为。

4.1 可复现的最小示例

### 环境
- Hermes 版本：v2.3.1
- Python 版本：3.11.9
- 操作系统：Ubuntu 24.04

### 触发步骤
1. 启动 hermes serve，连接本地 Ollama（llama3.2）
2. 发送 /memory recall 2026-06-01 之前的某条记录
3. Agent 进入循环，反复输出 "Recalling..."

### 实际行为
终端无限滚动 "Recalling..."，CPU 占用维持 98%

### 预期行为
Agent 应在 5 秒内返回回忆结果或提示 "No records found"

预期结果
维护者依据你给出的步骤能在本地复现，从而快速定位问题，而不是在 Issue 下与你来回澄清。

注意
如果不提供系统环境与完整复现步骤，这类“幽灵 Issue”大概率会被标记为 need more info，并在两周内自动关闭。Feature Request 同样需要写清“现在做不到什么”“为什么需要这个功能”“你期待的交互方式”。

步骤五：发起你的第一个 Pull Request

5.1 创建分支

git checkout -b fix/recall-loop-guard

分支命名建议采用 type/description 格式，例如 feat/add-skill-time-zone、fix/shell-token-leak。

5.2 修改代码并运行检查

# 完成修改后运行测试
pytest tests/ -v

# 手动触发一次 pre-commit 全量检查
pre-commit run --all-files

5.3 提交并推送

git add .
git commit -m "fix: guard against infinite recall loop on empty history"
git push origin fix/recall-loop-guard

5.4 在 GitHub 上创建 PR

从你的 fork 分支向 main 发起 Pull Request，按 PR 模板填写所有字段。一旦提交，CI 流水线会自动运行测试和代码风格检查。

预期结果
PR 页面显示 “All checks have passed”，等待维护者 review。如果维护者请求修改，你只需在本地同一分支上追加 commit 并推送，PR 会自动更新，无需重新创建。

踩坑经验
千万不要在 main 分支上直接修改代码。一旦 main 上游更新，你的提交历史会与上游分叉，导致合并冲突一团乱麻。始终在独立分支上工作，并定期将上游 main 合并或 rebase 进你的分支。

步骤六（可选）：贡献一个 Skill

Hermes Agent 的 Skill 系统允许社区通过 SKILL.md 文件扩展 Agent 的能力。一份合格的 Skill 文件至少需要包含：

# Skill: convert-timezone

## Metadata
- version: 1.0.0
- author: your-github-handle
- triggers: ["/timezone", "convert time"]

## Description
Converts a given time between timezones using the built-in world clock tool.

## Usage
1. User inputs "/timezone 14:00 EST to UTC"
2. Agent parses time and timezones, calls `world_clock` tool.
3. Returns converted time in friendly format.

## Examples
- Input: `/timezone 09:00 PST to CET`
- Output: `18:00 CET`

提交 Skill 时，将其放在 skills/community/ 目录下，并同样通过 PR 提交。Skill 有独立的校验脚本，可在本地运行：

python scripts/validate_skills.py

预期结果
校验通过后，你的 Skill 会出现在下一次 Hermes CLI 的 Skill 列表中，供全部用户调用。

回顾

现在，你不再只是 Hermes 的“用户”——你已经握住了它内部管线的把手，知道如何安全地将自己的改进注入这个 160k+ 星标的有机体，也知道什么样的 Issue 会被维护者认真对待。

你接下来可以做的 5 件事

1. 克隆仓库，运行 setup-hermes.sh，确保 pytest 全绿
2. 在 Issues 页面筛选 good first issue 标签，认领一个简单的 bug 修复
3. 用本章模板提交一个 Issue，附上你之前遇到的任何“不适配”场景
4. 走通一次完整 PR 流程（包括代码修改、pre-commit 检查与 CI 通过）
5. 根据你日常使用的痛点，编写一个 SKILL.md 并提交到 skills/community/

当你成功合入第一个贡献后，视角会从“我能不能用”悄然切换到“它还能怎么变”。这种转变恰好会把我们引向全书的最后一站：从整体的知识节点和延伸路径，重新审视你在这趟 Agent 操作系统之旅中每一种能力的坐标。