在 Hermes 上与在 Hermes 里做开发
Hermes 是 MIT 协议的开源 Python 项目，积极接受外部贡献。本课覆盖开发环境、代码质量规则、评审者真正在意的跨平台与安全不变式、三条扩展路径，以及提交 / PR 规范。
主要来源：贡献指南 https://hermes-agent.nousresearch.com/docs/developer-guide/contributing。提 PR 前一定要回看那页，规范可能随时间演进。
贡献优先级
Hermes 对贡献类型有明确的排序 —— 挑选工作内容之前值得内化：
- Bug 修复 —— 崩溃、错误行为、数据丢失。
- 跨平台兼容。
- 安全加固。
- 性能改进。
- 新功能。
一个带终端权限的智能体，引入投机性新功能的损失比收益大 —— 这个排序就是这个意思。
开发环境搭建
需要：
- Python 3.11+。
- 带 LFS 的 Git —— 仓库对某些资源使用 LFS。
uv作为包管理器（不要直接用 pip）。- 一份
~/.hermes/配置树，含config.yaml、.env，以及标准子目录（sessions、logs、memories、skills）。 - 至少一个大模型提供商的 API key 写进
.env，供本地测试用。
克隆时带子模块（git clone --recurse-submodules），用 uv venv 建虚拟环境，装依赖时启用全部 extras，让可选集成的测试也能跑。
代码质量规范
代码库遵循 PEP 8 加务实例外，风格指南对注释的态度很明确：最小化、聚焦意图。好的变量名加短文档注释胜过一段解释代码在做什么的话。
错误处理：捕获具体异常，不要广捕。意料之外的错用 logger.warning() 或 logger.error() 配 exc_info=True，这样 traceback 真的会进日志。
一条不那么显而易见的规则：永远不要硬编码 ~/.hermes 这样的路径。内部逻辑用 get_hermes_home()，用户可见的消息用 display_hermes_home()。多 profile 安装靠这个机制 —— 硬编码会静悄悄地把它们搞坏。
跨平台不变式
官方支持：Linux、macOS、WSL2。但代码防御性写得足以在纯 Windows 上跑。常出现的三种模式：
- Unix 专属模块（
termios、fcntl）必须在 try/except 里 import，同时捕获ImportError和NotImplementedError。 - 文件编码在 locale 不是 UTF-8 时要能回退到 latin-1 —— 不要对环境做任何假设。
- 路径永远用
pathlib.Path，不要字符串拼接。这是被评审强制执行的。
安全优先设计
Hermes 默认携带终端能力，所以安全是代码评审的不变式，而不是一个功能：
- 用户输入拼到 shell 命令里时必须用
shlex.quote()防注入。 - 访问控制检查前先用
os.path.realpath()解析软链接。 - 正则驱动的危险命令检测器会对高风险命令强制要求用户批准。
- Hub 下载的技能在使用前会被安全扫描。
- 沙箱代码执行会从子进程环境里剥离 API key。
- 容器部署放弃所有 Linux capabilities 并限制 PID。
不要打日志打到秘密。任何改动碰到文件路径或子进程管理的，都要手工在多个平台测 —— 评审一定会问。
扩展：三条路径
有三条定义良好的扩展路径，不用 fork：
- 工具 —— 最低层级原语。参见「Adding Tools」文档。
- 技能 —— 更高层级的流程。参见「Creating Skills」文档与 agentskills.io 开放标准。
- 提供商 —— 新的推理后端。参见「Adding Providers」文档。
这三层是刻意分开的。如果你发现自己想在 provider 实现里伸手进终端工具内部，停一下 —— 这通常说明这份活属于另一层。
测试与 PR 礼仪
提 PR 前：pytest tests/ -v。任何被改的代码路径都要手工测一遍。PR 保持一个逻辑改动 —— 原子的比宏大的更好评审。
分支名按严格前缀：fix/、feat/、docs/、test/、refactor/。Commit 走 Conventional Commits，带 scope（cli、gateway、tools、skills、agent、install、whatsapp、security）。像 feat(gateway): add Matrix voice support 这样的提交信息一眼就能看出改了什么、改在哪。
PR 描述要写：改了什么、为什么、怎么测的、在哪些平台测过、关联哪些 Issue。Issue 报告需要 OS 信息、Python 版本、hermes version 输出、完整 traceback，以及复现步骤。
社区
贡献通过 GitHub Issues 与 Discussions 进行，实时讨论在 Discord。全项目 MIT 协议，企业与社区贡献的法律路径都很简单。
下一步
第 8 课是 CLI 命令速查，日常使用和写插件前先看一遍都很合适。想长期随手查，可以把 /learn/hermes/reference/ 加书签，按命令回来查。