跳到主要内容

上下文文件

Hermes Agent 会自动发现并加载影响其行为的上下文文件。其中一部分是项目本地文件，会从当前工作目录附近发现；SOUL.md 则是 Hermes 实例级的全局文件，只从 HERMES_HOME 加载。

支持的上下文文件​

FilePurposeDiscovery
.hermes.md / HERMES.md项目说明（最高优先级）向上查找到 git 根
AGENTS.md项目说明、约定、架构启动时从 CWD 读取，并在子目录中渐进发现
CLAUDE.mdClaude Code 上下文文件（也会检测）启动时从 CWD 读取，并在子目录中渐进发现
SOUL.md当前 Hermes 实例的人格与语气自定义HERMES_HOME/SOUL.md only
.cursorrulesCursor IDE 编码约定仅 CWD
.cursor/rules/*.mdcCursor IDE 规则模块仅 CWD
Priority system

每个会话中只会加载 一种 项目上下文类型（先匹配先使用）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 会始终独立加载，作为智能体身份（slot #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

相比启动时一次性加载全部上下文，这种方式有两个优点：

  • 不会让系统提示膨胀 — 只有真正需要时才加入子目录提示
  • 保留 prompt cache — 系统提示在多轮之间保持稳定

每个子目录在同一会话中最多检查一次。发现过程还会向上遍历父目录，因此读取 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 控制智能体的人格、语气和沟通风格。详见 Personality。

位置：

  • ~/.hermes/SOUL.md
  • 或在使用自定义 home 时为 $HERMES_HOME/SOUL.md

重要细节：

  • 如果 SOUL.md 不存在，Hermes 会自动创建默认版本
  • Hermes 只会从 HERMES_HOME 加载 SOUL.md
  • Hermes 不会在当前工作目录中查找 SOUL.md
  • 如果文件为空，不会把其中任何内容加入提示
  • 如果文件有内容，则在安全扫描和截断后原样注入

.cursorrules​

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

这意味着你现有的 Cursor 约定在 Hermes 中也能自动生效。

上下文文件如何加载​

启动时（系统提示）​

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

  1. 扫描工作目录 — 按 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 顺序检查（先命中先使用）
  2. 读取内容 — 以 UTF-8 文本形式读取每个文件
  3. 安全扫描 — 检查 prompt injection 模式
  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. 安全扫描 — 与启动阶段相同的 prompt injection 扫描
  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 内容会被直接插入，不会额外加包装文字。

安全性：Prompt Injection 防护​

所有上下文文件在被纳入前都会扫描潜在 prompt injection 风险。扫描器会检查：

  • 覆盖指令尝试：例如 “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
  • 不可见字符：零宽空格、双向控制字符、word joiner

若检测到任一风险模式，文件会被拦截：

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

该扫描器能防御常见注入模式，但不能替代你对共享仓库中上下文文件的人工审查。对于不是你自己编写的项目，请始终检查 AGENTS.md 内容。

大小限制​

LimitValue
Max chars per file20,000 (~7,000 tokens)
Head truncation ratio70%
Tail truncation ratio20%
Truncation marker10%（显示字符数并提示使用文件工具读取全文）

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

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

如何写好上下文文件​

Best practices for AGENTS.md
  1. 保持简洁 — 尽量远低于 20K 字符，因为智能体每轮都会看到它
  2. 用标题组织结构 — 使用 ## 分节组织架构、约定、重要说明
  3. 包含具体示例 — 展示偏好的代码模式、API 结构和命名约定
  4. 明确写出不要做什么 — 比如 “never modify migration files directly”
  5. 列出关键路径和端口 — 智能体会在终端命令中使用这些信息
  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/`