智能体总是不听话？90% 的人没用对 Hermes 的「上下文」——这才是正确的打开方式
一、上下文系统核心概念
1.1 核心价值
上下文系统本质是"给智能明确行为边界与背景信息"：
全局人格：通过固定文件定义智能体沟通风格、工作原则，所有会话统一生效。
项目规范：注入项目技术栈、编码规则、架构约定，避免 "答非所问"。
动态内容：实时注入代码片段、文档、Git 差异，无需手动复制粘贴。
1.2 两大核心能力
上下文文件（Context Files）：静态配置文件，定义全局人格、项目规范，会话启动时自动加载。
上下文引用（Context References）：动态注入语法，通过
@符号实时加载文件、目录、URL 等内容。
图1：上下文系统架构
上下文文件 · 静态加载
对话中 @ 语法触发
冲突时覆盖
优先级层级
Hermes 专属文件
最高优先级
AGENTS.md
项目通用
CLAUDE.md
兼容层
.cursorrules
上下文引用 · 动态注入
@file:path
文件引用
@folder:path
目录引用
@diff / @staged
Git 变更
@git:N
提交历史
@url:link
网页内容
~/.hermes/SOUL.md
全局人格文件
智能体行为决策
.hermes.md / HERMES.md
AGENTS.md
项目规范
CLAUDE.md
.cursorrules
二、上下文文件（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)