上下文文件

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

支持的上下文文件

文件	用途	发现方式
.hermes.md / HERMES.md	项目指令（最高优先级）	向上查找到 git 根目录
AGENTS.md	项目指令、约定、架构	启动时的 CWD + 子目录渐进发现
CLAUDE.md	Claude Code 上下文文件（也会被检测）	启动时的 CWD + 子目录渐进发现
SOUL.md	此 Hermes 实例的全局个性和语气定制	仅 HERMES_HOME/SOUL.md
.cursorrules	Cursor IDE 编码约定	仅 CWD
.cursor/rules/*.mdc	Cursor IDE 规则模块	仅 CWD

:::info 优先级系统 每个会话仅加载一个项目上下文类型（首个匹配获胜）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终作为代理身份独立加载（#1 插槽）。 :::

AGENTS.md

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

子目录渐进发现

在会话启动时，Hermes 从你的工作目录加载 AGENTS.md 到系统提示中。当代理在会话期间导航到子目录时（通过 read_file、terminal、search_files 等），它会渐进发现这些目录中的上下文文件，并在它们变得相关时注入到对话中。

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

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

• 系统提示不会膨胀——子目录提示仅在需要时出现
• 提示缓存得以保留——系统提示在多次对话之间保持稳定

每个子目录每个会话最多检查一次。发现还会向上遍历父目录，因此读取 backend/src/main.py 会发现 backend/AGENTS.md，即使 backend/src/ 本身没有上下文文件。

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

AGENTS.md 示例

# 项目上下文
 
这是一个 Next.js 14 Web 应用程序，使用 Python FastAPI 后端。
 
## 架构
- 前端：Next.js 14，使用 `/frontend` 中的 App Router
- 后端：FastAPI 在 `/backend`，使用 SQLAlchemy ORM
- 数据库：PostgreSQL 16
- 部署：Hetzner VPS 上的 Docker Compose
 
## 约定
- 所有前端代码使用 TypeScript strict 模式
- Python 代码遵循 PEP 8，各处使用类型提示
- 所有 API 端点返回 `{data, error, meta}` 格式的 JSON
- 测试放在 `__tests__/` 目录（前端）或 `tests/`（后端）
 
## 重要提示
- 绝不直接修改迁移文件——使用 Alembic 命令
- `.env.local` 文件包含真实的 API 密钥，不要提交
- 前端端口 3000，后端 8000，数据库 5432

SOUL.md

SOUL.md 控制代理的个性、语气和沟通风格。详情请参见个性页面。

位置：

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

重要细节：

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

.cursorrules

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

这意味着你现有的 Cursor 约定在使用 Hermes 时自动适用。

上下文文件的加载方式

启动时（系统提示）

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

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

会话期间（渐进发现）

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

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

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

# Project Context
 
以下项目上下文文件已加载，应遵循：
 
## AGENTS.md
 
[你的 AGENTS.md 内容在此]
 
## .cursorrules
 
[你的 .cursorrules 内容在此]
 
[你的 SOUL.md 内容在此]

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

安全：提示注入防护

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

• 指令覆盖尝试：“忽略之前的指令”、“无视你的规则”
• 欺骗模式：“不要告诉用户”
• 系统提示覆盖：“系统提示覆盖”
• 隐藏 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.]

:::warning 此扫描器可防御常见的注入模式，但不能替代审查共享仓库中的上下文文件。始终验证不是你创作的项目中的 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.]

有效上下文文件的技巧

:::tip AGENTS.md 最佳实践

1. 保持简洁——远低于 20K 字符；代理每轮都会读取它
2. 使用标题结构化——使用 ## 章节组织架构、约定、重要提示
3. 包含具体示例——展示偏好的代码模式、API 形状、命名约定
4. 提及不要做什么——“绝不直接修改迁移文件”
5. 列出关键路径和端口——代理在终端命令中使用这些
6. 随项目演进更新——过时的上下文比没有上下文更糟 :::

每个子目录的上下文

对于单仓库，将子目录特定指令放在嵌套的 AGENTS.md 文件中：

<!-- frontend/AGENTS.md -->
# 前端上下文
 
- 使用 `pnpm` 而非 `npm` 进行包管理
- 组件放在 `src/components/`，页面放在 `src/app/`
- 使用 Tailwind CSS，绝不使用内联样式
- 使用 `pnpm test` 运行测试

<!-- backend/AGENTS.md -->
# 后端上下文
 
- 使用 `poetry` 进行依赖管理
- 使用 `poetry run uvicorn main:app --reload` 运行开发服务器
- 所有端点需要 OpenAPI 文档字符串
- 数据库模型在 `models/`，模式在 `schemas/`