上下文文件

上下文文件（Context Files）是 Hermes Agent 自动读取并注入到对话上下文中的特殊 Markdown 文件，用于向智能体提供项目特定的指令、规范和背景信息。

优先级层级

Hermes 在工作目录及其父目录中按以下优先级顺序查找上下文文件：

.hermes.md          ← 最高优先级（Hermes 专属）
    ↓
AGENTS.md           ← 多智能体框架通用
    ↓
CLAUDE.md           ← Claude Code 兼容
    ↓
.cursorrules        ← Cursor IDE 兼容（最低优先级）

当多个文件同时存在时，优先级高的文件内容覆盖低优先级文件的冲突指令，但两者都会被读取注入（非互斥）。

优先级说明

文件名	优先级	适用场景
.hermes.md	最高	Hermes 专用指令，覆盖一切
AGENTS.md	高	多智能体项目规范，跨工具共享
CLAUDE.md	中	Claude Code 用户迁移到 Hermes
.cursorrules	低	Cursor IDE 项目规则复用

---

SOUL.md — 全局人格配置

~/.hermes/SOUL.md 是一个特殊的全局上下文文件，定义 Hermes 的全局人格和行为基调，在所有会话和项目中始终生效。

<!-- ~/.hermes/SOUL.md -->

# Hermes Soul

你是一个务实、高效的工程助手。你的核心特质：

## 沟通风格
- 回答简洁直接，避免不必要的客套和废话
- 优先提供可执行的代码和命令
- 遇到歧义主动询问，而非猜测
- 使用中文回复（除非用户用英文提问）

## 工作原则
- 代码质量第一：安全、可维护、有测试
- 诚实面对不确定性，不编造信息
- 尊重用户的技术判断
- 主动提示潜在风险

## 禁止行为
- 不添加无意义的感叹词（"好的！""当然！""很棒！"）
- 不对完成的任务过度解释
- 不主动推荐自己不熟悉的工具

SOUL.md 在上下文注入顺序中位于最前面，为所有其他指令提供基础行为框架。

---

文件大小限制

为防止上下文膨胀，Hermes 对上下文文件有以下大小限制：

类型	限制
根目录上下文文件（单文件）	20,000 字符
子目录上下文文件（单文件）	8,000 字符

超出限制的内容将被截断，并在日志中记录警告。建议保持上下文文件简洁，聚焦最重要的规范。

多目录上下文

Hermes 会从工作目录向上遍历，收集所有层级的上下文文件：

~/projects/my-app/
├── .hermes.md          # 根目录（20,000 字符限制）
├── backend/
│   ├── .hermes.md      # 后端子目录（8,000 字符限制）
│   └── api/
│       └── .hermes.md  # API 子目录（8,000 字符限制）
└── frontend/
    └── .hermes.md      # 前端子目录（8,000 字符限制）

当 Hermes 在 backend/api/ 目录中工作时，会加载：

1. ~/projects/my-app/.hermes.md（根）
2. ~/projects/my-app/backend/.hermes.md（父目录）
3. ~/projects/my-app/backend/api/.hermes.md（当前目录）

---

提示词注入防护

Hermes 会对上下文文件内容进行提示词注入扫描，防止恶意文件劫持智能体行为。

检测的模式包括：

• 伪造系统消息（[SYSTEM]、<system> 等标签）
• 角色覆盖指令（"你现在是..."、"忘记之前的指令"等）
• 权限提升尝试（"你有权限..."、"无需确认直接执行"等）

发现可疑内容时，Hermes 会：

1. 拒绝加载该文件
2. 向用户显示警告
3. 记录到安全日志

# 查看安全日志
cat ~/.hermes/logs/security.log

---

项目专属指令示例

Go 后端项目（.hermes.md）

# Project: new-api

## 技术栈
- Go 1.22+，Gin 框架，GORM v2
- 数据库：SQLite / MySQL / PostgreSQL（三者同时兼容）
- 前端：React 18 + Vite + Semi Design

## 编码规范

### JSON 操作
所有 JSON 操作必须使用 `common/json.go` 中的包装函数：
- `common.Marshal()` — 序列化
- `common.Unmarshal()` — 反序列化
- 禁止直接导入 `encoding/json`

### 数据库
- 优先使用 GORM 方法，避免原始 SQL
- 跨数据库差异处理：使用 `commonGroupCol`、`commonTrueVal` 等变量
- 迁移脚本必须在三种数据库上测试

### 请求 DTO
可选字段必须使用指针类型（`*int`、`*bool` 等）加 `omitempty`

## 架构分层
Router → Controller → Service → Model
不允许跨层直接调用（如 Router 直接调用 Model）

## 禁止事项
- 不修改受保护的项目标识信息（new-api、QuantumNous）
- 不提交 .env 文件到 git
- 不使用 MySQL 专有函数（如 GROUP_CONCAT）而不提供 PostgreSQL 兼容版本

Python 数据科学项目（.hermes.md）

# Project: data-pipeline

## 环境
- Python 3.11+，使用 uv 管理依赖
- 主要库：pandas, polars, scikit-learn, matplotlib
- 数据存储：DuckDB（本地分析）/ S3（生产）

## 代码规范
- 类型注解：所有公开函数必须有完整类型注解
- 文档字符串：Google 风格
- 测试：pytest，覆盖率 > 80%
- 格式化：ruff format + ruff check

## 数据处理原则
- 大数据集优先使用 Polars（懒加载）
- 避免在循环中使用 pandas apply（改用向量化操作）
- 所有数据管道必须有幂等性保证

## 文件组织
src/
├── ingestion/    # 数据采集
├── processing/   # 数据处理
├── analysis/     # 分析逻辑
└── visualization/ # 可视化

前端 React 项目（AGENTS.md）

# Frontend Agent Guidelines

## 技术栈
- React 18 + TypeScript 5
- Vite 5 构建
- Tailwind CSS + shadcn/ui
- Zustand 状态管理
- React Query 数据获取

## 组件规范
- 优先使用函数组件 + Hooks
- Props 接口命名：`ComponentNameProps`
- 文件结构：每个组件一个目录，包含 index.tsx、types.ts、*.test.tsx

## 样式规范
- 使用 Tailwind 工具类，避免自定义 CSS
- 响应式优先（mobile-first）
- 暗色模式：使用 CSS 变量，不硬编码颜色

## 禁止事项
- 不使用 class components
- 不使用内联 style（除非动态值）
- 不在组件内部直接调用 fetch（使用 React Query）

---

调试上下文加载

查看 Hermes 实际加载了哪些上下文文件：

# 显示上下文加载信息
hermes chat --debug-context

# 输出示例：
# [Context] Loaded SOUL.md (1,234 chars)
# [Context] Loaded /home/user/projects/my-app/.hermes.md (3,456 chars)
# [Context] Loaded /home/user/projects/my-app/backend/.hermes.md (1,789 chars)
# [Context] Total context files: 3 files, 6,479 chars

---

最佳实践

1. 保持简洁：只写智能体真正需要知道的内容，避免重复通用知识。

2. 结构清晰：使用标题分组，让智能体快速定位相关规范。

3. 具体可操作：写"使用 common.Marshal() 而非 json.Marshal()"比写"遵循 JSON 规范"更有效。

4. 定期更新：项目演进时同步更新上下文文件，过时的规范会造成混淆。

5. 分层组织：根目录放全局规范，子目录放局部规范，避免冗余。