企业官网建设流程全解析

如何为 oh-my-hermes 贡献代码：CONTRIBUTING 与本地开发循环完全指南

【免费下载链接】oh-my-hermesAll in one plugin for Hermes Agent ⚚ the coding intelligence, a long-term memory system and model optimized workflow packages项目地址: https://gitcode.com/GitHub_Trending/ohm/oh-my-hermes

想给 oh-my-hermes 贡献代码吗？这篇文章会带你完整走一遍 oh-my-hermes 开发流程：从一键搭建本地开发环境，到跑通测试与 Lint 检查，再到符合规范的提交与 Pull Request（PR）清单。oh-my-hermes 是一个纯 Python、零运行时依赖的 Hermes Agent 插件，核心功能包括编码智能路由、长期记忆系统和模型优化的工作流包，而 CONTRIBUTING.md 是每一位贡献者必读的开发约定。

为什么值得参与 oh-my-hermes 开发

在动手之前，先花一分钟了解你要改动的代码"长什么样"。oh-my-hermes 运行在 Hermes Agent 之上，把一次普通的自然语言请求变成一条可观察的工作流：路由打分、分派模型、执行、验证、留痕。

这意味着贡献者改动的不只是"一个命令"，而是一整套契约：路由规则、技能目录、生成文档、精确计数断言。项目里最常见的返工原因不是算法 bug，而是contract drift（契约漂移）——比如手改了生成文件、或新增路由用例后忘了更新测试里的精确计数。REVIEW.md 开篇就写明了这一点，建议你在提交 PR 前先读一遍。

oh-my-hermes 本地开发环境一键搭建步骤

oh-my-hermes 使用 uv 管理依赖（如果你还没有，可先安装 uv）。首次搭建只需两条命令：

git clone https://gitcode.com/GitHub_Trending/ohm/oh-my-hermes cd oh-my-hermes uv sync --group lint

uv sync --group lint会创建一个严格的可编辑安装（strict editable mode），并把 lint 工具组（锁定版本ruff==0.16.7，见 pyproject.toml）一并装好。

两个新手最容易忽略的配置细节：

• 在编辑器中选中项目根目录下.venv的 Python 解释器。这样基于 pyright 的类型检查才能读到与 wheel 相同的omh包布局。
• pyrightconfig.json已为测试配置了PYTHONPATH=tests导入根，测试共享的辅助模块都放在tests/根目录，本地跑测试时必须带上它。

如果你后续新增、重命名或替换了源文件，记得刷新可编辑链接布局：

uv sync --group lint --reinstall-package oh-my-hermes

💡 提示：使用 pip 的贡献者可以用python -m pip install -e . --config-settings editable_mode=strict得到同样的布局。

本地开发循环：测试 + Lint + 生成文档检查

oh-my-hermes 的本地开发循环就三步，和 CI（.github/workflows/ci.yml）的门槛完全一致。

1️⃣ 跑测试

最小闭环是先跑单个测试文件，确认自己的改动：

PYTHONPATH=tests uv run python -m unittest tests/test_cli.py -v

确认无误后，跑完整套件（本地开发文档化的标准路径，见 AGENTS.md 的 Verification 章节）：

PYTHONPATH=tests uv run python -m unittest discover -s tests

PYTHONPATH=tests不能省——共享测试辅助函数就住在tests/根目录。

2️⃣ 跑静态分析（与 CI 相同的 Ruff 版本）

不需要全局安装ruff，直接用锁定版本跑：

uv run --group lint ruff check src tests

CI 中这一步只启用 Pyflakes 的F规则（未使用导入、未定义变量等正确性问题），刻意不做格式检查——详见 pyproject.toml 中的注释说明。

3️⃣ 生成文档一致性检查

oh-my-hermes 的skills/*/SKILL.md、docs/WORKFLOWS.md、docs/ROLES.md 等都是从 src/skills/catalog.py 等源码自动生成的，门禁是逐字节精确比对，差一个字符 CI 就失败。所以每次改动后建议执行：

uv run python -m omh.cli docs workflows --check git diff --check

常见返工原因速查表

完整清单可对照 docs/ADDING-A-SKILL.md——新增一个可安装技能时要触及的每个位置（awareness lane、上下文卡片、精确计数夹具、再生成命令）都在那里有可粘贴的指引。

提交规范：DCO 签名是硬性要求

每个提交都必须携带Developer Certificate of Origin 签名，PR 上会运行DCO检查，缺签名的提交无法合入。用-s自动附加：

git commit -s -m "fix: stop the router matching bare 'plan'"

它会自动追加一行 trailer：

Signed-off-by: Your Name <you@example.com>

两个常见补救操作：

# 最近一次提交忘了签名 git commit --amend -s --no-edit # 整个分支一次性补签名 git rebase --signoff origin/main

两者都会改写历史，之后需要git push --force-with-lease。

维护者和 AI 代理的提交还会额外携带Constraint、Rejected、Confidence、Scope-risk、Tested等决策 trailer（格式见 AGENTS.md 的 Git And Commits 章节）——外部贡献者不带这些也可以，唯一硬性要求是 DCO 签名，且Signed-off-by:必须保持在消息最末尾。

Pull Request 清单：提交前逐条自查

oh-my-hermes 的 PR 模板 不是走形式，它要求 PR 描述读起来像一份"有用的功能报告"而不是简短的 changelog。提交前对照 CONTRIBUTING.md 的 Pull Request Checklist 自查：

• ✅ 改动范围清晰，并解释了"为什么改"
• ✅ 本地测试通过（完整套件命令见上文）
• ✅uv run --group lint ruff check src tests本地通过
• ✅ 行为变化时同步更新了公开文档
• ✅ 目录数据变化时重新生成了文档，或跑过--check
• ✅ PR 描述包含风险、验证方式与已知缺口

🎯 经验之谈：在 REVIEW.md 里被标记为 Important（阻塞性）的问题，绝大多数是契约漂移——生成产物被手改、精确计数没同步、路由触发缺少负向用例。先读它，能帮你省下一整轮往返。

开始你的第一次贡献

1. 读 CONTRIBUTING.md 与 REVIEW.md（各 10 分钟，回报巨大）
2. uv sync --group lint搭建环境，跑一遍完整测试确认本地是绿的
3. 从一个小而完整的用户目标开始（项目约定：一个用户目标通常对应一个 PR）
4. 本地循环：改代码 → 跑测试 → 跑 ruff → 跑--check→ 生成产物
5. 用git commit -s提交，按模板填写 PR 描述

更多背景资料：docs/README.md 是文档地图，docs/ARCHITECTURE.md 讲整体架构，docs/WORKFLOWS.md 是工作流参考目录。

祝提交顺利——你的第一行Signed-off-by，就是和这个项目的正式握手 🤝

【免费下载链接】oh-my-hermesAll in one plugin for Hermes Agent ⚚ the coding intelligence, a long-term memory system and model optimized workflow packages项目地址: https://gitcode.com/GitHub_Trending/ohm/oh-my-hermes