11. Hermes Agent 上下文文件——让智能体读懂你的项目一个 Agent 走进你的代码仓库它怎么知道你用 Next.js 还是 Django、端口是 3000 还是 8000、迁移文件能不能动答案藏在上下文文件里。Hermes Agent 会自动发现并加载这些文件把它们注入系统提示词从而塑造自己的行为方式。支持哪些上下文文件Hermes 识别的项目上下文文件不止一种发现方式也各不相同文件用途发现方式.hermes.md/HERMES.md项目指令最高优先级向上遍历至 git 根目录AGENTS.md项目指令、规范、架构说明启动时的 CWD 及子目录渐进式CLAUDE.mdClaude Code 上下文文件启动时的 CWD 及子目录渐进式SOUL.md全局个性与语气定制仅从HERMES_HOME加载.cursorrulesCursor IDE 编码规范仅 CWD.cursor/rules/*.mdcCursor 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 5432SOUL.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 不用 npmbackend 里写用 poetry 管理依赖。Frequently Asked QuestionsQ我已经有 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 写了用 pnpmAgent 进入 frontend 后生成的命令是不是 pnpm。更可靠的是检查/status显示的会话信息或在工具结果里观察是否出现了子目录上下文的注入痕迹。一个常见误区是以为子目录文件启动时就加载了其实它要等 Agent 通过工具调用走进那个目录才触发。如果你希望启动时就可见把关键信息放到根目录的 AGENTS.md 里更稳妥。Qprompt 注入扫描会不会误伤我自己写的合法内容比如我文档里确实有 curl 示例。A有可能。扫描器对curl ... $API_KEY、cat .env这类模式比较敏感如果你的 AGENTS.md 里写了包含这些内容的示例代码段可能被误判拦截。规避方式有几种把示例命令拆开写避免完整命中威胁模式或用代码块包裹并加上明确的安全说明“以下仅为示例不要执行”最稳妥的是把敏感示例放到单独的文档文件里让 Agent 通过文件引用按需读取而不是塞进上下文文件。万一被误伤文件被拦截时会有[BLOCKED: ...]提示按提示调整内容即可。延伸阅读与交流本文涉及的Hermes Agent自进化智能体技术体系目前已有系统化的深度学习资源可供参考。中国通信工业协会通信和信息技术创新人才培养工程项目办公室将于近期组织相关技术专题分享围绕本文讨论的AI原生架构、智能体工作流、自进化数据层等方向展开系统讲解。专题信息主题AI原生Hermes自进化智能体系统时间2026年8月22-23日形式线上直播内容方向AI原生架构 · Hermes智能体拆解 · 全栈扩展 · 智能自动化 · 产品级实战 · Context Engine · 自进化数据层分享嘉宾王老师GavinAgentic AI企业联合创始人兼CTO十余年硅谷AI系统工程经验。长期深耕NLP、强化学习、可控AI与智能体系统架构提出语言即控制Language as Control原创范式在RLHF、PPO、DPO、GRPO等方向有系统化工程实践推动智能体技术在社交媒体、医疗、金融、法律、教育等专业场景落地。联系邮箱hiheartfirstgmail.com技术交流联系人SamHermes Agent技术文档https://hermes-agent.nousresearch.com/docs/