跳到主要内容

上下文文件

Hermes Agent 会自动发现并加载塑造其行为的上下文文件。有些文件是项目本地的，从工作目录发现。SOUL.md 现在是 Hermes 实例的全局文件，仅从 HERMES_HOME 加载。

支持的上下文文件​

文件用途发现方式
.hermes.md / HERMES.md项目指令（最高优先级）向上遍历至 git 根目录
AGENTS.md项目指令、约定、架构启动时 CWD + 子目录逐步加载
CLAUDE.mdClaude Code 上下文文件（也可检测）启动时 CWD + 子目录逐步加载
SOUL.md此 Hermes 实例的全局个性和语气定制仅 HERMES_HOME/SOUL.md
.cursorrulesCursor IDE 编码约定仅 CWD
.cursor/rules/*.mdcCursor IDE 规则模块仅 CWD
优先级系统

每个会话只加载一种项目上下文类型（先匹配先赢）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载，作为 Agent 身份（插槽 #1）。

AGENTS.md​

AGENTS.md 是主要的项目上下文文件。它告诉 Agent 你的项目结构、需要遵循的约定以及任何特殊指令。

渐进式子目录发现​

会话开始时，Hermes 将工作目录中的 AGENTS.md 加载到系统提示中。当 Agent 在会话期间通过 read_file、terminal、search_files 等工具导航到子目录时，它会逐步发现这些目录中的上下文文件，并在它们变得相关时将其注入对话。

my-project/
├── AGENTS.md              ← 启动时加载（系统提示）
├── frontend/
│   └── AGENTS.md          ← 当 Agent 读取 frontend/ 文件时发现
├── backend/
│   └── AGENTS.md          ← 当 Agent 读取 backend/ 文件时发现
└── shared/
    └── AGENTS.md          ← 当 Agent 读取 shared/ 文件时发现

与在启动时加载所有内容相比，这种方式有两个优势：

  • 无系统提示膨胀——子目录提示仅在需要时出现
  • 保留提示缓存——系统提示在各轮次间保持稳定

每个子目录在每个会话中最多检查一次。发现过程还会向上遍历父目录，因此读取 backend/src/main.py 时，即使 backend/src/ 没有自己的上下文文件，也会发现 backend/AGENTS.md。

信息

子目录上下文文件会经过与启动上下文文件相同的安全扫描。恶意文件会被阻止。

AGENTS.md 示例​

# Project Context

This is a Next.js 14 web application with a Python FastAPI backend.

## Architecture
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

## Conventions
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## Important Notes
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md​

SOUL.md 控制 Agent 的个性、语气和沟通风格。详见个性页面。

位置：

  • ~/.hermes/SOUL.md
  • 或 $HERMES_HOME/SOUL.md（如果你使用自定义主目录运行 Hermes）

重要说明：

  • 如果 SOUL.md 不存在，Hermes 会自动生成默认的 SOUL.md
  • Hermes 仅从 HERMES_HOME 加载 SOUL.md
  • Hermes 不会在工作目录中查找 SOUL.md
  • 如果文件为空，不会向提示中添加任何 SOUL.md 内容
  • 如果文件有内容，在扫描和截断后将内容逐字注入

.cursorrules​

Hermes 兼容 Cursor IDE 的 .cursorrules 文件和 .cursor/rules/*.mdc 规则模块。如果这些文件存在于项目根目录，且未找到更高优先级的上下文文件（.hermes.md、AGENTS.md 或 CLAUDE.md），它们将作为项目上下文加载。

这意味着使用 Hermes 时，你现有的 Cursor 约定会自动生效。

上下文文件的加载方式​

启动时（系统提示）​

上下文文件由 agent/prompt_builder.py 中的 build_context_files_prompt() 加载：

  1. 扫描工作目录——检查 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules（先匹配先赢）
  2. 读取内容——以 UTF-8 文本读取每个文件
  3. 安全扫描——检查内容是否存在提示注入模式
  4. 截断——超过 20,000 字符的文件进行头尾截断（70% 头部，20% 尾部，中间带标记）
  5. 组装——所有部分合并在 # Project Context 标题下
  6. 注入——组装后的内容添加到系统提示

会话期间（渐进式发现）​

agent/subdirectory_hints.py 中的 SubdirectoryHintTracker 监视工具调用参数中的文件路径：

  1. 路径提取——每次工具调用后，从参数（path、workdir、shell 命令）中提取文件路径
  2. 祖先遍历——检查目录及最多 5 个父目录（在已访问目录处停止）
  3. 提示加载——如果找到 AGENTS.md、CLAUDE.md 或 .cursorrules，则加载（每个目录第一个匹配）
  4. 安全扫描——与启动文件相同的提示注入扫描
  5. 截断——每个文件上限 8,000 字符
  6. 注入——附加到工具结果，使模型自然地在上下文中看到它

最终的提示部分大致如下：

# Project Context

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

注意 SOUL 内容直接插入，没有额外的包装文本。

安全性：提示注入保护​

所有上下文文件在被包含前都会扫描潜在的提示注入。扫描器检查：

  • 指令覆盖尝试："ignore previous instructions"、"disregard your rules"
  • 欺骗模式："do not tell the user"
  • 系统提示覆盖："system prompt override"
  • 隐藏 HTML 注释：<!-- ignore instructions -->
  • 隐藏 div 元素：<div style="display:none">
  • 凭证泄露：curl ... $API_KEY
  • 密钥文件访问：cat .env、cat credentials
  • 不可见字符：零宽空格、双向覆盖、字符连接符

如果检测到任何威胁模式，该文件将被阻止：

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
注意

此扫描器防护常见的注入模式，但不能替代对共享仓库中上下文文件的审查。在你未编写的项目中，始终验证 AGENTS.md 内容。

大小限制​

限制值
每个文件最大字符数20,000（约 7,000 个 token）
头部截断比例70%
尾部截断比例20%
截断标记10%（显示字符数并建议使用文件工具）

当文件超过 20,000 字符时，截断消息如下：

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

有效上下文文件的技巧​

AGENTS.md 的最佳实践
  1. 保持简洁——远低于 20K 字符；Agent 每轮都会读取它
  2. 使用标题结构——使用 ## 区分架构、约定、重要说明等部分
  3. 包含具体示例——展示首选的代码模式、API 形状、命名约定
  4. 提及不应做的事——"绝不直接修改迁移文件"
  5. 列出关键路径和端口——Agent 在终端命令中会用到这些
  6. 随项目演进更新——过时的上下文比没有上下文更糟糕

每个子目录的上下文​

对于 monorepo，在嵌套的 AGENTS.md 文件中放置子目录专属指令：

<!-- frontend/AGENTS.md -->
# Frontend Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`
<!-- backend/AGENTS.md -->
# Backend Context

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`