Hermes Production Patterns

Production-grade engineering patterns for Hermes Agent
Built on Harness Engineering methodology + Loop Engineering + 12-Factor Agents

把 Hermes Agent 从「聊天玩具」变成「7x24 小时自主工作的生产系统」所需的全部工程模式、公约和模板。

简介 · Introduction

中文

Hermes Production Patterns 是一套面向 Hermes Agent 的生产级工程模式集。

如果你已经装好了 Hermes，但发现：

• 不知道怎么写一个「靠谱」的技能（Skill）？
• Cron 任务跑着跑着就跑偏了，没人发现？
• Agent 输出质量不稳定，全靠肉眼审查？
• 多个任务的状态全靠脑子记，一重启就断片？
• 错误一出来就把上下文炸了，Agent 直接失焦？

这个项目就是为你准备的。

它不是什么「最佳实践」大合集，每一条模式都在真实的 7x24 运行环境中验证过，踩过坑，打过补丁，最终沉淀为可复用的工程公约。

English

Hermes Production Patterns is a collection of production-grade engineering patterns for Hermes Agent.

You've installed Hermes. Now what? If you're struggling with:

• Writing reliable Skills that don't drift over time
• Cron jobs that silently produce garbage
• Agent output quality that requires constant human babysitting
• Task state that evaporates the moment the session ends
• Error traces that flood the context window and derail the agent

This project is for you.

These aren't armchair best practices. Every pattern here has been battle-tested in real 7x24 production runs, broken, fixed, and hardened into reusable conventions.

为什么需要这个项目

Hermes Agent 本身是一个强大的 Agent 框架，但社区里最缺的不是「怎么装 Hermes」，而是：

• 怎么让 Cron 任务不跑偏、不重复、不静默失败？
• 怎么从「手写提示词」进化到「设计自动化的 Loop」？
• Maker/Checker 分离怎么做？
• 多个 Agent 任务的状态怎么管理？
• 错误来了怎么处理，不让 Agent 失焦？
• 什么时候用 LLM，什么时候用确定性代码？

这个项目回答的就是这些问题。

项目结构

hermes-production-patterns/
├── AGENTS.md                    ← Harness 入口（AI 读我）
├── README.md
├── LICENSE                      ← MIT
├── config.yaml.example          ← Hermes 配置模板
│
├── conventions/                 ← 工程公约（核心产出）
│   ├── maker-checker.md         — 生成/验证双角色分离
│   ├── state-file-pattern.md    — STATE.md 跨运行状态管理
│   ├── control-flow-separation.md — 确定性 vs LLM 控制流
│   ├── error-compact-pattern.md — 错误压缩、分类与自愈
│   ├── skill-evolution.md       — 技能版本化与生命周期管理
│   ├── cron-job-pattern.md      — Cron 任务幂等、防静默失败
│   ├── checkpoint-pattern.md    — 长任务检查点恢复
│   ├── secret-management.md     — 密钥存放与轮换规范
│   ├── anti-patterns.md         — 💡 反面模式与纠正方案
│   ├── pattern-composition.md   — 🧩 场景→模式组合决策树
│   └── state-schema.json        — 📐 STATE.md JSON Schema（程序校验用）
│
├── templates/                   ← 可复用的文件模板
│   ├── SKILL.md.template
│   ├── STATE.md.template
│   └── AGENTS.md.template
│
├── patterns/                    ← 设计模式与方法论
│   ├── loop-engineering-14-steps.md
│   ├── 12-factor-agents-for-hermes.md
│   └── maturity-staging-l1-l2-l3.md
│
└── examples/                    ← 完整实战示例
    ├── daily-news-digest.md
    ├── maker-checker-article-pipeline.md
    └── cron-safety-integration.md

三大设计原则

1. Harness Engineering — 仓库即真理之源

整个项目本身就是 Harness 的落地案例。AGENTS.md 是 AI 读你的切入点，每个 conventions/ 文件是可执行的技能，模板是可实例化的原型。

2. Loop Engineering — 从提示词到系统设计

不是手写每一条 Prompt，而是设计一个自主循环：接任务 → 派给 Agent → 验证结果 → 记录状态 → 决策下一步。

3. 12-Factor Agents — 可靠性的十二条守则

每一条原则对应一个具体的工程决策：

• Factor 2 → 写 SKILL.md 不写临时 Prompt
• Factor 5 → 用 STATE.md 统一状态
• Factor 7 → Maker/Checker 双角色
• Factor 8 → 控制流分离（代码 vs LLM）
• Factor 9 → 错误压缩不炸锅

