一、上下文系统核心概念1.1 核心价值上下文系统本质是给智能明确行为边界与背景信息全局人格通过固定文件定义智能体沟通风格、工作原则所有会话统一生效。项目规范注入项目技术栈、编码规则、架构约定避免 答非所问。动态内容实时注入代码片段、文档、Git 差异无需手动复制粘贴。1.2 两大核心能力上下文文件Context Files静态配置文件定义全局人格、项目规范会话启动时自动加载。上下文引用Context References动态注入语法通过符号实时加载文件、目录、URL 等内容。图1上下文系统架构上下文文件 · 静态加载对话中 语法触发冲突时覆盖优先级层级Hermes 专属文件最高优先级AGENTS.md项目通用CLAUDE.md兼容层.cursorrules上下文引用 · 动态注入file:path文件引用folder:path目录引用diff / stagedGit 变更git:N提交历史url:link网页内容~/.hermes/SOUL.md全局人格文件智能体行为决策.hermes.md / HERMES.mdAGENTS.md项目规范CLAUDE.md.cursorrules二、上下文文件Context Files上下文文件是静态配置载体分为全局人格文件SOUL.md与项目规范文件.hermes.md/AGENTS.md 等会话启动时自动扫描加载。2.1 文件优先级从高到低Hermes 按以下顺序扫描项目目录高优先级文件覆盖低优先级冲突指令但所有文件内容均会注入上下文.hermes.md/HERMES.mdHermes 专属最高优先级文件。AGENTS.md多智能体通用项目文件兼容性最强。CLAUDE.md兼容 Claude Code 上下文文件。.cursorrules兼容 Cursor IDE 编码规则。2.2 全局人格文件SOUL.md2.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.22Gin 框架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.gofile:路径:起始-结束注入指定行范围1 索引。file:src/main.go:10-25folder:路径注入目录树与文件元数据。folder:src/componentsdiff注入 Git 未暂存变更。diffstaged注入 Git 已暂存变更。stagedgit:N注入最近 N 次提交最多 10。git:5url:链接注入网页正文。url:https://xxx.com/doc3.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 上下文文件