跳到主要內容

上下文文件

Hermes Agent 會自動發現並加載上下文文件，這些文件決定了其行為方式。部分文件為項目本地文件，從當前工作目錄中發現。SOUL.md 現在是 Hermes 實例的全局文件，僅從 HERMES_HOME 加載。

支持的上下文文件​

文件用途發現方式
.hermes.md / HERMES.md項目指令（優先級最高）向上遍歷至 Git 倉庫根目錄
AGENTS.md項目指令、規範與架構說明啟動時從當前工作目錄（CWD）開始，逐步檢查子目錄
CLAUDE.mdClaude 代碼上下文文件（也支持檢測）啟動時從當前工作目錄（CWD）開始，逐步檢查子目錄
SOUL.md當前 Hermes 實例的全局個性與語氣定製僅從 HERMES_HOME/SOUL.md 加載
.cursorrulesCursor IDE 編碼規範僅從當前工作目錄（CWD）加載
.cursor/rules/*.mdcCursor IDE 規則模塊僅從當前工作目錄（CWD）加載
優先級系統

每個會話中，僅加載一種項目上下文類型（首個匹配項勝出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始終獨立加載，作為 Agent 身份（槽位 #1）。

AGENTS.md​

AGENTS.md 是主要的項目上下文文件。它告訴 Agent 你的項目結構、應遵循的規範以及任何特殊指令。

逐級子目錄發現機制​

在會話啟動時，Hermes 會將當前工作目錄中的 AGENTS.md 加載到系統提示中。當 Agent 在會話過程中通過 read_file、terminal、search_files 等方式進入子目錄時，它會逐級發現這些目錄中的上下文文件，並在相關性出現時立即將其注入對話。

my-project/
├── AGENTS.md              ← Loaded at startup (system prompt)
├── frontend/
│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
├── backend/
│   └── AGENTS.md          ← Discovered when agent reads backend/ files
└── shared/
    └── AGENTS.md          ← Discovered when agent reads shared/ files

這種做法相較於啟動時一次性加載所有內容具有兩個優勢：

  • 無系統提示膨脹 —— 子目錄提示僅在需要時出現
  • 提示緩存保留 —— 系統提示在各輪對話中保持穩定

每個子目錄在會話中最多被檢查一次。發現過程還會向上遍歷父目錄，因此即使 backend/src/ 目錄本身沒有上下文文件，讀取 backend/src/main.py 也會發現 backend/AGENTS.md。

信息

子目錄上下文文件會經過與啟動時上下文文件相同的 安全掃描。惡意文件將被阻止。

AGENTS.md 示例​

# 項目上下文

This is a Next.js 14 web application with a Python FastAPI backend.

## 架構
- Frontend: Next.js 14 with App Router in `/frontend`
- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
- Database: PostgreSQL 16
- Deployment: Docker Compose on a Hetzner VPS

## 約定
- Use TypeScript strict mode for all frontend code
- Python code follows PEP 8, use type hints everywhere
- All API endpoints return JSON with `{data, error, meta}` shape
- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)

## 重要說明
- Never modify migration files directly — use Alembic commands
- The `.env.local` file has real API keys, don't commit it
- Frontend port is 3000, backend is 8000, DB is 5432

SOUL.md​

SOUL.md 控制 Agent 的個性、語氣和溝通風格。詳情請參見 個性 頁面。

位置：

  • ~/.hermes/SOUL.md
  • 或 $HERMES_HOME/SOUL.md（如果你使用自定義主目錄運行 Hermes）

重要說明：

  • 如果尚未存在 SOUL.md，Hermes 會自動創建一個默認文件
  • Hermes 僅從 HERMES_HOME 加載 SOUL.md
  • Hermes 不會在工作目錄中搜索 SOUL.md
  • 如果文件為空，則不會將任何內容添加到提示中
  • 如果文件有內容，內容將在掃描和截斷後原樣注入

.cursorrules​

Hermes 兼容 Cursor IDE 的 .cursorrules 文件和 .cursor/rules/*.mdc 規則模塊。如果這些文件存在於項目根目錄中，且未發現更高優先級的上下文文件（.hermes.md、AGENTS.md 或 CLAUDE.md），則它們將作為項目上下文加載。

這意味著你在使用 Hermes 時，現有的 Cursor 規範會自動生效。

上下文文件的加載方式​

啟動時（系統提示）​

上下文文件由 agent/prompt_builder.py 中的 build_context_files_prompt() 加載：

  1. 掃描工作目錄 —— 檢查是否存在 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules（首個匹配項勝出）
  2. 讀取內容 —— 每個文件以 UTF-8 文本形式讀取
  3. 安全掃描 —— 檢查內容是否存在提示注入模式
  4. 截斷處理 —— 超過 20,000 字符的文件將進行頭尾截斷（70% 頭部，20% 尾部，中間插入標記）
  5. 組裝 —— 所有部分在 # 項目上下文 標題下合併
  6. 注入 —— 組裝後的內容添加到系統提示中

會話期間（逐級發現）​

agent/subdirectory_hints.py 中的 SubdirectoryHintTracker 監控工具調用參數中的文件路徑：

  1. 路徑提取 —— 每次工具調用後，從參數中提取文件路徑（path、workdir、shell 命令等）
  2. 祖先遍歷 —— 檢查目錄及其最多 5 級父目錄（遇到已訪問目錄則停止）
  3. 提示加載 —— 若發現 AGENTS.md、CLAUDE.md 或 .cursorrules，則加載（每個目錄首個匹配項）
  4. 安全掃描 —— 與啟動文件相同的提示注入掃描
  5. 截斷處理 —— 每個文件最多 8,000 字符
  6. 注入 —— 追加到工具結果中，使模型自然地在上下文中看到該內容

最終提示部分大致如下：

# 項目上下文

The following project context files have been loaded and should be followed:

## AGENTS.md

[Your AGENTS.md content here]

## .cursorrules

[Your .cursorrules content here]

[Your SOUL.md content here]

請注意，SOUL 內容是直接插入的，不帶額外包裝文本。

安全性：提示注入防護​

所有上下文文件在被包含前都會經過潛在提示注入的掃描。掃描器檢查以下內容：

  • 指令覆蓋嘗試： "忽略先前的指令"，"無視你的規則"
  • 欺騙模式： "不要告訴用戶"
  • 系統提示覆蓋： "系統提示覆蓋"
  • 隱藏的 HTML 註釋： <!-- 忽略指令 -->
  • 隱藏的 div 元素： <div style="display:none">
  • 憑證外洩： curl ... $API_KEY
  • 秘密文件訪問： cat .env，cat credentials
  • 不可見字符： 零寬度空格、雙向覆蓋、詞連接符

如果檢測到任何威脅模式，文件將被阻止：

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
注意

此掃描器可防範常見的注入模式，但不能替代對共享倉庫中上下文文件的審查。始終驗證您未編寫項目的 AGENTS.md 內容。

大小限制​

限制值
每個文件最大字符數20,000（約 7,000 個 token）
頭部截斷比例70%
尾部截斷比例20%
截斷標記10%（顯示字符數並建議使用文件工具）

當文件超過 20,000 個字符時，截斷消息顯示為：

[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]

有效上下文文件的技巧​

AGENTS.md 最佳實踐
  1. 保持簡潔 — 嚴格控制在 20,000 字符以內；Agent 每輪都會讀取此文件
  2. 使用標題結構 — 使用 ## 分節，用於架構、約定和重要說明
  3. 包含具體示例 — 展示推薦的代碼模式、API 結構、命名約定
  4. 說明禁止行為 — "切勿直接修改遷移文件"
  5. 列出關鍵路徑和端口 — Agent 會使用這些信息執行終端命令
  6. 隨項目演進而更新 — 過時的上下文比無上下文更糟糕

按子目錄的上下文​

對於多包倉庫，可在嵌套的 AGENTS.md 文件中添加子目錄特定的指令：

<!-- 前端/AGENTS.md -->
# 前端 Context

- Use `pnpm` not `npm` for package management
- Components go in `src/components/`, pages in `src/app/`
- Use Tailwind CSS, never inline styles
- Run tests with `pnpm test`
<!-- 後端/AGENTS.md -->
# 後端上下文

- Use `poetry` for dependency management
- Run the dev server with `poetry run uvicorn main:app --reload`
- All endpoints need OpenAPI docstrings
- Database models are in `models/`, schemas in `schemas/`