fanfei's blog

Hermes Context Files

Hermes Agent 自动发现和加载上下文文件来塑造其行为。核心文件包括 AGENTS.md（项目指令）、SOUL.md（全局人格）和 .cursorrules（Cursor IDE 兼容），通过优先级系统和渐进式子目录发现来管理。

支持的上下文文件

文件 用途 发现方式
.hermes.md / HERMES.md 项目指令（最高优先级） 向上遍历到 git root
AGENTS.md 项目指令、约定、架构 CWD + 渐进式子目录发现
CLAUDE.md Claude Code 上下文文件 CWD + 渐进式子目录发现
SOUL.md 全局人格和语气 仅从 HERMES_HOME
.cursorrules Cursor IDE 编码约定 仅 CWD

优先级

同一会话中只加载一种项目上下文（首次匹配优先）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 独立加载，始终作为 agent 身份。

AGENTS.md

渐进式子目录发现

启动时加载 CWD 的 AGENTS.md。Agent 在会话中浏览到子目录时，渐进式发现该目录的上下文文件并注入对话：

my-project/
├── AGENTS.md              ← 启动时加载
├── frontend/
│   └── AGENTS.md          ← Agent 读取 frontend/ 文件时发现
├── backend/
│   └── AGENTS.md          ← Agent 读取 backend/ 文件时发现

优势：

  • 无系统提示膨胀——子目录上下文仅在需要时出现
  • 缓存友好——系统提示在对话回合间保持稳定

加载流程

  1. 扫描工作目录（检查优先级链）
  2. 读取 UTF-8 内容
  3. 安全扫描（检测 prompt 注入模式）
  4. 截断（超过 20,000 字符时 70% 头部 + 20% 尾部）
  5. 组装到系统提示的 # Project Context 区块

安全：Prompt 注入保护

所有上下文文件在注入前经过安全扫描，检测：

  • 指令覆盖尝试（“ignore previous instructions”）
  • 欺骗模式（“do not tell the user”）
  • 隐藏 HTML 注释和元素
  • 凭证泄露尝试
  • 不可见字符

检测到威胁时文件被阻止加载。

容量限制

限制 值
每文件最大字符数 20,000 (~7,000 tokens)
子目录文件截断上限 8,000 字符

最佳实践

  • 保持简洁——远低于 20K 字符
  • 使用 ## 标题分区
  • 包含具体代码示例和约定
  • 明确说明不该做的事
  • 随项目演进更新

Timeline

相关条目