快速开始

1. 把模式装进你的 Hermes

所有 conventions/ 文件已包含 Hermes Skill 标准的 YAML frontmatter，可直接安装：

# clone 项目
git clone https://github.com/Komagon/hermes-production-patterns.git
cd hermes-production-patterns

# 一键复制 conventions 到 Hermes skills 目录（保持各自独立子目录）
mkdir -p ~/.hermes/skills/hermes-production-patterns
cp -r conventions/* ~/.hermes/skills/hermes-production-patterns/
cp -r templates/ ~/.hermes/skills/hermes-production-patterns/
cp AGENTS.md ~/.hermes/skills/hermes-production-patterns/

安装后重新加载 Hermes（新会话自动生效，当前会话运行 /reload-skills），然后即可用 /skill 加载：

# 在 Hermes 会话中
/reload-skills
/skill maker-checker    # 加载 Maker/Checker 公约
/skill state-file-pattern  # 加载状态管理公约

# Windows (PowerShell) 同样操作
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.hermes\skills\hermes-production-patterns"
Copy-Item -Recurse -Path conventions\* -Destination "$env:USERPROFILE\.hermes\skills\hermes-production-patterns\"
Copy-Item -Recurse -Path templates\* -Destination "$env:USERPROFILE\.hermes\skills\hermes-production-patterns\templates\"
Copy-Item AGENTS.md -Destination "$env:USERPROFILE\.hermes\skills\hermes-production-patterns\"

2. 用模板创建你的第一个技能

# Linux / macOS
mkdir -p ~/.hermes/skills/my-skill
cp templates/SKILL.md.template ~/.hermes/skills/my-skill/SKILL.md

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\AppData\Local\hermes\skills\my-skill"
Copy-Item templates\SKILL.md.template "$env:USERPROFILE\AppData\Local\hermes\skills\my-skill\SKILL.md"

3. 为你的 Cron 任务添加 STATE.md

mkdir -p reports/my-cron-job
cp templates/STATE.md.template reports/my-cron-job/STATE.md

New-Item -ItemType Directory -Force -Path "reports\my-cron-job"
Copy-Item templates\STATE.md.template "reports\my-cron-job\STATE.md"

4. 参考 config.yaml.example 配置你的 Hermes

cp config.yaml.example ~/.hermes/config.yaml
# 替换 YOUR_xxx_HERE 为你的真实 API Key

核心概念速查

|| 概念 | 文件 | 一句话 | ||:---|:---|:---| || Maker/Checker | conventions/maker-checker.md | 写代码的 Agent 和验证的 Agent 不是同一个 | || STATE.md | conventions/state-file-pattern.md | 每次运行先读状态，每步执行后写状态 | || 控制流分离 | conventions/control-flow-separation.md | 能用代码的别用 LLM | || 错误压缩与自愈 | conventions/error-compact-pattern.md | 错误压成一行，分类后尝试自愈 | || 技能进化 | conventions/skill-evolution.md | 技能有版本、有生命周期、有迁移路径 | || Cron 任务设计 | conventions/cron-job-pattern.md | 幂等执行+防静默失败+自动暂停 | || 检查点恢复 | conventions/checkpoint-pattern.md | 长任务挂了能从检查点续跑 | || 密钥管理 | conventions/secret-management.md | 密钥不进 Git、不进上下文、不落日志 | || 💡 反面模式 | conventions/anti-patterns.md | 8 种常见错误实践及纠正 | || 🧩 模式组合 | conventions/pattern-composition.md | 场景→模式决策树+成熟度映射 | || 📐 状态 Schema | conventions/state-schema.json | STATE.md 的 JSON Schema 程序校验 | || Loop Engineering | patterns/loop-engineering-14-steps.md | 先判断值不值得做，再设计怎么做 | || 成熟度分级 | patterns/maturity-staging-l1-l2-l3.md | L1 只报告 → L2 辅助 → L3 自动 | || 12-Factor 对照 | patterns/12-factor-agents-for-hermes.md | 12 条工程原则的 Hermes 落地映射 |

引用与致谢

核心框架

延伸参考

本项目中的关联文档

先决条件

• Hermes Agent v0.6+
• Obsidian（可选，用于知识管理）
• Git（用于版本化技能文件）

许可

MIT — 自由使用、修改、分发。

贡献

PR 和 Issues 都欢迎。核心原则：每条模式必须在生产环境中验证过，不接受纯理论设计。