11. Hermes Agent 上下文文件——让智能体读懂你的项目

一个 Agent 走进你的代码仓库，它怎么知道你用 Next.js 还是 Django、端口是 3000 还是 8000、迁移文件能不能动？答案藏在上下文文件里。Hermes Agent 会自动发现并加载这些文件，把它们注入系统提示词，从而塑造自己的行为方式。

支持哪些上下文文件

Hermes 识别的项目上下文文件不止一种，发现方式也各不相同：

文件	用途	发现方式
.hermes.md / HERMES.md	项目指令（最高优先级）	向上遍历至 git 根目录
AGENTS.md	项目指令、规范、架构说明	启动时的 CWD 及子目录（渐进式）
CLAUDE.md	Claude Code 上下文文件	启动时的 CWD 及子目录（渐进式）
SOUL.md	全局个性与语气定制	仅从 HERMES_HOME 加载
.cursorrules	Cursor IDE 编码规范	仅 CWD
.cursor/rules/*.mdc	Cursor IDE 规则模块	仅 CWD

关键规则是"先匹配先生效"：每次会话仅加载一种项目上下文类型，优先级为 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。而 SOUL.md 始终作为 Agent 身份独立加载，位于系统提示词的插槽 #1，不受这套优先级约束。

AGENTS.md：主力项目上下文

AGENTS.md 是最主要的项目上下文文件，告诉 Agent 项目的结构、要遵循的规范和特殊指令。它的杀手锏是"渐进式子目录发现"：会话启动时只加载工作目录根部的 AGENTS.md 到系统提示词；当 Agent 通过 read_file、terminal、search_files 等工具进入子目录时，才动态发现并注入该子目录的上下文文件。

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

相比启动时一股脑加载所有内容，这种方式有两个工程上的优势：一是避免系统提示词膨胀，子目录提示只在需要时出现；二是保留 prompt 缓存——系统提示词在各轮次间保持稳定，缓存命中率更高。发现机制还会向上遍历父目录，所以读取 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

## Conventions
- Use TypeScript strict mode for all frontend code
- All API endpoints return JSON with `{data, error, meta}` shape

## Important Notes
- Never modify migration files directly — use Alembic commands
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md：全局人格，不随项目变

SOUL.md 控制 Agent 的个性、语气和沟通风格，位置固定在 ~/.hermes/SOUL.md（或 $HERMES_HOME/SOUL.md）。几个要点容易踩坑：Hermes 只从 HERMES_HOME 加载它，不会在工作目录中探测；文件不存在会自动生成默认版本；文件为空则不添加到 prompt，有内容则在扫描和截断后原样注入。这意味着 SOUL.md 是跨所有项目生效的"人格底色"，想按项目切换人格应该用 /personality 预设。

加载机制与安全防护

启动时，agent/prompt_builder.py 中的 build_context_files_prompt() 负责加载：扫描工作目录、读取内容、安全扫描、截断、组装到 # Project Context 标题下、注入系统提示词。会话期间则由 SubdirectoryHintTracker 监视工具调用参数中的文件路径，做祖先目录遍历并加载发现的上下文文件，追加到工具结果中让模型自然看到。

所有上下文文件在纳入前都会扫描 prompt 注入。扫描器检查指令覆盖尝试（“ignore previous instructions”）、欺骗模式（“do not tell the user”）、系统提示词覆盖、隐藏 HTML 注释、隐藏 div 元素、凭据窃取（curl ... $API_KEY）、密钥文件访问（cat .env）、不可见字符（零宽空格、双向覆盖字符）等。一旦命中威胁模式，该文件会被拦截：

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

需要注意的是，扫描器能拦常见模式，但替代不了人工审查。对非本人编写的共享仓库，务必核对 AGENTS.md 内容。

大小限制与最佳实践

单个文件最大 20,000 字符（约 7,000 token），超出会按 70% 头部、20% 尾部截断，中间插入提示建议用文件工具读取全文。子目录发现的文件上限则是 8,000 字符。

写好 AGENTS.md 的几条经验：保持简洁、远低于 20K；用 ## 分节描述架构、规范、重要说明；包含具体示例展示首选代码模式；明确写出禁止事项（如"不得直接修改迁移文件"）；列出关键路径和端口供终端命令使用；随项目演进及时更新——过时的上下文比没有上下文更糟。对 monorepo，把子目录专属指令放进嵌套的 AGENTS.md，比如 frontend 里写"用 pnpm 不用 npm"，backend 里写"用 poetry 管理依赖"。

Frequently Asked Questions

Q：我已经有 CLAUDE.md 和 .cursorrules 了，还要再写 AGENTS.md 吗？会不会冲突？

A： 不会冲突，因为优先级是"先匹配先生效"。Hermes 按 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 顺序扫描，命中一个就不再加载后面的。所以如果你的 CLAUDE.md 或 .cursorrules 已经写得很完善，Hermes 会直接复用，无需重写。但如果你想给 Hermes 专属的、比其他工具更具体的指令，就新建一个 .hermes.md（优先级最高）或 AGENTS.md（优先级次高，也是社区事实标准）。我的建议是统一用 AGENTS.md 作为项目主上下文，既兼容多工具协作，又避免维护多份重复内容。

Q：渐进式子目录发现听着很好，但我怎么确认子目录的 AGENTS.md 真的被加载了？

A： 最直接的办法是看 Agent 的行为是否符合子目录里的规范——比如你在 frontend/AGENTS.md 写了"用 pnpm"，Agent 进入 frontend 后生成的命令是不是 pnpm。更可靠的是检查 /status 显示的会话信息，或在工具结果里观察是否出现了子目录上下文的注入痕迹。一个常见误区是以为子目录文件启动时就加载了，其实它要等 Agent 通过工具调用"走进"那个目录才触发。如果你希望启动时就可见，把关键信息放到根目录的 AGENTS.md 里更稳妥。

Q：prompt 注入扫描会不会误伤我自己写的合法内容？比如我文档里确实有 curl 示例。

A： 有可能。扫描器对 curl ... $API_KEY、cat .env 这类模式比较敏感，如果你的 AGENTS.md 里写了包含这些内容的示例代码段，可能被误判拦截。规避方式有几种：把示例命令拆开写，避免完整命中威胁模式；或用代码块包裹并加上明确的安全说明（“以下仅为示例，不要执行”）；最稳妥的是把敏感示例放到单独的文档文件里，让 Agent 通过文件引用按需读取，而不是塞进上下文文件。万一被误伤，文件被拦截时会有 [BLOCKED: ...] 提示，按提示调整内容即可。

延伸阅读与交流

本文涉及的Hermes Agent自进化智能体技术体系，目前已有系统化的深度学习资源可供参考。中国通信工业协会通信和信息技术创新人才培养工程项目办公室将于近期组织相关技术专题分享，围绕本文讨论的AI原生架构、智能体工作流、自进化数据层等方向展开系统讲解。

专题信息

• 主题：AI原生Hermes自进化智能体系统
• 时间：2026年8月22-23日
• 形式：线上直播
• 内容方向：AI原生架构 · Hermes智能体拆解 · 全栈扩展 · 智能自动化 · 产品级实战 · Context Engine · 自进化数据层

分享嘉宾

王老师（Gavin），Agentic AI企业联合创始人兼CTO，十余年硅谷AI系统工程经验。长期深耕NLP、强化学习、可控AI与智能体系统架构，提出"语言即控制（Language as Control）"原创范式，在RLHF、PPO、DPO、GRPO等方向有系统化工程实践，推动智能体技术在社交媒体、医疗、金融、法律、教育等专业场景落地。联系邮箱：hiheartfirst@gmail.com

技术交流

• 联系人：Sam
• Hermes Agent技术文档：https://hermes-agent.nousresearch.com/docs/