Skip to main content

上下文文件

Hermes Agent 会自动发现并加载影响其行为的上下文文件。部分文件为项目本地文件，从当前工作目录中发现。SOUL.md 现在对整个 Hermes 实例全局生效，并仅从 HERMES_HOME 加载。

支持的上下文文件​

文件用途发现方式
.hermes.md / HERMES.md项目说明（优先级最高）向上遍历至 Git 仓库根目录
AGENTS.md项目说明、规范与架构启动时从当前工作目录 + 逐级子目录查找
CLAUDE.mdClaude 代码上下文文件（也支持检测）启动时从当前工作目录 + 逐级子目录查找
SOUL.md当前 Hermes 实例的全局人格与语气定制仅从 HERMES_HOME/SOUL.md 加载
.cursorrulesCursor IDE 编码规范仅限当前工作目录
.cursor/rules/*.mdcCursor IDE 规则模块仅限当前工作目录
优先级系统

每个会话中，只加载一种项目上下文类型（首个匹配项胜出）：.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              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

这种做法相比在启动时一次性加载所有内容具有两大优势：

  • 避免系统提示膨胀 —— 子目录提示仅在需要时出现
  • 保持提示缓存稳定 —— 系统提示在各轮对话间保持一致

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

info

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

示例 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 控制代理的人格、语气和沟通风格。详情请参见 人格设定 页面。

位置：

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

重要说明：

  • 如果尚未存在，Hermes 会自动创建一个默认的 SOUL.md
  • Hermes 只从 SOUL.md 加载 HERMES_HOME
  • Hermes 不会向工作目录搜索 SOUL.md
  • 如果文件为空，则不会将任何内容添加到提示中
  • 如果文件有内容，内容将在扫描和截断后原样注入

.cursorrules​

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

这意味着你在使用 Hermes 时，现有的 Cursor 规范可自动生效。

上下文文件如何加载​

启动时（系统提示）​

上下文文件由 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

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 内容是直接插入的，不带额外包装文本。

安全性：提示注入防护​

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

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

使用有效上下文文件的技巧​

AGENTS.md 最佳实践
  1. 保持简洁 —— 严格控制在 20K 字符以内；代理每轮都会读取
  2. 使用标题结构化 —— 用 ## 分节，用于架构、规范、重点说明
  3. 提供具体示例 —— 展示首选代码模式、API 结构、命名规范
  4. 说明禁止事项 —— “永远不要直接修改迁移文件”
  5. 列出关键路径与端口 —— 代理会据此生成终端命令
  6. 随项目演进更新 —— 过时的上下文比无上下文更糟糕

按子目录设置上下文​

对于多包仓库（monorepo），可在嵌套目录中放置特定于子目录的说明：

<!-- 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/`