智能体总是不听话？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 按以下顺序扫描项目目录，高优先级文件覆盖低优先级冲突指令，但所有文件内容均会注入上下文：

1. .hermes.md/HERMES.md：Hermes 专属最高优先级文件。

2. AGENTS.md：多智能体通用项目文件，兼容性最强。

3. CLAUDE.md：兼容 Claude Code 上下文文件。

4. .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 支持的引用类型

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 上下文文件