Hermes 代理上下文使用教程：从核心概念到最佳实践
智能体行为不听话、回答总与项目规范不符——问题往往出在"上下文"上。Hermes Agent 的上下文（Context）系统是智能体行为的核心"指挥中枢"，分为上下文文件（Context Files）与上下文引用（Context References） 两大核心能力。前者定义全局人格与项目规范，后者实时注入代码、文档、Git 变更等动态内容，结合后可让智能体精准对齐项目规则、理解开发意图，大幅提升交互效率与输出质量。本文从核心概念、文件配置、引用用法、安全规范到最佳实践，带你全面掌握上下文系统使用。
一、上下文系统核心概念
1.1 核心价值
上下文系统本质是 "给智能明确行为边界与背景信息"：
全局人格：通过固定文件定义智能体沟通风格、工作原则，所有会话统一生效。
项目规范：注入项目技术栈、编码规则、架构约定，避免 "答非所问"。
动态内容：实时注入代码片段、文档、Git 差异，无需手动复制粘贴。
1.2 两大核心能力
上下文文件（Context Files）：静态配置文件，定义全局人格、项目规范，会话启动时自动加载。
上下文引用（Context References）：动态注入语法，通过
@符号实时加载文件、目录、URL 等内容。
图1：上下文系统架构
flowchart TB
subgraph Static[上下文文件 · 静态加载]
direction TB
Soul[~/.hermes/SOUL.md<br/>全局人格文件] --> Agent[智能体行为决策]
HermesMD[.hermes.md / HERMES.md] --> Agent
AgentsMD[AGENTS.md<br/>项目规范] --> Agent
ClaudeMD[CLAUDE.md] --> Agent
Cursor[.cursorrules] --> Agent
end
subgraph Dynamic[上下文引用 · 动态注入]
File[@file:path<br/>文件引用]
Folder[@folder:path<br/>目录引用]
Diff[@diff / @staged<br/>Git 变更]
GitLog[@git:N<br/>提交历史]
URL[@url:link<br/>网页内容]
end
Dynamic -->|对话中 @ 语法触发| Agent
subgraph Priority[优先级层级]
P1[Hermes 专属文件<br/>最高优先级] --> P2[AGENTS.md<br/>项目通用]
P2 --> P3[CLAUDE.md<br/>兼容层] --> P4[.cursorrules]
end
Priority -.->|冲突时覆盖| Agent
二、上下文文件（Context Files）
上下文文件是静态配置载体，分为全局人格文件（SOUL.md）与项目规范文件（.hermes.md/AGENTS.md 等），会话启动时自动扫描加载。
2.1 文件优先级（从高到低）
Hermes 按以下顺序扫描项目目录，高优先级文件覆盖低优先级冲突指令，但所有文件内容均会注入上下文：
.hermes.md/HERMES.md：Hermes 专属最高优先级文件。AGENTS.md：多智能体通用项目文件，兼容性最强。CLAUDE.md：兼容 Claude Code 上下文文件。.cursorrules：兼容 Cursor IDE 编码规则。
2.2 全局人格文件（SOUL.md）
2.2.1 路径与特性
固定路径：
~/.hermes/SOUL.md（仅从 Hermes 主目录加载，不扫描项目目录）。作用：定义智能体全局沟通风格、工作原则、禁止行为，所有会话默认生效。
自动创建：首次使用 Hermes 时自动生成默认文件。
2.2.2 示例配置
# Hermes 全局人格
## 沟通风格
- 中文回复（英文提问除外），简洁直接，无冗余客套。
- 优先提供可执行代码/命令，避免空泛解释。
- 歧义处主动确认，不猜测用户意图。
## 工作原则
- 代码优先：安全、可维护、有单元测试。
- 诚实透明：不懂不编造，主动提示风险。
- 高效务实：聚焦问题，不额外推荐无关工具。
## 禁止行为
- 不添加无意义感叹词，不过度解释简单任务。
- 不修改受保护文件（如 .env、迁移脚本）。
2.3 项目规范文件（AGENTS.md 为主）
2.3.1 作用与加载机制
作用：定义项目技术栈、编码规范、架构规则、禁止事项。
渐进加载：会话启动时加载当前目录
AGENTS.md；进入子目录（如frontend/）时，自动加载子目录AGENTS.md，仅在需要时注入，避免上下文膨胀。
2.3.2 示例配置（Go 后端项目）
# 项目上下文：Go 后端服务
## 技术栈
- Go 1.22+，Gin 框架，GORM ORM。
- 数据库：SQLite（开发）/ PostgreSQL（生产）。
- 部署：Docker Compose，端口 8000。
## 编码规范
- 严格 PEP8，全量类型注解。
- API 响应统一 {code, data, msg} 格式。
- 禁止直接拼接 SQL，优先 GORM 方法。
## 禁止事项
- 不提交 .env 文件到 Git。
- 不直接修改数据库迁移脚本。
2.3.3 多目录分层配置
大型项目可按目录拆分规范，Hermes 会逐级加载：
my-project/
├── AGENTS.md # 根目录全局规范。
├── frontend/
│ └── AGENTS.md # 前端专属规范。
└── backend/
└── AGENTS.md # 后端专属规范。
2.4 大小与安全限制
单文件上限：根目录文件 20000 字符，子目录文件 8000 字符，超出自动截断。
安全扫描：自动检测提示注入、凭证外泄、恶意指令，拦截风险文件。
三、上下文引用（Context References）
上下文引用是动态注入语法，通过 @ 符号实时加载文件、目录、Git 变更、URL 等内容，无需手动复制，支持 CLI 自动补全。
3.1 支持的引用类型
| 语法 | 说明 | 示例 |
|---|---|---|
@file:路径 |
注入完整文件内容。 | @file:src/main.go |
@file:路径:起始-结束 |
注入指定行范围（1 索引）。 | @file:src/main.go:10-25 |
@folder:路径 |
注入目录树与文件元数据。 | @folder:src/components |
@diff |
注入 Git 未暂存变更。 | @diff |
@staged |
注入 Git 已暂存变更。 | @staged |
@git:N |
注入最近 N 次提交（最多 10）。 | @git:5 |
@url:链接 |
注入网页正文。 | @url:https://xxx.com/doc |
3.2 基础使用示例
3.2.1 代码审查
审查 @file:src/main.go:10-50，检查 SQL 注入风险
3.2.2 对比配置
对比 @file:dev.yaml 和 @file:prod.yaml 的数据库配置差异
3.2.3 注入文档
总结 @url:https://xxx.com/api-doc 的核心接口
3.3 CLI 自动补全
交互式 CLI 中输入 @，自动触发补全：
输入
@file:，自动补全当前目录文件。输入
@git:，提示可输入的提交数量。
3.4 大小与安全限制
3.4.1 大小限制
软限制：引用内容不超过上下文 25%，超出警告但继续。
硬限制：不超过 50%，超出拒绝注入。
目录最多 200 个文件，Git 最多 10 次提交。
3.4.2 安全拦截
敏感路径：禁止引用
~/.ssh/、~/.env、~/.aws/等凭证目录。二进制文件：自动检测并拒绝 .exe、.so 等二进制文件。
路径遍历：禁止引用工作目录外文件。
四、上下文调试与最佳实践
4.1 调试上下文加载
查看 Hermes 实际加载的上下文文件，排查配置是否生效：
hermes chat --debug-context
输出示例：
[Context] Loaded SOUL.md (1234 chars)
[Context] Loaded /my-project/AGENTS.md (3456 chars)
4.2 最佳实践
4.2.1 上下文文件
精简内容：聚焦核心规范，避免冗余，控制在 20000 字符内。
分层组织：根目录放全局规则，子目录放模块专属规范。
定期更新：项目演进时同步更新，避免过时规范。
4.2.2 上下文引用
精准引用：用行范围注入关键代码，避免大文件全量注入。
组合使用：同时引用文件 + Git 变更，完整还原开发场景。
敏感规避：不引用含密钥、密码的文件。
五、总结
Hermes 上下文系统通过静态文件定义规则、动态引用注入内容，实现智能体行为精准可控。SOUL.md 统一全局人格，AGENTS.md 规范项目开发，@ 语法实时注入动态内容，三者结合可大幅提升开发协作效率。合理配置上下文、遵循安全规范，能让 Hermes 成为贴合项目需求的专属开发助手。
